@hyperframes/share 0.0.0-stage → 0.9.21

package/dist/reviewExport.d.mts

@@ -0,0 +1,172 @@
+/** ffprobe's JSON as facts, or null when it names no picture or no length. @param {string} stdout */
+export function factsOf(stdout: string): {
+    duration: number;
+    width: any;
+    height: any;
+} | null;
+/** What the popover shows about versions. `last.current`: the project as it is now and, when the server says, still
+ * its latest ready version (a removed one, or a newer one from elsewhere, is not "on the page").
+ * @param {string} projectPath @param {{ latestReadyVersionId?: string | null }} [server] */
+export function reviewVersion(projectPath: string, server?: {
+    latestReadyVersionId?: string | null;
+}): Promise<{
+    held?: boolean | undefined;
+    failure: string;
+    retryable: boolean;
+    exportHelps: boolean;
+    last: {
+        exportedAt: string;
+        current: boolean;
+    } | null;
+    source: "ready" | "none" | "not-mp4" | "stale";
+    exporting: import("./types/share.js").ReviewExportProgress | null;
+} | {
+    failure: null;
+    last: {
+        exportedAt: string;
+        current: boolean;
+    } | null;
+    source: "ready" | "none" | "not-mp4" | "stale";
+    exporting: import("./types/share.js").ReviewExportProgress | null;
+}>;
+/** Adds the newest export as a version and resolves once it is ready, failed, or out of watch, with the sentence when
+ * it did not go up. One run per project; a second asks nothing and resolves at once. A run onto another project keeps
+ * a failure from before the upload to itself: the recorded page is not the one it failed on.
+ * @param {VersionRequest} request @returns {Promise<string | null>} */
+export function addVersion(request: VersionRequest): Promise<string | null>;
+/** The popover opening reads a held video again: a running watch reads now, and one that ran out reads the video
+ * back once, so a video staff approved or refused since shows as it is. A read that finds it still held changes
+ * nothing; Check again starts a new watch.
+ * @param {string} projectPath @param {ReviewClient} client @param {FromReview | null} [fromReview] */
+export function recheckHeld(projectPath: string, client: ReviewClient, fromReview?: FromReview | null): Promise<undefined>;
+/** Settle a saved upload after its host exits, without competing with an active uploader.
+ * @param {string} projectPath @param {ReviewClient} client @param {FromReview | null} [fromReview] */
+export function refreshReviewExport(projectPath: string, client: ReviewClient, fromReview?: FromReview | null): Promise<void>;
+/** The first share puts the newest export up with the link, when there is one to put and no version yet.
+ * @param {VersionRequest} request */
+export function addFirstVersion(request: VersionRequest): Promise<void>;
+/** What the files line and a later attach read of a project's versions: the newest one this app put on the page, with
+ * whether the project is still as it was then; whether the newest export is the project now; whether a run is out.
+ * @param {string} dir */
+export function versionFacts(dir: string): Promise<{
+    last: {
+        current: boolean;
+        fingerprint: string;
+        versionId: string;
+        exportedAt: string;
+        projectId: string;
+        files?: boolean;
+        checksum?: string;
+    } | null;
+    source: "ready" | "none" | "not-mp4" | "stale";
+    running: boolean;
+}>;
+/** The newest version this app put on the page, read without hashing the project; null while a run is out.
+ * @param {string} dir */
+export function versionOnPage(dir: string): Promise<{
+    fingerprint: string;
+    versionId: string;
+    exportedAt: string;
+    projectId: string;
+    files?: boolean;
+    checksum?: string;
+} | null>;
+/** Records that `versionId` carries files now, if it is still the last ready version.
+ * @param {string} dir @param {string} versionId @param {string} [projectId] */
+export function markFiles(dir: string, versionId: string, projectId?: string): Promise<void>;
+/** A pending operation is not the last ready version. @param {string} projectPath */
+export function pendingReviewExport(projectPath: string): Promise<{
+    projectId: string | null;
+    videoId: string | null;
+    operationId: string;
+    fingerprint: string | null;
+    checksum: string;
+} | null>;
+export type SavedLast = Omit<NonNullable<VersionRecord["last"]>, "fingerprint"> & {
+    fingerprint?: string;
+};
+export type ReviewClient = import("./reviewClient.mjs").ReviewClient;
+export type ExportDTO = import("./types/reviewWire.js").ExportDTO;
+export type ExportRequest = import("./types/reviewWire.js").ExportRequest;
+export type ReviewVersion = import("./types/share.js").ReviewVersion;
+export type ReviewExportProgress = import("./types/share.js").ReviewExportProgress;
+export type VideoFacts = {
+    duration: number;
+    width: number;
+    height: number;
+};
+export type FromReview = import("./fromReview.mjs").FromReview;
+export type ReviewSent = {
+    since: number;
+    value?: "yes" | "no";
+};
+export type Added = {
+    files: boolean;
+    first: boolean;
+    fromReview?: "yes" | "no";
+};
+/**
+ * `pending`: the create body as sent and its video once answered, so a retry is the same; `snapshotRefused`: the
+ * server refused its snapshot, so it goes up video-only; `unanswered`: its create may have gone out without a
+ * definitive result; `reviewSent`: cleanup cutoff, with attribution only when the accepted attempt is
+ * known; `last`: the newest version.
+ */
+export type VersionRecord = {
+    pending: {
+        body: ExportRequest;
+        videoId: string | null;
+        projectId?: string | null;
+        checkingSince?: number;
+        snapshotRefused?: boolean;
+        unanswered?: boolean;
+        reviewSent?: ReviewSent;
+    } | null;
+    last: {
+        fingerprint: string;
+        versionId: string;
+        exportedAt: string;
+        projectId: string;
+        files?: boolean;
+        checksum?: string;
+    } | null;
+};
+/**
+ * `onAdded`: a version went ready, with whether it carries files and whether it is the page's first from here.
+ */
+export type VersionHooks = {
+    onProgress?: (progress: ReviewExportProgress | null) => void;
+    onUploaded?: () => Promise<void>;
+    open?: () => boolean;
+    onAdded?: (added: Added) => void;
+};
+/**
+ * `projectId` overrides the recorded review project; `open`: a held video is watched only while the project is open.
+ * `filesForExport`: the synced snapshot a new version carries, null for
+ * none.
+ */
+export type VersionRequest = VersionHooks & {
+    projectPath: string;
+    title: string;
+    client: ReviewClient;
+    put?: typeof putFile;
+    sleep?: (ms: number) => Promise<void>;
+    probe?: (file: string) => Promise<VideoFacts | null>;
+    now?: () => number;
+    projectId?: string | null;
+    filesForExport?: FilesForRender;
+    fromReview?: FromReview | null;
+};
+/**
+ * The snapshot of `rendered`, the project as the export was rendered; null when the folder is not that render.
+ */
+export type FilesForRender = (projectPath: string, rendered: string | null) => Promise<import("./types/reviewWire.js").SnapshotRef | null>;
+export type Said = {
+    sentence: string;
+    final: boolean;
+    exportHelps: boolean;
+    held?: boolean;
+};
+export type Failure = Said & {
+    exportKey: string;
+};
+import { putFile } from "./reviewUpload.mjs";

