@vxil/sdk 0.26.1 → 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;
@@ -1727,7 +1815,11 @@ export interface PaymentsSubscriptionGrantedEventPayload {
1727
1815
  state: 'ok';
1728
1816
  }
1729
1817
  /** `payments.subscription.revoked` — a row ended by `/revoke` or `DELETE`, or by
1730
- * its charge's full refund / chargeback. */
1818
+ * its charge's full refund / chargeback: a charge-linked grant or pass, or
1819
+ * (since 2026-10-13) a provider subscription (Stripe, Paddle, PayPal,
1820
+ * RevenueCat) whose current period's charge was fully refunded or disputed.
1821
+ * `charge_id` is null when the money-back names no recorded charge
1822
+ * (RevenueCat). */
1731
1823
  export interface PaymentsSubscriptionRevokedEventPayload {
1732
1824
  end_user_id: string;
1733
1825
  subscription_id: string;
@@ -1873,12 +1965,53 @@ export interface PaymentsTestClockMovedEventPayload {
1873
1965
  level: 'info';
1874
1966
  state: 'ok';
1875
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
+ }
1876
2008
  /** Event name → typed `data`, for the events that settle work you started and
1877
2009
  * (since 2026-10-01) every `payments.*` event. `VxilEventPayload<'job.generation.failed'>`
1878
2010
  * names one; everything else on the catalog is `Record<string, unknown>` until
1879
2011
  * typed here. */
1880
2012
  export interface VxilEventPayloads {
1881
2013
  'job.generation.queued': JobGenerationQueuedEventPayload;
2014
+ 'job.generation.retrying': JobGenerationRetryingEventPayload;
1882
2015
  'job.generation.completed': JobGenerationSettledEventPayload;
1883
2016
  'job.generation.failed': JobGenerationSettledEventPayload;
1884
2017
  'job.succeeded': JobRunEventPayload;
@@ -1909,6 +2042,10 @@ export interface VxilEventPayloads {
1909
2042
  'payments.reconcile.ok': PaymentsReconcileOkEventPayload;
1910
2043
  'payments.conformance': PaymentsConformanceEventPayload;
1911
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;
1912
2049
  }
1913
2050
  export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloads ? VxilEventPayloads[E] : Record<string, unknown>;
1914
2051
  /** The `trigger` label on the envelope. The config spells two of them in
@@ -4432,8 +4569,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4432
4569
  * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
4433
4570
  * only for identities the import creates or still holds, and a subject
4434
4571
  * already linked stays where it is (`identities_linked` counts the new
4435
- * ones). `vxil migrate data --with-password-hashes` /
4436
- * `--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). */
4437
4576
  import: (input: {
4438
4577
  users: Array<{
4439
4578
  id: string;
@@ -4445,7 +4584,37 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4445
4584
  }>;
4446
4585
  }>;
4447
4586
  oidc_issuer?: string;
4587
+ /** report what would be created / updated / kept / skipped / linked; nothing is written */
4588
+ dry_run?: boolean;
4448
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>;
4449
4618
  /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
4450
4619
  * deep-merges a bounded `attributes` object into its OWN shared identity
4451
4620
  * row (null deletes a key at any depth — RFC 7396; ≤8 KB, ≤64 top-level keys, depth ≤8). Profile
@@ -4639,7 +4808,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4639
4808
  }>;
4640
4809
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
4641
4810
  * for a vxil session (`linked` marks whether the user was created or
4642
- * 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. */
4643
4814
  native: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4644
4815
  id_token?: string;
4645
4816
  access_token?: string;
@@ -7141,7 +7312,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7141
7312
  listSubscriptions: (q?: {
7142
7313
  user_id?: string;
7143
7314
  status?: string;
7315
+ limit?: number;
7144
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
+ }>;
7145
7329
  /**
7146
7330
  * Create a hosted-checkout session (guide ch. 6, payments). Redirect the buyer to
7147
7331
  * the returned `url`; completion lands server-side via the provider webhook
@@ -7441,6 +7625,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7441
7625
  };
7442
7626
  }
7443
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
+ }
7444
7639
  /** `auth.users.import` (POST /v1/auth/users/import) — one result per id. */
7445
7640
  export interface AuthImportResult {
7446
7641
  results: Array<{
@@ -7454,4 +7649,8 @@ export interface AuthImportResult {
7454
7649
  skipped: number;
7455
7650
  /** social sign-in links (users[].identities) created by this call */
7456
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;
7457
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/dist/retry.d.ts CHANGED
@@ -53,7 +53,10 @@ export declare const CAPACITY_ERROR_CODES: ReadonlySet<string>;
53
53
  /** The 503 answers retried the same way (M1, 2026-10-04): the generation
54
54
  * lane could not reach payments to place its credit hold — nothing was
55
55
  * started and nothing held, and the SAME request re-sent after Retry-After
56
- * starts the run (the refused run released its idempotency key). */
56
+ * starts the run (the refused run released its idempotency key).
57
+ * `outcome_unknown` (JOBS-ENQUEUE-500-AFTER-COMMIT, 2026-10-13): the run was
58
+ * committed but its enqueue could not be confirmed — the SAME keyed request
59
+ * re-sent answers with that run (`retryOnCapacity` always sends a key). */
57
60
  export declare const UNAVAILABLE_ERROR_CODES: ReadonlySet<string>;
58
61
  /** The 409 answers retried the same way: the run this idempotency_key names
59
62
  * is still placing its credit hold (`generation_in_progress`, Retry-After 5)
@@ -74,7 +77,7 @@ export interface RetryOnCapacityOptions {
74
77
  }
75
78
  /**
76
79
  * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
77
- * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
80
+ * a 503 `payments_unavailable` / `enqueue_interrupted` / `outcome_unknown` (`UNAVAILABLE_ERROR_CODES`)
78
81
  * or a 409 `generation_in_progress` (`IN_PROGRESS_ERROR_CODES`):
79
82
  * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
80
83
  * so many clients told the same second do not all return on it), and never
package/dist/retry.js CHANGED
@@ -165,8 +165,11 @@ export const CAPACITY_ERROR_CODES = new Set([
165
165
  /** The 503 answers retried the same way (M1, 2026-10-04): the generation
166
166
  * lane could not reach payments to place its credit hold — nothing was
167
167
  * started and nothing held, and the SAME request re-sent after Retry-After
168
- * starts the run (the refused run released its idempotency key). */
169
- export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable', 'enqueue_interrupted']);
168
+ * starts the run (the refused run released its idempotency key).
169
+ * `outcome_unknown` (JOBS-ENQUEUE-500-AFTER-COMMIT, 2026-10-13): the run was
170
+ * committed but its enqueue could not be confirmed — the SAME keyed request
171
+ * re-sent answers with that run (`retryOnCapacity` always sends a key). */
172
+ export const UNAVAILABLE_ERROR_CODES = new Set(['payments_unavailable', 'enqueue_interrupted', 'outcome_unknown']);
170
173
  /** The 409 answers retried the same way: the run this idempotency_key names
171
174
  * is still placing its credit hold (`generation_in_progress`, Retry-After 5)
172
175
  * — the SAME request re-sent then answers with that run (or, when the
@@ -186,7 +189,7 @@ export function isCapacityRetryable(e) {
186
189
  const CAPACITY_DEFAULT_WAIT_MS = 5_000;
187
190
  /**
188
191
  * Re-run `attempt` while it throws a CAPACITY 429 (`CAPACITY_ERROR_CODES`),
189
- * a 503 `payments_unavailable` / `enqueue_interrupted` (`UNAVAILABLE_ERROR_CODES`)
192
+ * a 503 `payments_unavailable` / `enqueue_interrupted` / `outcome_unknown` (`UNAVAILABLE_ERROR_CODES`)
190
193
  * or a 409 `generation_in_progress` (`IN_PROGRESS_ERROR_CODES`):
191
194
  * wait the server's `Retry-After` (else 5 s) plus up to 20 % jitter (≤ 1 s,
192
195
  * so many clients told the same second do not all return on it), and never
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.26.1",
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).",