@vxil/sdk 0.20.1 → 0.22.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
@@ -154,6 +154,15 @@ export interface VxilUser {
154
154
  /** Set when the row's PII was scrubbed via DELETE /v1/users/:id?erase=true (GDPR Article 17). null = retained. */
155
155
  erased_at?: string | null;
156
156
  }
157
+ /** POST /v1/users and POST /v1/users/bulk entry. A full replace on upsert:
158
+ * an omitted field is cleared on an existing user. */
159
+ export interface VxilUserInput {
160
+ id: string;
161
+ email?: string;
162
+ display_name?: string;
163
+ avatar_url?: string;
164
+ attributes?: Record<string, unknown>;
165
+ }
157
166
  export interface Delivery {
158
167
  delivery_id: string;
159
168
  end_user_id: string;
@@ -347,8 +356,8 @@ export interface UsageCurrent {
347
356
  /** max(quota − used, 0); null when quota is null. */
348
357
  remaining: number | null;
349
358
  /** the PLAN's hard-cap policy — true only on the free tier (which is cut
350
- * off with 429 quota_exceeded when exhausted); paid tiers are never
351
- * interrupted mid-month. Not a live "the next request will 429" signal. */
359
+ * off with 429 quota_exceeded when exhausted); paid tiers have no monthly
360
+ * cap and are never billed for overage. Not a live "the next request will 429" signal. */
352
361
  enforced: boolean;
353
362
  };
354
363
  /** month-to-date per-feature metered detail. Aggregated periodically — it
@@ -367,6 +376,25 @@ export interface UsageCurrent {
367
376
  route_class: string;
368
377
  requests: number;
369
378
  }>;
379
+ /** private file storage now: live (not deleted, not expired) objects and
380
+ * bytes, and `limit` — the quota uploads are held to (the plan's ceiling,
381
+ * or your own lower `files.quotas.maxTotalBytes`). At the limit new uploads
382
+ * answer 422 quota_exceeded. null for an end-user (thin-client) key. */
383
+ files: {
384
+ objects: number;
385
+ bytes: number;
386
+ limit: number;
387
+ } | null;
388
+ /** today's (UTC) function calls vs the plan's daily budget. The count is a
389
+ * snapshot refreshed while calls run, so it can trail the live count by up
390
+ * to about a minute or two; null when there is no snapshot for today or it
391
+ * cannot be read (0 only when today's snapshot says 0). `as_of` is when it
392
+ * was taken. The block is null for an end-user (thin-client) key. */
393
+ functions: {
394
+ invocations_today: number | null;
395
+ limit_per_day: number;
396
+ as_of: string | null;
397
+ } | null;
370
398
  }
