mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
feat(share): measure local sharing outcomes (#7138)
This commit is contained in:
@@ -11,6 +11,8 @@ const mocks = vi.hoisted(() => ({
|
||||
add: vi.fn(),
|
||||
pending: vi.fn(),
|
||||
refresh: vi.fn(),
|
||||
event: vi.fn(),
|
||||
access: vi.fn(),
|
||||
}));
|
||||
vi.mock("@hyperframes/share", () => ({
|
||||
reviewClient: () => ({ project: mocks.project, spaces: mocks.spaces, reviewFlags: mocks.flags }),
|
||||
@@ -33,7 +35,7 @@ vi.mock("@hyperframes/share", () => ({
|
||||
},
|
||||
}));
|
||||
vi.mock("./auth.js", () => ({
|
||||
createShareAccess: () => ({ access: vi.fn() }),
|
||||
createShareAccess: () => ({ access: mocks.access }),
|
||||
shareSite: () => "https://hyperframes.dev",
|
||||
}));
|
||||
vi.mock("./host.js", () => ({
|
||||
@@ -41,6 +43,11 @@ vi.mock("./host.js", () => ({
|
||||
bindCliShareProject: (path: string) => path,
|
||||
}));
|
||||
vi.mock("./render.js", () => ({ prepareShareRender: mocks.render }));
|
||||
vi.mock("../telemetry/client.js", () => ({
|
||||
trackEvent: mocks.event,
|
||||
resetTelemetryPostureCache: vi.fn(),
|
||||
}));
|
||||
vi.mock("../telemetry/config.js", () => ({ readConfigFresh: vi.fn() }));
|
||||
import { createShareService } from "./service.js";
|
||||
const shared = {
|
||||
projectId: "project",
|
||||
@@ -269,3 +276,115 @@ describe("asynchronous share recovery", () => {
|
||||
});
|
||||
});
|
||||
});
|
||||
describe("share rollout signals", () => {
|
||||
const events = () => mocks.event.mock.calls.map(([name]) => name);
|
||||
it("records a completed video even when its review link is disabled", async () => {
|
||||
mocks.status.mockResolvedValue({ ...shared, url: null });
|
||||
mocks.add.mockImplementation(async (request) => request.onAdded());
|
||||
const result = await createShareService("/secret").run({ action: "update" });
|
||||
expect(result.state).toBe("link_off");
|
||||
expect(events()).toContain("share_video_ready");
|
||||
expect(events()).not.toContain("share_mutation_processing");
|
||||
});
|
||||
it("records the allowlisted missing-audience usage reason", async () => {
|
||||
await expect(createShareService("/secret").run({ action: "share" })).rejects.toMatchObject({
|
||||
code: "audience_required",
|
||||
});
|
||||
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ reason: "audience_required" });
|
||||
});
|
||||
it("records recovery before refreshing a completed pending upload clears its state", async () => {
|
||||
mocks.status.mockResolvedValue(shared);
|
||||
mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" });
|
||||
mocks.refresh.mockImplementation(async () => mocks.pending.mockResolvedValue(null));
|
||||
await createShareService("/secret").run({ action: "share" });
|
||||
expect(events()).toContain("share_recovery_attempted");
|
||||
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true });
|
||||
expect(events()).not.toContain("share_video_ready");
|
||||
expect(mocks.add).not.toHaveBeenCalled();
|
||||
});
|
||||
it("records only verified upload admission and ready, attributed to local Studio", async () => {
|
||||
mocks.status.mockResolvedValue(shared);
|
||||
mocks.add.mockImplementation(async (request) => {
|
||||
request.onProgress({ step: "preparing", sent: 0, total: 0 });
|
||||
request.onProgress({ step: "uploading", sent: 1, total: 2 });
|
||||
request.onProgress({ step: "processing", sent: 2, total: 2 });
|
||||
request.onAdded();
|
||||
});
|
||||
await createShareService("/private/project", undefined, { surface: "local_studio" }).run({
|
||||
action: "update",
|
||||
});
|
||||
expect(events()).toEqual([
|
||||
"share_mutation_attempted",
|
||||
"share_mutation_authenticated",
|
||||
"share_mutation_admitted",
|
||||
"share_video_ready",
|
||||
]);
|
||||
expect(mocks.event.mock.calls.every(([, data]) => data.client_surface === "local_studio")).toBe(
|
||||
true,
|
||||
);
|
||||
expect(new Set(mocks.event.mock.calls.map(([, data]) => data.attempt_id)).size).toBe(1);
|
||||
});
|
||||
it("counts quota refusal without admission, rendering, or raw error details", async () => {
|
||||
mocks.spaces.mockResolvedValue([
|
||||
{
|
||||
space_id: "space",
|
||||
bound: true,
|
||||
can_create_review: true,
|
||||
review_entitlements: { can_register_project: false },
|
||||
},
|
||||
]);
|
||||
await expect(
|
||||
createShareService("/secret").run({ action: "share", audience: "public" }),
|
||||
).rejects.toBeDefined();
|
||||
expect(events()).toEqual([
|
||||
"share_mutation_attempted",
|
||||
"share_mutation_authenticated",
|
||||
"share_mutation_failed",
|
||||
]);
|
||||
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({
|
||||
reason: "review_project_limit_reached",
|
||||
});
|
||||
expect(mocks.render).not.toHaveBeenCalled();
|
||||
});
|
||||
it("records pending recovery without labeling the prior ready version new", async () => {
|
||||
mocks.status.mockResolvedValue(shared);
|
||||
mocks.pending.mockResolvedValue({ projectId: "project", videoId: "pending" });
|
||||
mocks.add.mockResolvedValue(null);
|
||||
mocks.version.mockResolvedValue({ last: { current: false }, source: "ready" });
|
||||
await createShareService("/secret").run({ action: "update" });
|
||||
expect(events()).toContain("share_recovery_attempted");
|
||||
expect(events()).toContain("share_mutation_processing");
|
||||
expect(events()).not.toContain("share_video_ready");
|
||||
expect(mocks.event.mock.lastCall?.[1]).toMatchObject({ recovery: true });
|
||||
});
|
||||
it("existing-link retrieval and polling never count as a new video or copied link", async () => {
|
||||
mocks.status.mockResolvedValue(shared);
|
||||
const service = createShareService("/secret");
|
||||
await service.run({ action: "status" });
|
||||
expect(events()).toEqual([]);
|
||||
await service.run({ action: "share" });
|
||||
expect(events()).toEqual([
|
||||
"share_mutation_attempted",
|
||||
"share_mutation_authenticated",
|
||||
"share_existing_link_returned",
|
||||
]);
|
||||
});
|
||||
it("stops entry creation on authoritative rollback while keeping existing links readable", async () => {
|
||||
mocks.flags.mockResolvedValue({ versionSharing: false });
|
||||
await expect(
|
||||
createShareService("/secret").run({ action: "share", audience: "public" }),
|
||||
).rejects.toMatchObject({ reason: "feature_unavailable" });
|
||||
expect(mocks.render).not.toHaveBeenCalled();
|
||||
expect(mocks.create).not.toHaveBeenCalled();
|
||||
mocks.status.mockResolvedValue(shared);
|
||||
expect((await createShareService("/secret").run({ action: "share" })).ready).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
it("link reactivation cannot bypass the first-share rollout gate", async () => {
|
||||
mocks.flags.mockResolvedValue({ versionSharing: false });
|
||||
await expect(createShareService("/secret").linkOn()).rejects.toMatchObject({
|
||||
reason: "not_shared",
|
||||
});
|
||||
expect(mocks.create).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
@@ -21,6 +21,7 @@ import { createShareAccess, shareSite } from "./auth.js";
|
||||
import { assertReviewUploadStorage, bindCliShareProject } from "./host.js";
|
||||
import { prepareShareRender } from "./render.js";
|
||||
import { prepareCliShareSource, uncheckedSource, type PreparedShareSource } from "./sources.js";
|
||||
import { observeShareMutation, type ShareAttempt, type ShareSurface } from "./telemetry.js";
|
||||
|
||||
export interface ShareAction {
|
||||
action: "share" | "update" | "status" | "manage";
|
||||
@@ -34,10 +35,25 @@ function linkState(share: ReviewShare | null, ready: boolean): string {
|
||||
if (!share.url) return "link_off";
|
||||
return ready ? "ready" : "processing";
|
||||
}
|
||||
async function readStatus(dir: string, client: ReviewClient, expectedProjectId?: string) {
|
||||
async function refreshShare(
|
||||
dir: string,
|
||||
client: ReviewClient,
|
||||
expectedProjectId?: string,
|
||||
onRecovery?: (pending: boolean) => void,
|
||||
) {
|
||||
const share = await reviewStatus({ projectPath: dir, client });
|
||||
if (expectedProjectId) assertUploadProject(share, expectedProjectId);
|
||||
if (onRecovery) onRecovery(isProcessing(await pendingReviewExport(dir), share));
|
||||
if (share) await refreshReviewExport(dir, client);
|
||||
return share;
|
||||
}
|
||||
async function readStatus(
|
||||
dir: string,
|
||||
client: ReviewClient,
|
||||
expectedProjectId?: string,
|
||||
onRecovery?: (pending: boolean) => void,
|
||||
) {
|
||||
const share = await refreshShare(dir, client, expectedProjectId, onRecovery);
|
||||
const project = await readProject(share, client);
|
||||
const latest = project?.latest_ready_version_id ?? null;
|
||||
const version = await reviewVersion(dir, { latestReadyVersionId: latest });
|
||||
@@ -142,6 +158,7 @@ function assertResumeSource(current: ShareState, input: ShareAction) {
|
||||
export function createShareService(
|
||||
projectPath: string,
|
||||
progress: (value: ReviewExportProgress | null) => void = () => {},
|
||||
options: { surface?: ShareSurface } = {},
|
||||
) {
|
||||
const dir = bindCliShareProject(projectPath);
|
||||
const auth = createShareAccess();
|
||||
@@ -150,7 +167,12 @@ export function createShareService(
|
||||
await auth.access();
|
||||
return readStatus(dir, client, expectedProjectId);
|
||||
};
|
||||
const upload = async (input: ShareAction, projectId: string, sources: PreparedShareSource) => {
|
||||
const upload = async (
|
||||
input: ShareAction,
|
||||
projectId: string,
|
||||
sources: PreparedShareSource,
|
||||
attempt: ShareAttempt,
|
||||
) => {
|
||||
const end = Date.now() + (input.waitSeconds ?? 300) * 1000;
|
||||
let added = false;
|
||||
const failure = await addVersion({
|
||||
@@ -158,7 +180,10 @@ export function createShareService(
|
||||
projectId,
|
||||
title: basename(dir),
|
||||
client,
|
||||
onProgress: progress,
|
||||
onProgress: (value) => {
|
||||
attempt.progress(value);
|
||||
progress(value);
|
||||
},
|
||||
allowPending: true,
|
||||
...(sources.filesForExport && { filesForExport: sources.filesForExport }),
|
||||
requireSource: sources.requireSource,
|
||||
@@ -171,8 +196,11 @@ export function createShareService(
|
||||
if (failure) throw new Error(failure);
|
||||
const result = { ...(await status(projectId)), source: sources.source };
|
||||
if (result.version.failure) throw new Error(result.version.failure);
|
||||
if (!added && !result.version.last?.current)
|
||||
if (!added && !result.version.last?.current) {
|
||||
attempt.complete(false, added);
|
||||
return { ...result, state: "processing", ready: false, url: null };
|
||||
}
|
||||
attempt.complete(result.ready, added);
|
||||
return result;
|
||||
};
|
||||
const uploadTarget = async (current: ReviewShare | null, input: ShareAction, space?: string) => {
|
||||
@@ -204,11 +232,15 @@ export function createShareService(
|
||||
audience: target.audience,
|
||||
});
|
||||
};
|
||||
const run = async (input: ShareAction) => {
|
||||
const current = await status();
|
||||
if (input.action === "status" || input.action === "manage") return current;
|
||||
const mutate = async (input: ShareAction, attempt: ShareAttempt) => {
|
||||
await auth.access();
|
||||
attempt.authenticated();
|
||||
const current = await readStatus(dir, client, undefined, attempt.recover);
|
||||
assertExistingIntent(current.share, input);
|
||||
if (retrievesExisting(current, input)) return current;
|
||||
if (retrievesExisting(current, input)) {
|
||||
attempt.retrieved();
|
||||
return current;
|
||||
}
|
||||
const flags = await client.reviewFlags();
|
||||
if (!flags.versionSharing) throw new ReviewFailed(403, "feature_unavailable");
|
||||
const space = current.share
|
||||
@@ -223,11 +255,16 @@ export function createShareService(
|
||||
shareFiles: flags.shareFiles,
|
||||
});
|
||||
if (sources.requireSource) await checkPreparedTarget(target);
|
||||
return upload(input, target.projectId, sources);
|
||||
return upload(input, target.projectId, sources, attempt);
|
||||
};
|
||||
return {
|
||||
status,
|
||||
run,
|
||||
run: (input: ShareAction) =>
|
||||
input.action === "status" || input.action === "manage"
|
||||
? status()
|
||||
: observeShareMutation(input.action, options.surface ?? "cli", (attempt) =>
|
||||
mutate(input, attempt),
|
||||
),
|
||||
capabilities: () => client.reviewFlags(),
|
||||
spaces: () => client.spaces(),
|
||||
setAccess: async (access: AccessMode) => {
|
||||
@@ -239,6 +276,7 @@ export function createShareService(
|
||||
return status();
|
||||
},
|
||||
linkOn: async () => {
|
||||
if (!(await status()).share) throw new ReviewFailed(404, "not_shared");
|
||||
await shareForReview({ projectPath: dir, title: basename(dir), client });
|
||||
return status();
|
||||
},
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterEach, beforeEach, expect, it, vi } from "vitest";
|
||||
|
||||
const mocks = vi.hoisted(() => ({ enqueue: vi.fn() }));
|
||||
vi.mock("../telemetry/transport.js", () => ({
|
||||
enqueue: mocks.enqueue,
|
||||
flush: vi.fn(),
|
||||
flushSync: vi.fn(),
|
||||
}));
|
||||
vi.mock("../utils/env.js", () => ({ isDevMode: () => false }));
|
||||
vi.mock("../telemetry/system.js", () => ({ getSystemMeta: () => ({}) }));
|
||||
vi.mock("../telemetry/canary.js", () => ({ canaryEventProperties: () => ({}) }));
|
||||
vi.mock("../telemetry/signedInUser.js", () => ({ signedInHeygenUsername: () => undefined }));
|
||||
import { observeShareMutation, trackShareInteraction } from "./telemetry.js";
|
||||
|
||||
let folder: string;
|
||||
function preference(enabled: boolean) {
|
||||
writeFileSync(
|
||||
join(folder, "config.json"),
|
||||
JSON.stringify({ anonymousId: "test", bucketSeed: "test", telemetryEnabled: enabled }),
|
||||
);
|
||||
}
|
||||
beforeEach(() => {
|
||||
mocks.enqueue.mockClear();
|
||||
folder = mkdtempSync(join(tmpdir(), "hf-share-opt-out-"));
|
||||
vi.stubEnv("HYPERFRAMES_CONFIG_DIR", folder);
|
||||
vi.stubEnv("HYPERFRAMES_NO_TELEMETRY", "");
|
||||
vi.stubEnv("DO_NOT_TRACK", "");
|
||||
preference(true);
|
||||
});
|
||||
afterEach(() => {
|
||||
vi.unstubAllEnvs();
|
||||
rmSync(folder, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
it("stops queueing events after a separate process changes the persisted preference", async () => {
|
||||
trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio");
|
||||
expect(mocks.enqueue).toHaveBeenCalledOnce();
|
||||
preference(false);
|
||||
mocks.enqueue.mockClear();
|
||||
trackShareInteraction({ event: "share_link_copied", via: "copy" }, "local_studio");
|
||||
await observeShareMutation("update", "local_studio", async (attempt) => {
|
||||
attempt.authenticated();
|
||||
attempt.complete(true, true);
|
||||
});
|
||||
expect(mocks.enqueue).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it.each(["HYPERFRAMES_NO_TELEMETRY", "DO_NOT_TRACK"])(
|
||||
"honors %s even after a previous event enabled the client cache",
|
||||
async (name) => {
|
||||
trackShareInteraction({ event: "share_opened", link: "none" });
|
||||
expect(mocks.enqueue).toHaveBeenCalledOnce();
|
||||
vi.stubEnv(name, "1");
|
||||
mocks.enqueue.mockClear();
|
||||
await observeShareMutation("share", "cli", async (attempt) => attempt.complete(true, true));
|
||||
expect(mocks.enqueue).not.toHaveBeenCalled();
|
||||
},
|
||||
);
|
||||
@@ -0,0 +1,49 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
const mocks = vi.hoisted(() => ({ track: vi.fn(), fresh: vi.fn(), reset: vi.fn() }));
|
||||
vi.mock("../telemetry/client.js", () => ({
|
||||
trackEvent: mocks.track,
|
||||
resetTelemetryPostureCache: mocks.reset,
|
||||
}));
|
||||
vi.mock("../telemetry/config.js", () => ({ readConfigFresh: mocks.fresh }));
|
||||
import { observeShareMutation, trackShareInteraction } from "./telemetry.js";
|
||||
beforeEach(() => vi.resetAllMocks());
|
||||
describe("share telemetry privacy boundary", () => {
|
||||
it("only forwards the declared interaction fields, never links or project data", () => {
|
||||
const input = {
|
||||
event: "share_link_copied" as const,
|
||||
via: "copy" as const,
|
||||
url: "https://private/token",
|
||||
project: "/example/project",
|
||||
};
|
||||
trackShareInteraction(input, "local_studio");
|
||||
expect(mocks.track).toHaveBeenCalledExactlyOnceWith("share_link_copied", {
|
||||
client_surface: "local_studio",
|
||||
via: "copy",
|
||||
});
|
||||
});
|
||||
it("refreshes persisted opt-out posture at each event in a long-lived preview", () => {
|
||||
trackShareInteraction({ event: "share_opened", link: "none" }, "local_studio");
|
||||
trackShareInteraction({ event: "share_link_copied", via: "publish" }, "local_studio");
|
||||
expect(mocks.fresh).toHaveBeenCalledTimes(2);
|
||||
expect(mocks.reset).toHaveBeenCalledTimes(2);
|
||||
});
|
||||
it("drops unknown failure reasons and never sends raw messages", async () => {
|
||||
const error = Object.assign(new Error("secret email@example.com"), {
|
||||
reason: "/secret/project",
|
||||
});
|
||||
await expect(
|
||||
observeShareMutation("update", "cli", async () => {
|
||||
throw error;
|
||||
}),
|
||||
).rejects.toBe(error);
|
||||
expect(mocks.track.mock.lastCall?.[1]).toMatchObject({ reason: "other" });
|
||||
expect(JSON.stringify(mocks.track.mock.calls)).not.toContain("secret");
|
||||
});
|
||||
it("telemetry configuration errors cannot block sharing or change its failure", async () => {
|
||||
mocks.fresh.mockImplementation(() => {
|
||||
throw new Error("EACCES");
|
||||
});
|
||||
expect(await observeShareMutation("share", "cli", async () => "done")).toBe("done");
|
||||
expect(mocks.track).not.toHaveBeenCalled();
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,96 @@
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { AuthError } from "../auth/errors.js";
|
||||
import { CliUsageError } from "../utils/commandResult.js";
|
||||
import { readConfigFresh } from "../telemetry/config.js";
|
||||
import { resetTelemetryPostureCache, trackEvent } from "../telemetry/client.js";
|
||||
import type { ReviewExportProgress } from "@hyperframes/share";
|
||||
|
||||
export type ShareSurface = "cli" | "local_studio";
|
||||
export type ShareInteraction =
|
||||
| { event: "share_opened"; link: "none" | "live" | "changed" }
|
||||
| { event: "share_link_copied"; via: "copy" | "publish" | "update" };
|
||||
const REASONS = new Set([
|
||||
"feature_unavailable",
|
||||
"audience_required",
|
||||
"workspace_cannot_share",
|
||||
"workspace_mismatch",
|
||||
"manage_existing_audience",
|
||||
"review_project_limit_reached",
|
||||
"review_subscription_required",
|
||||
"review_entitlement_unavailable",
|
||||
"review_public_consent_required",
|
||||
"moderation_hold",
|
||||
"review_operation_busy",
|
||||
"not_shared",
|
||||
"offline",
|
||||
"signed_out",
|
||||
]);
|
||||
function failureReason(error: unknown): string {
|
||||
if (error instanceof AuthError) return "authentication";
|
||||
if (error instanceof CliUsageError && REASONS.has(error.code)) return error.code;
|
||||
if (typeof error === "object" && error !== null && "reason" in error) {
|
||||
const reason = error.reason;
|
||||
if (typeof reason === "string" && REASONS.has(reason)) return reason;
|
||||
}
|
||||
return "other";
|
||||
}
|
||||
function emit(event: string, properties: Record<string, string | boolean>): void {
|
||||
try {
|
||||
// A preview process can outlive an opt-out made from another terminal.
|
||||
readConfigFresh();
|
||||
resetTelemetryPostureCache();
|
||||
trackEvent(event, properties);
|
||||
} catch {
|
||||
// Telemetry must not alter whether a share succeeds or fails.
|
||||
}
|
||||
}
|
||||
export function trackShareInteraction(input: ShareInteraction, surface: ShareSurface = "cli") {
|
||||
if (input.event === "share_opened")
|
||||
emit(input.event, { client_surface: surface, link: input.link });
|
||||
else emit(input.event, { client_surface: surface, via: input.via });
|
||||
}
|
||||
function shareAttempt(action: "share" | "update", surface: ShareSurface) {
|
||||
const base = { client_surface: surface, action, attempt_id: randomUUID() };
|
||||
let admitted = false;
|
||||
let recovery = false;
|
||||
const track = (event: string, extra: Record<string, string | boolean> = {}) =>
|
||||
emit(event, { ...base, recovery, ...extra });
|
||||
const admit = () => {
|
||||
if (admitted) return;
|
||||
admitted = true;
|
||||
track("share_mutation_admitted");
|
||||
};
|
||||
track("share_mutation_attempted");
|
||||
return {
|
||||
authenticated: () => track("share_mutation_authenticated"),
|
||||
recover: (pending: boolean) => {
|
||||
recovery = pending;
|
||||
if (pending) track("share_recovery_attempted");
|
||||
},
|
||||
progress: (value: ReviewExportProgress | null) => {
|
||||
if (value && value.step !== "preparing") admit();
|
||||
},
|
||||
retrieved: () => track("share_existing_link_returned"),
|
||||
complete: (ready: boolean, added: boolean) => {
|
||||
if (!added)
|
||||
return track(ready ? "share_existing_link_returned" : "share_mutation_processing");
|
||||
admit();
|
||||
track("share_video_ready");
|
||||
},
|
||||
failed: (error: unknown) => track("share_mutation_failed", { reason: failureReason(error) }),
|
||||
};
|
||||
}
|
||||
export type ShareAttempt = ReturnType<typeof shareAttempt>;
|
||||
export async function observeShareMutation<T>(
|
||||
action: "share" | "update",
|
||||
surface: ShareSurface,
|
||||
run: (attempt: ShareAttempt) => Promise<T>,
|
||||
): Promise<T> {
|
||||
const attempt = shareAttempt(action, surface);
|
||||
try {
|
||||
return await run(attempt);
|
||||
} catch (error) {
|
||||
attempt.failed(error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user