@vxil/sdk 0.14.0 → 0.15.0

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/** The 429 error codes `retryOnCapacity` treats as "at a capacity cap — try the
+ *  SAME request again shortly". Declared here with an explicit type (not a
+ *  re-export) so the served single-file index.d.ts never imports ./retry. */
+export declare const CAPACITY_ERROR_CODES: ReadonlySet<string>;
 export type ApiVersion = 'v1';
 /** A per-feature API-version override key: the URL namespace that leads a path
  *  (`/v1/<namespace>/…`). Matches the segment `versionedPath` rewrites, so an
@@ -361,7 +365,9 @@ export interface JobRun {
     queued_at: string;
     started_at?: string | null;
     completed_at: string | null;
-    /** generation runs (POST /v1/jobs/generation) only: the provider-side status */
+    /** generation runs (POST /v1/jobs/generation) only: the provider-side status
+     *  (pending | processing | completed | failed); null for a plain run. On the
+     *  list (`vx.jobs.runs`) and the single-run read. */
     generation_status?: string | null;
     generation_json?: Record<string, unknown> | null;
     /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
@@ -392,6 +398,115 @@ export interface JobRun {
      *  `processing` ping on its signed callback (plain run) or its provider's
      *  webhook (generation run). null until one arrives. */
     progress?: JobRunProgress | null;
+    /** the single-run read, generation runs only: the LAST `status_mirror`
+     *  write the target refused, or null. A full write refused as a body
+     *  problem (400 / 413 / 422 — e.g. a callback key the collection does not
+     *  declare) is retried with only the status column (a progress update tries
+     *  the declared `progress_fields` first), so an undeclared key no longer
+     *  strands the row; this says what was dropped. Never flips the run; not cleared by a later
+     *  successful mirror (compare `generation_status` / `at`). */
+    mirror_error?: JobRunMirrorError | null;
+    /** the single-run read only: the enqueue `concurrency_key` this run holds
+     *  while running or waiting; null for an unkeyed run */
+    concurrency_key?: string | null;
+    /** the single-run read only: how many runs sharing the key may hold it at
+     *  once; null for an unkeyed run */
+    concurrency_limit?: number | null;
+    /** the fan-in batch the run joined (enqueue `batch_id`); null otherwise */
+    batch_id?: string | null;
+    /** a plain run enqueued with `ttl_seconds`: its START deadline (it is
+     *  dead-lettered `Expired` if not started by then); null otherwise */
+    expires_at?: string | null;
+    /** the single-run read only: the debounce key of a debounced run */
+    debounce_key?: string | null;
+}
+/** The plain-run enqueue input shared by `enqueue` and `enqueueBatch` items. */
+export interface JobEnqueueInput {
+    job_name: string;
+    target_url: string;
+    payload?: Record<string, unknown>;
+    idempotency_key?: string;
+    max_attempts?: number;
+    deliver_after?: string;
+    delay_seconds?: number;
+    /** 60..2678400: dead-letter the run (`Expired`) if not started this long after it is due */
+    ttl_seconds?: number;
+    /** per-key concurrency: at most `concurrency_limit` runs sharing this key hold it at once */
+    concurrency_key?: string;
+    /** 1..100, default 1; requires concurrency_key */
+    concurrency_limit?: number;
+}
+/** The answer of `vx.jobs.enqueue`. */
+export interface JobEnqueueResult {
+    run_id: string;
+    state: string;
+    deduplicated?: boolean;
+    /** a debounced enqueue that pushed the open run (same run_id) */
+    debounced?: boolean;
+    deliver_after?: string;
+    callback_url?: string;
+    /** the START deadline when `ttl_seconds` was given */
+    expires_at?: string;
+    batch_id?: string;
+    /** true when the run's first attempt is already in flight (it started on
+     *  the enqueue request, no queue in front of it); absent when it was queued */
+    direct?: boolean;
+}
+/** `vx.jobs.runs` / `runsPage` filters. */
+export interface JobRunsQuery {
+    job_name?: string;
+    state?: JobRun['state'] | string;
+    ids?: string[];
+    batch_id?: string;
+    /** ISO: runs created at or after */
+    since?: string;
+    /** ISO: runs created before */
+    until?: string;
+    limit?: number;
+}
+/** One page of `vx.jobs.runsPage`. */
+export interface JobRunsPage {
+    runs: JobRun[];
+    /** pass back as `cursor` for the next older page; null on the last page */
+    next_cursor: string | null;
+}
+/** `GET /v1/jobs/batches/{batch_id}` — a fan-in batch. */
+export interface JobBatch {
+    batch_id: string;
+    /** 'completed' once every run is terminal (the event fired, or fires within a minute) */
+    state: 'open' | 'completed';
+    total: number;
+    /** the declared size (`batch_total`), or null */
+    expected_total: number | null;
+    open: number;
+    succeeded: number;
+    dead_lettered: number;
+    cancelled: number;
+    /** live count of the batch's RETAINED runs by state (runs past retention drop out; the counters above do not) */
+    runs_by_state: Partial<Record<JobRun['state'], number>>;
+    created_at: string;
+    completed_at: string | null;
+    /** when `job.batch.completed` was written */
+    event_emitted_at: string | null;
+}
+/** A refused status-mirror write (`JobRun.mirror_error`). */
+export interface JobRunMirrorError {
+    /** the status word the refused write carried */
+    generation_status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** the target's HTTP status on the full write; 0 = no answer (network / timeout) */
+    status: number;
+    /** the target's error code (e.g. `validation_failed`), `network_error` / `timeout`, or null */
+    code: string | null;
+    /** the target's message (≤ 200 chars), e.g. "unknown field 'video_url'" */
+    message: string | null;
+    /** when it was refused (ISO) */
+    at: string;
+    /** present when a narrower retry LANDED: the keys that were not written */
+    fields_dropped?: string[];
+    /** present when every narrower retry was refused too (the last one's HTTP
+     *  status, 0 = no answer): the status word itself was refused and the
+     *  record still holds the previous status */
+    retry_status?: number;
 }
 /** A run's latest progress report (`JobRun.progress`): only these keys pass. */
 export interface JobRunProgress {
@@ -481,8 +596,11 @@ export interface JobScheduleHeld {
 export interface JobSchedule {
     schedule_id: string;
     job_name: string;
-    /** the create echo carries no cron; the list names it `cron_expr` */
+    /** the cron expression under the request field's name — every schedule
+     *  answer (create, update, list) carries it, equal to `cron_expr`; null for
+     *  a one-shot `run_at` schedule. (Before 2026-10-03 only `cron_expr`.) */
     cron?: string | null;
+    /** the same value under the stored column's name */
     cron_expr?: string | null;
     run_at?: string | null;
     next_run_at: string | null;
@@ -497,7 +615,41 @@ export interface JobSchedule {
     last_skipped_at?: string | null;
     /** non-null while the schedule is HELD (list only) */
     held?: JobScheduleHeld | null;
+    /** the IANA zone the cron is read in (default `'UTC'`); DST-correct */
+    timezone?: string;
+    /** your upsert key — a create naming a live schedule's external_id updates
+     *  that schedule instead of adding one */
+    external_id?: string | null;
+    /** each fired run's attempt budget; null = the project's
+     *  `jobs.retry.defaultMaxAttempts` */
+    max_attempts?: number | null;
+    /** on a create: true = a new schedule (201); false = the external_id
+     *  matched a live schedule, which was updated in place (200) */
+    created?: boolean;
+}
+/** The fields of a schedule create (`vx.jobs.schedules.create`). */
+export interface JobScheduleInput {
+    job_name: string;
+    target_url: string;
+    payload?: Record<string, unknown>;
+    /** 5-field cron, read in `timezone` — exactly one of cron / run_at */
+    cron?: string;
+    /** a future ISO timestamp (a one-shot) */
+    run_at?: string;
+    overlap?: 'allow' | 'skip';
+    /** an IANA zone, e.g. `'Asia/Amman'`, `'Europe/London'` (default `'UTC'`) */
+    timezone?: string;
+    /** ≤ 200 printable ASCII, no spaces — makes the create an upsert */
+    external_id?: string;
+    /** 1..20 */
+    max_attempts?: number;
 }
+/** The fields of a schedule PATCH (`vx.jobs.schedules.update`): any create
+ *  field; `external_id` / `max_attempts` accept null (clear). */
+export type JobSchedulePatch = Partial<Omit<JobScheduleInput, 'external_id' | 'max_attempts'>> & {
+    external_id?: string | null;
+    max_attempts?: number | null;
+};
 export interface AuthSession {
     token: string;
     refresh_token: string;
@@ -1042,9 +1194,25 @@ export interface JobRunEventPayload {
      *  `queue_backstop` (the queue's own retries ran out), `callback_failed`
      *  (the run's signed callback reported `status: 'failed'`) or
      *  `callback_timeout` (the handler handed the run off with a 202 and no
-     *  callback completed it within its lifetime). Absent when the run
+     *  callback completed it within its lifetime) or `expired` (a run enqueued
+     *  with `ttl_seconds` that had not started by its deadline — never
+     *  delivered; `last_error_class: 'Expired'`). Absent when the run
      *  exhausted its attempts normally. */
-    reason?: 'reaped' | 'queue_backstop' | 'callback_failed' | 'callback_timeout';
+    reason?: 'reaped' | 'queue_backstop' | 'callback_failed' | 'callback_timeout' | 'expired';
+}
+/** The `data` of `job.batch.completed`: EVERY run enqueued with this
+ *  `batch_id` reached a terminal state (and, with a declared `batch_total`,
+ *  that many runs joined). Emitted exactly ONCE per batch — a run replayed
+ *  later is a new run outside the batch. The fan-in signal: subscribe a
+ *  function to `job.batch.` and aggregate there; vxil runs no next step. */
+export interface JobBatchCompletedEventPayload {
+    batch_id: string;
+    /** runs that joined the batch */
+    total: number;
+    succeeded: number;
+    /** ended `dead` (retries exhausted, reaped, expired, callback failed …) */
+    dead_lettered: number;
+    cancelled: number;
 }
 /** The provider-reported environment of the money (`production` | `sandbox`). */
 export type PaymentsEventEnvironment = 'production' | 'sandbox';
@@ -1291,6 +1459,7 @@ export interface VxilEventPayloads {
     'job.generation.failed': JobGenerationSettledEventPayload;
     'job.succeeded': JobRunEventPayload;
     'job.dead_lettered': JobRunEventPayload;
+    'job.batch.completed': JobBatchCompletedEventPayload;
     'payments.charge.succeeded': PaymentsChargeEventPayload;
     'payments.charge.completed': PaymentsChargeEventPayload;
     'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
@@ -2925,44 +3094,72 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * delivery): an external worker POSTs it to complete / fail the run, report
          * progress, or wake a `wait`. A handler that answers 202 HANDS the run off
          * — it waits for that callback (dead-lettered as `CallbackTimeout` when the
-         * lifetime passes). See `postRunCallback`. */
-        enqueue: (input: {
-            job_name: string;
-            target_url: string;
-            payload?: Record<string, unknown>;
-            idempotency_key?: string;
-            max_attempts?: number;
-            deliver_after?: string;
-            delay_seconds?: number;
+         * lifetime passes). See `postRunCallback`.
+         *
+         * `concurrency_key` (≤ 200 chars) + `concurrency_limit` (1..100, default
+         * 1): at most that many runs of this job_name sharing the key hold it at
+         * once — e.g. the end user's id for "one import per user". A run holds its
+         * key from its first start until it finishes (running, waiting, and
+         * between retries). The rest stay queued and start oldest first (never
+         * rejected).
+         *
+         * Queue controls (2026-10-03):
+         * - `ttl_seconds` (60 s..31 d): a run not STARTED within this long of
+         *   being due is dead-lettered (`last_error_class: 'Expired'`,
+         *   `job.dead_lettered` with `reason: 'expired'`) and never delivered.
+         * - `debounce: { key, delay_seconds (1..86400), max_delay_seconds? }`: the
+         *   first enqueue for (job_name, key) makes a run due in delay_seconds;
+         *   each later one while it has not started REPLACES its payload and pushes
+         *   it to now + delay_seconds (never past first enqueue +
+         *   max_delay_seconds — default 10 × delay_seconds, clamped to 1..30 d)
+         *   and answers the SAME run_id with `debounced: true`.
+         *   Not combinable with idempotency_key / deliver_after / delay_seconds /
+         *   callback / batch_id.
+         * - `batch_id` (+ optional `batch_total`): the run joins a fan-in batch —
+         *   when every run of the batch is terminal, ONE `job.batch.completed`
+         *   event fires (see `batch()`). A completed batch takes no new runs (409
+         *   `batch_closed`). */
+        enqueue: (input: JobEnqueueInput & {
             callback?: boolean | {
                 ttl_seconds?: number;
             };
-        }) => Promise<{
-            run_id: string;
-            state: string;
-            deduplicated?: boolean;
-            deliver_after?: string;
-            callback_url?: string;
-        }>;
+            concurrency_key?: string;
+            concurrency_limit?: number;
+            debounce?: {
+                key: string;
+                delay_seconds: number;
+                max_delay_seconds?: number;
+            };
+            batch_id?: string;
+            batch_total?: number;
+        }) => Promise<JobEnqueueResult>;
         /** Atomic multi-enqueue (≤100 items; any invalid item rejects the whole
-         * batch). Each item = the enqueue input, incl. per-item idempotency_key
-         * and deliver_after/delay_seconds. Results align with the input order. */
-        enqueueBatch: (items: Array<{
-            job_name: string;
-            target_url: string;
-            payload?: Record<string, unknown>;
-            idempotency_key?: string;
-            max_attempts?: number;
-            deliver_after?: string;
-            delay_seconds?: number;
-        }>) => Promise<{
+         * batch). Each item = the enqueue input, incl. per-item idempotency_key,
+         * deliver_after/delay_seconds, ttl_seconds and concurrency_key/concurrency_limit. Results align with the
+         * input order.
+         *
+         * FAN-IN: `opts.batch_id` puts every item in one batch; when every run of
+         * the batch is terminal, ONE `job.batch.completed` event fires ({ batch_id,
+         * total, succeeded, dead_lettered, cancelled }) — subscribe a function to
+         * `job.batch.` to aggregate. A batch may span several calls: pass the same
+         * batch_id and declare `batch_total` (the full size) so it cannot complete
+         * between calls. */
+        enqueueBatch: (items: JobEnqueueInput[], opts?: {
+            batch_id?: string;
+            batch_total?: number;
+        }) => Promise<{
             runs: Array<{
                 run_id: string;
                 state: string;
                 deduplicated?: boolean;
             }>;
             count: number;
+            batch_id?: string;
         }>;
+        /** A fan-in batch: its exact counters (`total`, `open`, `succeeded`,
+         *  `dead_lettered`, `cancelled`), `state` ('open' | 'completed') and the
+         *  live count of its retained runs by state. 404 for an unknown batch. */
+        batch: (batchId: string) => Promise<JobBatch>;
         /** Enqueue a long-running EXTERNAL generation run (guide ch. 6, jobs): Vxil calls
          * the provider (BYO key), tracks completion via poll/webhook, mirrors a typed
          * generation_status onto a tenant record, enforces a built-in timeout, and
@@ -2987,7 +3184,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * sends `provider.body` exactly; `completion.status_map` maps up to 8
          * provider words to completed | failed | processing (`{ OK: 'completed',
          * ERROR: 'failed' }`); `completion.result_path` names the value the run
-         * settles with — the status mirror receives it as `result`. */
+         * settles with — the status mirror receives it as `result`.
+         *
+         * A mirror write the record refuses never fails the run: a body refusal
+         * (e.g. a callback key the collection does not declare) is retried with
+         * only the status column, so the row still reaches `completed`; the run then reports `mirror_error`
+         * (`JobRun.mirror_error` on `vx.jobs.run(run_id)`).
+         *
+         * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
+         * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
+         * `queue_full`) honouring Retry-After with jitter, with the SAME
+         * idempotency_key (one is generated when the input has none), until
+         * maxWaitMs has passed — then the last 429 is thrown. */
         generation: (input: {
             job_name: string;
             provider: {
@@ -3045,18 +3253,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             payload?: Record<string, unknown>;
             idempotency_key?: string;
             max_attempts?: number;
+        }, opts?: {
+            retryOnCapacity?: {
+                maxWaitMs: number;
+            };
         }) => Promise<{
             run_id: string;
             generation_status: string;
             state?: string;
             deduplicated?: boolean;
         }>;
-        runs: (q?: {
-            job_name?: string;
-            state?: string;
-            ids?: string[];
-            limit?: number;
-        }) => Promise<JobRun[]>;
+        /** The newest runs (≤ `limit`, default 50, max 100). Filters: job_name,
+         *  state, batch_id, ids, since/until (creation time, ISO). For more than
+         *  one page use `runsPage` (it returns the `next_cursor`). */
+        runs: (q?: JobRunsQuery) => Promise<JobRun[]>;
+        /** One page of runs, newest first, plus `next_cursor` (null on the last
+         *  page): pass it back as `cursor` for the next older page. The keyset
+         *  keeps pages stable while new runs arrive. */
+        runsPage: (q?: JobRunsQuery & {
+            cursor?: string | null;
+        }) => Promise<JobRunsPage>;
         run: (runId: string) => Promise<JobRun>;
         /** "Wait for this run": `GET /v1/jobs/runs/{run_id}?wait=<seconds>` holds
          *  the request platform-side (re-reading the run on one bounded connection,
@@ -3078,6 +3294,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** The live queue: depth by state, the oldest waiting run's age (the
          *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
         queue: () => Promise<JobsQueue>;
+        /** Cancel a run that has not started its current attempt (`queued`,
+         *  `delayed`, `retrying`) or a plain run handed off to its signed callback
+         *  (`waiting` after its handler answered 202 — the callback URL is
+         *  consumed). A `running` run (a delivery in flight, or a generation
+         *  waiting on its provider), a run waiting on an event, or a terminal run
+         *  answers `409 not_cancellable`. A generation's credit hold is released. */
         cancel: (runId: string) => Promise<{
             run_id: string;
             state: string;
@@ -3110,17 +3332,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
         signingSecret: () => Promise<string>;
         schedules: {
-            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at.
+            /** Recurring (5-field cron) or one-shot (run_at). Exactly one of cron/run_at.
+             *  `timezone` (IANA, default UTC) is the zone the cron is read in, DST-
+             *  correct. `external_id` makes it an UPSERT: a live schedule with the
+             *  same key is updated in place (`created: false`) — one schedule per
+             *  key, safe to call on every sign-in / settings save (an identical
+             *  repeat writes nothing). Server mode only: in end-user mode a create
+             *  with `external_id` is `403 server_only` (the key is tenant-wide).
              *  `overlap: 'skip'` (cron only): no new run while the previous one is
              *  still open — a missed window is never caught up either way. */
-            create: (input: {
-                job_name: string;
-                target_url: string;
-                payload?: Record<string, unknown>;
-                cron?: string;
-                run_at?: string;
-                overlap?: "allow" | "skip";
-            }) => Promise<JobSchedule>;
+            create: (input: JobScheduleInput) => Promise<JobSchedule>;
+            /** Change a live schedule in place (its id, state and counters kept). A
+             *  cron / run_at / timezone change recomputes the next fire. Server mode
+             *  only (`403 server_only` in end-user mode). */
+            update: (scheduleId: string, patch: JobSchedulePatch) => Promise<JobSchedule>;
             list: () => Promise<JobSchedule[]>;
             delete: (scheduleId: string) => Promise<void>;
             /** Stop an active schedule firing (the row + next_run_at survive). */

package/dist/index.js

@@ -8,7 +8,11 @@
  *  widens this union. Every path the SDK builds is major-versioned; the default
  *  is the compile-time constant `'v1'` (never a floating `latest` alias). */
 import { qs } from './qs.js';
-import { createTransport, parseRetryAfter } from './retry.js';
+import { createTransport, parseRetryAfter, retryOnCapacity, CAPACITY_ERROR_CODES as CAPACITY_CODES } from './retry.js';
+/** The 429 error codes `retryOnCapacity` treats as "at a capacity cap — try the
+ *  SAME request again shortly". Declared here with an explicit type (not a
+ *  re-export) so the served single-file index.d.ts never imports ./retry. */
+export const CAPACITY_ERROR_CODES = CAPACITY_CODES;
 /** Rewrite a built `/v1/<ns>/…` path onto the version configured for its
  *  namespace: the per-namespace override wins, else the global default. PURE and
  *  exported so it is unit-testable with a hypothetical future major (the runtime
@@ -688,12 +692,52 @@ export class Vxil {
          * delivery): an external worker POSTs it to complete / fail the run, report
          * progress, or wake a `wait`. A handler that answers 202 HANDS the run off
          * — it waits for that callback (dead-lettered as `CallbackTimeout` when the
-         * lifetime passes). See `postRunCallback`. */
+         * lifetime passes). See `postRunCallback`.
+         *
+         * `concurrency_key` (≤ 200 chars) + `concurrency_limit` (1..100, default
+         * 1): at most that many runs of this job_name sharing the key hold it at
+         * once — e.g. the end user's id for "one import per user". A run holds its
+         * key from its first start until it finishes (running, waiting, and
+         * between retries). The rest stay queued and start oldest first (never
+         * rejected).
+         *
+         * Queue controls (2026-10-03):
+         * - `ttl_seconds` (60 s..31 d): a run not STARTED within this long of
+         *   being due is dead-lettered (`last_error_class: 'Expired'`,
+         *   `job.dead_lettered` with `reason: 'expired'`) and never delivered.
+         * - `debounce: { key, delay_seconds (1..86400), max_delay_seconds? }`: the
+         *   first enqueue for (job_name, key) makes a run due in delay_seconds;
+         *   each later one while it has not started REPLACES its payload and pushes
+         *   it to now + delay_seconds (never past first enqueue +
+         *   max_delay_seconds — default 10 × delay_seconds, clamped to 1..30 d)
+         *   and answers the SAME run_id with `debounced: true`.
+         *   Not combinable with idempotency_key / deliver_after / delay_seconds /
+         *   callback / batch_id.
+         * - `batch_id` (+ optional `batch_total`): the run joins a fan-in batch —
+         *   when every run of the batch is terminal, ONE `job.batch.completed`
+         *   event fires (see `batch()`). A completed batch takes no new runs (409
+         *   `batch_closed`). */
         enqueue: async (input) => (await this.call('POST', '/v1/jobs/enqueue', input)).data,
         /** Atomic multi-enqueue (≤100 items; any invalid item rejects the whole
-         * batch). Each item = the enqueue input, incl. per-item idempotency_key
-         * and deliver_after/delay_seconds. Results align with the input order. */
-        enqueueBatch: async (items) => (await this.call('POST', '/v1/jobs/enqueue-batch', { jobs: items })).data,
+         * batch). Each item = the enqueue input, incl. per-item idempotency_key,
+         * deliver_after/delay_seconds, ttl_seconds and concurrency_key/concurrency_limit. Results align with the
+         * input order.
+         *
+         * FAN-IN: `opts.batch_id` puts every item in one batch; when every run of
+         * the batch is terminal, ONE `job.batch.completed` event fires ({ batch_id,
+         * total, succeeded, dead_lettered, cancelled }) — subscribe a function to
+         * `job.batch.` to aggregate. A batch may span several calls: pass the same
+         * batch_id and declare `batch_total` (the full size) so it cannot complete
+         * between calls. */
+        enqueueBatch: async (items, opts) => (await this.call('POST', '/v1/jobs/enqueue-batch', {
+            jobs: items,
+            ...(opts?.batch_id !== undefined ? { batch_id: opts.batch_id } : {}),
+            ...(opts?.batch_total !== undefined ? { batch_total: opts.batch_total } : {}),
+        })).data,
+        /** A fan-in batch: its exact counters (`total`, `open`, `succeeded`,
+         *  `dead_lettered`, `cancelled`), `state` ('open' | 'completed') and the
+         *  live count of its retained runs by state. 404 for an unknown batch. */
+        batch: async (batchId) => (await this.call('GET', `/v1/jobs/batches/${encodeURIComponent(batchId)}`)).data,
         /** Enqueue a long-running EXTERNAL generation run (guide ch. 6, jobs): Vxil calls
          * the provider (BYO key), tracks completion via poll/webhook, mirrors a typed
          * generation_status onto a tenant record, enforces a built-in timeout, and
@@ -718,17 +762,42 @@ export class Vxil {
          * sends `provider.body` exactly; `completion.status_map` maps up to 8
          * provider words to completed | failed | processing (`{ OK: 'completed',
          * ERROR: 'failed' }`); `completion.result_path` names the value the run
-         * settles with — the status mirror receives it as `result`. */
-        generation: async (input) => (await this.call('POST', '/v1/jobs/generation', input)).data,
+         * settles with — the status mirror receives it as `result`.
+         *
+         * A mirror write the record refuses never fails the run: a body refusal
+         * (e.g. a callback key the collection does not declare) is retried with
+         * only the status column, so the row still reaches `completed`; the run then reports `mirror_error`
+         * (`JobRun.mirror_error` on `vx.jobs.run(run_id)`).
+         *
+         * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
+         * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
+         * `queue_full`) honouring Retry-After with jitter, with the SAME
+         * idempotency_key (one is generated when the input has none), until
+         * maxWaitMs has passed — then the last 429 is thrown. */
+        generation: async (input, opts) => {
+            if (!opts?.retryOnCapacity) {
+                return (await this.call('POST', '/v1/jobs/generation', input)).data;
+            }
+            // the SAME request every time: a retry that races an accepted earlier
+            // one is deduplicated server-side by this key
+            const body = input.idempotency_key ? input : { ...input, idempotency_key: randomIdempotencyKey() };
+            return retryOnCapacity(async () => (await this.call('POST', '/v1/jobs/generation', body)).data, { maxWaitMs: opts.retryOnCapacity.maxWaitMs });
+        },
+        /** The newest runs (≤ `limit`, default 50, max 100). Filters: job_name,
+         *  state, batch_id, ids, since/until (creation time, ISO). For more than
+         *  one page use `runsPage` (it returns the `next_cursor`). */
         runs: async (q) => {
-            const s = qs({
-                job_name: q?.job_name || undefined,
-                state: q?.state || undefined,
-                ids: q?.ids,
-                limit: q?.limit || undefined,
-            });
+            const s = jobRunsQs(q);
             return (await this.call('GET', `/v1/jobs/runs${s}`)).data.runs;
         },
+        /** One page of runs, newest first, plus `next_cursor` (null on the last
+         *  page): pass it back as `cursor` for the next older page. The keyset
+         *  keeps pages stable while new runs arrive. */
+        runsPage: async (q) => {
+            const s = jobRunsQs(q);
+            const d = (await this.call('GET', `/v1/jobs/runs${s}`)).data;
+            return { runs: d.runs, next_cursor: d.next_cursor ?? null };
+        },
         run: async (runId) => (await this.call('GET', `/v1/jobs/runs/${encodeURIComponent(runId)}`)).data,
         /** "Wait for this run": `GET /v1/jobs/runs/{run_id}?wait=<seconds>` holds
          *  the request platform-side (re-reading the run on one bounded connection,
@@ -748,6 +817,12 @@ export class Vxil {
         /** The live queue: depth by state, the oldest waiting run's age (the
          *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
         queue: async () => (await this.call('GET', '/v1/jobs/queue')).data,
+        /** Cancel a run that has not started its current attempt (`queued`,
+         *  `delayed`, `retrying`) or a plain run handed off to its signed callback
+         *  (`waiting` after its handler answered 202 — the callback URL is
+         *  consumed). A `running` run (a delivery in flight, or a generation
+         *  waiting on its provider), a run waiting on an event, or a terminal run
+         *  answers `409 not_cancellable`. A generation's credit hold is released. */
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
         /** Clone a terminal run into a fresh queued run. A generation run answers
          *  `409 not_replayable` — submit the generation again instead. */
@@ -765,10 +840,20 @@ export class Vxil {
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
         signingSecret: async () => (await this.call('GET', '/v1/jobs/signing-secret')).data.signing_secret,
         schedules: {
-            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at.
+            /** Recurring (5-field cron) or one-shot (run_at). Exactly one of cron/run_at.
+             *  `timezone` (IANA, default UTC) is the zone the cron is read in, DST-
+             *  correct. `external_id` makes it an UPSERT: a live schedule with the
+             *  same key is updated in place (`created: false`) — one schedule per
+             *  key, safe to call on every sign-in / settings save (an identical
+             *  repeat writes nothing). Server mode only: in end-user mode a create
+             *  with `external_id` is `403 server_only` (the key is tenant-wide).
              *  `overlap: 'skip'` (cron only): no new run while the previous one is
              *  still open — a missed window is never caught up either way. */
             create: async (input) => (await this.call('POST', '/v1/jobs/schedules', input)).data,
+            /** Change a live schedule in place (its id, state and counters kept). A
+             *  cron / run_at / timezone change recomputes the next fire. Server mode
+             *  only (`403 server_only` in end-user mode). */
+            update: async (scheduleId, patch) => (await this.call('PATCH', `/v1/jobs/schedules/${encodeURIComponent(scheduleId)}`, patch)).data,
             list: async () => (await this.call('GET', '/v1/jobs/schedules')).data.schedules,
             delete: async (scheduleId) => {
                 await this.call('DELETE', `/v1/jobs/schedules/${encodeURIComponent(scheduleId)}`);
@@ -2345,3 +2430,23 @@ export class Vxil {
 // Failure reporting for tenant functions — the Sentry-envelope forwarder
 // (guide ch. 8). Zero dependencies; see reporting.ts.
 export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, } from './reporting.js';
+/** The query string of `vx.jobs.runs` / `runsPage`. */
+function jobRunsQs(q) {
+    return qs({
+        job_name: q?.job_name || undefined,
+        state: q?.state || undefined,
+        ids: q?.ids,
+        batch_id: q?.batch_id || undefined,
+        since: q?.since || undefined,
+        until: q?.until || undefined,
+        cursor: q?.cursor || undefined,
+        limit: q?.limit || undefined,
+    });
+}
+/** A fresh idempotency key (crypto.randomUUID where the runtime has it). */
+function randomIdempotencyKey() {
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return `sdk-${c.randomUUID()}`;
+    return `sdk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}

package/dist/retry.d.ts

@@ -45,3 +45,27 @@ export interface Transport {
  *  `retry` / `timeoutMs` / `hooks` set this is one `fetch` + `text()` — the
  *  pre-seam behaviour, byte for byte. */
 export declare function createTransport(opts: TransportOptions): Transport;
+/** The 429 answers that mean "the project is at a capacity cap right now —
+ *  try the SAME request again shortly" (the generation lane's in-flight cap
+ *  and outstanding-holds ceiling, and the queue admission cap). Any other 429
+ *  (a rate limit, a plan quota) is not a capacity answer and is rethrown. */
+export declare const CAPACITY_ERROR_CODES: ReadonlySet<string>;
+/** `retryOnCapacity` options. */
+export interface RetryOnCapacityOptions {
+    /** Give up (rethrow the last 429) once waiting again would pass this many
+     *  milliseconds since the first attempt. */
+    maxWaitMs: number;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    now?: () => number;
+}
+/**
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`):
+ * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
+ * so many clients told the same second do not all return on it), and never
+ * past `maxWaitMs` since the first attempt — then the last 429 is rethrown.
+ * The caller makes `attempt` repeat the SAME request (same idempotency key),
+ * so a retry that races an earlier accepted one is deduplicated server-side.
+ * Duck-typed on `{ status, code, retryAfter }` (VxilError's fields).
+ */
+export declare function retryOnCapacity<T>(attempt: () => Promise<T>, opts: RetryOnCapacityOptions): Promise<T>;

package/dist/retry.js

@@ -154,3 +154,45 @@ export function createTransport(opts) {
         },
     };
 }
+// ─── capacity retry (`vx.jobs.generation(…, { retryOnCapacity })`) ────────────
+/** The 429 answers that mean "the project is at a capacity cap right now —
+ *  try the SAME request again shortly" (the generation lane's in-flight cap
+ *  and outstanding-holds ceiling, and the queue admission cap). Any other 429
+ *  (a rate limit, a plan quota) is not a capacity answer and is rethrown. */
+export const CAPACITY_ERROR_CODES = new Set([
+    'generation_concurrency_exceeded', 'reserve_holds_exceeded', 'queue_full',
+]);
+/** Fallback wait (ms) when a capacity 429 carries no Retry-After. */
+const CAPACITY_DEFAULT_WAIT_MS = 5_000;
+/**
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`):
+ * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
+ * so many clients told the same second do not all return on it), and never
+ * past `maxWaitMs` since the first attempt — then the last 429 is rethrown.
+ * The caller makes `attempt` repeat the SAME request (same idempotency key),
+ * so a retry that races an earlier accepted one is deduplicated server-side.
+ * Duck-typed on `{ status, code, retryAfter }` (VxilError's fields).
+ */
+export async function retryOnCapacity(attempt, opts) {
+    const sleep = opts.sleep ?? defaultSleep;
+    const random = opts.random ?? Math.random;
+    const now = opts.now ?? Date.now;
+    const started = now();
+    for (;;) {
+        try {
+            return await attempt();
+        }
+        catch (e) {
+            const err = e;
+            if (!err || err.status !== 429 || typeof err.code !== 'string' || !CAPACITY_ERROR_CODES.has(err.code))
+                throw e;
+            const baseMs = typeof err.retryAfter === 'number' && err.retryAfter >= 0
+                ? Math.round(err.retryAfter * 1000)
+                : CAPACITY_DEFAULT_WAIT_MS;
+            const waitMs = baseMs + Math.round(Math.min(1_000, baseMs * 0.2) * random());
+            if (now() - started + waitMs > opts.maxWaitMs)
+                throw e;
+            await sleep(waitMs);
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",