@vxil/sdk 0.26.2 → 0.27.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
@@ -491,6 +491,13 @@ export interface JobRun {
491
491
  /** the single-run read, generation runs only: when that healing terminal
492
492
  * mirror landed (ISO); null otherwise */
493
493
  mirror_ok_at?: string | null;
494
+ /** the single-run read, generation runs only: each provider START call
495
+ * (timing, HTTP status, error class), oldest first, the last 10 kept; a
496
+ * START with no answer (network fault, timeout) is recorded with
497
+ * `http_status: null`. null before the first START returned and on every
498
+ * other run. A START that threw before its outcome was read records no
499
+ * entry, so attempt numbers can skip. */
500
+ attempts?: GenerationProviderAttempt[] | null;
494
501
  /** the single-run read only: the enqueue `concurrency_key` this run holds
495
502
  * while running or waiting; null for an unkeyed run */
496
503
  concurrency_key?: string | null;
@@ -1051,6 +1058,9 @@ export type PaymentsSubscription = {
1051
1058
  status: string;
1052
1059
  current_period_start: string | null;
1053
1060
  current_period_end: string | null;
1061
+ /** the scheduled cancellation (2026-10-13): access ends then; null when
1062
+ * none. Informational — access follows `status` and `current_period_end` */
1063
+ cancel_at: string | null;
1054
1064
  /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
1055
1065
  charge_id: string | null;
1056
1066
  /** the tenant's own reference from the checkout's custom data (Paddle
@@ -1143,6 +1153,19 @@ export interface PublishedFile {
1143
1153
  published_at: string | null;
1144
1154
  variants: Record<string, string>;
1145
1155
  }
1156
+ /** `VxilError.code` values a social / OIDC sign-in (`auth.oauth.native`, the
1157
+ * `…/callback` exchange) can answer beyond the generic envelope codes:
1158
+ * `oauth_token_invalid` (401, the token did not verify),
1159
+ * `oidc_domain_not_allowed` (403, the email is outside
1160
+ * `providers.oidc.allowedDomains`), `oidc_link_only` (403,
1161
+ * `providers.oidc.linkOnly` is on and no existing account matches the
1162
+ * identity — nothing was created; create or import the user first),
1163
+ * `signup_not_allowed` (403, the sign-up gate refused a new account),
1164
+ * `auth_method_disabled` (403, the provider is turned off in `methods`),
1165
+ * `oauth_email_conflict` (409, the email belongs to an account the rule will
1166
+ * not link to), `oauth_provider_unconfigured` (501),
1167
+ * `oauth_provider_unreachable` (502). */
1168
+ 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
1169
  /** Why one id of a bulk publish was not published. */
1147
1170
  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
1171
  /** A live shared link as listed by GET /v1/files/{id}/shared-links (guide ch. 6,
@@ -1446,6 +1469,11 @@ export interface AiGenerationRecord {
1446
1469
  * user was erased) · `not_recorded` (not settled yet, or a sync/stream
1447
1470
  * generation) */
1448
1471
  result_state: 'stored' | 'purged' | 'not_recorded';
1472
+ /** a job-lane generation's model calls (timing, the upstream HTTP status,
1473
+ * error class), oldest first, the last 10 kept — a retried attempt shows
1474
+ * up here with the status the model provider answered. Empty on a
1475
+ * sync/stream generation and before the first call returned */
1476
+ attempts?: GenerationProviderAttempt[];
1449
1477
  }
1450
1478
  /** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
1451
1479
  export interface JobGenerationQueuedEventPayload {
@@ -1488,6 +1516,16 @@ export interface JobGenerationSettledEventPayload {
1488
1516
  * null without the option or when the provider never accepted the run;
1489
1517
  * absent on events written before 2026-10-11 */
1490
1518
  provider_ref?: string | null;
1519
+ /** the START attempt the run settled on (1-based; 0 when it never made
1520
+ * one — expired or refused before its first provider call). Absent on a
1521
+ * run refused at its credit hold and on events written before 2026-10-13 */
1522
+ attempt?: number;
1523
+ /** how long the settling provider START call took, in ms, when the run
1524
+ * settled from that answer (the ai lane: the START is the whole model
1525
+ * call); null when it settled from a poll, a callback or the expiry.
1526
+ * Every attempt's timing is on the run: GET /v1/jobs/runs/{id} `attempts`
1527
+ * (and GET /v1/ai/generations/{id} `attempts` for an ai generation) */
1528
+ provider_ms?: number | null;
1491
1529
  /** the failure-event vocabulary every `*.failed` carries (guide 12):
1492
1530
  * `completed` → info; `failed` → error, except a refusal at admission
1493
1531
  * (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
@@ -1495,9 +1533,41 @@ export interface JobGenerationSettledEventPayload {
1495
1533
  level: 'info' | 'warn' | 'error';
1496
1534
  state: 'ok' | 'broken';
1497
1535
  }
1536
+ /** One provider call of a generation, as the run keeps it (AI-ATTEMPT-TIMING,
1537
+ * 2026-10-13). On a jobs run (`attempts` on GET /v1/jobs/runs/{id}) it is
1538
+ * one START call, timed from the jobs side — on the ai lane its
1539
+ * `http_status` is the ai exec receiver's answer (e.g. 422, 503), not the
1540
+ * model provider's; on GET /v1/ai/generations/{id} it is the model call
1541
+ * itself, timed inside ai, with the provider's own status. The last 10 are
1542
+ * kept. */
1543
+ export interface GenerationProviderAttempt {
1544
+ /** 1-based attempt number */
1545
+ attempt: number;
1546
+ /** ISO time the call started */
1547
+ started_at: string;
1548
+ /** how long the call took, in ms */
1549
+ ms: number;
1550
+ /** the HTTP status the call answered (on ai: the upstream model provider's),
1551
+ * or null when there was none (a network fault, a timeout) */
1552
+ http_status: number | null;
1553
+ /** the attempt's error class, or null when it succeeded */
1554
+ error_class: string | null;
1555
+ }
1556
+ /** The `data` of `job.generation.retrying` (2026-10-13): a START attempt
1557
+ * failed with a retryable error (a 5xx, 429, 408 or a network fault) and the
1558
+ * run will call the provider again in `retry_in_s` seconds. Informational —
1559
+ * the run is not over; it still ends with `completed` or `failed`. */
1560
+ export interface JobGenerationRetryingEventPayload extends GenerationProviderAttempt {
1561
+ run_id: string;
1562
+ generation_id: string | null;
1563
+ correlation_id: string | null;
1564
+ /** seconds until the next attempt */
1565
+ retry_in_s: number;
1566
+ }
1498
1567
  /** 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;
1568
+ * narrow on `'status' in data` (queued and retrying carry none) and on
1569
+ * `'retry_in_s' in data` (retrying only). */
1570
+ export type JobGenerationEventPayload = JobGenerationQueuedEventPayload | JobGenerationRetryingEventPayload | JobGenerationSettledEventPayload;
1501
1571
  /** The `data` of `job.succeeded` / `job.dead_lettered` (every run kind). The
1502
1572
  * dead letter is the one that carries `level: 'error'` / `state: 'broken'`;
1503
1573
  * `job.succeeded` carries neither. */
@@ -1695,8 +1765,26 @@ export interface PaymentsSubscriptionStatusEventPayload {
1695
1765
  /** the store transaction id of that purchase / renewal (RevenueCat
1696
1766
  * `transaction_id`) — a stable dedup id for ad-platform conversions */
1697
1767
  transaction_id: string | null;
1768
+ /** the store the subscription is billed through, lower-case (RevenueCat
1769
+ * `store`: `app_store` | `play_store` | `stripe` | `promotional` | …);
1770
+ * null for Stripe / Paddle / PayPal / manual rows */
1771
+ store: string | null;
1772
+ /** the purchase country, ISO 3166-1 alpha-2 upper-case, when THIS delivery
1773
+ * carries it (RevenueCat `country_code`; Paddle only when the payload
1774
+ * includes the address); null otherwise */
1775
+ country: string | null;
1776
+ /** when access ends because the subscription will not renew (auto-renew
1777
+ * off / a scheduled cancel): Stripe `cancel_at`, Paddle
1778
+ * `scheduled_change.effective_at`, RevenueCat CANCELLATION's period end —
1779
+ * cleared by UNCANCELLATION / a renewal. null when nothing is scheduled */
1780
+ cancel_at: string | null;
1781
+ /** the provider's OWN event type (RevenueCat `RENEWAL` vs
1782
+ * `INITIAL_PURCHASE`, Stripe `customer.subscription.updated`, Paddle
1783
+ * `subscription.updated`, PayPal `BILLING.SUBSCRIPTION.ACTIVATED`); null
1784
+ * when no provider delivery wrote it (sync, period-end sweep, test clock) */
1785
+ provider_event_type: string | null;
1698
1786
  environment: PaymentsEventEnvironment;
1699
- /** what wrote it: the provider event type, `subscription.synced` /
1787
+ /** what wrote it: the normalized event type (`subscription.updated`, …), `subscription.synced` /
1700
1788
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
1701
1789
  * `moveSubscriptionUntil` on a non-production project ended the row) */
1702
1790
  event_type: string;
@@ -1877,12 +1965,53 @@ export interface PaymentsTestClockMovedEventPayload {
1877
1965
  level: 'info';
1878
1966
  state: 'ok';
1879
1967
  }
1968
+ /** Who wrote a cms item: `'function'` a deployed function's own callback
1969
+ * (`end_user_id` still names the user it acted for), `'end_user'` a verified
1970
+ * end-user session, `'server'` a server key or a platform hop. */
1971
+ export type CmsWriterKind = 'server' | 'end_user' | 'function';
1972
+ /** `data` of `cms.item.created` / `cms.item.updated` / `cms.item.deleted` /
1973
+ * `cms.item.published`. No field values: re-read the item by `item_id`.
1974
+ * Delivery is at-least-once and may arrive out of order — keep the highest
1975
+ * `version` you applied per `item_id` and drop any delivery at or below it;
1976
+ * when `version` is absent, re-read the item instead of comparing.
1977
+ * `version`, `writer_kind` and `key_id` are absent on events written before
1978
+ * 2026-10-13 (a retry or replay can still deliver one). Retention sweeps,
1979
+ * cascaded children, read-model targets and account re-keys change rows
1980
+ * WITHOUT a per-item event (they write `cms.collection.retention_swept`,
1981
+ * `cms.item.cascade`, `cms.readmodel.materialized`, `cms.items.rekeyed`):
1982
+ * a mirror re-syncs on those. */
1983
+ export interface CmsItemEventPayload {
1984
+ collection: string;
1985
+ item_id: string;
1986
+ /** the item's version AFTER this write (the If-Match / ETag counter);
1987
+ * absent before 2026-10-13 */
1988
+ version?: number;
1989
+ /** absent before 2026-10-13 */
1990
+ writer_kind?: CmsWriterKind;
1991
+ /** the calling API key's id (`ak_…`), or null when the key isn't known
1992
+ * (a function callback, a platform write, or briefly after a key-cache
1993
+ * refresh) — null does NOT prove a function wrote it; read `writer_kind`.
1994
+ * Absent before 2026-10-13. */
1995
+ key_id?: string | null;
1996
+ /** the verified end user behind the write; absent for a server write */
1997
+ end_user_id?: string;
1998
+ /** `created` only */
1999
+ status?: string;
2000
+ /** set when the write was one step of `cms.transaction` */
2001
+ tx_id?: string;
2002
+ /** `updated` by `$inc` only: the deltas applied */
2003
+ inc?: Record<string, number>;
2004
+ /** `deleted` only: rows the declared cascade removed / nulled */
2005
+ cascaded?: number;
2006
+ set_null?: number;
2007
+ }
1880
2008
  /** Event name → typed `data`, for the events that settle work you started and
1881
2009
  * (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
1882
2010
  * names one; everything else on the catalog is `Record<string, unknown>` until
1883
2011
  * typed here. */
1884
2012
  export interface VxilEventPayloads {
1885
2013
  'job.generation.queued': JobGenerationQueuedEventPayload;
2014
+ 'job.generation.retrying': JobGenerationRetryingEventPayload;
1886
2015
  'job.generation.completed': JobGenerationSettledEventPayload;
1887
2016
  'job.generation.failed': JobGenerationSettledEventPayload;
1888
2017
  'job.succeeded': JobRunEventPayload;
@@ -1913,6 +2042,10 @@ export interface VxilEventPayloads {
1913
2042
  'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
1914
2043
  'payments.conformance': PaymentsConformanceEventPayload;
1915
2044
  'payments.test_clock.moved': PaymentsTestClockMovedEventPayload;
2045
+ 'cms.item.created': CmsItemEventPayload;
2046
+ 'cms.item.updated': CmsItemEventPayload;
2047
+ 'cms.item.deleted': CmsItemEventPayload;
2048
+ 'cms.item.published': CmsItemEventPayload;
1916
2049
  }
1917
2050
  export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
1918
2051
  /** The `trigger` label on the envelope. The config spells two of them in
@@ -4436,8 +4569,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4436
4569
  * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
4437
4570
  * only for identities the import creates or still holds, and a subject
4438
4571
  * 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. */
4572
+ * ones). `dry_run: true` answers exactly what the call would do now
4573
+ * (same results, counts and link counts) and writes nothing.
4574
+ * `vxil migrate data --with-password-hashes` /
4575
+ * `--with-oauth-identities` drives this for you (without `--execute` it previews). */
4441
4576
  import: (input: {
4442
4577
  users: Array<{
4443
4578
  id: string;
@@ -4449,7 +4584,37 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4449
4584
  }>;
4450
4585
  }>;
4451
4586
  oidc_issuer?: string;
4587
+ /** report what would be created / updated / kept / skipped / linked; nothing is written */
4588
+ dry_run?: boolean;
4452
4589
  }) => Promise<AuthImportResult>;
4590
+ /** PRODUCTION CANARIES / STORE REVIEWERS (server key only, `auth:write`):
4591
+ * flag (`true`) or unflag (`false`) the ONE user a CI canary or an
4592
+ * app-store reviewer signs in as. Off until the auth config sets
4593
+ * `security: { canarySessions: true }` (403 `canary_sessions_disabled`;
4594
+ * unflagging always works). Every user starts unflagged. Unflagging
4595
+ * revokes the user's live canary sessions (`revoked` counts them). A
4596
+ * signed-in end user, a function or an app key gets 403
4597
+ * `server_key_required`; a guest cannot be flagged (409). */
4598
+ setCanary: (userId: string, enabled: boolean) => Promise<{
4599
+ user_id: string;
4600
+ canary: boolean;
4601
+ revoked: number;
4602
+ }>;
4603
+ /** Mint a short session for a user flagged with `setCanary` — no password,
4604
+ * code or mail (server key only, `auth:write`). Lasts `ttlMinutes`
4605
+ * (1–60, default 15, never longer than `session.ttlMinutes`) and comes
4606
+ * WITHOUT a refresh token: it cannot be refreshed. Its JWT carries
4607
+ * `cny: 1` (tell it from a real sign-in) and it does not count toward
4608
+ * `session.maxConcurrent`. Revoke it with `sessions.revokeById(session_id)`
4609
+ * or by unflagging the user. 403 `canary_sessions_disabled` unless the
4610
+ * auth config sets `security.canarySessions: true`; 403
4611
+ * `canary_not_enabled` for an unflagged user; 429
4612
+ * `canary_session_rate_limited` past 3 mints per user per minute
4613
+ * (revoked ones count) or 10 live canary sessions. Audited as `auth.session.canary_minted` with
4614
+ * the calling key's id. */
4615
+ canarySession: (userId: string, opts?: {
4616
+ ttlMinutes?: number;
4617
+ }) => Promise<AuthCanarySession>;
4453
4618
  /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
4454
4619
  * deep-merges a bounded `attributes` object into its OWN shared identity
4455
4620
  * row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
@@ -4643,7 +4808,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4643
4808
  }>;
