@vxil/sdk 0.20.1 → 0.21.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
@@ -367,6 +367,25 @@ export interface UsageCurrent {
367
367
  route_class: string;
368
368
  requests: number;
369
369
  }>;
370
+ /** private file storage now: live (not deleted, not expired) objects and
371
+ * bytes, and `limit` — the quota uploads are held to (the plan's ceiling,
372
+ * or your own lower `files.quotas.maxTotalBytes`). At the limit new uploads
373
+ * answer 422 quota_exceeded. null for an end-user (thin-client) key. */
374
+ files: {
375
+ objects: number;
376
+ bytes: number;
377
+ limit: number;
378
+ } | null;
379
+ /** today's (UTC) function calls vs the plan's daily budget. The count is a
380
+ * snapshot refreshed while calls run, so it can trail the live count by up
381
+ * to about a minute or two; null when there is no snapshot for today or it
382
+ * cannot be read (0 only when today's snapshot says 0). `as_of` is when it
383
+ * was taken. The block is null for an end-user (thin-client) key. */
384
+ functions: {
385
+ invocations_today: number | null;
386
+ limit_per_day: number;
387
+ as_of: string | null;
388
+ } | null;
370
389
  }
371
390
  export interface DeadLetter {
372
391
  delivery_id: string;
@@ -1134,6 +1153,11 @@ export interface SearchQueryResult {
1134
1153
  /** true when the configured BYO reranker re-ordered the fused candidates;
1135
1154
  * false when not configured, opted out, or the provider failed (fail-open). */
1136
1155
  reranked?: boolean;
1156
+ /** which embedder ranked these results — the collection's provider.
1157
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
1158
+ * of the text, not by meaning, so results look real but are not semantic.
1159
+ * Set a real provider (or `'byov'`) before you ship. */
1160
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1137
1161
  }
1138
1162
  /** Embedding-token + query + rerank counts since a timestamp (GET /v1/search/usage). */
1139
1163
  export interface SearchUsage {
@@ -1176,6 +1200,13 @@ export interface AiToolCall {
1176
1200
  name: string;
1177
1201
  arguments: unknown;
1178
1202
  }
1203
+ /** Gemini thinking depth for `ai.generate` / `stream` / `generateAsync`
1204
+ * (`thinking_level`). Sent to Gemini only — every other provider ignores it;
1205
+ * omitted → `features.ai.defaults.thinkingLevel` → the model's own default.
1206
+ * `'minimal'` is refused (422 `thinking_level_unsupported`) by models that do
1207
+ * not accept it (newer flash and Pro models; flash-lite accepts it). Thinking
1208
+ * tokens are billed as output tokens. */
1209
+ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
1179
1210
  /** A prior conversation turn for the tool-calling round-trip: assistant turns
1180
1211
  * carry the tool_calls they made; `role:'tool'` turns carry one call's result
1181
1212
  * (`tool_call_id` correlates it; `name` is the tool's name). */
@@ -1948,6 +1979,11 @@ export interface RagAnswer {
1948
1979
  output_tokens: number | null;
1949
1980
  };
1950
1981
  finish?: string;
1982
+ /** which embedder ranked the grounding chunks — the collection's provider.
1983
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
1984
+ * of the text, not by meaning, so results look real but are not semantic.
1985
+ * Set a real provider (or `'byov'`) before you ship. */
1986
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1951
1987
  }
1952
1988
  /** A streamed grounded answer: citations up front, tokens over the channel. */
1953
1989
  export interface RagStreamHandle {
@@ -1966,6 +2002,11 @@ export interface RagStreamHandle {
1966
2002
  retrieved: number;
1967
2003
  used: number;
1968
2004
  };
2005
+ /** which embedder ranked the grounding chunks — the collection's provider.
2006
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
2007
+ * of the text, not by meaning, so results look real but are not semantic.
2008
+ * Set a real provider (or `'byov'`) before you ship. */
2009
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1969
2010
  }
1970
2011
  /** A scored hit from the retrieval-only surface (POST /v1/rag/search). */
1971
2012
  export interface RagSearchHit {
@@ -1993,6 +2034,11 @@ export interface RagSearchResult {
1993
2034
  retrieval_ms: number;
1994
2035
  retrieved: number;
1995
2036
  };
2037
+ /** which embedder ranked these results — the collection's provider.
2038
+ * `'mock'` = the deterministic zero-config TEST embedder: it ranks by a hash
2039
+ * of the text, not by meaning, so results look real but are not semantic.
2040
+ * Set a real provider (or `'byov'`) before you ship. */
2041
+ embed_provider?: 'byov' | 'mock' | 'openai' | 'cohere' | (string & {});
1996
2042
  }
1997
2043
  /** A replayed frame page from the rag-native resume endpoint (proxies the ai
1998
2044
  * feature's replay buffer: every recorded frame with seq > since, plus done). */
@@ -2749,6 +2795,13 @@ export type ExpandedRow<C extends {
2749
2795
  }, S extends VxilSchemaShape, E extends readonly string[]> = Omit<C['Row'], E[number]> & {
2750
2796
  [K in E[number]]: CmsExpanded<TargetRow<C, S, K>>;
2751
2797
  };
2798
+ /** The typed `from(c).query` options (the `meta: true` overloads reuse it). */
2799
+ type CollectionQuery<C extends VxilSchemaShape['cms'][string]> = {
2800
+ filter?: Partial<C['Filterable']>;
2801
+ sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
2802
+ limit?: number;
2803
+ cursor?: string;
2804
+ };
2752
2805
  /** A per-collection typed handle returned by `vx.from(collection)`. `S` (the
2753
2806
  * whole generated schema) is DEFAULTED so `CollectionClient<X>` — the only
2754
2807
  * spelling that existed before typed expand — still compiles; it is what lets
@@ -2768,11 +2821,41 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2768
2821
  /** `expand` inlines the named relation/file fields (guide ch. 4) — the names
2769
2822
  * come from the generated `Relations`, so a typo is a compile error. Bounds
2770
2823
  * (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`. */
2824
+ * (ceiling 25). Omit it and the result type is exactly today's `Row`.
2825
+ *
2826
+ * `meta: true` (opt-in) returns the item ENVELOPE `{ item_id, status,
2827
+ * version, data: Row, … }` instead of the bare field bag — what you need to
2828
+ * `patch`/`publish`/`delete` the row you just read or pass `ifVersion`.
2829
+ * Combines with `expand` (expanded members stay inside `data`). `meta:
2830
+ * false` is the same as omitting it. */
2831
+ get<E extends readonly ExpandableOf<C>[]>(itemId: string, opts: {
2832
+ expand: E;
2833
+ meta: true;
2834
+ }): Promise<CmsItemEnvelope<ExpandedRow<C, S, E>>>;
2835
+ get(itemId: string, opts: {
2836
+ meta: true;
2837
+ }): Promise<CmsItemEnvelope<C['Row']>>;
2772
2838
  get<E extends readonly ExpandableOf<C>[]>(itemId: string, opts: {
2773
2839
  expand: E;
2840
+ meta?: false;
2774
2841
  }): Promise<ExpandedRow<C, S, E>>;
2775
- get(itemId: string): Promise<C['Row']>;
2842
+ get(itemId: string, opts?: {
2843
+ meta?: false;
2844
+ }): Promise<C['Row']>;
2845
+ /** `meta: true` returns each item as its envelope — see `get`. */
2846
+ query<E extends readonly ExpandableOf<C>[]>(q: CollectionQuery<C> & {
2847
+ expand: E;
2848
+ meta: true;
2849
+ }): Promise<{
2850
+ items: CmsItemEnvelope<ExpandedRow<C, S, E>>[];
2851
+ next_cursor: string | null;
2852
+ }>;
2853
+ query(q: CollectionQuery<C> & {
2854
+ meta: true;
2855
+ }): Promise<{
2856
+ items: CmsItemEnvelope<C['Row']>[];
2857
+ next_cursor: string | null;
2858
+ }>;
2776
2859
  query<E extends readonly ExpandableOf<C>[]>(q: {
2777
2860
  filter?: Partial<C['Filterable']>;
2778
2861
  sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
@@ -2781,6 +2864,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2781
2864
  /** relation/file fields to inline — see `get`. Cannot be combined with
2782
2865
  * `count` (a separate method here; the raw API 422s when both are sent). */
2783
2866
  expand: E;
2867
+ meta?: false;
2784
2868
  }): Promise<{
2785
2869
  items: ExpandedRow<C, S, E>[];
2786
2870
  next_cursor: string | null;
@@ -2796,6 +2880,7 @@ export interface CollectionClient<C extends VxilSchemaShape['cms'][string], S ex
2796
2880
  sort?: C['Sortable'] | `-${C['Sortable'] & string}`;
2797
2881
  limit?: number;
2798
2882
  cursor?: string;
2883
+ meta?: false;
2799
2884
  }): Promise<{
2800
2885
  items: C['Row'][];
2801
2886
  next_cursor: string | null;
@@ -3240,6 +3325,12 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3240
3325
  /** recipients in `suppression.testRecipients` on this page: recorded
3241
3326
  * `test_sink`, never sent, never billed */
3242
3327
  test_sink?: number;
3328
+ /** sends delayed by whole seconds to honour `rateLimit.perTenantSec`
3329
+ * (included in `deferred`; never dropped) */
3330
+ deferred_rate_limit?: number;
3331
+ /** page rows not processed because `rateLimit.perDay` was reached —
3332
+ * nothing written for them, so a later run picks them up */
3333
+ held_daily_cap?: number;
3243
3334
  }>;
3244
3335
  };
3245
3336
  };
@@ -5838,6 +5929,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5838
5929
  model?: string;
5839
5930
  max_tokens?: number;
5840
5931
  temperature?: number;
5932
+ /** Gemini thinking depth — see AiThinkingLevel. */
5933
+ thinking_level?: AiThinkingLevel;
5841
5934
  tools?: Array<{
5842
5935
  name: string;
5843
5936
  description?: string;
@@ -5896,6 +5989,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5896
5989
  model?: string;
5897
5990
  max_tokens?: number;
5898
5991
  temperature?: number;
5992
+ /** Gemini thinking depth — see AiThinkingLevel. */
5993
+ thinking_level?: AiThinkingLevel;
5899
5994
  tools?: Array<{
5900
5995
  name: string;
5901
5996
  description?: string;
@@ -5931,6 +6026,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5931
6026
  model?: string;
5932
6027
  max_tokens?: number;
5933
6028
  temperature?: number;
6029
+ /** Gemini thinking depth — see AiThinkingLevel. */
6030
+ thinking_level?: AiThinkingLevel;
5934
6031
  tools?: Array<{
5935
6032
  name: string;
5936
6033
  description?: string;
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),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.20.1",
3
+ "version": "0.21.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).",