package/dist/reviewFiles.d.mts

@@ -0,0 +1,43 @@
+/** Files vs. the last sync: `off` (share_files or sync off), `elsewhere`
+ * (syncs to `workspace`, not ours), `differs` (no sync, syncing, writing, changed), `matches` (a version can carry it).
+ * @typedef {{ at: "off" } | { at: "differs" } | { at: "elsewhere", workspace: string }
+ *   | { at: "matches", snapshot: import("./types/reviewWire.js").SnapshotRef }} SyncedFiles */
+/** @typedef {import("./types/share.js").ReviewFiles} FilesAnswer */
+/** The files line from what is known: the version on the page carrying files says so first; a project synced to
+ * another workspace says which, since neither a sync nor a render here fixes it; a project moved past its render is
+ * `changed`; a render not on the page yet is `included` when the version it would add carries files.
+ * @param {Awaited<ReturnType<typeof versionFacts>>} facts @param {SyncedFiles} found @returns {FilesAnswer} */
+export function filesStateOf({ last, source }: Awaited<ReturnType<typeof versionFacts>>, found: SyncedFiles): FilesAnswer;
+/** `match` answers the files line; `forRender` is the only way to files for a version, held to its render (the same
+ * one an export's `filesForExport` is). @param {{ client: Pick<import("./reviewClient.mjs").ReviewClient,
+ *   "attachSnapshot">, match: (projectPath: string) => Promise<SyncedFiles>,
+ *   forRender: import("./reviewExport.mjs").FilesForRender }} deps */
+export function reviewFiles({ client, match, forRender }: {
+    client: Pick<import("./reviewClient.mjs").ReviewClient, "attachSnapshot">;
+    match: (projectPath: string) => Promise<SyncedFiles>;
+    forRender: import("./reviewExport.mjs").FilesForRender;
+}): {
+    /** Attaches the last sync to the version on the page when it can; anything else leaves it as it is. */
+    attach: (dir: string) => Promise<void>;
+    /** The files line, once any attach a sync made possible has gone in. @param {string} dir
+     * @returns {Promise<FilesAnswer>} */
+    state: (dir: string) => Promise<FilesAnswer>;
+};
+/**
+ * Files vs. the last sync: `off` (share_files or sync off), `elsewhere`
+ * (syncs to `workspace`, not ours), `differs` (no sync, syncing, writing, changed), `matches` (a version can carry it).
+ */
+export type SyncedFiles = {
+    at: "off";
+} | {
+    at: "differs";
+} | {
+    at: "elsewhere";
+    workspace: string;
+} | {
+    at: "matches";
+    snapshot: import("./types/reviewWire.js").SnapshotRef;
+};
+export type FilesAnswer = import("./types/share.js").ReviewFiles;
+export type ReviewFiles = ReturnType<typeof reviewFiles>;
+import { versionFacts } from "./reviewExport.mjs";

