@dexcost/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dexwox Innovations and contributors
+
+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,210 @@
+# @dexcost/sdk
+
+**Agent Unit Economics SDK for Node.js** — track LLM costs, non-LLM service fees, and retry waste attributed to customers, projects, and workflows.
+
+## Install
+
+```bash
+npm install @dexcost/sdk
+```
+
+With LLM provider SDKs (peer dependencies):
+
+```bash
+npm install @dexcost/sdk openai @anthropic-ai/sdk
+```
+
+## Quick Start
+
+```typescript
+import { init, track, close } from '@dexcost/sdk';
+
+init({ apiKey: 'dx_live_...' });  // or set DEXCOST_API_KEY env var
+
+await track({ taskType: 'summarise', customerId: 'acme' }, async (task) => {
+  // LLM calls are auto-captured — just use OpenAI/Anthropic normally
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Summarise this document' }],
+  });
+
+  // Record non-LLM costs manually
+  task.recordCost('pdf_parser', 0.002);
+});
+
+await close();
+```
+
+## Auto-Instrumentation
+
+dexcost auto-instruments **6 LLM providers** and the **global fetch API**.
+
+### LLM Providers
+
+| Provider | Package | Auto-Patched |
+|----------|---------|-------------|
+| OpenAI | `openai` | `chat.completions.create` |
+| Anthropic | `@anthropic-ai/sdk` | `messages.create` |
+| Vercel AI | `ai` | Vercel AI SDK functions |
+| Google Gemini | `@google/generative-ai` | `generateContent` |
+| AWS Bedrock | `@aws-sdk/client-bedrock-runtime` | `invokeModel` |
+| Cohere | `cohere-ai` | `chat` / `generate` |
+
+LLM provider packages are **peer dependencies** — install only the ones you use. dexcost detects them at runtime and patches automatically.
+
+### HTTP (Non-LLM Cost Capture)
+
+dexcost patches `globalThis.fetch` to capture HTTP calls to domains in the [163-service catalog](src/data/service_prices.json) — Pinecone, Twilio, SendGrid, Stripe, Firecrawl, Exa, and more. Costs are extracted from response headers/body and recorded as `external_cost` events.
+
+### Controlling Instrumentation
+
+```typescript
+// Instrument only specific providers
+init({ autoInstrument: ['openai', 'anthropic'] });
+
+// Disable all auto-instrumentation
+init({ autoInstrument: [] });
+```
+
+## Configuration
+
+### `init()` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | `DEXCOST_API_KEY` env | API key for cloud push |
+| `autoInstrument` | `string[]` | All 6 providers | Which LLM SDKs to patch |
+| `batchSize` | `number` | `100` | Events per sync batch |
+| `flushIntervalMs` | `number` | `30000` | Milliseconds between sync pushes |
+| `redactFields` | `string[]` | `undefined` | Field names to redact from event details |
+| `hashCustomerId` | `boolean` | `false` | SHA-256 hash customer_id before storage |
+| `environment` | `string` | `undefined` | Set to `"development"` for dev console mode |
+| `dbPath` | `string` | `~/.dexcost/buffer.db` | Path to local SQLite buffer |
+| `enableRetryHeuristics` | `boolean` | `false` | Auto-detect retries via pattern matching |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `DEXCOST_API_KEY` | API key (if not passed to `init()`) |
+| `DEXCOST_ENDPOINT` | Control Layer URL (default: `https://api.dexcost.io`) |
+| `DEXCOST_ENV` | Set to `development` for dev console output |
+
+## API
+
+### Singleton Pattern
+
+dexcost uses a singleton. Call `init()` once at app startup:
+
+```typescript
+import { init, getTracker, track, flush, close } from '@dexcost/sdk';
+
+init({ apiKey: 'dx_live_...' });
+
+// Use the global track() anywhere
+await track({ taskType: 'chat', customerId: 'acme' }, async (task) => {
+  task.recordLlmCall('openai', 'gpt-4o', 800, 150);
+});
+
+// Or get the tracker instance
+const tracker = getTracker();
+```
+
+### TrackedTask Methods
+
+```typescript
+await track({ taskType: '...' }, async (task) => {
+  // Record LLM call manually (usually auto-captured)
+  task.recordLlmCall('openai', 'gpt-4o', 800, 150);
+
+  // Record non-LLM cost
+  task.recordCost('pinecone', 0.001);
+
+  // Record usage (cost computed from registered rates)
+  task.recordUsage('s3_storage', 1024);
+
+  // Mark a retry
+  task.markRetry('rate_limit', 0.005);
+
+  // Link to external trace
+  task.linkTrace('datadog', 'trace-abc123');
+
+  // End with status (auto-detected from exceptions)
+  task.end('success');
+});
+```
+
+### Customer Attribution
+
+```typescript
+import { setContext, track } from '@dexcost/sdk';
+
+setContext({ customerId: 'acme-corp', projectId: 'proj-alpha' });
+
+// All tasks inherit the context
+await track({ taskType: 'resolve_ticket' }, async (task) => {
+  // task.task.customerId === 'acme-corp'
+});
+```
+
+### Context Propagation
+
+dexcost uses `AsyncLocalStorage` — task context propagates across `await`, `Promise.all`, `setTimeout`, and any async operation without manual threading.
+
+```typescript
+import { getCurrentTask } from '@dexcost/sdk';
+
+// Inside any async function within a tracked task:
+const task = getCurrentTask();  // Returns the active Task or undefined
+```
+
+### Nested Tasks
+
+```typescript
+await track({ taskType: 'pipeline' }, async (parent) => {
+  await track({ taskType: 'step_1' }, async (child) => {
+    // child.task.parentTaskId === parent.task.taskId (auto-linked)
+  });
+});
+```
+
+## Dev Mode
+
+Set `DEXCOST_ENV=development` or pass `environment: "development"` to `init()`. In dev mode:
+- Cost events are printed to the console
+- No data is pushed to the cloud
+
+## Express Middleware
+
+```typescript
+import { createExpressMiddleware } from '@dexcost/sdk';
+
+app.use(createExpressMiddleware({
+  taskType: 'api_request',
+  extractCustomerId: (req) => req.headers['x-customer-id'],
+}));
+```
+
+## Runtime Dependencies
+
+- `better-sqlite3` — local event buffer
+- `ajv` — JSON Schema validation
+- `js-yaml` — rate file parsing
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm run lint
+```
+
+## Privacy
+
+When you connect to the Dexcost Control Layer, the SDK transmits usage data
+subject to our [Privacy Policy](https://dexcost.io/privacy).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/adapters/_netbytes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Helpers for the HTTP network adapter: destination classification and
+ * byte measurement. Pure functions — no SDK state, no I/O beyond parsing.
+ *
+ * Mirrors python/src/dexcost/adapters/_netbytes.py.
+ */
+/**
+ * Return whether *host* is internal traffic.
+ *
+ * - `true`  — host is an RFC1918 / loopback / link-local IPv4 literal, an
+ *             IPv6 ULA (`fc00::/7`), IPv6 link-local (`fe80::/10`), or
+ *             IPv6 loopback (`::1`).
+ * - `false` — host parses as an IP literal but is not in the above ranges.
+ * - `null`  — host is a name (not an IP literal); the SDK does not perform
+ *             an extra DNS lookup to resolve it.
+ *
+ * Note: CGNAT shared address space (100.64.0.0/10, RFC 6598) is classified
+ * `false` — Python's `ipaddress.is_private` does not include it, and we
+ * mirror that behaviour for cross-SDK parity.
+ */
+export declare function classifyDestination(host: string): boolean | null;
+/**
+ * Approximate the on-the-wire byte size of one HTTP message.
+ *
+ * `request line + header block + body`. Used for both directions: pass the
+ * request method/url/headers for bytes-out, or `"" / "" / response headers`
+ * for bytes-in. `bodyLen` is the known body length in bytes; negative values
+ * are clamped to zero.
+ */
+export declare function measureBytesFromHeaders(method: string, url: string, headers: Record<string, string>, bodyLen: number): number;
+//# sourceMappingURL=_netbytes.d.ts.map

package/dist/adapters/_netbytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_netbytes.d.ts","sourceRoot":"","sources":["../../src/adapters/_netbytes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAyEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA+BhE;AAeD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,EAAE,MAAM,GACd,MAAM,CAKR"}

package/dist/adapters/_netbytes.js

@@ -0,0 +1,154 @@
+/**
+ * Helpers for the HTTP network adapter: destination classification and
+ * byte measurement. Pure functions — no SDK state, no I/O beyond parsing.
+ *
+ * Mirrors python/src/dexcost/adapters/_netbytes.py.
+ */
+// ---------------------------------------------------------------------------
+// IP literal parsing (open-coded, no `ipaddr.js` dependency — recommended in
+// the network-capture plan to avoid adding a dep just for classification).
+// ---------------------------------------------------------------------------
+const IPV4_RE = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/;
+function parseIPv4(host) {
+    const m = IPV4_RE.exec(host);
+    if (!m)
+        return null;
+    const octets = [];
+    for (let i = 1; i <= 4; i++) {
+        const n = Number(m[i]);
+        if (!Number.isInteger(n) || n < 0 || n > 255)
+            return null;
+        // Reject leading zeros beyond a single "0" (e.g. "010" is ambiguous on the
+        // wire). ipaddress.ip_address in Python is similarly strict in 3.10+.
+        if (m[i].length > 1 && m[i].startsWith("0"))
+            return null;
+        octets.push(n);
+    }
+    return octets;
+}
+/**
+ * Loose-grammar IPv6 detector: covers the common literal shapes including
+ * `::`-compressed forms. We do not need full numeric reconstruction because
+ * the classifier only inspects the textual prefix (`fc00::/7`, `fe80::/10`,
+ * `::1`).
+ */
+function isIPv6Literal(host) {
+    if (host.length === 0)
+        return false;
+    // Strip optional zone-id (`fe80::1%eth0`) before validation.
+    const bare = host.split("%", 1)[0];
+    if (bare.indexOf(":") === -1)
+        return false;
+    // Disallow obvious non-hex characters.
+    if (!/^[0-9a-fA-F:.]+$/.test(bare))
+        return false;
+    // At most one "::".
+    const dblIdx = bare.indexOf("::");
+    if (dblIdx !== -1 && bare.indexOf("::", dblIdx + 1) !== -1)
+        return false;
+    // Split and sanity-check each group.
+    const parts = bare.split(":");
+    if (parts.length < 3 || parts.length > 8)
+        return false;
+    for (const p of parts) {
+        if (p.length === 0)
+            continue; // produced by "::"
+        if (p.length > 4) {
+            // Could be an embedded IPv4 ("::ffff:1.2.3.4") — accept if last segment.
+            if (p === parts[parts.length - 1] && parseIPv4(p) !== null)
+                continue;
+            return false;
+        }
+    }
+    return true;
+}
+function isPrivateIPv4(octets) {
+    const [a, b] = octets;
+    // 10.0.0.0/8
+    if (a === 10)
+        return true;
+    // 172.16.0.0/12
+    if (a === 172 && b >= 16 && b <= 31)
+        return true;
+    // 192.168.0.0/16
+    if (a === 192 && b === 168)
+        return true;
+    return false;
+}
+function isLoopbackIPv4(octets) {
+    return octets[0] === 127;
+}
+function isLinkLocalIPv4(octets) {
+    return octets[0] === 169 && octets[1] === 254;
+}
+/**
+ * Return whether *host* is internal traffic.
+ *
+ * - `true`  — host is an RFC1918 / loopback / link-local IPv4 literal, an
+ *             IPv6 ULA (`fc00::/7`), IPv6 link-local (`fe80::/10`), or
+ *             IPv6 loopback (`::1`).
+ * - `false` — host parses as an IP literal but is not in the above ranges.
+ * - `null`  — host is a name (not an IP literal); the SDK does not perform
+ *             an extra DNS lookup to resolve it.
+ *
+ * Note: CGNAT shared address space (100.64.0.0/10, RFC 6598) is classified
+ * `false` — Python's `ipaddress.is_private` does not include it, and we
+ * mirror that behaviour for cross-SDK parity.
+ */
+export function classifyDestination(host) {
+    if (!host)
+        return null;
+    const v4 = parseIPv4(host);
+    if (v4 !== null) {
+        return (isPrivateIPv4(v4) || isLoopbackIPv4(v4) || isLinkLocalIPv4(v4));
+    }
+    if (isIPv6Literal(host)) {
+        const lower = host.toLowerCase().split("%", 1)[0];
+        // ::1 loopback (also covers "0:0:0:0:0:0:0:1").
+        if (lower === "::1")
+            return true;
+        if (/^0:0:0:0:0:0:0:0*1$/.test(lower))
+            return true;
+        // fc00::/7 — ULA. First byte is 0xfc or 0xfd; in text form that means
+        // the address starts with "fc" or "fd" followed by a hex digit (or "::").
+        if (/^f[cd][0-9a-f]{0,2}:/.test(lower) || /^f[cd]:/.test(lower)) {
+            return true;
+        }
+        // fe80::/10 — link-local. First 10 bits are 1111111010, so the leading
+        // 16 bits are between 0xfe80 and 0xfebf.
+        const firstGroup = lower.split(":")[0];
+        if (firstGroup.length > 0 && firstGroup.length <= 4) {
+            const v = parseInt(firstGroup, 16);
+            if (!Number.isNaN(v) && v >= 0xfe80 && v <= 0xfebf)
+                return true;
+        }
+        return false;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Byte-size measurement
+// ---------------------------------------------------------------------------
+function _headersByteLen(headers) {
+    let total = 0;
+    for (const [key, value] of Object.entries(headers)) {
+        // ": " + CRLF == 4 extra bytes per header line.
+        total += String(key).length + String(value).length + 4;
+    }
+    return total + 2; // trailing CRLF that ends the header block
+}
+/**
+ * Approximate the on-the-wire byte size of one HTTP message.
+ *
+ * `request line + header block + body`. Used for both directions: pass the
+ * request method/url/headers for bytes-out, or `"" / "" / response headers`
+ * for bytes-in. `bodyLen` is the known body length in bytes; negative values
+ * are clamped to zero.
+ */
+export function measureBytesFromHeaders(method, url, headers, bodyLen) {
+    // method + url + " HTTP/1.1\r\n" → +12 trailing bytes
+    const requestLine = String(method).length + String(url).length + 12;
+    const body = Math.max(0, Math.trunc(Number(bodyLen) || 0));
+    return requestLine + _headersByteLen(headers) + body;
+}
+//# sourceMappingURL=_netbytes.js.map

package/dist/adapters/_netbytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_netbytes.js","sourceRoot":"","sources":["../../src/adapters/_netbytes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAE9E,MAAM,OAAO,GAAG,8CAA8C,CAAC;AAE/D,SAAS,SAAS,CAAC,IAAY;IAC7B,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7B,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG;YAAE,OAAO,IAAI,CAAC;QAC1D,2EAA2E;QAC3E,sEAAsE;QACtE,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAE,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAC3D,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjB,CAAC;IACD,OAAO,MAA0C,CAAC;AACpD,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACpC,6DAA6D;IAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;IACpC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,uCAAuC;IACvC,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,oBAAoB;IACpB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,MAAM,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACzE,qCAAqC;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACvD,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS,CAAC,mBAAmB;QACjD,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACjB,yEAAyE;YACzE,IAAI,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI;gBAAE,SAAS;YACrE,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,MAAwC;IAC7D,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC;IACtB,aAAa;IACb,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC1B,gBAAgB;IAChB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO,IAAI,CAAC;IACjD,iBAAiB;IACjB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,cAAc,CAAC,MAAwC;IAC9D,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;AAC3B,CAAC;AAED,SAAS,eAAe,CAAC,MAAwC;IAC/D,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,MAAM,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,OAAO,CACL,aAAa,CAAC,EAAE,CAAC,IAAI,cAAc,CAAC,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,CAAC,CAC/D,CAAC;IACJ,CAAC;IAED,IAAI,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;QACnD,gDAAgD;QAChD,IAAI,KAAK,KAAK,KAAK;YAAE,OAAO,IAAI,CAAC;QACjC,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QACnD,sEAAsE;QACtE,0EAA0E;QAC1E,IAAI,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChE,OAAO,IAAI,CAAC;QACd,CAAC;QACD,uEAAuE;QACvE,yCAAyC;QACzC,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;QACxC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACpD,MAAM,CAAC,GAAG,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YACnC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,MAAM;gBAAE,OAAO,IAAI,CAAC;QAClE,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E,SAAS,eAAe,CAAC,OAA+B;IACtD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,gDAAgD;QAChD,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,GAAG,CAAC,CAAC,CAAC,2CAA2C;AAC/D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,GAAW,EACX,OAA+B,EAC/B,OAAe;IAEf,sDAAsD;IACtD,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,EAAE,CAAC;IACpE,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;AACvD,CAAC"}

package/dist/adapters/aws-lambda.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AWS Lambda cost adapter — compute cost from duration, memory, and region.
+ *
+ * `lambdaCost` is a pure function that returns the cost (in USD) and a
+ * breakdown for a single Lambda invocation, using bundled pricing data
+ * (no network I/O). Mirrors the Python SDK's `adapters/aws_lambda.py`.
+ */
+/** Breakdown of a Lambda invocation's cost. */
+export interface LambdaCostDetails {
+    region: string;
+    durationMs: number;
+    memoryMb: number;
+    gbSeconds: number;
+    durationCostUsd: number;
+    requestCostUsd: number;
+    ratePerGbSecond: number;
+}
+/** Result of {@link lambdaCost}. */
+export interface LambdaCostResult {
+    /** Total invocation cost in USD. */
+    costUsd: number;
+    /** Cost breakdown. */
+    details: LambdaCostDetails;
+}
+/**
+ * Return a sorted list of AWS region codes with bundled pricing data.
+ */
+export declare function getSupportedRegions(): string[];
+/**
+ * Calculate the cost of a single AWS Lambda invocation.
+ *
+ * Pure function — no I/O, no side effects. Uses the bundled
+ * `aws_lambda_pricing.json` for rates.
+ *
+ * @param durationMs - Execution duration in milliseconds (>= 0).
+ * @param memoryMb - Allocated memory in MB (> 0).
+ * @param region - AWS region code (e.g. `"us-east-1"`).
+ * @throws Error when `region` is unknown, `durationMs` < 0, or `memoryMb` <= 0.
+ */
+export declare function lambdaCost(durationMs: number, memoryMb: number, region: string): LambdaCostResult;
+//# sourceMappingURL=aws-lambda.d.ts.map

package/dist/adapters/aws-lambda.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-lambda.d.ts","sourceRoot":"","sources":["../../src/adapters/aws-lambda.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuBH,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,oCAAoC;AACpC,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,OAAO,EAAE,iBAAiB,CAAC;CAC5B;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,GACb,gBAAgB,CAuClB"}

package/dist/adapters/aws-lambda.js

@@ -0,0 +1,65 @@
+/**
+ * AWS Lambda cost adapter — compute cost from duration, memory, and region.
+ *
+ * `lambdaCost` is a pure function that returns the cost (in USD) and a
+ * breakdown for a single Lambda invocation, using bundled pricing data
+ * (no network I/O). Mirrors the Python SDK's `adapters/aws_lambda.py`.
+ */
+// Sprint 3 Theme E / §4.2.3 — Node 18 compat: runtime JSON load.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const _thisDir = dirname(fileURLToPath(import.meta.url));
+const pricingData = JSON.parse(readFileSync(join(_thisDir, "data", "aws_lambda_pricing.json"), "utf-8"));
+const _pricing = pricingData;
+/**
+ * Return a sorted list of AWS region codes with bundled pricing data.
+ */
+export function getSupportedRegions() {
+    return Object.keys(_pricing.regions).sort();
+}
+/**
+ * Calculate the cost of a single AWS Lambda invocation.
+ *
+ * Pure function — no I/O, no side effects. Uses the bundled
+ * `aws_lambda_pricing.json` for rates.
+ *
+ * @param durationMs - Execution duration in milliseconds (>= 0).
+ * @param memoryMb - Allocated memory in MB (> 0).
+ * @param region - AWS region code (e.g. `"us-east-1"`).
+ * @throws Error when `region` is unknown, `durationMs` < 0, or `memoryMb` <= 0.
+ */
+export function lambdaCost(durationMs, memoryMb, region) {
+    if (durationMs < 0) {
+        throw new Error(`durationMs must be >= 0, got ${durationMs}`);
+    }
+    if (memoryMb <= 0) {
+        throw new Error(`memoryMb must be > 0, got ${memoryMb}`);
+    }
+    const regionPricing = _pricing.regions[region];
+    if (regionPricing === undefined) {
+        const supported = getSupportedRegions().join(", ");
+        throw new Error(`Unknown AWS region '${region}'. Supported regions: ${supported}`);
+    }
+    // GB-seconds = duration (s) * memory (GB)
+    const durationSeconds = durationMs / 1000;
+    const memoryGb = memoryMb / 1024;
+    const gbSeconds = durationSeconds * memoryGb;
+    const ratePerGbSecond = Number(regionPricing.duration_per_gb_second);
+    const requestCharge = Number(regionPricing.request_per_invocation);
+    const durationCost = gbSeconds * ratePerGbSecond;
+    const totalCost = durationCost + requestCharge;
+    return {
+        costUsd: totalCost,
+        details: {
+            region,
+            durationMs,
+            memoryMb,
+            gbSeconds,
+            durationCostUsd: durationCost,
+            requestCostUsd: requestCharge,
+            ratePerGbSecond,
+        },
+    };
+}
+//# sourceMappingURL=aws-lambda.js.map

package/dist/adapters/aws-lambda.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aws-lambda.js","sourceRoot":"","sources":["../../src/adapters/aws-lambda.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,iEAAiE;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACzD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAC5B,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,yBAAyB,CAAC,EAAE,OAAO,CAAC,CACzE,CAAC;AAWF,MAAM,QAAQ,GAAG,WAA2C,CAAC;AAqB7D;;GAEG;AACH,MAAM,UAAU,mBAAmB;IACjC,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,UAAkB,EAClB,QAAgB,EAChB,MAAc;IAEd,IAAI,UAAU,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,gCAAgC,UAAU,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CAAC,6BAA6B,QAAQ,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,SAAS,GAAG,mBAAmB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnD,MAAM,IAAI,KAAK,CACb,uBAAuB,MAAM,yBAAyB,SAAS,EAAE,CAClE,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,MAAM,eAAe,GAAG,UAAU,GAAG,IAAI,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IACjC,MAAM,SAAS,GAAG,eAAe,GAAG,QAAQ,CAAC;IAE7C,MAAM,eAAe,GAAG,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;IACrE,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC,sBAAsB,CAAC,CAAC;IAEnE,MAAM,YAAY,GAAG,SAAS,GAAG,eAAe,CAAC;IACjD,MAAM,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC;IAE/C,OAAO;QACL,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE;YACP,MAAM;YACN,UAAU;YACV,QAAQ;YACR,SAAS;YACT,eAAe,EAAE,YAAY;YAC7B,cAAc,EAAE,aAAa;YAC7B,eAAe;SAChB;KACF,CAAC;AACJ,CAAC"}

package/dist/adapters/browser.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Browser cost adapter — automatic cost tracking for Playwright sessions.
+ *
+ * `trackBrowser` wraps a block of Playwright work, measures wall-clock
+ * time, and records a `compute_cost` event proportional to session
+ * duration. Mirrors the Python SDK's `adapters/browser.py`.
+ *
+ * `playwright` is an optional peer dependency — this adapter is duck-typed
+ * and never imports it, so it works with any object exposing a `.url`.
+ *
+ * Usage:
+ *
+ *   import { trackBrowser } from "dexcost";
+ *
+ *   await tracker.track({ taskType: "scrape" }, async () => {
+ *     await trackBrowser(page, async () => {
+ *       await page.goto("https://example.com");
+ *     }, { ratePerMinute: 0.01 });
+ *   });
+ */
+import { type CostEvent } from "../core/models.js";
+import type { EventBuffer } from "../transport/buffer.js";
+/**
+ * Wire the browser adapter to a storage buffer. The CostTracker calls this on
+ * construction so `trackBrowser()` cost events reach SQLite and the sync
+ * pusher. Pass `null` to detach (events then stay in-memory only).
+ */
+export declare function setBrowserBuffer(buffer: EventBuffer | null): void;
+/** Return all events recorded by the browser adapter since the last clear. */
+export declare function getBrowserEvents(): CostEvent[];
+/** Clear the browser adapter's recorded events list. */
+export declare function clearBrowserEvents(): void;
+/** Options for {@link trackBrowser}. */
+export interface TrackBrowserOptions {
+    /** Cost per minute of browser usage in USD. Defaults to `0.01`. */
+    ratePerMinute?: number;
+}
+/**
+ * Run `fn` while measuring browser session wall-clock time, then record a
+ * `compute_cost` event with `costUsd = elapsedMinutes * ratePerMinute`.
+ *
+ * The event is only recorded when there is an active task in the context
+ * (via `getCurrentTask()`). When no task is active, the timing wrapper is
+ * a silent pass-through. The cost is always recorded even if `fn` throws.
+ *
+ * @param page - A Playwright `Page` (or any object with a `.url`). Not
+ *   type-checked, to avoid requiring `playwright` as a hard dependency.
+ * @param fn - The browser work to run and time.
+ * @param options - Optional `ratePerMinute` override.
+ */
+export declare function trackBrowser<T>(page: any, fn: () => Promise<T>, options?: TrackBrowserOptions): Promise<T>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/adapters/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/adapters/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAwB1D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED,8EAA8E;AAC9E,wBAAgB,gBAAgB,IAAI,SAAS,EAAE,CAE9C;AAED,wDAAwD;AACxD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,GAAG,EACT,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,CAAC,CAAC,CASZ"}