371
399
  export interface DeadLetter {
372
400
  delivery_id: string;
@@ -883,6 +911,10 @@ export interface PaymentsCharge {
883
911
  * reviewer's sandbox purchase (`revenuecat.sandboxUsers`) is `sandbox` —
884
912
  * leave it out of revenue */
885
913
  environment: PaymentsEventEnvironment;
914
+ /** the tenant's own reference from the checkout's custom data (Paddle
915
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
916
+ * can set it, so match on it — never grant access because of it */
917
+ reference: string | null;
886
918
  created_at: string;
887
919
  }
888
920
  /** A credit ledger row as listed by GET /v1/payments/credits/ledger (2026-10-05). */
@@ -952,6 +984,10 @@ export type PaymentsSubscription = {
952
984
  current_period_end: string | null;
953
985
  /** the vxil charge (`chg_…`) a pass or a charge-linked grant was bought with */
954
986
  charge_id: string | null;
987
+ /** the tenant's own reference from the checkout's custom data (Paddle
988
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
989
+ * can set it, so match on it — never grant access because of it */
990
+ reference: string | null;
955
991
  created_at: string;
956
992
  [key: string]: unknown;
957
993
  };
@@ -1134,6 +1170,17 @@ export interface SearchQueryResult {
1134
1170
  /** true when the configured BYO reranker re-ordered the fused candidates;
1135
1171
  * false when not configured, opted out, or the provider failed (fail-open). */
1136
1172
  reranked?: boolean;
1173
+ /** which embedder ranked these results — the collection's provider.
1174
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
1175
+ * of the text, not by meaning, so results look real but are not semantic.
1176
+ * Set a real provider (or `'byov'`) before you ship. */
1177
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1178
+ /** Present (true) only when the collection's pinned embed config (taken from
1179
+ * the default at create) differs from the current vector-search default; an
1180
+ * explicit embed override is never flagged. Re-create it (same name and
1181
+ * dimensions) with the embed you want (omit embed to take the current
1182
+ * default), then re-ingest. */
1183
+ embed_cfg_stale?: boolean;
1137
1184
  }
1138
1185
  /** Embedding-token + query + rerank counts since a timestamp (GET /v1/search/usage). */
1139
1186
  export interface SearchUsage {
@@ -1176,6 +1223,13 @@ export interface AiToolCall {
1176
1223
  name: string;
1177
1224
  arguments: unknown;
1178
1225
  }
1226
+ /** Gemini thinking depth for `ai.generate` / `stream` / `generateAsync`
1227
+ * (`thinking_level`). Sent to Gemini only — every other provider ignores it;
1228
+ * omitted → `features.ai.defaults.thinkingLevel` → the model's own default.
1229
+ * `'minimal'` is refused (422 `thinking_level_unsupported`) by models that do
1230
+ * not accept it (newer flash and Pro models; flash-lite accepts it). Thinking
1231
+ * tokens are billed as output tokens. */
1232
+ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
1179
1233
  /** A prior conversation turn for the tool-calling round-trip: assistant turns
1180
1234
  * carry the tool_calls they made; `role:'tool'` turns carry one call's result
1181
1235
  * (`tool_call_id` correlates it; `name` is the tool's name). */
@@ -1411,6 +1465,10 @@ export interface PaymentsChargeEventPayload {
1411
1465
  currency: string;
1412
1466
  product_id: string | null;
1413
1467
  provider_status: PaymentsProviderChargeStatus | null;
1468
+ /** the tenant's own reference from the checkout's custom data (Paddle
1469
+ * `customData.vxil_ref`, 1..128 chars; 2026-10-11), else null. The BUYER
1470
+ * can set it, so match on it — never grant access because of it */
1471
+ reference: string | null;
1414
1472
  environment: PaymentsEventEnvironment;
1415
1473
  level: 'info';
1416
1474
  }
@@ -1437,6 +1495,8 @@ export interface PaymentsChargeRefundedEventPayload {
1437
1495
  credit_type: string;
1438
1496
  amount: number;
1439
1497
  }>;
1498
+ /** the charge row's `reference` (see `PaymentsCharge.reference`) */
1499
+ reference: string | null;
1440
1500
  source: 'api' | 'webhook';
1441
1501
  environment: PaymentsEventEnvironment;
1442
1502
  level: 'info';
@@ -1469,6 +1529,9 @@ export interface PaymentsSubscriptionStatusEventPayload {
1469
1529
  status: 'trialing' | 'active' | 'past_due' | 'cancelled' | 'expired' | 'lapsed';
1470
1530
  current_period_start: string | null;
1471
1531
  current_period_end: string | null;
1532
+ /** the subscription row's `reference` (a provider subscription carries the
1533
+ * checkout's; null on manual grants and passes) */
1534
+ reference: string | null;
1472
1535
  environment: PaymentsEventEnvironment;
1473
1536
  /** what wrote it: the provider event type, `subscription.synced` /
1474
1537
  * `subscription.restored`, `period_end_enforced`, or `test_clock` (a
@@ -1703,15 +1766,15 @@ export interface FunctionEnvelopeBase {
1703
1766
  /** The edge to call vxil back through. */
1704
1767
  vxil_base: string;
1705
1768
  scoped_jwts: FunctionScopedJwts;
1706
- /** Your declared per-function secrets (`secrets: ['secret:<name>']`), keyed by
1769
+ /** Your declared per-function secrets (`secrets: ['<name>']`), keyed by
1707
1770
  * bare name and resolved at invoke time. */
1708
1771
  secrets: Record<string, string>;
1709
1772
  }
1710
1773
  /** `payload` of a `cms-hook` invocation. It carries no field values: re-read
1711
1774
  * the item by `item_id`. */
1712
1775
  export interface CmsHookTriggerPayload {
1713
- /** `cms.item.created` or `cms.item.updated` for a binding that names a
1714
- * collection; a binding without one also sees the other `cms.item.*` events */
1776
+ /** `cms.item.created`, `cms.item.updated` or `cms.item.published` (per the
1777
+ * binding's event) for a binding that names a collection; a binding without one also sees the other `cms.item.*` events */
1715
1778
  event: string;
1716
1779
  collection: string;
1717
1780
  item_id: string;
@@ -1926,6 +1989,21 @@ export interface AiUsageReport {
1926
1989
  output_tokens: number;
1927
1990
  }>;
1928
1991
  }
1992
+ /** POST /v1/webhooks/sources result. The receiver URL is returned ONCE; the
1993
+ * source verifies signatures once you set `signing_secret_name`
1994
+ * (`signing_secret_ref` says how). */
1995
+ export interface WebhookSourceCreated {
1996
+ source_id: string;
1997
+ receiver_url_path: string;
1998
+ provider: string;
1999
+ name: string;
2000
+ forward_url?: string | null;
2001
+ target_function?: string | null;
2002
+ state: string;
2003
+ created_at: string;
2004
+ signing_secret_name: string;
2005
+ signing_secret_ref: string;
2006
+ }
1929
2007
  /** A citation: the retrieved chunk that grounded the answer. */
1930
2008
  export interface RagCitation {
1931
2009
  chunk_id: string;
@@ -1948,6 +2026,11 @@ export interface RagAnswer {
1948
2026
  output_tokens: number | null;
1949
2027
  };
1950
2028
  finish?: string;
2029
+ /** which embedder ranked the grounding chunks — the collection's provider.
2030
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
2031
+ * of the text, not by meaning, so results look real but are not semantic.
2032
+ * Set a real provider (or `'byov'`) before you ship. */
2033
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1951
2034
  }
1952
2035
  /** A streamed grounded answer: citations up front, tokens over the channel. */
1953
2036
  export interface RagStreamHandle {
@@ -1966,6 +2049,11 @@ export interface RagStreamHandle {
1966
2049
  retrieved: number;
1967
2050
  used: number;
1968
2051
  };
2052
+ /** which embedder ranked the grounding chunks — the collection's provider.
2053
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
2054
+ * of the text, not by meaning, so results look real but are not semantic.
2055
+ * Set a real provider (or `'byov'`) before you ship. */
2056
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1969
2057
  }
1970
2058
  /** A scored hit from the retrieval-only surface (POST /v1/rag/search). */
1971
2059
  export interface RagSearchHit {
@@ -1993,6 +2081,11 @@ export interface RagSearchResult {
1993
2081
  retrieval_ms: number;
1994
2082
  retrieved: number;
1995
2083
  };
2084
+ /** which embedder ranked these results — the collection's provider.
2085
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
2086
+ * of the text, not by meaning, so results look real but are not semantic.
2087
+ * Set a real provider (or `'byov'`) before you ship. */
2088
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1996
2089
  }
1997
2090
  /** A replayed frame page from the rag-native resume endpoint (proxies the ai
1998
2091
  * feature's replay buffer: every recorded frame with seq > since, plus done). */
@@ -2022,9 +2115,12 @@ export interface CopilotConversation {
2022
2115
  * budgeted kept chunks — a citation can never lie). */
2023
2116
  export interface CopilotCitation {
2024
2117
  chunk_id: string;
2025
- document_id?: string;
2026
- score?: number;
2027
- [k: string]: unknown;
2118
+ doc_id: string;
2119
+ source?: {
2120
+ file?: string;
2121
+ page?: number;
2122
+ } | undefined;
2123
+ score: number;
2028
2124
  }
2029
2125
  /** A proposed WRITE action the agent wants to take — inert until confirmed. */
2030
2126
  export interface CopilotProposal {
@@ -2749,6 +2845,13 @@ export type ExpandedRow<C extends {
2749
2845
  }, S extends VxilSchemaShape, E extends readonly string[]> = Omit<C['Row'], E[number]> & {
2750
2846
  [K in E[number]]: CmsExpanded<TargetRow<C, S, K>>;
2751
2847
  };
2848
+ /** The typed `from(c).query` options (the `meta: true` overloads reuse it). */
2849
+ type CollectionQuery<C extends VxilSchemaShape['cms'][string]> = {
2850
+ filter?: Partial<C['Filterable']>;
2851
+ sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
2852
+ limit?: number;
2853
+ cursor?: string;
2854
+ };
2752
2855
  /** A per-collection typed handle returned by `vx.from(collection)`. `S` (the
2753
2856
  * whole generated schema) is DEFAULTED so `CollectionClient<X>` — the only
2754
2857
  * spelling that existed before typed expand — still compiles; it is what lets
@@ -2768,11 +2871,41 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2768
2871
  /** `expand` inlines the named relation/file fields (guide ch. 4) — the names
2769
2872
  * come from the generated `Relations`, so a typo is a compile error. Bounds
2770
2873
  * (worker-clamped regardless of config): depth 1 (ceiling 2), ≤5 fields
2771
- * (ceiling 25). Omit it and the result type is exactly today's `Row`. */
2874
+ * (ceiling 25). Omit it and the result type is exactly today's `Row`.
2875
+ *
2876
+ * `meta: true` (opt-in) returns the item ENVELOPE `{ item_id, status,
2877
+ * version, data: Row, … }` instead of the bare field bag — what you need to
2878
+ * `patch`/`publish`/`delete` the row you just read or pass `ifVersion`.
2879
+ * Combines with `expand` (expanded members stay inside `data`). `meta:
2880
+ * false` is the same as omitting it. */
2881
+ get<E extends readonly ExpandableOf<C>[]>(itemId: string, opts: {
2882
+ expand: E;
2883
+ meta: true;
2884
+ }): Promise<CmsItemEnvelope<ExpandedRow<C, S, E>>>;
2885
+ get(itemId: string, opts: {
2886
+ meta: true;
2887
+ }): Promise<CmsItemEnvelope<C['Row']>>;
2772
2888
  get<E extends readonly ExpandableOf<C>[]>(itemId: string, opts: {
2773
2889
  expand: E;
2890
+ meta?: false;
2774
2891
  }): Promise<ExpandedRow<C, S, E>>;
2775
- get(itemId: string): Promise<C['Row']>;
2892
+ get(itemId: string, opts?: {
2893
+ meta?: false;
2894
+ }): Promise<C['Row']>;
2895
+ /** `meta: true` returns each item as its envelope — see `get`. */
2896
+ query<E extends readonly ExpandableOf<C>[]>(q: CollectionQuery<C> & {
2897
+ expand: E;
2898
+ meta: true;
2899
+ }): Promise<{
2900
+ items: CmsItemEnvelope<ExpandedRow<C, S, E>>[];
2901
+ next_cursor: string | null;
2902
+ }>;
2903
+ query(q: CollectionQuery<C> & {
2904
+ meta: true;
2905
+ }): Promise<{
2906
+ items: CmsItemEnvelope<C['Row']>[];
2907
+ next_cursor: string | null;
2908
+ }>;
2776
2909
  query<E extends readonly ExpandableOf<C>[]>(q: {
2777
2910
  filter?: Partial<C['Filterable']>;
2778
2911
  sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
@@ -2781,6 +2914,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2781
2914
  /** relation/file fields to inline — see `get`. Cannot be combined with
2782
2915
  * `count` (a separate method here; the raw API 422s when both are sent). */
2783
2916
  expand: E;
2917
+ meta?: false;
2784
2918
  }): Promise<{
2785
2919
  items: ExpandedRow<C, S, E>[];
2786
2920
  next_cursor: string | null;
@@ -2796,6 +2930,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2796
2930
  sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
2797
2931
  limit?: number;
2798
2932
  cursor?: string;
2933
+ meta?: false;
2799
2934
  }): Promise<{
2800
2935
  items: C['Row'][];
2801
2936
  next_cursor: string | null;
@@ -2839,6 +2974,8 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2839
2974
  key?: Record<string, unknown>;
2840
2975
  }>;
2841
2976
  scanned: number;
2977
+ truncated: boolean;
2978
+ limit: number;
2842
2979
  }>;
2843
2980
  /** Window ranking over the aggregate (guide ch. 4). */
2844
2981
  rank(q: Omit<CmsRankBody, 'groupBy' | 'partitionBy' | 'metric'> & {
@@ -2918,17 +3055,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
2918
3055
  * (`erased_at` cleared — the erase already removed the old data). While
2919
3056
  * the erased user's files are still being erased the call fails with 409
2920
3057
  * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
2921
- upsert: (user: {
2922
- id: string;
2923
- email?: string;
2924
- display_name?: string;
2925
- avatar_url?: string;
2926
- attributes?: Record<string, unknown>;
2927
- }) => Promise<VxilUser>;
2928
- bulk: (users: Array<{
2929
- id: string;
2930
- email?: string;
2931
- }>) => Promise<number>;
3058
+ upsert: (user: VxilUserInput) => Promise<VxilUser>;
3059
+ /** Upsert up to the bulk cap in one all-or-nothing call. Like `upsert`,
3060
+ * each entry is a FULL REPLACE: a field you leave out (display_name,
3061
+ * avatar_url, attributes, email) is cleared on an existing user. */
3062
+ bulk: (users: VxilUserInput[]) => Promise<number>;
2932
3063
  get: (id: string, opts?: {
2933
3064
  includeDeleted?: boolean;
2934
3065
  }) => Promise<VxilUser>;
@@ -3193,7 +3324,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3193
3324
  name: string;
3194
3325
  template: string;
3195
3326
  audience_ref: string;
3196
- channel?: "email" | "push" | "all";
3327
+ /** Only `email` is sent today; `push` / `all` are rejected (422). */
3328
+ channel?: "email";
3197
3329
  data?: Record<string, unknown>;
3198
3330
  schedule_cron?: string;
3199
3331
  quiet_hours?: {
@@ -3240,6 +3372,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3240
3372
  /** recipients in `suppression.testRecipients` on this page: recorded
3241
3373
  * `test_sink`, never sent, never billed */
3242
3374
  test_sink?: number;
3375
+ /** sends delayed by whole seconds to honour `rateLimit.perTenantSec`
3376
+ * (included in `deferred`; never dropped) */
3377
+ deferred_rate_limit?: number;
3378
+ /** page rows not processed because `rateLimit.perDay` was reached —
3379
+ * nothing written for them, so a later run picks them up */
3380
+ held_daily_cap?: number;
3243
3381
  }>;
3244
3382
  };
3245
3383
  };
@@ -4358,8 +4496,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4358
4496
  reindex_required: boolean;
4359
4497
  }>;
