@forgeintel/sdk 0.5.0-beta.13 → 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,9 +55,11 @@ 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, 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. |
+| 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. |
 | 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`. |
@@ -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/ask.js

@@ -2,10 +2,10 @@
 export const TONES = ["soft", "lifecycle"];
 export const ASK = {
     soft: {
-        challengeSentence: "After your call, please rate this service for other agents: GET {rate_url}?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. If it wasn't fully, please also add &issue= (e.g. wrong_output, slow, unclear_docs) so the merchant knows what to fix.",
-        shortChallengeSentence: "After your call, please rate it for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free, no payment.",
-        rateHint: "Please rate this service for other agents: GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, no payment: any HTTP client works, including your x402 one. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
-        extensionAsk: "After your call, please rate this service for other agents. Free, no payment: any HTTP client works, including your x402 one. When the outcome is not fully, the issue field tells the merchant what to fix.",
+        challengeSentence: "After your call, please rate this service for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Free, one request.",
+        shortChallengeSentence: "After your call, please rate it for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free, one request.",
+        rateHint: "Please rate this service for other agents: GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, one request.",
+        extensionAsk: "After your call, please rate this service for other agents. Free, one request.",
         extensionExtras: {},
     },
     lifecycle: {

package/dist/bazaar.d.ts

@@ -1,7 +1,15 @@
 import { type ContextOptions } from "./context.js";
+type Json = Record<string, unknown>;
 /**
  * Declare agent context in a v2 challenge's `bazaar` extension, in place: an `agent_context` object on JSON
  * bodies, or the `agent_*` query parameters on routes without a body. Other body types, composed or
  * referenced schemas, and fields the merchant already declares are left alone. Returns whether it changed.
  */
 export declare function addContextToBazaar(bazaar: unknown, options: ContextOptions): boolean;
+/**
+ * Preview the paid response's feedback object in the `bazaar` extension's output example, in place, so agents
+ * that inspect the 402 see the rating fields as part of what the call returns. JSON outputs with an object
+ * example only, and only when the output schema lets the example have extra keys. Returns whether it changed.
+ */
+export declare function addFeedbackToBazaar(bazaar: unknown, field: string, preview: Json): boolean;
+export {};

package/dist/bazaar.js

@@ -56,3 +56,23 @@ export function addContextToBazaar(bazaar, options) {
     const query = agentContextQuerySchema(options);
     return extend(inputSchema.properties, info, "queryParams", query.properties, query.required, agentContextExample(options, "query"));
 }
+/**
+ * Preview the paid response's feedback object in the `bazaar` extension's output example, in place, so agents
+ * that inspect the 402 see the rating fields as part of what the call returns. JSON outputs with an object
+ * example only, and only when the output schema lets the example have extra keys. Returns whether it changed.
+ */
+export function addFeedbackToBazaar(bazaar, field, preview) {
+    if (!isObj(bazaar) || !isObj(bazaar.info) || !isObj(bazaar.info.output))
+        return false;
+    const output = bazaar.info.output;
+    if (output.type !== undefined && output.type !== "json")
+        return false;
+    if (!isObj(output.example) || field in output.example)
+        return false;
+    const outputSchema = isObj(bazaar.schema) && isObj(bazaar.schema.properties) ? bazaar.schema.properties.output : undefined;
+    const exampleSchema = isObj(outputSchema) && isObj(outputSchema.properties) ? outputSchema.properties.example : undefined;
+    if (isObj(exampleSchema) && (exampleSchema.additionalProperties === false || COMPOSED.some((key) => key in exampleSchema)))
+        return false;
+    output.example = { ...output.example, [field]: preview };
+    return true;
+}

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;
@@ -175,6 +174,8 @@ export declare const FEEDBACK_HEADERS: {
     "Cache-Control": string;
     "X-Robots-Tag": string;
 };
+/** Placeholder ID in the Bazaar output preview: the right format, obviously not a real call's ID. */
+export declare const SAMPLE_FEEDBACK_ID = "AbCdEfGhIjKlMnOpQrStUv";
 /** Max JSON body for POST {basePath}. */
 export declare const BODY_LIMIT: number;
 /** Max OpenAPI document an adapter should buffer for enrichment. */

package/dist/core.js

@@ -10,6 +10,8 @@ import { captureClientHeaders } from "./client-signals.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL, parseSubmission } from "./values.js";
 import { FEEDBACK_FIELD, challengeOrigin, describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, paymentOrigin, readPaymentHeader, readReceipt, receiptExtension } from "./x402.js";
 export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
+/** Placeholder ID in the Bazaar output preview: the right format, obviously not a real call's ID. */
+export const SAMPLE_FEEDBACK_ID = "AbCdEfGhIjKlMnOpQrStUv";
 /** Max JSON body for POST {basePath}. */
 export const BODY_LIMIT = 8 * 1024;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
@@ -180,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
@@ -234,6 +236,15 @@ function enabledCore(options, configWarnings) {
             additions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery, required: requiredContext }), optional: !requiredContext } };
         if (collectContext)
             additions.bazaarContext = { searchQuery, required: requiredContext };
+        if (feedback && injectBody) {
+            // What the paid body will carry, with a sample ID, so agents inspecting the 402 see the rating fields.
+            const sampleUrl = `${links.rate}?feedback_id=${SAMPLE_FEEDBACK_ID}&outcome=`;
+            additions.bazaarFeedback = {
+                feedback_id: SAMPLE_FEEDBACK_ID,
+                feedback_url: sampleUrl,
+                ...(rateHint ? { rate_this_call: rateHint.replaceAll("{feedback_url}", sampleUrl).replaceAll("{summary_url}", links.summary) } : {}),
+            };
+        }
         if (additionsCache.size >= 16)
             additionsCache.clear(); // one entry per origin; bounded against spoofed Host headers
         additionsCache.set(links.rate, additions);

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/dist/openapi.js

@@ -314,8 +314,9 @@ export function enrichOpenApi(input, options) {
                         addAgentContext(doc, version, item, method, op, options.agentContext, opReport);
                     continue;
                 }
+                // No description: start from the summary, so the operation keeps its own words.
                 if (options.describeOperations ?? true)
-                    op.description = appendSentence(op.description, options.sentence, options.marker);
+                    op.description = appendSentence(op.description || op.summary, options.sentence, options.marker);
                 const produces = (op.produces ?? doc.produces);
                 for (const [code, rawResponse] of Object.entries(isObj(op.responses) ? op.responses : {})) {
                     if (!is2xx(code))

package/dist/x402.d.ts

@@ -20,10 +20,6 @@ export declare function feedbackExtension(rateUrl: string, tone?: Tone): {
     info: {
         rate: string;
         outcome: string[];
-        issue: {
-            when: string;
-            values: string[];
-        };
         feedback_id: string;
         payment: string;
         protocol: string;
@@ -38,10 +34,6 @@ export declare function receiptExtension(rateUrl: string, feedbackId: string, to
         feedback_id: string;
         rate: string;
         outcome: string[];
-        issue: {
-            when: string;
-            values: string[];
-        };
         payment: string;
     };
 };
@@ -70,6 +62,8 @@ export interface ChallengeAdditions {
     contextExtension?: unknown;
     /** Declare agent context in the merchant's `bazaar` extension (schema and example together). */
     bazaarContext?: ContextOptions;
+    /** Preview the paid response's forge_feedback object in the merchant's `bazaar` output example. */
+    bazaarFeedback?: Record<string, unknown>;
 }
 /**
  * Add the rating sentence, Forge's extensions and Bazaar agent context to a base64 PAYMENT-REQUIRED header (x402 v2).

package/dist/x402.js

@@ -1,6 +1,6 @@
 import { ASK } from "./ask.js";
-import { addContextToBazaar } from "./bazaar.js";
-import { ISSUES, PROTOCOL } from "./values.js";
+import { addContextToBazaar, addFeedbackToBazaar } from "./bazaar.js";
+import { PROTOCOL } from "./values.js";
 /** Key of the Forge extension in x402 v2 `extensions`: in the 402 challenge (next to e.g. `bazaar`) and in the payment receipt. */
 export const FEEDBACK_EXTENSION = "forge-feedback";
 /** Key of the object the SDK adds to paid JSON response bodies: feedback_id, feedback_url, and optionally rate_this_call. */
@@ -50,7 +50,6 @@ export function feedbackExtension(rateUrl, tone = "soft") {
             ...ASK[tone].extensionExtras,
             rate: `GET ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully`,
             outcome: ["fully", "partially", "no"],
-            issue: { when: "The outcome is not fully. Tells the merchant what to fix.", values: Object.keys(ISSUES) },
             feedback_id: `In the paid response body (${FEEDBACK_FIELD}.feedback_id) and the Forge-Feedback-Id header.`,
             payment: "None. Plain GET, not an x402 endpoint.",
         },
@@ -65,7 +64,6 @@ export function receiptExtension(rateUrl, feedbackId, tone = "soft") {
             feedback_id: feedbackId,
             rate: `GET ${rateUrl}?feedback_id=${feedbackId}&outcome=fully`,
             outcome: ["fully", "partially", "no"],
-            issue: { when: "The outcome is not fully. Tells the merchant what to fix.", values: Object.keys(ISSUES) },
             payment: "None. Plain GET, not an x402 endpoint.",
         },
     };
@@ -138,6 +136,8 @@ function addToV2(challenge, add) {
     const extensions = challenge.extensions;
     if (add.bazaarContext && extensions && typeof extensions === "object" && addContextToBazaar(extensions.bazaar, add.bazaarContext))
         changed = true;
+    if (add.bazaarFeedback && extensions && typeof extensions === "object" && addFeedbackToBazaar(extensions.bazaar, FEEDBACK_FIELD, add.bazaarFeedback))
+        changed = true;
     return changed;
 }
 /**

package/package.json

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