@vxil/sdk 0.2.0 → 0.4.0

package/dist/index.js

@@ -2,6 +2,13 @@
 // Every non-2xx response throws VxilError carrying the structured envelope
 // (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
+ *  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). */
+import { qs } from './qs.js';
+import { createTransport, parseRetryAfter } from './retry.js';
 /** Rewrite a built `/v1/<ns>/…` path onto the version configured for its
  *  namespace: the per-namespace override wins, else the global default. PURE and
  *  exported so it is unit-testable with a hypothetical future major (the runtime
@@ -15,19 +22,28 @@ export function versionedPath(path, globalDefault, overrides) {
     const version = overrides[ns] ?? globalDefault;
     return `/${version}/${ns}${m[2]}`;
 }
+/** Every non-2xx answer is thrown as this class, carrying the structured error
+ *  envelope. `status` is the HTTP status — or `0` when no response arrived
+ *  (a `timeoutMs` timeout, `code: 'request_timeout'`). */
 export class VxilError extends Error {
     status;
     code;
     hint;
     fixUrl;
     requestId;
-    constructor(status, code, message, hint, fixUrl, requestId) {
+    retryAfter;
+    constructor(status, code, message, hint, fixUrl, requestId, 
+    /** Seconds the server asked the caller to wait — parsed from `Retry-After`
+     *  (delta-seconds or an HTTP-date) when the answer carried it (a rate
+     *  limit, a busy upstream); otherwise undefined. */
+    retryAfter) {
         super(message);
         this.status = status;
         this.code = code;
         this.hint = hint;
         this.fixUrl = fixUrl;
         this.requestId = requestId;
+        this.retryAfter = retryAfter;
         this.name = 'VxilError';
     }
 }
@@ -54,17 +70,13 @@ function resolveBase(explicit) {
 export function cmsPublicUrl(tenantId, collection, query, opts) {
     const base = resolveBase(opts?.baseUrl);
     const path = `/v1/cms/public/${encodeURIComponent(tenantId)}/${encodeURIComponent(collection)}`;
-    const qs = new URLSearchParams();
-    if (query?.filter)
-        qs.set('filter', JSON.stringify(query.filter));
-    if (query?.sort)
-        qs.set('sort', query.sort);
-    if (query?.limit !== undefined)
-        qs.set('limit', String(query.limit));
-    if (query?.cursor)
-        qs.set('cursor', query.cursor);
-    const s = qs.toString();
-    return `${base}${path}${s ? `?${s}` : ''}`;
+    const s = qs({
+        filter: query?.filter ? JSON.stringify(query.filter) : undefined,
+        sort: query?.sort || undefined,
+        limit: query?.limit,
+        cursor: query?.cursor || undefined,
+    });
+    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
@@ -85,12 +97,12 @@ export async function listCmsPublic(tenantId, collection, query, opts) {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new VxilError(res.status, `http_${res.status}`, text.slice(0, 200));
+            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) {
         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);
+        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 ?? { items: [], next_cursor: null };
 }
@@ -103,6 +115,12 @@ export class Vxil {
     /** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
      *  mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
     endUserToken;
+    /** The ONE path every request takes: retry + timeout + hooks around
+     *  `fetchImpl`. With none of the three configured it is a single fetch. */
+    transport;
+    retryOpts;
+    timeoutMs;
+    hooks;
     constructor(opts) {
         this.key = opts.apiKey;
         this.base = resolveBase(opts.baseUrl);
@@ -110,6 +128,16 @@ export class Vxil {
         this.apiVersion = opts.apiVersion ?? 'v1';
         this.apiVersions = opts.apiVersions ?? {};
         this.endUserToken = opts.endUserToken;
+        this.retryOpts = opts.retry;
+        this.timeoutMs = opts.timeoutMs;
+        this.hooks = opts.hooks;
+        this.transport = createTransport({
+            fetch: this.fetchImpl,
+            ...(opts.retry ? { retry: opts.retry } : {}),
+            ...(opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+            ...(opts.hooks ? { hooks: opts.hooks } : {}),
+            timeoutError: (ms) => new VxilError(0, 'request_timeout', `request timed out after ${ms}ms`),
+        });
     }
     /** The header bag every request layers on top of `authorization`: the
      *  `X-Vxil-End-User` session token in end-user mode, nothing in server mode.
@@ -120,8 +148,8 @@ export class Vxil {
     /** Return a client that sends `X-Vxil-End-User: <token>` on every request —
      *  a per-call/scoped override of end-user mode over an otherwise server-mode
      *  client, mirroring how the edge threads the verified principal. The base
-     *  URL, api key, fetch impl and version pins are inherited unchanged; only the
-     *  end-user token is (re)set. Pass a falsy token to get back a server-mode
+     *  URL, api key, fetch impl, version pins and the retry/timeout/hooks options
+     *  are inherited unchanged; only the end-user token is (re)set. Pass a falsy token to get back a server-mode
      *  client (drops the header). See docs/end-user-principals-design.md §4.1. */
     asEndUser(endUserToken) {
         return new Vxil({
@@ -130,6 +158,9 @@ export class Vxil {
             fetch: this.fetchImpl,
             apiVersion: this.apiVersion,
             apiVersions: this.apiVersions,
+            ...(this.retryOpts ? { retry: this.retryOpts } : {}),
+            ...(this.timeoutMs !== undefined ? { timeoutMs: this.timeoutMs } : {}),
+            ...(this.hooks ? { hooks: this.hooks } : {}),
             ...(endUserToken ? { endUserToken } : {}),
         });
     }
@@ -188,26 +219,25 @@ export class Vxil {
             // envelope), so bypass call()'s unwrap — read the body directly, like
             // audit.export. Errors still surface as VxilError.
             return async (payload) => {
-                const res = await this.fetchImpl(`${this.base}${this.path(`/v1/fn/${encodeURIComponent(prop)}`)}`, {
+                const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/fn/${encodeURIComponent(prop)}`)}`, {
                     method: 'POST',
                     headers: { authorization: `Bearer ${this.key}`, ...this.authHeaders(), 'content-type': 'application/json' },
                     body: JSON.stringify(payload ?? {}),
                 });
-                const text = await res.text();
                 if (!res.ok) {
                     let e = {};
                     try {
                         e = JSON.parse(text).error ?? {};
                     }
                     catch { /* non-JSON error body */ }
-                    throw new VxilError(res.status, e.code ?? `http_${res.status}`, e.message ?? text.slice(0, 200));
+                    throw new VxilError(res.status, e.code ?? `http_${res.status}`, e.message ?? text.slice(0, 200), undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
                 }
                 return text.length ? JSON.parse(text) : undefined;
             };
         },
     });
     async call(method, path, body, headers = {}) {
-        const res = await this.fetchImpl(`${this.base}${this.path(path)}`, {
+        const { response: res, text } = await this.transport.send(`${this.base}${this.path(path)}`, {
             method,
             headers: {
                 authorization: `Bearer ${this.key}`,
@@ -217,7 +247,6 @@ export class Vxil {
             },
             ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
         });
-        const text = await res.text();
         // 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)
@@ -231,16 +260,16 @@ export class Vxil {
                 // only surface the parse failure as an error on a non-2xx.
                 if (res.ok)
                     return { data: undefined, meta: { request_id: '' }, response: res };
-                throw new VxilError(res.status, `http_${res.status}`, text.slice(0, 200));
+                throw new VxilError(res.status, `http_${res.status}`, text.slice(0, 200), undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
             }
         }
         else if (!res.ok) {
             // Empty-body non-2xx: no envelope to surface, fall back to the status.
-            throw new VxilError(res.status, `http_${res.status}`, `request failed (${res.status})`);
+            throw new VxilError(res.status, `http_${res.status}`, `request failed (${res.status})`, undefined, undefined, undefined, parseRetryAfter(res.headers.get('retry-after')));
         }
         if (!res.ok || parsed.error) {
             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);
+            throw new VxilError(res.status, e.code, e.message, e.hint, e.fixUrl, parsed.meta?.request_id, parseRetryAfter(res.headers.get('retry-after')));
         }
         return { data: parsed.data, meta: parsed.meta ?? { request_id: '' }, response: res };
     }
@@ -262,31 +291,36 @@ export class Vxil {
             await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`);
         },
         list: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.email)
-                qs.set('email', q.email);
-            if (q?.q)
-                qs.set('q', q.q);
-            if (q?.cursor)
-                qs.set('cursor', q.cursor);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/users${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                email: q?.email || undefined,
+                q: q?.q || undefined,
+                cursor: q?.cursor || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/users${s}`)).data;
         },
     };
     notifications = {
         send: async (input, opts) => (await this.call('POST', '/v1/notifications/send', input, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
+        /** Up to 100 sends in one call. Each item is INDEPENDENTLY atomic (recorded
+         *  + enqueued, or neither) and `results` is index-aligned with `items`. */
+        sendBatch: async (items) => (await this.call('POST', '/v1/notifications/send/batch', { items })).data,
+        /** Render a template exactly as a send would, WITHOUT sending. `missing`
+         *  lists the required data keys you left out. Needs `notifications:read`. */
+        preview: async (templateId, input) => (await this.call('POST', `/v1/notifications/templates/${encodeURIComponent(templateId)}/preview`, input ?? {})).data,
+        /** Read-only deliverability probe: is `config.fromEmail`'s domain verified
+         *  at the provider? FAIL-SOFT — `verified: 'unknown'` whenever it cannot be
+         *  determined (mock provider, no key, provider unreachable). */
+        senderDomain: async () => (await this.call('GET', '/v1/notifications/sender-domain')).data,
         inbox: {
             list: async (q) => {
-                const qs = new URLSearchParams({ user_id: q.user_id });
-                if (q.unread_only)
-                    qs.set('unread_only', 'true');
-                if (q.cursor)
-                    qs.set('cursor', q.cursor);
-                if (q.limit)
-                    qs.set('limit', String(q.limit));
-                return (await this.call('GET', `/v1/notifications/inbox?${qs.toString()}`)).data;
+                const s = qs({
+                    user_id: q.user_id,
+                    unread_only: q.unread_only || undefined,
+                    cursor: q.cursor || undefined,
+                    limit: q.limit || undefined,
+                });
+                return (await this.call('GET', `/v1/notifications/inbox${s}`)).data;
             },
             markRead: async (msgId, userId) => {
                 await this.call('POST', `/v1/notifications/inbox/${encodeURIComponent(msgId)}/read`, { user_id: userId });
@@ -294,15 +328,13 @@ export class Vxil {
             markAllRead: async (userId) => (await this.call('POST', '/v1/notifications/inbox/read-all', { user_id: userId })).data.marked_read,
         },
         deliveries: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.status)
-                qs.set('status', q.status);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/notifications/deliveries${s ? `?${s}` : ''}`)).data.deliveries;
+            const s = qs({
+                user_id: q?.user_id || undefined,
+                status: q?.status || undefined,
+                engagement: q?.engagement || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/notifications/deliveries${s}`)).data.deliveries;
         },
         suppressions: {
             list: async () => (await this.call('GET', '/v1/notifications/suppressions')).data.suppressions,
@@ -329,6 +361,19 @@ export class Vxil {
         campaigns: {
             create: async (input) => (await this.call('POST', '/v1/notifications/campaigns', input)).data,
             list: async () => (await this.call('GET', '/v1/notifications/campaigns')).data.campaigns,
+            /** Stop a scheduled campaign from firing (the jobs cron is torn down). */
+            pause: async (campaignId) => (await this.call('POST', `/v1/notifications/campaigns/${encodeURIComponent(campaignId)}/pause`)).data,
+            /** Re-register the cron (back to `scheduled`, or `draft` with no cron). */
+            resume: async (campaignId) => (await this.call('POST', `/v1/notifications/campaigns/${encodeURIComponent(campaignId)}/resume`)).data,
+            /** Terminal stop — the cron is removed and the campaign cannot resume. */
+            cancel: async (campaignId) => (await this.call('POST', `/v1/notifications/campaigns/${encodeURIComponent(campaignId)}/cancel`)).data,
+            /** Soft-delete: hidden from the list, cron removed; the dedupe ledger
+             *  survives so a re-created campaign cannot re-send to a served user. */
+            remove: async (campaignId) => (await this.call('DELETE', `/v1/notifications/campaigns/${encodeURIComponent(campaignId)}`)).data,
+            /** Push ONE audience page (≤ 1000 rows) into a campaign run — the shape a
+             *  tenant audience callback uses. Omit `audience` for a campaign whose
+             *  `audience_ref` is the built-in `users:all` selector. */
+            run: async (campaignId, audience) => (await this.call('POST', `/v1/notifications/campaigns/${encodeURIComponent(campaignId)}/run`, audience ? { audience } : {})).data,
         },
     };
     config = {
@@ -366,35 +411,28 @@ export class Vxil {
     };
     audit = {
         list: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.since)
-                qs.set('since', q.since);
-            if (q?.cursor)
-                qs.set('cursor', q.cursor);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/audit${s ? `?${s}` : ''}`)).data.events;
+            const s = qs({
+                since: q?.since || undefined,
+                cursor: q?.cursor || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/audit${s}`)).data.events;
         },
         /**
          * NDJSON export (≤10k rows/call, id-ascending). Returns parsed events +
          * next_after_id for resumption (null = done).
          */
         export: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.since)
-                qs.set('since', q.since);
-            if (q?.until)
-                qs.set('until', q.until);
-            if (q?.after_id)
-                qs.set('after_id', q.after_id);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            const res = await this.fetchImpl(`${this.base}${this.path(`/v1/audit/export${s ? `?${s}` : ''}`)}`, {
+            const s = qs({
+                since: q?.since || undefined,
+                until: q?.until || undefined,
+                after_id: q?.after_id || undefined,
+                limit: q?.limit || undefined,
+            });
+            const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/audit/export${s}`)}`, {
+                method: 'GET',
                 headers: { authorization: `Bearer ${this.key}` },
             });
-            const text = await res.text();
             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
@@ -405,7 +443,7 @@ export class Vxil {
                 }
                 catch { /* non-JSON error body — fall through to the status default */ }
                 const e = env.error ?? { code: `http_${res.status}`, message: text.slice(0, 200) };
-                throw new VxilError(res.status, e.code, e.message, e.hint, e.fixUrl, env.meta?.request_id);
+                throw new VxilError(res.status, e.code, e.message, e.hint, e.fixUrl, env.meta?.request_id, parseRetryAfter(res.headers.get('retry-after')));
             }
             // 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
@@ -429,6 +467,13 @@ export class Vxil {
             };
         },
     };
+    /** Current-month usage: requests used vs the plan's included quota, plus
+     *  month-to-date per-feature metered detail. Read-only (needs `usage:read`
+     *  or `features:read`). Agents: call this before a bulk run to self-check
+     *  remaining quota. */
+    usage = {
+        current: async () => (await this.call('GET', '/v1/usage')).data,
+    };
     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
@@ -452,17 +497,13 @@ export class Vxil {
          * outstanding-holds ceiling → 429. */
         generation: async (input) => (await this.call('POST', '/v1/jobs/generation', input)).data,
         runs: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.job_name)
-                qs.set('job_name', q.job_name);
-            if (q?.state)
-                qs.set('state', q.state);
-            if (q?.ids?.length)
-                qs.set('ids', q.ids.join(','));
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/jobs/runs${s ? `?${s}` : ''}`)).data.runs;
+            const s = qs({
+                job_name: q?.job_name || undefined,
+                state: q?.state || undefined,
+                ids: q?.ids,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/jobs/runs${s}`)).data.runs;
         },
         run: async (runId) => (await this.call('GET', `/v1/jobs/runs/${encodeURIComponent(runId)}`)).data,
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
@@ -503,6 +544,16 @@ export class Vxil {
             },
         },
     };
