nenavi 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -30,12 +30,14 @@ Every supported operation of the hosted API has a method. Three helpers cover th
 const answer = await client.ingest({ content: 'Jo is learning Portuguese.', user_id: 'user-1' });
 const status = await client.events.waitForExtraction(answer.event_id, { timeout: 300_000 }); // complete or failed
 const run = await client.reingest.run({ user_id: 'user-1' }); // starts a run and polls it every 5 seconds
-for await (const node of client.nodes.scanAll({ user_id: 'user-1' })) console.log(node.id); // every page
+for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+  console.log(node.id); // every page, 1 000 nodes each
+}
 ```
 
 `reingest.preview()` estimates a re-ingest without starting one; only `reingest.start()` and `reingest.run()` start a real run. A run takes at most `limit` memories, so a `complete` run can leave some for later: while `run.remaining` is above 0, call `reingest.run()` again with the same parameters to continue it.
 
-The helpers' `timeout` and `interval` are in milliseconds, and aborting their `signal` stops them and any pending poll. A helper that runs out of time throws `WaitTimeoutError` with the last status as `lastStatus`; `timeout: 0` polls once, and `reingest.run()` still starts the run. Every poll and every scan page counts against the key's request rate limit like any other call, so for a large scan pass a larger `limit` (up to 1 000 nodes a page), and run background jobs with a longer `interval` or their own key. The helpers are on the client only, not on `withRawResponse`.
+The helpers' `timeout` and `interval` are in milliseconds, and aborting their `signal` stops them and any pending poll. A helper that runs out of time throws `WaitTimeoutError` with the last status as `lastStatus`, and a poll that fails inside `reingest.run()` throws its own error with `lastStatus` set the same way, so the run's `run_id` is not lost; `timeout: 0` polls once, and `reingest.run()` still starts the run. Every poll and every scan page counts against the key's request rate limit (60 a minute by default) like any other call, and `store()`, `ingest()` and `retrieve()` are never retried on a `429`. So for a large scan pass a larger `limit` (up to 1 000 nodes a page), and run background jobs with a longer `interval` or their own key. The helpers are on the client only, not on `withRawResponse`.
 
 ## Options
 
@@ -55,7 +57,7 @@ Request and response fields keep the API's snake_case names (`user_id`, `event_i
 
 Every error the SDK throws is a `NenaviError`, and every class works with `instanceof`: `APIError` and its subclasses (`AuthenticationError`, `NotFoundError`, `RateLimitError`, `QuotaExceededError`, `ServiceUnavailableError` and the others) carry `status`, `reasonCode`, `detail` and `requestId`. `APIConnectionError` and `APITimeoutError` mean no response arrived. `ResponseValidationError` means a `2xx` answer had a body the SDK could not read as the operation's type: the call may have taken effect, so read its `body` (for example the `event_id` of a `store()`) and `requestId` before calling again. `body` can hold stored memory text, and `console.error(error)` or `JSON.stringify(error)` prints it: log the message and `requestId` instead.
 
-Only `GET` methods and `ingestFast()` retry by themselves, on a `429 rate_limited` (after `Retry-After`), a `503 database_unavailable` or `lease_unavailable`, or a connection error. `store()`, `ingest()` and `retrieve()` never retry: a retried store stores the text again and counts twice against the monthly limits. `ingestFast()` sends one `Idempotency-Key` on every retry of a call; to retry it by hand, pass the error's `idempotencyKey`.
+Only `GET` methods and `ingestFast()` retry by themselves, on a `429 rate_limited` (after `Retry-After`), a `503 database_unavailable` or `lease_unavailable`, or a connection error. `store()`, `ingest()` and `retrieve()` never retry: a retried store stores the text again and counts twice against the monthly limits. `ingestFast()` sends one `Idempotency-Key` on every retry of a call. A timeout is never retried, so to retry it by hand, pass the error's `idempotencyKey`. If you wrap `ingestFast()` in your own retry loop, make one key before the first attempt and pass it on every attempt: a call without a key gets a new one, and the service stores and meters the batch again.
 
 ## Development
 

package/dist/cjs/client.d.ts

