@vxil/sdk 0.18.0 → 0.19.0

package/dist/index.d.ts

@@ -1646,9 +1646,11 @@ export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloa
 export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
 /** The audiences a function's scoped callback tokens are minted for — one per
  *  feature its declared scopes reach. `control-plane` carries `users:*` /
- *  `usage:read` only. There is deliberately no `functions` audience: a function
- *  cannot call another function. */
-export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
+ *  `usage:read` / `audit:read` only; `webhooks` carries `webhooks:read` only (read the inbound
+ *  sources and received events — e.g. `GET /v1/webhooks/events?after=`). There
+ *  is deliberately no `functions` audience: a function cannot call another
+ *  function. */
+export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane' | 'webhooks';
 /** One short-lived scoped token per audience your scopes imply
  *  (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
  *  scopes do not reach is absent. Send it as `Authorization: Bearer …` to
@@ -1710,6 +1712,43 @@ export interface WebhookTriggerPayload<D = Record<string, unknown>> {
         truncated: true;
     } | null;
 }
+/** The verification parameters of an inbound `hmac` source (`webhooks.sources.create`). */
+export interface WebhookHmacVerify {
+    /** the header carrying the signature (case-insensitive) */
+    header: string;
+    algorithm?: 'sha256' | 'sha1';
+    encoding?: 'hex' | 'base64';
+    /** stripped before comparing (e.g. `sha256=`); required on the request when set */
+    prefix?: string;
+    /** a header carrying the signing timestamp (unix seconds or ISO 8601): the
+     *  signed message becomes `<timestamp><timestamp_separator><body>` */
+    timestamp_header?: string;
+    /** default '.'; '' to concatenate */
+    timestamp_separator?: string;
+    /** default 300, 1..3600 */
+    tolerance_seconds?: number;
+    event_id_header?: string;
+    event_type_header?: string;
+}
+/** `payload.data` of a `webhook` invocation fired by an inbound source whose
+ *  `target_function` is this function (`payload.event === 'inbound_webhook.received'`). */
+export interface InboundWebhookTriggerData {
+    vxil_event_id: string;
+    source_id: string;
+    provider: string;
+    provider_event_id: string | null;
+    event_type: string | null;
+    sig_verified: boolean;
+    /** the provider's JSON body; null when it was larger than 48 000 bytes
+     *  (`payload_omitted: true`) — read it with
+     *  `GET /v1/webhooks/events?event_id=<vxil_event_id>` (scope webhooks:read) */
+    payload: Record<string, unknown> | unknown[] | null;
+    payload_omitted?: true;
+    /** true on a `POST /v1/webhooks/sources/:id/test` probe */
+    test?: true;
+    /** true on a `POST /v1/webhooks/events/:id/replay` */
+    replayed?: true;
+}
 /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
  *  parameters on a GET). */
 export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
@@ -2847,6 +2886,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
     private call;
     readonly 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: (user: {
             id: string;
             email?: string;
@@ -3215,11 +3259,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             brief?: boolean;
         }) => Promise<VxilPlan>;
     };