+    /** vxil-auth. SCOPES (docs/features/auth.md §7.6): every flow here that
+     *  obtains, renews, verifies or ends the caller's OWN session (signUp/signIn,
+     *  magicLink, otp, anonymous, stepUp, oauth, sessions.refresh/revoke/verify,
+     *  password reset) accepts the narrow `auth:signin` — the ONLY auth scope a
+     *  key baked into a browser/mobile bundle should carry. `sessions.list` needs
+     *  `auth:read`; `sessions.revokeById` and `users.erase` need `auth:write`
+     *  (administrative — server keys only). In end-user mode (`endUserToken` /
+     *  `asEndUser`) the administrative calls bind to the signed-in user: own
+     *  sessions only, own devices only, erase self only. `auth:write` still
+     *  satisfies every call. */
     auth = {
         signUp: async (input) => (await this.call('POST', '/v1/auth/sign-up', input)).data,
         signIn: async (input) => (await this.call('POST', '/v1/auth/sign-in', input)).data,
@@ -516,9 +567,11 @@ export class Vxil {
          *  Server-side guessing budget (config otp.maxAttempts), single active code,
          *  resend cooldown (429 otp_rate_limited). */
         otp: {
-            request: async (input) => {
-                await this.call('POST', '/v1/auth/otp/request', input);
-            },
+            /** `test_code` is present ONLY when the address matches auth config
+             *  `otp.testRecipients` (store-review / CI accounts): no mail is sent and
+             *  the code comes back instead. `captcha_token` is required when the
+             *  tenant configured `security.captchaSecretRef`. */
+            request: async (input) => (await this.call('POST', '/v1/auth/otp/request', input)).data,
             verify: async (input) => (await this.call('POST', '/v1/auth/otp/verify', input)).data,
         },
         /** Anonymous (guest) sessions: instant end-user + session (JWT carries
@@ -526,9 +579,12 @@ export class Vxil {
         anonymous: {
             signIn: async () => (await this.call('POST', '/v1/auth/anonymous/sign-in', {})).data,
             link: {
-                request: async (input) => {
-                    await this.call('POST', '/v1/auth/anonymous/link/request', input);
-                },
+                request: async (input) => (await this.call('POST', '/v1/auth/anonymous/link/request', input)).data,
+                /** 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). */
                 verify: async (input) => (await this.call('POST', '/v1/auth/anonymous/link/verify', input)).data,
             },
         },
