@forgeintel/sdk 0.2.0-beta.0 → 0.4.0-beta.0

package/dist/next.js

@@ -0,0 +1,30 @@
+import { createForge as createForgeFetch } from "./fetch.js";
+/**
+ * Rebuild a forwarded Request as the original's class (NextRequest), so handlers and withX402 still get
+ * `nextUrl` and friends. Next isn't imported: the constructor comes from the request itself.
+ */
+function sameKind(original, forwarded) {
+    const Kind = original.constructor;
+    return Kind === Request ? forwarded : new Kind(forwarded);
+}
+export function createForge(options) {
+    const forge = createForgeFetch(options);
+    const own = async (request) => (await forge.route(request)) ?? new Response(JSON.stringify({ error: "not_found" }), { status: 404, headers: { "Content-Type": "application/json" } });
+    return {
+        enabled: forge.enabled,
+        challengeSentence: forge.challengeSentence,
+        enrichOpenApi: forge.enrichOpenApi,
+        diagnostics: forge.diagnostics,
+        shutdown: forge.shutdown,
+        handle: forge.handle,
+        withForge: (handler) => (request, context) => forge.handle(request, (forwarded) => handler(forwarded === request ? request : sameKind(request, forwarded), context)),
+        routes: { GET: own, POST: own, HEAD: own },
+        proxy: (proxy) => async (request) => {
+            const response = await proxy(request);
+            // Only the 402: the proxy passes paid requests on to the route, where withForge mints the feedback ID.
+            if (response.status !== 402 || !forge.enabled)
+                return response;
+            return forge.handle(request, () => response);
+        },
+    };
+}

package/dist/openapi.d.ts

