@forgeintel/sdk 0.5.0-alpha.oldfeedback.1 → 0.5.0-alpha.oldfeedback.1.b13

package/README.md

@@ -2,7 +2,7 @@
 
 > **Beta.** Install with `npm install @forgeintel/sdk`. The API may change before 1.0.
 
-The Forge SDK for x402 paid APIs. Paid responses carry a `feedback_id`, the 402 challenge asks agents to rate the call, a rating is one free GET, and every call is reported to your Forge dashboard in the background. Never on your critical path: no network calls while your API serves a request, and it fails open. Aware of x402 v1 and v2, and of OpenAPI 2.0 through 3.2. Every change is additive, and anything it doesn't understand passes through untouched.
+The Forge SDK for x402 paid APIs. Paid responses carry a `feedback_id`, the 402 challenge asks agents to rate the call, a rating is a free GET with no payment, and every call is reported to your Forge dashboard in the background. Never on your critical path: no network calls while your API serves a request, and it fails open. Aware of x402 v1 and v2, and of OpenAPI 2.0 through 3.2. Every change is additive, and anything it doesn't understand passes through untouched.
 
 ## Express
 
@@ -11,22 +11,20 @@ import { createForge } from "@forgeintel/sdk";
 
 const forge = createForge({
   apiKey: process.env.FORGE_API_KEY,
-  agentContext: true,
-  feedback: true,
 });
 
 app.use(forge.middleware());                        // 1. first: before payments and your /openapi.json route
 app.use(paymentMiddleware(routes, resourceServer)); // 2. your existing x402 setup, unchanged
 ```
 
-Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5. The root export is the Express adapter (also at `@forgeintel/sdk/express`).
+Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5. Complete example: [forge-examples/node-express](https://github.com/tryforgeintel/forge-examples/tree/main/node-express). The root export is the Express adapter (also at `@forgeintel/sdk/express`).
 
 ## Hono (Node, Bun, Deno, Cloudflare Workers)
 
 ```ts
 import { createForge } from "@forgeintel/sdk/hono";
 
-const forge = createForge({ apiKey, agentContext: true, feedback: true });
+const forge = createForge({ apiKey });
 app.use(forge.middleware());                        // before paymentMiddleware from @x402/hono
 app.use(paymentMiddleware(routes, resourceServer));
 ```
@@ -36,7 +34,7 @@ app.use(paymentMiddleware(routes, resourceServer));
 ```ts
 import { createForge } from "@forgeintel/sdk/next";
 
-export const forge = createForge({ apiKey, agentContext: true, feedback: true });
+export const forge = createForge({ apiKey });
 // app/api/…/route.ts: Forge outermost, around @x402/next's withX402
 export const POST = forge.withForge(withX402(handler, route, resourceServer));
 // app/feedback/[[...path]]/route.ts: Forge's own routes
@@ -49,7 +47,7 @@ export const { GET, POST, HEAD } = forge.routes;
 
 ## Any other framework
 
