@vxil/sdk 0.25.0 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
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;
@@ -4501,8 +4542,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4501
4542
  }>>;
4502
4543
  };
4503
4544
  password: {
4504
- /** Always resolves (anti-enumeration). `captcha_token` is required when
4505
- * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
4545
+ /** Always resolves (anti-enumeration). `captcha_token` is required only
4546
+ * when the tenant set BOTH `security.captchaOnReset: true` and
4547
+ * `security.captchaSecretRef` (403 `captcha_failed`). */
4506
4548
  requestReset: (input: {
4507
4549
  email: string;
4508
4550
  redirect_url: string;
@@ -4615,7 +4657,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4615
4657
  * an Apple "Hide My Email" relay address on an OTP account. Idempotent
4616
4658
  * for an identity this user already holds; 409 `oauth_identity_linked`
4617
4659
  * when another user holds it; 401 `invalid_session` / 409
4618
- * `anonymous_user` for an unknown or guest session. */
4660
+ * `anonymous_user` for an unknown or guest session; 409
4661
+ * `email_unverified` (verify the address first) or `password_unproven`
4662
+ * (complete a password reset, or step up then `password/change`) on a
4663
+ * password account, unless the provider-verified address is its own. */
4619
4664
  link: (provider: "google" | "apple" | "github" | "facebook" | "mock" | "oidc", input: {
4620
4665
  session_token: string;
4621
4666
  id_token?: string;
@@ -6116,9 +6161,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6116
6161
  * on the PUT) and kept with the upload: `complete` compares it with the
6117
6162
  * SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
6118
6163
  * they differ, 409 `checksum_unverified` when the store reports none —
6119
- * and on success answers the verified `checksum_sha256`. */
6164
+ * and on success answers the verified `checksum_sha256`.
6165
+ * Workspace files: `org: true` (end-user mode) makes the
6166
+ * session's ACTIVE org own the object — every member of that org can
6167
+ * list (`list({ scope: 'org' })`) and read it, it survives the uploader's
6168
+ * erasure, and deleting the org removes it. A server key names `org_id`. */
6120
6169
  createUploadUrl: (input: {
6121
6170
  user_id?: string;
6171
+ org?: boolean;
6172
+ org_id?: string;
6122
6173
  filename: string;
6123
6174
  content_type: string;
6124
6175
  size_bytes: number;
@@ -6168,10 +6219,15 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6168
6219
  }>;
6169
6220
  expires_in: number;
6170
6221
  }>;
6222
+ /** List objects. End-user mode: your PERSONAL files, or `scope: 'org'`
6223
+ * for the active org's WORKSPACE files (403 `org_required` without an
6224
+ * active org). Server key: `user_id` / `org_id` filters. */
6171
6225
  list: (q?: {
6172
6226
  user_id?: string;
6173
6227
  cursor?: string;
6174
6228
  limit?: number;
6229
+ scope?: "org";
6230
+ org_id?: string;
6175
6231
  }) => Promise<{
6176
6232
  files: FileObject[];
6177
6233
  next_cursor: string | null;
@@ -6297,12 +6353,25 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6297
6353
  createCollection: (input: {
6298
6354
  collection: string;
6299
6355
  dimensions?: number;
6356
+ /** Workspace-scoped: every document carries an org id and every end-user
6357
+ * read is filtered to the session's active workspace (a server-key query
6358
+ * must pass `org_id`). Immutable after creation. */
6359
+ org_scoped?: boolean;
6300
6360
  embed?: {
6301
6361
  provider?: "byov" | "mock" | "openai" | "cohere";
6302
6362
  model?: string;
6303
6363
  apiKeyRef?: string;
6304
6364
  dimensions?: number;
6305
6365
  };
6366
+ /** Keyword-lane normaliser. 'arabic' folds alef variants (أ إ آ ٱ → ا),
6367
+ * ى → ي, ة → ه and strips tashkeel/tatweel at index AND query time (no
6368
+ * fuzzy matching). Omitted = keep the current setting; 'none' turns it
6369
+ * off. On an EXISTING collection, send `{ collection, keywordNormalize }`
6370
+ * WITHOUT `embed` to change only the fold (the stored embed config and
6371
+ * dimensions are kept); a call with `embed` replaces the embed setup.
6372
+ * Turning it on for a populated collection needs a re-ingest
6373
+ * (`keyword_reindex_required`). */
6374
+ keywordNormalize?: "arabic" | "none";
6306
6375
  }) => Promise<SearchCollection>;
6307
6376
  /** List the tenant's collections (with per-collection document counts). */
6308
6377
  listCollections: () => Promise<Array<{
@@ -6312,9 +6381,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6312
6381
  provider?: string;
6313
6382
  documents?: number;
6314
6383
  created_at?: string;
6384
+ keyword_normalize?: "arabic" | "none";
6315
6385
  /** true when the embed config pinned from the default differs from the
6316
6386
  * current default (an explicit embed override is never flagged). */
6317
6387
  embed_cfg_stale?: boolean;
6388
+ /** present (true) on a workspace-scoped collection */
6389
+ org_scoped?: true;
6318
6390
  }>>;
6319
6391
  /** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
6320
6392
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -6341,6 +6413,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6341
6413
  rrf_k?: number;
6342
6414
  vector?: number[];
6343
6415
  rerank?: boolean;
6416
+ /** orgScoped collections: the workspace to search — REQUIRED with a
6417
+ * server key (422 without); end-user sessions search their active one. */
6418
+ org_id?: string;
6344
6419
  }) => Promise<SearchQueryResult>;
6345
6420
  /** Embedding-token + query + rerank counts since a timestamp (default 30 days). */
6346
6421
  usage: (q?: {
@@ -6698,6 +6773,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6698
6773
  /** Drop chunks whose cosine `similarity` to the query is below this
6699
6774
  * (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
6700
6775
  min_similarity?: number;
6776
+ /** a server key's workspace for an orgScoped collection (end users: their active one) */
6777
+ org_id?: string;
6701
6778
  }) => Promise<RagAnswer>;
6702
6779
  /** Streamed grounded answer: citations + the channel handle up front, tokens
6703
6780
  * over the realtime channel. */
@@ -6715,6 +6792,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6715
6792
  /** Drop chunks whose cosine `similarity` to the query is below this
6716
6793
  * (-1..1) before grounding; overrides rag config `retrieval.minSimilarity`. */
6717
6794
  min_similarity?: number;
6795
+ /** a server key's workspace for an orgScoped collection (end users: their active one) */
6796
+ org_id?: string;
6718
6797
  }) => Promise<RagStreamHandle>;
6719
6798
  /** Retrieval-only grounding preview (guide ch. 6, rag): the exact chunks `answer`
6720
6799
  * would ground on, with rerank + metadata boosts applied — no generation,
@@ -6734,6 +6813,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6734
6813
  boosts?: Record<string, unknown>;
6735
6814
  min_score?: number;
6736
6815
  min_similarity?: number;
6816
+ /** a server key's workspace for an orgScoped collection (end users: their active one) */
6817
+ org_id?: string;
6737
6818
  }) => Promise<RagSearchResult>;
