@vxil/sdk 0.14.1 → 0.16.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
@@ -400,6 +406,88 @@ export interface JobRun {
      *  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 {
@@ -508,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;
@@ -524,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;
@@ -740,6 +865,47 @@ export interface FileObject {
     /** The object's public URL when it is published to the public asset host
      *  (`files.publish`), else null. */
     public_url?: string | null;
+    /** When the object expires (null = never). An expired object is no longer
+     *  listed and answers 404, even before the sweep deletes it. */
+    expires_at?: string | null;
+}
+/** `files.createUploadUrl` answer. */
+export interface FileUploadUrl {
+    object_id: string;
+    upload_url: string;
+    upload_method: string;
+    /** Seconds the UPLOAD URL stays valid (`uploadUrlTtl`, default 900). */
+    expires_in: number;
+    /** When the OBJECT expires (null = never). */
+    expires_at: string | null;
+}
+/** `files.usage` answer. */
+export interface FilesUsage {
+    usage: {
+        object_count: number;
+        total_bytes: number;
+    };
+    /** `maxTotalBytes` = the storage quota enforced now (see `storage_plan`). */
+    quotas: {
+        maxObjectCount?: number;
+        maxObjectBytes?: number;
+        maxTotalBytes?: number;
+    };
+    available: Record<string, number | null>;
+    /** Your plan's storage ceiling, and whether `quotas.maxTotalBytes` is that
+     *  ceiling (`plan`) or your own lower value (`config`). */
+    storage_plan?: {
+        tier: string | null;
+        max_total_bytes: number;
+        source: 'plan' | 'config';
+    };
+    public_assets?: {
+        enabled: boolean;
+        published_objects: number;
+        published_bytes: number;
+        max_published_bytes: number;
+        bytes_remaining: number;
+    };
 }
 /** A published object (guide ch. 6, files, "Public asset delivery"): a stable,
  *  content-addressed URL on vxil's public asset host, served with
@@ -1042,13 +1208,23 @@ export interface JobGenerationSettledEventPayload {
     /** `completed` on the healthy terminal, `failed` on the broken one */
     status: 'completed' | 'failed';
     /** the run's SETTLED error class (`provider_error`, `PollExhausted`,
-     *  `GenerationExpired`, `ReserveInsufficient`, …); always null on `completed` */
+     *  `GenerationExpired`, `RetryableHttp`, `ReserveInsufficient`,
+     *  `PaymentsUnavailable`, `Cancelled`, …); always null on `completed`.
+     *  BRANCH ON THIS in a settle handler: `ReserveInsufficient` (the caller got
+     *  a 402), `PaymentsUnavailable` (the run was refused before it started —
+     *  usually the caller got a 503; a caller handed this run by a duplicate
+     *  request that raced it (202 `deduplicated`) learns it HERE and re-sends
+     *  the same request — a NEW run follows) and `Cancelled` are not render
+     *  failures. */
     error_class: string | null;
     /** the provider hint alone (`Upstream said: gemini 400: …`); null on
      *  `completed` and whenever the failure carried none */
     error_hint: string | null;
-    /** the failure-event vocabulary every `*.failed` carries (guide 12) */
-    level: 'info' | 'error';
+    /** the failure-event vocabulary every `*.failed` carries (guide 12):
+     *  `completed` → info; `failed` → error, except a refusal at admission
+     *  (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
+     *  (`Cancelled`) → info, so neither pages through the immediate digest */
+    level: 'info' | 'warn' | 'error';
     state: 'ok' | 'broken';
 }
 /** The union a handler subscribed to `job.generation.` receives as `data`:
@@ -1069,9 +1245,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';
@@ -1318,6 +1510,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;
@@ -2952,44 +3145,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
@@ -3006,7 +3227,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
          * the enqueue (insufficient balance; the run ends with job.generation.failed
          * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
-         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5).
+         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5). Payments
+         * unreachable at the hold → 503 `payments_unavailable` (Retry-After 15;
+         * nothing started, nothing held — re-send the same request), unless
+         * `reserve_credits.on_unavailable: 'proceed'`.
          *
          * Generic completion options for queue-style providers (fal.ai and alike —
          * no vendor adapter): `completion.callback.query_param` puts the signed
@@ -3019,7 +3243,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * 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)`). */
+         * (`JobRun.mirror_error` on `vx.jobs.run(run_id)`).
+         *
+         * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
+         * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
+         * `queue_full`) and a 503 `payments_unavailable`, 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: {
@@ -3073,22 +3304,41 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 amount: number;
                 user_id: string;
                 reason?: string;
+                /** payments unreachable when the hold is placed (a 5xx other than
+                 *  501, a 429, no answer within 5 s; payments switched off is NOT
+                 *  unreachable — that run starts without a hold): `'fail'` (default)
+                 *  → 503 `payments_unavailable` + Retry-After, nothing started or
+                 *  held — re-send the SAME request; `'proceed'` → start WITHOUT a
+                 *  hold (a free run while payments is down) */
+                on_unavailable?: "fail" | "proceed";
             };
             payload?: Record<string, unknown>;
             idempotency_key?: string;
