@vxil/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -8,7 +8,7 @@ export type ApiVersion = 'v1';
  *  (`/v1/<namespace>/…`). Matches the segment `versionedPath` rewrites, so an
  *  override changes exactly that namespace's paths. Renamed client accessors map
  *  onto their real namespaces (`vx.search` → `search`, `vx.feeds` → `feeds`). */
-export type FeatureKey = 'users' | 'notifications' | 'config' | 'features' | 'audit' | 'jobs' | 'auth' | 'rate-limits' | 'files' | 'cms' | 'comments' | 'dm' | 'feeds' | 'realtime' | 'orgs' | 'webhooks' | 'search' | 'ai' | 'rag' | 'payments' | 'fn' | 'copilot';
+export type FeatureKey = 'users' | 'notifications' | 'config' | 'features' | 'audit' | 'usage' | 'jobs' | 'auth' | 'rate-limits' | 'files' | 'cms' | 'comments' | 'dm' | 'feeds' | 'realtime' | 'orgs' | 'webhooks' | 'search' | 'ai' | 'rag' | 'payments' | 'fn' | 'copilot';
 export interface VxilOptions {
     apiKey: string;
     /** defaults to the production edge */
@@ -131,6 +131,33 @@ export interface VxilPlan {
     /** which brain produced the plan. */
     source: 'ai' | 'deterministic';
 }
+/** Current-month usage projection (GET /v1/usage) — the same meter the
+ *  platform bills and enforces request quotas from. */
+export interface UsageCurrent {
+    /** the current UTC month, 'YYYY-MM'. */
+    period: string;
+    /** the plan tier the quota is derived from. */
+    tier: string;
+    requests: {
+        /** requests recorded this month (0 until the meter has rows). */
+        used: number;
+        /** the plan's included monthly requests; null = no fixed cap. */
+        quota: number | null;
+        /** max(quota − used, 0); null when quota is null. */
+        remaining: number | null;
+        /** the PLAN's hard-cap policy — true only on the free tier (which is cut
+         *  off with 429 quota_exceeded when exhausted); paid tiers are never
+         *  interrupted mid-month. Not a live "the next request will 429" signal. */
+        enforced: boolean;
+    };
+    /** month-to-date per-feature metered detail. Aggregated periodically — it
+     *  may lag and may be empty. */
+    features: Array<{
+        feature: string;
+        metric: string;
+        quantity: number;
+    }>;
+}
 export interface DeadLetter {
     delivery_id: string;
     template_id: string;
@@ -351,6 +378,12 @@ export interface AiGeneration {
     usage: AiUsage;
     finish: string;
     tool_calls?: AiToolCall[];
+    /** the parsed JSON output — present when the request (or its template)
+     *  carried a response schema; guaranteed to satisfy it (a 200 never violates
+     *  the schema — final-invalid is a 422 output_schema_mismatch). */
+    output?: unknown;
+    /** true when the output only validated after the single repair pass. */
+    repaired?: boolean;
     cached: boolean;
 }
 /** A streamed generation handle: open the realtime channel for token frames. */
@@ -1249,6 +1282,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
         }>;
     };
+    /** Current-month usage: requests used vs the plan's included quota, plus
+     *  month-to-date per-feature metered detail. Read-only (needs `usage:read`
+     *  or `features:read`). Agents: call this before a bulk run to self-check
+     *  remaining quota. */
+    readonly usage: {
+        current: () => Promise<UsageCurrent>;
+    };
     readonly jobs: {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
@@ -2730,7 +2770,10 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
     readonly ai: {
         templates: {
             /** Store a tenant-authored prompt template; versions are monotonic per name.
-             *  `{{var}}` placeholders are filled from `generate`'s `input`. */
+             *  `{{var}}` placeholders are filled from `generate`'s `input`.
+             *  `schema` (a JSON Schema) is now ENFORCED at generate time on sync/job
+             *  requests — the output is validated (with one repair pass) against it;
+             *  a per-request `response_schema` overrides it. Ignored on streams. */
             put: (input: {
                 template: string;
                 user: string;
@@ -2772,6 +2815,13 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
              *  role:'tool' results) — vxil relays; you execute the tools. */
             messages?: AiChatMessage[];
             json_mode?: boolean;
+            /** JSON Schema the completion must satisfy (schema-guaranteed structured
+             *  output): enforced natively where the provider supports strict
+             *  structured output, else via one validate-and-repair pass; the parsed
+             *  object lands in `output` (+`repaired` when the repair pass fired). A
+             *  still-invalid result is a 422 `output_schema_mismatch` (billed). Wins
+             *  over the template's stored schema. */
+            response_schema?: Record<string, unknown>;
             images?: string[];
             user_id?: string;
         }) => Promise<AiGeneration>;
@@ -2823,6 +2873,11 @@ export declare class Vxil<S extends VxilSchemaShape = VxilSchemaShape> {
             }>;
             messages?: AiChatMessage[];
             json_mode?: boolean;
+            /** JSON Schema the completion must satisfy — same contract as
+             *  `generate`; the validated answer lands in the replay buffer (a
+             *  schema-mismatch delivers finish:'schema_mismatch' on the terminal
+             *  usage frame). */
+            response_schema?: Record<string, unknown>;
             images?: string[];
             user_id?: string;
         }) => Promise<AiJobHandle>;

package/dist/index.js

@@ -429,6 +429,13 @@ export class Vxil {
             };
         },
     };
+    /** Current-month usage: requests used vs the plan's included quota, plus
+     *  month-to-date per-feature metered detail. Read-only (needs `usage:read`
+     *  or `features:read`). Agents: call this before a bulk run to self-check
+     *  remaining quota. */
+    usage = {
+        current: async () => (await this.call('GET', '/v1/usage')).data,
+    };
     jobs = {
         /** Enqueue a one-off job; Vxil POSTs a signed callback to target_url with
          * retries. deliver_after (ISO) / delay_seconds (≤ 30 d, at most one of the
@@ -1190,7 +1197,10 @@ export class Vxil {
     ai = {
         templates: {
             /** Store a tenant-authored prompt template; versions are monotonic per name.
-             *  `{{var}}` placeholders are filled from `generate`'s `input`. */
+             *  `{{var}}` placeholders are filled from `generate`'s `input`.
+             *  `schema` (a JSON Schema) is now ENFORCED at generate time on sync/job
+             *  requests — the output is validated (with one repair pass) against it;
+             *  a per-request `response_schema` overrides it. Ignored on streams. */
             put: async (input) => (await this.call('POST', '/v1/ai/templates', input)).data,
             /** List stored templates (each name + its latest version). */
             list: async () => (await this.call('GET', '/v1/ai/templates')).data.templates,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "description": "Typed client for the Vxil REST API (notifications, auth, jobs, files, cms, comments, webhooks, realtime, orgs, rate-limits).",