manifest 7.0.0 → 7.1.0

package/CONTRACT.md

@@ -2,6 +2,18 @@
 
 The SDK talks to the configured Manifest API using `Authorization: Bearer <project key>` and `User-Agent: mnfst-node/<version>`.
 
+## Handshake
+
+`POST /v1/hello` announces an install — `{"runtime":"node-22.0.0"}` — authorized with the same bearer key. A `200` confirms the key; `401`, or a `403` whose body is not `{"error":"project_disabled"}`, rejects it. The `200` body may carry project and activity context, all optional:
+
+```json
+{"project": {"name": "Find Concierge"}, "requests": 12}
+```
+
+`manifest doctor` reads `project` (also accepting `projectName`, `project_name` or a bare `name`) and `requests` (also accepting `requestCount`, `requestsCount`, `requests_count`, `request_count`, or an object with `total`) to print the project and to warn when no request has arrived yet. Missing fields simply hide those lines.
+
+A capture may carry a top-level `"synthetic": true`, which `manifest doctor --send-test` sets. Synthetic captures exist only to prove the pipeline end to end and must be excluded from statistics.
+
 ## Capture
 
 `POST /v1/heal` receives:
@@ -21,7 +33,7 @@ A successful heal response may contain `status: patched|unverified`, `healAttemp
 
 ## Apply
 
-A healed URL replaces the URL only within the original origin. Headers set or replace case-insensitively; null removes a header. Content length is recalculated. Objects merge using the server's healed body as the authoritative copy of fields sent to the server; withheld local credential fields are restored. Non-object JSON replaces the body. Form-urlencoded retries use the original encoding and are re-encoded from the parsed structure, so repeated keys return as indexed keys; a non-object healed body is not retried for them. Incomplete or malformed request captures and incomplete error captures are not retried.
+A healed URL replaces the URL only within the original origin. Headers set or replace case-insensitively; null removes a header. Content length is recalculated. Objects merge using the server's healed body as the authoritative copy of fields sent to the server; withheld local credential fields are restored. Non-object JSON replaces the body. Form-urlencoded retries use the original encoding and are re-encoded from the parsed structure, so repeated keys return as indexed keys; a non-object healed body is not retried for them. A healed body that merges to nothing is sent as no body at all: GET, HEAD, DELETE and OPTIONS retry bodyless, and any other method is not retried. GET and HEAD never carry a body on a retry. Incomplete or malformed request captures and incomplete error captures are not retried.
 
 Each captured failure permits one retry. A retry response, including another failure, is returned to the caller. A transport failure returns the original response. Successful response streams are not eagerly consumed.
 

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MNFST, Inc
+
+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

@@ -1,10 +1,48 @@
+<div align="center">
+
+![Manifest SDK Architecture](./docs/github-sdk.png)
+
 # Manifest for Node.js
 
+**Turn 🔴 4xx API errors into 🟢 2xx in real time.**
+
 [![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)
 [![npm downloads](https://img.shields.io/npm/dm/manifest?label=npm%20downloads)](https://www.npmjs.com/package/manifest)
 
-**An API rejects your request. Manifest fixes it and retries. You do nothing.**
+</div>
+
+---
+
+## What is Manifest
+
+Manifest is a self-healing layer that fixes and retries failed API requests on the fly.
+
+* 🎯 **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.
+
+## 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)
+
+## Prerequisites
+
+- <a href="https://nodejs.org/en/download/" target="_blank">Node.js 22</a> or higher
+
+## Get started
+
+### Start with your agent
+
+```
+"Install Manifest in this app: https://dashboard.manifest.build/prompt-node.md"
+```
+
+[Read the prompt →](https://dashboard.manifest.build/prompt-node.md)
+
+The prompt adds the one-line install to your entry file and stops to let you paste your key.
+
+### Start with code
 
 ```sh
 npm install manifest
@@ -13,31 +51,40 @@ npm install manifest
 ```js
 import { manifest } from 'manifest';
 
-manifest(); // once, at startup
+manifest();  // Once, at startup.
 // Keep making your API calls as usual.
 ```
 
-Works with built-in `fetch`, `node:http`, `node:https` and Axios, for JSON and form-urlencoded bodies. Node.js 22+. TypeScript, ESM and CommonJS. Zero dependencies.
-
-![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/healing-diagram.svg)
+TypeScript, ESM and CommonJS. Zero dependencies.
 
 ## Setup
 
-1. Create a project in your Manifest dashboard and copy its project key.
-2. Turn on **Autofix** in **Project Settings**.
-3. Set the key:
+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:
 
 ```sh
 export MNFST_KEY='your-project-key'
 ```
 
