@vxil/sdk 0.21.0 → 0.22.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
@@ -902,6 +911,10 @@ export interface PaymentsCharge {
902
911
  * reviewer's sandbox purchase (`revenuecat.sandboxUsers`) is `sandbox` —
903
912
  * leave it out of revenue */
904
913
  environment: PaymentsEventEnvironment;
914
+ /** the tenant's own reference from the checkout's custom data (Paddle
915
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
916
+ * can set it, so match on it — never grant access because of it */
917
+ reference: string | null;
905
918
  created_at: string;
906
919
  }
907
920
  /** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
@@ -971,6 +984,10 @@ export type PaymentsSubscription = {
971
984
  current_period_end: string | null;
972
985
  /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
973
986
  charge_id: string | null;
987
+ /** the tenant's own reference from the checkout's custom data (Paddle
988
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
989
+ * can set it, so match on it — never grant access because of it */
990
+ reference: string | null;
974
991
  created_at: string;
975
992
  [key: string]: unknown;
976
993
  };
@@ -1158,6 +1175,12 @@ export interface SearchQueryResult {
1158
1175
  * of the text, not by meaning, so results look real but are not semantic.
1159
1176
  * Set a real provider (or `'byov'`) before you ship. */
1160
1177
  embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1178
+ /** Present (true) only when the collection's pinned embed config (taken from
1179
+ * the default at create) differs from the current vector-search default; an
1180
+ * explicit embed override is never flagged. Re-create it (same name and
1181
+ * dimensions) with the embed you want (omit embed to take the current
1182
+ * default), then re-ingest. */
1183
+ embed_cfg_stale?: boolean;
1161
1184
  }
1162
1185
  /** Embedding-token + query + rerank counts since a timestamp (GET /v1/search/usage). */
