@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.
- package/dist/index.d.ts +280 -21
- package/dist/index.js +257 -23
- 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
|
|
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).
|
|
3167
|
-
|
|
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`. `
|
|
4264
|
-
*
|
|
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
|
|
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),
|
|
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
|
|
5678
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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?:
|
|
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?:
|
|
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?:
|
|
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?:
|
|
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 (
|
|
115
|
-
return p
|
|
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.
|
|
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).
|
|
264
|
-
|
|
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
|
|
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
|
-
|
|
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`. `
|
|
1112
|
-
*
|
|
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),
|
|
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:
|
|
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
|
|
1974
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
1995
|
-
|
|
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
|
-
|
|
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