6738
6819
  /** Ingest into the backing vector-search collection (chunk → embed → index). */
6739
6820
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -6863,15 +6944,19 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6863
6944
  * higher tier's earlier end; access does not dip (a lapsed winner re-folds
6864
6945
  * on read and the lower tier takes over), but a client that CACHES `until`
6865
6946
  * will show an early expiry — re-read instead of trusting a cached value
6866
- * past it. */
6867
- getEntitlements: (userId: string, opts?: {
6947
+ * past it.
6948
+ *
6949
+ * WORKSPACE BILLING: pass `{ org_id }` (server) or `{ subject: 'org' }`
6950
+ * (thin client, the active workspace) for a workspace's entitlements. */
6951
+ getEntitlements: (userId: PaymentsSubject, opts?: {
6868
6952
  quota?: string;
6869
6953
  creditType?: string;
6870
6954
  }) => Promise<PaymentsEntitlementView>;
6871
6955
  /** Boolean gate: does the user hold `entitlement`? Returns granted + its
6872
6956
  * 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<{
6957
+ * the answer is good for) and `as_of`. Non-2xx = unknown, never free.
6958
+ * `{ org_id }` / `{ subject: 'org' }` check a workspace (PaymentsSubject). */
6959
+ hasEntitlement: (userId: PaymentsSubject, entitlement: string) => Promise<{
6875
6960
  granted: boolean;
6876
6961
  source: string | null;
6877
6962
  tier: string;
@@ -6880,10 +6965,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6880
6965
  }>;
6881
6966
  /** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
6882
6967
  * the resolved tier declares no such quota. Convenience over getEntitlements. */
6883
- getQuota: (userId: string, quota: string) => Promise<number | null>;
6968
+ getQuota: (userId: PaymentsSubject, quota: string) => Promise<number | null>;
6884
6969
  /** The credit balance for a credit type: balance/held/available (= balance −
6885
- * held) + the current period_end. */
6886
- getBalance: (userId: string, creditType: string) => Promise<{
6970
+ * held) + the current period_end. `{ org_id }` / `{ subject: 'org' }`
6971
+ * read a workspace's balance (PaymentsSubject). */
6972
+ getBalance: (userId: PaymentsSubject, creditType: string) => Promise<{
6887
6973
  credit_type: string;
6888
6974
  balance: number;
6889
6975
  held: number;
@@ -6913,8 +6999,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6913
6999
  * listed in the answer's `parts`; a job hold of a split settles and
6914
7000
  * releases every part.
6915
7001
  */
6916
- consume: (input: PaymentsCreditTypeChoice & {
6917
- user_id: string;
7002
+ consume: (input: PaymentsCreditTypeChoice & PaymentsSubjectBody & {
6918
7003
  amount: number;
6919
7004
  /** link this debit to a jobs run_id → provisional hold + auto-reverse. */
6920
7005
  job_id?: string;
@@ -6947,8 +7032,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6947
7032
  }) => Promise<PaymentsReverseResult>;
6948
7033
  /** Additive grant (recurring/top-up) — idempotent per Idempotency-Key. A grant
6949
7034
  * only ADDS; `amount` must be ≥ 1. */
6950
- grant: (input: {
6951
- user_id: string;
7035
+ grant: (input: PaymentsSubjectBody & {
6952
7036
  credit_type: string;
6953
7037
  amount: number;
6954
7038
  period?: string;
@@ -6961,8 +7045,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6961
7045
  }>;
6962
7046
  /** One-time grant idempotent on `grant_key` (at-most-once across ALL flows,
6963
7047
  * not just retries). A repeat with the same key → granted:false. */
6964
- grantOnce: (input: {
6965
- user_id: string;
7048
+ grantOnce: (input: PaymentsSubjectBody & {
6966
7049
  credit_type: string;
6967
7050
  amount: number;
6968
7051
  grant_key: string;
@@ -6971,9 +7054,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6971
7054
  granted: boolean;
6972
7055
  }>;
6973
7056
  /** Recent ledger rows for the user (the audit/trail surface), newest first;
6974
- * optionally scoped to one credit type. */
6975
- usage: (q: {
7057
+ * optionally scoped to one credit type. `org_id` (SERVER key only) reads a
7058
+ * workspace's rows instead — the workspace trail lists every member's
7059
+ * consumes, so a thin client gets 403 org_usage_server_only. */
7060
+ usage: (q: ({
6976
7061
  user_id: string;
7062
+ } | {
7063
+ org_id: string;
7064
+ }) & {
6977
7065
  credit_type?: string;
6978
7066
  limit?: number;
6979
7067
  }) => Promise<{
@@ -7019,8 +7107,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7019
7107
  /** Start a subscription (mock = instant checkout; real providers redirect via
7020
7108
  * their own flow). `tier` keys the tierMap fold; `price_ref` is your catalog
7021
7109
  * ref. Returns the vxil subscription_id + provider sub id + status. */
7022
- subscribe: (input: {
7023
- user_id: string;
7110
+ subscribe: (input: PaymentsSubjectBody & {
7024
7111
  price_ref: string;
7025
7112
  tier?: string;
7026
7113
  trial_days?: number;
@@ -7054,8 +7141,17 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7054
7141
  * (the matching session flips to completed, the charge/grant is folded).
7055
7142
  * Idempotency-Key REQUIRED — a retry replays the SAME session verbatim.
7056
7143
  */
7057
- createCheckoutSession: (input: {
7144
+ createCheckoutSession: (input: (
7145
+ /** WORKSPACE BILLING: `org_id` attributes the purchase to the
7146
+ * workspace (the provider checkout is tagged `vxil_org_id`); a
7147
+ * `user_id` beside it is the PAYER only. */
7148
+ {
7058
7149
  user_id: string;
7150
+ org_id?: string;
7151
+ } | {
7152
+ org_id: string;
7153
+ user_id?: string;
7154
+ }) & {
7059
7155
  line_items: Array<{
7060
7156
  price_ref: string;
7061
7157
  quantity?: number;
@@ -7134,8 +7230,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7134
7230
  * charge_refunded (the refund beat the grant — nothing to grant against).
7135
7231
  * 422 reserved_idempotency_key when `idempotency_key` starts with
7136
7232
  * `purchase:` (the namespace of purchase passes). */
7137
- grantSubscription: (input: {
7138
- user_id: string;
7233
+ grantSubscription: (input: PaymentsSubjectBody & {
7139
7234
  tier: string;
7140
7235
  until?: string | null;
7141
7236
  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
@@ -1379,8 +1394,9 @@ export class Vxil {
1379
1394
  list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
1380
1395
  },
1381
1396
  password: {
1382
- /** Always resolves (anti-enumeration). `captcha_token` is required when
1383
- * the tenant set `security.captchaSecretRef` (403 `captcha_failed`). */
1397
+ /** Always resolves (anti-enumeration). `captcha_token` is required only
1398
+ * when the tenant set BOTH `security.captchaOnReset: true` and
1399
+ * `security.captchaSecretRef` (403 `captcha_failed`). */
1384
1400
  requestReset: async (input) => {
1385
1401
  await this.call('POST', '/v1/auth/password/reset/request', input);
1386
1402
  },
@@ -1465,7 +1481,10 @@ export class Vxil {
1465
1481
  * an Apple "Hide My Email" relay address on an OTP account. Idempotent
1466
1482
  * for an identity this user already holds; 409 `oauth_identity_linked`
1467
1483
  * when another user holds it; 401 `invalid_session` / 409
1468
- * `anonymous_user` for an unknown or guest session. */
1484
+ * `anonymous_user` for an unknown or guest session; 409
1485
+ * `email_unverified` (verify the address first) or `password_unproven`
1486
+ * (complete a password reset, or step up then `password/change`) on a
1487
+ * password account, unless the provider-verified address is its own. */
1469
1488
  link: async (provider, input) => (await this.call('POST', `/v1/auth/oauth/${encodeURIComponent(provider)}/native`, { ...input, link: true })).data,
1470
1489
  },
1471
1490
  };
@@ -2294,7 +2313,11 @@ export class Vxil {
2294
2313
  * on the PUT) and kept with the upload: `complete` compares it with the
2295
2314
  * SHA-256 the store reports for the bytes — 409 `checksum_mismatch` when
2296
2315
  * they differ, 409 `checksum_unverified` when the store reports none —
2297
- * and on success answers the verified `checksum_sha256`. */
2316
+ * and on success answers the verified `checksum_sha256`.
2317
+ * Workspace files: `org: true` (end-user mode) makes the
2318
+ * session's ACTIVE org own the object — every member of that org can
2319
+ * list (`list({ scope: 'org' })`) and read it, it survives the uploader's
2320
+ * erasure, and deleting the org removes it. A server key names `org_id`. */
2298
2321
  createUploadUrl: async (input) => (await this.call('POST', '/v1/files/upload-url', input)).data,
2299
2322
  /** Confirm the PUT (bytes verified, object → available). Answers the
2300
2323
  * object's `expires_at` (null = never) and `checksum_sha256` (hex; null
@@ -2328,9 +2351,14 @@ export class Vxil {
2328
2351
  * `inline`. For expo-image, cache on the object id, not the URL:
2329
2352
  * `<Image source={{ uri: u.download_url, cacheKey: u.object_id }} />`. */
2330
2353
  downloadUrls: async (objectIds) => (await this.call('GET', `/v1/files/download-urls?object_ids=${encodeURIComponent(objectIds.join(','))}`)).data,
2354
+ /** List objects. End-user mode: your PERSONAL files, or `scope: 'org'`
2355
+ * for the active org's WORKSPACE files (403 `org_required` without an
2356
+ * active org). Server key: `user_id` / `org_id` filters. */
2331
2357
  list: async (q) => {
2332
2358
  const s = qs({
2333
2359
  user_id: q?.user_id || undefined,
2360
+ scope: q?.scope || undefined,
2361
+ org_id: q?.org_id || undefined,
2334
2362
  cursor: q?.cursor || undefined,
2335
2363
  limit: q?.limit || undefined,
2336
2364
  });
@@ -2686,10 +2714,13 @@ export class Vxil {
2686
2714
  * higher tier's earlier end; access does not dip (a lapsed winner re-folds
2687
2715
  * on read and the lower tier takes over), but a client that CACHES `until`
2688
2716
  * will show an early expiry — re-read instead of trusting a cached value
2689
- * past it. */
2717
+ * past it.
2718
+ *
2719
+ * WORKSPACE BILLING: pass `{ org_id }` (server) or `{ subject: 'org' }`
2720
+ * (thin client, the active workspace) for a workspace's entitlements. */
2690
2721
  getEntitlements: async (userId, opts) => {
2691
2722
  const s = qs({
2692
- user_id: userId,
2723
+ ...paymentsSubjectQuery(userId),
2693
2724
  quota: opts?.quota || undefined,
2694
2725
  credit_type: opts?.creditType || undefined,
2695
2726
  });
@@ -2697,8 +2728,9 @@ export class Vxil {
2697
2728
  },
2698
2729
  /** Boolean gate: does the user hold `entitlement`? Returns granted + its
2699
2730
  * 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,
2731
+ * the answer is good for) and `as_of`. Non-2xx = unknown, never free.
2732
+ * `{ org_id }` / `{ subject: 'org' }` check a workspace (PaymentsSubject). */
2733
+ hasEntitlement: async (userId, entitlement) => (await this.call('GET', `/v1/payments/entitlements/check?${paymentsSubjectPairs(userId)}&entitlement=${encodeURIComponent(entitlement)}`)).data,
2702
2734
  /** A single numeric quota for the user (e.g. `seats`, `api_calls`); null when
2703
2735
  * the resolved tier declares no such quota. Convenience over getEntitlements. */
2704
2736
  getQuota: async (userId, quota) => {
@@ -2707,8 +2739,9 @@ export class Vxil {
2707
2739
  return typeof v === 'number' ? v : null;
2708
2740
  },
2709
2741
  /** 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,
2742
+ * held) + the current period_end. `{ org_id }` / `{ subject: 'org' }`
2743
+ * read a workspace's balance (PaymentsSubject). */
2744
+ getBalance: async (userId, creditType) => (await this.call('GET', `/v1/payments/credits/balance?${paymentsSubjectPairs(userId)}&credit_type=${encodeURIComponent(creditType)}`)).data,
2712
2745
  /**
2713
2746
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
2714
2747
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
@@ -2752,10 +2785,12 @@ export class Vxil {
2752
2785
  * not just retries). A repeat with the same key → granted:false. */
2753
2786
  grantOnce: async (input) => (await this.call('POST', '/v1/payments/credits/grant-once', input)).data,
2754
2787
  /** Recent ledger rows for the user (the audit/trail surface), newest first;
2755
- * optionally scoped to one credit type. */
2788
+ * optionally scoped to one credit type. `org_id` (SERVER key only) reads a
2789
+ * workspace's rows instead — the workspace trail lists every member's
2790
+ * consumes, so a thin client gets 403 org_usage_server_only. */
2756
2791
  usage: async (q) => {
2757
2792
  const s = qs({
2758
- user_id: q.user_id,
2793
+ ...paymentsSubjectQuery(q),
2759
2794
  credit_type: q.credit_type || undefined,
2760
2795
  limit: q.limit || undefined,
2761
2796
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.25.0",
3
+ "version": "0.26.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",