@vxil/sdk 0.13.0 → 0.14.0

package/dist/index.js

@@ -3,7 +3,7 @@
 // (code/message/hint/fixUrl + request id) so callers — humans or agents —
 // can self-correct.
 /** The released API majors, as a CLOSED union — one per released major (docs/
- *  feature-versioning.md §3). `'v1'` is the only released major, so pinning
+ *  guide ch. 5). `'v1'` is the only released major, so pinning
  *  anything else (`apiVersion: 'v2'`) is a COMPILE error until a v2 GAs and
  *  widens this union. Every path the SDK builds is major-versioned; the default
  *  is the compile-time constant `'v1'` (never a floating `latest` alias). */
@@ -136,7 +136,7 @@ function resolveBase(explicit) {
     return (explicit ?? envBase ?? DEFAULT_BASE).replace(/\/$/, '');
 }
 /** Build the anonymous, KEYLESS public-delivery URL for a collection's PUBLISHED
- *  items (roadmap §4.4) — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
+ *  items (guide ch. 4, "Draft and publish") — `{base}/v1/cms/public/:tenantId/:collection[?…]`. This is
  *  the reader path a public blog/storefront/docs site hits with NO api key: the
  *  edge mints a restricted read-only inner token bound to the URL tenant, forces
  *  `status='published'`, and strips the collection's owner_field. PURE (no
@@ -155,7 +155,7 @@ export function cmsPublicUrl(tenantId, collection, query, opts) {
     return `${base}${path}${s}`;
 }
 /** Fetch a page of a collection's PUBLISHED items over the KEYLESS public lane
- *  (roadmap §4.4) — NO api key, no `Vxil` client, no auth of any kind. This is the
+ *  (guide ch. 4) — NO api key, no `Vxil` client, no auth of any kind. This is the
  *  anonymous reader path (a blog/storefront/docs front-end). Returns the same
  *  `{ items, next_cursor }` envelope the authed list does, but rows are stripped
  *  to the public surface (`CmsPublicRow`) — drafts and the owner_field are never
@@ -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;
@@ -254,7 +284,7 @@ export class Vxil {
     static connect(opts) {
         return new Vxil(opts);
     }
-    /** Typed per-collection CMS handle (design §4.8). A thin wrapper over the
+    /** Typed per-collection CMS handle (guide ch. 5). A thin wrapper over the
      *  generic `cms.items.*` methods — the wire calls are identical; the generated
      *  `VxilSchema` supplies the field types. `vx.cms.items.*` stays as the
      *  always-available un-generic fallback. */
@@ -291,7 +321,7 @@ export class Vxil {
             rank: (q) => this.cms.items.rank(c, q),
         };
     }
