@vxil/sdk 0.13.1 → 0.14.1

package/dist/index.d.ts

@@ -382,6 +382,82 @@ export interface JobRun {
      *  the fire); `started_at − scheduled_for` is how late it started. null for a
      *  run you enqueued (and for runs fired before 2026-10-01). */
     scheduled_for?: string | null;
+    /** the single-run read only: what the run completed with — the `result` of
+     *  its signed callback's `completed` body, or the value a generation run
+     *  settled with (the fields its status mirror received; an over-64 KiB value
+     *  reads `{ truncated: true, bytes, max_bytes }`). null when nothing reported
+     *  one — a handler's own 2xx response body is never stored. */
+    result?: unknown;
+    /** the single-run read only: the latest progress report of the run — a
+     *  `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;
+}
+/** 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 {
+    /** 0..100 */
+    progress?: number;
+    /** ≤ 64 chars */
+    stage?: string;
+    /** ≤ 200 chars */
+    message?: string;
+    /** when the report was stored (ISO) */
+    at: string;
+}
+/** The body an external worker POSTs to a run's signed `callback_url`
+ *  (`postRunCallback`). `completed` ends the run `succeeded` with `result`
+ *  stored (≤ 64 KiB of JSON); `failed` dead-letters it with `error`;
+ *  `processing` only records progress (repeatable). On a run suspended in
+ *  `jobs.wait(…)`, completed / failed WAKE the handler instead, with
+ *  `payload.wakeup = { via: 'callback', status, result?, error? }`. */
+export type RunCallbackBody = {
+    status: 'completed';
+    result?: unknown;
+} | {
+    status: 'failed';
+    error?: string;
+} | {
+    status: 'processing';
+    progress?: number;
+    stage?: string;
+    message?: string;
+};
+/** What a run callback answers: the run's state after it (`deduplicated: true`
+ *  when the URL was already used or the run was already terminal — nothing
+ *  changed). */
+export interface RunCallbackAnswer {
+    run_id: string;
+    state: JobRun['state'];
+    deduplicated?: boolean;
+    woken?: boolean;
+    event?: string;
 }
 /** The run states no later write can move — what `waitForRun` and an
  *  async+wait invoke resolve `done: true` on. */
@@ -661,7 +737,25 @@ export interface FileObject {
     size_bytes: number;
     status: 'pending' | 'available' | 'deleted';
     created_at: string;
+    /** The object's public URL when it is published to the public asset host
+     *  (`files.publish`), else null. */
+    public_url?: string | null;
+}
+/** A published object (guide ch. 6, files, "Public asset delivery"): a stable,
+ *  content-addressed URL on vxil's public asset host, served with
+ *  `Cache-Control: public, max-age=31536000, immutable`. `variants` maps each
+ *  declared image preset (`publicAssets.variants`) to its URL — images only. */
+export interface PublishedFile {
+    object_id: string;
+    url: string;
+    sha256: string;
+    content_type: string;
+    size_bytes: number;
+    published_at: string | null;
+    variants: Record<string, string>;
 }
+/** Why one id of a bulk publish was not published. */
+export type PublishErrorCode = 'not_found' | 'upload_incomplete' | 'content_type_not_publishable' | 'object_too_large' | 'quota_exceeded' | 'batch_budget_exceeded' | 'asset_taken_down' | 'publish_failed';
 /** A live shared link as listed by GET /v1/files/{id}/shared-links (guide ch. 6,
  *  files). `downloads` is the burn-on-read counter; `max_downloads` null =
  *  unlimited (1 = a one-time link). A link that hit its cap, expired, or was
@@ -971,10 +1065,13 @@ export interface JobRunEventPayload {
     level?: 'error';
     state?: 'broken';
     /** `job.dead_lettered` only, and only when something other than the
-     *  executor killed the run: `reaped` (the stuck-run reaper) or
-     *  `queue_backstop` (the queue's own retries ran out). Absent when the run
+     *  executor killed the run: `reaped` (the stuck-run reaper),
+     *  `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
      *  exhausted its attempts normally. */
