@vxil/sdk 0.21.0 → 0.23.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
@@ -154,6 +154,15 @@ export interface VxilUser {
154
154
  /** Set when the row's PII was scrubbed via DELETE /v1/users/:id?erase=true (GDPR Article 17). null = retained. */
155
155
  erased_at?: string | null;
156
156
  }
157
+ /** POST /v1/users and POST /v1/users/bulk entry. A full replace on upsert:
158
+ * an omitted field is cleared on an existing user. */
159
+ export interface VxilUserInput {
160
+ id: string;
161
+ email?: string;
162
+ display_name?: string;
163
+ avatar_url?: string;
164
+ attributes?: Record<string, unknown>;
165
+ }
157
166
  export interface Delivery {
158
167
  delivery_id: string;
159
168
  end_user_id: string;
@@ -347,8 +356,8 @@ export interface UsageCurrent {
347
356
  /** max(quota − used, 0); null when quota is null. */
348
357
  remaining: number | null;
349
358
  /** the PLAN's hard-cap policy — true only on the free tier (which is cut
350
- * off with 429 quota_exceeded when exhausted); paid tiers are never
351
- * interrupted mid-month. Not a live "the next request will 429" signal. */
359
+ * off with 429 quota_exceeded when exhausted); paid tiers have no monthly
360
+ * cap and are never billed for overage. Not a live "the next request will 429" signal. */
352
361
  enforced: boolean;
353
362
  };
354
363
  /** month-to-date per-feature metered detail. Aggregated periodically — it
@@ -414,6 +423,10 @@ export interface JobRun {
414
423
  * list (`vx.jobs.runs`) and the single-run read. */
415
424
  generation_status?: string | null;
416
425
  generation_json?: Record<string, unknown> | null;
426
+ /** generation runs only: the provider's job id, read from its accepted
427
+ * START answer at `completion.ref_path` (e.g. fal's `request_id`); null
428
+ * without the option or before the provider answered. List + single read. */
429
+ provider_ref?: string | null;
417
430
  /** the single-run read (`vx.jobs.run` / `waitForRun`) only: your enqueue
418
431
  * payload — `{ redacted: true }` for a platform-internal run; never on lists */
419
432
  payload_json?: unknown;
@@ -902,6 +915,10 @@ export interface PaymentsCharge {
902
915
  * reviewer's sandbox purchase (`revenuecat.sandboxUsers`) is `sandbox` —
903
916
  * leave it out of revenue */
904
917
  environment: PaymentsEventEnvironment;
918
+ /** the tenant's own reference from the checkout's custom data (Paddle
919
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
920
+ * can set it, so match on it — never grant access because of it */
921
+ reference: string | null;
905
922
  created_at: string;
906
923
  }
907
924
  /** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
@@ -971,6 +988,10 @@ export type PaymentsSubscription = {
971
988
  current_period_end: string | null;
972
989
  /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
973
990
  charge_id: string | null;
991
+ /** the tenant's own reference from the checkout's custom data (Paddle
992
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
993
+ * can set it, so match on it — never grant access because of it */
994
+ reference: string | null;
974
995
  created_at: string;
975
996
  [key: string]: unknown;
976
997
  };
@@ -1158,6 +1179,12 @@ export interface SearchQueryResult {
1158
1179
  * of the text, not by meaning, so results look real but are not semantic.
1159
1180
  * Set a real provider (or `'byov'`) before you ship. */
1160
1181
  embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1182
+ /** Present (true) only when the collection's pinned embed config (taken from
1183
+ * the default at create) differs from the current vector-search default; an
1184
+ * explicit embed override is never flagged. Re-create it (same name and
1185
+ * dimensions) with the embed you want (omit embed to take the current
1186
+ * default), then re-ingest. */
1187
+ embed_cfg_stale?: boolean;
1161
1188
  }
1162
1189
  /** Embedding-token + query + rerank counts since a timestamp (GET /v1/search/usage). */