-    /** Typed function invoke (design §4.5). `vx.fn.<name>(payload)` POSTs to
+    /** Typed function invoke (guide ch. 8). `vx.fn.<name>(payload)` POSTs to
      *  /v1/fn/<name>; the generated `VxilSchema` types Input/Output (Level-0
      *  opaque until a function declares a signature). A Proxy gives the
      *  `vx.fn.<name>` accessor shape without enumerating names at runtime.
@@ -359,7 +389,7 @@ export class Vxil {
         });
         // An empty body on a 2xx is a valid "no content" success (e.g. 204 from
         // DELETE/markRead) — never an error. Only parse when there are bytes; a
-        // void-returning caller ignores `data` anyway. (audit #115)
+        // void-returning caller ignores `data` anyway.
         let parsed = {};
         if (text.length > 0) {
             try {
@@ -395,7 +425,7 @@ export class Vxil {
          * (email/display_name/avatar_url/attributes) is scrubbed, while the id is
          * kept so cross-feature references stay intact. NOTE: a full account-delete
          * flow also calls the auth half — POST /v1/auth/users/:id/erase — to erase
-         * the credential/session identity (see features/tenant-users.md §3).
+         * the credential/session identity (see guide ch. 6, auth).
          */
         delete: async (id, opts) => {
             await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`);
@@ -497,7 +527,7 @@ export class Vxil {
          *  does not cover them, so an "unsubscribe from everything" click can never
          *  lock a user out of its own account. Muteable ids: `welcome`,
          *  `transactional`. (Password-reset mail rides `transactional`, which stays
-         *  muteable — see the notifications feature doc §6c.)
+         *  muteable — see guide ch. 6, notifications.)
          *
          *  SCOPES: with an end-user token both calls are confined to the verified
          *  principal and take `notifications:read` (a browser key that can mute its
@@ -524,7 +554,7 @@ export class Vxil {
         },
         /** A single delivery by id (the list is `deliveries()`). */
         delivery: async (deliveryId) => (await this.call('GET', `/v1/notifications/deliveries/${encodeURIComponent(deliveryId)}`)).data,
-        /** Email broadcast campaigns (notifications.md §11b): audience-ref fan-out
+        /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
          *  send (status `scheduled`); omit it for a `draft`. */
         campaigns: {
@@ -557,12 +587,12 @@ export class Vxil {
         /** The tenant's enabled-feature summary (GET /v1/features). Privilege-
          * independent: any valid key may read it — it leaks no secrets, only which
          * features the tenant has turned on. Mirrors what the MCP tool-list
-         * aggregation sees. (audit #113) */
+         * aggregation sees. */
         list: async () => (await this.call('GET', '/v1/features')).data.features,
         /** The FULL enabled-feature summary: `features` + `api_versions` (released
          * API majors per feature) + the additive `key` block — the CALLING key's
          * identity and per-tool MCP permissions (allowed_tools/denied_tools
-         * patterns, api_keys 0057; mcp.md §6.7). `key` is absent for non-key
+         * patterns; guide ch. 10). `key` is absent for non-key
          * callers and for keys without explicit tool perms. `list()` stays the
          * stable flat-array shorthand. */
         summary: async () => (await this.call('GET', '/v1/features')).data,
@@ -610,7 +640,7 @@ export class Vxil {
             if (!res.ok) {
                 // Preserve the structured error envelope on failure — the export path
                 // is hand-rolled (no this.call), so without this a 403/429 would lose
-                // its code/hint/requestId. (audit #119)
+                // its code/hint/requestId.
                 let env = {};
                 try {
                     env = JSON.parse(text);
@@ -621,7 +651,7 @@ export class Vxil {
             }
             // Skip blank lines AND tolerate a single malformed NDJSON line rather
             // than aborting the whole batch (e.g. a truncated final line on a large
-            // page) — collect parse failures so the caller can decide. (audit #116)
+            // page) — collect parse failures so the caller can decide.
             const events = [];
             const parseErrors = [];
             text.split('\n').forEach((l, i) => {
@@ -651,13 +681,20 @@ 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
          * 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,
-        /** Enqueue a long-running EXTERNAL generation run (jobs.md §11): Vxil calls
+        /** 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
          * (on failure) fires the payments credit-reversal.
@@ -666,7 +703,7 @@ export class Vxil {
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
          * status NOW (`processing`, `completed` or `failed` too).
          *
-         * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
+         * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
          * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
@@ -717,11 +754,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. */
@@ -1059,7 +1097,7 @@ export class Vxil {
         check: async (input) => (await this.call('POST', '/v1/rate-limits/check', input)).data,
         /** Per-identifier overrides layered over a policy: `pattern` matches the
          *  RENDERED key (exact, or a `*`-glob where the longest literal prefix
-         *  wins). Propagates to the check path within ≤30s (KV cacheTtl). */
+         *  wins). Propagates to the check path within ≤30s (cache TTL). */
         overrides: {
             list: async (policyId) => (await this.call('GET', `/v1/rate-limits/policies/${encodeURIComponent(policyId)}/overrides`)).data.overrides,
             create: async (policyId, input) => (await this.call('POST', `/v1/rate-limits/policies/${encodeURIComponent(policyId)}/overrides`, input)).data,
@@ -1078,7 +1116,7 @@ export class Vxil {
             addField: async (collection, field) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, field);
             },
-            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (cms.md §18) —
+            /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
              *  the same-type in-place alter on the fields route. Re-sends the field's
              *  `type` (required by the alter path); every OTHER attribute the field
              *  carries is re-sent from `rest`, because the alter overwrites the whole
@@ -1088,7 +1126,7 @@ export class Vxil {
             setFieldReadRoles: async (collection, field, type, roles, rest = {}) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { ...rest, field, type, read_roles: roles ?? [] });
             },
-            /** Turn a field's EQUALITY INDEX on or off (cms.md §3 "Indexed equality")
+            /** Turn a field's EQUALITY INDEX on or off (guide ch. 4 "Indexed equality")
              *  — the same-type in-place alter on the fields route; `indexed` is
              *  present-key, so no other attribute moves. Only for UNSLOTTED,
              *  non-computed fields, ≤4 per collection (422 `eq_index_budget`).
@@ -1112,11 +1150,11 @@ export class Vxil {
                 }
             },
             /** Set (or clear, with `null`) the collection's end-user owner-scope flag
-             *  (design §5.1). Names an existing `string` field that holds the owner id. */
+             *  (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
             setOwnerField: async (collection, ownerField) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField });
             },
-            /** Toggle the collection's PUBLIC-delivery flag (roadmap §4.4). When `true`,
+            /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
              *  its PUBLISHED items become KEYLESS-readable via the anonymous public lane
              *  (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
              *  the owner_field are never exposed. `false` closes the lane (and purges the
@@ -1125,7 +1163,7 @@ export class Vxil {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
             },
             /** Re-project the collection's index slots after an `index_slot` move
-             *  (cms.md §19). Slots are projected on WRITE only, so until this runs,
+             *  (guide ch. 4). Slots are projected on WRITE only, so until this runs,
              *  stored rows keep their OLD projection: the new slot is NULL and the
              *  VACATED slot still holds the old field's values — range/sort on the
              *  moved field returns the WRONG rows, not merely missing ones. ONE page
@@ -1180,7 +1218,7 @@ export class Vxil {
                 }
                 return { scanned, updated, skipped, pages, ...(indexCertify ? { index_certify: indexCertify } : {}) };
             },
-            /** Replace the collection's per-record ACTION list (cms.md §17) — the
+            /** Replace the collection's per-record ACTION list (guide ch. 4) — the
              *  `{ actions }` fields-route meta-op; `[]` clears. Each action is ONE
              *  human-initiated step: the dashboard renders it as a button per record,
              *  and `items.runAction` invokes its deployed function. */
@@ -1189,10 +1227,10 @@ export class Vxil {
             },
         },
         items: {
-            /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
-             *  is the declarative capacity/overlap invariant (requires lock) — cms.md §10. */
+            /** `lock` serializes same-key writers (a per-key lock); `guard`
+             *  is the declarative capacity/overlap invariant (requires lock) — guide ch. 4. */
             create: async (collection, input) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input)).data,
-            /** `expand` inlines relation/file fields into `data` (cms.md §6.2): the
+            /** `expand` inlines relation/file fields into `data` (guide ch. 4): the
              *  full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
              *  the bare id on a cycle/depth cut, `null` for an invisible target. */
             get: async (collection, itemId, opts) => {
@@ -1224,9 +1262,9 @@ export class Vxil {
                 });
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s}`)).data;
             },
