@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 +86 -31
- package/dist/index.js +12 -5
- package/package.json +1 -1
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
|
|
351
|
-
*
|
|
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: ['
|
|
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.
|
|
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
|
-
|
|
2072
|
-
|
|
2073
|
-
|
|
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
|
-
|
|
3008
|
-
|
|
3009
|
-
|
|
3010
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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, '
|
|
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
|
|
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
|
-
|
|
1359
|
-
|
|
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, '
|
|
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
|
|
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