@vxil/sdk 0.37.1 → 0.38.1

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.
Files changed (2) hide show
  1. package/dist/index.d.ts +91 -16
  2. package/package.json +1 -1
package/dist/index.d.ts CHANGED
@@ -483,13 +483,16 @@ export interface UsageCurrent {
483
483
  requests: {
484
484
  /** requests recorded this month (0 until the meter has rows). */
485
485
  used: number;
486
- /** the plan's included monthly requests; null = no fixed cap. */
486
+ /** the plan's daily API-call cap × 30 (a month's worth, kept for older
487
+ * clients); null = no fixed cap. The enforced limit is daily, on every
488
+ * plan: the `api_calls` lane of `daily_caps` (429 daily_limit_reached
489
+ * past it until 00:00 UTC). */
487
490
  quota: number | null;
488
491
  /** max(quota − used, 0); null when quota is null. */
489
492
  remaining: number | null;
490
- /** the PLAN's hard-cap policy — true only on the free tier (which is cut
491
- * off with 429 quota_exceeded when exhausted); paid tiers have no monthly
492
- * cap and are never billed for overage. Not a live "the next request will 429" signal. */
493
+ /** the PLAN's hard-cap policy flag — true only on the free tier. Not a
494
+ * live "the next request will 429" signal: every plan refuses calls past
495
+ * its daily limit, and no plan is ever billed for overage. */
493
496
  enforced: boolean;
494
497
  };
495
498
  /** month-to-date per-feature metered detail. Aggregated periodically — it
@@ -1519,6 +1522,12 @@ export interface AiUsage {
1519
1522
  * need no adjustment — these are for your own visibility. */
1520
1523
  cache_creation_input_tokens?: number;
1521
1524
  cache_read_input_tokens?: number;
1525
+ /** Thinking / reasoning tokens, present only when the provider reports them
1526
+ * (Gemini, and Anthropic when it sends a breakdown). Already INSIDE
1527
+ * `output_tokens` — a breakdown, never added again. Like the cache counts,
1528
+ * these are on the generation record and the `?since=` usage frame too, and
1529
+ * never change metering. */
1530
+ thinking_tokens?: number;
1522
1531
  }
1523
1532
  /** One tool invocation the model asked for (tool-use passthrough — vxil relays,
1524
1533
  * YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
@@ -1541,6 +1550,13 @@ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
1541
1550
  * with `ai.templates.put`) → `features.ai.defaults.mediaResolution` → the
1542
1551
  * model's own default. */
1543
1552
  export type AiMediaResolution = 'low' | 'medium' | 'high';
1553
+ /** Anthropic effort for `ai.generate` / `stream` / `generateAsync` (`effort`):
1554
+ * how much the model thinks and spends before it answers. Sent to Anthropic
1555
+ * only, as `output_config.effort` — every other provider ignores it; omitted →
1556
+ * `features.ai.defaults.effort` → the model's own default. A level a model does
1557
+ * not accept is the provider's own error. Thinking tokens are billed as output
1558
+ * tokens. Never derived from `thinking_level`. */
1559
+ export type AiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
1544
1560
  /** A prior conversation turn for the tool-calling round-trip: assistant turns
1545
1561
  * carry the tool_calls they made; `role:'tool'` turns carry one call's result
1546
1562
  * (`tool_call_id` correlates it; `name` is the tool's name). */
