@hyperframes/share 0.0.0-stage → 0.9.21

package/src/reviewSwitch.mjs

@@ -0,0 +1,430 @@
+// @ts-check
+// Changing a review link's space (decided 2026-10-13): a new link in the new space, the old one off.
+// The record keeps the old project until the new one has the video; a file beside the record holds the change
+// meanwhile, so the next read of the link finishes one a failure or a crash left half done.
+import { firstReviewAudience } from "./reviewAudience.mjs";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdirInside } from "./storage.mjs";
+import { writeJsonAtomic } from "./storage.mjs";
+import { ReviewFailed } from "./reviewClient.mjs";
+import {
+  applyFirstAudience,
+  listSpaces,
+  oneAtATime,
+  projectLine,
+  readReviewSwitch as readSwitch,
+  readShare,
+  rebindRecord,
+  reviewRecord,
+  reviewSentence,
+  reviewSwitchPath,
+  shown,
+  takenDown,
+} from "./reviewShare.mjs";
+import { rm } from "./storage.mjs";
+
+/** @typedef {import("./reviewClient.mjs").ReviewClient} ReviewClient
+ * @typedef {import("./types/share.js").ReviewShare} ReviewShare */
+
+/** `body`: the registration as sent, so a retry is exact; `revokeFailures`: failed turn-offs of the old link.
+ * @typedef {{ 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 }} Switch */
+
+/** Puts the newest export on `projectId`; `onUploaded` runs once the server has it. Answers the sentence when it did
+ * not go up. @typedef {(projectId: string, onUploaded: () => Promise<void>) => Promise<string | null>} Upload */
+
+/** Why the newest export cannot go up now, or null when it can. @typedef {() => Promise<"export_first" |
+ * "version_running" | null>} CanUpload */
+
+/** A refusal of a change of space, with the space's name and, for a failed upload, why it failed. */
+class SwitchFailed extends ReviewFailed {
+  /** @param {number} status @param {string} reason
+   * @param {{ space?: string, from?: string, sentence?: string }} said */
+  constructor(status, reason, { space = "", from = "", sentence = "" } = {}) {
+    super(status, reason);
+    this.space = space;
+    this.from = from;
+    this.sentence = sentence;
+  }
+}
+
+const switchPath = reviewSwitchPath;
+
+/** Starts a new journal; only ever called once no earlier one holds an old link on. @param {string} dir
+ * @param {Switch} change */
+async function startSwitch(dir, change) {
+  await oneAtATime(dir, async () => {
+    const record = await reviewRecord(dir);
+    if (record?.removed) throw new ReviewFailed(410, "review_project_removed");
+    if (record?.projectId !== change.from) throw new ReviewFailed(409, "switch_cancelled");
+    await mkdirInside(dir, ".hyperframes");
+    await writeJsonAtomic(switchPath(dir), change);
+  });
+}
+
+/** Whether the journal on disk is still this change's: a stale step never rewrites or drops a newer one.
+ * @param {string} dir @param {Switch} change */
+const owns = async (dir, change) => {
+  const saved = await readSwitch(dir);
+  return (
+    saved !== null &&
+    saved.id === change.id &&
+    saved.from === change.from &&
+    saved.spaceId === change.spaceId &&
+    saved.body.client_operation_id === change.body.client_operation_id
+  );
+};
+
+/** A removed or superseded change cannot publish or replace the current record.
+ * @param {string} dir @param {Switch} change */
+async function assertCurrent(dir, change) {
+  const record = await reviewRecord(dir);
+  if (record?.removed) throw new ReviewFailed(410, "review_project_removed");
+  if (
+    !(await owns(dir, change)) ||
+    !record ||
+    (record.projectId !== change.from && record.projectId !== change.projectId)
+  )
+    throw new ReviewFailed(409, "switch_cancelled");
+}
+
+/** @param {string} dir @param {Switch} change */
+async function writeSwitch(dir, change) {
+  if (await owns(dir, change)) await writeJsonAtomic(switchPath(dir), change);
+}
+
+/** @param {string} dir @param {Switch} change */
+async function advanceSwitch(dir, change) {
+  await oneAtATime(dir, async () => {
+    await assertCurrent(dir, change);
+    await writeSwitch(dir, change);
+  });
+}
+
+/** @param {string} dir @param {Switch} change */
+async function dropSwitch(dir, change) {
+  if (await owns(dir, change)) await rm(switchPath(dir), { force: true });
+}
+
+/** The same change asks with the same key: the studio project, the old project, the space and the title. The title
+ * keeps a later round trip under a new name from replaying an earlier key with another body (operation_conflict).
+ * @param {string} studioProjectId @param {string} spaceId @param {string} from @param {string} title */
+export const switchOperationId = (studioProjectId, spaceId, from, title) =>
+  `space-${createHash("sha256")
+    .update(JSON.stringify([studioProjectId, spaceId, from, title]))
+    .digest("hex")
+    .slice(0, 48)}`;
+
+/** Every step that touches a project's journal (a change, a read's cleanup or resume) runs one after another. Its own
+ * line: a change waits inside it on the record's line, so sharing that one would wait on itself. */
+const journal = projectLine();
+const inTurn = journal.inTurn;
+
+/** A read's own step only when nothing else holds the project: a read never waits on an upload, and the step that
+ * holds it finishes the journal itself. @param {string} dir @param {() => Promise<void>} step */
+const whenIdle = (dir, step) => (journal.busy(dir) ? Promise.resolve() : inTurn(dir, step));
+
+/** A space this token can register into, by id; anything else is refused before any write.
+ * @param {ReviewClient} client @param {string} spaceId */
+async function targetSpace(client, spaceId) {
+  const space = (await listSpaces(client)).find((s) => s.space_id === spaceId);
+  if (!space?.can_create_review)
+    throw new SwitchFailed(403, "space_forbidden", { space: space?.name ?? "" });
+  return space;
+}
+
+/** Registration answers no retry fixes: the change is dropped and says why. */
+const ENDS_A_CHANGE = new Set(["space_forbidden", "project_bound_to_other_owner", "same_project"]);
+
+/** Registers the change's body in its space, once; a refusal there ends the change. So does an answer naming the
+ * old project: going on would put the version back on it and then turn its link, the only one, off.
+ * @param {ReviewClient} client @param {string} dir @param {Switch} change @returns {Promise<Switch>} */
+async function registered(client, dir, change) {
+  if (change.projectId) return change;
+  try {
+    const { project_id } = await client.register(change.body, change.spaceId);
+    if (project_id === change.from) {
+      console.error("[review] registration in another space answered the old project:", {
+        request: { space: change.spaceId, body: change.body },
+        answer: { project_id },
+      });
+      throw new SwitchFailed(409, "same_project", { space: change.space });
+    }
+    const next = { ...change, projectId: project_id };
+    await advanceSwitch(dir, next);
+    return next;
+  } catch (error) {
+    return registrationRefused(error, dir, change);
+  }
+}
+
+/** @param {unknown} error @param {string} dir @param {Switch} change @returns {Promise<never>} */
+async function registrationRefused(error, dir, change) {
+  const reason = error instanceof ReviewFailed ? error.reason : "";
+  if (reason === "review_project_limit_reached" || reason === "review_subscription_required") {
+    await advanceSwitch(dir, { ...change, paused: true });
+    throw error;
+  }
+  if (reason === "review_project_removed") {
+    await dropSwitch(dir, change);
+    throw error;
+  }
+  if (!ENDS_A_CHANGE.has(reason)) throw error;
+  await dropSwitch(dir, change);
+  throw new SwitchFailed(/** @type {ReviewFailed} */ (error).status, reason, {
+    space: change.space,
+    from: change.fromSpace ?? "",
+  });
+}
+
+/** The new link on and open to its space, then the old one off; a failed turn-off stays in the file. A takedown of
+ * the old review before the new link opened keeps the new one as it is: private, its link not turned on.
+ * @param {ReviewClient} client @param {string} dir @param {Switch & { projectId: string }} change */
+async function settle(client, dir, change) {
+  return oneAtATime(dir, async () => {
+    await assertCurrent(dir, change);
+    let share = await readShare(client, change.projectId);
+    let now = change;
+    if (!now.opened) {
+      if (!(await oldTakenDown(client, now)))
+        share = await openNew(client, now.projectId, share, now.audience);
+      await writeSwitch(dir, (now = { ...now, opened: true }));
+    }
+    await turnOffOld(client, dir, now);
+    return shown(client, share);
+  });
+}
+
+/** The new link on and open to its space. A takedown refuses both for good (409 moderation_hold), so the change
+ * stops asking and still turns the old link off. @param {ReviewClient} client @param {string} id
+ * @param {import("./types/reviewWire.js").ShareDTO} share @param {import("./types/share.js").AccessMode} [audience] */
+async function openNew(client, id, share, audience) {
+  if (takenDown(share)) return share;
+  try {
+    if (share.revoked)
+      share = await client.linkOn(id, {
+        expected_link_generation: share.link_generation,
+        client_operation_id: randomUUID(),
+      });
+    return await applyFirstAudience(client, id, share, audience);
+  } catch (error) {
+    if (!(error instanceof ReviewFailed) || error.reason !== "moderation_hold") throw error;
+    return readShare(client, id);
+  }
+}
+
+/** Only a 204, or a 404 for a share the server no longer has, ends the cleanup. Anything else keeps it, a lost
+ * permission (403) included: that proves nothing about the link, and the owner may need to act.
+ * @param {ReviewClient} client @param {string} dir @param {Switch} change */
+async function turnOffOld(client, dir, change) {
+  try {
+    await client.linkOff(change.from);
+  } catch (error) {
+    if (!(error instanceof ReviewFailed) || error.status !== 404) {
+      console.error("[review] old link not turned off yet:", error);
+      const failed =
+        (change.revokeFailures ?? 0) +
+        (error instanceof ReviewFailed && error.status === 403 ? 2 : 1);
+      return writeSwitch(dir, { ...change, revokeFailures: failed });
+    }
+  }
+  await dropSwitch(dir, change);
+}
+
+/** The switched change whose old link is still to turn off, or null. @param {string} dir */
+async function cleanupOf(dir) {
+  const change = await readSwitch(dir);
+  if (!change?.projectId) return null;
+  const at = (await reviewRecord(dir))?.projectId;
+  return change.opened || at === change.projectId
+    ? { ...change, projectId: change.projectId }
+    : null;
+}
+
+/** Each read of the link turns off an old link a change left on, in turn with every other journal step.
+ * @param {{ projectPath: string, client: ReviewClient }} request @returns {Promise<void>} */
+export const retryOldLink = ({ projectPath, client }) =>
+  whenIdle(projectPath, async () => {
+    const change = await cleanupOf(projectPath);
+    if (change) await settle(client, projectPath, change);
+  });
+
+/** 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 async function oldLinkOf(projectPath) {
+  const change = await cleanupOf(projectPath);
+  if (!change) return null;
+  return { space: change.fromSpace ?? "the old space", stuck: (change.revokeFailures ?? 0) >= 2 };
+}
+
+/** Registered: the video goes up to the new project, the record switches there once it has it, then `settle`.
+ * @param {ReviewClient} client @param {string} dir @param {Switch} change @param {Upload} upload */
+async function carryOn(client, dir, change, upload) {
+  const at = await registered(client, dir, change);
+  await oneAtATime(dir, () => assertCurrent(dir, at));
+  await readShare(client, /** @type {string} */ (at.projectId)).catch(async (error) => {
+    if (error instanceof ReviewFailed && error.reason === "review_project_removed")
+      await dropSwitch(dir, at);
+    throw error;
+  });
+  const projectId = /** @type {string} */ (at.projectId);
+  let switched = false;
+  const failure = await new Promise((done, failed) => {
+    const onUploaded = async () => {
+      await oneAtATime(dir, async () => {
+        await assertCurrent(dir, at);
+        await openNew(client, projectId, await readShare(client, projectId), at.audience);
+        await writeSwitch(dir, { ...at, opened: true });
+        await rebindRecord(dir, projectId, at.spaceId);
+      });
+      switched = true;
+      done(null);
+    };
+    upload(projectId, onUploaded).then(done, failed);
+  });
+  if (!switched)
+    throw new SwitchFailed(409, "switch_upload", {
+      sentence: failure ?? "Couldn't add this version. Try again.",
+    });
+  return settle(client, dir, { ...at, projectId });
+}
+
+/** A change that switched but left its old link on finishes first; no new change starts while it stays on.
+ * @param {ReviewClient} client @param {string} dir @param {Switch} saved */
+async function oldLinkFirst(client, dir, saved) {
+  await settle(client, dir, { ...saved, projectId: /** @type {string} */ (saved.projectId) });
+  if (await readSwitch(dir))
+    throw new SwitchFailed(409, "old_link_on", { space: saved.fromSpace ?? "" });
+}
+
+/** A change to `spaceId`, refused before anything is written when the space or the export cannot take it.
+ * @param {{ client: ReviewClient, record: { studioProjectId: string, projectId: string | null }, title: string,
+ * spaceId: string, now: import("./types/reviewWire.js").ShareDTO, canUpload: CanUpload, audience?:
+ * import("./types/share.js").AccessMode | undefined }} request
+ * @returns {Promise<Switch>} */
+async function newChange({ client, record, title, spaceId, now, canUpload, audience }) {
+  const space = await targetSpace(client, spaceId);
+  const chosen = firstReviewAudience(space.review_entitlements, audience);
+  const blocked = await canUpload();
+  if (blocked) throw new SwitchFailed(409, blocked, { space: space.name });
+  const from = /** @type {string} */ (record.projectId);
+  const named = title.slice(0, 255);
+  return {
+    id: randomUUID(),
+    audience: chosen,
+    from,
+    fromSpace: now.space?.name ?? "the old space",
+    spaceId,
+    space: space.name,
+    projectId: null,
+    body: {
+      studio_project_id: record.studioProjectId,
+      title: named,
+      client_operation_id: switchOperationId(record.studioProjectId, spaceId, from, named),
+    },
+  };
+}
+
+/** @param {string} projectPath */
+async function sharedRecord(projectPath) {
+  const record = await reviewRecord(projectPath);
+  if (record?.removed) throw new ReviewFailed(410, "review_project_removed");
+  if (!record?.opened || !record.projectId) throw new ReviewFailed(404, "not_shared");
+  return { ...record, projectId: record.projectId };
+}
+
+/** Moves a shared project's link to `spaceId`: a new link there, the newest export on it, the old link off. Its own
+ * space answers the link as it is. Refuses before any write when the export cannot go up.
+ * @param {{ projectPath: string, title: string, client: ReviewClient, spaceId: string, upload: Upload,
+ * canUpload: CanUpload, audience?: import("./types/share.js").AccessMode | undefined }} request @returns
+ * {Promise<ReviewShare>} */
+export const changeSpace = ({ projectPath, title, client, spaceId, upload, canUpload, audience }) =>
+  inTurn(projectPath, async () => {
+    const record = await sharedRecord(projectPath);
+    const from = record.projectId;
+    const saved = await readSwitch(projectPath);
+    if (saved?.projectId === from) await oldLinkFirst(client, projectPath, saved);
+    // A change already registered there carries on; one never registered is made again, with the same key.
+    if (saved?.from === from && saved.spaceId === spaceId) {
+      if (await droppedForTakedown(client, projectPath, saved))
+        throw new ReviewFailed(409, "moderation_hold");
+      const target = await targetSpace(client, spaceId);
+      const retry = {
+        ...saved,
+        audience: firstReviewAudience(target.review_entitlements, audience),
+        paused: false,
+      };
+      await advanceSwitch(projectPath, retry);
+      return carryOn(client, projectPath, retry, upload);
+    }
+    const now = await readShare(client, from);
+    if (sameSpace(now, record.spaceId, spaceId)) return shown(client, now);
+    if (takenDown(now)) throw new ReviewFailed(409, "moderation_hold");
+    const change = await newChange({ client, record, title, spaceId, now, canUpload, audience });
+    await startSwitch(projectPath, change);
+    return carryOn(client, projectPath, change, upload);
+  });
+
+/** On the next read of the link: finishes the upload of a change a crash or a failure left half done (the old link's
+ * turn-off is `retryOldLink`'s). One never switched that the record has moved past is dropped: no link of it is on.
+ * @param {{ projectPath: string, client: ReviewClient, upload: Upload, canUpload: CanUpload }} request */
+export const resumeSpaceChange = async ({ projectPath, client, upload, canUpload }) => {
+  // An old link still on is retryOldLink's: holding the journal only to see that would make the next read skip it.
+  if (await cleanupOf(projectPath)) return;
+  return whenIdle(projectPath, async () => {
+    const change = await readSwitch(projectPath);
+    if (!change || change.paused || (await cleanupOf(projectPath))) return;
+    const at = (await reviewRecord(projectPath))?.projectId;
+    if (at !== change.from) return dropSwitch(projectPath, change);
+    if (await droppedForTakedown(client, projectPath, change)) return;
+    if (!(await canUpload())) await carryOn(client, projectPath, change, upload);
+  });
+};
+
+/** A saved change whose old review staff took down is dropped before it registers, uploads or opens anything: the
+ * server takes all three under a takedown, so finishing it would share the review again. A failed read is no
+ * takedown and the change goes on as it did. @param {ReviewClient} client @param {string} dir @param {Switch} change */
+async function droppedForTakedown(client, dir, change) {
+  try {
+    if (!(await oldTakenDown(client, change))) return false;
+  } catch (error) {
+    if (error instanceof ReviewFailed && error.reason === "review_project_removed")
+      await dropSwitch(dir, change);
+    throw error;
+  }
+  await dropSwitch(dir, change);
+  return true;
+}
+
+/** Whether staff took the change's old review down; a failed read says no.
+ * @param {ReviewClient} client @param {Switch} change */
+async function oldTakenDown(client, change) {
+  const old = await readShare(client, change.from).catch((error) => {
+    if (error instanceof ReviewFailed && error.reason === "review_project_removed") throw error;
+    return null;
+  });
+  return Boolean(old && takenDown(old));
+}
+
+/** 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, fallback) {
+  if (!(error instanceof SwitchFailed)) return reviewSentence(error, fallback);
+  const space = error.space || "that space";
+  if (error.reason === "space_forbidden") return `You can't share to ${space} with this account.`;
+  if (error.reason === "project_bound_to_other_owner")
+    return `Someone else already shares this project in ${space}.`;
+  if (error.reason === "export_first")
+    return `Export an MP4 of the project as it is now, then share it to ${space}.`;
+  if (error.reason === "old_link_on")
+    return "Couldn’t move the link. Your current link still works.";
+  if (error.reason === "same_project")
+    return `HyperFrames kept this link in ${error.from || "its space"} instead of moving it to ${space}. The old link still works.`;
+  if (error.reason === "version_running")
+    return "A version is still going up. Change the space once it's on the page.";
+  return `${error.sentence} The old link still works.`;
+}
+
+/** @param {import("./types/reviewWire.js").ShareDTO} share @param {string | null} saved @param {string} target */
+const sameSpace = (share, saved, target) => (share.space?.space_id ?? saved) === target;