-    reason?: 'reaped' | 'queue_backstop';
+    reason?: 'reaped' | 'queue_backstop' | 'callback_failed' | 'callback_timeout';
 }
 /** The provider-reported environment of the money (`production` | `sandbox`). */
 export type PaymentsEventEnvironment = 'production' | 'sandbox';
@@ -1366,6 +1463,13 @@ export interface JobDelivery<P = unknown> {
     payload: P;
     /** a schedule-fired run only: the slot it was due for (ISO, UTC) */
     scheduled_for?: string;
+    /** a run enqueued with `callback` only: its CURRENT single-use signed
+     *  callback URL. Hand it to the worker that finishes the job (no API key
+     *  needed) and answer 202 — the run waits until that worker POSTs
+     *  `{ status: 'completed', result }` / `{ status: 'failed', error }` /
+     *  `{ status: 'processing', progress, stage, message }` to it (see
+     *  `postRunCallback`). */
+    callback_url?: string;
 }
 /** The `?since=` replay read (GET /v1/ai/generations/{id}/stream). */
 export interface AiResumePage {
@@ -1798,6 +1902,16 @@ export declare function listCmsPublic(tenantId: string, collection: string, quer
     items: CmsPublicRow[];
     next_cursor: string | null;
 }>;
+/** POST a run's single-use signed `callback_url` (guide ch. 6, "Hand a run to
+ *  an external worker") — KEYLESS: no API key, no `Vxil` client; the URL is the
+ *  credential, so call this from the worker that finishes the job (a render
+ *  farm, a GPU box, another queue's task). Idempotent: a repeat of a used URL
+ *  answers `deduplicated: true`. A non-2xx throws `VxilError` (401 a forged or
+ *  altered URL, 410 `callback_expired`, 413 `result_too_large`, 404 a run that
+ *  did not opt in). */
+export declare function postRunCallback(callbackUrl: string, body: RunCallbackBody, opts?: {
+    fetch?: typeof fetch;
+}): Promise<RunCallbackAnswer>;
 /** The structural shape a `vxil gen`-generated `VxilSchema` satisfies. The base
  *  `Vxil` class is generic over it (`new Vxil<VxilSchema>(...)`), exactly the
  *  `createClient<Database>()` move — types are layered on; the runtime is
@@ -2831,7 +2945,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly jobs: {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
-         * two) defer the first delivery; > 12 h returns state 'delayed'. */
+         * two) defer the first delivery; > 12 h returns state 'delayed'.
+         *
+         * `callback: true` (or `{ ttl_seconds }`, 60 s..31 d; default 24 h) opts
+         * the run in to a KEYLESS signed `callback_url` (in the answer and on every
+         * 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;
@@ -2840,11 +2961,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             max_attempts?: number;
             deliver_after?: string;
             delay_seconds?: number;
+            callback?: boolean | {
+                ttl_seconds?: number;
+            };
         }) => Promise<{
             run_id: string;
             state: string;
             deduplicated?: boolean;
             deliver_after?: string;
+            callback_url?: string;
         }>;
         /** Atomic multi-enqueue (≤100 items; any invalid item rejects the whole
          * batch). Each item = the enqueue input, incl. per-item idempotency_key
@@ -2889,7 +3014,12 @@ 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)`). */
         generation: (input: {
             job_name: string;
             provider: {
@@ -2916,11 +3046,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 /** dotted path of the value a completed run settles with (mirrored as `result`) */
                 result_path?: string;
             };
+            /** `progress_fields`: the progress keys (`progress` / `stage` /
+             *  `message`) a webhook-mode `processing` callback also writes onto the
+             *  mirrored record — realtime clients of that record see them live */
             status_mirror?: {
                 feature: string;
                 collection: string;
                 record_id: string;
                 column?: string;
+                progress_fields?: Array<"progress" | "stage" | "message">;
             };
             timeout?: {
                 after_ms: number;
@@ -2988,12 +3122,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         }>;
         /**
          * Suspend the RUNNING run until an event (call from the executing
-         * handler, then return 200 — the suspension wins).
+         * handler, then return 200 — the suspension wins). `state: 'resumed'` =
+         * the event already fired (continue; `wakeup` is its payload). A run
+         * enqueued with `callback` also gets its `callback_url`: an external worker
+         * POSTing it wakes this wait with no API key.
          */
         wait: (runId: string, input: {
             event: string;
             timeout_seconds?: number;
-        }) => Promise<void>;
+        }) => Promise<{
+            run_id: string;
+            state: "waiting" | "resumed";
+            event: string;
+            wakeup?: unknown;
+            callback_url?: string;
+        }>;
         /** Wake every run waiting on the event. */
         emitEvent: (event: string, payload?: Record<string, unknown>) => Promise<number>;
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
@@ -4708,7 +4851,9 @@ 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). */
+        /** Aggregate storage usage vs quotas (the FilesManager Storage panel).
+         *  `public_assets` = published copies vs the plan's published-bytes ceiling
+         *  (identical bytes count once). */
         usage: () => Promise<{
             usage: {
                 object_count: number;
@@ -4720,7 +4865,46 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 maxTotalBytes?: number;
             };
             available: Record<string, number | null>;
+            public_assets?: {
+                enabled: boolean;
+                published_objects: number;
+                published_bytes: number;
+                max_published_bytes: number;
+                bytes_remaining: number;
+            };
+        }>;
+        /** 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
+         *  edge cache with `Cache-Control: public, max-age=31536000, immutable`,
+         *  playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
+         *  `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
+         *  mp4/webm, mp3/m4a/ogg, woff2/woff, json — never HTML or SVG (422
+         *  `content_type_not_publishable`). Counts against the plan's
+         *  published-bytes ceiling (422 `quota_exceeded`). Idempotent: an already
+         *  published object answers its existing URL. Emits
+         *  `files.object.published`. */
+        publish: (objectId: string) => Promise<PublishedFile>;
+        /** SERVER-ONLY. Publish up to 100 objects (about 2 GiB of bytes) in one
+         *  call; a bad id lands in `errors[]` without failing the rest (ids past
+         *  the byte budget as `batch_budget_exceeded` — send them again),
+         *  `published[]` keeps your order. */
+        publishMany: (objectIds: string[]) => Promise<{
+            published: PublishedFile[];
+            errors: Array<{
+                object_id: string;
+                code: PublishErrorCode;
+                message: string;
+            }>;
         }>;
