@vxil/sdk 0.18.0 → 0.20.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 +314 -18
- package/dist/index.js +160 -14
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -885,6 +885,33 @@ export interface PaymentsCharge {
|
|
|
885
885
|
environment: PaymentsEventEnvironment;
|
|
886
886
|
created_at: string;
|
|
887
887
|
}
|
|
888
|
+
/** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
|
|
889
|
+
export interface PaymentsLedgerEntry {
|
|
890
|
+
/** `led_…` */
|
|
891
|
+
ledger_entry_id: string;
|
|
892
|
+
user_id: string;
|
|
893
|
+
credit_type: string;
|
|
894
|
+
/** grant / grant_once add credits; consume and expire remove them; settle and
|
|
895
|
+
* reversal correct a job-linked consume (`reverses_entry_id` names it) */
|
|
896
|
+
kind: 'grant' | 'grant_once' | 'consume' | 'settle' | 'reversal' | 'expire';
|
|
897
|
+
/** `provisional` = a job-linked hold not settled yet */
|
|
898
|
+
state: 'provisional' | 'committed' | 'reversed';
|
|
899
|
+
/** `insufficient` = a recorded 402 consume (no balance moved) */
|
|
900
|
+
outcome: 'applied' | 'insufficient';
|
|
901
|
+
/** the signed amount: positive adds credits, negative removes them */
|
|
902
|
+
delta: number;
|
|
903
|
+
balance_after: number | null;
|
|
904
|
+
source: string | null;
|
|
905
|
+
/** the jobs run this row is linked to */
|
|
906
|
+
job_id: string | null;
|
|
907
|
+
/** on a settle / reversal: the consume entry it corrects */
|
|
908
|
+
reverses_entry_id: string | null;
|
|
909
|
+
/** the grant-once dedup key */
|
|
910
|
+
grant_key: string | null;
|
|
911
|
+
/** the Idempotency-Key the consume / grant was sent with */
|
|
912
|
+
idempotency_key: string | null;
|
|
913
|
+
created_at: string;
|
|
914
|
+
}
|
|
888
915
|
/** A refund row as listed by GET /v1/payments/refunds (2026-10-01). */
|
|
889
916
|
export interface PaymentsRefund {
|
|
890
917
|
/** `ref_…` — what `createRefund` returned, and what a 502 / `payments.refund.failed`
|
|
@@ -1646,9 +1673,11 @@ export type VxilEventPayload<E extends string> = E extends keyof VxilEventPayloa
|
|
|
1646
1673
|
export type FunctionEnvelopeTrigger = 'http' | 'cms-hook' | 'auth-hook' | 'queue' | 'cron' | 'webhook';
|
|
1647
1674
|
/** The audiences a function's scoped callback tokens are minted for — one per
|
|
1648
1675
|
* feature its declared scopes reach. `control-plane` carries `users:*` /
|
|
1649
|
-
* `usage:read`
|
|
1650
|
-
*
|
|
1651
|
-
|
|
1676
|
+
* `usage:read` / `audit:read` only; `webhooks` carries `webhooks:read` only (read the inbound
|
|
1677
|
+
* sources and received events — e.g. `GET /v1/webhooks/events?after=`). There
|
|
1678
|
+
* is deliberately no `functions` audience: a function cannot call another
|
|
1679
|
+
* function. */
|
|
1680
|
+
export type FunctionCallbackAudience = 'cms' | 'payments' | 'notifications' | 'comments' | 'files' | 'ai' | 'rag' | 'vector-search' | 'activity-feed' | 'orgs' | 'auth' | 'jobs' | 'realtime' | 'rate-limits' | 'control-plane' | 'webhooks';
|
|
1652
1681
|
/** One short-lived scoped token per audience your scopes imply
|
|
1653
1682
|
* (`env.scoped_jwts.cms`, `env.scoped_jwts['control-plane']`); an audience your
|
|
1654
1683
|
* scopes do not reach is absent. Send it as `Authorization: Bearer …` to
|
|
@@ -1710,6 +1739,43 @@ export interface WebhookTriggerPayload<D = Record<string, unknown>> {
|
|
|
1710
1739
|
truncated: true;
|
|
1711
1740
|
} | null;
|
|
1712
1741
|
}
|
|
1742
|
+
/** The verification parameters of an inbound `hmac` source (`webhooks.sources.create`). */
|
|
1743
|
+
export interface WebhookHmacVerify {
|
|
1744
|
+
/** the header carrying the signature (case-insensitive) */
|
|
1745
|
+
header: string;
|
|
1746
|
+
algorithm?: 'sha256' | 'sha1';
|
|
1747
|
+
encoding?: 'hex' | 'base64';
|
|
1748
|
+
/** stripped before comparing (e.g. `sha256=`); required on the request when set */
|
|
1749
|
+
prefix?: string;
|
|
1750
|
+
/** a header carrying the signing timestamp (unix seconds or ISO 8601): the
|
|
1751
|
+
* signed message becomes `<timestamp><timestamp_separator><body>` */
|
|
1752
|
+
timestamp_header?: string;
|
|
1753
|
+
/** default '.'; '' to concatenate */
|
|
1754
|
+
timestamp_separator?: string;
|
|
1755
|
+
/** default 300, 1..3600 */
|
|
1756
|
+
tolerance_seconds?: number;
|
|
1757
|
+
event_id_header?: string;
|
|
1758
|
+
event_type_header?: string;
|
|
1759
|
+
}
|
|
1760
|
+
/** `payload.data` of a `webhook` invocation fired by an inbound source whose
|
|
1761
|
+
* `target_function` is this function (`payload.event === 'inbound_webhook.received'`). */
|
|
1762
|
+
export interface InboundWebhookTriggerData {
|
|
1763
|
+
vxil_event_id: string;
|
|
1764
|
+
source_id: string;
|
|
1765
|
+
provider: string;
|
|
1766
|
+
provider_event_id: string | null;
|
|
1767
|
+
event_type: string | null;
|
|
1768
|
+
sig_verified: boolean;
|
|
1769
|
+
/** the provider's JSON body; null when it was larger than 48 000 bytes
|
|
1770
|
+
* (`payload_omitted: true`) — read it with
|
|
1771
|
+
* `GET /v1/webhooks/events?event_id=<vxil_event_id>` (scope webhooks:read) */
|
|
1772
|
+
payload: Record<string, unknown> | unknown[] | null;
|
|
1773
|
+
payload_omitted?: true;
|
|
1774
|
+
/** true on a `POST /v1/webhooks/sources/:id/test` probe */
|
|
1775
|
+
test?: true;
|
|
1776
|
+
/** true on a `POST /v1/webhooks/events/:id/replay` */
|
|
1777
|
+
replayed?: true;
|
|
1778
|
+
}
|
|
1713
1779
|
/** `POST /v1/fn/:name`: `payload` is the JSON request body (the query
|
|
1714
1780
|
* parameters on a GET). */
|
|
1715
1781
|
export interface HttpFunctionEnvelope<P = unknown> extends FunctionEnvelopeBase {
|
|
@@ -2847,6 +2913,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
2847
2913
|
readonly fn: { [K in keyof S["functions"] & string]: FnInvoker<S["functions"][K]["Input"], S["functions"][K]["Output"]>; };
|
|
2848
2914
|
private call;
|
|
2849
2915
|
readonly users: {
|
|
2916
|
+
/** Create or replace a tenant user by id. Upserting a deleted id brings it
|
|
2917
|
+
* back; upserting an ERASED id re-creates it as a new, empty user
|
|
2918
|
+
* (`erased_at` cleared — the erase already removed the old data). While
|
|
2919
|
+
* the erased user's files are still being erased the call fails with 409
|
|
2920
|
+
* `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
|
|
2850
2921
|
upsert: (user: {
|
|
2851
2922
|
id: string;
|
|
2852
2923
|
email?: string;
|
|
@@ -3215,11 +3286,23 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3215
3286
|
brief?: boolean;
|
|
3216
3287
|
}) => Promise<VxilPlan>;
|
|
3217
3288
|
};
|
|
3289
|
+
/** The project audit log. Needs `audit:read` (the narrow read-only scope —
|
|
3290
|
+
* declare it on a function to read the log from its callback token) or
|
|
3291
|
+
* `features:read`. Server-only: a public / thin-client key cannot read it. */
|
|
3218
3292
|
readonly audit: {
|
|
3293
|
+
/**
|
|
3294
|
+
* The audit trail, newest first. `subject` narrows to the events about ONE
|
|
3295
|
+
* thing: a user id (`payload.user_id` / `payload.id`), a cms record
|
|
3296
|
+
* (`payload.item_id` — the record's history), a verified end user
|
|
3297
|
+
* (`payload.end_user_id` — what that person changed through a thin-client
|
|
3298
|
+
* key or a function acting for them, and their payments events), or a
|
|
3299
|
+
* principal (`actor`). Server keys only.
|
|
3300
|
+
*/
|
|
3219
3301
|
list: (q?: {
|
|
3220
3302
|
since?: string;
|
|
3221
3303
|
cursor?: string;
|
|
3222
3304
|
limit?: number;
|
|
3305
|
+
subject?: string;
|
|
3223
3306
|
}) => Promise<Array<{
|
|
3224
3307
|
id: string;
|
|
3225
3308
|
event: string;
|
|
@@ -3237,6 +3320,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3237
3320
|
until?: string;
|
|
3238
3321
|
after_id?: string;
|
|
3239
3322
|
limit?: number;
|
|
3323
|
+
/** the same subject filter as `list` */
|
|
3324
|
+
subject?: string;
|
|
3240
3325
|
}) => Promise<{
|
|
3241
3326
|
events: Array<{
|
|
3242
3327
|
id: string;
|
|
@@ -3521,7 +3606,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3521
3606
|
state: string;
|
|
3522
3607
|
}>;
|
|
3523
3608
|
/** Clone a terminal run into a fresh queued run. A generation run answers
|
|
3524
|
-
* `409 not_replayable` — submit the generation again instead
|
|
3609
|
+
* `409 not_replayable` — submit the generation again instead; a redacted
|
|
3610
|
+
* or erased run answers `409 run_redacted` (its payload is gone). */
|
|
3525
3611
|
replay: (runId: string) => Promise<{
|
|
3526
3612
|
run_id: string;
|
|
3527
3613
|
replayed_from: string;
|
|
@@ -3544,6 +3630,30 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3544
3630
|
moved: number;
|
|
3545
3631
|
done: boolean;
|
|
3546
3632
|
}>;
|
|
3633
|
+
/** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
|
|
3634
|
+
* that hold personal data: the payload becomes `{ erased: true }`, the
|
|
3635
|
+
* result, progress, callback body and error text are cleared, a
|
|
3636
|
+
* generation's provider request body/headers are dropped and its credit
|
|
3637
|
+
* hold's user id is pseudonymized (unless its settle is still owed). The
|
|
3638
|
+
* row itself stays (state, timings, job_name). The same fields a GDPR
|
|
3639
|
+
* erase clears on the runs it can link to a user — use this for runs
|
|
3640
|
+
* nothing links to one (a plain queue run, an async function call).
|
|
3641
|
+
* `{ run_ids }` (≤500, one call; open runs are left alone and counted in
|
|
3642
|
+
* `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
|
|
3643
|
+
* names that user — ONE page of ≤500 per call, call again until `done`).
|
|
3644
|
+
* Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
|
|
3645
|
+
* call redacted nothing). NOT cleared: concurrency_key, debounce_key,
|
|
3646
|
+
* idempotency_key and target_url — keep user ids out of those (hash them).
|
|
3647
|
+
* A redacted run does not replay. Scope jobs:write. */
|
|
3648
|
+
redact: (input: {
|
|
3649
|
+
run_ids: string[];
|
|
3650
|
+
} | {
|
|
3651
|
+
user_id: string;
|
|
3652
|
+
}) => Promise<{
|
|
3653
|
+
redacted: number;
|
|
3654
|
+
skipped_open: number;
|
|
3655
|
+
done: boolean;
|
|
3656
|
+
}>;
|
|
3547
3657
|
/**
|
|
3548
3658
|
* Suspend the RUNNING run until an event (call from the executing
|
|
3549
3659
|
* handler, then return 200 — the suspension wins). `state: 'resumed'` =
|
|
@@ -3734,8 +3844,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3734
3844
|
/** On success the guest keeps its user id (`user_id` unchanged).
|
|
3735
3845
|
* If the claimed email ALREADY has an account, the guest is MERGED
|
|
3736
3846
|
* into it: `user_id` is the existing account, `merged: true`, and a
|
|
3737
|
-
* fresh `session.token` (same session
|
|
3738
|
-
* identity — swap it client-side
|
|
3847
|
+
* fresh `session.token` (the same session carried over to the merged
|
|
3848
|
+
* identity under a new session id — swap it client-side: the old
|
|
3849
|
+
* guest token is revoked, the refresh token keeps working; other
|
|
3850
|
+
* guest sessions are revoked).
|
|
3739
3851
|
* `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
|
|
3740
3852
|
* files rows were already moved onto `user_id` when this returned, so
|
|
3741
3853
|
* the merged user's next request finds them; false ⇒ the move ran
|
|
@@ -3967,15 +4079,34 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3967
4079
|
verified: true;
|
|
3968
4080
|
}>;
|
|
3969
4081
|
};
|
|
3970
|
-
/** Social sign-in. The web `
|
|
3971
|
-
* (
|
|
3972
|
-
* `GET /v1/auth/oauth/{provider}/start
|
|
3973
|
-
*
|
|
4082
|
+
/** Social sign-in. The web flow: `startUrl` fetches the provider authorize
|
|
4083
|
+
* URL with your key (a browser cannot follow the header-carrying 302 of
|
|
4084
|
+
* `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
|
|
4085
|
+
* there, and hand the returned `code`+`state` to `…/callback`; `native`
|
|
3974
4086
|
* is the mobile / broker token-exchange the SDK wraps. `oidc` is the
|
|
3975
4087
|
* tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
|
|
3976
4088
|
* Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
|
|
3977
4089
|
* speaks OIDC); it rides the same three routes. */
|
|
3978
4090
|
oauth: {
|
|
4091
|
+
/** Start the web sign-in from a browser SPA: answers the provider
|
|
4092
|
+
* `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
|
|
4093
|
+
* nonce bound to the flow — all held server-side) for you to navigate
|
|
4094
|
+
* to: `location.assign((await vx.auth.oauth.startUrl('oidc',
|
|
4095
|
+
* { redirect_uri })).authorize_url)`. The provider returns to
|
|
4096
|
+
* `redirect_uri` with `?code&state`, which your page sends to
|
|
4097
|
+
* `GET /v1/auth/oauth/{provider}/callback` for the session. The same
|
|
4098
|
+
* rules as the redirect form apply: `redirect_uri` must match the auth
|
|
4099
|
+
* config `security.allowedRedirectOrigins` when set (else
|
|
4100
|
+
* `422 redirect_not_allowed`), and the state expires after
|
|
4101
|
+
* `expires_in` seconds (600). `anonymous_token` (a guest bearer)
|
|
4102
|
+
* promotes or merges that guest at the callback. */
|
|
4103
|
+
startUrl: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
|
|
4104
|
+
redirect_uri: string;
|
|
4105
|
+
anonymous_token?: string;
|
|
4106
|
+
}) => Promise<{
|
|
4107
|
+
authorize_url: string;
|
|
4108
|
+
expires_in: number;
|
|
4109
|
+
}>;
|
|
3979
4110
|
/** Native social sign-in: exchange a provider `id_token`/`access_token`
|
|
3980
4111
|
* for a vxil session (`linked` marks whether the user was created or
|
|
3981
4112
|
* matched to an existing identity). */
|
|
@@ -4126,6 +4257,20 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4126
4257
|
* (end-user reads and writes are `403 server_only`, even with an
|
|
4127
4258
|
* owner_field). Server keys are never affected. */
|
|
4128
4259
|
end_user_access?: CmsEndUserAccess;
|
|
4260
|
+
/** Role slugs one of which a VERIFIED end user must hold to WRITE this
|
|
4261
|
+
* collection (create / update / $inc / delete / publish / transaction
|
|
4262
|
+
* step / batch / filtered delete, and an end-user delete's cascade into
|
|
4263
|
+
* it) — otherwise `403 role_required`. Reads are unaffected; server keys
|
|
4264
|
+
* are never affected. Omitted/`[]` = ungated. ≤16 entries, each
|
|
4265
|
+
* `^[a-z0-9][a-z0-9_-]{0,31}$` (the `orgs` role alphabet). */
|
|
4266
|
+
write_roles?: string[];
|
|
4267
|
+
/** Retention (guide ch. 4): live items created more than this many days
|
|
4268
|
+
* ago (1..3650) are soft-deleted by the nightly platform sweep — like a
|
|
4269
|
+
* normal delete (no restore; purged at least 30 days later, unique values freed), with ONE
|
|
4270
|
+
* `cms.collection.retention_swept` audit event per collection per night
|
|
4271
|
+
* instead of per-item delete events. A collection another collection
|
|
4272
|
+
* references with an `on_delete` rule is skipped. Omit/null = keep. */
|
|
4273
|
+
retain_days?: number | null;
|
|
4129
4274
|
fields?: Array<{
|
|
4130
4275
|
field: string;
|
|
4131
4276
|
type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
|
|
@@ -4175,6 +4320,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4175
4320
|
actions?: CmsActionDef[];
|
|
4176
4321
|
/** present when not the default 'readwrite' */
|
|
4177
4322
|
end_user_access?: CmsEndUserAccess;
|
|
4323
|
+
/** present when the collection is role-gated for end-user writes */
|
|
4324
|
+
write_roles?: string[];
|
|
4325
|
+
/** present when retention is set */
|
|
4326
|
+
retain_days?: number;
|
|
4178
4327
|
}>;
|
|
4179
4328
|
list: () => Promise<Array<{
|
|
4180
4329
|
collection: string;
|
|
@@ -4183,6 +4332,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4183
4332
|
owner_field?: string | null;
|
|
4184
4333
|
/** the collection's end-user access mode (absent from an older server = 'readwrite') */
|
|
4185
4334
|
end_user_access?: CmsEndUserAccess;
|
|
4335
|
+
/** the roles an end user needs to write it (null / absent = ungated) */
|
|
4336
|
+
write_roles?: string[] | null;
|
|
4337
|
+
/** retention in days (null = keep until deleted; absent from an older server) */
|
|
4338
|
+
retain_days?: number | null;
|
|
4186
4339
|
}>>;
|
|
4187
4340
|
addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
|
|
4188
4341
|
/** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
|
|
@@ -4225,6 +4378,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4225
4378
|
collection: string;
|
|
4226
4379
|
end_user_access: CmsEndUserAccess;
|
|
4227
4380
|
}>;
|
|
4381
|
+
/** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
|
|
4382
|
+
* ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
|
|
4383
|
+
* session's verified role claims — orgs roles) to write the collection,
|
|
4384
|
+
* otherwise every write door answers `403 role_required`. Reads are
|
|
4385
|
+
* unaffected; server keys are never affected. Audited; takes effect on
|
|
4386
|
+
* the next write. */
|
|
4387
|
+
setWriteRoles: (collection: string, roles: string[] | null) => Promise<{
|
|
4388
|
+
collection: string;
|
|
4389
|
+
write_roles: string[];
|
|
4390
|
+
}>;
|
|
4391
|
+
/** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
|
|
4392
|
+
* ch. 4): the nightly platform sweep soft-deletes live items created more
|
|
4393
|
+
* than `days` ago — bounded per project per night, no restore, purged at
|
|
4394
|
+
* least 30 days later like any delete, one `cms.collection.retention_swept` audit event
|
|
4395
|
+
* per collection per sweep. Audited (`cms.collection.retain_days.set`). */
|
|
4396
|
+
setRetention: (collection: string, days: number | null) => Promise<{
|
|
4397
|
+
collection: string;
|
|
4398
|
+
retain_days: number | null;
|
|
4399
|
+
}>;
|
|
4228
4400
|
/** Re-project the collection's index slots after an `index_slot` move
|
|
4229
4401
|
* (guide ch. 4). Slots are projected on WRITE only, so until this runs,
|
|
4230
4402
|
* stored rows keep their OLD projection: the new slot is NULL and the
|
|
@@ -4276,6 +4448,29 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4276
4448
|
version: number;
|
|
4277
4449
|
data: Record<string, unknown>;
|
|
4278
4450
|
}>;
|
|
4451
|
+
/** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
|
|
4452
|
+
* — when a live item already holds `data[field]` — merges `patch` into
|
|
4453
|
+
* THAT item instead (one transaction; update hooks, guards, version bump
|
|
4454
|
+
* and a `cms.item.updated` audit, exactly like `patch`; null clears a
|
|
4455
|
+
* field). `created` tells which happened (201 vs 200). Concurrent upserts
|
|
4456
|
+
* of one key serialize, so they never create a duplicate. */
|
|
4457
|
+
upsert: (collection: string, input: {
|
|
4458
|
+
data: Record<string, unknown>;
|
|
4459
|
+
onConflict: {
|
|
4460
|
+
field: string;
|
|
4461
|
+
patch: Record<string, unknown>;
|
|
4462
|
+
};
|
|
4463
|
+
status?: "draft" | "published";
|
|
4464
|
+
lock?: string;
|
|
4465
|
+
guard?: CmsGuard;
|
|
4466
|
+
guards?: CmsGuardTerm[];
|
|
4467
|
+
}) => Promise<{
|
|
4468
|
+
item_id: string;
|
|
4469
|
+
status: string;
|
|
4470
|
+
version: number;
|
|
4471
|
+
data: Record<string, unknown>;
|
|
4472
|
+
created: boolean;
|
|
4473
|
+
}>;
|
|
4279
4474
|
/** `expand` inlines relation/file fields into `data` (guide ch. 4): the
|
|
4280
4475
|
* full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
|
|
4281
4476
|
* the bare id on a cycle/depth cut, `null` for an invisible target. */
|
|
@@ -4284,7 +4479,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4284
4479
|
}) => Promise<Record<string, unknown>>;
|
|
4285
4480
|
/**
|
|
4286
4481
|
* The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
|
|
4287
|
-
* $
|
|
4482
|
+
* ($ne is NULL-safe: a row whose field is absent or null counts as not
|
|
4483
|
+
* equal; on a dotted join term the row still needs a readable target,
|
|
4484
|
+
* so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
|
|
4288
4485
|
* fields) $arrayContains/$anyOf (json/relation array containment, indexed);
|
|
4289
4486
|
* range/sort needs slot-indexed fields. This is the
|
|
4290
4487
|
* DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
|
|
@@ -4674,6 +4871,32 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4674
4871
|
};
|
|
4675
4872
|
warnings?: string[];
|
|
4676
4873
|
}>;
|
|
4874
|
+
/**
|
|
4875
|
+
* Log records of ONE function, one per invocation (outcome, wall/cpu ms,
|
|
4876
|
+
* console lines, exceptions), oldest first. Pass the returned `next_since`
|
|
4877
|
+
* back as `since` to read only newer records (a tail); without it, the most
|
|
4878
|
+
* recent records of the last 24 hours. Kept 14 days. Needs
|
|
4879
|
+
* `functions:read`. (GET /v1/functions/:name/logs)
|
|
4880
|
+
*/
|
|
4881
|
+
logs: (name: string, opts?: {
|
|
4882
|
+
since?: string;
|
|
4883
|
+
}) => Promise<{
|
|
4884
|
+
lines: Array<{
|
|
4885
|
+
ts: string;
|
|
4886
|
+
outcome: string;
|
|
4887
|
+
wall_ms: number | null;
|
|
4888
|
+
cpu_ms: number | null;
|
|
4889
|
+
logs: Array<{
|
|
4890
|
+
level: string;
|
|
4891
|
+
message: string;
|
|
4892
|
+
}>;
|
|
4893
|
+
exceptions: Array<{
|
|
4894
|
+
name: string;
|
|
4895
|
+
message: string;
|
|
4896
|
+
}>;
|
|
4897
|
+
}>;
|
|
4898
|
+
next_since: string | null;
|
|
4899
|
+
}>;
|
|
4677
4900
|
};
|
|
4678
4901
|
/** The MCP aggregation surface (the `mcp` feature). */
|
|
4679
4902
|
readonly mcp: {
|
|
@@ -4969,20 +5192,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4969
5192
|
last_error_msg?: string | null;
|
|
4970
5193
|
}>;
|
|
4971
5194
|
sources: {
|
|
4972
|
-
/** Register an inbound source; the receiver URL is returned ONCE.
|
|
5195
|
+
/** Register an inbound source; the receiver URL is returned ONCE.
|
|
5196
|
+
*
|
|
5197
|
+
* Destination: `forward_url` (your endpoint) OR `target_function` (a
|
|
5198
|
+
* deployed function that declares a bare `trigger: { kind: 'webhook' }`
|
|
5199
|
+
* binding — it receives `payload.event === 'inbound_webhook.received'`
|
|
5200
|
+
* with the inbound envelope as `payload.data`), never both; neither =
|
|
5201
|
+
* store only (read with `events.list`).
|
|
5202
|
+
*
|
|
5203
|
+
* `provider: 'hmac'` is the parameterized preset for any provider that
|
|
5204
|
+
* signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
|
|
5205
|
+
* `verify` says which header, sha256|sha1, hex|base64, an optional prefix
|
|
5206
|
+
* and an optional timestamp header + tolerance. Like stripe/paddle/slack it
|
|
5207
|
+
* fails closed (401) until the source's signing secret is set. */
|
|
4973
5208
|
create: (input: {
|
|
4974
|
-
provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic";
|
|
5209
|
+
provider: "stripe" | "paddle" | "github" | "slack" | "revenuecat" | "generic" | "hmac";
|
|
4975
5210
|
name: string;
|
|
4976
5211
|
forward_url?: string;
|
|
5212
|
+
target_function?: string;
|
|
5213
|
+
verify?: WebhookHmacVerify;
|
|
4977
5214
|
}) => Promise<{
|
|
4978
5215
|
source_id: string;
|
|
4979
5216
|
receiver_url_path: string;
|
|
4980
5217
|
provider: string;
|
|
5218
|
+
target_function?: string | null;
|
|
4981
5219
|
}>;
|
|
4982
5220
|
list: () => Promise<Array<{
|
|
4983
5221
|
source_id: string;
|
|
4984
5222
|
provider: string;
|
|
4985
5223
|
name: string;
|
|
5224
|
+
forward_url?: string | null;
|
|
5225
|
+
target_function?: string | null;
|
|
5226
|
+
verify?: WebhookHmacVerify | null;
|
|
4986
5227
|
}>>;
|
|
4987
5228
|
delete: (sourceId: string) => Promise<void>;
|
|
4988
5229
|
/** Send a sample envelope to the source's forward_url through the real
|
|
@@ -4997,20 +5238,38 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4997
5238
|
}>;
|
|
4998
5239
|
};
|
|
4999
5240
|
events: {
|
|
5241
|
+
/** Received events. Newest first, paged with `cursor`; or — with `after`
|
|
5242
|
+
* (your watermark, an event id) — OLDEST first from just after it, the
|
|
5243
|
+
* drain shape: store `next_after` and pass it back, `has_more` says
|
|
5244
|
+
* another page waits. The `after` drain answers only events received
|
|
5245
|
+
* at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
|
|
5246
|
+
* event could otherwise commit below a stored watermark and be
|
|
5247
|
+
* skipped); `cursor` and `event_id` reads are not lagged. `event_id`
|
|
5248
|
+
* reads exactly one event. `cursor` and `after` are exclusive. */
|
|
5000
5249
|
list: (q?: {
|
|
5001
5250
|
source_id?: string;
|
|
5002
5251
|
status?: string;
|
|
5003
5252
|
cursor?: string;
|
|
5004
5253
|
limit?: number;
|
|
5254
|
+
after?: string;
|
|
5255
|
+
event_id?: string;
|
|
5005
5256
|
}) => Promise<{
|
|
5006
5257
|
events: Array<{
|
|
5007
5258
|
event_id: string;
|
|
5259
|
+
source_id: string;
|
|
5260
|
+
provider: string;
|
|
5261
|
+
provider_event_id: string | null;
|
|
5008
5262
|
event_type: string | null;
|
|
5009
5263
|
payload: Record<string, unknown>;
|
|
5010
5264
|
sig_verified: boolean;
|
|
5011
5265
|
status: string;
|
|
5266
|
+
received_at: string;
|
|
5012
5267
|
}>;
|
|
5013
5268
|
next_cursor: string | null;
|
|
5269
|
+
/** `after` pages only */
|
|
5270
|
+
next_after?: string | null;
|
|
5271
|
+
/** `after` pages only */
|
|
5272
|
+
has_more?: boolean;
|
|
5014
5273
|
}>;
|
|
5015
5274
|
replay: (eventId: string) => Promise<void>;
|
|
5016
5275
|
/** The Svix message-attempt view: delivery state/attempts/DLQ flag for
|
|
@@ -5231,8 +5490,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5231
5490
|
* matching its TokenProvider type *structurally* (no import — a static
|
|
5232
5491
|
* import would break the single-file served sdk.mjs) that re-mints via
|
|
5233
5492
|
* POST /v1/realtime/tokens with `defaults` merged over the channel the
|
|
5234
|
-
* client asks for.
|
|
5235
|
-
*
|
|
5493
|
+
* client asks for. Two safe ways to use it:
|
|
5494
|
+
* - on a server, with a server key (`user_id` names the subject); or
|
|
5495
|
+
* - in a browser / mobile app, with a PUBLIC `end_user_required` key and
|
|
5496
|
+
* the signed-in user's session (`endUserToken` on the client): the mint
|
|
5497
|
+
* runs in end-user mode and the token's subject is FORCED to the
|
|
5498
|
+
* verified user (any `user_id` you pass is overridden), so no
|
|
5499
|
+
* backend of your own is needed.
|
|
5500
|
+
* Never ship a server key to a browser. */
|
|
5236
5501
|
tokenProvider: (defaults: {
|
|
5237
5502
|
user_id: string;
|
|
5238
5503
|
ttl_seconds?: number;
|
|
@@ -5808,6 +6073,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5808
6073
|
model?: string;
|
|
5809
6074
|
user_id?: string;
|
|
5810
6075
|
input?: Record<string, unknown>;
|
|
6076
|
+
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6077
|
+
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6078
|
+
min_similarity?: number;
|
|
5811
6079
|
}) => Promise<RagAnswer>;
|
|
5812
6080
|
/** Streamed grounded answer: citations + the channel handle up front, tokens
|
|
5813
6081
|
* over the realtime channel. */
|
|
@@ -5822,13 +6090,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5822
6090
|
model?: string;
|
|
5823
6091
|
user_id?: string;
|
|
5824
6092
|
input?: Record<string, unknown>;
|
|
6093
|
+
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6094
|
+
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6095
|
+
min_similarity?: number;
|
|
5825
6096
|
}) => Promise<RagStreamHandle>;
|
|
5826
6097
|
/** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
|
|
5827
6098
|
* would ground on, with rerank + metadata boosts applied — no generation,
|
|
5828
6099
|
* no token spend. `boosts`/`rerank`/`min_score` override the rag config.
|
|
5829
6100
|
* `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
|
|
5830
|
-
* 0.016–0.033 at the top): a floor above ~0.033 drops every hit.
|
|
5831
|
-
* relevance
|
|
6101
|
+
* 0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
|
|
6102
|
+
* relevance threshold use `min_similarity`, which floors each hit's cosine
|
|
6103
|
+
* `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
|
|
6104
|
+
* with no measured similarity, e.g. keyword mode, is kept). */
|
|
5832
6105
|
search: (input: {
|
|
5833
6106
|
query: string;
|
|
5834
6107
|
collection?: string;
|
|
@@ -5838,6 +6111,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5838
6111
|
rerank?: boolean;
|
|
5839
6112
|
boosts?: Record<string, unknown>;
|
|
5840
6113
|
min_score?: number;
|
|
6114
|
+
min_similarity?: number;
|
|
5841
6115
|
}) => Promise<RagSearchResult>;
|
|
5842
6116
|
/** Ingest into the backing vector-search collection (chunk → embed → index). */
|
|
5843
6117
|
ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
|
|
@@ -5999,7 +6273,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5999
6273
|
* (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
|
|
6000
6274
|
* committed): a linked jobs run that terminally fails auto-refunds the hold,
|
|
6001
6275
|
* a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
|
|
6002
|
-
* available balance can't cover `amount`.
|
|
6276
|
+
* available balance can't cover `amount`. Throws VxilError(409,
|
|
6277
|
+
* 'job_released') when `job_id` names a generation run that already ended
|
|
6278
|
+
* (cancelled or failed) before this hold landed: nothing is held.
|
|
6003
6279
|
*
|
|
6004
6280
|
* Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
|
|
6005
6281
|
* `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
|
|
@@ -6062,6 +6338,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6062
6338
|
created_at: string;
|
|
6063
6339
|
}>;
|
|
6064
6340
|
}>;
|
|
6341
|
+
/** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
|
|
6342
|
+
* reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
|
|
6343
|
+
* `next_cursor` as `cursor` until it is null; start at `since` (inclusive
|
|
6344
|
+
* ISO-8601). To tail later, start a new walk with `since` = the last
|
|
6345
|
+
* `created_at` you stored MINUS an overlap (a minute) and dedupe on
|
|
6346
|
+
* `ledger_entry_id` — `created_at` is the writing transaction's start, so
|
|
6347
|
+
* a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
|
|
6348
|
+
* Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
|
|
6349
|
+
* (`end_user_required`) key gets 403 `server_only` (use `usage` for one
|
|
6350
|
+
* user's own rows). */
|
|
6351
|
+
ledger: (q?: {
|
|
6352
|
+
since?: string;
|
|
6353
|
+
cursor?: string;
|
|
6354
|
+
user_id?: string;
|
|
6355
|
+
credit_type?: string;
|
|
6356
|
+
limit?: number;
|
|
6357
|
+
}) => Promise<{
|
|
6358
|
+
entries: PaymentsLedgerEntry[];
|
|
6359
|
+
next_cursor: string | null;
|
|
6360
|
+
}>;
|
|
6065
6361
|
/** Start a subscription (mock = instant checkout; real providers redirect via
|
|
6066
6362
|
* their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
|
|
6067
6363
|
* ref. Returns the vxil subscription_id + provider sub id + status. */
|
package/dist/index.js
CHANGED
|
@@ -429,6 +429,11 @@ export class Vxil {
|
|
|
429
429
|
return { data: parsed.data, meta: parsed.meta ?? { request_id: '' }, response: res };
|
|
430
430
|
}
|
|
431
431
|
users = {
|
|
432
|
+
/** Create or replace a tenant user by id. Upserting a deleted id brings it
|
|
433
|
+
* back; upserting an ERASED id re-creates it as a new, empty user
|
|
434
|
+
* (`erased_at` cleared — the erase already removed the old data). While
|
|
435
|
+
* the erased user's files are still being erased the call fails with 409
|
|
436
|
+
* `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
|
|
432
437
|
upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
|
|
433
438
|
bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
|
|
434
439
|
get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
|
|
@@ -638,12 +643,24 @@ export class Vxil {
|
|
|
638
643
|
...(opts?.brief === false ? { brief: false } : {}),
|
|
639
644
|
})).data,
|
|
640
645
|
};
|
|
646
|
+
/** The project audit log. Needs `audit:read` (the narrow read-only scope —
|
|
647
|
+
* declare it on a function to read the log from its callback token) or
|
|
648
|
+
* `features:read`. Server-only: a public / thin-client key cannot read it. */
|
|
641
649
|
audit = {
|
|
650
|
+
/**
|
|
651
|
+
* The audit trail, newest first. `subject` narrows to the events about ONE
|
|
652
|
+
* thing: a user id (`payload.user_id` / `payload.id`), a cms record
|
|
653
|
+
* (`payload.item_id` — the record's history), a verified end user
|
|
654
|
+
* (`payload.end_user_id` — what that person changed through a thin-client
|
|
655
|
+
* key or a function acting for them, and their payments events), or a
|
|
656
|
+
* principal (`actor`). Server keys only.
|
|
657
|
+
*/
|
|
642
658
|
list: async (q) => {
|
|
643
659
|
const s = qs({
|
|
644
660
|
since: q?.since || undefined,
|
|
645
661
|
cursor: q?.cursor || undefined,
|
|
646
662
|
limit: q?.limit || undefined,
|
|
663
|
+
subject: q?.subject || undefined,
|
|
647
664
|
});
|
|
648
665
|
return (await this.call('GET', `/v1/audit${s}`)).data.events;
|
|
649
666
|
},
|
|
@@ -657,6 +674,7 @@ export class Vxil {
|
|
|
657
674
|
until: q?.until || undefined,
|
|
658
675
|
after_id: q?.after_id || undefined,
|
|
659
676
|
limit: q?.limit || undefined,
|
|
677
|
+
subject: q?.subject || undefined,
|
|
660
678
|
});
|
|
661
679
|
const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/audit/export${s}`)}`, {
|
|
662
680
|
method: 'GET',
|
|
@@ -864,7 +882,8 @@ export class Vxil {
|
|
|
864
882
|
* terminal run answers `409 not_cancellable`. */
|
|
865
883
|
cancel: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/cancel`)).data,
|
|
866
884
|
/** Clone a terminal run into a fresh queued run. A generation run answers
|
|
867
|
-
* `409 not_replayable` — submit the generation again instead
|
|
885
|
+
* `409 not_replayable` — submit the generation again instead; a redacted
|
|
886
|
+
* or erased run answers `409 run_redacted` (its payload is gone). */
|
|
868
887
|
replay: async (runId) => (await this.call('POST', `/v1/jobs/runs/${encodeURIComponent(runId)}/replay`)).data,
|
|
869
888
|
/** SERVER-ONLY (403 server_only in end-user mode). Account merge: move the
|
|
870
889
|
* credit-hold owner (`reserve_credits.user_id`) of every run of
|
|
@@ -878,6 +897,22 @@ export class Vxil {
|
|
|
878
897
|
* files re-key it does not check that `into_user_id` exists.
|
|
879
898
|
* Scope jobs:write. */
|
|
880
899
|
reKey: async (input) => (await this.call('POST', '/v1/jobs/runs/re-key', input)).data,
|
|
900
|
+
/** SERVER-ONLY (403 server_only in end-user mode). Redact FINISHED runs
|
|
901
|
+
* that hold personal data: the payload becomes `{ erased: true }`, the
|
|
902
|
+
* result, progress, callback body and error text are cleared, a
|
|
903
|
+
* generation's provider request body/headers are dropped and its credit
|
|
904
|
+
* hold's user id is pseudonymized (unless its settle is still owed). The
|
|
905
|
+
* row itself stays (state, timings, job_name). The same fields a GDPR
|
|
906
|
+
* erase clears on the runs it can link to a user — use this for runs
|
|
907
|
+
* nothing links to one (a plain queue run, an async function call).
|
|
908
|
+
* `{ run_ids }` (≤500, one call; open runs are left alone and counted in
|
|
909
|
+
* `skipped_open`) or `{ user_id }` (the generation runs whose credit hold
|
|
910
|
+
* names that user — ONE page of ≤500 per call, call again until `done`).
|
|
911
|
+
* Idempotent. Audited as `jobs.runs.redacted` (counts only; none when a
|
|
912
|
+
* call redacted nothing). NOT cleared: concurrency_key, debounce_key,
|
|
913
|
+
* idempotency_key and target_url — keep user ids out of those (hash them).
|
|
914
|
+
* A redacted run does not replay. Scope jobs:write. */
|
|
915
|
+
redact: async (input) => (await this.call('POST', '/v1/jobs/runs/redact', input)).data,
|
|
881
916
|
/**
|
|
882
917
|
* Suspend the RUNNING run until an event (call from the executing
|
|
883
918
|
* handler, then return 200 — the suspension wins). `state: 'resumed'` =
|
|
@@ -995,8 +1030,10 @@ export class Vxil {
|
|
|
995
1030
|
/** On success the guest keeps its user id (`user_id` unchanged).
|
|
996
1031
|
* If the claimed email ALREADY has an account, the guest is MERGED
|
|
997
1032
|
* into it: `user_id` is the existing account, `merged: true`, and a
|
|
998
|
-
* fresh `session.token` (same session
|
|
999
|
-
* identity — swap it client-side
|
|
1033
|
+
* fresh `session.token` (the same session carried over to the merged
|
|
1034
|
+
* identity under a new session id — swap it client-side: the old
|
|
1035
|
+
* guest token is revoked, the refresh token keeps working; other
|
|
1036
|
+
* guest sessions are revoked).
|
|
1000
1037
|
* `rekeyed` (present on a merge): true ⇒ the guest's payments / cms /
|
|
1001
1038
|
* files rows were already moved onto `user_id` when this returned, so
|
|
1002
1039
|
* the merged user's next request finds them; false ⇒ the move ran
|
|
@@ -1182,15 +1219,33 @@ export class Vxil {
|
|
|
1182
1219
|
},
|
|
1183
1220
|
confirm: async (token) => (await this.call('POST', '/v1/auth/email/verify/confirm', { token })).data,
|
|
1184
1221
|
},
|
|
1185
|
-
/** Social sign-in. The web `
|
|
1186
|
-
* (
|
|
1187
|
-
* `GET /v1/auth/oauth/{provider}/start
|
|
1188
|
-
*
|
|
1222
|
+
/** Social sign-in. The web flow: `startUrl` fetches the provider authorize
|
|
1223
|
+
* URL with your key (a browser cannot follow the header-carrying 302 of
|
|
1224
|
+
* `GET /v1/auth/oauth/{provider}/start` itself), you navigate the browser
|
|
1225
|
+
* there, and hand the returned `code`+`state` to `…/callback`; `native`
|
|
1189
1226
|
* is the mobile / broker token-exchange the SDK wraps. `oidc` is the
|
|
1190
1227
|
* tenant's generic OIDC / SSO issuer (auth config `providers.oidc` —
|
|
1191
1228
|
* Okta / Entra / Auth0 / any OpenID Connect IdP, or a SAML broker that
|
|
1192
1229
|
* speaks OIDC); it rides the same three routes. */
|
|
1193
1230
|
oauth: {
|
|
1231
|
+
/** Start the web sign-in from a browser SPA: answers the provider
|
|
1232
|
+
* `authorize_url` (PKCE challenge, one-shot `state`, and for `oidc` a
|
|
1233
|
+
* nonce bound to the flow — all held server-side) for you to navigate
|
|
1234
|
+
* to: `location.assign((await vx.auth.oauth.startUrl('oidc',
|
|
1235
|
+
* { redirect_uri })).authorize_url)`. The provider returns to
|
|
1236
|
+
* `redirect_uri` with `?code&state`, which your page sends to
|
|
1237
|
+
* `GET /v1/auth/oauth/{provider}/callback` for the session. The same
|
|
1238
|
+
* rules as the redirect form apply: `redirect_uri` must match the auth
|
|
1239
|
+
* config `security.allowedRedirectOrigins` when set (else
|
|
1240
|
+
* `422 redirect_not_allowed`), and the state expires after
|
|
1241
|
+
* `expires_in` seconds (600). `anonymous_token` (a guest bearer)
|
|
1242
|
+
* promotes or merges that guest at the callback. */
|
|
1243
|
+
startUrl: async (provider, input) => {
|
|
1244
|
+
// plain encodeURIComponent (no URLSearchParams — React Native ≤ 0.79)
|
|
1245
|
+
const q = `redirect_uri=${encodeURIComponent(input.redirect_uri)}`
|
|
1246
|
+
+ (input.anonymous_token ? `&anonymous_token=${encodeURIComponent(input.anonymous_token)}` : '');
|
|
1247
|
+
return (await this.call('GET', `/v1/auth/oauth/${encodeURIComponent(provider)}/start?${q}`, undefined, { accept: 'application/json' })).data;
|
|
1248
|
+
},
|
|
1194
1249
|
/** Native social sign-in: exchange a provider `id_token`/`access_token`
|
|
1195
1250
|
* for a vxil session (`linked` marks whether the user was created or
|
|
1196
1251
|
* matched to an existing identity). */
|
|
@@ -1201,6 +1256,9 @@ export class Vxil {
|
|
|
1201
1256
|
* (`linked: 'merged'`, `user_id` = that account, `rekeyed` says whether
|
|
1202
1257
|
* the guest's owner-scoped rows already moved — see
|
|
1203
1258
|
* `anonymous.link.verify`). */
|
|
1259
|
+
/** `nonce`: the value your app put on the IdP authorize request. For
|
|
1260
|
+
* When sent, the id_token's `nonce` claim must equal it (401
|
|
1261
|
+
* `oauth_token_invalid` otherwise); omitted, it is not checked. */
|
|
1204
1262
|
input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, input)).data,
|
|
1205
1263
|
},
|
|
1206
1264
|
};
|
|
@@ -1311,6 +1369,19 @@ export class Vxil {
|
|
|
1311
1369
|
* (default) restores today's behaviour. Server keys are never affected.
|
|
1312
1370
|
* Audited; takes effect on the next request. */
|
|
1313
1371
|
setEndUserAccess: async (collection, access) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { end_user_access: access })).data,
|
|
1372
|
+
/** Set (or clear, with `[]` / `null`) the collection's END-USER WRITE
|
|
1373
|
+
* ROLES (guide ch. 9): a verified end user must hold one of `roles` (the
|
|
1374
|
+
* session's verified role claims — orgs roles) to write the collection,
|
|
1375
|
+
* otherwise every write door answers `403 role_required`. Reads are
|
|
1376
|
+
* unaffected; server keys are never affected. Audited; takes effect on
|
|
1377
|
+
* the next write. */
|
|
1378
|
+
setWriteRoles: async (collection, roles) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { write_roles: roles ?? [] })).data,
|
|
1379
|
+
/** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
|
|
1380
|
+
* ch. 4): the nightly platform sweep soft-deletes live items created more
|
|
1381
|
+
* than `days` ago — bounded per project per night, no restore, purged at
|
|
1382
|
+
* least 30 days later like any delete, one `cms.collection.retention_swept` audit event
|
|
1383
|
+
* per collection per sweep. Audited (`cms.collection.retain_days.set`). */
|
|
1384
|
+
setRetention: async (collection, days) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { retain_days: days })).data,
|
|
1314
1385
|
/** Re-project the collection's index slots after an `index_slot` move
|
|
1315
1386
|
* (guide ch. 4). Slots are projected on WRITE only, so until this runs,
|
|
1316
1387
|
* stored rows keep their OLD projection: the new slot is NULL and the
|
|
@@ -1379,6 +1450,16 @@ export class Vxil {
|
|
|
1379
1450
|
/** `lock` serializes same-key writers (a per-key lock); `guard`
|
|
1380
1451
|
* is the declarative capacity/overlap invariant (requires lock) — guide ch. 4. */
|
|
1381
1452
|
create: async (collection, input) => (await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input)).data,
|
|
1453
|
+
/** Upsert by a declared `unique` field (guide ch. 4): creates the item, or
|
|
1454
|
+
* — when a live item already holds `data[field]` — merges `patch` into
|
|
1455
|
+
* THAT item instead (one transaction; update hooks, guards, version bump
|
|
1456
|
+
* and a `cms.item.updated` audit, exactly like `patch`; null clears a
|
|
1457
|
+
* field). `created` tells which happened (201 vs 200). Concurrent upserts
|
|
1458
|
+
* of one key serialize, so they never create a duplicate. */
|
|
1459
|
+
upsert: async (collection, input) => {
|
|
1460
|
+
const r = await this.call('POST', `/v1/cms/items/${encodeURIComponent(collection)}`, input);
|
|
1461
|
+
return { ...r.data, created: r.response.status === 201 };
|
|
1462
|
+
},
|
|
1382
1463
|
/** `expand` inlines relation/file fields into `data` (guide ch. 4): the
|
|
1383
1464
|
* full item envelope, a `{ object_id, $ref: 'files' }` stub for a file,
|
|
1384
1465
|
* the bare id on a cycle/depth cut, `null` for an invisible target. */
|
|
@@ -1388,7 +1469,9 @@ export class Vxil {
|
|
|
1388
1469
|
},
|
|
1389
1470
|
/**
|
|
1390
1471
|
* The bounded query DSL. filter ops: $eq $ne $gt $gte $lt $lte $in
|
|
1391
|
-
* $
|
|
1472
|
+
* ($ne is NULL-safe: a row whose field is absent or null counts as not
|
|
1473
|
+
* equal; on a dotted join term the row still needs a readable target,
|
|
1474
|
+
* so a null or dangling relation is excluded) $contains $startsWith (LIKE-escaped; substring-searchable on s*-slotted
|
|
1392
1475
|
* fields) $arrayContains/$anyOf (json/relation array containment, indexed);
|
|
1393
1476
|
* range/sort needs slot-indexed fields. This is the
|
|
1394
1477
|
* DELIBERATELY-UNTYPED escape hatch: it accepts everything the server
|
|
@@ -1619,6 +1702,17 @@ export class Vxil {
|
|
|
1619
1702
|
* `features:write`. (DELETE /v1/functions/:name)
|
|
1620
1703
|
*/
|
|
1621
1704
|
delete: async (name, opts) => (await this.call('DELETE', `/v1/functions/${encodeURIComponent(name)}`, undefined, opts?.ifMatch !== undefined ? { 'if-match': String(opts.ifMatch) } : {})).data,
|
|
1705
|
+
/**
|
|
1706
|
+
* Log records of ONE function, one per invocation (outcome, wall/cpu ms,
|
|
1707
|
+
* console lines, exceptions), oldest first. Pass the returned `next_since`
|
|
1708
|
+
* back as `since` to read only newer records (a tail); without it, the most
|
|
1709
|
+
* recent records of the last 24 hours. Kept 14 days. Needs
|
|
1710
|
+
* `functions:read`. (GET /v1/functions/:name/logs)
|
|
1711
|
+
*/
|
|
1712
|
+
logs: async (name, opts) => {
|
|
1713
|
+
const s = qs({ since: opts?.since || undefined });
|
|
1714
|
+
return (await this.call('GET', `/v1/functions/${encodeURIComponent(name)}/logs${s}`)).data;
|
|
1715
|
+
},
|
|
1622
1716
|
};
|
|
1623
1717
|
/** The MCP aggregation surface (the `mcp` feature). */
|
|
1624
1718
|
mcp = {
|
|
@@ -1757,7 +1851,19 @@ export class Vxil {
|
|
|
1757
1851
|
*/
|
|
1758
1852
|
test: async (subId) => (await this.call('POST', `/v1/webhooks/subscriptions/${encodeURIComponent(subId)}/test`)).data,
|
|
1759
1853
|
sources: {
|
|
1760
|
-
/** Register an inbound source; the receiver URL is returned ONCE.
|
|
1854
|
+
/** Register an inbound source; the receiver URL is returned ONCE.
|
|
1855
|
+
*
|
|
1856
|
+
* Destination: `forward_url` (your endpoint) OR `target_function` (a
|
|
1857
|
+
* deployed function that declares a bare `trigger: { kind: 'webhook' }`
|
|
1858
|
+
* binding — it receives `payload.event === 'inbound_webhook.received'`
|
|
1859
|
+
* with the inbound envelope as `payload.data`), never both; neither =
|
|
1860
|
+
* store only (read with `events.list`).
|
|
1861
|
+
*
|
|
1862
|
+
* `provider: 'hmac'` is the parameterized preset for any provider that
|
|
1863
|
+
* signs an HMAC of the raw body (Shopify, Intercom, Linear, Zendesk, …):
|
|
1864
|
+
* `verify` says which header, sha256|sha1, hex|base64, an optional prefix
|
|
1865
|
+
* and an optional timestamp header + tolerance. Like stripe/paddle/slack it
|
|
1866
|
+
* fails closed (401) until the source's signing secret is set. */
|
|
1761
1867
|
create: async (input) => (await this.call('POST', '/v1/webhooks/sources', input)).data,
|
|
1762
1868
|
list: async () => (await this.call('GET', '/v1/webhooks/sources')).data.sources,
|
|
1763
1869
|
delete: async (sourceId) => {
|
|
@@ -1768,11 +1874,21 @@ export class Vxil {
|
|
|
1768
1874
|
test: async (sourceId) => (await this.call('POST', `/v1/webhooks/sources/${encodeURIComponent(sourceId)}/test`)).data,
|
|
1769
1875
|
},
|
|
1770
1876
|
events: {
|
|
1877
|
+
/** Received events. Newest first, paged with `cursor`; or — with `after`
|
|
1878
|
+
* (your watermark, an event id) — OLDEST first from just after it, the
|
|
1879
|
+
* drain shape: store `next_after` and pass it back, `has_more` says
|
|
1880
|
+
* another page waits. The `after` drain answers only events received
|
|
1881
|
+
* at least 10 s ago (ids are not strictly arrival-ordered, so a fresher
|
|
1882
|
+
* event could otherwise commit below a stored watermark and be
|
|
1883
|
+
* skipped); `cursor` and `event_id` reads are not lagged. `event_id`
|
|
1884
|
+
* reads exactly one event. `cursor` and `after` are exclusive. */
|
|
1771
1885
|
list: async (q) => {
|
|
1772
1886
|
const s = qs({
|
|
1773
1887
|
source_id: q?.source_id || undefined,
|
|
1774
1888
|
status: q?.status || undefined,
|
|
1775
1889
|
cursor: q?.cursor || undefined,
|
|
1890
|
+
after: q?.after || undefined,
|
|
1891
|
+
event_id: q?.event_id || undefined,
|
|
1776
1892
|
limit: q?.limit || undefined,
|
|
1777
1893
|
});
|
|
1778
1894
|
return (await this.call('GET', `/v1/webhooks/events${s}`)).data;
|
|
@@ -1875,8 +1991,14 @@ export class Vxil {
|
|
|
1875
1991
|
* matching its TokenProvider type *structurally* (no import — a static
|
|
1876
1992
|
* import would break the single-file served sdk.mjs) that re-mints via
|
|
1877
1993
|
* POST /v1/realtime/tokens with `defaults` merged over the channel the
|
|
1878
|
-
* client asks for.
|
|
1879
|
-
*
|
|
1994
|
+
* client asks for. Two safe ways to use it:
|
|
1995
|
+
* - on a server, with a server key (`user_id` names the subject); or
|
|
1996
|
+
* - in a browser / mobile app, with a PUBLIC `end_user_required` key and
|
|
1997
|
+
* the signed-in user's session (`endUserToken` on the client): the mint
|
|
1998
|
+
* runs in end-user mode and the token's subject is FORCED to the
|
|
1999
|
+
* verified user (any `user_id` you pass is overridden), so no
|
|
2000
|
+
* backend of your own is needed.
|
|
2001
|
+
* Never ship a server key to a browser. */
|
|
1880
2002
|
tokenProvider: (defaults) => (ctx) => this.realtime.mintToken({ channel: ctx.channel, ...defaults }),
|
|
1881
2003
|
/** One-shot: mint a token AND open the WebSocket. Uses the global
|
|
1882
2004
|
* `WebSocket` (browser / Node ≥22). On older Node, pass a constructor —
|
|
@@ -2170,8 +2292,10 @@ export class Vxil {
|
|
|
2170
2292
|
* would ground on, with rerank + metadata boosts applied — no generation,
|
|
2171
2293
|
* no token spend. `boosts`/`rerank`/`min_score` override the rag config.
|
|
2172
2294
|
* `min_score` floors the EFFECTIVE `score`, which is a RANK value (about
|
|
2173
|
-
* 0.016–0.033 at the top): a floor above ~0.033 drops every hit.
|
|
2174
|
-
* relevance
|
|
2295
|
+
* 0.016–0.033 at the top): a floor above ~0.033 drops every hit. For a
|
|
2296
|
+
* relevance threshold use `min_similarity`, which floors each hit's cosine
|
|
2297
|
+
* `similarity` (-1..1; overrides config `retrieval.minSimilarity`; a hit
|
|
2298
|
+
* with no measured similarity, e.g. keyword mode, is kept). */
|
|
2175
2299
|
search: async (input) => (await this.call('POST', '/v1/rag/search', input)).data,
|
|
2176
2300
|
/** Ingest into the backing vector-search collection (chunk → embed → index). */
|
|
2177
2301
|
ingest: async (collection, input) => (await this.call('POST', `/v1/rag/ingest/${encodeURIComponent(collection)}`, input)).data,
|
|
@@ -2309,7 +2433,9 @@ export class Vxil {
|
|
|
2309
2433
|
* (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
|
|
2310
2434
|
* committed): a linked jobs run that terminally fails auto-refunds the hold,
|
|
2311
2435
|
* a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
|
|
2312
|
-
* available balance can't cover `amount`.
|
|
2436
|
+
* available balance can't cover `amount`. Throws VxilError(409,
|
|
2437
|
+
* 'job_released') when `job_id` names a generation run that already ended
|
|
2438
|
+
* (cancelled or failed) before this hold landed: nothing is held.
|
|
2313
2439
|
*
|
|
2314
2440
|
* Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
|
|
2315
2441
|
* `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
|
|
@@ -2334,6 +2460,26 @@ export class Vxil {
|
|
|
2334
2460
|
});
|
|
2335
2461
|
return (await this.call('GET', `/v1/payments/usage${s}`)).data;
|
|
2336
2462
|
},
|
|
2463
|
+
/** (2026-10-05) The credit ledger ACROSS users, OLDEST first — for
|
|
2464
|
+
* reconciliation or a warehouse sync. Keyset-paged: pass the prior page's
|
|
2465
|
+
* `next_cursor` as `cursor` until it is null; start at `since` (inclusive
|
|
2466
|
+
* ISO-8601). To tail later, start a new walk with `since` = the last
|
|
2467
|
+
* `created_at` you stored MINUS an overlap (a minute) and dedupe on
|
|
2468
|
+
* `ledger_entry_id` — `created_at` is the writing transaction's start, so
|
|
2469
|
+
* a slow transaction can commit a row behind one already listed. `limit` 1..500 (default 100).
|
|
2470
|
+
* Needs payments:read. SERVER-SIDE KEYS ONLY — a thin-client
|
|
2471
|
+
* (`end_user_required`) key gets 403 `server_only` (use `usage` for one
|
|
2472
|
+
* user's own rows). */
|
|
2473
|
+
ledger: async (q) => {
|
|
2474
|
+
const suffix = qs({
|
|
2475
|
+
since: q?.since || undefined,
|
|
2476
|
+
cursor: q?.cursor || undefined,
|
|
2477
|
+
user_id: q?.user_id || undefined,
|
|
2478
|
+
credit_type: q?.credit_type || undefined,
|
|
2479
|
+
limit: q?.limit || undefined,
|
|
2480
|
+
});
|
|
2481
|
+
return (await this.call('GET', `/v1/payments/credits/ledger${suffix}`)).data;
|
|
2482
|
+
},
|
|
2337
2483
|
/** Start a subscription (mock = instant checkout; real providers redirect via
|
|
2338
2484
|
* their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
|
|
2339
2485
|
* ref. Returns the vxil subscription_id + provider sub id + status. */
|
package/package.json
CHANGED