@vxil/sdk 0.24.1 → 0.26.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 +393 -42
- package/dist/index.js +299 -32
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -91,6 +91,19 @@ export interface VxilOptions {
|
|
|
91
91
|
* See https://vxil.com/docs/guide/09-security-and-multitenancy. For a per-call override on
|
|
92
92
|
* an otherwise server-mode client, use `vx.asEndUser(token)`. */
|
|
93
93
|
endUserToken?: string;
|
|
94
|
+
/** The signed-in user's whole session PAIR (token + refresh_token), instead
|
|
95
|
+
* of `endUserToken`. End-user mode as with `endUserToken`, plus the client
|
|
96
|
+
* can then rotate the pair itself: on `401 session_stale` (auth
|
|
97
|
+
* `orgClaims.activeOrg`: the user's org membership or role changed) it
|
|
98
|
+
* forces ONE refresh and retries the request once, and
|
|
99
|
+
* `vx.auth.sessions.switchOrg(orgId)` needs no pair argument. Every
|
|
100
|
+
* rotation it makes is handed to `onSessionChange` — store it there (the
|
|
101
|
+
* old refresh token is revoked). Wins over `endUserToken` when both are set. */
|
|
102
|
+
endUserSession?: AuthSession;
|
|
103
|
+
/** Called after the client replaced its `endUserSession` pair (a forced
|
|
104
|
+
* refresh on `session_stale`, or `switchOrg`). Persist `session` (cookie,
|
|
105
|
+
* secure storage); `info` says why and which org the new token acts in. */
|
|
106
|
+
onSessionChange?: (session: AuthSession, info: SessionChangeInfo) => void | Promise<void>;
|
|
94
107
|
/** Global API major every request pins (default `'v1'`). Path-major, per
|
|
95
108
|
* the versioning section of https://vxil.com/docs/guide/12-going-to-production — a breaking change ships as a new major on a
|
|
96
109
|
* new path, never in place. */
|
|
@@ -759,6 +772,30 @@ export interface AuthSession {
|
|
|
759
772
|
refresh_token: string;
|
|
760
773
|
expires_at: string;
|
|
761
774
|
}
|
|
775
|
+
/** The workspace a session token acts in (`vx.auth.session.org`): the
|
|
776
|
+
* session JWT's `org` claim, read without verification. */
|
|
777
|
+
export interface SessionOrg {
|
|
778
|
+
id: string;
|
|
779
|
+
role: string;
|
|
780
|
+
perms: string[];
|
|
781
|
+
}
|
|
782
|
+
/** Why the client replaced its end-user session pair (`onSessionChange`). */
|
|
783
|
+
export interface SessionChangeInfo {
|
|
784
|
+
/** `session_stale`: the edge said the org claims went stale (a membership or
|
|
785
|
+
* role change) and the client force-refreshed once. `switch_org`: the app
|
|
786
|
+
* called `vx.auth.sessions.switchOrg`. */
|
|
787
|
+
reason: 'session_stale' | 'switch_org';
|
|
788
|
+
/** The org the new token acts in (auth `orgClaims.activeOrg`); null = none —
|
|
789
|
+
* the user left the stored org, so the app picks again. Undefined when the
|
|
790
|
+
* answer did not say (the pair came from a rotation another call made). */
|
|
791
|
+
org?: {
|
|
792
|
+
id: string;
|
|
793
|
+
role: string;
|
|
794
|
+
} | null;
|
|
795
|
+
/** true: orgs could not be reached, so `org` is null for THIS token only.
|
|
796
|
+
* Not a removal — keep the current workspace and refresh again later. */
|
|
797
|
+
org_unavailable?: true;
|
|
798
|
+
}
|
|
762
799
|
export interface RateLimitPolicy {
|
|
763
800
|
policy_id: string;
|
|
764
801
|
name: string;
|
|
@@ -1036,6 +1073,10 @@ export interface FileObject {
|
|
|
1036
1073
|
/** When the object expires (null = never). An expired object is no longer
|
|
1037
1074
|
* listed and answers 404, even before the sweep deletes it. */
|
|
1038
1075
|
expires_at?: string | null;
|
|
1076
|
+
/** The owning workspace (orgs `org_id`) — present only on a workspace object. */
|
|
1077
|
+
org_id?: string;
|
|
1078
|
+
/** The uploader; null for a workspace object whose uploader was erased. */
|
|
1079
|
+
end_user_id?: string | null;
|
|
1039
1080
|
}
|
|
1040
1081
|
/** `files.createUploadUrl` answer. */
|
|
1041
1082
|
export interface FileUploadUrl {
|
|
@@ -1050,6 +1091,8 @@ export interface FileUploadUrl {
|
|
|
1050
1091
|
* signed into the URL: `content-type`, plus `x-amz-checksum-sha256` when
|
|
1051
1092
|
* the request declared `checksum_sha256`. */
|
|
1052
1093
|
upload_headers?: Record<string, string>;
|
|
1094
|
+
/** The owning workspace — present only for a workspace upload (`org: true` / `org_id`). */
|
|
1095
|
+
org_id?: string;
|
|
1053
1096
|
}
|
|
1054
1097
|
/** `files.usage` answer. */
|
|
1055
1098
|
export interface FilesUsage {
|
|
@@ -1137,6 +1180,13 @@ export interface SearchCollection {
|
|
|
1137
1180
|
collection: string;
|
|
1138
1181
|
dimensions: number;
|
|
1139
1182
|
backend: string;
|
|
1183
|
+
/** The keyword lane's normaliser ('none' = exact lexemes). */
|
|
1184
|
+
keyword_normalize?: 'arabic' | 'none';
|
|
1185
|
+
/** true when this call turned the fold ON for an existing collection:
|
|
1186
|
+
* re-ingest its documents (or reset its cms sync) so old chunks fold too. */
|
|
1187
|
+
keyword_reindex_required?: boolean;
|
|
1188
|
+
/** present (true) on a workspace-scoped collection (`org_scoped: true` at create) */
|
|
1189
|
+
org_scoped?: true;
|
|
1140
1190
|
}
|
|
1141
1191
|
/** A document row in a collection listing (GET …/documents). */
|
|
1142
1192
|
export interface SearchDocument {
|
|
@@ -1147,11 +1197,16 @@ export interface SearchDocument {
|
|
|
1147
1197
|
chunks: number;
|
|
1148
1198
|
metadata: Record<string, unknown>;
|
|
1149
1199
|
created_at: string;
|
|
1200
|
+
/** the document's workspace — present only in an orgScoped collection */
|
|
1201
|
+
org_id?: string;
|
|
1150
1202
|
}
|
|
1151
1203
|
/** One ingest input: chunk text OR bring-your-own precomputed vectors. */
|
|
1152
1204
|
export interface SearchIngestInput {
|
|
1153
1205
|
doc_id: string;
|
|
1154
1206
|
user_id?: string;
|
|
1207
|
+
/** orgScoped collections: the document's workspace. REQUIRED with a server
|
|
1208
|
+
* key; an end-user session always writes into its active workspace. */
|
|
1209
|
+
org_id?: string;
|
|
1155
1210
|
source_file?: string;
|
|
1156
1211
|
/** vxil chunks + embeds this. Omit when supplying `chunks`/`vector`. */
|
|
1157
1212
|
text?: string;
|
|
@@ -1194,6 +1249,17 @@ export interface SearchHit {
|
|
|
1194
1249
|
rerank_score?: number;
|
|
1195
1250
|
metadata: Record<string, unknown>;
|
|
1196
1251
|
}
|
|
1252
|
+
/** A vector-search / rag metadata filter (guide ch. 6, vector-search): each
|
|
1253
|
+
* key is a top-level metadata key; `{ key: value }` is exact scalar equality
|
|
1254
|
+
* (a key whose metadata value is an array never matches — store one flag per
|
|
1255
|
+
* value instead, e.g. `aud_public: true`) and
|
|
1256
|
+
* `{ key: { $in: [...] } }` matches any of 1–50 values (at most 4 `$in` keys).
|
|
1257
|
+
* Keys AND together. Any other value — null, an array, another operator — is
|
|
1258
|
+
* refused with 422, never ignored. */
|
|
1259
|
+
export type SearchFilterValue = string | number | boolean;
|
|
1260
|
+
export type SearchFilter = Record<string, SearchFilterValue | {
|
|
1261
|
+
$in: SearchFilterValue[];
|
|
1262
|
+
}>;
|
|
1197
1263
|
/** A query result set (POST …/query). */
|
|
1198
1264
|
export interface SearchQueryResult {
|
|
1199
1265
|
results: SearchHit[];
|
|
@@ -1480,6 +1546,29 @@ export type PaymentsCreditTypeChoice = {
|
|
|
1480
1546
|
credit_types: string[];
|
|
1481
1547
|
credit_type?: never;
|
|
1482
1548
|
};
|
|
1549
|
+
/** WORKSPACE BILLING (2026-10-12): who a payments READ is about. A string is
|
|
1550
|
+
* a user id (unchanged). `{ org_id }` (server key) is the workspace subject
|
|
1551
|
+
* `org:<org_id>` — a subscription / purchase whose provider checkout carried
|
|
1552
|
+
* `vxil_org_id` folds there. `{ subject: 'org' }` (thin-client key) is the
|
|
1553
|
+
* signed-in user's ACTIVE workspace (`auth.orgClaims.activeOrg`; any member
|
|
1554
|
+
* reads it) — 403 `org_required` without one, and a thin client can never
|
|
1555
|
+
* name another workspace (403 `other_org`). */
|
|
1556
|
+
export type PaymentsSubject = string | {
|
|
1557
|
+
user_id: string;
|
|
1558
|
+
} | {
|
|
1559
|
+
org_id: string;
|
|
1560
|
+
} | {
|
|
1561
|
+
subject: 'org';
|
|
1562
|
+
};
|
|
1563
|
+
/** WORKSPACE BILLING: a server-only payments body names its subject by
|
|
1564
|
+
* `user_id` OR `org_id` (the workspace subject `org:<org_id>`), never both. */
|
|
1565
|
+
export type PaymentsSubjectBody = {
|
|
1566
|
+
user_id: string;
|
|
1567
|
+
org_id?: never;
|
|
1568
|
+
} | {
|
|
1569
|
+
org_id: string;
|
|
1570
|
+
user_id?: never;
|
|
1571
|
+
};
|
|
1483
1572
|
/** `POST /v1/payments/credits/consume` → `data`. */
|
|
1484
1573
|
export interface PaymentsConsumeResult {
|
|
1485
1574
|
balance_after: number;
|
|
@@ -1596,6 +1685,16 @@ export interface PaymentsSubscriptionStatusEventPayload {
|
|
|
1596
1685
|
/** the subscription row's `reference` (a provider subscription carries the
|
|
1597
1686
|
* checkout's; null on manual grants and passes) */
|
|
1598
1687
|
reference: string | null;
|
|
1688
|
+
/** what THIS delivery charged, in minor units — set by a RevenueCat
|
|
1689
|
+
* INITIAL_PURCHASE / RENEWAL that reports a price (the buyer's
|
|
1690
|
+
* own currency when RevenueCat sends it, else USD); null otherwise,
|
|
1691
|
+
* including a PRODUCT_CHANGE (not a charge — its revenue rides the renewal). */
|
|
1692
|
+
amount_cents: number | null;
|
|
1693
|
+
/** lower-case ISO 4217 code of `amount_cents`; null when it is null */
|
|
1694
|
+
currency: string | null;
|
|
1695
|
+
/** the store transaction id of that purchase / renewal (RevenueCat
|
|
1696
|
+
* `transaction_id`) — a stable dedup id for ad-platform conversions */
|
|
1697
|
+
transaction_id: string | null;
|
|
1599
1698
|
environment: PaymentsEventEnvironment;
|
|
1600
1699
|
/** what wrote it: the provider event type, `subscription.synced` /
|
|
1601
1700
|
* `subscription.restored`, `period_end_enforced`, or `test_clock` (a
|
|
@@ -1836,6 +1935,14 @@ export interface FunctionEndUser {
|
|
|
1836
1935
|
sid: string;
|
|
1837
1936
|
/** the step-up epoch, when the session has one */
|
|
1838
1937
|
elv?: number;
|
|
1938
|
+
/** `true` for a guest (anonymous sign-in) session, `false` for a registered
|
|
1939
|
+
* user. Sent since 2026-10-12 on every path that reaches a function as an
|
|
1940
|
+
* end user (direct call, cms action, copilot tool, function → function).
|
|
1941
|
+
* Caveat: a guest session refreshed BEFORE 2026-10-12 lost the claim and
|
|
1942
|
+
* reads `false` until its next refresh. Optional in the type so envelope
|
|
1943
|
+
* fixtures written against older SDKs still compile; treat an absent value
|
|
1944
|
+
* as unknown, not as "registered". */
|
|
1945
|
+
anon?: boolean;
|
|
1839
1946
|
}
|
|
1840
1947
|
/** The fields every invocation carries, whatever fired it. */
|
|
1841
1948
|
export interface FunctionEnvelopeBase {
|
|
@@ -3146,7 +3253,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3146
3253
|
private readonly apiVersions;
|
|
3147
3254
|
/** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
|
|
3148
3255
|
* mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
|
|
3149
|
-
private
|
|
3256
|
+
private endUserToken;
|
|
3257
|
+
/** The end-user session pair (`endUserSession`), when the client holds one:
|
|
3258
|
+
* replaced in place by a `session_stale` recovery or `switchOrg`. */
|
|
3259
|
+
private endUserPair;
|
|
3260
|
+
private readonly onSessionChange;
|
|
3150
3261
|
/** The ONE path every request takes: retry + timeout + hooks around
|
|
3151
3262
|
* `fetchImpl`. With none of the three configured it is a single fetch. */
|
|
3152
3263
|
private readonly transport;
|
|
@@ -3163,8 +3274,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3163
3274
|
* client, mirroring how the edge threads the verified principal. The base
|
|
3164
3275
|
* URL, api key, fetch impl, version pins and the retry/timeout/hooks options
|
|
3165
3276
|
* are inherited unchanged; only the end-user token is (re)set. Pass a falsy token to get back a server-mode
|
|
3166
|
-
* client (drops the header).
|
|
3167
|
-
|
|
3277
|
+
* client (drops the header). Pass the whole session PAIR (`AuthSession`)
|
|
3278
|
+
* instead of the bare token to let the client recover from
|
|
3279
|
+
* `401 session_stale` and `switchOrg` on its own (see `endUserSession`);
|
|
3280
|
+
* `opts.onSessionChange` then receives each pair it rotates (default: this
|
|
3281
|
+
* client's own). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
|
|
3282
|
+
asEndUser(endUser: string | AuthSession | undefined, opts?: {
|
|
3283
|
+
onSessionChange?: VxilOptions['onSessionChange'];
|
|
3284
|
+
}): Vxil<S>;
|
|
3285
|
+
/** Adopt a rotated end-user pair when it replaces the one this client sends
|
|
3286
|
+
* (a no-op for a pair this client does not hold), then tell the app. */
|
|
3287
|
+
private adoptSession;
|
|
3288
|
+
/** The edge answered `401 session_stale` — force ONE
|
|
3289
|
+
* rotation of the held pair (no near-expiry check; the stale token stays on
|
|
3290
|
+
* the request, which the edge admits on the refresh route only). Concurrent
|
|
3291
|
+
* stale requests share the rotation through the process-wide cache.
|
|
3292
|
+
* false = nothing to rotate with (no pair held) or the rotation failed. */
|
|
3293
|
+
private recoverStale;
|
|
3294
|
+
/** The session_stale test: ONLY the edge's own 401 envelope (a feature never
|
|
3295
|
+
* answers this code at top level). */
|
|
3296
|
+
private static isSessionStale;
|
|
3168
3297
|
/** Build the versioned request path — the ONE place a wire path is finalized.
|
|
3169
3298
|
* Every request (call(), audit.export, the fn proxy) routes through here, so
|
|
3170
3299
|
* the per-feature/global major pin applies uniformly. Default → unchanged
|
|
@@ -3277,6 +3406,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3277
3406
|
send_at?: string;
|
|
3278
3407
|
/** …or this many seconds from now (≤ 30 d). At most one of the two. */
|
|
3279
3408
|
delay_seconds?: number;
|
|
3409
|
+
/** Deliver to this address instead of the user's stored email (e.g. an
|
|
3410
|
+
* invitee with no account yet). `user_id` must still be an existing
|
|
3411
|
+
* user: it anchors preferences, the inbox copy and the delivery row.
|
|
3412
|
+
* Suppressions are checked against THIS address; caps apply as usual. */
|
|
3413
|
+
to_email?: string;
|
|
3414
|
+
/** This send's sender display name (≤ 64 chars); default config.fromName. */
|
|
3415
|
+
from_name?: string;
|
|
3416
|
+
/** This send's from-address local part, `[a-z0-9._-]{1,40}`. The domain is
|
|
3417
|
+
* ALWAYS your config fromEmail domain; default config.fromEmail. */
|
|
3418
|
+
from_local_part?: string;
|
|
3419
|
+
/** This send's Reply-To address; default config.replyTo. */
|
|
3420
|
+
reply_to?: string;
|
|
3280
3421
|
}, opts?: {
|
|
3281
3422
|
idempotencyKey?: string;
|
|
3282
3423
|
}) => Promise<NotificationSendResult>;
|
|
@@ -3290,6 +3431,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
3290
3431
|
channel?: "email" | "inbox" | "both";
|
|
3291
3432
|
send_at?: string;
|
|
3292
3433
|
delay_seconds?: number;
|
|
3434
|
+
/** the `send` fields of the same names (address override, per-send sender) */
|
|
3435
|
+
to_email?: string;
|
|
3436
|
+
from_name?: string;
|
|
3437
|
+
from_local_part?: string;
|
|
3438
|
+
reply_to?: string;
|
|
3293
3439
|
/** per-item 24 h idempotency key (the header equivalent for one item) */
|
|
3294
3440
|
idempotency_key?: string;
|
|
3295
3441
|
}>) => Promise<{
|
|
@@ -4034,6 +4180,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4034
4180
|
* sessions only, own devices only, erase self only. `auth:write` still
|
|
4035
4181
|
* satisfies every call. */
|
|
4036
4182
|
readonly auth: {
|
|
4183
|
+
/** The end-user session this client sends (end-user mode), read from its
|
|
4184
|
+
* token WITHOUT verification — for display (the workspace switcher), not
|
|
4185
|
+
* for authorization (the edge verifies). */
|
|
4186
|
+
session: {
|
|
4187
|
+
/** The org the session acts in (its `org` claim, auth `orgClaims`), or
|
|
4188
|
+
* null: server mode, no membership, the user left the stored org, or
|
|
4189
|
+
* orgs was unreachable at the last refresh. Updates after `switchOrg`
|
|
4190
|
+
* and a `session_stale` recovery. */
|
|
4191
|
+
readonly org: SessionOrg | null;
|
|
4192
|
+
/** The pair the client holds (`endUserSession`), after any rotation. */
|
|
4193
|
+
readonly current: AuthSession | null;
|
|
4194
|
+
};
|
|
4037
4195
|
signUp: (input: {
|
|
4038
4196
|
email: string;
|
|
4039
4197
|
password: string;
|
|
@@ -4260,13 +4418,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4260
4418
|
* (e.g. a rehearsal dev backend) is `skipped` / `id_taken`. `oidc_issuer` links each id as that
|
|
4261
4419
|
* issuer's subject, so an installed app can trade its old session token
|
|
4262
4420
|
* for a vxil one (`auth.oauth.native('oidc', …)`). One result per id:
|
|
4263
|
-
* `created` / `updated` / `kept` / `skipped` + `reason`. `
|
|
4264
|
-
*
|
|
4421
|
+
* `created` / `updated` / `kept` / `skipped` + `reason`. `identities`
|
|
4422
|
+
* (≤ 8 per user: google / apple / github / facebook + the provider's
|
|
4423
|
+
* subject — Supabase `auth.identities.provider_id`) seeds the social
|
|
4424
|
+
* sign-in links, so the first Google / Apple sign-in after the move lands
|
|
4425
|
+
* on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
|
|
4426
|
+
* only for identities the import creates or still holds, and a subject
|
|
4427
|
+
* already linked stays where it is (`identities_linked` counts the new
|
|
4428
|
+
* ones). `vxil migrate data --with-password-hashes` /
|
|
4429
|
+
* `--with-oauth-identities` drives this for you. */
|
|
4265
4430
|
import: (input: {
|
|
4266
4431
|
users: Array<{
|
|
4267
4432
|
id: string;
|
|
4268
4433
|
password_hash?: string | null;
|
|
4269
4434
|
email_verified?: boolean;
|
|
4435
|
+
identities?: Array<{
|
|
4436
|
+
provider: "google" | "apple" | "github" | "facebook";
|
|
4437
|
+
subject: string;
|
|
4438
|
+
}>;
|
|
4270
4439
|
}>;
|
|
4271
4440
|
oidc_issuer?: string;
|
|
4272
4441
|
}) => Promise<AuthImportResult>;
|
|
@@ -4326,6 +4495,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4326
4495
|
session: AuthSession;
|
|
4327
4496
|
refreshed: boolean;
|
|
4328
4497
|
}>;
|
|
4498
|
+
/** Workspaces (auth `orgClaims.activeOrg`): make `orgId` the org the
|
|
4499
|
+
* session acts in — a refresh with `org_id`, so the NEW pair carries that
|
|
4500
|
+
* org's claim and later refreshes keep it. `pair` defaults to the pair
|
|
4501
|
+
* this client holds (`endUserSession` / `asEndUser(pair)`); a client
|
|
4502
|
+
* sending that pair's token switches to the new one in place and calls
|
|
4503
|
+
* `onSessionChange`. Store the returned `session` (the old refresh token
|
|
4504
|
+
* is revoked). The user must be a member: 403 `not_a_member`, and
|
|
4505
|
+
* 503 `orgs_unavailable`, leave the session untouched. List the
|
|
4506
|
+
* choices with `vx.orgs.list()`. Needs `@vxil/sdk` 0.25.0 or later on
|
|
4507
|
+
* the client for the `session_stale` recovery that goes with it. */
|
|
4508
|
+
switchOrg: (orgId: string, pair?: AuthSession) => Promise<{
|
|
4509
|
+
user_id: string;
|
|
4510
|
+
session: AuthSession;
|
|
4511
|
+
org: {
|
|
4512
|
+
id: string;
|
|
4513
|
+
role: string;
|
|
4514
|
+
} | null;
|
|
4515
|
+
}>;
|
|
4329
4516
|
revoke: (token: string) => Promise<void>;
|
|
4330
4517
|
/** "Sign out everywhere": revoke EVERY live session of a user in one call
|
|
4331
4518
|
* (one statement, one batched edge-cache write; each session's
|
|
@@ -4355,22 +4542,51 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4355
4542
|
}>>;
|
|
4356
4543
|
};
|
|
4357
4544
|
password: {
|
|
4545
|
+
/** Always resolves (anti-enumeration). `captcha_token` is required only
|
|
4546
|
+
* when the tenant set BOTH `security.captchaOnReset: true` and
|
|
4547
|
+
* `security.captchaSecretRef` (403 `captcha_failed`). */
|
|
4358
4548
|
requestReset: (input: {
|
|
4359
4549
|
email: string;
|
|
4360
4550
|
redirect_url: string;
|
|
4551
|
+
locale?: string;
|
|
4552
|
+
captcha_token?: string;
|
|
4361
4553
|
}) => Promise<void>;
|
|
4362
4554
|
/** Confirming kills every existing session for the user. */
|
|
4363
4555
|
confirmReset: (input: {
|
|
4364
4556
|
token: string;
|
|
4365
4557
|
password: string;
|
|
4366
4558
|
}) => Promise<void>;
|
|
4559
|
+
/** Change (or set a first) password for a signed-in user. `token` is the
|
|
4560
|
+
* user's CURRENT session. An account with a password sends
|
|
4561
|
+
* `current_password` (wrong → 403 `invalid_credentials`, counts toward
|
|
4562
|
+
* `security.lockout`). An account with none yet (OTP, magic-link or social
|
|
4563
|
+
* sign-up) needs a step-up on this session in the last 300 s instead
|
|
4564
|
+
* (`stepUp.request` / `stepUp.verify`, then pass the rotated token) —
|
|
4565
|
+
* otherwise 403 `step_up_required`. Step-up needs `otp.enabled`; with
|
|
4566
|
+
* OTP off, such a user sets a first password through
|
|
4567
|
+
* `password.requestReset` (the reset email) instead. Every OTHER session is revoked
|
|
4568
|
+
* (reason `password_changed`); the presenting one keeps working. A guest
|
|
4569
|
+
* session is 409 `anonymous_user`. */
|
|
4570
|
+
change: (input: {
|
|
4571
|
+
token: string;
|
|
4572
|
+
new_password: string;
|
|
4573
|
+
current_password?: string;
|
|
4574
|
+
}) => Promise<{
|
|
4575
|
+
user_id: string;
|
|
4576
|
+
changed: true;
|
|
4577
|
+
revoked_sessions: number;
|
|
4578
|
+
}>;
|
|
4367
4579
|
};
|
|
4368
4580
|
/** Email verification (the flow behind auth config `emailVerification.required`,
|
|
4369
4581
|
* which makes password sign-in answer 403 `email_not_verified` until the
|
|
4370
4582
|
* address is confirmed). `request` always resolves (anti-enumeration —
|
|
4371
4583
|
* a link is mailed only to an existing, unverified user; `redirect_url`
|
|
4372
4584
|
* is your page that reads `?token=` and calls `confirm`). `confirm` is
|
|
4373
|
-
* single-use and expires after 24h.
|
|
4585
|
+
* single-use and expires after 24h. Pass the session sign-up returned as
|
|
4586
|
+
* `session_token` to keep the password: without the same user's live
|
|
4587
|
+
* session the click proves only the mailbox, so a never-verified
|
|
4588
|
+
* account's password is cleared and its sessions revoked
|
|
4589
|
+
* (`password_cleared: true` — send the user to a password reset). */
|
|
4374
4590
|
emailVerification: {
|
|
4375
4591
|
request: (input: {
|
|
4376
4592
|
email: string;
|
|
@@ -4378,9 +4594,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4378
4594
|
locale?: string;
|
|
4379
4595
|
captcha_token?: string;
|
|
4380
4596
|
}) => Promise<void>;
|
|
4381
|
-
confirm: (token: string
|
|
4597
|
+
confirm: (token: string, opts?: {
|
|
4598
|
+
session_token?: string;
|
|
4599
|
+
}) => Promise<{
|
|
4382
4600
|
user_id: string;
|
|
4383
4601
|
verified: true;
|
|
4602
|
+
password_cleared: boolean;
|
|
4384
4603
|
}>;
|
|
4385
4604
|
};
|
|
4386
4605
|
/** Social sign-in. The web flow: `startUrl` fetches the provider authorize
|
|
@@ -4438,7 +4657,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4438
4657
|
* an Apple "Hide My Email" relay address on an OTP account. Idempotent
|
|
4439
4658
|
* for an identity this user already holds; 409 `oauth_identity_linked`
|
|
4440
4659
|
* when another user holds it; 401 `invalid_session` / 409
|
|
4441
|
-
* `anonymous_user` for an unknown or guest session
|
|
4660
|
+
* `anonymous_user` for an unknown or guest session; 409
|
|
4661
|
+
* `email_unverified` (verify the address first) or `password_unproven`
|
|
4662
|
+
* (complete a password reset, or step up then `password/change`) on a
|
|
4663
|
+
* password account, unless the provider-verified address is its own. */
|
|
4442
4664
|
link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
|
|
4443
4665
|
session_token: string;
|
|
4444
4666
|
id_token?: string;
|
|
@@ -4592,6 +4814,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4592
4814
|
* instead of per-item delete events. A collection another collection
|
|
4593
4815
|
* references with an `on_delete` rule is skipped. Omit/null = keep. */
|
|
4594
4816
|
retain_days?: number | null;
|
|
4817
|
+
/** Workspace scope (guide ch. 4): the workspace field — a string field on
|
|
4818
|
+
* index slot s1–s4 holding the orgs org id. End users then read and
|
|
4819
|
+
* write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
|
|
4820
|
+
* `write_roles` match the active-org role. Needs `auth.orgClaims.activeOrg`. */
|
|
4821
|
+
org_field?: string;
|
|
4822
|
+
/** Active-org roles allowed to READ (owner always passes). Needs org_field. */
|
|
4823
|
+
org_read_roles?: string[];
|
|
4595
4824
|
fields?: Array<{
|
|
4596
4825
|
field: string;
|
|
4597
4826
|
type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
|
|
@@ -4645,6 +4874,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4645
4874
|
write_roles?: string[];
|
|
4646
4875
|
/** present when retention is set */
|
|
4647
4876
|
retain_days?: number;
|
|
4877
|
+
/** present when the collection is workspace-scoped */
|
|
4878
|
+
org_field?: string;
|
|
4879
|
+
org_read_roles?: string[];
|
|
4648
4880
|
}>;
|
|
4649
4881
|
list: () => Promise<Array<{
|
|
4650
4882
|
collection: string;
|
|
@@ -4657,6 +4889,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4657
4889
|
write_roles?: string[] | null;
|
|
4658
4890
|
/** retention in days (null = keep until deleted; absent from an older server) */
|
|
4659
4891
|
retain_days?: number | null;
|
|
4892
|
+
/** the workspace field / org read gate (null = not workspace-scoped) */
|
|
4893
|
+
org_field?: string | null;
|
|
4894
|
+
org_read_roles?: string[] | null;
|
|
4660
4895
|
}>>;
|
|
4661
4896
|
addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
|
|
4662
4897
|
/** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
|
|
@@ -4713,6 +4948,28 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4713
4948
|
collection: string;
|
|
4714
4949
|
write_roles: string[];
|
|
4715
4950
|
}>;
|
|
4951
|
+
/** Set (or clear, with `null`) the collection's WORKSPACE field (guide
|
|
4952
|
+
* ch. 4, "Workspace-scoped collections"): a `string` field on an index
|
|
4953
|
+
* slot (s1–s4) holding the orgs org id. A verified end user then reads and
|
|
4954
|
+
* writes only rows of the session's ACTIVE org, and `writeRoles` match the
|
|
4955
|
+
* active-org role. Server keys are never affected. Changing or clearing a
|
|
4956
|
+
* set one needs `{ allowDestructive: true }` (422 destructive_change_requires_ack). */
|
|
4957
|
+
setOrgField: (collection: string, orgField: string | null, opts?: {
|
|
4958
|
+
allowDestructive?: boolean;
|
|
4959
|
+
}) => Promise<{
|
|
4960
|
+
collection: string;
|
|
4961
|
+
org_field: string | null;
|
|
4962
|
+
}>;
|
|
4963
|
+
/** Set (or clear, with `[]` / `null`) the active-org roles one of which a
|
|
4964
|
+
* verified end user must hold to READ a workspace collection (the built-in
|
|
4965
|
+
* `owner` always passes; empty = any member). Needs an org field. Widening
|
|
4966
|
+
* (clearing or adding a role) needs `{ allowDestructive: true }`. */
|
|
4967
|
+
setOrgReadRoles: (collection: string, roles: string[] | null, opts?: {
|
|
4968
|
+
allowDestructive?: boolean;
|
|
4969
|
+
}) => Promise<{
|
|
4970
|
+
collection: string;
|
|
4971
|
+
org_read_roles: string[];
|
|
4972
|
+
}>;
|
|
4716
4973
|
/** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
|
|
4717
4974
|
* ch. 4): the nightly platform sweep soft-deletes live items created more
|
|
4718
4975
|
* than `days` ago — bounded per project per night, no restore, purged at
|
|
@@ -5661,7 +5918,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5661
5918
|
limit?: number | undefined;
|
|
5662
5919
|
cursor?: string | null | undefined;
|
|
5663
5920
|
}) => Promise<OrgsListPage>;
|
|
5664
|
-
/** Every org (walks `listPage` at 500 a page), each with `member_count`.
|
|
5921
|
+
/** Every org (walks `listPage` at 500 a page), each with `member_count`.
|
|
5922
|
+
* In END-USER mode with no `user_id` it lists the SIGNED-IN user's orgs,
|
|
5923
|
+
* each with their `role` — the workspace switcher's read (the id comes
|
|
5924
|
+
* from the session token; with auth `orgClaims.activeOrg` the server
|
|
5925
|
+
* binds the list to the verified caller whatever is sent). */
|
|
5665
5926
|
list: (q?: {
|
|
5666
5927
|
user_id?: string;
|
|
5667
5928
|
}) => Promise<OrgListRow[]>;
|
|
@@ -5677,11 +5938,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5677
5938
|
role: string | null;
|
|
5678
5939
|
source?: string;
|
|
5679
5940
|
}>;
|
|
5680
|
-
/** The
|
|
5681
|
-
*
|
|
5941
|
+
/** The org snapshot auth embeds in session JWTs when the tenant enables
|
|
5942
|
+
* auth config `orgClaims`: the most recent membership by joined_at — or,
|
|
5943
|
+
* with `orgClaims.activeOrg`, the org the session picked (first sign-in
|
|
5944
|
+
* stores the most recent; `vx.auth.sessions.switchOrg` changes it).
|
|
5682
5945
|
* EVENTUAL-CONSISTENT for JWTs (recomputed at refresh); use `check` for
|
|
5683
|
-
* revocation-grade authz. No membership → org_id null.
|
|
5684
|
-
|
|
5946
|
+
* revocation-grade authz. No membership → org_id null. `opts.orgId`
|
|
5947
|
+
* resolves that org's claim instead (null when not a member). */
|
|
5948
|
+
sessionClaims: (userId: string, opts?: {
|
|
5949
|
+
orgId?: string;
|
|
5950
|
+
}) => Promise<{
|
|
5685
5951
|
user_id: string;
|
|
5686
5952
|
org_id: string | null;
|
|
5687
5953
|
role: string | null;
|
|
@@ -5716,15 +5982,37 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5716
5982
|
remove: (orgId: string, userId: string) => Promise<void>;
|
|
5717
5983
|
};
|
|
5718
5984
|
invitations: {
|
|
5719
|
-
/** invite_token is returned ONCE — your app builds the accept URL.
|
|
5720
|
-
|
|
5985
|
+
/** invite_token is returned ONCE — your app builds the accept URL.
|
|
5986
|
+
* `role`: admin | member | viewer, or a custom role_key defined with
|
|
5987
|
+
* `roles.define` (never owner). Pass `email: null` for a LINK invite —
|
|
5988
|
+
* no email is sent and any signed-in user holding the token may accept. */
|
|
5989
|
+
create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {})) => Promise<{
|
|
5721
5990
|
invite_id: string;
|
|
5722
5991
|
invite_token: string;
|
|
5992
|
+
org_id: string;
|
|
5993
|
+
role: string;
|
|
5994
|
+
email: string | null;
|
|
5723
5995
|
}>;
|
|
5724
|
-
|
|
5996
|
+
/** Redeem a token. With an end-user session the signed-in user is seated
|
|
5997
|
+
* (omit `userId`) and an email invite needs that user's VERIFIED email to
|
|
5998
|
+
* match (403 `invitation_email_mismatch`); a server key passes `userId`. */
|
|
5999
|
+
accept: (token: string, userId?: string) => Promise<{
|
|
5725
6000
|
org_id: string;
|
|
6001
|
+
user_id: string;
|
|
5726
6002
|
role: string;
|
|
5727
6003
|
}>;
|
|
6004
|
+
/** Server key only: one address's PENDING invitations across your orgs
|
|
6005
|
+
* (newest first, at most 100; never the token). */
|
|
6006
|
+
pendingForEmail: (email: string) => Promise<Array<{
|
|
6007
|
+
invite_id: string;
|
|
6008
|
+
org_id: string;
|
|
6009
|
+
org_name?: string;
|
|
6010
|
+
org_slug?: string;
|
|
6011
|
+
email: string;
|
|
6012
|
+
role: string;
|
|
6013
|
+
created_at?: string;
|
|
6014
|
+
expires_at?: string;
|
|
6015
|
+
}>>;
|
|
5728
6016
|
revoke: (inviteId: string) => Promise<void>;
|
|
5729
6017
|
/** List an org's pending invitations. */
|
|
5730
6018
|
list: (orgId: string) => Promise<Array<{
|
|
@@ -5873,9 +6161,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5873
6161
|
* on the PUT) and kept with the upload: `complete` compares it with the
|
|
5874
6162
|
* SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
|
|
5875
6163
|
* they differ, 409 `checksum_unverified` when the store reports none —
|
|
5876
|
-
* and on success answers the verified `checksum_sha256`.
|
|
6164
|
+
* and on success answers the verified `checksum_sha256`.
|
|
6165
|
+
* Workspace files: `org: true` (end-user mode) makes the
|
|
6166
|
+
* session's ACTIVE org own the object — every member of that org can
|
|
6167
|
+
* list (`list({ scope: 'org' })`) and read it, it survives the uploader's
|
|
6168
|
+
* erasure, and deleting the org removes it. A server key names `org_id`. */
|
|
5877
6169
|
createUploadUrl: (input: {
|
|
5878
6170
|
user_id?: string;
|
|
6171
|
+
org?: boolean;
|
|
6172
|
+
org_id?: string;
|
|
5879
6173
|
filename: string;
|
|
5880
6174
|
content_type: string;
|
|
5881
6175
|
size_bytes: number;
|
|
@@ -5894,7 +6188,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5894
6188
|
checksum_sha256?: string | null;
|
|
5895
6189
|
expires_at?: string | null;
|
|
5896
6190
|
}>;
|
|
5897
|
-
|
|
6191
|
+
/** Mint a short-lived presigned GET. Options:
|
|
6192
|
+
* `disposition: 'inline'` opens a PDF (or an image, ICO, audio/video) in
|
|
6193
|
+
* the browser instead of downloading it — html/svg/js and every other
|
|
6194
|
+
* type stay attachments whatever you ask; `'attachment'` forces a
|
|
6195
|
+
* download; omitted = raster images inline, everything else attachment.
|
|
6196
|
+
* `filename` sets the name the browser saves (sanitised server-side:
|
|
6197
|
+
* control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
|
|
6198
|
+
* RFC 6266 `filename*`), default the upload's filename. */
|
|
6199
|
+
downloadUrl: (objectId: string, opts?: {
|
|
6200
|
+
disposition?: "inline" | "attachment";
|
|
6201
|
+
filename?: string;
|
|
6202
|
+
}) => Promise<string>;
|
|
5898
6203
|
/** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
|
|
5899
6204
|
* — a gallery page costs one request, not one per image. `urls[]` keeps
|
|
5900
6205
|
* your order (duplicates collapse); an id that is unknown, someone else's
|
|
@@ -5914,10 +6219,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
5914
6219
|
}>;
|
|
5915
6220
|
expires_in: number;
|
|
5916
6221
|
}>;
|
|
6222
|
+
/** List objects. End-user mode: your PERSONAL files, or `scope: 'org'`
|
|
6223
|
+
* for the active org's WORKSPACE files (403 `org_required` without an
|
|
6224
|
+
* active org). Server key: `user_id` / `org_id` filters. */
|
|
5917
6225
|
list: (q?: {
|
|
5918
6226
|
user_id?: string;
|
|
5919
6227
|
cursor?: string;
|
|
5920
6228
|
limit?: number;
|
|
6229
|
+
scope?: "org";
|
|
6230
|
+
org_id?: string;
|
|
5921
6231
|
}) => Promise<{
|
|
5922
6232
|
files: FileObject[];
|
|
5923
6233
|
next_cursor: string | null;
|
|
@@ -6043,12 +6353,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6043
6353
|
createCollection: (input: {
|
|
6044
6354
|
collection: string;
|
|
6045
6355
|
dimensions?: number;
|
|
6356
|
+
/** Workspace-scoped: every document carries an org id and every end-user
|
|
6357
|
+
* read is filtered to the session's active workspace (a server-key query
|
|
6358
|
+
* must pass `org_id`). Immutable after creation. */
|
|
6359
|
+
org_scoped?: boolean;
|
|
6046
6360
|
embed?: {
|
|
6047
6361
|
provider?: "byov" | "mock" | "openai" | "cohere";
|
|
6048
6362
|
model?: string;
|
|
6049
6363
|
apiKeyRef?: string;
|
|
6050
6364
|
dimensions?: number;
|
|
6051
6365
|
};
|
|
6366
|
+
/** Keyword-lane normaliser. 'arabic' folds alef variants (أ إ آ ٱ → ا),
|
|
6367
|
+
* ى → ي, ة → ه and strips tashkeel/tatweel at index AND query time (no
|
|
6368
|
+
* fuzzy matching). Omitted = keep the current setting; 'none' turns it
|
|
6369
|
+
* off. On an EXISTING collection, send `{ collection, keywordNormalize }`
|
|
6370
|
+
* WITHOUT `embed` to change only the fold (the stored embed config and
|
|
6371
|
+
* dimensions are kept); a call with `embed` replaces the embed setup.
|
|
6372
|
+
* Turning it on for a populated collection needs a re-ingest
|
|
6373
|
+
* (`keyword_reindex_required`). */
|
|
6374
|
+
keywordNormalize?: "arabic" | "none";
|
|
6052
6375
|
}) => Promise<SearchCollection>;
|
|
6053
6376
|
/** List the tenant's collections (with per-collection document counts). */
|
|
6054
6377
|
listCollections: () => Promise<Array<{
|
|
@@ -6058,9 +6381,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6058
6381
|
provider?: string;
|
|
6059
6382
|
documents?: number;
|
|
6060
6383
|
created_at?: string;
|
|
6384
|
+
keyword_normalize?: "arabic" | "none";
|
|
6061
6385
|
/** true when the embed config pinned from the default differs from the
|
|
6062
6386
|
* current default (an explicit embed override is never flagged). */
|
|
6063
6387
|
embed_cfg_stale?: boolean;
|
|
6388
|
+
/** present (true) on a workspace-scoped collection */
|
|
6389
|
+
org_scoped?: true;
|
|
6064
6390
|
}>>;
|
|
6065
6391
|
/** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
|
|
6066
6392
|
ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
|
|
@@ -6083,10 +6409,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6083
6409
|
query: string;
|
|
6084
6410
|
top_k?: number;
|
|
6085
6411
|
mode?: "hybrid" | "vector" | "keyword";
|
|
6086
|
-
filter?:
|
|
6412
|
+
filter?: SearchFilter;
|
|
6087
6413
|
rrf_k?: number;
|
|
6088
6414
|
vector?: number[];
|
|
6089
6415
|
rerank?: boolean;
|
|
6416
|
+
/** orgScoped collections: the workspace to search — REQUIRED with a
|
|
6417
|
+
* server key (422 without); end-user sessions search their active one. */
|
|
6418
|
+
org_id?: string;
|
|
6090
6419
|
}) => Promise<SearchQueryResult>;
|
|
6091
6420
|
/** Embedding-token + query + rerank counts since a timestamp (default 30 days). */
|
|
6092
6421
|
usage: (q?: {
|
|
@@ -6435,7 +6764,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6435
6764
|
collection?: string;
|
|
6436
6765
|
template?: string;
|
|
6437
6766
|
top_k?: number;
|
|
6438
|
-
filter?:
|
|
6767
|
+
filter?: SearchFilter;
|
|
6439
6768
|
mode?: "hybrid" | "vector" | "keyword";
|
|
6440
6769
|
provider?: string;
|
|
6441
6770
|
model?: string;
|
|
@@ -6444,6 +6773,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6444
6773
|
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6445
6774
|
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6446
6775
|
min_similarity?: number;
|
|
6776
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6777
|
+
org_id?: string;
|
|
6447
6778
|
}) => Promise<RagAnswer>;
|
|
6448
6779
|
/** Streamed grounded answer: citations + the channel handle up front, tokens
|
|
6449
6780
|
* over the realtime channel. */
|
|
@@ -6452,7 +6783,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6452
6783
|
collection?: string;
|
|
6453
6784
|
template?: string;
|
|
6454
6785
|
top_k?: number;
|
|
6455
|
-
filter?:
|
|
6786
|
+
filter?: SearchFilter;
|
|
6456
6787
|
mode?: "hybrid" | "vector" | "keyword";
|
|
6457
6788
|
provider?: string;
|
|
6458
6789
|
model?: string;
|
|
@@ -6461,6 +6792,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6461
6792
|
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6462
6793
|
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6463
6794
|
min_similarity?: number;
|
|
6795
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6796
|
+
org_id?: string;
|
|
6464
6797
|
}) => Promise<RagStreamHandle>;
|
|
6465
6798
|
/** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
|
|
6466
6799
|
* would ground on, with rerank + metadata boosts applied — no generation,
|
|
@@ -6474,12 +6807,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6474
6807
|
query: string;
|
|
6475
6808
|
collection?: string;
|
|
6476
6809
|
top_k?: number;
|
|
6477
|
-
filter?:
|
|
6810
|
+
filter?: SearchFilter;
|
|
6478
6811
|
mode?: "hybrid" | "vector" | "keyword";
|
|
6479
6812
|
rerank?: boolean;
|
|
6480
6813
|
boosts?: Record<string, unknown>;
|
|
6481
6814
|
min_score?: number;
|
|
6482
6815
|
min_similarity?: number;
|
|
6816
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6817
|
+
org_id?: string;
|
|
6483
6818
|
}) => Promise<RagSearchResult>;
|
|
6484
6819
|
/** Ingest into the backing vector-search collection (chunk → embed → index). */
|
|
6485
6820
|
ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
|
|
@@ -6609,15 +6944,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6609
6944
|
* higher tier's earlier end; access does not dip (a lapsed winner re-folds
|
|
6610
6945
|
* on read and the lower tier takes over), but a client that CACHES `until`
|
|
6611
6946
|
* will show an early expiry — re-read instead of trusting a cached value
|
|
6612
|
-
* past it.
|
|
6613
|
-
|
|
6947
|
+
* past it.
|
|
6948
|
+
*
|
|
6949
|
+
* WORKSPACE BILLING: pass `{ org_id }` (server) or `{ subject: 'org' }`
|
|
6950
|
+
* (thin client, the active workspace) for a workspace's entitlements. */
|
|
6951
|
+
getEntitlements: (userId: PaymentsSubject, opts?: {
|
|
6614
6952
|
quota?: string;
|
|
6615
6953
|
creditType?: string;
|
|
6616
6954
|
}) => Promise<PaymentsEntitlementView>;
|
|
6617
6955
|
/** Boolean gate: does the user hold `entitlement`? Returns granted + its
|
|
6618
6956
|
* source (subscription/tier) + the resolved tier, plus `until` (how long
|
|
6619
|
-
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
6620
|
-
|
|
6957
|
+
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
6958
|
+
* `{ org_id }` / `{ subject: 'org' }` check a workspace (PaymentsSubject). */
|
|
6959
|
+
hasEntitlement: (userId: PaymentsSubject, entitlement: string) => Promise<{
|
|
6621
6960
|
granted: boolean;
|
|
6622
6961
|
source: string | null;
|
|
6623
6962
|
tier: string;
|
|
@@ -6626,10 +6965,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6626
6965
|
}>;
|
|
6627
6966
|
/** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
|
|
6628
6967
|
* the resolved tier declares no such quota. Convenience over getEntitlements. */
|
|
6629
|
-
getQuota: (userId:
|
|
6968
|
+
getQuota: (userId: PaymentsSubject, quota: string) => Promise<number | null>;
|
|
6630
6969
|
/** The credit balance for a credit type: balance/held/available (= balance −
|
|
6631
|
-
* held) + the current period_end.
|
|
6632
|
-
|
|
6970
|
+
* held) + the current period_end. `{ org_id }` / `{ subject: 'org' }`
|
|
6971
|
+
* read a workspace's balance (PaymentsSubject). */
|
|
6972
|
+
getBalance: (userId: PaymentsSubject, creditType: string) => Promise<{
|
|
6633
6973
|
credit_type: string;
|
|
6634
6974
|
balance: number;
|
|
6635
6975
|
held: number;
|
|
@@ -6659,8 +6999,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6659
6999
|
* listed in the answer's `parts`; a job hold of a split settles and
|
|
6660
7000
|
* releases every part.
|
|
6661
7001
|
*/
|
|
6662
|
-
consume: (input: PaymentsCreditTypeChoice & {
|
|
6663
|
-
user_id: string;
|
|
7002
|
+
consume: (input: PaymentsCreditTypeChoice & PaymentsSubjectBody & {
|
|
6664
7003
|
amount: number;
|
|
6665
7004
|
/** link this debit to a jobs run_id → provisional hold + auto-reverse. */
|
|
6666
7005
|
job_id?: string;
|
|
@@ -6693,8 +7032,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6693
7032
|
}) => Promise<PaymentsReverseResult>;
|
|
6694
7033
|
/** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
|
|
6695
7034
|
* only ADDS; `amount` must be ≥ 1. */
|
|
6696
|
-
grant: (input: {
|
|
6697
|
-
user_id: string;
|
|
7035
|
+
grant: (input: PaymentsSubjectBody & {
|
|
6698
7036
|
credit_type: string;
|
|
6699
7037
|
amount: number;
|
|
6700
7038
|
period?: string;
|
|
@@ -6707,8 +7045,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6707
7045
|
}>;
|
|
6708
7046
|
/** One-time grant idempotent on `grant_key` (at-most-once across ALL flows,
|
|
6709
7047
|
* not just retries). A repeat with the same key → granted:false. */
|
|
6710
|
-
grantOnce: (input: {
|
|
6711
|
-
user_id: string;
|
|
7048
|
+
grantOnce: (input: PaymentsSubjectBody & {
|
|
6712
7049
|
credit_type: string;
|
|
6713
7050
|
amount: number;
|
|
6714
7051
|
grant_key: string;
|
|
@@ -6717,9 +7054,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6717
7054
|
granted: boolean;
|
|
6718
7055
|
}>;
|
|
6719
7056
|
/** Recent ledger rows for the user (the audit/trail surface), newest first;
|
|
6720
|
-
* optionally scoped to one credit type.
|
|
6721
|
-
|
|
7057
|
+
* optionally scoped to one credit type. `org_id` (SERVER key only) reads a
|
|
7058
|
+
* workspace's rows instead — the workspace trail lists every member's
|
|
7059
|
+
* consumes, so a thin client gets 403 org_usage_server_only. */
|
|
7060
|
+
usage: (q: ({
|
|
6722
7061
|
user_id: string;
|
|
7062
|
+
} | {
|
|
7063
|
+
org_id: string;
|
|
7064
|
+
}) & {
|
|
6723
7065
|
credit_type?: string;
|
|
6724
7066
|
limit?: number;
|
|
6725
7067
|
}) => Promise<{
|
|
@@ -6765,8 +7107,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6765
7107
|
/** Start a subscription (mock = instant checkout; real providers redirect via
|
|
6766
7108
|
* their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
|
|
6767
7109
|
* ref. Returns the vxil subscription_id + provider sub id + status. */
|
|
6768
|
-
subscribe: (input: {
|
|
6769
|
-
user_id: string;
|
|
7110
|
+
subscribe: (input: PaymentsSubjectBody & {
|
|
6770
7111
|
price_ref: string;
|
|
6771
7112
|
tier?: string;
|
|
6772
7113
|
trial_days?: number;
|
|
@@ -6800,8 +7141,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6800
7141
|
* (the matching session flips to completed, the charge/grant is folded).
|
|
6801
7142
|
* Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
|
|
6802
7143
|
*/
|
|
6803
|
-
createCheckoutSession: (input:
|
|
7144
|
+
createCheckoutSession: (input: (
|
|
7145
|
+
/** WORKSPACE BILLING: `org_id` attributes the purchase to the
|
|
7146
|
+
* workspace (the provider checkout is tagged `vxil_org_id`); a
|
|
7147
|
+
* `user_id` beside it is the PAYER only. */
|
|
7148
|
+
{
|
|
6804
7149
|
user_id: string;
|
|
7150
|
+
org_id?: string;
|
|
7151
|
+
} | {
|
|
7152
|
+
org_id: string;
|
|
7153
|
+
user_id?: string;
|
|
7154
|
+
}) & {
|
|
6805
7155
|
line_items: Array<{
|
|
6806
7156
|
price_ref: string;
|
|
6807
7157
|
quantity?: number;
|
|
@@ -6880,8 +7230,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6880
7230
|
* charge_refunded (the refund beat the grant — nothing to grant against).
|
|
6881
7231
|
* 422 reserved_idempotency_key when `idempotency_key` starts with
|
|
6882
7232
|
* `purchase:` (the namespace of purchase passes). */
|
|
6883
|
-
grantSubscription: (input: {
|
|
6884
|
-
user_id: string;
|
|
7233
|
+
grantSubscription: (input: PaymentsSubjectBody & {
|
|
6885
7234
|
tier: string;
|
|
6886
7235
|
until?: string | null;
|
|
6887
7236
|
reason: string;
|
|
@@ -7096,4 +7445,6 @@ export interface AuthImportResult {
|
|
|
7096
7445
|
updated: number;
|
|
7097
7446
|
kept: number;
|
|
7098
7447
|
skipped: number;
|
|
7448
|
+
/** social sign-in links (users[].identities) created by this call */
|
|
7449
|
+
identities_linked?: number;
|
|
7099
7450
|
}
|