+            /** START attempts = provider calls (1..20, default jobs.retry
+             *  .defaultMaxAttempts 5); a 408 / 429 / 5xx / network error retries
+             *  after min(2^n × 15, 600) s — or the provider's Retry-After on a
+             *  429 / 503 (1 s..10 min, never past the deadline) */
             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,
@@ -3110,6 +3360,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;
@@ -3142,17 +3398,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). */
@@ -4805,21 +5064,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }) => Promise<WebSocket>;
     };
     readonly files: {
-        /** Mint a presigned PUT; upload the bytes yourself, then call complete(). */
+        /** Mint a presigned PUT; upload the bytes yourself, then call complete().
+         *  `expiresInSeconds` (60 s up to 100 years) makes the OBJECT expire — it is deleted that
+         *  long after the mint, whether or not `files.ttl` is enabled; `null` =
+         *  never. The answer's `expires_in` is the UPLOAD URL's life in seconds;
+         *  `expires_at` is when the object expires (null = never). `user_id` is
+         *  required with a server key and omitted in end-user mode. */
         createUploadUrl: (input: {
-            user_id: string;
+            user_id?: string;
             filename: string;
             content_type: string;
             size_bytes: number;
-        }) => Promise<{
-            object_id: string;
-            upload_url: string;
-            upload_method: string;
-            expires_at: string;
-        }>;
+            expiresInSeconds?: number | null;
+        }) => Promise<FileUploadUrl>;
+        /** Confirm the PUT (bytes verified, object → available). Answers the
+         *  object's `expires_at` (null = never). */
         complete: (objectId: string) => Promise<{
             object_id: string;
             status: string;
+            checksum_sha256?: string | null;
+            expires_at?: string | null;
         }>;
         downloadUrl: (objectId: string) => Promise<string>;
         /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
@@ -4852,27 +5116,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Soft delete; bytes are hard-deleted 30 days later. */
         delete: (objectId: string) => Promise<void>;
         /** Aggregate storage usage vs quotas (the FilesManager Storage panel).
+         *  `quotas.maxTotalBytes` is the quota ENFORCED now — the plan's ceiling
+         *  unless you set a lower `quotas.maxTotalBytes` (`storage_plan.source`
+         *  says which). An object past its expiry no longer counts.
          *  `public_assets` = published copies vs the plan's published-bytes ceiling
          *  (identical bytes count once). */
-        usage: () => Promise<{
-            usage: {
-                object_count: number;
-                total_bytes: number;
-            };
-            quotas: {
-                maxObjectCount?: number;
-                maxObjectBytes?: number;
-                maxTotalBytes?: number;
-            };
-            available: Record<string, number | null>;
-            public_assets?: {
-                enabled: boolean;
-                published_objects: number;
-                published_bytes: number;
-                max_published_bytes: number;
-                bytes_remaining: number;
-            };
-        }>;
+        usage: () => Promise<FilesUsage>;
         /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
          *  object to vxil's public asset host: a stable, content-addressed URL
          *  (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
@@ -4932,7 +5181,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             error?: string | null;
         }>;
         /** Set / extend / clear an object's TTL. `expiresInSeconds: null` clears it
-         *  (else a future auto-delete after the given seconds; minimum 60). */
+         *  (else a future auto-delete after the given seconds; 60 s up to 100
+         *  years). An object already past its expiry is a 404 — never revived. */
         setTtl: (objectId: string, expiresInSeconds: number | null) => Promise<{
             object_id: string;
             expires_at: string | null;

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
@@ -349,9 +353,20 @@ export class Vxil {
                     body: JSON.stringify(payload ?? {}),
                 });
                 if (!res.ok) {
+                    // A function answers its OWN error body: the platform envelope
+                    // `{ error: { code, message } }`, or a bare string code
+                    // `{ error: 'role_required', message? }` (the blueprints' shape) —
+                    // both keep their code (a string used to collapse to http_<status>).
                     let e = {};
                     try {
-                        e = JSON.parse(text).error ?? {};
+                        const b = JSON.parse(text);
+                        if (typeof b.error === 'string') {
+                            if (b.error)
+                                e = { code: b.error, message: typeof b.message === 'string' && b.message ? b.message : b.error };
+                        }
+                        else if (b.error && typeof b.error === 'object') {
+                            e = b.error;
+                        }
                     }
                     catch { /* non-JSON error body */ }
                     throw new VxilError(res.status, e.code ?? `http_${res.status}`, e.message ?? text.slice(0, 200), undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
@@ -688,12 +703,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
@@ -710,7 +765,10 @@ export class Vxil {
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
          * the enqueue (insufficient balance; the run ends with job.generation.failed
          * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
-         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5).
+         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5). Payments
+         * unreachable at the hold → 503 `payments_unavailable` (Retry-After 15;
+         * nothing started, nothing held — re-send the same request), unless
+         * `reserve_credits.on_unavailable: 'proceed'`.
          *
          * Generic completion options for queue-style providers (fal.ai and alike —
          * no vendor adapter): `completion.callback.query_param` puts the signed
@@ -723,17 +781,38 @@ export class Vxil {
          * 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)`). */
-        generation: async (input) => (await this.call('POST', '/v1/jobs/generation', input)).data,
+         * (`JobRun.mirror_error` on `vx.jobs.run(run_id)`).
+         *
+         * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
+         * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
+         * `queue_full`) and a 503 `payments_unavailable`, 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,
@@ -753,6 +832,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. */
@@ -770,10 +855,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)}`);
@@ -1752,8 +1847,15 @@ export class Vxil {
         },
     };
     files = {
-        /** Mint a presigned PUT; upload the bytes yourself, then call complete(). */
+        /** Mint a presigned PUT; upload the bytes yourself, then call complete().
+         *  `expiresInSeconds` (60 s up to 100 years) makes the OBJECT expire — it is deleted that
+         *  long after the mint, whether or not `files.ttl` is enabled; `null` =
+         *  never. The answer's `expires_in` is the UPLOAD URL's life in seconds;
+         *  `expires_at` is when the object expires (null = never). `user_id` is
+         *  required with a server key and omitted in end-user mode. */
         createUploadUrl: async (input) => (await this.call('POST', '/v1/files/upload-url', input)).data,
+        /** Confirm the PUT (bytes verified, object → available). Answers the
+         *  object's `expires_at` (null = never). */
         complete: async (objectId) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/complete`)).data,
         downloadUrl: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url`)).data.download_url,
         /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
