@hyperframes/share 0.0.0-stage → 0.9.22

package/src/signedInRequest.mjs

@@ -0,0 +1,125 @@
+// @ts-check
+
+/** 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() {
+    super("the saved sign-in could not be renewed: HeyGen was unreachable");
+    this.name = "AccountUnreachable";
+  }
+}
+
+/** What a sign-in read yields, through readOrUnreachable, when its renewal could not reach HeyGen. */
+export const UNREACHABLE = /** @type {"unreachable"} */ ("unreachable");
+
+/** `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 async function readOrUnreachable(access, refused) {
+  try {
+    return await access(refused);
+  } catch (error) {
+    if (error instanceof AccountUnreachable) return UNREACHABLE;
+    throw error;
+  }
+}
+
+/** `run`, answering `value` when the saved sign-in's renewal could not reach HeyGen; other errors rethrow. A probe's
+ * `access` is `orIfUnreachable(access, null)`. @template {any[]} A, R @param {(...args: A) => Promise<R>} run
+ * @param {R} value */
+export const orIfUnreachable =
+  (run, value) =>
+  async (/** @type {A} */ ...args) => {
+    try {
+      return await run(...args);
+    } catch (error) {
+      if (error instanceof AccountUnreachable) return value;
+      throw error;
+    }
+  };
+
+/** 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 = fetch,
+  timeoutMs,
+  tag,
+  offline,
+  signedOut,
+  host = "heygen",
+  headers: always = {},
+  trace = (init) => init,
+}) {
+  /** @param {{ token: string, heygen: string, heygenApi: string }} signedIn
+   * @param {string} method @param {string} route @param {unknown} body @param {Record<string, string>} headers
+   * @param {number[] | null} answers @param {string} label */
+  const send = (signedIn, method, route, body, headers, answers, label) => {
+    /** @type {RequestInit} */
+    const init = {
+      method,
+      headers: {
+        // Never a caller's Authorization, in any case: fetch would join it to the bearer.
+        ...Object.fromEntries(
+          Object.entries({ ...always, ...headers }).filter(
+            ([name]) => name.toLowerCase() !== "authorization",
+          ),
+        ),
+        authorization: `Bearer ${signedIn.token}`,
+        ...(body === undefined ? {} : { "content-type": "application/json" }),
+      },
+      // A redirect would drop the bearer.
+      redirect: "error",
+      body: body === undefined ? null : JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+    return fetchImpl(`${signedIn[host]}${route}`, answers ? trace(init, answers) : init).catch(
+      (error) => {
+        console.error(`[${tag}] ${label} failed:`, /** @type {Error} */ (error).name);
+        throw offline();
+      },
+    );
+  };
+
+  /** `answers`: a background check's own "no" (offline is then one too), not reported as an API failure. `label`
+   * names the call in the log in place of its route, for a route that carries a secret (a share token).
+   * @param {string} method @param {string} route @param {unknown} [body] @param {Record<string, string>} [headers]
+   * @param {number[] | null} [answers] @param {string} [label]
+   * @returns {Promise<{ reply: Response, heygen: string, owner: string | null }>} */
+  return async (
+    method,
+    route,
+    body,
+    headers = {},
+    answers = null,
+    label = `${method} ${route}`,
+  ) => {
+    let refused = "";
+    for (;;) {
+      // The refused token is passed on: the account renews only past a token it is told the server refused.
+      const signedIn = await access(refused || undefined).catch((error) => {
+        throw error instanceof AccountUnreachable ? offline() : error;
+      });
+      if (!signedIn || signedIn.token === refused) throw signedOut();
+      const sending = typeof body === "function" ? await body() : body;
+      const reply = await send(signedIn, method, route, sending, headers, answers, label);
+      if (reply.status !== 401 || refused)
+        return { reply, heygen: signedIn.heygen, owner: signedIn.owner ?? null };
+      refused = signedIn.token;
+      await reply.body?.cancel().catch(() => {});
+    }
+  };
+}

package/src/storage.mjs