package/dist/reviewLinkStates.d.mts

@@ -0,0 +1,18 @@
+/** @param {import("./types/reviewWire.js").ShareDTO} share @returns {LinkStateRead} */
+export function linkStateOf(share: import("./types/reviewWire.js").ShareDTO): LinkStateRead;
+/** Each project's link, read a few at a time; a read that fails leaves that project out, so its row shows no state.
+ * @param {{ client: { share: (id: string) => Promise<import("./types/reviewWire.js").ShareDTO> },
+ *   projectIds: string[] }} request
+ * @returns {Promise<Record<string, LinkStateRead>>} */
+export function reviewLinkStates({ client, projectIds }: {
+    client: {
+        share: (id: string) => Promise<import("./types/reviewWire.js").ShareDTO>;
+    };
+    projectIds: string[];
+}): Promise<Record<string, LinkStateRead>>;
+export type LinkState = "on" | "off" | "paused" | "taken-down";
+export type LinkStateRead = {
+    state: LinkState;
+    access: import("./types/share.js").AccessMode;
+    pausedFor?: "report" | "plan";
+};

package/dist/reviewOpenCalls.d.mts

@@ -0,0 +1,16 @@
+/** @param {(what: string, method: string, route: string, body?: unknown) => Promise<any>} tokenCall */
+export function shareOpenCalls(tokenCall: (what: string, method: string, route: string, body?: unknown) => Promise<any>): {
+    /** C1, for the requested version or the latest. @param {string} token @param {string | null} versionId
+     * @returns {Promise<import("./types/shareOpen.js").OpenSummaryDTO>} */
+    openSummary: (token: string, versionId: string | null) => Promise<import("./types/shareOpen.js").OpenSummaryDTO>;
+    /** C2: the snapshot's manifest and the first signed URLs (at most 500 files).
+     * @param {string} token @param {string} versionId @returns {Promise<import("./types/shareOpen.js").VersionFilesDTO>} */
+    versionFiles: (token: string, versionId: string) => Promise<import("./types/shareOpen.js").VersionFilesDTO>;
+    /** C2's refresh: URLs for `sha256s` (at most 500) of the same snapshot, by the token the last answer carried.
+     * @param {string} token @param {string} versionId @param {string} continuation @param {string[]} sha256s
+     * @returns {Promise<import("./types/shareOpen.js").FileUrlsDTO>} */
+    fileUrls: (token: string, versionId: string, continuation: string, sha256s: string[]) => Promise<import("./types/shareOpen.js").FileUrlsDTO>;
+    /** C3: a copy finished; the same handoff again is the same copy. The server answers 204 with no body.
+     * @param {string} token @param {string} versionId @param {string | null} handoffId @returns {Promise<null>} */
+    logCopy: (token: string, versionId: string, handoffId: string | null) => Promise<null>;
+};