-            /** Merge-patch data keys; null clears a key. Concurrency opts (cms.md §9):
+            /** Merge-patch data keys; null clears a key. Concurrency opts (guide ch. 4):
              *  `ifVersion` → If-Match CAS; `if` → bounded field precondition against
-             *  the locked row; `lock`/`guard` → the §10 serialization primitives. */
+             *  the locked row; `lock`/`guard` → the write-serialization primitives (guide ch. 4). */
             patch: async (collection, itemId, data, opts) => (await this.call('PATCH', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, {
                 data,
                 ...(opts?.if ? { if: opts.if } : {}),
@@ -1237,18 +1275,18 @@ export class Vxil {
             /** Atomic in-database increment — PATCH `{ $inc: {field: delta} }`, ONE
              *  conditional UPDATE guarded by the field's validation min/max (the quota
              *  shape), the optional `if` precondition, and If-Match. 409
-             *  inc_out_of_bounds when the guard refuses (cms.md §9.3). */
+             *  inc_out_of_bounds when the guard refuses (guide ch. 4). */
             inc: async (collection, itemId, incs, opts) => (await this.call('PATCH', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, { $inc: incs, ...(opts?.if ? { if: opts.if } : {}) }, opts?.ifVersion !== undefined ? { 'if-match': String(opts.ifVersion) } : {})).data,
-            /** `{ count }` under the same bounded filter grammar (cms.md §9.4). 422
+            /** `{ count }` under the same bounded filter grammar (guide ch. 4). 422
              *  count_unavailable_with_read_hooks on beforeRead-hooked collections. */
             count: async (collection, filter) => {
                 const s = qs({ count: 'true', filter: filter ? JSON.stringify(filter) : undefined });
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s}`)).data.count;
             },
-            /** Returns the cascade tally (cms.md §11); `ifVersion` rides If-Match and
+            /** Returns the cascade tally (guide ch. 4); `ifVersion` rides If-Match and
              *  a conflict aborts BEFORE any cascade side-effect. */
             delete: async (collection, itemId, opts) => (await this.call('DELETE', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}`, undefined, opts?.ifVersion !== undefined ? { 'if-match': String(opts.ifVersion) } : {})).data,
-            /** N-22 (cms.md §20): BOUNDED FILTERED delete — soft-delete up to `limit`
+            /** BOUNDED FILTERED delete — soft-delete up to `limit`
              *  items (1–100, default 25) matching `filter`, newest id first. A filter
              *  is REQUIRED (an unselected sweep is refused 422). Each matched row runs
              *  the SAME single-item delete path (restrict refusal, cascade budget,
@@ -1268,7 +1306,7 @@ export class Vxil {
                 ...(q.dryRun !== undefined ? { dry_run: q.dryRun } : {}),
             })).data,
             publish: async (collection, itemId) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/publish`)).data,
-            /** P1-12 (cms.md §11.1): the BOUNDED reverse read — which live items
+            /** The BOUNDED reverse read — which live items
              *  reference this one, through which relation field. Owner-scoped in
              *  end-user mode like `get`. `count` is the page returned (≤ limit, max
              *  100), never a total; `has_more` says the cap was hit. A DELETE refused
@@ -1278,19 +1316,19 @@ export class Vxil {
                 const qs = opts?.limit !== undefined ? `?limit=${encodeURIComponent(String(opts.limit))}` : '';
                 return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/backlinks${qs}`)).data;
             },
-            /** P1-7 (cms.md §17): run ONE declared per-record action — invokes the
+            /** Run ONE declared per-record action — invokes the
              *  action's deployed function with `{ collection, item_id, action, actor,
              *  item }` and returns its result. 404 when the key is not declared;
              *  502 `action_failed` (with `upstream.code` = the function's error
              *  class) when the function fails. Requires cms:write. */
             runAction: async (collection, itemId, key) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/${encodeURIComponent(itemId)}/actions/${encodeURIComponent(key)}`)).data,
-            /** cms-rel B2 (cms.md §12): bounded group-by aggregate. fns count|sum|
+            /** Bounded group-by aggregate. fns count|sum|
              *  min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
              *  fields; filter = the full query DSL incl. ONE-hop dotted join terms
              *  ({"channel.visibility":"public"}); scan capped at 50k rows → 422
              *  window_too_large (narrow the window or materialize a read-model). */
             aggregate: async (collection, body) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/aggregate`, body)).data,