4644
4809
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
4645
4810
  * for a vxil session (`linked` marks whether the user was created or
4646
- * matched to an existing identity). */
4811
+ * matched to an existing identity). Refusals throw `VxilError` with an
4812
+ * `OAuthSignInErrorCode` — e.g. 403 `oidc_link_only` when the auth config
4813
+ * sets `providers.oidc.linkOnly` and no existing account matches. */
4647
4814
  native: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4648
4815
  id_token?: string;
4649
4816
  access_token?: string;
@@ -7145,7 +7312,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7145
7312
  listSubscriptions: (q?: {
7146
7313
  user_id?: string;
7147
7314
  status?: string;
7315
+ limit?: number;
7148
7316
  }) => Promise<PaymentsSubscription[]>;
7317
+ /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
7318
+ * — null on the last page; pass it back as `cursor`. `limit` 1..100,
7319
+ * default 50. A malformed cursor is a 422. */
7320
+ listSubscriptionsPage: (q?: {
7321
+ user_id?: string;
7322
+ status?: string;
7323
+ cursor?: string | null;
7324
+ limit?: number;
7325
+ }) => Promise<{
7326
+ subscriptions: PaymentsSubscription[];
7327
+ next_cursor: string | null;
7328
+ }>;
7149
7329
  /**
7150
7330
  * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
7151
7331
  * the returned `url`; completion lands server-side via the provider webhook
@@ -7445,6 +7625,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7445
7625
  };
7446
7626
  }
7447
7627
  export { withReporting, report, buildEnvelope, parseDsn, exceptionEvent, reportServerErrors, REPORT_TIMEOUT_MS, type ReportingOptions, type ReportEvent, type FetchHandler, } from './reporting.js';
7628
+ /** `auth.users.canarySession` (POST /v1/auth/users/{id}/canary-session):
7629
+ * a short, non-refreshable session for a canary-flagged user. */
7630
+ export interface AuthCanarySession {
7631
+ user_id: string;
7632
+ session_id: string;
7633
+ canary: true;
7634
+ session: {
7635
+ token: string;
7636
+ expires_at: string;
7637
+ };
7638
+ }
7448
7639
  /** `auth.users.import` (POST /v1/auth/users/import) — one result per id. */
