@vxil/sdk 0.17.0 → 0.19.0

package/dist/index.js

@@ -429,9 +429,23 @@ export class Vxil {
         return { data: parsed.data, meta: parsed.meta ?? { request_id: '' }, response: res };
     }
     users = {
+        /** Create or replace a tenant user by id. Upserting a deleted id brings it
+         *  back; upserting an ERASED id re-creates it as a new, empty user
+         *  (`erased_at` cleared — the erase already removed the old data). While
+         *  the erased user's files are still being erased the call fails with 409
+         *  `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
         upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
         bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
         get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
+        /**
+         * Update a user. `email` / `display_name` / `avatar_url` are replaced
+         * (null clears them). `attributes` is DEEP-MERGED into the stored
+         * attributes (RFC 7396 merge patch): objects merge key by key, arrays and
+         * scalars replace, and `null` deletes a key AT ANY DEPTH — including inside
+         * a subtree the row does not have yet, where the null is simply dropped
+         * (`{ attributes: { prefs: { phone: null } } }` never stores a null).
+         * Scope users:write.
+         */
         patch: async (id, patch) => (await this.call('PATCH', `/v1/users/${encodeURIComponent(id)}`, patch)).data,
         /**
          * Delete a user. By default this is a SOFT delete (sets deleted_at; the PII
@@ -449,7 +463,7 @@ export class Vxil {
          * Merge a REGISTRY-ONLY user (a row you created with upsert that never
          * signed in) INTO another user of the tenant: its attributes fill the
          * survivor's gaps (the survivor wins on conflicts), the merged id is
-         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * soft-deleted, its owner-scoped cms / files / payments / jobs rows move to the
          * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
          * is audited. `rekeyed: false` means a re-key could not finish inside the
          * request — the event is the backstop (call the feature's re-key route
@@ -567,7 +581,8 @@ export class Vxil {
                 await this.call('POST', `/v1/notifications/dead-letters/${encodeURIComponent(deliveryId)}/replay`);
             },
         },
-        /** A single delivery by id (the list is `deliveries()`). */
+        /** A single delivery by id (the list is `deliveries()`), with its render —
+         *  the full one for a `test_sink` row (see `DeliveryDetail`). */
         delivery: async (deliveryId) => (await this.call('GET', `/v1/notifications/deliveries/${encodeURIComponent(deliveryId)}`)).data,
         /** Email broadcast campaigns (guide ch. 6, notifications): audience-ref fan-out
          *  with quiet-hours + frequency-cap policy. `schedule_cron` sets a recurring
@@ -628,12 +643,24 @@ export class Vxil {
             ...(opts?.brief === false ? { brief: false } : {}),
         })).data,
     };
+    /** The project audit log. Needs `audit:read` (the narrow read-only scope —
+     *  declare it on a function to read the log from its callback token) or
+     *  `features:read`. Server-only: a public / thin-client key cannot read it. */
     audit = {
+        /**
+         * The audit trail, newest first. `subject` narrows to the events about ONE
+         * thing: a user id (`payload.user_id` / `payload.id`), a cms record
+         * (`payload.item_id` — the record's history), a verified end user
+         * (`payload.end_user_id` — what that person changed through a thin-client
+         * key or a function acting for them, and their payments events), or a
+         * principal (`actor`). Server keys only.
+         */
         list: async (q) => {
             const s = qs({
                 since: q?.since || undefined,
                 cursor: q?.cursor || undefined,
                 limit: q?.limit || undefined,
+                subject: q?.subject || undefined,
             });
             return (await this.call('GET', `/v1/audit${s}`)).data.events;
         },
@@ -647,6 +674,7 @@ export class Vxil {
                 until: q?.until || undefined,
                 after_id: q?.after_id || undefined,
                 limit: q?.limit || undefined,
+                subject: q?.subject || undefined,
             });
             const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/audit/export${s}`)}`, {
                 method: 'GET',
@@ -756,7 +784,16 @@ export class Vxil {
          *
          * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
          * of the same `idempotency_key` (`deduplicated: true`) carries the run's
-         * status NOW (`processing`, `completed` or `failed` too).
+         * status NOW (`processing`, `completed` or `failed` too). The key is bound
+         * to the request BODY: re-sending it with a different body (another
+         * payload — a rebuilt `deadline_at` included —, provider, completion,
+         * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
+         * original run (the ai-v1 rule). That check is being rolled out: today a
+         * mismatch is only logged, on every project, and the send is still
+         * deduplicated to the first run; a changelog entry will announce
+         * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
+         * (Retry-After 5) means the run that key names is still placing its
+         * credit hold.
          *
          * `reserve_credits` takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
@@ -764,7 +801,8 @@ export class Vxil {
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
          * 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
+         * `ReserveInsufficient` and the 402 names its `run_id`; the key is released,
+         * so the same request after a top-up starts a new run); a runaway over the
          * 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
@@ -785,8 +823,9 @@ export class Vxil {
          *
          * `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
+         * `queue_full`), a 503 `payments_unavailable` / `enqueue_interrupted` and a
+         * 409 `generation_in_progress` (the key's run is still placing its credit
+         * hold), 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) => {
@@ -835,13 +874,45 @@ export class Vxil {
         /** 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. */
+         *  consumed). A generation's credit hold is released — a STARTED
+         *  generation's too (its provider accepted it): it ends `failed`
+         *  (`Cancelled`) and a late provider callback is a no-op, but the provider
+         *  is NOT told, so its work and its charge may still complete. A plain
+         *  `running` run (a delivery in flight), a run waiting on an event, or a
+         *  terminal run answers `409 not_cancellable`. */
         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. */
+         *  `409 not_replayable` — submit the generation again instead; a redacted
+         *  or erased run answers `409 run_redacted` (its payload is gone). */
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
+        /** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
+         *  credit-hold owner (`reserve_credits.user_id`) of every run of
+         *  `from_user_id`, in any state, onto `into_user_id`, so the surviving
+         *  account reads, cancels and replays the generation runs it started as a
+         *  guest. ONE bounded page (≤500 runs) per call — call again until `done`
+         *  (idempotent: a second call moves 0). The jobs consumer of
+         *  `auth.user.merged { from, into }`; auth and `users.merge` call it after
+         *  a merge, the event is the backstop. Emits one `jobs.runs.rekeyed` when
+         *  a call moved at least one run (none on a zero-move call). Unlike the
+         *  files re-key it does not check that `into_user_id` exists.
+         *  Scope jobs:write. */
+        reKey: async (input) => (await this.call('POST', '/v1/jobs/runs/re-key', input)).data,
+        /** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
+         *  that hold personal data: the payload becomes `{ erased: true }`, the
+         *  result, progress, callback body and error text are cleared, a
+         *  generation's provider request body/headers are dropped and its credit
+         *  hold's user id is pseudonymized (unless its settle is still owed). The
+         *  row itself stays (state, timings, job_name). The same fields a GDPR
+         *  erase clears on the runs it can link to a user — use this for runs
+         *  nothing links to one (a plain queue run, an async function call).
+         *  `{ run_ids }` (≤500, one call; open runs are left alone and counted in
+         *  `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
+         *  names that user — ONE page of ≤500 per call, call again until `done`).
+         *  Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
+         *  call redacted nothing). NOT cleared: concurrency_key, debounce_key,
+         *  idempotency_key and target_url — keep user ids out of those (hash them).
+         *  A redacted run does not replay. Scope jobs:write. */
+        redact: async (input) => (await this.call('POST', '/v1/jobs/runs/redact', input)).data,
         /**
          * Suspend the RUNNING run until an event (call from the executing
          * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -926,9 +997,10 @@ export class Vxil {
              *  existing account; swap tokens). Needs `anonymous.enabled`; a non-guest
              *  bearer is `409 not_anonymous`. */
             request: async (input) => (await this.call('POST', '/v1/auth/magic-link/request', input)).data,
-            /** `opts.anonymous_token` is REQUIRED for a link that was requested with
-             *  one (the guest claim above): the same guest session must present it,
-             *  else `401 invalid_session`. `merged` is true only when the guest was
+            /** An unknown, expired or already-used link answers `401 invalid_token`
+             *  (request a new one with `request`). `opts.anonymous_token` is REQUIRED
+             *  for a link that was requested with one (the guest claim above): the
+             *  same guest session must present it, else `401 invalid_session`. `merged` is true only when the guest was
              *  folded into an existing account (then `user_id` is that account), and
              *  `rekeyed` rides beside it: true ⇒ the guest's payments / cms / files
              *  rows were already moved onto `user_id` when this returned; false ⇒
@@ -958,8 +1030,10 @@ export class Vxil {
                 /** On success the guest keeps its user id (`user_id` unchanged).
                  *  If the claimed email ALREADY has an account, the guest is MERGED
                  *  into it: `user_id` is the existing account, `merged: true`, and a
-                 *  fresh `session.token` (same session, re-signed for the merged
-                 *  identity — swap it client-side; other guest sessions are revoked).
+                 *  fresh `session.token` (the same session carried over to the merged
+                 *  identity under a new session id — swap it client-side: the old
+                 *  guest token is revoked, the refresh token keeps working; other
+                 *  guest sessions are revoked).
                  *  `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
                  *  files rows were already moved onto `user_id` when this returned, so
                  *  the merged user's next request finds them; false ⇒ the move ran
@@ -1026,7 +1100,7 @@ export class Vxil {
             import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
             /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
              *  deep-merges a bounded `attributes` object into its OWN shared identity
-             *  row (null deletes a key; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
+             *  row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
              *  fields are not patchable here. In server mode the call throws 422
              *  `end_user_mode_required` — use `users.patch(id, …)` instead. */
             patchMe: async (attributes) => (await this.call('PATCH', '/v1/auth/users/me', { attributes })).data,
@@ -1145,15 +1219,33 @@ export class Vxil {
             },
             confirm: async (token) => (await this.call('POST', '/v1/auth/email/verify/confirm', { token })).data,
         },
-        /** Social sign-in. The web `start`/`callback` flows are browser redirects
-         *  (not JSON calls): send the browser to
-         *  `GET /v1/auth/oauth/{provider}/start?redirect_uri=…` (server-side, with
-         *  your key) and hand the returned `code`+`state` to `…/callback`; `native`
+        /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
+         *  URL with your key (a browser cannot follow the header-carrying 302 of
+         *  `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
+         *  there, and hand the returned `code`+`state` to `…/callback`; `native`
          *  is the mobile / broker token-exchange the SDK wraps. `oidc` is the
          *  tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
          *  Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
          *  speaks OIDC); it rides the same three routes. */
         oauth: {
+            /** Start the web sign-in from a browser SPA: answers the provider
+             *  `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
+             *  nonce bound to the flow — all held server-side) for you to navigate
+             *  to: `location.assign((await vx.auth.oauth.startUrl('oidc',
+             *  { redirect_uri })).authorize_url)`. The provider returns to
+             *  `redirect_uri` with `?code&state`, which your page sends to
+             *  `GET /v1/auth/oauth/{provider}/callback` for the session. The same
+             *  rules as the redirect form apply: `redirect_uri` must match the auth
+             *  config `security.allowedRedirectOrigins` when set (else
+             *  `422 redirect_not_allowed`), and the state expires after
+             *  `expires_in` seconds (600). `anonymous_token` (a guest bearer)
+             *  promotes or merges that guest at the callback. */
+            startUrl: async (provider, input) => {
+                // plain encodeURIComponent (no URLSearchParams — React Native ≤ 0.79)
+                const q = `redirect_uri=${encodeURIComponent(input.redirect_uri)}`
+                    + (input.anonymous_token ? `&anonymous_token=${encodeURIComponent(input.anonymous_token)}` : '');
+                return (await this.call('GET', `/v1/auth/oauth/${encodeURIComponent(provider)}/start?${q}`, undefined, { accept: 'application/json' })).data;
+            },
             /** Native social sign-in: exchange a provider `id_token`/`access_token`
              *  for a vxil session (`linked` marks whether the user was created or
              *  matched to an existing identity). */
@@ -1164,6 +1256,9 @@ export class Vxil {
              *  (`linked: 'merged'`, `user_id` = that account, `rekeyed` says whether
              *  the guest's owner-scoped rows already moved — see
              *  `anonymous.link.verify`). */
+            /** `nonce`: the value your app put on the IdP authorize request. For
+             *  When sent, the id_token's `nonce` claim must equal it (401
+             *  `oauth_token_invalid` otherwise); omitted, it is not checked. */
             input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
         },
     };
@@ -1274,6 +1369,19 @@ export class Vxil {
              *  (default) restores today's behaviour. Server keys are never affected.
              *  Audited; takes effect on the next request. */
             setEndUserAccess: async (collection, access) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { end_user_access: access })).data,
+            /** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
+             *  ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
+             *  session's verified role claims — orgs roles) to write the collection,
+             *  otherwise every write door answers `403 role_required`. Reads are
+             *  unaffected; server keys are never affected. Audited; takes effect on
+             *  the next write. */
+            setWriteRoles: async (collection, roles) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { write_roles: roles ?? [] })).data,
+            /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
+             *  ch. 4): the nightly platform sweep soft-deletes live items created more
+             *  than `days` ago — bounded per project per night, no restore, purged at
+             *  least 30 days later like any delete, one `cms.collection.retention_swept` audit event
+             *  per collection per sweep. Audited (`cms.collection.retain_days.set`). */
+            setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
             /** Re-project the collection's index slots after an `index_slot` move
              *  (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
@@ -1342,6 +1450,16 @@ export class Vxil {
             /** `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,
+            /** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
+             *  — when a live item already holds `data[field]` — merges `patch` into
+             *  THAT item instead (one transaction; update hooks, guards, version bump
+             *  and a `cms.item.updated` audit, exactly like `patch`; null clears a
+             *  field). `created` tells which happened (201 vs 200). Concurrent upserts
+             *  of one key serialize, so they never create a duplicate. */
+            upsert: async (collection, input) => {
+                const r = await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input);
+                return { ...r.data, created: r.response.status === 201 };
+            },
             /** `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. */
