@useautumn/gateway 0.0.1

package/LICENSE.md

@@ -0,0 +1,7 @@
+The MIT License (MIT) Copyright (c) 2025 - present, Recase Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @useautumn/gateway
+
+[Autumn](https://useautumn.com) adapters for AI SDKs and gateways. Wrap your model or client once and every LLM call's token usage is tracked against the customer's AI credit balance — no manual `trackTokens` calls.
+
+Autumn converts the token counts to a dollar cost server-side using live [models.dev](https://models.dev) rates plus your configured markup, so pricing changes never require a client redeploy.
+
+## Install
+
+```bash
+npm install @useautumn/gateway
+# or
+bun add @useautumn/gateway
+```
+
+Authentication: pass an `autumn` client (from `autumn-js`), or set `AUTUMN_API_KEY` (or `AUTUMN_SECRET_KEY`) in the environment and omit it.
+
+## Vercel AI SDK
+
+```ts
+import { openai } from "@ai-sdk/openai";
+import { generateText } from "ai";
+import { withAutumn } from "@useautumn/gateway/ai-sdk";
+
+const model = withAutumn({
+  model: openai("gpt-4o"),
+  customerId: "user_123",
+});
+
+const { text } = await generateText({ model, prompt: "Hello!" });
+// usage tracked automatically — streaming too
+```
+
+The wrapped model is a drop-in `LanguageModelV3`. Usage is read from the response (or the stream's finish chunk) and reported as `<provider>/<model>` (e.g. `anthropic/claude-sonnet-4-5`). If your provider's name doesn't match its models.dev key, override it with `providerId`.
+
+## OpenRouter
+
+```ts
+import { OpenRouter } from "@openrouter/sdk";
+import { withAutumn, trackingSettled } from "@useautumn/gateway/openrouter";
+
+const client = withAutumn({
+  openRouter: new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY }),
+  customerId: "user_123",
+});
+
+const result = await client.chat.send({
+  model: "openai/gpt-4o",
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+The wrapper forces OpenRouter usage accounting on every request, tracks `chat.send` (streaming and non-streaming) and the responses API (including `@openrouter/agent`'s `callModel`), and reports models as `openrouter/<slug>` using the response's resolved model — router aliases like `openrouter/auto` bill against the model that actually served the request. OpenRouter's own reported charge is attached to each event as `openrouter_cost`.
+
+Streaming usage is tracked in the background; call `await trackingSettled(client)` before reading balances that must reflect calls just made. For consumption patterns the wrapper doesn't cover, `trackOpenRouterUsage({ usage, model, customerId })` accepts both SDK camelCase and raw snake_case usage objects.
+
+## Options
+
+Both adapters accept the shared tracking options:
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `customerId` | Yes | Autumn customer ID to attribute usage to |
+| `autumn` | No | `autumn-js` client; falls back to `AUTUMN_API_KEY` env |
+| `featureId` | No | Target AI credit system feature (auto-detected if you have one) |
+| `entityId` | No | Entity for entity-scoped balances |
+| `properties` | No | Extra properties attached to each usage event |
+
+Tracking failures are caught and logged — they never break your AI responses.
+
+## Docs
+
+- [Vercel AI SDK guide](https://docs.useautumn.com/documentation/external-providers/ai-sdk)
+- [OpenRouter guide](https://docs.useautumn.com/documentation/external-providers/openrouter)
+- [trackTokens API reference](https://docs.useautumn.com/api-reference/balances/trackTokens)

package/dist/ai-sdk/index.cjs

@@ -0,0 +1,214 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ai-sdk/index.ts
+var ai_sdk_exports = {};
+__export(ai_sdk_exports, {
+  withAutumn: () => withAutumn
+});
+module.exports = __toCommonJS(ai_sdk_exports);
+var import_ai = require("ai");
+
+// src/shared/track.ts
+var WIRE_KEYS = {
+  customerId: "customer_id",
+  entityId: "entity_id",
+  featureId: "feature_id",
+  modelId: "model_id",
+  inputTokens: "input_tokens",
+  outputTokens: "output_tokens",
+  cacheReadTokens: "cache_read_tokens",
+  cacheWriteTokens: "cache_write_tokens",
+  audioInputTokens: "audio_input_tokens",
+  audioOutputTokens: "audio_output_tokens",
+  reasoningTokens: "reasoning_tokens"
+};
+var toWire = (params) => Object.fromEntries(
+  Object.entries(params).filter(([, value]) => value !== void 0).map(([key, value]) => [WIRE_KEYS[key] ?? key, value])
+);
+var envClient = () => {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  const secretKey = env?.AUTUMN_API_KEY ?? env?.AUTUMN_SECRET_KEY;
+  const baseUrl = env?.AUTUMN_BASE_URL ?? "https://api.useautumn.com";
+  return {
+    trackTokens: async (params) => {
+      if (!secretKey) {
+        throw new Error(
+          "[Autumn] No autumn client was passed and AUTUMN_API_KEY is not set."
+        );
+      }
+      const response = await fetch(`${baseUrl}/v1/balances.track_tokens`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${secretKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(toWire(params))
+      });
+      if (!response.ok) {
+        throw new Error(
+          `track_tokens failed (${response.status}): ${await response.text()}`
+        );
+      }
+      return response.json();
+    }
+  };
+};
+var createTracker = ({
+  autumn = envClient(),
+  customerId,
+  featureId,
+  entityId,
+  properties
+}) => (getEvent) => trackTokenUsage({
+  autumn,
+  getParams: () => {
+    const event = getEvent();
+    return {
+      ...event.pools,
+      customerId,
+      modelId: event.modelId,
+      featureId,
+      entityId,
+      properties: event.properties ?? properties
+    };
+  }
+});
+var trackTokenUsage = async ({
+  autumn,
+  getParams
+}) => {
+  try {
+    const balances = autumn.balances;
+    const trackTokens = balances?.trackTokens?.bind(balances) ?? autumn.trackTokens?.bind(autumn);
+    if (!trackTokens) {
+      throw new Error(
+        "Autumn client does not support trackTokens \u2014 upgrade @useautumn/sdk."
+      );
+    }
+    await trackTokens(getParams());
+  } catch (error) {
+    console.error("[Autumn Tracking] Failed to track usage:", error);
+  }
+};
+
+// src/shared/usage.ts
+var clamp = (value) => Math.max(0, value);
+var requiredCount = (value, label, modelName) => {
+  if (value == null) {
+    throw new Error(
+      `[Autumn] ${label} token usage was not returned by the model provider (${modelName}). This provider may not support usage tracking.`
+    );
+  }
+  return value;
+};
+var poolsFromParts = (parts, modelName) => {
+  const cacheRead = parts.cacheRead ?? 0;
+  const cacheWrite = parts.cacheWrite ?? 0;
+  const reasoning = parts.reasoning ?? 0;
+  const audioInput = parts.audioInput ?? 0;
+  const textInput = parts.textInput ?? (parts.totalInput != null ? parts.totalInput - cacheRead - cacheWrite - audioInput : void 0);
+  const textOutput = parts.textOutput ?? (parts.totalOutput != null ? parts.totalOutput - reasoning : void 0);
+  return {
+    inputTokens: clamp(requiredCount(textInput, "Input", modelName)),
+    outputTokens: clamp(requiredCount(textOutput, "Output", modelName)),
+    cacheReadTokens: clamp(cacheRead),
+    cacheWriteTokens: clamp(cacheWrite),
+    reasoningTokens: clamp(reasoning),
+    ...parts.audioInput !== void 0 && {
+      audioInputTokens: clamp(audioInput)
+    }
+  };
+};
+
+// src/ai-sdk/usage.ts
+var flatCount = (value) => typeof value === "number" ? value : value?.total ?? void 0;
+var isNested = (value) => value != null && typeof value === "object";
+var toParts = (usage) => {
+  const input = usage.inputTokens;
+  const output = usage.outputTokens;
+  if (isNested(input)) {
+    const out = isNested(output) ? output : void 0;
+    return {
+      cacheRead: input.cacheRead ?? 0,
+      cacheWrite: input.cacheWrite ?? 0,
+      reasoning: out?.reasoning ?? 0,
+      textInput: input.noCache,
+      totalInput: input.total,
+      textOutput: out?.text,
+      totalOutput: out?.total
+    };
+  }
+  return {
+    cacheRead: usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens ?? 0,
+    cacheWrite: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
+    reasoning: usage.outputTokenDetails?.reasoningTokens ?? usage.reasoningTokens ?? 0,
+    textInput: usage.inputTokenDetails?.noCacheTokens,
+    totalInput: typeof input === "number" ? input : flatCount(usage.promptTokens),
+    textOutput: usage.outputTokenDetails?.textTokens,
+    totalOutput: typeof output === "number" ? output : flatCount(usage.completionTokens)
+  };
+};
+var normalizeUsage = (usage, modelName) => poolsFromParts(toParts(usage), modelName);
+
+// src/ai-sdk/index.ts
+var withAutumn = ({
+  model,
+  providerId,
+  ...tracking
+}) => {
+  const modelName = `${providerId ?? model.provider}/${model.modelId}`;
+  const track = createTracker(tracking);
+  const trackUsage = (usage) => track(() => ({
+    pools: normalizeUsage(usage, modelName),
+    modelId: modelName
+  }));
+  const middleware = {
+    specificationVersion: "v3",
+    wrapGenerate: async ({ doGenerate }) => {
+      const result = await doGenerate();
+      await trackUsage(result.usage);
+      return result;
+    },
+    wrapStream: async ({ doStream }) => {
+      const { stream, ...rest } = await doStream();
+      let trackingPromise;
+      const transformStream = new TransformStream({
+        transform(chunk, controller) {
+          if (chunk.type === "finish" && chunk.usage) {
+            trackingPromise = trackUsage(chunk.usage);
+          }
+          controller.enqueue(chunk);
+        },
+        async flush() {
+          await trackingPromise;
+        }
+      });
+      return {
+        stream: stream.pipeThrough(transformStream),
+        ...rest
+      };
+    }
+  };
+  return (0, import_ai.wrapLanguageModel)({ model, middleware });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  withAutumn
+});

package/dist/ai-sdk/index.d.cts

@@ -0,0 +1,43 @@
+import { LanguageModelV3 } from '@ai-sdk/provider';
+import { A as AutumnTrackingOptions } from '../track-C73uYSG_.cjs';
+export { a as AutumnClient, T as TokenPools } from '../track-C73uYSG_.cjs';
+
+type NestedTokens = {
+    total?: number | null;
+    noCache?: number | null;
+    cacheRead?: number | null;
+    cacheWrite?: number | null;
+    text?: number | null;
+    reasoning?: number | null;
+};
+type LegacyCount = number | {
+    total?: number | null;
+} | null;
+/** Lenient view over AI SDK usage shapes: nested V3 counts, flat counts with token details, and legacy prompt/completion counts. */
+type UsageLike = {
+    inputTokens?: number | NestedTokens | null;
+    outputTokens?: number | NestedTokens | null;
+    promptTokens?: LegacyCount;
+    completionTokens?: LegacyCount;
+    inputTokenDetails?: {
+        noCacheTokens?: number | null;
+        cacheReadTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    outputTokenDetails?: {
+        textTokens?: number | null;
+        reasoningTokens?: number | null;
+    } | null;
+    cachedInputTokens?: number | null;
+    reasoningTokens?: number | null;
+};
+
+type WithAutumnOptions = AutumnTrackingOptions & {
+    /** The AI SDK language model to wrap. */
+    model: LanguageModelV3;
+    /** Override the provider prefix used in the model name (e.g. "openrouter", "custom"). Falls back to `model.provider`. */
+    providerId?: string;
+};
+declare const withAutumn: ({ model, providerId, ...tracking }: WithAutumnOptions) => LanguageModelV3;
+
+export { AutumnTrackingOptions, type UsageLike, type WithAutumnOptions, withAutumn };

package/dist/ai-sdk/index.d.ts

@@ -0,0 +1,43 @@
+import { LanguageModelV3 } from '@ai-sdk/provider';
+import { A as AutumnTrackingOptions } from '../track-C73uYSG_.js';
+export { a as AutumnClient, T as TokenPools } from '../track-C73uYSG_.js';
+
+type NestedTokens = {
+    total?: number | null;
+    noCache?: number | null;
+    cacheRead?: number | null;
+    cacheWrite?: number | null;
+    text?: number | null;
+    reasoning?: number | null;
+};
+type LegacyCount = number | {
+    total?: number | null;
+} | null;
+/** Lenient view over AI SDK usage shapes: nested V3 counts, flat counts with token details, and legacy prompt/completion counts. */
+type UsageLike = {
+    inputTokens?: number | NestedTokens | null;
+    outputTokens?: number | NestedTokens | null;
+    promptTokens?: LegacyCount;
+    completionTokens?: LegacyCount;
+    inputTokenDetails?: {
+        noCacheTokens?: number | null;
+        cacheReadTokens?: number | null;
+        cacheWriteTokens?: number | null;
+    } | null;
+    outputTokenDetails?: {
+        textTokens?: number | null;
+        reasoningTokens?: number | null;
+    } | null;
+    cachedInputTokens?: number | null;
+    reasoningTokens?: number | null;
+};
+
+type WithAutumnOptions = AutumnTrackingOptions & {
+    /** The AI SDK language model to wrap. */
+    model: LanguageModelV3;
+    /** Override the provider prefix used in the model name (e.g. "openrouter", "custom"). Falls back to `model.provider`. */
+    providerId?: string;
+};
+declare const withAutumn: ({ model, providerId, ...tracking }: WithAutumnOptions) => LanguageModelV3;
+
+export { AutumnTrackingOptions, type UsageLike, type WithAutumnOptions, withAutumn };

package/dist/ai-sdk/index.js

@@ -0,0 +1,189 @@
+// src/ai-sdk/index.ts
+import { wrapLanguageModel } from "ai";
+
+// src/shared/track.ts
+var WIRE_KEYS = {
+  customerId: "customer_id",
+  entityId: "entity_id",
+  featureId: "feature_id",
+  modelId: "model_id",
+  inputTokens: "input_tokens",
+  outputTokens: "output_tokens",
+  cacheReadTokens: "cache_read_tokens",
+  cacheWriteTokens: "cache_write_tokens",
+  audioInputTokens: "audio_input_tokens",
+  audioOutputTokens: "audio_output_tokens",
+  reasoningTokens: "reasoning_tokens"
+};
+var toWire = (params) => Object.fromEntries(
+  Object.entries(params).filter(([, value]) => value !== void 0).map(([key, value]) => [WIRE_KEYS[key] ?? key, value])
+);
+var envClient = () => {
+  const env = typeof process === "undefined" ? void 0 : process.env;
+  const secretKey = env?.AUTUMN_API_KEY ?? env?.AUTUMN_SECRET_KEY;
+  const baseUrl = env?.AUTUMN_BASE_URL ?? "https://api.useautumn.com";
+  return {
+    trackTokens: async (params) => {
+      if (!secretKey) {
+        throw new Error(
+          "[Autumn] No autumn client was passed and AUTUMN_API_KEY is not set."
+        );
+      }
+      const response = await fetch(`${baseUrl}/v1/balances.track_tokens`, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${secretKey}`,
+          "content-type": "application/json"
+        },
+        body: JSON.stringify(toWire(params))
+      });
+      if (!response.ok) {
+        throw new Error(
+          `track_tokens failed (${response.status}): ${await response.text()}`
+        );
+      }
+      return response.json();
+    }
+  };
+};
+var createTracker = ({
+  autumn = envClient(),
+  customerId,
+  featureId,
+  entityId,
+  properties
+}) => (getEvent) => trackTokenUsage({
+  autumn,
+  getParams: () => {
+    const event = getEvent();
+    return {
+      ...event.pools,
+      customerId,
+      modelId: event.modelId,
+      featureId,
+      entityId,
+      properties: event.properties ?? properties
+    };
+  }
+});
+var trackTokenUsage = async ({
+  autumn,
+  getParams
+}) => {
+  try {
+    const balances = autumn.balances;
+    const trackTokens = balances?.trackTokens?.bind(balances) ?? autumn.trackTokens?.bind(autumn);
+    if (!trackTokens) {
+      throw new Error(
+        "Autumn client does not support trackTokens \u2014 upgrade @useautumn/sdk."
+      );
+    }
+    await trackTokens(getParams());
+  } catch (error) {
+    console.error("[Autumn Tracking] Failed to track usage:", error);
+  }
+};
+
+// src/shared/usage.ts
+var clamp = (value) => Math.max(0, value);
+var requiredCount = (value, label, modelName) => {
+  if (value == null) {
+    throw new Error(
+      `[Autumn] ${label} token usage was not returned by the model provider (${modelName}). This provider may not support usage tracking.`
+    );
+  }
+  return value;
+};
+var poolsFromParts = (parts, modelName) => {
+  const cacheRead = parts.cacheRead ?? 0;
+  const cacheWrite = parts.cacheWrite ?? 0;
+  const reasoning = parts.reasoning ?? 0;
+  const audioInput = parts.audioInput ?? 0;
+  const textInput = parts.textInput ?? (parts.totalInput != null ? parts.totalInput - cacheRead - cacheWrite - audioInput : void 0);
+  const textOutput = parts.textOutput ?? (parts.totalOutput != null ? parts.totalOutput - reasoning : void 0);
+  return {
+    inputTokens: clamp(requiredCount(textInput, "Input", modelName)),
+    outputTokens: clamp(requiredCount(textOutput, "Output", modelName)),
+    cacheReadTokens: clamp(cacheRead),
+    cacheWriteTokens: clamp(cacheWrite),
+    reasoningTokens: clamp(reasoning),
+    ...parts.audioInput !== void 0 && {
+      audioInputTokens: clamp(audioInput)
+    }
+  };
+};
+
+// src/ai-sdk/usage.ts
+var flatCount = (value) => typeof value === "number" ? value : value?.total ?? void 0;
+var isNested = (value) => value != null && typeof value === "object";
+var toParts = (usage) => {
+  const input = usage.inputTokens;
+  const output = usage.outputTokens;
+  if (isNested(input)) {
+    const out = isNested(output) ? output : void 0;
+    return {
+      cacheRead: input.cacheRead ?? 0,
+      cacheWrite: input.cacheWrite ?? 0,
+      reasoning: out?.reasoning ?? 0,
+      textInput: input.noCache,
+      totalInput: input.total,
+      textOutput: out?.text,
+      totalOutput: out?.total
+    };
+  }
+  return {
+    cacheRead: usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens ?? 0,
+    cacheWrite: usage.inputTokenDetails?.cacheWriteTokens ?? 0,
+    reasoning: usage.outputTokenDetails?.reasoningTokens ?? usage.reasoningTokens ?? 0,
+    textInput: usage.inputTokenDetails?.noCacheTokens,
+    totalInput: typeof input === "number" ? input : flatCount(usage.promptTokens),
+    textOutput: usage.outputTokenDetails?.textTokens,
+    totalOutput: typeof output === "number" ? output : flatCount(usage.completionTokens)
+  };
+};
+var normalizeUsage = (usage, modelName) => poolsFromParts(toParts(usage), modelName);
+
+// src/ai-sdk/index.ts
+var withAutumn = ({
+  model,
+  providerId,
+  ...tracking
+}) => {
+  const modelName = `${providerId ?? model.provider}/${model.modelId}`;
+  const track = createTracker(tracking);
+  const trackUsage = (usage) => track(() => ({
+    pools: normalizeUsage(usage, modelName),
+    modelId: modelName
+  }));
+  const middleware = {
+    specificationVersion: "v3",
+    wrapGenerate: async ({ doGenerate }) => {
+      const result = await doGenerate();
+      await trackUsage(result.usage);
+      return result;
+    },
+    wrapStream: async ({ doStream }) => {
+      const { stream, ...rest } = await doStream();
+      let trackingPromise;
+      const transformStream = new TransformStream({
+        transform(chunk, controller) {
+          if (chunk.type === "finish" && chunk.usage) {
+            trackingPromise = trackUsage(chunk.usage);
+          }
+          controller.enqueue(chunk);
+        },
+        async flush() {
+          await trackingPromise;
+        }
+      });
+      return {
+        stream: stream.pipeThrough(transformStream),
+        ...rest
+      };
+    }
+  };
+  return wrapLanguageModel({ model, middleware });
+};
+export {
+  withAutumn
+};