@vxil/sdk 0.10.0 → 0.11.1

package/dist/index.d.ts

@@ -367,6 +367,21 @@ export interface JobRun {
     /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
      *  payload — `{ redacted: true }` for a platform-internal run; never on lists */
     payload_json?: unknown;
+    /** a platform webhook delivery run (`job_name: 'webhooks.deliver'`) only:
+     *  the event type it delivers (e.g. `payments.charge.refunded`) — so a dead
+     *  delivery names WHICH event was lost while its payload stays redacted;
+     *  null on every other run (list + single read, since 2026-10-01) */
+    webhook_event?: string | null;
+    /** a platform webhook delivery run only: the event's id — the `audit_id`
+     *  the delivery carries to your handler and the row id in `GET /v1/audit`;
+     *  null on every other run */
+    audit_id?: number | null;
+    /** the schedule (`sch_…`) that fired this run; null for a run you enqueued */
+    schedule_id?: string | null;
+    /** the SLOT a schedule-fired run was due for (the schedule's next_run_at at
+     *  the fire); `started_at − scheduled_for` is how late it started. null for a
+     *  run you enqueued (and for runs fired before 2026-10-01). */
+    scheduled_for?: string | null;
 }
 /** The run states no later write can move — what `waitForRun` and an
  *  async+wait invoke resolve `done: true` on. */
@@ -404,13 +419,35 @@ export interface JobFlowRule {
     state: string;
     created_at: string;
 }