@@ -536,9 +592,7 @@ export class Vxil {
          *  bearer token ROTATES (the returned session.token replaces the old one —
          *  swap it client-side) and the JWT gains an `elv` claim. */
         stepUp: {
-            request: async (input) => {
-                await this.call('POST', '/v1/auth/step-up/request', input);
-            },
+            request: async (input) => (await this.call('POST', '/v1/auth/step-up/request', input)).data,
             verify: async (input) => (await this.call('POST', '/v1/auth/step-up/verify', input)).data,
         },
         /** End-user administration (server/function surface, auth:write). */
@@ -547,8 +601,16 @@ export class Vxil {
              *  (email → tombstone, password/name/avatar cleared) and revoke every
              *  live session. Idempotent — a second call on an already-erased user is a
              *  no-op. Meant to be called from a "delete my account" server route or
-             *  vxil function (which declares `auth:write`). */
+             *  vxil function (which declares `auth:write`). In END-USER mode the call
+             *  is SELF-only: `userId` must be the signed-in user, any other id throws
+             *  403 `server_only` (a thin client can never erase someone else). */
             erase: async (userId) => (await this.call('POST', `/v1/auth/users/${encodeURIComponent(userId)}/erase`, {})).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
+             *  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,
         },
         sessions: {
             verify: async (token) => (await this.call('POST', '/v1/auth/sessions/verify', { token })).data,
@@ -557,13 +619,24 @@ export class Vxil {
             revoke: async (token) => {
                 await this.call('POST', '/v1/auth/sessions/revoke', { token });
             },
+            /** "Sign out everywhere": revoke EVERY live session of a user in one call
+             *  (one statement, one batched edge-cache write; each session's
+             *  revoked_reason = 'revoke_all'). SERVER mode names the user (`userId`,
+             *  scope `auth:write`); in END-USER mode the signed-in user's own sessions
+             *  go and `userId` is ignored (scope `auth:signin` suffices). Idempotent:
+             *  a user with no live sessions returns `revoked: 0`. */
+            revokeAll: async (userId) => (await this.call('POST', '/v1/auth/sessions/revoke-all', userId !== undefined ? { user_id: userId } : {})).data,
             /** Force-revoke a SPECIFIC session by its `session_id` (from `list`) — the
              *  server-forced device-lockout path beyond the client-cooperative
-             *  by-token `revoke`. Throws 404 when the id is unknown or already revoked. */
+             *  by-token `revoke`. Throws 404 when the id is unknown or already revoked
+             *  — or, in end-user mode, when it belongs to another user (a signed-in
+             *  user can kick only their OWN devices). Scope `auth:write`. */
             revokeById: async (sessionId) => {
                 await this.call('POST', `/v1/auth/sessions/${encodeURIComponent(sessionId)}/revoke`, {});
             },
-            /** List a user's active sessions (the account "signed-in devices" surface). */
+            /** List a user's active sessions (the account "signed-in devices" surface).
+             *  Scope `auth:read`. In end-user mode the list is bound to the signed-in
+             *  user regardless of `userId` (the verified principal wins). */
             list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
         },
         password: {
@@ -575,13 +648,36 @@ export class Vxil {
                 await this.call('POST', '/v1/auth/password/reset/confirm', input);
             },
         },
+        /** Email verification (the flow behind auth config `emailVerification.required`,
+         *  which makes password sign-in answer 403 `email_not_verified` until the
+         *  address is confirmed). `request` always resolves (anti-enumeration —
+         *  a link is mailed only to an existing, unverified user; `redirect_url`
+         *  is your page that reads `?token=` and calls `confirm`). `confirm` is
+         *  single-use and expires after 24h. */
+        emailVerification: {
+            request: async (input) => {
+                await this.call('POST', '/v1/auth/email/verify/request', input);
+            },
+            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); `native` is the mobile token-exchange the SDK wraps. */
+         *  (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`
+         *  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: {
             /** 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). */
-            native: async (provider, input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
+            native: async (provider, 
+            /** `anonymous_token`: the caller's CURRENT guest session bearer — the
+             *  guest is PROMOTED to this identity (same user id, `linked: 'promoted'`)
+             *  or, if the identity already has an account, MERGED into it
+             *  (`linked: 'merged'`, `user_id` = that account). */
+            input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
         },
     };
     rateLimits = {
@@ -599,10 +695,8 @@ export class Vxil {
         /** Per-policy usage analytics: hourly allowed/blocked buckets + top keys
          *  (last `hours`, clamped 1..48, default 24). */
         analytics: async (input) => {
-            const qs = new URLSearchParams({ policy_id: input.policy_id });
-            if (input.hours !== undefined)
-                qs.set('hours', String(input.hours));
-            return (await this.call('GET', `/v1/rate-limits/analytics?${qs.toString()}`)).data;
+            const s = qs({ policy_id: input.policy_id, hours: input.hours });
+            return (await this.call('GET', `/v1/rate-limits/analytics${s}`)).data;
         },
         /**
          * Consume budget. With behavior 'block' an exceeded check throws
@@ -631,6 +725,16 @@ 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) —
+             *  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
+             *  definition. In verified end-user mode a gated field is omitted from every
+             *  read unless the session's verified roles intersect `roles`; server-caller
+             *  reads and ALL writes are unaffected. */
+            setFieldReadRoles: async (collection, field, type, roles, rest = {}) => {
+                await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { ...rest, field, type, read_roles: roles ?? [] });
+            },
             /** 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. */
             setOwnerField: async (collection, ownerField) => {
@@ -644,6 +748,13 @@ export class Vxil {
             setPublic: async (collection, isPublic) => {
                 await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { public: isPublic });
             },
+            /** Replace the collection's per-record ACTION list (cms.md §17) — 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. */
+            setActions: async (collection, actions) => {
+                await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { actions });
+            },
         },
         items: {
             /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
@@ -661,17 +772,13 @@ export class Vxil {
              * per-field `Filterable` unions on `vx.from(...).query` exclude.
              */
             query: async (collection, q) => {
-                const qs = new URLSearchParams();
-                if (q?.filter)
-                    qs.set('filter', JSON.stringify(q.filter));
-                if (q?.sort)
-                    qs.set('sort', q.sort);
-                if (q?.limit)
-                    qs.set('limit', String(q.limit));
-                if (q?.cursor)
-                    qs.set('cursor', q.cursor);
-                const s = qs.toString();
-                return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}${s ? `?${s}` : ''}`)).data;
+                const s = qs({
+                    filter: q?.filter ? JSON.stringify(q.filter) : undefined,
+                    sort: q?.sort || undefined,
+                    limit: q?.limit || undefined,
+                    cursor: q?.cursor || undefined,
+                });
+                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):
              *  `ifVersion` → If-Match CAS; `if` → bounded field precondition against
