@plurnk/plurnk-providers 1.5.0 → 1.6.0

package/src/accounting.ts

@@ -1,6 +1,17 @@
 import type {
-    AuthoritativeChargeNormalizer,
+    ChargedCost,
+    ProviderAccounting,
+    ProviderCost,
+    ProviderCostNormalizer,
+    ProviderRequestAccounting,
+    ProviderUsage,
 } from "./types.ts";
+import {
+    sumProviderCostsUsd,
+    validateChargedCost,
+    validateProviderCost,
+} from "./cost.ts";
+import { validateProviderUsage } from "./usage.ts";
 
 const recordOf = (value: unknown): Record<string, unknown> | null =>
     typeof value === "object" && value !== null && !Array.isArray(value)
@@ -33,7 +44,7 @@ const usdFromTicks = (ticks: number): string => {
     return fraction === "" ? integer : `${integer}.${fraction}`;
 };
 
-const xaiCharge: AuthoritativeChargeNormalizer = ({ usage }) => {
+const xaiCost: ProviderCostNormalizer = ({ usage }) => {
     const wireUsage = recordOf(usage);
     if (wireUsage === null || !("cost_in_usd_ticks" in wireUsage)) return undefined;
     const ticks = wireUsage.cost_in_usd_ticks;
@@ -41,48 +52,139 @@ const xaiCharge: AuthoritativeChargeNormalizer = ({ usage }) => {
         throw new TypeError("xAI usage.cost_in_usd_ticks must be numeric");
     }
     return {
-        kind: "authoritative",
+        kind: "charged",
         amount: { amount: String(ticks), currency: "USDTICK" },
         usdEquivalent: usdFromTicks(ticks),
         source: "xAI response usage.cost_in_usd_ticks",
     };
 };
 
-const openRouterCharge: AuthoritativeChargeNormalizer = ({ providerMetadata }) => {
+const openRouterCost: ProviderCostNormalizer = ({ providerMetadata }) => {
     const usage = recordOf(recordOf(recordOf(providerMetadata)?.openrouter)?.usage);
     if (usage === null || !("cost" in usage)) return undefined;
     const cost = usage.cost;
     if (typeof cost !== "number") throw new TypeError("OpenRouter usage.cost must be numeric");
-    const amount = decimalFromNumber(cost, "OpenRouter usage.cost");
     return {
-        kind: "authoritative",
-        amount: { amount, currency: "USD" },
-        usdEquivalent: amount,
+        kind: "charged",
+        amount: { amount: decimalFromNumber(cost, "OpenRouter usage.cost"), currency: "USD" },
         source: "OpenRouter response usage.cost",
     };
 };
 
-const deepInfraCharge: AuthoritativeChargeNormalizer = ({ usage }) => {
+const deepInfraCost: ProviderCostNormalizer = ({ usage }) => {
     const wireUsage = recordOf(usage);
     if (wireUsage === null || !("estimated_cost" in wireUsage)) return undefined;
     const cost = wireUsage.estimated_cost;
     if (typeof cost !== "number") throw new TypeError("DeepInfra usage.estimated_cost must be numeric");
-    const amount = decimalFromNumber(cost, "DeepInfra usage.estimated_cost");
     return {
-        kind: "authoritative",
-        amount: { amount, currency: "USD" },
-        usdEquivalent: amount,
+        kind: "estimated",
+        amount: { amount: decimalFromNumber(cost, "DeepInfra usage.estimated_cost"), currency: "USD" },
         source: "DeepInfra response usage.estimated_cost",
     };
 };
 
-export const authoritativeChargeNormalizer = (
+// The first-party endpoint owns the direct charged-cost wire field.
+export const plurnkCostNormalizer: ProviderCostNormalizer = ({ charge }) => {
+    if (charge === undefined) return undefined;
+    return validateChargedCost(charge) as ChargedCost;
+};
+
+export const providerCostNormalizer = (
     sdkPackage: string,
-): AuthoritativeChargeNormalizer | undefined => {
+): ProviderCostNormalizer | undefined => {
     switch (sdkPackage) {
-        case "@ai-sdk/xai": return xaiCharge;
-        case "@ai-sdk/deepinfra": return deepInfraCharge;
-        case "@openrouter/ai-sdk-provider": return openRouterCharge;
+        case "@ai-sdk/xai": return xaiCost;
+        case "@ai-sdk/deepinfra": return deepInfraCost;
+        case "@openrouter/ai-sdk-provider": return openRouterCost;
         default: return undefined;
     }
 };
+
+export const validateProviderRequestAccounting = (
+    value: unknown,
+): ProviderRequestAccounting => {
+    const request = recordOf(value);
+    if (request === null) throw new TypeError("provider request accounting must be an object");
+    if (typeof request.provider !== "string" || request.provider.length === 0) {
+        throw new TypeError("provider request accounting.provider must be non-empty");
+    }
+    if (typeof request.model !== "string" || request.model.length === 0) {
+        throw new TypeError("provider request accounting.model must be non-empty");
+    }
+    if (request.outcome !== "response" && request.outcome !== "error") {
+        throw new TypeError("provider request accounting.outcome must be response or error");
+    }
+    if (request.status !== undefined
+        && (!Number.isInteger(request.status) || (request.status as number) < 100 || (request.status as number) > 599)) {
+        throw new TypeError("provider request accounting.status must be an HTTP status");
+    }
+    if (request.usage !== undefined) validateProviderUsage(request.usage as ProviderUsage);
+    validateProviderCost(request.cost);
+    return value as ProviderRequestAccounting;
+};
+
+const sumKnown = (
+    requests: readonly ProviderRequestAccounting[],
+    read: (usage: ProviderUsage) => number | undefined,
+): number | undefined => {
+    const values = requests.map((request) => request.usage === undefined
+        ? undefined
+        : read(request.usage));
+    return values.some((value) => value === undefined)
+        ? undefined
+        : (values as number[]).reduce((sum, value) => sum + value, 0);
+};
+
+export const aggregateProviderAccounting = (
+    values: readonly ProviderRequestAccounting[],
+): ProviderAccounting => {
+    const requests = values.map(validateProviderRequestAccounting);
+    if (requests.length === 0) {
+        return {
+            requests: [],
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                totalTokens: 0,
+                inputTokenDetails: {
+                    noCacheTokens: 0,
+                    cacheReadTokens: 0,
+                    cacheWriteTokens: 0,
+                },
+                outputTokenDetails: { textTokens: 0, reasoningTokens: 0 },
+            },
+            costUsd: "0",
+        };
+    }
+
+    const inputTokens = sumKnown(requests, (usage) => usage.inputTokens);
+    const outputTokens = sumKnown(requests, (usage) => usage.outputTokens);
+    const totalTokens = sumKnown(requests, (usage) => usage.totalTokens);
+    const noCacheTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.noCacheTokens);
+    const cacheReadTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.cacheReadTokens);
+    const cacheWriteTokens = sumKnown(requests, (usage) => usage.inputTokenDetails?.cacheWriteTokens);
+    const textTokens = sumKnown(requests, (usage) => usage.outputTokenDetails?.textTokens);
+    const reasoningTokens = sumKnown(requests, (usage) => usage.outputTokenDetails?.reasoningTokens);
+    const inputTokenDetails = noCacheTokens === undefined
+        && cacheReadTokens === undefined && cacheWriteTokens === undefined
+        ? undefined
+        : { noCacheTokens, cacheReadTokens, cacheWriteTokens };
+    const outputTokenDetails = textTokens === undefined && reasoningTokens === undefined
+        ? undefined
+        : { textTokens, reasoningTokens };
+    const usage = inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
+        && inputTokenDetails === undefined && outputTokenDetails === undefined
+        ? null
+        : validateProviderUsage({
+            ...(inputTokens === undefined ? {} : { inputTokens }),
+            ...(outputTokens === undefined ? {} : { outputTokens }),
+            ...(totalTokens === undefined ? {} : { totalTokens }),
+            ...(inputTokenDetails === undefined ? {} : { inputTokenDetails }),
+            ...(outputTokenDetails === undefined ? {} : { outputTokenDetails }),
+        });
+    return {
+        requests: [...requests],
+        usage,
+        costUsd: sumProviderCostsUsd(requests.map(({ cost }) => cost)),
+    };
+};

package/src/aiSdkTransport.test.ts

@@ -1,5 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { APICallError } from "ai";
 import { executeOpenAICompatible } from "./aiSdkTransport.ts";
 
 const request = {
@@ -9,29 +10,33 @@ const request = {
     body: {},
     messages: [{ role: "user" as const, content: "question" }],
     fetchTimeoutMs: 1_000,
-    retryAttempts: 2,
     streaming: false,
     captureRawBody: false,
 };
 
-test("X-Should-Retry:false prevents nested retries for a normally retryable status", async () => {
+test("the transport performs exactly one physical request", async () => {
     let calls = 0;
-    await assert.rejects(executeOpenAICompatible({
-        ...request,
-        fetch: async () => {
-            calls += 1;
-            return new Response(
-                JSON.stringify({ error: { message: "upstream attempts exhausted" } }),
-                {
-                    status: 503,
-                    headers: {
-                        "content-type": "application/json",
-                        "x-should-retry": "false",
+    await assert.rejects(
+        executeOpenAICompatible({
+            ...request,
+            fetch: async () => {
+                calls += 1;
+                return new Response(
+                    JSON.stringify({ error: { message: "upstream attempts exhausted" } }),
+                    {
+                        status: 503,
+                        headers: {
+                            "content-type": "application/json",
+                            "x-should-retry": "false",
+                        },
                     },
-                },
-            );
-        },
-    }));
+                );
+            },
+        }),
+        (error) => APICallError.isInstance(error)
+            && error.statusCode === 503
+            && error.isRetryable === false,
+    );
     assert.equal(calls, 1);
 });
 
@@ -64,7 +69,6 @@ test("the adapter preserves PLURNK request extensions and response evidence", as
     };
     const result = await executeOpenAICompatible({
         ...request,
-        retryAttempts: 0,
         captureRawBody: true,
         body: {
             grammar: "root ::= \"answer\"",
@@ -85,11 +89,10 @@ test("the adapter preserves PLURNK request extensions and response evidence", as
     assert.equal(result.reasoning, "because");
     assert.equal(result.finishReason, "stop");
     assert.deepEqual(result.usage, {
-        prompt: 3,
-        completion: 3,
-        reasoning: 2,
-        cached: 0,
-        total: 8,
+        inputTokens: 3,
+        outputTokens: 5,
+        totalTokens: 8,
+        outputTokenDetails: { textTokens: 3, reasoningTokens: 2 },
     });
     assert.equal(result.logprobs[0]?.token, "answer");
     assert.deepEqual(result.metadata.balance, { amount: 1.25, currency: "USD" });
@@ -116,7 +119,6 @@ test("the adapter maps leading system messages to AI SDK instructions", async ()
             { role: "user", content: "hello" },
         ],
         fetchTimeoutMs: 1000,
-        retryAttempts: 0,
         streaming: false,
         captureRawBody: false,
         fetch,
@@ -130,7 +132,6 @@ test("the adapter maps leading system messages to AI SDK instructions", async ()
 test("the adapter preserves nonstandard reasoning accounting after SDK parsing", async (t) => {
     const execute = (responseBody: object) => executeOpenAICompatible({
         ...request,
-        retryAttempts: 0,
         fetch: async () => new Response(JSON.stringify(responseBody), {
             headers: { "content-type": "application/json" },
         }),
@@ -153,25 +154,22 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             { prompt_tokens: 2, completion_tokens: 3, total_tokens: 9 },
         ));
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 3,
-            reasoning: 4,
-            cached: 0,
-            total: 9,
+            inputTokens: 2,
+            outputTokens: 7,
+            totalTokens: 9,
+            outputTokenDetails: { textTokens: 3, reasoningTokens: 4 },
         });
     });
 
-    await t.test("Fireworks-style unitemized output is split by returned channels", async () => {
+    await t.test("Fireworks-style channels do not invent token attribution", async () => {
         const result = await execute(response(
             { content: "aa", reasoning_content: "bbbbbb" },
             { prompt_tokens: 2, completion_tokens: 10, total_tokens: 12 },
         ));
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 2,
-            reasoning: 8,
-            cached: 0,
-            total: 12,
+            inputTokens: 2,
+            outputTokens: 10,
+            totalTokens: 12,
         });
     });
 
@@ -195,7 +193,6 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
         ];
         const result = await executeOpenAICompatible({
             ...request,
-            retryAttempts: 0,
             streaming: true,
             fetch: async () => new Response(
                 `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`,
@@ -203,15 +200,14 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             ),
         });
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 3,
-            reasoning: 4,
-            cached: 0,
-            total: 9,
+            inputTokens: 2,
+            outputTokens: 7,
+            totalTokens: 9,
+            outputTokenDetails: { textTokens: 3, reasoningTokens: 4 },
         });
     });
 
-    await t.test("streamed Fireworks-style channels preserve the output split", async () => {
+    await t.test("streamed Fireworks-style channels do not invent an output split", async () => {
         const chunks = [
             {
                 id: "response-1",
@@ -235,7 +231,6 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
         ];
         const result = await executeOpenAICompatible({
             ...request,
-            retryAttempts: 0,
             streaming: true,
             fetch: async () => new Response(
                 `${chunks.map((chunk) => `data: ${JSON.stringify(chunk)}\n\n`).join("")}data: [DONE]\n\n`,
@@ -243,11 +238,9 @@ test("the adapter preserves nonstandard reasoning accounting after SDK parsing",
             ),
         });
         assert.deepEqual(result.usage, {
-            prompt: 2,
-            completion: 2,
-            reasoning: 8,
-            cached: 0,
-            total: 12,
+            inputTokens: 2,
+            outputTokens: 10,
+            totalTokens: 12,
         });
     });
 });