+/** A schedule that fired on time but whose run has not STARTED for more than
+ *  two of the schedule's intervals past its slot — held downstream (a busy
+ *  queue, your concurrency cap, a flow rule). Announced once as
+ *  `jobs.schedule.missed` with `reason: 'held'` — `functions.schedule.missed`
+ *  (with `function`) for a function's cron trigger (`fn-cron:*`). */
+export interface JobScheduleHeld {
+    run_id: string;
+    scheduled_for: string;
+    held_seconds: number;
+}
 export interface JobSchedule {
     schedule_id: string;
     job_name: string;
-    cron: string | null;
-    run_at: string | null;
+    /** the create echo carries no cron; the list names it `cron_expr` */
+    cron?: string | null;
+    cron_expr?: string | null;
+    run_at?: string | null;
     next_run_at: string | null;
+    last_run_at?: string | null;
     state: string;
+    /** `'skip'`: a due slot fires nothing while an earlier run of this schedule
+     *  is still open (queued / running / retrying / waiting / delayed); the slot
+     *  is counted in `skipped_fires`. `'allow'` (default): every slot fires. */
+    overlap?: 'allow' | 'skip';
+    /** slots skipped since the schedule last fired a run (list only) */
+    skipped_fires?: number;
+    last_skipped_at?: string | null;
+    /** non-null while the schedule is HELD (list only) */
+    held?: JobScheduleHeld | null;
 }
 export interface AuthSession {
     token: string;
@@ -557,11 +594,42 @@ export interface PaymentsCharge {
     /** the one-off product the charge bought (the `ledger.productMap` key), if any */
     product_id: string | null;
     amount_cents: number;
+    /** SETTLED refunds only (2026-10-01): a refund still awaiting the provider is
+     *  in `amount_refund_pending`, and `status` follows the settled total */
     amount_refunded: number;
+    /** reserved by outbound refunds the provider has not settled yet (a Paddle
+     *  adjustment awaiting approval); moves to `amount_refunded` when approved,
+     *  back to 0 when refused */
+    amount_refund_pending: number;
     currency: string;
+    /** succeeded | partially_refunded | refunded | disputed | pending | failed —
+     *  of SETTLED money */
     status: string;
+    /** the provider-reported environment of the money (2026-10-01): a store
+     *  reviewer's sandbox purchase (`revenuecat.sandboxUsers`) is `sandbox` —
+     *  leave it out of revenue */
+    environment: PaymentsEventEnvironment;
     created_at: string;
 }
+/** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
+export interface PaymentsRefund {
+    /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
+     *  / `payments.charge.refunded` names */
+    refund_id: string;
+    charge_id: string;
+    provider: string;
+    /** the provider's own refund / adjustment id (null until the provider answered) */
+    provider_refund_id: string | null;
+    amount_cents: number;
+    currency: string;
+    reason: string | null;
+    /** `pending` until the provider settles it (a Paddle adjustment awaiting approval) */
+    status: 'pending' | 'succeeded' | 'failed';
+    /** `api` = issued through POST /v1/payments/refunds; `webhook` = recorded from the
+     *  provider (a refund made in the provider's own dashboard) */
+    source: 'api' | 'webhook';
+    created_at: string | null;
+}
 /** A subscription row as listed by GET /v1/payments/subscriptions (payments.md
  *  §3) — provider subscriptions, manual grants and purchase passes alike.
  *  `current_period_start` (2026-09-25) is the row's own window start: for a
@@ -797,8 +865,9 @@ export interface AiTokenExpiringEvent {
     remint_path: string;
 }
 /** A job-routed async generation handle (POST /v1/ai/generate with mode:'job').
- *  The jobs run drives the provider call; read the answer via the replay buffer
- *  (`resume_path`) or track the run through the jobs surface. */
+ *  The jobs run drives the provider call; read the settled answer with
+ *  `ai.getGeneration(generation_id)` (kept 30 days) or via `resume_path`, or
+ *  track the run through the jobs surface. */
 export interface AiJobHandle {
     generation_id: string;
     run_id: string;
@@ -806,8 +875,46 @@ export interface AiJobHandle {
      *  `job.generation.completed|failed` events carry BOTH `generation_id` and
      *  `correlation_id` next to `run_id`, so no run→record link is needed. */
     correlation_id?: string | null;
-    status: string;
+    /** `pending` on a fresh handle; on a replay (`deduplicated`) the
+     *  generation's status NOW — `processing`, `completed` or `failed` too */
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    /** a /v1 route, stable within the v1 major */
     resume_path: string;
+    /** true when this answer is the REPLAY of an earlier request carrying the
+     *  same `Idempotency-Key` and body (within 24 h) — nothing was enqueued
+     *  again. The same key with a DIFFERENT body is `422 idempotency_key_reused`. */
+    deduplicated?: true;
+}
+/** One generation as `GET /v1/ai/generations/{id}` (and the `?correlation_id=`
+ *  lookup) reads it. `result` is the settled answer of a JOB-lane generation
+ *  (`generateAsync`), kept 30 days after it settles; a sync/stream generation
+ *  returned its answer to you directly and records none. The lookup always
+ *  carries `result: null` — read the text by id. */
+export interface AiGenerationRecord {
+    generation_id: string;
+    correlation_id: string | null;
+    /** the jobs run carrying a job-lane generation (null on the other lanes) */
+    run_id: string | null;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    provider: string;
+    model: string;
+    template: string | null;
+    usage: {
+        input_tokens: number;
+        output_tokens: number;
+    };
+    cached: boolean;
+    created_at: string;
+    settled_at: string | null;
+    result: {
+        text: string;
+        finish: string;
+        truncated: boolean;
+    } | null;
+    /** `stored` (in `result`) · `purged` (past the 30-day retention, or the
+     *  user was erased) · `not_recorded` (not settled yet, or a sync/stream
+     *  generation) */
+    result_state: 'stored' | 'purged' | 'not_recorded';
 }
 /** The `data` of `job.generation.queued` (jobs.md §11): the run was accepted. */
 export interface JobGenerationQueuedEventPayload {
@@ -823,15 +930,18 @@ export interface JobGenerationQueuedEventPayload {
     /** when the run is failed as expired if the provider never settles it */
     expires_at: string;
 }
-/** The `data` of `job.generation.completed` / `job.generation.failed`. */
+/** The `data` of `job.generation.completed` / `job.generation.failed`. Every
+ *  run that emitted `job.generation.queued` ends with exactly one of the two —
+ *  a run refused at its credit hold included (`failed`, `error_class:
+ *  'ReserveInsufficient'`, beside the older `job.generation.reserve_aborted`). */
 export interface JobGenerationSettledEventPayload {
     run_id: string;
     generation_id: string | null;
     correlation_id: string | null;
     /** `completed` on the healthy terminal, `failed` on the broken one */
     status: 'completed' | 'failed';
-    /** the run's SETTLED error class (`provider_error`, `PollExhausted`, …);
-     *  always null on `completed` */
+    /** the run's SETTLED error class (`provider_error`, `PollExhausted`,
+     *  `GenerationExpired`, `ReserveInsufficient`, …); always null on `completed` */
     error_class: string | null;
     /** the provider hint alone (`Upstream said: gemini 400: …`); null on
      *  `completed` and whenever the failure carried none */
@@ -859,15 +969,274 @@ export interface JobRunEventPayload {
      *  exhausted its attempts normally. */
     reason?: 'reaped' | 'queue_backstop';
 }
-/** Event name → typed `data`, for the events that settle work you started.
- *  `VxilEventPayload<'job.generation.failed'>` names one; everything else on
- *  the catalog is `Record<string, unknown>` until typed here. */
+/** The provider-reported environment of the money (`production` | `sandbox`). */
+export type PaymentsEventEnvironment = 'production' | 'sandbox';
+/** Which credits a debit spends: ONE `credit_type`, or an ORDERED
+ *  `credit_types` (1–8 distinct) — the whole amount from the FIRST type whose
+ *  available balance covers it, never split across types (2026-10-01 W9). */
+export type PaymentsCreditTypeChoice = {
+    credit_type: string;
+    credit_types?: never;
+} | {
+    credit_types: string[];
+    credit_type?: never;
+};
+/** `POST /v1/payments/credits/consume` → `data`. */
+export interface PaymentsConsumeResult {
+    balance_after: number;
+    ledger_entry_id: string | null;
+    reversed: boolean;
+    /** the credit type the debit came from (the chosen one for an ordered consume) */
+    credit_type: string;
+}
+/** `payments.charge.succeeded` (a new charge row) / `payments.charge.completed`
+ *  (a recorded charge reached the provider's completed state — Paddle's
+ *  `transaction.completed` after `transaction.paid`). */
+export interface PaymentsChargeEventPayload {
+    end_user_id: string;
+    provider: string;
+    /** the vxil charge id (`chg_…`) */
+    charge_id: string | null;
+    /** the provider's own transaction / payment id */
+    provider_charge_id: string | null;
+    amount_cents: number | null;
+    currency: string;
+    product_id: string | null;
+    provider_status: PaymentsProviderChargeStatus | null;
+    environment: PaymentsEventEnvironment;
+    level: 'info';
+}
+/** `payments.charge.refunded` / `payments.charge.disputed` — the SAME keys on
+ *  the outbound route (`source: 'api'`, emitted when the route fully refunds a
+ *  charge) and on a provider delivery (`source: 'webhook'`). */
+export interface PaymentsChargeRefundedEventPayload {
+    end_user_id: string;
+    provider: string;
+    charge_id: string | null;
+    provider_charge_id: string | null;
+    provider_refund_id: string | null;
+    /** the refunds row (`ref_…`, readable at `GET /v1/payments/refunds?refund_id=`);
+     *  null for a dispute */
+    refund_id: string | null;
+    /** what THIS refund moved (a Stripe delivery's own delta, never the running total) */
+    amount_cents: number | null;
+    currency: string;
+    /** the charge is fully refunded (or disputed): what it bought has ended */
+    full: boolean;
+    reason: string | null;
+    /** the credits taken back, per credit type (bounded by what was unspent) */
+    reversed: Array<{
+        credit_type: string;
+        amount: number;
+    }>;
+    source: 'api' | 'webhook';
+    environment: PaymentsEventEnvironment;
+    level: 'info';
+}
+/** `payments.refund.failed` — the provider refused (or the call failed) and the
+ *  reserve went back onto the charge. */
+export interface PaymentsRefundFailedEventPayload {
+    refund_id: string;
+    charge_id: string;
+    end_user_id: string | null;
+    provider: string;
+    provider_charge_id: string | null;
+    provider_refund_id: string | null;
+    amount_cents: number;
+    reason: string | null;
+    source: 'api' | 'webhook';
+    environment: PaymentsEventEnvironment;
+    level: 'warn';
+    state: 'broken';
+}
+/** `payments.subscription.<status>` (`trialing` | `active` | `past_due` |
+ *  `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
+ *  (the period-end sweep's own ending). */
+export interface PaymentsSubscriptionStatusEventPayload {
+    end_user_id: string;
+    subscription_id: string;
+    provider: string;
+    provider_sub_id: string | null;
+    tier: string | null;
+    status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
+    current_period_start: string | null;
+    current_period_end: string | null;
+    environment: PaymentsEventEnvironment;
+    /** what wrote it: the provider event type, `subscription.synced` /
+     *  `subscription.restored`, or `period_end_enforced` */
+    event_type: string;
+    slack_hours: number | null;
+    level: 'info';
+    state: 'ok';
+}
+/** `payments.subscription.granted` — a manual / support grant (`source:
+ *  'manual'`) or a purchase pass the fold wrote (`source: 'purchase'`). */
+export interface PaymentsSubscriptionGrantedEventPayload {
+    end_user_id: string;
+    subscription_id: string | null;
+    tier: string;
+    /** the window start (a queued pass's first day may be in the future) */
+    since: string;
+    until: string | null;
+    reason: string;
+    source: 'manual' | 'purchase';
+    charge_id: string | null;
+    /** the manual grant's own key; null for a purchase */
+    idempotency_key: string | null;
+    /** the product a purchase bought; null for a manual grant */
+    product_id: string | null;
+    /** the provider of the purchase; null for a manual grant */
+    provider: string | null;
+    environment: PaymentsEventEnvironment | null;
+    level: 'info';
+    state: 'ok';
+}
+/** `payments.subscription.revoked` — a row ended by `/revoke` or `DELETE`, or by
+ *  its charge's full refund / chargeback. */
+export interface PaymentsSubscriptionRevokedEventPayload {
+    end_user_id: string;
+    subscription_id: string;
+    tier: string | null;
+    via: 'delete' | 'revoke' | 'refund' | 'chargeback';
+    charge_id: string | null;
+    provider_refund_id: string | null;
+    level: 'info';
+    state: 'ok';
+}
+/** `payments.subscription.transferred` — a RevenueCat TRANSFER (`reason:
+ *  'transfer'`) or the account-merge re-key (`reason: 'account_merge'`,
+ *  `provider: null`). */
+export interface PaymentsSubscriptionTransferredEventPayload {
+    end_user_id: string;
+    from_user_ids: string[];
+    moved: number;
+    credits_moved: number;
+    provider: string | null;
+    reason: 'transfer' | 'account_merge';
+    environment: PaymentsEventEnvironment;
+    level: 'info';
+}
+/** `payments.entitlement.changed` — the user's resolved snapshot changed. */
+export interface PaymentsEntitlementChangedEventPayload {
+    end_user_id: string;
+    from_tier: string | null;
+    tier: string;
+    entitlements: string[];
+    quotas: Record<string, number>;
+    source_sub_id: string | null;
+    status: string | null;
+    until: string | null;
+    reason: string;
+    environment: PaymentsEventEnvironment;
+    level: 'info';
+}
+/** `payments.entitlement.revoke.failed` — the daily sweep found a refunded or
+ *  disputed charge whose access is still live (`refunded_but_entitled`). */
+export interface PaymentsEntitlementRevokeFailedEventPayload {
+    kind: 'refunded_but_entitled';
+    count: number;
+    subscription_ids: string[];
+    level: 'error';
+    state: 'broken';
+}
+/** `payments.grant.failed` — a recurring tier grant could not be written. */
+export interface PaymentsGrantFailedEventPayload {
+    end_user_id: string;
+    credit_type: string;
+    amount: number;
+    grant_key: string;
+    source: string;
+    error: string;
+    level: 'error';
+    state: 'broken';
+}
+/** `payments.webhook.rejected` — a signature / parse failure was persisted. */
+export interface PaymentsWebhookRejectedEventPayload {
+    event_id: string;
+    provider: string;
+    reason: 'sig_failed' | 'parse_failed';
+    fingerprint: string;
+    level: 'warn';
+    state: 'broken';
+}
+/** `payments.webhook_event.failed` — a fold threw or resolved to `error`. */
+export interface PaymentsWebhookEventFailedEventPayload {
+    /** the delivery-log row (`whe_…`) when known */
+    event_id: string | null;
+    provider: string;
+    /** the provider's own event id when known */
+    provider_evt_id: string | null;
+    event_type: string;
+    error: string;
+    level: 'error';
+    state: 'broken';
+}
+/** `payments.webhook_event.reprocessed` — an operator replay ran. */
+export interface PaymentsWebhookEventReprocessedEventPayload {
+    event_id: string;
+    provider: string;
+    event_type: string;
+}
+/** `payments.reconcile.discrepancy` — one per finding kind per daily sweep. */
+export interface PaymentsReconcileDiscrepancyEventPayload {
+    kind: string;
+    count: number;
+    /** opaque ids only (users / subscriptions / charges / events / refunds) */
+    ids: string[];
+    level: 'error';
+    state: 'broken';
+}
+/** `payments.reconcile.ok` — the tenant crossed back to clean. */
+export interface PaymentsReconcileOkEventPayload {
+    level: 'info';
+    state: 'ok';
+}
+/** `payments.conformance` — a lifecycle simulation ran (mock/dev tenants). */
+export interface PaymentsConformanceEventPayload {
+    scenario: string;
+    run_id: string;
+    end_user_id: string;
+    tier: string;
+    expected: Record<string, unknown>;
+    observed: Record<string, unknown>;
+    pass: boolean;
+    tenant_kind: string;
+    level: 'info' | 'error';
+    state: 'ok' | 'broken';
+}
+/** Event name → typed `data`, for the events that settle work you started and
+ *  (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
+ *  names one; everything else on the catalog is `Record<string, unknown>` until
+ *  typed here. */
 export interface VxilEventPayloads {
     'job.generation.queued': JobGenerationQueuedEventPayload;
     'job.generation.completed': JobGenerationSettledEventPayload;
     'job.generation.failed': JobGenerationSettledEventPayload;
     'job.succeeded': JobRunEventPayload;
     'job.dead_lettered': JobRunEventPayload;
+    'payments.charge.succeeded': PaymentsChargeEventPayload;
+    'payments.charge.completed': PaymentsChargeEventPayload;
+    'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
+    'payments.charge.disputed': PaymentsChargeRefundedEventPayload;
+    'payments.refund.failed': PaymentsRefundFailedEventPayload;
+    'payments.subscription.trialing': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.active': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.past_due': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.cancelled': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.expired': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.lapsed': PaymentsSubscriptionStatusEventPayload;
+    'payments.subscription.granted': PaymentsSubscriptionGrantedEventPayload;
+    'payments.subscription.revoked': PaymentsSubscriptionRevokedEventPayload;
+    'payments.subscription.transferred': PaymentsSubscriptionTransferredEventPayload;
+    'payments.entitlement.changed': PaymentsEntitlementChangedEventPayload;
+    'payments.entitlement.revoke.failed': PaymentsEntitlementRevokeFailedEventPayload;
+    'payments.grant.failed': PaymentsGrantFailedEventPayload;
+    'payments.webhook.rejected': PaymentsWebhookRejectedEventPayload;
+    'payments.webhook_event.failed': PaymentsWebhookEventFailedEventPayload;
+    'payments.webhook_event.reprocessed': PaymentsWebhookEventReprocessedEventPayload;
+    'payments.reconcile.discrepancy': PaymentsReconcileDiscrepancyEventPayload;
+    'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
+    'payments.conformance': PaymentsConformanceEventPayload;
 }
 export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
 /** The `trigger` label on the envelope. The config spells two of them in
@@ -960,10 +1329,14 @@ export interface QueueFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase
     trigger: 'queue';
     payload: P;
 }
-/** A schedule tick carries no data: `payload` is `{}`. */
+/** A schedule tick carries no data: `payload` is `{}`. `scheduled_for` is the
+ *  SLOT this tick was due for (ISO, UTC) — stable across a late start and a
+ *  re-delivery, so key per-slot work on it (a rollup "for 13:15"). Absent only
+ *  on a tick fired before 2026-10-01. */
 export interface CronFunctionEnvelope extends FunctionEnvelopeBase {
     trigger: 'cron';
     payload: Record<string, unknown>;
+    scheduled_for?: string;
 }
 export interface WebhookFunctionEnvelope<D = Record<string, unknown>> extends FunctionEnvelopeBase {
     trigger: 'webhook';
@@ -984,6 +1357,21 @@ export interface JobDelivery<P = unknown> {
     attempt: number;
     /** exactly what the run was enqueued with */
     payload: P;
+    /** a schedule-fired run only: the slot it was due for (ISO, UTC) */
+    scheduled_for?: string;
+}
+/** The `?since=` replay read (GET /v1/ai/generations/{id}/stream). */
+export interface AiResumePage {
+    generation_id: string;
+    correlation_id: string | null;
+    since: number;
+    status: 'pending' | 'processing' | 'completed' | 'failed';
+    frames: Array<Record<string, unknown>>;
+    done: boolean;
+    max_seq: number;
+    /** the generation settled but its frames are gone (the 1 h buffer was
+     *  reclaimed, or a job-lane answer passed its 30-day retention) */
+    expired: boolean;
 }
 /** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
 export interface AiStreamToken {
@@ -1424,6 +1812,47 @@ export interface VxilSchemaShape {
         Output: unknown;
     }>;
 }
+/** One deployed tenant function as GET /v1/functions lists it. */
+export interface DeployedFunction {
+    name: string;
+    /** the content-addressed script name (`fn-<tenant8>-<name>-<sha12>`) */
+    scriptRef: string;
+    /** `/v1/fn/<name>` */
+    endpoint: string;
+    scopes: string[];
+    egressAllow: string[];
+    /** secret REFS only (`secret:<name>`) — never values */
+    secrets: string[];
+    enabled: boolean;
+    trigger: string;
+    bindings: Array<{
+        kind: string;
+        schedule?: string;
+        source?: string;
+        path?: string;
+        collection?: string;
+        event?: string;
+        retry?: {
+            maxAttempts: number;
+        };
+    }>;
+    signature: {
+        input?: unknown;
+        output?: unknown;
+    } | null;
+    limits: {
+        cpuMs?: number;
+        timeoutMs?: number;
+    } | null;
+    /** the runtime settings the deployed script runs under; `cpuMs` = the
+     *  per-invocation CPU limit (ms) its script carries — min(limits.cpuMs, the
+     *  plan's ceiling). Absent on scripts deployed before it was recorded. */
+    runtime?: {
+        compatibilityDate: string;
+        compatibilityFlags: string[];
+        cpuMs?: number;
+    };
+}
 /** Per-call options of `vx.fn.<name>(input, opts)`. */
 export interface FnInvokeOptions {
     /** `true` ⇒ the ASYNC http lane (`x-vxil-async: 1`): the call resolves to the
@@ -2425,13 +2854,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * generation_status onto a tenant record, enforces a built-in timeout, and
          * (on failure) fires the payments credit-reversal.
          *
+         * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
+         * of the same `idempotency_key` (`deduplicated: true`) carries the run's
+         * status NOW (`processing`, `completed` or `failed` too).
+         *
          * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
          * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
-         * the enqueue (insufficient balance); a runaway over the per-tenant
-         * outstanding-holds ceiling → 429. */
+         * the enqueue (insufficient balance; the run ends with job.generation.failed
+         * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
+         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5).
+         *
+         * Generic completion options for queue-style providers (fal.ai and alike —
+         * no vendor adapter): `completion.callback.query_param` puts the signed
+         * callback URL in the provider URL's query string (`?fal_webhook=…`) and
+         * sends `provider.body` exactly; `completion.status_map` maps up to 8
+         * provider words to completed | failed | processing (`{ OK: 'completed',
+         * ERROR: 'failed' }`); `completion.result_path` names the value the run
+         * settles with — the status mirror receives it as `result`. */
         generation: (input: {
             job_name: string;
             provider: {
@@ -2449,6 +2891,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     headers?: Record<string, string>;
                     interval_ms?: number;
                 };
+                /** webhook mode: the signed callback URL rides `?<query_param>=` */
+                callback?: {
+                    query_param: string;
+                };
+                /** ≤ 8 provider words → the run's terminal (or processing) state */
+                status_map?: Record<string, "completed" | "failed" | "processing">;
+                /** dotted path of the value a completed run settles with (mirrored as `result`) */
+                result_path?: string;
             };
             status_mirror?: {
                 feature: string;
@@ -2467,10 +2917,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     };
                 };
             };
-            reserve_credits?: {
+            /** the held debit; name ONE `credit_type`, or an ordered `credit_types`
+             *  (the whole amount is held on the first type that covers it) */
+            reserve_credits?: PaymentsCreditTypeChoice & {
                 amount: number;
                 user_id: string;
-                credit_type: string;
                 reason?: string;
             };
             payload?: Record<string, unknown>;
@@ -2532,13 +2983,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
         signingSecret: () => Promise<string>;
         schedules: {
-            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at. */
+            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at.
+             *  `overlap: 'skip'` (cron only): no new run while the previous one is
+             *  still open — a missed window is never caught up either way. */
             create: (input: {
                 job_name: string;
                 target_url: string;
                 payload?: Record<string, unknown>;
                 cron?: string;
                 run_at?: string;
+                overlap?: "allow" | "skip";
             }) => Promise<JobSchedule>;
             list: () => Promise<JobSchedule[]>;
             delete: (scheduleId: string) => Promise<void>;
@@ -2791,6 +3245,28 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 user_id: string;
                 erased: boolean;
             }>;
+            /** LIVE-APP MIGRATION (server only, `auth:write`; 1–500 ids per call):
+             *  give ids already registered through `users.bulk` their sign-in
+             *  identity, carrying each user's SOURCE password hash — bcrypt
+             *  (`$2a$`/`$2b$`/`$2y$`, cost 4–10; verified once at that user's first
+             *  sign-in and replaced there) or a hash from vxil's own owner-only
+             *  credential export. An existing identity is updated only while it still
+             *  holds an imported hash; one with a vxil password, or a passwordless
+             *  (OAuth / magic-link) one, is `kept`, never overwritten. Ids are unique
+             *  across every project in an environment: an id another project holds
+             *  (e.g. a rehearsal dev backend) is `skipped` / `id_taken`. `oidc_issuer` links each id as that
+             *  issuer's subject, so an installed app can trade its old session token
+             *  for a vxil one (`auth.oauth.native('oidc', …)`). One result per id:
+             *  `created` / `updated` / `kept` / `skipped` + `reason`. `vxil migrate
+             *  data --with-password-hashes` drives this for you. */
+            import: (input: {
+                users: Array<{
+                    id: string;
+                    password_hash?: string | null;
+                    email_verified?: boolean;
+                }>;
+                oidc_issuer?: string;
+            }) => Promise<AuthImportResult>;
             /** 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
@@ -3184,6 +3660,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              * admits, including unslotted range ops (served by unindexed
              * scans, bounded only by the statement timeout) that the generated
              * per-field `Filterable` unions on `vx.from(...).query` exclude.
+             *
+             * Paging: feed `next_cursor` back as `cursor` with the SAME `filter` and
+             * `sort` — it works for the default order and (since 2026-10-01) for any
+             * slot-indexed or `created_at`/`updated_at`/`published_at` sort; a cursor
+             * sent with a different sort is a 422. A joined (dotted) sort has no cursor.
              */
             query: (collection: string, q?: {
                 filter?: Record<string, unknown>;
@@ -3508,6 +3989,59 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             blocked_state: boolean;
         }>;
     };
+    /**
+     * The deployed tenant functions — the MANAGEMENT surface (`vx.fn.<name>()`
+     * invokes them). Deploying stays on `vxil push` / `vxil functions deploy`
+     * (the CLI bundles the source); this namespace reads and removes.
+     */
+    readonly functions: {
+        /** The deployed functions (name, endpoint, bindings, scopes, limits, the
+         *  runtime each script runs under), `runtime`, the settings a deploy uses
+         *  now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
+         *  gives a function now (its own `limits.cpuMs` can only lower it), and
+         *  `enabled`: false while the project's functions are paused as a whole
+         *  (a Free project on the production workload, a downgrade) — invokes then
+         *  answer 404. Any authenticated key may read it. (GET /v1/functions) */
+        list: () => Promise<{
+            enabled?: boolean;
+            functions: DeployedFunction[];
+            runtime?: {
+                compatibilityDate: string;
+                compatibilityFlags: string[];
+            };
+            cpuMsCeiling?: number;
+        }>;
+        /**
+         * Remove ONE function from the deployed set — a new functions config
+         * version without it (invokes answer 404, its crons and trigger
+         * subscriptions are unbound). The uploaded code is kept until the nightly
+         * cleanup, so a functions config rollback restores it exactly. Pass
+         * `ifMatch` (the active functions config version) to refuse the delete if
+         * someone else changed the set first (409 `config_version_conflict`);
+         * with or without it, a delete that loses a race to a concurrent deploy
+         * is refused the same way and never erases that deploy. A
+         * name that is not deployed is 404 `function_not_found`. Needs
+         * `features:write`. (DELETE /v1/functions/:name)
+         */
+        delete: (name: string, opts?: {
+            ifMatch?: number;
+        }) => Promise<{
+            deleted: string;
+            version: number;
+            hook_reconcile?: {
+                created: number;
+                updated: number;
+                deleted: number;
+                failed: number;
+            };
+            cron_schedules?: {
+                created: number;
+                deleted: number;
+                failed: number;
+            };
+            warnings?: string[];
+        }>;
+    };
     /** The MCP aggregation surface (the `mcp` feature). */
     readonly mcp: {
         /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
@@ -4108,6 +4642,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             status: string;
         }>;
         downloadUrl: (objectId: string) => Promise<string>;
+        /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
+         *  — a gallery page costs one request, not one per image. `urls[]` keeps
+         *  your order (duplicates collapse); an id that is unknown, someone else's
+         *  (end-user mode), deleted or still uploading lands in `errors[]` instead of
+         *  failing the batch. Raster images (png/jpeg/webp/gif/avif/heic) are served
+         *  `inline`. For expo-image, cache on the object id, not the URL:
+         *  `<Image source={{ uri: u.download_url, cacheKey: u.object_id }} />`. */
+        downloadUrls: (objectIds: string[]) => Promise<{
+            urls: Array<{
+                object_id: string;
+                download_url: string;
+                content_type: string;
+            }>;
+            errors: Array<{
+                object_id: string;
+                code: "not_found" | "upload_incomplete";
+            }>;
+            expires_in: number;
+        }>;
         list: (q?: {
             user_id?: string;
             cursor?: string;
@@ -4318,6 +4871,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 created_at: string;
                 content_sha256?: string;
             }>>;
+            /** Retire a stored template (soft): every live version of the name leaves
+             *  the list and can no longer be rendered (by name or by version → 404
+             *  `template_not_found`); the rows stay for the generations that used
+             *  them, and storing the name again starts a new live version. A name
+             *  with no live version is a 404. `vxil push --allow-destructive` retires
+             *  the templates a config no longer declares. */
+            retire: (name: string) => Promise<{
+                retired: string;
+                versions: number;
+            }>;
         };
         /** Provider × capability matrix + the tenant's default provider (the set an
          *  agent/dashboard reads to know which providers/features are configured). */
@@ -4413,8 +4976,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             correlation_id?: string;
         }) => Promise<AiStreamHandle>;
         /** Job-routed async generation (long/vision/batch): 202 + a jobs run drives
-         *  the provider call; the settled answer lands in the replay buffer at
-         *  `resume_path`. Reserve/settle + credit reversal-on-failure ride the run. */
+         *  the provider call; the settled answer is stored on the generation (read
+         *  it with `getGeneration`, 30 days) and replayed at `resume_path`.
+         *  Reserve/settle + credit reversal-on-failure ride the run.
+         *  `opts.idempotencyKey` deduplicates for 24 h: a re-send after a timeout
+         *  or a lost answer returns the ORIGINAL handle (`deduplicated: true`) and
+         *  never pays the provider twice. */
         generateAsync: (input: {
             template?: string;
             template_version?: number;
@@ -4463,22 +5030,35 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the row, echoed on the answer and the replay read, and (job mode)
              *  carried on the `job.generation.*` events with `generation_id`. */
             correlation_id?: string;
+        }, opts?: {
+            idempotencyKey?: string;
         }) => Promise<AiJobHandle>;
+        /** One generation: status, usage, run, and — for a settled job-lane
+         *  generation — the settled answer (`result`, kept 30 days). In end-user
+         *  mode only the caller's own generation reads (a foreign id is a 404). */
+        getGeneration: (generationId: string) => Promise<AiGenerationRecord>;
+        /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
+         *  the recovery read after a timed-out or lost `generateAsync` answer.
+         *  Each carries `result: null` (`result_state` still says whether an answer
+         *  is stored): read the text with `getGeneration(generation_id)`. */
+        findGenerations: (q: {
+            correlation_id: string;
+        }) => Promise<{
+            generations: AiGenerationRecord[];
+        }>;
         /** Re-mint a fresh connect token for a LIVE stream (a generation that
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
         remintToken: (generationId: string) => Promise<AiStreamToken>;
         /** Resume a streamed generation after a dropped socket: every recorded frame
          *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
-         *  an SSE stream). The rag-native mirror is `rag.resume()`. */
+         *  an SSE stream; the buffer lives 1 h). A settled JOB-lane generation is
+         *  served from its stored answer instead (30 days). `status` says where the
+         *  generation is; `expired: true` means it settled but its frames are gone
+         *  (`done` is then true — nothing more will come). The rag-native mirror
+         *  is `rag.resume()`. */
         resume: (generationId: string, q?: {
             since?: number;
-        }) => Promise<{
-            generation_id: string;
-            since: number;
-            frames: Array<Record<string, unknown>>;
-            done: boolean;
-            max_seq: number;
-        }>;
+        }) => Promise<AiResumePage>;
         /** 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
@@ -4741,21 +5321,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * committed): a linked jobs run that terminally fails auto-refunds the hold,
          * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
          * available balance can't cover `amount`.
+         *
+         * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
+         * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
+         * amount comes from the FIRST type whose available balance covers it (one
+         * ledger row, never split across types) and the answer's `credit_type` names
+         * it. A retry with the same key answers the same type.
          */
