@hyperframes/share 0.0.0-stage → 0.9.21

package/src/hosts.d.ts

@@ -0,0 +1,39 @@
+import type { SignedInDeps, signedInRequest } from "./signedInRequest.mjs";
+
+/** What sharing a project and its review link take from the host's main process (host.mjs bindShareHost). The
+ * network and the person's session stay the host's: every review call goes through its signed-in request and every
+ * archive through its uploader. */
+export interface ShareHost {
+  execFile: typeof import("node:child_process").execFile;
+  /** The key every open-project lookup uses: the real path. */
+  normalize(path: string): string;
+  /** The open project's normalized path; refuses a project that is not open. */
+  assertOpenProject(path: string): string;
+  /** The open project at `path`, or null when it is not open. */
+  resolveOpenProjectByPath(path: string): { id: string; dir: string } | null;
+  /** All open projects, for invalidating removed review identities. */
+  listOpenProjects(): Array<{ dir: string }>;
+  /** The name the host shows for a project. */
+  homeName(path: string, folder?: string): string;
+  /** PUTs an archive through the host's network, hearing each chunk sent; answers the HTTP status. */
+  uploadWithProgress(
+    url: URL,
+    headers: Record<string, string>,
+    archive: Uint8Array,
+    onSent: (sent: number) => void,
+  ): Promise<number>;
+  /** Requests to HeyGen's sign-in host as the signed-in person, traced as the host traces its API calls. */
+  signedInRequest(deps: Omit<SignedInDeps, "trace">): ReturnType<typeof signedInRequest>;
+  /** The newest finished export recorded in the project's renders folder whose file is still there. */
+  latestExportFile(dir: string): { path: string; fingerprint?: string; id: string } | null;
+  /** Trusted video upload origins configured by the host independently of the review API response. */
+  reviewUploadOrigins?: readonly string[];
+  /** The project as change detection sees it, as one hash. */
+  projectFingerprint(dir: string): Promise<string>;
+  /** The path of the host's FFmpeg tool `name`. */
+  ffBinary(name: "ffprobe"): string;
+  /** The sign-in site of the host's own channel, whose review record keeps the original name. */
+  channelSite: string;
+  /** Every sign-in site the host can sign in on. */
+  signinSites: string[];
+}

package/src/index.mjs

@@ -0,0 +1,82 @@
+export {
+  setReviewSite,
+  takenDown,
+  listSpaces,
+  reviewSpaces,
+  shown,
+  ownerOf,
+  projectLine,
+  oneAtATime,
+  changeShare,
+  reviewProjectId,
+  localReviewProjects,
+  reviewRecord,
+  reviewRecordPath,
+  reviewSwitchPath,
+  onRebound,
+  rebindRecord,
+  setAsideReview,
+  shareAnew,
+  readShare,
+  reviewStatus,
+  shareForReview,
+  setReviewAccess,
+  turnOffReviewLink,
+  reviewSentence,
+  markReviewRemoved,
+  removeLocalReview,
+  removeReviewProject,
+  reviewDestination,
+} from "./reviewShare.mjs";
+export {
+  factsOf,
+  reviewVersion,
+  addVersion,
+  recheckHeld,
+  refreshReviewExport,
+  addFirstVersion,
+  versionFacts,
+  versionOnPage,
+  markFiles,
+} from "./reviewExport.mjs";
+export { ReviewFailed, SHARING_REFUSALS, reviewClient } from "./reviewClient.mjs";
+export { filesStateOf, reviewFiles } from "./reviewFiles.mjs";
+export {
+  switchOperationId,
+  retryOldLink,
+  oldLinkOf,
+  changeSpace,
+  resumeSpaceChange,
+  switchSentence,
+} from "./reviewSwitch.mjs";
+export { fileSha256Base64, putFile } from "./reviewUpload.mjs";
+export { firstReviewAudience } from "./reviewAudience.mjs";
+export { versionSentence } from "./reviewVersionSentences.mjs";
+export { linkStateOf, reviewLinkStates } from "./reviewLinkStates.mjs";
+export { shareOpenCalls } from "./reviewOpenCalls.mjs";
+export {
+  AccountUnreachable,
+  UNREACHABLE,
+  readOrUnreachable,
+  orIfUnreachable,
+  signedInRequest,
+} from "./signedInRequest.mjs";
+export {
+  HF_ID_ATTRIBUTE,
+  contentKey,
+  snapshotProject,
+  snapshotFingerprint,
+  snapshotFiles,
+  diffChangedFiles,
+  projectFingerprint,
+} from "./projectSnapshot.mjs";
+export { ShareBusyError, withProjectShareLock } from "./projectLock.mjs";
+export { bindShareHost } from "./host.mjs";
+/** @typedef {import("./hosts.js").ShareHost} ShareHost */
+/** @typedef {import("./reviewClient.mjs").ReviewClient} ReviewClient */
+/** @typedef {import("./types/share.js").ReviewShare} ReviewShare */
+/** @typedef {import("./reviewExport.mjs").VersionRequest} VersionRequest */
+/** @typedef {import("./types/reviewWire.js")} Wire */
+/** @typedef {import("./types/share.js").AccessMode} AccessMode */
+/** @typedef {import("./types/share.js").ReviewExportProgress} ReviewExportProgress */
+export { pendingReviewExport } from "./reviewExport.mjs";

