@tollgateai/sdk 0.3.0 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Real-time gross-margin observability for AI agents. Track every LLM call's cost, attribute it to a customer, and see whether you're making money — before the invoice goes out.
 
-**v0.3.0** · [npm](https://www.npmjs.com/package/@tollgateai/sdk) · [Dashboard](https://tollgateai.vercel.app)
+**v0.4.0** · [npm](https://www.npmjs.com/package/@tollgateai/sdk) · [Dashboard](https://tollgateai.vercel.app)
 
 ---
 
@@ -189,6 +189,7 @@ Every auto-instrumented call captures the following from the provider response:
 | `cacheWrite5mTokens` | `cache_creation_input_tokens` | 5-min TTL cache write tokens |
 | `cacheWrite1hTokens` | `cache_creation.ephemeral_1h_input_tokens` | 1-hour TTL cache write tokens |
 | `toolCalls` | Content block / choice inspection | Number of tool calls in the response |
+| `externalCostCents` | User-provided | Cost of external tools/services (image gen, sandbox, search) |
 | `provider` | Wrapper default or override | `anthropic`, `openai`, `openai_compatible`, `bedrock` |
 | `model` | Response object | Model identifier as reported by the provider |
 
@@ -224,6 +225,40 @@ For simple per-call billing, pass `revenueUnitCents` in the wrap options and ski
 
 ---
 
+## External Tool Costs
+
+AI agents often call external services — image generation, code sandboxes, search APIs, vector databases — that cost real money outside of LLM token pricing. Report these costs alongside the LLM call so Tollgate includes them in the margin calculation.
+
+```ts
+// Agent generates an image during the run
+const image = await dalle.generate({ prompt: '...' }); // costs $0.04
+
+await tollgate.track({
+  customerId: 'cust_acme',
+  runId: 'ticket_8842',
+  provider: 'openai',
+  model: 'gpt-4o',
+  tokensIn: 500,
+  tokensOut: 200,
+  toolCalls: 1,                // LLM tool_use count (auto-extracted by wrappers)
+  externalCostCents: 4.0,     // $0.04 for the DALL-E call
+  idempotencyKey: 'ticket_8842#step_2',
+});
+```
+
+Common examples:
+
+| Service | Typical Cost | How to report |
+|---|---|---|
+| DALL-E image generation | ~$0.04/image | `externalCostCents: 4` |
+| E2B code sandbox | ~$0.01/run | `externalCostCents: 1` |
+| Tavily search API | ~$0.01/search | `externalCostCents: 1` |
+| Pinecone vector query | ~$0.001/query | `externalCostCents: 0.1` |
+
+External costs flow into the **Tools** bucket in the Customer Drawer's cost-split chart — so you can see exactly what share of each customer's cost comes from external services vs. LLM tokens.
+
+---
+
 ## Customer & Plan Setup
 
 Create customers and assign plans **before** sending usage so plan-priced revenue is recognized from the first event. Idempotent — safe to run on every boot.

package/dist/index.d.cts

@@ -28,6 +28,11 @@ interface TrackEventInput {
     cacheWrite1hTokens?: number;
     toolCalls?: number;
     toolName?: string;
+    /** Cost in cents of external tools/services used in this event (image
+     *  generation, code sandbox, search APIs, vector DB lookups, etc.).
+     *  Added directly to the cost breakdown — no rate-card lookup needed.
+     *  Fractional cents accepted (e.g. 1.5 for $0.015). */
+    externalCostCents?: number;
     /** Terminal run outcome, set on the run's closing event only (omit on
      *  intermediate steps). Gates outcome-priced revenue. See `resolve()`. */
     outcome?: RunOutcome;

package/dist/index.d.ts

@@ -28,6 +28,11 @@ interface TrackEventInput {
     cacheWrite1hTokens?: number;
     toolCalls?: number;
     toolName?: string;
+    /** Cost in cents of external tools/services used in this event (image
+     *  generation, code sandbox, search APIs, vector DB lookups, etc.).
+     *  Added directly to the cost breakdown — no rate-card lookup needed.
+     *  Fractional cents accepted (e.g. 1.5 for $0.015). */
+    externalCostCents?: number;
     /** Terminal run outcome, set on the run's closing event only (omit on
      *  intermediate steps). Gates outcome-priced revenue. See `resolve()`. */
     outcome?: RunOutcome;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tollgateai/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Track real LLM model usage and compute live gross margin with Tollgate.",
   "license": "UNLICENSED",
   "type": "module",