1163
1190
  export interface SearchUsage {
@@ -1363,6 +1390,10 @@ export interface JobGenerationSettledEventPayload {
1363
1390
  /** the provider hint alone (`Upstream said: gemini 400: …`); null on
1364
1391
  * `completed` and whenever the failure carried none */
1365
1392
  error_hint: string | null;
1393
+ /** the provider's job id (`completion.ref_path` of the START answer);
1394
+ * null without the option or when the provider never accepted the run;
1395
+ * absent on events written before 2026-10-11 */
1396
+ provider_ref?: string | null;
1366
1397
  /** the failure-event vocabulary every `*.failed` carries (guide 12):
1367
1398
  * `completed` → info; `failed` → error, except a refusal at admission
1368
1399
  * (`ReserveInsufficient`, `PaymentsUnavailable`) → warn and a cancel
@@ -1412,7 +1443,8 @@ export interface JobBatchCompletedEventPayload {
1412
1443
  export type PaymentsEventEnvironment = 'production' | 'sandbox';
1413
1444
  /** Which credits a debit spends: ONE `credit_type`, or an ORDERED
1414
1445
  * `credit_types` (1–8 distinct) — the whole amount from the FIRST type whose
1415
- * available balance covers it, never split across types (2026-10-01 W9). */
1446
+ * available balance covers it, never split across types by default (unless
1447
+ * `allow_split: true` — 2026-10-11) (2026-10-01 W9). */
1416
1448
  export type PaymentsCreditTypeChoice = {
1417
1449
  credit_type: string;
1418
1450
  credit_types?: never;
@@ -1425,8 +1457,35 @@ export interface PaymentsConsumeResult {
1425
1457
  balance_after: number;
1426
1458
  ledger_entry_id: string | null;
1427
1459
  reversed: boolean;
1428
- /** the credit type the debit came from (the chosen one for an ordered consume) */
1460
+ /** the credit type the debit came from (the chosen one for an ordered
1461
+ * consume; the first part's for a split) */
1429
1462
  credit_type: string;
1463
+ /** (2026-10-11) only on a SPLIT (`allow_split: true` and no single type
1464
+ * covered the amount): one entry per type drawn, in list order — the first
1465
+ * is the row `ledger_entry_id` / `balance_after` / `credit_type` describe */
1466
+ parts?: Array<{
1467
+ credit_type: string;
1468
+ amount: number;
1469
+ ledger_entry_id: string;
1470
+ balance_after: number;
1471
+ }>;
1472
+ }
1473
+ /** `POST /v1/payments/credits/reverse` → `data` (2026-10-11). */
1474
+ export interface PaymentsReverseResult {
1475
+ user_id: string;
1476
+ /** the credits put back, summed over `entries` */
1477
+ amount: number;
1478
+ /** true when every consume was already reversed (a repeat): nothing moved */
1479
+ already_reversed: boolean;
1480
+ entries: Array<{
1481
+ /** the consume reversed */
1482
+ ledger_entry_id: string;
1483
+ /** the `reversal` ledger row */
1484
+ reversal_entry_id: string;
1485
+ credit_type: string;
1486
+ amount: number;
1487
+ balance_after: number | null;
1488
+ }>;
1430
1489
  }
1431
1490
  /** `payments.charge.succeeded` (a new charge row) / `payments.charge.completed`
1432
1491
  * (a recorded charge reached the provider's completed state — Paddle's
@@ -1442,6 +1501,10 @@ export interface PaymentsChargeEventPayload {
1442
1501
  currency: string;
1443
1502
  product_id: string | null;
1444
1503
  provider_status: PaymentsProviderChargeStatus | null;
1504
+ /** the tenant's own reference from the checkout's custom data (Paddle
1505
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1506
+ * can set it, so match on it — never grant access because of it */
1507
+ reference: string | null;
1445
1508
  environment: PaymentsEventEnvironment;
1446
1509
  level: 'info';
1447
1510
  }
@@ -1468,6 +1531,8 @@ export interface PaymentsChargeRefundedEventPayload {
1468
1531
  credit_type: string;
1469
1532
  amount: number;
1470
1533
  }>;
1534
+ /** the charge row's `reference` (see `PaymentsCharge.reference`) */
1535
+ reference: string | null;
1471
1536
  source: 'api' | 'webhook';
1472
1537
  environment: PaymentsEventEnvironment;
1473
1538
  level: 'info';
@@ -1500,6 +1565,9 @@ export interface PaymentsSubscriptionStatusEventPayload {
1500
1565
  status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1501
1566
  current_period_start: string | null;
1502
1567
  current_period_end: string | null;
1568
+ /** the subscription row's `reference` (a provider subscription carries the
1569
+ * checkout's; null on manual grants and passes) */
1570
+ reference: string | null;
1503
1571
  environment: PaymentsEventEnvironment;
1504
1572
  /** what wrote it: the provider event type, `subscription.synced` /
1505
1573
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
@@ -1590,6 +1658,22 @@ export interface PaymentsGrantFailedEventPayload {
1590
1658
  level: 'error';
1591
1659
  state: 'broken';
1592
1660
  }
1661
+ /** `payments.credits.reversed` (2026-10-11) — one committed consume was
1662
+ * reversed through `POST /v1/payments/credits/reverse` (one event per
1663
+ * consume; a repeated call emits nothing). */
1664
+ export interface PaymentsCreditsReversedEventPayload {
1665
+ end_user_id: string;
1666
+ credit_type: string;
1667
+ /** the credits put back (what the consume charged) */
1668
+ amount: number;
1669
+ /** the consume that was reversed */
1670
+ ledger_entry_id: string;
1671
+ /** the `reversal` ledger row */
1672
+ reversal_entry_id: string;
1673
+ /** the job the consume was held for, else null */
1674
+ job_id: string | null;
1675
+ reason: string | null;
1676
+ }
1593
1677
  /** `payments.webhook.rejected` — a signature / parse failure was persisted. */
1594
1678
  export interface PaymentsWebhookRejectedEventPayload {
1595
1679
  event_id: string;
@@ -1690,6 +1774,7 @@ export interface VxilEventPayloads {
1690
1774
  'payments.entitlement.changed': PaymentsEntitlementChangedEventPayload;
1691
1775
  'payments.entitlement.revoke.failed': PaymentsEntitlementRevokeFailedEventPayload;
1692
1776
  'payments.grant.failed': PaymentsGrantFailedEventPayload;
1777
+ 'payments.credits.reversed': PaymentsCreditsReversedEventPayload;
1693
1778
  'payments.webhook.rejected': PaymentsWebhookRejectedEventPayload;
1694
1779
  'payments.webhook_event.failed': PaymentsWebhookEventFailedEventPayload;
1695
1780
  'payments.webhook_event.reprocessed': PaymentsWebhookEventReprocessedEventPayload;
@@ -1734,15 +1819,15 @@ export interface FunctionEnvelopeBase {
1734
1819
  /** The edge to call vxil back through. */
1735
1820
  vxil_base: string;
1736
1821
  scoped_jwts: FunctionScopedJwts;
1737
- /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
1822
+ /** Your declared per-function secrets (`secrets: ['<name>']`), keyed by
1738
1823
  * bare name and resolved at invoke time. */
1739
1824
  secrets: Record<string, string>;
1740
1825
  }
1741
1826
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1742
1827
  * the item by `item_id`. */
1743
1828
  export interface CmsHookTriggerPayload {
1744
- /** `cms.item.created` or `cms.item.updated` for a binding that names a
1745
- * collection; a binding without one also sees the other `cms.item.*` events */
1829
+ /** `cms.item.created`, `cms.item.updated` or `cms.item.published` (per the
1830
+ * binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
1746
1831
  event: string;
1747
1832
  collection: string;
1748
1833
  item_id: string;
@@ -1807,12 +1892,35 @@ export interface InboundWebhookTriggerData {
1807
1892
  /** true on a `POST /v1/webhooks/events/:id/replay` */
1808
1893
  replayed?: true;
1809
1894
  }
1895
+ /** Who called an `http` function (2026-10-11). Absent when there is nothing
1896
+ * to carry, and always on an async invoke. */
1897
+ export interface FunctionClient {
1898
+ /** The caller's IP address, set by vxil from the network connection — never
1899
+ * from anything the caller sent. Present when the call came straight to
1900
+ * the API with a project key; absent when another function or a platform
1901
+ * hop made it. Key per-address limits on an IPv6 address's /64, and expect
1902
+ * many users behind one IPv4 address on mobile networks. */
1903
+ ip?: string;
1904
+ /** ISO 3166-1 alpha-2 country of `ip`, when known */
1905
+ country?: string;
1906
+ /** The request headers named in the http trigger's `forwardHeaders` that the
1907
+ * call carried (lower-case names, values ≤ 256 bytes). The caller wrote
1908
+ * them: never trust one for authorization. */
1909
+ headers?: Record<string, string>;
1910
+ }
1810
1911
  /** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
1811
1912
  * parameters on a GET). */
1812
1913
  export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
1813
1914
  trigger: 'http';
1814
1915
  /** present only when the caller presented a verified end-user session */
1815
1916
  end_user?: FunctionEndUser;
1917
+ /** the caller's address and forwarded headers (see FunctionClient) */
1918
+ client?: FunctionClient;
1919
+ /** Tenant-only tokens for the http trigger's `serverScopes` (each one of the
1920
+ * function's own scopes), present only when the trigger declares them. Not
1921
+ * bound to the end user: use them for rows the user must not write, and
1922
+ * take the owner from `end_user.id`, never from the payload. */
1923
+ server_jwts?: FunctionScopedJwts;
1816
1924
  payload: P;
1817
1925
  }
1818
1926
  export interface CmsHookFunctionEnvelope extends FunctionEnvelopeBase {
@@ -1957,6 +2065,21 @@ export interface AiUsageReport {
1957
2065
  output_tokens: number;
1958
2066
  }>;
1959
2067
  }
2068
+ /** POST /v1/webhooks/sources result. The receiver URL is returned ONCE; the
2069
+ * source verifies signatures once you set `signing_secret_name`
2070
+ * (`signing_secret_ref` says how). */
2071
+ export interface WebhookSourceCreated {
2072
+ source_id: string;
2073
+ receiver_url_path: string;
2074
+ provider: string;
2075
+ name: string;
2076
+ forward_url?: string | null;
2077
+ target_function?: string | null;
2078
+ state: string;
2079
+ created_at: string;
2080
+ signing_secret_name: string;
2081
+ signing_secret_ref: string;
2082
+ }
1960
2083
  /** A citation: the retrieved chunk that grounded the answer. */
1961
2084
  export interface RagCitation {
1962
2085
  chunk_id: string;
@@ -2068,9 +2191,12 @@ export interface CopilotConversation {
2068
2191
  * budgeted kept chunks — a citation can never lie). */
2069
2192
  export interface CopilotCitation {
2070
2193
  chunk_id: string;
2071
- document_id?: string;
2072
- score?: number;
2073
- [k: string]: unknown;
2194
+ doc_id: string;
2195
+ source?: {
2196
+ file?: string;
2197
+ page?: number;
2198
+ } | undefined;
2199
+ score: number;
2074
2200
  }
2075
2201
  /** A proposed WRITE action the agent wants to take — inert until confirmed. */
2076
2202
  export interface CopilotProposal {
@@ -2924,6 +3050,8 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2924
3050
  key?: Record<string, unknown>;
2925
3051
  }>;
2926
3052
  scanned: number;
3053
+ truncated: boolean;
3054
+ limit: number;
2927
3055
  }>;
2928
3056
  /** Window ranking over the aggregate (guide ch. 4). */
2929
3057
  rank(q: Omit<CmsRankBody, 'groupBy' | 'partitionBy' | 'metric'> & {
@@ -3003,17 +3131,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3003
3131
  * (`erased_at` cleared — the erase already removed the old data). While
3004
3132
  * the erased user's files are still being erased the call fails with 409
3005
3133
  * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
3006
- upsert: (user: {
3007
- id: string;
3008
- email?: string;
3009
- display_name?: string;
3010
- avatar_url?: string;
3011
- attributes?: Record<string, unknown>;
3012
- }) => Promise<VxilUser>;
3013
- bulk: (users: Array<{
3014
- id: string;
3015
- email?: string;
3016
- }>) => Promise<number>;
3134
+ upsert: (user: VxilUserInput) => Promise<VxilUser>;
3135
+ /** Upsert up to the bulk cap in one all-or-nothing call. Like `upsert`,
3136
+ * each entry is a FULL REPLACE: a field you leave out (display_name,
3137
+ * avatar_url, attributes, email) is cleared on an existing user. */
3138
+ bulk: (users: VxilUserInput[]) => Promise<number>;
3017
3139
  get: (id: string, opts?: {
3018
3140
  includeDeleted?: boolean;
3019
3141
  }) => Promise<VxilUser>;
@@ -3278,7 +3400,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3278
3400
  name: string;
3279
3401
  template: string;
3280
3402
  audience_ref: string;
3281
- channel?: "email" | "push" | "all";
3403
+ /** Only `email` is sent today; `push` / `all` are rejected (422). */
3404
+ channel?: "email";
3282
3405
  data?: Record<string, unknown>;
3283
3406
  schedule_cron?: string;
3284
3407
  quiet_hours?: {
@@ -3547,6 +3670,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3547
3670
  * provider words to completed | failed | processing (`{ OK: 'completed',
3548
3671
  * ERROR: 'failed' }`); `completion.result_path` names the value the run
3549
3672
  * settles with — the status mirror receives it as `result`.
3673
+ * `completion.ref_path` keeps the provider's job id from its START answer
3674
+ * (`provider_ref` on run reads and on job.generation.completed|failed);
3675
+ * with `provider.cancel` that job is cancelled at the provider when the
3676
+ * run is cancelled or expires. `completion.error_path` keeps a failed
3677
+ * answer's detail (`error_detail`). The 202 answers `expires_at`.
3550
3678
  *
3551
3679
  * A mirror write the record refuses never fails the run: a body refusal
3552
3680
  * (e.g. a callback key the collection does not declare) is retried with
@@ -3567,6 +3695,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3567
3695
  method?: string;
3568
3696
  headers?: Record<string, string>;
3569
3697
  body?: Record<string, unknown>;
3698
+ /** the provider's own cancel call, made ONCE (best-effort, no retry)
3699
+ * when the run is cancelled or expires after the provider accepted
3700
+ * it; `{provider_ref}` in the url is replaced by the job id
3701
+ * `completion.ref_path` read (required with it). Method default POST. */
3702
+ cancel?: {
3703
+ url: string;
3704
+ method?: string;
3705
+ headers?: Record<string, string>;
3706
+ };
3570
3707
  };
3571
3708
  completion: {
3572
3709
  mode: "poll" | "webhook";
@@ -3585,6 +3722,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3585
3722
  status_map?: Record<string, "completed" | "failed" | "processing">;
3586
3723
  /** dotted path of the value a completed run settles with (mirrored as `result`) */
3587
3724
  result_path?: string;
3725
+ /** dotted path of the provider's job id in its START answer (e.g.
3726
+ * `request_id`) — kept as the run's `provider_ref` */
3727
+ ref_path?: string;
3728
+ /** dotted path of the failure detail in a failed answer (e.g.
3729
+ * `payload.detail`) — kept on the run (≤ 1000 chars of JSON text)
3730
+ * and mirrored as `error_detail` (declare that field) */
3731
+ error_path?: string;
3588
3732
  };
3589
3733
  /** `progress_fields`: the progress keys (`progress` / `stage` /
3590
3734
  * `message`) a webhook-mode `processing` callback also writes onto the
@@ -3626,6 +3770,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3626
3770
  amount: number;
3627
3771
  user_id: string;
3628
3772
  reason?: string;
3773
+ /** with `credit_types` only (2026-10-11): hold across the types in
3774
+ * order when no single one covers `amount` (default: 402) */
3775
+ allow_split?: boolean;
3629
3776
  /** payments unreachable when the hold is placed (a 5xx other than
3630
3777
  * 501, a 429, no answer within 5 s; payments switched off is NOT
3631
3778
  * unreachable — that run starts without a hold): `'fail'` (default)
@@ -3650,6 +3797,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3650
3797
  generation_status: string;
3651
3798
  state?: string;
3652
3799
  deduplicated?: boolean;
3800
+ expires_at: string | null;
3653
3801
  }>;
3654
3802
  /** The newest runs (≤ `limit`, default 50, max 100). Filters: job_name,
3655
3803
  * state, batch_id, ids, since/until (creation time, ISO). For more than
@@ -4217,6 +4365,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4217
4365
  /** sessions taken over by auth config session.maxConcurrent (present once opted in) */
4218
4366
  took_over?: string[];
4219
4367
  }>;
4368
+ /** Attach another sign-in method to the SIGNED-IN user: verifies the
4369
+ * provider token like `native`, then links its stable (provider, sub)
4370
+ * to the user behind `session_token` — no new user, no new session
4371
+ * (keep the one you hold). Use it when an address would not match, e.g.
4372
+ * an Apple "Hide My Email" relay address on an OTP account. Idempotent
4373
+ * for an identity this user already holds; 409 `oauth_identity_linked`
4374
+ * when another user holds it; 401 `invalid_session` / 409
4375
+ * `anonymous_user` for an unknown or guest session. */
4376
+ link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4377
+ session_token: string;
4378
+ id_token?: string;
4379
+ access_token?: string;
4380
+ nonce?: string;
4381
+ }) => Promise<{
4382
+ user_id: string;
4383
+ linked: "linked";
4384
+ }>;
4220
4385
  };
4221
4386
  };
4222
4387
  readonly rateLimits: {
@@ -4449,8 +4614,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4449
4614
  reindex_required: boolean;
4450
4615
  }>;
4451
4616
  /** Set (or clear, with `null`) the collection's end-user owner-scope flag
4452
- * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
4453
- setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
4617
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
4618
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
4619
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
4620
+ setOwnerField: (collection: string, ownerField: string | null, opts?: {
4621
+ allowDestructive?: boolean;
4622
+ }) => Promise<void>;
4454
4623
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
4455
4624
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
4456
4625
  * (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
@@ -4668,6 +4837,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4668
4837
  key?: Record<string, unknown>;
4669
4838
  }>;
4670
4839
  scanned: number;
4840
+ /** true when more groups matched than `limit`: the result was cut. */
4841
+ truncated: boolean;
4842
+ /** the group limit applied (default min(100, the group cap)). */
4843
+ limit: number;
4671
4844
  }>;
