@vxil/sdk 0.37.0 → 0.38.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
@@ -912,6 +912,20 @@ export type JobSchedulePatch = Partial<Omit<JobScheduleInput, 'external_id' | 'm
912
912
  external_id?: string | null;
913
913
  max_attempts?: number | null;
914
914
  };
915
+ /** One listed session of `vx.auth.sessions.list` (`GET /v1/auth/sessions`). */
916
+ export interface VxilAuthSessionInfo {
917
+ session_id: string;
918
+ created_at: string;
919
+ /** when the ACCESS token expires */
920
+ expires_at: string;
921
+ user_agent: string | null;
922
+ /** `active` while the access token is valid; `idle` when only the refresh
923
+ * token is (the device has not refreshed yet). */
924
+ state: 'active' | 'idle';
925
+ /** when the refresh token stops working (created_at + session.refreshTtlDays);
926
+ * null for a canary session, which never refreshes. */
927
+ refresh_expires_at: string | null;
928
+ }
915
929
  export interface AuthSession {
916
930
  token: string;
917
931
  refresh_token: string;
@@ -1010,6 +1024,12 @@ export interface PaymentsSyncOutcome {
1010
1024
  tier: string | null;
1011
1025
  until: string | null;
1012
1026
  }>;
1027
+ /** RevenueCat only, present only when non-empty: products the sync
1028
+ * deliberately did not fold, `<id>: <why>` (`<id>: not_restored` on an
1029
+ * end-user restore) — an ended product matching no store purchase, a
1030
+ * purchase the store ended inside the same period, a product whose own
1031
+ * row belongs to another store. Not errors: nothing was written. */
1032
+ not_folded?: string[];
1013
1033
  dry_run?: boolean;
1014
1034
  }
1015
1035
  /** A lifecycle simulation run (guide ch. 6, payments; mock/dev tenants only). */
@@ -1499,6 +1519,12 @@ export interface AiUsage {
1499
1519
  * need no adjustment — these are for your own visibility. */
1500
1520
  cache_creation_input_tokens?: number;
1501
1521
  cache_read_input_tokens?: number;
1522
+ /** Thinking / reasoning tokens, present only when the provider reports them
1523
+ * (Gemini, and Anthropic when it sends a breakdown). Already INSIDE
1524
+ * `output_tokens` — a breakdown, never added again. Like the cache counts,
1525
+ * these are on the generation record and the `?since=` usage frame too, and
1526
+ * never change metering. */
1527
+ thinking_tokens?: number;
1502
1528
  }
1503
1529
  /** One tool invocation the model asked for (tool-use passthrough — vxil relays,
1504
1530
  * YOU execute). Echo `id` back as `tool_call_id` on the `role:'tool'` turn. */
@@ -1521,6 +1547,13 @@ export type AiThinkingLevel = 'minimal' | 'low' | 'medium' | 'high';
1521
1547
  * with `ai.templates.put`) → `features.ai.defaults.mediaResolution` → the
1522
1548
  * model's own default. */
1523
1549
  export type AiMediaResolution = 'low' | 'medium' | 'high';
1550
+ /** Anthropic effort for `ai.generate` / `stream` / `generateAsync` (`effort`):
1551
+ * how much the model thinks and spends before it answers. Sent to Anthropic
1552
+ * only, as `output_config.effort` — every other provider ignores it; omitted →
1553
+ * `features.ai.defaults.effort` → the model's own default. A level a model does
1554
+ * not accept is the provider's own error. Thinking tokens are billed as output
1555
+ * tokens. Never derived from `thinking_level`. */
1556
+ export type AiEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
1524
1557
  /** A prior conversation turn for the tool-calling round-trip: assistant turns
1525
1558
  * carry the tool_calls they made; `role:'tool'` turns carry one call's result
1526
1559
  * (`tool_call_id` correlates it; `name` is the tool's name). */