@@ -691,15 +798,29 @@ export class Vxil {
             /** `{ count }` under the same bounded filter grammar (cms.md §9.4). 422
              *  count_unavailable_with_read_hooks on beforeRead-hooked collections. */
             count: async (collection, filter) => {
-                const qs = new URLSearchParams({ count: 'true' });
-                if (filter)
-                    qs.set('filter', JSON.stringify(filter));
-                return (await this.call('GET', `/v1/cms/items/${encodeURIComponent(collection)}?${qs.toString()}`)).data.count;
+                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
              *  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,
             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
+             *  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
+             *  with 409 `referenced` (an `on_delete: 'restrict'` edge) names the same
+             *  refs in its `referencing` field. */
+            backlinks: async (collection, itemId, opts) => {
+                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
+             *  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|
              *  min|max|avg over index-slot-bound fields; groupBy ≤2 slot-bound
              *  fields; filter = the full query DSL incl. ONE-hop dotted join terms
@@ -728,12 +849,8 @@ export class Vxil {
     comments = {
         create: async (input) => (await this.call('POST', '/v1/comments', input)).data,
         list: async (q) => {
-            const qs = new URLSearchParams({ topic: q.topic });
-            if (q.cursor)
-                qs.set('cursor', q.cursor);
-            if (q.limit)
-                qs.set('limit', String(q.limit));
-            return (await this.call('GET', `/v1/comments?${qs.toString()}`)).data;
+            const s = qs({ topic: q.topic, cursor: q.cursor || undefined, limit: q.limit || undefined });
+            return (await this.call('GET', `/v1/comments${s}`)).data;
         },
         /** Author edit, allowed within the tenant's editWindowMinutes. */
         edit: async (commentId, input) => {
@@ -748,17 +865,13 @@ export class Vxil {
         /** Cross-topic recent-comments feed (tenant-wide, newest-first) — the
          *  dashboard "recent activity" surface. Keyset cursor + optional filters. */
         recent: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.topic_prefix)
-                qs.set('topic_prefix', q.topic_prefix);
-            if (q?.author_id)
-                qs.set('author_id', q.author_id);
-            if (q?.cursor)
-                qs.set('cursor', q.cursor);
-            if (q?.limit !== undefined)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/comments/recent${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                topic_prefix: q?.topic_prefix || undefined,
+                author_id: q?.author_id || undefined,
+                cursor: q?.cursor || undefined,
+                limit: q?.limit,
+            });
+            return (await this.call('GET', `/v1/comments/recent${s}`)).data;
         },
     };
     /**
@@ -786,12 +899,8 @@ export class Vxil {
             /** Read a conversation's messages (an authz'd participant only; messages
              *  from authors the viewer has blocked are filtered out). Keyset cursor. */
             messages: async (conversationId, q) => {
-                const qs = new URLSearchParams({ user_id: q.user_id });
-                if (q.cursor)
-                    qs.set('cursor', q.cursor);
-                if (q.limit !== undefined)
-                    qs.set('limit', String(q.limit));
-                return (await this.call('GET', `/v1/dm/conversations/${encodeURIComponent(conversationId)}/messages?${qs.toString()}`)).data;
+                const s = qs({ user_id: q.user_id, cursor: q.cursor || undefined, limit: q.limit });
+                return (await this.call('GET', `/v1/dm/conversations/${encodeURIComponent(conversationId)}/messages${s}`)).data;
             },
         },
         /** Send a message (an authz'd participant). Stored as a comment on the
@@ -834,21 +943,15 @@ export class Vxil {
          * feed; `notificationState` filters to unseen | unread | all.
          */
         read: async (group, feedId, q) => {
-            const qs = new URLSearchParams();
-            if (q?.limit !== undefined)
-                qs.set('limit', String(q.limit));
-            if (q?.id_lt)
-                qs.set('id_lt', q.id_lt);
-            if (q?.id_gt)
-                qs.set('id_gt', q.id_gt);
-            if (q?.notificationState)
-                qs.set('notification_state', q.notificationState);
-            if (q?.markSeen)
-                qs.set('mark_seen', 'true');
-            if (q?.markRead)
-                qs.set('mark_read', 'true');
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/feeds/${encodeURIComponent(group)}/${encodeURIComponent(feedId)}${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                limit: q?.limit,
+                id_lt: q?.id_lt || undefined,
+                id_gt: q?.id_gt || undefined,
+                notification_state: q?.notificationState || undefined,
+                mark_seen: q?.markSeen || undefined,
+                mark_read: q?.markRead || undefined,
+            });
+            return (await this.call('GET', `/v1/feeds/${encodeURIComponent(group)}/${encodeURIComponent(feedId)}${s}`)).data;
         },
         /** Remove an activity by id (or by foreign_id); tombstones + un-fans-out. */
         removeActivity: async (group, feedId, ref) => {
@@ -879,13 +982,8 @@ export class Vxil {
         /** Who a feed FOLLOWS (`following[]` + `following_count`) plus the true
          *  `followers_count` (who follows this feed). Keyset cursor via `after`. */
         listFollows: async (group, feedId, q) => {
-            const qs = new URLSearchParams();
-            if (q?.limit !== undefined)
-                qs.set('limit', String(q.limit));
-            if (q?.after)
-                qs.set('after', q.after);
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/feeds/${encodeURIComponent(group)}/${encodeURIComponent(feedId)}/follows${s ? `?${s}` : ''}`)).data;
+            const s = qs({ limit: q?.limit, after: q?.after || undefined });
+            return (await this.call('GET', `/v1/feeds/${encodeURIComponent(group)}/${encodeURIComponent(feedId)}/follows${s}`)).data;
         },
         /**
          * Block (two-way fan-out suppression, removes existing rows) or mute (one-way
@@ -961,17 +1059,13 @@ export class Vxil {
         },
         events: {
             list: async (q) => {
-                const qs = new URLSearchParams();
-                if (q?.source_id)
-                    qs.set('source_id', q.source_id);
-                if (q?.status)
-                    qs.set('status', q.status);
-                if (q?.cursor)
-                    qs.set('cursor', q.cursor);
-                if (q?.limit)
-                    qs.set('limit', String(q.limit));
-                const s = qs.toString();
-                return (await this.call('GET', `/v1/webhooks/events${s ? `?${s}` : ''}`)).data;
+                const s = qs({
+                    source_id: q?.source_id || undefined,
+                    status: q?.status || undefined,
+                    cursor: q?.cursor || undefined,
+                    limit: q?.limit || undefined,
+                });
+                return (await this.call('GET', `/v1/webhooks/events${s}`)).data;
             },
             replay: async (eventId) => {
                 await this.call('POST', `/v1/webhooks/events/${encodeURIComponent(eventId)}/replay`);
@@ -980,6 +1074,12 @@ export class Vxil {
              * every jobs run this event's forwards created. */
             runs: async (eventId) => (await this.call('GET', `/v1/webhooks/events/${encodeURIComponent(eventId)}/runs`)).data,
         },
+        /** Every audit event the platform can emit, with the subscribable prefixes
+         * and their counts — the discovery surface for `subscribe({ event_prefixes })`.
+         * Static reference data (CI-generated from the emitters), identical for every
+         * tenant. `level` is the event CLASS ('lifecycle' | 'failure'), not the
+         * payload's 'info'|'warn'|'error' severity key. */
+        eventCatalog: async () => (await this.call('GET', '/v1/webhooks/events/catalog')).data,
     };
     orgs = {
         create: async (input) => (await this.call('POST', '/v1/orgs', input)).data,
@@ -995,10 +1095,8 @@ export class Vxil {
          *  `opts.resource` to additionally consult per-resource ACL grants; the
          *  response `source` marks whether a grant came from the role lattice or an ACL. */
         check: async (orgId, userId, permission, opts) => {
-            const qs = new URLSearchParams({ user_id: userId, permission });
-            if (opts?.resource)
-                qs.set('resource', opts.resource);
-            return (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}/check?${qs.toString()}`)).data;
+            const s = qs({ user_id: userId, permission, resource: opts?.resource || undefined });
+            return (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}/check${s}`)).data;
         },
         /** The active-org snapshot auth embeds in session JWTs when the tenant
          *  enables auth config `orgClaims` (most-recent membership by joined_at).
@@ -1093,15 +1191,12 @@ export class Vxil {
         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,
         list: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.cursor)
-                qs.set('cursor', q.cursor);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/files${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                user_id: q?.user_id || undefined,
+                cursor: q?.cursor || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/files${s}`)).data;
         },
         /** Soft delete; bytes are hard-deleted 30 days later. */
         delete: async (objectId) => {
@@ -1119,9 +1214,12 @@ export class Vxil {
          *  (else a future auto-delete after the given seconds; minimum 60). */
         setTtl: async (objectId, expiresInSeconds) => (await this.call('PUT', `/v1/files/${encodeURIComponent(objectId)}/ttl`, { expiresInSeconds })).data,
         sharedLinks: {
-            /** Public (unauthenticated) URL for the object; revocable. */
+            /** Public (unauthenticated) URL for the object; revocable. Optional
+             *  `max_downloads` (1 = one-time link) and an absolute `expires_at`; the
+             *  public resolver answers 410 `link_exhausted` / `link_expired` past
+             *  either bound. */
             create: async (objectId, opts) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/shared-links`, opts ?? {})).data,
-            /** List an object's active (unrevoked, unexpired) shared links. */
+            /** List an object's active (unrevoked, unexpired, unexhausted) shared links. */
             list: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/shared-links`)).data.links,
             revoke: async (linkId) => {
                 await this.call('DELETE', `/v1/files/shared-links/${encodeURIComponent(linkId)}`);
@@ -1145,15 +1243,12 @@ export class Vxil {
         ingest: async (collection, input) => (await this.call('POST', `/v1/search/${encodeURIComponent(collection)}/documents`, input)).data,
         /** List indexed documents (keyset cursor, optional `user_id` filter). */
         listDocuments: async (collection, q) => {
-            const qs = new URLSearchParams();
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.cursor)
-                qs.set('cursor', q.cursor);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/search/${encodeURIComponent(collection)}/documents${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                user_id: q?.user_id || undefined,
+                cursor: q?.cursor || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/search/${encodeURIComponent(collection)}/documents${s}`)).data;
         },
         /** De-index a document (+ invalidate the query cache). */
         deleteDocument: async (collection, docId) => {
@@ -1190,7 +1285,10 @@ export class Vxil {
     ai = {
         templates: {
             /** Store a tenant-authored prompt template; versions are monotonic per name.
-             *  `{{var}}` placeholders are filled from `generate`'s `input`. */
+             *  `{{var}}` placeholders are filled from `generate`'s `input`.
+             *  `schema` (a JSON Schema) is now ENFORCED at generate time on sync/job
+             *  requests — the output is validated (with one repair pass) against it;
+             *  a per-request `response_schema` overrides it. Ignored on streams. */
             put: async (input) => (await this.call('POST', '/v1/ai/templates', input)).data,
             /** List stored templates (each name + its latest version). */
             list: async () => (await this.call('GET', '/v1/ai/templates')).data.templates,
@@ -1220,19 +1318,34 @@ export class Vxil {
             const s = q?.since != null ? `?since=${q.since}` : '';
             return (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}/stream${s}`)).data;
         },
+        /** Classify an input into one of YOUR labels (or, with `multi:true`, every
+         *  label that applies) — a schema-forced verdict over the generate path:
+         *  the allowed labels ride the structured-output schema as an enum, so the
+         *  model cannot answer off-list; the reply is `{ label | labels,
+         *  confidence, rationale }`. Same metering/cache/provider rules as
+         *  `generate` (a still-invalid verdict is a billed 422
+         *  output_schema_mismatch). Caps: 2–64 labels (≤64 chars, unique), input
+         *  ≤32k chars (a string or ordered `{ text }` parts joined into ONE
+         *  input), rubric ≤4k, ≤16 examples. */
+        classify: async (input) => (await this.call('POST', '/v1/ai/classify', input)).data,
+        /** Grade a candidate response (or rank up to 8) against YOUR criteria —
+         *  a schema-forced integer score inside `scale` (default 0..10) plus
+         *  `pass|fail` for one candidate, or `scores[]` + `best` (+ `verdict:'tie'`)
+         *  for several — `candidates` always yields `scores`/`best`, even at
+         *  length 1. Same metering/cache/provider rules as `generate`. Caps:
+         *  input ≤16k chars, candidates ≤8 × 4k chars, criteria ≤16 items / 4k
+         *  chars, scale span ≤100. */
+        judge: async (input) => (await this.call('POST', '/v1/ai/judge', input)).data,
         /** Embed a batch of strings (1–256). */
         embed: async (input) => (await this.call('POST', '/v1/ai/embed', input)).data,
         /** Per-user token rollups (optionally scoped by `since`/`user_id`). */
         usage: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.since)
