@vxil/sdk 0.26.2 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -412,6 +412,25 @@ export interface UsageCurrent {
412
412
  cpu_ms_limit_per_day: number | null;
413
413
  as_of: string | null;
414
414
  } | null;
415
+ /** pricing v3: each capped lane of the plan (used / cap / resets_at /
416
+ * state) for the pool its caps count in — a Free account's projects share
417
+ * one. `used` null = not readable here yet; `cap` null = by contract.
418
+ * `db_bytes` is the project's row payload in the shared database (cms
419
+ * items, vector-search documents and chunks), measured nightly
420
+ * (`measured_at`; `resets_at` null): over it cms creates and updates
421
+ * answer 413 db_size_limit, reads and deletes always work.
422
+ * Absent from an older server; null for an end-user (thin-client) key. */
423
+ daily_caps?: {
424
+ pool: 'account' | 'project';
425
+ lanes: Array<{
426
+ lane: string;
427
+ used: number | null;
428
+ cap: number | null;
429
+ resets_at: string | null;
430
+ state: 'ok' | 'warning' | 'reached' | 'unknown';
431
+ measured_at?: string | null;
432
+ }>;
433
+ } | null;
415
434
  }
416
435
  export interface DeadLetter {
417
436
  delivery_id: string;
@@ -491,6 +510,13 @@ export interface JobRun {
491
510
  /** the single-run read, generation runs only: when that healing terminal
492
511
  * mirror landed (ISO); null otherwise */
493
512
  mirror_ok_at?: string | null;
513
+ /** the single-run read, generation runs only: each provider START call
514
+ * (timing, HTTP status, error class), oldest first, the last 10 kept; a
515
+ * START with no answer (network fault, timeout) is recorded with
516
+ * `http_status: null`. null before the first START returned and on every
517
+ * other run. A START that threw before its outcome was read records no
518
+ * entry, so attempt numbers can skip. */
519
+ attempts?: GenerationProviderAttempt[] | null;
494
520
  /** the single-run read only: the enqueue `concurrency_key` this run holds
495
521
  * while running or waiting; null for an unkeyed run */
496
522
  concurrency_key?: string | null;
@@ -1013,6 +1039,24 @@ export interface PaymentsLedgerEntry {
1013
1039
  }
1014
1040
  /** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
1015
1041
  export type PaymentsLedgerHold = 'held' | 'settled' | 'released';
1042
+ /** What `createRefund` answers. `cancel` is present only when the refund asked
1043
+ * for a cancel (`cancel: 'period_end' | 'immediately'`, or the payments config
1044
+ * `refunds.cancelAtProvider` default): `cancel_scheduled` (the provider
1045
+ * subscription now ends — at period end, or at once for `immediately`), `awaiting_refund_settlement` (the refund is still
1046
+ * pending — the cancel runs when the provider settles it), `no_subscription`
1047
+ * (the charge paid no subscription), `failed` (see `error`; call
1048
+ * `DELETE /v1/payments/subscriptions/{id}` yourself). */
1049
+ export interface PaymentsRefundResult {
1050
+ refund_id: string;
1051
+ status: 'pending' | 'succeeded' | 'failed';
1052
+ amount_cents: number;
1053
+ cancel?: {
1054
+ requested: 'period_end' | 'immediately';
1055
+ status: 'cancel_scheduled' | 'awaiting_refund_settlement' | 'no_subscription' | 'failed';
1056
+ subscription_id?: string;
1057
+ error?: string;
1058
+ };
1059
+ }
1016
1060
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
1017
1061
  export interface PaymentsRefund {
1018
1062
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1047,16 +1091,24 @@ export type PaymentsSubscription = {
1047
1091
  provider: string;
1048
1092
  provider_sub_id: string;
1049
1093
  tier: string | null;
1050
- /** trialing | active | past_due | cancelled | expired | lapsed */
1094
+ /** trialing | active | past_due | paused | cancelled | expired | lapsed */
1051
1095
  status: string;
1052
1096
  current_period_start: string | null;
1053
1097
  current_period_end: string | null;
1098
+ /** the scheduled cancellation (2026-10-13): access ends then; null when
1099
+ * none. Informational — access follows `status` and `current_period_end` */
1100
+ cancel_at: string | null;
1054
1101
  /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
1055
1102
  charge_id: string | null;
1056
1103
  /** the tenant's own reference from the checkout's custom data (Paddle
1057
1104
  * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1058
1105
  * can set it, so match on it — never grant access because of it */
1059
1106
  reference: string | null;
1107
+ /** true while a refund / chargeback ended this row in vxil but its PROVIDER
1108
+ * subscription keeps billing (Stripe, Paddle, PayPal) — cancel it with
1109
+ * `cancelSubscription`. false otherwise; a cancel or a newer provider
1110
+ * event clears it. */
1111
+ provider_subscription_active: boolean;
1060
1112
  created_at: string;
1061
1113
  [key: string]: unknown;
1062
1114
  };
@@ -1143,6 +1195,19 @@ export interface PublishedFile {
1143
1195
  published_at: string | null;
1144
1196
  variants: Record<string, string>;
1145
1197
  }
1198
+ /** `VxilError.code` values a social / OIDC sign-in (`auth.oauth.native`, the
1199
+ * `…/callback` exchange) can answer beyond the generic envelope codes:
1200
+ * `oauth_token_invalid` (401, the token did not verify),
1201
+ * `oidc_domain_not_allowed` (403, the email is outside
1202
+ * `providers.oidc.allowedDomains`), `oidc_link_only` (403,
1203
+ * `providers.oidc.linkOnly` is on and no existing account matches the
1204
+ * identity — nothing was created; create or import the user first),
1205
+ * `signup_not_allowed` (403, the sign-up gate refused a new account),
1206
+ * `auth_method_disabled` (403, the provider is turned off in `methods`),
1207
+ * `oauth_email_conflict` (409, the email belongs to an account the rule will
1208
+ * not link to), `oauth_provider_unconfigured` (501),
1209
+ * `oauth_provider_unreachable` (502). */
1210
+ export type OAuthSignInErrorCode = 'oauth_token_invalid' | 'oidc_domain_not_allowed' | 'oidc_link_only' | 'signup_not_allowed' | 'auth_method_disabled' | 'oauth_email_conflict' | 'oauth_provider_unconfigured' | 'oauth_provider_unreachable';
1146
1211
  /** Why one id of a bulk publish was not published. */
1147
1212
  export type PublishErrorCode = 'not_found' | 'upload_incomplete' | 'content_type_not_publishable' | 'object_too_large' | 'quota_exceeded' | 'batch_budget_exceeded' | 'asset_taken_down' | 'publish_failed';
1148
1213
  /** A live shared link as listed by GET /v1/files/{id}/shared-links (guide ch. 6,
@@ -1421,6 +1486,12 @@ export interface AiJobHandle {
1421
1486
  * (`generateAsync`), kept 30 days after it settles; a sync/stream generation
1422
1487
  * returned its answer to you directly and records none. The lookup always
1423
1488
  * carries `result: null` — read the text by id. */
1489
+ /** What `vx.ai.getGeneration(id, { wait })` resolves to: the record, plus
1490
+ * `wait` only when a held read did not see a terminal generation. */
1491
+ export type AiGenerationRead = AiGenerationRecord & {
1492
+ /** `timeout` — the bound passed first; `unavailable` — the wait was not held */
1493
+ wait?: 'timeout' | 'unavailable';
1494
+ };
1424
1495
  export interface AiGenerationRecord {
1425
1496
  generation_id: string;
1426
1497
  correlation_id: string | null;
@@ -1446,6 +1517,11 @@ export interface AiGenerationRecord {
1446
1517
  * user was erased) · `not_recorded` (not settled yet, or a sync/stream
1447
1518
  * generation) */
1448
1519
  result_state: 'stored' | 'purged' | 'not_recorded';
1520
+ /** a job-lane generation's model calls (timing, the upstream HTTP status,
1521
+ * error class), oldest first, the last 10 kept — a retried attempt shows
1522
+ * up here with the status the model provider answered. Empty on a
1523
+ * sync/stream generation and before the first call returned */
1524
+ attempts?: GenerationProviderAttempt[];
1449
1525
  }
1450
1526
  /** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
1451
1527
  export interface JobGenerationQueuedEventPayload {
@@ -1488,6 +1564,16 @@ export interface JobGenerationSettledEventPayload {
1488
1564
  * null without the option or when the provider never accepted the run;
1489
1565
  * absent on events written before 2026-10-11 */
1490
1566
  provider_ref?: string | null;
1567
+ /** the START attempt the run settled on (1-based; 0 when it never made
1568
+ * one — expired or refused before its first provider call). Absent on a
1569
+ * run refused at its credit hold and on events written before 2026-10-13 */
1570
+ attempt?: number;
1571
+ /** how long the settling provider START call took, in ms, when the run
1572
+ * settled from that answer (the ai lane: the START is the whole model
1573
+ * call); null when it settled from a poll, a callback or the expiry.
1574
+ * Every attempt's timing is on the run: GET /v1/jobs/runs/{id} `attempts`
1575
+ * (and GET /v1/ai/generations/{id} `attempts` for an ai generation) */
1576
+ provider_ms?: number | null;
1491
1577
  /** the failure-event vocabulary every `*.failed` carries (guide 12):
1492
1578
  * `completed` → info; `failed` → error, except a refusal at admission
1493
1579
  * (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
@@ -1495,9 +1581,41 @@ export interface JobGenerationSettledEventPayload {
1495
1581
  level: 'info' | 'warn' | 'error';
1496
1582
  state: 'ok' | 'broken';
1497
1583
  }
1584
+ /** One provider call of a generation, as the run keeps it (AI-ATTEMPT-TIMING,
1585
+ * 2026-10-13). On a jobs run (`attempts` on GET /v1/jobs/runs/{id}) it is
1586
+ * one START call, timed from the jobs side — on the ai lane its
1587
+ * `http_status` is the ai exec receiver's answer (e.g. 422, 503), not the
1588
+ * model provider's; on GET /v1/ai/generations/{id} it is the model call
1589
+ * itself, timed inside ai, with the provider's own status. The last 10 are
1590
+ * kept. */
1591
+ export interface GenerationProviderAttempt {
1592
+ /** 1-based attempt number */
1593
+ attempt: number;
1594
+ /** ISO time the call started */
1595
+ started_at: string;
1596
+ /** how long the call took, in ms */
1597
+ ms: number;
1598
+ /** the HTTP status the call answered (on ai: the upstream model provider's),
1599
+ * or null when there was none (a network fault, a timeout) */
1600
+ http_status: number | null;
1601
+ /** the attempt's error class, or null when it succeeded */
1602
+ error_class: string | null;
1603
+ }
1604
+ /** The `data` of `job.generation.retrying` (2026-10-13): a START attempt
1605
+ * failed with a retryable error (a 5xx, 429, 408 or a network fault) and the
1606
+ * run will call the provider again in `retry_in_s` seconds. Informational —
1607
+ * the run is not over; it still ends with `completed` or `failed`. */
1608
+ export interface JobGenerationRetryingEventPayload extends GenerationProviderAttempt {
1609
+ run_id: string;
1610
+ generation_id: string | null;
1611
+ correlation_id: string | null;
1612
+ /** seconds until the next attempt */
1613
+ retry_in_s: number;
1614
+ }
1498
1615
  /** The union a handler subscribed to `job.generation.` receives as `data`:
1499
- * narrow on `'status' in data` (queued carries none). */
1500
- export type JobGenerationEventPayload = JobGenerationQueuedEventPayload | JobGenerationSettledEventPayload;
1616
+ * narrow on `'status' in data` (queued and retrying carry none) and on
1617
+ * `'retry_in_s' in data` (retrying only). */
1618
+ export type JobGenerationEventPayload = JobGenerationQueuedEventPayload | JobGenerationRetryingEventPayload | JobGenerationSettledEventPayload;
1501
1619
  /** The `data` of `job.succeeded` / `job.dead_lettered` (every run kind). The
1502
1620
  * dead letter is the one that carries `level: 'error'` / `state: 'broken'`;
1503
1621
  * `job.succeeded` carries neither. */
@@ -1671,7 +1789,7 @@ export interface PaymentsRefundFailedEventPayload {
1671
1789
  state: 'broken';
1672
1790
  }
1673
1791
  /** `payments.subscription.<status>` (`trialing` | `active` | `past_due` |
1674
- * `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1792
+ * `paused` | `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1675
1793
  * (the period-end sweep's own ending). */
1676
1794
  export interface PaymentsSubscriptionStatusEventPayload {
1677
1795
  end_user_id: string;
@@ -1679,7 +1797,7 @@ export interface PaymentsSubscriptionStatusEventPayload {
1679
1797
  provider: string;
1680
1798
  provider_sub_id: string | null;
1681
1799
  tier: string | null;
1682
- status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1800
+ status: 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired' | 'lapsed';
1683
1801
  current_period_start: string | null;
1684
1802
  current_period_end: string | null;
1685
1803
  /** the subscription row's `reference` (a provider subscription carries the
@@ -1695,8 +1813,26 @@ export interface PaymentsSubscriptionStatusEventPayload {
1695
1813
  /** the store transaction id of that purchase / renewal (RevenueCat
1696
1814
  * `transaction_id`) — a stable dedup id for ad-platform conversions */
1697
1815
  transaction_id: string | null;
1816
+ /** the store the subscription is billed through, lower-case (RevenueCat
1817
+ * `store`: `app_store` | `play_store` | `stripe` | `promotional` | …);
1818
+ * null for Stripe / Paddle / PayPal / manual rows */
1819
+ store: string | null;
1820
+ /** the purchase country, ISO 3166-1 alpha-2 upper-case, when THIS delivery
1821
+ * carries it (RevenueCat `country_code`; Paddle only when the payload
1822
+ * includes the address); null otherwise */
1823
+ country: string | null;
1824
+ /** when access ends because the subscription will not renew (auto-renew
1825
+ * off / a scheduled cancel): Stripe `cancel_at`, Paddle
1826
+ * `scheduled_change.effective_at`, RevenueCat CANCELLATION's period end —
1827
+ * cleared by UNCANCELLATION / a renewal. null when nothing is scheduled */
1828
+ cancel_at: string | null;
1829
+ /** the provider's OWN event type (RevenueCat `RENEWAL` vs
1830
+ * `INITIAL_PURCHASE`, Stripe `customer.subscription.updated`, Paddle
1831
+ * `subscription.updated`, PayPal `BILLING.SUBSCRIPTION.ACTIVATED`); null
1832
+ * when no provider delivery wrote it (sync, period-end sweep, test clock) */
1833
+ provider_event_type: string | null;
1698
1834
  environment: PaymentsEventEnvironment;
1699
- /** what wrote it: the provider event type, `subscription.synced` /
1835
+ /** what wrote it: the normalized event type (`subscription.updated`, …), `subscription.synced` /
1700
1836
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
1701
1837
  * `moveSubscriptionUntil` on a non-production project ended the row) */
1702
1838
  event_type: string;
@@ -1739,9 +1875,43 @@ export interface PaymentsSubscriptionRevokedEventPayload {
1739
1875
  via: 'delete' | 'revoke' | 'refund' | 'chargeback';
1740
1876
  charge_id: string | null;
1741
1877
  provider_refund_id: string | null;
1878
+ /** (2026-10-22 PAY-REFUND-STILL-BILLING) `true` when this ended row is a
1879
+ * PROVIDER subscription (Stripe, Paddle, PayPal) that vxil did NOT cancel at
1880
+ * the provider — the customer is charged again at the next renewal unless the
1881
+ * handler calls `DELETE /v1/payments/subscriptions/{id}` (or the refund was
1882
+ * made with `cancel: 'period_end'`). `false` for a manual / purchase-entitlement
1883
+ * row and a `/revoke` or `DELETE`; `null` for a store subscription
1884
+ * (RevenueCat — the store, not vxil, controls renewal). */
1885
+ provider_subscription_active: boolean | null;
1742
1886
  level: 'info';
1743
1887
  state: 'ok';
1744
1888
  }
1889
+ /** `payments.charge.dispute_reversed` (2026-10-22 PAY-DISPUTE-REINSTATE) — a
1890
+ * dispute / chargeback was WON or REVERSED (Stripe `charge.dispute.closed`
1891
+ * won / `funds_reinstated`, Paddle `chargeback_reverse`, PayPal
1892
+ * `CUSTOMER.DISPUTE.RESOLVED` in your favour, RevenueCat `REFUND_REVERSED`).
1893
+ * Fires only when something came back: the subscription rows the dispute
1894
+ * ended (`restored_subscriptions`), the `disputed` charge label, or the credits
1895
+ * it clawed back (`credits_restored`). */
1896
+ export interface PaymentsChargeDisputeReversedEventPayload {
1897
+ end_user_id: string | null;
1898
+ provider: string;
1899
+ charge_id: string | null;
1900
+ provider_charge_id: string | null;
1901
+ provider_refund_id: string | null;
1902
+ restored_subscriptions: Array<{
1903
+ subscription_id: string;
1904
+ tier: string | null;
1905
+ }>;
1906
+ credits_restored: Array<{
1907
+ credit_type: string;
1908
+ amount: number;
1909
+ }>;
1910
+ reference: string | null;
1911
+ source: 'webhook';
1912
+ environment: PaymentsEventEnvironment;
1913
+ level: 'info';
1914
+ }
1745
1915
  /** `payments.subscription.transferred` — a RevenueCat TRANSFER (`reason:
1746
1916
  * 'transfer'`) or the account-merge re-key (`reason: 'account_merge'`,
1747
1917
  * `provider: null`). */
@@ -1877,12 +2047,53 @@ export interface PaymentsTestClockMovedEventPayload {
1877
2047
  level: 'info';
1878
2048
  state: 'ok';
1879
2049
  }
2050
+ /** Who wrote a cms item: `'function'` a deployed function's own callback
2051
+ * (`end_user_id` still names the user it acted for), `'end_user'` a verified
2052
+ * end-user session, `'server'` a server key or a platform hop. */
2053
+ export type CmsWriterKind = 'server' | 'end_user' | 'function';
2054
+ /** `data` of `cms.item.created` / `cms.item.updated` / `cms.item.deleted` /
2055
+ * `cms.item.published`. No field values: re-read the item by `item_id`.
2056
+ * Delivery is at-least-once and may arrive out of order — keep the highest
2057
+ * `version` you applied per `item_id` and drop any delivery at or below it;
2058
+ * when `version` is absent, re-read the item instead of comparing.
2059
+ * `version`, `writer_kind` and `key_id` are absent on events written before
2060
+ * 2026-10-13 (a retry or replay can still deliver one). Retention sweeps,
2061
+ * cascaded children, read-model targets and account re-keys change rows
2062
+ * WITHOUT a per-item event (they write `cms.collection.retention_swept`,
2063
+ * `cms.item.cascade`, `cms.readmodel.materialized`, `cms.items.rekeyed`):
2064
+ * a mirror re-syncs on those. */
2065
+ export interface CmsItemEventPayload {
2066
+ collection: string;
2067
+ item_id: string;
2068
+ /** the item's version AFTER this write (the If-Match / ETag counter);
2069
+ * absent before 2026-10-13 */
2070
+ version?: number;
2071
+ /** absent before 2026-10-13 */
2072
+ writer_kind?: CmsWriterKind;
2073
+ /** the calling API key's id (`ak_…`), or null when the key isn't known
2074
+ * (a function callback, a platform write, or briefly after a key-cache
2075
+ * refresh) — null does NOT prove a function wrote it; read `writer_kind`.
2076
+ * Absent before 2026-10-13. */
2077
+ key_id?: string | null;
2078
+ /** the verified end user behind the write; absent for a server write */
2079
+ end_user_id?: string;
2080
+ /** `created` only */
2081
+ status?: string;
2082
+ /** set when the write was one step of `cms.transaction` */
2083
+ tx_id?: string;
2084
+ /** `updated` by `$inc` only: the deltas applied */
2085
+ inc?: Record<string, number>;
2086
+ /** `deleted` only: rows the declared cascade removed / nulled */
2087
+ cascaded?: number;
2088
+ set_null?: number;
2089
+ }
1880
2090
  /** Event name → typed `data`, for the events that settle work you started and
1881
2091
  * (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
1882
2092
  * names one; everything else on the catalog is `Record<string, unknown>` until
1883
2093
  * typed here. */
1884
2094
  export interface VxilEventPayloads {
1885
2095
  'job.generation.queued': JobGenerationQueuedEventPayload;
2096
+ 'job.generation.retrying': JobGenerationRetryingEventPayload;
1886
2097
  'job.generation.completed': JobGenerationSettledEventPayload;
1887
2098
  'job.generation.failed': JobGenerationSettledEventPayload;
1888
2099
  'job.succeeded': JobRunEventPayload;
@@ -1892,10 +2103,12 @@ export interface VxilEventPayloads {
1892
2103
  'payments.charge.completed': PaymentsChargeEventPayload;
1893
2104
  'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
1894
2105
  'payments.charge.disputed': PaymentsChargeRefundedEventPayload;
2106
+ 'payments.charge.dispute_reversed': PaymentsChargeDisputeReversedEventPayload;
1895
2107
  'payments.refund.failed': PaymentsRefundFailedEventPayload;
1896
2108
  'payments.subscription.trialing': PaymentsSubscriptionStatusEventPayload;
1897
2109
  'payments.subscription.active': PaymentsSubscriptionStatusEventPayload;
1898
2110
  'payments.subscription.past_due': PaymentsSubscriptionStatusEventPayload;
2111
+ 'payments.subscription.paused': PaymentsSubscriptionStatusEventPayload;
1899
2112
  'payments.subscription.cancelled': PaymentsSubscriptionStatusEventPayload;
1900
2113
  'payments.subscription.expired': PaymentsSubscriptionStatusEventPayload;
1901
2114
  'payments.subscription.lapsed': PaymentsSubscriptionStatusEventPayload;
@@ -1913,6 +2126,10 @@ export interface VxilEventPayloads {
1913
2126
  'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
1914
2127
  'payments.conformance': PaymentsConformanceEventPayload;
1915
2128
  'payments.test_clock.moved': PaymentsTestClockMovedEventPayload;
2129
+ 'cms.item.created': CmsItemEventPayload;
2130
+ 'cms.item.updated': CmsItemEventPayload;
2131
+ 'cms.item.deleted': CmsItemEventPayload;
2132
+ 'cms.item.published': CmsItemEventPayload;
1916
2133
  }
1917
2134
  export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
1918
2135
  /** The `trigger` label on the envelope. The config spells two of them in
@@ -1971,11 +2188,16 @@ export interface FunctionEnvelopeBase {
1971
2188
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1972
2189
  * the item by `item_id`. */
1973
2190
  export interface CmsHookTriggerPayload {
1974
- /** `cms.item.created`, `cms.item.updated` or `cms.item.published` (per the
1975
- * binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
2191
+ /** `cms.item.created`, `cms.item.updated`, `cms.item.published` or
2192
+ * `cms.item.deleted` (`afterDelete`) (per the binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
1976
2193
  event: string;
1977
2194
  collection: string;
1978
2195
  item_id: string;
2196
+ /** `cms.item.deleted` only: the deleted row's owner (null when the
2197
+ * collection has no owner or the row had none). Absent on other events. */
2198
+ owner?: string | null;
2199
+ /** `cms.item.deleted` only: the row's workspace org (null when none). */
2200
+ org?: string | null;
1979
2201
  }
1980
2202
  /** `payload` of an `auth-hook` invocation: the event's own fields plus
1981
2203
  * `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
@@ -4436,20 +4658,56 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4436
4658
  * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
4437
4659
  * only for identities the import creates or still holds, and a subject
4438
4660
  * already linked stays where it is (`identities_linked` counts the new
4439
- * ones). `vxil migrate data --with-password-hashes` /
4440
- * `--with-oauth-identities` drives this for you. */
4661
+ * ones). `dry_run: true` answers exactly what the call would do now
4662
+ * (same results, counts and link counts) and writes nothing.
4663
+ * `vxil migrate data --with-password-hashes` /
4664
+ * `--with-oauth-identities` drives this for you (without `--execute` it previews). */
4441
4665
  import: (input: {
4442
4666
  users: Array<{
4443
4667
  id: string;
4444
4668
  password_hash?: string | null;
4445
4669
  email_verified?: boolean;
4670
+ /** source timestamps (ISO 8601 with a zone), written on create only and
4671
+ * clamped to now; `email_verified_at` implies `email_verified` */
4672
+ created_at?: string;
4673
+ email_verified_at?: string;
4446
4674
  identities?: Array<{
4447
4675
  provider: "google" | "apple" | "github" | "facebook";
4448
4676
  subject: string;
4449
4677
  }>;
4450
4678
  }>;
4451
4679
  oidc_issuer?: string;
4680
+ /** report what would be created / updated / kept / skipped / linked; nothing is written */
4681
+ dry_run?: boolean;
4452
4682
  }) => Promise<AuthImportResult>;
4683
+ /** PRODUCTION CANARIES / STORE REVIEWERS (server key only, `auth:write`):
4684
+ * flag (`true`) or unflag (`false`) the ONE user a CI canary or an
4685
+ * app-store reviewer signs in as. Off until the auth config sets
4686
+ * `security: { canarySessions: true }` (403 `canary_sessions_disabled`;
4687
+ * unflagging always works). Every user starts unflagged. Unflagging
4688
+ * revokes the user's live canary sessions (`revoked` counts them). A
4689
+ * signed-in end user, a function or an app key gets 403
4690
+ * `server_key_required`; a guest cannot be flagged (409). */
4691
+ setCanary: (userId: string, enabled: boolean) => Promise<{
4692
+ user_id: string;
4693
+ canary: boolean;
4694
+ revoked: number;
4695
+ }>;
4696
+ /** Mint a short session for a user flagged with `setCanary` — no password,
4697
+ * code or mail (server key only, `auth:write`). Lasts `ttlMinutes`
4698
+ * (1–60, default 15, never longer than `session.ttlMinutes`) and comes
4699
+ * WITHOUT a refresh token: it cannot be refreshed. Its JWT carries
4700
+ * `cny: 1` (tell it from a real sign-in) and it does not count toward
4701
+ * `session.maxConcurrent`. Revoke it with `sessions.revokeById(session_id)`
4702
+ * or by unflagging the user. 403 `canary_sessions_disabled` unless the
4703
+ * auth config sets `security.canarySessions: true`; 403
4704
+ * `canary_not_enabled` for an unflagged user; 429
4705
+ * `canary_session_rate_limited` past 3 mints per user per minute
4706
+ * (revoked ones count) or 10 live canary sessions. Audited as `auth.session.canary_minted` with
4707
+ * the calling key's id. */
4708
+ canarySession: (userId: string, opts?: {
4709
+ ttlMinutes?: number;
4710
+ }) => Promise<AuthCanarySession>;
4453
4711
  /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
4454
4712
  * deep-merges a bounded `attributes` object into its OWN shared identity
4455
4713
  * row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
@@ -4643,7 +4901,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4643
4901
  }>;
4644
4902
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
4645
4903
  * for a vxil session (`linked` marks whether the user was created or
4646
- * matched to an existing identity). */
4904
+ * matched to an existing identity). Refusals throw `VxilError` with an
4905
+ * `OAuthSignInErrorCode` — e.g. 403 `oidc_link_only` when the auth config
4906
+ * sets `providers.oidc.linkOnly` and no existing account matches. */
4647
4907
  native: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4648
4908
  id_token?: string;
4649
4909
  access_token?: string;
@@ -4825,6 +5085,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4825
5085
  * instead of per-item delete events. A collection another collection
4826
5086
  * references with an `on_delete` rule is skipped. Omit/null = keep. */
4827
5087
  retain_days?: number | null;
5088
+ /** Recovery window for DELETED items (guide ch. 4): 0..29 days a
5089
+ * soft-deleted item stays restorable before the nightly cleanup purges
5090
+ * it (0 = at the next nightly run). Omit/null = the default 30 days. */
5091
+ deleted_retain_days?: number | null;
5092
+ /** What a GDPR erase of a user does to the items they own here (guide
5093
+ * ch. 9; needs `owner_field`): 'delete' hard-deletes them in the erase
5094
+ * transaction; 'keep' (default) leaves them. */
5095
+ on_owner_erase?: "delete" | "keep" | null;
4828
5096
  /** Workspace scope (guide ch. 4): the workspace field — a string field on
4829
5097
  * index slot s1–s4 holding the orgs org id. End users then read and
4830
5098
  * write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
@@ -4885,6 +5153,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4885
5153
  write_roles?: string[];
4886
5154
  /** present when retention is set */
4887
5155
  retain_days?: number;
5156
+ /** present when a shorter deleted-item window is set */
5157
+ deleted_retain_days?: number;
5158
+ /** present when a user's erase deletes their items here */
5159
+ on_owner_erase?: "delete";
4888
5160
  /** present when the collection is workspace-scoped */
4889
5161
  org_field?: string;
4890
5162
  org_read_roles?: string[];
@@ -4900,6 +5172,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4900
5172
  write_roles?: string[] | null;
4901
5173
  /** retention in days (null = keep until deleted; absent from an older server) */
4902
5174
  retain_days?: number | null;
5175
+ /** deleted-item recovery window in days (null = the default 30) */
5176
+ deleted_retain_days?: number | null;
5177
+ /** 'delete' = a user's erase deletes the items they own (null = keep) */
5178
+ on_owner_erase?: "delete" | null;
4903
5179
  /** the workspace field / org read gate (null = not workspace-scoped) */
4904
5180
  org_field?: string | null;
4905
5181
  org_read_roles?: string[] | null;
@@ -4990,6 +5266,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4990
5266
  collection: string;
4991
5267
  retain_days: number | null;
4992
5268
  }>;
5269
+ /** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
5270
+ * item stays restorable (guide ch. 4) before the nightly cleanup purges
5271
+ * it for good; 0 = purged at the next nightly run. Audited
5272
+ * (`cms.collection.deleted_retain_days.set`). */
5273
+ setDeletedRetention: (collection: string, days: number | null) => Promise<{
5274
+ collection: string;
5275
+ deleted_retain_days: number | null;
5276
+ }>;
5277
+ /** What a GDPR erase of a user does to the items they OWN in this
5278
+ * collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
5279
+ * them (live and deleted) inside the erase transaction; 'keep' (the
5280
+ * default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
5281
+ setOnOwnerErase: (collection: string, mode: "delete" | "keep") => Promise<{
5282
+ collection: string;
5283
+ on_owner_erase: "delete" | null;
5284
+ }>;
4993
5285
  /** Re-project the collection's index slots after an `index_slot` move
4994
5286
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
4995
5287
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -5996,8 +6288,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5996
6288
  /** invite_token is returned ONCE — your app builds the accept URL.
5997
6289
  * `role`: admin | member | viewer, or a custom role_key defined with
5998
6290
  * `roles.define` (never owner). Pass `email: null` for a LINK invite —
5999
- * no email is sent and any signed-in user holding the token may accept. */
6000
- create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {})) => Promise<{
6291
+ * no email is sent and any signed-in user holding the token may accept.
6292
+ * `opts.notify: false` keeps vxil from e-mailing the invitee (your app
6293
+ * delivers the invitation itself with the returned token). */
6294
+ create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {}), opts?: {
6295
+ notify?: boolean;
6296
+ }) => Promise<{
6001
6297
  invite_id: string;
6002
6298
  invite_token: string;
6003
6299
  org_id: string;
@@ -6684,8 +6980,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6684
6980
  }) => Promise<AiJobHandle>;
