@dexcost/sdk 0.2.0

package/dist/clients.js

@@ -0,0 +1,240 @@
+/**
+ * Thin wrapper classes around the OpenAI and Anthropic clients that
+ * auto-record LLM cost events.
+ *
+ * Alternative to auto-instrumentation (no monkey-patching). Matching
+ * the Python SDK's clients.py.
+ *
+ * Usage:
+ *
+ *   import { TrackedOpenAI } from "dexcost/clients";
+ *
+ *   const client = new TrackedOpenAI({ tracker });
+ *   // Inside a tracked task, events are auto-recorded:
+ *   const response = await client.chat.completions.create({ model: "gpt-4o", messages: [] });
+ */
+import { randomUUID } from "node:crypto";
+import { getCurrentTask } from "./core/context.js";
+import { createCostEvent } from "./core/models.js";
+import { createAutoTask } from "./core/auto-task.js";
+import { PricingEngine } from "./pricing/engine.js";
+// ---------------------------------------------------------------------------
+// TrackedOpenAI
+// ---------------------------------------------------------------------------
+/**
+ * Wraps `openai.OpenAI` and auto-records llm_call events on every
+ * `chat.completions.create` call when running inside a tracked task context.
+ */
+export class TrackedOpenAI {
+    _client;
+    _pricing;
+    _buffer;
+    constructor(opts) {
+        if (opts?.client !== undefined) {
+            this._client = opts.client;
+        }
+        else {
+            // Lazy require — openai is an optional peer dependency
+            let OpenAIClass;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const openaiModule = require("openai");
+                OpenAIClass = (openaiModule.default ?? openaiModule.OpenAI);
+            }
+            catch {
+                throw new Error("The 'openai' package is required for TrackedOpenAI. Install it with: npm install openai");
+            }
+            this._client = new OpenAIClass();
+        }
+        if (opts?.tracker !== undefined) {
+            this._pricing = opts.tracker.pricing;
+            this._buffer = opts.tracker.buffer;
+        }
+        else if (opts?.pricing !== undefined) {
+            this._pricing = opts.pricing;
+            this._buffer = null;
+        }
+        else {
+            this._pricing = new PricingEngine();
+            this._buffer = null;
+        }
+    }
+    get chat() {
+        const pricing = this._pricing;
+        const buffer = this._buffer;
+        const client = this._client;
+        return {
+            completions: {
+                create: async (...args) => {
+                    const response = await client.chat.completions.create(...args);
+                    recordOpenAIEvent(response, args[0], pricing, buffer);
+                    return response;
+                },
+            },
+        };
+    }
+}
+function recordOpenAIEvent(response, body, pricing, buffer) {
+    if (!buffer)
+        return;
+    let task = getCurrentTask();
+    if (!task) {
+        // Auto-create a task so LLM costs are never silently lost
+        // (mirrors Python create_auto_task).
+        task = createAutoTask("openai.chat");
+        buffer.upsertTask(task);
+    }
+    const resp = response;
+    const bodyObj = (body ?? {});
+    const model = resp["model"] ??
+        bodyObj["model"] ??
+        "unknown";
+    const usage = resp["usage"];
+    const hasUsage = usage != null;
+    const inputTokens = usage?.["prompt_tokens"] ?? 0;
+    const outputTokens = usage?.["completion_tokens"] ?? 0;
+    const promptDetails = usage?.["prompt_tokens_details"];
+    const cachedTokens = promptDetails?.["cached_tokens"] ?? 0;
+    let costUsd = 0;
+    let costConfidence = "estimated";
+    let pricingSource = "unknown";
+    if (hasUsage) {
+        const result = pricing.getCost(model, inputTokens, outputTokens, cachedTokens);
+        costUsd = result.costUsd;
+        costConfidence = result.costConfidence;
+        pricingSource = result.pricingSource;
+    }
+    _addEventAndUpdateTask(task, buffer, {
+        provider: "openai",
+        model,
+        inputTokens,
+        outputTokens,
+        cachedTokens,
+        costUsd,
+        costConfidence,
+        pricingSource,
+    });
+}
+// ---------------------------------------------------------------------------
+// TrackedAnthropic
+// ---------------------------------------------------------------------------
+/**
+ * Wraps `@anthropic-ai/sdk Anthropic` and auto-records llm_call events on
+ * every `messages.create` call when running inside a tracked task context.
+ */
+export class TrackedAnthropic {
+    _client;
+    _pricing;
+    _buffer;
+    constructor(opts) {
+        if (opts?.client !== undefined) {
+            this._client = opts.client;
+        }
+        else {
+            // Lazy require — @anthropic-ai/sdk is an optional peer dependency
+            let AnthropicClass;
+            try {
+                // eslint-disable-next-line @typescript-eslint/no-require-imports
+                const anthropicModule = require("@anthropic-ai/sdk");
+                AnthropicClass = (anthropicModule.default ?? anthropicModule.Anthropic);
+            }
+            catch {
+                throw new Error("The '@anthropic-ai/sdk' package is required for TrackedAnthropic. Install it with: npm install @anthropic-ai/sdk");
+            }
+            this._client = new AnthropicClass();
+        }
+        if (opts?.tracker !== undefined) {
+            this._pricing = opts.tracker.pricing;
+            this._buffer = opts.tracker.buffer;
+        }
+        else if (opts?.pricing !== undefined) {
+            this._pricing = opts.pricing;
+            this._buffer = null;
+        }
+        else {
+            this._pricing = new PricingEngine();
+            this._buffer = null;
+        }
+    }
+    get messages() {
+        const pricing = this._pricing;
+        const buffer = this._buffer;
+        const client = this._client;
+        return {
+            create: async (...args) => {
+                const response = await client.messages.create(...args);
+                recordAnthropicEvent(response, args[0], pricing, buffer);
+                return response;
+            },
+        };
+    }
+}
+function recordAnthropicEvent(response, body, pricing, buffer) {
+    if (!buffer)
+        return;
+    let task = getCurrentTask();
+    if (!task) {
+        // Auto-create a task so LLM costs are never silently lost
+        // (mirrors Python create_auto_task).
+        task = createAutoTask("anthropic.messages");
+        buffer.upsertTask(task);
+    }
+    const resp = response;
+    const bodyObj = (body ?? {});
+    const model = resp["model"] ??
+        bodyObj["model"] ??
+        "unknown";
+    const usage = resp["usage"];
+    const hasUsage = usage != null;
+    const inputTokens = usage?.["input_tokens"] ?? 0;
+    const outputTokens = usage?.["output_tokens"] ?? 0;
+    const cacheCreationTokens = usage?.["cache_creation_input_tokens"] ?? 0;
+    const cacheReadTokens = usage?.["cache_read_input_tokens"] ?? 0;
+    // cachedTokens tracks cache_read (for aggregation); cache_creation stored in details
+    const cachedTokens = cacheReadTokens;
+    let costUsd = 0;
+    let costConfidence = "estimated";
+    let pricingSource = "unknown";
+    if (hasUsage) {
+        const result = pricing.getCost(model, inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens);
+        costUsd = result.costUsd;
+        costConfidence = result.costConfidence;
+        pricingSource = result.pricingSource;
+    }
+    _addEventAndUpdateTask(task, buffer, {
+        provider: "anthropic",
+        model,
+        inputTokens,
+        outputTokens,
+        cachedTokens,
+        costUsd,
+        costConfidence,
+        pricingSource,
+        details: cacheCreationTokens > 0 ? { cache_creation_input_tokens: cacheCreationTokens } : undefined,
+    });
+}
+function _addEventAndUpdateTask(task, buffer, spec) {
+    const event = createCostEvent({
+        eventId: randomUUID(),
+        taskId: task.taskId,
+        eventType: "llm_call",
+        costUsd: spec.costUsd,
+        costConfidence: spec.costConfidence,
+        pricingSource: spec.pricingSource,
+        provider: spec.provider,
+        model: spec.model,
+        inputTokens: spec.inputTokens,
+        outputTokens: spec.outputTokens,
+        cachedTokens: spec.cachedTokens,
+        isRetry: false,
+        details: spec.details ?? {},
+    });
+    buffer.addEvent(event);
+    task.llmCostUsd += spec.costUsd;
+    task.totalCostUsd += spec.costUsd;
+    task.totalInputTokens += spec.inputTokens;
+    task.totalOutputTokens += spec.outputTokens;
+    task.totalCachedTokens += spec.cachedTokens;
+    buffer.upsertTask(task);
+}
+//# sourceMappingURL=clients.js.map

