@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 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 when
4505
- * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
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
- getEntitlements: (userId: string, opts?: {
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
- hasEntitlement: (userId: string, entitlement: string) => Promise<{
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: string, quota: string) => Promise<number | null>;
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
- getBalance: (userId: string, creditType: string) => Promise<{
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
- usage: (q: {
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 when
1383
- * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
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
- user_id: userId,
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
- hasEntitlement: async (userId, entitlement) => (await this.call('GET', `/v1/payments/entitlements/check?user_id=${encodeURIComponent(userId)}&entitlement=${encodeURIComponent(entitlement)}`)).data,
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
- getBalance: async (userId, creditType) => (await this.call('GET', `/v1/payments/credits/balance?user_id=${encodeURIComponent(userId)}&credit_type=${encodeURIComponent(creditType)}`)).data,
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
- user_id: q.user_id,
2799
+ ...paymentsSubjectQuery(q),
2759
2800
  credit_type: q.credit_type || undefined,
2760
2801
  limit: q.limit || undefined,
2761
2802
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.25.0",
3
+ "version": "0.26.1",
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).",