@vxil/sdk 0.27.0 → 0.29.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
@@ -219,9 +219,13 @@ export interface Delivery {
219
219
  * sunk at delivery time (an address added to `testRecipients` after the send
220
220
  * was queued): those are rendered WITHOUT the send's data (`rendered_from:
221
221
  * 'send_redacted'`), so a sign-in link, code or reset link is never stored or
222
- * readable. For every other row the template variables were never stored, so
223
- * `rendered` is the template re-rendered with no data (`rendered_from:
224
- * 'template'`), or null when it cannot be rendered. */
222
+ * readable. A `sent` row of a project with `templates.retainSentRender: true`
223
+ * carries the render of the real send the same way (`'send'`, or
224
+ * `'send_redacted'` for auth mail) for 7 days after `sent_at`. For every other
225
+ * row the template variables were never stored, so `rendered` is the template
226
+ * re-rendered with NO data — every `{{placeholder}}` empty, including the
227
+ * `transactional` subject (`rendered_from: 'template'`), or null when it
228
+ * cannot be rendered. */
225
229
  export interface DeliveryDetail extends Delivery {
226
230
  last_error_msg?: string | null;
227
231
  rendered: {
@@ -412,6 +416,25 @@ export interface UsageCurrent {
412
416
  cpu_ms_limit_per_day: number | null;
413
417
  as_of: string | null;
414
418
  } | null;
419
+ /** pricing v3: each capped lane of the plan (used / cap / resets_at /
420
+ * state) for the pool its caps count in — a Free account's projects share
421
+ * one. `used` null = not readable here yet; `cap` null = by contract.
422
+ * `db_bytes` is the project's row payload in the shared database (cms
423
+ * items, vector-search documents and chunks), measured nightly
424
+ * (`measured_at`; `resets_at` null): over it cms creates and updates
425
+ * answer 413 db_size_limit, reads and deletes always work.
426
+ * Absent from an older server; null for an end-user (thin-client) key. */
427
+ daily_caps?: {
428
+ pool: 'account' | 'project';
429
+ lanes: Array<{
430
+ lane: string;
431
+ used: number | null;
432
+ cap: number | null;
433
+ resets_at: string | null;
434
+ state: 'ok' | 'warning' | 'reached' | 'unknown';
435
+ measured_at?: string | null;
436
+ }>;
437
+ } | null;
415
438
  }
416
439
  export interface DeadLetter {
417
440
  delivery_id: string;
@@ -1020,6 +1043,24 @@ export interface PaymentsLedgerEntry {
1020
1043
  }
1021
1044
  /** Where a job hold's ledger row stands (`PaymentsLedgerEntry.hold`). */
1022
1045
  export type PaymentsLedgerHold = 'held' | 'settled' | 'released';
1046
+ /** What `createRefund` answers. `cancel` is present only when the refund asked
1047
+ * for a cancel (`cancel: 'period_end' | 'immediately'`, or the payments config
1048
+ * `refunds.cancelAtProvider` default): `cancel_scheduled` (the provider
1049
+ * subscription now ends — at period end, or at once for `immediately`), `awaiting_refund_settlement` (the refund is still
1050
+ * pending — the cancel runs when the provider settles it), `no_subscription`
1051
+ * (the charge paid no subscription), `failed` (see `error`; call
1052
+ * `DELETE /v1/payments/subscriptions/{id}` yourself). */
1053
+ export interface PaymentsRefundResult {
1054
+ refund_id: string;
1055
+ status: 'pending' | 'succeeded' | 'failed';
1056
+ amount_cents: number;
1057
+ cancel?: {
1058
+ requested: 'period_end' | 'immediately';
1059
+ status: 'cancel_scheduled' | 'awaiting_refund_settlement' | 'no_subscription' | 'failed';
1060
+ subscription_id?: string;
1061
+ error?: string;
1062
+ };
1063
+ }
1023
1064
  /** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
1024
1065
  export interface PaymentsRefund {
1025
1066
  /** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
@@ -1054,7 +1095,7 @@ export type PaymentsSubscription = {
1054
1095
  provider: string;
1055
1096
  provider_sub_id: string;
1056
1097
  tier: string | null;
1057
- /** trialing | active | past_due | cancelled | expired | lapsed */
1098
+ /** trialing | active | past_due | paused | cancelled | expired | lapsed */
1058
1099
  status: string;
1059
1100
  current_period_start: string | null;
1060
1101
  current_period_end: string | null;
@@ -1067,6 +1108,11 @@ export type PaymentsSubscription = {
1067
1108
  * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1068
1109
  * can set it, so match on it — never grant access because of it */
1069
1110
  reference: string | null;
1111
+ /** true while a refund / chargeback ended this row in vxil but its PROVIDER
1112
+ * subscription keeps billing (Stripe, Paddle, PayPal) — cancel it with
1113
+ * `cancelSubscription`. false otherwise; a cancel or a newer provider
1114
+ * event clears it. */
1115
+ provider_subscription_active: boolean;
1070
1116
  created_at: string;
1071
1117
  [key: string]: unknown;
1072
1118
  };
@@ -1351,6 +1397,12 @@ export interface AiToolCall {
1351
1397
  * not accept it (newer flash and Pro models; flash-lite accepts it). Thinking
1352
1398
  * tokens are billed as output tokens. */
1353
1399
  export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
1400
+ /** Gemini media resolution for `ai.generate` / `stream` / `generateAsync`
1401
+ * (`media_resolution`): the token budget Gemini spends per image or PDF page.
1402
+ * A lower level is faster and bills fewer input tokens. Sent to Gemini only —
1403
+ * every other provider ignores it; omitted →
1404
+ * `features.ai.defaults.mediaResolution` → the model's own default. */
1405
+ export type AiMediaResolution = 'low' | 'medium' | 'high';
1354
1406
  /** A prior conversation turn for the tool-calling round-trip: assistant turns
1355
1407
  * carry the tool_calls they made; `role:'tool'` turns carry one call's result
1356
1408
  * (`tool_call_id` correlates it; `name` is the tool's name). */
@@ -1444,6 +1496,12 @@ export interface AiJobHandle {
1444
1496
  * (`generateAsync`), kept 30 days after it settles; a sync/stream generation
1445
1497
  * returned its answer to you directly and records none. The lookup always
1446
1498
  * carries `result: null` — read the text by id. */
1499
+ /** What `vx.ai.getGeneration(id, { wait })` resolves to: the record, plus
1500
+ * `wait` only when a held read did not see a terminal generation. */
1501
+ export type AiGenerationRead = AiGenerationRecord & {
1502
+ /** `timeout` — the bound passed first; `unavailable` — the wait was not held */
1503
+ wait?: 'timeout' | 'unavailable';
1504
+ };
1447
1505
  export interface AiGenerationRecord {
1448
1506
  generation_id: string;
1449
1507
  correlation_id: string | null;
@@ -1741,7 +1799,7 @@ export interface PaymentsRefundFailedEventPayload {
1741
1799
  state: 'broken';
1742
1800
  }
1743
1801
  /** `payments.subscription.<status>` (`trialing` | `active` | `past_due` |
1744
- * `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1802
+ * `paused` | `cancelled` | `expired` | `lapsed`). `slack_hours` is set on `lapsed` only
1745
1803
  * (the period-end sweep's own ending). */
1746
1804
  export interface PaymentsSubscriptionStatusEventPayload {
1747
1805
  end_user_id: string;
@@ -1749,7 +1807,7 @@ export interface PaymentsSubscriptionStatusEventPayload {
1749
1807
  provider: string;
1750
1808
  provider_sub_id: string | null;
1751
1809
  tier: string | null;
1752
- status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1810
+ status: 'trialing' | 'active' | 'past_due' | 'paused' | 'cancelled' | 'expired' | 'lapsed';
1753
1811
  current_period_start: string | null;
1754
1812
  current_period_end: string | null;
1755
1813
  /** the subscription row's `reference` (a provider subscription carries the
@@ -1827,9 +1885,43 @@ export interface PaymentsSubscriptionRevokedEventPayload {
1827
1885
  via: 'delete' | 'revoke' | 'refund' | 'chargeback';
1828
1886
  charge_id: string | null;
1829
1887
  provider_refund_id: string | null;
1888
+ /** (2026-10-22 PAY-REFUND-STILL-BILLING) `true` when this ended row is a
1889
+ * PROVIDER subscription (Stripe, Paddle, PayPal) that vxil did NOT cancel at
1890
+ * the provider — the customer is charged again at the next renewal unless the
1891
+ * handler calls `DELETE /v1/payments/subscriptions/{id}` (or the refund was
1892
+ * made with `cancel: 'period_end'`). `false` for a manual / purchase-entitlement
1893
+ * row and a `/revoke` or `DELETE`; `null` for a store subscription
1894
+ * (RevenueCat — the store, not vxil, controls renewal). */
1895
+ provider_subscription_active: boolean | null;
1830
1896
  level: 'info';
1831
1897
  state: 'ok';
1832
1898
  }
1899
+ /** `payments.charge.dispute_reversed` (2026-10-22 PAY-DISPUTE-REINSTATE) — a
1900
+ * dispute / chargeback was WON or REVERSED (Stripe `charge.dispute.closed`
1901
+ * won / `funds_reinstated`, Paddle `chargeback_reverse`, PayPal
1902
+ * `CUSTOMER.DISPUTE.RESOLVED` in your favour, RevenueCat `REFUND_REVERSED`).
1903
+ * Fires only when something came back: the subscription rows the dispute
1904
+ * ended (`restored_subscriptions`), the `disputed` charge label, or the credits
1905
+ * it clawed back (`credits_restored`). */
1906
+ export interface PaymentsChargeDisputeReversedEventPayload {
1907
+ end_user_id: string | null;
1908
+ provider: string;
1909
+ charge_id: string | null;
1910
+ provider_charge_id: string | null;
1911
+ provider_refund_id: string | null;
1912
+ restored_subscriptions: Array<{
1913
+ subscription_id: string;
1914
+ tier: string | null;
1915
+ }>;
1916
+ credits_restored: Array<{
1917
+ credit_type: string;
1918
+ amount: number;
1919
+ }>;
1920
+ reference: string | null;
1921
+ source: 'webhook';
1922
+ environment: PaymentsEventEnvironment;
1923
+ level: 'info';
1924
+ }
1833
1925
  /** `payments.subscription.transferred` — a RevenueCat TRANSFER (`reason:
1834
1926
  * 'transfer'`) or the account-merge re-key (`reason: 'account_merge'`,
1835
1927
  * `provider: null`). */
@@ -2021,10 +2113,12 @@ export interface VxilEventPayloads {
2021
2113
  'payments.charge.completed': PaymentsChargeEventPayload;
2022
2114
  'payments.charge.refunded': PaymentsChargeRefundedEventPayload;
2023
2115
  'payments.charge.disputed': PaymentsChargeRefundedEventPayload;
2116
+ 'payments.charge.dispute_reversed': PaymentsChargeDisputeReversedEventPayload;
2024
2117
  'payments.refund.failed': PaymentsRefundFailedEventPayload;
2025
2118
  'payments.subscription.trialing': PaymentsSubscriptionStatusEventPayload;
2026
2119
  'payments.subscription.active': PaymentsSubscriptionStatusEventPayload;
2027
2120
  'payments.subscription.past_due': PaymentsSubscriptionStatusEventPayload;
2121
+ 'payments.subscription.paused': PaymentsSubscriptionStatusEventPayload;
2028
2122
  'payments.subscription.cancelled': PaymentsSubscriptionStatusEventPayload;
2029
2123
  'payments.subscription.expired': PaymentsSubscriptionStatusEventPayload;
2030
2124
  'payments.subscription.lapsed': PaymentsSubscriptionStatusEventPayload;
@@ -2104,11 +2198,16 @@ export interface FunctionEnvelopeBase {
2104
2198
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
2105
2199
  * the item by `item_id`. */
2106
2200
  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 */
2201
+ /** `cms.item.created`, `cms.item.updated`, `cms.item.published` or
2202
+ * `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
2203
  event: string;
2110
2204
  collection: string;
2111
2205
  item_id: string;
2206
+ /** `cms.item.deleted` only: the deleted row's owner (null when the
2207
+ * collection has no owner or the row had none). Absent on other events. */
2208
+ owner?: string | null;
2209
+ /** `cms.item.deleted` only: the row's workspace org (null when none). */
2210
+ org?: string | null;
2112
2211
  }
2113
2212
  /** `payload` of an `auth-hook` invocation: the event's own fields plus
2114
2213
  * `event`. `auth.user.created` → `{ user_id, method, is_anonymous }`;
@@ -4578,6 +4677,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4578
4677
  id: string;
4579
4678
  password_hash?: string | null;
4580
4679
  email_verified?: boolean;
4680
+ /** source timestamps (ISO 8601 with a zone), written on create only and
4681
+ * clamped to now; `email_verified_at` implies `email_verified` */
4682
+ created_at?: string;
4683
+ email_verified_at?: string;
4581
4684
  identities?: Array<{
4582
4685
  provider: "google" | "apple" | "github" | "facebook";
4583
4686
  subject: string;
@@ -4798,10 +4901,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4798
4901
  * config `security.allowedRedirectOrigins` when set (else
4799
4902
  * `422 redirect_not_allowed`), and the state expires after
4800
4903
  * `expires_in` seconds (600). `anonymous_token` (a guest bearer)
4801
- * promotes or merges that guest at the callback. */
4904
+ * promotes or merges that guest at the callback. `prompt` (google and
4905
+ * oidc only; 2026-10-23) asks the provider to show its account picker
4906
+ * (`select_account`), the consent screen (`consent`) or a fresh sign-in
4907
+ * (`login`); any other value, or a prompt on another provider, is a 422. */
4802
4908
  startUrl: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4803
4909
  redirect_uri: string;
4804
4910
  anonymous_token?: string;
4911
+ prompt?: "select_account" | "consent" | "login";
4805
4912
  }) => Promise<{
4806
4913
  authorize_url: string;
4807
4914
  expires_in: number;
@@ -4992,6 +5099,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4992
5099
  * instead of per-item delete events. A collection another collection
4993
5100
  * references with an `on_delete` rule is skipped. Omit/null = keep. */
4994
5101
  retain_days?: number | null;
5102
+ /** Recovery window for DELETED items (guide ch. 4): 0..29 days a
5103
+ * soft-deleted item stays restorable before the nightly cleanup purges
5104
+ * it (0 = at the next nightly run). Omit/null = the default 30 days. */
5105
+ deleted_retain_days?: number | null;
5106
+ /** What a GDPR erase of a user does to the items they own here (guide
5107
+ * ch. 9; needs `owner_field`): 'delete' hard-deletes them in the erase
5108
+ * transaction; 'keep' (default) leaves them. */
5109
+ on_owner_erase?: "delete" | "keep" | null;
4995
5110
  /** Workspace scope (guide ch. 4): the workspace field — a string field on
4996
5111
  * index slot s1–s4 holding the orgs org id. End users then read and
4997
5112
  * write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
@@ -5052,6 +5167,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5052
5167
  write_roles?: string[];
5053
5168
  /** present when retention is set */
5054
5169
  retain_days?: number;
5170
+ /** present when a shorter deleted-item window is set */
5171
+ deleted_retain_days?: number;
5172
+ /** present when a user's erase deletes their items here */
5173
+ on_owner_erase?: "delete";
5055
5174
  /** present when the collection is workspace-scoped */
5056
5175
  org_field?: string;
5057
5176
  org_read_roles?: string[];
@@ -5067,6 +5186,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5067
5186
  write_roles?: string[] | null;
5068
5187
  /** retention in days (null = keep until deleted; absent from an older server) */
5069
5188
  retain_days?: number | null;
5189
+ /** deleted-item recovery window in days (null = the default 30) */
5190
+ deleted_retain_days?: number | null;
5191
+ /** 'delete' = a user's erase deletes the items they own (null = keep) */
5192
+ on_owner_erase?: "delete" | null;
5070
5193
  /** the workspace field / org read gate (null = not workspace-scoped) */
5071
5194
  org_field?: string | null;
5072
5195
  org_read_roles?: string[] | null;
@@ -5157,6 +5280,22 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5157
5280
  collection: string;
5158
5281
  retain_days: number | null;
5159
5282
  }>;
5283
+ /** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
5284
+ * item stays restorable (guide ch. 4) before the nightly cleanup purges
5285
+ * it for good; 0 = purged at the next nightly run. Audited
5286
+ * (`cms.collection.deleted_retain_days.set`). */
5287
+ setDeletedRetention: (collection: string, days: number | null) => Promise<{
5288
+ collection: string;
5289
+ deleted_retain_days: number | null;
5290
+ }>;
5291
+ /** What a GDPR erase of a user does to the items they OWN in this
5292
+ * collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
5293
+ * them (live and deleted) inside the erase transaction; 'keep' (the
5294
+ * default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
5295
+ setOnOwnerErase: (collection: string, mode: "delete" | "keep") => Promise<{
5296
+ collection: string;
5297
+ on_owner_erase: "delete" | null;
5298
+ }>;
5160
5299
  /** Re-project the collection's index slots after an `index_slot` move
5161
5300
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
5162
5301
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -6163,8 +6302,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6163
6302
  /** invite_token is returned ONCE — your app builds the accept URL.
6164
6303
  * `role`: admin | member | viewer, or a custom role_key defined with
6165
6304
  * `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<{
6305
+ * no email is sent and any signed-in user holding the token may accept.
6306
+ * `opts.notify: false` keeps vxil from e-mailing the invitee (your app
6307
+ * delivers the invitation itself with the returned token). */
6308
+ create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {}), opts?: {
6309
+ notify?: boolean;
6310
+ }) => Promise<{
6168
6311
  invite_id: string;
6169
6312
  invite_token: string;
6170
6313
  org_id: string;
@@ -6589,6 +6732,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6589
6732
  mode?: "hybrid" | "vector" | "keyword";
6590
6733
  filter?: SearchFilter;
6591
6734
  rrf_k?: number;
6735
+ /** Hybrid mode only: per-lane RRF weights (0..100 each, not both 0).
6736
+ * Default: the config's `hybrid.weights`, else 1 / 1 (unweighted). */
6737
+ weights?: {
6738
+ vector: number;
6739
+ keyword: number;
6740
+ };
6592
6741
  vector?: number[];
6593
6742
  rerank?: boolean;
6594
6743
  /** orgScoped collections: the workspace to search — REQUIRED with a
@@ -6690,6 +6839,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6690
6839
  temperature?: number;
6691
6840
  /** Gemini thinking depth — see AiThinkingLevel. */
6692
6841
  thinking_level?: AiThinkingLevel;
6842
+ /** Gemini per-image / per-page token budget — see AiMediaResolution. */
6843
+ media_resolution?: AiMediaResolution;
6693
6844
  tools?: Array<{
6694
6845
  name: string;
6695
6846
  description?: string;
@@ -6750,6 +6901,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6750
6901
  temperature?: number;
6751
6902
  /** Gemini thinking depth — see AiThinkingLevel. */
6752
6903
  thinking_level?: AiThinkingLevel;
6904
+ /** Gemini per-image / per-page token budget — see AiMediaResolution. */
6905
+ media_resolution?: AiMediaResolution;
6753
6906
  tools?: Array<{
6754
6907
  name: string;
6755
6908
  description?: string;
@@ -6787,6 +6940,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6787
6940
  temperature?: number;
6788
6941
  /** Gemini thinking depth — see AiThinkingLevel. */
6789
6942
  thinking_level?: AiThinkingLevel;
6943
+ /** Gemini per-image / per-page token budget — see AiMediaResolution. */
6944
+ media_resolution?: AiMediaResolution;
6790
6945
  tools?: Array<{
6791
6946
  name: string;
6792
6947
  description?: string;
@@ -6848,11 +7003,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6848
7003
  };
6849
7004
  }, opts?: {
6850
7005
  idempotencyKey?: string;
7006
+ /** Interactive job runs: bound the run's FIRST provider call at this
7007
+ * many ms (integer 1000–17000; sent as `deadline_ms`). A run with a
7008
+ * deadline can start without the queue hop; a first call that passes
7009
+ * it is retried on the queue with the normal job-lane bound. Pair it
7010
+ * with `getGeneration(id, { wait: 25 })`. */
7011
+ deadlineMs?: number;
6851
7012
  }) => Promise<AiJobHandle>;
6852
7013
  /** One generation: status, usage, run, and — for a settled job-lane
6853
7014
  * 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>;
7015
+ * mode only the caller's own generation reads (a foreign id is a 404).
7016
+ * With `{ wait }` (integer 1..25 seconds) the read is held platform-side
7017
+ * until the generation is `completed` / `failed` — ONE API call instead of
7018
+ * a poll loop; if it is still running at the deadline the current record
7019
+ * comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
7020
+ * budget of 300 held reads a minute declined to hold). A client
7021
+ * `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
7022
+ getGeneration: (generationId: string, opts?: {
7023
+ wait?: number;
7024
+ }) => Promise<AiGenerationRead>;
6856
7025
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
6857
7026
  * the recovery read after a timed-out or lost `generateAsync` answer.
6858
7027
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -7091,6 +7260,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7091
7260
  capabilities: string[];
7092
7261
  ledger_capabilities: string[];
7093
7262
  missing: string[];
7263
+ /** (2026-10-22) every provider the tenant can drive (primary + secondaries with their own config block) */
7264
+ providers: Array<{
7265
+ provider: string;
7266
+ primary: boolean;
7267
+ capabilities: string[];
7268
+ missing: string[];
7269
+ }>;
7094
7270
  client: {
7095
7271
  revenuecat: {
7096
7272
  project_id: string;
@@ -7271,11 +7447,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7271
7447
  * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
7272
7448
  * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
7273
7449
  * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
7274
- * user's own rows). */
7450
+ * user's own rows). `org_id` (2026-10-23) lists one workspace's rows (the
7451
+ * same as `user_id: 'org:<id>'`); give it OR `user_id`. */
7275
7452
  ledger: (q?: {
7276
7453
  since?: string;
7277
7454
  cursor?: string;
7278
7455
  user_id?: string;
7456
+ org_id?: string;
7279
7457
  credit_type?: string;
7280
7458
  limit?: number;
7281
7459
  }) => Promise<{
@@ -7312,6 +7490,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7312
7490
  listSubscriptions: (q?: {
7313
7491
  user_id?: string;
7314
7492
  status?: string;
7493
+ still_billing?: boolean;
7315
7494
  limit?: number;
7316
7495
  }) => Promise<PaymentsSubscription[]>;
7317
7496
  /** One page of {@link listSubscriptions} (newest first) plus `next_cursor`
@@ -7320,6 +7499,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7320
7499
  listSubscriptionsPage: (q?: {
7321
7500
  user_id?: string;
7322
7501
  status?: string;
7502
+ still_billing?: boolean;
7323
7503
  cursor?: string | null;
7324
7504
  limit?: number;
7325
7505
  }) => Promise<{
@@ -7383,18 +7563,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7383
7563
  * retrying the same refund fails the same way. A provider call that actually
7384
7564
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
7385
7565
  * (the row that went `failed`) so you can tie them to this call.
7566
+ *
7567
+ * A refund ends access in vxil but the PROVIDER subscription keeps billing
7568
+ * until it is cancelled. `cancel: 'period_end'` stops it at period end once
7569
+ * the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
7570
+ * and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
7571
+ * `'none'` keeps them separate. Without `cancel` the payments config
7572
+ * `refunds.cancelAtProvider` decides (default off). Rows still billing:
7573
+ * `listSubscriptions({ still_billing: true })`.
7386
7574
  */
7387
7575
  createRefund: (input: {
7388
7576
  charge_id: string;
7389
7577
  amount_cents?: number;
7390
7578
  reason?: string;
7579
+ cancel?: "none" | "period_end" | "immediately";
7391
7580
  }, opts: {
7392
7581
  idempotencyKey: string;
7393
- }) => Promise<{
7394
- refund_id: string;
7395
- status: "pending" | "succeeded" | "failed";
7396
- amount_cents: number;
7397
- }>;
7582
+ }) => Promise<PaymentsRefundResult>;
7398
7583
  /** Where the user MANAGES their subscription, resolved by FUNDING SOURCE
7399
7584
  * (the provider of their live subscription, not the tenant's primary):
7400
7585
  * `kind: 'portal'` = a provider-minted portal session URL (Stripe, Paddle
package/dist/index.js CHANGED
@@ -1483,11 +1483,15 @@ export class Vxil {
1483
1483
  * config `security.allowedRedirectOrigins` when set (else
1484
1484
  * `422 redirect_not_allowed`), and the state expires after
1485
1485
  * `expires_in` seconds (600). `anonymous_token` (a guest bearer)
1486
- * promotes or merges that guest at the callback. */
1486
+ * promotes or merges that guest at the callback. `prompt` (google and
1487
+ * oidc only; 2026-10-23) asks the provider to show its account picker
1488
+ * (`select_account`), the consent screen (`consent`) or a fresh sign-in
1489
+ * (`login`); any other value, or a prompt on another provider, is a 422. */
1487
1490
  startUrl: async (provider, input) => {
1488
1491
  // plain encodeURIComponent (no URLSearchParams — React Native ≤ 0.79)
1489
1492
  const q = `redirect_uri=${encodeURIComponent(input.redirect_uri)}`
1490
- + (input.anonymous_token ? `&anonymous_token=${encodeURIComponent(input.anonymous_token)}` : '');
1493
+ + (input.anonymous_token ? `&anonymous_token=${encodeURIComponent(input.anonymous_token)}` : '')
1494
+ + (input.prompt ? `&prompt=${encodeURIComponent(input.prompt)}` : '');
1491
1495
  return (await this.call('GET', `/v1/auth/oauth/${encodeURIComponent(provider)}/start?${q}`, undefined, { accept: 'application/json' })).data;
1492
1496
  },
1493
1497
  /** Native social sign-in: exchange a provider `id_token`/`access_token`
@@ -1654,6 +1658,16 @@ export class Vxil {
1654
1658
  * least 30 days later like any delete, one `cms.collection.retention_swept` audit event
1655
1659
  * per collection per sweep. Audited (`cms.collection.retain_days.set`). */
1656
1660
  setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
1661
+ /** Set (0..29 days) or reset (`null` = the default 30) how long a DELETED
1662
+ * item stays restorable (guide ch. 4) before the nightly cleanup purges
1663
+ * it for good; 0 = purged at the next nightly run. Audited
1664
+ * (`cms.collection.deleted_retain_days.set`). */
1665
+ setDeletedRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { deleted_retain_days: days })).data,
1666
+ /** What a GDPR erase of a user does to the items they OWN in this
1667
+ * collection (guide ch. 9; needs its owner_field): 'delete' hard-deletes
1668
+ * them (live and deleted) inside the erase transaction; 'keep' (the
1669
+ * default) leaves them. Audited (`cms.collection.on_owner_erase.set`). */
1670
+ setOnOwnerErase: async (collection, mode) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { on_owner_erase: mode })).data,
1657
1671
  /** Re-project the collection's index slots after an `index_slot` move
1658
1672
  * (guide ch. 4). Slots are projected on WRITE only, so until this runs,
1659
1673
  * stored rows keep their OLD projection: the new slot is NULL and the
@@ -2253,8 +2267,10 @@ export class Vxil {
2253
2267
  /** invite_token is returned ONCE — your app builds the accept URL.
2254
2268
  * `role`: admin | member | viewer, or a custom role_key defined with
2255
2269
  * `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,
2270
+ * no email is sent and any signed-in user holding the token may accept.
2271
+ * `opts.notify: false` keeps vxil from e-mailing the invitee (your app
2272
+ * delivers the invitation itself with the returned token). */
2273
+ 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
2274
  /** Redeem a token. With an end-user session the signed-in user is seated
2259
2275
  * (omit `userId`) and an email invite needs that user's VERIFIED email to
2260
2276
  * match (403 `invitation_email_mismatch`); a server key passes `userId`. */
