manifest 5.45.1 → 7.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
+}
+```
+
+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. 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.
+
+## 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,67 @@
-<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
 
-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.
+[![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)
 
-### Docker
+**An API rejects your request. Manifest fixes it and retries. You do nothing.**
 
-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.
+```sh
+npm install manifest
+```
 
-### Which version choose?
+```js
+import { manifest } from 'manifest';
 
-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.
+manifest(); // once, at startup
+// Keep making your API calls as usual.
+```
 
-Not sure which one to choose? Start with cloud.
+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 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/healing-diagram.svg)
 
-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.
+## Setup
 
-All routing data (tokens, costs, model, duration) is recorded automatically. You see it in the dashboard. No extra 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:
 
-## Manifest vs OpenRouter
+```sh
+export MNFST_KEY='your-project-key'
+```
 
-|              | 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                |
+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:
 
-## Supported providers
+```sh
+node --import manifest/register app.js
+```
 
-Works with 300+ models across these providers:
+## See it work
 
-| 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                  |
+```js
+import { manifest } from 'manifest';
 
-## Contributing
+manifest({
+  onHeal(event) {
+    console.log('[manifest]', event.healStatus, event.replayStatusCode);
+  },
+});
 
-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).
+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
+});
+```
 
-## Quick links
+## Good to know
 
-- [GitHub](https://github.com/mnfst/manifest)
-- [Docs](https://manifest.build/docs)
-- [Discord](https://discord.com/invite/FepAked3W7)
-- [Discussions](https://github.com/mnfst/manifest/discussions)
+- **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.
 
-## License
+## More
 
-[MIT](LICENSE)
+[Configuration, limits & development](docs/guide.md) · [API contract](CONTRACT.md) · [Python SDK](https://github.com/mnfst/manifest-python)