@@ -0,0 +1,116 @@
+// @ts-check
+import {
+  lstat,
+  mkdir,
+  readFile,
+  writeFile,
+  rename as renameFile,
+  rm as remove,
+} from "node:fs/promises";
+import { basename, join, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** @param {unknown} error */
+export const errorCode = (error) =>
+  error instanceof Error && "code" in error ? error.code : undefined;
+
+/** @template T @param {() => Promise<T>} run */
+async function retryBusy(run) {
+  const waits = [10, 25, 50, 100, 200];
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await run();
+    } catch (error) {
+      const delay = waits[attempt];
+      if (
+        process.platform !== "win32" ||
+        !["EPERM", "EBUSY", "EACCES", "ENOTEMPTY"].includes(String(errorCode(error))) ||
+        delay === undefined
+      )
+        throw error;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+/** @param {string} from @param {string} to */
+export const rename = (from, to) => retryBusy(() => renameFile(from, to));
+/** @param {string} path @param {import("node:fs").RmOptions} [options] */
+export const rm = (path, options) => retryBusy(() => remove(path, options));
+
+/** Create metadata folders only inside an existing project. @param {string} root @param {string} rel */
+export async function mkdirInside(root, rel) {
+  let dir = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    if (part === ".." || part === ".") throw new Error("Invalid metadata directory.");
+    dir = join(dir, part);
+    await mkdir(dir).catch((error) => {
+      if (errorCode(error) !== "EEXIST") throw error;
+    });
+    if (!(await lstat(dir)).isDirectory())
+      throw new Error("The destination must be a real folder, not a link.");
+  }
+  return dir;
+}
+/** @type {Map<string, Promise<void>>} */
+const queued = new Map();
+/** @param {string} path @param {unknown} data */
+export function writeJsonAtomic(path, data) {
+  const text = JSON.stringify(data, null, 2);
+  const save = (queued.get(path) ?? Promise.resolve()).then(async () => {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+      await writeFile(temp, text, { mode: 0o600 });
+      await rename(temp, path);
+    } finally {
+      await rm(temp, { force: true });
+    }
+  });
+  const settled = save.catch(() => {});
+  queued.set(path, settled);
+  void settled.then(() => queued.get(path) === settled && queued.delete(path));
+  return save;
+}
+export class SharingStateError extends Error {
+  /** @param {string} path @param {unknown} [cause] */
+  constructor(path, cause) {
+    super(
+      `Sharing state in .hyperframes/${basename(path)} could not be read. Restore this file from a backup, or contact support to reconnect the existing share. Keep the file; deleting it can lose recovery state or create a duplicate share.`,
+      { cause },
+    );
+    this.name = "SharingStateError";
+  }
+}
+
+/** @template T @param {string} path @param {T} fallback @returns {Promise<Record<string, unknown> | Exclude<T, object>>} */
+export async function readJsonOr(path, fallback) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (errorCode(error) !== "ENOENT") throw new SharingStateError(path, error);
+    return /** @type {Record<string, unknown> | Exclude<T, object>} */ (fallback);
+  }
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+export const isJsonObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** @param {unknown} value @returns {value is string} */
+export const isSavedId = (value) => typeof value === "string" && value.trim() !== "";
+
+/** @param {unknown} value @returns {value is string | null} */
+export const isNullableSavedId = (value) => value === null || isSavedId(value);
+
+/** @param {unknown} value @returns {value is string | null | undefined} */
+export const isOptionalSavedId = (value) => value === undefined || isNullableSavedId(value);
+
+/** @param {unknown} value @returns {value is boolean | undefined} */
+export const isOptionalBoolean = (value) => value === undefined || typeof value === "boolean";
+
+/** An absent file is the only source of an empty record. @param {string} path */
+export async function readJsonRecord(path) {
+  const value = await readJsonOr(path, undefined);
+  if (value === undefined) return null;
+  if (!isJsonObject(value)) throw new SharingStateError(path);
+  return value;
+}

package/src/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/src/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;
+}

package/src/types/reviewWire.d.ts

