@hyperframes/share 0.9.27 → 0.9.28-alpha.0

package/README.md

@@ -35,7 +35,7 @@ const [current, version] = await Promise.all([
 
 `access(refusedToken?)` returns `{ token, heygen, heygenApi, owner }` or null. It is read for every request. A refused bearer is passed back so the host can refresh it. `heygen` is the review API base. A host can inject its own `signedInRequest` to retain network tracing. `execFile` can likewise be injected to retain native process policy.
 
-Video uploads require exact storage origins from trusted host configuration. Set `reviewUploadOrigins` on the host or supply a comma-separated `HYPERFRAMES_REVIEW_UPLOAD_ORIGINS` environment variable. Configure the bucket-specific HTTPS origins used by the signer. Use URL origins without paths, trailing slashes, or wildcards. Local tests can explicitly allow an HTTP origin on `127.0.0.1`. An empty list refuses every video upload.
+Video and source uploads require exact storage origins from trusted host configuration. Set `reviewUploadOrigins` on the host or supply a comma-separated `HYPERFRAMES_REVIEW_UPLOAD_ORIGINS` environment variable. Configure the bucket-specific HTTPS origins used by the signer. Use URL origins without paths, trailing slashes, or wildcards. Local tests can explicitly allow an HTTP origin on `127.0.0.1`. An empty list refuses every upload.
 
 Before first registration the host must obtain explicit audience consent and prepare a current MP4. `shareForReview` registers/enables the link; it does not imply playable media. Await `addVersion`, then check the server project/latest ready version before reporting success. `addFirstVersion` starts background work and is for long-lived hosts only. `open: () => boolean` on `addVersion` bounds the polling lifetime without discarding the saved operation. `filesForExport(projectPath, renderedFingerprint)` optionally supplies an already-synced matching snapshot. Omit it for ordinary video sharing.
 
@@ -50,3 +50,60 @@ Metadata mutations and version uploads use separate cross-process locks under `.
 `snapshotProject` skips symlinks by default, retaining Desktop watcher, change-set and saved-render compatibility; `snapshotFiles` also skips symlink entries. Set `followSymlinks: true` for a link-aware full snapshot. The CLI-facing `projectFingerprint` opts into following linked media (with cycle detection), so edited linked files invalidate its cached render. Both comparisons ignore HTML ID stamps. Export/history metadata, caches, hidden folders and installed packages are excluded. Hosts must record the fingerprint of the actual rendered source and must not relabel an old render with a newer fingerprint.
 
 Public type exports include `ShareHost`, `ReviewClient`, `ReviewShare`, `VersionRequest`, and `Wire`, plus `@hyperframes/share/types/reviewWire` and `types/share`. Per-module entry points preserve Desktop imports during adoption.
+
+## Source snapshots
+
+`shareSources({access, spaceId})` prepares editable source for a rendered version:
+
+```js
+const sources = shareSources({ access, spaceId });
+const result = await sources.prepare(projectPath, renderedFingerprint);
+if (result.at === "ready") {
+  await addVersion({
+    projectPath,
+    title,
+    client,
+    filesForExport: sources.filesForExport,
+    requireSource: true,
+  });
+}
+```
+
+Handle `unavailable.reason` before creating the video version. Plan ineligibility
+can use video-only; changed source, conflicts and unexpected upload failures need
+an explicit choice to omit source. The CLI exposes `--video-only` for that choice.
+`filesForExport` only validates already-prepared source; it does not upload.
+
+The adapter uses the portable-source-v4 capture/manifest rules and
+multipart transport. The pinned policy, Unicode 15.1 registry (with its license),
+and manifest test vectors are checked into this repository. Source is captured through
+verified file handles; upload bytes are streamed and checked against their hash.
+Workspace limits, upload receipts and published snapshot identity are checked.
+Pending uploads retain their original idempotency key across retries. A conflict
+is never auto-resolved. When local source changes, the adapter cancels an older
+pending upload before starting another; uploads under verification are preserved.
+A stalled storage PUT stops after 60 seconds without progress and can retry with
+the same upload identity.
+
+Default state uses `.hyperframes/share-sync.<backend-hash>.json`, with strict
+account/backend/realpath binding, private atomic writes, and a process lock.
+Hosts can inject a compatible `store` or read-only `existingBinding` resolver.
+An external Desktop binding is reused only when exact and settled; this adapter
+never writes Desktop's binding or starts a second upload on its behalf.
+
+Source sharing requires an authorized account and a workspace that supports editable project files.
+Source-plan/feature eligibility remains server controlled. Automated fixtures do
+not establish live entitlement, moderation, source download or outside-editor
+acceptance. See [the source guide](https://hyperframes.heygen.com/developers/share-source).
+
+Tests run locally without an account or service credentials:
+
+```bash
+node --test packages/share/tests/*.test.mjs
+bun run --cwd packages/share build
+```
+
+The bundled Unicode data records SHA-256 hashes for its inputs in `sources`.
+Those files are published in the [Unicode 15.1 database](https://www.unicode.org/Public/15.1.0/ucd/).
+Keep the included Unicode license with redistributed data. The pinned version
+keeps path comparison consistent across Node versions and operating systems.

package/dist/index.d.mts

@@ -19,3 +19,4 @@ export { linkStateOf, reviewLinkStates } from "./reviewLinkStates.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 { shareSources, shareSourceFingerprint, createProjectShareSourceStore } from "./shareSources.mjs";

package/dist/projectLock.d.mts

@@ -1,6 +1,6 @@
-/** @template T @param {string} projectPath @param {"review" | "export"} lane @param {() => Promise<T>} run
+/** @template T @param {string} projectPath @param {"review" | "export" | "source"} lane @param {() => Promise<T>} run
  * @param {{ timeoutMs?: number, signal?: AbortSignal }} [options] @returns {Promise<T>} */
-export function withProjectShareLock<T>(projectPath: string, lane: "review" | "export", run: () => Promise<T>, { timeoutMs, signal }?: {
+export function withProjectShareLock<T>(projectPath: string, lane: "review" | "export" | "source", run: () => Promise<T>, { timeoutMs, signal }?: {
     timeoutMs?: number;
     signal?: AbortSignal;
 }): Promise<T>;

package/dist/projectSnapshot.d.mts

@@ -16,5 +16,7 @@ export function snapshotFiles(dir: string, files: Iterable<string>): Promise<Map
 /** @param {Snapshot} before @param {Snapshot} after */
 export function diffChangedFiles(before: Snapshot, after: Snapshot): string[];
 export const HF_ID_ATTRIBUTE: RegExp;
-export function projectFingerprint(projectPath: string): Promise<string>;
+export function projectFingerprint(projectPath: string, options?: {
+    byContent?: boolean;
+}): Promise<string>;
 export type Snapshot = Map<string, unknown>;

package/dist/reviewExport.d.mts

@@ -56,6 +56,7 @@ export function versionFacts(dir: string): Promise<{
         exportedAt: string;
         projectId: string;
         files?: boolean;
+        snapshot?: ExportRequest["snapshot"];
         checksum?: string;
     } | null;
     source: "ready" | "none" | "not-mp4" | "stale";
@@ -69,6 +70,7 @@ export function versionOnPage(dir: string): Promise<{
     exportedAt: string;
     projectId: string;
     files?: boolean;
+    snapshot?: ExportRequest["snapshot"];
     checksum?: string;
 } | null>;
 /** Records that `versionId` carries files now, if it is still the last ready version.
@@ -116,6 +118,7 @@ export type VersionRecord = {
         body: ExportRequest;
         videoId: string | null;
         projectId?: string | null;
+        renderKey?: string;
         checkingSince?: number;
         snapshotRefused?: boolean;
         unanswered?: boolean;
@@ -127,8 +130,12 @@ export type VersionRecord = {
         exportedAt: string;
         projectId: string;
         files?: boolean;
+        snapshot?: ExportRequest["snapshot"];
         checksum?: string;
     } | null;
+    failure?: (Failure & {
+        projectId: string;
+    }) | null;
 };
 /**
  * `onAdded`: a version went ready, with whether it carries files and whether it is the page's first from here.
@@ -142,7 +149,7 @@ export type VersionHooks = {
 /**
  * `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.
+ * none. `allowPending` lets a host treat accepted processing or screening as a successful return.
  */
 export type VersionRequest = VersionHooks & {
     projectPath: string;
@@ -155,6 +162,9 @@ export type VersionRequest = VersionHooks & {
     projectId?: string | null;
     filesForExport?: FilesForRender;
     fromReview?: FromReview | null;
+    allowPending?: boolean;
+    requireSource?: boolean;
+    omitSource?: boolean;
 };
 /**
  * The snapshot of `rendered`, the project as the export was rendered; null when the folder is not that render.

package/dist/reviewUpload.d.mts

@@ -2,6 +2,8 @@
  * @param {string} file @returns {Promise<string>} */
 export function fileSha256Base64(file: string): Promise<string>;
 /** @typedef {"sent" | "expired" | "refused" | "offline"} PutOutcome */
+/** @param {string} url */
+export function trustedUploadUrl(url: string): URL | null;
 /** 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

package/dist/shareSources.d.mts

@@ -0,0 +1,24 @@
+/** Content identity for sharing, including portable hidden render inputs. The Desktop watch inventory stays separate.
+ * @param {string} projectPath @returns {Promise<string | null>} */
+export function shareSourceFingerprint(projectPath: string): Promise<string | null>;
+/** Prepare source explicitly before adding the video version. No unexpected network or filesystem failure is
+ * converted to video-only. `filesForExport` revalidates the prepared bytes and never starts another upload.
+ * @param {import("./sources/adapterTypes.js").SourceOptions} options */
+export function shareSources(options: import("./sources/adapterTypes.js").SourceOptions): {
+    prepare: (projectPath: string, rendered: string | null) => Promise<SourceResult>;
+    filesForExport: (projectPath: string, rendered: string | null) => Promise<import("./types/reviewWire.js").SnapshotRef | null>;
+};
+export { createProjectShareSourceStore } from "./sources/store.mjs";
+export type Preparation = {
+    binding: Binding;
+    own: boolean;
+    external: boolean;
+    api: import("./sources/api.mjs").SourceApi;
+    store: import("./sources/adapterTypes.js").SourceStore;
+    options: import("./sources/adapterTypes.js").SourceOptions;
+    signal: AbortSignal;
+    fingerprint: (path: string) => Promise<string | null>;
+    rendered: string;
+};
+export type SourceResult = import("./sources/adapterTypes.js").SourceResult;
+export type Binding = import("./sources/types.js").Binding;

package/dist/sources/adapterTypes.d.ts

@@ -0,0 +1,39 @@
+import type { Binding, BindingKey, Manifest } from "./types.js";
+import type { SnapshotRef } from "../types/reviewWire.js";
+import type { SignedInAccess } from "../signedInRequest.mjs";
+import type { SourceApi } from "./api.mjs";
+
+export interface SourceStore {
+  read(key: BindingKey): Promise<Binding | null>;
+  write(binding: Binding): Promise<void>;
+}
+export type SourceResult =
+  | { at: "ready"; snapshot: SnapshotRef }
+  | { at: "unavailable"; reason: string };
+export interface SourceOptions {
+  access: SignedInAccess;
+  spaceId: string;
+  store?: SourceStore;
+  enabled?: () => boolean;
+  fingerprint?: (path: string) => Promise<string | null>;
+  /** Host-owned Desktop bindings may be read for exact reuse, never overwritten. */
+  existingBinding?: (key: BindingKey) => Promise<Binding | null>;
+  fetchImpl?: typeof fetch;
+  signal?: AbortSignal;
+  verificationTimeoutMs?: number;
+  onProgress?: (bytes: number) => void;
+  /** Test/host seams; the default is the authenticated v3 client. */
+  api?: SourceApi;
+  wait?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export interface SourceRun {
+  binding: Binding;
+  manifest: Manifest;
+  api: SourceApi;
+  store: SourceStore;
+  fetchImpl: typeof fetch;
+  signal: AbortSignal;
+  wait: (ms: number, signal?: AbortSignal) => Promise<void>;
+  timeoutMs: number;
+  onProgress: (bytes: number) => void;
+}

package/dist/sources/api.d.mts

@@ -0,0 +1,29 @@
+/** @param {{ access: import("../signedInRequest.mjs").SignedInAccess, fetchImpl?: typeof fetch }} deps */
+export function sourceApi({ access, fetchImpl }: {
+    access: import("../signedInRequest.mjs").SignedInAccess;
+    fetchImpl?: typeof fetch;
+}): {
+    /** @param {string} space */
+    limits: (space: string) => Promise<{
+        at: "read";
+        syncAllowed: boolean;
+        maxCompositions: number;
+        compositions: number;
+        push: import("./types.js").Limits;
+    }>;
+    /** @param {string} space @param {string} composition @param {string} title */
+    create: (space: string, composition: string, title: string) => Promise<import("./types.js").Composition>;
+    /** @param {string} space @param {string} composition @param {string} snapshot */
+    snapshot: (space: string, composition: string, snapshot: string) => Promise<import("./types.js").Snapshot>;
+    /** @param {string} space @param {string} composition @param {import("./types.js").BeginRequest} body */
+    begin: (space: string, composition: string, body: import("./types.js").BeginRequest) => Promise<import("./types.js").BeginResult>;
+    /** @param {string} space @param {string} composition @param {string} upload @param {import("./types.js").GrantRequest[]} files */
+    uploadUrls: (space: string, composition: string, upload: string, files: import("./types.js").GrantRequest[]) => Promise<import("./types.js").FileGrant[]>;
+    /** @param {string} space @param {string} composition @param {string} upload */
+    status: (space: string, composition: string, upload: string) => Promise<import("./types.js").UploadReceipt>;
+    /** @param {string} space @param {string} composition @param {string} upload */
+    cancel: (space: string, composition: string, upload: string) => Promise<import("./types.js").UploadReceipt>;
+    /** @param {string} space @param {string} composition @param {string} upload */
+    submit: (space: string, composition: string, upload: string) => Promise<import("./types.js").UploadReceipt>;
+};
+export type SourceApi = ReturnType<typeof sourceApi>;

package/dist/sources/capture.d.mts

@@ -0,0 +1,24 @@
+/** A file's SHA-256 by path, size, time and inode, kept for the launch so a check after a focus reads no bytes.
+ * Only a settled file's hash is kept. */
+export function hashMemo(now?: () => number): {
+    /** @param {Found} file */
+    get: (file: Found) => string | null;
+    /** @param {Found} file @param {string} sha256 */
+    set: (file: Found, sha256: string) => void;
+};
+/** The file's SHA-256, read through the handle `openListed` checked; null when the file is not the one listed, or its
+ * bytes changed while being read. `root` is the project's real path; `resolve` finds a folder's real path.
+ * @param {string} root @param {Found} file @param {typeof realpath} [resolve] */
+export function hashListedFile(root: string, file: Found, resolve?: typeof realpath): Promise<string | null>;
+/** Captures `root` (a project's real path). `memo` reuses hashes of unchanged files; a send should pass a fresh one.
+ * @param {string} root @param {{ memo?: ReturnType<typeof hashMemo>, limits?: import("./types.js").Limits }} [options]
+ * @returns {Promise<Capture>} */
+export function captureProject(root: string, { memo, limits }?: {
+    memo?: ReturnType<typeof hashMemo>;
+    limits?: import("./types.js").Limits;
+}): Promise<Capture>;
+export type CaptureProblem = import("./types.js").CaptureProblem;
+export type Found = import("./types.js").Found;
+export type Walk = import("./types.js").Walk;
+export type Capture = import("./types.js").Capture;
+import { realpath } from "node:fs/promises";

package/dist/sources/contract.d.mts

@@ -0,0 +1,2 @@
+/** A registry's parsed JSON. @param {string} name a file in contract/, such as "path-policy.json" @returns {any} */
+export function readContract(name: string): any;

package/dist/sources/errors.d.mts

@@ -0,0 +1,24 @@
+/** The typed error for a refusal: the envelope's code when it is one of the sync routes', else the status's.
+ * @param {Response} reply @returns {Promise<SyncApiError>} */
+export function refusalOf(reply: Response): Promise<SyncApiError>;
+/** A sync route's refusal or failure. `status` is 0 when the server was never reached. */
+export class SyncApiError extends Error {
+    /** @param {SyncErrorKind} kind @param {{ status?: number, code?: string | null, param?: string | null,
+     *   requestId?: string | null, retryAfterMs?: number | null, detail?: string }} [about] */
+    constructor(kind: SyncErrorKind, about?: {
+        status?: number;
+        code?: string | null;
+        param?: string | null;
+        requestId?: string | null;
+        retryAfterMs?: number | null;
+        detail?: string;
+    });
+    kind: import("./types.js").SyncErrorKind;
+    status: number;
+    code: string | null;
+    param: string | null;
+    requestId: string | null;
+    retryAfterMs: number | null;
+    detail: string | null;
+}
+export type SyncErrorKind = import("./types.js").SyncErrorKind;

package/dist/sources/limits.d.mts

@@ -0,0 +1,12 @@
+/** The first limit broken, in the server's fixed order (file count, file size, project size, manifest size), with
+ * the biggest files first; null when the push fits. @param {readonly { path: string, size: number }[]} files
+ * @param {number} manifestBytes @param {Limits} [limits] @returns {import("./types.js").OverLimit | null} */
+export function overLimit(files: readonly {
+    path: string;
+    size: number;
+}[], manifestBytes: number, limits?: Limits): import("./types.js").OverLimit | null;
+/** @typedef {import("./types.js").Limits} Limits @typedef {import("./types.js").LimitName} LimitName */
+/** @type {Limits} */
+export const V1_LIMITS: Limits;
+export type Limits = import("./types.js").Limits;
+export type LimitName = import("./types.js").LimitName;

package/dist/sources/manifest.d.mts

@@ -0,0 +1,23 @@
+/** The canonical bytes of a valid document. @param {ManifestDocument} document */
+export function canonicalBytes(document: ManifestDocument): Buffer<ArrayBuffer>;
+/** Validates a manifest document as the server does; throws ManifestInvalid. @param {unknown} raw
+ * @param {boolean} [stored] @returns {Manifest} */
+export function parseManifest(raw: unknown, stored?: boolean): Manifest;
+/** Stored manifest bytes, which must already be canonical so their hash is the snapshot's manifest_sha256.
+ * @param {Uint8Array} body @returns {Manifest} */
+export function parseCanonicalManifest(body: Uint8Array): Manifest;
+export const ENTRYPOINT: "index.html";
+/** @typedef {import("./types.js").ManifestFile} ManifestFile @typedef {import("./types.js").Violation} Violation
+ * @typedef {import("./types.js").ManifestDocument} ManifestDocument @typedef {import("./types.js").Manifest} Manifest */
+/** Why a manifest was refused; `code` is the first violation's, in the server's order. */
+export class ManifestInvalid extends Error {
+    /** @param {Violation[]} violations */
+    constructor(violations: Violation[]);
+    violations: import("./types.js").Violation[];
+    code: string;
+}
+export function parseStoredManifest(raw: unknown): Manifest;
+export type ManifestFile = import("./types.js").ManifestFile;
+export type Violation = import("./types.js").Violation;
+export type ManifestDocument = import("./types.js").ManifestDocument;
+export type Manifest = import("./types.js").Manifest;

package/dist/sources/pathPolicy.d.mts

@@ -0,0 +1,25 @@
+/** The first rule matching a path's folded spelling. @param {string} path @returns {PathRule} */
+export function classifyPath(path: string): PathRule;
+/** `path` unchanged when every client can store it and the policy lets it travel; throws PathViolation otherwise,
+ * naming the first failing check in the registry's order. @param {string} path
+ * @param {boolean} [stored] */
+export function validatePath(path: string, stored?: boolean): string;
+/** Refuses duplicates, and any two paths (or a path and a directory prefix) one filesystem would store as one name.
+ * Each path must already pass validatePath. @param {readonly string[]} paths */
+export function checkInventoryPaths(paths: readonly string[]): void;
+/** Whether no file under folder `dir` can be listed, so a capture need not open it: its first matching rule
+ * excludes the folder and all below it, and no include rule before that one can reach inside. @param {string} dir */
+export function excludedFolder(dir: string): boolean;
+/** @typedef {import("./types.js").PathRule} PathRule @typedef {import("./types.js").PolicyDocument} PolicyDocument */
+/** A path the policy refuses: `code` is the golden vectors' shared vocabulary, `rule` the excluding rule's id. */
+export class PathViolation extends Error {
+    /** @param {string} code @param {string} path @param {string} [rule] */
+    constructor(code: string, path: string, rule?: string);
+    code: string;
+    path: string;
+    rule: string | null;
+}
+export function prefiltered(name: string): boolean;
+export function skippedSymlink(path: string): boolean;
+export type PathRule = import("./types.js").PathRule;
+export type PolicyDocument = import("./types.js").PolicyDocument;

package/dist/sources/projectState.d.mts

@@ -0,0 +1,9 @@
+/** A predicate for the paths the project's render-outputs.json lists, and everything under them; none when the file
+ * is missing or not version 1. @param {string} root @returns {Promise<(rel: string) => boolean>} */
+export function readRenderOutputs(root: string): Promise<(rel: string) => boolean>;
+/** An open agent turn (its history-turn.json exists) or a project lock whose holder still runs.
+ * @param {string} root */
+export function settledState(root: string): Promise<{
+    agentTurnOpen: boolean;
+    projectLocked: boolean;
+}>;

package/dist/sources/store.d.mts

@@ -0,0 +1,3 @@
+/** Project-local state is excluded by the portable source policy. Account/root mismatches fail closed, including copied folders.
+ * @returns {import("./adapterTypes.js").SourceStore} */
+export function createProjectShareSourceStore(): import("./adapterTypes.js").SourceStore;

package/dist/sources/transfer.d.mts

@@ -0,0 +1,45 @@
+/** PUTs bytes of `file` to a signed URL with exactly the headers the grant signed. Resolves once storage keeps them;
+ * the bytes sent must hash to `sha256`, or it throws `changed` whatever storage answered.
+ * @param {{ fetchImpl: typeof fetch, url: string, headers: Record<string, string>, file: string, path: string,
+ *   start: number, length: number, sha256: string, signal: AbortSignal, onBytes?: (bytes: number) => void, stallMs?: number }} put */
+export function putRange(put: {
+    fetchImpl: typeof fetch;
+    url: string;
+    headers: Record<string, string>;
+    file: string;
+    path: string;
+    start: number;
+    length: number;
+    sha256: string;
+    signal: AbortSignal;
+    onBytes?: (bytes: number) => void;
+    stallMs?: number;
+}): Promise<void>;
+/** Each part's SHA-256 (parts of `partBytes`, the last one shorter) and the whole file's, in one read.
+ * @param {string} file @param {number} size @param {number} partBytes @param {AbortSignal} signal */
+export function partDigests(file: string, size: number, partBytes: number, signal: AbortSignal): Promise<{
+    parts: string[];
+    whole: string;
+    complete: boolean;
+}>;
+/** Runs `work` over `items`, `limit` at a time. The first failure stops new work; the rest finish, then it throws.
+ * @template T @param {readonly T[]} items @param {number} limit @param {(item: T) => Promise<void>} work */
+export function eachLimit<T>(items: readonly T[], limit: number, work: (item: T) => Promise<void>): Promise<void>;
+/** Why a transfer stopped. `expired`: the signed URL no longer works (ask for a new one). `exists`: a create-only PUT
+ * found the object already written. `changed`: the file's bytes are not the ones captured. `unreadable`: the file
+ * could not be read (a drive unplugged, a file deleted). `corrupt`: downloaded bytes do not hash to what was asked.
+ * `transient`: the network or the store failed; the same request may be sent again. */
+export class TransferError extends Error {
+    /** @param {"expired" | "exists" | "changed" | "unreadable" | "corrupt" | "transient" | "refused"} kind
+     * @param {{ status?: number, path?: string }} [about] */
+    constructor(kind: "expired" | "exists" | "changed" | "unreadable" | "corrupt" | "transient" | "refused", about?: {
+        status?: number;
+        path?: string;
+    });
+    kind: "expired" | "refused" | "changed" | "unreadable" | "exists" | "corrupt" | "transient";
+    status: number;
+    path: string | null;
+}
+export function isAbort(error: unknown): boolean;
+export function realWait(ms: number, signal?: AbortSignal): Promise<undefined>;
+export function backoffMs(attempt: number, askedMs?: number | null, baseMs?: number, maxMs?: number): number;