@@ -1582,8 +1598,9 @@ export interface AiStreamHandle {
1582
1598
  /** Frames delivered over the ai-<generation_id> realtime channel and the
1583
1599
  * ?since= replay buffer (the WS envelope is { event, data } — `event` is the
1584
1600
  * frame type; replayed frames carry it as `type`). `title` arrives early when
1585
- * the stream was requested with title/title_template; only the terminal usage
1586
- * frame carries done:true. */
1601
+ * the stream was requested with title/title_template; the terminal frame —
1602
+ * usage, or the error frame — carries done:true, so narrow a usage frame with
1603
+ * `'usage' in frame`, not `frame.done`. */
1587
1604
  export type AiStreamFrame = {
1588
1605
  type?: 'token';
1589
1606
  seq: number;
@@ -1596,10 +1613,38 @@ export type AiStreamFrame = {
1596
1613
  type?: 'usage';
1597
1614
  seq: number;
1598
1615
  done: true;
1616
+ /** the provider's own finish word (only `tool_use` is normalised), or
1617
+ * `schema_mismatch` when a structured answer failed its schema */
1599
1618
  finish: string;
1600
1619
  usage: AiUsage;
1601
1620
  tool_calls?: AiToolCall[];
1621
+ /** the structured-output repair fixed the answer */
1622
+ repaired?: boolean;
1623
+ /** the stored answer was cut at 262,144 characters (vxil's storage cut,
1624
+ * not a token cut) */
1625
+ truncated?: boolean;
1626
+ }
1627
+ /** The terminal failure frame. Live on `ai-<generation_id>`: `{ done,
1628
+ * message }` from a stream, `{ seq: 1, done, message, error_class }` from a
1629
+ * job-lane run — never a hint. Replayed by `?since=` for a failed job-lane
1630
+ * generation, with `hint` (the provider's own error text, up to 200
1631
+ * characters) for API-key callers only — never for an end-user session. */
1632
+ | {
1633
+ type?: 'error';
1634
+ seq?: number;
1635
+ done: true;
1636
+ message: string;
1637
+ error_class?: string | null;
1638
+ hint?: string;
1602
1639
  };
1640
+ /** The request's `repair` (`ai.generate` / `generateAsync`, with a response
1641
+ * schema): `false` = no repair call — an invalid answer is
1642
+ * `output_schema_mismatch` after ONE call. Omitted / `true` = one repair call
1643
+ * when it can help; never after a refusal, a safety stop, a length cut or an
1644
+ * empty answer, which keep the provider's own finish word (`refusal`,
1645
+ * `max_tokens`, `MAX_TOKENS`, `length`, `content_filter`, …) on the record
1646
+ * and the frame, and in the sync 422's `details.finish`. */
1647
+ export type AiRepair = boolean;
1603
1648
  /** The live-only `token_expiring` event (never seq'd, never replayed): fired
1604
1649
  * ~30s before each 300s connect-token window ends on a long stream. Re-mint
1605
1650
  * via ai.remintToken() and reconnect with ?since=<last seen seq>. */
@@ -1649,13 +1694,20 @@ export interface AiGenerationRecord {
1649
1694
  provider: string;
1650
1695
  model: string;
1651
1696
  template: string | null;
1652
- usage: {
1653
- input_tokens: number;
1654
- output_tokens: number;
1655
- };
1697
+ /** input / output, plus `cache_creation_input_tokens`,
1698
+ * `cache_read_input_tokens` and `thinking_tokens` when Anthropic or
1699
+ * Gemini report them (cache counts: Anthropic; thinking: either; absent
1700
+ * otherwise, never 0) — summed over the first call and the repair */
1701
+ usage: AiUsage;
1656
1702
  cached: boolean;
1703
+ /** the structured-output repair call fixed the answer (optional: a server
1704
+ * before 2026-11 does not send it) */
1705
+ repaired?: boolean;
1657
1706
  created_at: string;
1658
1707
  settled_at: string | null;
1708
+ /** `finish` is the provider's own word (only `tool_use` is normalised) or
1709
+ * `schema_mismatch`; `truncated` is vxil's 262,144-character storage cut,
1710
+ * not a token cut */
1659
1711
  result: {
1660
1712
  text: string;
1661
1713
  finish: string;
@@ -1665,11 +1717,23 @@ export interface AiGenerationRecord {
1665
1717
  * user was erased) · `not_recorded` (not settled yet, or a sync/stream
1666
1718
  * generation) */
1667
1719
  result_state: 'stored' | 'purged' | 'not_recorded';
1668
- /** a job-lane generation's model calls (timing, the upstream HTTP status,
1669
- * error class), oldest first, the last 10 kept — a retried attempt shows
1670
- * up here with the status the model provider answered. Empty on a
1671
- * sync/stream generation and before the first call returned */
1672
- attempts?: GenerationProviderAttempt[];
1720
+ /** a job-lane generation's execution attempts — one per attempt, timing
1721
+ * its FIRST provider call (the repair's own time is `repair_ms`), with the
1722
+ * upstream HTTP status and error class — oldest first, at most 10 kept. A
1723
+ * retried attempt shows up here with the status the model provider
1724
+ * answered. Empty on a sync/stream generation and before the first call
1725
+ * returned */
1726
+ attempts?: AiGenerationAttempt[];
1727
+ }
1728
+ /** One execution attempt on GET /v1/ai/generations/{id}. */
1729
+ export interface AiGenerationAttempt extends GenerationProviderAttempt {
1730
+ /** the structured-output repair call's time, in ms, on the settling
1731
+ * attempt when a repair ran */
1732
+ repair_ms?: number;
1733
+ /** on a failed or released attempt: the provider's own error text, up to
1734
+ * 200 characters (vxil never adds the prompt). API-key callers only —
1735
+ * never on an end-user session's read */
1736
+ hint?: string;
1673
1737
  }
1674
1738
  /** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
1675
1739
  export interface JobGenerationQueuedEventPayload {
@@ -7096,6 +7160,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7096
7160
  thinking_level?: AiThinkingLevel;
7097
7161
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7098
7162
  media_resolution?: AiMediaResolution;
7163
+ /** Anthropic effort — see AiEffort. */
7164
+ effort?: AiEffort;
7099
7165
  tools?: Array<{
7100
7166
  name: string;
7101
7167
  description?: string;
@@ -7112,6 +7178,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7112
7178
  * still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
7113
7179
  * over the template's stored schema. */
7114
7180
  response_schema?: Record<string, unknown>;
7181
+ /** See AiRepair: `false` = no repair call on an invalid structured answer. */
7182
+ repair?: AiRepair;
7115
7183
  images?: string[];
7116
7184
  /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
7117
7185
  * URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
@@ -7158,6 +7226,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7158
7226
  thinking_level?: AiThinkingLevel;
7159
7227
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7160
7228
  media_resolution?: AiMediaResolution;
7229
+ /** Anthropic effort — see AiEffort. */
7230
+ effort?: AiEffort;
7161
7231
  tools?: Array<{
7162
7232
  name: string;
7163
7233
  description?: string;
@@ -7197,6 +7267,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7197
7267
  thinking_level?: AiThinkingLevel;
7198
7268
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7199
7269
  media_resolution?: AiMediaResolution;
7270
+ /** Anthropic effort — see AiEffort. */
7271
+ effort?: AiEffort;
7200
7272
  tools?: Array<{
7201
7273
  name: string;
7202
7274
  description?: string;
@@ -7207,8 +7279,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7207
7279
  /** JSON Schema the completion must satisfy — same contract as
7208
7280
  * `generate`; the validated answer lands in the replay buffer (a
7209
7281
  * schema-mismatch delivers finish:'schema_mismatch' on the terminal
7210
- * usage frame). */
7282
+ * usage frame, or the provider's own word when the answer could not be
7283
+ * repaired). */
7211
7284
  response_schema?: Record<string, unknown>;
7285
+ /** See AiRepair: `false` = no repair call on an invalid structured answer. */
7286
+ repair?: AiRepair;
7212
7287
  images?: string[];
7213
7288
  /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
7214
7289
  * URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.37.1",
3
+ "version": "0.38.1",
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).",