package/dist/reviewShare.d.mts

@@ -0,0 +1,106 @@
+/** Every space the account is in, the signed-in one marked: the later workspace switch lists them; v1 names one.
+ * @param {{ client: ReviewClient }} request @returns {Promise<ReviewSpace[]>} */
+export function reviewSpaces({ client }: {
+    client: ReviewClient;
+}): Promise<ReviewSpace[]>;
+/** The share as the person sees it: owner routes do not hold a token to its workspace, so a page in another one
+ * than Desktop is signed into works as any other, and is only named (`elsewhere`). A failed list names nothing.
+ * @param {ReviewClient} client @param {ShareDTO} share @returns {Promise<ReviewShare>} */
+export function shown(client: ReviewClient, share: ShareDTO): Promise<ReviewShare>;
+/** A line per project: each step runs once the one before it settled; `busy` while one runs or waits. */
+export function projectLine(): {
+    inTurn: <T>(projectPath: string, run: () => Promise<T>) => Promise<T>;
+    busy: (projectPath: string) => boolean;
+};
+/** Applies the person's choice over whatever else the share holds; a stale revision is read again once.
+ * @param {ReviewClient} client @param {string} id @param {ShareDTO} share
+ * @param {Partial<Pick<ShareDTO, "access_mode" | "default_role">>} change @returns {Promise<ShareDTO>} */
+export function changeShare(client: ReviewClient, id: string, share: ShareDTO, change: Partial<Pick<ShareDTO, "access_mode" | "default_role">>): Promise<ShareDTO>;
+/** The server's id for a project this app finished sharing, else null; the comment feed reads it.
+ * @param {string} projectPath @returns {Promise<string | null>} */
+export function reviewProjectId(projectPath: string): Promise<string | null>;
+/** Which local project each review project was shared from: review project id to its folder.
+ * @param {string[]} paths @returns {Promise<Record<string, string>>} */
+export function localReviewProjects(paths: string[]): Promise<Record<string, string>>;
+/** @param {string} dir @returns {Promise<import("./reviewSwitch.mjs").Switch | null>} */
+export function readReviewSwitch(dir: string): Promise<import("./reviewSwitch.mjs").Switch | null>;
+/** Points the record at another review project, keeping every other field the record holds.
+ * @param {string} projectPath @param {string} projectId @param {string} spaceId */
+export function rebindRecord(projectPath: string, projectId: string, spaceId: string): Promise<void>;
+/** Shares a project anew from the signed-in account: its record set aside, then `share` makes the new link, and the
+ * feed in view follows to the new page.
+ * @template T @param {string} projectPath @param {() => Promise<T>} share @returns {Promise<T>} */
+export function shareAnew<T>(projectPath: string, share: () => Promise<T>): Promise<T>;
+/** The link as the server holds it now; null until the first share finished.
+ * @param {{ projectPath: string, client: ReviewClient }} request @returns {Promise<ReviewShare | null>} */
+export function reviewStatus({ projectPath, client }: {
+    projectPath: string;
+    client: ReviewClient;
+}): Promise<ReviewShare | null>;
+/** @param {ReviewClient} client @param {string} id @param {ShareDTO} share
+ * @param {import("./types/share.js").AccessMode} [audience] */
+export function applyFirstAudience(client: ReviewClient, id: string, share: ShareDTO, audience?: import("./types/share.js").AccessMode): Promise<import("./types/reviewWire.js").ShareDTO>;
+/** The one sentence a person reads for a failed call; the log keeps the status and reason. `fallback` names the
+ * call when the reason has no sentence of its own.
+ * @param {unknown} error @param {string} [fallback] */
+export function reviewSentence(error: unknown, fallback?: string): string;
+/** Locks each open binding involved in this removal before sending DELETE, including a move's source.
+ * @param {string} projectId @param {ReviewClient} client @param {string[]} projectPaths */
+export function removeReviewProject(projectId: string, client: ReviewClient, projectPaths: string[]): Promise<void>;
+/** The owner workspace of an unfinished binding takes precedence over the active workspace.
+ * @param {{client: ReviewClient, projectPath: string}} request @returns {Promise<ReviewSpace | null>} */
+export function reviewDestination({ client, projectPath }: {
+    client: ReviewClient;
+    projectPath: string;
+}): Promise<ReviewSpace | null>;
+export function setReviewSite(now: string): void;
+export function reviewRecordPath(projectPath: string): string;
+export function takenDown(share: ShareDTO): boolean;
+export function listSpaces(client: ReviewClient): Promise<import("./types/reviewWire.js").SpaceDTO[] | never[]>;
+export function ownerOf(reason: string): string | null;
+export function oneAtATime<T>(projectPath: string, run: () => Promise<T>): Promise<T>;
+export function reviewRecord(projectPath: string): Promise<ReviewRecord | null>;
+export function reviewSwitchPath(projectPath: string): string;
+export function onRebound(listener: (projectPath: string) => void): undefined;
+export function setAsideReview(projectPath: string): Promise<void>;
+export function readShare(client: ReviewClient, id: string, projectPath?: string): Promise<import("./types/reviewWire.js").ShareDTO>;
+export function shareForReview({ projectPath, title, client, spaceId, audience }: {
+    projectPath: string;
+    title: string;
+    client: ReviewClient;
+    spaceId?: string | null;
+    audience?: import("./types/share.js").AccessMode | undefined;
+}): Promise<import("./types/share.js").ReviewShare>;
+export function setReviewAccess({ projectPath, client, change }: {
+    projectPath: string;
+    client: ReviewClient;
+    change: ReviewAccessChange;
+}): Promise<ReviewShare>;
+export function turnOffReviewLink({ projectPath, client }: {
+    projectPath: string;
+    client: ReviewClient;
+}): Promise<ReviewShare>;
+export function markReviewRemoved(projectPath: string, projectId: string): Promise<void>;
+export function removeLocalReview(projectPath: string, projectId: string, client: ReviewClient): Promise<void>;
+export type ReviewClient = import("./reviewClient.mjs").ReviewClient;
+export type ShareDTO = import("./types/reviewWire.js").ShareDTO;
+export type ReviewShare = import("./types/share.js").ReviewShare;
+export type ReviewSpace = import("./types/share.js").ReviewSpace;
+export type ReviewAccessChange = import("./types/share.js").ReviewAccessChange;
+/**
+ * Persist studioProjectId/spaceId before sending so a lost reply retries the same project and space; projectId after.
+ * opened marks the first completed share; site/ownerEmail bind the record to its backend/account.
+ */
+export type ReviewRecord = {
+    studioProjectId: string;
+    spaceId: string | null;
+    projectId: string | null;
+    opened: boolean;
+    site: string;
+    ownerEmail: string | null;
+    removed?: boolean;
+    registration?: import("./types/reviewWire.js").RegisterProjectRequest | undefined;
+};
+export type SavedIdentity = {
+    studioProjectId: string;
+} & Partial<Pick<ReviewRecord, "spaceId" | "projectId" | "opened" | "removed">>;