@@ -2564,11 +2580,22 @@ export class Vxil {
2564
2580
  * `opts.idempotencyKey` deduplicates for 24 h: a re-send after a timeout
2565
2581
  * or a lost answer returns the ORIGINAL handle (`deduplicated: true`) and
2566
2582
  * never pays the provider twice. */
2567
- generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job' }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
2583
+ generateAsync: async (input, opts) => (await this.call('POST', '/v1/ai/generate', { ...input, mode: 'job', ...(opts?.deadlineMs !== undefined ? { deadline_ms: opts.deadlineMs } : {}) }, opts?.idempotencyKey ? { 'idempotency-key': opts.idempotencyKey } : {})).data,
2568
2584
  /** One generation: status, usage, run, and — for a settled job-lane
2569
2585
  * 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,
2586
+ * mode only the caller's own generation reads (a foreign id is a 404).
2587
+ * With `{ wait }` (integer 1..25 seconds) the read is held platform-side
2588
+ * until the generation is `completed` / `failed` — ONE API call instead of
2589
+ * a poll loop; if it is still running at the deadline the current record
2590
+ * comes back with `wait: 'timeout'` (`'unavailable'` when the per-tenant
2591
+ * budget of 300 held reads a minute declined to hold). A client
2592
+ * `timeoutMs` shorter than `wait` × 1000 aborts the call first. */
2593
+ getGeneration: async (generationId, opts) => {
2594
+ const qs = opts?.wait !== undefined ? `?wait=${encodeURIComponent(String(opts.wait))}` : '';
2595
+ const { data, response } = await this.call('GET', `/v1/ai/generations/${encodeURIComponent(generationId)}${qs}`);
2596
+ const w = response.headers.get('x-vxil-wait');
2597
+ return w === 'timeout' || w === 'unavailable' ? { ...data, wait: w } : data;
2598
+ },
2572
2599
  /** Find generations by YOUR `correlation_id` (newest first, at most 20) —
2573
2600
  * the recovery read after a timed-out or lost `generateAsync` answer.
2574
2601
  * Each carries `result: null` (`result_state` still says whether an answer
@@ -2837,12 +2864,14 @@ export class Vxil {
2837
2864
  * a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
2838
2865
  * Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
2839
2866
  * (`end_user_required`) key gets 403 `server_only` (use `usage` for one
2840
- * user's own rows). */
2867
+ * user's own rows). `org_id` (2026-10-23) lists one workspace's rows (the
2868
+ * same as `user_id: 'org:<id>'`); give it OR `user_id`. */
2841
2869
  ledger: async (q) => {
2842
2870
  const suffix = qs({
2843
2871
  since: q?.since || undefined,
2844
2872
  cursor: q?.cursor || undefined,
2845
2873
  user_id: q?.user_id || undefined,
2874
+ org_id: q?.org_id || undefined,
2846
2875
  credit_type: q?.credit_type || undefined,
2847
2876
  limit: q?.limit || undefined,
2848
2877
  });
@@ -2868,6 +2897,7 @@ export class Vxil {
2868
2897
  const s = qs({
2869
2898
  user_id: q?.user_id || undefined,
2870
2899
  status: q?.status || undefined,
2900
+ still_billing: q?.still_billing ? 'true' : undefined,
2871
2901
  cursor: q?.cursor || undefined,
2872
2902
  limit: q?.limit || undefined,
2873
2903
  });
@@ -2905,6 +2935,14 @@ export class Vxil {
2905
2935
  * retrying the same refund fails the same way. A provider call that actually
2906
2936
  * fails is still 502 `provider_error`. Both failure bodies carry `refund_id`
2907
2937
  * (the row that went `failed`) so you can tie them to this call.
2938
+ *
2939
+ * A refund ends access in vxil but the PROVIDER subscription keeps billing
2940
+ * until it is cancelled. `cancel: 'period_end'` stops it at period end once
2941
+ * the refund has settled; `cancel: 'immediately'` ends it at once (Stripe
2942
+ * and the mock only — 422 `cancel_immediately_unsupported` elsewhere);
2943
+ * `'none'` keeps them separate. Without `cancel` the payments config
2944
+ * `refunds.cancelAtProvider` decides (default off). Rows still billing:
2945
+ * `listSubscriptions({ still_billing: true })`.
2908
2946
  */
2909
2947
  createRefund: async (input, opts) => (await this.call('POST', '/v1/payments/refunds', input, { 'idempotency-key': opts.idempotencyKey })).data,
2910
2948
  /** 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.29.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).",