@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.
Files changed (3) hide show
  1. package/dist/index.d.ts +393 -42
  2. package/dist/index.js +299 -32
  3. 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 readonly endUserToken;
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). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
3167
- asEndUser(endUserToken: string | undefined): Vxil<S>;
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`. `vxil migrate
4264
- * data --with-password-hashes` drives this for you. */
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) => Promise<{
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 active-org snapshot auth embeds in session JWTs when the tenant
5681
- * enables auth config `orgClaims` (most-recent membership by joined_at).
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
- sessionClaims: (userId: string) => Promise<{
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
- create: (orgId: string, email: string, role: "admin" | "member" | "viewer") => Promise<{
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
- accept: (token: string, userId: string) => Promise<{
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
- downloadUrl: (objectId: string) => Promise<string>;
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?: Record<string, unknown>;
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?: Record<string, unknown>;
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?: Record<string, unknown>;
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?: Record<string, unknown>;
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
- getEntitlements: (userId: string, opts?: {
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
- hasEntitlement: (userId: string, entitlement: string) => Promise<{
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: string, quota: string) => Promise<number | null>;
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
- getBalance: (userId: string, creditType: string) => Promise<{
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
- usage: (q: {
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
  }