4360
4498
  /** Set (or clear, with `null`) the collection's end-user owner-scope flag
4361
- * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
4362
- setOwnerField: (collection: string, ownerField: string | null) => Promise<void>;
4499
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
4500
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
4501
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
4502
+ setOwnerField: (collection: string, ownerField: string | null, opts?: {
4503
+ allowDestructive?: boolean;
4504
+ }) => Promise<void>;
4363
4505
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
4364
4506
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
4365
4507
  * (`GET {base}/v1/cms/public/:tenantId/:collection` — no api key); drafts and
@@ -4577,6 +4719,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4577
4719
  key?: Record<string, unknown>;
4578
4720
  }>;
4579
4721
  scanned: number;
4722
+ /** true when more groups matched than `limit`: the result was cut. */
4723
+ truncated: boolean;
4724
+ /** the group limit applied (default min(100, the group cap)). */
4725
+ limit: number;
4580
4726
  }>;
4581
4727
  /** Window ranking over the aggregate — rank ∈
4582
4728
  * row_number|rank|percent_rank, computed over ≤500 aggregated groups
@@ -5210,12 +5356,7 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5210
5356
  forward_url?: string;
5211
5357
  target_function?: string;
5212
5358
  verify?: WebhookHmacVerify;
5213
- }) => Promise<{
5214
- source_id: string;
5215
- receiver_url_path: string;
5216
- provider: string;
5217
- target_function?: string | null;
5218
- }>;
5359
+ }) => Promise<WebhookSourceCreated>;
5219
5360
  list: () => Promise<Array<{
5220
5361
  source_id: string;
5221
5362
  provider: string;
@@ -5368,7 +5509,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5368
5509
  settings?: Record<string, unknown>;
5369
5510
  }>;
5370
5511
  members: {
5371
- add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer") => Promise<void>;
5512
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
5513
+ add: (orgId: string, userId: string, role: "owner" | "admin" | "member" | "viewer" | (string & {})) => Promise<void>;
5372
5514
  list: (orgId: string) => Promise<Array<{
5373
5515
  user_id: string;
5374
5516
  role: string;
@@ -5718,6 +5860,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5718
5860
  provider?: string;
5719
5861
  documents?: number;
5720
5862
  created_at?: string;
5863
+ /** true when the embed config pinned from the default differs from the
5864
+ * current default (an explicit embed override is never flagged). */
5865
+ embed_cfg_stale?: boolean;
5721
5866
  }>>;
