@vxil/sdk 0.27.0 → 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;
@@ -1020,6 +1039,24 @@ export interface PaymentsLedgerEntry {
1020
1039
  }
1021
1040
  /** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
1022
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
+ }
1023
1060
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
1024
1061
  export interface PaymentsRefund {
1025
1062
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1054,7 +1091,7 @@ export type PaymentsSubscription = {
1054
1091
  provider: string;
1055
1092
  provider_sub_id: string;
1056
1093
  tier: string | null;
1057
- /** trialing | active | past_due | cancelled | expired | lapsed */
1094
+ /** trialing | active | past_due | paused | cancelled | expired | lapsed */
1058
1095
  status: string;
1059
1096
  current_period_start: string | null;
1060
1097
  current_period_end: string | null;
@@ -1067,6 +1104,11 @@ export type PaymentsSubscription = {
1067
1104
  * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1068
1105
  * can set it, so match on it — never grant access because of it */
1069
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;
1070
1112
  created_at: string;
1071
1113
  [key: string]: unknown;
1072
1114
  };
@@ -1444,6 +1486,12 @@ export interface AiJobHandle {
1444
1486
  * (`generateAsync`), kept 30 days after it settles; a sync/stream generation
1445
1487
  * returned its answer to you directly and records none. The lookup always
1446
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
+ };
1447
1495
  export interface AiGenerationRecord {
1448
1496
  generation_id: string;
1449
1497
  correlation_id: string | null;
@@ -1741,7 +1789,7 @@ export interface PaymentsRefundFailedEventPayload {
1741
1789
  state: 'broken';
1742
1790
  }
1743
1791
  /** `payments.subscription.<status>` (`trialing` | `active` | `past_due` |
1744
- * `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1792
+ * `paused` | `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1745
1793
  * (the period-end sweep's own ending). */
1746
1794
  export interface PaymentsSubscriptionStatusEventPayload {
1747
1795
  end_user_id: string;
@@ -1749,7 +1797,7 @@ export interface PaymentsSubscriptionStatusEventPayload {
1749
1797
  provider: string;
1750
1798
  provider_sub_id: string | null;
1751
1799
  tier: string | null;
1752
- status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1800
+ status: 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired' | 'lapsed';
1753
1801
  current_period_start: string | null;
1754
1802
  current_period_end: string | null;
1755
1803
  /** the subscription row's `reference` (a provider subscription carries the
@@ -1827,9 +1875,43 @@ export interface PaymentsSubscriptionRevokedEventPayload {
1827
1875
  via: 'delete' | 'revoke' | 'refund' | 'chargeback';
1828
1876
  charge_id: string | null;
1829
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;
1830
1886
  level: 'info';
1831
1887
  state: 'ok';
1832
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
+ }
1833
1915
  /** `payments.subscription.transferred` — a RevenueCat TRANSFER (`reason:
1834
1916
  * 'transfer'`) or the account-merge re-key (`reason: 'account_merge'`,
1835
1917
  * `provider: null`). */
@@ -2021,10 +2103,12 @@ export interface VxilEventPayloads {
2021
2103
  'payments.charge.completed': PaymentsChargeEventPayload;
2022
2104
  'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
2023
2105
  'payments.charge.disputed': PaymentsChargeRefundedEventPayload;
2106
+ 'payments.charge.dispute_reversed': PaymentsChargeDisputeReversedEventPayload;
2024
2107
  'payments.refund.failed': PaymentsRefundFailedEventPayload;
2025
2108
  'payments.subscription.trialing': PaymentsSubscriptionStatusEventPayload;
2026
2109
  'payments.subscription.active': PaymentsSubscriptionStatusEventPayload;
2027
2110
  'payments.subscription.past_due': PaymentsSubscriptionStatusEventPayload;
2111
+ 'payments.subscription.paused': PaymentsSubscriptionStatusEventPayload;
2028
2112
  'payments.subscription.cancelled': PaymentsSubscriptionStatusEventPayload;
2029
2113
  'payments.subscription.expired': PaymentsSubscriptionStatusEventPayload;
2030
2114
  'payments.subscription.lapsed': PaymentsSubscriptionStatusEventPayload;
@@ -2104,11 +2188,16 @@ export interface FunctionEnvelopeBase {
2104
2188
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
2105
2189
  * the item by `item_id`. */
2106
2190
  export interface CmsHookTriggerPayload {
2107
- /** `cms.item.created`, `cms.item.updated` or `cms.item.published` (per the
2108
- * 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 */
2109
2193
  event: string;
2110
2194
  collection: string;
2111
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;
2112
2201
  }
2113
2202
  /** `payload` of an `auth-hook` invocation: the event's own fields plus
2114
2203
  * `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
@@ -4578,6 +4667,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4578
4667
  id: string;
4579
4668
  password_hash?: string | null;
4580
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;
4581
4674
  identities?: Array<{
4582
4675
  provider: "google" | "apple" | "github" | "facebook";
4583
4676
  subject: string;
@@ -4992,6 +5085,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4992
5085
  * instead of per-item delete events. A collection another collection
4993
5086
  * references with an `on_delete` rule is skipped. Omit/null = keep. */
4994
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;
4995
5096
  /** Workspace scope (guide ch. 4): the workspace field — a string field on
4996
5097
  * index slot s1–s4 holding the orgs org id. End users then read and
4997
5098
  * write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
@@ -5052,6 +5153,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5052
5153
  write_roles?: string[];
5053
5154
  /** present when retention is set */
5054
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";
5055
5160
  /** present when the collection is workspace-scoped */
5056
5161
  org_field?: string;
5057
5162
  org_read_roles?: string[];
@@ -5067,6 +5172,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5067
5172
  write_roles?: string[] | null;
5068
5173
  /** retention in days (null = keep until deleted; absent from an older server) */
5069
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;
5070
5179
  /** the workspace field / org read gate (null = not workspace-scoped) */
5071
5180
  org_field?: string | null;
5072
5181
  org_read_roles?: string[] | null;
@@ -5157,6 +5266,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5157
5266
  collection: string;
5158
5267
  retain_days: number | null;
5159
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
+ }>;
5160
5285
  /** Re-project the collection's index slots after an `index_slot` move
5161
5286
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
5162
5287
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -6163,8 +6288,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6163
6288
  /** invite_token is returned ONCE — your app builds the accept URL.
6164
6289
  * `role`: admin | member | viewer, or a custom role_key defined with
6165
6290
  * `roles.define` (never owner). Pass `email: null` for a LINK invite —
6166
- * no email is sent and any signed-in user holding the token may accept. */
6167
- 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<{
6168
6297
  invite_id: string;
6169
6298
  invite_token: string;
6170
6299
  org_id: string;
@@ -6851,8 +6980,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6851
6980
  }) => Promise<AiJobHandle>;
6852
6981
  /** One generation: status, usage, run, and — for a settled job-lane
6853
6982
  * generation — the settled answer (`result`, kept 30 days). In end-user
6854
- * mode only the caller's own generation reads (a foreign id is a 404). */
6855
- 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>;
6856
6993
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
6857
6994
  * the recovery read after a timed-out or lost `generateAsync` answer.
6858
6995
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -7091,6 +7228,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7091
7228
  capabilities: string[];
7092
7229
  ledger_capabilities: string[];
7093
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
+ }>;
7094
7238
  client: {
7095
7239
  revenuecat: {
7096
7240
  project_id: string;
@@ -7312,6 +7456,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7312
7456
  listSubscriptions: (q?: {
7313
7457
  user_id?: string;
7314
7458
  status?: string;
7459
+ still_billing?: boolean;
7315
7460
  limit?: number;
7316
7461
  }) => Promise<PaymentsSubscription[]>;
7317
7462
  /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
@@ -7320,6 +7465,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7320
7465
  listSubscriptionsPage: (q?: {
7321
7466
  user_id?: string;
7322
7467
  status?: string;
7468
+ still_billing?: boolean;
7323
7469
  cursor?: string | null;
7324
7470
  limit?: number;
7325
7471
  }) => Promise<{
@@ -7383,18 +7529,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7383
7529
  * retrying the same refund fails the same way. A provider call that actually
7384
7530
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
7385
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 })`.
7386
7540
  */
7387
7541
  createRefund: (input: {
7388
7542
  charge_id: string;
7389
7543
  amount_cents?: number;
7390
7544
  reason?: string;
7545
+ cancel?: "none" | "period_end" | "immediately";
7391
7546
  }, opts: {
7392
7547
  idempotencyKey: string;
7393
- }) => Promise<{
7394
- refund_id: string;
7395
- status: "pending" | "succeeded" | "failed";
7396
- amount_cents: number;
7397
- }>;
7548
+ }) => Promise<PaymentsRefundResult>;
7398
7549
  /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
7399
7550
  * (the provider of their live subscription, not the tenant's primary):
7400
7551
  * `kind: 'portal'` = a provider-minted portal session URL (Stripe, Paddle
package/dist/index.js CHANGED
@@ -1654,6 +1654,16 @@ export class Vxil {
1654
1654
  * least 30 days later like any delete, one `cms.collection.retention_swept` audit event
1655
1655
  * per collection per sweep. Audited (`cms.collection.retain_days.set`). */
1656
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,
1657
1667
  /** Re-project the collection's index slots after an `index_slot` move
1658
1668
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
1659
1669
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -2253,8 +2263,10 @@ export class Vxil {
2253
2263
  /** invite_token is returned ONCE — your app builds the accept URL.
2254
2264
  * `role`: admin | member | viewer, or a custom role_key defined with
2255
2265
  * `roles.define` (never owner). Pass `email: null` for a LINK invite —
2256
- * no email is sent and any signed-in user holding the token may accept. */
2257
- 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,
2258
2270
  /** Redeem a token. With an end-user session the signed-in user is seated
2259
2271
  * (omit `userId`) and an email invite needs that user's VERIFIED email to
2260
2272
  * match (403 `invitation_email_mismatch`); a server key passes `userId`. */
@@ -2567,8 +2579,19 @@ export class Vxil {
2567
2579
  generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
2568
2580
  /** One generation: status, usage, run, and — for a settled job-lane
2569
2581
  * generation — the settled answer (`result`, kept 30 days). In end-user
2570
- * mode only the caller's own generation reads (a foreign id is a 404). */
2571
- 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
+ },
2572
2595
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
2573
2596
  * the recovery read after a timed-out or lost `generateAsync` answer.
2574
2597
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -2868,6 +2891,7 @@ export class Vxil {
2868
2891
  const s = qs({
2869
2892
  user_id: q?.user_id || undefined,
2870
2893
  status: q?.status || undefined,
2894
+ still_billing: q?.still_billing ? 'true' : undefined,
2871
2895
  cursor: q?.cursor || undefined,
2872
2896
  limit: q?.limit || undefined,
2873
2897
  });
@@ -2905,6 +2929,14 @@ export class Vxil {
2905
2929
  * retrying the same refund fails the same way. A provider call that actually
2906
2930
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
2907
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 })`.
2908
2940
  */
2909
2941
  createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
2910
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.27.0",
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).",