4672
4845
  /** Window ranking over the aggregate — rank ∈
4673
4846
  * row_number|rank|percent_rank, computed over ≤500 aggregated groups
@@ -5301,12 +5474,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5301
5474
  forward_url?: string;
5302
5475
  target_function?: string;
5303
5476
  verify?: WebhookHmacVerify;
5304
- }) => Promise<{
5305
- source_id: string;
5306
- receiver_url_path: string;
5307
- provider: string;
5308
- target_function?: string | null;
5309
- }>;
5477
+ }) => Promise<WebhookSourceCreated>;
5310
5478
  list: () => Promise<Array<{
5311
5479
  source_id: string;
5312
5480
  provider: string;
@@ -5459,7 +5627,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5459
5627
  settings?: Record<string, unknown>;
5460
5628
  }>;
5461
5629
  members: {
5462
- add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer") => Promise<void>;
5630
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
5631
+ add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer" | (string & {})) => Promise<void>;
5463
5632
  list: (orgId: string) => Promise<Array<{
5464
5633
  user_id: string;
5465
5634
  role: string;
@@ -5684,7 +5853,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5684
5853
  usage: () => Promise<FilesUsage>;
5685
5854
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
5686
5855
  * object to vxil's public asset host: a stable, content-addressed URL
5687
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
5856
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
5688
5857
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
5689
5858
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
5690
5859
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -5809,6 +5978,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5809
5978
  provider?: string;
5810
5979
  documents?: number;
5811
5980
  created_at?: string;
5981
+ /** true when the embed config pinned from the default differs from the
5982
+ * current default (an explicit embed override is never flagged). */
5983
+ embed_cfg_stale?: boolean;
5812
5984
  }>>;