-            /** cms-rel B3 (cms.md §12): window ranking over the aggregate — rank ∈
+            /** Window ranking over the aggregate — rank ∈
              *  row_number|rank|percent_rank, computed over ≤500 aggregated groups
              *  (never raw rows), optional partitionBy. Same scan cap as aggregate. */
             rank: async (collection, body) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}/rank`, body)).data,
@@ -1304,13 +1342,13 @@ export class Vxil {
              *  merge, the event is the backstop. Emits one `cms.items.rekeyed`. */
             reKey: async (input) => (await this.call('POST', '/v1/cms/items/re-key', input)).data,
         },
-        /** cms-rel B4 (cms.md §13): atomic multi-collection transaction — 1–5
+        /** Atomic multi-collection transaction — 1–5
          *  steps over ≤3 collections, per-step `$where` CAS preconditions (the
          *  PATCH `if` grammar). All-or-nothing: any failed precondition/validation
          *  rolls the WHOLE transaction back (409 precondition_failed names the
          *  step). cms-internal only — no cross-feature effects inside the tx. */
         transaction: async (steps) => (await this.call('POST', '/v1/cms/transactions', { steps })).data,
-        /** P1-1 (cms.md §21): several get / query / create / patch / delete ops in
+        /** Several get / query / create / patch / delete ops in
          *  ONE round trip — the function-chain shape ("read 3 rows → patch 2 →
          *  create 1" is one call, not six). ≤25 ops, each run through the SAME path
          *  its single route uses (scopes, owner-scoping, hooks, guards, `if`,
@@ -1325,7 +1363,7 @@ export class Vxil {
             ops: ops.map((o) => ('expand' in o && o.expand !== undefined ? { ...o, expand: expandParam(o.expand) } : o)),
             ...(opts?.atomic !== undefined ? { atomic: opts.atomic } : {}),
         })).data,
-        /** cms-rel B5 (cms.md §12.4): declared read-models (config `readModels`
+        /** Declared read-models (config `readModels`
          *  bag) — list with last-run status, and "run now" materialization into
          *  the rollup collection. */
         readModels: {
@@ -1373,7 +1411,7 @@ export class Vxil {
         /** Read the resolved DM config (defaults merged with the stored partial). */
         getConfig: async () => (await this.call('GET', '/v1/dm/config')).data,
         /** Write the DM master config — a partial merge (omitted leaves keep their
-         *  current value), version-bumped and republished to the gate's KV key. */
+         *  current value), version-bumped and republished to the gate's cache. */
         setConfig: async (patch) => (await this.call('PUT', '/v1/dm/config', patch)).data,
         conversations: {
             /** Open (or, for a direct pair, return the existing) conversation. A
@@ -1436,7 +1474,7 @@ export class Vxil {
     /** The MCP aggregation surface (the `mcp` feature). */
     mcp = {
         /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
-         *  MCP tool calls (mcp.md §6.5) — the mirror of jobs.signingSecret(). */
+         *  MCP tool calls (guide ch. 10) — the mirror of jobs.signingSecret(). */
         signingSecret: async () => (await this.call('GET', '/v1/mcp/signing-secret')).data.signing_secret,
     };
     /**
@@ -1521,7 +1559,7 @@ export class Vxil {
             markAll: async (userId) => this.feedsMark(userId, 'read'),
             /** Archive/dismiss groups (hidden from inbox + dropped from the badge). */
             archive: async (userId, scope) => this.feedsMark(userId, 'archive', scope),
-            /** The badge: { unseen, unread, total } (KV-cached over the authority). */
+            /** The badge: { unseen, unread, total } (cached, recomputed on a miss). */
             unreadCount: async (userId) => (await this.call('GET', `/v1/feeds/notification/${encodeURIComponent(userId)}/count`)).data,
         },
         /**
@@ -1649,7 +1687,7 @@ export class Vxil {
             /** List an org's pending invitations. */
             list: async (orgId) => (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`)).data.invitations,
         },
