@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 +103 -7
- package/dist/index.js +13 -8
- package/package.json +1 -1
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
|
|
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…)
|
|
3433
|
-
* original run (the ai-v1 rule)
|
|
3434
|
-
*
|
|
3435
|
-
*
|
|
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
|
-
|
|
316
|
-
|
|
317
|
-
|
|
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…)
|
|
791
|
-
* original run (the ai-v1 rule)
|
|
792
|
-
*
|
|
793
|
-
*
|
|
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