@vxil/sdk 0.20.0 → 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
  };
@@ -3429,11 +3520,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
3429
3520
  * status NOW (`processing`, `completed` or `failed` too). The key is bound
3430
3521
  * to the request BODY: re-sending it with a different body (another
3431
3522
  * payload — a rebuilt `deadline_at` included —, provider, completion,
3432
- * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
3433
- * original run (the ai-v1 rule). That check is being rolled out: today a
3434
- * mismatch is only logged, on every project, and the send is still
3435
- * deduplicated to the first run; a changelog entry will announce
3436
- * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
3523
+ * timeout, reserve…) answers 422 `idempotency_key_reused` naming the
3524
+ * original run (the ai-v1 rule), on every project — so keep the body
3525
+ * deterministic (provider header VALUES are not compared, so a rotated
3526
+ * key is fine). A 409 `generation_in_progress`
3437
3527
  * (Retry-After 5) means the run that key names is still placing its
3438
3528
  * credit hold.
3439
3529
  *
@@ -5839,6 +5929,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5839
5929
  model?: string;
5840
5930
  max_tokens?: number;
5841
5931
  temperature?: number;
5932
+ /** Gemini thinking depth — see AiThinkingLevel. */
5933
+ thinking_level?: AiThinkingLevel;
5842
5934
  tools?: Array<{
5843
5935
  name: string;
5844
5936
  description?: string;
@@ -5897,6 +5989,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5897
5989
  model?: string;
5898
5990
  max_tokens?: number;
5899
5991
  temperature?: number;
5992
+ /** Gemini thinking depth — see AiThinkingLevel. */
5993
+ thinking_level?: AiThinkingLevel;
5900
5994
  tools?: Array<{
5901
5995
  name: string;
5902
5996
  description?: string;
@@ -5932,6 +6026,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
5932
6026
  model?: string;
5933
6027
  max_tokens?: number;
5934
6028
  temperature?: number;
6029
+ /** Gemini thinking depth — see AiThinkingLevel. */
6030
+ thinking_level?: AiThinkingLevel;
5935
6031
  tools?: Array<{
5936
6032
  name: string;
5937
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),
@@ -787,11 +793,10 @@ export class Vxil {
787
793
  * status NOW (`processing`, `completed` or `failed` too). The key is bound
788
794
  * to the request BODY: re-sending it with a different body (another
789
795
  * payload — a rebuilt `deadline_at` included —, provider, completion,
790
- * timeout, reserve…) will answer 422 `idempotency_key_reused` naming the
791
- * original run (the ai-v1 rule). That check is being rolled out: today a
792
- * mismatch is only logged, on every project, and the send is still
793
- * deduplicated to the first run; a changelog entry will announce
794
- * enforcement — so keep the body deterministic now. A 409 `generation_in_progress`
796
+ * timeout, reserve…) answers 422 `idempotency_key_reused` naming the
797
+ * original run (the ai-v1 rule), on every project — so keep the body
798
+ * deterministic (provider header VALUES are not compared, so a rotated
799
+ * key is fine). A 409 `generation_in_progress`
795
800
  * (Retry-After 5) means the run that key names is still placing its
796
801
  * credit hold.
797
802
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.20.0",
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).",