package/src/projectLock.mjs

@@ -0,0 +1,120 @@
+// @ts-check
+import fs, { open, readFile, realpath, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+import { errorCode, mkdirInside } from "./storage.mjs";
+
+export class ShareBusyError extends Error {
+  /** @param {string} path */
+  constructor(path) {
+    super("Another process is sharing this project. Wait for it to finish, then retry.");
+    this.name = "ShareBusyError";
+    this.reason = "review_operation_busy";
+    this.lockPath = path;
+  }
+}
+/** @typedef {{ token: string, pid: number, hostname: string }} Owner */
+/** @param {string} path @returns {Promise<Owner | null>} */
+async function ownerAt(path) {
+  try {
+    const value = JSON.parse(await readFile(path, "utf8"));
+    return typeof value.token === "string" &&
+      /^[a-f0-9-]{36}$/.test(value.token) &&
+      Number.isInteger(value.pid) &&
+      value.pid > 0 &&
+      typeof value.hostname === "string"
+      ? value
+      : null;
+  } catch (error) {
+    if (errorCode(error) === "ENOENT" || error instanceof SyntaxError) return null;
+    throw error;
+  }
+}
+/** @param {Owner} owner */
+function isDead(owner) {
+  if (owner.hostname !== hostname()) return false;
+  try {
+    process.kill(owner.pid, 0);
+    return false;
+  } catch (error) {
+    return errorCode(error) === "ESRCH";
+  }
+}
+/** A claim scoped to the old owner prevents two stale readers deleting a replacement lock. @param {string} path */
+async function reap(path) {
+  const old = await ownerAt(path);
+  if (!old || !isDead(old)) return;
+  const claim = `${path}.reap-${old.token}`;
+  const guard = await open(claim, "wx", 0o600).catch((error) => {
+    if (errorCode(error) === "EEXIST") return null;
+    throw error;
+  });
+  if (!guard) return;
+  try {
+    if ((await ownerAt(path))?.token === old.token) await unlink(path);
+  } finally {
+    await guard.close();
+    await unlink(claim);
+  }
+}
+/** @param {string} candidate @param {string} lock @param {Owner} owner */
+async function claim(candidate, lock, owner) {
+  try {
+    await fs.link(candidate, lock);
+  } catch (error) {
+    if (
+      !["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV", "EINVAL", "EISDIR"].includes(
+        String(errorCode(error)),
+      )
+    )
+      throw error;
+    const handle = await open(lock, "wx", 0o600);
+    let written = false;
+    try {
+      await handle.writeFile(JSON.stringify(owner));
+      written = true;
+    } finally {
+      await handle.close();
+      if (!written) await unlink(lock);
+    }
+  }
+}
+/** @template T @param {string} projectPath @param {"review" | "export"} lane @param {() => Promise<T>} run
+ * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options] @returns {Promise<T>} */
+export async function withProjectShareLock(
+  projectPath,
+  lane,
+  run,
+  { timeoutMs = 30_000, signal } = {},
+) {
+  const root = await realpath(projectPath);
+  const folder = await mkdirInside(root, ".hyperframes");
+  const lock = join(folder, lane === "review" ? "review.lock" : "review-export.lock");
+  const owner = { token: randomUUID(), pid: process.pid, hostname: hostname() };
+  const candidate = `${lock}.${owner.token}.tmp`;
+  await writeFile(candidate, JSON.stringify(owner), { flag: "wx", mode: 0o600 });
+  const deadline = Date.now() + timeoutMs;
+  let held = false;
+  try {
+    while (!held) {
+      signal?.throwIfAborted();
+      held = await claim(candidate, lock, owner).then(
+        () => true,
+        (error) => {
+          if (errorCode(error) === "EEXIST") return false;
+          throw error;
+        },
+      );
+      if (held) break;
+      await reap(lock);
+      if (Date.now() >= deadline) throw new ShareBusyError(lock);
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+    signal?.throwIfAborted();
+    return await run();
+  } finally {
+    if (held && (await ownerAt(lock))?.token === owner.token) await unlink(lock);
+    await unlink(candidate);
+  }
+}

package/src/projectSnapshot.mjs

@@ -0,0 +1,120 @@
+// @ts-check
+// A project's files as change detection sees them: every file the film can use (isOutsideFilm), keyed by mtime and
+// size, except html, keyed by content without the data-hf-id stamps. A run's change set and the watcher both read it.
+import fs from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { isOutsideFilm } from "./appOwnedPaths.mjs";
+
+export const HF_ID_ATTRIBUTE = /\sdata-hf-id\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/g;
+
+const sha256 = (/** @type {import("node:crypto").BinaryLike} */ data) =>
+  createHash("sha256").update(data).digest("hex");
+
+// A write that only adds data-hf-id stamps must not count as a change, or reload -> stamp -> reload never ends (KTD4).
+/** @param {string} html */
+export function contentKey(html) {
+  return sha256(html.replace(HF_ID_ATTRIBUTE, ""));
+}
+
+/** A file renamed away between readdir and stat (atomic writes), or one the app may not read, is simply not there
+ * (undefined): one unreadable entry must not blind the whole scan. @param {string} full @param {boolean} byContent */
+async function snapshotKey(full, byContent) {
+  const resolved = await fs.realpath(full).catch(() => null);
+  if (!resolved) return undefined;
+  const handle = await fs
+    .open(resolved, constants.O_RDONLY | constants.O_NOFOLLOW)
+    .catch(() => null);
+  if (!handle) return undefined;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) return undefined;
+    if (full.endsWith(".html")) return contentKey(await handle.readFile("utf8"));
+    if (byContent) return sha256(await handle.readFile());
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return undefined;
+  } finally {
+    await handle.close();
+  }
+}
+
+/** @param {import("node:fs").Dirent} entry @param {string} full @param {boolean} followSymlinks */
+async function entryKind(entry, full, followSymlinks) {
+  if (!entry.isSymbolicLink()) return entry;
+  return followSymlinks ? fs.stat(full).catch(() => null) : null;
+}
+
+// What a run is judged against: each file's mtime and size, except html, whose key ignores the data-hf-id stamps an
+// open or a save writes. Files the film cannot use are not part of the snapshot.
+/** @typedef {Map<string, unknown>} Snapshot */
+/** @param {string} dir @param {{ byContent?: boolean, followSymlinks?: boolean }} [options] @returns {Promise<Snapshot>} */
+export async function snapshotProject(dir, { byContent = false, followSymlinks = false } = {}) {
+  /** @type {Snapshot} */
+  const result = new Map();
+  /** @param {string} current @param {Set<string>} ancestors */
+  async function walk(current, ancestors) {
+    const real = await fs.realpath(current).catch(() => null);
+    if (!real || ancestors.has(real)) return;
+    const parents = new Set([...ancestors, real]);
+    /** @type {import("node:fs").Dirent[]} */
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      if (isOutsideFilm(path.relative(dir, full))) continue;
+      const kind = await entryKind(entry, full, followSymlinks);
+      if (kind?.isDirectory()) await walk(full, parents);
+      else if (kind?.isFile()) {
+        const key = await snapshotKey(full, byContent);
+        if (key !== undefined) result.set(path.relative(dir, full), key);
+      }
+    }
+  }
+  await walk(dir, new Set());
+  return result;
+}
+
+/** What an export's sidecar records of the project, from a snapshot already taken.
+ * @param {Snapshot} snapshot */
+export function snapshotFingerprint(snapshot) {
+  const files = [...snapshot].sort(([a], [b]) => (a < b ? -1 : 1));
+  return createHash("sha256").update(JSON.stringify(files)).digest("hex");
+}
+
+/** Just these project files, keyed as snapshotProject keys them (undefined: not a file the snapshot holds); null when
+ * one is a folder, which only a whole snapshot covers. @param {string} dir @param {Iterable<string>} files
+ * @returns {Promise<Map<string, unknown> | null>} */
+export async function snapshotFiles(dir, files) {
+  /** @type {Map<string, unknown>} */
+  const result = new Map();
+  for (const file of files) {
+    const full = path.join(dir, file);
+    const stat = await fs.lstat(full).catch(() => null);
+    if (stat?.isDirectory()) return null;
+    const holds = stat?.isFile() && !isOutsideFilm(path.relative(dir, full));
+    result.set(file, holds ? await snapshotKey(full, false) : undefined);
+  }
+  return result;
+}
+
+/** @param {Snapshot} before @param {Snapshot} after */
+export function diffChangedFiles(before, after) {
+  /** @type {string[]} */
+  const changed = [];
+  for (const [file, key] of after) {
+    if (before.get(file) !== key) changed.push(file);
+  }
+  // A file gone after the run was changed by it too, as the project watcher counts it.
+  for (const file of before.keys()) if (!after.has(file)) changed.push(file);
+  return changed;
+}
+
+/** @param {string} projectPath */
+export const projectFingerprint = async (projectPath) =>
+  snapshotFingerprint(await snapshotProject(projectPath, { followSymlinks: true }));