5813
5985
  /** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
5814
5986
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -6368,16 +6540,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6368
6540
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
6369
6541
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
6370
6542
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
6371
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
6543
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
6372
6544
  * available balance can't cover `amount`. Throws VxilError(409,
6373
6545
  * 'job_released') when `job_id` names a generation run that already ended
6374
- * (cancelled or failed) before this hold landed: nothing is held.
6546
+ * (cancelled, failed, or completed with nothing held) before this hold
6547
+ * landed: nothing is held.
6375
6548
  *
6376
6549
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6377
6550
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
6378
6551
  * amount comes from the FIRST type whose available balance covers it (one
6379
- * ledger row, never split across types) and the answer's `credit_type` names
6552
+ * ledger row, never split across types by default — unless `allow_split: true`,
6553
+ * below) and the answer's `credit_type` names
6380
6554
  * it. A retry with the same key answers the same type.
6555
+ *
6556
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
6557
+ * amount no single type covers draw across the types in list order (58
6558
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
6559
+ * listed in the answer's `parts`; a job hold of a split settles and
6560
+ * releases every part.
6381
6561
  */
6382
6562
  consume: (input: PaymentsCreditTypeChoice & {
6383
6563
  user_id: string;
@@ -6385,9 +6565,31 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6385
6565
  /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
6386
6566
  job_id?: string;
6387
6567
  reason?: string;
6568
+ /** with `credit_types` only: draw across the types when no single
6569
+ * one covers the amount (default false: 402 instead) */
6570
+ allow_split?: boolean;
6388
6571
  }, opts: {
6389
6572
  idempotencyKey: string;
6390
6573
  }) => Promise<PaymentsConsumeResult>;