-                qs.set('since', q.since);
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/ai/usage${s ? `?${s}` : ''}`)).data;
+            const s = qs({
+                since: q?.since || undefined,
+                user_id: q?.user_id || undefined,
+                limit: q?.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/ai/usage${s}`)).data;
         },
     };
     /**
@@ -1283,12 +1396,7 @@ export class Vxil {
             /** List an agent's conversations, newest-updated first (optionally scoped
              *  to one end user). */
             list: async (agentId, q) => {
-                const qs = new URLSearchParams();
-                if (q?.user_id)
-                    qs.set('user_id', q.user_id);
-                if (q?.limit)
-                    qs.set('limit', String(q.limit));
-                const s = qs.size ? `?${qs.toString()}` : '';
+                const s = qs({ user_id: q?.user_id || undefined, limit: q?.limit || undefined });
                 return (await this.call('GET', `/v1/copilot/${encodeURIComponent(agentId)}/conversations${s}`)).data;
             },
             /** A conversation row + the last N transcript messages (oldest-first). */
@@ -1306,11 +1414,8 @@ export class Vxil {
          *  frame with seq > `since` plus `done` — replays without re-running (or
          *  re-billing) the turn. Defaults to the conversation's latest turn. */
         resume: async (conversationId, q) => {
-            const qs = new URLSearchParams();
-            qs.set('since', String(q?.since ?? 0));
-            if (q?.message_id)
-                qs.set('message_id', q.message_id);
-            return (await this.call('GET', `/v1/copilot/conversations/${encodeURIComponent(conversationId)}/stream?${qs.toString()}`)).data;
+            const s = qs({ since: q?.since ?? 0, message_id: q?.message_id || undefined });
+            return (await this.call('GET', `/v1/copilot/conversations/${encodeURIComponent(conversationId)}/stream${s}`)).data;
         },
         /** Confirm a proposed action — the ONLY way a write executes. The client
          *  sends just the path ids; everything that runs comes from the persisted
@@ -1320,14 +1425,11 @@ export class Vxil {
         confirm: async (conversationId, messageId, opts) => (await this.call('POST', `/v1/copilot/conversations/${encodeURIComponent(conversationId)}/actions/${encodeURIComponent(messageId)}/confirm`, undefined, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
         /** Per-user token rollup across assistant turns. */
         usage: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.since)