package/src/reviewUpload.mjs

@@ -0,0 +1,98 @@
+// @ts-check
+// The bytes of a review version: its checksum, and the signed PUT to storage.
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import { reviewUploadOrigins } from "./host.mjs";
+
+/** 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) {
+  return new Promise((resolve, reject) => {
+    const hash = createHash("sha256");
+    createReadStream(file)
+      .on("data", (chunk) => hash.update(chunk))
+      .on("error", reject)
+      .on("end", () => resolve(hash.digest("base64")));
+  });
+}
+
+/** @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 async function putFile(
+  upload,
+  file,
+  size,
+  onSent,
+  { stallMs = 60_000, fetchImpl = fetch } = {},
+) {
+  let target;
+  try {
+    target = new URL(upload.put_url);
+  } catch {
+    return "refused";
+  }
+  const loopback = target.protocol === "http:" && target.hostname === "127.0.0.1";
+  if (
+    (target.protocol !== "https:" && !loopback) ||
+    target.username ||
+    target.password ||
+    target.hash ||
+    !reviewUploadOrigins().includes(target.origin)
+  ) {
+    return "refused";
+  }
+  const stall = new AbortController();
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const arm = () => (clearTimeout(timer), (timer = setTimeout(() => stall.abort(), stallMs)));
+  let sent = 0;
+  // Pulled, never read ahead: a chunk is read when the network takes it, so the stall timer measures sending.
+  const stream = createReadStream(file);
+  const chunks = stream[Symbol.asyncIterator]();
+  const body = new ReadableStream(
+    {
+      async pull(controller) {
+        const { value, done } = await chunks.next();
+        if (done) return controller.close();
+        sent += value.length;
+        arm();
+        onSent(sent);
+        controller.enqueue(value);
+      },
+      cancel: () => void chunks.return?.(),
+    },
+    { highWaterMark: 0 },
+  );
+  arm();
+  try {
+    /** @type {RequestInit & {duplex: "half"}} */
+    const request = {
+      method: "PUT",
+      headers: { ...upload.headers, "content-length": String(size) },
+      body,
+      duplex: "half",
+      redirect: "manual",
+      signal: stall.signal,
+    };
+    const reply = await fetchImpl(target, request);
+    return await outcomeOf(reply);
+  } catch (error) {
+    console.error("[review] upload failed:", /** @type {Error} */ (error).name);
+    return "offline";
+  } finally {
+    clearTimeout(timer);
+    stream.destroy();
+  }
+}
+
+/** S3 answers 403 both when the signed URL has expired and when the signature does not match; only the first is
+ * fixed by fresh instructions. @param {Response} reply @returns {Promise<PutOutcome>} */
+async function outcomeOf(reply) {
+  if (reply.status < 300) return (await reply.body?.cancel(), "sent");
+  const text = await reply.text().catch(() => "");
+  return reply.status === 403 && /expired/i.test(text) ? "expired" : "refused";
+}

