@forgeintel/sdk 0.5.0-beta.11 → 0.5.0-beta.13

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
 
@@ -17,7 +17,7 @@ app.use(forge.middleware());                        // 1. first: before payments
 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)
 
@@ -47,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()`.
 
@@ -103,7 +103,7 @@ 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.
 

package/dist/core.js

@@ -104,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,
@@ -113,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 {

package/dist/express.js

@@ -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

@@ -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;
@@ -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.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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.11",
+  "version": "0.5.0-beta.13",
   "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",
@@ -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\"",