-                qs.set('since', q.since);
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const s = qs.size ? `?${qs.toString()}` : '';
+            const s = qs({
+                since: q?.since || undefined,
+                user_id: q?.user_id || undefined,
+                limit: q?.limit || undefined,
+            });
             return (await this.call('GET', `/v1/copilot/usage${s}`)).data;
         },
     };
@@ -1341,13 +1443,30 @@ export class Vxil {
      */
     payments = {
         /** Provider + ledger capability surface (+ the `missing` set an agent can act
-         *  on to recommend a provider). */
+         *  on to recommend a provider). `client` is the RevenueCat tenant's PUBLIC
+         *  SDK handout (project id + public SDK key — never the secret key); null
+         *  for every other provider. */
         capabilities: async () => (await this.call('GET', '/v1/payments/capabilities')).data,
         /** The user's effective entitlement snapshot (the multi-sub tier fold):
-         *  tier + boolean entitlements + numeric quotas. */
-        getEntitlements: async (userId) => (await this.call('GET', `/v1/payments/entitlements?user_id=${encodeURIComponent(userId)}`)).data,
+         *  tier + boolean entitlements + numeric quotas — plus the access window
+         *  (`since` / `until` = the winning subscription's period end, or end +
+         *  grace when it is past_due), `as_of` (server time), the `environment`
+         *  the winning subscription was written from, and OPTIONAL inline reads:
+         *  `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). */
+        getEntitlements: async (userId, opts) => {
+            const s = qs({
+                user_id: userId,
+                quota: opts?.quota || undefined,
+                credit_type: opts?.creditType || undefined,
+            });
+            return (await this.call('GET', `/v1/payments/entitlements${s}`)).data;
+        },
         /** Boolean gate: does the user hold `entitlement`? Returns granted + its
-         *  source (subscription/tier) + the resolved tier. */
+         *  source (subscription/tier) + the resolved tier, plus `until` (how long
+         *  the answer is good for) and `as_of`. Non-2xx = unknown, never free. */
         hasEntitlement: async (userId, entitlement) => (await this.call('GET', `/v1/payments/entitlements/check?user_id=${encodeURIComponent(userId)}&entitlement=${encodeURIComponent(entitlement)}`)).data,
         /** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
          *  the resolved tier declares no such quota. Convenience over getEntitlements. */
@@ -1376,12 +1495,12 @@ export class Vxil {
         /** Recent ledger rows for the user (the audit/trail surface), newest first;
          *  optionally scoped to one credit type. */
         usage: async (q) => {
-            const qs = new URLSearchParams({ user_id: q.user_id });
-            if (q.credit_type)
-                qs.set('credit_type', q.credit_type);
-            if (q.limit)
-                qs.set('limit', String(q.limit));
-            return (await this.call('GET', `/v1/payments/usage?${qs.toString()}`)).data;
+            const s = qs({
+                user_id: q.user_id,
+                credit_type: q.credit_type || undefined,
+                limit: q.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/payments/usage${s}`)).data;
         },
         /** Start a subscription (mock = instant checkout; real providers redirect via
          *  their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
@@ -1393,13 +1512,8 @@ export class Vxil {
         /** List subscriptions (the cancel enabler — discover the subscription_id);
          *  optionally scoped to one user / status. */
         listSubscriptions: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.status)