package/dist/reviewSwitch.d.mts

@@ -0,0 +1,53 @@
+/** What the popover says of an old link still on: where it is, and whether retries keep failing.
+ * @param {string} projectPath @returns {Promise<ReviewShare["oldLink"]>} */
+export function oldLinkOf(projectPath: string): Promise<ReviewShare["oldLink"]>;
+/** The sentence for a failed change of space; any other failure reads as the share's, or as `fallback`.
+ * @param {unknown} error @param {string} [fallback] */
+export function switchSentence(error: unknown, fallback?: string): string;
+export function switchOperationId(studioProjectId: string, spaceId: string, from: string, title: string): string;
+export function retryOldLink({ projectPath, client }: {
+    projectPath: string;
+    client: ReviewClient;
+}): Promise<void>;
+export function changeSpace({ projectPath, title, client, spaceId, upload, canUpload, audience }: {
+    projectPath: string;
+    title: string;
+    client: ReviewClient;
+    spaceId: string;
+    upload: Upload;
+    canUpload: CanUpload;
+    audience?: import("./types/share.js").AccessMode | undefined;
+}): Promise<ReviewShare>;
+export function resumeSpaceChange({ projectPath, client, upload, canUpload }: {
+    projectPath: string;
+    client: ReviewClient;
+    upload: Upload;
+    canUpload: CanUpload;
+}): Promise<void>;
+export type ReviewClient = import("./reviewClient.mjs").ReviewClient;
+export type ReviewShare = import("./types/share.js").ReviewShare;
+/**
+ * `body`: the registration as sent, so a retry is exact; `revokeFailures`: failed turn-offs of the old link.
+ */
+export type Switch = {
+    id?: string;
+    from: string;
+    fromSpace?: string;
+    spaceId: string;
+    space: string;
+    projectId: string | null;
+    opened?: boolean;
+    paused?: boolean;
+    audience?: import("./types/share.js").AccessMode | undefined;
+    revokeFailures?: number;
+    body: import("./types/reviewWire.js").RegisterProjectRequest;
+};
+/**
+ * Puts the newest export on `projectId`; `onUploaded` runs once the server has it. Answers the sentence when it did
+ * not go up.
+ */
+export type Upload = (projectId: string, onUploaded: () => Promise<void>) => Promise<string | null>;
+/**
+ * Why the newest export cannot go up now, or null when it can.
+ */
+export type CanUpload = () => Promise<"export_first" | "version_running" | null>;