6685
6981
  /** One generation: status, usage, run, and — for a settled job-lane
6686
6982
  * generation — the settled answer (`result`, kept 30 days). In end-user
6687
- * mode only the caller's own generation reads (a foreign id is a 404). */
6688
- getGeneration: (generationId: string) => Promise<AiGenerationRecord>;
6983
+ * mode only the caller's own generation reads (a foreign id is a 404).
6984
+ * With `{ wait }` (integer 1..25 seconds) the read is held platform-side
6985
+ * until the generation is `completed` / `failed` — ONE API call instead of
6986
+ * a poll loop; if it is still running at the deadline the current record
6987
+ * comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
6988
+ * budget of 60 held reads a minute declined to hold). A client
6989
+ * `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
6990
+ getGeneration: (generationId: string, opts?: {
6991
+ wait?: number;
6992
+ }) => Promise<AiGenerationRead>;
6689
6993
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
6690
6994
  * the recovery read after a timed-out or lost `generateAsync` answer.
6691
6995
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -6924,6 +7228,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6924
7228
  capabilities: string[];
6925
7229
  ledger_capabilities: string[];
6926
7230
  missing: string[];
7231
+ /** (2026-10-22) every provider the tenant can drive (primary + secondaries with their own config block) */
7232
+ providers: Array<{
7233
+ provider: string;
7234
+ primary: boolean;
7235
+ capabilities: string[];
7236
+ missing: string[];
7237
+ }>;
6927
7238
  client: {
6928
7239
  revenuecat: {
6929
7240
  project_id: string;
@@ -7145,7 +7456,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7145
7456
  listSubscriptions: (q?: {
7146
7457
  user_id?: string;
7147
7458
  status?: string;
7459
+ still_billing?: boolean;
7460
+ limit?: number;
7148
7461
  }) => Promise<PaymentsSubscription[]>;
7462
+ /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
7463
+ * — null on the last page; pass it back as `cursor`. `limit` 1..100,
7464
+ * default 50. A malformed cursor is a 422. */
7465
+ listSubscriptionsPage: (q?: {
7466
+ user_id?: string;
7467
+ status?: string;
7468
+ still_billing?: boolean;
7469
+ cursor?: string | null;
7470
+ limit?: number;
7471
+ }) => Promise<{
7472
+ subscriptions: PaymentsSubscription[];
7473
+ next_cursor: string | null;
7474
+ }>;
7149
7475
  /**
7150
7476
  * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
7151
7477
  * the returned `url`; completion lands server-side via the provider webhook
@@ -7203,18 +7529,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7203
7529
  * retrying the same refund fails the same way. A provider call that actually
7204
7530
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
7205
7531
  * (the row that went `failed`) so you can tie them to this call.
7532
+ *
7533
+ * A refund ends access in vxil but the PROVIDER subscription keeps billing
7534
+ * until it is cancelled. `cancel: 'period_end'` stops it at period end once
7535
+ * the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
7536
+ * and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
7537
+ * `'none'` keeps them separate. Without `cancel` the payments config
7538
+ * `refunds.cancelAtProvider` decides (default off). Rows still billing:
7539
+ * `listSubscriptions({ still_billing: true })`.
7206
7540
  */
7207
7541
  createRefund: (input: {
7208
7542
  charge_id: string;
7209
7543
  amount_cents?: number;
7210
7544
  reason?: string;
7545
+ cancel?: "none" | "period_end" | "immediately";
7211
7546
  }, opts: {
7212
7547
  idempotencyKey: string;
7213
- }) => Promise<{
7214
- refund_id: string;
7215
- status: "pending" | "succeeded" | "failed";
7216
- amount_cents: number;
7217
- }>;
7548
+ }) => Promise<PaymentsRefundResult>;
7218
7549
  /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
7219
7550
  * (the provider of their live subscription, not the tenant's primary):
7220
7551
  * `kind: 'portal'` = a provider-minted portal session URL (Stripe, Paddle
@@ -7445,6 +7776,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7445
7776
  };
7446
7777
  }
7447
7778
  export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, type ReportingOptions, type ReportEvent, type FetchHandler, } from './reporting.js';
7779
+ /** `auth.users.canarySession` (POST /v1/auth/users/{id}/canary-session):
7780
+ * a short, non-refreshable session for a canary-flagged user. */
7781
+ export interface AuthCanarySession {
7782
+ user_id: string;
7783
+ session_id: string;
7784
+ canary: true;
7785
+ session: {
7786
+ token: string;
7787
+ expires_at: string;
7788
+ };
7789
+ }
7448
7790
  /** `auth.users.import` (POST /v1/auth/users/import) — one result per id. */
7449
7791
  export interface AuthImportResult {
7450
7792
  results: Array<{
@@ -7458,4 +7800,8 @@ export interface AuthImportResult {
7458
7800
  skipped: number;
7459
7801
  /** social sign-in links (users[].identities) created by this call */
7460
7802
  identities_linked?: number;
7803
+ /** session hand-over links (oidc_issuer) created by this call */
7804
+ oidc_linked?: number;
7805
+ /** true when the call ran with `dry_run`: every figure is what it WOULD do; nothing was written */
7806
+ dry_run?: boolean;
7461
7807
  }
package/dist/index.js CHANGED
@@ -1266,9 +1266,33 @@ export class Vxil {
1266
1266
  * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
1267
1267
  * only for identities the import creates or still holds, and a subject
1268
1268
  * already linked stays where it is (`identities_linked` counts the new
1269
- * ones). `vxil migrate data --with-password-hashes` /
1270
- * `--with-oauth-identities` drives this for you. */
1269
+ * ones). `dry_run: true` answers exactly what the call would do now
1270
+ * (same results, counts and link counts) and writes nothing.
1271
+ * `vxil migrate data --with-password-hashes` /
1272
+ * `--with-oauth-identities` drives this for you (without `--execute` it previews). */
1271
1273
  import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
1274
+ /** PRODUCTION CANARIES / STORE REVIEWERS (server key only, `auth:write`):
1275
+ * flag (`true`) or unflag (`false`) the ONE user a CI canary or an
1276
+ * app-store reviewer signs in as. Off until the auth config sets
1277
+ * `security: { canarySessions: true }` (403 `canary_sessions_disabled`;
1278
+ * unflagging always works). Every user starts unflagged. Unflagging
1279
+ * revokes the user's live canary sessions (`revoked` counts them). A
1280
+ * signed-in end user, a function or an app key gets 403
1281
+ * `server_key_required`; a guest cannot be flagged (409). */
1282
+ setCanary: async (userId, enabled) => (await this.call('PUT', `/v1/auth/users/${encodeURIComponent(userId)}/canary`, { enabled })).data,
1283
+ /** Mint a short session for a user flagged with `setCanary` — no password,
1284
+ * code or mail (server key only, `auth:write`). Lasts `ttlMinutes`
1285
+ * (1–60, default 15, never longer than `session.ttlMinutes`) and comes
1286
+ * WITHOUT a refresh token: it cannot be refreshed. Its JWT carries
1287
+ * `cny: 1` (tell it from a real sign-in) and it does not count toward
1288
+ * `session.maxConcurrent`. Revoke it with `sessions.revokeById(session_id)`
1289
+ * or by unflagging the user. 403 `canary_sessions_disabled` unless the
1290
+ * auth config sets `security.canarySessions: true`; 403
1291
+ * `canary_not_enabled` for an unflagged user; 429
1292
+ * `canary_session_rate_limited` past 3 mints per user per minute
1293
+ * (revoked ones count) or 10 live canary sessions. Audited as `auth.session.canary_minted` with
1294
+ * the calling key's id. */
1295
+ canarySession: async (userId, opts = {}) => (await this.call('POST', `/v1/auth/users/${encodeURIComponent(userId)}/canary-session`, opts.ttlMinutes !== undefined ? { ttl_minutes: opts.ttlMinutes } : {})).data,
1272
1296
  /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
1273
1297
  * deep-merges a bounded `attributes` object into its OWN shared identity
1274
1298
  * row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
@@ -1468,7 +1492,9 @@ export class Vxil {
1468
1492
  },
1469
1493
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
1470
1494
  * for a vxil session (`linked` marks whether the user was created or
1471
- * matched to an existing identity). */
1495
+ * matched to an existing identity). Refusals throw `VxilError` with an
1496
+ * `OAuthSignInErrorCode` — e.g. 403 `oidc_link_only` when the auth config
1497
+ * sets `providers.oidc.linkOnly` and no existing account matches. */
1472
1498
  native: async (provider,
1473
1499
  /** `anonymous_token`: the caller's CURRENT guest session bearer — the
1474
1500
  * guest is PROMOTED to this identity (same user id, `linked: 'promoted'`)
@@ -1628,6 +1654,16 @@ export class Vxil {
1628
1654
  * least 30 days later like any delete, one `cms.collection.retention_swept` audit event
1629
1655
  * per collection per sweep. Audited (`cms.collection.retain_days.set`). */
1630
1656
  setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
1657
+ /** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
1658
+ * item stays restorable (guide ch. 4) before the nightly cleanup purges
1659
+ * it for good; 0 = purged at the next nightly run. Audited
1660
+ * (`cms.collection.deleted_retain_days.set`). */
1661
+ setDeletedRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { deleted_retain_days: days })).data,
1662
+ /** What a GDPR erase of a user does to the items they OWN in this
1663
+ * collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
1664
+ * them (live and deleted) inside the erase transaction; 'keep' (the
1665
+ * default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
1666
+ setOnOwnerErase: async (collection, mode) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { on_owner_erase: mode })).data,
1631
1667
  /** Re-project the collection's index slots after an `index_slot` move
1632
1668
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
1633
1669
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -2227,8 +2263,10 @@ export class Vxil {
2227
2263
  /** invite_token is returned ONCE — your app builds the accept URL.
2228
2264
  * `role`: admin | member | viewer, or a custom role_key defined with
2229
2265
  * `roles.define` (never owner). Pass `email: null` for a LINK invite —
2230
- * no email is sent and any signed-in user holding the token may accept. */
2231
- create: async (orgId, email, role) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`, email === null ? { role } : { email, role })).data,
2266
+ * no email is sent and any signed-in user holding the token may accept.
2267
+ * `opts.notify: false` keeps vxil from e-mailing the invitee (your app
2268
+ * delivers the invitation itself with the returned token). */
2269
+ create: async (orgId, email, role, opts) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`, { ...(email === null ? { role } : { email, role }), ...(opts?.notify === false ? { notify: false } : {}) })).data,
2232
2270
  /** Redeem a token. With an end-user session the signed-in user is seated
2233
2271
  * (omit `userId`) and an email invite needs that user's VERIFIED email to
2234
2272
  * match (403 `invitation_email_mismatch`); a server key passes `userId`. */
@@ -2541,8 +2579,19 @@ export class Vxil {
2541
2579
  generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
2542
2580
  /** One generation: status, usage, run, and — for a settled job-lane
2543
2581
  * generation — the settled answer (`result`, kept 30 days). In end-user
2544
- * mode only the caller's own generation reads (a foreign id is a 404). */
2545
- getGeneration: async (generationId) => (await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}`)).data,
2582
+ * mode only the caller's own generation reads (a foreign id is a 404).
2583
+ * With `{ wait }` (integer 1..25 seconds) the read is held platform-side
2584
+ * until the generation is `completed` / `failed` — ONE API call instead of
2585
+ * a poll loop; if it is still running at the deadline the current record
2586
+ * comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
2587
+ * budget of 60 held reads a minute declined to hold). A client
2588
+ * `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
2589
+ getGeneration: async (generationId, opts) => {
2590
+ const qs = opts?.wait !== undefined ? `?wait=${encodeURIComponent(String(opts.wait))}` : '';
2591
+ const { data, response } = await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}${qs}`);
2592
+ const w = response.headers.get('x-vxil-wait');
2593
+ return w === 'timeout' || w === 'unavailable' ? { ...data, wait: w } : data;
2594
+ },
2546
2595
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
2547
2596
  * the recovery read after a timed-out or lost `generateAsync` answer.