@@ -1351,7 +1469,9 @@ export class Vxil {
             },
             /**
              * The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
-             * $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
+             * ($ne is NULL-safe: a row whose field is absent or null counts as not
+             * equal; on a dotted join term the row still needs a readable target,
+             * so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
              * fields) $arrayContains/$anyOf (json/relation array containment, indexed);
              * range/sort needs slot-indexed fields. This is the
              * DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
@@ -1582,6 +1702,17 @@ export class Vxil {
          * `features:write`. (DELETE /v1/functions/:name)
          */
         delete: async (name, opts) => (await this.call('DELETE', `/v1/functions/${encodeURIComponent(name)}`, undefined, opts?.ifMatch !== undefined ? { 'if-match': String(opts.ifMatch) } : {})).data,
+        /**
+         * Log records of ONE function, one per invocation (outcome, wall/cpu ms,
+         * console lines, exceptions), oldest first. Pass the returned `next_since`
+         * back as `since` to read only newer records (a tail); without it, the most
+         * recent records of the last 24 hours. Kept 14 days. Needs
+         * `functions:read`. (GET /v1/functions/:name/logs)
+         */
+        logs: async (name, opts) => {
+            const s = qs({ since: opts?.since || undefined });
+            return (await this.call('GET', `/v1/functions/${encodeURIComponent(name)}/logs${s}`)).data;
+        },
     };
     /** The MCP aggregation surface (the `mcp` feature). */
     mcp = {
@@ -1720,7 +1851,19 @@ export class Vxil {
          */
         test: async (subId) => (await this.call('POST', `/v1/webhooks/subscriptions/${encodeURIComponent(subId)}/test`)).data,
         sources: {
-            /** Register an inbound source; the receiver URL is returned ONCE. */
+            /** Register an inbound source; the receiver URL is returned ONCE.
+             *
+             * Destination: `forward_url` (your endpoint) OR `target_function` (a
+             * deployed function that declares a bare `trigger: { kind: 'webhook' }`
+             * binding — it receives `payload.event === 'inbound_webhook.received'`
+             * with the inbound envelope as `payload.data`), never both; neither =
+             * store only (read with `events.list`).
+             *
+             * `provider: 'hmac'` is the parameterized preset for any provider that
+             * signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
+             * `verify` says which header, sha256|sha1, hex|base64, an optional prefix
+             * and an optional timestamp header + tolerance. Like stripe/paddle/slack it
+             * fails closed (401) until the source's signing secret is set. */
             create: async (input) => (await this.call('POST', '/v1/webhooks/sources', input)).data,
             list: async () => (await this.call('GET', '/v1/webhooks/sources')).data.sources,
             delete: async (sourceId) => {
@@ -1731,11 +1874,21 @@ export class Vxil {
             test: async (sourceId) => (await this.call('POST', `/v1/webhooks/sources/${encodeURIComponent(sourceId)}/test`)).data,
         },
         events: {
+            /** Received events. Newest first, paged with `cursor`; or — with `after`
+             * (your watermark, an event id) — OLDEST first from just after it, the
+             * drain shape: store `next_after` and pass it back, `has_more` says
+             * another page waits. The `after` drain answers only events received
+             * at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
+             * event could otherwise commit below a stored watermark and be
+             * skipped); `cursor` and `event_id` reads are not lagged. `event_id`
+             * reads exactly one event. `cursor` and `after` are exclusive. */
             list: async (q) => {
                 const s = qs({
                     source_id: q?.source_id || undefined,
                     status: q?.status || undefined,
                     cursor: q?.cursor || undefined,
+                    after: q?.after || undefined,
+                    event_id: q?.event_id || undefined,
                     limit: q?.limit || undefined,
                 });
                 return (await this.call('GET', `/v1/webhooks/events${s}`)).data;
@@ -1838,8 +1991,14 @@ export class Vxil {
          * matching its TokenProvider type *structurally* (no import — a static
          * import would break the single-file served sdk.mjs) that re-mints via
          * POST /v1/realtime/tokens with `defaults` merged over the channel the
-         * client asks for. Server-side (Node) use only — it needs the API key;
-         * browsers must fetch tokens from YOUR backend instead. */
+         * client asks for. Two safe ways to use it:
+         *   - on a server, with a server key (`user_id` names the subject); or
+         *   - in a browser / mobile app, with a PUBLIC `end_user_required` key and
+         *     the signed-in user's session (`endUserToken` on the client): the mint
+         *     runs in end-user mode and the token's subject is FORCED to the
+         *     verified user (any `user_id` you pass is overridden), so no
+         *     backend of your own is needed.
+         * Never ship a server key to a browser. */
         tokenProvider: (defaults) => (ctx) => this.realtime.mintToken({ channel: ctx.channel, ...defaults }),
         /** One-shot: mint a token AND open the WebSocket. Uses the global
          * `WebSocket` (browser / Node ≥22). On older Node, pass a constructor —
@@ -1864,10 +2023,20 @@ export class Vxil {
          *  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. */
+         *  required with a server key and omitted in end-user mode.
+         *  `checksum_sha256` (the SHA-256 of the bytes, 64 hex or 44 base64
+         *  characters) is signed into the URL (send the answer's `upload_headers`
+         *  on the PUT) and kept with the upload: `complete` compares it with the
+         *  SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
+         *  they differ, 409 `checksum_unverified` when the store reports none —
+         *  and on success answers the verified `checksum_sha256`. */
         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). */
+         *  object's `expires_at` (null = never) and `checksum_sha256` (hex; null
+         *  when the store reported none) — a repeated complete answers the same.
+         *  When the upload declared `checksum_sha256`: 409 `checksum_mismatch` if
+         *  the bytes hash differently, 409 `checksum_unverified` if the store
+         *  reports no checksum (the object stays pending either way). */
         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`)
@@ -2123,8 +2292,10 @@ export class Vxil {
          *  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
-         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. Judge
-         *  relevance by each hit's `similarity` (cosine, -1..1) instead. */
+         *  0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
+         *  relevance threshold use `min_similarity`, which floors each hit's cosine
+         *  `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
+         *  with no measured similarity, e.g. keyword mode, is kept). */
         search: async (input) => (await this.call('POST', '/v1/rag/search', input)).data,
         /** Ingest into the backing vector-search collection (chunk → embed → index). */
         ingest: async (collection, input) => (await this.call('POST', `/v1/rag/ingest/${encodeURIComponent(collection)}`, input)).data,
@@ -2262,7 +2433,9 @@ export class Vxil {
          * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
          * committed): a linked jobs run that terminally fails auto-refunds the hold,
          * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
-         * available balance can't cover `amount`.
+         * available balance can't cover `amount`. Throws VxilError(409,
+         * 'job_released') when `job_id` names a generation run that already ended
+         * (cancelled or failed) before this hold landed: nothing is held.
          *
          * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
          * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
@@ -2383,6 +2556,30 @@ export class Vxil {
          *  past-due-grace, cross-platform-unlock, transfer) through the mock
          *  webhook path and judge it with the conformance oracle. */
         simulate: async (input) => (await this.call('POST', '/v1/payments/simulate', input)).data,
+        /** SERVER-ONLY TEST CLOCK — move the end (`until`, past or future, within
+         *  5 years of now) of a MANUAL grant or a purchase pass, to test expired /
+         *  export-window / renew-soon states on demand. Allowed only where no live
+         *  money can be involved: a `mock`-provider project, a project whose
+         *  provider runs in its sandbox (`paddle.sandbox`, `paypal.sandbox`, a
+         *  Stripe `sk_test_` key), or a dev/preview project — elsewhere 403
+         *  `test_clock_forbidden` (also for a pass linked to a non-sandbox charge).
+         *  409 `provider_managed` for a provider subscription (use the provider's
+         *  own test clock); 409 `subscription_ended` for a revoked/refunded row.
+         *  The effect is a natural lapse's: the entitlements refold
+         *  (`payments.entitlement.changed`), a move into the past turns an active
+         *  row `lapsed` and emits `payments.subscription.lapsed` (`event_type:
+         *  'test_clock'`, `environment: 'sandbox'`) once; a move back into the
+         *  future revives it (as `active` — a `trialing` row does not return to
+         *  `trialing`; a `past_due` row's status is left as it is). Only the end
+         *  moves: `since` (the period start) is never rewritten, so after a move
+         *  before it `since` > `until`. Every move emits
+         *  `payments.test_clock.moved`. Both events are emitted after the move
+         *  commits, best-effort (as the period-end sweep's are): if one fails to
+         *  record, the move still stands and is not re-announced on a retry, so
+         *  assert on the returned `status` / `lapsed` rather than only on the
+         *  event. Same-tier passes stacked behind the moved one are not
+         *  re-chained. No credits are granted or reversed. */
+        moveSubscriptionUntil: async (subscriptionId, until) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/until`, { until: typeof until === 'string' ? until : until.toISOString() })).data,
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,

package/dist/retry.d.ts

@@ -55,6 +55,11 @@ export declare const CAPACITY_ERROR_CODES: ReadonlySet<string>;
  *  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>;
+/** The 409 answers retried the same way: the run this idempotency_key names
+ *  is still placing its credit hold (`generation_in_progress`, Retry-After 5)
+ *  — the SAME request re-sent then answers with that run (or, when the
+ *  earlier enqueue was cut off, starts a fresh one). */
+export declare const IN_PROGRESS_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;
@@ -68,8 +73,9 @@ export interface RetryOnCapacityOptions {
     now?: () => number;
 }
 /**
- * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`) or
- * a 503 `payments_unavailable` (`UNAVAILABLE_ERROR_CODES`):
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
+ * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
+ * or a 409 `generation_in_progress` (`IN_PROGRESS_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

@@ -166,7 +166,12 @@ export const CAPACITY_ERROR_CODES = new Set([
  *  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']);
+export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable', 'enqueue_interrupted']);
+/** The 409 answers retried the same way: the run this idempotency_key names
+ *  is still placing its credit hold (`generation_in_progress`, Retry-After 5)
+ *  — the SAME request re-sent then answers with that run (or, when the
+ *  earlier enqueue was cut off, starts a fresh one). */
+export const IN_PROGRESS_ERROR_CODES = new Set(['generation_in_progress']);
 /** Is this thrown error one `retryOnCapacity` waits out? Duck-typed on
  *  `{ status, code }` (VxilError's fields). */
 export function isCapacityRetryable(e) {
@@ -174,13 +179,15 @@ export function isCapacityRetryable(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));
+        || (err.status === 503 && UNAVAILABLE_ERROR_CODES.has(err.code))
+        || (err.status === 409 && IN_PROGRESS_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`):
+ * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
+ * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
+ * or a 409 `generation_in_progress` (`IN_PROGRESS_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/package.json

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