@@ -1562,8 +1595,9 @@ export interface AiStreamHandle {
1562
1595
  /** Frames delivered over the ai-<generation_id> realtime channel and the
1563
1596
  * ?since= replay buffer (the WS envelope is { event, data } — `event` is the
1564
1597
  * frame type; replayed frames carry it as `type`). `title` arrives early when
1565
- * the stream was requested with title/title_template; only the terminal usage
1566
- * frame carries done:true. */
1598
+ * the stream was requested with title/title_template; the terminal frame —
1599
+ * usage, or the error frame — carries done:true, so narrow a usage frame with
1600
+ * `'usage' in frame`, not `frame.done`. */
1567
1601
  export type AiStreamFrame = {
1568
1602
  type?: 'token';
1569
1603
  seq: number;
@@ -1576,10 +1610,38 @@ export type AiStreamFrame = {
1576
1610
  type?: 'usage';
1577
1611
  seq: number;
1578
1612
  done: true;
1613
+ /** the provider's own finish word (only `tool_use` is normalised), or
1614
+ * `schema_mismatch` when a structured answer failed its schema */
1579
1615
  finish: string;
1580
1616
  usage: AiUsage;
1581
1617
  tool_calls?: AiToolCall[];
1618
+ /** the structured-output repair fixed the answer */
1619
+ repaired?: boolean;
1620
+ /** the stored answer was cut at 262,144 characters (vxil's storage cut,
1621
+ * not a token cut) */
1622
+ truncated?: boolean;
1623
+ }
1624
+ /** The terminal failure frame. Live on `ai-<generation_id>`: `{ done,
1625
+ * message }` from a stream, `{ seq: 1, done, message, error_class }` from a
1626
+ * job-lane run — never a hint. Replayed by `?since=` for a failed job-lane
1627
+ * generation, with `hint` (the provider's own error text, up to 200
1628
+ * characters) for API-key callers only — never for an end-user session. */
1629
+ | {
1630
+ type?: 'error';
1631
+ seq?: number;
1632
+ done: true;
1633
+ message: string;
1634
+ error_class?: string | null;
1635
+ hint?: string;
1582
1636
  };
1637
+ /** The request's `repair` (`ai.generate` / `generateAsync`, with a response
1638
+ * schema): `false` = no repair call — an invalid answer is
1639
+ * `output_schema_mismatch` after ONE call. Omitted / `true` = one repair call
1640
+ * when it can help; never after a refusal, a safety stop, a length cut or an
1641
+ * empty answer, which keep the provider's own finish word (`refusal`,
1642
+ * `max_tokens`, `MAX_TOKENS`, `length`, `content_filter`, …) on the record
1643
+ * and the frame, and in the sync 422's `details.finish`. */
1644
+ export type AiRepair = boolean;
1583
1645
  /** The live-only `token_expiring` event (never seq'd, never replayed): fired
1584
1646
  * ~30s before each 300s connect-token window ends on a long stream. Re-mint
1585
1647
  * via ai.remintToken() and reconnect with ?since=<last seen seq>. */
@@ -1629,13 +1691,20 @@ export interface AiGenerationRecord {
1629
1691
  provider: string;
1630
1692
  model: string;
1631
1693
  template: string | null;
1632
- usage: {
1633
- input_tokens: number;
1634
- output_tokens: number;
1635
- };
1694
+ /** input / output, plus `cache_creation_input_tokens`,
1695
+ * `cache_read_input_tokens` and `thinking_tokens` when Anthropic or
1696
+ * Gemini report them (cache counts: Anthropic; thinking: either; absent
1697
+ * otherwise, never 0) — summed over the first call and the repair */
1698
+ usage: AiUsage;
1636
1699
  cached: boolean;
1700
+ /** the structured-output repair call fixed the answer (optional: a server
1701
+ * before 2026-11 does not send it) */
1702
+ repaired?: boolean;
1637
1703
  created_at: string;
1638
1704
  settled_at: string | null;
1705
+ /** `finish` is the provider's own word (only `tool_use` is normalised) or
1706
+ * `schema_mismatch`; `truncated` is vxil's 262,144-character storage cut,
1707
+ * not a token cut */
1639
1708
  result: {
1640
1709
  text: string;
1641
1710
  finish: string;
@@ -1645,11 +1714,23 @@ export interface AiGenerationRecord {
1645
1714
  * user was erased) · `not_recorded` (not settled yet, or a sync/stream
1646
1715
  * generation) */
1647
1716
  result_state: 'stored' | 'purged' | 'not_recorded';
1648
- /** a job-lane generation's model calls (timing, the upstream HTTP status,
1649
- * error class), oldest first, the last 10 kept — a retried attempt shows
1650
- * up here with the status the model provider answered. Empty on a
1651
- * sync/stream generation and before the first call returned */
1652
- attempts?: GenerationProviderAttempt[];
1717
+ /** a job-lane generation's execution attempts — one per attempt, timing
1718
+ * its FIRST provider call (the repair's own time is `repair_ms`), with the
1719
+ * upstream HTTP status and error class — oldest first, at most 10 kept. A
1720
+ * retried attempt shows up here with the status the model provider
1721
+ * answered. Empty on a sync/stream generation and before the first call
1722
+ * returned */
1723
+ attempts?: AiGenerationAttempt[];
1724
+ }
1725
+ /** One execution attempt on GET /v1/ai/generations/{id}. */
1726
+ export interface AiGenerationAttempt extends GenerationProviderAttempt {
1727
+ /** the structured-output repair call's time, in ms, on the settling
1728
+ * attempt when a repair ran */
1729
+ repair_ms?: number;
1730
+ /** on a failed or released attempt: the provider's own error text, up to
1731
+ * 200 characters (vxil never adds the prompt). API-key callers only —
1732
+ * never on an end-user session's read */
1733
+ hint?: string;
1653
1734
  }
1654
1735
  /** The `data` of `job.generation.queued` (guide ch. 6, jobs): the run was accepted. */
1655
1736
  export interface JobGenerationQueuedEventPayload {
@@ -4976,13 +5057,14 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
4976
5057
  revokeById: (sessionId: string) => Promise<void>;
4977
5058
  /** List a user's active sessions (the account "signed-in devices" surface).
4978
5059
  * Scope `auth:read`. In end-user mode the list is bound to the signed-in
4979
- * user regardless of `userId` (the verified principal wins). */
4980
- list: (userId: string) => Promise<Array<{
4981
- session_id: string;
4982
- created_at: string;
4983
- expires_at: string;
4984
- user_agent: string | null;
4985
- }>>;
5060
+ * user regardless of `userId` (the verified principal wins). Each
5061
+ * session says `state` — `active` while its access token is valid,
5062
+ * `idle` when only its refresh token is — and `refresh_expires_at`
5063
+ * (null for a canary session, which never refreshes). Today only
5064
+ * `active` sessions are listed; idle devices are listed (and counted by
5065
+ * `session.maxConcurrent`) from the release the changelog's Coming next
5066
+ * names. */
5067
+ list: (userId: string) => Promise<Array<VxilAuthSessionInfo>>;
4986
5068
  };
4987
5069
  password: {
4988
5070
  /** Always resolves (anti-enumeration). `captcha_token` is required only
@@ -7075,6 +7157,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7075
7157
  thinking_level?: AiThinkingLevel;
7076
7158
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7077
7159
  media_resolution?: AiMediaResolution;
7160
+ /** Anthropic effort — see AiEffort. */
7161
+ effort?: AiEffort;
7078
7162
  tools?: Array<{
7079
7163
  name: string;
7080
7164
  description?: string;
@@ -7091,6 +7175,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7091
7175
  * still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
7092
7176
  * over the template's stored schema. */
7093
7177
  response_schema?: Record<string, unknown>;
7178
+ /** See AiRepair: `false` = no repair call on an invalid structured answer. */
7179
+ repair?: AiRepair;
7094
7180
  images?: string[];
7095
7181
  /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
7096
7182
  * URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
@@ -7137,6 +7223,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7137
7223
  thinking_level?: AiThinkingLevel;
7138
7224
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7139
7225
  media_resolution?: AiMediaResolution;
7226
+ /** Anthropic effort — see AiEffort. */
7227
+ effort?: AiEffort;
7140
7228
  tools?: Array<{
7141
7229
  name: string;
7142
7230
  description?: string;
@@ -7176,6 +7264,8 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7176
7264
  thinking_level?: AiThinkingLevel;
7177
7265
  /** Gemini per-image / per-page token budget — see AiMediaResolution. */
7178
7266
  media_resolution?: AiMediaResolution;
7267
+ /** Anthropic effort — see AiEffort. */
7268
+ effort?: AiEffort;
7179
7269
  tools?: Array<{
7180
7270
  name: string;
7181
7271
  description?: string;
@@ -7186,8 +7276,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7186
7276
  /** JSON Schema the completion must satisfy — same contract as
7187
7277
  * `generate`; the validated answer lands in the replay buffer (a
7188
7278
  * schema-mismatch delivers finish:'schema_mismatch' on the terminal
7189
- * usage frame). */
7279
+ * usage frame, or the provider's own word when the answer could not be
7280
+ * repaired). */
7190
7281
  response_schema?: Record<string, unknown>;
7282
+ /** See AiRepair: `false` = no repair call on an invalid structured answer. */
7283
+ repair?: AiRepair;
7191
7284
  images?: string[];
7192
7285
  /** DOCUMENT inputs (pdf / plain text), up to 8 refs, each a public https
7193
7286
  * URL, a `data:application/pdf;base64,…` (or `text/plain`) URL, or
@@ -7883,8 +7976,9 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7883
7976
  * subscription — use `cancel`; a production store row ends when the store
7884
7977
  * cancels or refunds it). Never touches a provider; a revoked RevenueCat
7885
7978
  * row is never revived by a later sandbox delivery or restore (a real
7886
- * production purchase still entitles the user). Credits the row
7887
- * already granted stay. */
7979
+ * production purchase still entitles the user). Revoke the user's
7980
+ * restored (`<app user id>:<product>`) row too if they have one: it is a
7981
+ * separate row. Credits the row already granted stay. */
7888
7982
  revokeSubscription: (subscriptionId: string) => Promise<{
7889
7983
  subscription_id: string;
7890
7984
  status: string;
@@ -7892,10 +7986,21 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7892
7986
  revoked_at: string | null;
7893
7987
  }>;
7894
7988
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
7895
- * fold them through the same conditional upsert a webhook uses (never a
7896
- * second write path). `dry_run` diffs without writing. Capped 30/min per
7897
- * project (429 rate_limited). The migration backfill (`vxil migrate
7898
- * payments --from-provider …`) drives this per customer. */
7989
+ * fold them through the same conditional upsert a webhook uses (a stale
7990
+ * snapshot never moves a newer row). `dry_run` diffs without writing.
7991
+ * Capped 30/min per project (429 rate_limited). The migration backfill
7992
+ * (`vxil migrate payments --from-provider …`) drives this per customer.
7993
+ *
7994
+ * RevenueCat: the subscriber read has no original transaction id, so a
7995
+ * snapshot is matched to the webhook row of the SAME store purchase — an
7996
+ * ended product only by its exact store transaction (else it is listed in
7997
+ * `not_folded` and nothing is written); a live one also by a live row of the
7998
+ * same store, environment and current product. With no match a live
7999
+ * product gets its own row (`<app user id>:<product>`) that ends at its
8000
+ * own period end and that the purchase's first webhook takes over. Emits
8001
+ * `payments.subscription.<status>` (`event_type: 'subscription.synced'`)
8002
+ * for each row it changes and `payments.entitlement.changed` (`reason:
8003
+ * 'subscription.synced'`) when access changed. */
7899
8004
  syncSubscriptions: (input: {
7900
8005
  user_id?: string;
7901
8006
  customer_ref?: string;
@@ -7905,7 +8010,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
7905
8010
  /** The server leg of "Restore Purchases": in end-user mode the verified
7906
8011
  * principal's OWN provider state is re-read (no user id needed); in server
7907
8012
  * mode pass `user_id`. 3 per hour per user (429). Returns the sync outcome
7908
- * plus the fresh entitlement view in one answer. */
8013
+ * plus the fresh entitlement view in one answer. The same matching and
8014
+ * events as `syncSubscriptions`, with `event_type` / `reason`
8015
+ * `'subscription.restored'`; in end-user mode an unmatched ended product
8016
+ * is listed in `not_folded` as `<id>: not_restored`. */
7909
8017
  restoreSubscriptions: (input?: {
7910
8018
  user_id?: string;
7911
8019
  provider?: "mock" | "stripe" | "paddle" | "revenuecat" | "paypal";
package/dist/index.js CHANGED
@@ -1520,7 +1520,13 @@ export class Vxil {
1520
1520
  },
1521
1521
  /** List a user's active sessions (the account "signed-in devices" surface).
1522
1522
  * Scope `auth:read`. In end-user mode the list is bound to the signed-in
1523
- * user regardless of `userId` (the verified principal wins). */
1523
+ * user regardless of `userId` (the verified principal wins). Each
1524
+ * session says `state` — `active` while its access token is valid,
1525
+ * `idle` when only its refresh token is — and `refresh_expires_at`
1526
+ * (null for a canary session, which never refreshes). Today only
1527
+ * `active` sessions are listed; idle devices are listed (and counted by
1528
+ * `session.maxConcurrent`) from the release the changelog's Coming next
1529
+ * names. */
1524
1530
  list: async (userId) => (await this.call('GET', `/v1/auth/sessions?user_id=${encodeURIComponent(userId)}`)).data.sessions,
1525
1531
  },
1526
1532
  password: {
@@ -3152,19 +3158,34 @@ export class Vxil {
3152
3158
  * subscription — use `cancel`; a production store row ends when the store
3153
3159
  * cancels or refunds it). Never touches a provider; a revoked RevenueCat
3154
3160
  * row is never revived by a later sandbox delivery or restore (a real
3155
- * production purchase still entitles the user). Credits the row
3156
- * already granted stay. */
3161
+ * production purchase still entitles the user). Revoke the user's
3162
+ * restored (`<app user id>:<product>`) row too if they have one: it is a
3163
+ * separate row. Credits the row already granted stay. */
3157
3164
  revokeSubscription: async (subscriptionId) => (await this.call('POST', `/v1/payments/subscriptions/${encodeURIComponent(subscriptionId)}/revoke`)).data,
3158
3165
  /** SERVER-ONLY. Re-read a customer's subscriptions FROM the provider and
3159
- * fold them through the same conditional upsert a webhook uses (never a
3160
- * second write path). `dry_run` diffs without writing. Capped 30/min per
3161
- * project (429 rate_limited). The migration backfill (`vxil migrate
3162
- * payments --from-provider …`) drives this per customer. */
3166
+ * fold them through the same conditional upsert a webhook uses (a stale
3167
+ * snapshot never moves a newer row). `dry_run` diffs without writing.
3168
+ * Capped 30/min per project (429 rate_limited). The migration backfill
3169
+ * (`vxil migrate payments --from-provider …`) drives this per customer.
3170
+ *
3171
+ * RevenueCat: the subscriber read has no original transaction id, so a
3172
+ * snapshot is matched to the webhook row of the SAME store purchase — an
3173
+ * ended product only by its exact store transaction (else it is listed in
3174
+ * `not_folded` and nothing is written); a live one also by a live row of the
3175
+ * same store, environment and current product. With no match a live
3176
+ * product gets its own row (`<app user id>:<product>`) that ends at its
3177
+ * own period end and that the purchase's first webhook takes over. Emits
3178
+ * `payments.subscription.<status>` (`event_type: 'subscription.synced'`)
3179
+ * for each row it changes and `payments.entitlement.changed` (`reason:
3180
+ * 'subscription.synced'`) when access changed. */
3163
3181
  syncSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/sync', input)).data,
3164
3182
  /** The server leg of "Restore Purchases": in end-user mode the verified
3165
3183
  * principal's OWN provider state is re-read (no user id needed); in server
3166
3184
  * mode pass `user_id`. 3 per hour per user (429). Returns the sync outcome
3167
- * plus the fresh entitlement view in one answer. */
3185
+ * plus the fresh entitlement view in one answer. The same matching and
3186
+ * events as `syncSubscriptions`, with `event_type` / `reason`
3187
+ * `'subscription.restored'`; in end-user mode an unmatched ended product
3188
+ * is listed in `not_folded` as `<id>: not_restored`. */
3168
3189
  restoreSubscriptions: async (input) => (await this.call('POST', '/v1/payments/subscriptions/restore', input ?? {})).data,
3169
3190
  /** SERVER-ONLY. Account merge: move EVERY provider's subscriptions,
3170
3191
  * customer links and available credit balances of `from_user_id` onto
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vxil/sdk",
3
- "version": "0.37.0",
3
+ "version": "0.38.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).",