2548
2597
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -2834,9 +2883,20 @@ export class Vxil {
2834
2883
  * window: `current_period_start` … `current_period_end` (a queued pass
2835
2884
  * starts in the future). In end-user mode the list is always the signed-in
2836
2885
  * user's own rows, whatever `user_id` says. */
2837
- listSubscriptions: async (q) => {
2838
- const s = qs({ user_id: q?.user_id || undefined, status: q?.status || undefined });
2839
- return (await this.call('GET', `/v1/payments/subscriptions${s}`)).data.subscriptions;
2886
+ listSubscriptions: async (q) => (await this.payments.listSubscriptionsPage(q)).subscriptions,
2887
+ /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
2888
+ * — null on the last page; pass it back as `cursor`. `limit` 1..100,
2889
+ * default 50. A malformed cursor is a 422. */
2890
+ listSubscriptionsPage: async (q) => {
2891
+ const s = qs({
2892
+ user_id: q?.user_id || undefined,
2893
+ status: q?.status || undefined,
2894
+ still_billing: q?.still_billing ? 'true' : undefined,
2895
+ cursor: q?.cursor || undefined,
2896
+ limit: q?.limit || undefined,
2897
+ });
2898
+ const d = (await this.call('GET', `/v1/payments/subscriptions${s}`)).data;
2899
+ return { subscriptions: d.subscriptions, next_cursor: d.next_cursor ?? null };
2840
2900
  },
2841
2901
  /**
2842
2902
  * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
@@ -2869,6 +2929,14 @@ export class Vxil {
2869
2929
  * retrying the same refund fails the same way. A provider call that actually
2870
2930
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
2871
2931
  * (the row that went `failed`) so you can tie them to this call.
2932
+ *
2933
+ * A refund ends access in vxil but the PROVIDER subscription keeps billing
2934
+ * until it is cancelled. `cancel: 'period_end'` stops it at period end once
2935
+ * the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
2936
+ * and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
2937
+ * `'none'` keeps them separate. Without `cancel` the payments config
2938
+ * `refunds.cancelAtProvider` decides (default off). Rows still billing:
2939
+ * `listSubscriptions({ still_billing: true })`.
2872
2940
  */
2873
2941
  createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
2874
2942
  /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.26.2",
3
+ "version": "0.28.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",