-                qs.set('status', q.status);
-            const s = qs.toString();
-            return (await this.call('GET', `/v1/payments/subscriptions${s ? `?${s}` : ''}`)).data.subscriptions;
+            const s = qs({ user_id: q?.user_id || undefined, status: q?.status || undefined });
+            return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;
         },
         /**
          * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
@@ -1415,20 +1529,56 @@ export class Vxil {
          * NEVER exceed the charge (422 refund_exceeds_charge).
          */
         createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
-        /** The provider-hosted billing-management portal URL for an end user (Stripe
-         *  billing portal; mock is deterministic; RC/Paddle/PayPal → 501). */
+        /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
+         *  (the provider of their live subscription, not the tenant's primary):
+         *  `kind: 'portal'` = a provider-minted portal session URL (Stripe, Paddle
+         *  via the captured customer id, mock); `'store'` = the App Store / Play
+         *  Store manage-subscriptions page for a RevenueCat row that recorded its
+         *  store; `'none'` (url null) = nothing to link (PayPal, a manual grant, no
+         *  live subscription on a portal-less primary). */
         getCustomerPortalUrl: async (userId) => (await this.call('GET', `/v1/payments/customer-portal-url?user_id=${encodeURIComponent(userId)}`)).data,
+        /** SERVER-ONLY. A support / promotional / migration grant: a `manual`
+         *  subscription row (no provider behind it) folded like a webhook —
+         *  entitlements + the tier's recurring credits apply; `until` null =
+         *  open-ended, else access ends at `until`. Idempotent on
+         *  `idempotency_key` (a replay returns the first grant, `replayed: true`).
+         *  422 unknown_tier when the tier is not in ledger.tierMap. */
+        grantSubscription: async (input) => (await this.call('POST', '/v1/payments/subscriptions/grant', input)).data,
+        /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
+         *  subscription — use `cancel`). Never touches a provider. */
+        revokeSubscription: async (subscriptionId) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/revoke`)).data,
+        /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
+         *  fold them through the same conditional upsert a webhook uses (never a
+         *  second write path). `dry_run` diffs without writing. Capped 30/min per
+         *  project (429 rate_limited). The migration backfill (`vxil migrate
+         *  payments --from-provider …`) drives this per customer. */
+        syncSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/sync', input)).data,
+        /** The server leg of "Restore Purchases": in end-user mode the verified
+         *  principal's OWN provider state is re-read (no user id needed); in server
+         *  mode pass `user_id`. 3 per hour per user (429). Returns the sync outcome
+         *  plus the fresh entitlement view in one answer. */
+        restoreSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/restore', input ?? {})).data,
+        /** SERVER-ONLY. Account merge: move EVERY provider's subscriptions,
+         *  customer links and available credit balances of `from_user_id` onto
+         *  `into_user_id` — at-most-once per pair. The consumer of the
+         *  `auth.user.merged { from, into }` audit event. */
+        reKeySubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/re-key', input)).data,
+        /** SERVER-ONLY, mock/dev tenants ONLY (403 simulation_not_allowed
+         *  elsewhere). Drive a scripted lifecycle (renewal, expiry, refund-pair,
+         *  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,
+        /** The last report-only reconciliation sweep result for this project
+         *  (`run: null` before the first daily tick). */
+        reconcile: async () => (await this.call('GET', '/v1/payments/reconcile')).data,
         /** List charges newest-first (the refund enabler — discover the charge_id).
          *  Filters: user_id, status, limit (clamped 1..100, default 50). */
         listCharges: async (q) => {
-            const qs = new URLSearchParams();
-            if (q?.user_id)
-                qs.set('user_id', q.user_id);
-            if (q?.status)
-                qs.set('status', q.status);
-            if (q?.limit)
-                qs.set('limit', String(q.limit));
-            const suffix = qs.size ? `?${qs.toString()}` : '';
+            const suffix = qs({
+                user_id: q?.user_id || undefined,
+                status: q?.status || undefined,
+                limit: q?.limit || undefined,
+            });
             return (await this.call('GET', `/v1/payments/charges${suffix}`)).data;
         },
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
@@ -1439,20 +1589,15 @@ export class Vxil {
             /** List deliveries newest-first (keyset-paginated; pass `cursor` from a
              *  prior page's next_cursor). List rows omit payload/raw_body. */
             list: async (q) => {
-                const qs = new URLSearchParams();
-                if (q?.provider)
-                    qs.set('provider', q.provider);
-                if (q?.event_type)
-                    qs.set('event_type', q.event_type);
-                if (q?.outcome)
-                    qs.set('outcome', q.outcome);
-                if (q?.since)
-                    qs.set('since', q.since);
-                if (q?.cursor)
-                    qs.set('cursor', q.cursor);
-                if (q?.limit)
-                    qs.set('limit', String(q.limit));
-                const suffix = qs.size ? `?${qs.toString()}` : '';
+                const suffix = qs({
+                    provider: q?.provider || undefined,
+                    event_type: q?.event_type || undefined,
+                    outcome: q?.outcome || undefined,
+                    environment: q?.environment || undefined,
+                    since: q?.since || undefined,
+                    cursor: q?.cursor || undefined,
+                    limit: q?.limit || undefined,
+                });
                 return (await this.call('GET', `/v1/payments/webhook-events${suffix}`)).data;
             },
             /** Full delivery detail incl. the verified payload and (for failed