6574
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
6575
+ * charge whose result you could not deliver. Name the consume's
6576
+ * `ledger_entry_id`, or the `job_id` (run_id) of a job hold that settled
6577
+ * (every part of a split). Puts back what was CHARGED (a pro-rated
6578
+ * settle's actual) as one `reversal` ledger row per consume — at most
6579
+ * once: a repeat answers `already_reversed: true` and moves nothing.
6580
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
6581
+ * job settles or releases it), 409 `nothing_charged` for a released hold
6582
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
6583
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
6584
+ reverse: (input: {
6585
+ ledger_entry_id: string;
6586
+ job_id?: never;
6587
+ reason?: string;
6588
+ } | {
6589
+ job_id: string;
6590
+ ledger_entry_id?: never;
6591
+ reason?: string;
6592
+ }) => Promise<PaymentsReverseResult>;
6391
6593
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
6392
6594
  * only ADDS; `amount` must be ≥ 1. */
6393
6595
  grant: (input: {
@@ -6431,6 +6633,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6431
6633
  balance_after: number | null;
6432
6634
  source: string | null;
6433
6635
  job_id: string | null;
6636
+ /** On a settle / reversal: the consume it corrects. */
6637
+ reverses_entry_id: string | null;
6434
6638
  created_at: string;
6435
6639
  }>;
6436
6640
  }>;
