manifest 6.0.0 → 7.0.0

package/CONTRACT.md

@@ -15,13 +15,13 @@ The SDK talks to the configured Manifest API using `Authorization: Bearer <proje
 }
 ```
 
-Credential filtering and body limits are described in the README. Capture gates live in `runtime.ts`; the server owns repair policy.
+Any 4xx response is captured except 401, 402, 403 and 429; those and every 5xx pass through untouched, because auth, billing, rate limiting and server faults are not repaired by editing the request. JSON bodies and `application/x-www-form-urlencoded` bodies are sent as structured JSON values. Credential filtering and body limits are described in the README. Capture gates live in `runtime.ts`; the server owns repair policy.
 
 A successful heal response may contain `status: patched|unverified`, `healAttemptId`, `operations` and `healedRequest` with `url`, `headers` or `body`. Only these two statuses authorize a retry. No patch, malformed responses and unavailable service return the original error response. HTTP 403 with `{"error":"project_disabled"}` suppresses healing for five minutes.
 
 ## 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. Incomplete request or 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. 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/README.md

@@ -1,52 +1,46 @@
 # Manifest for Node.js
 
 [![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)
 
-Repair failed JSON API requests automatically. Works with Node's built-in `fetch`, for everyday APIs and LLMs alike.
+**An API rejects your request. Manifest fixes it and retries. You do nothing.**
+
+```sh
+npm install manifest
+```
 
 ```js
 import { manifest } from 'manifest';
 
-manifest();
+manifest(); // once, at startup
 // Keep making your API calls as usual.
 ```
 
-Your API rejects a request → Manifest finds a repair → the SDK retries once, locally.
-
-## Setup
-
-### 1. Install
-
-Requires **Node.js 22+**:
-
-```sh
-npm install manifest
-```
+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.
 
-JavaScript, TypeScript, ESM and CommonJS are supported; there are no runtime 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)
 
-### 2. Connect your project
+## Setup
 
-Create a project in your Manifest dashboard and copy the project key shown during setup. In **Project Settings**, turn **Autofix** on to enable repairs.
+1. Create a project in your Manifest dashboard and copy its project key.
+2. Turn on **Autofix** in **Project Settings**.
+3. Set the key:
 
 ```sh
 export MNFST_KEY='your-project-key'
 ```
 
-The SDK defaults to `https://api.manifest.build`. For a local app running on port 5310, also set:
+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:
 
 ```sh
-export MNFST_URL='http://127.0.0.1:5310'
+node --import manifest/register app.js
 ```
 
-Your server must support the [SDK API contract](CONTRACT.md). The local app must already be running.
-
-### 3. Initialize before your requests
-
-Call `manifest()` once at startup, before other libraries save a reference to `fetch`. Save this as `example.mjs`, replacing the example endpoint and payload with your own:
+## See it work
 
 ```js
-import { manifest, flush } from 'manifest';
+import { manifest } from 'manifest';
 
 manifest({
   onHeal(event) {
@@ -54,36 +48,19 @@ manifest({
   },
 });
 
-try {
-  const response = await fetch('https://api.example.com/orders', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ limit: 500 }),
-  });
-  console.log(response.status, await response.text());
-} finally {
-  await flush({ timeoutMs: 5000 });
-}
+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
+});
 ```
 
-Run it with `node example.mjs`. For an API that rejects `limit: 500` and has a matching repair, Manifest can retry with a valid limit. Repairs depend on the API error and available patches.
-
-CommonJS uses `const { manifest, flush } = require('manifest')`.
-
-## Check that it works
-
-Send a JSON request that your test API rejects with **400, 404 or 422**. Check the failure in your project's dashboard and the `onHeal` callback for the repair result. A successful request alone does not contact Manifest. `flush()` lets a short script wait for outcome reports before exiting.
-
-## What to expect
-
-- **One retry.** Manifest returns a repair; the SDK sends the corrected request directly to your API.
-- **Original error if healing is unavailable.** A heal call can add up to 60 seconds. If a retry returns an HTTP response, that response reaches your application.
-- **Built-in fetch.** Browser JavaScript, default Axios, `node:http` and separately imported fetch implementations are not intercepted.
-- **Retry semantics still matter.** Use idempotency keys where needed; a repeated request can repeat side effects.
-
-## Privacy
+## Good to know
 
-Manifest receives failed request URLs, headers, JSON bodies and error responses. Known credential fields are masked or withheld, but nested secrets, prompts and business data can still be sent. Enable it only for traffic you permit your Manifest server to process and store.
+- **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.
 
 ## More