@forgeintel/sdk 0.5.0-beta.1 → 0.5.0-beta.10

package/dist/openapi.d.ts

@@ -2,10 +2,10 @@ 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 optional agent context. */
+    /** Disable all feedback additions while retaining enabled agent context. */
     feedback?: boolean;
-    /** Merchant public origin, e.g. https://api.example.com */
-    publicUrl: string;
+    /** Optional merchant public origin. Without it, feedback links use same-origin paths. */
+    publicUrl?: string;
     /** Public path of the feedback routes, e.g. /feedback */
     basePath: string;
     /** Sentence appended to x-guidance and paid operation descriptions. */
@@ -18,9 +18,10 @@ export interface EnrichOptions {
     describeOperations?: boolean;
     /** Also document the optional rate_this_call body field (when the SDK's rateHint is on). */
     hintField?: boolean;
-    /** Document optional agent context on paid operations: `agent_context` in JSON request bodies, agent_* query parameters otherwise. */
+    /** Document agent context on paid operations: `agent_context` in JSON request bodies, agent_* query parameters otherwise. */
     agentContext?: {
         searchQuery: boolean;
+        required?: boolean;
     };
 }
 export interface OperationReport {
@@ -29,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 optional agent context was documented, if asked to. */
+    /** Where enabled agent context was documented, if asked to. */
     agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }

package/dist/openapi.js

@@ -3,6 +3,7 @@
 // and on any unexpected input return the original document unchanged.
 import { CONTEXT_FIELD, agentContextParameters, agentContextSchema } from "./context.js";
 import { FEEDBACK_ID_PATTERN } from "./id.js";
+import { FEEDBACK_FIELD } from "./x402.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL } from "./values.js";
 const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
 const ANNOTATIONS = new Set(["$ref", "description", "title", "summary", "example", "examples", "deprecated", "readOnly", "writeOnly", "$comment"]);