package/dist/index.js CHANGED
@@ -441,6 +441,9 @@ export class Vxil {
441
441
  * the erased user's files are still being erased the call fails with 409
442
442
  * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
443
443
  upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
444
+ /** Upsert up to the bulk cap in one all-or-nothing call. Like `upsert`,
445
+ * each entry is a FULL REPLACE: a field you leave out (display_name,
446
+ * avatar_url, attributes, email) is cleared on an existing user. */
444
447
  bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
445
448
  get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
446
449
  /**
@@ -820,6 +823,11 @@ export class Vxil {
820
823
  * provider words to completed | failed | processing (`{ OK: 'completed',
821
824
  * ERROR: 'failed' }`); `completion.result_path` names the value the run
822
825
  * settles with — the status mirror receives it as `result`.
826
+ * `completion.ref_path` keeps the provider's job id from its START answer
827
+ * (`provider_ref` on run reads and on job.generation.completed|failed);
828
+ * with `provider.cancel` that job is cancelled at the provider when the
829
+ * run is cancelled or expires. `completion.error_path` keeps a failed
830
+ * answer's detail (`error_detail`). The 202 answers `expires_at`.
823
831
  *
824
832
  * A mirror write the record refuses never fails the run: a body refusal
825
833
  * (e.g. a callback key the collection does not declare) is retried with
@@ -1265,6 +1273,15 @@ export class Vxil {
1265
1273
  * When sent, the id_token's `nonce` claim must equal it (401
1266
1274
  * `oauth_token_invalid` otherwise); omitted, it is not checked. */
1267
1275
  input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
1276
+ /** Attach another sign-in method to the SIGNED-IN user: verifies the
1277
+ * provider token like `native`, then links its stable (provider, sub)
1278
+ * to the user behind `session_token` — no new user, no new session
1279
+ * (keep the one you hold). Use it when an address would not match, e.g.
1280
+ * an Apple "Hide My Email" relay address on an OTP account. Idempotent
1281
+ * for an identity this user already holds; 409 `oauth_identity_linked`
1282
+ * when another user holds it; 401 `invalid_session` / 409
1283
+ * `anonymous_user` for an unknown or guest session. */
1284
+ link: async (provider, input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, { ...input, link: true })).data,
1268
1285
  },
