marginfuse 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0]
+
+First release from this repository. Earlier versions were published from a
+private monorepo, which is why the 0.1.0 page on npm links to a repository
+nobody can open. That is what this release fixes, along with everything below.
+
+### Added
+
+- `fromOpenRouter()` maps an OpenRouter `usage` object to MarginFuse fields,
+  including the gateway's own `cost`, so figures from a gateway are exact
+  rather than estimated. It exists because mapping the fields by hand gets two
+  things silently wrong: `prompt_tokens` already contains cached reads and
+  cache writes, which MarginFuse prices separately, and small costs stringify
+  to exponent notation, which the API rejects.
+- `openrouter` in the `provider` union.
+- Published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
+  so the build that produced this package is publicly verifiable.
+
+### Fixed
+
+- **A `block` verdict with no decision id no longer runs the provider call.**
+  Enforcement checked the action and the id together, so a decision that
+  arrived without an id fell through and the call went out. A missing id costs
+  an acknowledgment; it must never turn a block into a provider call. The same
+  applied to `topup_required`.
+- **`track()` no longer throws on Node 18.** The auto-generated event id used
+  `crypto.randomUUID()`, and `globalThis.crypto` only became a global in Node
+  19, so on Node 18 (which this package supports) omitting `eventId` threw a
+  `ReferenceError` synchronously into application code. The id now comes from
+  whatever the runtime offers and degrades rather than throwing, so it also
+  works on edge runtimes with no `node:crypto`.
+
+### Changed
+
+- Verified against [marginfuse/sdk-contract](https://github.com/marginfuse/sdk-contract),
+  the shared conformance suite every MarginFuse SDK is held to. Fifteen
+  behavioral scenarios and thirteen gateway vectors run in CI against the packed
+  artifact, not against the source tree.
+
+## [0.1.0]
+
+Initial release. Published from a private monorepo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pemira Labs
+
+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,157 @@
+# marginfuse
+
+[![npm](https://img.shields.io/npm/v/marginfuse)](https://www.npmjs.com/package/marginfuse)
+[![ci](https://github.com/marginfuse/marginfuse-node/actions/workflows/ci.yml/badge.svg)](https://github.com/marginfuse/marginfuse-node/actions/workflows/ci.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Server-side SDK for [MarginFuse](https://marginfuse.com): profitability
+guardrails for AI SaaS. Connect revenue to per-request AI cost, see gross margin
+per customer, and stop loss-making requests before they run.
+
+- **Metadata only, by construction.** The event shape has no field for prompts
+  or responses, so they cannot be sent. Not a policy, an absence.
+- **Never breaks your app.** It does not throw into your code, and it does not
+  block your request on MarginFuse being up. If MarginFuse is unreachable, your
+  requests proceed unchanged.
+- **Zero dependencies.** Node 18+, Next.js route handlers, serverless functions.
+
+> **Server side only.** This SDK carries a secret API key. Never ship it in a
+> browser bundle, a mobile app, or anything else a user can read.
+
+## Install
+
+```bash
+npm install marginfuse
+```
+
+## Track an AI call
+
+Monitoring. One call after each AI request, metadata only.
+
+```ts
+import { MarginFuse } from "marginfuse";
+
+const mf = new MarginFuse({ apiKey: process.env.MARGINFUSE_KEY! });
+
+mf.track({
+  customerId: "cus_8x2m91",   // your Stripe customer id, or your own id
+  feature: "ai_chat",
+  provider: "openai",
+  model: "gpt-4.1",
+  usage: { inputTokens: 1204, outputTokens: 388 },
+  // or costUsd: "0.0084" when your provider reports the real charge
+});
+```
+
+`track()` is fire and forget with retries. In a script or a background job, call
+`await mf.flush()` before the process exits, or the last events are lost.
+
+## Guard a call
+
+Protection. Ask before the call runs, and act on the answer.
+
+```ts
+const out = await mf.guard(
+  { customerId: "cus_8x2m91", feature: "ai_chat", provider: "openai", model: "gpt-4.1" },
+  async ({ model }) => {
+    const r = await openai.chat.completions.create({ model, messages });
+    return {
+      result: r,
+      usage: { inputTokens: r.usage.prompt_tokens, outputTokens: r.usage.completion_tokens },
+    };
+  },
+);
+
+if (out.kind === "completed") use(out.result);
+// out.kind === "blocked" | "topup_required" -> your own UX decides what to show
+```
+
+One wrapper does the whole loop: ask, run with the resolved model, report the
+real cost, acknowledge what your application did. A `downgrade` verdict changes
+the `model` your callback receives, so the cheaper model is actually the one
+that runs.
+
+Policies run in dry-run first. You see what protection would have done against
+your real traffic before anything is allowed to act.
+
+## OpenRouter and other gateways
+
+Gateways report the real cost of every call. Forward it and your figures are
+exact instead of estimated.
+
+```ts
+import { MarginFuse, fromOpenRouter } from "marginfuse";
+
+const r = await openai.chat.completions.create({ model: "anthropic/claude-sonnet-4.5", messages });
+
+mf.track({
+  customerId: "cus_8x2m91",
+  feature: "ai_chat",
+  provider: "openrouter",
+  model: "anthropic/claude-sonnet-4.5",
+  ...fromOpenRouter(r.usage),
+});
+```
+
+Use the helper rather than mapping the fields yourself. OpenRouter's
+`prompt_tokens` already includes cached reads and cache writes, which MarginFuse
+prices separately, so passing it through directly charges every cached token
+twice at the full input rate. The helper also formats the cost as a decimal
+string, because `String(cost)` produces `1.2e-7` for small costs and the API
+rejects that.
+
+If a gateway event arrives without a cost, MarginFuse prices it from the
+upstream vendor's list price for the model behind the id and labels the figure
+**EST**, because the gateway's own margin is not in that number.
+
+## Configuration
+
+```ts
+new MarginFuse({
+  apiKey: process.env.MARGINFUSE_KEY!,
+  baseUrl: "https://api.marginfuse.com",  // point at your own deployment in dev
+  timeoutMs: 1500,                        // decide() budget before failing open
+  onError: (err, context) => log.warn({ err, context }),  // the SDK never throws
+});
+```
+
+## What it sends
+
+Everything, and nothing else:
+
+```
+eventId  customerId  feature  provider  model  requestedModel
+usage { inputTokens, outputTokens, cachedInputTokens, cacheCreationTokens, images, audioSeconds }
+costUsd  occurredAt  outcome  decisionId  retryOfEventId  correctsEventId
+```
+
+There is no field for message content anywhere in the wire types. The
+[conformance suite](https://github.com/marginfuse/sdk-contract) checks this
+against the bytes that actually leave the process, on every scenario.
+
+## Conformance
+
+This SDK is verified against
+[marginfuse/sdk-contract](https://github.com/marginfuse/sdk-contract), the same
+contract every MarginFuse SDK in every language is held to. It is a submodule
+here, so the pinned commit records exactly which contract a release passed.
+
+```bash
+git clone --recurse-submodules https://github.com/marginfuse/marginfuse-node
+cd marginfuse-node
+npm install
+npm test          # unit tests, plus the shared gateway vectors
+npm run build && npm pack
+npm --prefix contract/harness install ../../marginfuse-*.tgz
+npm run conformance   # 16 scenarios against the packed artifact
+```
+
+## Links
+
+- [MarginFuse](https://marginfuse.com), product and pricing
+- [Live demo](https://marginfuse.com/demo), a read-only workspace, no signup
+- [API reference](https://api.marginfuse.com/openapi.json)
+- [Security policy](SECURITY.md)
+- [Contributing](CONTRIBUTING.md)
+
+MIT, Pemira Labs.

package/dist/index.cjs

@@ -0,0 +1,264 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MarginFuse: () => MarginFuse,
+  fromOpenRouter: () => fromOpenRouter
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.marginfuse.com";
+var DEFAULT_TIMEOUT_MS = 1500;
+var TRACK_RETRIES = 3;
+var MarginFuse = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  onError;
+  fetchImpl;
+  pending = /* @__PURE__ */ new Set();
+  constructor(options) {
+    if (!options.apiKey) throw new Error("MarginFuse: apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.onError = options.onError ?? (() => {
+    });
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Pre-request policy check (protection-ready integrations, §13.2).
+   * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+   */
+  async decide(params) {
+    const failOpen = (reason) => ({
+      action: "allow",
+      model: params.model,
+      provider: params.provider,
+      degraded: true,
+      degradedReason: reason
+    });
+    try {
+      const res = await this.post("/v1/decisions", params, this.timeoutMs);
+      if (!res.ok) {
+        this.onError(new Error(`decide: HTTP ${res.status}`), "decide");
+        return failOpen(`server responded ${res.status}`);
+      }
+      const body = await res.json();
+      return {
+        id: body.id,
+        action: body.action,
+        model: body.model ?? params.model,
+        provider: body.provider ?? params.provider,
+        ...body.topupContext !== void 0 ? { topupContext: body.topupContext } : {},
+        degraded: body.degraded ?? false,
+        ...body.degradedReason !== void 0 ? { degradedReason: body.degradedReason } : {}
+      };
+    } catch (err) {
+      this.onError(err, "decide");
+      return failOpen(err.name === "TimeoutError" ? "timeout" : "unreachable");
+    }
+  }
+  /**
+   * Report actual usage after the provider call (monitor-only §13.1 and
+   * post-request reconciliation §25.3). Fire-and-forget with retries.
+   */
+  track(params) {
+    const event = {
+      eventId: params.eventId ?? cryptoRandomId(),
+      occurredAt: (params.occurredAt ?? /* @__PURE__ */ new Date()).toISOString(),
+      outcome: params.outcome ?? "success",
+      ...params
+    };
+    this.background(async () => {
+      let lastErr;
+      for (let attempt = 0; attempt < TRACK_RETRIES; attempt++) {
+        try {
+          const res = await this.post("/v1/events", { events: [event] }, 5e3);
+          if (res.ok) return;
+          if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            this.onError(new Error(`track: HTTP ${res.status} ${await safeText(res)}`), "track");
+            return;
+          }
+          lastErr = new Error(`track: HTTP ${res.status}`);
+        } catch (err) {
+          lastErr = err;
+        }
+        await sleep(250 * 2 ** attempt);
+      }
+      if (lastErr) this.onError(lastErr, "track");
+    });
+  }
+  /** Awaitable variant of track for jobs/scripts that must not exit early. */
+  async trackAndWait(params) {
+    this.track(params);
+    await this.flush();
+  }
+  /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+  acknowledge(decisionId, acknowledgment) {
+    this.background(async () => {
+      try {
+        const res = await this.post(`/v1/decisions/${encodeURIComponent(decisionId)}/ack`, { acknowledgment }, 5e3);
+        if (!res.ok) this.onError(new Error(`ack: HTTP ${res.status}`), "acknowledge");
+      } catch (err) {
+        this.onError(err, "acknowledge");
+      }
+    });
+  }
+  /**
+   * Full protection loop in one wrapper: decide → run your provider call with
+   * the resolved model → report usage → acknowledge.
+   *
+   * const out = await mf.guard(
+   *   { customerId, feature: "ai_chat", provider: "openai", model: "gpt-4.1" },
+   *   async ({ model }) => {
+   *     const r = await openai.chat.completions.create({ model, messages });
+   *     return { result: r, usage: { inputTokens: r.usage.prompt_tokens, outputTokens: r.usage.completion_tokens } };
+   *   },
+   * );
+   * if (out.kind === "completed") use(out.result);
+   * else handle out.kind === "blocked" | "topup_required" with your own UX.
+   */
+  async guard(params, run) {
+    const decision = await this.decide(params);
+    if (decision.action === "block") {
+      if (decision.id) this.acknowledge(decision.id, "blocked_before_provider_call");
+      return { kind: "blocked", decision };
+    }
+    if (decision.action === "topup_required") {
+      if (decision.id) this.acknowledge(decision.id, "presented_topup");
+      return { kind: "topup_required", decision };
+    }
+    const modelToUse = decision.action === "downgrade" ? decision.model : params.model;
+    let outcome = "success";
+    try {
+      const out = await run({ model: modelToUse, provider: decision.provider, decision });
+      this.track({
+        customerId: params.customerId,
+        ...params.feature !== void 0 ? { feature: params.feature } : {},
+        provider: params.provider,
+        model: modelToUse,
+        requestedModel: params.model,
+        usage: out.usage,
+        ...out.costUsd !== void 0 ? { costUsd: out.costUsd } : {},
+        outcome: out.outcome ?? "success",
+        ...decision.id !== void 0 ? { decisionId: decision.id } : {}
+      });
+      if (decision.id) {
+        this.acknowledge(
+          decision.id,
+          decision.action === "downgrade" ? "used_downgrade_model" : "proceeded_as_requested"
+        );
+      }
+      return { kind: "completed", result: out.result, decision };
+    } catch (err) {
+      outcome = "provider_error";
+      this.track({
+        customerId: params.customerId,
+        ...params.feature !== void 0 ? { feature: params.feature } : {},
+        provider: params.provider,
+        model: modelToUse,
+        requestedModel: params.model,
+        usage: {},
+        outcome,
+        ...decision.id !== void 0 ? { decisionId: decision.id } : {}
+      });
+      if (decision.id) this.acknowledge(decision.id, "proceeded_as_requested");
+      throw err;
+    }
+  }
+  /** Wait for queued track/ack calls (use before process exit). */
+  async flush() {
+    await Promise.allSettled([...this.pending]);
+  }
+  background(fn) {
+    const p = fn().finally(() => this.pending.delete(p));
+    this.pending.add(p);
+  }
+  post(path, body, timeoutMs) {
+    return this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json",
+        "user-agent": "marginfuse-node/0.1.0"
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  }
+};
+function cryptoRandomId() {
+  return `evt_${uuidV4()}`;
+}
+function uuidV4() {
+  const webcrypto = globalThis.crypto;
+  if (typeof webcrypto?.randomUUID === "function") return webcrypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (typeof webcrypto?.getRandomValues === "function") {
+    webcrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (const b of bytes) hex.push(b.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function safeText(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return "";
+  }
+}
+
+// src/openrouter.ts
+var int = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+function creditsToUsd(cost) {
+  const s = cost.toFixed(9);
+  const trimmed = s.includes(".") ? s.replace(/0+$/, "").replace(/\.$/, "") : s;
+  return trimmed === "" || trimmed === "-0" ? "0" : trimmed;
+}
+function fromOpenRouter(usage) {
+  const cachedInputTokens = int(usage?.prompt_tokens_details?.cached_tokens);
+  const cacheCreationTokens = int(usage?.prompt_tokens_details?.cache_write_tokens);
+  const inputTokens = Math.max(0, int(usage?.prompt_tokens) - cachedInputTokens - cacheCreationTokens);
+  const out = {};
+  if (inputTokens > 0) out.inputTokens = inputTokens;
+  const outputTokens = int(usage?.completion_tokens);
+  if (outputTokens > 0) out.outputTokens = outputTokens;
+  if (cachedInputTokens > 0) out.cachedInputTokens = cachedInputTokens;
+  if (cacheCreationTokens > 0) out.cacheCreationTokens = cacheCreationTokens;
+  const cost = usage?.cost;
+  const hasCost = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
+  return { usage: out, ...hasCost ? { costUsd: creditsToUsd(cost) } : {} };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MarginFuse,
+  fromOpenRouter
+});

package/dist/index.d.cts

@@ -0,0 +1,191 @@
+/**
+ * Wire types for the MarginFuse SDK. Deliberately: there is NO field for
+ * prompt text, responses, or documents - the SDK cannot leak what it cannot
+ * carry (spec §5.6, §33).
+ */
+interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    cacheCreationTokens?: number;
+    images?: number;
+    audioSeconds?: number;
+}
+type Outcome = "success" | "provider_error" | "app_cancelled" | "timeout";
+interface TrackParams {
+    /** Your unique id for this call; reusing one is safe (idempotent). Auto-generated if omitted. */
+    eventId?: string;
+    /** Your application's id for the end customer (or their Stripe customer id). */
+    customerId: string;
+    /** Stable feature key, e.g. "ai_chat". */
+    feature?: string;
+    provider: "openai" | "anthropic" | "openrouter" | (string & {});
+    model: string;
+    requestedModel?: string;
+    usage: Usage;
+    /** Actual cost if your provider response includes it (decimal string, e.g. "0.0142"). */
+    costUsd?: string;
+    occurredAt?: Date;
+    outcome?: Outcome;
+    /** Link to a prior decide() result for reconciliation. */
+    decisionId?: string;
+    retryOfEventId?: string;
+    correctsEventId?: string;
+}
+interface DecideParams {
+    customerId: string;
+    feature?: string;
+    provider: "openai" | "anthropic" | "openrouter" | (string & {});
+    model: string;
+    /** Optional expected usage for a better pre-request cost estimate. */
+    expectedUsage?: Usage;
+}
+type DecisionAction = "allow" | "downgrade" | "topup_required" | "block";
+interface Decision {
+    /** Present when the server produced the decision; absent on fail-open. */
+    id?: string;
+    action: DecisionAction;
+    /** The model your app should use for this request (downgrades change it). */
+    model: string;
+    provider: string;
+    /** For topup_required: pass-through context configured in the policy. */
+    topupContext?: string;
+    /** True when MarginFuse could not be reached / evaluated - request allowed (fail-open). */
+    degraded: boolean;
+    degradedReason?: string;
+}
+type Acknowledgment = "proceeded_as_requested" | "used_downgrade_model" | "presented_topup" | "blocked_before_provider_call" | "failed_to_apply";
+interface MarginFuseOptions {
+    apiKey: string;
+    /** Default https://api.marginfuse.com - point at your own deployment in dev. */
+    baseUrl?: string;
+    /** Decision timeout. On expiry the SDK fails open (allow). Default 1500 ms. */
+    timeoutMs?: number;
+    /** Called with transport errors the SDK swallowed (it never throws into your app). */
+    onError?: (error: Error, context: string) => void;
+    fetch?: typeof fetch;
+}
+
+/**
+ * MarginFuse Node SDK.
+ *
+ * Reliability contract (spec §5.5, §29.3): this SDK NEVER throws into
+ * application code and NEVER blocks a request on MarginFuse availability.
+ * decide() fails open to "allow" on any timeout or error; track()/report()
+ * retry in the background and surface problems only via options.onError.
+ */
+
+declare class MarginFuse {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly onError;
+    private readonly fetchImpl;
+    private readonly pending;
+    constructor(options: MarginFuseOptions);
+    /**
+     * Pre-request policy check (protection-ready integrations, §13.2).
+     * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+     */
+    decide(params: DecideParams): Promise<Decision>;
+    /**
+     * Report actual usage after the provider call (monitor-only §13.1 and
+     * post-request reconciliation §25.3). Fire-and-forget with retries.
+     */
+    track(params: TrackParams): void;
+    /** Awaitable variant of track for jobs/scripts that must not exit early. */
+    trackAndWait(params: TrackParams): Promise<void>;
+    /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+    acknowledge(decisionId: string, acknowledgment: Acknowledgment): void;
+    /**
+     * Full protection loop in one wrapper: decide → run your provider call with
+     * the resolved model → report usage → acknowledge.
+     *
+     * const out = await mf.guard(
+     *   { customerId, feature: "ai_chat", provider: "openai", model: "gpt-4.1" },
+     *   async ({ model }) => {
+     *     const r = await openai.chat.completions.create({ model, messages });
+     *     return { result: r, usage: { inputTokens: r.usage.prompt_tokens, outputTokens: r.usage.completion_tokens } };
+     *   },
+     * );
+     * if (out.kind === "completed") use(out.result);
+     * else handle out.kind === "blocked" | "topup_required" with your own UX.
+     */
+    guard<T>(params: DecideParams, run: (ctx: {
+        model: string;
+        provider: string;
+        decision: Decision;
+    }) => Promise<{
+        result: T;
+        usage: TrackParams["usage"];
+        costUsd?: string;
+        outcome?: TrackParams["outcome"];
+    }>): Promise<{
+        kind: "completed";
+        result: T;
+        decision: Decision;
+    } | {
+        kind: "blocked";
+        decision: Decision;
+    } | {
+        kind: "topup_required";
+        decision: Decision;
+    }>;
+    /** Wait for queued track/ack calls (use before process exit). */
+    flush(): Promise<void>;
+    private background;
+    private post;
+}
+
+/**
+ * OpenRouter helper.
+ *
+ * OpenRouter returns a `usage` object on every response (no opt-in parameter -
+ * the old `usage: { include: true }` flag is deprecated and does nothing), and
+ * that object carries the provider-final `cost`. Forwarding it is what makes an
+ * OpenRouter integration exact rather than estimated: MarginFuse cannot know
+ * what a gateway charged, because routing, fees and BYOK terms are not visible
+ * in a usage event.
+ *
+ * Two details this helper exists to get right, both of which silently
+ * misstate margin when hand-rolled:
+ *
+ *  1. `prompt_tokens` is the TOTAL input count - cached reads and cache writes
+ *     are already inside it. MarginFuse prices inputTokens, cachedInputTokens
+ *     and cacheCreationTokens as three separate charges and adds them up, so
+ *     passing `prompt_tokens` straight through double-counts every cached
+ *     token, at the full uncached rate.
+ *  2. `cost` is a JavaScript number, and small ones stringify to exponent
+ *     notation ("1.2e-7"), which the API rejects as a decimal string.
+ */
+
+/**
+ * The fields this helper reads from an OpenRouter `usage` object. Structural on
+ * purpose - it accepts the response of the OpenAI SDK pointed at OpenRouter,
+ * or a plain fetch, without either side importing the other's types.
+ */
+interface OpenRouterUsage {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    cost?: number | null;
+    prompt_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+        audio_tokens?: number | null;
+    } | null;
+}
+/**
+ * Map an OpenRouter `usage` object to the MarginFuse fields, ready to spread
+ * into track() or return from guard().
+ *
+ * const r = await openai.chat.completions.create({ model, messages });
+ * mf.track({ customerId, feature: "ai_chat", provider: "openrouter", model, ...fromOpenRouter(r.usage) });
+ *
+ * `costUsd` is omitted when the response carried no cost, which lets the event
+ * fall through to MarginFuse's own pricing instead of claiming a $0 charge.
+ */
+declare function fromOpenRouter(usage: OpenRouterUsage | null | undefined): Pick<TrackParams, "usage"> & {
+    costUsd?: string;
+};
+
+export { type Acknowledgment, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };

package/dist/index.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Wire types for the MarginFuse SDK. Deliberately: there is NO field for
+ * prompt text, responses, or documents - the SDK cannot leak what it cannot
+ * carry (spec §5.6, §33).
+ */
+interface Usage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    cacheCreationTokens?: number;
+    images?: number;
+    audioSeconds?: number;
+}
+type Outcome = "success" | "provider_error" | "app_cancelled" | "timeout";
+interface TrackParams {
+    /** Your unique id for this call; reusing one is safe (idempotent). Auto-generated if omitted. */
+    eventId?: string;
+    /** Your application's id for the end customer (or their Stripe customer id). */
+    customerId: string;
+    /** Stable feature key, e.g. "ai_chat". */
+    feature?: string;
+    provider: "openai" | "anthropic" | "openrouter" | (string & {});
+    model: string;
+    requestedModel?: string;
+    usage: Usage;
+    /** Actual cost if your provider response includes it (decimal string, e.g. "0.0142"). */
+    costUsd?: string;
+    occurredAt?: Date;
+    outcome?: Outcome;
+    /** Link to a prior decide() result for reconciliation. */
+    decisionId?: string;
+    retryOfEventId?: string;
+    correctsEventId?: string;
+}
+interface DecideParams {
+    customerId: string;
+    feature?: string;
+    provider: "openai" | "anthropic" | "openrouter" | (string & {});
+    model: string;
+    /** Optional expected usage for a better pre-request cost estimate. */
+    expectedUsage?: Usage;
+}
+type DecisionAction = "allow" | "downgrade" | "topup_required" | "block";
+interface Decision {
+    /** Present when the server produced the decision; absent on fail-open. */
+    id?: string;
+    action: DecisionAction;
+    /** The model your app should use for this request (downgrades change it). */
+    model: string;
+    provider: string;
+    /** For topup_required: pass-through context configured in the policy. */
+    topupContext?: string;
+    /** True when MarginFuse could not be reached / evaluated - request allowed (fail-open). */
+    degraded: boolean;
+    degradedReason?: string;
+}
+type Acknowledgment = "proceeded_as_requested" | "used_downgrade_model" | "presented_topup" | "blocked_before_provider_call" | "failed_to_apply";
+interface MarginFuseOptions {
+    apiKey: string;
+    /** Default https://api.marginfuse.com - point at your own deployment in dev. */
+    baseUrl?: string;
+    /** Decision timeout. On expiry the SDK fails open (allow). Default 1500 ms. */
+    timeoutMs?: number;
+    /** Called with transport errors the SDK swallowed (it never throws into your app). */
+    onError?: (error: Error, context: string) => void;
+    fetch?: typeof fetch;
+}
+
+/**
+ * MarginFuse Node SDK.
+ *
+ * Reliability contract (spec §5.5, §29.3): this SDK NEVER throws into
+ * application code and NEVER blocks a request on MarginFuse availability.
+ * decide() fails open to "allow" on any timeout or error; track()/report()
+ * retry in the background and surface problems only via options.onError.
+ */
+
+declare class MarginFuse {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly onError;
+    private readonly fetchImpl;
+    private readonly pending;
+    constructor(options: MarginFuseOptions);
+    /**
+     * Pre-request policy check (protection-ready integrations, §13.2).
+     * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+     */
+    decide(params: DecideParams): Promise<Decision>;
+    /**
+     * Report actual usage after the provider call (monitor-only §13.1 and
+     * post-request reconciliation §25.3). Fire-and-forget with retries.
+     */
+    track(params: TrackParams): void;
+    /** Awaitable variant of track for jobs/scripts that must not exit early. */
+    trackAndWait(params: TrackParams): Promise<void>;
+    /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+    acknowledge(decisionId: string, acknowledgment: Acknowledgment): void;
+    /**
+     * Full protection loop in one wrapper: decide → run your provider call with
+     * the resolved model → report usage → acknowledge.
+     *
+     * const out = await mf.guard(
+     *   { customerId, feature: "ai_chat", provider: "openai", model: "gpt-4.1" },
+     *   async ({ model }) => {
+     *     const r = await openai.chat.completions.create({ model, messages });
+     *     return { result: r, usage: { inputTokens: r.usage.prompt_tokens, outputTokens: r.usage.completion_tokens } };
+     *   },
+     * );
+     * if (out.kind === "completed") use(out.result);
+     * else handle out.kind === "blocked" | "topup_required" with your own UX.
+     */
+    guard<T>(params: DecideParams, run: (ctx: {
+        model: string;
+        provider: string;
+        decision: Decision;
+    }) => Promise<{
+        result: T;
+        usage: TrackParams["usage"];
+        costUsd?: string;
+        outcome?: TrackParams["outcome"];
+    }>): Promise<{
+        kind: "completed";
+        result: T;
+        decision: Decision;
+    } | {
+        kind: "blocked";
+        decision: Decision;
+    } | {
+        kind: "topup_required";
+        decision: Decision;
+    }>;
+    /** Wait for queued track/ack calls (use before process exit). */
+    flush(): Promise<void>;
+    private background;
+    private post;
+}
+
+/**
+ * OpenRouter helper.
+ *
+ * OpenRouter returns a `usage` object on every response (no opt-in parameter -
+ * the old `usage: { include: true }` flag is deprecated and does nothing), and
+ * that object carries the provider-final `cost`. Forwarding it is what makes an
+ * OpenRouter integration exact rather than estimated: MarginFuse cannot know
+ * what a gateway charged, because routing, fees and BYOK terms are not visible
+ * in a usage event.
+ *
+ * Two details this helper exists to get right, both of which silently
+ * misstate margin when hand-rolled:
+ *
+ *  1. `prompt_tokens` is the TOTAL input count - cached reads and cache writes
+ *     are already inside it. MarginFuse prices inputTokens, cachedInputTokens
+ *     and cacheCreationTokens as three separate charges and adds them up, so
+ *     passing `prompt_tokens` straight through double-counts every cached
+ *     token, at the full uncached rate.
+ *  2. `cost` is a JavaScript number, and small ones stringify to exponent
+ *     notation ("1.2e-7"), which the API rejects as a decimal string.
+ */
+
+/**
+ * The fields this helper reads from an OpenRouter `usage` object. Structural on
+ * purpose - it accepts the response of the OpenAI SDK pointed at OpenRouter,
+ * or a plain fetch, without either side importing the other's types.
+ */
+interface OpenRouterUsage {
+    prompt_tokens?: number | null;
+    completion_tokens?: number | null;
+    cost?: number | null;
+    prompt_tokens_details?: {
+        cached_tokens?: number | null;
+        cache_write_tokens?: number | null;
+        audio_tokens?: number | null;
+    } | null;
+}
+/**
+ * Map an OpenRouter `usage` object to the MarginFuse fields, ready to spread
+ * into track() or return from guard().
+ *
+ * const r = await openai.chat.completions.create({ model, messages });
+ * mf.track({ customerId, feature: "ai_chat", provider: "openrouter", model, ...fromOpenRouter(r.usage) });
+ *
+ * `costUsd` is omitted when the response carried no cost, which lets the event
+ * fall through to MarginFuse's own pricing instead of claiming a $0 charge.
+ */
+declare function fromOpenRouter(usage: OpenRouterUsage | null | undefined): Pick<TrackParams, "usage"> & {
+    costUsd?: string;
+};
+
+export { type Acknowledgment, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };

package/dist/index.js

@@ -0,0 +1,236 @@
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.marginfuse.com";
+var DEFAULT_TIMEOUT_MS = 1500;
+var TRACK_RETRIES = 3;
+var MarginFuse = class {
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  onError;
+  fetchImpl;
+  pending = /* @__PURE__ */ new Set();
+  constructor(options) {
+    if (!options.apiKey) throw new Error("MarginFuse: apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.onError = options.onError ?? (() => {
+    });
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Pre-request policy check (protection-ready integrations, §13.2).
+   * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+   */
+  async decide(params) {
+    const failOpen = (reason) => ({
+      action: "allow",
+      model: params.model,
+      provider: params.provider,
+      degraded: true,
+      degradedReason: reason
+    });
+    try {
+      const res = await this.post("/v1/decisions", params, this.timeoutMs);
+      if (!res.ok) {
+        this.onError(new Error(`decide: HTTP ${res.status}`), "decide");
+        return failOpen(`server responded ${res.status}`);
+      }
+      const body = await res.json();
+      return {
+        id: body.id,
+        action: body.action,
+        model: body.model ?? params.model,
+        provider: body.provider ?? params.provider,
+        ...body.topupContext !== void 0 ? { topupContext: body.topupContext } : {},
+        degraded: body.degraded ?? false,
+        ...body.degradedReason !== void 0 ? { degradedReason: body.degradedReason } : {}
+      };
+    } catch (err) {
+      this.onError(err, "decide");
+      return failOpen(err.name === "TimeoutError" ? "timeout" : "unreachable");
+    }
+  }
+  /**
+   * Report actual usage after the provider call (monitor-only §13.1 and
+   * post-request reconciliation §25.3). Fire-and-forget with retries.
+   */
+  track(params) {
+    const event = {
+      eventId: params.eventId ?? cryptoRandomId(),
+      occurredAt: (params.occurredAt ?? /* @__PURE__ */ new Date()).toISOString(),
+      outcome: params.outcome ?? "success",
+      ...params
+    };
+    this.background(async () => {
+      let lastErr;
+      for (let attempt = 0; attempt < TRACK_RETRIES; attempt++) {
+        try {
+          const res = await this.post("/v1/events", { events: [event] }, 5e3);
+          if (res.ok) return;
+          if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+            this.onError(new Error(`track: HTTP ${res.status} ${await safeText(res)}`), "track");
+            return;
+          }
+          lastErr = new Error(`track: HTTP ${res.status}`);
+        } catch (err) {
+          lastErr = err;
+        }
+        await sleep(250 * 2 ** attempt);
+      }
+      if (lastErr) this.onError(lastErr, "track");
+    });
+  }
+  /** Awaitable variant of track for jobs/scripts that must not exit early. */
+  async trackAndWait(params) {
+    this.track(params);
+    await this.flush();
+  }
+  /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+  acknowledge(decisionId, acknowledgment) {
+    this.background(async () => {
+      try {
+        const res = await this.post(`/v1/decisions/${encodeURIComponent(decisionId)}/ack`, { acknowledgment }, 5e3);
+        if (!res.ok) this.onError(new Error(`ack: HTTP ${res.status}`), "acknowledge");
+      } catch (err) {
+        this.onError(err, "acknowledge");
+      }
+    });
+  }
+  /**
+   * Full protection loop in one wrapper: decide → run your provider call with
+   * the resolved model → report usage → acknowledge.
+   *
+   * const out = await mf.guard(
+   *   { customerId, feature: "ai_chat", provider: "openai", model: "gpt-4.1" },
+   *   async ({ model }) => {
+   *     const r = await openai.chat.completions.create({ model, messages });
+   *     return { result: r, usage: { inputTokens: r.usage.prompt_tokens, outputTokens: r.usage.completion_tokens } };
+   *   },
+   * );
+   * if (out.kind === "completed") use(out.result);
+   * else handle out.kind === "blocked" | "topup_required" with your own UX.
+   */
+  async guard(params, run) {
+    const decision = await this.decide(params);
+    if (decision.action === "block") {
+      if (decision.id) this.acknowledge(decision.id, "blocked_before_provider_call");
+      return { kind: "blocked", decision };
+    }
+    if (decision.action === "topup_required") {
+      if (decision.id) this.acknowledge(decision.id, "presented_topup");
+      return { kind: "topup_required", decision };
+    }
+    const modelToUse = decision.action === "downgrade" ? decision.model : params.model;
+    let outcome = "success";
+    try {
+      const out = await run({ model: modelToUse, provider: decision.provider, decision });
+      this.track({
+        customerId: params.customerId,
+        ...params.feature !== void 0 ? { feature: params.feature } : {},
+        provider: params.provider,
+        model: modelToUse,
+        requestedModel: params.model,
+        usage: out.usage,
+        ...out.costUsd !== void 0 ? { costUsd: out.costUsd } : {},
+        outcome: out.outcome ?? "success",
+        ...decision.id !== void 0 ? { decisionId: decision.id } : {}
+      });
+      if (decision.id) {
+        this.acknowledge(
+          decision.id,
+          decision.action === "downgrade" ? "used_downgrade_model" : "proceeded_as_requested"
+        );
+      }
+      return { kind: "completed", result: out.result, decision };
+    } catch (err) {
+      outcome = "provider_error";
+      this.track({
+        customerId: params.customerId,
+        ...params.feature !== void 0 ? { feature: params.feature } : {},
+        provider: params.provider,
+        model: modelToUse,
+        requestedModel: params.model,
+        usage: {},
+        outcome,
+        ...decision.id !== void 0 ? { decisionId: decision.id } : {}
+      });
+      if (decision.id) this.acknowledge(decision.id, "proceeded_as_requested");
+      throw err;
+    }
+  }
+  /** Wait for queued track/ack calls (use before process exit). */
+  async flush() {
+    await Promise.allSettled([...this.pending]);
+  }
+  background(fn) {
+    const p = fn().finally(() => this.pending.delete(p));
+    this.pending.add(p);
+  }
+  post(path, body, timeoutMs) {
+    return this.fetchImpl(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${this.apiKey}`,
+        "content-type": "application/json",
+        "user-agent": "marginfuse-node/0.1.0"
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+  }
+};
+function cryptoRandomId() {
+  return `evt_${uuidV4()}`;
+}
+function uuidV4() {
+  const webcrypto = globalThis.crypto;
+  if (typeof webcrypto?.randomUUID === "function") return webcrypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (typeof webcrypto?.getRandomValues === "function") {
+    webcrypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) bytes[i] = Math.floor(Math.random() * 256);
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = [];
+  for (const b of bytes) hex.push(b.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function safeText(res) {
+  try {
+    return (await res.text()).slice(0, 200);
+  } catch {
+    return "";
+  }
+}
+
+// src/openrouter.ts
+var int = (n) => typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+function creditsToUsd(cost) {
+  const s = cost.toFixed(9);
+  const trimmed = s.includes(".") ? s.replace(/0+$/, "").replace(/\.$/, "") : s;
+  return trimmed === "" || trimmed === "-0" ? "0" : trimmed;
+}
+function fromOpenRouter(usage) {
+  const cachedInputTokens = int(usage?.prompt_tokens_details?.cached_tokens);
+  const cacheCreationTokens = int(usage?.prompt_tokens_details?.cache_write_tokens);
+  const inputTokens = Math.max(0, int(usage?.prompt_tokens) - cachedInputTokens - cacheCreationTokens);
+  const out = {};
+  if (inputTokens > 0) out.inputTokens = inputTokens;
+  const outputTokens = int(usage?.completion_tokens);
+  if (outputTokens > 0) out.outputTokens = outputTokens;
+  if (cachedInputTokens > 0) out.cachedInputTokens = cachedInputTokens;
+  if (cacheCreationTokens > 0) out.cacheCreationTokens = cacheCreationTokens;
+  const cost = usage?.cost;
+  const hasCost = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
+  return { usage: out, ...hasCost ? { costUsd: creditsToUsd(cost) } : {} };
+}
+export {
+  MarginFuse,
+  fromOpenRouter
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "marginfuse",
+  "version": "0.2.0",
+  "description": "MarginFuse server-side SDK. AI profitability guardrails: connect revenue to per-request AI cost and stop loss-making requests before they run. Sends usage metadata only, never prompts or responses.",
+  "license": "MIT",
+  "author": "Pemira Labs",
+  "homepage": "https://marginfuse.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/marginfuse/marginfuse-node.git"
+  },
+  "bugs": {
+    "url": "https://github.com/marginfuse/marginfuse-node/issues"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "cost",
+    "margin",
+    "profitability",
+    "stripe",
+    "openai",
+    "anthropic",
+    "openrouter"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "conformance": "npm --prefix contract/harness run conformance node"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.0"
+  }
+}