@@ -38,16 +39,23 @@ function resolveRef(doc, ref) {
 }
 function feedbackProperties(rateUrl, hintField = false) {
     return {
-        ...(hintField ? { rate_this_call: { type: "string", description: "How to rate this paid call in one free request." } } : {}),
-        feedback_id: {
-            type: "string",
-            pattern: FEEDBACK_ID_PATTERN.source,
-            description: "Rating ID for this paid call (also sent as the Forge-Feedback-Id header). See x-forge-feedback.",
-        },
-        feedback_url: {
-            type: "string",
-            format: "uri",
-            description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
+        [FEEDBACK_FIELD]: {
+            type: "object",
+            description: "Added by Forge to paid responses: how to rate this call. See x-forge-feedback.",
+            required: ["feedback_id", "rate"],
+            properties: {
+                feedback_id: {
+                    type: "string",
+                    pattern: FEEDBACK_ID_PATTERN.source,
+                    description: "Rating ID for this paid call (also sent as the Forge-Feedback-Id header).",
+                },
+                rate: {
+                    type: "string",
+                    format: "uri-reference",
+                    description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
+                },
+                ...(hintField ? { rate_this_call: { type: "string", description: "How to rate this paid call in one free request." } } : {}),
+            },
         },
     };
 }
@@ -100,8 +108,9 @@ function extendSchema(doc, schema, props) {
     return { schema: copy };
 }
 const BODYLESS = new Set(["get", "head", "delete", "options", "trace"]);
-/** Document optional agent context on one paid operation. Never required; skipped when a schema can't take it safely. */
+/** 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) };
@@ -115,8 +124,8 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         if (!params.length)
             return notAdded("parameter_collision");
         const documented = params.map((p) => version === "2.0"
-            ? { name: p.name, in: "query", required: false, description: p.description, ...p.schema }
-            : { name: p.name, in: "query", required: false, description: p.description, schema: p.schema });
+            ? { name: p.name, in: "query", required: !!opts.required && p.name !== "agent_type_other", description: p.description, ...p.schema }
+            : { name: p.name, in: "query", required: !!opts.required && p.name !== "agent_type_other", description: p.description, schema: p.schema });
         op.parameters = [...(Array.isArray(op.parameters) ? op.parameters : []), ...documented];
         report.agentContext = "query";
         return;
@@ -130,6 +139,10 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         const result = extendSchema(doc, param.schema, props);
         if ("reason" in result)
             return notAdded(result.reason);
+        if (opts.required) {
+            result.schema.required = [...new Set([...(Array.isArray(result.schema.required) ? result.schema.required : []), CONTEXT_FIELD])];
+            param.required = true;
+        }
         param.schema = result.schema;
         op.parameters = params.map((p, i) => (i === index ? param : p)); // inline copy if it was a shared $ref
         report.agentContext = "body";
@@ -146,8 +159,12 @@ function addAgentContext(doc, version, item, method, op, opts, report) {
         const result = extendSchema(doc, entry.schema, props);
         if ("reason" in result)
             return notAdded(result.reason);
+        if (opts.required)
+            result.schema.required = [...new Set([...(Array.isArray(result.schema.required) ? result.schema.required : []), CONTEXT_FIELD])];
         entry.schema = result.schema;
     }
+    if (opts.required)
+        copy.required = true;
     op.requestBody = copy; // inline copy if it was a shared $ref
     report.agentContext = "body";
 }
@@ -161,20 +178,21 @@ function appendSentence(text, sentence, marker) {
 }
 /** Work out the path prefix document paths are relative to, and whether it's this service's origin. */
 function serverBase(doc, version, publicUrl) {
-    const origin = new URL(publicUrl).origin;
+    const origin = publicUrl ? new URL(publicUrl).origin : undefined;
+    const baseUrl = publicUrl ?? "https://forge.invalid";
     try {
         if (version === "2.0") {
-            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(publicUrl).protocol.slice(0, -1);
+            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(baseUrl).protocol.slice(0, -1);
             const base = typeof doc.basePath === "string" ? doc.basePath : "";
-            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", publicUrl);
-            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", baseUrl);
+            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
         }
         const server = Array.isArray(doc.servers) ? doc.servers[0] : undefined;
         if (!isObj(server) || typeof server.url !== "string")
             return { prefix: "", sameOrigin: true };
         const raw = server.url.replace(/\{([^}]+)\}/g, (_, name) => server.variables?.[name]?.default ?? "");
-        const url = new URL(raw, publicUrl);
-        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+        const url = new URL(raw, baseUrl);
+        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
     }
     catch {
         return { prefix: "", sameOrigin: false };
@@ -253,7 +271,7 @@ export function enrichOpenApi(input, options) {
     }
     try {
         const doc = clone(original);
-        const origin = new URL(options.publicUrl).origin;
+        const origin = options.publicUrl ? new URL(options.publicUrl).origin : "";
         const base = options.basePath.replace(/\/+$/, "");
         const rateUrl = `${origin}${base}/rate`;
         const formUrl = `${origin}${base}`;
@@ -368,7 +386,7 @@ export function enrichOpenApi(input, options) {
         }
         else {
             const ops = feedbackOperations(version, formUrl, rateUrl, operationIds);
-            const servers = inPrefix ? {} : { servers: [{ url: origin }] };
+            const servers = inPrefix ? {} : { servers: [{ url: origin || "/" }] };
             paths[docBase] = { ...servers, get: ops.form, post: ops.submit };
             paths[`${docBase}/rate`] = { ...servers, get: ops.rate };
             paths[`${docBase}/summary`] = { ...servers, get: ops.summary };

package/dist/x402.d.ts

@@ -1,14 +1,23 @@
 import { type Tone } from "./ask.js";
+import type { ContextOptions } from "./context.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 declare const FEEDBACK_EXTENSION = "forge-feedback";
+/** Key of the object the SDK adds to paid JSON response bodies: feedback_id, rate, and optionally rate_this_call. */
+export declare const FEEDBACK_FIELD = "forge_feedback";
+/**
+ * The service origin a challenge was issued for: v2 `resource.url` (header or body), or v1 `accepts[].resource`.
+ * Used for absolute rating links when no origin is configured or registered. Never throws.
+ */
+export declare function challengeOrigin(challenge: string | unknown): string | undefined;
+/** The service origin a payment was made for (x402 v2 `resource.url` in the payment header). Never throws. */
+export declare function paymentOrigin(headerValue: string): string | undefined;
 /**
  * The `forge-feedback` challenge extension: how to rate the call, as structured data. Clients that inspect
  * the 402 (e.g. `awal x402 details`) print every extension, so this reaches agents before they pay.
- * With `agentContext`, it also says how to report agent context with the paid request.
+ * Agent context is a separate switch with its own extension (`forge-agent-context`).
  */
-export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentContext?: string): {
+export declare function feedbackExtension(rateUrl: string, tone?: Tone): {
     info: {
-        agent_context?: string | undefined;
         rate: string;
         outcome: string[];
         issue: {
@@ -18,14 +27,14 @@ export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentCon
         feedback_id: string;
         payment: string;
         protocol: string;
-        ask: string;
+        about: string;
     };
 };
 /** The receipt extension: the same ask, with the real feedback ID, in the settlement response after payment. */
 export declare function receiptExtension(rateUrl: string, feedbackId: string, tone?: Tone): {
     info: {
         protocol: string;
-        ask: string;
+        about: string;
         feedback_id: string;
         rate: string;
         outcome: string[];
@@ -42,21 +51,30 @@ export declare function receiptExtension(rateUrl: string, feedbackId: string, to
  * Returns undefined when the header can't be parsed, settlement failed, or the extension is already there.
  */
 export declare function describeReceipt(headerValue: string, extension: unknown): string | undefined;
+/**
+ * The longest challenge description the SDK produces. Clients copy the description into the payment payload,
+ * and the CDP facilitator rejects a payload whose resource.description exceeds 500 characters, failing the payment.
+ */
+export declare const MAX_DESCRIPTION = 500;
 /** What the SDK adds to a challenge. Each part is skipped when already present. */
 export interface ChallengeAdditions {
     /** Appended to the description (v2 resource.description, v1 accepts[].description). */
     sentence?: string;
+    /** Appended instead when `sentence` would pass MAX_DESCRIPTION; the description is left alone when this doesn't fit either. */
+    shortSentence?: string;
     /** Idempotency marker for the sentence. Default: the sentence itself. */
     marker?: string;
     /** Added as extensions["forge-feedback"] (v2 only; v1 challenges have no extensions). */
     extension?: unknown;
-    /** Independent context prompt when feedback is disabled. */
+    /** Added as extensions["forge-agent-context"] whenever agent context is enabled, independent of feedback. */
     contextExtension?: unknown;
+    /** Declare agent context in the merchant's `bazaar` extension (schema and example together). */
+    bazaarContext?: ContextOptions;
 }
 /**
- * Add the rating sentence and/or the forge-feedback extension to a base64 PAYMENT-REQUIRED header (x402 v2).
- * `accepts` is untouched: v2 matches payments on `accepts`, and @x402/core only checks echoed extensions
- * the server itself advertised, so an added extension doesn't affect payment.
+ * Add the rating sentence, Forge's extensions and Bazaar agent context to a base64 PAYMENT-REQUIRED header (x402 v2).
+ * `accepts` is untouched: v2 matches payments on `accepts`. @x402/core checks that each echoed extension's `info`
+ * contains what the server advertised, so added extensions and added Bazaar fields don't affect payment.
  * Returns undefined when the header can't be parsed or already has everything.
  */
 export declare function describeChallenge(headerValue: string, additions: ChallengeAdditions): string | undefined;

package/dist/x402.js

@@ -1,24 +1,58 @@
 import { ASK } from "./ask.js";
+import { addContextToBazaar } from "./bazaar.js";
 import { ISSUES, 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, rate, and optionally rate_this_call. */
+export const FEEDBACK_FIELD = "forge_feedback";
+const originOf = (url) => {
+    try {
+        const parsed = new URL(String(url));
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The service origin a challenge was issued for: v2 `resource.url` (header or body), or v1 `accepts[].resource`.
+ * Used for absolute rating links when no origin is configured or registered. Never throws.
+ */
+export function challengeOrigin(challenge) {
+    try {
+        const value = typeof challenge === "string" ? JSON.parse(Buffer.from(challenge, "base64").toString("utf8")) : challenge;
+        const resource = value?.resource?.url ?? (Array.isArray(value?.accepts) ? value.accepts[0]?.resource : undefined);
+        return originOf(resource);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The service origin a payment was made for (x402 v2 `resource.url` in the payment header). Never throws. */
+export function paymentOrigin(headerValue) {
+    try {
+        return originOf(JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"))?.resource?.url);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * The `forge-feedback` challenge extension: how to rate the call, as structured data. Clients that inspect
  * the 402 (e.g. `awal x402 details`) print every extension, so this reaches agents before they pay.
- * With `agentContext`, it also says how to report agent context with the paid request.
+ * Agent context is a separate switch with its own extension (`forge-agent-context`).
  */
-export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
+export function feedbackExtension(rateUrl, tone = "soft") {
     return {
         info: {
             protocol: PROTOCOL,
-            ask: ASK[tone].extensionAsk,
+            about: ASK[tone].extensionAsk,
             ...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_id) and the Forge-Feedback-Id header.",
+            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.",
-            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
@@ -27,7 +61,7 @@ export function receiptExtension(rateUrl, feedbackId, tone = "soft") {
     return {
         info: {
             protocol: PROTOCOL,
-            ask: ASK[tone].extensionAsk,
+            about: ASK[tone].extensionAsk,
             feedback_id: feedbackId,
             rate: `GET ${rateUrl}?feedback_id=${feedbackId}&outcome=fully`,
             outcome: ["fully", "partially", "no"],
@@ -57,16 +91,31 @@ export function describeReceipt(headerValue, extension) {
     receipt.extensions = { ...extensions, [FEEDBACK_EXTENSION]: extension };
     return Buffer.from(JSON.stringify(receipt), "utf8").toString("base64");
 }
-function appendSentence(description, sentence, marker) {
+/**
+ * The longest challenge description the SDK produces. Clients copy the description into the payment payload,
+ * and the CDP facilitator rejects a payload whose resource.description exceeds 500 characters, failing the payment.
+ */
+export const MAX_DESCRIPTION = 500;
+function appendSentence(description, sentence, marker, shortSentence) {
     const current = typeof description === "string" ? description.trim() : "";
-    return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;
+    if (current.includes(marker))
+        return current;
+    for (const candidate of [sentence, shortSentence]) {
+        if (!candidate)
+            continue;
+        const next = current ? `${current} ${candidate}` : candidate;
+        if (next.length <= MAX_DESCRIPTION)
+            return next;
+    }
+    // Nothing fits: the forge-feedback extension still carries the ask.
+    return current;
 }
 /** Apply additions to a v2 PaymentRequired in place. Returns whether anything changed. */
 function addToV2(challenge, add) {
     let changed = false;
     const resource = challenge.resource;
     if (add.sentence && resource && typeof resource === "object") {
-        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence);
+        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence, add.shortSentence);
         if (next !== resource.description) {
             resource.description = next;
             changed = true;
@@ -81,17 +130,20 @@ function addToV2(challenge, add) {
             changed = true;
         }
         else if (typeof extensions === "object" && !Array.isArray(extensions) && !(key in extensions)) {
-            // Added last, so the merchant's own extensions (e.g. bazaar) keep their order and content.
+            // Added last, so the merchant's own extensions (e.g. bazaar) keep their order.
             challenge.extensions = { ...extensions, [key]: extension };
             changed = true;
         }
     }
+    const extensions = challenge.extensions;
+    if (add.bazaarContext && extensions && typeof extensions === "object" && addContextToBazaar(extensions.bazaar, add.bazaarContext))
+        changed = true;
     return changed;
 }
 /**
- * Add the rating sentence and/or the forge-feedback extension to a base64 PAYMENT-REQUIRED header (x402 v2).
- * `accepts` is untouched: v2 matches payments on `accepts`, and @x402/core only checks echoed extensions
- * the server itself advertised, so an added extension doesn't affect payment.
+ * Add the rating sentence, Forge's extensions and Bazaar agent context to a base64 PAYMENT-REQUIRED header (x402 v2).
+ * `accepts` is untouched: v2 matches payments on `accepts`. @x402/core checks that each echoed extension's `info`
+ * contains what the server advertised, so added extensions and added Bazaar fields don't affect payment.
  * Returns undefined when the header can't be parsed or already has everything.
  */
 export function describeChallenge(headerValue, additions) {
@@ -124,7 +176,7 @@ export function describeChallengeBody(body, additions) {
         const marker = additions.marker ?? sentence;
         return {
             ...b,
-            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker) } : a),
+            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker, additions.shortSentence) } : a),
         };
     }
     if (b.x402Version === 2 && b.resource && typeof b.resource === "object") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.1",
-  "description": "The Forge SDK for x402 paid APIs: agent feedback (feedback IDs, one-request GET ratings), agent context, OpenAPI and challenge enrichment, and passive call signals. Express, Hono, Next.js and any fetch handler. Never on your critical path.",
+  "version": "0.5.0-beta.10",
+  "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.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -73,7 +73,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "peerDependencies": {
     "express": ">=4.21 <6",