-        /** Custom tenant roles (permission-sets; migration orgs/0019). A custom role
+        /** Custom tenant roles (permission-sets). A custom role
          *  is a named set of permissions assignable like any built-in; the four
          *  built-ins reproduce the fixed owner>admin>member>viewer lattice. */
         roles: {
@@ -1662,7 +1700,7 @@ export class Vxil {
                 await this.call('DELETE', `/v1/orgs/roles/${encodeURIComponent(roleKey)}`);
             },
         },
-        /** Per-org/user resource ACL grants (migration orgs/0019): grant a permission
+        /** Per-org/user resource ACL grants: grant a permission
          *  on a specific resource string; `check(...,{ resource })` consults them. */
         acl: {
             grant: async (orgId, input) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/acl`, input)).data,
@@ -1733,9 +1771,38 @@ 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,
-        /** OCR / text extraction (files.md §1.1, BYO-key add-on). Small/mock inputs
+        /** 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()`. */
         extractText: async (objectId, opts) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/extract-text`, opts ?? {})).data,
@@ -1818,7 +1885,7 @@ export class Vxil {
      * The AI substrate (the `ai` feature): store prompt TEMPLATES (config-as-code),
      * then generate (sync or streamed) and embed across providers. 'mock' is the
      * deterministic default; the real providers (openai/anthropic/gemini/azure/
-     * openrouter) route via BYO keys in tenant_secrets. `images` on the generate
+     * openrouter) route via BYO keys in your project secrets. `images` on the generate
      * inputs takes up to 8 vision refs: a public https:// URL, a
      * data:image/...;base64 URL, or file:<object_id> (a files-feature object) —
      * fetched images are capped at 4 MiB each; `documents` (pdf/text, ≤10 MiB
@@ -1878,7 +1945,7 @@ export class Vxil {
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
         remintToken: async (generationId) => (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}/token`)).data,
         /** Resume a streamed generation after a dropped socket: every recorded frame
-         *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
+         *  with seq > `since` plus `done` (the replay buffer — plain JSON, not
          *  an SSE stream; the buffer lives 1 h). A settled JOB-lane generation is
          *  served from its stored answer instead (30 days). `status` says where the
          *  generation is; `expired: true` means it settled but its frames are gone
@@ -1929,7 +1996,7 @@ export class Vxil {
         /** Streamed grounded answer: citations + the channel handle up front, tokens
          *  over the realtime channel. */
         stream: async (input) => (await this.call('POST', '/v1/rag/answer', { ...input, stream: true })).data,
