@vxil/sdk 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -535,6 +535,33 @@ export interface PaymentsEntitlementView {
         period_end: string | null;
     };
 }
+/** The provider's own state of a charge, as a closed union (2026-09-25). Paddle
+ *  delivers `paid` (money taken) and then `completed` (fulfilled) for ONE
+ *  charge; every other provider has a single terminal state and lands
+ *  `completed` at once. `payments.charge.succeeded` carries the state of the
+ *  delivery that recorded the charge; `payments.charge.completed` fires at
+ *  most once per charge, only when a recorded charge later TRANSITIONS to
+ *  `completed` (Paddle paid → completed). Handle `succeeded` gated on
+ *  `provider_status === 'completed'` plus `completed` to act once per charge. */
+export type PaymentsProviderChargeStatus = 'paid' | 'completed';
+/** A charge row as listed by GET /v1/payments/charges (payments.md §3). */
+export interface PaymentsCharge {
+    /** the vxil charge id (`chg_…`) — what refunds and a charge-linked grant key on */
+    charge_id: string;
+    end_user_id: string;
+    provider: string;
+    /** the provider's own transaction / payment id */
+    provider_charge_id: string | null;
+    /** null on rows recorded before the provider-state column existed */
+    provider_status: PaymentsProviderChargeStatus | null;
+    /** the one-off product the charge bought (the `ledger.productMap` key), if any */
+    product_id: string | null;
+    amount_cents: number;
+    amount_refunded: number;
+    currency: string;
+    status: string;
+    created_at: string;
+}
 export interface FileObject {
     object_id: string;
     filename: string;
@@ -802,6 +829,11 @@ export interface JobRunEventPayload {
     attempt: number;
     level?: 'error';
     state?: 'broken';
+    /** `job.dead_lettered` only, and only when something other than the
+     *  executor killed the run: `reaped` (the stuck-run reaper) or
+     *  `queue_backstop` (the queue's own retries ran out). Absent when the run
+     *  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
@@ -814,6 +846,121 @@ export interface VxilEventPayloads {
     'job.dead_lettered': JobRunEventPayload;
 }
 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
+ *  camelCase (`cmsHook`, `authHook`); on the wire they are kebab-case. */
+export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
+/** The audiences a function's scoped callback tokens are minted for — one per
+ *  feature its declared scopes reach. `control-plane` carries `users:*` /
+ *  `usage:read` only. There is deliberately no `functions` audience: a function
+ *  cannot call another function. */
+export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane';
+/** One short-lived scoped token per audience your scopes imply
+ *  (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
+ *  scopes do not reach is absent. Send it as `Authorization: Bearer …` to
+ *  `vxil_base`. */
+export type FunctionScopedJwts = {
+    [A in FunctionCallbackAudience]?: string;
+};
+/** The verified end-user an `http` invocation carries when the caller presented
+ *  a vxil-auth session. */
+export interface FunctionEndUser {
+    id: string;
+    sid: string;
+    /** the step-up epoch, when the session has one */
+    elv?: number;
+}
+/** The fields every invocation carries, whatever fired it. */
+export interface FunctionEnvelopeBase {
+    tenant_id: string;
+    request_id: string;
+    /** Stable across redeliveries of the same event: delivery is at-least-once,
+     *  so dedupe your writes on it. */
+    idempotency_key: string;
+    /** The edge to call vxil back through. */
+    vxil_base: string;
+    scoped_jwts: FunctionScopedJwts;
+    /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
+     *  bare name and resolved at invoke time. */
+    secrets: Record<string, string>;
+}
+/** `payload` of a `cms-hook` invocation. It carries no field values: re-read
+ *  the item by `item_id`. */
+export interface CmsHookTriggerPayload {
+    /** `cms.item.created` or `cms.item.updated` for a binding that names a
+     *  collection; a binding without one also sees the other `cms.item.*` events */
+    event: string;
+    collection: string;
+    item_id: string;
+}
+/** `payload` of an `auth-hook` invocation: the event's own fields plus
+ *  `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
+ *  `auth.session.created` → `{ user_id, session_id }`; `auth.session.revoked`
+ *  adds `reason`; `auth.signin.failure` → `{ email_hash | user_id, reason }`. */
+export interface AuthHookTriggerPayload {
+    event: string;
+    user_id?: string;
+    [field: string]: unknown;
+}
+/** `payload` of a `webhook` invocation: one platform event under the binding's
+ *  `source` prefix. `D` is the event's own payload (see `VxilEventPayload`). */
+export interface WebhookTriggerPayload<D = Record<string, unknown>> {
+    event: string;
+    audit_id: number | null;
+    occurred_at: string | null;
+    actor: string | null;
+    surface: string | null;
+    /** the event's payload; `{ truncated: true }` when it was larger than the
+     *  function's webhook payload bound, null when the event carried none */
+    data: D | {
+        truncated: true;
+    } | null;
+}
+/** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
+ *  parameters on a GET). */
+export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'http';
+    /** present only when the caller presented a verified end-user session */
+    end_user?: FunctionEndUser;
+    payload: P;
+}
+export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cms-hook';
+    payload: CmsHookTriggerPayload;
+}
+export interface AuthHookFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'auth-hook';
+    payload: AuthHookTriggerPayload;
+}
+/** `payload` is exactly what the job was enqueued with. */
+export interface QueueFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
+    trigger: 'queue';
+    payload: P;
+}
+/** A schedule tick carries no data: `payload` is `{}`. */
+export interface CronFunctionEnvelope extends FunctionEnvelopeBase {
+    trigger: 'cron';
+    payload: Record<string, unknown>;
+}
+export interface WebhookFunctionEnvelope<D = Record<string, unknown>> extends FunctionEnvelopeBase {
+    trigger: 'webhook';
+    payload: WebhookTriggerPayload<D>;
+}
+/** The invocation envelope, discriminated on `trigger`. `P` types the `http`
+ *  body and the `queue` payload. A function bound to one trigger can name its
+ *  member directly (`CmsHookFunctionEnvelope`, `WebhookFunctionEnvelope<D>`). */
+export type FunctionEnvelope<P = unknown> = HttpFunctionEnvelope<P> | CmsHookFunctionEnvelope | AuthHookFunctionEnvelope | QueueFunctionEnvelope<P> | CronFunctionEnvelope | WebhookFunctionEnvelope;
+/** The body the jobs engine POSTs to a run's `target_url` (signed with
+ *  `X-Vxil-Jobs-Signature`; verify it with the secret from
+ *  `jobs.signingSecret()`). Redelivered attempts carry the same `run_id` and a
+ *  higher `attempt`. */
+export interface JobDelivery<P = unknown> {
+    run_id: string;
+    job_name: string;
+    /** 1-based */
+    attempt: number;
+    /** exactly what the run was enqueued with */
+    payload: P;
+}
 /** A re-minted mid-stream connect token (GET /v1/ai/generations/{id}/token). */
 export interface AiStreamToken {
     generation_id: string;
@@ -1393,7 +1540,12 @@ export interface CmsReindexPage {
 /** The result of a bounded filtered delete (cms.md §20). `matched` counts the
  *  rows this page selected (≤ `limit`); `deleted` counts the ones actually
  *  removed (a row that vanished between the match and the delete is skipped).
- *  Loop while `deleted > 0` — the filter re-evaluates against live rows. */
+ *  Loop while `deleted > 0` — the filter re-evaluates against live rows.
+ *  `complete` is false when the call stopped starting rows at its wall-clock
+ *  bound (8 s; the row in flight finishes) before every matched row was
+ *  processed — such a call always deleted at least one row, so the loop above
+ *  stays exact; `next_cursor` resumes that page if you prefer. Rows already
+ *  deleted stay deleted. */
 export interface CmsBulkDeleteResult {
     collection: string;
     matched: number;
@@ -1401,6 +1553,8 @@ export interface CmsBulkDeleteResult {
     cascaded: number;
     set_null: number;
     dry_run: boolean;
+    /** every matched row was processed (always true for a dry run). */
+    complete: boolean;
     next_cursor: string | null;
 }
 /** A write guard (cms.md §10): "after this write, at most `max` live items
@@ -1839,6 +1993,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
         delete: (id: string, opts?: {
             erase?: boolean;
         }) => Promise<void>;
+        /**
+         * Merge a REGISTRY-ONLY user (a row you created with upsert that never
+         * signed in) INTO another user of the tenant: its attributes fill the
+         * survivor's gaps (the survivor wins on conflicts), the merged id is
+         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
+         * is audited. `rekeyed: false` means a re-key could not finish inside the
+         * request — the event is the backstop (call the feature's re-key route
+         * again; it is idempotent). 409 `has_auth_identity` when the id already
+         * has a sign-in identity: merge that through the auth flows instead.
+         * Server-only (403 in end-user mode). Scope users:write.
+         */
+        merge: (id: string, into: string) => Promise<{
+            from: string;
+            into: string;
+            merged: boolean;
+            rekeyed: boolean;
+        }>;
         list: (q?: {
             email?: string;
             /** substring match on email + display name (server-side, trgm-indexed), 1-100 chars */
@@ -1966,6 +2138,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  `counts.total / sent` to 4 dp, or null when nothing was sent. `sent`
              *  counts deliveries the provider ACCEPTED, not inbox-delivered mail —
              *  this is a suppressions-per-accepted-send ratio, not an RFC bounce rate.
+             *  `sent` is counted up to 100 000: past that it is the cap and
+             *  `sent_capped` is true (the rate is then a lower bound).
              *  Operator surface: a verified end-user token gets 403. */
             stats: (q?: {
                 days?: number;
@@ -1980,6 +2154,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     total: number;
                 };
                 sent: number;
+                sent_capped?: boolean;
                 rate: number | null;
             }>;
         };
@@ -2616,6 +2791,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                 user_id: string;
                 session: AuthSession;
             }>;
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: (pair: AuthSession, opts?: {
+                skewSeconds?: number;
+            }) => Promise<{
+                session: AuthSession;
+                refreshed: boolean;
+            }>;
             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
@@ -2984,7 +3187,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  the SAME single-item delete path (restrict refusal, cascade budget,
              *  unique-claim freeing, CDC), so this is N deletes in one round trip, not
              *  a set-delete. `dryRun` reports `matched` and mutates nothing. Loop
-             *  while `deleted > 0`. A refusal mid-sweep (409 referenced / 422
+             *  while `deleted > 0`. A call stops STARTING rows after 8 s of wall
+             *  clock (the row in flight finishes; never before its first delete) and
+             *  answers `complete: false` + `next_cursor` (pass it as `cursor` to
+             *  resume the page). A refusal mid-sweep (409 referenced / 422
              *  cascade_too_large) stops the call — rows already deleted STAY deleted,
              *  and the error message names how many. Soft-deleted rows are hard-purged
              *  by the platform 30 days later (there is no per-tenant retention knob). */
@@ -3529,6 +3735,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             state: string;
         }>>;
         unsubscribe: (subId: string) => Promise<void>;
+        /**
+         * Change a subscription's event filter in place (2026-09-25). The sub_id
+         * and the delivery cursor are kept — nothing is replayed, nothing is
+         * skipped; the new prefixes apply from the next delivery pass. An empty
+         * array subscribes to every event. `target_url` is the subscription's
+         * identity and is not editable: a new target is a new subscription.
+         */
+        update: (subId: string, input: {
+            event_prefixes: string[];
+        }) => Promise<{
+            sub_id: string;
+            target_url: string;
+            event_prefixes: string[];
+            state: string;
+        }>;
         /**
          * Send a synthetic 'webhooks.test' event to the subscription's endpoint
          * through the REAL signing+delivery pipeline and wait inline (≤ ~8 s).
@@ -4646,19 +4867,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          *  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. */
+         *  422 unknown_tier when the tier is not in ledger.tierMap.
+         *  `charge_id` (optional) links the grant to the vxil charge (`chg_…`, from
+         *  `listCharges` or the `payments.charge.succeeded` / `.completed` event)
+         *  it was bought with: a FULL refund or chargeback of that charge ends the
+         *  grant (`payments.subscription.revoked` with `via: 'refund' | 'chargeback'`).
+         *  404 charge_not_found; 422 charge_user_mismatch (another user's charge) /
+         *  charge_refunded (the refund beat the grant — nothing to grant against).
+         *  422 reserved_idempotency_key when `idempotency_key` starts with
+         *  `purchase:` (the namespace of purchase passes). */
         grantSubscription: (input: {
             user_id: string;
             tier: string;
             until?: string | null;
             reason: string;
             idempotency_key: string;
+            charge_id?: string | null;
         }) => Promise<{
             subscription_id: string | null;
             user_id: string;
             tier: string;
             status: string;
             until: string | null;
+            charge_id: string | null;
             replayed: boolean;
         }>;
         /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
@@ -4736,22 +4967,18 @@ 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, limit (clamped 1..100, default 50).
+         *  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. */
         listCharges: (q?: {
             user_id?: string;
             status?: "succeeded" | "failed" | "refunded" | "partially_refunded" | "pending";
             limit?: number;
         }) => Promise<{
-            charges: Array<{
-                charge_id: string;
-                end_user_id: string;
-                provider: string;
-                amount_cents: number;
-                amount_refunded: number;
-                currency: string;
-                status: string;
-                created_at: string;
-            }>;
+            charges: PaymentsCharge[];
         }>;
         /** Provider webhook event log (payments.md §7 "Event log & replay"):
          *  operator visibility over every delivery — incl. persisted signature

package/dist/index.js

@@ -50,6 +50,69 @@ export class VxilError extends Error {
 /** The run states no later write can move — what `waitForRun` and an
  *  async+wait invoke resolve `done: true` on. */
 export const JOB_TERMINAL_STATES = new Set(['succeeded', 'failed', 'dead', 'cancelled']);
+/** `vx.auth.sessions.ensureFresh` rotates a pair this many seconds before it
+ *  expires unless the call names its own `skewSeconds`. */
+const ENSURE_FRESH_SKEW_SECONDS = 300;
+/** The window never exceeds this fraction of the token's own lifetime (iat→exp
+ *  from the session JWT), so a short session TTL cannot make every call rotate. */
+const ENSURE_FRESH_MAX_WINDOW_FRACTION = 0.5;
+/** Cap for a token whose lifetime cannot be read (an opaque, non-JWT token). */
+const ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS = 60;
+/** An end-user-mode client keeps its X-Vxil-End-User token on the rotation
+ *  while that token has at least this long left (a thin-client key has no
+ *  server-mode fallback at the edge); closer to expiry it rotates in server mode. */
+const ENSURE_FRESH_HEADER_MARGIN_MS = 10_000;
+/** A settled rotation stays readable this long: a request that arrives just
+ *  after the winner still carrying the OLD pair adopts the winner's pair
+ *  instead of re-sending a revoked refresh token, and a pair this process just
+ *  minted is never rotated again inside the window (bounds rotations to one
+ *  per window per session per process whatever the clocks say). */
+const ENSURE_FRESH_GRACE_MS = 30_000;
+/** Rotations keyed by (edge base, OLD refresh token), shared by every client in
+ *  the process. `until` is Infinity while in flight and settle-time + grace
+ *  after a success; a failure is dropped at once. */
+const refreshRotations = new Map();
+/** (edge base, NEW refresh token) → the time until which that just-minted pair
+ *  is returned unchanged even if it already looks due. */
+const refreshJustMinted = new Map();
+function sweepRefreshCaches(now) {
+    for (const [k, r] of refreshRotations)
+        if (r.until <= now)
+            refreshRotations.delete(k);
+    for (const [k, until] of refreshJustMinted)
+        if (until <= now)
+            refreshJustMinted.delete(k);
+}
+const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+/** iat→exp of a session JWT in seconds, read WITHOUT verification (it only
+ *  schedules the refresh); undefined for an opaque or malformed token. No
+ *  atob: the SDK also runs on React Native builds that lack it. */
+function sessionLifetimeSeconds(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts[1] || parts[1].length > 8192)
+        return undefined;
+    let acc = 0;
+    let bits = 0;
+    let json = '';
+    for (const ch of parts[1].replace(/=+$/, '')) {
+        const v = B64URL.indexOf(ch);
+        if (v < 0)
+            return undefined;
+        acc = ((acc << 6) | v) & 0xffff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            json += String.fromCharCode((acc >> bits) & 0xff);
+        }
+    }
+    try {
+        const p = JSON.parse(json);
+        if (typeof p.iat === 'number' && typeof p.exp === 'number' && p.exp > p.iat)
+            return p.exp - p.iat;
+    }
+    catch { /* not a JWT payload */ }
+    return undefined;
+}
 const DEFAULT_BASE = 'https://api.vxil.com';
 /** Normalize the `expand` option to the `$expand` query value: a comma-joined
  *  list (the server's spelling), or `undefined` when nothing is expanded so the
@@ -337,6 +400,19 @@ export class Vxil {
         delete: async (id, opts) => {
             await this.call('DELETE', `/v1/users/${encodeURIComponent(id)}${opts?.erase ? '?erase=true' : ''}`);
         },
+        /**
+         * Merge a REGISTRY-ONLY user (a row you created with upsert that never
+         * signed in) INTO another user of the tenant: its attributes fill the
+         * survivor's gaps (the survivor wins on conflicts), the merged id is
+         * soft-deleted, its owner-scoped cms / files / payments rows move to the
+         * survivor, and `auth.user.merged { from, into, method: 'registry_merge' }`
+         * is audited. `rekeyed: false` means a re-key could not finish inside the
+         * request — the event is the backstop (call the feature's re-key route
+         * again; it is idempotent). 409 `has_auth_identity` when the id already
+         * has a sign-in identity: merge that through the auth flows instead.
+         * Server-only (403 in end-user mode). Scope users:write.
+         */
+        merge: async (id, into) => (await this.call('POST', `/v1/users/${encodeURIComponent(id)}/merge`, { into })).data,
         list: async (q) => {
             const s = qs({
                 email: q?.email || undefined,
@@ -397,6 +473,8 @@ export class Vxil {
              *  `counts.total / sent` to 4 dp, or null when nothing was sent. `sent`
              *  counts deliveries the provider ACCEPTED, not inbox-delivered mail —
              *  this is a suppressions-per-accepted-send ratio, not an RFC bounce rate.
+             *  `sent` is counted up to 100 000: past that it is the cap and
+             *  `sent_capped` is true (the rate is then a lower bound).
              *  Operator surface: a verified end-user token gets 403. */
             stats: async (q) => {
                 const s = qs({ days: q?.days || undefined });
@@ -788,6 +866,69 @@ export class Vxil {
             verify: async (token) => (await this.call('POST', '/v1/auth/sessions/verify', { token })).data,
             /** Rotates the refresh token: store the returned pair, discard the old one. */
             refresh: async (refreshToken) => (await this.call('POST', '/v1/auth/sessions/refresh', { refresh_token: refreshToken })).data,
+            /** Keep a session pair usable: when it expires within `skewSeconds`
+             *  (default 300) — or `expires_at` is missing/unparseable, or already past
+             *  — rotate it through `refresh` and return the NEW pair with
+             *  `refreshed: true`; otherwise return it unchanged, with no request.
+             *  Store the pair again whenever `refreshed` is true (the old refresh
+             *  token is revoked by the rotation).
+             *
+             *  The window is capped at half the token's own lifetime (iat→exp, read
+             *  from the session JWT; 60 s for an opaque token), so a short session
+             *  TTL never makes every call rotate. Concurrent calls for the same
+             *  refresh token in one process share ONE rotation, and for 30 s after it
+             *  settles a call still carrying the OLD pair gets the new pair (no second
+             *  request) while a call with the just-minted pair gets it back unchanged.
+             *  A refresh that fails (revoked, expired, or already rotated by another
+             *  process) throws the `VxilError` — treat it as "sign in again".
+             *
+             *  Call it on a client whose key carries `auth:signin` — normally the
+             *  sign-in key, in server mode. An end-user-mode client sends its
+             *  X-Vxil-End-User token with the rotation only while that token is the
+             *  pair's own and still has 10 s left; otherwise the rotation goes out
+             *  without it, which a thin-client (`end_user_required`) key cannot do.
+             *  See https://vxil.com/docs/guide/09-security-and-multitenancy. */
+            ensureFresh: async (pair, opts = {}) => {
+                const skew = opts.skewSeconds ?? ENSURE_FRESH_SKEW_SECONDS;
+                if (typeof skew !== 'number' || !Number.isFinite(skew) || skew < 0) {
+                    throw new VxilError(0, 'invalid_argument', 'ensureFresh: skewSeconds must be a finite number ≥ 0.');
+                }
+                const now = Date.now();
+                const key = `${this.base}\n${pair.refresh_token}`;
+                // A pair this process already rotated (or is rotating): its tokens are
+                // revoked, so the answer is the winner's pair whatever expires_at says.
+                const prior = pair.refresh_token ? refreshRotations.get(key) : undefined;
+                if (prior && prior.until > now)
+                    return { session: await prior.session, refreshed: true };
+                const lifetime = sessionLifetimeSeconds(pair.token);
+                const window = lifetime !== undefined
+                    ? Math.min(skew, lifetime * ENSURE_FRESH_MAX_WINDOW_FRACTION)
+                    : Math.min(skew, ENSURE_FRESH_OPAQUE_MAX_SKEW_SECONDS);
+                const expMs = Date.parse(pair.expires_at);
+                if (Number.isFinite(expMs) && expMs - now > window * 1000)
+                    return { session: pair, refreshed: false };
+                if (pair.refresh_token && (refreshJustMinted.get(key) ?? 0) > now)
+                    return { session: pair, refreshed: false };
+                if (!pair.refresh_token) {
+                    throw new VxilError(0, 'refresh_token_missing', 'ensureFresh: the session is due for refresh but the pair carries no refresh_token.', 'Store both halves of the pair a sign-in returns (token + refresh_token), or sign in again.');
+                }
+                const keepEndUser = this.endUserToken !== undefined && this.endUserToken === pair.token
+                    && Number.isFinite(expMs) && expMs - now >= ENSURE_FRESH_HEADER_MARGIN_MS;
+                const client = this.endUserToken && !keepEndUser ? this.asEndUser(undefined) : this;
+                sweepRefreshCaches(now);
+                const entry = {
+                    session: client.call('POST', '/v1/auth/sessions/refresh', { refresh_token: pair.refresh_token }).then((r) => r.data.session),
+                    until: Number.POSITIVE_INFINITY,
+                };
+                entry.session.then((fresh) => {
+                    entry.until = Date.now() + ENSURE_FRESH_GRACE_MS;
+                    if (fresh.refresh_token)
+                        refreshJustMinted.set(`${this.base}\n${fresh.refresh_token}`, entry.until);
+                }, () => { if (refreshRotations.get(key) === entry)
+                    refreshRotations.delete(key); });
+                refreshRotations.set(key, entry);
+                return { session: await entry.session, refreshed: true };
+            },
             revoke: async (token) => {
                 await this.call('POST', '/v1/auth/sessions/revoke', { token });
             },
@@ -1044,7 +1185,10 @@ export class Vxil {
              *  the SAME single-item delete path (restrict refusal, cascade budget,
              *  unique-claim freeing, CDC), so this is N deletes in one round trip, not
              *  a set-delete. `dryRun` reports `matched` and mutates nothing. Loop
-             *  while `deleted > 0`. A refusal mid-sweep (409 referenced / 422
+             *  while `deleted > 0`. A call stops STARTING rows after 8 s of wall
+             *  clock (the row in flight finishes; never before its first delete) and
+             *  answers `complete: false` + `next_cursor` (pass it as `cursor` to
+             *  resume the page). A refusal mid-sweep (409 referenced / 422
              *  cascade_too_large) stops the call — rows already deleted STAY deleted,
              *  and the error message names how many. Soft-deleted rows are hard-purged
              *  by the platform 30 days later (there is no per-tenant retention knob). */
@@ -1313,6 +1457,14 @@ export class Vxil {
         unsubscribe: async (subId) => {
             await this.call('DELETE', `/v1/webhooks/subscriptions/${encodeURIComponent(subId)}`);
         },
+        /**
+         * Change a subscription's event filter in place (2026-09-25). The sub_id
+         * and the delivery cursor are kept — nothing is replayed, nothing is
+         * skipped; the new prefixes apply from the next delivery pass. An empty
+         * array subscribes to every event. `target_url` is the subscription's
+         * identity and is not editable: a new target is a new subscription.
+         */
+        update: async (subId, input) => (await this.call('PATCH', `/v1/webhooks/subscriptions/${encodeURIComponent(subId)}`, input)).data,
         /**
          * Send a synthetic 'webhooks.test' event to the subscription's endpoint
          * through the REAL signing+delivery pipeline and wait inline (≤ ~8 s).
@@ -1862,7 +2014,15 @@ export class Vxil {
          *  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. */
+         *  422 unknown_tier when the tier is not in ledger.tierMap.
+         *  `charge_id` (optional) links the grant to the vxil charge (`chg_…`, from
+         *  `listCharges` or the `payments.charge.succeeded` / `.completed` event)
+         *  it was bought with: a FULL refund or chargeback of that charge ends the
+         *  grant (`payments.subscription.revoked` with `via: 'refund' | 'chargeback'`).
+         *  404 charge_not_found; 422 charge_user_mismatch (another user's charge) /
+         *  charge_refunded (the refund beat the grant — nothing to grant against).
+         *  422 reserved_idempotency_key when `idempotency_key` starts with
+         *  `purchase:` (the namespace of purchase passes). */
         grantSubscription: async (input) => (await this.call('POST', '/v1/payments/subscriptions/grant', input)).data,
         /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
          *  subscription — use `cancel`). Never touches a provider. */
@@ -1896,7 +2056,12 @@ export class Vxil {
          *  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, limit (clamped 1..100, default 50).
+         *  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. */
         listCharges: async (q) => {
             const suffix = qs({
                 user_id: q?.user_id || undefined,

package/package.json

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