@@ -1777,6 +1879,9 @@ export class Vxil {
             await this.call('DELETE', `/v1/files/${encodeURIComponent(objectId)}`);
         },
         /** Aggregate storage usage vs quotas (the FilesManager Storage panel).
+         *  `quotas.maxTotalBytes` is the quota ENFORCED now — the plan's ceiling
+         *  unless you set a lower `quotas.maxTotalBytes` (`storage_plan.source`
+         *  says which). An object past its expiry no longer counts.
          *  `public_assets` = published copies vs the plan's published-bytes ceiling
          *  (identical bytes count once). */
         usage: async () => (await this.call('GET', '/v1/files/usage')).data,
@@ -1814,7 +1919,8 @@ export class Vxil {
         /** Fetch the cached extraction (status: not_extracted|pending|available|failed). */
         getText: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/text`)).data,
         /** Set / extend / clear an object's TTL. `expiresInSeconds: null` clears it
-         *  (else a future auto-delete after the given seconds; minimum 60). */
+         *  (else a future auto-delete after the given seconds; 60 s up to 100
+         *  years). An object already past its expiry is a 404 — never revived. */
         setTtl: async (objectId, expiresInSeconds) => (await this.call('PUT', `/v1/files/${encodeURIComponent(objectId)}/ttl`, { expiresInSeconds })).data,
         /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move
          *  every object `from_user_id` owns (every status, tombstones included) and
@@ -2350,3 +2456,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,36 @@ 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>;
+/** The 503 answers retried the same way (M1, 2026-10-04): the generation
+ *  lane could not reach payments to place its credit hold — nothing was
+ *  started and nothing held, and the SAME request re-sent after Retry-After
+ *  starts the run (the refused run released its idempotency key). */
+export declare const UNAVAILABLE_ERROR_CODES: ReadonlySet<string>;
+/** Is this thrown error one `retryOnCapacity` waits out? Duck-typed on
+ *  `{ status, code }` (VxilError's fields). */
+export declare function isCapacityRetryable(e: unknown): boolean;
+/** `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`) or
+ * a 503 `payments_unavailable` (`UNAVAILABLE_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,60 @@ 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',
+]);
+/** The 503 answers retried the same way (M1, 2026-10-04): the generation
+ *  lane could not reach payments to place its credit hold — nothing was
+ *  started and nothing held, and the SAME request re-sent after Retry-After
+ *  starts the run (the refused run released its idempotency key). */
+export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable']);
+/** Is this thrown error one `retryOnCapacity` waits out? Duck-typed on
+ *  `{ status, code }` (VxilError's fields). */
+export function isCapacityRetryable(e) {
+    const err = e;
+    if (!err || typeof err.code !== 'string')
+        return false;
+    return (err.status === 429 && CAPACITY_ERROR_CODES.has(err.code))
+        || (err.status === 503 && UNAVAILABLE_ERROR_CODES.has(err.code));
+}
+/** 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`) or
+ * a 503 `payments_unavailable` (`UNAVAILABLE_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 || !isCapacityRetryable(err))
+                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.1",
+  "version": "0.16.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",