@@ -12,9 +12,11 @@ declare class Resource<Raw extends boolean> {
 /** A helper's options (sdks/CONTRACT.md, Helpers). */
 export interface HelperOptions {
     /**
-     * Milliseconds after which the helper stops waiting: it polls no more once they run
-     * out. A poll already sent finishes first, with its own per-attempt timeout and retries.
-     * 0 polls once (`run()` still starts the run); `Infinity` waits without a limit.
+     * Milliseconds after which the helper stops: a deadline. Each poll's attempt gets no
+     * more than the time left (at least 1 000 milliseconds), and a retry that would wait
+     * past it is not made; a poll the deadline stops this way throws `WaitTimeoutError`
+     * too, with the poll's error as its `cause`. 0 polls once (`run()` still starts the
+     * run, with the client's own timeout); `Infinity` waits without a limit.
      */
     timeout?: number;
     /** Milliseconds between polls. */
@@ -185,12 +187,14 @@ export declare class Learning<Raw extends boolean = false> extends Resource<Raw>
 /** `client.events`: the event routes and `waitForExtraction()`. */
 export declare class EventsWithHelpers extends Events<false> {
     /**
-     * Poll the event's extraction status until it is `complete` or `failed`.
+     * Poll the event's extraction status until it is no longer `pending` or `running`.
      *
      * Polls `GET /v1/events/{event_id}/extraction-status` at once and then every
-     * `interval` milliseconds (2 000), and returns the last status; a `failed` status is
-     * returned, not thrown. When `timeout` milliseconds (300 000) run out first, throws
-     * `WaitTimeoutError` with the last status as `lastStatus`. Aborting `signal` stops
+     * `interval` milliseconds (2 000), and returns the first status that is not `pending`
+     * or `running`: `complete`, `failed` (returned, not thrown), or a status this SDK does
+     * not know yet. When `timeout` milliseconds (300 000) run out first, throws
+     * `WaitTimeoutError` with the last status as `lastStatus`; `timeout` is a deadline that
+     * also bounds each poll and its retries (see `HelperOptions`). Aborting `signal` stops
      * the helper and any pending poll or retry. Each poll is an ordinary call, with the
      * client's retries and errors, and counts against the key's request rate limit like any
      * other call, so many waits at once can slow the key's other calls. A job can stay
@@ -211,24 +215,30 @@ export declare class NodesWithHelpers extends Nodes<false> {
      * `NenaviError`, so a scan never ends early without saying so.
      *
      * @example
-     * for await (const node of client.nodes.scanAll({ user_id: 'user-1' })) console.log(node.id);
+     * for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+     *   console.log(node.id);
+     * }
      */
     scanAll(params?: NodesScanParams, options?: RequestOptions): AsyncGenerator<NodeResponse, void, undefined>;
 }
 /** `client.reingest`: the re-ingest routes and `run()`. */
 export declare class ReingestWithHelpers extends Reingest<false> {
     /**
-     * Start a re-ingest run and poll it until its `state` is `complete` or `failed`.
+     * Start a re-ingest run and poll it until its `state` is final.
      *
      * Sends `start()` (`dry_run: false`), then polls `get()` every `interval` milliseconds
-     * (5 000) and returns the last status; a `failed` run is returned, not thrown. When
-     * nothing needs re-deriving, the service's `200` answer is returned as it is. A `409`
-     * `reingest_running` throws `ConflictError`. When `timeout` milliseconds (3 600 000)
-     * run out first, throws `WaitTimeoutError` with the last status as `lastStatus`; the
-     * run itself goes on. The timeout never prevents the start. Aborting `signal` stops the
-     * helper and any pending poll, not the run. A failed poll throws that call's error while
-     * the run goes on; to keep the run's id across such failures, call `start()` and poll
-     * `get()` yourself.
+     * (5 000) and returns the first status whose `state` is not `pending` or `running`:
+     * `complete`, `failed` (returned, not thrown), or a state this SDK does not know yet.
+     * When nothing needs re-deriving, the service's `200` answer is returned as it is. A
+     * `409` `reingest_running` throws `ConflictError`. When `timeout` milliseconds
+     * (3 600 000) run out first, throws `WaitTimeoutError` with the last status as
+     * `lastStatus`; the run itself goes on. `timeout` is a deadline that also bounds each
+     * poll and its retries (see `HelperOptions`); it never prevents or cuts short the start,
+     * which has the client's own timeout. Aborting `signal` stops the helper and any pending
+     * poll, not the run. A poll that fails throws that call's error while the run goes on,
+     * with the last status read before it as `lastStatus`: its `run_id` lets the caller go
+     * on polling with `get()` instead of calling `run()` again, which throws `ConflictError`
+     * (`reingest_running`) until the run ends.
      *
      * A run takes at most `limit` memories, so a `complete` run can leave some for later
      * (`remaining` above 0): calling `run()` again with the same parameters continues it.

package/dist/cjs/client.js

@@ -26,8 +26,24 @@ class Resource {
         return this._core.request(call, this._raw);
     }
 }
-/** The states after which a helper stops polling. */
-const FINISHED = new Set(['complete', 'failed']);
+/**
+ * The states a helper keeps polling through. Any other state, one the service adds later
+ * included, is final and returned.
+ */
+const WORKING = new Set(['pending', 'running']);
+/** `GET /v1/events/{event_id}/extraction-status`, for the method and its helper. */
+function extractionStatusCall(eventId, options) {
+    return {
+        method: 'GET',
+        path: `/v1/events/${(0, core_js_1.pathParam)(eventId)}/extraction-status`,
+        retrySafe: true,
+        options,
+    };
+}
+/** `GET /v1/reingest/{run_id}`, for the method and its helper. */
+function reingestGetCall(runId, options) {
+    return { method: 'GET', path: `/v1/reingest/${(0, core_js_1.pathParam)(runId)}`, retrySafe: true, options };
+}
 /** A caller's `Idempotency-Key`, or null; an empty value counts as not given. */
 function callerKey(options) {
     const key = (0, core_js_1.ownProperties)(options).idempotencyKey;
@@ -73,12 +89,7 @@ class Events extends Resource {
     }
     /** `GET /v1/events/{event_id}/extraction-status`. */
     extractionStatus(eventId, options) {
-        return this._request(() => ({
-            method: 'GET',
-            path: `/v1/events/${(0, core_js_1.pathParam)(eventId)}/extraction-status`,
-            retrySafe: true,
-            options,
-        }));
+        return this._request(() => extractionStatusCall(eventId, options));
     }
     /** `POST /v1/events/{event_id}/retry-extraction`. Not retried automatically. */
     retryExtraction(eventId, params, options) {
@@ -244,12 +255,7 @@ class Reingest extends Resource {
     }
     /** `GET /v1/reingest/{run_id}`: the run's state, counts and usage. */
     get(runId, options) {
-        return this._request(() => ({
-            method: 'GET',
-            path: `/v1/reingest/${(0, core_js_1.pathParam)(runId)}`,
-            retrySafe: true,
-            options,
-        }));
+        return this._request(() => reingestGetCall(runId, options));
     }
 }
 exports.Reingest = Reingest;
@@ -594,12 +600,14 @@ exports.Learning = Learning;
 /** `client.events`: the event routes and `waitForExtraction()`. */
 class EventsWithHelpers extends Events {
     /**
-     * Poll the event's extraction status until it is `complete` or `failed`.
+     * Poll the event's extraction status until it is no longer `pending` or `running`.
      *
      * Polls `GET /v1/events/{event_id}/extraction-status` at once and then every
-     * `interval` milliseconds (2 000), and returns the last status; a `failed` status is
-     * returned, not thrown. When `timeout` milliseconds (300 000) run out first, throws
-     * `WaitTimeoutError` with the last status as `lastStatus`. Aborting `signal` stops
+     * `interval` milliseconds (2 000), and returns the first status that is not `pending`
+     * or `running`: `complete`, `failed` (returned, not thrown), or a status this SDK does
+     * not know yet. When `timeout` milliseconds (300 000) run out first, throws
+     * `WaitTimeoutError` with the last status as `lastStatus`; `timeout` is a deadline that
+     * also bounds each poll and its retries (see `HelperOptions`). Aborting `signal` stops
      * the helper and any pending poll or retry. Each poll is an ordinary call, with the
      * client's retries and errors, and counts against the key's request rate limit like any
      * other call, so many waits at once can slow the key's other calls. A job can stay
@@ -609,10 +617,26 @@ class EventsWithHelpers extends Events {
         const { timeout = 300_000, interval = 2_000, signal = null } = (0, core_js_1.ownProperties)(options);
         const core = this._core;
         const deadline = (0, core_js_1.helperDeadline)(core.now(), timeout, interval);
+        let lastStatus = null;
         for (;;) {
-            const status = await this.extractionStatus(eventId, { signal });
-            if (FINISHED.has(status.status))
+            let status;
+            try {
+                status = await this._request(() => ({
+                    ...extractionStatusCall(eventId, { signal }),
+                    deadline,
+                }));
+            }
+            catch (error) {
+                // Only a poll the deadline stopped throws WaitTimeoutError; its own error is the cause.
+                if (!(error instanceof errors_js_1.WaitTimeoutError))
+                    throw error;
+                const last = lastStatus === null ? 'none' : JSON.stringify(lastStatus.status);
+                throw (0, core_js_1.withCause)(new errors_js_1.WaitTimeoutError(`The extraction did not finish within ${timeout} ms: ${error.message}. The last ` +
+                    `status read was ${last}.`, { lastStatus }), error.cause);
+            }
+            if (!WORKING.has(status.status))
                 return status;
+            lastStatus = status;
             const wait = (0, core_js_1.helperWait)(core.now(), deadline, interval);
             if (wait === null) {
                 throw new errors_js_1.WaitTimeoutError(`The extraction did not finish within ${timeout} ms; its last status was ` +
@@ -636,7 +660,9 @@ class NodesWithHelpers extends Nodes {
      * `NenaviError`, so a scan never ends early without saying so.
      *
      * @example
-     * for await (const node of client.nodes.scanAll({ user_id: 'user-1' })) console.log(node.id);
+     * for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+     *   console.log(node.id);
+     * }
      */
     async *scanAll(params, options) {
         const given = (0, core_js_1.ownProperties)(params);
@@ -663,17 +689,21 @@ exports.NodesWithHelpers = NodesWithHelpers;
 /** `client.reingest`: the re-ingest routes and `run()`. */
 class ReingestWithHelpers extends Reingest {
     /**
-     * Start a re-ingest run and poll it until its `state` is `complete` or `failed`.
+     * Start a re-ingest run and poll it until its `state` is final.
      *
      * Sends `start()` (`dry_run: false`), then polls `get()` every `interval` milliseconds
-     * (5 000) and returns the last status; a `failed` run is returned, not thrown. When
-     * nothing needs re-deriving, the service's `200` answer is returned as it is. A `409`
-     * `reingest_running` throws `ConflictError`. When `timeout` milliseconds (3 600 000)
-     * run out first, throws `WaitTimeoutError` with the last status as `lastStatus`; the
-     * run itself goes on. The timeout never prevents the start. Aborting `signal` stops the
-     * helper and any pending poll, not the run. A failed poll throws that call's error while
-     * the run goes on; to keep the run's id across such failures, call `start()` and poll
-     * `get()` yourself.
+     * (5 000) and returns the first status whose `state` is not `pending` or `running`:
+     * `complete`, `failed` (returned, not thrown), or a state this SDK does not know yet.
+     * When nothing needs re-deriving, the service's `200` answer is returned as it is. A
+     * `409` `reingest_running` throws `ConflictError`. When `timeout` milliseconds
+     * (3 600 000) run out first, throws `WaitTimeoutError` with the last status as
+     * `lastStatus`; the run itself goes on. `timeout` is a deadline that also bounds each
+     * poll and its retries (see `HelperOptions`); it never prevents or cuts short the start,
+     * which has the client's own timeout. Aborting `signal` stops the helper and any pending
+     * poll, not the run. A poll that fails throws that call's error while the run goes on,
+     * with the last status read before it as `lastStatus`: its `run_id` lets the caller go
+     * on polling with `get()` instead of calling `run()` again, which throws `ConflictError`
+     * (`reingest_running`) until the run ends.
      *
      * A run takes at most `limit` memories, so a `complete` run can leave some for later
      * (`remaining` above 0): calling `run()` again with the same parameters continues it.
@@ -683,14 +713,32 @@ class ReingestWithHelpers extends Reingest {
         const core = this._core;
         const deadline = (0, core_js_1.helperDeadline)(core.now(), timeout, interval);
         let status = await this.start(params, { signal });
-        while (status.run_id !== null && status.run_id !== undefined && !FINISHED.has(status.state)) {
+        while (status.run_id !== null && status.run_id !== undefined && WORKING.has(status.state)) {
             const wait = (0, core_js_1.helperWait)(core.now(), deadline, interval);
             if (wait === null) {
                 throw new errors_js_1.WaitTimeoutError(`The re-ingest run ${status.run_id} did not finish within ${timeout} ms; its ` +
                     `last state was ${JSON.stringify(status.state)}.`, { lastStatus: status });
             }
             await core.sleep(wait, signal);
-            status = await this.get(status.run_id, { signal });
+            const runId = status.run_id;
+            try {
+                status = await this._request(() => ({
+                    ...reingestGetCall(runId, { signal }),
+                    deadline,
+                }));
+            }
+            catch (error) {
+                // A poll the deadline stopped throws WaitTimeoutError; its own error is the cause.
+                if (error instanceof errors_js_1.WaitTimeoutError) {
+                    throw (0, core_js_1.withCause)(new errors_js_1.WaitTimeoutError(`The re-ingest run ${runId} did not finish within ${timeout} ms: ` +
+                        `${error.message}. Its last state was ${JSON.stringify(status.state)}.`, { lastStatus: status }), error.cause);
+                }
+                // The run goes on; without its id the caller could only call run() again, which
+                // the service refuses with 409 until the run ends. An abort keeps its own reason.
+                if (error instanceof errors_js_1.NenaviError && !signal?.aborted)
+                    error.lastStatus = status;
+                throw error;
+            }
         }
         return status;
     }

package/dist/cjs/core.d.ts

@@ -1,3 +1,4 @@
+import { NenaviError } from './errors.js';
 /** The `fetch` the SDK calls: the runtime's own, or one the caller passes. */
 export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
 export interface ClientOptions {
@@ -46,6 +47,11 @@ export interface Call {
     options?: RequestOptions | undefined;
     /** The JSON type of the answer: an object (the default), an array, or an object or null. */
     answer?: 'object' | 'array' | 'nullable';
+    /**
+     * A helper's deadline on `Core.now`: it caps each attempt's timeout and stops a retry
+     * whose wait would end past it. Unset for an ordinary call.
+     */
+    deadline?: number;
 }
 /** Encode one path parameter, so a value cannot add or change path segments. */
 export declare function pathParam(value: string): string;
@@ -57,6 +63,8 @@ export declare function helperDeadline(now: number, timeout: number, interval: n
 export declare function helperWait(now: number, deadline: number, interval: number): number | null;
 /** Wait `ms` milliseconds, or reject with the signal's reason when it is aborted first. */
 export declare function sleep(ms: number, signal?: AbortSignal | null): Promise<void>;
+/** Set `cause` as the `Error` constructor does: an own property that is not enumerable. */
+export declare function withCause<E extends Error>(error: E, cause: NenaviError): E;
 /** Holds the configuration and sends the calls. The key is a private field. */
 export declare class Core {
     #private;

package/dist/cjs/core.js

@@ -10,6 +10,7 @@ exports.ownProperties = ownProperties;
 exports.helperDeadline = helperDeadline;
 exports.helperWait = helperWait;
 exports.sleep = sleep;
+exports.withCause = withCause;
 const errors_js_1 = require("./errors.js");
 const version_js_1 = require("./version.js");
 const DEFAULT_BASE_URL = 'https://api.prismemory.com';
@@ -20,6 +21,11 @@ const DEFAULT_MAX_RETRIES = 2;
 const MAX_RETRY_AFTER = 60;
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const RETRYABLE_503 = new Set(['database_unavailable', 'lease_unavailable']);
+/**
+ * Milliseconds: the shortest attempt timeout a helper's poll gets near its deadline, so the
+ * poll at the deadline (and the one poll of `timeout: 0`) can still be answered.
+ */
+const MIN_POLL_TIMEOUT = 1_000;
 /** The longest delay setTimeout keeps: a longer one fires at once. */
 const MAX_TIMEOUT = 2_147_483_647;
 // Visible ASCII only: what an HTTP header can carry without encoding. This is not a check
@@ -201,6 +207,21 @@ function retryWait(error, retryNumber) {
     }
     return null;
 }
+/**
+ * The error for a helper's poll that its deadline stopped; the helper adds its status. The
+ * poll's own error becomes its `cause`.
+ */
+function deadlineError(error, retrySkipped) {
+    const reason = retrySkipped
+        ? `the last poll threw ${error.name}, and its retry would have waited past the deadline`
+        : `the last poll got no answer before the deadline (${error.name})`;
+    return withCause(new errors_js_1.WaitTimeoutError(reason, { idempotencyKey: error.idempotencyKey }), error);
+}
+/** Set `cause` as the `Error` constructor does: an own property that is not enumerable. */
+function withCause(error, cause) {
+    Object.defineProperty(error, 'cause', { value: cause, writable: true, configurable: true });
+    return error;
+}
 /** The name, and the system error code when there is one, of what fetch threw. */
 function failureName(error) {
     const raw = error instanceof Error ? error.name : typeof error;
@@ -264,7 +285,8 @@ class Core {
         if (auth && this.#apiKey === null) {
             throw new errors_js_1.ConfigurationError('No API key: pass apiKey or set NENAVI_API_KEY. Only health() works without a key.');
         }
-        const timeout = checkTimeout(options.timeout ?? this.timeout);
+        const callTimeout = checkTimeout(options.timeout ?? this.timeout);
+        const deadline = call.deadline ?? null;
         const maxRetries = checkMaxRetries(options.maxRetries ?? this.maxRetries);
         const idempotencyKey = call.idempotencyKey ?? null;
         const headers = {
@@ -288,6 +310,10 @@ class Core {
         const url = `${this.baseURL}${call.path}${queryString(call.query)}`;
         let retries = 0;
         for (;;) {
+            // A helper's poll gets only the time left.
+            const left = deadline === null ? Infinity : Math.max(deadline - this.now(), MIN_POLL_TIMEOUT);
+            const shortened = left < callTimeout;
+            const timeout = shortened ? left : callTimeout;
             const attempt = await this.#send(url, call.method, headers, body, timeout, signal, idempotencyKey);
             if (attempt.response !== undefined) {
                 return this.#result(attempt.response, attempt.text, raw, idempotencyKey, call.answer ?? 'object');
@@ -295,11 +321,17 @@ class Core {
             if (call.retrySafe && retries < maxRetries) {
                 const wait = retryWait(attempt.error, retries + 1);
                 if (wait !== null) {
-                    retries += 1;
-                    await this.sleep(wait, signal);
-                    continue;
+                    if (deadline === null || this.now() + wait < deadline) {
+                        retries += 1;
+                        await this.sleep(wait, signal);
+                        continue;
+                    }
+                    throw deadlineError(attempt.error, true);
                 }
             }
+            if (shortened && attempt.error instanceof errors_js_1.APITimeoutError) {
+                throw deadlineError(attempt.error, false);
+            }
             throw attempt.error;
         }
     }

package/dist/cjs/errors.d.ts

@@ -1,9 +1,21 @@
 /** Base class of every error the SDK throws. */
 export declare class NenaviError extends Error {
+    /**
+     * `value instanceof` this class, also for an error from another copy of the package.
+     * Installed below with `Object.defineProperty`.
+     */
+    static [Symbol.hasInstance]: <T>(this: abstract new (...args: never[]) => T, value: unknown) => value is T;
     /** The `Idempotency-Key` the call sent, or null when it sent none. */
     idempotencyKey: string | null;
+    /**
+     * The last status a helper read before it threw: on `WaitTimeoutError`, and on the
+     * error of a poll that failed inside `reingest.run()`, where it holds the run's
+     * `run_id`. Null on other errors.
+     */
+    lastStatus: unknown;
     constructor(message: string, options?: {
         idempotencyKey?: string | null;
+        lastStatus?: unknown;
     });
 }
 /** No key for an operation that needs one, or an invalid option. */
@@ -11,12 +23,6 @@ export declare class ConfigurationError extends NenaviError {
 }
 /** A helper ran out of time before the work it waited for finished. */
 export declare class WaitTimeoutError extends NenaviError {
-    /** The last status the helper read. */
-    lastStatus: unknown;
-    constructor(message: string, options?: {
-        lastStatus?: unknown;
-        idempotencyKey?: string | null;
-    });
 }
 export interface ResponseValidationErrorOptions {
     status: number;

package/dist/cjs/errors.js

@@ -4,32 +4,79 @@
 // An error holds plain values only: the status, a copy of the response headers and the
 // parsed body. It never holds a Request, a Response or the error fetch threw, so the
 // `Authorization` header cannot reach a message, `util.inspect` or `JSON.stringify`.
+//
+// The package ships an ES module build and a CommonJS build, and a process that loads
+// both holds two copies of every class here. So that `instanceof` still works across the
+// copies, each class's prototype carries its name under a key in the global symbol
+// registry, and `instanceof` falls back to matching that name along the prototype chain.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DETAIL_TEXT_LIMIT = exports.ServiceUnavailableError = exports.InternalServerError = exports.QuotaExceededError = exports.RateLimitError = exports.UnprocessableEntityError = exports.PayloadTooLargeError = exports.ConflictError = exports.NotFoundError = exports.PermissionDeniedError = exports.AuthenticationError = exports.BadRequestError = exports.APIError = exports.APITimeoutError = exports.APIConnectionError = exports.ResponseValidationError = exports.WaitTimeoutError = exports.ConfigurationError = exports.NenaviError = void 0;
 exports.parseRetryAfter = parseRetryAfter;
 exports.errorFromResponse = errorFromResponse;
+/**
+ * The key, shared by every copy of the package, under which a prototype names its class.
+ *
+ * Copies of different versions match each other by this key and the class name alone, so
+ * the key is a contract between versions. A release that changes an error class's fields
+ * incompatibly must change the key (for example to `nenavi.error.class.v2`), so that its
+ * errors stop matching older copies' classes instead of narrowing to the old shape.
+ */
+const CLASS_NAME = Symbol.for('nenavi.error.class');
 /** Base class of every error the SDK throws. */
 class NenaviError extends Error {
     /** The `Idempotency-Key` the call sent, or null when it sent none. */
     idempotencyKey;
+    /**
+     * The last status a helper read before it threw: on `WaitTimeoutError`, and on the
+     * error of a poll that failed inside `reingest.run()`, where it holds the run's
+     * `run_id`. Null on other errors.
+     */
+    lastStatus;
     constructor(message, options = {}) {
         super(message);
         this.idempotencyKey = options.idempotencyKey ?? null;
+        this.lastStatus = options.lastStatus ?? null;
     }
 }
 exports.NenaviError = NenaviError;
+// The ordinary check comes first. Failing that, a class of this package matches a value
+// whose prototype chain holds a prototype marked with the same class name, as the other
+// copy's classes are. A subclass written outside the package keeps the ordinary check.
+//
+// This is defined as a property rather than written as a static method, because a loose
+// class transform in a consumer's build turns a static method into an assignment, and
+// assigning over the read-only `Function.prototype[Symbol.hasInstance]` throws.
+Object.defineProperty(NenaviError, Symbol.hasInstance, {
+    value: function hasInstance(value) {
+        if (Function.prototype[Symbol.hasInstance].call(this, value))
+            return true;
+        if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+            return false;
+        }
+        const prototype = this.prototype;
+        if (typeof prototype !== 'object' || prototype === null)
+            return false;
+        if (!Object.hasOwn(prototype, CLASS_NAME))
+            return false;
+        const name = prototype[CLASS_NAME];
+        for (let link = Object.getPrototypeOf(value); link !== null; link = Object.getPrototypeOf(link)) {
+            if (Object.hasOwn(link, CLASS_NAME) &&
+                link[CLASS_NAME] === name) {
+                return true;
+            }
+        }
+        return false;
+    },
+    writable: true,
+    enumerable: false,
+    configurable: true,
+});
 /** No key for an operation that needs one, or an invalid option. */
 class ConfigurationError extends NenaviError {
 }
 exports.ConfigurationError = ConfigurationError;
 /** A helper ran out of time before the work it waited for finished. */
 class WaitTimeoutError extends NenaviError {
-    /** The last status the helper read. */
-    lastStatus;
-    constructor(message, options = {}) {
-        super(message, options);
-        this.lastStatus = options.lastStatus ?? null;
-    }
 }
 exports.WaitTimeoutError = WaitTimeoutError;
 /**
@@ -140,7 +187,8 @@ class ServiceUnavailableError extends APIError {
 }
 exports.ServiceUnavailableError = ServiceUnavailableError;
 // Each class's name, written out so that `error.name` survives a minifier that renames
-// classes. It sits on the prototype, so it is not an own property of an error.
+// classes. It sits on the prototype, so it is not an own property of an error. The same
+// name marks the prototype under CLASS_NAME for the cross-copy `instanceof` above.
 const NAMES = [
     [NenaviError, 'NenaviError'],
     [ConfigurationError, 'ConfigurationError'],
@@ -168,6 +216,12 @@ for (const [ErrorClass, name] of NAMES) {
         enumerable: false,
         configurable: true,
     });
+    Object.defineProperty(ErrorClass.prototype, CLASS_NAME, {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: false,
+    });
 }
 const BY_STATUS = {
     400: BadRequestError,

package/dist/cjs/version.d.ts

@@ -1,2 +1,2 @@
 /** The SDK's version, sent in the `User-Agent` header. test/client.test.ts keeps it equal to package.json. */
-export declare const VERSION = "0.1.0-alpha.1";
+export declare const VERSION = "0.1.0-alpha.2";

package/dist/cjs/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 /** The SDK's version, sent in the `User-Agent` header. test/client.test.ts keeps it equal to package.json. */
-exports.VERSION = '0.1.0-alpha.1';
+exports.VERSION = '0.1.0-alpha.2';

package/dist/esm/client.d.ts

@@ -12,9 +12,11 @@ declare class Resource<Raw extends boolean> {
 /** A helper's options (sdks/CONTRACT.md, Helpers). */
 export interface HelperOptions {
     /**
-     * Milliseconds after which the helper stops waiting: it polls no more once they run
-     * out. A poll already sent finishes first, with its own per-attempt timeout and retries.
-     * 0 polls once (`run()` still starts the run); `Infinity` waits without a limit.
+     * Milliseconds after which the helper stops: a deadline. Each poll's attempt gets no
+     * more than the time left (at least 1 000 milliseconds), and a retry that would wait
+     * past it is not made; a poll the deadline stops this way throws `WaitTimeoutError`
+     * too, with the poll's error as its `cause`. 0 polls once (`run()` still starts the
+     * run, with the client's own timeout); `Infinity` waits without a limit.
      */
     timeout?: number;
     /** Milliseconds between polls. */
@@ -185,12 +187,14 @@ export declare class Learning<Raw extends boolean = false> extends Resource<Raw>
 /** `client.events`: the event routes and `waitForExtraction()`. */
 export declare class EventsWithHelpers extends Events<false> {
     /**
-     * Poll the event's extraction status until it is `complete` or `failed`.
+     * Poll the event's extraction status until it is no longer `pending` or `running`.
      *
      * Polls `GET /v1/events/{event_id}/extraction-status` at once and then every
-     * `interval` milliseconds (2 000), and returns the last status; a `failed` status is
-     * returned, not thrown. When `timeout` milliseconds (300 000) run out first, throws
-     * `WaitTimeoutError` with the last status as `lastStatus`. Aborting `signal` stops
+     * `interval` milliseconds (2 000), and returns the first status that is not `pending`
+     * or `running`: `complete`, `failed` (returned, not thrown), or a status this SDK does
+     * not know yet. When `timeout` milliseconds (300 000) run out first, throws
+     * `WaitTimeoutError` with the last status as `lastStatus`; `timeout` is a deadline that
+     * also bounds each poll and its retries (see `HelperOptions`). Aborting `signal` stops
      * the helper and any pending poll or retry. Each poll is an ordinary call, with the
      * client's retries and errors, and counts against the key's request rate limit like any
      * other call, so many waits at once can slow the key's other calls. A job can stay
@@ -211,24 +215,30 @@ export declare class NodesWithHelpers extends Nodes<false> {
      * `NenaviError`, so a scan never ends early without saying so.
      *
      * @example
-     * for await (const node of client.nodes.scanAll({ user_id: 'user-1' })) console.log(node.id);
+     * for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+     *   console.log(node.id);
+     * }
      */
     scanAll(params?: NodesScanParams, options?: RequestOptions): AsyncGenerator<NodeResponse, void, undefined>;
 }
 /** `client.reingest`: the re-ingest routes and `run()`. */
 export declare class ReingestWithHelpers extends Reingest<false> {
     /**
-     * Start a re-ingest run and poll it until its `state` is `complete` or `failed`.
+     * Start a re-ingest run and poll it until its `state` is final.
      *
      * Sends `start()` (`dry_run: false`), then polls `get()` every `interval` milliseconds
-     * (5 000) and returns the last status; a `failed` run is returned, not thrown. When
-     * nothing needs re-deriving, the service's `200` answer is returned as it is. A `409`
-     * `reingest_running` throws `ConflictError`. When `timeout` milliseconds (3 600 000)
-     * run out first, throws `WaitTimeoutError` with the last status as `lastStatus`; the
-     * run itself goes on. The timeout never prevents the start. Aborting `signal` stops the
-     * helper and any pending poll, not the run. A failed poll throws that call's error while
-     * the run goes on; to keep the run's id across such failures, call `start()` and poll
-     * `get()` yourself.
+     * (5 000) and returns the first status whose `state` is not `pending` or `running`:
+     * `complete`, `failed` (returned, not thrown), or a state this SDK does not know yet.
+     * When nothing needs re-deriving, the service's `200` answer is returned as it is. A
+     * `409` `reingest_running` throws `ConflictError`. When `timeout` milliseconds
+     * (3 600 000) run out first, throws `WaitTimeoutError` with the last status as
+     * `lastStatus`; the run itself goes on. `timeout` is a deadline that also bounds each
+     * poll and its retries (see `HelperOptions`); it never prevents or cuts short the start,
+     * which has the client's own timeout. Aborting `signal` stops the helper and any pending
+     * poll, not the run. A poll that fails throws that call's error while the run goes on,
+     * with the last status read before it as `lastStatus`: its `run_id` lets the caller go
+     * on polling with `get()` instead of calling `run()` again, which throws `ConflictError`
+     * (`reingest_running`) until the run ends.
      *
      * A run takes at most `limit` memories, so a `complete` run can leave some for later
      * (`remaining` above 0): calling `run()` again with the same parameters continues it.

package/dist/esm/client.js

@@ -3,7 +3,7 @@
 // Each method describes one call: its HTTP method and path, where its fields go, and
 // whether the SDK may retry it by itself. Core in core.ts sends it.
 import { NenaviError, WaitTimeoutError } from './errors.js';
-import { Core, helperDeadline, helperWait, ownProperties, pathParam, } from './core.js';
+import { Core, helperDeadline, helperWait, ownProperties, pathParam, withCause, } from './core.js';
 class Resource {
     _core;
     _raw;
@@ -23,8 +23,24 @@ class Resource {
         return this._core.request(call, this._raw);
     }
 }
-/** The states after which a helper stops polling. */
-const FINISHED = new Set(['complete', 'failed']);
+/**
+ * The states a helper keeps polling through. Any other state, one the service adds later
+ * included, is final and returned.
+ */
+const WORKING = new Set(['pending', 'running']);
+/** `GET /v1/events/{event_id}/extraction-status`, for the method and its helper. */
+function extractionStatusCall(eventId, options) {
+    return {
+        method: 'GET',
+        path: `/v1/events/${pathParam(eventId)}/extraction-status`,
+        retrySafe: true,
+        options,
+    };
+}
+/** `GET /v1/reingest/{run_id}`, for the method and its helper. */
+function reingestGetCall(runId, options) {
+    return { method: 'GET', path: `/v1/reingest/${pathParam(runId)}`, retrySafe: true, options };
+}
 /** A caller's `Idempotency-Key`, or null; an empty value counts as not given. */
 function callerKey(options) {
     const key = ownProperties(options).idempotencyKey;
@@ -70,12 +86,7 @@ export class Events extends Resource {
     }
     /** `GET /v1/events/{event_id}/extraction-status`. */
     extractionStatus(eventId, options) {
-        return this._request(() => ({
-            method: 'GET',
-            path: `/v1/events/${pathParam(eventId)}/extraction-status`,
-            retrySafe: true,
-            options,
-        }));
+        return this._request(() => extractionStatusCall(eventId, options));
     }
     /** `POST /v1/events/{event_id}/retry-extraction`. Not retried automatically. */
     retryExtraction(eventId, params, options) {
@@ -239,12 +250,7 @@ export class Reingest extends Resource {
     }
     /** `GET /v1/reingest/{run_id}`: the run's state, counts and usage. */
     get(runId, options) {
-        return this._request(() => ({
-            method: 'GET',
-            path: `/v1/reingest/${pathParam(runId)}`,
-            retrySafe: true,
-            options,
-        }));
+        return this._request(() => reingestGetCall(runId, options));
     }
 }
 /** The claim routes: supersedences and contradictions. Not retried automatically. */
@@ -577,12 +583,14 @@ export class Learning extends Resource {
 /** `client.events`: the event routes and `waitForExtraction()`. */
 export class EventsWithHelpers extends Events {
     /**
-     * Poll the event's extraction status until it is `complete` or `failed`.
+     * Poll the event's extraction status until it is no longer `pending` or `running`.
      *
      * Polls `GET /v1/events/{event_id}/extraction-status` at once and then every
-     * `interval` milliseconds (2 000), and returns the last status; a `failed` status is
-     * returned, not thrown. When `timeout` milliseconds (300 000) run out first, throws
-     * `WaitTimeoutError` with the last status as `lastStatus`. Aborting `signal` stops
+     * `interval` milliseconds (2 000), and returns the first status that is not `pending`
+     * or `running`: `complete`, `failed` (returned, not thrown), or a status this SDK does
+     * not know yet. When `timeout` milliseconds (300 000) run out first, throws
+     * `WaitTimeoutError` with the last status as `lastStatus`; `timeout` is a deadline that
+     * also bounds each poll and its retries (see `HelperOptions`). Aborting `signal` stops
      * the helper and any pending poll or retry. Each poll is an ordinary call, with the
      * client's retries and errors, and counts against the key's request rate limit like any
      * other call, so many waits at once can slow the key's other calls. A job can stay
@@ -592,10 +600,26 @@ export class EventsWithHelpers extends Events {
         const { timeout = 300_000, interval = 2_000, signal = null } = ownProperties(options);
         const core = this._core;
         const deadline = helperDeadline(core.now(), timeout, interval);
+        let lastStatus = null;
         for (;;) {
-            const status = await this.extractionStatus(eventId, { signal });
-            if (FINISHED.has(status.status))
+            let status;
+            try {
+                status = await this._request(() => ({
+                    ...extractionStatusCall(eventId, { signal }),
+                    deadline,
+                }));
+            }
+            catch (error) {
+                // Only a poll the deadline stopped throws WaitTimeoutError; its own error is the cause.
+                if (!(error instanceof WaitTimeoutError))
+                    throw error;
+                const last = lastStatus === null ? 'none' : JSON.stringify(lastStatus.status);
+                throw withCause(new WaitTimeoutError(`The extraction did not finish within ${timeout} ms: ${error.message}. The last ` +
+                    `status read was ${last}.`, { lastStatus }), error.cause);
+            }
+            if (!WORKING.has(status.status))
                 return status;
+            lastStatus = status;
             const wait = helperWait(core.now(), deadline, interval);
             if (wait === null) {
                 throw new WaitTimeoutError(`The extraction did not finish within ${timeout} ms; its last status was ` +
@@ -618,7 +642,9 @@ export class NodesWithHelpers extends Nodes {
      * `NenaviError`, so a scan never ends early without saying so.
      *
      * @example
-     * for await (const node of client.nodes.scanAll({ user_id: 'user-1' })) console.log(node.id);
+     * for await (const node of client.nodes.scanAll({ user_id: 'user-1', limit: 1000 })) {
+     *   console.log(node.id);
+     * }
      */
     async *scanAll(params, options) {
         const given = ownProperties(params);
@@ -644,17 +670,21 @@ export class NodesWithHelpers extends Nodes {
 /** `client.reingest`: the re-ingest routes and `run()`. */
 export class ReingestWithHelpers extends Reingest {
     /**
-     * Start a re-ingest run and poll it until its `state` is `complete` or `failed`.
+     * Start a re-ingest run and poll it until its `state` is final.
      *
      * Sends `start()` (`dry_run: false`), then polls `get()` every `interval` milliseconds
-     * (5 000) and returns the last status; a `failed` run is returned, not thrown. When
-     * nothing needs re-deriving, the service's `200` answer is returned as it is. A `409`
-     * `reingest_running` throws `ConflictError`. When `timeout` milliseconds (3 600 000)
-     * run out first, throws `WaitTimeoutError` with the last status as `lastStatus`; the
-     * run itself goes on. The timeout never prevents the start. Aborting `signal` stops the
-     * helper and any pending poll, not the run. A failed poll throws that call's error while
-     * the run goes on; to keep the run's id across such failures, call `start()` and poll
-     * `get()` yourself.
+     * (5 000) and returns the first status whose `state` is not `pending` or `running`:
+     * `complete`, `failed` (returned, not thrown), or a state this SDK does not know yet.
+     * When nothing needs re-deriving, the service's `200` answer is returned as it is. A
+     * `409` `reingest_running` throws `ConflictError`. When `timeout` milliseconds
+     * (3 600 000) run out first, throws `WaitTimeoutError` with the last status as
+     * `lastStatus`; the run itself goes on. `timeout` is a deadline that also bounds each
+     * poll and its retries (see `HelperOptions`); it never prevents or cuts short the start,
+     * which has the client's own timeout. Aborting `signal` stops the helper and any pending
+     * poll, not the run. A poll that fails throws that call's error while the run goes on,
+     * with the last status read before it as `lastStatus`: its `run_id` lets the caller go
+     * on polling with `get()` instead of calling `run()` again, which throws `ConflictError`
+     * (`reingest_running`) until the run ends.
      *
      * A run takes at most `limit` memories, so a `complete` run can leave some for later
      * (`remaining` above 0): calling `run()` again with the same parameters continues it.
@@ -664,14 +694,32 @@ export class ReingestWithHelpers extends Reingest {
         const core = this._core;
         const deadline = helperDeadline(core.now(), timeout, interval);
         let status = await this.start(params, { signal });
-        while (status.run_id !== null && status.run_id !== undefined && !FINISHED.has(status.state)) {
+        while (status.run_id !== null && status.run_id !== undefined && WORKING.has(status.state)) {
             const wait = helperWait(core.now(), deadline, interval);
             if (wait === null) {
                 throw new WaitTimeoutError(`The re-ingest run ${status.run_id} did not finish within ${timeout} ms; its ` +
                     `last state was ${JSON.stringify(status.state)}.`, { lastStatus: status });
             }
             await core.sleep(wait, signal);
-            status = await this.get(status.run_id, { signal });
+            const runId = status.run_id;
+            try {
+                status = await this._request(() => ({
+                    ...reingestGetCall(runId, { signal }),
+                    deadline,
+                }));
+            }
+            catch (error) {
+                // A poll the deadline stopped throws WaitTimeoutError; its own error is the cause.
+                if (error instanceof WaitTimeoutError) {
+                    throw withCause(new WaitTimeoutError(`The re-ingest run ${runId} did not finish within ${timeout} ms: ` +
+                        `${error.message}. Its last state was ${JSON.stringify(status.state)}.`, { lastStatus: status }), error.cause);
+                }
+                // The run goes on; without its id the caller could only call run() again, which
+                // the service refuses with 409 until the run ends. An abort keeps its own reason.
+                if (error instanceof NenaviError && !signal?.aborted)
+                    error.lastStatus = status;
+                throw error;
+            }
         }
         return status;
     }

package/dist/esm/core.d.ts

@@ -1,3 +1,4 @@
+import { NenaviError } from './errors.js';
 /** The `fetch` the SDK calls: the runtime's own, or one the caller passes. */
 export type Fetch = (input: string, init: RequestInit) => Promise<Response>;
 export interface ClientOptions {
@@ -46,6 +47,11 @@ export interface Call {
     options?: RequestOptions | undefined;
     /** The JSON type of the answer: an object (the default), an array, or an object or null. */
     answer?: 'object' | 'array' | 'nullable';
+    /**
+     * A helper's deadline on `Core.now`: it caps each attempt's timeout and stops a retry
+     * whose wait would end past it. Unset for an ordinary call.
+     */
+    deadline?: number;
 }
 /** Encode one path parameter, so a value cannot add or change path segments. */
 export declare function pathParam(value: string): string;
@@ -57,6 +63,8 @@ export declare function helperDeadline(now: number, timeout: number, interval: n
 export declare function helperWait(now: number, deadline: number, interval: number): number | null;
 /** Wait `ms` milliseconds, or reject with the signal's reason when it is aborted first. */
 export declare function sleep(ms: number, signal?: AbortSignal | null): Promise<void>;
+/** Set `cause` as the `Error` constructor does: an own property that is not enumerable. */
+export declare function withCause<E extends Error>(error: E, cause: NenaviError): E;
 /** Holds the configuration and sends the calls. The key is a private field. */
 export declare class Core {
     #private;

package/dist/esm/core.js

@@ -2,7 +2,7 @@
 //
 // Everything that decides what to send, whether to retry, how long to wait and which
 // error to throw lives here. The method classes in client.ts only describe each call.
-import { APIConnectionError, APIError, APITimeoutError, ConfigurationError, DETAIL_TEXT_LIMIT, NenaviError, RateLimitError, ResponseValidationError, ServiceUnavailableError, errorFromResponse, parseRetryAfter, } from './errors.js';
+import { APIConnectionError, APIError, APITimeoutError, ConfigurationError, DETAIL_TEXT_LIMIT, NenaviError, RateLimitError, ResponseValidationError, ServiceUnavailableError, WaitTimeoutError, errorFromResponse, parseRetryAfter, } from './errors.js';
 import { VERSION } from './version.js';
 const DEFAULT_BASE_URL = 'https://api.prismemory.com';
 /** Milliseconds per attempt. */
@@ -12,6 +12,11 @@ const DEFAULT_MAX_RETRIES = 2;
 const MAX_RETRY_AFTER = 60;
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
 const RETRYABLE_503 = new Set(['database_unavailable', 'lease_unavailable']);
+/**
+ * Milliseconds: the shortest attempt timeout a helper's poll gets near its deadline, so the
+ * poll at the deadline (and the one poll of `timeout: 0`) can still be answered.
+ */
+const MIN_POLL_TIMEOUT = 1_000;
 /** The longest delay setTimeout keeps: a longer one fires at once. */
 const MAX_TIMEOUT = 2_147_483_647;
 // Visible ASCII only: what an HTTP header can carry without encoding. This is not a check
@@ -193,6 +198,21 @@ function retryWait(error, retryNumber) {
     }
     return null;
 }
+/**
+ * The error for a helper's poll that its deadline stopped; the helper adds its status. The
+ * poll's own error becomes its `cause`.
+ */
+function deadlineError(error, retrySkipped) {
+    const reason = retrySkipped
+        ? `the last poll threw ${error.name}, and its retry would have waited past the deadline`
+        : `the last poll got no answer before the deadline (${error.name})`;
+    return withCause(new WaitTimeoutError(reason, { idempotencyKey: error.idempotencyKey }), error);
+}
+/** Set `cause` as the `Error` constructor does: an own property that is not enumerable. */
+export function withCause(error, cause) {
+    Object.defineProperty(error, 'cause', { value: cause, writable: true, configurable: true });
+    return error;
+}
 /** The name, and the system error code when there is one, of what fetch threw. */
 function failureName(error) {
     const raw = error instanceof Error ? error.name : typeof error;
@@ -256,7 +276,8 @@ export class Core {
         if (auth && this.#apiKey === null) {
             throw new ConfigurationError('No API key: pass apiKey or set NENAVI_API_KEY. Only health() works without a key.');
         }
-        const timeout = checkTimeout(options.timeout ?? this.timeout);
+        const callTimeout = checkTimeout(options.timeout ?? this.timeout);
+        const deadline = call.deadline ?? null;
         const maxRetries = checkMaxRetries(options.maxRetries ?? this.maxRetries);
         const idempotencyKey = call.idempotencyKey ?? null;
         const headers = {
@@ -280,6 +301,10 @@ export class Core {
         const url = `${this.baseURL}${call.path}${queryString(call.query)}`;
         let retries = 0;
         for (;;) {
+            // A helper's poll gets only the time left.
+            const left = deadline === null ? Infinity : Math.max(deadline - this.now(), MIN_POLL_TIMEOUT);
+            const shortened = left < callTimeout;
+            const timeout = shortened ? left : callTimeout;
             const attempt = await this.#send(url, call.method, headers, body, timeout, signal, idempotencyKey);
             if (attempt.response !== undefined) {
                 return this.#result(attempt.response, attempt.text, raw, idempotencyKey, call.answer ?? 'object');
@@ -287,11 +312,17 @@ export class Core {
             if (call.retrySafe && retries < maxRetries) {
                 const wait = retryWait(attempt.error, retries + 1);
                 if (wait !== null) {
-                    retries += 1;
-                    await this.sleep(wait, signal);
-                    continue;
+                    if (deadline === null || this.now() + wait < deadline) {
+                        retries += 1;
+                        await this.sleep(wait, signal);
+                        continue;
+                    }
+                    throw deadlineError(attempt.error, true);
                 }
             }
+            if (shortened && attempt.error instanceof APITimeoutError) {
+                throw deadlineError(attempt.error, false);
+            }
             throw attempt.error;
         }
     }

package/dist/esm/errors.d.ts

@@ -1,9 +1,21 @@
 /** Base class of every error the SDK throws. */
 export declare class NenaviError extends Error {
+    /**
+     * `value instanceof` this class, also for an error from another copy of the package.
+     * Installed below with `Object.defineProperty`.
+     */
+    static [Symbol.hasInstance]: <T>(this: abstract new (...args: never[]) => T, value: unknown) => value is T;
     /** The `Idempotency-Key` the call sent, or null when it sent none. */
     idempotencyKey: string | null;
+    /**
+     * The last status a helper read before it threw: on `WaitTimeoutError`, and on the
+     * error of a poll that failed inside `reingest.run()`, where it holds the run's
+     * `run_id`. Null on other errors.
+     */
+    lastStatus: unknown;
     constructor(message: string, options?: {
         idempotencyKey?: string | null;
+        lastStatus?: unknown;
     });
 }
 /** No key for an operation that needs one, or an invalid option. */
@@ -11,12 +23,6 @@ export declare class ConfigurationError extends NenaviError {
 }
 /** A helper ran out of time before the work it waited for finished. */
 export declare class WaitTimeoutError extends NenaviError {
-    /** The last status the helper read. */
-    lastStatus: unknown;
-    constructor(message: string, options?: {
-        lastStatus?: unknown;
-        idempotencyKey?: string | null;
-    });
 }
 export interface ResponseValidationErrorOptions {
     status: number;

package/dist/esm/errors.js

@@ -3,26 +3,73 @@
 // An error holds plain values only: the status, a copy of the response headers and the
 // parsed body. It never holds a Request, a Response or the error fetch threw, so the
 // `Authorization` header cannot reach a message, `util.inspect` or `JSON.stringify`.
+//
+// The package ships an ES module build and a CommonJS build, and a process that loads
+// both holds two copies of every class here. So that `instanceof` still works across the
+// copies, each class's prototype carries its name under a key in the global symbol
+// registry, and `instanceof` falls back to matching that name along the prototype chain.
+/**
+ * The key, shared by every copy of the package, under which a prototype names its class.
+ *
+ * Copies of different versions match each other by this key and the class name alone, so
+ * the key is a contract between versions. A release that changes an error class's fields
+ * incompatibly must change the key (for example to `nenavi.error.class.v2`), so that its
+ * errors stop matching older copies' classes instead of narrowing to the old shape.
+ */
+const CLASS_NAME = Symbol.for('nenavi.error.class');
 /** Base class of every error the SDK throws. */
 export class NenaviError extends Error {
     /** The `Idempotency-Key` the call sent, or null when it sent none. */
     idempotencyKey;
+    /**
+     * The last status a helper read before it threw: on `WaitTimeoutError`, and on the
+     * error of a poll that failed inside `reingest.run()`, where it holds the run's
+     * `run_id`. Null on other errors.
+     */
+    lastStatus;
     constructor(message, options = {}) {
         super(message);
         this.idempotencyKey = options.idempotencyKey ?? null;
+        this.lastStatus = options.lastStatus ?? null;
     }
 }
+// The ordinary check comes first. Failing that, a class of this package matches a value
+// whose prototype chain holds a prototype marked with the same class name, as the other
+// copy's classes are. A subclass written outside the package keeps the ordinary check.
+//
+// This is defined as a property rather than written as a static method, because a loose
+// class transform in a consumer's build turns a static method into an assignment, and
+// assigning over the read-only `Function.prototype[Symbol.hasInstance]` throws.
+Object.defineProperty(NenaviError, Symbol.hasInstance, {
+    value: function hasInstance(value) {
+        if (Function.prototype[Symbol.hasInstance].call(this, value))
+            return true;
+        if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+            return false;
+        }
+        const prototype = this.prototype;
+        if (typeof prototype !== 'object' || prototype === null)
+            return false;
+        if (!Object.hasOwn(prototype, CLASS_NAME))
+            return false;
+        const name = prototype[CLASS_NAME];
+        for (let link = Object.getPrototypeOf(value); link !== null; link = Object.getPrototypeOf(link)) {
+            if (Object.hasOwn(link, CLASS_NAME) &&
+                link[CLASS_NAME] === name) {
+                return true;
+            }
+        }
+        return false;
+    },
+    writable: true,
+    enumerable: false,
+    configurable: true,
+});
 /** No key for an operation that needs one, or an invalid option. */
 export class ConfigurationError extends NenaviError {
 }
 /** A helper ran out of time before the work it waited for finished. */
 export class WaitTimeoutError extends NenaviError {
-    /** The last status the helper read. */
-    lastStatus;
-    constructor(message, options = {}) {
-        super(message, options);
-        this.lastStatus = options.lastStatus ?? null;
-    }
 }
 /**
  * A 2xx response whose body does not match the shape the operation answers with.
@@ -117,7 +164,8 @@ export class InternalServerError extends APIError {
 export class ServiceUnavailableError extends APIError {
 }
 // Each class's name, written out so that `error.name` survives a minifier that renames
-// classes. It sits on the prototype, so it is not an own property of an error.
+// classes. It sits on the prototype, so it is not an own property of an error. The same
+// name marks the prototype under CLASS_NAME for the cross-copy `instanceof` above.
 const NAMES = [
     [NenaviError, 'NenaviError'],
     [ConfigurationError, 'ConfigurationError'],
@@ -145,6 +193,12 @@ for (const [ErrorClass, name] of NAMES) {
         enumerable: false,
         configurable: true,
     });
+    Object.defineProperty(ErrorClass.prototype, CLASS_NAME, {
+        value: name,
+        writable: false,
+        enumerable: false,
+        configurable: false,
+    });
 }
 const BY_STATUS = {
     400: BadRequestError,

package/dist/esm/version.d.ts

@@ -1,2 +1,2 @@
 /** The SDK's version, sent in the `User-Agent` header. test/client.test.ts keeps it equal to package.json. */
-export declare const VERSION = "0.1.0-alpha.1";
+export declare const VERSION = "0.1.0-alpha.2";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 /** The SDK's version, sent in the `User-Agent` header. test/client.test.ts keeps it equal to package.json. */
-export const VERSION = '0.1.0-alpha.1';
+export const VERSION = '0.1.0-alpha.2';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nenavi",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "description": "TypeScript client for the Nenavi Cloud memory API",
   "license": "Apache-2.0",
   "homepage": "https://nenavi.com",