manifest 5.45.1 → 6.0.0

package/CONTRACT.md

@@ -0,0 +1,50 @@
+# SDK / app contract
+
+The SDK talks to the configured Manifest API using `Authorization: Bearer <project key>` and `User-Agent: mnfst-node/<version>`.
+
+## Capture
+
+`POST /v1/heal` receives:
+
+```json
+{
+  "traceId": "unique-capture-id",
+  "request": {"method": "POST", "url": "https://example.com/orders", "headers": {}, "body": {"limit": 200}},
+  "response": {"statusCode": 400, "body": {"error": "limit must be at most 100"}, "truncated": false},
+  "responseTimeMs": 25
+}
+```
+
+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.
+
+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.
+
+## Outcome
+
+`PATCH /v1/heal-attempts/:id` sends exactly one of:
+
+```json
+{"response":{"statusCode":200}}
+```
+
+```json
+{"response":{"statusCode":400,"body":{"error":"raw upstream error"},"truncated":false}}
+```
+
+```json
+{"failure":{"kind":"transport_error","message":"Upstream retry failed before an HTTP response"}}
+```
+
+```json
+{"failure":{"kind":"not_attempted","message":"replay_not_attempted"}}
+```
+
+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.

package/README.md

@@ -1,121 +1,90 @@
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/mnfst/manifest/HEAD/.github/assets/logo-white.svg" />
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/mnfst/manifest/HEAD/.github/assets/logo-dark.svg" />
-    <img src="https://raw.githubusercontent.com/mnfst/manifest/HEAD/.github/assets/logo-dark.svg" alt="Manifest" height="53" title="Manifest"/>
-  </picture>
-</p>
-<p align="center">
-    Take control of your OpenClaw costs
-</p>
-
-![manifest-gh](https://github.com/user-attachments/assets/7dd74fc2-f7d6-4558-a95a-014ed754a125)
-
-<p align="center">
-  <span><img src="https://img.shields.io/badge/status-beta-yellow" alt="beta" /></span>
-  &nbsp;
-  <a href="https://github.com/mnfst/manifest/stargazers"><img src="https://img.shields.io/github/stars/mnfst/manifest?style=flat" alt="GitHub stars" /></a>
-  &nbsp;
-  <a href="https://www.npmjs.com/package/manifest"><img src="https://img.shields.io/npm/v/manifest?color=cb3837&label=npm" alt="npm version" /></a>
-  &nbsp;
-  <a href="https://www.npmjs.com/package/manifest"><img src="https://img.shields.io/npm/dw/manifest?color=cb3837" alt="npm downloads" /></a>
-  &nbsp;
-  <a href="https://hub.docker.com/r/manifestdotbuild/manifest"><img src="https://img.shields.io/docker/pulls/manifestdotbuild/manifest?color=2496ED&label=docker%20pulls" alt="Docker pulls" /></a>
-  &nbsp;
-  <a href="https://github.com/mnfst/manifest/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/mnfst/manifest/ci.yml?branch=main&label=CI" alt="CI status" /></a>
-  &nbsp;
-  <a href="https://app.codecov.io/gh/mnfst/manifest"><img src="https://img.shields.io/codecov/c/github/mnfst/manifest?label=coverage" alt="Codecov" /></a>
-  &nbsp;
-  <a href="LICENSE"><img src="https://img.shields.io/github/license/mnfst/manifest?color=blue" alt="license" /></a>
-  &nbsp;
-  <a href="https://discord.gg/FepAked3W7"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
-</p>
-
-<p align="center">
-<a href="https://trendshift.io/repositories/12890" target="_blank"><img src="https://trendshift.io/api/badge/repositories/12890" alt="mnfst%2Fmanifest | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
-</p>
-
-## What is Manifest?
-
-Manifest is a smart model router for OpenClaw. It sits between your agent and your LLM providers, scores each request, and routes it to the cheapest model that can handle it. Simple questions go to fast, cheap models. Hard problems go to expensive ones. You save money without thinking about it.
-
-- Route requests to the right model: Cut costs up to 70%
-- Automatic fallbacks: If a model fails, the next one picks up
-- Set limits: Don't exceed your budget
-
-## Quick start
-
-### Cloud version
-
-Go to [app.manifest.build](https://app.manifest.build) and follow the guide.
-
-### Local version
-
-```bash
-openclaw plugins install manifest
-openclaw gateway restart
+# 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)
+
+Repair failed JSON API requests automatically. Works with Node's built-in `fetch`, for everyday APIs and LLMs alike.
+
+```js
+import { manifest } from 'manifest';
+
+manifest();
+// Keep making your API calls as usual.
 ```
 
-Dashboard opens at **http://127.0.0.1:2099**. The plugin starts an embedded server, runs the dashboard locally, and registers itself as a provider automatically. No account or API key needed.
+Your API rejects a request → Manifest finds a repair → the SDK retries once, locally.
 
-### Docker
+## Setup
 
-Our <a href="https://hub.docker.com/r/manifestdotbuild/manifest">Manifest Docker Image</a> allows you to self-host Manifest router in your own infrastructure.
+### 1. Install
 
-### Which version choose?
+Requires **Node.js 22+**:
 
-Pick cloud version for quick setup and multi-device access. Pick local version for keeping all your data on your machine or for using local models like Ollama. Pick Docker for self-hosting on your own infrastructure.
+```sh
+npm install manifest
+```
+
+JavaScript, TypeScript, ESM and CommonJS are supported; there are no runtime dependencies.
 
-Not sure which one to choose? Start with cloud.
+### 2. Connect your project
 
-## How it works
+Create a project in your Manifest dashboard and copy the project key shown during setup. In **Project Settings**, turn **Autofix** on to enable repairs.
 
-Every request to `manifest/auto` goes through a 23-dimension scoring algorithm (runs in under 2ms). The scorer picks a tier (simple, standard, complex, or reasoning) and routes to the best model in that tier from your connected providers.
+```sh
+export MNFST_KEY='your-project-key'
+```
 
-All routing data (tokens, costs, model, duration) is recorded automatically. You see it in the dashboard. No extra setup.
+The SDK defaults to `https://api.manifest.build`. For a local app running on port 5310, also set:
 
-## Manifest vs OpenRouter
+```sh
+export MNFST_URL='http://127.0.0.1:5310'
+```
+
+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:
+
+```js
+import { manifest, flush } from 'manifest';
+
+manifest({
+  onHeal(event) {
+    console.log('[manifest]', event.healStatus, event.replayStatusCode);
+  },
+});
+
+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 });
+}
+```
 
-|              | Manifest                                     | OpenRouter                                          |
-| ------------ | -------------------------------------------- | --------------------------------------------------- |
-| Architecture | Local. Your requests, your providers         | Cloud proxy. All traffic goes through their servers |
-| Cost         | Free                                         | 5% fee on every API call                            |
-| Source code  | MIT, fully open                              | Proprietary                                         |
-| Data privacy | Metadata only (cloud) or fully local         | Prompts and responses pass through a third party    |
-| Transparency | Open scoring. You see why a model was chosen | No visibility into routing decisions                |
+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.
 
-## Supported providers
+CommonJS uses `const { manifest, flush } = require('manifest')`.
 
-Works with 300+ models across these providers:
+## Check that it works
 
-| Provider                                                                       | Models                                                               |
-| ------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
-| [OpenAI](https://platform.openai.com/)                                         | `gpt-5.3`, `gpt-4.1`, `o3`, `o4-mini` + 54 more                      |
-| [Anthropic](https://www.anthropic.com/)                                        | `claude-opus-4-6`, `claude-sonnet-4.5`, `claude-haiku-4.5` + 14 more |
-| [Google Gemini](https://ai.google.dev/)                                        | `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-pro` + 19 more       |
-| [DeepSeek](https://www.deepseek.com/)                                          | `deepseek-chat`, `deepseek-reasoner` + 11 more                       |
-| [xAI](https://x.ai/)                                                           | `grok-4`, `grok-3`, `grok-3-mini` + 8 more                           |
-| [Mistral AI](https://mistral.ai/)                                              | `mistral-large`, `codestral`, `devstral` + 26 more                   |
-| [Qwen (Alibaba)](https://www.alibabacloud.com/en/solutions/generative-ai/qwen) | `qwen3-235b`, `qwen3-coder`, `qwq-32b` + 42 more                     |
-| [MiniMax](https://www.minimax.io/)                                             | `minimax-m2.5`, `minimax-m1`, `minimax-m2` + 5 more                  |
-| [Kimi (Moonshot)](https://kimi.ai/)                                            | `kimi-k2`, `kimi-k2.5` + 3 more                                      |
-| [Amazon Nova](https://aws.amazon.com/ai/nova/)                                 | `nova-pro`, `nova-lite`, `nova-micro` + 5 more                       |
-| [Z.ai (Zhipu)](https://z.ai/)                                                  | `glm-5`, `glm-4.7`, `glm-4.5` + 5 more                               |
-| [OpenRouter](https://openrouter.ai/)                                           | 300+ models from all providers                                       |
-| [Ollama](https://ollama.com/)                                                  | Run any model locally (Llama, Gemma, Mistral, ...)                   |
-| Custom providers                                                               | Any provider with an OpenAI-compatible API endpoint                  |
+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.
 
-## Contributing
+## What to expect
 
-Manifest is open source under the [MIT license](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, architecture, and workflow. Join the conversation on [Discord](https://discord.gg/FepAked3W7).
+- **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.
 
-## Quick links
+## Privacy
 
-- [GitHub](https://github.com/mnfst/manifest)
-- [Docs](https://manifest.build/docs)
-- [Discord](https://discord.com/invite/FepAked3W7)
-- [Discussions](https://github.com/mnfst/manifest/discussions)
+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.
 
-## License
+## More
 
-[MIT](LICENSE)
+[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python)