-        consume: (input: {
+        consume: (input: PaymentsCreditTypeChoice & {
             user_id: string;
-            credit_type: string;
             amount: number;
             /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
             job_id?: string;
             reason?: string;
         }, opts: {
             idempotencyKey: string;
-        }) => Promise<{
-            balance_after: number;
-            ledger_entry_id: string | null;
-            reversed: boolean;
-        }>;
+        }) => Promise<PaymentsConsumeResult>;
         /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
          *  only ADDS; `amount` must be ≥ 1. */
         grant: (input: {
@@ -4870,14 +5451,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * approving webhook flips it to `succeeded`. A rejected adjustment flips it
          * to `failed`, releases the reserved amount back onto the charge and emits
          * `payments.refund.failed`. While a refund is `pending`, the credits the
-         * charge bought are NOT yet reversed. Stripe and the mock settle inline.
+         * charge bought are NOT yet reversed, and (since 2026-10-01) the charge's
+         * `amount_refunded` / `status` do not move either — the amount shows in its
+         * `amount_refund_pending` until the provider settles it. Stripe and the
+         * mock settle inline. Poll it with `listRefunds({ refund_id })`.
          *
          * If the provider has nothing left to refund on the charge — e.g. a refund
          * was already issued in the provider's own dashboard, which vxil's running
          * total cannot see — the call returns 422 `refund_not_allocatable` with the
          * precise reason, and nothing is sent to the provider. It is deterministic:
          * retrying the same refund fails the same way. A provider call that actually
-         * fails is still 502 `provider_error`.
+         * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
+         * (the row that went `failed`) so you can tie them to this call.
          */
         createRefund: (input: {
             charge_id: string;
@@ -4989,7 +5574,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,
-         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`.
+         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`,
+         *  `refunded_but_entitled`, `paid_without_grant`, `refund_reserve_drift`
+         *  (a charge's pending refund amount no pending refund explains).
          *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
          *  403 `server_only`; the sweep is a tenant-wide operator surface. */
         reconcile: () => Promise<{
@@ -5010,18 +5597,45 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             } | null;
         }>;
         /** List charges newest-first (the refund enabler — discover the charge_id).
-         *  Filters: user_id, status, limit (clamped 1..100, default 50).
+         *  Filters: user_id, status, and (2026-10-01) EXACT `charge_id` /
+         *  `provider_charge_id` lookups; keyset-paged — pass `cursor` from a prior
+         *  page's `next_cursor` (limit clamped 1..100, default 50). An unknown query
+         *  parameter is a 422 `unknown_query_param`, never an unfiltered page.
          *  Each row carries the provider's own charge id (`provider_charge_id`),
          *  the provider's charge state (`provider_status`: `'paid'` — Paddle's
          *  money-taken state — or `'completed'`; null on rows recorded before
          *  2026-09-25) and the one-off `product_id` it bought, so a function can
-         *  match a charge to a provider event without reading the delivery log. */
+         *  match a charge to a provider event without reading the delivery log.
+         *  `amount_refunded` / `status` are SETTLED money; a refund awaiting the
+         *  provider shows in `amount_refund_pending`. */
         listCharges: (q?: {
             user_id?: string;
-            status?: "succeeded" | "failed" | "refunded" | "partially_refunded" | "pending";
+            status?: "succeeded" | "failed" | "refunded" | "partially_refunded" | "pending" | "disputed";
+            /** exact match on the vxil charge id (`chg_…`) */
+            charge_id?: string;
+            /** exact match on the provider's own charge id (a Paddle `txn_…`, a Stripe `pi_…`) */
+            provider_charge_id?: string;
+            /** `production` = revenue; `sandbox` = store-review test purchases */
+            environment?: PaymentsEventEnvironment;
+            cursor?: string;
             limit?: number;
         }) => Promise<{
             charges: PaymentsCharge[];
+            next_cursor: string | null;
+        }>;
+        /** (2026-10-01) The refunds of ONE charge (`charge_id`) or one refund by id
+         *  (`refund_id`) — one of the two is required — newest first, with each
+         *  refund's `status` (`pending` until the provider settles it). Use it to
+         *  tie a `refund_id` from `createRefund`, its 502 / 422 answer or a
+         *  `payments.refund.failed` / `payments.charge.refunded` event back to the
+         *  money. A thin-client key sees only its own charges' refunds. */
+        listRefunds: (q: {
+            charge_id?: string;
+            refund_id?: string;
+            status?: "pending" | "succeeded" | "failed";
+            limit?: number;
+        }) => Promise<{
+            refunds: PaymentsRefund[];
         }>;
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
@@ -5068,3 +5682,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     };
 }
 export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, type ReportingOptions, type ReportEvent, type FetchHandler, } from './reporting.js';
+/** `auth.users.import` (POST /v1/auth/users/import) — one result per id. */
+export interface AuthImportResult {
+    results: Array<{
+        id: string;
+        status: 'created' | 'updated' | 'kept' | 'skipped';
+        reason?: 'invalid_id' | 'invalid_hash' | 'duplicate_id' | 'not_registered' | 'no_email' | 'deleted' | 'email_taken' | 'id_taken';
+    }>;
+    created: number;
+    updated: number;
+    kept: number;
+    skipped: number;
+}

package/dist/index.js

@@ -662,13 +662,26 @@ export class Vxil {
          * generation_status onto a tenant record, enforces a built-in timeout, and
          * (on failure) fires the payments credit-reversal.
          *
+         * The answer's `generation_status` is `pending` on a fresh enqueue; a replay
+         * of the same `idempotency_key` (`deduplicated: true`) carries the run's
+         * status NOW (`processing`, `completed` or `failed` too).
+         *
          * `reserve_credits` (§11.8) takes a PROVISIONAL held credit debit at enqueue
          * (linked to the run), committed on `completed` and reversed on
          * failed/timeout/DLQ. `amount` is positive-only and CLAMPED to the platform
          * `config.generation.maxReserveCredits` cap; in end-user mode `user_id` is
          * FORCED to the verified end-user (a mismatched user_id → 400). A 402 aborts
-         * the enqueue (insufficient balance); a runaway over the per-tenant
-         * outstanding-holds ceiling → 429. */
+         * the enqueue (insufficient balance; the run ends with job.generation.failed
+         * `ReserveInsufficient` and the 402 names its `run_id`); a runaway over the
+         * per-tenant outstanding-holds ceiling → 429 (Retry-After 5).
+         *
+         * Generic completion options for queue-style providers (fal.ai and alike —
+         * no vendor adapter): `completion.callback.query_param` puts the signed
+         * callback URL in the provider URL's query string (`?fal_webhook=…`) and
+         * sends `provider.body` exactly; `completion.status_map` maps up to 8
+         * provider words to completed | failed | processing (`{ OK: 'completed',
+         * ERROR: 'failed' }`); `completion.result_path` names the value the run
+         * settles with — the status mirror receives it as `result`. */
         generation: async (input) => (await this.call('POST', '/v1/jobs/generation', input)).data,
         runs: async (q) => {
             const s = qs({
@@ -714,7 +727,9 @@ export class Vxil {
         /** Secret for verifying X-Vxil-Jobs-Signature on your callback endpoints. */
         signingSecret: async () => (await this.call('GET', '/v1/jobs/signing-secret')).data.signing_secret,
         schedules: {
-            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at. */
+            /** Recurring (5-field cron, UTC) or one-shot (run_at). Exactly one of cron/run_at.
+             *  `overlap: 'skip'` (cron only): no new run while the previous one is
+             *  still open — a missed window is never caught up either way. */
             create: async (input) => (await this.call('POST', '/v1/jobs/schedules', input)).data,
             list: async () => (await this.call('GET', '/v1/jobs/schedules')).data.schedules,
             delete: async (scheduleId) => {
@@ -856,6 +871,21 @@ export class Vxil {
              *  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,
+            /** LIVE-APP MIGRATION (server only, `auth:write`; 1–500 ids per call):
+             *  give ids already registered through `users.bulk` their sign-in
+             *  identity, carrying each user's SOURCE password hash — bcrypt
+             *  (`$2a$`/`$2b$`/`$2y$`, cost 4–10; verified once at that user's first
+             *  sign-in and replaced there) or a hash from vxil's own owner-only
+             *  credential export. An existing identity is updated only while it still
+             *  holds an imported hash; one with a vxil password, or a passwordless
+             *  (OAuth / magic-link) one, is `kept`, never overwritten. Ids are unique
+             *  across every project in an environment: an id another project holds
+             *  (e.g. a rehearsal dev backend) is `skipped` / `id_taken`. `oidc_issuer` links each id as that
+             *  issuer's subject, so an installed app can trade its old session token
+             *  for a vxil one (`auth.oauth.native('oidc', …)`). One result per id:
+             *  `created` / `updated` / `kept` / `skipped` + `reason`. `vxil migrate
+             *  data --with-password-hashes` drives this for you. */
+            import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
             /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
              *  deep-merges a bounded `attributes` object into its OWN shared identity
              *  row (null deletes a key; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
@@ -1152,6 +1182,11 @@ export class Vxil {
              * admits, including unslotted range ops (served by unindexed
              * scans, bounded only by the statement timeout) that the generated
              * per-field `Filterable` unions on `vx.from(...).query` exclude.
+             *
+             * Paging: feed `next_cursor` back as `cursor` with the SAME `filter` and
+             * `sort` — it works for the default order and (since 2026-10-01) for any
+             * slot-indexed or `created_at`/`updated_at`/`published_at` sort; a cursor
+             * sent with a different sort is a 422. A joined (dotted) sort has no cursor.
              */
             query: async (collection, q) => {
                 const s = qs({
@@ -1344,6 +1379,34 @@ export class Vxil {
          *  tenant's `blockingEnabled` DM config (else 403). */
         block: async (input) => (await this.call('POST', '/v1/dm/blocks', input)).data,
     };
+    /**
+     * The deployed tenant functions — the MANAGEMENT surface (`vx.fn.<name>()`
+     * invokes them). Deploying stays on `vxil push` / `vxil functions deploy`
+     * (the CLI bundles the source); this namespace reads and removes.
+     */
+    functions = {
+        /** The deployed functions (name, endpoint, bindings, scopes, limits, the
+         *  runtime each script runs under), `runtime`, the settings a deploy uses
+         *  now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
+         *  gives a function now (its own `limits.cpuMs` can only lower it), and
+         *  `enabled`: false while the project's functions are paused as a whole
+         *  (a Free project on the production workload, a downgrade) — invokes then
+         *  answer 404. Any authenticated key may read it. (GET /v1/functions) */
+        list: async () => (await this.call('GET', '/v1/functions')).data,
+        /**
+         * Remove ONE function from the deployed set — a new functions config
+         * version without it (invokes answer 404, its crons and trigger
+         * subscriptions are unbound). The uploaded code is kept until the nightly
+         * cleanup, so a functions config rollback restores it exactly. Pass
+         * `ifMatch` (the active functions config version) to refuse the delete if
+         * someone else changed the set first (409 `config_version_conflict`);
+         * with or without it, a delete that loses a race to a concurrent deploy
+         * is refused the same way and never erases that deploy. A
+         * name that is not deployed is 404 `function_not_found`. Needs
+         * `features:write`. (DELETE /v1/functions/:name)
+         */
+        delete: async (name, opts) => (await this.call('DELETE', `/v1/functions/${encodeURIComponent(name)}`, undefined, opts?.ifMatch !== undefined ? { 'if-match': String(opts.ifMatch) } : {})).data,
+    };
     /** The MCP aggregation surface (the `mcp` feature). */
     mcp = {
         /** Per-tenant secret for verifying the X-Vxil-Mcp-Signature header on custom
@@ -1624,6 +1687,14 @@ export class Vxil {
         createUploadUrl: async (input) => (await this.call('POST', '/v1/files/upload-url', input)).data,
         complete: async (objectId) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/complete`)).data,
         downloadUrl: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url`)).data.download_url,
+        /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
+         *  — a gallery page costs one request, not one per image. `urls[]` keeps
+         *  your order (duplicates collapse); an id that is unknown, someone else's
+         *  (end-user mode), deleted or still uploading lands in `errors[]` instead of
+         *  failing the batch. Raster images (png/jpeg/webp/gif/avif/heic) are served
+         *  `inline`. For expo-image, cache on the object id, not the URL:
+         *  `<Image source={{ uri: u.download_url, cacheKey: u.object_id }} />`. */
+        downloadUrls: async (objectIds) => (await this.call('GET', `/v1/files/download-urls?object_ids=${encodeURIComponent(objectIds.join(','))}`)).data,
         list: async (q) => {
             const s = qs({
                 user_id: q?.user_id || undefined,
@@ -1741,6 +1812,13 @@ export class Vxil {
              *  declared `ai.templates[]` entry against; absent on a version stored
              *  before 2026-09-23 (the next push re-puts that template once). */
             list: async () => (await this.call('GET', '/v1/ai/templates')).data.templates,
+            /** Retire a stored template (soft): every live version of the name leaves
+             *  the list and can no longer be rendered (by name or by version → 404
+             *  `template_not_found`); the rows stay for the generations that used
+             *  them, and storing the name again starts a new live version. A name
+             *  with no live version is a 404. `vxil push --allow-destructive` retires
+             *  the templates a config no longer declares. */
+            retire: async (name) => (await this.call('DELETE', `/v1/ai/templates/${encodeURIComponent(name)}`)).data,
         },
         /** Provider × capability matrix + the tenant's default provider (the set an
          *  agent/dashboard reads to know which providers/features are configured). */
@@ -1754,15 +1832,32 @@ export class Vxil {
          *  live-only `token_expiring` events — see AiTokenExpiringEvent. */
         stream: async (input) => (await this.call('POST', '/v1/ai/generate', { ...input, stream: true })).data,
         /** Job-routed async generation (long/vision/batch): 202 + a jobs run drives
-         *  the provider call; the settled answer lands in the replay buffer at
-         *  `resume_path`. Reserve/settle + credit reversal-on-failure ride the run. */
-        generateAsync: async (input) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' })).data,
+         *  the provider call; the settled answer is stored on the generation (read
+         *  it with `getGeneration`, 30 days) and replayed at `resume_path`.
+         *  Reserve/settle + credit reversal-on-failure ride the run.
+         *  `opts.idempotencyKey` deduplicates for 24 h: a re-send after a timeout
+         *  or a lost answer returns the ORIGINAL handle (`deduplicated: true`) and
+         *  never pays the provider twice. */
+        generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
+        /** One generation: status, usage, run, and — for a settled job-lane
+         *  generation — the settled answer (`result`, kept 30 days). In end-user
+         *  mode only the caller's own generation reads (a foreign id is a 404). */
+        getGeneration: async (generationId) => (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}`)).data,
+        /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
+         *  the recovery read after a timed-out or lost `generateAsync` answer.
+         *  Each carries `result: null` (`result_state` still says whether an answer
+         *  is stored): read the text with `getGeneration(generation_id)`. */
+        findGenerations: async (q) => (await this.call('GET', `/v1/ai/generations?correlation_id=${encodeURIComponent(q.correlation_id)}`)).data,
         /** Re-mint a fresh connect token for a LIVE stream (a generation that
          *  outlives the ≤300s realtime token TTL); reconnect with `?since=<seq>`. */
         remintToken: async (generationId) => (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}/token`)).data,
         /** Resume a streamed generation after a dropped socket: every recorded frame
          *  with seq > `since` plus `done` (the §2a replay buffer — plain JSON, not
-         *  an SSE stream). The rag-native mirror is `rag.resume()`. */
+         *  an SSE stream; the buffer lives 1 h). A settled JOB-lane generation is
+         *  served from its stored answer instead (30 days). `status` says where the
+         *  generation is; `expired: true` means it settled but its frames are gone
+         *  (`done` is then true — nothing more will come). The rag-native mirror
+         *  is `rag.resume()`. */
         resume: async (generationId, q) => {
             const s = q?.since != null ? `?since=${q.since}` : '';
             return (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}/stream${s}`)).data;
@@ -1949,6 +2044,12 @@ export class Vxil {
          * committed): a linked jobs run that terminally fails auto-refunds the hold,
          * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
          * available balance can't cover `amount`.
+         *
+         * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
+         * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
+         * amount comes from the FIRST type whose available balance covers it (one
+         * ledger row, never split across types) and the answer's `credit_type` names
+         * it. A retry with the same key answers the same type.
          */
         consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
         /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
@@ -2002,14 +2103,18 @@ export class Vxil {
          * approving webhook flips it to `succeeded`. A rejected adjustment flips it
          * to `failed`, releases the reserved amount back onto the charge and emits
          * `payments.refund.failed`. While a refund is `pending`, the credits the
-         * charge bought are NOT yet reversed. Stripe and the mock settle inline.
+         * charge bought are NOT yet reversed, and (since 2026-10-01) the charge's
+         * `amount_refunded` / `status` do not move either — the amount shows in its
+         * `amount_refund_pending` until the provider settles it. Stripe and the
+         * mock settle inline. Poll it with `listRefunds({ refund_id })`.
          *
          * If the provider has nothing left to refund on the charge — e.g. a refund
          * was already issued in the provider's own dashboard, which vxil's running
          * total cannot see — the call returns 422 `refund_not_allocatable` with the
          * precise reason, and nothing is sent to the provider. It is deterministic:
          * retrying the same refund fails the same way. A provider call that actually
-         * fails is still 502 `provider_error`.
+         * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
+         * (the row that went `failed`) so you can tie them to this call.
          */
         createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
         /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
@@ -2062,25 +2167,51 @@ export class Vxil {
         /** The last report-only reconciliation sweep result for this project
          *  (`run: null` before the first daily tick). Finding kinds:
          *  `balance_drift`, `entitlement_lag`, `null_tier`, `refund_pending`,
-         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`.
+         *  `stranded_webhook`, `terminal_entitled`, `webhook_secret_missing`,
+         *  `refunded_but_entitled`, `paid_without_grant`, `refund_reserve_drift`
+         *  (a charge's pending refund amount no pending refund explains).
          *  SERVER-SIDE KEYS ONLY — a thin-client (`end_user_required`) key gets
          *  403 `server_only`; the sweep is a tenant-wide operator surface. */
         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).
+         *  Filters: user_id, status, and (2026-10-01) EXACT `charge_id` /
+         *  `provider_charge_id` lookups; keyset-paged — pass `cursor` from a prior
+         *  page's `next_cursor` (limit clamped 1..100, default 50). An unknown query
+         *  parameter is a 422 `unknown_query_param`, never an unfiltered page.
          *  Each row carries the provider's own charge id (`provider_charge_id`),
          *  the provider's charge state (`provider_status`: `'paid'` — Paddle's
          *  money-taken state — or `'completed'`; null on rows recorded before
          *  2026-09-25) and the one-off `product_id` it bought, so a function can
-         *  match a charge to a provider event without reading the delivery log. */
+         *  match a charge to a provider event without reading the delivery log.
+         *  `amount_refunded` / `status` are SETTLED money; a refund awaiting the
+         *  provider shows in `amount_refund_pending`. */
         listCharges: async (q) => {
             const suffix = qs({
                 user_id: q?.user_id || undefined,
                 status: q?.status || undefined,
+                charge_id: q?.charge_id || undefined,
+                provider_charge_id: q?.provider_charge_id || undefined,
+                environment: q?.environment || undefined,
+                cursor: q?.cursor || undefined,
                 limit: q?.limit || undefined,
             });
             return (await this.call('GET', `/v1/payments/charges${suffix}`)).data;
         },
+        /** (2026-10-01) The refunds of ONE charge (`charge_id`) or one refund by id
+         *  (`refund_id`) — one of the two is required — newest first, with each
+         *  refund's `status` (`pending` until the provider settles it). Use it to
+         *  tie a `refund_id` from `createRefund`, its 502 / 422 answer or a
+         *  `payments.refund.failed` / `payments.charge.refunded` event back to the
+         *  money. A thin-client key sees only its own charges' refunds. */
+        listRefunds: async (q) => {
+            const suffix = qs({
+                charge_id: q.charge_id || undefined,
+                refund_id: q.refund_id || undefined,
+                status: q.status || undefined,
+                limit: q.limit || undefined,
+            });
+            return (await this.call('GET', `/v1/payments/refunds${suffix}`)).data;
+        },
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature
          *  failures — plus an idempotent reprocess verb. Needs payments:read

package/package.json

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