package/dist/reviewUpload.d.mts

@@ -0,0 +1,16 @@
+/** The checksum the export route takes: the SHA-256 digest as padded base64, never hex.
+ * @param {string} file @returns {Promise<string>} */
+export function fileSha256Base64(file: string): Promise<string>;
+/** @typedef {"sent" | "expired" | "refused" | "offline"} PutOutcome */
+/** Streams the file to the signed URL through main's fetch (the app's proxy), the server's headers as given plus
+ * the length, and no bearer. Nothing sent or answered for `stallMs` ends it as offline, never "Uploading" forever.
+ * @param {{ put_url: string, headers: Record<string, string> }} upload @param {string} file @param {number} size
+ * @param {(sent: number) => void} onSent @param {{ stallMs?: number, fetchImpl?: typeof fetch }} [options] */
+export function putFile(upload: {
+    put_url: string;
+    headers: Record<string, string>;
+}, file: string, size: number, onSent: (sent: number) => void, { stallMs, fetchImpl }?: {
+    stallMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<PutOutcome>;
+export type PutOutcome = "sent" | "expired" | "refused" | "offline";

package/dist/reviewVersionSentences.d.mts

@@ -0,0 +1,2 @@
+/** @param {unknown} error */
+export function versionSentence(error: unknown): string;

package/dist/signedInRequest.d.mts

@@ -0,0 +1,56 @@
+/** `access(refused)`, or UNREACHABLE when the saved sign-in's renewal could not reach HeyGen; other errors rethrow.
+ * @template T @param {(refused?: string) => Promise<T>} access @param {string} [refused] */
+export function readOrUnreachable<T>(access: (refused?: string) => Promise<T>, refused?: string): Promise<"unreachable" | T>;
+/** The sign-in each send reads again: the bearer, the backend it is for and the account it is; null signed out, and
+ * a reader may throw AccountUnreachable. A host's reader may take a bearer a server refused, which these requests
+ * never pass.
+ * @typedef {(refused?: string) => Promise<{ token: string, heygen: string, heygenApi: string, owner?: string | null }
+ *   | null>} SignedInAccess */
+/** `host` picks the sign-in host or HeyGen's /v3 API; `trace` marks `answers` as answers, not failures.
+ * `headers` go on every send, beneath a call's own.
+ * @typedef {{ access: SignedInAccess, fetchImpl?: typeof fetch, timeoutMs: number, tag: string, offline: () => Error,
+ *   headers?: Record<string, string>,
+ *   signedOut: () => Error, host?: "heygen" | "heygenApi",
+ *   trace?: (init: RequestInit, answers: number[]) => RequestInit }} SignedInDeps */
+/** Requests to a HeyGen host as the signed-in person. A 401 reads the sign-in again and retries only with a
+ * renewed token; a second 401 comes back as the answer. Signed out, or the same token refused, throws `signedOut()`;
+ * an unreachable server throws `offline()`. @param {SignedInDeps} deps */
+export function signedInRequest({ access, fetchImpl, timeoutMs, tag, offline, signedOut, host, headers: always, trace, }: SignedInDeps): (method: string, route: string, body?: unknown, headers?: Record<string, string>, answers?: number[] | null, label?: string) => Promise<{
+    reply: Response;
+    heygen: string;
+    owner: string | null;
+}>;
+/** The sign-in exists but its renewal could not reach HeyGen: a reader throws it, and a request reads it as offline,
+ * never as signed out. */
+export class AccountUnreachable extends Error {
+    constructor();
+}
+/** What a sign-in read yields, through readOrUnreachable, when its renewal could not reach HeyGen. */
+export const UNREACHABLE: "unreachable";
+export function orIfUnreachable<A extends any[], R>(run: (...args: A) => Promise<R>, value: R): (/** @type {A} */ ...args: A) => Promise<R>;
+/**
+ * The sign-in each send reads again: the bearer, the backend it is for and the account it is; null signed out, and
+ * a reader may throw AccountUnreachable. A host's reader may take a bearer a server refused, which these requests
+ * never pass.
+ */
+export type SignedInAccess = (refused?: string) => Promise<{
+    token: string;
+    heygen: string;
+    heygenApi: string;
+    owner?: string | null;
+} | null>;
+/**
+ * `host` picks the sign-in host or HeyGen's /v3 API; `trace` marks `answers` as answers, not failures.
+ * `headers` go on every send, beneath a call's own.
+ */
+export type SignedInDeps = {
+    access: SignedInAccess;
+    fetchImpl?: typeof fetch;
+    timeoutMs: number;
+    tag: string;
+    offline: () => Error;
+    headers?: Record<string, string>;
+    signedOut: () => Error;
+    host?: "heygen" | "heygenApi";
+    trace?: (init: RequestInit, answers: number[]) => RequestInit;
+};

package/dist/storage.d.mts

@@ -0,0 +1,20 @@
+/** Create metadata folders only inside an existing project. @param {string} root @param {string} rel */
+export function mkdirInside(root: string, rel: string): Promise<string>;
+/** @param {string} path @param {unknown} data */
+export function writeJsonAtomic(path: string, data: unknown): Promise<void>;
+/** @template T @param {string} path @param {T} fallback @returns {Promise<Record<string, unknown> | Exclude<T, object>>} */
+export function readJsonOr<T>(path: string, fallback: T): Promise<Record<string, unknown> | Exclude<T, object>>;
+/** An absent file is the only source of an empty record. @param {string} path */
+export function readJsonRecord(path: string): Promise<Record<string, unknown> | null>;
+export function errorCode(error: unknown): unknown;
+export function rename(from: string, to: string): Promise<void>;
+export function rm(path: string, options?: import("node:fs").RmOptions): Promise<void>;
+export class SharingStateError extends Error {
+    /** @param {string} path @param {unknown} [cause] */
+    constructor(path: string, cause?: unknown);
+}
+export function isJsonObject(value: unknown): value is Record<string, unknown>;
+export function isSavedId(value: unknown): value is string;
+export function isNullableSavedId(value: unknown): value is string | null;
+export function isOptionalSavedId(value: unknown): value is string | null | undefined;
+export function isOptionalBoolean(value: unknown): value is boolean | undefined;

package/dist/types/access.d.ts

@@ -0,0 +1,12 @@
+/** Read for each request, so a share that outlives a token meets the renewed one; pass a bearer a server refused.
+ * `owner` is the account the token is (accountPrincipal), for what is counted per account. */
+/** `orOffline`: a saved sign-in whose renewal could not reach HeyGen throws AccountUnreachable instead of null. */
+export type ApiAccess = (
+  refused?: string,
+  orOffline?: boolean,
+) => Promise<{
+  token: string;
+  owner: string | null;
+  heygen: string;
+  heygenApi: string;
+} | null>;

package/dist/types/review.d.ts

@@ -0,0 +1,59 @@
+export type ReviewPoint = [number, number];
+/** Where on the video a comment points, as the share page sends it. */
+export type ReviewAnchor =
+  | { version: 1; kind: "moment"; time: number; at?: ReviewPoint | null; from?: ReviewPoint | null }
+  | { version: 1; kind: "range"; start: number; end: number }
+  | { version: 1; kind: "region"; time: number; points: ReviewPoint[]; elements?: string[] }
+  | { version: 1; kind: "element"; time: number; selector: string; label?: string | null }
+  | { version: 1; kind: "track"; time: number; track: number };
+
+/** A review comment as the window sees it: no signed URL, no author id. */
+export interface ReviewComment {
+  id: string;
+  parentId: string | null;
+  body: string;
+  anchor: ReviewAnchor | null;
+  /** The export the comment was left on. */
+  origin: { versionId: string; exportedAt: string; width: number; height: number } | null;
+  /** Project-relative path of the saved frame once it is on disk; null until then, when there is none, or once the
+   * thread is resolved. */
+  framePath: string | null;
+  /** The comment carries a saved frame (the share page's capture can fail, leaving an anchored comment without one). */
+  hasFrame: boolean;
+  author: string;
+  authorRole: "owner" | "editor" | "commenter" | "viewer" | "guest" | null;
+  status: "open" | "resolved" | null;
+  /** `completed`: accepted, and the edit it asked for is done (the `resolve` action). */
+  resolution: "accepted" | "dismissed" | "completed" | null;
+  /** The thread was forwarded for follow-up. Defaults to false when absent. */
+  forwarded: boolean;
+  revision: number;
+  statusRevision: number | null;
+  createdAt: string;
+  deleted: boolean;
+  canResolve: boolean;
+  /** The server's hashed, project-scoped ref for a root comment, sent only to those who can decide; absent from older
+   * servers. Usage events alone carry it: it is never shown and never goes into a request to the agent. */
+  analyticsRef?: string;
+}
+
+/** The thread decisions the review server takes on its status route. */
+export type ReviewAction = "accept" | "dismiss" | "reopen" | "resolve";
+
+/** A thread write's answer: the thread's new status revision, or why it was refused. */
+export type ReviewWriteResult =
+  | { ok: true; statusRevision: number | null }
+  | {
+      ok: false;
+      reason: "conflict" | "forwarded" | "offline" | "signed-out" | "denied" | "gone" | "failed";
+    };
+
+/** The project's review comments, kept current while the project is in view. */
+export interface ReviewFeedView {
+  /** off: the flag is off, or the project was never shared for review. */
+  state: "off" | "loading" | "ready" | "reconnecting" | "signed-out" | "denied" | "gone";
+  comments: ReviewComment[];
+  latestVersionId: string | null;
+  reviewUrl: string | null;
+  syncedAt: number | null;
+}