@vxil/sdk 0.7.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;
@@ -1513,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;
@@ -1521,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
@@ -1959,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 */
@@ -2086,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;
@@ -2100,6 +2154,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
                     total: number;
                 };
                 sent: number;
+                sent_capped?: boolean;
                 rate: number | null;
             }>;
         };
@@ -3132,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). */
@@ -3677,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).
@@ -4794,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
@@ -4884,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

@@ -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 });
@@ -1170,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). */
@@ -1439,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).
@@ -1988,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. */
@@ -2022,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.7.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).",