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

package/README.md

@@ -10,8 +10,8 @@ The Forge SDK for x402 paid APIs. Paid responses carry a `feedback_id`, the 402
 import { createForge } from "@forgeintel/sdk";
 
 const forge = createForge({
-  apiKey: process.env.FORGE_FEEDBACK_KEY,    // from the Forge backend
-  backendUrl: process.env.FORGE_BACKEND_URL, // your Forge backend
+  apiKey: process.env.FORGE_API_KEY,         // from your Forge project's Agents page
+  backendUrl: process.env.FORGE_BACKEND_URL, // Forge: <API origin>/api/sdk/v2
   publicUrl: "https://api.example.com",      // your public origin (never taken from the Host header)
 });
 
@@ -19,7 +19,33 @@ app.use(forge.middleware());                        // 1. first: before payments
 app.use(paymentMiddleware(routes, resourceServer)); // 2. your existing x402 setup, unchanged
 ```
 
-Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5.
+Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5. The root export is the Express adapter (also at `@forgeintel/sdk/express`).
+
+## Hono (Node, Bun, Deno, Cloudflare Workers)
+
+```ts
+import { createForge } from "@forgeintel/sdk/hono";
+
+const forge = createForge({ apiKey, backendUrl, publicUrl });
+app.use(forge.middleware());                        // before paymentMiddleware from @x402/hono
+app.use(paymentMiddleware(routes, resourceServer));
+```
+
+## Next.js (App Router)
+
+```ts
+import { createForge } from "@forgeintel/sdk/next";
+
+export const forge = createForge({ apiKey, backendUrl, publicUrl });
+// 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
+export const { GET, POST, HEAD } = forge.routes;
+```
+
+## Any fetch handler
+
+`@forgeintel/sdk/fetch`: `export default { fetch: forge.wrap(handler) }`, or `forge.handle(request, next)` per request.
 
 ## Any other framework
 
@@ -37,7 +63,9 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 | `GET /feedback/rate` | Quick rating: `feedback_id`, `outcome`, optional `issue`. |
 | `POST /feedback` | Same fields, plus an optional `note` (≤ 280 chars). |
 | `GET /feedback`, `GET /feedback/summary` | The form description, and public aggregate ratings. |
-| Every 402 and paid call | Sends a challenge or interaction event to the backend in the background. |
+| Payment receipt (v2) | Adds the `forge-feedback` extension, with the real ID, to the `PAYMENT-RESPONSE` settlement header. |
+| Paid request | Reads the agent's self-reported `agent_context` (JSON body) or `agent_*` query parameters, and removes them before your code runs. |
+| Every 402 and paid call | Sends a challenge or interaction event (with any agent context) to the backend in the background. |
 
 IDs are minted locally with an HMAC, so the paid path makes no network call. If the backend is down, paid calls still work, and ratings return `503 feedback_unavailable`.
 
@@ -59,9 +87,12 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `backendUrl` | required | Forge backend origin. |
 | `publicUrl` | required | This service's public origin. Used in rating URLs. |
 | `basePath` | `/feedback` | Feedback routes (`/feedback`, `/feedback/rate`, `/feedback/summary`). |
+| `tone` | `"soft"` | `"lifecycle"` describes this service's flow as four steps (402, pay, response, rate). Both stay soft asks. |
 | `describeChallenges` | `true` | Append the sentence to 402 challenges. |
-| `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. |
+| `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. Wording that presents the rating as required, makes anything depend on it, or asks for user data is refused (with a warning). |
 | `challengeExtension` | `true` | Add the `forge-feedback` extension to x402 v2 challenges. |
+| `receiptExtension` | `true` | Add it, with the real `feedback_id`, to the x402 v2 payment receipt (`PAYMENT-RESPONSE`). |
+| `agentContext` | `true` | Ask for self-reported `agent_context` (agent, client, search query), record it, and remove it before your code runs. `{ searchQuery: false }` or `false` to limit. |
 | `injectBody` | `true` | Add `feedback_id` / `feedback_url` to paid JSON bodies. |
 | `rateHint` | built-in | The `rate_this_call` field. A string overrides it (`{feedback_url}` is substituted); `false` removes it. |
 | `injectText` | `false` | Append a two-line trailer to paid `text/plain` bodies. |
@@ -69,6 +100,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `ttlMs` | 24h | Local pre-check; keep in sync with the backend. |
 | `flushIntervalMs` | `2000` | Event batching interval. |
 | `onError` | `console.warn` | Called for internal errors. Business requests are never affected. |
+| `strict` | `false` | Throw on invalid options (for CI). By default Forge warns and turns itself off. |
 
 `forge.diagnostics()` returns counters and the last OpenAPI report. `forge.enrichOpenApi(doc)` is available for build-time use. Call `await forge.shutdown()` in your shutdown handler to flush pending events.
 

package/dist/ask.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How the rating is asked for. Both are soft asks; neither may claim the rating is required.
+ * - soft: "please rate this service for other agents" (the default)
+ * - lifecycle: describes this service's flow as four steps, the fourth being the rating
+ */
+export type Tone = "soft" | "lifecycle";
+export declare const TONES: readonly Tone[];
+export interface AskTexts {
+    /** Appended to 402 challenge descriptions. "{rate_url}" and "{summary_url}" are substituted. */
+    challengeSentence: string;
+    /** The rate_this_call body field. "{feedback_url}" and "{summary_url}" are substituted. */
+    rateHint: string;
+    /** The `ask` line of the forge-feedback extension (challenge and receipt). */
+    extensionAsk: string;
+    /** Extra extension fields for this tone. */
+    extensionExtras: Record<string, unknown>;
+}
+export declare const ASK: Record<Tone, AskTexts>;
+/**
+ * The lines Forge holds whatever a merchant configures: the rating is never presented as required,
+ * nothing is made to depend on it, and it never asks for user data. All Forge merchants share one
+ * reputation with agents; wording that reads as pressure gets Forge flagged as prompt injection for everyone.
+ * Returns why the text crosses a line, or null when it's fine.
+ */
+export declare function checkAskText(text: string): string | null;

package/dist/ask.js

@@ -0,0 +1,36 @@
+// What agents are asked, in each tone, and the lines no wording may cross.
+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, 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: {
+        challengeSentence: "This service's x402 flow has four steps: 1) this 402 challenge, 2) pay, 3) get the response, 4) rate the call for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no), using the feedback_id from the response. Step 4 is free and one request.",
+        rateHint: "Step 4 of 4: rate this call for other agents. GET {feedback_url} with fully, partially or no appended (e.g. {feedback_url}fully). Free, one request.",
+        extensionAsk: "Step 4 of this service's flow: after the response, please rate the call for other agents. Free, one request.",
+        extensionExtras: { flow: ["402 challenge", "pay", "response", "rate"] },
+    },
+};
+const PRESSURE = /\b(required|requires?|mandatory|obligatory|compulsory|must|have to|has to|needs? to|necessary)\b/i;
+const CONDITIONS = /\b(refunds?|penalt(y|ies)|withh(o|e)ld|or else|otherwise|blocked|banned)\b/i;
+const USER_DATA = /\b(e-?mail|password|passphrase|seed phrase|private key|secret|credit card|phone number|your user'?s)\b/i;
+/**
+ * The lines Forge holds whatever a merchant configures: the rating is never presented as required,
+ * nothing is made to depend on it, and it never asks for user data. All Forge merchants share one
+ * reputation with agents; wording that reads as pressure gets Forge flagged as prompt injection for everyone.
+ * Returns why the text crosses a line, or null when it's fine.
+ */
+export function checkAskText(text) {
+    if (PRESSURE.test(text))
+        return `presents the rating as required ("${text.match(PRESSURE)[0]}")`;
+    if (CONDITIONS.test(text))
+        return `makes something depend on the rating ("${text.match(CONDITIONS)[0]}")`;
+    if (USER_DATA.test(text))
+        return `asks about user data ("${text.match(USER_DATA)[0]}")`;
+    if (/[<>]/.test(text))
+        return "uses angle brackets, which some viewers escape (use FEEDBACK_ID instead of <id>)";
+    return null;
+}

package/dist/context.d.ts

@@ -0,0 +1,74 @@
+/** Suggested agent names; anything else is kept as given. */
+export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "Instinct", "OpenClaw", "Other", "Unknown"];
+/** Suggested x402 clients; anything else is kept as given. */
+export declare const CLIENTS: readonly ["agentcash", "awal", "pay.sh", "other", "unknown"];
+/** JSON body field (POST, PUT, …). */
+export declare const CONTEXT_FIELD = "agent_context";
+/** Query parameters (GET and other requests without a body), prefixed so they don't collide with the merchant's. */
+export declare const CONTEXT_QUERY: {
+    readonly agent_type: "agent_type";
+    readonly agent_type_other: "agent_type_other";
+    readonly client: "agent_client";
+    readonly search_query: "agent_search_query";
+};
+export interface AgentContext {
+    agent_type?: string;
+    agent_type_other?: string;
+    client?: string;
+    search_query?: string;
+}
+/** Lenient: bad or unknown values are dropped or kept as plain text, never rejected. Known names get their canonical case. */
+export declare function parseAgentContext(input: unknown, { searchQuery }?: {
+    searchQuery?: boolean;
+}): AgentContext | undefined;
+/** Split `agent_context` off a parsed JSON body. The body is returned as a new object; the input is untouched. */
+export declare function takeFromBody(body: unknown): {
+    body: unknown;
+    raw?: unknown;
+};
+/** Split the agent_* query parameters off a URL (path + query). Other parameters stay byte-for-byte as they were. */
+export declare function takeFromUrl(url: string): {
+    url: string;
+    raw?: Record<string, string>;
+};
+/** JSON Schema for the optional `agent_context` body property. */
+export declare function agentContextSchema({ searchQuery }?: {
+    searchQuery?: boolean;
+}): {
+    type: string;
+    description: string;
+    properties: {
+        search_query?: {
+            type: string;
+            maxLength: number;
+            description: string;
+        } | undefined;
+        agent_type: {
+            type: string;
+            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok" | "Hermes" | "Instinct" | "OpenClaw" | "Other" | "Unknown")[];
+            description: string;
+        };
+        agent_type_other: {
+            type: string;
+            maxLength: number;
+            description: string;
+        };
+        client: {
+            type: string;
+            enum: ("agentcash" | "awal" | "pay.sh" | "other" | "unknown")[];
+            description: string;
+        };
+    };
+};
+/** The optional query parameters, for operations without a request body. */
+export declare function agentContextParameters({ searchQuery }?: {
+    searchQuery?: boolean;
+}): {
+    name: string;
+    description: string;
+    schema: Record<string, unknown>;
+}[];
+/** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
+export declare function agentContextAsk({ searchQuery }?: {
+    searchQuery?: boolean;
+}): "Please add agent_context {agent_type, client, search_query} to your paid request's JSON body (without a body: agent_type, agent_client, agent_search_query query parameters). Self-reported; omit what you don't know. search_query is what you searched to find this service, never your user's request." | "Please add agent_context {agent_type, client} to your paid request's JSON body (without a body: agent_type and agent_client query parameters). Self-reported; omit what you don't know.";

package/dist/context.js

@@ -0,0 +1,117 @@
+// Agent context: optional, self-reported facts about the calling agent, sent with the paid request.
+// Forge reads it and removes it before the merchant's validators and handlers run, so the merchant's
+// API contract never changes. Never required: a required field breaks strict validators and makes
+// agents invent answers.
+/** Suggested agent names; anything else is kept as given. */
+export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "Instinct", "OpenClaw", "Other", "Unknown"];
+/** Suggested x402 clients; anything else is kept as given. */
+export const CLIENTS = ["agentcash", "awal", "pay.sh", "other", "unknown"];
+/** JSON body field (POST, PUT, …). */
+export const CONTEXT_FIELD = "agent_context";
+/** Query parameters (GET and other requests without a body), prefixed so they don't collide with the merchant's. */
+export const CONTEXT_QUERY = {
+    agent_type: "agent_type",
+    agent_type_other: "agent_type_other",
+    client: "agent_client",
+    search_query: "agent_search_query",
+};
+const LIMITS = { agent_type: 80, agent_type_other: 80, client: 80, search_query: 200 };
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Lenient: bad or unknown values are dropped or kept as plain text, never rejected. Known names get their canonical case. */
+export function parseAgentContext(input, { searchQuery = true } = {}) {
+    if (!isObj(input))
+        return undefined;
+    const context = {};
+    for (const key of Object.keys(LIMITS)) {
+        if (key === "search_query" && !searchQuery)
+            continue;
+        const raw = Array.isArray(input[key]) ? input[key][0] : input[key];
+        if (typeof raw !== "string")
+            continue;
+        const text = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, LIMITS[key]);
+        if (!text)
+            continue;
+        const known = key === "agent_type" ? AGENT_TYPES : key === "client" ? CLIENTS : null;
+        context[key] = known?.find((v) => v.toLowerCase() === text.toLowerCase()) ?? text;
+    }
+    return Object.keys(context).length ? context : undefined;
+}
+/** Split `agent_context` off a parsed JSON body. The body is returned as a new object; the input is untouched. */
+export function takeFromBody(body) {
+    if (!isObj(body) || Object.getPrototypeOf(body) !== Object.prototype || !Object.hasOwn(body, CONTEXT_FIELD))
+        return { body };
+    const { [CONTEXT_FIELD]: raw, ...rest } = body;
+    return { body: rest, raw };
+}
+/** Split the agent_* query parameters off a URL (path + query). Other parameters stay byte-for-byte as they were. */
+export function takeFromUrl(url) {
+    const q = url.indexOf("?");
+    if (q < 0)
+        return { url };
+    const hash = url.indexOf("#", q);
+    const query = url.slice(q + 1, hash < 0 ? undefined : hash);
+    const names = new Map(Object.entries(CONTEXT_QUERY).map(([k, v]) => [v, k]));
+    const raw = {};
+    const kept = [];
+    for (const segment of query.split("&")) {
+        const eq = segment.indexOf("=");
+        let key;
+        let value;
+        try {
+            key = decodeURIComponent((eq < 0 ? segment : segment.slice(0, eq)).replace(/\+/g, " "));
+            value = eq < 0 ? "" : decodeURIComponent(segment.slice(eq + 1).replace(/\+/g, " "));
+        }
+        catch {
+            kept.push(segment); // not ours if we can't even decode it
+            continue;
+        }
+        const field = names.get(key);
+        if (field) {
+            if (!(field in raw))
+                raw[field] = value;
+        }
+        else
+            kept.push(segment);
+    }
+    if (!Object.keys(raw).length)
+        return { url };
+    const rest = kept.filter(Boolean).join("&");
+    return { url: `${url.slice(0, q)}${rest ? `?${rest}` : ""}${hash < 0 ? "" : url.slice(hash)}`, raw };
+}
+const DESCRIPTIONS = {
+    object: "Self-reported context about the calling agent, so the merchant can see which agents use this service. Not needed for the result; omit anything you don't know.",
+    agent_type: "Which agent are you? Use Other (with agent_type_other) if yours isn't listed, or Unknown.",
+    agent_type_other: "Your agent's name, when agent_type is Other.",
+    client: "Which x402 client or wallet paid for this call?",
+    search_query: "The search terms you used to find this service, for example in a marketplace or search tool. Omit if you didn't search; don't invent one, and never include your user's request.",
+};
+/** JSON Schema for the optional `agent_context` body property. */
+export function agentContextSchema({ searchQuery = true } = {}) {
+    return {
+        type: "object",
+        description: DESCRIPTIONS.object,
+        properties: {
+            agent_type: { type: "string", enum: [...AGENT_TYPES], description: DESCRIPTIONS.agent_type },
+            agent_type_other: { type: "string", maxLength: LIMITS.agent_type_other, description: DESCRIPTIONS.agent_type_other },
+            client: { type: "string", enum: [...CLIENTS], description: DESCRIPTIONS.client },
+            ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, description: DESCRIPTIONS.search_query } } : {}),
+        },
+    };
+}
+/** The optional query parameters, for operations without a request body. */
+export function agentContextParameters({ searchQuery = true } = {}) {
+    const params = [
+        { name: CONTEXT_QUERY.agent_type, description: DESCRIPTIONS.agent_type, schema: { type: "string", enum: [...AGENT_TYPES] } },
+        { name: CONTEXT_QUERY.agent_type_other, description: DESCRIPTIONS.agent_type_other, schema: { type: "string", maxLength: LIMITS.agent_type_other } },
+        { name: CONTEXT_QUERY.client, description: DESCRIPTIONS.client, schema: { type: "string", enum: [...CLIENTS] } },
+    ];
+    if (searchQuery)
+        params.push({ name: CONTEXT_QUERY.search_query, description: DESCRIPTIONS.search_query, schema: { type: "string", maxLength: LIMITS.search_query } });
+    return params;
+}
+/** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
+export function agentContextAsk({ searchQuery = true } = {}) {
+    return searchQuery
+        ? "Please add agent_context {agent_type, client, search_query} to your paid request's JSON body (without a body: agent_type, agent_client, agent_search_query query parameters). Self-reported; omit what you don't know. search_query is what you searched to find this service, never your user's request."
+        : "Please add agent_context {agent_type, client} to your paid request's JSON body (without a body: agent_type and agent_client query parameters). Self-reported; omit what you don't know.";
+}

package/dist/core.d.ts

@@ -1,4 +1,5 @@
 import { type EnrichReport } from "./openapi.js";
+import { type Tone } from "./ask.js";
 export interface OpenApiOptions {
     /** Paths where your OpenAPI JSON is served. Default ["/openapi.json"]. */
     paths?: string[];
@@ -14,21 +15,48 @@ export type ForgeFeedbackOptions = ForgeOptions;
 export interface ForgeOptions {
     /** Merchant API key issued by the Forge backend. Also the HMAC key for feedback IDs. */
     apiKey: string;
-    /** Forge backend origin, e.g. https://forge-feedback.up.railway.app */
+    /**
+     * Where events and ratings go. An origin (https://backend.example.com) uses its /v1/events, /v1/feedback and
+     * /v1/summary routes; a URL with a path (https://api.forgeintel.co/api/sdk/v2) uses {path}/events, and so on.
+     */
     backendUrl: string;
     /** This service's public origin, e.g. https://pixels.gateway.clawca.sh. Never derived from the Host header. */
     publicUrl: string;
     /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
     basePath?: string;
+    /**
+     * How the rating is asked for: "soft" (default, "please rate this service for other agents") or "lifecycle"
+     * (describes this service's flow as four steps: 402, pay, response, rate). Both stay soft asks.
+     */
+    tone?: Tone;
     /** Append the rating sentence to x402 challenges (v2 header, v1 JSON body). Default true. */
     describeChallenges?: boolean;
-    /** Override the appended sentence, for wording experiments. "{rate_url}" and "{summary_url}" are substituted. */
+    /**
+     * Override the appended sentence, for wording experiments. "{rate_url}" and "{summary_url}" are substituted.
+     * Text that presents the rating as required, makes anything depend on it, or asks for user data is refused
+     * (with a warning) and the tone's default is used.
+     */
     challengeSentence?: string;
     /**
      * Add a structured `forge-feedback` extension to x402 v2 challenges (next to e.g. `bazaar`), which clients
      * that inspect the 402 print as its own block. Default true; `false` turns it off. v1 challenges have no extensions.
      */
     challengeExtension?: boolean;
+    /**
+     * Add the `forge-feedback` extension, with the real feedback_id, to the x402 v2 payment receipt
+     * (the PAYMENT-RESPONSE settlement header), so the rating follows the payment on the wire. Default true.
+     */
+    receiptExtension?: boolean;
+    /**
+     * Agent context: optional, self-reported `agent_context` {agent_type, client, search_query} on the paid request
+     * (JSON body, or agent_type / agent_client / 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. Default true. `{ 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).
+     */
+    agentContext?: boolean | {
+        searchQuery?: boolean;
+    };
     /** Add feedback_id and feedback_url to JSON object bodies of paid responses. Default true. */
     injectBody?: boolean;
     /**
@@ -80,8 +108,18 @@ export interface ForgeCall {
     json(status: number, body: unknown): unknown;
     /** A text body about to be sent: gets the two-line trailer on paid 2xx text/plain when injectText is on. */
     text(status: number, contentType: string, body: string): string;
-    /** Headers to set once the final status is known: a rewritten PAYMENT-REQUIRED on 402, Forge-Feedback-Id on paid 2xx. */
-    headers(status: number, paymentRequired: string | undefined): Record<string, string>;
+    /**
+     * Headers to set once the final status is known: a rewritten PAYMENT-REQUIRED on 402; on a paid 2xx,
+     * Forge-Feedback-Id and (when you pass the settlement header) a PAYMENT-RESPONSE with the receipt extension.
+     */
+    headers(status: number, paymentRequired: string | undefined, paymentResponse?: string): Record<string, string>;
+    /**
+     * A parsed JSON request body, before your validators and handlers see it: reads `agent_context` and returns
+     * the body without it (a new object; other fields untouched). Anything else is returned as is.
+     */
+    requestBody(body: unknown): unknown;
+    /** A request URL (path + query): reads the agent_* query parameters and returns the URL without them. */
+    requestUrl(url: string): string;
     /**
      * Report the challenge / interaction events after the response is sent. A 402 counts as a challenge when
      * headers() saw a PAYMENT-REQUIRED value or json() saw a challenge body; pass true if you know of one otherwise.