@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 +239 -35
- package/dist/index.js +46 -7
- 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
|
|
@@ -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
|
|
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
|
|
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: ['
|
|
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.
|
|
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
|
-
|
|
2072
|
-
|
|
2073
|
-
|
|
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
|
-
|
|
3008
|
-
|
|
3009
|
-
|
|
3010
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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, '
|
|
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
|
|
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
|
|
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
|
-
|
|
1359
|
-
|
|
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.
|
|
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, '
|
|
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
|
|
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
|
|
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