package/src/reviewAudience.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+import { ReviewFailed } from "./reviewClient.mjs";
+
+/** @param {import("./types/reviewWire.js").ReviewEntitlements | null | undefined} entitlements
+ * @param {import("./types/share.js").AccessMode | undefined} chosen */
+export function firstReviewAudience(entitlements, chosen) {
+  // An omitted field is the legacy server contract; explicit null is an unavailable read.
+  if (entitlements === undefined) return chosen ?? "team";
+  if (!entitlements) throw new ReviewFailed(503, "review_entitlement_unavailable");
+  const audience =
+    chosen ?? (entitlements.allowed_collaborative_access_modes.includes("team") ? "team" : null);
+  if (!audience)
+    throw new ReviewFailed(402, "review_public_consent_required", undefined, undefined, {
+      reason: "review_public_consent_required",
+      workspace_id: entitlements.workspace_id,
+    });
+  if (audience !== "private" && !entitlements.allowed_collaborative_access_modes.includes(audience))
+    throw new ReviewFailed(402, "review_subscription_required", undefined, undefined, {
+      reason: "review_subscription_required",
+      workspace_id: entitlements.workspace_id,
+      requested_feature: audience,
+    });
+  return audience;
+}

package/src/reviewClient.mjs

@@ -0,0 +1,260 @@
+// @ts-check
+// Review requests run on the host so the browser never receives the account bearer.
+
+import { randomUUID } from "node:crypto";
+import { rejectedGrantRequest } from "./grantRefusal.mjs";
+import { signedInRequest } from "./host.mjs";
+import { shareOpenCalls } from "./reviewOpenCalls.mjs";
+
+/** @typedef {import("./types/reviewWire.js").ShareDTO} ShareDTO @typedef {import("./types/reviewWire.js").ProjectDTO} ProjectDTO
+ * @typedef {import("./types/reviewWire.js").ExportDTO} ExportDTO */
+
+const TIMEOUT_MS = 30_000;
+const PROJECTS = "/v1/hyperframes/review-projects";
+const SPACES = "/v1/hyperframes/review-spaces";
+
+/** A refused or failed call: the HTTP status (0 when the server was never reached) and the server's reason. */
+export class ReviewFailed extends Error {
+  /** @param {number} status @param {string} reason @param {number} [currentRevision] @param {number} [retryAfterMs]
+   * @param {import("./types/reviewWire.js").ErrorEnvelope["data"]} [details] */
+  constructor(status, reason, currentRevision, retryAfterMs, details) {
+    super(`review ${status} ${reason}`);
+    this.status = status;
+    this.reason = reason;
+    this.currentRevision = currentRevision;
+    this.retryAfterMs = retryAfterMs;
+    this.details = details;
+  }
+}
+
+/** The answer's data; null for a 204. A refusal throws with the server's status and reason.
+ * @param {Response} reply @param {string} what @returns {Promise<any>} */
+async function dataOf(reply, what) {
+  if (reply.status === 204) return null;
+  const payload = await reply.json().catch(() => null);
+  if (reply.ok) return payload?.data ?? null;
+  /** @type {import("./types/reviewWire.js").ErrorEnvelope["data"] | undefined} */
+  const data = payload?.data;
+  throw responseFailure(reply, what, data);
+}
+
+/** @param {Response} reply @param {string} what @param {import("./types/reviewWire.js").ErrorEnvelope["data"] | undefined} data */
+function responseFailure(reply, what, data) {
+  console.error(`[review] ${what} refused:`, reply.status, data?.reason);
+  const retryAfter = Number(reply.headers.get("retry-after") ?? NaN);
+  return new ReviewFailed(
+    reply.status,
+    data?.reason ?? "",
+    data?.current_revision,
+    retryAfter >= 0 ? retryAfter * 1000 : undefined,
+    data,
+  );
+}
+
+/** The server's own "no" to the sharing read: signed out, not allowed, or no such route. */
+export const SHARING_REFUSALS = [401, 403, 404];
+
+/** @param {{ access: import("./types/access.js").ApiAccess, fetchImpl?: typeof fetch,
+ *   signedInEmail?: () => Promise<string | null> }} deps */
+export function reviewClient({ access, fetchImpl = fetch, signedInEmail = async () => null }) {
+  const request = signedInRequest({
+    access,
+    fetchImpl,
+    timeoutMs: TIMEOUT_MS,
+    tag: "review",
+    offline: () => new ReviewFailed(0, "offline"),
+    signedOut: () => new ReviewFailed(401, "login_required"),
+  });
+  /** @param {string} method @param {string} route @param {unknown} [body] @param {Record<string, string>} [headers]
+   * @param {number[] | null} [answers] @returns {Promise<any>} */
+  const call = async (method, route, body, headers = {}, answers = null) =>
+    dataOf((await request(method, route, body, headers, answers)).reply, `${method} ${route}`);
+  /** A call on a share token's route, logged as `what`: the token opens the share to anyone holding it.
+   * @param {string} what @param {string} method @param {string} route @param {unknown} [body]
+   * @returns {Promise<any>} */
+  const tokenCall = async (what, method, route, body) =>
+    dataOf((await request(method, route, body, {}, null, what)).reply, what);
+
+  const project = (/** @type {string} */ id) => `${PROJECTS}/${encodeURIComponent(id)}`;
+  return {
+    /** The signed-in account's email, null when unknown; the record keeps it as the project's owner. */
+    signedInEmail,
+    /** The spaces this account can share into, personal first.
+     * @returns {Promise<import("./types/reviewWire.js").SpaceDTO[]>} */
+    spaces: async () => {
+      const items = (await call("GET", SPACES))?.items;
+      // An answer without a list is not "no spaces": sharing then would pick a workspace nobody chose.
+      if (!Array.isArray(items)) throw new ReviewFailed(502, "malformed_spaces");
+      return items;
+    },
+    /** The server's per-account flags on review-spaces, each on only for `true`: `hyperframes-review-version-sharing`
+     * and `hyperframes-review-share-files`. One read answers both.
+     * @returns {Promise<{ versionSharing: boolean, shareFiles: boolean }>} */
+    reviewFlags: async () => {
+      const data = await call("GET", SPACES, undefined, {}, SHARING_REFUSALS);
+      return {
+        versionSharing: data?.version_sharing === true,
+        shareFiles: data?.share_files === true,
+      };
+    },
+    /** Registers into `spaceId`; without one the server uses the caller's default space.
+     * @param {import("./types/reviewWire.js").RegisterProjectRequest} body @param {string | null} [spaceId]
+     * @returns {Promise<ProjectDTO>} */
+    register: (body, spaceId) =>
+      call("POST", PROJECTS, body, spaceId ? { "x-space-id": spaceId } : {}),
+    /** @param {string} id @returns {Promise<ShareDTO>} */
+    share: (id) => call("GET", `${project(id)}/share`),
+    /** @param {string} id @param {import("./types/reviewWire.js").UpdateProjectShareRequest} body
+     * @returns {Promise<ShareDTO>} */
+    updateShare: (id, body) => call("PATCH", `${project(id)}/share`, body),
+    /** @param {string} id @param {import("./types/reviewWire.js").ProjectOperationRequest} body @returns {Promise<ShareDTO>} */
+    linkOn: (id, body) => call("POST", `${project(id)}/share`, body),
+    /** @param {string} id @returns {Promise<null>} */
+    linkOff: (id) => call("DELETE", `${project(id)}/share`),
+    /** @param {string} id @returns {Promise<ProjectDTO>} */
+    project: (id) => call("GET", project(id)),
+    /** One page of the project's comments, every state. @param {string} id @param {URLSearchParams} query
+     * @returns {Promise<import("./types/reviewWire.js").FeedbackPage>} */
+    feedback: (id, query) => call("GET", `${project(id)}/feedback?${query}`),
+    /** A new version from a local MP4. A body factory runs after sign-in on each attempt.
+     * @param {string} id @param {ExportRequest | (() => Promise<ExportRequest>)} body @returns {Promise<ExportDTO>} */
+    createExport: (id, body) => call("POST", `${project(id)}/exports`, body),
+    /** @param {string} id @param {string} videoId @returns {Promise<ExportDTO>} */
+    readExport: (id, videoId) =>
+      call("GET", `${project(id)}/exports/${encodeURIComponent(videoId)}`),
+    /** The upload is in storage: start processing. @param {string} id @param {string} videoId
+     * @returns {Promise<ExportDTO>} */
+    completeExport: (id, videoId) =>
+      call("POST", `${project(id)}/exports/${encodeURIComponent(videoId)}/complete`),
+    /** Attaches the synced snapshot to a version that has none; the same one again is a no-op, another is refused
+     * with 409 `snapshot_already_attached`. @param {string} id @param {string} versionId
+     * @param {import("./types/reviewWire.js").SnapshotRef} snapshot @returns {Promise<unknown>} */
+    attachSnapshot: (id, versionId, snapshot) =>
+      call("PUT", `${project(id)}/versions/${encodeURIComponent(versionId)}/snapshot`, snapshot),
+    ...shareOpenCalls(tokenCall),
+    ...managementClient(call, project, access),
+    ...threadWrites(call, project),
+  };
+}
+
+/** The owner's writes on one thread. @param {(method: string, route: string, body?: unknown) => Promise<any>} call
+ * @param {(id: string) => string} project */
+function threadWrites(call, project) {
+  const thread = (/** @type {string} */ id, /** @type {string} */ rootId) =>
+    `${project(id)}/comments/${encodeURIComponent(rootId)}`;
+  return {
+    /** Accept, dismiss, reopen or resolve a thread. @param {string} id @param {string} rootId
+     * @param {{ action: import("./types/review.js").ReviewAction, expected_status_revision: number }} body */
+    setStatus: (id, rootId, body) => call("PATCH", `${thread(id, rootId)}/status`, body),
+    /** @param {string} id @param {string} rootId
+     * @param {{ client_operation_id: string, body: string, attachment_ids: string[] }} body */
+    reply: (id, rootId, body) => call("POST", `${thread(id, rootId)}/replies`, body),
+  };
+}
+
+/** An invite to an email whose grant was revoked: the server keeps the revoked row, leaves it out of the grant list,
+ * and takes it back only with that row's revision and a fresh operation ID, so the one revision the client can learn is
+ * the conflict's. Null for any other refusal, or one the same revision already got.
+ * @param {unknown} error @param {import("./types/reviewWire.js").CreateGrantRequest} body
+ * @returns {import("./types/reviewWire.js").CreateGrantRequest | null} */
+function regrantOf(error, body) {
+  if (!(error instanceof ReviewFailed) || error.reason !== "revision_conflict") return null;
+  if (typeof error.currentRevision !== "number") return null;
+  // A current revision of 0 is no row at all, which the server asks for as no revision.
+  const revision = error.currentRevision || null;
+  if (revision === body.expected_revision) return null;
+  return { ...body, client_operation_id: randomUUID(), expected_revision: revision };
+}
+
+/** Creating a grant, keeping the re-grant `regrantOf` makes as that invitation's retry. The window retries with the
+ * operation it first sent; once a re-grant went out under a new operation, that exact re-grant is sent again, so the
+ * server's replay recovers a lost answer (or refuses it as revoked since) and no further re-grant is made. It goes
+ * exactly when the window drops its own operation: on an answer, on a refusal `rejectedGrantRequest` (the window's own
+ * test) calls final, or when the email is invited afresh. Any other refusal, a moderation hold among them, keeps it.
+ * @param {(method: string, route: string, body?: unknown) => Promise<any>} call @param {(id: string) => string} project
+ * @param {import("./types/access.js").ApiAccess} access */
+function grantCreator(call, project, access) {
+  /** Re-grants awaiting a final answer, by site, account, project and the operation the window sent.
+   * @type {Map<string, { email: string, regrant: import("./types/reviewWire.js").CreateGrantRequest }>} */
+  const sent = new Map();
+  /** @param {string} route @param {string} key @param {import("./types/reviewWire.js").CreateGrantRequest} body */
+  const settle = async (route, key, body) => {
+    try {
+      const answer = await call("POST", route, body);
+      sent.delete(key);
+      return answer;
+    } catch (error) {
+      if (rejectedGrantRequest(error)) sent.delete(key);
+      throw error;
+    }
+  };
+  /** @param {string} id @param {import("./types/reviewWire.js").CreateGrantRequest} body
+   * @returns {Promise<import("./types/reviewWire.js").AccessGrantDTO>} */
+  return async (id, body) => {
+    const route = `${project(id)}/access-grants`;
+    // expected: signed out, the POST below refuses as login_required; the scope is only a key.
+    const who = await access().catch(() => null);
+    const scope = grantScope(who, id);
+    const key = `${scope}\n${body.client_operation_id}`;
+    const retained = sent.get(key);
+    if (retained) return settle(route, key, retained.regrant);
+    for (const [other, kept] of sent)
+      if (other.startsWith(`${scope}\n`) && kept.email === body.email) sent.delete(other);
+    try {
+      return await call("POST", route, body);
+    } catch (error) {
+      const regrant = regrantOf(error, body);
+      if (!regrant) throw error;
+      sent.set(key, { email: body.email, regrant });
+      return settle(route, key, regrant);
+    }
+  };
+}
+
+/** @typedef {ReturnType<typeof reviewClient>} ReviewClient
+ * @typedef {import("./types/reviewWire.js").ExportRequest} ExportRequest */
+
+/** @param {(method: string, route: string, body?: unknown, headers?: Record<string,string>) => Promise<any>} call
+ * @param {(id: string) => string} project @param {import("./types/access.js").ApiAccess} access */
+function managementClient(call, project, access) {
+  return {
+    /** @param {string} id @param {{ title: string, expected_title: string }} body
+     * @returns {Promise<{title: string}>} */
+    updateTitle: (id, body) => call("PATCH", project(id), body),
+    /** @param {string} spaceId @param {string | null} [cursor] @returns
+     * {Promise<import("./types/reviewWire.js").ManagedReviewPage>} */
+    listProjects: (spaceId, cursor = null) =>
+      call("GET", `${PROJECTS}?${new URLSearchParams(cursor ? { cursor } : {})}`, undefined, {
+        "x-space-id": spaceId,
+      }),
+    /** @param {string} id @returns {Promise<null>} */
+    removeProject: (id) => call("DELETE", project(id)),
+    /** @param {string} id @returns {Promise<{items: import("./types/reviewWire.js").AccessGrantDTO[]}>} */
+    grants: async (id) => {
+      const items = [];
+      const cursors = new Set();
+      let cursor = null;
+      do {
+        const query = new URLSearchParams(cursor ? { cursor } : {});
+        const page = await call("GET", `${project(id)}/access-grants?${query}`);
+        items.push(...page.items);
+        cursor = page.next_cursor;
+        if (cursor && (cursors.has(cursor) || cursors.size >= 1000))
+          throw new ReviewFailed(502, "malformed_grant_pagination");
+        cursors.add(cursor);
+      } while (cursor);
+      return { items };
+    },
+    createGrant: grantCreator(call, project, access),
+    /** @param {string} id @param {string} grantId @param {{role: import("./types/reviewWire.js").AccessGrantDTO["role"],
+     * expected_revision: number}} body @returns {Promise<import("./types/reviewWire.js").AccessGrantDTO>} */
+    updateGrant: (id, grantId, body) =>
+      call("PATCH", `${project(id)}/access-grants/${encodeURIComponent(grantId)}`, body),
+    /** @param {string} id @param {string} grantId @returns {Promise<null>} */
+    revokeGrant: (id, grantId) =>
+      call("DELETE", `${project(id)}/access-grants/${encodeURIComponent(grantId)}`),
+  };
+}
+
+/** @param {Awaited<ReturnType<import("./types/access.js").ApiAccess>>} who @param {string} id */
+const grantScope = (who, id) => [who?.heygen ?? "", who?.owner ?? "", id].join("\n");