@vxil/sdk 0.24.0 → 0.25.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 +280 -21
  2. package/dist/index.js +257 -23
  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;
@@ -1194,6 +1231,17 @@ export interface SearchHit {
1194
1231
  rerank_score?: number;
1195
1232
  metadata: Record<string, unknown>;
1196
1233
  }
1234
+ /** A vector-search / rag metadata filter (guide ch. 6, vector-search): each
1235
+ * key is a top-level metadata key; `{ key: value }` is exact scalar equality
1236
+ * (a key whose metadata value is an array never matches — store one flag per
1237
+ * value instead, e.g. `aud_public: true`) and
1238
+ * `{ key: { $in: [...] } }` matches any of 1–50 values (at most 4 `$in` keys).
1239
+ * Keys AND together. Any other value — null, an array, another operator — is
1240
+ * refused with 422, never ignored. */
1241
+ export type SearchFilterValue = string | number | boolean;
1242
+ export type SearchFilter = Record<string, SearchFilterValue | {
1243
+ $in: SearchFilterValue[];
1244
+ }>;
1197
1245
  /** A query result set (POST …/query). */
1198
1246
  export interface SearchQueryResult {
1199
1247
  results: SearchHit[];
@@ -1596,6 +1644,16 @@ export interface PaymentsSubscriptionStatusEventPayload {
1596
1644
  /** the subscription row's `reference` (a provider subscription carries the
1597
1645
  * checkout's; null on manual grants and passes) */
1598
1646
  reference: string | null;
1647
+ /** what THIS delivery charged, in minor units — set by a RevenueCat
1648
+ * INITIAL_PURCHASE / RENEWAL that reports a price (the buyer's
1649
+ * own currency when RevenueCat sends it, else USD); null otherwise,
1650
+ * including a PRODUCT_CHANGE (not a charge — its revenue rides the renewal). */
1651
+ amount_cents: number | null;
1652
+ /** lower-case ISO 4217 code of `amount_cents`; null when it is null */
1653
+ currency: string | null;
1654
+ /** the store transaction id of that purchase / renewal (RevenueCat
1655
+ * `transaction_id`) — a stable dedup id for ad-platform conversions */
1656
+ transaction_id: string | null;
1599
1657
  environment: PaymentsEventEnvironment;
1600
1658
  /** what wrote it: the provider event type, `subscription.synced` /
1601
1659
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
@@ -1836,6 +1894,14 @@ export interface FunctionEndUser {
1836
1894
  sid: string;
1837
1895
  /** the step-up epoch, when the session has one */
1838
1896
  elv?: number;
1897
+ /** `true` for a guest (anonymous sign-in) session, `false` for a registered
1898
+ * user. Sent since 2026-10-12 on every path that reaches a function as an
1899
+ * end user (direct call, cms action, copilot tool, function → function).
1900
+ * Caveat: a guest session refreshed BEFORE 2026-10-12 lost the claim and
1901
+ * reads `false` until its next refresh. Optional in the type so envelope
1902
+ * fixtures written against older SDKs still compile; treat an absent value
1903
+ * as unknown, not as "registered". */
1904
+ anon?: boolean;
1839
1905
  }
1840
1906
  /** The fields every invocation carries, whatever fired it. */
1841
1907
  export interface FunctionEnvelopeBase {
@@ -3146,7 +3212,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3146
3212
  private readonly apiVersions;
3147
3213
  /** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
3148
3214
  * mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
3149
- private readonly endUserToken;
3215
+ private endUserToken;
3216
+ /** The end-user session pair (`endUserSession`), when the client holds one:
3217
+ * replaced in place by a `session_stale` recovery or `switchOrg`. */
3218
+ private endUserPair;
3219
+ private readonly onSessionChange;
3150
3220
  /** The ONE path every request takes: retry + timeout + hooks around
3151
3221
  * `fetchImpl`. With none of the three configured it is a single fetch. */
3152
3222
  private readonly transport;
@@ -3163,8 +3233,26 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3163
3233
  * client, mirroring how the edge threads the verified principal. The base
3164
3234
  * URL, api key, fetch impl, version pins and the retry/timeout/hooks options
3165
3235
  * 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>;
3236
+ * client (drops the header). Pass the whole session PAIR (`AuthSession`)
3237
+ * instead of the bare token to let the client recover from
3238
+ * `401 session_stale` and `switchOrg` on its own (see `endUserSession`);
3239
+ * `opts.onSessionChange` then receives each pair it rotates (default: this
3240
+ * client's own). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
3241
+ asEndUser(endUser: string | AuthSession | undefined, opts?: {
3242
+ onSessionChange?: VxilOptions['onSessionChange'];
3243
+ }): Vxil<S>;
3244
+ /** Adopt a rotated end-user pair when it replaces the one this client sends
3245
+ * (a no-op for a pair this client does not hold), then tell the app. */
3246
+ private adoptSession;
3247
+ /** The edge answered `401 session_stale` — force ONE
3248
+ * rotation of the held pair (no near-expiry check; the stale token stays on
3249
+ * the request, which the edge admits on the refresh route only). Concurrent
3250
+ * stale requests share the rotation through the process-wide cache.
3251
+ * false = nothing to rotate with (no pair held) or the rotation failed. */
3252
+ private recoverStale;
3253
+ /** The session_stale test: ONLY the edge's own 401 envelope (a feature never
3254
+ * answers this code at top level). */
3255
+ private static isSessionStale;
3168
3256
  /** Build the versioned request path — the ONE place a wire path is finalized.
3169
3257
  * Every request (call(), audit.export, the fn proxy) routes through here, so
3170
3258
  * the per-feature/global major pin applies uniformly. Default → unchanged
@@ -3277,6 +3365,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3277
3365
  send_at?: string;
3278
3366
  /** …or this many seconds from now (≤ 30 d). At most one of the two. */
3279
3367
  delay_seconds?: number;
3368
+ /** Deliver to this address instead of the user's stored email (e.g. an
3369
+ * invitee with no account yet). `user_id` must still be an existing
3370
+ * user: it anchors preferences, the inbox copy and the delivery row.
3371
+ * Suppressions are checked against THIS address; caps apply as usual. */
3372
+ to_email?: string;
3373
+ /** This send's sender display name (≤ 64 chars); default config.fromName. */
3374
+ from_name?: string;
3375
+ /** This send's from-address local part, `[a-z0-9._-]{1,40}`. The domain is
3376
+ * ALWAYS your config fromEmail domain; default config.fromEmail. */
3377
+ from_local_part?: string;
3378
+ /** This send's Reply-To address; default config.replyTo. */
3379
+ reply_to?: string;
3280
3380
  }, opts?: {
3281
3381
  idempotencyKey?: string;
3282
3382
  }) => Promise<NotificationSendResult>;
@@ -3290,6 +3390,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3290
3390
  channel?: "email" | "inbox" | "both";
3291
3391
  send_at?: string;
3292
3392
  delay_seconds?: number;
3393
+ /** the `send` fields of the same names (address override, per-send sender) */
3394
+ to_email?: string;
3395
+ from_name?: string;
3396
+ from_local_part?: string;
3397
+ reply_to?: string;
3293
3398
  /** per-item 24 h idempotency key (the header equivalent for one item) */
3294
3399
  idempotency_key?: string;
3295
3400
  }>) => Promise<{
@@ -4034,6 +4139,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4034
4139
  * sessions only, own devices only, erase self only. `auth:write` still
4035
4140
  * satisfies every call. */
4036
4141
  readonly auth: {
4142
+ /** The end-user session this client sends (end-user mode), read from its
4143
+ * token WITHOUT verification — for display (the workspace switcher), not
4144
+ * for authorization (the edge verifies). */
4145
+ session: {
4146
+ /** The org the session acts in (its `org` claim, auth `orgClaims`), or
4147
+ * null: server mode, no membership, the user left the stored org, or
4148
+ * orgs was unreachable at the last refresh. Updates after `switchOrg`
4149
+ * and a `session_stale` recovery. */
4150
+ readonly org: SessionOrg | null;
4151
+ /** The pair the client holds (`endUserSession`), after any rotation. */
4152
+ readonly current: AuthSession | null;
4153
+ };
4037
4154
  signUp: (input: {
4038
4155
  email: string;
4039
4156
  password: string;
@@ -4260,13 +4377,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4260
4377
  * (e.g. a rehearsal dev backend) is `skipped` / `id_taken`. `oidc_issuer` links each id as that
4261
4378
  * issuer's subject, so an installed app can trade its old session token
4262
4379
  * 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. */
4380
+ * `created` / `updated` / `kept` / `skipped` + `reason`. `identities`
4381
+ * (≤ 8 per user: google / apple / github / facebook + the provider's
4382
+ * subject — Supabase `auth.identities.provider_id`) seeds the social
4383
+ * sign-in links, so the first Google / Apple sign-in after the move lands
4384
+ * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
4385
+ * only for identities the import creates or still holds, and a subject
4386
+ * already linked stays where it is (`identities_linked` counts the new
4387
+ * ones). `vxil migrate data --with-password-hashes` /
4388
+ * `--with-oauth-identities` drives this for you. */
4265
4389
  import: (input: {
4266
4390
  users: Array<{
4267
4391
  id: string;
4268
4392
  password_hash?: string | null;
4269
4393
  email_verified?: boolean;
4394
+ identities?: Array<{
4395
+ provider: "google" | "apple" | "github" | "facebook";
4396
+ subject: string;
4397
+ }>;
4270
4398
  }>;
4271
4399
  oidc_issuer?: string;
4272
4400
  }) => Promise<AuthImportResult>;
@@ -4326,6 +4454,24 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4326
4454
  session: AuthSession;
4327
4455
  refreshed: boolean;
4328
4456
  }>;
4457
+ /** Workspaces (auth `orgClaims.activeOrg`): make `orgId` the org the
4458
+ * session acts in — a refresh with `org_id`, so the NEW pair carries that
4459
+ * org's claim and later refreshes keep it. `pair` defaults to the pair
4460
+ * this client holds (`endUserSession` / `asEndUser(pair)`); a client
4461
+ * sending that pair's token switches to the new one in place and calls
4462
+ * `onSessionChange`. Store the returned `session` (the old refresh token
4463
+ * is revoked). The user must be a member: 403 `not_a_member`, and
4464
+ * 503 `orgs_unavailable`, leave the session untouched. List the
4465
+ * choices with `vx.orgs.list()`. Needs `@vxil/sdk` 0.25.0 or later on
4466
+ * the client for the `session_stale` recovery that goes with it. */
4467
+ switchOrg: (orgId: string, pair?: AuthSession) => Promise<{
4468
+ user_id: string;
4469
+ session: AuthSession;
4470
+ org: {
4471
+ id: string;
4472
+ role: string;
4473
+ } | null;
4474
+ }>;
4329
4475
  revoke: (token: string) => Promise<void>;
4330
4476
  /** "Sign out everywhere": revoke EVERY live session of a user in one call
4331
4477
  * (one statement, one batched edge-cache write; each session's
@@ -4355,22 +4501,50 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4355
4501
  }>>;
4356
4502
  };
4357
4503
  password: {
4504
+ /** Always resolves (anti-enumeration). `captcha_token` is required when
4505
+ * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
4358
4506
  requestReset: (input: {
4359
4507
  email: string;
4360
4508
  redirect_url: string;
4509
+ locale?: string;
4510
+ captcha_token?: string;
4361
4511
  }) => Promise<void>;
4362
4512
  /** Confirming kills every existing session for the user. */
4363
4513
  confirmReset: (input: {
4364
4514
  token: string;
4365
4515
  password: string;
4366
4516
  }) => Promise<void>;
4517
+ /** Change (or set a first) password for a signed-in user. `token` is the
4518
+ * user's CURRENT session. An account with a password sends
4519
+ * `current_password` (wrong → 403 `invalid_credentials`, counts toward
4520
+ * `security.lockout`). An account with none yet (OTP, magic-link or social
4521
+ * sign-up) needs a step-up on this session in the last 300 s instead
4522
+ * (`stepUp.request` / `stepUp.verify`, then pass the rotated token) —
4523
+ * otherwise 403 `step_up_required`. Step-up needs `otp.enabled`; with
4524
+ * OTP off, such a user sets a first password through
4525
+ * `password.requestReset` (the reset email) instead. Every OTHER session is revoked
4526
+ * (reason `password_changed`); the presenting one keeps working. A guest
4527
+ * session is 409 `anonymous_user`. */
4528
+ change: (input: {
4529
+ token: string;
4530
+ new_password: string;
4531
+ current_password?: string;
4532
+ }) => Promise<{
4533
+ user_id: string;
4534
+ changed: true;
4535
+ revoked_sessions: number;
4536
+ }>;
4367
4537
  };
4368
4538
  /** Email verification (the flow behind auth config `emailVerification.required`,
4369
4539
  * which makes password sign-in answer 403 `email_not_verified` until the
4370
4540
  * address is confirmed). `request` always resolves (anti-enumeration —
4371
4541
  * a link is mailed only to an existing, unverified user; `redirect_url`
4372
4542
  * is your page that reads `?token=` and calls `confirm`). `confirm` is
4373
- * single-use and expires after 24h. */
4543
+ * single-use and expires after 24h. Pass the session sign-up returned as
4544
+ * `session_token` to keep the password: without the same user's live
4545
+ * session the click proves only the mailbox, so a never-verified
4546
+ * account's password is cleared and its sessions revoked
4547
+ * (`password_cleared: true` — send the user to a password reset). */
4374
4548
  emailVerification: {
4375
4549
  request: (input: {
4376
4550
  email: string;
@@ -4378,9 +4552,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4378
4552
  locale?: string;
4379
4553
  captcha_token?: string;
4380
4554
  }) => Promise<void>;
4381
- confirm: (token: string) => Promise<{
4555
+ confirm: (token: string, opts?: {
4556
+ session_token?: string;
4557
+ }) => Promise<{
4382
4558
  user_id: string;
4383
4559
  verified: true;
4560
+ password_cleared: boolean;
4384
4561
  }>;
4385
4562
  };
4386
4563
  /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
@@ -4592,6 +4769,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4592
4769
  * instead of per-item delete events. A collection another collection
4593
4770
  * references with an `on_delete` rule is skipped. Omit/null = keep. */
4594
4771
  retain_days?: number | null;
4772
+ /** Workspace scope (guide ch. 4): the workspace field — a string field on
4773
+ * index slot s1–s4 holding the orgs org id. End users then read and
4774
+ * write only rows of their ACTIVE org (`vx.auth.sessions.switchOrg`);
4775
+ * `write_roles` match the active-org role. Needs `auth.orgClaims.activeOrg`. */
4776
+ org_field?: string;
4777
+ /** Active-org roles allowed to READ (owner always passes). Needs org_field. */
4778
+ org_read_roles?: string[];
4595
4779
  fields?: Array<{
4596
4780
  field: string;
4597
4781
  type: "string" | "text" | "int" | "float" | "bool" | "datetime" | "json" | "relation" | "file";
@@ -4645,6 +4829,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4645
4829
  write_roles?: string[];
4646
4830
  /** present when retention is set */
4647
4831
  retain_days?: number;
4832
+ /** present when the collection is workspace-scoped */
4833
+ org_field?: string;
4834
+ org_read_roles?: string[];
4648
4835
  }>;
4649
4836
  list: () => Promise<Array<{
4650
4837
  collection: string;
@@ -4657,6 +4844,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4657
4844
  write_roles?: string[] | null;
4658
4845
  /** retention in days (null = keep until deleted; absent from an older server) */
4659
4846
  retain_days?: number | null;
4847
+ /** the workspace field / org read gate (null = not workspace-scoped) */
4848
+ org_field?: string | null;
4849
+ org_read_roles?: string[] | null;
4660
4850
  }>>;
4661
4851
  addField: (collection: string, field: Record<string, unknown>) => Promise<void>;
4662
4852
  /** Set (or clear, with `null`/`[]`) a field's READ-ROLE gate (guide ch. 4) —
@@ -4713,6 +4903,28 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4713
4903
  collection: string;
4714
4904
  write_roles: string[];
4715
4905
  }>;
4906
+ /** Set (or clear, with `null`) the collection's WORKSPACE field (guide
4907
+ * ch. 4, "Workspace-scoped collections"): a `string` field on an index
4908
+ * slot (s1–s4) holding the orgs org id. A verified end user then reads and
4909
+ * writes only rows of the session's ACTIVE org, and `writeRoles` match the
4910
+ * active-org role. Server keys are never affected. Changing or clearing a
4911
+ * set one needs `{ allowDestructive: true }` (422 destructive_change_requires_ack). */
4912
+ setOrgField: (collection: string, orgField: string | null, opts?: {
4913
+ allowDestructive?: boolean;
4914
+ }) => Promise<{
4915
+ collection: string;
4916
+ org_field: string | null;
4917
+ }>;
4918
+ /** Set (or clear, with `[]` / `null`) the active-org roles one of which a
4919
+ * verified end user must hold to READ a workspace collection (the built-in
4920
+ * `owner` always passes; empty = any member). Needs an org field. Widening
4921
+ * (clearing or adding a role) needs `{ allowDestructive: true }`. */
4922
+ setOrgReadRoles: (collection: string, roles: string[] | null, opts?: {
4923
+ allowDestructive?: boolean;
4924
+ }) => Promise<{
4925
+ collection: string;
4926
+ org_read_roles: string[];
4927
+ }>;
4716
4928
  /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
4717
4929
  * ch. 4): the nightly platform sweep soft-deletes live items created more
4718
4930
  * than `days` ago — bounded per project per night, no restore, purged at
@@ -5161,7 +5373,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5161
5373
  /** The deployed functions (name, endpoint, bindings, scopes, limits, the
5162
5374
  * runtime each script runs under), `runtime`, the settings a deploy uses
5163
5375
  * now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
5164
- * gives a function now (its own `limits.cpuMs` can only lower it), and
5376
+ * gives a function now (its own `limits.cpuMs` can only lower it),
5377
+ * `cpuMsDefault`, the CPU (ms) a function declaring no `limits.cpuMs`
5378
+ * gets (50 on a dev project, the ceiling elsewhere), and
5165
5379
  * `enabled`: false while the project's functions are paused as a whole
5166
5380
  * (a Free project on the production workload, a downgrade) — invokes then
5167
5381
  * answer 404. Any authenticated key may read it. (GET /v1/functions) */
@@ -5173,6 +5387,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5173
5387
  compatibilityFlags: string[];
5174
5388
  };
5175
5389
  cpuMsCeiling?: number;
5390
+ cpuMsDefault?: number;
5176
5391
  }>;