-Call `manifest()` before any library grabs its own reference to `fetch` or `node:http`. To install before any of your modules run, preload it instead:
+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
+node -r manifest/register app.js
+```
+
+Self-healing is enabled by default in your project settings.
+
+Verify the install from your project directory:
 
 ```sh
-node --import manifest/register app.js
+npx manifest doctor
 ```
 
-## See it work
+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.
+
+## Try it
+
+Send a request that would normally fail. Manifest catches it, repairs it, and retries:
 
 ```js
 import { manifest } from 'manifest';
@@ -51,17 +98,13 @@ manifest({
 const res = await fetch('https://api.example.com/orders', {
   method: 'POST',
   headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ limit: 500 }), // rejected? Manifest retries with a valid limit
+  body: JSON.stringify({ limit: 500 }),  // Invalid? Manifest fixes it and retries.
 });
+console.log(res.status);  // See the 200 OK response.
 ```
 
-## Good to know
-
-- **Retries repeat side effects.** Use idempotency keys on non-idempotent calls.
-- **A heal adds up to 60 s** to a failed request. Successful requests are untouched.
-- **Not intercepted:** browsers, HTTP/2, and directly imported `undici`.
-- **Privacy.** Failed URLs, headers, JSON or form-urlencoded bodies, and error responses are sent to Manifest. Known credentials are masked, but nested secrets and business data are not. Enable it only for traffic you allow Manifest to process.
+Check your [Manifest dashboard](https://dashboard.manifest.build) to see all repairs and insights.
 
 ## More
 
-[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python)
+[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python) · [Website](https://manifest.build)

package/dist/bin.cjs

@@ -0,0 +1,410 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_node_module = require("module");
+var import_node_fs = require("fs");
+var import_promises = require("fs/promises");
+var import_node_path = __toESM(require("path"), 1);
+
+// src/wire.ts
+var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+// src/api.ts
+var VERSION = "7.1.0";
+
+// src/cli.ts
+var DEFAULT_URL = "https://api.manifest.build";
+var REQUEST_TIMEOUT_MS = 1e4;
+var symbols = {
+  ok: "\u2705",
+  fail: "\u274C",
+  warn: "\u26A0\uFE0F",
+  skip: "\u2796"
+};
+function maskKey(key) {
+  const tail = key.slice(-4);
+  if (key.length <= tail.length + 2) return "\u2026";
+  const prefix = /^(?:mnfst(?:_[a-z]+)*_)/i.exec(key)?.[0] ?? key.slice(0, 4);
+  const head = prefix.length + tail.length < key.length ? prefix : "";
+  return `${head}\u2026${tail}`;
+}
+function normalizeBase(raw) {
+  try {
+    const url = new URL(raw);
+    if (!["https:", "http:"].includes(url.protocol) || url.username || url.password || url.search || url.hash)
+      return null;
+    if (!url.pathname.endsWith("/")) url.pathname += "/";
+    return url.toString();
+  } catch {
+    return null;
+  }
+}
+async function readJson(response) {
+  try {
+    const text = await response.text();
+    return text.length > 1e6 ? null : JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function projectName(body) {
+  if (!isObject(body)) return void 0;
+  const candidate = body.project ?? body.projectName ?? body.project_name ?? body.name;
+  if (typeof candidate === "string" && candidate.trim())
+    return candidate.trim();
+  if (isObject(candidate) && typeof candidate.name === "string" && candidate.name.trim())
+    return candidate.name.trim();
+  return void 0;
+}
+function requestCount(body) {
+  if (!isObject(body)) return void 0;
+  const candidate = body.requests ?? body.requestCount ?? body.requestsCount ?? body.requests_count ?? body.request_count;
+  if (typeof candidate === "number") return candidate;
+  if (isObject(candidate) && typeof candidate.total === "number")
+    return candidate.total;
+  return void 0;
+}
+function headers(key) {
+  return {
+    authorization: `Bearer ${key}`,
+    "content-type": "application/json",
+    "user-agent": `mnfst-node/${VERSION}`
+  };
+}
+async function probe(url, key, doFetch) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const response = await doFetch(new URL("v1/hello", url), {
+      method: "POST",
+      headers: headers(key),
+      // `probe` marks this a key check, not a boot: the server answers but
+      // records no install. Without it, running doctor from a laptop makes
+      // the dashboard claim the app is connected — while doctor is printing
+      // "manifest is not installed in this project" two lines above.
+      body: JSON.stringify({ probe: true }),
+      signal: controller.signal,
+      redirect: "error"
+    });
+    const body = await readJson(response);
+    if (response.status === 200)
+      return {
+        kind: "valid",
+        project: projectName(body),
+        requests: requestCount(body)
+      };
+    if (response.status === 401)
+      return { kind: "invalid", detail: "the key was rejected (401)" };
+    if (response.status === 403)
+      return {
+        kind: "invalid",
+        detail: isObject(body) && body.error === "project_disabled" ? "the key is valid but the project is disabled (403)" : "the key was rejected (403)"
+      };
+    return {
+      kind: "error",
+      detail: `unexpected response (${response.status})`
+    };
+  } catch (error) {
+    const timedOut = error instanceof Error && error.name === "AbortError";
+    return {
+      kind: "error",
+      detail: `${timedOut ? "timed out" : "could not be reached"} at ${url}`
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function installedVersion(cwd) {
+  try {
+    const entry = (0, import_node_module.createRequire)(import_node_path.default.join(cwd, "package.json")).resolve(
+      "manifest"
+    );
+    let dir = import_node_path.default.dirname(entry);
+    while (true) {
+      const manifest = import_node_path.default.join(dir, "package.json");
+      if ((0, import_node_fs.existsSync)(manifest)) {
+        const pkg = JSON.parse((0, import_node_fs.readFileSync)(manifest, "utf8"));
+        if (pkg.name === "manifest" && pkg.version) return pkg.version;
+      }
+      const parent = import_node_path.default.dirname(dir);
+      if (parent === dir) return void 0;
+      dir = parent;
+    }
+  } catch {
+    return void 0;
+  }
+}
+async function nearestPackage(cwd) {
+  let dir = import_node_path.default.resolve(cwd);
+  while (true) {
+    const file = import_node_path.default.join(dir, "package.json");
+    if ((0, import_node_fs.existsSync)(file)) {
+      try {
+        return {
+          dir,
+          pkg: JSON.parse(await (0, import_promises.readFile)(file, "utf8"))
+        };
+      } catch {
+        return void 0;
+      }
+    }
+    const parent = import_node_path.default.dirname(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
+var instrumentationFiles = [
+  "instrumentation.ts",
+  "instrumentation.js",
+  "instrumentation.mjs",
+  "src/instrumentation.ts",
+  "src/instrumentation.js",
+  "src/instrumentation.mjs"
+];
+async function loadCheck(cwd) {
+  const label = "Loads before your app";
+  const found = await nearestPackage(cwd);
+  if (!found)
+    return {
+      label,
+      status: "warn",
+      detail: "no package.json found; cannot tell how Manifest loads"
+    };
+  const scripts = isObject(found.pkg.scripts) ? found.pkg.scripts : {};
+  const values = Object.values(scripts).filter(
+    (value) => typeof value === "string"
+  );
+  if (values.some((value) => value.includes("manifest/register")))
+    return {
+      label,
+      status: "ok",
+      detail: "a script preloads manifest/register"
+    };
+  const dependencies = {
+    ...isObject(found.pkg.dependencies) ? found.pkg.dependencies : {},
+    ...isObject(found.pkg.devDependencies) ? found.pkg.devDependencies : {}
+  };
+  if ("next" in dependencies) {
+    for (const relative of instrumentationFiles) {
+      const file = import_node_path.default.join(found.dir, relative);
+      if (!(0, import_node_fs.existsSync)(file)) continue;
+      if (/manifest/.test(await (0, import_promises.readFile)(file, "utf8")))
+        return {
+          label,
+          status: "ok",
+          detail: `${relative} installs Manifest before the app runs`
+        };
+    }
+    return {
+      label,
+      status: "fail",
+      detail: 'package.json "start" relies on Next.js with no NODE_OPTIONS and no instrumentation file \u2014 Manifest will not load'
+    };
+  }
+  const start = scripts.start;
+  if (typeof start === "string" && start.trim())
+    return {
+      label,
+      status: "warn",
+      detail: "cannot tell from here whether manifest() runs; check Requests received"
+    };
+  return {
+    label,
+    status: "warn",
+    detail: "no start script found; cannot confirm Manifest loads before your app"
+  };
+}
+function sdkCheck(cwd, injected) {
+  const label = "SDK installed";
+  const version = injected ?? installedVersion(cwd);
+  if (!version)
+    return {
+      label,
+      status: "fail",
+      detail: "manifest is not installed in this project"
+    };
+  return { label, status: "ok", detail: `manifest ${version}` };
+}
+async function runDoctor(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const env = options.env ?? process.env;
+  const doFetch = options.fetch ?? globalThis.fetch;
+  const checks = [sdkCheck(cwd, options.sdkVersion)];
+  const rawUrl = options.url ?? env.MNFST_URL ?? DEFAULT_URL;
+  const url = normalizeBase(rawUrl);
+  const key = env.MNFST_KEY;
+  if (!key) {
+    checks.push({
+      label: "MNFST_KEY set",
+      status: "fail",
+      detail: "MNFST_KEY is not set"
+    });
+  } else {
+    checks.push({ label: "MNFST_KEY set", status: "ok", detail: maskKey(key) });
+  }
+  let requests;
+  if (!url) {
+    checks.push({
+      label: "Key valid",
+      status: "fail",
+      detail: `invalid Manifest URL: ${rawUrl}`
+    });
+  } else if (!key) {
+    checks.push({ label: "Key valid", status: "skip", detail: "" });
+  } else {
+    const result = await probe(url, key, doFetch);
+    if (result.kind === "valid") {
+      requests = result.requests;
+      checks.push({
+        label: "Key valid",
+        status: "ok",
+        detail: result.project ? `project "${result.project}"` : "the server accepted the key"
+      });
+    } else {
+      checks.push({
+        label: "Key valid",
+        status: "fail",
+        detail: result.detail
+      });
+    }
+  }
+  checks.push(await loadCheck(cwd));
+  if (requests !== void 0) {
+    checks.push({
+      label: "Requests received",
+      status: requests > 0 ? "ok" : "warn",
+      detail: requests > 0 ? `${requests} request${requests === 1 ? "" : "s"} received` : "no requests received yet"
+    });
+  }
+  return { checks, ok: checks.every((check) => check.status !== "fail") };
+}
+function wrap(text, width) {
+  if (!text) return [""];
+  const lines = [];
+  let line = "";
+  for (const word of text.split(" ")) {
+    if (!line) line = word;
+    else if (line.length + 1 + word.length <= width) line += ` ${word}`;
+    else {
+      lines.push(line);
+      line = word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+function render(report) {
+  const width = Math.max(
+    20,
+    ...report.checks.map((check) => check.label.length)
+  );
+  const lines = [];
+  for (const check of report.checks) {
+    const left = `  ${symbols[check.status]} ${check.label.padEnd(width)}`;
+    const detail = wrap(check.detail, Math.max(24, 96 - left.length - 2));
+    lines.push(`${left}  ${detail[0] ?? ""}`.trimEnd());
+    for (const extra of detail.slice(1))
+      lines.push(`${" ".repeat(left.length + 2)}${extra}`);
+  }
+  lines.push("");
+  lines.push("Runtime coverage");
+  lines.push(
+    "  Node.js runtime   fetch, http.request, https.request, http.get are patched"
+  );
+  lines.push(
+    "  Edge runtime      not supported \u2014 middleware.ts and Edge route handlers are never covered"
+  );
+  return `${lines.join("\n")}
+`;
+}
+function parseArgs(argv) {
+  const args = { help: false, version: false };
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help") args.help = true;
+    else if (arg === "-v" || arg === "--version") args.version = true;
+    else if (arg === "--url") {
+      const value = argv[++index];
+      if (!value) throw new Error("--url needs a value");
+      args.url = value;
+    } else if (arg.startsWith("--url=")) args.url = arg.slice("--url=".length);
+    else if (arg.startsWith("-")) throw new Error(`unknown option: ${arg}`);
+    else if (args.command === void 0) args.command = arg;
+    else throw new Error(`unexpected argument: ${arg}`);
+  }
+  return args;
+}
+var HELP = `Usage: manifest <command> [options]
+
+Commands
+  doctor              Check that this project is wired up to Manifest
+
+Options
+  --url <url>         Manifest API base URL (default: $MNFST_URL)
+  -h, --help          Show this help
+  -v, --version       Print the SDK version
+
+Examples
+  npx manifest doctor
+  npx manifest doctor --url=https://api.manifest.build
+`;
+async function main(argv = process.argv.slice(2)) {
+  let args;
+  try {
+    args = parseArgs(argv);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    console.error(HELP);
+    return 1;
+  }
+  if (args.version) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (args.help || !args.command) {
+    console.log(HELP);
+    return 0;
+  }
+  if (args.command !== "doctor") {
+    console.error(`Unknown command: ${args.command}`);
+    console.error(HELP);
+    return 1;
+  }
+  const report = await runDoctor({ url: args.url });
+  process.stdout.write(render(report));
+  return report.ok ? 0 : 1;
+}
+
+// src/bin.ts
+main().then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+);

package/dist/bin.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/bin.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node