+    /** 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. */
     readonly 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: (q?: {
             since?: string;
             cursor?: string;
             limit?: number;
+            subject?: string;
         }) => Promise<Array<{
             id: string;
             event: string;
@@ -3237,6 +3293,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             until?: string;
             after_id?: string;
             limit?: number;
+            /** the same subject filter as `list` */
+            subject?: string;
         }) => Promise<{
             events: Array<{
                 id: string;
@@ -3521,7 +3579,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             state: string;
         }>;
         /** 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: (runId: string) => Promise<{
             run_id: string;
             replayed_from: string;
@@ -3544,6 +3603,30 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             moved: number;
             done: boolean;
         }>;
+        /** 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: (input: {
+            run_ids: string[];
+        } | {
+            user_id: string;
+        }) => Promise<{
+            redacted: number;
+            skipped_open: number;
+            done: boolean;
+        }>;
         /**
          * Suspend the RUNNING run until an event (call from the executing
          * handler, then return 200 — the suspension wins). `state: 'resumed'` =
@@ -3734,8 +3817,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 /** 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
@@ -3967,15 +4052,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 verified: true;
             }>;
         };
-        /** 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: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
+                redirect_uri: string;
+                anonymous_token?: string;
+            }) => Promise<{
+                authorize_url: string;
+                expires_in: number;
+            }>;
             /** 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). */
@@ -4126,6 +4230,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                  *  (end-user reads and writes are `403 server_only`, even with an
                  *  owner_field). Server keys are never affected. */
                 end_user_access?: CmsEndUserAccess;
+                /** Role slugs one of which a VERIFIED end user must hold to WRITE this
+                 *  collection (create / update / $inc / delete / publish / transaction
+                 *  step / batch / filtered delete, and an end-user delete's cascade into
+                 *  it) — otherwise `403 role_required`. Reads are unaffected; server keys
+                 *  are never affected. Omitted/`[]` = ungated. ≤16 entries, each
+                 *  `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
+                write_roles?: string[];
+                /** Retention (guide ch. 4): live items created more than this many days
+                 *  ago (1..3650) are soft-deleted by the nightly platform sweep — like a
+                 *  normal delete (no restore; purged at least 30 days later, unique values freed), with ONE
+                 *  `cms.collection.retention_swept` audit event per collection per night
+                 *  instead of per-item delete events. A collection another collection
+                 *  references with an `on_delete` rule is skipped. Omit/null = keep. */
+                retain_days?: number | null;
                 fields?: Array<{
                     field: string;
                     type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -4175,6 +4293,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 actions?: CmsActionDef[];
                 /** present when not the default 'readwrite' */
                 end_user_access?: CmsEndUserAccess;
+                /** present when the collection is role-gated for end-user writes */
+                write_roles?: string[];
+                /** present when retention is set */
+                retain_days?: number;
             }>;
             list: () => Promise<Array<{
                 collection: string;
@@ -4183,6 +4305,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string | null;
                 /** the collection's end-user access mode (absent from an older server = 'readwrite') */
                 end_user_access?: CmsEndUserAccess;
+                /** the roles an end user needs to write it (null / absent = ungated) */
+                write_roles?: string[] | null;
+                /** retention in days (null = keep until deleted; absent from an older server) */
+                retain_days?: number | null;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
             /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4225,6 +4351,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 collection: string;
                 end_user_access: CmsEndUserAccess;
             }>;
+            /** 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: (collection: string, roles: string[] | null) => Promise<{
+                collection: string;
+                write_roles: string[];
+            }>;
+            /** 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: (collection: string, days: number | null) => Promise<{
+                collection: string;
+                retain_days: number | null;
+            }>;
             /** 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
@@ -4276,6 +4421,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 version: number;
                 data: Record<string, unknown>;
             }>;
+            /** 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: (collection: string, input: {
+                data: Record<string, unknown>;
+                onConflict: {
+                    field: string;
+                    patch: Record<string, unknown>;
+                };
+                status?: "draft" | "published";
+                lock?: string;
+                guard?: CmsGuard;
+                guards?: CmsGuardTerm[];
+            }) => Promise<{
+                item_id: string;
+                status: string;
+                version: number;
+                data: Record<string, unknown>;
+                created: boolean;
+            }>;
             /** `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. */
@@ -4284,7 +4452,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }) => Promise<Record<string, unknown>>;
             /**
              * 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
@@ -4674,6 +4844,32 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             };
             warnings?: string[];
         }>;
+        /**
+         * 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: (name: string, opts?: {
+            since?: string;
+        }) => Promise<{
+            lines: Array<{
+                ts: string;
+                outcome: string;
+                wall_ms: number | null;
+                cpu_ms: number | null;
+                logs: Array<{
+                    level: string;
+                    message: string;
+                }>;
+                exceptions: Array<{
+                    name: string;
+                    message: string;
+                }>;
+            }>;
+            next_since: string | null;
+        }>;
     };
     /** The MCP aggregation surface (the `mcp` feature). */
     readonly mcp: {
@@ -4969,20 +5165,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             last_error_msg?: string | null;
         }>;
         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: (input: {
-                provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic";
+                provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic" | "hmac";
                 name: string;
                 forward_url?: string;
+                target_function?: string;
+                verify?: WebhookHmacVerify;
             }) => Promise<{
                 source_id: string;
                 receiver_url_path: string;
                 provider: string;
+                target_function?: string | null;
             }>;
             list: () => Promise<Array<{
                 source_id: string;
                 provider: string;
                 name: string;
+                forward_url?: string | null;
+                target_function?: string | null;
+                verify?: WebhookHmacVerify | null;
             }>>;
             delete: (sourceId: string) => Promise<void>;
             /** Send a sample envelope to the source's forward_url through the real
@@ -4997,20 +5211,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
         };
         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: (q?: {
                 source_id?: string;
                 status?: string;
                 cursor?: string;
                 limit?: number;
+                after?: string;
+                event_id?: string;
             }) => Promise<{
                 events: Array<{
                     event_id: string;
+                    source_id: string;
+                    provider: string;
+                    provider_event_id: string | null;
                     event_type: string | null;
                     payload: Record<string, unknown>;
                     sig_verified: boolean;
                     status: string;
+                    received_at: string;
                 }>;
                 next_cursor: string | null;
+                /** `after` pages only */
+                next_after?: string | null;
+                /** `after` pages only */
+                has_more?: boolean;
             }>;
             replay: (eventId: string) => Promise<void>;
             /** The Svix message-attempt view: delivery state/attempts/DLQ flag for
@@ -5231,8 +5463,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * 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: {
             user_id: string;
             ttl_seconds?: number;
@@ -5808,6 +6046,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             model?: string;
             user_id?: string;
             input?: Record<string, unknown>;
+            /** Drop chunks whose cosine `similarity` to the query is below this
+             *  (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
+            min_similarity?: number;
         }) => Promise<RagAnswer>;
         /** Streamed grounded answer: citations + the channel handle up front, tokens
          *  over the realtime channel. */
@@ -5822,13 +6063,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             model?: string;
             user_id?: string;
             input?: Record<string, unknown>;
+            /** Drop chunks whose cosine `similarity` to the query is below this
+             *  (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
+            min_similarity?: number;
         }) => Promise<RagStreamHandle>;
         /** 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
-         *  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: (input: {
             query: string;
             collection?: string;
@@ -5838,6 +6084,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             rerank?: boolean;
             boosts?: Record<string, unknown>;
             min_score?: number;
+            min_similarity?: number;
         }) => Promise<RagSearchResult>;
         /** Ingest into the backing vector-search collection (chunk → embed → index). */
         ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -5999,7 +6246,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * (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

package/dist/index.js

@@ -429,6 +429,11 @@ 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,
@@ -638,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;
         },
@@ -657,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',
@@ -864,7 +882,8 @@ export class Vxil {
          *  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
@@ -878,6 +897,22 @@ export class Vxil {
          *  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'` =
@@ -995,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
@@ -1182,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). */
@@ -1201,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,
         },
     };
@@ -1311,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
@@ -1379,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. */
@@ -1388,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
@@ -1619,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 = {
@@ -1757,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) => {
@@ -1768,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;
@@ -1875,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 —
@@ -2170,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,
@@ -2309,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.18.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).",