5177
5392
  /**
5178
5393
  * Remove ONE function from the deployed set — a new functions config
@@ -5658,7 +5873,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5658
5873
  limit?: number | undefined;
5659
5874
  cursor?: string | null | undefined;
5660
5875
  }) => Promise<OrgsListPage>;
5661
- /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
5876
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`.
5877
+ * In END-USER mode with no `user_id` it lists the SIGNED-IN user's orgs,
5878
+ * each with their `role` — the workspace switcher's read (the id comes
5879
+ * from the session token; with auth `orgClaims.activeOrg` the server
5880
+ * binds the list to the verified caller whatever is sent). */
5662
5881
  list: (q?: {
5663
5882
  user_id?: string;
5664
5883
  }) => Promise<OrgListRow[]>;
@@ -5674,11 +5893,16 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5674
5893
  role: string | null;
5675
5894
  source?: string;
5676
5895
  }>;
5677
- /** The active-org snapshot auth embeds in session JWTs when the tenant
5678
- * enables auth config `orgClaims` (most-recent membership by joined_at).
5896
+ /** The org snapshot auth embeds in session JWTs when the tenant enables
5897
+ * auth config `orgClaims`: the most recent membership by joined_at — or,
5898
+ * with `orgClaims.activeOrg`, the org the session picked (first sign-in
5899
+ * stores the most recent; `vx.auth.sessions.switchOrg` changes it).
5679
5900
  * EVENTUAL-CONSISTENT for JWTs (recomputed at refresh); use `check` for
5680
- * revocation-grade authz. No membership → org_id null. */
5681
- sessionClaims: (userId: string) => Promise<{
5901
+ * revocation-grade authz. No membership → org_id null. `opts.orgId`
5902
+ * resolves that org's claim instead (null when not a member). */
5903
+ sessionClaims: (userId: string, opts?: {
5904
+ orgId?: string;
5905
+ }) => Promise<{
5682
5906
  user_id: string;
5683
5907
  org_id: string | null;
5684
5908
  role: string | null;
@@ -5713,15 +5937,37 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5713
5937
  remove: (orgId: string, userId: string) => Promise<void>;
5714
5938
  };
5715
5939
  invitations: {
5716
- /** invite_token is returned ONCE — your app builds the accept URL. */
5717
- create: (orgId: string, email: string, role: "admin" | "member" | "viewer") => Promise<{
5940
+ /** invite_token is returned ONCE — your app builds the accept URL.
5941
+ * `role`: admin | member | viewer, or a custom role_key defined with
5942
+ * `roles.define` (never owner). Pass `email: null` for a LINK invite —
5943
+ * no email is sent and any signed-in user holding the token may accept. */
5944
+ create: (orgId: string, email: string | null, role: "admin" | "member" | "viewer" | (string & {})) => Promise<{
5718
5945
  invite_id: string;
5719
5946
  invite_token: string;
5947
+ org_id: string;
5948
+ role: string;
5949
+ email: string | null;
5720
5950
  }>;
5721
- accept: (token: string, userId: string) => Promise<{
5951
+ /** Redeem a token. With an end-user session the signed-in user is seated
5952
+ * (omit `userId`) and an email invite needs that user's VERIFIED email to
5953
+ * match (403 `invitation_email_mismatch`); a server key passes `userId`. */
5954
+ accept: (token: string, userId?: string) => Promise<{
5722
5955
  org_id: string;
5956
+ user_id: string;
5723
5957
  role: string;
5724
5958
  }>;
5959
+ /** Server key only: one address's PENDING invitations across your orgs
5960
+ * (newest first, at most 100; never the token). */
5961
+ pendingForEmail: (email: string) => Promise<Array<{
5962
+ invite_id: string;
5963
+ org_id: string;
5964
+ org_name?: string;
5965
+ org_slug?: string;
5966
+ email: string;
5967
+ role: string;
5968
+ created_at?: string;
5969
+ expires_at?: string;
5970
+ }>>;
5725
5971
  revoke: (inviteId: string) => Promise<void>;
5726
5972
  /** List an org's pending invitations. */
5727
5973
  list: (orgId: string) => Promise<Array<{
@@ -5891,7 +6137,18 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5891
6137
  checksum_sha256?: string | null;
5892
6138
  expires_at?: string | null;
5893
6139
  }>;
5894
- downloadUrl: (objectId: string) => Promise<string>;
6140
+ /** Mint a short-lived presigned GET. Options:
6141
+ * `disposition: 'inline'` opens a PDF (or an image, ICO, audio/video) in
6142
+ * the browser instead of downloading it — html/svg/js and every other
6143
+ * type stay attachments whatever you ask; `'attachment'` forces a
6144
+ * download; omitted = raster images inline, everything else attachment.
6145
+ * `filename` sets the name the browser saves (sanitised server-side:
6146
+ * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
6147
+ * RFC 6266 `filename*`), default the upload's filename. */
6148
+ downloadUrl: (objectId: string, opts?: {
6149
+ disposition?: "inline" | "attachment";
6150
+ filename?: string;
6151
+ }) => Promise<string>;
5895
6152
  /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
5896
6153
  * — a gallery page costs one request, not one per image. `urls[]` keeps
5897
6154
  * your order (duplicates collapse); an id that is unknown, someone else's
@@ -6080,7 +6337,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6080
6337
  query: string;
6081
6338
  top_k?: number;
6082
6339
  mode?: "hybrid" | "vector" | "keyword";
6083
- filter?: Record<string, unknown>;
6340
+ filter?: SearchFilter;
6084
6341
  rrf_k?: number;
6085
6342
  vector?: number[];
6086
6343
  rerank?: boolean;
@@ -6432,7 +6689,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6432
6689
  collection?: string;
6433
6690
  template?: string;
6434
6691
  top_k?: number;
6435
- filter?: Record<string, unknown>;
6692
+ filter?: SearchFilter;
6436
6693
  mode?: "hybrid" | "vector" | "keyword";
6437
6694
  provider?: string;
6438
6695
  model?: string;
@@ -6449,7 +6706,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6449
6706
  collection?: string;
6450
6707
  template?: string;
6451
6708
  top_k?: number;
6452
- filter?: Record<string, unknown>;
6709
+ filter?: SearchFilter;
6453
6710
  mode?: "hybrid" | "vector" | "keyword";
6454
6711
  provider?: string;
6455
6712
  model?: string;
@@ -6471,7 +6728,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6471
6728
  query: string;
6472
6729
  collection?: string;
6473
6730
  top_k?: number;
6474
- filter?: Record<string, unknown>;
6731
+ filter?: SearchFilter;
6475
6732
  mode?: "hybrid" | "vector" | "keyword";
6476
6733
  rerank?: boolean;
6477
6734
  boosts?: Record<string, unknown>;
@@ -7093,4 +7350,6 @@ export interface AuthImportResult {
7093
7350
  updated: number;
7094
7351
  kept: number;
7095
7352
  skipped: number;
7353
+ /** social sign-in links (users[].identities) created by this call */
7354
+ identities_linked?: number;
7096
7355
  }
package/dist/index.js CHANGED
@@ -92,6 +92,14 @@ const B64URL = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_
92
92
  * schedules the refresh); undefined for an opaque or malformed token. No
93
93
  * atob: the SDK also runs on React Native builds that lack it. */
94
94
  function sessionLifetimeSeconds(token) {
95
+ const p = jwtPayloadUnverified(token);
96
+ if (p && typeof p.iat === 'number' && typeof p.exp === 'number' && p.exp > p.iat)
97
+ return p.exp - p.iat;
98
+ return undefined;
99
+ }
100
+ /** A session JWT's payload, read WITHOUT verification (display/scheduling
101
+ * only — the edge verifies); undefined for an opaque or malformed token. */
102
+ function jwtPayloadUnverified(token) {
95
103
  const parts = token.split('.');
96
104
  if (parts.length !== 3 || !parts[1] || parts[1].length > 8192)
97
105
  return undefined;
@@ -110,13 +118,26 @@ function sessionLifetimeSeconds(token) {
110
118
  }
111
119
  }
112
120
  try {
121
+ // byte-per-char decode: the claims read here (iat/exp/org) are ASCII
113
122
  const p = JSON.parse(json);
114
- if (typeof p.iat === 'number' && typeof p.exp === 'number' && p.exp > p.iat)
115
- return p.exp - p.iat;
123
+ if (p && typeof p === 'object' && !Array.isArray(p))
124
+ return p;
116
125
  }
117
126
  catch { /* not a JWT payload */ }
118
127
  return undefined;
119
128
  }
129
+ function sessionOrgOf(token) {
130
+ const org = token ? jwtPayloadUnverified(token)?.org : undefined;
131
+ if (!org || typeof org !== 'object')
132
+ return null;
133
+ const o = org;
134
+ if (typeof o.id !== 'string' || typeof o.role !== 'string')
135
+ return null;
136
+ return {
137
+ id: o.id, role: o.role,
138
+ perms: Array.isArray(o.perms) ? o.perms.filter((x) => typeof x === 'string') : [],
139
+ };
140
+ }
120
141
  const DEFAULT_BASE = 'https://api.vxil.com';
121
142
  /** Normalize the `expand` option to the `$expand` query value: a comma-joined
122
143
  * list (the server's spelling), or `undefined` when nothing is expanded so the
@@ -225,6 +246,10 @@ export class Vxil {
225
246
  /** The end-user session token threaded as `X-Vxil-End-User` when set (end-user
226
247
  * mode). Undefined ⇒ no header ⇒ server-caller mode (unchanged). */
227
248
  endUserToken;
249
+ /** The end-user session pair (`endUserSession`), when the client holds one:
250
+ * replaced in place by a `session_stale` recovery or `switchOrg`. */
251
+ endUserPair;
252
+ onSessionChange;
228
253
  /** The ONE path every request takes: retry + timeout + hooks around
229
254
  * `fetchImpl`. With none of the three configured it is a single fetch. */
230
255
  transport;
@@ -237,7 +262,9 @@ export class Vxil {
237
262
  this.fetchImpl = opts.fetch ?? fetch;
238
263
  this.apiVersion = opts.apiVersion ?? 'v1';
239
264
  this.apiVersions = opts.apiVersions ?? {};
240
- this.endUserToken = opts.endUserToken;
265
+ this.endUserPair = opts.endUserSession?.token ? { ...opts.endUserSession } : undefined;
266
+ this.endUserToken = this.endUserPair?.token ?? opts.endUserToken;
267
+ this.onSessionChange = opts.onSessionChange;
241
268
  this.retryOpts = opts.retry;
242
269
  this.timeoutMs = opts.timeoutMs;
243
270
  this.hooks = opts.hooks;
@@ -260,8 +287,15 @@ export class Vxil {
260
287
  * client, mirroring how the edge threads the verified principal. The base
261
288
  * URL, api key, fetch impl, version pins and the retry/timeout/hooks options
262
289
  * are inherited unchanged; only the end-user token is (re)set. Pass a falsy token to get back a server-mode
263
- * client (drops the header). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
264
- asEndUser(endUserToken) {
290
+ * client (drops the header). Pass the whole session PAIR (`AuthSession`)
291
+ * instead of the bare token to let the client recover from
292
+ * `401 session_stale` and `switchOrg` on its own (see `endUserSession`);
293
+ * `opts.onSessionChange` then receives each pair it rotates (default: this
294
+ * client's own). See https://vxil.com/docs/guide/09-security-and-multitenancy. */
295
+ asEndUser(endUser, opts = {}) {
296
+ const pair = endUser && typeof endUser === 'object' ? endUser : undefined;
297
+ const endUserToken = pair ? pair.token : endUser;
298
+ const onSessionChange = opts.onSessionChange ?? this.onSessionChange;
265
299
  return new Vxil({
266
300
  apiKey: this.key,
267
301
  baseUrl: this.base,
@@ -272,8 +306,76 @@ export class Vxil {
272
306
  ...(this.timeoutMs !== undefined ? { timeoutMs: this.timeoutMs } : {}),
273
307
  ...(this.hooks ? { hooks: this.hooks } : {}),
274
308
  ...(endUserToken ? { endUserToken } : {}),
309
+ ...(pair?.token ? { endUserSession: pair } : {}),
310
+ ...(onSessionChange ? { onSessionChange } : {}),
275
311
  });
276
312
  }
313
+ /** Adopt a rotated end-user pair when it replaces the one this client sends
314
+ * (a no-op for a pair this client does not hold), then tell the app. */
315
+ async adoptSession(old, fresh, info) {
316
+ if (this.endUserToken !== old.token || fresh.token === old.token)
317
+ return;
318
+ this.endUserToken = fresh.token;
319
+ this.endUserPair = { ...fresh };
320
+ await this.onSessionChange?.(fresh, info);
321
+ }
322
+ /** The edge answered `401 session_stale` — force ONE
323
+ * rotation of the held pair (no near-expiry check; the stale token stays on
324
+ * the request, which the edge admits on the refresh route only). Concurrent
325
+ * stale requests share the rotation through the process-wide cache.
326
+ * false = nothing to rotate with (no pair held) or the rotation failed. */
327
+ async recoverStale() {
328
+ const pair = this.endUserPair;
329
+ if (!pair?.refresh_token || this.endUserToken !== pair.token)
330
+ return false;
331
+ const now = Date.now();
332
+ const key = `${this.base}\n${pair.refresh_token}`;
333
+ let info = { reason: 'session_stale' };
334
+ let entry = refreshRotations.get(key);
335
+ if (!entry || entry.until <= now) {
336
+ sweepRefreshCaches(now);
337
+ const fresh = {
338
+ session: this.call('POST', '/v1/auth/sessions/refresh', { refresh_token: pair.refresh_token }, {}, false).then((r) => {
339
+ info = {
340
+ reason: 'session_stale',
341
+ ...(r.data.org !== undefined ? { org: r.data.org } : {}),
342
+ ...(r.data.org_unavailable === true ? { org_unavailable: true } : {}),
343
+ };
344
+ return r.data.session;
345
+ }),
346
+ until: Number.POSITIVE_INFINITY,
347
+ };
348
+ fresh.session.then((s) => {
349
+ fresh.until = Date.now() + ENSURE_FRESH_GRACE_MS;
350
+ if (s.refresh_token)
351
+ refreshJustMinted.set(`${this.base}\n${s.refresh_token}`, fresh.until);
352
+ }, () => { if (refreshRotations.get(key) === fresh)
353
+ refreshRotations.delete(key); });
354
+ refreshRotations.set(key, fresh);
355
+ entry = fresh;
356
+ }
357
+ let session;
358
+ try {
359
+ session = await entry.session;
360
+ }
361
+ catch {
362
+ return false;
363
+ }
364
+ await this.adoptSession(pair, session, info);
365
+ return this.endUserToken === session.token;
366
+ }
367
+ /** The session_stale test: ONLY the edge's own 401 envelope (a feature never
368
+ * answers this code at top level). */
369
+ static isSessionStale(status, text) {
370
+ if (status !== 401 || !text.includes('session_stale'))
371
+ return false;
372
+ try {
373
+ return JSON.parse(text).error?.code === 'session_stale';
374
+ }
375
+ catch {
376
+ return false;
377
+ }
378
+ }
277
379
  /** Build the versioned request path — the ONE place a wire path is finalized.
278
380
  * Every request (call(), audit.export, the fn proxy) routes through here, so
279
381
  * the per-feature/global major pin applies uniformly. Default → unchanged
@@ -348,7 +450,7 @@ export class Vxil {
348
450
  // envelope), so bypass call()'s unwrap — read the body directly, like
349
451
  // audit.export. Errors still surface as VxilError.
350
452
  return async (payload, opts) => {
351
- const { response: res, text } = await this.transport.send(`${this.base}${this.path(`/v1/fn/${encodeURIComponent(prop)}`)}`, {
453
+ const send = () => this.transport.send(`${this.base}${this.path(`/v1/fn/${encodeURIComponent(prop)}`)}`, {
352
454
  method: 'POST',
353
455
  headers: {
354
456
  authorization: `Bearer ${this.key}`, ...this.authHeaders(), 'content-type': 'application/json',
@@ -358,6 +460,13 @@ export class Vxil {
358
460
  },
359
461
  body: JSON.stringify(payload ?? {}),
360
462
  });
463
+ let { response: res, text } = await send();
464
+ // session_stale: rotate the held pair once (the next call works);
465
+ // re-invoke only with an idempotencyKey — a function's own error
466
+ // body could relay the code after it already ran side effects.
467
+ if (Vxil.isSessionStale(res.status, text) && await this.recoverStale() && opts?.idempotencyKey) {
468
+ ({ response: res, text } = await send());
469
+ }
361
470
  if (!res.ok) {
362
471
  // A function answers its OWN error body: the platform envelope
363
472
  // `{ error: { code, message } }`, or a bare string code
@@ -397,8 +506,10 @@ export class Vxil {
397
506
  };
398
507
  },
399
508
  });
400
- async call(method, path, body, headers = {}) {
401
- const { response: res, text } = await this.transport.send(`${this.base}${this.path(path)}`, {
509
+ async call(method, path, body, headers = {},
510
+ /** false on the recovery refresh itself (no recursion). */
511
+ staleRetry = true) {
512
+ const send = () => this.transport.send(`${this.base}${this.path(path)}`, {
402
513
  method,
403
514
  headers: {
404
515
  authorization: `Bearer ${this.key}`,
@@ -408,6 +519,13 @@ export class Vxil {
408
519
  },
409
520
  ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
410
521
  });
522
+ let { response: res, text } = await send();
523
+ // session_stale: the edge refused BEFORE dispatch, so re-sending is
524
+ // safe for any method. ONE forced refresh, ONE retry; a second
525
+ // session_stale (or no pair to rotate) surfaces to the app.
526
+ if (staleRetry && Vxil.isSessionStale(res.status, text) && await this.recoverStale()) {
527
+ ({ response: res, text } = await send());
528
+ }
411
529
  // An empty body on a 2xx is a valid "no content" success (e.g. 204 from
412
530
  // DELETE/markRead) — never an error. Only parse when there are bytes; a
413
531
  // void-returning caller ignores `data` anyway.
@@ -985,6 +1103,18 @@ export class Vxil {
985
1103
  * sessions only, own devices only, erase self only. `auth:write` still
986
1104
  * satisfies every call. */
987
1105
  auth = {
1106
+ /** The end-user session this client sends (end-user mode), read from its
1107
+ * token WITHOUT verification — for display (the workspace switcher), not
1108
+ * for authorization (the edge verifies). */
1109
+ session: ((vx) => ({
1110
+ /** The org the session acts in (its `org` claim, auth `orgClaims`), or
1111
+ * null: server mode, no membership, the user left the stored org, or
1112
+ * orgs was unreachable at the last refresh. Updates after `switchOrg`
1113
+ * and a `session_stale` recovery. */
1114
+ get org() { return sessionOrgOf(vx.endUserToken); },
1115
+ /** The pair the client holds (`endUserSession`), after any rotation. */
1116
+ get current() { return vx.endUserPair ? { ...vx.endUserPair } : null; },
1117
+ }))(this),
988
1118
  signUp: async (input) => (await this.call('POST', '/v1/auth/sign-up', input)).data,
989
1119
  signIn: async (input) => (await this.call('POST', '/v1/auth/sign-in', input)).data,
990
1120
  /** Magic-link sign-in: vxil mails a single-use link to the address and the
@@ -1108,8 +1238,15 @@ export class Vxil {
1108
1238
  * (e.g. a rehearsal dev backend) is `skipped` / `id_taken`. `oidc_issuer` links each id as that
1109
1239
  * issuer's subject, so an installed app can trade its old session token
1110
1240
  * for a vxil one (`auth.oauth.native('oidc', …)`). One result per id:
1111
- * `created` / `updated` / `kept` / `skipped` + `reason`. `vxil migrate
1112
- * data --with-password-hashes` drives this for you. */
1241
+ * `created` / `updated` / `kept` / `skipped` + `reason`. `identities`
1242
+ * (≤ 8 per user: google / apple / github / facebook + the provider's
1243
+ * subject — Supabase `auth.identities.provider_id`) seeds the social
1244
+ * sign-in links, so the first Google / Apple sign-in after the move lands
1245
+ * on the same user (Apple Hide-My-Email included); like `oidc_issuer`,
1246
+ * only for identities the import creates or still holds, and a subject
1247
+ * already linked stays where it is (`identities_linked` counts the new
1248
+ * ones). `vxil migrate data --with-password-hashes` /
1249
+ * `--with-oauth-identities` drives this for you. */
1113
1250
  import: async (input) => (await this.call('POST', '/v1/auth/users/import', input)).data,
1114
1251
  /** END-USER MODE ONLY (`endUserToken` / `asEndUser`): the signed-in user
1115
1252
  * deep-merges a bounded `attributes` object into its OWN shared identity
@@ -1188,6 +1325,36 @@ export class Vxil {
1188
1325
  refreshRotations.set(key, entry);
1189
1326
  return { session: await entry.session, refreshed: true };
1190
1327
  },
1328
+ /** Workspaces (auth `orgClaims.activeOrg`): make `orgId` the org the
1329
+ * session acts in — a refresh with `org_id`, so the NEW pair carries that
1330
+ * org's claim and later refreshes keep it. `pair` defaults to the pair
1331
+ * this client holds (`endUserSession` / `asEndUser(pair)`); a client
1332
+ * sending that pair's token switches to the new one in place and calls
1333
+ * `onSessionChange`. Store the returned `session` (the old refresh token
1334
+ * is revoked). The user must be a member: 403 `not_a_member`, and
1335
+ * 503 `orgs_unavailable`, leave the session untouched. List the
1336
+ * choices with `vx.orgs.list()`. Needs `@vxil/sdk` 0.25.0 or later on
1337
+ * the client for the `session_stale` recovery that goes with it. */
1338
+ switchOrg: async (orgId, pair) => {
1339
+ const p = pair ?? this.endUserPair;
1340
+ if (!p?.refresh_token) {
1341
+ throw new VxilError(0, 'refresh_token_missing', 'switchOrg: no session pair to rotate.', 'Pass the pair (token + refresh_token) as the second argument, or build the client with endUserSession.');
1342
+ }
1343
+ const expMs = Date.parse(p.expires_at);
1344
+ const keepEndUser = this.endUserToken !== undefined && this.endUserToken === p.token
1345
+ && Number.isFinite(expMs) && expMs - Date.now() >= ENSURE_FRESH_HEADER_MARGIN_MS;
1346
+ const client = this.endUserToken && !keepEndUser ? this.asEndUser(undefined) : this;
1347
+ const r = (await client.call('POST', '/v1/auth/sessions/refresh', { refresh_token: p.refresh_token, org_id: orgId })).data;
1348
+ // the old pair is revoked: a concurrent ensureFresh / stale recovery
1349
+ // still carrying it adopts this pair instead of re-sending it
1350
+ const until = Date.now() + ENSURE_FRESH_GRACE_MS;
1351
+ refreshRotations.set(`${this.base}\n${p.refresh_token}`, { session: Promise.resolve(r.session), until });
1352
+ if (r.session.refresh_token)
1353
+ refreshJustMinted.set(`${this.base}\n${r.session.refresh_token}`, until);
1354
+ const org = r.org ?? null;
1355
+ await this.adoptSession(p, r.session, { reason: 'switch_org', org });
1356
+ return { user_id: r.user_id, session: r.session, org };
1357
+ },
1191
1358
  revoke: async (token) => {
1192
1359
  await this.call('POST', '/v1/auth/sessions/revoke', { token });
1193
1360
  },
@@ -1212,6 +1379,8 @@ export class Vxil {
1212
1379
  list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
1213
1380
  },
1214
1381
  password: {
1382
+ /** Always resolves (anti-enumeration). `captcha_token` is required when
1383
+ * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
1215
1384
  requestReset: async (input) => {
1216
1385
  await this.call('POST', '/v1/auth/password/reset/request', input);
1217
1386
  },
@@ -1219,18 +1388,34 @@ export class Vxil {
1219
1388
  confirmReset: async (input) => {
1220
1389
  await this.call('POST', '/v1/auth/password/reset/confirm', input);
1221
1390
  },
1391
+ /** Change (or set a first) password for a signed-in user. `token` is the
1392
+ * user's CURRENT session. An account with a password sends
1393
+ * `current_password` (wrong → 403 `invalid_credentials`, counts toward
1394
+ * `security.lockout`). An account with none yet (OTP, magic-link or social
1395
+ * sign-up) needs a step-up on this session in the last 300 s instead
1396
+ * (`stepUp.request` / `stepUp.verify`, then pass the rotated token) —
1397
+ * otherwise 403 `step_up_required`. Step-up needs `otp.enabled`; with
1398
+ * OTP off, such a user sets a first password through
1399
+ * `password.requestReset` (the reset email) instead. Every OTHER session is revoked
1400
+ * (reason `password_changed`); the presenting one keeps working. A guest
1401
+ * session is 409 `anonymous_user`. */
1402
+ change: async (input) => (await this.call('POST', '/v1/auth/password/change', input)).data,
1222
1403
  },
1223
1404
  /** Email verification (the flow behind auth config `emailVerification.required`,
1224
1405
  * which makes password sign-in answer 403 `email_not_verified` until the
1225
1406
  * address is confirmed). `request` always resolves (anti-enumeration —
1226
1407
  * a link is mailed only to an existing, unverified user; `redirect_url`
1227
1408
  * is your page that reads `?token=` and calls `confirm`). `confirm` is
1228
- * single-use and expires after 24h. */
1409
+ * single-use and expires after 24h. Pass the session sign-up returned as
1410
+ * `session_token` to keep the password: without the same user's live
1411
+ * session the click proves only the mailbox, so a never-verified
1412
+ * account's password is cleared and its sessions revoked
1413
+ * (`password_cleared: true` — send the user to a password reset). */
1229
1414
  emailVerification: {
1230
1415
  request: async (input) => {
1231
1416
  await this.call('POST', '/v1/auth/email/verify/request', input);
1232
1417
  },
1233
- confirm: async (token) => (await this.call('POST', '/v1/auth/email/verify/confirm', { token })).data,
1418
+ confirm: async (token, opts) => (await this.call('POST', '/v1/auth/email/verify/confirm', opts?.session_token ? { token, session_token: opts.session_token } : { token })).data,
1234
1419
  },
1235
1420
  /** Social sign-in. The web flow: `startUrl` fetches the provider authorize
1236
1421
  * URL with your key (a browser cannot follow the header-carrying 302 of
@@ -1400,6 +1585,18 @@ export class Vxil {
1400
1585
  * unaffected; server keys are never affected. Audited; takes effect on
1401
1586
  * the next write. */
1402
1587
  setWriteRoles: async (collection, roles) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { write_roles: roles ?? [] })).data,
1588
+ /** Set (or clear, with `null`) the collection's WORKSPACE field (guide
1589
+ * ch. 4, "Workspace-scoped collections"): a `string` field on an index
1590
+ * slot (s1–s4) holding the orgs org id. A verified end user then reads and
1591
+ * writes only rows of the session's ACTIVE org, and `writeRoles` match the
1592
+ * active-org role. Server keys are never affected. Changing or clearing a
1593
+ * set one needs `{ allowDestructive: true }` (422 destructive_change_requires_ack). */
1594
+ setOrgField: async (collection, orgField, opts) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { org_field: orgField, ...(opts?.allowDestructive ? { allow_destructive: true } : {}) })).data,
1595
+ /** Set (or clear, with `[]` / `null`) the active-org roles one of which a
1596
+ * verified end user must hold to READ a workspace collection (the built-in
1597
+ * `owner` always passes; empty = any member). Needs an org field. Widening
1598
+ * (clearing or adding a role) needs `{ allowDestructive: true }`. */
1599
+ setOrgReadRoles: async (collection, roles, opts) => (await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { org_read_roles: roles && roles.length ? roles : null, ...(opts?.allowDestructive ? { allow_destructive: true } : {}) })).data,
1403
1600
  /** Set (1..3650 days) or clear (`null`) the collection's RETENTION (guide
1404
1601
  * ch. 4): the nightly platform sweep soft-deletes live items created more
1405
1602
  * than `days` ago — bounded per project per night, no restore, purged at
@@ -1714,7 +1911,9 @@ export class Vxil {
1714
1911
  /** The deployed functions (name, endpoint, bindings, scopes, limits, the
1715
1912
  * runtime each script runs under), `runtime`, the settings a deploy uses
1716
1913
  * now, and `cpuMsCeiling`, the per-invocation CPU limit (ms) the plan
1717
- * gives a function now (its own `limits.cpuMs` can only lower it), and
1914
+ * gives a function now (its own `limits.cpuMs` can only lower it),
1915
+ * `cpuMsDefault`, the CPU (ms) a function declaring no `limits.cpuMs`
1916
+ * gets (50 on a dev project, the ceiling elsewhere), and
1718
1917
  * `enabled`: false while the project's functions are paused as a whole
1719
1918
  * (a Free project on the production workload, a downgrade) — invokes then
1720
1919
  * answer 404. Any authenticated key may read it. (GET /v1/functions) */
@@ -1948,12 +2147,19 @@ export class Vxil {
1948
2147
  const d = (await this.call('GET', `/v1/orgs${s}`)).data;
1949
2148
  return { orgs: d.orgs, next_cursor: d.next_cursor ?? null };
1950
2149
  },
1951
- /** Every org (walks `listPage` at 500 a page), each with `member_count`. */
2150
+ /** Every org (walks `listPage` at 500 a page), each with `member_count`.
2151
+ * In END-USER mode with no `user_id` it lists the SIGNED-IN user's orgs,
2152
+ * each with their `role` — the workspace switcher's read (the id comes
2153
+ * from the session token; with auth `orgClaims.activeOrg` the server
2154
+ * binds the list to the verified caller whatever is sent). */
1952
2155
  list: async (q) => {
2156
+ const self = q?.user_id === undefined && this.endUserToken
2157
+ ? jwtPayloadUnverified(this.endUserToken)?.sub : undefined;
2158
+ const userId = q?.user_id ?? (typeof self === 'string' && self ? self : undefined);
1953
2159
  const out = [];
1954
2160
  let cursor = null;
1955
2161
  do {
1956
- const page = await this.orgs.listPage({ user_id: q?.user_id, limit: 500, cursor });
2162
+ const page = await this.orgs.listPage({ user_id: userId, limit: 500, cursor });
1957
2163
  out.push(...page.orgs);
1958
2164
  cursor = page.next_cursor;
1959
2165
  } while (cursor);
@@ -1970,11 +2176,14 @@ export class Vxil {
1970
2176
  const s = qs({ user_id: userId, permission, resource: opts?.resource || undefined });
1971
2177
  return (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}/check${s}`)).data;
1972
2178
  },
1973
- /** The active-org snapshot auth embeds in session JWTs when the tenant
1974
- * enables auth config `orgClaims` (most-recent membership by joined_at).
2179
+ /** The org snapshot auth embeds in session JWTs when the tenant enables
2180
+ * auth config `orgClaims`: the most recent membership by joined_at — or,
2181
+ * with `orgClaims.activeOrg`, the org the session picked (first sign-in
2182
+ * stores the most recent; `vx.auth.sessions.switchOrg` changes it).
1975
2183
  * EVENTUAL-CONSISTENT for JWTs (recomputed at refresh); use `check` for
1976
- * revocation-grade authz. No membership → org_id null. */
1977
- sessionClaims: async (userId) => (await this.call('GET', `/v1/orgs/session-claims?user_id=${encodeURIComponent(userId)}`)).data,
2184
+ * revocation-grade authz. No membership → org_id null. `opts.orgId`
2185
+ * resolves that org's claim instead (null when not a member). */
2186
+ sessionClaims: async (userId, opts) => (await this.call('GET', `/v1/orgs/session-claims?user_id=${encodeURIComponent(userId)}${opts?.orgId ? `&org_id=${encodeURIComponent(opts.orgId)}` : ''}`)).data,
1978
2187
  /** Read one workspace (incl. `settings`). */
1979
2188
  get: async (orgId) => (await this.call('GET', `/v1/orgs/${encodeURIComponent(orgId)}`)).data,
1980
2189
  /** Update a workspace's name / `settings` JSON. */
@@ -1990,9 +2199,18 @@ export class Vxil {
1990
2199
  },
1991
2200
  },
1992
2201
  invitations: {
1993
- /** invite_token is returned ONCE — your app builds the accept URL. */
1994
- create: async (orgId, email, role) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`, { email, role })).data,
1995
- accept: async (token, userId) => (await this.call('POST', '/v1/orgs/invitations/accept', { token, user_id: userId })).data,
2202
+ /** invite_token is returned ONCE — your app builds the accept URL.
2203
+ * `role`: admin | member | viewer, or a custom role_key defined with
2204
+ * `roles.define` (never owner). Pass `email: null` for a LINK invite —
2205
+ * no email is sent and any signed-in user holding the token may accept. */
2206
+ create: async (orgId, email, role) => (await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/invitations`, email === null ? { role } : { email, role })).data,
2207
+ /** Redeem a token. With an end-user session the signed-in user is seated
2208
+ * (omit `userId`) and an email invite needs that user's VERIFIED email to
2209
+ * match (403 `invitation_email_mismatch`); a server key passes `userId`. */
2210
+ accept: async (token, userId) => (await this.call('POST', '/v1/orgs/invitations/accept', userId === undefined ? { token } : { token, user_id: userId })).data,
2211
+ /** Server key only: one address's PENDING invitations across your orgs
2212
+ * (newest first, at most 100; never the token). */
2213
+ pendingForEmail: async (email) => (await this.call('GET', `/v1/orgs/invitations?email=${encodeURIComponent(email)}`)).data.invitations,
1996
2214
  revoke: async (inviteId) => {
1997
2215
  await this.call('DELETE', `/v1/orgs/invitations/${encodeURIComponent(inviteId)}`);
1998
2216
  },
@@ -2085,7 +2303,23 @@ export class Vxil {
2085
2303
  * the bytes hash differently, 409 `checksum_unverified` if the store
2086
2304
  * reports no checksum (the object stays pending either way). */
2087
2305
  complete: async (objectId) => (await this.call('POST', `/v1/files/${encodeURIComponent(objectId)}/complete`)).data,
2088
- downloadUrl: async (objectId) => (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url`)).data.download_url,
2306
+ /** Mint a short-lived presigned GET. Options:
2307
+ * `disposition: 'inline'` opens a PDF (or an image, ICO, audio/video) in
2308
+ * the browser instead of downloading it — html/svg/js and every other
2309
+ * type stay attachments whatever you ask; `'attachment'` forces a
2310
+ * download; omitted = raster images inline, everything else attachment.
2311
+ * `filename` sets the name the browser saves (sanitised server-side:
2312
+ * control/bidi characters dropped, `/` → `_`, ≤ 200 characters; sent as
2313
+ * RFC 6266 `filename*`), default the upload's filename. */
2314
+ downloadUrl: async (objectId, opts = {}) => {
2315
+ const q = [];
2316
+ if (opts.disposition !== undefined)
2317
+ q.push(`disposition=${encodeURIComponent(opts.disposition)}`);
2318
+ if (opts.filename !== undefined)
2319
+ q.push(`filename=${encodeURIComponent(opts.filename)}`);
2320
+ const qs = q.join('&');
2321
+ return (await this.call('GET', `/v1/files/${encodeURIComponent(objectId)}/download-url${qs ? `?${qs}` : ''}`)).data.download_url;
2322
+ },
2089
2323
  /** Mint up to 100 presigned GETs in ONE call (`GET /v1/files/download-urls`)
2090
2324
  * — a gallery page costs one request, not one per image. `urls[]` keeps
2091
2325
  * your order (duplicates collapse); an id that is unknown, someone else's
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.24.0",
3
+ "version": "0.25.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",