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

package/README.md

@@ -55,7 +55,7 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 
 | 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`. |

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

@@ -175,6 +175,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. */
@@ -104,7 +106,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 +118,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 {
@@ -231,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/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)
@@ -309,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.12",
+  "version": "0.5.0-beta.14",
   "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",