@@ -0,0 +1,200 @@
+// Review API request and response shapes. Nullable fields use `| null`.
+
+import type { AccessMode, LinkRole } from "./share.js";
+
+export interface ErrorEnvelope {
+  code: number;
+  message: string;
+  data: {
+    reason: string;
+    current_revision?: number;
+    /** On a 403 `workspace_membership_required`: the team workspace the link is for, absent when it has no name of
+     * its own to show (a personal space never has one). */
+    space?: { name: string; kind: "team" };
+    workspace_id?: string;
+    project_limit?: number;
+    projects_used_up_to_limit?: number;
+    requested_feature?: string;
+  };
+}
+
+export interface RegisterProjectRequest {
+  studio_project_id: string;
+  title: string;
+  client_operation_id: string;
+}
+
+interface Capabilities {
+  can_view: true;
+  can_comment: boolean;
+  can_export: boolean;
+  can_resolve: boolean;
+  can_manage_sharing: boolean;
+}
+
+export interface ProjectDTO {
+  review_entitlements?: ReviewEntitlements | null;
+  project_id: string;
+  title: string;
+  access_mode: AccessMode;
+  latest_ready_version_id: string | null;
+  review_url: string | null;
+  authenticated_review_url: string;
+  capabilities: Capabilities;
+}
+
+// GET /v1/hyperframes/review-spaces: personal first, then team spaces by last use. The data
+// is `{ items: SpaceDTO[], version_sharing?: boolean, share_files?: boolean }`: the server's per-account flags for
+// shared reviews and for files on their versions, and anything but `true` (absent from an older server too) is off.
+export interface SpaceDTO {
+  review_entitlements?: ReviewEntitlements | null;
+  space_id: string;
+  name: string;
+  kind: "personal" | "team";
+  can_create_review: boolean;
+  last_used_at: string | null;
+  /** The workspace this token is bound to; absent from servers before it. */
+  bound?: boolean;
+  /** Someone other than the calling user is a member; absent when the server could not count, or
+   * predates it. */
+  has_other_members?: boolean;
+}
+
+// The workspace a project was registered in.
+interface SpaceRef {
+  space_id: string;
+  name: string;
+  kind: SpaceDTO["kind"];
+  /** Someone other than the project's owner is a member; absent as on SpaceDTO. */
+  has_other_members?: boolean;
+}
+
+export interface ShareDTO {
+  review_entitlements?: ReviewEntitlements | null;
+  sharing_state?: ReviewSharingState;
+  project_id: string;
+  access_mode: AccessMode;
+  default_role: LinkRole;
+  comments_enabled: boolean;
+  revision: number;
+  link_generation: number;
+  /** Null when the link is off or the frontend base is unset. */
+  review_url: string | null;
+  authenticated_review_url: string;
+  revoked: boolean;
+  space?: SpaceRef | null;
+  /** While a moderation hold is active, link viewers and guests receive 404. */
+  moderation_hold?: boolean;
+  /** Which hold: a staff takedown admits only the owner and refuses any reshare with 409 moderation_hold. */
+  moderation_hold_kind?: "takedown" | "auto_reports" | null;
+}
+
+export interface UpdateProjectShareRequest {
+  access_mode: AccessMode;
+  default_role: LinkRole;
+  comments_enabled: boolean;
+  expected_revision: number;
+}
+
+export interface ProjectOperationRequest {
+  expected_link_generation: number;
+  client_operation_id: string;
+}
+
+// GET …/feedback: only the final page carries change_cursor.
+export interface FeedbackPage {
+  items: unknown[];
+  next_cursor: string | null;
+  change_cursor: string | null;
+}
+
+// POST /v1/hyperframes/review-projects/{id}/exports with a local MP4 (contract "Export a new video version").
+export interface ExportRequest {
+  client_operation_id: string;
+  title_snapshot: string;
+  coordinate_width: number;
+  coordinate_height: number;
+  duration_seconds: number;
+  render_settings: Record<string, never>;
+  source_revision_id: null;
+  source_fingerprint: string | null;
+  local_upload: { size_bytes: number; checksum_sha256: string; content_type: "video/mp4" };
+  /** The synced snapshot the video was rendered from, sent only while the server's `share_files` is on. The server
+   * refuses one it cannot match with 422 `snapshot_mismatch`. */
+  snapshot?: SnapshotRef;
+  /** Whether this version addresses review feedback, when the host can tell. */
+  from_review?: "yes" | "no";
+}
+
+/** A composition-sync snapshot a review version carries, named in the snapshot's own workspace, which may differ from
+ * the review project's. Also the body of PUT …/versions/{version_id}/snapshot, which attaches one later. */
+export interface SnapshotRef {
+  space_id: string;
+  composition_id: string;
+  snapshot_id: string;
+}
+
+// A version is playable only after screening completes.
+export interface ExportDTO {
+  video_id: string;
+  version_id: string;
+  status: "upload_pending" | "processing" | "screening" | "ready" | "failed";
+  exported_at: string;
+  upload: { put_url: string; headers: Record<string, string> } | null;
+  error: { reason: string; message: string } | null;
+  /** Owner reads only (absent from an older backend); status stays "screening" for both, null when not screening.
+   * "checking" is any screening not held for a person at HeyGen. */
+  screening_state?: "checking" | "held" | null;
+}
+
+export interface ReviewEntitlements {
+  policy_version: 1;
+  workspace_id: string;
+  plan: "free" | "subscribed";
+  project_limit: 5 | null;
+  projects_used_up_to_limit: number | null;
+  can_register_project: boolean;
+  allowed_collaborative_access_modes: Array<"public" | "team" | "invite">;
+  can_manage_email_grants: boolean;
+  /** Whether the owner's plan can give Can edit; sent only while `share_files` is on, false on Free. */
+  can_offer_edit?: boolean;
+}
+interface ReviewSharingState {
+  state: "available" | "closed" | "subscription_required";
+  can_close_access: boolean;
+  can_create_email_grants?: boolean;
+  can_update_email_grants?: boolean;
+  can_rotate_link?: boolean;
+  can_create_link?: boolean;
+  can_revoke_link?: boolean;
+  allowed_collaborative_access_modes?: Array<"public" | "team" | "invite">;
+  allowed_default_roles?: LinkRole[];
+  can_enable_comments?: boolean;
+}
+export interface AccessGrantDTO {
+  effective?: boolean;
+  can_revoke?: boolean;
+  allowed_roles?: Array<"viewer" | "commenter" | "editor">;
+  id: string;
+  email: string;
+  role: "viewer" | "commenter" | "editor";
+  revision: number;
+  revoked_at: string | null;
+}
+export interface CreateGrantRequest {
+  client_operation_id: string;
+  email: string;
+  role: AccessGrantDTO["role"];
+  expected_revision: number | null;
+}
+export interface ManagedReviewPage {
+  items: Array<{
+    project_id: string;
+    title: string;
+    created_at: string;
+    owner_user_id: string;
+    can_remove: boolean;
+  }>;
+  next_cursor: string | null;
+  review_entitlements: ReviewEntitlements | null;
+}