package/dist/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../src/clients.ts"],"names":[],"mappings":"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"}

package/dist/cloud-detect.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Cloud-environment detection for egress pricing.
+ *
+ * Mirrors `python/src/dexcost/cloud_detect.py` exactly — env-var names,
+ * DMI strings, and IMDS endpoints have all been verified against May-2026
+ * docs and MUST NOT be changed in this port.
+ *
+ * Phase 1a — env-var detection  (sub-millisecond, synchronous).
+ * Phase 1b — DMI vendor check   (~1 ms, Linux-only — silent no-op elsewhere).
+ * Phase 2  — background metadata probe (fire-and-forget Promise, ~250 ms
+ *            budget, never blocks `dexcost.init()`).
+ *
+ * Notes — research May 2026:
+ * - AWS Lambda / Fargate / App Runner set `AWS_REGION` automatically; ECS
+ *   (Fargate and on-EC2) also sets `ECS_CONTAINER_METADATA_URI_V4`.
+ * - Azure Container Apps embeds the region in `CONTAINER_APP_HOSTNAME` and
+ *   `CONTAINER_APP_ENV_DNS_SUFFIX` as `<host>.<REGION>.azurecontainerapps.io`.
+ * - GCP Cloud Run / Cloud Functions Gen2 / App Engine do NOT expose a region
+ *   env var; region must come from the metadata server (Phase 2).
+ * - AWS IMDSv2 has a default HTTP hop-limit of 1, which prevents Docker/Pod
+ *   containers from reaching the metadata service; the probe fails silent.
+ */
+export interface CloudEnv {
+    provider: string | null;
+    region: string | null;
+    source: "env" | "dmi" | "imds" | "none";
+    /**
+     * IaaS instance type when known — e.g. "c7g.xlarge", "n2-standard-2",
+     * "Standard_D2s_v3". Compute pricing reads this at task finalize for
+     * EC2 / GCE / Azure VM SKU rate resolution (Decision #3 — extracted in
+     * the same Phase 2 background thread as the region probe).
+     */
+    instanceType?: string | null;
+}
+export declare function getCloudEnv(): CloudEnv;
+/**
+ * Test-only — force the resolved CloudEnv to a known value. Used by
+ * downstream finalize tests (Phase D Task 10) that need a deterministic
+ * egress rate without actually probing IMDS or reading DMI. The
+ * `_for_tests` suffix marks this as not-public-API.
+ */
+export declare function _setResultForTests(env: CloudEnv): void;
+export declare function _resetCloudDetectForTests(): void;
+export declare function _setReadDmiForTests(fn: (() => Record<string, string>) | null): void;
+/**
+ * Strip a GCP metadata-server `projects/.../<X>/<name>` response to a region.
+ *
+ * Zone form  (`projects/123/zones/us-central1-a`) → `us-central1` when
+ *   `dropZoneLetter=true`.
+ * Region form (`projects/123/regions/us-central1`) → `us-central1` when
+ *   `dropZoneLetter=false`.
+ */
+export declare function _gcpPathToRegion(value: string, dropZoneLetter: boolean): string | null;
+export declare function _setFetchForTests(impl: typeof fetch | null): void;
+declare function _probeAws(): Promise<CloudEnv | null>;
+declare function _probeGcp(): Promise<CloudEnv | null>;
+declare function _probeAzure(): Promise<CloudEnv | null>;
+declare function _probeOci(): Promise<CloudEnv | null>;
+declare function _probeDigitalOcean(): Promise<CloudEnv | null>;
+declare function _probeAlibaba(): Promise<CloudEnv | null>;
+/**
+ * Provider hint → metadata probe. Mutable so tests can stub individual
+ * probes via `monkeypatch.setitem` (Python idiom) → `_PROBES["aws"] = …`.
+ */
+export declare const _PROBES: Record<string, () => Promise<CloudEnv | null>>;
+/**
+ * Phase 2 fanout providers. When DMI doesn't pre-classify, we race AWS/GCP/
+ * Azure in parallel — adding OCI/DO/Alibaba would lengthen worst-case wait
+ * and hit the wrong metadata server (DO uses the same 169.254.169.254 IP).
+ */
+export declare const _FANOUT_PROBES: readonly ["aws", "gcp", "azure"];
+declare function _runProbe(providerHint: string | null): Promise<CloudEnv>;
+/** Run Phase 1a + 1b synchronously. Used by tests; never calls IMDS. */
+export declare function detectNow(): CloudEnv;
+/**
+ * Resolve provider/region without blocking. Idempotent.
+ *
+ * When `trackNetwork` is false, no probe is launched.
+ *
+ * Phase 1a + 1b run synchronously; Phase 2 is fire-and-forget so init()
+ * returns immediately. Tests can await `_backgroundPromise` via the
+ * `_awaitBackgroundForTests` helper.
+ */
+export declare function startBackgroundDetection(trackNetwork?: boolean): void;
+/** Test-only helper to await the background Phase 2 probe. */
+export declare function _awaitBackgroundForTests(): Promise<void>;
+export declare const _probes: {
+    aws: typeof _probeAws;
+    gcp: typeof _probeGcp;
+    azure: typeof _probeAzure;
+    oci: typeof _probeOci;
+    digitalocean: typeof _probeDigitalOcean;
+    alibaba: typeof _probeAlibaba;
+};
+export { _runProbe };
+//# sourceMappingURL=cloud-detect.d.ts.map

package/dist/cloud-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud-detect.d.ts","sourceRoot":"","sources":["../src/cloud-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAiED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAEtD;AAGD,wBAAgB,yBAAyB,IAAI,IAAI,CAGhD;AAmID,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,IAAI,CAEnF;AA0BD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUtF;AAID,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,KAAK,GAAG,IAAI,GAAG,IAAI,CAEjE;AAED,iBAAe,SAAS,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAgDnD;AAED,iBAAe,SAAS,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAsDnD;AAED,iBAAe,WAAW,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAqBrD;AAED,iBAAe,SAAS,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAenD;AAED,iBAAe,kBAAkB,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAW5D;AAED,iBAAe,aAAa,IAAI,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAWvD;AAED;;;GAGG;AACH,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAOlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,kCAAmC,CAAC;AAE/D,iBAAe,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgDvE;AAMD,wEAAwE;AACxE,wBAAgB,SAAS,IAAI,QAAQ,CAQpC;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,GAAE,OAAc,GAAG,IAAI,CAsC3E;AAED,8DAA8D;AAC9D,wBAAsB,wBAAwB,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9D;AAID,eAAO,MAAM,OAAO;;;;;;;CAOnB,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC"}