@vxil/sdk 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -535,6 +535,57 @@ 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;
+}
+/** 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
+ *  purchase pass (`provider_sub_id: 'purchase:<charge_id>'`) the day its access
+ *  begins, which is in the FUTURE for a pass queued behind a live one; for a
+ *  manual grant the time the grant was written. A `type` with an index
+ *  signature (not an interface), so code that typed these rows as
+ *  `Record<string, unknown>` keeps compiling. */
+export type PaymentsSubscription = {
+    subscription_id: string;
+    end_user_id: string;
+    /** 'manual' for a support grant or a purchase pass; else the provider */
+    provider: string;
+    provider_sub_id: string;
+    tier: string | null;
+    /** trialing | active | past_due | cancelled | expired | lapsed */
+    status: string;
+    current_period_start: string | null;
+    current_period_end: string | null;
+    /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
+    charge_id: string | null;
+    created_at: string;
+    [key: string]: unknown;
+};
 export interface FileObject {
     object_id: string;
     filename: string;
@@ -1513,7 +1564,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;
@@ -1521,6 +1577,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
@@ -1959,6 +2017,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 */
@@ -2086,6 +2162,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;
@@ -2100,6 +2178,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     total: number;
                 };
                 sent: number;
+                sent_capped?: boolean;
                 rate: number | null;
             }>;
         };
@@ -2434,7 +2513,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             run_id: string;
             state: string;
         }>;
-        /** Clone a terminal run into a fresh queued run. */
+        /** Clone a terminal run into a fresh queued run. A generation run answers
+         *  `409 not_replayable` — submit the generation again instead. */
         replay: (runId: string) => Promise<{
             run_id: string;
             replayed_from: string;
@@ -2749,8 +2829,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  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".
+             *  A refresh that fails throws the `VxilError`. A `401 invalid_refresh`
+             *  can be a rotation another process (another server instance) just
+             *  made, so do not clear the session on the first one — keep the cookie
+             *  and treat only a repeat failure of the same pair after a short grace
+             *  as "sign in again"; see guide 09's refresh recipe.
              *
              *  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
@@ -2910,9 +2993,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
          * Consume budget. With behavior 'block' an exceeded check throws
          * VxilError(429); 'shape' resolves with allowed=false instead.
          * `override_id` is present when a per-identifier override was applied.
+         * Name the policy by EXACTLY ONE of `policy_id` or `policy` (its name —
+         * unique per project, and it survives a delete-and-recreate). An unknown
+         * name is the same 404 `not_found` as an unknown id; a policy created
+         * before 2026-09-23 is found by name once it has been saved or listed again.
          */
-        check: (input: {
+        check: (input: ({
             policy_id: string;
+            policy?: never;
+        } | {
+            policy: string;
+            policy_id?: never;
+        }) & {
             key_values?: Record<string, string>;
             cost?: number;
         }) => Promise<{
@@ -3132,7 +3224,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). */
@@ -3677,6 +3772,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).
@@ -4716,11 +4826,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             cancel_at: string | null;
         }>;
         /** List subscriptions (the cancel enabler — discover the subscription_id);
-         *  optionally scoped to one user / status. */
+         *  optionally scoped to one user / status. Each row carries its own
+         *  window: `current_period_start` … `current_period_end` (a queued pass
+         *  starts in the future). In end-user mode the list is always the signed-in
+         *  user's own rows, whatever `user_id` says. */
         listSubscriptions: (q?: {
             user_id?: string;
             status?: string;
-        }) => Promise<Array<Record<string, unknown>>>;
+        }) => Promise<PaymentsSubscription[]>;
         /**
          * Create a hosted-checkout session (payments.md §3). Redirect the buyer to
          * the returned `url`; completion lands server-side via the provider webhook
@@ -4794,19 +4907,32 @@ 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;
+            /** (2026-09-25) the grant row's start — the time it was WRITTEN (a replay
+             *  answers the first grant's), never a window you computed */
+            since?: string | null;
             until: string | null;
+            charge_id: string | null;
             replayed: boolean;
         }>;
         /** SERVER-ONLY. Revoke a MANUAL grant now (409 not_manual for a provider
@@ -4884,22 +5010,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

@@ -400,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,
@@ -460,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 });
@@ -684,7 +699,8 @@ export class Vxil {
          *  number to alarm on), in-flight runs per lane, dead letters in 24 h. */
         queue: async () => (await this.call('GET', '/v1/jobs/queue')).data,
         cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
-        /** Clone a terminal run into a fresh queued run. */
+        /** Clone a terminal run into a fresh queued run. A generation run answers
+         *  `409 not_replayable` — submit the generation again instead. */
         replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
         /**
          * Suspend the RUNNING run until an event (call from the executing
@@ -864,8 +880,11 @@ export class Vxil {
              *  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".
+             *  A refresh that fails throws the `VxilError`. A `401 invalid_refresh`
+             *  can be a rotation another process (another server instance) just
+             *  made, so do not clear the session on the first one — keep the cookie
+             *  and treat only a repeat failure of the same pair after a short grace
+             *  as "sign in again"; see guide 09's refresh recipe.
              *
              *  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
@@ -1002,6 +1021,10 @@ export class Vxil {
          * Consume budget. With behavior 'block' an exceeded check throws
          * VxilError(429); 'shape' resolves with allowed=false instead.
          * `override_id` is present when a per-identifier override was applied.
+         * Name the policy by EXACTLY ONE of `policy_id` or `policy` (its name —
+         * unique per project, and it survives a delete-and-recreate). An unknown
+         * name is the same 404 `not_found` as an unknown id; a policy created
+         * before 2026-09-23 is found by name once it has been saved or listed again.
          */
         check: async (input) => (await this.call('POST', '/v1/rate-limits/check', input)).data,
         /** Per-identifier overrides layered over a policy: `pattern` matches the
@@ -1170,7 +1193,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). */
@@ -1439,6 +1465,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).
@@ -1941,7 +1975,10 @@ export class Vxil {
          *  period closes; false revokes immediately and re-folds entitlements. */
         cancel: async (subscriptionId, opts) => (await this.call('DELETE', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}${opts?.atPeriodEnd ? '?at_period_end=true' : ''}`)).data,
         /** List subscriptions (the cancel enabler — discover the subscription_id);
-         *  optionally scoped to one user / status. */
+         *  optionally scoped to one user / status. Each row carries its own
+         *  window: `current_period_start` … `current_period_end` (a queued pass
+         *  starts in the future). In end-user mode the list is always the signed-in
+         *  user's own rows, whatever `user_id` says. */
         listSubscriptions: async (q) => {
             const s = qs({ user_id: q?.user_id || undefined, status: q?.status || undefined });
             return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;
@@ -1988,7 +2025,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. */
@@ -2022,7 +2067,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.7.0",
+  "version": "0.9.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",