@vxil/sdk 0.25.0 → 0.26.1
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 +127 -25
- package/dist/index.js +54 -13
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -1073,6 +1073,10 @@ export interface FileObject {
|
|
|
1073
1073
|
/** When the object expires (null = never). An expired object is no longer
|
|
1074
1074
|
* listed and answers 404, even before the sweep deletes it. */
|
|
1075
1075
|
expires_at?: string | null;
|
|
1076
|
+
/** The owning workspace (orgs `org_id`) — present only on a workspace object. */
|
|
1077
|
+
org_id?: string;
|
|
1078
|
+
/** The uploader; null for a workspace object whose uploader was erased. */
|
|
1079
|
+
end_user_id?: string | null;
|
|
1076
1080
|
}
|
|
1077
1081
|
/** `files.createUploadUrl` answer. */
|
|
1078
1082
|
export interface FileUploadUrl {
|
|
@@ -1087,6 +1091,8 @@ export interface FileUploadUrl {
|
|
|
1087
1091
|
* signed into the URL: `content-type`, plus `x-amz-checksum-sha256` when
|
|
1088
1092
|
* the request declared `checksum_sha256`. */
|
|
1089
1093
|
upload_headers?: Record<string, string>;
|
|
1094
|
+
/** The owning workspace — present only for a workspace upload (`org: true` / `org_id`). */
|
|
1095
|
+
org_id?: string;
|
|
1090
1096
|
}
|
|
1091
1097
|
/** `files.usage` answer. */
|
|
1092
1098
|
export interface FilesUsage {
|
|
@@ -1174,6 +1180,13 @@ export interface SearchCollection {
|
|
|
1174
1180
|
collection: string;
|
|
1175
1181
|
dimensions: number;
|
|
1176
1182
|
backend: string;
|
|
1183
|
+
/** The keyword lane's normaliser ('none' = exact lexemes). */
|
|
1184
|
+
keyword_normalize?: 'arabic' | 'none';
|
|
1185
|
+
/** true when this call turned the fold ON for an existing collection:
|
|
1186
|
+
* re-ingest its documents (or reset its cms sync) so old chunks fold too. */
|
|
1187
|
+
keyword_reindex_required?: boolean;
|
|
1188
|
+
/** present (true) on a workspace-scoped collection (`org_scoped: true` at create) */
|
|
1189
|
+
org_scoped?: true;
|
|
1177
1190
|
}
|
|
1178
1191
|
/** A document row in a collection listing (GET …/documents). */
|
|
1179
1192
|
export interface SearchDocument {
|
|
@@ -1184,11 +1197,16 @@ export interface SearchDocument {
|
|
|
1184
1197
|
chunks: number;
|
|
1185
1198
|
metadata: Record<string, unknown>;
|
|
1186
1199
|
created_at: string;
|
|
1200
|
+
/** the document's workspace — present only in an orgScoped collection */
|
|
1201
|
+
org_id?: string;
|
|
1187
1202
|
}
|
|
1188
1203
|
/** One ingest input: chunk text OR bring-your-own precomputed vectors. */
|
|
1189
1204
|
export interface SearchIngestInput {
|
|
1190
1205
|
doc_id: string;
|
|
1191
1206
|
user_id?: string;
|
|
1207
|
+
/** orgScoped collections: the document's workspace. REQUIRED with a server
|
|
1208
|
+
* key; an end-user session always writes into its active workspace. */
|
|
1209
|
+
org_id?: string;
|
|
1192
1210
|
source_file?: string;
|
|
1193
1211
|
/** vxil chunks + embeds this. Omit when supplying `chunks`/`vector`. */
|
|
1194
1212
|
text?: string;
|
|
@@ -1528,6 +1546,29 @@ export type PaymentsCreditTypeChoice = {
|
|
|
1528
1546
|
credit_types: string[];
|
|
1529
1547
|
credit_type?: never;
|
|
1530
1548
|
};
|
|
1549
|
+
/** WORKSPACE BILLING (2026-10-12): who a payments READ is about. A string is
|
|
1550
|
+
* a user id (unchanged). `{ org_id }` (server key) is the workspace subject
|
|
1551
|
+
* `org:<org_id>` — a subscription / purchase whose provider checkout carried
|
|
1552
|
+
* `vxil_org_id` folds there. `{ subject: 'org' }` (thin-client key) is the
|
|
1553
|
+
* signed-in user's ACTIVE workspace (`auth.orgClaims.activeOrg`; any member
|
|
1554
|
+
* reads it) — 403 `org_required` without one, and a thin client can never
|
|
1555
|
+
* name another workspace (403 `other_org`). */
|
|
1556
|
+
export type PaymentsSubject = string | {
|
|
1557
|
+
user_id: string;
|
|
1558
|
+
} | {
|
|
1559
|
+
org_id: string;
|
|
1560
|
+
} | {
|
|
1561
|
+
subject: 'org';
|
|
1562
|
+
};
|
|
1563
|
+
/** WORKSPACE BILLING: a server-only payments body names its subject by
|
|
1564
|
+
* `user_id` OR `org_id` (the workspace subject `org:<org_id>`), never both. */
|
|
1565
|
+
export type PaymentsSubjectBody = {
|
|
1566
|
+
user_id: string;
|
|
1567
|
+
org_id?: never;
|
|
1568
|
+
} | {
|
|
1569
|
+
org_id: string;
|
|
1570
|
+
user_id?: never;
|
|
1571
|
+
};
|
|
1531
1572
|
/** `POST /v1/payments/credits/consume` → `data`. */
|
|
1532
1573
|
export interface PaymentsConsumeResult {
|
|
1533
1574
|
balance_after: number;
|
|
@@ -4308,7 +4349,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4308
4349
|
* a taken address surfaces at `verify` as 409 `email_in_use`. A guest
|
|
4309
4350
|
* session is 409 `anonymous_user` — guests use `anonymous.link`. Shares
|
|
4310
4351
|
* the OTP knobs (cooldown → 429 `otp_rate_limited`, attempts, TTL,
|
|
4311
|
-
* `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`.
|
|
4352
|
+
* `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`.
|
|
4353
|
+
* A completed change mails a security notice to the OLD address (new
|
|
4354
|
+
* address masked; its language is the user's stored `attributes.locale`,
|
|
4355
|
+
* else `verify`'s optional `locale`; no mute preference suppresses it). With
|
|
4356
|
+
* the auth config's `security.emailChangeStepUp: true`, `request` answers
|
|
4357
|
+
* 403 `step_up_required` unless this session passed `auth.stepUp` in the
|
|
4358
|
+
* last 300 s — retry with the rotated token. */
|
|
4312
4359
|
email: {
|
|
4313
4360
|
change: {
|
|
4314
4361
|
request: (input: {
|
|
@@ -4323,6 +4370,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4323
4370
|
token: string;
|
|
4324
4371
|
new_email: string;
|
|
4325
4372
|
code: string;
|
|
4373
|
+
locale?: string;
|
|
4326
4374
|
}) => Promise<{
|
|
4327
4375
|
user_id: string;
|
|
4328
4376
|
email: string;
|
|
@@ -4501,8 +4549,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4501
4549
|
}>>;
|
|
4502
4550
|
};
|
|
4503
4551
|
password: {
|
|
4504
|
-
/** Always resolves (anti-enumeration). `captcha_token` is required
|
|
4505
|
-
* the tenant set `security.
|
|
4552
|
+
/** Always resolves (anti-enumeration). `captcha_token` is required only
|
|
4553
|
+
* when the tenant set BOTH `security.captchaOnReset: true` and
|
|
4554
|
+
* `security.captchaSecretRef` (403 `captcha_failed`). */
|
|
4506
4555
|
requestReset: (input: {
|
|
4507
4556
|
email: string;
|
|
4508
4557
|
redirect_url: string;
|
|
@@ -4615,7 +4664,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
4615
4664
|
* an Apple "Hide My Email" relay address on an OTP account. Idempotent
|
|
4616
4665
|
* for an identity this user already holds; 409 `oauth_identity_linked`
|
|
4617
4666
|
* when another user holds it; 401 `invalid_session` / 409
|
|
4618
|
-
* `anonymous_user` for an unknown or guest session
|
|
4667
|
+
* `anonymous_user` for an unknown or guest session; 409
|
|
4668
|
+
* `email_unverified` (verify the address first) or `password_unproven`
|
|
4669
|
+
* (complete a password reset, or step up then `password/change`) on a
|
|
4670
|
+
* password account, unless the provider-verified address is its own. */
|
|
4619
4671
|
link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
|
|
4620
4672
|
session_token: string;
|
|
4621
4673
|
id_token?: string;
|
|
@@ -6116,9 +6168,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6116
6168
|
* on the PUT) and kept with the upload: `complete` compares it with the
|
|
6117
6169
|
* SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
|
|
6118
6170
|
* they differ, 409 `checksum_unverified` when the store reports none —
|
|
6119
|
-
* and on success answers the verified `checksum_sha256`.
|
|
6171
|
+
* and on success answers the verified `checksum_sha256`.
|
|
6172
|
+
* Workspace files: `org: true` (end-user mode) makes the
|
|
6173
|
+
* session's ACTIVE org own the object — every member of that org can
|
|
6174
|
+
* list (`list({ scope: 'org' })`) and read it, it survives the uploader's
|
|
6175
|
+
* erasure, and deleting the org removes it. A server key names `org_id`. */
|
|
6120
6176
|
createUploadUrl: (input: {
|
|
6121
6177
|
user_id?: string;
|
|
6178
|
+
org?: boolean;
|
|
6179
|
+
org_id?: string;
|
|
6122
6180
|
filename: string;
|
|
6123
6181
|
content_type: string;
|
|
6124
6182
|
size_bytes: number;
|
|
@@ -6168,10 +6226,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6168
6226
|
}>;
|
|
6169
6227
|
expires_in: number;
|
|
6170
6228
|
}>;
|
|
6229
|
+
/** List objects. End-user mode: your PERSONAL files, or `scope: 'org'`
|
|
6230
|
+
* for the active org's WORKSPACE files (403 `org_required` without an
|
|
6231
|
+
* active org). Server key: `user_id` / `org_id` filters. */
|
|
6171
6232
|
list: (q?: {
|
|
6172
6233
|
user_id?: string;
|
|
6173
6234
|
cursor?: string;
|
|
6174
6235
|
limit?: number;
|
|
6236
|
+
scope?: "org";
|
|
6237
|
+
org_id?: string;
|
|
6175
6238
|
}) => Promise<{
|
|
6176
6239
|
files: FileObject[];
|
|
6177
6240
|
next_cursor: string | null;
|
|
@@ -6297,12 +6360,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6297
6360
|
createCollection: (input: {
|
|
6298
6361
|
collection: string;
|
|
6299
6362
|
dimensions?: number;
|
|
6363
|
+
/** Workspace-scoped: every document carries an org id and every end-user
|
|
6364
|
+
* read is filtered to the session's active workspace (a server-key query
|
|
6365
|
+
* must pass `org_id`). Immutable after creation. */
|
|
6366
|
+
org_scoped?: boolean;
|
|
6300
6367
|
embed?: {
|
|
6301
6368
|
provider?: "byov" | "mock" | "openai" | "cohere";
|
|
6302
6369
|
model?: string;
|
|
6303
6370
|
apiKeyRef?: string;
|
|
6304
6371
|
dimensions?: number;
|
|
6305
6372
|
};
|
|
6373
|
+
/** Keyword-lane normaliser. 'arabic' folds alef variants (أ إ آ ٱ → ا),
|
|
6374
|
+
* ى → ي, ة → ه and strips tashkeel/tatweel at index AND query time (no
|
|
6375
|
+
* fuzzy matching). Omitted = keep the current setting; 'none' turns it
|
|
6376
|
+
* off. On an EXISTING collection, send `{ collection, keywordNormalize }`
|
|
6377
|
+
* WITHOUT `embed` to change only the fold (the stored embed config and
|
|
6378
|
+
* dimensions are kept); a call with `embed` replaces the embed setup.
|
|
6379
|
+
* Turning it on for a populated collection needs a re-ingest
|
|
6380
|
+
* (`keyword_reindex_required`). */
|
|
6381
|
+
keywordNormalize?: "arabic" | "none";
|
|
6306
6382
|
}) => Promise<SearchCollection>;
|
|
6307
6383
|
/** List the tenant's collections (with per-collection document counts). */
|
|
6308
6384
|
listCollections: () => Promise<Array<{
|
|
@@ -6312,9 +6388,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6312
6388
|
provider?: string;
|
|
6313
6389
|
documents?: number;
|
|
6314
6390
|
created_at?: string;
|
|
6391
|
+
keyword_normalize?: "arabic" | "none";
|
|
6315
6392
|
/** true when the embed config pinned from the default differs from the
|
|
6316
6393
|
* current default (an explicit embed override is never flagged). */
|
|
6317
6394
|
embed_cfg_stale?: boolean;
|
|
6395
|
+
/** present (true) on a workspace-scoped collection */
|
|
6396
|
+
org_scoped?: true;
|
|
6318
6397
|
}>>;
|
|
6319
6398
|
/** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
|
|
6320
6399
|
ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
|
|
@@ -6341,6 +6420,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6341
6420
|
rrf_k?: number;
|
|
6342
6421
|
vector?: number[];
|
|
6343
6422
|
rerank?: boolean;
|
|
6423
|
+
/** orgScoped collections: the workspace to search — REQUIRED with a
|
|
6424
|
+
* server key (422 without); end-user sessions search their active one. */
|
|
6425
|
+
org_id?: string;
|
|
6344
6426
|
}) => Promise<SearchQueryResult>;
|
|
6345
6427
|
/** Embedding-token + query + rerank counts since a timestamp (default 30 days). */
|
|
6346
6428
|
usage: (q?: {
|
|
@@ -6698,6 +6780,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6698
6780
|
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6699
6781
|
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6700
6782
|
min_similarity?: number;
|
|
6783
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6784
|
+
org_id?: string;
|
|
6701
6785
|
}) => Promise<RagAnswer>;
|
|
6702
6786
|
/** Streamed grounded answer: citations + the channel handle up front, tokens
|
|
6703
6787
|
* over the realtime channel. */
|
|
@@ -6715,6 +6799,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6715
6799
|
/** Drop chunks whose cosine `similarity` to the query is below this
|
|
6716
6800
|
* (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
|
|
6717
6801
|
min_similarity?: number;
|
|
6802
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6803
|
+
org_id?: string;
|
|
6718
6804
|
}) => Promise<RagStreamHandle>;
|
|
6719
6805
|
/** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
|
|
6720
6806
|
* would ground on, with rerank + metadata boosts applied — no generation,
|
|
@@ -6734,6 +6820,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6734
6820
|
boosts?: Record<string, unknown>;
|
|
6735
6821
|
min_score?: number;
|
|
6736
6822
|
min_similarity?: number;
|
|
6823
|
+
/** a server key's workspace for an orgScoped collection (end users: their active one) */
|
|
6824
|
+
org_id?: string;
|
|
6737
6825
|
}) => Promise<RagSearchResult>;
|
|
6738
6826
|
/** Ingest into the backing vector-search collection (chunk → embed → index). */
|
|
6739
6827
|
ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
|
|
@@ -6863,15 +6951,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6863
6951
|
* higher tier's earlier end; access does not dip (a lapsed winner re-folds
|
|
6864
6952
|
* on read and the lower tier takes over), but a client that CACHES `until`
|
|
6865
6953
|
* will show an early expiry — re-read instead of trusting a cached value
|
|
6866
|
-
* past it.
|
|
6867
|
-
|
|
6954
|
+
* past it.
|
|
6955
|
+
*
|
|
6956
|
+
* WORKSPACE BILLING: pass `{ org_id }` (server) or `{ subject: 'org' }`
|
|
6957
|
+
* (thin client, the active workspace) for a workspace's entitlements. */
|
|
6958
|
+
getEntitlements: (userId: PaymentsSubject, opts?: {
|
|
6868
6959
|
quota?: string;
|
|
6869
6960
|
creditType?: string;
|
|
6870
6961
|
}) => Promise<PaymentsEntitlementView>;
|
|
6871
6962
|
/** Boolean gate: does the user hold `entitlement`? Returns granted + its
|
|
6872
6963
|
* source (subscription/tier) + the resolved tier, plus `until` (how long
|
|
6873
|
-
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
6874
|
-
|
|
6964
|
+
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
6965
|
+
* `{ org_id }` / `{ subject: 'org' }` check a workspace (PaymentsSubject). */
|
|
6966
|
+
hasEntitlement: (userId: PaymentsSubject, entitlement: string) => Promise<{
|
|
6875
6967
|
granted: boolean;
|
|
6876
6968
|
source: string | null;
|
|
6877
6969
|
tier: string;
|
|
@@ -6880,10 +6972,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6880
6972
|
}>;
|
|
6881
6973
|
/** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
|
|
6882
6974
|
* the resolved tier declares no such quota. Convenience over getEntitlements. */
|
|
6883
|
-
getQuota: (userId:
|
|
6975
|
+
getQuota: (userId: PaymentsSubject, quota: string) => Promise<number | null>;
|
|
6884
6976
|
/** The credit balance for a credit type: balance/held/available (= balance −
|
|
6885
|
-
* held) + the current period_end.
|
|
6886
|
-
|
|
6977
|
+
* held) + the current period_end. `{ org_id }` / `{ subject: 'org' }`
|
|
6978
|
+
* read a workspace's balance (PaymentsSubject). */
|
|
6979
|
+
getBalance: (userId: PaymentsSubject, creditType: string) => Promise<{
|
|
6887
6980
|
credit_type: string;
|
|
6888
6981
|
balance: number;
|
|
6889
6982
|
held: number;
|
|
@@ -6913,8 +7006,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6913
7006
|
* listed in the answer's `parts`; a job hold of a split settles and
|
|
6914
7007
|
* releases every part.
|
|
6915
7008
|
*/
|
|
6916
|
-
consume: (input: PaymentsCreditTypeChoice & {
|
|
6917
|
-
user_id: string;
|
|
7009
|
+
consume: (input: PaymentsCreditTypeChoice & PaymentsSubjectBody & {
|
|
6918
7010
|
amount: number;
|
|
6919
7011
|
/** link this debit to a jobs run_id → provisional hold + auto-reverse. */
|
|
6920
7012
|
job_id?: string;
|
|
@@ -6947,8 +7039,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6947
7039
|
}) => Promise<PaymentsReverseResult>;
|
|
6948
7040
|
/** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
|
|
6949
7041
|
* only ADDS; `amount` must be ≥ 1. */
|
|
6950
|
-
grant: (input: {
|
|
6951
|
-
user_id: string;
|
|
7042
|
+
grant: (input: PaymentsSubjectBody & {
|
|
6952
7043
|
credit_type: string;
|
|
6953
7044
|
amount: number;
|
|
6954
7045
|
period?: string;
|
|
@@ -6961,8 +7052,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6961
7052
|
}>;
|
|
6962
7053
|
/** One-time grant idempotent on `grant_key` (at-most-once across ALL flows,
|
|
6963
7054
|
* not just retries). A repeat with the same key → granted:false. */
|
|
6964
|
-
grantOnce: (input: {
|
|
6965
|
-
user_id: string;
|
|
7055
|
+
grantOnce: (input: PaymentsSubjectBody & {
|
|
6966
7056
|
credit_type: string;
|
|
6967
7057
|
amount: number;
|
|
6968
7058
|
grant_key: string;
|
|
@@ -6971,9 +7061,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
6971
7061
|
granted: boolean;
|
|
6972
7062
|
}>;
|
|
6973
7063
|
/** Recent ledger rows for the user (the audit/trail surface), newest first;
|
|
6974
|
-
* optionally scoped to one credit type.
|
|
6975
|
-
|
|
7064
|
+
* optionally scoped to one credit type. `org_id` (SERVER key only) reads a
|
|
7065
|
+
* workspace's rows instead — the workspace trail lists every member's
|
|
7066
|
+
* consumes, so a thin client gets 403 org_usage_server_only. */
|
|
7067
|
+
usage: (q: ({
|
|
6976
7068
|
user_id: string;
|
|
7069
|
+
} | {
|
|
7070
|
+
org_id: string;
|
|
7071
|
+
}) & {
|
|
6977
7072
|
credit_type?: string;
|
|
6978
7073
|
limit?: number;
|
|
6979
7074
|
}) => Promise<{
|
|
@@ -7019,8 +7114,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7019
7114
|
/** Start a subscription (mock = instant checkout; real providers redirect via
|
|
7020
7115
|
* their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
|
|
7021
7116
|
* ref. Returns the vxil subscription_id + provider sub id + status. */
|
|
7022
|
-
subscribe: (input: {
|
|
7023
|
-
user_id: string;
|
|
7117
|
+
subscribe: (input: PaymentsSubjectBody & {
|
|
7024
7118
|
price_ref: string;
|
|
7025
7119
|
tier?: string;
|
|
7026
7120
|
trial_days?: number;
|
|
@@ -7054,8 +7148,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7054
7148
|
* (the matching session flips to completed, the charge/grant is folded).
|
|
7055
7149
|
* Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
|
|
7056
7150
|
*/
|
|
7057
|
-
createCheckoutSession: (input:
|
|
7151
|
+
createCheckoutSession: (input: (
|
|
7152
|
+
/** WORKSPACE BILLING: `org_id` attributes the purchase to the
|
|
7153
|
+
* workspace (the provider checkout is tagged `vxil_org_id`); a
|
|
7154
|
+
* `user_id` beside it is the PAYER only. */
|
|
7155
|
+
{
|
|
7058
7156
|
user_id: string;
|
|
7157
|
+
org_id?: string;
|
|
7158
|
+
} | {
|
|
7159
|
+
org_id: string;
|
|
7160
|
+
user_id?: string;
|
|
7161
|
+
}) & {
|
|
7059
7162
|
line_items: Array<{
|
|
7060
7163
|
price_ref: string;
|
|
7061
7164
|
quantity?: number;
|
|
@@ -7134,8 +7237,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
|
|
|
7134
7237
|
* charge_refunded (the refund beat the grant — nothing to grant against).
|
|
7135
7238
|
* 422 reserved_idempotency_key when `idempotency_key` starts with
|
|
7136
7239
|
* `purchase:` (the namespace of purchase passes). */
|
|
7137
|
-
grantSubscription: (input: {
|
|
7138
|
-
user_id: string;
|
|
7240
|
+
grantSubscription: (input: PaymentsSubjectBody & {
|
|
7139
7241
|
tier: string;
|
|
7140
7242
|
until?: string | null;
|
|
7141
7243
|
reason: string;
|
package/dist/index.js
CHANGED
|
@@ -138,6 +138,21 @@ function sessionOrgOf(token) {
|
|
|
138
138
|
perms: Array.isArray(o.perms) ? o.perms.filter((x) => typeof x === 'string') : [],
|
|
139
139
|
};
|
|
140
140
|
}
|
|
141
|
+
/** The query members for a PaymentsSubject (insertion order = wire order). */
|
|
142
|
+
function paymentsSubjectQuery(s) {
|
|
143
|
+
if (typeof s === 'string')
|
|
144
|
+
return { user_id: s };
|
|
145
|
+
if ('org_id' in s)
|
|
146
|
+
return { org_id: s.org_id };
|
|
147
|
+
if ('subject' in s)
|
|
148
|
+
return { subject: s.subject };
|
|
149
|
+
return { user_id: s.user_id };
|
|
150
|
+
}
|
|
151
|
+
/** `k=v&…` (no leading `?`) for a PaymentsSubject — a string subject is
|
|
152
|
+
* byte-identical to the old `user_id=${encodeURIComponent(id)}`. */
|
|
153
|
+
function paymentsSubjectPairs(s) {
|
|
154
|
+
return Object.entries(paymentsSubjectQuery(s)).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&');
|
|
155
|
+
}
|
|
141
156
|
const DEFAULT_BASE = 'https://api.vxil.com';
|
|
142
157
|
/** Normalize the `expand` option to the `$expand` query value: a comma-joined
|
|
143
158
|
* list (the server's spelling), or `undefined` when nothing is expanded so the
|
|
@@ -1202,7 +1217,13 @@ export class Vxil {
|
|
|
1202
1217
|
* a taken address surfaces at `verify` as 409 `email_in_use`. A guest
|
|
1203
1218
|
* session is 409 `anonymous_user` — guests use `anonymous.link`. Shares
|
|
1204
1219
|
* the OTP knobs (cooldown → 429 `otp_rate_limited`, attempts, TTL,
|
|
1205
|
-
* `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`.
|
|
1220
|
+
* `test_code` for `otp.testRecipients`) but does NOT need `otp.enabled`.
|
|
1221
|
+
* A completed change mails a security notice to the OLD address (new
|
|
1222
|
+
* address masked; its language is the user's stored `attributes.locale`,
|
|
1223
|
+
* else `verify`'s optional `locale`; no mute preference suppresses it). With
|
|
1224
|
+
* the auth config's `security.emailChangeStepUp: true`, `request` answers
|
|
1225
|
+
* 403 `step_up_required` unless this session passed `auth.stepUp` in the
|
|
1226
|
+
* last 300 s — retry with the rotated token. */
|
|
1206
1227
|
email: {
|
|
1207
1228
|
change: {
|
|
1208
1229
|
request: async (input) => (await this.call('POST', '/v1/auth/email/change/request', input)).data,
|
|
@@ -1379,8 +1400,9 @@ export class Vxil {
|
|
|
1379
1400
|
list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
|
|
1380
1401
|
},
|
|
1381
1402
|
password: {
|
|
1382
|
-
/** Always resolves (anti-enumeration). `captcha_token` is required
|
|
1383
|
-
* the tenant set `security.
|
|
1403
|
+
/** Always resolves (anti-enumeration). `captcha_token` is required only
|
|
1404
|
+
* when the tenant set BOTH `security.captchaOnReset: true` and
|
|
1405
|
+
* `security.captchaSecretRef` (403 `captcha_failed`). */
|
|
1384
1406
|
requestReset: async (input) => {
|
|
1385
1407
|
await this.call('POST', '/v1/auth/password/reset/request', input);
|
|
1386
1408
|
},
|
|
@@ -1465,7 +1487,10 @@ export class Vxil {
|
|
|
1465
1487
|
* an Apple "Hide My Email" relay address on an OTP account. Idempotent
|
|
1466
1488
|
* for an identity this user already holds; 409 `oauth_identity_linked`
|
|
1467
1489
|
* when another user holds it; 401 `invalid_session` / 409
|
|
1468
|
-
* `anonymous_user` for an unknown or guest session
|
|
1490
|
+
* `anonymous_user` for an unknown or guest session; 409
|
|
1491
|
+
* `email_unverified` (verify the address first) or `password_unproven`
|
|
1492
|
+
* (complete a password reset, or step up then `password/change`) on a
|
|
1493
|
+
* password account, unless the provider-verified address is its own. */
|
|
1469
1494
|
link: async (provider, input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, { ...input, link: true })).data,
|
|
1470
1495
|
},
|
|
1471
1496
|
};
|
|
@@ -2294,7 +2319,11 @@ export class Vxil {
|
|
|
2294
2319
|
* on the PUT) and kept with the upload: `complete` compares it with the
|
|
2295
2320
|
* SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
|
|
2296
2321
|
* they differ, 409 `checksum_unverified` when the store reports none —
|
|
2297
|
-
* and on success answers the verified `checksum_sha256`.
|
|
2322
|
+
* and on success answers the verified `checksum_sha256`.
|
|
2323
|
+
* Workspace files: `org: true` (end-user mode) makes the
|
|
2324
|
+
* session's ACTIVE org own the object — every member of that org can
|
|
2325
|
+
* list (`list({ scope: 'org' })`) and read it, it survives the uploader's
|
|
2326
|
+
* erasure, and deleting the org removes it. A server key names `org_id`. */
|
|
2298
2327
|
createUploadUrl: async (input) => (await this.call('POST', '/v1/files/upload-url', input)).data,
|
|
2299
2328
|
/** Confirm the PUT (bytes verified, object → available). Answers the
|
|
2300
2329
|
* object's `expires_at` (null = never) and `checksum_sha256` (hex; null
|
|
@@ -2328,9 +2357,14 @@ export class Vxil {
|
|
|
2328
2357
|
* `inline`. For expo-image, cache on the object id, not the URL:
|
|
2329
2358
|
* `<Image source={{ uri: u.download_url, cacheKey: u.object_id }} />`. */
|
|
2330
2359
|
downloadUrls: async (objectIds) => (await this.call('GET', `/v1/files/download-urls?object_ids=${encodeURIComponent(objectIds.join(','))}`)).data,
|
|
2360
|
+
/** List objects. End-user mode: your PERSONAL files, or `scope: 'org'`
|
|
2361
|
+
* for the active org's WORKSPACE files (403 `org_required` without an
|
|
2362
|
+
* active org). Server key: `user_id` / `org_id` filters. */
|
|
2331
2363
|
list: async (q) => {
|
|
2332
2364
|
const s = qs({
|
|
2333
2365
|
user_id: q?.user_id || undefined,
|
|
2366
|
+
scope: q?.scope || undefined,
|
|
2367
|
+
org_id: q?.org_id || undefined,
|
|
2334
2368
|
cursor: q?.cursor || undefined,
|
|
2335
2369
|
limit: q?.limit || undefined,
|
|
2336
2370
|
});
|
|
@@ -2686,10 +2720,13 @@ export class Vxil {
|
|
|
2686
2720
|
* higher tier's earlier end; access does not dip (a lapsed winner re-folds
|
|
2687
2721
|
* on read and the lower tier takes over), but a client that CACHES `until`
|
|
2688
2722
|
* will show an early expiry — re-read instead of trusting a cached value
|
|
2689
|
-
* past it.
|
|
2723
|
+
* past it.
|
|
2724
|
+
*
|
|
2725
|
+
* WORKSPACE BILLING: pass `{ org_id }` (server) or `{ subject: 'org' }`
|
|
2726
|
+
* (thin client, the active workspace) for a workspace's entitlements. */
|
|
2690
2727
|
getEntitlements: async (userId, opts) => {
|
|
2691
2728
|
const s = qs({
|
|
2692
|
-
|
|
2729
|
+
...paymentsSubjectQuery(userId),
|
|
2693
2730
|
quota: opts?.quota || undefined,
|
|
2694
2731
|
credit_type: opts?.creditType || undefined,
|
|
2695
2732
|
});
|
|
@@ -2697,8 +2734,9 @@ export class Vxil {
|
|
|
2697
2734
|
},
|
|
2698
2735
|
/** Boolean gate: does the user hold `entitlement`? Returns granted + its
|
|
2699
2736
|
* source (subscription/tier) + the resolved tier, plus `until` (how long
|
|
2700
|
-
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
2701
|
-
|
|
2737
|
+
* the answer is good for) and `as_of`. Non-2xx = unknown, never free.
|
|
2738
|
+
* `{ org_id }` / `{ subject: 'org' }` check a workspace (PaymentsSubject). */
|
|
2739
|
+
hasEntitlement: async (userId, entitlement) => (await this.call('GET', `/v1/payments/entitlements/check?${paymentsSubjectPairs(userId)}&entitlement=${encodeURIComponent(entitlement)}`)).data,
|
|
2702
2740
|
/** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
|
|
2703
2741
|
* the resolved tier declares no such quota. Convenience over getEntitlements. */
|
|
2704
2742
|
getQuota: async (userId, quota) => {
|
|
@@ -2707,8 +2745,9 @@ export class Vxil {
|
|
|
2707
2745
|
return typeof v === 'number' ? v : null;
|
|
2708
2746
|
},
|
|
2709
2747
|
/** The credit balance for a credit type: balance/held/available (= balance −
|
|
2710
|
-
* held) + the current period_end.
|
|
2711
|
-
|
|
2748
|
+
* held) + the current period_end. `{ org_id }` / `{ subject: 'org' }`
|
|
2749
|
+
* read a workspace's balance (PaymentsSubject). */
|
|
2750
|
+
getBalance: async (userId, creditType) => (await this.call('GET', `/v1/payments/credits/balance?${paymentsSubjectPairs(userId)}&credit_type=${encodeURIComponent(creditType)}`)).data,
|
|
2712
2751
|
/**
|
|
2713
2752
|
* Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
|
|
2714
2753
|
* (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
|
|
@@ -2752,10 +2791,12 @@ export class Vxil {
|
|
|
2752
2791
|
* not just retries). A repeat with the same key → granted:false. */
|
|
2753
2792
|
grantOnce: async (input) => (await this.call('POST', '/v1/payments/credits/grant-once', input)).data,
|
|
2754
2793
|
/** Recent ledger rows for the user (the audit/trail surface), newest first;
|
|
2755
|
-
* optionally scoped to one credit type.
|
|
2794
|
+
* optionally scoped to one credit type. `org_id` (SERVER key only) reads a
|
|
2795
|
+
* workspace's rows instead — the workspace trail lists every member's
|
|
2796
|
+
* consumes, so a thin client gets 403 org_usage_server_only. */
|
|
2756
2797
|
usage: async (q) => {
|
|
2757
2798
|
const s = qs({
|
|
2758
|
-
|
|
2799
|
+
...paymentsSubjectQuery(q),
|
|
2759
2800
|
credit_type: q.credit_type || undefined,
|
|
2760
2801
|
limit: q.limit || undefined,
|
|
2761
2802
|
});
|
package/package.json
CHANGED