-        /** Retrieval-only grounding preview (rag.md §1c): the exact chunks `answer`
+        /** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
          *  would ground on, with rerank + metadata boosts applied — no generation,
          *  no token spend. `boosts`/`rerank`/`min_score` override the rag config.
          *  `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
@@ -2028,7 +2095,7 @@ export class Vxil {
          *  `quota` inlines one quota, `creditType` inlines the same owner-bound
          *  balance `getBalance` returns — ONE call for a thin client's paywall.
          *  A non-2xx answer means UNKNOWN: render the last cached answer, never
-         *  free (payments.md §3a).
+         *  free (guide ch. 6, payments).
          *
          *  OVERLAPPING SUBSCRIPTIONS — what `until` means. The WINNER is the
          *  entitled subscription with the highest `tierMap[tier].rank` (default 0);
@@ -2114,14 +2181,14 @@ export class Vxil {
             return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;
         },
         /**
-         * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
+         * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
          * the returned `url`; completion lands server-side via the provider webhook
          * (the matching session flips to completed, the charge/grant is folded).
          * Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
          */
         createCheckoutSession: async (input, opts) => (await this.call('POST', '/v1/payments/checkout-sessions', input, { 'idempotency-key': opts.idempotencyKey })).data,
         /**
-         * Refund a charge at-most-once (payments.md §6a). Omit `amount_cents` to
+         * Refund a charge at-most-once (guide ch. 6, payments). Omit `amount_cents` to
          * refund the full un-refunded remainder. Idempotency-Key REQUIRED — a retry
          * replays the recorded refund (never a second provider refund); a refund can
          * NEVER exceed the charge (422 refund_exceeds_charge).
@@ -2241,7 +2308,7 @@ export class Vxil {
             });
             return (await this.call('GET', `/v1/payments/refunds${suffix}`)).data;
         },
-        /** Provider webhook event log (payments.md §7 "Event log & replay"):
+        /** Provider webhook event log (guide ch. 6, payments "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read
          *  (reprocess: payments:write).
@@ -2276,5 +2343,5 @@ export class Vxil {
     };
 }
 // Failure reporting for tenant functions — the Sentry-envelope forwarder
-// (roadmap §4.11 P0-4e). Zero dependencies; see reporting.ts.
+// (guide ch. 8). Zero dependencies; see reporting.ts.
 export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, } from './reporting.js';

package/dist/qs.js

@@ -1,5 +1,5 @@
 // Query-string builder — the SDK's replacement for the WHATWG `URLSearchParams`
-// at every call site (F7-44, the React-Native-clean SDK).
+// at every call site (the React-Native-clean SDK).
 //
 // WHY (implementation note; `//` comments never reach the shipped .d.ts):
 // React Native supplies its own URLSearchParams polyfill, and up to RN 0.79

package/dist/reporting.js

@@ -1,6 +1,5 @@
 // withReporting — forward a tenant function's failure to the tenant's OWN
-// error reporter over the Sentry envelope HTTP format (roadmap §4.11 P0-4e,
-// techmaker evaluation P0-5's "SDK half", 2026-09-23).
+// error reporter over the Sentry envelope HTTP format.
 //
 // NOT a Sentry SDK and NOT a dependency on one: the function sandbox is
 // Web-standard fetch/crypto only, so this is the plain ingestion envelope

package/dist/retry.js

@@ -1,6 +1,6 @@
 // The request seam: retry + timeout + hooks around the ONE `fetch` every SDK
-// request goes through (parity P1 #9), and the `Retry-After` parser
-// `VxilError.retryAfter` shares (F7-44). DEFAULT OFF — with no `retry`,
+// request goes through, and the `Retry-After` parser
+// `VxilError.retryAfter` shares. DEFAULT OFF — with no `retry`,
 // `timeoutMs` or `hooks` option the transport is a single `fetch` + `text()`,
 // exactly what `call()` did before.
 //

package/package.json

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