+        /** SERVER-ONLY. Take an object off the public asset host. Its public copy
+         *  is deleted once no other object of yours has the same bytes, and the
+         *  edge cache stops serving it within about a minute and a half (a
+         *  browser that already downloaded it keeps its copy). Deleting the object
+         *  unpublishes it too. 404 when it is not published; 503
+         *  `unpublish_failed` when the public copy could not be removed right
+         *  then (it stays published — retry). Emits `files.object.unpublished`. */
+        unpublish: (objectId: string) => Promise<void>;
         /** OCR / text extraction (guide ch. 6, files, BYO-key add-on). Small/mock inputs
          *  extract inline (status `available`); large inputs (or `async:true`) return
          *  202 with a `job_id` — poll `getText()`. */

package/dist/index.js

@@ -182,6 +182,36 @@ export async function listCmsPublic(tenantId, collection, query, opts) {
     }
     return parsed.data ?? { items: [], next_cursor: null };
 }
+/** POST a run's single-use signed `callback_url` (guide ch. 6, "Hand a run to
+ *  an external worker") — KEYLESS: no API key, no `Vxil` client; the URL is the
+ *  credential, so call this from the worker that finishes the job (a render
+ *  farm, a GPU box, another queue's task). Idempotent: a repeat of a used URL
+ *  answers `deduplicated: true`. A non-2xx throws `VxilError` (401 a forged or
+ *  altered URL, 410 `callback_expired`, 413 `result_too_large`, 404 a run that
+ *  did not opt in). */
+export async function postRunCallback(callbackUrl, body, opts) {
+    const fetchImpl = opts?.fetch ?? fetch;
+    const res = await fetchImpl(callbackUrl, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text();
+    let parsed = {};
+    if (text.length > 0) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new VxilError(res.status, `http_${res.status}`, text.slice(0, 200), undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
+        }
+    }
+    if (!res.ok || parsed.error || !parsed.data) {
+        const e = parsed.error ?? { code: `http_${res.status}`, message: text.slice(0, 200) };
+        throw new VxilError(res.status, e.code, e.message, e.hint, e.fixUrl, parsed.meta?.request_id, parseRetryAfter(res.headers.get('retry-after')));
+    }
+    return parsed.data;
+}
 export class Vxil {
     base;
     key;
@@ -651,7 +681,14 @@ export class Vxil {
     jobs = {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
-         * two) defer the first delivery; > 12 h returns state 'delayed'. */
+         * two) defer the first delivery; > 12 h returns state 'delayed'.
+         *
+         * `callback: true` (or `{ ttl_seconds }`, 60 s..31 d; default 24 h) opts
+         * the run in to a KEYLESS signed `callback_url` (in the answer and on every
+         * 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: 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
@@ -681,7 +718,12 @@ 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`. */
+         * 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)`). */
         generation: async (input) => (await this.call('POST', '/v1/jobs/generation', input)).data,
         runs: async (q) => {
             const s = qs({
@@ -717,11 +759,12 @@ export class Vxil {
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
         /**
          * Suspend the RUNNING run until an event (call from the executing
-         * handler, then return 200 — the suspension wins).
+         * handler, then return 200 — the suspension wins). `state: 'resumed'` =
+         * the event already fired (continue; `wakeup` is its payload). A run
+         * enqueued with `callback` also gets its `callback_url`: an external worker
+         * POSTing it wakes this wait with no API key.
          */
-        wait: async (runId, input) => {
-            await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/wait`, input);
-        },
+        wait: async (runId, input) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/wait`, input)).data,
         /** Wake every run waiting on the event. */
         emitEvent: async (event, payload) => (await this.call('POST', '/v1/jobs/events', { event, ...(payload ? { payload } : {}) })).data.woken,
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
@@ -1733,8 +1776,37 @@ export class Vxil {
         delete: async (objectId) => {
             await this.call('DELETE', `/v1/files/${encodeURIComponent(objectId)}`);
         },
-        /** Aggregate storage usage vs quotas (the FilesManager Storage panel). */
+        /** Aggregate storage usage vs quotas (the FilesManager Storage panel).
+         *  `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,
+        /** 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
+         *  edge cache with `Cache-Control: public, max-age=31536000, immutable`,
+         *  playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
+         *  `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
+         *  mp4/webm, mp3/m4a/ogg, woff2/woff, json — never HTML or SVG (422
+         *  `content_type_not_publishable`). Counts against the plan's
+         *  published-bytes ceiling (422 `quota_exceeded`). Idempotent: an already
+         *  published object answers its existing URL. Emits
+         *  `files.object.published`. */
+        publish: async (objectId) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/publish`)).data,
+        /** SERVER-ONLY. Publish up to 100 objects (about 2 GiB of bytes) in one
+         *  call; a bad id lands in `errors[]` without failing the rest (ids past
+         *  the byte budget as `batch_budget_exceeded` — send them again),
+         *  `published[]` keeps your order. */
+        publishMany: async (objectIds) => (await this.call('POST', '/v1/files/publish', { object_ids: objectIds })).data,
+        /** SERVER-ONLY. Take an object off the public asset host. Its public copy
+         *  is deleted once no other object of yours has the same bytes, and the
+         *  edge cache stops serving it within about a minute and a half (a
+         *  browser that already downloaded it keeps its copy). Deleting the object
+         *  unpublishes it too. 404 when it is not published; 503
+         *  `unpublish_failed` when the public copy could not be removed right
+         *  then (it stays published — retry). Emits `files.object.unpublished`. */
+        unpublish: async (objectId) => {
+            await this.call('DELETE', `/v1/files/${encodeURIComponent(objectId)}/publish`);
+        },
         /** OCR / text extraction (guide ch. 6, files, BYO-key add-on). Small/mock inputs
          *  extract inline (status `available`); large inputs (or `async:true`) return
          *  202 with a `job_id` — poll `getText()`. */

package/package.json

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