manifest 7.1.0 → 7.2.1

package/CONTRACT.md

@@ -60,3 +60,17 @@ Each captured failure permits one retry. A retry response, including another fai
 HTTP status must be 200–599. Transport failures use a fixed message without exception prose. HTTP status zero is not a wire status. Transport failures and unattempted retries are inconclusive evidence; neither can verify or invalidate a patch. The server determines the verdict from the raw evidence, with the first accepted report winning.
 
 Reports are best effort, bounded, and observable through Node warnings with code `MNFST`. The SDK sends the failed retry's raw body so the app can distinguish recurrence from a newly revealed issue. It does not assert `succeeded` or `failed` itself.
+
+## Tracked requests
+
+Every call the SDK sees and does not send to `POST /v1/heal`, whatever its status (2xx, 3xx, 401, 402, 403, 429, 5xx, and a 4xx that is not sent for healing: after a redirect, while the project is disabled, or while all eight heal slots are busy), is recorded and sent in batches to `POST /v1/requests`:
+
+```json
+{"requests":[{"traceId":"a-uuid","method":"POST","url":"https://example.com/orders","statusCode":200,"responseTimeMs":84,"occurredAt":"2026-09-23T10:14:07.512Z"}]}
+```
+
+Metadata only. The URL carries scheme, host, port and path: no query string, userinfo or fragment. No headers and no request or response body are sent, and a response body is never read to record a call. A call sent to `/v1/heal` is not also tracked.
+
+Recording is an in-memory append and never delays or fails the caller's request. A batch is sent when 500 calls are queued or every five seconds, at most once per second, one send at a time, up to 500 calls per request, with a five-second deadline. At most 5,000 calls are buffered; newer calls are dropped past that. A network error, timeout, 429 or 5xx is retried once, then the batch is dropped; any other answer, including 404 from a server without the route, drops it. HTTP 403 with `{"error":"project_disabled"}` suspends sending for five minutes, as for healing. Methods are upper-cased; a record whose method exceeds 16 characters or whose URL exceeds 4,096 is not sent. Buffered calls are sent once when the event loop drains (`beforeExit`), for at most two seconds: a send still in flight then is aborted and the rest is dropped, so a script never hangs on an unreachable server. A process killed first can lose them.
+
+On a serverless platform (`VERCEL`, `AWS_LAMBDA_FUNCTION_NAME` or `K_SERVICE` set), the function freezes as soon as it responds, so neither the interval nor the exit flush would run. There, each call is sent as soon as it is recorded, still at most once per second and one send at a time, and the send and every outcome report are handed to the platform's `waitUntil` (Vercel's request context, or Next.js's own), so the function stays alive until they are delivered. Where no `waitUntil` exists, the send still starts during the invocation.

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-![Manifest SDK Architecture](./docs/github-sdk.png)
+![Manifest SDK Architecture](https://raw.githubusercontent.com/mnfst/manifest-node/main/docs/github-sdk.png)
 
 # Manifest for Node.js
 
-**Turn 🔴 4xx API errors into 🟢 2xx in real time.**
+**The API resilience layer for your Node.js apps.**
 
 [![CI](https://github.com/mnfst/manifest-node/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/mnfst/manifest-node/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/manifest?label=npm)](https://www.npmjs.com/package/manifest)
@@ -16,15 +16,17 @@
 
 ## What is Manifest
 
-Manifest is a self-healing layer that fixes and retries failed API requests on the fly.
+Manifest is the API resilience layer for your apps and agents. It works with every API they call: external services, your internal APIs and MCP tools.
 
-* 🎯 **Fix failures automatically** before they impact your users.
-* 🔔 **Get notified of root causes** so you can fix them permanently.
-* 🔌 **Works across your stack** with internal APIs, external services, and agent tools.
+* 🗺️ **See every API your app depends on**, and how reliable each one is.
+* 🎯 **Repair failed API requests on the fly**, so your app keeps working.
+* 🛠️ **Know what to fix in your code**, with a prompt for your coding agent.
 
 ## How it works
 
-![How Manifest heals a failed request: a 400 reaches Manifest, drops to a patch from the knowledge base or the healing agents, and is retried once, returning a 200 OK](./docs/sdk-flow-diagram.png)
+![How the SDK works: every call Manifest does not heal is recorded in the background as metadata (method, URL, status, timing, no body); a failure Manifest can heal is sent with its error, patched, and retried once, returning a 200 OK](./docs/sdk-flow-diagram.png)
+
+Every call your app makes is reported to Manifest as metadata only (method, URL without its query string, status and timing), in the background. A failure Manifest can heal is sent in full, so it can be repaired. [What is sent](docs/guide.md#data-sent-to-manifest).
 
 ## Prerequisites
 
@@ -44,47 +46,73 @@ The prompt adds the one-line install to your entry file and stops to let you pas
 
 ### Start with code
 
-```sh
-npm install manifest
-```
+1. Create a project in your [Manifest dashboard](https://dashboard.manifest.build) and copy its project key.
 
-```js
-import { manifest } from 'manifest';
+2. Install the SDK:
 
-manifest();  // Once, at startup.
-// Keep making your API calls as usual.
-```
+   ```sh
+   npm install manifest
+   ```
 
-TypeScript, ESM and CommonJS. Zero dependencies.
+3. Call `manifest()` from the first import of the file that starts your app, before any client is constructed:
 
-## Setup
+   ```js
+   import { manifest } from 'manifest';
 
-1. Create a project in your [Manifest dashboard](https://dashboard.manifest.build) and copy its project key.
-2. Set the key as an environment variable:
+   manifest();  // Once, at startup.
+   // Keep making your API calls as usual.
+   ```
 
-```sh
-export MNFST_KEY='your-project-key'
-```
+   TypeScript, ESM and CommonJS. Zero dependencies.
+
+4. Set your key in the environment of your app:
 
-Call `manifest()` from the first import of the file that starts your app, before any client is constructed. Some clients keep the `fetch` they saw when they were built, and a client built at import time runs before your call. Where that happens, or where the start command is not yours to change, preload the SDK instead:
+   ```sh
+   export MNFST_KEY='your-project-key'
+   ```
+
+5. Restart your app, then check the install from your project directory:
+
+   ```sh
+   npx manifest doctor
+   ```
+
+   It resolves the installed SDK version, masks and validates the key, checks that Manifest loads before your app, and prints the runtime coverage.
+
+Some clients keep the `fetch` they saw when they were built, and a client built at import time runs before your call. Where that happens, or where the start command is not yours to change, preload the SDK instead:
 
 ```sh
 node -r manifest/register app.js
 ```
 
-Self-healing is enabled by default in your project settings.
+### n8n
 
-Verify the install from your project directory:
+Manifest runs in a self-hosted n8n with Docker Compose, through this SDK. n8n Cloud cannot load it. Run the steps in this order:
 
-```sh
-npx manifest doctor
-```
+1. Install the SDK from the folder of your `docker-compose.yml`:
+
+   ```sh
+   docker compose exec n8n npm install --prefix /home/node/.n8n/manifest manifest
+   ```
+
+2. Add these two lines to the `environment` of your n8n service, and of every worker service in queue mode:
+
+   ```yaml
+   MNFST_KEY: your-project-key
+   NODE_OPTIONS: --require /home/node/.n8n/manifest/node_modules/manifest/dist/register.cjs
+   ```
+
+3. Restart n8n:
+
+   ```sh
+   docker compose up -d
+   ```
 
-It resolves the installed SDK version, masks and validates the key against the handshake endpoint, checks that Manifest loads before your app, and prints the runtime coverage.
+n8n does not start when `NODE_OPTIONS` names a file that is not installed yet, so keep this order.
 
 ## Try it
 
-Send a request that would normally fail. Manifest catches it, repairs it, and retries:
+Send a request that fails with a 4xx error, such as a value the API rejects:
 
 ```js
 import { manifest } from 'manifest';
@@ -98,13 +126,13 @@ manifest({
 const res = await fetch('https://api.example.com/orders', {
   method: 'POST',
   headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ limit: 500 }),  // Invalid? Manifest fixes it and retries.
+  body: JSON.stringify({ limit: 500 }),  // rejected by the API
 });
-console.log(res.status);  // See the 200 OK response.
+console.log(res.status);
 ```
 
-Check your [Manifest dashboard](https://dashboard.manifest.build) to see all repairs and insights.
+The failed request appears in your [Manifest dashboard](https://dashboard.manifest.build), grouped with others like it in an issue. Once Manifest has a patch for that error, the next request that fails the same way is repaired and retried: `onHeal` reports `patched` or `unverified` with the retry's status code, and your app receives the answer to the retry.
 
 ## More
 
-[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python) · [Website](https://manifest.build)
+[Documentation](https://docs.manifest.build) · [Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python) · [PHP SDK](https://github.com/mnfst/manifest-php) · [Website](https://manifest.build)

package/dist/bin.cjs

@@ -33,7 +33,7 @@ var import_node_path = __toESM(require("path"), 1);
 var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 
 // src/api.ts
-var VERSION = "7.1.0";
+var VERSION = "7.2.1";
 
 // src/cli.ts
 var DEFAULT_URL = "https://api.manifest.build";

package/dist/bin.js

@@ -2,7 +2,7 @@
 import {
   VERSION,
   isObject
-} from "./chunk-AR23I2QK.js";
+} from "./chunk-OXOZQLZ3.js";
 
 // src/cli.ts
 import { createRequire } from "module";

package/dist/{chunk-AR23I2QK.js → chunk-OXOZQLZ3.js}

@@ -37,6 +37,19 @@ function safeUrl(raw) {
   url.search = new URLSearchParams(pairs).toString();
   return url.toString();
 }
+function trackedUrl(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+    url.username = "";
+    url.password = "";
+    url.search = "";
+    url.hash = "";
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
 function safeHeaders(headers) {
   return Object.fromEntries([...headers].map(([key, value]) => [
     key,
@@ -280,8 +293,29 @@ async function captureResponse(original, limit = RESPONSE_LIMIT, timeoutMs = CAP
   return { response, body: errorBody(captured.bytes), truncated: !captured.complete || Buffer.byteLength(Buffer.from(captured.bytes).toString("utf8")) > limit, complete: captured.complete };
 }
 
+// src/serverless.ts
+var CONTEXTS = [/* @__PURE__ */ Symbol.for("@vercel/request-context"), /* @__PURE__ */ Symbol.for("@next/request-context")];
+function isServerless(env = process.env) {
+  return Boolean(env.VERCEL || env.AWS_LAMBDA_FUNCTION_NAME || env.K_SERVICE);
+}
+function keepAlive(promise) {
+  try {
+    const globals = globalThis;
+    for (const symbol of CONTEXTS) {
+      const waitUntil = globals[symbol]?.get?.()?.waitUntil;
+      if (typeof waitUntil === "function") {
+        waitUntil(promise.catch(() => {
+        }));
+        return;
+      }
+    }
+  } catch {
+  }
+}
+
 // src/api.ts
-var VERSION = "7.1.0";
+var VERSION = "7.2.1";
+var MAX_HEALS_IN_FLIGHT = 8;
 var warn = (message) => process.emitWarning(message, { code: "MNFST" });
 var HealApi = class {
   constructor(rawFetch, key, url, timeoutMs = 6e4, reportTimeoutMs = 5e3) {
@@ -303,6 +337,14 @@ var HealApi = class {
   enabled() {
     return performance.now() >= this.disabledUntil;
   }
+  /**
+   * Whether a heal call would be sent right now: the project is not disabled
+   * and a heal slot is free. A healable failure that cannot be sent is tracked
+   * instead, so it is never lost from both ledgers.
+   */
+  canHeal() {
+    return this.enabled() && this.inFlight < MAX_HEALS_IN_FLIGHT;
+  }
   headers() {
     return {
       authorization: `Bearer ${this.key}`,
@@ -311,7 +353,7 @@ var HealApi = class {
     };
   }
   async heal(capture, signal) {
-    if (!this.enabled() || this.inFlight >= 8) return null;
+    if (!this.canHeal()) return null;
     this.inFlight++;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -386,6 +428,41 @@ var HealApi = class {
     }).catch(() => {
     }).finally(() => clearTimeout(timer));
   }
+  /**
+   * Ship one batch of tracked calls to `POST /v1/requests`. Throws only when a
+   * retry could help (network error, timeout, 429, 5xx), so the buffer retries
+   * once; any other answer, including 404 from a backend that predates the
+   * route, drops the batch quietly. Uses `rawFetch`, so the send is never
+   * tracked or healed by our own patch.
+   */
+  async sendRequests(calls, signal) {
+    if (!this.enabled() || calls.length === 0) return;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.reportTimeoutMs);
+    try {
+      const response = await this.rawFetch(new URL("v1/requests", this.url), {
+        method: "POST",
+        headers: this.headers(),
+        body: JSON.stringify({ requests: calls }),
+        signal: signal ? AbortSignal.any([signal, controller.signal]) : controller.signal,
+        redirect: "error"
+      });
+      if (response.status === 403) {
+        const body = await response.json().catch(() => null);
+        if (isObject(body) && body.error === "project_disabled") {
+          this.disabledUntil = performance.now() + 3e5;
+        }
+        return;
+      }
+      void response.body?.cancel().catch(() => {
+      });
+      if (response.status === 429 || response.status >= 500) {
+        throw new Error(`tracked calls refused (${response.status})`);
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
   report(id, outcome) {
     if (!id) return;
     if (this.pending.size >= 64) {
@@ -395,6 +472,7 @@ var HealApi = class {
     const promise = this.send(id, outcome);
     this.pending.add(promise);
     void promise.then(() => this.pending.delete(promise));
+    keepAlive(promise);
   }
   async send(id, outcome) {
     const controller = new AbortController();
@@ -425,6 +503,7 @@ var HealApi = class {
 export {
   isObject,
   safeUrl,
+  trackedUrl,
   safeHeaders,
   travelingBody,
   mergeBody,
@@ -434,6 +513,8 @@ export {
   REQUEST_LIMIT,
   captureRequest,
   captureResponse,
+  isServerless,
+  keepAlive,
   VERSION,
   warn,
   HealApi

package/dist/{chunk-4OVLT3PO.js → chunk-RO6CIYR2.js}

@@ -5,14 +5,17 @@ import {
   captureRequest,
   captureResponse,
   isObject,
+  isServerless,
+  keepAlive,
   mergeBody,
   parseRequestBody,
   safeHeaders,
   safeUrl,
   serializeRequestBody,
+  trackedUrl,
   travelingBody,
   warn
-} from "./chunk-AR23I2QK.js";
+} from "./chunk-OXOZQLZ3.js";
 
 // src/http.ts
 import http from "http";
@@ -23,6 +26,121 @@ import { createBrotliDecompress, createUnzip } from "zlib";
 
 // src/runtime.ts
 import { randomUUID } from "crypto";
+
+// src/tracking.ts
+var MAX_BUFFER = 5e3;
+var MAX_BATCH = 500;
+var CallBuffer = class {
+  constructor(send, options = {}) {
+    this.send = send;
+    this.flushAt = options.flushAt ?? 500;
+    this.minGapMs = options.minGapMs ?? 1e3;
+    this.immediate = options.immediate ?? false;
+    this.keepAlive = options.keepAlive ?? keepAlive;
+    this.timer = setInterval(() => void this.kick(), options.intervalMs ?? 5e3);
+    this.timer.unref();
+  }
+  send;
+  queue = [];
+  inFlight = null;
+  lastSentAt = -Infinity;
+  /** Past this instant, nothing is retried or waited for, and a send in flight is aborted. */
+  deadline = Infinity;
+  controller = new AbortController();
+  timer;
+  flushAt;
+  minGapMs;
+  immediate;
+  keepAlive;
+  draining = null;
+  record(call) {
+    if (this.queue.length >= MAX_BUFFER) return;
+    this.queue.push(call);
+    if (this.immediate) this.drain();
+    else if (this.queue.length >= this.flushAt) void this.kick();
+  }
+  size() {
+    return this.queue.length;
+  }
+  /** Resolves when the send in flight, if any, has settled. */
+  async idle() {
+    await this.inFlight;
+  }
+  /**
+   * Send everything buffered now, one batch at a time through the same
+   * in-flight guard as the timer. With `deadlineMs` (the exit path), it gives
+   * up at the deadline: the send in flight is aborted, nothing is retried, and
+   * what is left is dropped, so a script never hangs on an unreachable server.
+   */
+  async flush(deadlineMs = Infinity) {
+    this.deadline = performance.now() + deadlineMs;
+    const abortAt = Number.isFinite(deadlineMs) ? setTimeout(() => this.controller.abort(), deadlineMs) : null;
+    try {
+      while ((this.queue.length > 0 || this.inFlight) && performance.now() < this.deadline) {
+        await (this.inFlight ?? this.start());
+      }
+    } finally {
+      if (abortAt) clearTimeout(abortAt);
+      if (this.controller.signal.aborted) this.controller = new AbortController();
+      this.deadline = Infinity;
+    }
+  }
+  stop() {
+    clearInterval(this.timer);
+  }
+  /**
+   * Serverless: the function may freeze as soon as its response is sent, before
+   * any timer fires. So send now, through `flush()` (same gap, same single send
+   * in flight), and let the platform wait for it. Calls recorded meanwhile ride
+   * the same drain; one that lands as it settles starts the next.
+   */
+  drain() {
+    if (this.draining) return;
+    const run = this.flush().finally(() => {
+      this.draining = null;
+      if (this.queue.length > 0) this.drain();
+    });
+    this.draining = run;
+    this.keepAlive(run);
+  }
+  kick() {
+    if (this.inFlight || this.queue.length === 0) return;
+    if (performance.now() - this.lastSentAt < this.minGapMs) return;
+    void this.start();
+  }
+  start() {
+    this.inFlight = this.sendOne().finally(() => {
+      this.inFlight = null;
+    });
+    return this.inFlight;
+  }
+  async sendOne() {
+    const batch = this.queue.splice(0, MAX_BATCH);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      if (attempt > 0 && performance.now() >= this.deadline) return;
+      await this.waitForGap();
+      this.lastSentAt = performance.now();
+      try {
+        await this.send(batch, this.controller.signal);
+        return;
+      } catch {
+      }
+      if (this.controller.signal.aborted) {
+        this.controller = new AbortController();
+        return;
+      }
+    }
+  }
+  // Referenced on purpose: this wait only happens while a send or an exit
+  // flush is under way, and an unref'd wait would let the process exit with
+  // the batch unsent. It never outlasts the flush deadline.
+  async waitForGap() {
+    const wait = Math.min(this.lastSentAt + this.minGapMs, this.deadline) - performance.now();
+    if (wait > 0) await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+};
+
+// src/runtime.ts
 var forbidden = /* @__PURE__ */ new Set([401, 402, 403, 429]);
 var bodyless = ["GET", "HEAD", "DELETE", "OPTIONS"];
 var neverBodied = (method) => method === "GET" || method === "HEAD";
@@ -32,20 +150,50 @@ var Runtime = class {
     this.options = options;
     this.original = original;
     this.api = api ?? new HealApi(original, options.key, options.url);
+    this.tracker = new CallBuffer(
+      (batch, signal) => this.api.sendRequests(batch, signal),
+      { immediate: isServerless() }
+    );
   }
   options;
   original;
   api;
+  /** Calls that did not go to `/v1/heal`, any status, on their way to `/v1/requests`. */
+  tracker;
+  /**
+   * Record a call that is not being healed. An in-memory append: never awaited,
+   * never throws, reads nothing of the response.
+   */
+  track(method, url, statusCode, startedAt, responseTimeMs) {
+    try {
+      const reported = trackedUrl(url());
+      const verb = method.toUpperCase();
+      if (!reported || reported.length > 4096 || !verb || verb.length > 16 || statusCode < 100 || statusCode > 599) return;
+      this.tracker.record({
+        traceId: randomUUID(),
+        method: verb,
+        url: reported,
+        statusCode,
+        responseTimeMs: Math.round(responseTimeMs),
+        occurredAt: new Date(startedAt).toISOString()
+      });
+    } catch {
+    }
+  }
   fetch = async (input, init) => {
     const request = new Request(input, init);
     const extras = { ...init };
     delete extras.body;
     delete extras.headers;
     const bodyPromise = captureRequest(request).catch(() => ({ body: null, complete: false }));
+    const startedAt = Date.now();
     const started = performance.now();
     const response = await this.original(request, extras);
     const responseTimeMs = performance.now() - started;
-    if (!eligible(response.status) || response.redirected || !this.api.enabled()) return response;
+    if (!eligible(response.status) || response.redirected || !this.api.canHeal()) {
+      this.track(request.method, () => request.url, response.status, startedAt, responseTimeMs);
+      return response;
+    }
     return this.handleResponse(request, response, await bodyPromise, responseTimeMs, extras);
   };
   async handleResponse(request, response, body, responseTimeMs, extras = {}) {
@@ -175,6 +323,7 @@ function wrapRequest(original, protocol, runtime) {
   return ((...received) => {
     const args = [...received];
     const callback = typeof args.at(-1) === "function" ? args.pop() : void 0;
+    const startedAt = Date.now();
     const started = performance.now();
     const request = original(...args);
     const capture = captureBody(request);
@@ -183,7 +332,14 @@ function wrapRequest(original, protocol, runtime) {
     request.emit = ((event, ...values) => {
       if (event !== "response") return emit(event, ...values);
       const response = values[0];
-      if (!eligible(response.statusCode ?? 0) || !runtime.api.enabled()) {
+      if (!eligible(response.statusCode ?? 0) || !runtime.api.canHeal()) {
+        runtime.track(
+          request.method,
+          () => requestUrl(request, protocol).toString(),
+          response.statusCode ?? 0,
+          startedAt,
+          performance.now() - started
+        );
         return emit(event, ...values);
       }
       void handleResponse(runtime, request, response, protocol, capture.body(), signal, started).then((healed) => emit("response", healed)).catch((error) => {
@@ -202,6 +358,10 @@ async function handleResponse(runtime, clientRequest, incoming, protocol, body,
   const healed = await runtime.handleResponse(request, response, body, performance.now() - started);
   return incomingResponse(healed, clientRequest);
 }
+function requestUrl(request, protocol) {
+  const authority = String(request.getHeader("host") ?? request.host);
+  return new URL(request.path, `${protocol}//${authority}`);
+}
 function webRequest(request, protocol, captured, signal) {
   const headers = new Headers();
   for (const name of request.getHeaderNames()) {
@@ -210,8 +370,7 @@ function webRequest(request, protocol, captured, signal) {
       if (item !== void 0) headers.append(name, String(item));
     }
   }
-  const authority = String(request.getHeader("host") ?? request.host);
-  const url = new URL(request.path, `${protocol}//${authority}`);
+  const url = requestUrl(request, protocol);
   const method = request.method;
   return new Request(url, {
     method,
@@ -320,6 +479,7 @@ function cancellation(request, external) {
 
 // src/index.ts
 var STATE = /* @__PURE__ */ Symbol.for("mnfst.node.runtime.v1");
+var EXIT_FLUSH_MS = 2e3;
 var globals = globalThis;
 function manifest(options = {}) {
   const key = options.key || process.env.MNFST_KEY;
@@ -351,6 +511,9 @@ function manifest(options = {}) {
   installHttp(runtime);
   globals[STATE] = runtime;
   runtime.api.hello(`node-${process.versions.node}`);
+  process.once("beforeExit", () => {
+    if (runtime.tracker.size() > 0) void runtime.tracker.flush(EXIT_FLUSH_MS);
+  });
 }
 
 export {