@@ -16,6 +16,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. */
+    agentContext?: {
+        searchQuery: boolean;
+    };
 }
 export interface OperationReport {
     method: string;
@@ -23,6 +27,8 @@ 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. */
+    agentContext?: "body" | "query" | "not_added";
     reasons: string[];
 }
 export interface EnrichReport {

package/dist/openapi.js

@@ -1,6 +1,7 @@
 // Additive, idempotent OpenAPI enrichment for Swagger 2.0 and OpenAPI 3.0 / 3.1 / 3.2.
 // Rules: never mutate the input, never modify a shared $ref target, never override merchant paths,
 // 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 { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL } from "./values.js";
 const METHODS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
@@ -98,6 +99,58 @@ function extendSchema(doc, schema, props) {
     copy.properties = { ...(isObj(copy.properties) ? copy.properties : {}), ...clone(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. */
+function addAgentContext(doc, version, item, method, op, opts, report) {
+    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) };
+    const notAdded = (reason) => {
+        report.agentContext = "not_added";
+        report.reasons.push(`request: ${reason}`);
+    };
+    if (BODYLESS.has(method)) {
+        const taken = new Set(listed.filter((p) => p.in === "query").map((p) => p.name));
+        const params = agentContextParameters(opts).filter((p) => !taken.has(p.name));
+        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 });
+        op.parameters = [...(Array.isArray(op.parameters) ? op.parameters : []), ...documented];
+        report.agentContext = "query";
+        return;
+    }
+    if (version === "2.0") {
+        const params = Array.isArray(op.parameters) ? op.parameters : [];
+        const index = params.findIndex((p) => resolve(p)?.in === "body");
+        if (index < 0)
+            return notAdded("no_request_body");
+        const param = clone(resolve(params[index]));
+        const result = extendSchema(doc, param.schema, props);
+        if ("reason" in result)
+            return notAdded(result.reason);
+        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";
+        return;
+    }
+    const body = resolve(op.requestBody);
+    if (!isObj(body) || !isObj(body.content))
+        return notAdded("no_request_body");
+    const copy = clone(body);
+    const media = Object.entries(copy.content).filter(([type, entry]) => isJsonMedia(type) && isObj(entry) && "schema" in entry);
+    if (!media.length)
+        return notAdded("no_json_request_body");
+    for (const [, entry] of media) {
+        const result = extendSchema(doc, entry.schema, props);
+        if ("reason" in result)
+            return notAdded(result.reason);
+        entry.schema = result.schema;
+    }
+    op.requestBody = copy; // inline copy if it was a shared $ref
+    report.agentContext = "body";
+}
 const isJsonMedia = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type);
 const is2xx = (code) => /^2(\d\d|XX)$/i.test(code);
 function appendSentence(text, sentence, marker) {
@@ -280,6 +333,8 @@ export function enrichOpenApi(input, options) {
                     op.responses[code] = response; // inline copy if it was a shared $ref
                     opReport.responses[code] = "extended";
                 }
+                if (options.agentContext)
+                    addAgentContext(doc, version, item, method, op, options.agentContext, opReport);
                 // agentcash-style payment metadata carries its own output schema.
                 const info = op["x-payment-info"];
                 if (isObj(info) && isObj(info.outputSchema)) {

package/dist/reporter.d.ts

@@ -1,8 +1,10 @@
+import type { AgentContext } from "./context.js";
 export type ForgeEvent = {
     type: "challenge";
     route: string;
     ts: number;
     user_agent?: string;
+    agent_context?: AgentContext;
 } | {
     type: "interaction";
     feedback_id: string;
@@ -12,7 +14,12 @@ export type ForgeEvent = {
     payer?: string;
     network?: string;
     amount?: string;
+    scheme?: string;
+    asset?: string;
+    /** Settlement transaction reference from the receipt. */
+    transaction?: string;
     user_agent?: string;
+    agent_context?: AgentContext;
     ts: number;
 };
 /** Batches events to the backend in the background. Drops the oldest events if the backend stays down. */

package/dist/x402.d.ts

@@ -1,19 +1,39 @@
-/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+import { type Tone } from "./ask.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";
 /**
  * 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.
  */
-export declare function feedbackExtension(rateUrl: string): {
+export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentContext?: string): {
     info: {
+        agent_context?: string | undefined;
+        rate: string;
+        outcome: string[];
+        feedback_id: string;
+        payment: string;
         protocol: string;
         ask: 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;
+        feedback_id: string;
         rate: string;
         outcome: string[];
-        feedback_id: string;
         payment: string;
     };
 };
+/**
+ * Add the receipt extension to a base64 PAYMENT-RESPONSE header (x402 v2 settlement response), only when
+ * settlement succeeded. The receipt is informational for the client: facilitator fields are untouched.
+ * 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;
 /** 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). */
@@ -40,6 +60,12 @@ export interface PaymentFacts {
     payer?: string;
     network?: string;
     amount?: string;
+    scheme?: string;
+    asset?: string;
+    /** Settlement transaction reference, from the receipt (see readReceipt). */
+    transaction?: string;
 }
-/** Best-effort read of the payer, network and amount from an x402 v1/v2 payment header. Never throws. */
+/** Best-effort read of the payer, network, amount, scheme and asset from an x402 v1/v2 payment header. Never throws. */
 export declare function readPaymentHeader(headerValue: string): PaymentFacts;
+/** Best-effort read of a successful settlement receipt (base64 PAYMENT-RESPONSE): transaction, payer, network. Never throws. */
+export declare function readReceipt(headerValue: string): Pick<PaymentFacts, "transaction" | "payer" | "network">;

package/dist/x402.js

@@ -1,22 +1,60 @@
+import { ASK } from "./ask.js";
 import { PROTOCOL } from "./values.js";
-/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+/** 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";
 /**
  * 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.
  */
-export function feedbackExtension(rateUrl) {
+export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
     return {
         info: {
             protocol: PROTOCOL,
-            ask: "After your call, please rate this service for other agents. Free, one request.",
+            ask: ASK[tone].extensionAsk,
+            ...ASK[tone].extensionExtras,
             rate: `GET ${rateUrl}?feedback_id=FEEDBACK_ID&outcome=fully`,
             outcome: ["fully", "partially", "no"],
             feedback_id: "In the paid response body (feedback_id) and the Forge-Feedback-Id header.",
             payment: "None. Plain GET, not an x402 endpoint.",
+            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
+/** The receipt extension: the same ask, with the real feedback ID, in the settlement response after payment. */
+export function receiptExtension(rateUrl, feedbackId, tone = "soft") {
+    return {
+        info: {
+            protocol: PROTOCOL,
+            ask: ASK[tone].extensionAsk,
+            feedback_id: feedbackId,
+            rate: `GET ${rateUrl}?feedback_id=${feedbackId}&outcome=fully`,
+            outcome: ["fully", "partially", "no"],
+            payment: "None. Plain GET, not an x402 endpoint.",
+        },
+    };
+}
+/**
+ * Add the receipt extension to a base64 PAYMENT-RESPONSE header (x402 v2 settlement response), only when
+ * settlement succeeded. The receipt is informational for the client: facilitator fields are untouched.
+ * Returns undefined when the header can't be parsed, settlement failed, or the extension is already there.
+ */
+export function describeReceipt(headerValue, extension) {
+    let receipt;
+    try {
+        receipt = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!receipt || typeof receipt !== "object" || receipt.success !== true)
+        return undefined;
+    const extensions = receipt.extensions;
+    if (extensions !== undefined && extensions !== null && (typeof extensions !== "object" || Array.isArray(extensions) || FEEDBACK_EXTENSION in extensions))
+        return undefined;
+    receipt.extensions = { ...extensions, [FEEDBACK_EXTENSION]: extension };
+    return Buffer.from(JSON.stringify(receipt), "utf8").toString("base64");
+}
 function appendSentence(description, sentence, marker) {
     const current = typeof description === "string" ? description.trim() : "";
     return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;
@@ -91,7 +129,7 @@ export function describeChallengeBody(body, additions) {
     }
     return undefined;
 }
-/** Best-effort read of the payer, network and amount from an x402 v1/v2 payment header. Never throws. */
+/** Best-effort read of the payer, network, amount, scheme and asset from an x402 v1/v2 payment header. Never throws. */
 export function readPaymentHeader(headerValue) {
     try {
         const p = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
@@ -100,6 +138,8 @@ export function readPaymentHeader(headerValue) {
             payer: authorization?.from,
             network: p?.accepted?.network ?? p?.network,
             amount: p?.accepted?.amount ?? authorization?.value,
+            scheme: p?.accepted?.scheme ?? p?.scheme,
+            asset: p?.accepted?.asset,
         };
         for (const key of Object.keys(facts)) {
             if (typeof facts[key] !== "string")
@@ -111,3 +151,20 @@ export function readPaymentHeader(headerValue) {
         return {};
     }
 }
+/** Best-effort read of a successful settlement receipt (base64 PAYMENT-RESPONSE): transaction, payer, network. Never throws. */
+export function readReceipt(headerValue) {
+    try {
+        const r = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+        if (r?.success !== true)
+            return {};
+        const facts = { transaction: r.transaction, payer: r.payer, network: r.network };
+        for (const key of Object.keys(facts)) {
+            if (typeof facts[key] !== "string" || !facts[key])
+                delete facts[key];
+        }
+        return facts;
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.2.0-beta.0",
-  "description": "The Forge SDK for x402 paid APIs: agent feedback (feedback IDs, one-request GET ratings), OpenAPI and challenge enrichment, and passive call signals. Express adapter plus a framework-free core. Never on your critical path.",
+  "version": "0.4.0-beta.0",
+  "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.",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -23,6 +23,21 @@
       "import": "./dist/core.js",
       "default": "./dist/core.js"
     },
+    "./fetch": {
+      "types": "./dist/fetch.d.ts",
+      "import": "./dist/fetch.js",
+      "default": "./dist/fetch.js"
+    },
+    "./hono": {
+      "types": "./dist/hono.d.ts",
+      "import": "./dist/hono.js",
+      "default": "./dist/hono.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "import": "./dist/next.js",
+      "default": "./dist/next.js"
+    },
     "./package.json": "./package.json"
   },
   "types": "./dist/index.d.ts",
@@ -40,7 +55,11 @@
     "openapi",
     "express",
     "payments",
-    "forge"
+    "forge",
+    "hono",
+    "nextjs",
+    "cloudflare-workers",
+    "bun"
   ],
   "repository": {
     "type": "git",
@@ -57,25 +76,24 @@
     "tag": "beta"
   },
   "peerDependencies": {
-    "express": ">=4.21 <6"
+    "express": ">=4.21 <6",
+    "hono": ">=4"
   },
   "peerDependenciesMeta": {
     "express": {
       "optional": true
+    },
+    "hono": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@apidevtools/swagger-parser": "^12.1.0",
     "@types/express": "^5.0.3",
     "@types/node": "^22.18.0",
-    "@x402/core": "~2.25.0",
-    "@x402/evm": "~2.25.0",
-    "@x402/express": "~2.25.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "express": "^5.2.1",
-    "typescript": "^5.9.2",
-    "viem": "^2.56.3",
-    "x402-express": "^1.2.0"
+    "hono": "^4.13.7",
+    "typescript": "^5.9.2"
   }
 }