-`@forgeintel/sdk/core` is the same logic without a framework. Call `forge.route()` first, then `forge.call()` per paid request, and `call.headers()` / `call.json()` / `call.finish()` where you build the 402 and the paid response. See the [core integration guide](https://github.com/ClawCash/forge-feedback/tree/main/examples/node-http-core) for a complete `node:http` + `@x402/core` example.
+`@forgeintel/sdk/core` is the same logic without a framework. Call `forge.route()` first, then `forge.call()` per paid request, and `call.headers()` / `call.json()` / `call.finish()` where you build the 402 and the paid response. See the [core API reference](https://docs.forgeintel.co/reference/core-api).
 
 Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require()`.
 
@@ -57,8 +55,8 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 
 | When | What happens |
 | --- | --- |
-| 402 challenge | Appends one line to the description: *Paid responses include a feedback_id. Please rate the result for other agents with one free GET: https://…/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully\|partially\|no.* On x402 v2 it also adds an `extensions["forge-feedback"]` block with the outcome and issue values. The description never exceeds 500 characters (the CDP facilitator rejects longer ones): a shorter line is used when the full one doesn't fit, and none when neither does. Payment terms are never touched. |
-| Paid 2xx response | Adds the `Forge-Feedback-Id` header. JSON object bodies also get one `forge_feedback` object: `feedback_id`, `rate` (with `outcome=` left blank) and `rate_this_call`, unless your body already has a `forge_feedback` key or your OpenAPI schema for that response couldn't safely take it. Rating links are absolute: your origin registered in Forge, fetched in the background, or the request's own x402 resource origin. |
+| 402 challenge | Appends one line to the description: *After your call, please rate this service for other agents: GET https://…/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Free, no payment: any HTTP client works, including your x402 one. …* On x402 v2 it also adds an `extensions["forge-feedback"]` block with the `ask`, the rating link, and the outcome and issue values. The description never exceeds 500 characters (the CDP facilitator rejects longer ones): a shorter line is used when the full one doesn't fit, and none when neither does. Payment terms are never touched. |
+| Paid 2xx response | Adds the `Forge-Feedback-Id` header. JSON object bodies also get one `forge_feedback` object: `feedback_id`, `feedback_url` (with `outcome=` left blank) and `rate_this_call`, unless your body already has a `forge_feedback` key or your OpenAPI schema for that response couldn't safely take it. Rating links are absolute: your origin registered in Forge, fetched in the background, or the request's own x402 resource origin. |
 | `GET /openapi.json` | Your document is served enriched: feedback routes documented, feedback fields added to paid response schemas, one sentence in `x-guidance`. |
 | `GET /feedback/rate` | Quick rating: `feedback_id`, `outcome`, optional `issue`. |
 | `POST /feedback` | Same fields, plus an optional `note` (≤ 280 chars). |
@@ -93,7 +91,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. Wording that presents the rating as required, makes anything depend on it, or asks for user data is refused (with a warning). |
 | `challengeExtension` | `true` | Add the `forge-feedback` extension to x402 v2 challenges. |
 | `receiptExtension` | `true` | Add it, with the real `feedback_id`, to the x402 v2 payment receipt (`PAYMENT-RESPONSE`). |
-| `agentContext` | `true` | Require self-reported `agent_context` (agent name, search query) on paid requests before payment processing; record and strip it before your code runs. `{ searchQuery: false }` requires only the agent name; `false` disables collection and enforcement. |
+| `agentContext` | optional | Ask for self-reported `agent_context` (agent name, search query) on paid requests; record and strip it before your code runs. Unset, it is optional and never rejects a request. `true` (or `{ required: true }`) requires it before payment processing. `{ searchQuery: false }` stops asking for the search query; `false` disables collection. |
 | `injectBody` | `true` | Add the `forge_feedback` object to paid JSON bodies. |
 | `rateHint` | built-in | The `forge_feedback.rate_this_call` field. A string overrides it (`{feedback_url}` is substituted); `false` removes it. |
 | `injectText` | `false` | Append a two-line trailer to paid `text/plain` bodies. |
@@ -105,23 +103,24 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 
 `forge.diagnostics()` returns counters and the last OpenAPI report. `forge.enrichOpenApi(doc)` is available for build-time use. Call `await forge.shutdown()` in your shutdown handler to flush pending events.
 
-Source, examples and design notes: [github.com/ClawCash/forge-feedback](https://github.com/ClawCash/forge-feedback).
+Runnable examples (Express and FastAPI): [github.com/tryforgeintel/forge-examples](https://github.com/tryforgeintel/forge-examples). Docs: [docs.forgeintel.co](https://docs.forgeintel.co).
 
 Client headers are captured automatically at discovery, challenge, payment, and rating stages, including unknown clients. Forge identifies awal, AgentCash, pay.sh and x402scan-mcp from known headers; other clients remain unknown. There is no client-signals switch. Legacy `agent_context.client` inputs remain accepted but are no longer requested.
 
 ### Agent context on paid requests
 
 ```ts
-const forge = createForge({
-  apiKey: process.env.FORGE_API_KEY!,
-  agentContext: true,
-});
+createForge({ apiKey });                                   // default: asked for, optional
+createForge({ apiKey, agentContext: true });               // required before payment
+createForge({ apiKey, agentContext: { searchQuery: false } }); // required, agent name only
+createForge({ apiKey, agentContext: { required: false, searchQuery: false } }); // optional, agent name only
+createForge({ apiKey, agentContext: false });              // off
 ```
 
-When enabled, context is always required on payment-bearing requests. `false` disables asking and recording. Forge documents `agent_context` and its `agent_type` and `search_query` fields as required. Any agent name is accepted; known spellings are normalized (`Claude` and `claude-code` become `Claude Code`). Send the search query, or `"direct"`. When the merchant declares a `bazaar` extension, Forge adds the same field there (schema and example), so agents that discover the service through Bazaar see it too. `{ searchQuery: false }` requires only the agent type. The legacy `required: false` option is ignored; disable `agentContext` to opt out. Context is self-reported, not authenticated identity.
+By default Forge asks for context and records it whenever an agent sends it, but a paid request without it is never rejected, so existing paying clients keep working. Forge documents `agent_context` and its `agent_type` and `search_query` fields as optional. Any agent name is accepted; known spellings are normalized (`Claude` and `claude-code` become `Claude Code`). Send the search query, or `"direct"`. When the merchant declares a `bazaar` extension, Forge adds the same field there (schema and example), so agents that discover the service through Bazaar see it too. Context is self-reported, not authenticated identity.
 
-Mount Forge **before payment middleware**. A request carrying `PAYMENT-SIGNATURE` or `X-PAYMENT` gets HTTP 400 with field errors when context is missing or invalid, before the downstream payment handler runs. Initial unpaid requests can still receive a 402, and inspection and feedback routes stay accessible. Feedback remains optional and has its own `feedback` switch.
+`agentContext: true`, or an object without `required: false`, makes context required: Forge documents the fields as required, and a request carrying `PAYMENT-SIGNATURE` or `X-PAYMENT` gets HTTP 400 with field errors when context is missing or invalid, before the downstream payment handler runs. Mount Forge **before payment middleware**. Initial unpaid requests can still receive a 402, and inspection and feedback routes stay accessible. Feedback has its own `feedback` switch.
 
 Required mode reads JSON bodies up to 1 MiB, including chunked bodies, before payment processing. It rejects malformed or oversized JSON. Express parses these bodies even if your JSON parser is mounted later; mount a custom parser before Forge if you need one. For non-JSON bodies and bodyless requests, supply `agent_type` and `agent_search_query` query parameters. Forge strips context before forwarding to merchant validators. Next.js integrations that use a payment proxy should wrap both the proxy with `forge.proxy(...)` and the route with `forge.withForge(...)`.
 
-If using the framework-free core directly, call `requestUrl` and `requestBody`, then check `call.contextError()` **before** invoking your payment logic; send its response when non-null. Upgrading an existing integration to this version makes enabled context mandatory for paid requests.
+If using the framework-free core directly, call `requestUrl` and `requestBody`, then check `call.contextError()` **before** invoking your payment logic; send its response when non-null (it is always null when context is optional).

package/dist/context.js

@@ -1,5 +1,5 @@
 // Self-reported facts about the calling agent, removed before merchant validation.
-// Enabled context is required on payment-bearing requests.
+// Optional by default; merchants can require context on payment-bearing requests.
 /** Suggested agent names; anything else is kept as given. */
 export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
 /** Spellings agents use for the suggested names, compared lowercase with only letters and digits kept. */

package/dist/core.d.ts

@@ -50,13 +50,14 @@ export interface ForgeOptions {
      */
     receiptExtension?: boolean;
     /**
-     * Agent context: required, self-reported `agent_context` {agent_type, search_query} on the paid request
+     * Agent context: self-reported `agent_context` {agent_type, search_query} on the paid request
      * (JSON body, or agent_type / agent_search_query query parameters). Forge documents it in the
      * extension and OpenAPI, reads it, reports it with the call, and removes it before your validators and handlers
-     * run. Default true. `{ searchQuery: false }` stops asking for (and recording) the search query; `false` stops
+     * run. By default it is asked for but optional: a paid request without it is never rejected.
+     * `true` or `{ required: true }` requires it: payment-bearing requests with missing/invalid context get a 400
+     * before payment middleware (an object is required unless it sets `required: false`).
+     * `{ searchQuery: false }` stops asking for (and recording) the search query; `false` stops
      * asking and recording altogether (the fields are still removed if an agent sends them).
-     * Enabled context rejects payment-bearing requests with missing/invalid context before payment middleware.
-     * `required` is retained for compatibility; `false` is ignored. Use `false` for agentContext to disable it.
      */
     agentContext?: boolean | {
         searchQuery?: boolean;

package/dist/core.js

@@ -67,8 +67,6 @@ export function checkOptions(input) {
     fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery, required }");
     if (raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)) {
         const context = raw.agentContext;
-        if (context.required === false)
-            warnings.push("agentContext.required: false is no longer supported; enabled context is required on paid requests. Set agentContext: false to disable context");
         for (const key of ["required", "searchQuery"]) {
             if (context[key] !== undefined && typeof context[key] !== "boolean") {
                 errors.push(`agentContext.${key} must be a boolean`);
@@ -106,7 +104,10 @@ export function checkOptions(input) {
     }
     return { errors, warnings, options };
 }
-/** Everything passes through untouched. Used when invalid options turned Forge off. */
+/**
+ * Used when invalid options turned Forge off: nothing is recorded or added, but agent context is still removed from
+ * requests, so agents that learned about it (an earlier deploy, a cached listing) can't trip strict validators.
+ */
 function disabledCore(errors, warnings) {
     const passThrough = {
         feedbackId: undefined,
@@ -115,8 +116,8 @@ function disabledCore(errors, warnings) {
         json: (_status, body) => body,
         text: (_status, _type, body) => body,
         headers: () => ({}),
-        requestBody: (body) => body,
-        requestUrl: (url) => url,
+        requestBody: (body) => takeFromBody(body).body,
+        requestUrl: (url) => takeFromUrl(url).url,
         finish: () => { },
     };
     return {
@@ -184,10 +185,11 @@ function enabledCore(options, configWarnings) {
     const injectBody = options.injectBody ?? true;
     const injectText = options.injectText ?? false;
     const tone = options.tone ?? "soft";
-    const contextOption = options.agentContext ?? true;
+    const contextOption = options.agentContext;
     const collectContext = contextOption !== false;
     const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
-    const requiredContext = collectContext;
+    // Optional unless configured: true, or an object without required: false, keeps the strict (400) behavior.
+    const requiredContext = contextOption === true || (typeof contextOption === "object" && contextOption.required !== false);
     const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null

package/dist/express.js

@@ -135,7 +135,7 @@ export function createForge(options) {
             core.onError(error);
         }
         if (call.contextRequired) {
-            // Enabled context: parse before payment middleware even when the merchant mounts express.json later.
+            // Required context: parse before payment middleware even when the merchant mounts express.json later.
             // The body setter above captures context and leaves only merchant fields in req.body.
             const parseError = await new Promise((resolve) => {
                 express.json({ limit: "1mb", type: ["application/json", "application/*+json"] })(req, res, resolve);
@@ -202,8 +202,18 @@ export function createForge(options) {
         diagnostics: core.diagnostics,
         shutdown: core.shutdown,
         middleware() {
-            if (!core.enabled)
-                return (_req, _res, next) => next();
+            if (!core.enabled) {
+                // Disabled by invalid options: only remove agent context, so strict validators never see it.
+                return (req, _res, next) => {
+                    try {
+                        takeAgentContext(req, core.call({ method: req.method, path: req.path, header: () => undefined }));
+                    }
+                    catch {
+                        // never break the business request
+                    }
+                    next();
+                };
+            }
             return (req, res, next) => {
                 core
                     .route({

package/dist/fetch.js

@@ -1,7 +1,7 @@
 // Web-standard adapter: Request in, Response out. Works wherever handlers are (request) => Response:
 // Hono, Next.js route handlers, Cloudflare Workers, Bun, Deno. The Hono and Next adapters build on this.
 import { BODY_LIMIT, SPEC_LIMIT, createForgeCore } from "./core.js";
-/** Buffer limit; enabled context rejects oversized paid JSON before payment processing. */
+/** Buffer limit; required context rejects oversized paid JSON before payment processing. */
 const JSON_LIMIT = 1024 * 1024;
 const isJson = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type ?? "");
 export function toResponse(response) {
@@ -113,8 +113,6 @@ export function createForge(options) {
         }
     }
     async function handle(request, next) {
-        if (!core.enabled)
-            return next(request);
         // Before the handler: our own routes, the spec, and agent context. Required-context errors stop paid attempts.
         let call;
         let forwarded = request;
@@ -135,10 +133,10 @@ export function createForge(options) {
                 if (without !== parsed)
                     body = JSON.stringify(without);
             }
-            else if (request.body && isJson(request.headers.get("content-type")) && smallEnough(request.headers, JSON_LIMIT)) {
-                const text = await request.clone().text();
-                if (text.includes('"agent_context"')) {
-                    const parsed = JSON.parse(text);
+            else if (request.body && isJson(request.headers.get("content-type")) && (smallEnough(request.headers, JSON_LIMIT) || !request.headers.has("content-length"))) {
+                // Optional context, best effort: a body that is too large or not JSON goes to the handler untouched.
+                const parsed = await boundedJson(request).catch(() => undefined);
+                if (parsed !== undefined) {
                     const without = call.requestBody(parsed);
                     if (without !== parsed)
                         body = JSON.stringify(without);
@@ -168,6 +166,9 @@ export function createForge(options) {
             }
             return next(request);
         }
+        // Disabled by invalid options: agent context is removed (above), nothing else.
+        if (!core.enabled)
+            return next(forwarded);
         const response = await next(forwarded);
         // After the handler: decorate the 402 or the paid response. Any failure before the body is read: the original
         // response goes out. Once read, the body is always sent from what was read (decorated or not).

package/dist/hono.js

@@ -10,8 +10,6 @@ export function createForge(options) {
         shutdown: forge.shutdown,
         validate: forge.validate,
         middleware() {
-            if (!forge.enabled)
-                return async (_c, next) => next();
             return async (c, next) => {
                 let ranNext = false;
                 const response = await forge.handle(c.req.raw, async (request) => {

package/dist/openapi.d.ts

@@ -2,7 +2,7 @@ type Json = Record<string, any>;
 export type SpecVersion = "2.0" | "3.0" | "3.1" | "3.2";
 export type ResponseSupport = "extended" | "incompatible" | "undocumented";
 export interface EnrichOptions {
-    /** Disable all feedback additions while retaining enabled agent context. */
+    /** Disable all feedback additions while retaining agent context. */
     feedback?: boolean;
     /** Optional merchant public origin. Without it, feedback links use same-origin paths. */
     publicUrl?: string;
@@ -30,7 +30,7 @@ export interface OperationReport {
     path: string;
     /** Per 2xx status code: whether feedback_id was added to its JSON schema. */
     responses: Record<string, ResponseSupport>;
-    /** Where enabled agent context was documented, if asked to. */
+    /** Where agent context was documented, if asked to. */
     agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }

package/dist/openapi.js

@@ -61,6 +61,8 @@ function feedbackProperties(rateUrl, hintField = false) {
 }
 /** Returns an extended copy of an object schema, or a reason it can't be extended safely. */
 function extendSchema(doc, schema, props) {
+    if (schema === true)
+        schema = {}; // `true` accepts any value, like {}
     if (!isObj(schema))
         return { reason: "no_schema" };
     let target = schema;
@@ -83,7 +85,10 @@ function extendSchema(doc, schema, props) {
     if (COMPOSITION.some((k) => k in copy))
         return { reason: "composition" };
     const types = Array.isArray(copy.type) ? copy.type : [copy.type];
-    const objectish = types.includes("object") || (copy.type === undefined && (isObj(copy.properties) || Array.isArray(copy.allOf)));
+    // {} (annotations only) accepts any value, e.g. FastAPI's default response schema. `properties` only constrains
+    // objects, so documenting the field there narrows nothing.
+    const anyValue = Object.keys(copy).every((k) => ANNOTATIONS.has(k));
+    const objectish = anyValue || types.includes("object") || (copy.type === undefined && (isObj(copy.properties) || Array.isArray(copy.allOf)));
     if (!objectish)
         return { reason: "not_object" };
     if ("propertyNames" in copy || "maxProperties" in copy)
@@ -110,7 +115,6 @@ function extendSchema(doc, schema, props) {
 const BODYLESS = new Set(["get", "head", "delete", "options", "trace"]);
 /** Document agent context on a paid operation; skip schemas that cannot be extended safely. */
 function addAgentContext(doc, version, item, method, op, opts, report) {
-    opts = { ...opts, required: true }; // Enabled context cannot be made optional by a legacy option.
     const resolve = (v) => (isObj(v) && typeof v.$ref === "string" ? resolveRef(doc, v.$ref) : v);
     const listed = [...(Array.isArray(item.parameters) ? item.parameters : []), ...(Array.isArray(op.parameters) ? op.parameters : [])].map(resolve).filter(isObj);
     const props = { [CONTEXT_FIELD]: agentContextSchema(opts) };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-alpha.oldfeedback.1",
-  "description": "The Forge SDK for x402 paid APIs: agent feedback, required agent context, OpenAPI and challenge enrichment, and passive call signals. Express, Hono, Next.js and fetch handlers. No Forge network request on the merchant response path.",
+  "version": "0.5.0-alpha.oldfeedback.1.b13",
+  "description": "The Forge SDK for x402 paid APIs: agent feedback, agent context, OpenAPI and challenge enrichment, and passive call signals. Express, Hono, Next.js and fetch handlers. No Forge network request on the merchant response path.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -61,11 +61,7 @@
     "cloudflare-workers",
     "bun"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ClawCash/forge-feedback.git",
-    "directory": "packages/sdk"
-  },
+  "homepage": "https://docs.forgeintel.co",
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "node -e \"require('fs').rmSync('dist-test',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test --test-reporter=spec \"dist-test/test/**/*.test.js\"",