7449
7640
  export interface AuthImportResult {
7450
7641
  results: Array<{
@@ -7458,4 +7649,8 @@ export interface AuthImportResult {
7458
7649
  skipped: number;
7459
7650
  /** social sign-in links (users[].identities) created by this call */
7460
7651
  identities_linked?: number;
7652
+ /** session hand-over links (oidc_issuer) created by this call */
7653
+ oidc_linked?: number;
7654
+ /** true when the call ran with `dry_run`: every figure is what it WOULD do; nothing was written */
7655
+ dry_run?: boolean;
7461
7656
  }
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'`)
@@ -2834,9 +2860,19 @@ export class Vxil {
2834
2860
  * window: `current_period_start` … `current_period_end` (a queued pass
2835
2861
  * starts in the future). In end-user mode the list is always the signed-in
2836
2862
  * 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;
2863
+ listSubscriptions: async (q) => (await this.payments.listSubscriptionsPage(q)).subscriptions,
2864
+ /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
2865
+ * — null on the last page; pass it back as `cursor`. `limit` 1..100,
2866
+ * default 50. A malformed cursor is a 422. */
2867
+ listSubscriptionsPage: async (q) => {
2868
+ const s = qs({
2869
+ user_id: q?.user_id || undefined,
2870
+ status: q?.status || undefined,
2871
+ cursor: q?.cursor || undefined,
2872
+ limit: q?.limit || undefined,
2873
+ });
2874
+ const d = (await this.call('GET', `/v1/payments/subscriptions${s}`)).data;
2875
+ return { subscriptions: d.subscriptions, next_cursor: d.next_cursor ?? null };
2840
2876
  },
2841
2877
  /**
2842
2878
  * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.26.2",
3
+ "version": "0.27.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).",