package/src/reviewVersionSentences.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+// The sentence a person reads for a version that did not go up; the log keeps the status and reason.
+import { ReviewFailed } from "./reviewClient.mjs";
+
+/** A held video is never called rejected: it waits for a person, and people with the link keep the version they had. */
+const HELD_FOR_REVIEW =
+  "Almost ready. Someone at HyperFrames needs to take a look first. This can take up to a day.";
+
+/** @type {Record<string, string | ((error: ReviewFailed) => string)>} */
+const SAID = {
+  export_too_large: "This video is over 2 GB, the most a review page takes. Export a smaller one.",
+  export_too_long:
+    "This video is over 30 minutes, the most a review page takes. Export a shorter one.",
+  export_daily_limit: (error) =>
+    `You've added the most versions for today. Try again ${laterIn(error.retryAfterMs)}.`,
+  content_rejected: "This video can't be shared.",
+  export_blocked: "Adding videos to review pages isn't available for this account.",
+  feature_unavailable: "Review pages aren't available for your account yet.",
+  permission_denied: "This account can't add videos to this review page yet.",
+  upload_expired: "The upload took too long. Try again.",
+  storage_refused: "HyperFrames couldn't store the upload. Try again.",
+  still_checking:
+    "HyperFrames is still checking the video. People with the link can watch once it's ready; open Share to look again.",
+  held_for_review: HELD_FOR_REVIEW,
+};
+
+/** @param {unknown} error */
+export function versionSentence(error) {
+  if (!(error instanceof ReviewFailed)) return "Couldn't add this version. Try again.";
+  const said = SAID[error.reason];
+  if (said) return typeof said === "function" ? said(error) : said;
+  if (error.status === 0) return "Couldn't reach HeyGen. Check your connection and try again.";
+  if (error.status === 401) return "Your sign-in has expired. Sign in again, then add the version.";
+  // A failed export whose reason has no sentence of its own (export_processing_failed): the server's message is
+  // written for developers, so it is never shown.
+  if (error.status === 200)
+    return "HyperFrames couldn't process this video. Export it again, then try again.";
+  return "Couldn't add this version. Try again.";
+}
+
+/** "in about 3 hours", from the server's Retry-After. @param {number | undefined} ms */
+function laterIn(ms) {
+  if (!ms) return "tomorrow";
+  const minutes = Math.ceil(ms / 60_000);
+  if (minutes < 60) return `in ${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const hours = Math.round(minutes / 60);
+  return `in about ${hours} hour${hours === 1 ? "" : "s"}`;
+}