@vxil/sdk 0.15.0 → 0.16.1

package/dist/index.d.ts

@@ -414,8 +414,10 @@ export interface JobRun {
     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 */
+    /** the run's deadline. A plain run enqueued with `ttl_seconds`: its START
+     *  deadline (dead-lettered `Expired` if not started by then). A generation
+     *  run: its completion deadline (`timeout.after_ms`; past it the run ends
+     *  `GenerationExpired` and any credit hold is released). Null otherwise. */
     expires_at?: string | null;
     /** the single-run read only: the debounce key of a debounced run */
     debounce_key?: string | null;
@@ -865,6 +867,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
@@ -1167,13 +1210,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`:
@@ -3176,7 +3229,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
@@ -3193,7 +3249,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *
          * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
          * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
-         * `queue_full`) honouring Retry-After with jitter, with the SAME
+         * `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: {
@@ -3249,9 +3306,20 @@ 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?: {
@@ -4998,21 +5066,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`)
@@ -5045,27 +5118,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
@@ -5125,7 +5183,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

@@ -353,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')));
@@ -754,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
@@ -771,7 +785,8 @@ export class Vxil {
          *
          * `opts.retryOnCapacity: { maxWaitMs }` retries a CAPACITY 429
          * (`generation_concurrency_exceeded`, `reserve_holds_exceeded`,
-         * `queue_full`) honouring Retry-After with jitter, with the SAME
+         * `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) => {
@@ -1832,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`)
@@ -1857,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,
@@ -1894,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

package/dist/retry.d.ts

@@ -50,6 +50,14 @@ export declare function createTransport(opts: TransportOptions): Transport;
  *  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
@@ -60,7 +68,8 @@ export interface RetryOnCapacityOptions {
     now?: () => number;
 }
 /**
- * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`):
+ * 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.

package/dist/retry.js

@@ -162,10 +162,25 @@ export function createTransport(opts) {
 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`):
+ * 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.
@@ -184,7 +199,7 @@ export async function retryOnCapacity(attempt, opts) {
         }
         catch (e) {
             const err = e;
-            if (!err || err.status !== 429 || typeof err.code !== 'string' || !CAPACITY_ERROR_CODES.has(err.code))
+            if (!err || !isCapacityRetryable(err))
                 throw e;
             const baseMs = typeof err.retryAfter === 'number' && err.retryAfter >= 0
                 ? Math.round(err.retryAfter * 1000)

package/package.json

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