package/src/types/share.d.ts

@@ -0,0 +1,119 @@
+/** Who a review link lets in, and as what, as the shared-reviews server names them. */
+export type AccessMode = "public" | "invite" | "team" | "private";
+export type LinkRole = "viewer" | "commenter" | "editor";
+
+/** Whether the version on the page, or the one a press would add, carries the project's synced files. `included`: it
+ * does. `not_synced`: the render is the project as it is now, but that is not what was last synced. `changed`: the
+ * project moved past the render. `other_workspace`: the project syncs to `workspace`, not the one Desktop is signed
+ * into, whose sign-in can't read its snapshots. `off`: share_files or sync is off, or there is no render to speak of. */
+export type ReviewFiles =
+  | { at: "off" }
+  | { at: "included" }
+  | { at: "not_synced" }
+  | { at: "changed" }
+  | { at: "other_workspace"; workspace: string };
+export type ReviewFilesState = ReviewFiles["at"];
+
+/** An upload under way: bytes sent of the archive's total (0 while the archive is made). */
+export interface ShareProgress {
+  sent: number;
+  total: number;
+}
+
+/** A project's shared link, as the Share popover reads it. */
+export interface ShareStatus {
+  /** Null until the first share; changedFiles counts the project's files changed since that link was made. */
+  link: { url: string; sharedAt: number; changedFiles: number } | null;
+  /** The project's files in bytes, and the most a shared project may be. */
+  bytes: number;
+  limit: number;
+  publishing: ShareProgress | null;
+}
+
+/** A project's review link, as the server holds it. */
+export interface ReviewShare {
+  projectId?: string;
+  entitlements?: import("./reviewWire.js").ReviewEntitlements | null | undefined;
+  sharingState?: import("./reviewWire.js").ShareDTO["sharing_state"];
+  removed?: boolean;
+  /** Null while the link is off. */
+  url: string | null;
+  access: AccessMode;
+  role: LinkRole;
+  commentsOn: boolean;
+  /** The space the link belongs to; null from a server that does not say. */
+  space: ReviewSpaceRef | null;
+  /** The link's space is not the one Desktop is signed into. Everything still works there; this only names it. */
+  elsewhere: boolean;
+  /** A report paused access through the link: only the owner, invited people and workspace members get in. */
+  held: boolean;
+  /** Staff took the review down: only the owner can open it, at `page`, and it can't be shared again. */
+  takedown?: { page: string };
+  /** Where the page's versions stand; every answer over IPC carries it. */
+  version?: ReviewVersion;
+  /** After a change of space: the old link not yet turned off, and whether retries keep failing. */
+  oldLink?: { space: string; stuck: boolean } | null;
+}
+
+/** An upload to the review page in flight. `checking` is the server's screening, which can take a while. */
+export interface ReviewExportProgress {
+  step: "preparing" | "uploading" | "processing" | "checking";
+  sent: number;
+  total: number;
+  /** Checking for over 2 minutes: staff review can take a while. */
+  slow?: boolean;
+  /** How screening stands, from a server that says: held for a person at HeyGen (no bar, polled slowly, up to a day)
+   * or checking. Absent from an older server, which leaves `slow` to say a long check. */
+  screening?: "checking" | "held";
+  /** Checking for over 15 minutes since the upload completed, by this computer's clock. */
+  late?: boolean;
+}
+
+export interface ReviewVersion {
+  /** The newest version this app put on the page; `current` when it is the project as it is now. */
+  last: { exportedAt: string; current: boolean } | null;
+  /** The newest export: ready to go up, none, not MP4, or older than the project now. */
+  source: "ready" | "none" | "not-mp4" | "stale";
+  exporting: ReviewExportProgress | null;
+  /** The last run's sentence when it did not go up. */
+  failure: string | null;
+  /** False when the same video would be refused again (blocked, rejected, not available): no Try again. */
+  retryable?: boolean;
+  /** With `retryable` false: a smaller or shorter export can go up, so offer Export MP4. */
+  exportHelps?: boolean;
+  /** The watch ran out while the video was held for review: not a refusal, so it is never shown as one. */
+  held?: boolean;
+}
+
+export interface ReviewSpaceRef {
+  id: string;
+  name: string;
+  kind: "personal" | "team";
+  /** Someone besides the link's owner (on a space list: besides the caller) is in the space; absent when the server
+   * does not say, which Share reads as yes. */
+  hasOtherMembers?: boolean;
+}
+
+/** A space the account is in. v1 shares into the signed-in one; the later workspace switch lists the rest. */
+export interface ReviewSpace extends ReviewSpaceRef {
+  /** Existing native registration verified by reading its owner share; a retry needs no new slot. */
+  existingProjectId?: string;
+  /** A durable registration request can be replayed; the server still decides admission. */
+  resumingRegistration?: boolean;
+  sharingState?: ReviewShare["sharingState"];
+  entitlements?: import("./reviewWire.js").ReviewEntitlements | null | undefined;
+  lastUsedAt: string | null;
+  canCreate: boolean;
+  /** The workspace Desktop is signed into, where a new link goes. */
+  signedIn: boolean;
+}
+
+export type ReviewAccessChange = { access: ReviewShare["access"] } | { role: ReviewShare["role"] };
+
+/** A share link as Settings' Cloud list shows it (packages/agent-runtime/src/share/reviewLinkStates.mjs). */
+export interface ReviewLinkState {
+  state: "on" | "off" | "paused" | "taken-down";
+  access: import("./share.js").AccessMode;
+  /** Why a paused link is paused: a report HyperFrames looks into, or a plan that no longer includes it. */
+  pausedFor?: "report" | "plan";
+}