@forgeintel/sdk 0.5.0-beta.14 → 0.5.0-beta.15

package/README.md

@@ -11,6 +11,8 @@ import { createForge } from "@forgeintel/sdk";
 
 const forge = createForge({
   apiKey: process.env.FORGE_API_KEY,
+  feedback: true,     // the rating ask; off by default
+  agentContext: true, // ask agents who they are, optional; off by default
 });
 
 app.use(forge.middleware());                        // 1. first: before payments and your /openapi.json route
@@ -24,7 +26,7 @@ Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5.
 ```ts
 import { createForge } from "@forgeintel/sdk/hono";
 
-const forge = createForge({ apiKey });
+const forge = createForge({ apiKey, feedback: true, agentContext: true });
 app.use(forge.middleware());                        // before paymentMiddleware from @x402/hono
 app.use(paymentMiddleware(routes, resourceServer));
 ```
@@ -34,7 +36,7 @@ app.use(paymentMiddleware(routes, resourceServer));
 ```ts
 import { createForge } from "@forgeintel/sdk/next";
 
-export const forge = createForge({ apiKey });
+export const forge = createForge({ apiKey, feedback: true, agentContext: true });
 // 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
@@ -53,6 +55,8 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 
 ## What it does
 
+Both switches are off by default: with only an API key, Forge reports every 402 and paid call in the background and changes nothing agents see. `feedback: true` turns on the rows about rating below; `agentContext: true` turns on the agent context row.
+
 | When | What happens |
 | --- | --- |
 | 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, one request.* On x402 v2 it also adds an `extensions["forge-feedback"]` block with the `ask`, the rating link and the outcome values, and previews the `forge_feedback` object (with a sample ID) in your Bazaar output example. 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. |
@@ -110,16 +114,16 @@ Client headers are captured automatically at discovery, challenge, payment, and
 ### Agent context on paid requests
 
 ```ts
-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
+createForge({ apiKey });                                        // default: off
+createForge({ apiKey, agentContext: true });                    // asked for, optional
+createForge({ apiKey, agentContext: { searchQuery: false } });  // optional, agent name only
+createForge({ apiKey, agentContext: { required: true } });      // required before payment
+createForge({ apiKey, agentContext: { required: true, searchQuery: false } }); // required, agent name only
 ```
 
-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.
+When on, Forge asks for context and records it whenever an agent sends it, but a paid request without it is never rejected unless you require it, 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.
 
-`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: true }` 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(...)`.
 

package/dist/core.d.ts

@@ -22,7 +22,7 @@ export interface ForgeOptions {
     backendUrl?: string;
     /** Optional public origin for absolute feedback links. By default links use same-origin paths. Never derived from the Host header. */
     publicUrl?: string;
-    /** Enable rating prompts, feedback IDs and feedback routes. Default true. Telemetry and agent context are independent. */
+    /** Enable rating prompts, feedback IDs and feedback routes. Off by default: with only an API key, Forge reports telemetry and changes nothing agents see. Agent context is independent. */
     feedback?: boolean;
     /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
     basePath?: string;
@@ -53,11 +53,10 @@ export interface ForgeOptions {
      * 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. 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).
+     * run. Off by default. `true` (or an object) asks for it but keeps it optional: a paid request without it is
+     * never rejected. `{ required: true }` requires it: payment-bearing requests with missing/invalid context get a
+     * 400 before payment middleware. `{ searchQuery: false }` stops asking for (and recording) the search query.
+     * When off, the fields are still removed if an agent sends them.
      */
     agentContext?: boolean | {
         searchQuery?: boolean;

package/dist/core.js

@@ -182,16 +182,16 @@ function enabledCore(options, configWarnings) {
     };
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
     const fetchImpl = options.fetch ?? fetch;
-    const feedback = options.feedback !== false;
+    const feedback = options.feedback === true;
     const describe = feedback && (options.describeChallenges ?? true);
     const injectBody = options.injectBody ?? true;
     const injectText = options.injectText ?? false;
     const tone = options.tone ?? "soft";
     const contextOption = options.agentContext;
-    const collectContext = contextOption !== false;
+    // Off unless configured. true or an object turns it on, optional; only { required: true } rejects (400).
+    const collectContext = contextOption === true || (!!contextOption && typeof contextOption === "object");
     const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
-    // 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 requiredContext = typeof contextOption === "object" && contextOption.required === true;
     const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null

package/dist/fetch.js

@@ -70,7 +70,7 @@ export function createForge(options) {
         return own ? toResponse(own) : null;
     }
     async function validate(request) {
-        if (!core.enabled || options.agentContext === false)
+        if (!core.enabled || !options.agentContext)
             return null;
         const url = new URL(request.url);
         const call = core.call(forgeRequest(request, url));

package/package.json

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