{"_id":"graceful-fail","_rev":"3-4e970b7e2e7cbde5dae6526d42a226c3","name":"graceful-fail","dist-tags":{"latest":"0.4.0"},"versions":{"0.1.0":{"name":"graceful-fail","version":"0.1.0","keywords":["ai-agents","api-proxy","error-handling","llm","langchain","self-healing","agent-reliability","graceful-fail","selfheal"],"author":{"name":"Freedom Engineers","email":"hello@freedomengineers.tech"},"license":"MIT","_id":"graceful-fail@0.1.0","maintainers":[{"name":"crollin","email":"carson.roell@gmail.com"}],"homepage":"https://selfheal.dev","bugs":{"url":"https://github.com/freedomengineers/graceful-fail-js/issues"},"dist":{"shasum":"7e13e1205286e5561973ab13bb4e05406423da02","tarball":"https://registry.npmjs.org/graceful-fail/-/graceful-fail-0.1.0.tgz","fileCount":10,"integrity":"sha512-lDqHaJ75krkzy1+XEblIDg8Fim9pSYJAemKVI26RBJHtNedWFlW60q3EcEV+ZBsgc6GOPp1w0xsaMXbRg9Atng==","signatures":[{"sig":"MEQCIDiDJ/242KRqKq6D1WccvQztRLaY3RWClAoE1GqFnatkAiBKAENdTG+/SnpZFWZpDVXDnUjvbH+uvm1jd1ClQgPbaw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1077559},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./langchain":{"types":"./dist/langchain.d.ts","import":"./dist/langchain.mjs","require":"./dist/langchain.js"}},"gitHead":"a74b80f3df46b4fddbff849fb85b9613cc68b53e","scripts":{"test":"vitest run","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"crollin","email":"carson.roell@gmail.com"},"repository":{"url":"git+https://github.com/freedomengineers/graceful-fail-js.git","type":"git"},"_npmVersion":"11.6.2","description":"Self-healing API proxy for AI agents. Route HTTP calls through Graceful Fail and get structured, LLM-powered fix instructions when APIs return errors.","directories":{},"_nodeVersion":"24.12.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","typescript":"^5.4.0","@langchain/core":"^1.1.36"},"peerDependencies":{"@langchain/core":">=0.1.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/graceful-fail_0.1.0_1774618092252_0.6971814500274283","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"graceful-fail","version":"0.3.0","keywords":["ai-agents","api-proxy","error-handling","llm","langchain","self-healing","agent-reliability","graceful-fail","selfheal"],"author":{"name":"Freedom Engineers","email":"hello@freedomengineers.tech"},"license":"MIT","_id":"graceful-fail@0.3.0","maintainers":[{"name":"crollin","email":"carson.roell@gmail.com"}],"homepage":"https://selfheal.dev","bugs":{"url":"https://github.com/freedomengineers/graceful-fail-js/issues"},"dist":{"shasum":"32c54185f5d71e4960e44c2afc2fd6eacbaca181","tarball":"https://registry.npmjs.org/graceful-fail/-/graceful-fail-0.3.0.tgz","fileCount":10,"integrity":"sha512-MgviXo0iXqiDfLhCddcsJiDfMq8c1gfhf/QVMGgTOtWehxwBoMyLrr2c7cw/NDuTvBwvLQqx2aimlmF3rR83bw==","signatures":[{"sig":"MEYCIQCFPwRs1AeAaCDc4Q6T7sWmNR29oiEyjKdMubxWOzsnaAIhAIa2jBFgp8nUxEF4iG7C+9WVeQ1CqMPVaNXzJ2xMVz81","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":1087961},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/index.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./langchain":{"types":"./dist/langchain.d.ts","import":"./dist/langchain.mjs","require":"./dist/langchain.js"}},"gitHead":"47a7e0c8633ebb77dd26b8ebe55cee19fa0d2c19","scripts":{"test":"vitest run","build":"tsup","prepublishOnly":"npm run build"},"_npmUser":{"name":"crollin","email":"carson.roell@gmail.com"},"repository":{"url":"git+https://github.com/freedomengineers/graceful-fail-js.git","type":"git"},"_npmVersion":"10.8.2","description":"Self-healing API proxy for AI agents. Route HTTP calls through Graceful Fail and get structured, LLM-powered fix instructions when APIs return errors.","directories":{},"_nodeVersion":"20.20.1","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.0.0","vitest":"^1.6.0","typescript":"^5.4.0","@langchain/core":"^1.1.36"},"peerDependencies":{"@langchain/core":">=0.1.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/graceful-fail_0.3.0_1774874612695_0.33667939621497234","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"graceful-fail","version":"0.4.0","description":"Self-healing API proxy for AI agents with x402 outcome-based pricing. Successes are free. Pay per successful heal in USDC.","main":"dist/index.js","module":"dist/index.mjs","types":"dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.mjs","require":"./dist/index.js"},"./langchain":{"types":"./dist/langchain.d.ts","import":"./dist/langchain.mjs","require":"./dist/langchain.js"}},"scripts":{"build":"tsup","test":"vitest run","prepublishOnly":"npm run build"},"keywords":["ai-agents","api-proxy","error-handling","llm","langchain","self-healing","agent-reliability","graceful-fail","selfheal","x402","micropayments","usdc"],"author":{"name":"Freedom Engineers","email":"hello@freedomengineers.tech"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/freedomengineers/graceful-fail-js.git"},"homepage":"https://selfheal.dev","devDependencies":{"@langchain/core":"^1.1.36","tsup":"^8.0.0","typescript":"^5.4.0","vitest":"^1.6.0"},"peerDependencies":{"@langchain/core":">=0.1.0"},"peerDependenciesMeta":{"@langchain/core":{"optional":true}},"gitHead":"21fe549f3c00a3638c550c1543d6e5071b7cd4b7","_id":"graceful-fail@0.4.0","bugs":{"url":"https://github.com/freedomengineers/graceful-fail-js/issues"},"_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-b9Wp0dIiWICVcFoWnnedhC0In32hwhgE1k26Jk7jYp2Erhw6ocMNB2GuGAsc/KlX6/i1wXT2XOsPxxCny8ZM9A==","shasum":"21ea5f50672c582730e99af26edbc092b5f0ab19","tarball":"https://registry.npmjs.org/graceful-fail/-/graceful-fail-0.4.0.tgz","fileCount":10,"unpackedSize":1111176,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD/AaF4y8vbfZIOq88Fuu+v+paadzLya27zFLWutmUA0QIhAM92lXiJ6H+kTGCs1RIpztLK+vn6xYDLCXpuxwn+agik"}]},"_npmUser":{"name":"crollin","email":"carson.roell@gmail.com"},"directories":{},"maintainers":[{"name":"crollin","email":"carson.roell@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/graceful-fail_0.4.0_1776174787739_0.6344336679679214"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-27T13:28:12.251Z","modified":"2026-04-14T13:53:08.316Z","0.1.0":"2026-03-27T13:28:12.485Z","0.3.0":"2026-03-30T12:43:32.882Z","0.4.0":"2026-04-14T13:53:07.908Z"},"bugs":{"url":"https://github.com/freedomengineers/graceful-fail-js/issues"},"author":{"name":"Freedom Engineers","email":"hello@freedomengineers.tech"},"license":"MIT","homepage":"https://selfheal.dev","keywords":["ai-agents","api-proxy","error-handling","llm","langchain","self-healing","agent-reliability","graceful-fail","selfheal","x402","micropayments","usdc"],"repository":{"type":"git","url":"git+https://github.com/freedomengineers/graceful-fail-js.git"},"description":"Self-healing API proxy for AI agents with x402 outcome-based pricing. Successes are free. Pay per successful heal in USDC.","maintainers":[{"name":"crollin","email":"carson.roell@gmail.com"}],"readme":"# graceful-fail\n\n[![PyPI](https://img.shields.io/pypi/v/graceful-fail)](https://pypi.org/project/graceful-fail/)\n[![npm](https://img.shields.io/npm/v/graceful-fail)](https://www.npmjs.com/package/graceful-fail)\n\n> Part of [SelfHeal](https://selfheal.dev) — autonomous error recovery for AI agents.\n\nSelf-healing API proxy for AI agents. Route your HTTP calls through Graceful Fail and get structured, LLM-powered fix instructions when APIs return errors.\n\nInstead of your agent crashing on a `422` or retrying a `503` blindly, it gets back:\n\n```json\n{\n  \"is_retriable\": false,\n  \"actionable_fix_for_agent\": \"Remove 'name' field. Add 'first_name' and 'last_name' as separate string fields.\",\n  \"suggested_payload_diff\": {\n    \"remove\": [\"name\"],\n    \"add\": { \"first_name\": \"string\", \"last_name\": \"string\" }\n  },\n  \"error_category\": \"validation_error\"\n}\n```\n\nSuccessful requests (2xx/3xx) pass through with zero overhead. You only pay when the LLM is invoked on a failed request.\n\n## Install\n\n```bash\nnpm install graceful-fail\n```\n\n## Quick Start\n\n```typescript\nimport { GracefulFail } from \"graceful-fail\";\n\nconst gf = new GracefulFail({ apiKey: \"gf_your_key\" });\n\nconst resp = await gf.post(\"https://api.example.com/users\", {\n  json: { name: \"Alice\" },\n});\n\nif (resp.intercepted) {\n  // The API returned an error — here's exactly how to fix it\n  console.log(resp.errorAnalysis!.actionable_fix_for_agent);\n  console.log(resp.errorAnalysis!.suggested_payload_diff);\n} else {\n  // Success — here's the data\n  console.log(resp.data);\n}\n```\n\n## All HTTP Methods\n\n```typescript\nconst gf = new GracefulFail({ apiKey: \"gf_your_key\" });\n\nawait gf.get(\"https://api.example.com/users/1\");\nawait gf.post(\"https://api.example.com/users\", { json: { name: \"Alice\" } });\nawait gf.put(\"https://api.example.com/users/1\", { json: { name: \"Bob\" } });\nawait gf.patch(\"https://api.example.com/users/1\", { json: { email: \"bob@example.com\" } });\nawait gf.delete(\"https://api.example.com/users/1\");\n```\n\n## Auto-Apply Fix\n\nWhen you get an intercepted error, apply the suggested diff and retry:\n\n```typescript\nimport { GracefulFail, applyDiff } from \"graceful-fail\";\n\nconst gf = new GracefulFail({ apiKey: \"gf_your_key\" });\nconst payload = { name: \"Alice\" };\n\nconst resp = await gf.post(\"https://api.example.com/users\", { json: payload });\n\nif (resp.intercepted && resp.errorAnalysis) {\n  const fixedPayload = applyDiff(payload, resp.errorAnalysis.suggested_payload_diff);\n  const retry = await gf.post(\"https://api.example.com/users\", { json: fixedPayload });\n  console.log(retry.data);\n}\n```\n\n## LangChain.js Integration\n\n```typescript\nimport { GracefulFailTool } from \"graceful-fail/langchain\";\n\nconst tool = new GracefulFailTool({ apiKey: \"gf_your_key\" });\n\n// Add to any LangChain agent — it handles all external API calls\n// On error, the agent gets structured fix instructions instead of raw HTTP errors\n```\n\nRequires `@langchain/core` as a peer dependency.\n\n## Error Handling\n\n```typescript\nimport { GracefulFail, AuthenticationError, RateLimitError } from \"graceful-fail\";\n\nconst gf = new GracefulFail({ apiKey: \"gf_your_key\" });\n\ntry {\n  const resp = await gf.post(url, { json: data });\n} catch (err) {\n  if (err instanceof AuthenticationError) {\n    // Invalid API key\n  } else if (err instanceof RateLimitError) {\n    // Monthly limit exceeded — upgrade tier\n  }\n}\n```\n\n## Response Object\n\n| Field | Type | Description |\n|---|---|---|\n| `statusCode` | `number` | HTTP status from the destination API |\n| `intercepted` | `boolean` | `true` if the error was analyzed by the LLM |\n| `data` | `T` | Response body (success) or full error envelope (intercepted) |\n| `errorAnalysis` | `ErrorAnalysis` | LLM analysis (only when `intercepted === true`) |\n| `rawResponse` | `unknown` | Original destination API response body |\n| `creditsUsed` | `number` | 0 for pass-through, 1 for intercepted |\n| `durationMs` | `number` | Total proxy round-trip time in milliseconds |\n\n## Get Your API Key\n\n1. Sign up at [selfheal.dev](https://selfheal.dev)\n2. Create an API key in the dashboard\n3. Free tier: 500 requests/month\n\n## Links\n\n- [Documentation](https://selfheal.dev/docs)\n- [Python SDK](https://pypi.org/project/graceful-fail/)\n- [Dashboard](https://selfheal.dev/dashboard)\n- [Status](https://selfheal.dev/status)\n","readmeFilename":"README.md"}