@vxil/sdk 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,15 +1,77 @@
-/** 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). */
 export type ApiVersion = 'v1';
 /** A per-feature API-version override key: the URL namespace that leads a path
  *  (`/v1/<namespace>/…`). Matches the segment `versionedPath` rewrites, so an
  *  override changes exactly that namespace's paths. Renamed client accessors map
  *  onto their real namespaces (`vx.search` → `search`, `vx.feeds` → `feeds`). */
-export type FeatureKey = 'users' | 'notifications' | 'config' | 'features' | 'audit' | 'jobs' | 'auth' | 'rate-limits' | 'files' | 'cms' | 'comments' | 'dm' | 'feeds' | 'realtime' | 'orgs' | 'webhooks' | 'search' | 'ai' | 'rag' | 'payments' | 'fn' | 'copilot';
+export type FeatureKey = 'users' | 'notifications' | 'config' | 'features' | 'audit' | 'usage' | 'jobs' | 'auth' | 'rate-limits' | 'files' | 'cms' | 'comments' | 'dm' | 'feeds' | 'realtime' | 'orgs' | 'webhooks' | 'search' | 'ai' | 'rag' | 'payments' | 'fn' | 'copilot';
+/** Retry policy for the client (DEFAULT OFF: `attempts` is `0`). Only
+ *  idempotent requests are ever retried — GET/HEAD/PUT/DELETE, and a POST only
+ *  when the call carries an `Idempotency-Key` header (`{ idempotencyKey }` on
+ *  the money routes) — so a retry can never double-apply a write. */
+export interface VxilRetryOptions {
+    /** How many RETRIES to make after the first attempt (`2` ⇒ up to 3 requests).
+     *  Default `0` = retries off. */
+    attempts?: number;
+    /** Response statuses that trigger a retry. Default `[429, 502, 503, 504]`. */
+    retryOn?: number[];
+    /** Base delay before the first retry; doubles each retry (with jitter in
+     *  `[½, 1]` of the computed delay). Default `250`. */
+    backoffMs?: number;
+    /** The longest the client will ever wait between attempts. Also the cap on
+     *  an honoured `Retry-After`: when the server asks for MORE than this the
+     *  client does not retry and surfaces the error (its `retryAfter` tells you
+     *  how long the server asked for). Default `10_000`. */
+    maxBackoffMs?: number;
+    /** Use the response's `Retry-After` header (seconds or an HTTP-date) as the
+     *  delay instead of the backoff schedule when present. Default `true`. */
+    respectRetryAfter?: boolean;
+    /** Also retry when `fetch` itself fails (DNS, connection reset, a
+     *  `timeoutMs` timeout) — again only for idempotent requests. Default `true`
+     *  (inert while `attempts` is `0`). */
+    retryOnNetworkError?: boolean;
+}
+/** What a hook sees of a request: a FROZEN descriptor. Credential headers
+ *  (`authorization`, `x-vxil-end-user`) are never included. */
+export interface VxilRequestInfo {
+    readonly method: string;
+    readonly url: string;
+    readonly headers: Readonly<Record<string, string>>;
+    /** 1 for the first attempt, 2 for the first retry, … */
+    readonly attempt: number;
+}
+/** Request lifecycle hooks. Each may be async; a thrown error propagates to
+ *  the caller (the request is not sent / the response is not returned). */
+export interface VxilHooks {
+    /** Runs before EVERY attempt (so a retry can carry a fresh trace id). May
+     *  return extra headers to add for that attempt — a correlation id, a
+     *  tracing header. The credential headers cannot be set from a hook (they
+     *  are dropped); rotate an end-user session with `vx.asEndUser(token)`. */
+    beforeRequest?: (request: VxilRequestInfo) => void | Record<string, string> | Promise<void | Record<string, string>>;
+    /** Runs after every response that arrives (2xx or not, retried or final),
+     *  before the retry decision. The body has already been read into the
+     *  client — inspect `response.status` / `response.headers`, not the body. */
+    afterResponse?: (info: {
+        request: VxilRequestInfo;
+        response: Response;
+        durationMs: number;
+    }) => void | Promise<void>;
+    /** Runs right before the client sleeps for a retry. `status` is set for a
+     *  retryable response, `error` for a network failure / timeout. */
+    onRetry?: (info: {
+        request: VxilRequestInfo;
+        delayMs: number;
+        status?: number;
+        error?: unknown;
+    }) => void | Promise<void>;
+}
 export interface VxilOptions {
+    /** The tenant API key (`vxil_live_…` / `vxil_test_…`).
+     *
+     *  A key may optionally be minted with an **IP allowlist** (`allowed_cidrs`,
+     *  set in the dashboard at mint time). When it is, a call from an address
+     *  outside that list is refused at the edge with `403 ip_not_allowed` —
+     *  before it reaches any feature — and the key is otherwise unchanged. Keys
+     *  minted without one (the default) are not IP-restricted. */
     apiKey: string;
     /** defaults to the production edge */
     baseUrl?: string;
@@ -33,6 +95,19 @@ export interface VxilOptions {
      *  over `apiVersion` for that namespace only. Optional; the compiled default
      *  is `'v1'` for every feature. */
     apiVersions?: Partial<Record<FeatureKey, ApiVersion>>;
+    /** Retry policy — DEFAULT OFF (`attempts: 0`). Only idempotent requests are
+     *  ever retried (GET/HEAD/PUT/DELETE, and a POST only when it carries an
+     *  `Idempotency-Key`), so a retry can never double-apply a write. See
+     *  `VxilRetryOptions` for the schedule and `Retry-After` handling. */
+    retry?: VxilRetryOptions;
+    /** Per-attempt timeout in milliseconds (default: none). On expiry the
+     *  request — body read included — is aborted and a `VxilError`
+     *  `{ status: 0, code: 'request_timeout' }` is thrown. A timeout counts as a
+     *  network error for `retry`. */
+    timeoutMs?: number;
+    /** Request lifecycle hooks — correlation ids, logging, metrics, a retry
+     *  audit. Nothing runs unless set. See `VxilHooks`. */
+    hooks?: VxilHooks;
 }
 /** Rewrite a built `/v1/<ns>/…` path onto the version configured for its
  *  namespace: the per-namespace override wins, else the global default. PURE and
@@ -44,13 +119,24 @@ export interface Meta {
     request_id: string;
     tenant_id?: string;
 }
+/** 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 declare class VxilError extends Error {
     readonly status: number;
     readonly code: string;
     readonly hint?: string | undefined;
     readonly fixUrl?: string | undefined;
     readonly requestId?: string | undefined;
-    constructor(status: number, code: string, message: string, hint?: string | undefined, fixUrl?: string | undefined, requestId?: string | undefined);
+    /** 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. */
+    readonly retryAfter?: number | undefined;
+    constructor(status: number, code: string, message: string, hint?: string | undefined, fixUrl?: string | undefined, requestId?: string | undefined, 
+    /** 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?: number | undefined);
 }
 export interface VxilUser {
     id: string;
@@ -78,6 +164,44 @@ export interface Delivery {
     queued_at: string;
     sent_at: string | null;
     failed_at: string | null;
+    /** Engagement stamps from the signed provider webhook (first-wins). `null`
+     *  means "no such event received", NOT "did not happen". */
+    delivered_at?: string | null;
+    opened_at?: string | null;
+    clicked_at?: string | null;
+}
+/** An ADDITIVE, non-fatal note on a 202 send — today only `mock_provider`
+ *  (the send is recorded but no email leaves vxil). */
+export interface NotificationWarning {
+    code: string;
+    message: string;
+    hint?: string;
+}
+export interface NotificationSendResult {
+    delivery_id?: string;
+    inbox_message_id?: string;
+    status: string;
+    /** present only for a scheduled send (`send_at` / `delay_seconds`) */
+    scheduled_for?: string;
+    warnings?: NotificationWarning[];
+}
+export interface Campaign {
+    campaign_id: string;
+    name: string;
+    channel: string;
+    template_id: string;
+    audience_ref: string;
+    schedule_cron: string | null;
+    status: 'draft' | 'scheduled' | 'running' | 'done' | 'paused' | 'cancelled';
+    created_at: string;
+    /** the jobs schedule row this campaign owns; null = no cron registered */
+    schedule_id?: string | null;
+    last_run_at?: string | null;
+}
+export interface CampaignState {
+    campaign_id: string;
+    status: string;
+    schedule_id: string | null;
 }
 export interface FeatureConfig {
     feature: string;
@@ -131,6 +255,33 @@ export interface VxilPlan {
     /** which brain produced the plan. */
     source: 'ai' | 'deterministic';
 }
+/** Current-month usage projection (GET /v1/usage) — the same meter the
+ *  platform bills and enforces request quotas from. */
+export interface UsageCurrent {
+    /** the current UTC month, 'YYYY-MM'. */
+    period: string;
+    /** the plan tier the quota is derived from. */
+    tier: string;
+    requests: {
+        /** requests recorded this month (0 until the meter has rows). */
+        used: number;
+        /** the plan's included monthly requests; null = no fixed cap. */
+        quota: number | null;
+        /** max(quota − used, 0); null when quota is null. */
+        remaining: number | null;
+        /** the PLAN's hard-cap policy — true only on the free tier (which is cut
+         *  off with 429 quota_exceeded when exhausted); paid tiers are never
+         *  interrupted mid-month. Not a live "the next request will 429" signal. */
+        enforced: boolean;
+    };
+    /** month-to-date per-feature metered detail. Aggregated periodically — it
+     *  may lag and may be empty. */
+    features: Array<{
+        feature: string;
+        metric: string;
+        quantity: number;
+    }>;
+}
 export interface DeadLetter {
     delivery_id: string;
     template_id: string;
@@ -203,8 +354,14 @@ export interface PaymentsWebhookEvent {
     provider: string;
     provider_evt_id: string;
     event_type: string;
-    /** received | processed | error | sig_failed | parse_failed | reprocessed */
+    /** received | processed | error | sig_failed | parse_failed | reprocessed |
+     *  ignored (a well-formed provider type we deliberately do not fold) |
+     *  unowned (no end user resolvable) | rejected_environment (a sandbox event
+     *  the tenant did not opt into) — the last three are 200-acked, never folded. */
     outcome: string | null;
+    /** the PROVIDER-reported environment of the delivery ('production' |
+     *  'sandbox') — a separate axis from the API key's live/test label. */
+    environment?: 'production' | 'sandbox';
     signature_ok: boolean;
     error: string | null;
     received_at: string | null;
@@ -217,6 +374,70 @@ export interface PaymentsWebhookEvent {
     raw_body?: string | null;
     provider_event_ts?: string | null;
 }
+/** The outcome of a provider re-sync / Restore Purchases (payments.md §7d). */
+export interface PaymentsSyncOutcome {
+    provider: string;
+    synced: number;
+    changed: number;
+    unchanged: number;
+    errors: string[];
+    changes: Array<{
+        provider_sub_id: string;
+        status: string;
+        tier: string | null;
+        until: string | null;
+    }>;
+    dry_run?: boolean;
+}
+/** A lifecycle simulation run (payments.md §7d; mock/dev tenants only). */
+export interface PaymentsSimulationResult {
+    scenario: string;
+    run_id: string;
+    user_id: string;
+    tier: string;
+    tenant_kind: 'standard' | 'dev' | 'unknown';
+    note: string;
+    steps: Array<{
+        event_type: string;
+        status: number;
+        outcome: string;
+    }>;
+    oracle: {
+        expected: Record<string, 'premium' | 'free'>;
+        observed: Record<string, {
+            tier: string;
+            until: string | null;
+        }>;
+        pass: boolean;
+    };
+}
+/** The ONE complete entitlement read (GET /v1/payments/entitlements; payments.md
+ *  §3a). `until` is the winning subscription's current_period_end (+ the
+ *  configured grace window when it is past_due); null on the free baseline. */
+export interface PaymentsEntitlementView {
+    user_id: string;
+    tier: string;
+    entitlements: string[];
+    quotas: Record<string, number>;
+    source_sub_id: string | null;
+    since: string | null;
+    until: string | null;
+    as_of: string;
+    environment: 'production' | 'sandbox';
+    /** present only when `?quota=` was asked for */
+    quota?: {
+        name: string;
+        value: number | null;
+    };
+    /** present only when `?credit_type=` was asked for */
+    credits?: {
+        credit_type: string;
+        balance: number;
+        held: number;
+        available: number;
+        period_end: string | null;
+    };
+}
 export interface FileObject {
     object_id: string;
     filename: string;
@@ -225,6 +446,26 @@ export interface FileObject {
     status: 'pending' | 'available' | 'deleted';
     created_at: string;
 }
+/** A live shared link as listed by GET /v1/files/{id}/shared-links (files.md
+ *  §6). `downloads` is the burn-on-read counter; `max_downloads` null =
+ *  unlimited (1 = a one-time link). A link that hit its cap, expired, or was
+ *  revoked no longer lists. */
+export interface FileSharedLink {
+    link_id: string;
+    created_at: string;
+    expires_at: string;
+    downloads: number;
+    max_downloads: number | null;
+}
+/** Options for POST /v1/files/{id}/shared-links. `expires_at` (ISO 8601) takes
+ *  precedence over `ttl_seconds`; both are clamped to the tenant's
+ *  `sharedLinks.maxTtl`. `max_downloads` ≥ 1 caps successful public
+ *  resolutions (1 = one-time link); omit for unlimited. */
+export interface CreateSharedLinkOptions {
+    ttl_seconds?: number;
+    expires_at?: string;
+    max_downloads?: number | null;
+}
 /** One recognized OCR text block (files.md §1.1). bbox is [x, y, w, h] in the
  *  provider's unit space; page is 1-based. confidence is 0..1 normalized per
  *  provider (Textract native 0..100 divided by 100; mock pins 0.95); absent
@@ -351,6 +592,12 @@ export interface AiGeneration {
     usage: AiUsage;
     finish: string;
     tool_calls?: AiToolCall[];
+    /** the parsed JSON output — present when the request (or its template)
+     *  carried a response schema; guaranteed to satisfy it (a 200 never violates
+     *  the schema — final-invalid is a 422 output_schema_mismatch). */
+    output?: unknown;
+    /** true when the output only validated after the single repair pass. */
+    repaired?: boolean;
     cached: boolean;
 }
 /** A streamed generation handle: open the realtime channel for token frames. */
@@ -415,6 +662,57 @@ export interface AiEmbedResult {
     usage: AiUsage;
     generation_id: string;
 }
+/** The per-request knobs every verdict route shares (POST /v1/ai/classify and
+ *  /v1/ai/judge): a stored template may author the whole prompt (rendered with
+ *  the verdict vars — `{{input}}`, `{{labels}}`, `{{rubric}}`, `{{examples}}` /
+ *  `{{candidate}}`, `{{candidates}}`, `{{criteria}}`, `{{scale_min}}`,
+ *  `{{scale_max}}` — plus your own `vars`); provider/model override the tenant
+ *  defaults; `max_tokens` defaults to min(config maxTokens, 512) and
+ *  `temperature` to 0. Verdicts are sync-only (no stream / job mode). */
+export interface AiVerdictOptions {
+    template?: string;
+    template_version?: number;
+    vars?: Record<string, unknown>;
+    provider?: string;
+    model?: string;
+    max_tokens?: number;
+    temperature?: number;
+    user_id?: string;
+}
+/** A classify verdict (POST /v1/ai/classify). `label` (single) or `labels`
+ *  (multi:true — every applicable label, possibly empty) is guaranteed to be
+ *  drawn from the request's `labels`: the allowed set is forced through the
+ *  structured-output schema, so a 200 can never carry an off-list label. */
+export interface AiClassifyResult {
+    generation_id: string;
+    label?: string;
+    labels?: string[];
+    /** 0..1 */
+    confidence: number;
+    rationale?: string;
+    usage: AiUsage;
+    /** true when the verdict only validated after the one repair pass. */
+    repaired?: boolean;
+    cached: boolean;
+}
+/** A judge verdict (POST /v1/ai/judge). One `candidate` → `score` (an integer
+ *  inside `scale`, default 0..10) + `verdict: 'pass' | 'fail'`; several
+ *  `candidates` → `scores` (one per candidate, in order) + `best` (the index of
+ *  the top score) + `verdict: 'tie'` when the top score is shared. Sending
+ *  `candidates` ALWAYS yields `scores` + `best` — a one-element list keeps the
+ *  richer `score`/`pass|fail` fields too, so the shape never flips out from
+ *  under a variable-length array. */
+export interface AiJudgeResult {
+    generation_id: string;
+    score?: number;
+    scores?: number[];
+    verdict?: 'pass' | 'fail' | 'tie';
+    best?: number;
+    rationale?: string;
+    usage: AiUsage;
+    repaired?: boolean;
+    cached: boolean;
+}
 /** Per-user token rollups (GET /v1/ai/usage). */
 export interface AiUsageReport {
     input_tokens: number;
@@ -817,6 +1115,35 @@ type DisabledFeatures<S extends VxilSchemaShape> = {
 export type EnabledVxil<S extends VxilSchemaShape> = Omit<Vxil<S>, DisabledFeatures<S>> & {
     [P in DisabledFeatures<S>]: DisabledFeature<FeatureMap[P] & string>;
 };
+/** One config-declared per-record ACTION (cms.md §17): a button on a record row
+ *  that invokes the deployed tenant function `fn` ONCE with `{ collection,
+ *  item_id, action, actor, item }`. Exactly one human-initiated step — no
+ *  conditions, no chaining, no scheduling. ≤8 per collection. */
+export interface CmsActionDef {
+    /** /^[a-z][a-z0-9_]{0,31}$/ — the URL key of `items.runAction` */
+    key: string;
+    /** the button label (1–64 chars) */
+    label: string;
+    /** the deployed function name (/^[a-z][a-z0-9-]{0,47}$/) */
+    fn: string;
+}
+/** One live item referencing another through a relation field (cms.md §11.1). */
+export interface CmsBacklink {
+    collection: string;
+    field: string;
+    item_id: string;
+    status: string;
+}
+/** The bounded reverse read (`items.backlinks`): `count` = rows in THIS page
+ *  (≤ `limit`), never a total; `has_more` = the cap was hit. */
+export interface CmsBacklinksPage {
+    collection: string;
+    item_id: string;
+    backlinks: CmsBacklink[];
+    count: number;
+    has_more: boolean;
+    limit: number;
+}
 /** A write guard (cms.md §10): "after this write, at most `max` live items
  *  match `filter`". Requires `lock` — an unlocked guard is racy by construction. */
 export interface CmsGuard {
@@ -1002,6 +1329,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     /** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
      *  mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
     private readonly endUserToken;
+    /** The ONE path every request takes: retry + timeout + hooks around
+     *  `fetchImpl`. With none of the three configured it is a single fetch. */
+    private readonly transport;
+    private readonly retryOpts;
+    private readonly timeoutMs;
+    private readonly hooks;
     constructor(opts: VxilOptions);
     /** 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.
@@ -1010,8 +1343,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     /** 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: string | undefined): Vxil<S>;
     /** Build the versioned request path — the ONE place a wire path is finalized.
@@ -1084,15 +1417,72 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id: string;
             template: "magic-link" | "welcome" | "transactional";
             data: Record<string, unknown>;
+            /** Explicit wins; otherwise the recipient's stored `locale` attribute
+             *  (set it via `users.upsert({ attributes: { locale } })`), then
+             *  `config.defaultLocale`. */
             locale?: string;
             /** 'inbox'/'both' require config inboxEnabled */
             channel?: "email" | "inbox" | "both";
+            /** hold the send until this ISO instant (≤ 30 d out) */
+            send_at?: string;
+            /** …or this many seconds from now (≤ 30 d). At most one of the two. */
+            delay_seconds?: number;
         }, opts?: {
             idempotencyKey?: string;
+        }) => Promise<NotificationSendResult>;
+        /** Up to 100 sends in one call. Each item is INDEPENDENTLY atomic (recorded
+         *  + enqueued, or neither) and `results` is index-aligned with `items`. */
+        sendBatch: (items: Array<{
+            user_id: string;
+            template: "magic-link" | "welcome" | "transactional";
+            data: Record<string, unknown>;
+            locale?: string;
+            channel?: "email" | "inbox" | "both";
+            send_at?: string;
+            delay_seconds?: number;
+            /** per-item 24 h idempotency key (the header equivalent for one item) */
+            idempotency_key?: string;
+        }>) => Promise<{
+            results: Array<{
+                index: number;
+                delivery_id?: string;
+                inbox_message_id?: string;
+                status?: string;
+                scheduled_for?: string;
+                error?: {
+                    code: string;
+                    message: string;
+                    hint?: string;
+                };
+            }>;
+            count: number;
+            accepted: number;
+            failed: number;
+            warnings?: NotificationWarning[];
+        }>;
+        /** Render a template exactly as a send would, WITHOUT sending. `missing`
+         *  lists the required data keys you left out. Needs `notifications:read`. */
+        preview: (templateId: string, input?: {
+            data?: Record<string, unknown>;
+            locale?: string;
         }) => Promise<{
-            delivery_id?: string;
-            inbox_message_id?: string;
-            status: string;
+            template_id: string;
+            locale: string;
+            overridden: boolean;
+            subject: string;
+            html: string;
+            text: string;
+            missing: string[];
+        }>;
+        /** 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: () => Promise<{
+            domain: string | null;
+            verified: boolean | "unknown";
+            provider: string;
+            checked_at: string;
+            reason?: string;
         }>;
         inbox: {
             list: (q: {
@@ -1120,6 +1510,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             user_id?: string;
             status?: string;
             limit?: number;
+            /** A7: only deliveries that reached this engagement state */
+            engagement?: "delivered" | "opened" | "clicked";
         }) => Promise<Delivery[]>;
         suppressions: {
             list: () => Promise<Array<{
@@ -1161,17 +1553,36 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }) => Promise<{
                 campaign_id: string;
                 status: string;
+                schedule_id: string | null;
             }>;
-            list: () => Promise<Array<{
+            list: () => Promise<Campaign[]>;
+            /** Stop a scheduled campaign from firing (the jobs cron is torn down). */
+            pause: (campaignId: string) => Promise<CampaignState>;
+            /** Re-register the cron (back to `scheduled`, or `draft` with no cron). */
+            resume: (campaignId: string) => Promise<CampaignState>;
+            /** Terminal stop — the cron is removed and the campaign cannot resume. */
+            cancel: (campaignId: string) => Promise<CampaignState>;
+            /** 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: (campaignId: string) => Promise<CampaignState & {
+                deleted?: boolean;
+            }>;
+            /** 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: (campaignId: string, audience?: Array<{
+                end_user_id: string;
+                locale?: string | null;
+            }>) => Promise<{
                 campaign_id: string;
-                name: string;
-                channel: string;
-                template_id: string;
-                audience_ref: string;
-                schedule_cron: string | null;
-                status: string;
-                created_at: string;
-            }>>;
+                audience_source: "supplied" | "builtin" | "external";
+                audience_size: number;
+                sent: number;
+                deferred: number;
+                skipped_freq_cap: number;
+                skipped_no_email: number;
+                already_sent: number;
+            }>;
         };
     };
     readonly config: {
@@ -1249,6 +1660,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
         }>;
     };
+    /** 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. */
+    readonly usage: {
+        current: () => Promise<UsageCurrent>;
+    };
     readonly jobs: {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
@@ -1414,6 +1832,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             delete: (ruleId: string) => Promise<void>;
         };
     };
+    /** 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. */
     readonly auth: {
         signUp: (input: {
             email: string;
@@ -1446,9 +1874,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  Server-side guessing budget (config otp.maxAttempts), single active code,
          *  resend cooldown (429 otp_rate_limited). */
         otp: {
+            /** `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: (input: {
                 email: string;
-            }) => Promise<void>;
+                locale?: string;
+                captcha_token?: string;
+            }) => Promise<{
+                sent: true;
+                test_code?: string;
+            }>;
             verify: (input: {
                 email: string;
                 code: string;
@@ -1470,7 +1907,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 request: (input: {
                     token: string;
                     email: string;
-                }) => Promise<void>;
+                    locale?: string;
+                }) => Promise<{
+                    sent: true;
+                    test_code?: string;
+                }>;
+                /** 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: (input: {
                     token: string;
                     email: string;
@@ -1479,6 +1925,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     user_id: string;
                     email: string;
                     verified: boolean;
+                    merged?: true;
+                    session?: {
+                        token: string;
+                        expires_at: string;
+                    };
                 }>;
             };
         };
@@ -1488,7 +1939,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         stepUp: {
             request: (input: {
                 token: string;
-            }) => Promise<void>;
+                locale?: string;
+            }) => Promise<{
+                sent: true;
+                test_code?: string;
+            }>;
             verify: (input: {
                 token: string;
                 code: string;
@@ -1506,11 +1961,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  (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: (userId: string) => Promise<{
                 user_id: string;
                 erased: boolean;
             }>;
+            /** 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: (attributes: Record<string, unknown>) => Promise<{
+                user_id: string;
+                attributes: Record<string, unknown>;
+            }>;
         };
         sessions: {
             verify: (token: string) => Promise<{
@@ -1528,11 +1994,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 session: AuthSession;
             }>;
             revoke: (token: string) => Promise<void>;
+            /** "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: (userId?: string) => Promise<{
+                user_id: string;
+                revoked: number;
+                session_ids: string[];
+            }>;
             /** 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: (sessionId: string) => Promise<void>;
-            /** 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: (userId: string) => Promise<Array<{
                 session_id: string;
                 created_at: string;
@@ -1551,21 +2032,48 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 password: string;
             }) => Promise<void>;
         };
+        /** 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: (input: {
+                email: string;
+                redirect_url: string;
+                locale?: string;
+                captcha_token?: string;
+            }) => Promise<void>;
+            confirm: (token: string) => Promise<{
+                user_id: string;
+                verified: true;
+            }>;
+        };
         /** 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: (provider: "google" | "apple" | "github" | "facebook" | "mock", input: {
+            native: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
                 id_token?: string;
                 access_token?: string;
                 nonce?: string;
+                anonymous_token?: string;
             }) => Promise<{
                 user_id: string;
                 session: AuthSession;
                 verified: boolean;
-                linked: "created" | "existing";
+                linked: "created" | "existing" | "promoted" | "merged";
+                /** sessions taken over by auth config session.maxConcurrent (present once opted in) */
+                took_over?: string[];
             }>;
         };
     };
@@ -1573,8 +2081,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         createPolicy: (input: {
             name: string;
             key_template: string;
-            limit: number;
-            window_seconds: number;
+            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` (F8-54) */
+            limit?: number;
+            /** omitted ⇒ seeded from the tenant's rate-limits config `defaults` (F8-54) */
+            window_seconds?: number;
             behavior?: "block" | "shape";
         }) => Promise<RateLimitPolicy>;
         listPolicies: () => Promise<RateLimitPolicy[]>;
@@ -1692,14 +2202,31 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                      *  scalar-valued types only. Concurrent duplicates → 409 unique_violation. */
                     unique?: boolean;
                     /** relation fields only: what a delete of the referenced item does to
-                     *  this one (bounded fan-out, cms.md §11). */
-                    on_delete?: "cascade" | "set_null";
+                     *  this one — cascade / set_null (bounded fan-out, cms.md §11) or
+                     *  `restrict` (§11.1: the delete is refused with 409 `referenced`
+                     *  while a live reference exists). */
+                    on_delete?: "cascade" | "set_null" | "restrict";
+                    /** FIELD-LEVEL read security (cms.md §18): the end-user ORG ROLE slugs
+                     *  allowed to READ this field. Omitted/`[]` = ungated. A non-empty list
+                     *  is FAIL-SAFE — in verified end-user mode the field is OMITTED from
+                     *  every read (get / list / query / `$expand` / the write-response echo)
+                     *  unless the session's verified roles intersect it, it is UNQUERYABLE
+                     *  (filter/sort/group-by on it is a 422), and it is NEVER served on the
+                     *  anonymous public lane. A SERVER caller (an API key with no end-user
+                     *  session) still sees every field. Writes are unaffected. ≤16 entries,
+                     *  each `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
+                    read_roles?: string[];
                 }>;
+                /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]` —
+                 *  exactly ONE human-initiated step each; `fn` names a deployed tenant
+                 *  function invoked by `items.runAction`. ≤8 per collection. */
+                actions?: CmsActionDef[];
             }) => Promise<{
                 collection: string;
                 fields: number;
                 owner_field?: string;
                 public?: boolean;
+                actions?: CmsActionDef[];
             }>;
             list: () => Promise<Array<{
                 collection: string;
@@ -1708,6 +2235,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 owner_field?: string | null;
             }>>;
             addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
+            /** 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: (collection: string, field: string, type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file", roles: string[] | null, rest?: Record<string, unknown>) => Promise<void>;
             /** 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: (collection: string, ownerField: string | null) => Promise<void>;
@@ -1717,6 +2252,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the owner_field are never exposed. `false` closes the lane (and purges the
              *  edge cache). Read the public side with `cmsPublicUrl` / `listCmsPublic`. */
             setPublic: (collection: string, isPublic: boolean) => Promise<void>;
+            /** 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: (collection: string, actions: CmsActionDef[]) => Promise<void>;
         };
         items: {
             /** `lock` serializes same-key writers (per-tenant advisory lock); `guard`
@@ -1774,6 +2314,27 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 set_null: number;
             }>;
             publish: (collection: string, itemId: string) => Promise<Record<string, unknown>>;
+            /** 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: (collection: string, itemId: string, opts?: {
+                limit?: number;
+            }) => Promise<CmsBacklinksPage>;
+            /** 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: (collection: string, itemId: string, key: string) => Promise<{
+                collection: string;
+                item_id: string;
+                action: string;
+                fn: string;
+                result: unknown;
+            }>;
             /** 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
@@ -2335,6 +2896,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 }>;
             }>;
         };
+        /** 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: () => Promise<{
+            count: number;
+            events: Array<{
+                name: string;
+                feature: string;
+                level: "lifecycle" | "failure";
+                payload_keys?: string[];
+            }>;
+            prefixes: Array<{
+                prefix: string;
+                count: number;
+            }>;
+        }>;
     };
     readonly orgs: {
         create: (input: {
@@ -2617,20 +3196,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             expires_at: string | null;
         }>;
         sharedLinks: {
-            /** Public (unauthenticated) URL for the object; revocable. */
-            create: (objectId: string, opts?: {
-                ttl_seconds?: number;
-            }) => Promise<{
+            /** 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: (objectId: string, opts?: CreateSharedLinkOptions) => Promise<{
                 link_id: string;
                 url: string;
-                expires_at: string | null;
+                expires_in: number;
+                expires_at: string;
+                max_downloads: number | null;
+                downloads: number;
             }>;
-            /** List an object's active (unrevoked, unexpired) shared links. */
-            list: (objectId: string) => Promise<Array<{
-                link_id: string;
-                created_at: string;
-                expires_at: string | null;
-            }>>;
+            /** List an object's active (unrevoked, unexpired, unexhausted) shared links. */
+            list: (objectId: string) => Promise<FileSharedLink[]>;
             revoke: (linkId: string) => Promise<void>;
         };
     };
@@ -2730,7 +3309,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly 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: (input: {
                 template: string;
                 user: string;
@@ -2772,6 +3354,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  role:'tool' results) — vxil relays; you execute the tools. */
             messages?: AiChatMessage[];
             json_mode?: boolean;
+            /** JSON Schema the completion must satisfy (schema-guaranteed structured
+             *  output): enforced natively where the provider supports strict
+             *  structured output, else via one validate-and-repair pass; the parsed
+             *  object lands in `output` (+`repaired` when the repair pass fired). A
+             *  still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
+             *  over the template's stored schema. */
+            response_schema?: Record<string, unknown>;
             images?: string[];
             user_id?: string;
         }) => Promise<AiGeneration>;
@@ -2823,6 +3412,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
             messages?: AiChatMessage[];
             json_mode?: boolean;
+            /** JSON Schema the completion must satisfy — same contract as
+             *  `generate`; the validated answer lands in the replay buffer (a
+             *  schema-mismatch delivers finish:'schema_mismatch' on the terminal
+             *  usage frame). */
+            response_schema?: Record<string, unknown>;
             images?: string[];
             user_id?: string;
         }) => Promise<AiJobHandle>;
@@ -2841,6 +3435,47 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             done: boolean;
             max_seq: number;
         }>;
+        /** 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: (input: AiVerdictOptions & {
+            input: string | Array<{
+                text: string;
+            }>;
+            labels: string[];
+            multi?: boolean;
+            rubric?: string;
+            examples?: Array<{
+                input: string;
+                label: string;
+            }>;
+        }) => Promise<AiClassifyResult>;
+        /** 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: (input: AiVerdictOptions & {
+            input: string;
+            candidate?: string;
+            candidates?: string[];
+            criteria: string | Array<{
+                name: string;
+                weight?: number;
+            }>;
+            scale?: {
+                min: number;
+                max: number;
+            };
+        }) => Promise<AiJudgeResult>;
         /** Embed a batch of strings (1–256). */
         embed: (input: {
             input: string[];
@@ -2990,27 +3625,43 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
      */
     readonly 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: () => Promise<{
             provider: string;
             capabilities: string[];
             ledger_capabilities: string[];
             missing: string[];
+            client: {
+                revenuecat: {
+                    project_id: string;
+                    public_sdk_key: string;
+                };
+            } | null;
         }>;
         /** The user's effective entitlement snapshot (the multi-sub tier fold):
-         *  tier + boolean entitlements + numeric quotas. */
-        getEntitlements: (userId: string) => Promise<{
-            user_id: string;
-            tier: string;
-            entitlements: string[];
-            quotas: Record<string, number>;
-        }>;
+         *  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: (userId: string, opts?: {
+            quota?: string;
+            creditType?: string;
+        }) => Promise<PaymentsEntitlementView>;
         /** 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: (userId: string, entitlement: string) => Promise<{
             granted: boolean;
             source: string | null;
             tier: string;
+            until: string | null;
+            as_of: string;
         }>;
         /** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
          *  the resolved tier declares no such quota. Convenience over getEntitlements. */
@@ -3161,10 +3812,107 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             status: "pending" | "succeeded" | "failed";
             amount_cents: number;
         }>;
-        /** 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: (userId: string) => Promise<{
-            url: string;
+            url: string | null;
+            kind: "portal" | "store" | "none";
+            provider: string | null;
+        }>;
+        /** 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: (input: {
+            user_id: string;
+            tier: string;
+            until?: string | null;
+            reason: string;
+            idempotency_key: string;
+        }) => Promise<{
+            subscription_id: string | null;
+            user_id: string;
+            tier: string;
+            status: string;
+            until: string | null;
+            replayed: boolean;
+        }>;
+        /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
+         *  subscription — use `cancel`). Never touches a provider. */
+        revokeSubscription: (subscriptionId: string) => Promise<{
+            subscription_id: string;
+            status: string;
+            cancel_at: string | null;
+            revoked_at: string | null;
+        }>;
+        /** 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: (input: {
+            user_id?: string;
+            customer_ref?: string;
+            provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
+            dry_run?: boolean;
+        }) => Promise<PaymentsSyncOutcome>;
+        /** 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: (input?: {
+            user_id?: string;
+            provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
+        }) => Promise<PaymentsSyncOutcome & {
+            entitlements: PaymentsEntitlementView;
+        }>;
+        /** 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: (input: {
+            from_user_id: string;
+            into_user_id: string;
+        }) => Promise<{
+            from_user_id: string;
+            into_user_id: string;
+            moved: number;
+            credits_moved: number;
+        }>;
+        /** 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: (input: {
+            scenario: "refund-pair" | "cross-platform-unlock" | "renewal" | "expiry" | "past-due-grace" | "transfer";
+            user_id: string;
+            tier?: string;
+        }) => Promise<PaymentsSimulationResult>;
+        /** The last report-only reconciliation sweep result for this project
+         *  (`run: null` before the first daily tick). */
+        reconcile: () => Promise<{
+            run: {
+                run_id: string;
+                ran_at: string | null;
+                clean: boolean;
+                discrepancy_count: number;
+                lapsed_count: number;
+                findings: Array<{
+                    kind: string;
+                    count: number;
+                    ids: string[];
+                }>;
+            } | null;
+            enforce_period_end: {
+                slack_hours: number;
+            } | null;
         }>;
         /** List charges newest-first (the refund enabler — discover the charge_id).
          *  Filters: user_id, status, limit (clamped 1..100, default 50). */
@@ -3194,7 +3942,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             list: (q?: {
                 provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
                 event_type?: string;
-                outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed";
+                outcome?: "received" | "processed" | "error" | "sig_failed" | "parse_failed" | "reprocessed" | "ignored" | "unowned" | "rejected_environment";
+                /** the provider-reported environment axis (not the API key's label) */
+                environment?: "production" | "sandbox";
                 since?: string;
                 cursor?: string;
                 limit?: number;