1163
1186
  export interface SearchUsage {
@@ -1442,6 +1465,10 @@ export interface PaymentsChargeEventPayload {
1442
1465
  currency: string;
1443
1466
  product_id: string | null;
1444
1467
  provider_status: PaymentsProviderChargeStatus | null;
1468
+ /** the tenant's own reference from the checkout's custom data (Paddle
1469
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1470
+ * can set it, so match on it — never grant access because of it */
1471
+ reference: string | null;
1445
1472
  environment: PaymentsEventEnvironment;
1446
1473
  level: 'info';
1447
1474
  }
@@ -1468,6 +1495,8 @@ export interface PaymentsChargeRefundedEventPayload {
1468
1495
  credit_type: string;
1469
1496
  amount: number;
1470
1497
  }>;
1498
+ /** the charge row's `reference` (see `PaymentsCharge.reference`) */
1499
+ reference: string | null;
1471
1500
  source: 'api' | 'webhook';
1472
1501
  environment: PaymentsEventEnvironment;
1473
1502
  level: 'info';
@@ -1500,6 +1529,9 @@ export interface PaymentsSubscriptionStatusEventPayload {
1500
1529
  status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1501
1530
  current_period_start: string | null;
1502
1531
  current_period_end: string | null;
1532
+ /** the subscription row's `reference` (a provider subscription carries the
1533
+ * checkout's; null on manual grants and passes) */
1534
+ reference: string | null;
1503
1535
  environment: PaymentsEventEnvironment;
1504
1536
  /** what wrote it: the provider event type, `subscription.synced` /
1505
1537
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
@@ -1734,15 +1766,15 @@ export interface FunctionEnvelopeBase {
1734
1766
  /** The edge to call vxil back through. */
1735
1767
  vxil_base: string;
1736
1768
  scoped_jwts: FunctionScopedJwts;
1737
- /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
1769
+ /** Your declared per-function secrets (`secrets: ['<name>']`), keyed by
1738
1770
  * bare name and resolved at invoke time. */
1739
1771
  secrets: Record<string, string>;
1740
1772
  }
1741
1773
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1742
1774
  * the item by `item_id`. */
1743
1775
  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 */
1776
+ /** `cms.item.created`, `cms.item.updated` or `cms.item.published` (per the
1777
+ * binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
1746
1778
  event: string;
1747
1779
  collection: string;
1748
1780
  item_id: string;
@@ -1957,6 +1989,21 @@ export interface AiUsageReport {
1957
1989
  output_tokens: number;
1958
1990
  }>;
1959
1991
  }
1992
+ /** POST /v1/webhooks/sources result. The receiver URL is returned ONCE; the
1993
+ * source verifies signatures once you set `signing_secret_name`
1994
+ * (`signing_secret_ref` says how). */
1995
+ export interface WebhookSourceCreated {
1996
+ source_id: string;
1997
+ receiver_url_path: string;
1998
+ provider: string;
1999
+ name: string;
2000
+ forward_url?: string | null;
2001
+ target_function?: string | null;
2002
+ state: string;
2003
+ created_at: string;
2004
+ signing_secret_name: string;
2005
+ signing_secret_ref: string;
2006
+ }
1960
2007
  /** A citation: the retrieved chunk that grounded the answer. */
1961
2008
  export interface RagCitation {
1962
2009
  chunk_id: string;
@@ -2068,9 +2115,12 @@ export interface CopilotConversation {
2068
2115
  * budgeted kept chunks — a citation can never lie). */
2069
2116
  export interface CopilotCitation {
2070
2117
  chunk_id: string;
2071
- document_id?: string;
2072
- score?: number;
2073
- [k: string]: unknown;
2118
+ doc_id: string;
2119
+ source?: {
2120
+ file?: string;
2121
+ page?: number;
2122
+ } | undefined;
2123
+ score: number;
2074
2124
  }
2075
2125
  /** A proposed WRITE action the agent wants to take — inert until confirmed. */
2076
2126
  export interface CopilotProposal {
@@ -2924,6 +2974,8 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2924
2974
  key?: Record<string, unknown>;
2925
2975
  }>;
2926
2976
  scanned: number;
2977
+ truncated: boolean;
2978
+ limit: number;
2927
2979
  }>;
2928
2980
  /** Window ranking over the aggregate (guide ch. 4). */
2929
2981
  rank(q: Omit<CmsRankBody, 'groupBy' | 'partitionBy' | 'metric'> & {
@@ -3003,17 +3055,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3003
3055
  * (`erased_at` cleared — the erase already removed the old data). While
3004
3056
  * the erased user's files are still being erased the call fails with 409
3005
3057
  * `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>;
3058
+ upsert: (user: VxilUserInput) => Promise<VxilUser>;
3059
+ /** Upsert up to the bulk cap in one all-or-nothing call. Like `upsert`,
3060
+ * each entry is a FULL REPLACE: a field you leave out (display_name,
3061
+ * avatar_url, attributes, email) is cleared on an existing user. */
3062
+ bulk: (users: VxilUserInput[]) => Promise<number>;
3017
3063
  get: (id: string, opts?: {
3018
3064
  includeDeleted?: boolean;
3019
3065
  }) => Promise<VxilUser>;
@@ -3278,7 +3324,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3278
3324
  name: string;
3279
3325
  template: string;
3280
3326
  audience_ref: string;
3281
- channel?: "email" | "push" | "all";
3327
+ /** Only `email` is sent today; `push` / `all` are rejected (422). */
3328
+ channel?: "email";
3282
3329
  data?: Record<string, unknown>;
3283
3330
  schedule_cron?: string;
3284
3331
  quiet_hours?: {
@@ -4449,8 +4496,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4449
4496
  reindex_required: boolean;
4450
4497
  }>;
4451
4498
  /** 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>;
4499
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
4500
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
4501
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
4502
+ setOwnerField: (collection: string, ownerField: string | null, opts?: {
4503
+ allowDestructive?: boolean;
4504
+ }) => Promise<void>;
4454
4505
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
4455
4506
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
4456
4507
  * (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
@@ -4668,6 +4719,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4668
4719
  key?: Record<string, unknown>;
4669
4720
  }>;
4670
4721
  scanned: number;
4722
+ /** true when more groups matched than `limit`: the result was cut. */
4723
+ truncated: boolean;
4724
+ /** the group limit applied (default min(100, the group cap)). */
4725
+ limit: number;
4671
4726
  }>;
4672
4727
  /** Window ranking over the aggregate — rank ∈
4673
4728
  * row_number|rank|percent_rank, computed over ≤500 aggregated groups
@@ -5301,12 +5356,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5301
5356
  forward_url?: string;
5302
5357
  target_function?: string;
5303
5358
  verify?: WebhookHmacVerify;
5304
- }) => Promise<{
5305
- source_id: string;
5306
- receiver_url_path: string;
5307
- provider: string;
5308
- target_function?: string | null;
5309
- }>;
5359
+ }) => Promise<WebhookSourceCreated>;
5310
5360
  list: () => Promise<Array<{
5311
5361
  source_id: string;
5312
5362
  provider: string;
@@ -5459,7 +5509,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5459
5509
  settings?: Record<string, unknown>;
5460
5510
  }>;
5461
5511
  members: {
5462
- add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer") => Promise<void>;
5512
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
5513
+ add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer" | (string & {})) => Promise<void>;
5463
5514
  list: (orgId: string) => Promise<Array<{
5464
5515
  user_id: string;
5465
5516
  role: string;
@@ -5809,6 +5860,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5809
5860
  provider?: string;
5810
5861
  documents?: number;
5811
5862
  created_at?: string;
5863
+ /** true when the embed config pinned from the default differs from the
5864
+ * current default (an explicit embed override is never flagged). */
5865
+ embed_cfg_stale?: boolean;
5812
5866
  }>>;
5813
5867
  /** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
5814
5868
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -6368,10 +6422,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6368
6422
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
6369
6423
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
6370
6424
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
6371
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
6425
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
6372
6426
  * available balance can't cover `amount`. Throws VxilError(409,
6373
6427
  * 'job_released') when `job_id` names a generation run that already ended
6374
- * (cancelled or failed) before this hold landed: nothing is held.
6428
+ * (cancelled, failed, or completed with nothing held) before this hold
6429
+ * landed: nothing is held.
6375
6430
  *
6376
6431
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6377
6432
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
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
  /**
@@ -1354,9 +1357,11 @@ export class Vxil {
1354
1357
  }
1355
1358
  },
1356
1359
  /** 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 });
1360
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
1361
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
1362
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
1363
+ setOwnerField: async (collection, ownerField, opts) => {
1364
+ await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField, ...(opts?.allowDestructive ? { allow_destructive: true } : {}) });
1360
1365
  },
1361
1366
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
1362
1367
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
@@ -1939,6 +1944,7 @@ export class Vxil {
1939
1944
  /** Update a workspace's name / `settings` JSON. */
1940
1945
  update: async (orgId, patch) => (await this.call('PATCH', `/v1/orgs/${encodeURIComponent(orgId)}`, patch)).data,
1941
1946
  members: {
1947
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
1942
1948
  add: async (orgId, userId, role) => {
1943
1949
  await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/members`, { user_id: userId, role });
1944
1950
  },
@@ -2437,10 +2443,11 @@ export class Vxil {
2437
2443
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
2438
2444
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
2439
2445
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
2440
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
2446
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
2441
2447
  * available balance can't cover `amount`. Throws VxilError(409,
2442
2448
  * 'job_released') when `job_id` names a generation run that already ended
2443
- * (cancelled or failed) before this hold landed: nothing is held.
2449
+ * (cancelled, failed, or completed with nothing held) before this hold
2450
+ * landed: nothing is held.
2444
2451
  *
2445
2452
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2446
2453
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.21.0",
3
+ "version": "0.22.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).",