akribes 0.21.17

package/dist/sub/clients.js

@@ -0,0 +1,190 @@
+/** Heartbeat backoff curve — SDK-wide canonical (#1182).
+ *  Exponential with full jitter, base 1s, cap 30s. The first failure waits
+ *  ~1s before retrying, the second ~2s, ..., capped at ~30s. Jitter spreads
+ *  reconnect attempts when many clients lose their token at once.
+ *
+ *  Exported for reuse in the SSE reconnect path and for tests. */
+export function heartbeatBackoffMs(consecutiveFailures) {
+    if (consecutiveFailures <= 0)
+        return 0;
+    const base = 1_000;
+    const cap = 30_000;
+    const exp = Math.min(base * 2 ** (consecutiveFailures - 1), cap);
+    return Math.floor(Math.random() * exp);
+}
+export class ClientsClient {
+    http;
+    projectId;
+    clientId;
+    clientName;
+    options;
+    heartbeatTimer;
+    inflightHeartbeat;
+    consecutiveFailures = 0;
+    lastStatus;
+    paused = false;
+    contractState = {
+        schemas: new Map(),
+        brokenScripts: new Set(),
+    };
+    constructor(http, projectId, clientId, clientName, options = {}) {
+        this.http = http;
+        this.projectId = projectId;
+        this.clientId = clientId;
+        this.clientName = clientName;
+        this.options = options;
+    }
+    async init(interests, opts) {
+        if (!this.clientId || !this.clientName) {
+            throw new Error('clientId and clientName are required for init(). Pass id and name to AkribesClient constructor.');
+        }
+        const res = await (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${this.projectId}/clients`, {
+            method: 'POST', headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id: this.clientId, name: this.clientName, interests }),
+            signal: opts?.signal,
+        })).json();
+        // Populate contract state from response
+        this.contractState.brokenScripts.clear();
+        if (res.interests) {
+            for (const interest of res.interests) {
+                this.contractState.schemas.set(interest.script_name, interest.input_schema);
+            }
+        }
+        // Reset paused state from any prior `auth_failed` so a fresh `init()`
+        // (e.g. after `setToken()` with a new token) revives the heartbeat.
+        this.paused = false;
+        this.consecutiveFailures = 0;
+        this.startHeartbeat();
+        return res;
+    }
+    /** Resume a heartbeat that was paused after an auth failure. Call this
+     *  after rotating the underlying token via {@link AkribesClient.setToken}. */
+    resumeHeartbeat() {
+        if (!this.heartbeatTimer && !this.inflightHeartbeat) {
+            this.paused = false;
+            this.consecutiveFailures = 0;
+            this.startHeartbeat();
+        }
+    }
+    fireStatus(status) {
+        if (this.lastStatus === status)
+            return;
+        this.lastStatus = status;
+        try {
+            this.options.onHeartbeatStatus?.(status);
+        }
+        catch { /* swallow */ }
+    }
+    startHeartbeat() {
+        // Use a recursive setTimeout chain rather than setInterval so we can vary
+        // the next delay based on the previous result — the canonical SDK-wide
+        // pattern (#1182). Base interval 30s on success, exponential-with-jitter
+        // capped at 30s on failure (added on TOP of the base interval).
+        const tick = () => {
+            this.inflightHeartbeat = (async () => {
+                try {
+                    const res = await this.http.authFetch(`${this.http.getBaseUrl()}/heartbeat`, {
+                        method: 'POST', headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify({ client_id: this.clientId }),
+                    });
+                    if (!res.ok) {
+                        if (res.status === 401 || res.status === 403) {
+                            // Revoked / expired token. Stop ticking — a 401/403 will not
+                            // self-heal by waiting, only by `setToken()` + `resumeHeartbeat()`.
+                            // Surfaces via the typed callback (#1220) instead of an endless
+                            // console.warn loop.
+                            this.fireStatus('auth_failed');
+                            this.paused = true;
+                            return;
+                        }
+                        this.consecutiveFailures += 1;
+                        this.fireStatus('unreachable');
+                        console.warn(`[Akribes SDK] heartbeat rejected: HTTP ${res.status}`);
+                    }
+                    else {
+                        this.consecutiveFailures = 0;
+                        this.fireStatus('ok');
+                    }
+                }
+                catch (e) {
+                    this.consecutiveFailures += 1;
+                    this.fireStatus('unreachable');
+                    console.warn('[Akribes SDK] heartbeat failed:', e);
+                }
+                finally {
+                    this.inflightHeartbeat = undefined;
+                    if (!this.paused) {
+                        const backoff = heartbeatBackoffMs(this.consecutiveFailures);
+                        this.heartbeatTimer = setTimeout(tick, 30_000 + backoff);
+                    }
+                    else {
+                        this.heartbeatTimer = undefined;
+                    }
+                }
+            })();
+        };
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        this.heartbeatTimer = setTimeout(tick, 30_000);
+    }
+    async list(opts) {
+        return (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${this.projectId}/clients`, opts)).json();
+    }
+    async delete(id, opts) {
+        await this.http.fetchOk(`${this.http.getBaseUrl()}/clients/${encodeURIComponent(id)}`, {
+            method: 'DELETE', signal: opts?.signal,
+        });
+    }
+    // ── Lock management ─────────────────────────────────────────────────
+    async listLocks(scriptName, opts) {
+        return (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${this.projectId}/scripts/${encodeURIComponent(scriptName)}/locks`, opts)).json();
+    }
+    async revokeLock(scriptName, lockId, opts) {
+        await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${this.projectId}/scripts/${encodeURIComponent(scriptName)}/locks/${lockId}`, { method: 'DELETE', signal: opts?.signal });
+    }
+    async rebindLock(scriptName, lockId, versionId, opts) {
+        return (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${this.projectId}/scripts/${encodeURIComponent(scriptName)}/locks/${lockId}/rebind`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ version_id: versionId ?? null }),
+            signal: opts?.signal,
+        })).json();
+    }
+    // ── Flat cross-project lock helpers (#1133) ───────────────────────────
+    //
+    // The methods above operate on `this.projectId`. The flat helpers below
+    // take an explicit `projectId` so admin tools spanning multiple projects
+    // can manage locks without spinning up a fresh project-scoped client.
+    // Mirrors Rust's `list_locks_for` / `delete_lock` / `update_lock`.
+    /** List contract locks for `scriptName` in `projectId`. Cross-project
+     *  variant of {@link listLocks}; the implicit project_id on this client
+     *  is ignored. */
+    async listLocksFor(projectId, scriptName, opts) {
+        return (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${projectId}/scripts/${encodeURIComponent(scriptName)}/locks`, opts)).json();
+    }
+    /** Delete (revoke) a single lock in `projectId`. Cross-project variant
+     *  of {@link revokeLock}. */
+    async deleteLock(projectId, scriptName, lockId, opts) {
+        await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${projectId}/scripts/${encodeURIComponent(scriptName)}/locks/${lockId}`, { method: 'DELETE', signal: opts?.signal });
+    }
+    /** Update (rebind) a single lock to a new version in `projectId`.
+     *  Cross-project variant of {@link rebindLock}. Pass `versionId =
+     *  undefined` to rebind the lock to the channel's current version. */
+    async updateLock(projectId, scriptName, lockId, versionId, opts) {
+        return (await this.http.fetchOk(`${this.http.getBaseUrl()}/projects/${projectId}/scripts/${encodeURIComponent(scriptName)}/locks/${lockId}/rebind`, {
+            method: 'PATCH',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ version_id: versionId ?? null }),
+            signal: opts?.signal,
+        })).json();
+    }
+    async destroy() {
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        this.heartbeatTimer = undefined;
+        this.paused = true;
+        if (this.inflightHeartbeat)
+            await this.inflightHeartbeat;
+    }
+}
+//# sourceMappingURL=clients.js.map

package/dist/sub/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../src/sub/clients.ts"],"names":[],"mappings":"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"}

package/dist/sub/documents.d.ts

@@ -0,0 +1,113 @@
+import type { HttpClient } from '../http';
+export type ConversionStatus = 'text' | 'ready' | 'converting' | 'pending' | 'failed' | 'unknown';
+export type UploadResult = {
+    document_id: string;
+    filename: string;
+    content_hash: string;
+    conversion_status: ConversionStatus;
+};
+export type ClaimOutcome = {
+    status: 'hit';
+    result: UploadResult;
+} | {
+    status: 'miss';
+};
+export type IngestPhase = 'claiming' | 'uploading' | 'converting' | 'ready';
+/** Per-page progress while a conversion is in flight on the server.
+ *  `done` and `total` are page counts (not chunks). `total = 0` means the
+ *  server hasn't yet rasterized far enough to know — render an indeterminate
+ *  bar in that case. */
+export type IngestProgress = {
+    done: number;
+    total: number;
+};
+export type IngestOptions = {
+    signal?: AbortSignal;
+    onPhase?: (phase: IngestPhase) => void;
+    /** Fires periodically while the server is converting. Polls a separate
+     *  metadata endpoint — never carries markdown, just page counts.
+     *  Frequency: every ~750 ms during the converting phase. */
+    onProgress?: (p: IngestProgress) => void;
+    /** Maximum time to keep polling a still-converting blob, in milliseconds.
+     *  When omitted, falls back to the client-level
+     *  `AkribesClientOptions.ingestPollTimeoutMs` (which itself defaults to
+     *  {@link DEFAULT_INGEST_POLL_TIMEOUT_MS} = 300 s). Use this per-call
+     *  option to override for a specific ingest, e.g. unusually large PDFs. */
+    pollTimeoutMs?: number;
+};
+/** Default poll budget for {@link DocumentsClient.ingest}, in milliseconds.
+ *
+ *  20 minutes. The previous 5 min default still surfaced
+ *  `IngestTimeoutError`s on perfectly healthy big-PDF conversions while the
+ *  server quietly kept working — that's a UX bug, not a hang signal. Real
+ *  hangs are caught by the server's own watchdogs (see
+ *  `wait_for_blob_ready`); the SDK timeout exists only as a final hard cap
+ *  so callers don't poll forever on a process leak. UIs are expected to
+ *  surface live progress via `onProgress` and offer a Cancel button rather
+ *  than waiting for this deadline.
+ *
+ *  Override via:
+ *  - per-ingest: {@link IngestOptions.pollTimeoutMs}
+ *  - per-client: `AkribesClientOptions.ingestPollTimeoutMs`
+ *  - process-wide: env var `AKRIBES_SDK_INGEST_TIMEOUT_SECS` (Node/Bun only).
+ */
+export declare const DEFAULT_INGEST_POLL_TIMEOUT_MS: number;
+/** Read `AKRIBES_SDK_INGEST_TIMEOUT_SECS` from the host's process env (Node/Bun
+ *  expose `process.env`; browser bundles don't and will skip this).
+ *  Returns `undefined` if unset, zero, or unparseable — the caller falls back
+ *  to the next-lower-precedence value. */
+export declare function ingestPollTimeoutMsFromEnv(): number | undefined;
+/** Thrown when the conversion pipeline fails. Two trigger paths:
+ *
+ *  1. The server returned a 4xx/5xx with `error_type: "conversion_failed"`
+ *     during claim/upload (e.g. the VLM rejected the file, pdfium couldn't
+ *     read it, the conversion service was down). `document_id` is empty
+ *     because no document was created.
+ *  2. The server returned 200 with `conversion_status: "failed"` from claim
+ *     (the bytes have a poisoned blob row that hasn't been reclaimed yet).
+ *
+ *  The `message` is server-supplied and user-facing — surface it directly in
+ *  the UI instead of swapping in a generic fallback. `reason` is a stable
+ *  machine-readable string for branching:
+ *  `service_unavailable`, `service_rejected`, `file_too_large`,
+ *  `invalid_file`, `extraction_failed`. */
+export declare class DocumentConversionError extends Error {
+    readonly document_id: string;
+    readonly reason?: string;
+    constructor(document_id: string, message: string, reason?: string);
+}
+/** Thrown when `ingest()` polls past its `pollTimeoutMs` deadline. */
+export declare class IngestTimeoutError extends Error {
+    readonly document_id: string;
+    readonly elapsed_ms: number;
+    constructor(message: string, document_id: string, elapsed_ms: number);
+}
+/** Thrown for protocol-level problems: unknown `conversion_status` strings,
+ *  `crypto.subtle` unavailable, etc. Signals schema drift or missing browser
+ *  features — surfacing loudly is the point. */
+export declare class IngestProtocolError extends Error {
+    readonly received_status?: string;
+    constructor(message: string, received_status?: string);
+}
+export declare class DocumentsClient {
+    private http;
+    private projectId;
+    /** Resolved client-level default poll timeout. Per-call
+     *  {@link IngestOptions.pollTimeoutMs} still wins. */
+    private readonly defaultPollTimeoutMs;
+    constructor(http: HttpClient, projectId: number, defaultPollTimeoutMs?: number);
+    /** The poll timeout this client applies when an `ingest()` caller doesn't
+     *  pass `pollTimeoutMs`. Mostly useful for tests / diagnostics. */
+    getDefaultPollTimeoutMs(): number;
+    /** Fetch a snapshot of the server-side conversion progress for a content
+     *  hash. Returns `null` if the server has no in-flight conversion (either
+     *  it's terminal already, or there's nothing to show). Cheap (a few-byte
+     *  JSON response off an in-memory map). */
+    progress(content_hash: string): Promise<IngestProgress | null>;
+    claim(content_hash: string, filename: string): Promise<ClaimOutcome>;
+    upload(filename: string, bytes: Uint8Array, opts?: {
+        signal?: AbortSignal;
+    }): Promise<UploadResult>;
+    ingest(filename: string, bytes: Uint8Array, opts?: IngestOptions): Promise<UploadResult>;
+}
+//# sourceMappingURL=documents.d.ts.map

package/dist/sub/documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../src/sub/documents.ts"],"names":[],"mappings":"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"}

package/dist/sub/documents.js

@@ -0,0 +1,329 @@
+// Document ingest sub-client. Mirrors the Rust akribes-sdk-rust
+// `DocumentsClient` surface (claim / upload / ingest), plus an `onPhase`
+// progress callback for browser UI.
+//
+// See `docs/superpowers/specs/2026-04-25-studio-documents-ingest-design.md`.
+import { AkribesHttpError } from '../errors';
+/** Translate `AkribesHttpError`s carrying the server's `conversion_failed`
+ *  envelope into a typed `DocumentConversionError`. Other HTTP errors are
+ *  re-thrown verbatim so callers can still inspect `status` / `body`. */
+function rethrowConversionFailure(e) {
+    if (e instanceof AkribesHttpError && e.errorType === 'conversion_failed') {
+        // serverMessage is the user-facing copy assembled by the server's
+        // `client_facing(reason)` helper. Pass it through unchanged.
+        throw new DocumentConversionError('', e.serverMessage ?? e.message, e.reason);
+    }
+    throw e;
+}
+/** Default poll budget for {@link DocumentsClient.ingest}, in milliseconds.
+ *
+ *  20 minutes. The previous 5 min default still surfaced
+ *  `IngestTimeoutError`s on perfectly healthy big-PDF conversions while the
+ *  server quietly kept working — that's a UX bug, not a hang signal. Real
+ *  hangs are caught by the server's own watchdogs (see
+ *  `wait_for_blob_ready`); the SDK timeout exists only as a final hard cap
+ *  so callers don't poll forever on a process leak. UIs are expected to
+ *  surface live progress via `onProgress` and offer a Cancel button rather
+ *  than waiting for this deadline.
+ *
+ *  Override via:
+ *  - per-ingest: {@link IngestOptions.pollTimeoutMs}
+ *  - per-client: `AkribesClientOptions.ingestPollTimeoutMs`
+ *  - process-wide: env var `AKRIBES_SDK_INGEST_TIMEOUT_SECS` (Node/Bun only).
+ */
+export const DEFAULT_INGEST_POLL_TIMEOUT_MS = 20 * 60 * 1000;
+/** Read `AKRIBES_SDK_INGEST_TIMEOUT_SECS` from the host's process env (Node/Bun
+ *  expose `process.env`; browser bundles don't and will skip this).
+ *  Returns `undefined` if unset, zero, or unparseable — the caller falls back
+ *  to the next-lower-precedence value. */
+export function ingestPollTimeoutMsFromEnv() {
+    // Browsers don't have `process`; guard so this file is tree-shake-safe.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const proc = globalThis.process;
+    const raw = proc?.env?.AKRIBES_SDK_INGEST_TIMEOUT_SECS;
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.floor(n) * 1000;
+}
+/** Thrown when the conversion pipeline fails. Two trigger paths:
+ *
+ *  1. The server returned a 4xx/5xx with `error_type: "conversion_failed"`
+ *     during claim/upload (e.g. the VLM rejected the file, pdfium couldn't
+ *     read it, the conversion service was down). `document_id` is empty
+ *     because no document was created.
+ *  2. The server returned 200 with `conversion_status: "failed"` from claim
+ *     (the bytes have a poisoned blob row that hasn't been reclaimed yet).
+ *
+ *  The `message` is server-supplied and user-facing — surface it directly in
+ *  the UI instead of swapping in a generic fallback. `reason` is a stable
+ *  machine-readable string for branching:
+ *  `service_unavailable`, `service_rejected`, `file_too_large`,
+ *  `invalid_file`, `extraction_failed`. */
+export class DocumentConversionError extends Error {
+    document_id;
+    reason;
+    constructor(document_id, message, reason) {
+        super(message);
+        this.name = 'DocumentConversionError';
+        this.document_id = document_id;
+        this.reason = reason;
+    }
+}
+/** Thrown when `ingest()` polls past its `pollTimeoutMs` deadline. */
+export class IngestTimeoutError extends Error {
+    document_id;
+    elapsed_ms;
+    constructor(message, document_id, elapsed_ms) {
+        super(message);
+        this.name = 'IngestTimeoutError';
+        this.document_id = document_id;
+        this.elapsed_ms = elapsed_ms;
+    }
+}
+/** Thrown for protocol-level problems: unknown `conversion_status` strings,
+ *  `crypto.subtle` unavailable, etc. Signals schema drift or missing browser
+ *  features — surfacing loudly is the point. */
+export class IngestProtocolError extends Error {
+    received_status;
+    constructor(message, received_status) {
+        super(message);
+        this.name = 'IngestProtocolError';
+        this.received_status = received_status;
+    }
+}
+/** Compute a hex-encoded SHA-256 digest of the given bytes. Throws
+ *  `IngestProtocolError` if `crypto.subtle` isn't available (insecure
+ *  context — e.g. plain HTTP deploy). */
+async function sha256Hex(bytes) {
+    if (typeof crypto === 'undefined' || !crypto.subtle) {
+        throw new IngestProtocolError('SHA-256 unavailable: ingest requires a secure context (HTTPS or localhost)');
+    }
+    // Cast: TypeScript 5.7+ narrows `Uint8Array<ArrayBufferLike>` which BufferSource
+    // excludes. Our bytes are always regular (non-shared) buffers, so the cast is safe.
+    const buf = await crypto.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(buf))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+/** Validate a `conversion_status` string from the wire. Throws
+ *  `IngestProtocolError` on `'unknown'` — schema drift signal. */
+function assertKnownStatus(s) {
+    if (s === 'unknown') {
+        throw new IngestProtocolError('received unknown conversion_status from server (schema drift)', 'unknown');
+    }
+}
+/** Throw `DocumentConversionError` if the server reports a `failed` status. */
+function ensureNotFailed(r) {
+    if (r.conversion_status === 'failed') {
+        throw new DocumentConversionError(r.document_id, `document ${r.document_id} conversion failed on the server — re-upload or call reconvert`);
+    }
+}
+export class DocumentsClient {
+    http;
+    projectId;
+    /** Resolved client-level default poll timeout. Per-call
+     *  {@link IngestOptions.pollTimeoutMs} still wins. */
+    defaultPollTimeoutMs;
+    constructor(http, projectId, defaultPollTimeoutMs) {
+        this.http = http;
+        this.projectId = projectId;
+        this.defaultPollTimeoutMs = defaultPollTimeoutMs ?? DEFAULT_INGEST_POLL_TIMEOUT_MS;
+    }
+    /** The poll timeout this client applies when an `ingest()` caller doesn't
+     *  pass `pollTimeoutMs`. Mostly useful for tests / diagnostics. */
+    getDefaultPollTimeoutMs() {
+        return this.defaultPollTimeoutMs;
+    }
+    /** Fetch a snapshot of the server-side conversion progress for a content
+     *  hash. Returns `null` if the server has no in-flight conversion (either
+     *  it's terminal already, or there's nothing to show). Cheap (a few-byte
+     *  JSON response off an in-memory map). */
+    async progress(content_hash) {
+        const url = `${this.http.getBaseUrl()}/projects/${this.projectId}/documents/by-hash/${content_hash}/progress`;
+        const res = await this.http.fetchOk(url);
+        const wire = (await res.json());
+        if (wire.state === 'idle')
+            return null;
+        return { done: wire.done_pages, total: wire.total_pages };
+    }
+    async claim(content_hash, filename) {
+        const url = `${this.http.getBaseUrl()}/projects/${this.projectId}/documents/claim`;
+        const res = await this.http.fetchOk(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ content_hash, filename }),
+        }).catch(rethrowConversionFailure);
+        const wire = await res.json();
+        if (wire.status === 'hit') {
+            return {
+                status: 'hit',
+                result: {
+                    document_id: wire.document_id,
+                    filename: wire.filename,
+                    content_hash: wire.content_hash,
+                    conversion_status: wire.conversion_status,
+                },
+            };
+        }
+        return { status: 'miss' };
+    }
+    async upload(filename, bytes, opts) {
+        const form = new FormData();
+        form.append('file', new Blob([bytes]), filename);
+        const url = `${this.http.getBaseUrl()}/projects/${this.projectId}/documents`;
+        // POST /documents blocks for the full server-side conversion. Bun
+        // enforces an internal 5-minute fetch timeout that AbortSignal cannot
+        // override; on dense documents the fetch will throw `TimeoutError` while
+        // the server keeps working. `ingest()` catches that and falls back to
+        // claim-polling, so we just propagate the error here.
+        const res = await this.http.fetchOk(url, {
+            method: 'POST',
+            body: form,
+            signal: opts?.signal,
+        }).catch(rethrowConversionFailure);
+        return (await res.json());
+    }
+    async ingest(filename, bytes, opts) {
+        const { signal, onPhase, onProgress, pollTimeoutMs = this.defaultPollTimeoutMs } = opts ?? {};
+        onPhase?.('claiming');
+        const hash = await sha256Hex(bytes);
+        const initial = await this.claim(hash, filename);
+        // Side-channel progress poller. Runs concurrently with the (blocking)
+        // upload fetch, hits the in-memory progress map endpoint every ~750 ms
+        // and pushes updates through `onProgress`. Stops as soon as `done`
+        // becomes 0 again (server cleared the entry → conversion finished) or
+        // the abort flag is set.
+        let progressPollerActive = false;
+        const stopProgressPoller = () => { progressPollerActive = false; };
+        const startProgressPoller = () => {
+            if (!onProgress || progressPollerActive)
+                return;
+            progressPollerActive = true;
+            void (async () => {
+                // Two distinct null cases:
+                //   1) Server hasn't created the entry yet (pdfium still parsing).
+                //      Keep polling — entry shows up once the page count is known.
+                //   2) Server cleared the entry (conversion finished). Stop.
+                // We only treat null as "finished" *after* we've seen a non-null
+                // snapshot at least once.
+                let everSawProgress = false;
+                while (progressPollerActive && !signal?.aborted) {
+                    try {
+                        const snap = await this.progress(hash);
+                        if (snap) {
+                            everSawProgress = true;
+                            onProgress(snap);
+                        }
+                        else if (everSawProgress) {
+                            break;
+                        }
+                    }
+                    catch {
+                        // Don't fail the upload because progress polling glitched.
+                    }
+                    await new Promise((r) => setTimeout(r, 750));
+                }
+            })();
+        };
+        let result;
+        if (initial.status === 'miss') {
+            onPhase?.('uploading');
+            startProgressPoller();
+            // The blocking upload connection can die before the server finishes
+            // converting for several distinct reasons, all of which mean
+            // "fetch is gone, bytes are still on the server, fall back to
+            // claim-polling so the conversion result can still be surfaced":
+            //
+            // 1. Bun's fetch enforces an internal 5-minute timeout that even
+            //    AbortSignal.timeout(longer) cannot extend. Surfaces as
+            //    `DOMException: TimeoutError`. (Server-side caller only.)
+            // 2. Browsers (Firefox in particular) drop the connection mid-
+            //    request when an idle keepalive elapses on a hop between
+            //    browser and aura-server (ISP NAT reaper, Traefik upstream
+            //    pool, OS conntrack). Firefox surfaces this as
+            //    `TypeError: NetworkError when attempting to fetch resource`,
+            //    Chrome as `TypeError: Failed to fetch`, Safari as
+            //    `TypeError: Load failed`. None of these are `TimeoutError`,
+            //    so a narrow timeout-only catch lets them propagate to the
+            //    UI as a misleading "upload failed" while the server is in
+            //    fact still busy converting.
+            //
+            // Detection: treat any `TypeError` from `fetch()` whose message
+            // matches the well-known network-failure phrases as recoverable.
+            // This is the same shape the WHATWG spec mandates fetch throw on
+            // network errors, so the heuristic is stable across browsers.
+            try {
+                result = await this.upload(filename, bytes, { signal });
+            }
+            catch (e) {
+                const isFetchTimeout = e?.name === 'TimeoutError' ||
+                    (e instanceof DOMException && /timed? *out/i.test(e.message));
+                const isFetchNetworkError = e instanceof TypeError &&
+                    /network ?error|failed to fetch|load failed/i.test(e?.message ?? '');
+                if (!isFetchTimeout && !isFetchNetworkError)
+                    throw e;
+                // Switch to converting phase and let the existing poll loop below take
+                // over by simulating a Hit-converting initial state.
+                onPhase?.('converting');
+                result = {
+                    document_id: '',
+                    filename,
+                    content_hash: hash,
+                    conversion_status: 'converting',
+                };
+            }
+        }
+        else {
+            // Hit path — may be terminal (return immediately) or non-terminal (poll).
+            assertKnownStatus(initial.result.conversion_status);
+            ensureNotFailed(initial.result);
+            result = initial.result;
+        }
+        // Poll until terminal. Reached when:
+        //   - Hit returned a non-terminal status (concurrent uploader still
+        //     processing), or
+        //   - Miss + upload's fetch died at Bun's 5-min timeout (we converted to
+        //     a synthetic converting state above).
+        if (result.conversion_status === 'converting' || result.conversion_status === 'pending') {
+            onPhase?.('converting');
+            // Hit-converting branch hasn't started the poller yet.
+            startProgressPoller();
+            const startedAt = Date.now();
+            const deadline = startedAt + pollTimeoutMs;
+            let backoffMs = 250;
+            while (result.conversion_status === 'converting' || result.conversion_status === 'pending') {
+                if (signal?.aborted) {
+                    throw new DOMException('Aborted', 'AbortError');
+                }
+                if (Date.now() >= deadline) {
+                    const elapsed = Date.now() - startedAt;
+                    throw new IngestTimeoutError('Document conversion did not finish within 20 minutes. The server is still working in the background. Refresh the page in a few minutes to check, or contact support.', result.document_id, elapsed);
+                }
+                await new Promise((resolve) => setTimeout(resolve, backoffMs));
+                backoffMs = Math.min(backoffMs * 2, 2000);
+                const pollOutcome = await this.claim(hash, filename);
+                if (pollOutcome.status === 'miss') {
+                    // GC reclaimed the blob mid-poll; re-upload to repopulate.
+                    onPhase?.('uploading');
+                    const uploaded = await this.upload(filename, bytes, { signal });
+                    assertKnownStatus(uploaded.conversion_status);
+                    ensureNotFailed(uploaded);
+                    onPhase?.('ready');
+                    return uploaded;
+                }
+                assertKnownStatus(pollOutcome.result.conversion_status);
+                ensureNotFailed(pollOutcome.result);
+                result = pollOutcome.result;
+            }
+        }
+        assertKnownStatus(result.conversion_status);
+        ensureNotFailed(result);
+        stopProgressPoller();
+        onPhase?.('ready');
+        return result;
+    }
+}
+//# sourceMappingURL=documents.js.map