marginfuse 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -4,6 +4,23 @@ 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.2]
+
+### Fixed
+
+- The user-agent reported `marginfuse-node/0.1.0` on every request, two
+  releases after 0.1.0. The version was a literal that nothing compared to
+  `package.json`, so support questions about which version sent a request got
+  a wrong answer. It is now derived from a single constant and a test asserts
+  the two agree.
+
+### Changed
+
+- Public documentation comments no longer cite internal specification section
+  numbers. They shipped in `dist/index.d.ts`, so hovering `decide()` in an
+  editor showed a reference to a document nobody outside can read. The
+  comments now say what the methods do.
+
 ## [0.2.1]
 
 No code changes. This is the first release published by the release workflow

package/dist/index.cjs

@@ -20,11 +20,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CONTRACT_VERSION: () => CONTRACT_VERSION,
   MarginFuse: () => MarginFuse,
   fromOpenRouter: () => fromOpenRouter
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/version.ts
+var VERSION = "0.2.2";
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.marginfuse.com";
 var DEFAULT_TIMEOUT_MS = 1500;
@@ -46,8 +50,9 @@ var MarginFuse = class {
     this.fetchImpl = options.fetch ?? fetch;
   }
   /**
-   * Pre-request policy check (protection-ready integrations, §13.2).
-   * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+   * Asks whether the next provider call should run.
+   * Always resolves. On any failure resolves {action:"allow", degraded:true},
+   * because MarginFuse being unreachable must never become your outage.
    */
   async decide(params) {
     const failOpen = (reason) => ({
@@ -79,8 +84,9 @@ var MarginFuse = class {
     }
   }
   /**
-   * Report actual usage after the provider call (monitor-only §13.1 and
-   * post-request reconciliation §25.3). Fire-and-forget with retries.
+   * Reports what a provider call actually consumed, after it happened.
+   * Returns immediately and retries in the background. Call flush() before
+   * the process exits, or the last events go with it.
    */
   track(params) {
     const event = {
@@ -113,7 +119,7 @@ var MarginFuse = class {
     this.track(params);
     await this.flush();
   }
-  /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+  /** Tells MarginFuse what your application did with a decision. */
   acknowledge(decisionId, acknowledgment) {
     this.background(async () => {
       try {
@@ -200,7 +206,7 @@ var MarginFuse = class {
       headers: {
         authorization: `Bearer ${this.apiKey}`,
         "content-type": "application/json",
-        "user-agent": "marginfuse-node/0.1.0"
+        "user-agent": `marginfuse-node/${VERSION}`
       },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(timeoutMs)
@@ -257,8 +263,12 @@ function fromOpenRouter(usage) {
   const hasCost = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
   return { usage: out, ...hasCost ? { costUsd: creditsToUsd(cost) } : {} };
 }
+
+// src/index.ts
+var CONTRACT_VERSION = 1;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CONTRACT_VERSION,
   MarginFuse,
   fromOpenRouter
 });

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 /**
  * 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).
+ * carry.
  */
 interface Usage {
     inputTokens?: number;
@@ -69,7 +69,7 @@ interface MarginFuseOptions {
 /**
  * MarginFuse Node SDK.
  *
- * Reliability contract (spec §5.5, §29.3): this SDK NEVER throws into
+ * Reliability contract: 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.
@@ -84,18 +84,20 @@ declare class MarginFuse {
     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}.
+     * Asks whether the next provider call should run.
+     * Always resolves. On any failure resolves {action:"allow", degraded:true},
+     * because MarginFuse being unreachable must never become your outage.
      */
     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.
+     * Reports what a provider call actually consumed, after it happened.
+     * Returns immediately and retries in the background. Call flush() before
+     * the process exits, or the last events go with it.
      */
     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). */
+    /** Tells MarginFuse what your application did with a decision. */
     acknowledge(decisionId: string, acknowledgment: Acknowledgment): void;
     /**
      * Full protection loop in one wrapper: decide → run your provider call with
@@ -188,4 +190,17 @@ declare function fromOpenRouter(usage: OpenRouterUsage | null | undefined): Pick
     costUsd?: string;
 };
 
-export { type Acknowledgment, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };
+/**
+ * The version of the shared SDK contract this build was verified against.
+ *
+ * Package versions differ per language, because each tracks its own breaking
+ * changes: a rename in Python must not tell Node users something broke. What
+ * makes the SDKs interchangeable is this, not the package version. Two SDKs
+ * reporting the same contract version have passed the same scenarios and the
+ * same vectors.
+ *
+ * See github.com/marginfuse/sdk-contract.
+ */
+declare const CONTRACT_VERSION = 1;
+
+export { type Acknowledgment, CONTRACT_VERSION, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * 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).
+ * carry.
  */
 interface Usage {
     inputTokens?: number;
@@ -69,7 +69,7 @@ interface MarginFuseOptions {
 /**
  * MarginFuse Node SDK.
  *
- * Reliability contract (spec §5.5, §29.3): this SDK NEVER throws into
+ * Reliability contract: 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.
@@ -84,18 +84,20 @@ declare class MarginFuse {
     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}.
+     * Asks whether the next provider call should run.
+     * Always resolves. On any failure resolves {action:"allow", degraded:true},
+     * because MarginFuse being unreachable must never become your outage.
      */
     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.
+     * Reports what a provider call actually consumed, after it happened.
+     * Returns immediately and retries in the background. Call flush() before
+     * the process exits, or the last events go with it.
      */
     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). */
+    /** Tells MarginFuse what your application did with a decision. */
     acknowledge(decisionId: string, acknowledgment: Acknowledgment): void;
     /**
      * Full protection loop in one wrapper: decide → run your provider call with
@@ -188,4 +190,17 @@ declare function fromOpenRouter(usage: OpenRouterUsage | null | undefined): Pick
     costUsd?: string;
 };
 
-export { type Acknowledgment, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };
+/**
+ * The version of the shared SDK contract this build was verified against.
+ *
+ * Package versions differ per language, because each tracks its own breaking
+ * changes: a rename in Python must not tell Node users something broke. What
+ * makes the SDKs interchangeable is this, not the package version. Two SDKs
+ * reporting the same contract version have passed the same scenarios and the
+ * same vectors.
+ *
+ * See github.com/marginfuse/sdk-contract.
+ */
+declare const CONTRACT_VERSION = 1;
+
+export { type Acknowledgment, CONTRACT_VERSION, type DecideParams, type Decision, type DecisionAction, MarginFuse, type MarginFuseOptions, type OpenRouterUsage, type Outcome, type TrackParams, type Usage, fromOpenRouter };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/version.ts
+var VERSION = "0.2.2";
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.marginfuse.com";
 var DEFAULT_TIMEOUT_MS = 1500;
@@ -19,8 +22,9 @@ var MarginFuse = class {
     this.fetchImpl = options.fetch ?? fetch;
   }
   /**
-   * Pre-request policy check (protection-ready integrations, §13.2).
-   * Always resolves. On any failure resolves {action:"allow", degraded:true}.
+   * Asks whether the next provider call should run.
+   * Always resolves. On any failure resolves {action:"allow", degraded:true},
+   * because MarginFuse being unreachable must never become your outage.
    */
   async decide(params) {
     const failOpen = (reason) => ({
@@ -52,8 +56,9 @@ var MarginFuse = class {
     }
   }
   /**
-   * Report actual usage after the provider call (monitor-only §13.1 and
-   * post-request reconciliation §25.3). Fire-and-forget with retries.
+   * Reports what a provider call actually consumed, after it happened.
+   * Returns immediately and retries in the background. Call flush() before
+   * the process exits, or the last events go with it.
    */
   track(params) {
     const event = {
@@ -86,7 +91,7 @@ var MarginFuse = class {
     this.track(params);
     await this.flush();
   }
-  /** Tell MarginFuse what your app actually did with a decision (§25.2). */
+  /** Tells MarginFuse what your application did with a decision. */
   acknowledge(decisionId, acknowledgment) {
     this.background(async () => {
       try {
@@ -173,7 +178,7 @@ var MarginFuse = class {
       headers: {
         authorization: `Bearer ${this.apiKey}`,
         "content-type": "application/json",
-        "user-agent": "marginfuse-node/0.1.0"
+        "user-agent": `marginfuse-node/${VERSION}`
       },
       body: JSON.stringify(body),
       signal: AbortSignal.timeout(timeoutMs)
@@ -230,7 +235,11 @@ function fromOpenRouter(usage) {
   const hasCost = typeof cost === "number" && Number.isFinite(cost) && cost >= 0;
   return { usage: out, ...hasCost ? { costUsd: creditsToUsd(cost) } : {} };
 }
+
+// src/index.ts
+var CONTRACT_VERSION = 1;
 export {
+  CONTRACT_VERSION,
   MarginFuse,
   fromOpenRouter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "marginfuse",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "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",