5722
5867
  /** Ingest a document: chunk → embed → index (202). BYOV skips embedding. */
5723
5868
  ingest: (collection: string, input: SearchIngestInput) => Promise<SearchIngestResult>;
@@ -5838,6 +5983,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5838
5983
  model?: string;
5839
5984
  max_tokens?: number;
5840
5985
  temperature?: number;
5986
+ /** Gemini thinking depth — see AiThinkingLevel. */
5987
+ thinking_level?: AiThinkingLevel;
5841
5988
  tools?: Array<{
5842
5989
  name: string;
5843
5990
  description?: string;
@@ -5896,6 +6043,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5896
6043
  model?: string;
5897
6044
  max_tokens?: number;
5898
6045
  temperature?: number;
6046
+ /** Gemini thinking depth — see AiThinkingLevel. */
6047
+ thinking_level?: AiThinkingLevel;
5899
6048
  tools?: Array<{
5900
6049
  name: string;
5901
6050
  description?: string;
@@ -5931,6 +6080,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5931
6080
  model?: string;
5932
6081
  max_tokens?: number;
5933
6082
  temperature?: number;
6083
+ /** Gemini thinking depth — see AiThinkingLevel. */
6084
+ thinking_level?: AiThinkingLevel;
5934
6085
  tools?: Array<{
5935
6086
  name: string;
5936
6087
  description?: string;
@@ -6271,10 +6422,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
6271
6422
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
6272
6423
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
6273
6424
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
6274
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
6425
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
6275
6426
  * available balance can't cover `amount`. Throws VxilError(409,
6276
6427
  * 'job_released') when `job_id` names a generation run that already ended
6277
- * (cancelled or failed) before this hold landed: nothing is held.
6428
+ * (cancelled, failed, or completed with nothing held) before this hold
6429
+ * landed: nothing is held.
6278
6430
  *
6279
6431
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
6280
6432
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
package/dist/index.js CHANGED
@@ -312,9 +312,15 @@ export class Vxil {
312
312
  // (the two `as` casts pick the OVERLOADED member type: one runtime
313
313
  // implementation serves both the plain and the `expand` overload, which
314
314
  // differ only in the result TYPE — the wire call is the same.)
315
- get: ((itemId, opts) => this.cms.items.get(c, itemId, opts).then(unwrap)),
316
- query: ((q) => this.cms.items.query(c, q)
317
- .then((r) => ({ items: r.items.map(unwrap), next_cursor: r.next_cursor }))),
315
+ // `meta: true` is SDK-side only (never sent): it skips the unwrap and
316
+ // hands back the envelope, so the caller keeps item_id/status/version.
317
+ get: ((itemId, opts) => this.cms.items.get(c, itemId, opts?.expand ? { expand: opts.expand } : undefined)
318
+ .then((item) => (opts?.meta ? item : unwrap(item)))),
319
+ query: ((q) => {
320
+ const { meta, ...wire } = q ?? {};
321
+ return this.cms.items.query(c, q ? wire : undefined)
322
+ .then((r) => ({ items: meta ? r.items : r.items.map(unwrap), next_cursor: r.next_cursor }));
323
+ }),
318
324
  count: (filter) => this.cms.items.count(c, filter),
319
325
  patch: (itemId, data, opts) => this.cms.items.patch(c, itemId, data, opts).then(unwrap),
320
326
  inc: (itemId, incs, opts) => this.cms.items.inc(c, itemId, incs, opts).then(unwrap),
@@ -435,6 +441,9 @@ export class Vxil {
435
441
  * the erased user's files are still being erased the call fails with 409
436
442
  * `user_erase_pending`; retry later. `bulk` is all-or-nothing. */
437
443
  upsert: async (user) => (await this.call('POST', '/v1/users', user)).data,
444
+ /** Upsert up to the bulk cap in one all-or-nothing call. Like `upsert`,
445
+ * each entry is a FULL REPLACE: a field you leave out (display_name,
446
+ * avatar_url, attributes, email) is cleared on an existing user. */
438
447
  bulk: async (users) => (await this.call('POST', '/v1/users/bulk', { users })).data.upserted,
439
448
  get: async (id, opts) => (await this.call('GET', `/v1/users/${encodeURIComponent(id)}${opts?.includeDeleted ? '?include_deleted=true' : ''}`)).data,
440
449
  /**
@@ -1348,9 +1357,11 @@ export class Vxil {
1348
1357
  }
1349
1358
  },
1350
1359
  /** Set (or clear, with `null`) the collection's end-user owner-scope flag
1351
- * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id. */
1352
- setOwnerField: async (collection, ownerField) => {
1353
- await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField });
1360
+ * (guide ch. 4, "`ownerField`"). Names an existing `string` field that holds the owner id.
1361
+ * Clearing a set flag WIDENS end-user access, so it needs `{ allowDestructive: true }`
1362
+ * (without it the server answers 422 destructive_change_requires_ack, like `vxil push`). */
1363
+ setOwnerField: async (collection, ownerField, opts) => {
1364
+ await this.call('POST', `/v1/cms/collections/${encodeURIComponent(collection)}/fields`, { owner_field: ownerField, ...(opts?.allowDestructive ? { allow_destructive: true } : {}) });
1354
1365
  },
1355
1366
  /** Toggle the collection's PUBLIC-delivery flag (guide ch. 4). When `true`,
1356
1367
  * its PUBLISHED items become KEYLESS-readable via the anonymous public lane
@@ -1933,6 +1944,7 @@ export class Vxil {
1933
1944
  /** Update a workspace's name / `settings` JSON. */
1934
1945
  update: async (orgId, patch) => (await this.call('PATCH', `/v1/orgs/${encodeURIComponent(orgId)}`, patch)).data,
1935
1946
  members: {
1947
+ /** `role`: a built-in, or a custom role_key defined with `roles.define`. */
1936
1948
  add: async (orgId, userId, role) => {
1937
1949
  await this.call('POST', `/v1/orgs/${encodeURIComponent(orgId)}/members`, { user_id: userId, role });
1938
1950
  },
@@ -2431,10 +2443,11 @@ export class Vxil {
2431
2443
  * Debit credits — idempotent (Idempotency-Key REQUIRED) + balance-guarded
2432
2444
  * (no oversell). Pass `job_id` to make the debit PROVISIONAL (held, not yet
2433
2445
  * committed): a linked jobs run that terminally fails auto-refunds the hold,
2434
- * a success settles it. Throws VxilError(402, 'INSUFFICIENT_CREDITS') when the
2446
+ * a success settles it. Throws VxilError(402, 'insufficient_credits') when the
2435
2447
  * available balance can't cover `amount`. Throws VxilError(409,
2436
2448
  * 'job_released') when `job_id` names a generation run that already ended
2437
- * (cancelled or failed) before this hold landed: nothing is held.
2449
+ * (cancelled, failed, or completed with nothing held) before this hold
2450
+ * landed: nothing is held.
2438
2451
  *
2439
2452
  * Ordered credits: pass `credit_types` (1–8, in spend order — e.g.
2440
2453
  * `['free', 'subscription', 'topup']`) instead of `credit_type`; the WHOLE
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.20.1",
3
+ "version": "0.22.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).",