pareta 2.0.0 → 2.1.0

package/dist/index.d.cts

@@ -47,6 +47,17 @@ declare class ChatCompletion extends BaseModel {
     get created(): number | null;
     get choices(): Choice[];
     get usage(): Usage;
+    /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+    private _cost?;
+    /** #164: attach the per-call receipt from the response headers (billed +
+     * the frontier counterfactual, micro-USD ints). Chainable. */
+    withCost(headers?: Headers): ChatCompletion;
+    /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+    get billedMicroUsd(): number | null;
+    /** What one list-priced frontier call would have cost, micro-USD. */
+    get frontierWouldHaveCostMicroUsd(): number | null;
+    /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+    get savingsFactor(): number | null;
 }
 /** One SSE delta. `chunk.choices[0].delta.content` is the incremental text. */
 declare class ChatCompletionChunk extends ChatCompletion {
@@ -632,6 +643,9 @@ interface RequestOptions {
     files?: Record<string, FilePart>;
     data?: Record<string, string>;
     cast?: (raw: unknown) => unknown;
+    /** Invoked with the response headers on success (before the body is cast) —
+     * lets a caller read receipt headers (#164: X-Pareta-Billed + counterfactual). */
+    onHeaders?: (headers: Headers) => void;
 }
 interface StreamOptions {
     body?: unknown;
@@ -698,7 +712,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "2.0.0";
+declare const VERSION = "2.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python

package/dist/index.d.ts

@@ -47,6 +47,17 @@ declare class ChatCompletion extends BaseModel {
     get created(): number | null;
     get choices(): Choice[];
     get usage(): Usage;
+    /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+    private _cost?;
+    /** #164: attach the per-call receipt from the response headers (billed +
+     * the frontier counterfactual, micro-USD ints). Chainable. */
+    withCost(headers?: Headers): ChatCompletion;
+    /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+    get billedMicroUsd(): number | null;
+    /** What one list-priced frontier call would have cost, micro-USD. */
+    get frontierWouldHaveCostMicroUsd(): number | null;
+    /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+    get savingsFactor(): number | null;
 }
 /** One SSE delta. `chunk.choices[0].delta.content` is the incremental text. */
 declare class ChatCompletionChunk extends ChatCompletion {
@@ -632,6 +643,9 @@ interface RequestOptions {
     files?: Record<string, FilePart>;
     data?: Record<string, string>;
     cast?: (raw: unknown) => unknown;
+    /** Invoked with the response headers on success (before the body is cast) —
+     * lets a caller read receipt headers (#164: X-Pareta-Billed + counterfactual). */
+    onHeaders?: (headers: Headers) => void;
 }
 interface StreamOptions {
     body?: unknown;
@@ -698,7 +712,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "2.0.0";
+declare const VERSION = "2.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python

package/dist/index.mjs

@@ -172,7 +172,7 @@ function parseSSE(reader, opts) {
 }
 
 // src/version.ts
-var VERSION = "2.0.0";
+var VERSION = "2.1.0";
 
 // src/money.ts
 var MICRO_PER_CENT = 10000n;
@@ -253,6 +253,36 @@ var ChatCompletion = class extends BaseModel {
   get usage() {
     return new Usage(this.raw.usage ?? {});
   }
+  /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+  _cost;
+  /** #164: attach the per-call receipt from the response headers (billed +
+   * the frontier counterfactual, micro-USD ints). Chainable. */
+  withCost(headers) {
+    const int = (name) => {
+      const v = headers?.get(name);
+      if (v == null) return null;
+      const n = parseInt(v, 10);
+      return Number.isNaN(n) ? null : n;
+    };
+    this._cost = {
+      billed: int("X-Pareta-Billed"),
+      frontier: int("X-Pareta-Frontier-Would-Have-Cost")
+    };
+    return this;
+  }
+  /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+  get billedMicroUsd() {
+    return this._cost?.billed ?? null;
+  }
+  /** What one list-priced frontier call would have cost, micro-USD. */
+  get frontierWouldHaveCostMicroUsd() {
+    return this._cost?.frontier ?? null;
+  }
+  /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+  get savingsFactor() {
+    const b = this.billedMicroUsd, f = this.frontierWouldHaveCostMicroUsd;
+    return b && f && b > 0 ? Math.round(f / b * 10) / 10 : null;
+  }
 };
 var ChatCompletionChunk = class extends ChatCompletion {
 };
@@ -642,10 +672,14 @@ var Completions = class {
         cast: (raw) => new ChatCompletionChunk(raw)
       });
     }
+    let headers;
     return this.client.request("POST", PATH, {
       body,
-      cast: (raw) => new ChatCompletion(raw)
-    });
+      cast: (raw) => new ChatCompletion(raw),
+      onHeaders: (h) => {
+        headers = h;
+      }
+    }).then((completion) => completion.withCost(headers));
   }
 };
 var Chat = class {
@@ -1308,6 +1342,7 @@ var Pareta = class _Pareta {
         break;
       }
       if (res.ok) {
+        if (opts.onHeaders) opts.onHeaders(res.headers);
         const text = await res.text();
         const raw = text ? JSON.parse(text) : {};
         return cast ? cast(raw) : raw;