1269
1286
  };
1270
1287
  rateLimits = {
@@ -1354,9 +1371,11 @@ export class Vxil {
1354
1371
  }
1355
1372
  },
1356
1373
  /** Set (or clear, with `null`) the collection's end-user owner-scope flag
1357
- * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
1358
- setOwnerField: async (collection, ownerField) => {
1359
- await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField });
1374
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
1375
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
1376
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
1377
+ setOwnerField: async (collection, ownerField, opts) => {
1378
+ await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField, ...(opts?.allowDestructive ? { allow_destructive: true } : {}) });
1360
1379
  },
1361
1380
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
1362
1381
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
@@ -1939,6 +1958,7 @@ export class Vxil {
1939
1958
  /** Update a workspace's name / `settings` JSON. */
1940
1959
  update: async (orgId, patch) => (await this.call('PATCH', `/v1/orgs/${encodeURIComponent(orgId)}`, patch)).data,
1941
1960
  members: {
1961
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
1942
1962
  add: async (orgId, userId, role) => {
1943
1963
  await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/members`, { user_id: userId, role });
1944
1964
  },
@@ -2073,7 +2093,7 @@ export class Vxil {
2073
2093
  usage: async () => (await this.call('GET', '/v1/files/usage')).data,
2074
2094
  /** SERVER-ONLY (403 server_only in end-user mode). Publish an available
2075
2095
  * object to vxil's public asset host: a stable, content-addressed URL
2076
- * (`https://cdn.vxil.app/<tenant>/<sha256>.<ext>`) served from a global
2096
+ * (`https://cdn.vxilcdn.com/<tenant>/<sha256>.<ext>`) served from a global
2077
2097
  * edge cache with `Cache-Control: public, max-age=31536000, immutable`,
2078
2098
  * playable video/audio and CORS from `publicAssets.corsOrigins`. Needs
2079
2099
  * `files.publicAssets.enabled`. Publishable: png/jpeg/webp/avif/gif,
@@ -2437,18 +2457,37 @@ export class Vxil {
2437
2457
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
2438
2458
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
2439
2459
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
2440
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
2460
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
2441
2461
  * available balance can't cover `amount`. Throws VxilError(409,
2442
2462
  * 'job_released') when `job_id` names a generation run that already ended
2443
- * (cancelled or failed) before this hold landed: nothing is held.
2463
+ * (cancelled, failed, or completed with nothing held) before this hold
2464
+ * landed: nothing is held.
2444
2465
  *
2445
2466
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2446
2467
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
2447
2468
  * amount comes from the FIRST type whose available balance covers it (one
2448
- * ledger row, never split across types) and the answer's `credit_type` names
2469
+ * ledger row, never split across types by default — unless `allow_split: true`,
2470
+ * below) and the answer's `credit_type` names
2449
2471
  * it. A retry with the same key answers the same type.
2472
+ *
2473
+ * Split (2026-10-11): with `credit_types`, `allow_split: true` lets an
2474
+ * amount no single type covers draw across the types in list order (58
2475
+ * `expiring` + 2 `permanent` for 60) — one ledger row per type drawn,
2476
+ * listed in the answer's `parts`; a job hold of a split settles and
2477
+ * releases every part.
2450
2478
  */
2451
2479
  consume: async (input, opts) => (await this.call('POST', '/v1/payments/credits/consume', input, { 'idempotency-key': opts.idempotencyKey })).data,
2480
+ /** (2026-10-11) Reverse a COMMITTED consume — the typed refund for a
2481
+ * charge whose result you could not deliver. Name the consume's
2482
+ * `ledger_entry_id`, or the `job_id` (run_id) of a job hold that settled
2483
+ * (every part of a split). Puts back what was CHARGED (a pro-rated
2484
+ * settle's actual) as one `reversal` ledger row per consume — at most
2485
+ * once: a repeat answers `already_reversed: true` and moves nothing.
2486
+ * Throws VxilError 409 `not_committed` while the hold is still held (its
2487
+ * job settles or releases it), 409 `nothing_charged` for a released hold
2488
+ * or a recorded 402, 404 for no such consume. Needs payments:write;
2489
+ * SERVER-SIDE KEYS ONLY (403 `server_only` on a thin-client key). */
2490
+ reverse: async (input) => (await this.call('POST', '/v1/payments/credits/reverse', input)).data,
2452
2491
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
2453
2492
  * only ADDS; `amount` must be ≥ 1. */
2454
2493
  grant: async (input, opts) => (await this.call('POST', '/v1/payments/credits/grant', input, { 'idempotency-key': opts.idempotencyKey })).data,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.21.0",
3
+ "version": "0.23.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).",