@forgeintel/sdk 0.5.0-beta.3 → 0.5.0-beta.5

package/README.md

@@ -1,6 +1,6 @@
 # @forgeintel/sdk
 
-> **Beta.** Install with `npm install @forgeintel/sdk@beta`. The API may change before 1.0.
+> **Beta.** Install with `npm install @forgeintel/sdk`. The API may change before 1.0.
 
 The Forge SDK for x402 paid APIs. Paid responses carry a `feedback_id`, the 402 challenge asks agents to rate the call, a rating is one free GET, and every call is reported to your Forge dashboard in the background. Never on your critical path: no network calls while your API serves a request, and it fails open. Aware of x402 v1 and v2, and of OpenAPI 2.0 through 3.2. Every change is additive, and anything it doesn't understand passes through untouched.
 
@@ -93,7 +93,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | `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 name, search query), record it, and remove it before your code runs. `{ searchQuery: false }` or `false` to limit. `{ required: true }` requires context before payment processing. |
+| `agentContext` | `true` | Require self-reported `agent_context` (agent name, search query) on paid requests before payment processing; record and strip it before your code runs. `{ searchQuery: false }` requires only the agent name; `false` disables collection and enforcement. |
 | `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. |
@@ -109,21 +109,21 @@ Source, examples and design notes: [github.com/ClawCash/forge-feedback](https://
 
 Client headers are captured automatically at discovery, challenge, payment, and rating stages, including unknown clients. Forge identifies awal, AgentCash, pay.sh and x402scan-mcp from known headers; other clients remain unknown. There is no client-signals switch. Legacy `agent_context.client` inputs remain accepted but are no longer requested.
 
-### Requiring agent context
+### Agent context on paid requests
 
 ```ts
 const forge = createForge({
   apiKey: process.env.FORGE_API_KEY!,
   backendUrl: "https://your-forge-backend.example/api/sdk/v2",
   publicUrl: "https://api.example.com",
-  agentContext: { required: true },
+  agentContext: true,
 });
 ```
 
-`agentContext: true` remains optional; `false` disables asking and recording. Required mode documents `agent_context` and its `agent_type` and `search_query` fields as required. Use a listed agent name (or `Others` with `agent_type_other`), and the search query or `"direct"`. `{ required: true, searchQuery: false }` requires only the agent type. Context is self-reported, not authenticated identity.
+When enabled, context is always required on payment-bearing requests. `false` disables asking and recording. Forge documents `agent_context` and its `agent_type` and `search_query` fields as required. Use a listed agent name (or `Others` with `agent_type_other`), and the search query or `"direct"`. `{ searchQuery: false }` requires only the agent type. The legacy `required: false` option is ignored; disable `agentContext` to opt out. Context is self-reported, not authenticated identity.
 
 Mount Forge **before payment middleware**. 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. Initial unpaid requests can still receive a 402, and inspection and feedback routes stay accessible. Feedback remains optional and 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(...)`.
 
-If using the framework-free core directly, call `requestUrl` and `requestBody`, then check `call.contextError()` **before** invoking your payment logic; send its response when non-null. Existing SDK integrations remain optional until explicitly configured and upgraded.
+If using the framework-free core directly, call `requestUrl` and `requestBody`, then check `call.contextError()` **before** invoking your payment logic; send its response when non-null. Upgrading an existing integration to this version makes enabled context mandatory for paid requests.

package/dist/context.js

@@ -1,5 +1,5 @@
 // Self-reported facts about the calling agent, removed before merchant validation.
-// Optional by default; merchants can require context on payment-bearing requests.
+// Enabled context is required on payment-bearing requests.
 /** Suggested agent names; anything else is kept as given. */
 export const AGENT_TYPES = ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
 /** Suggested x402 clients; anything else is kept as given. */
@@ -91,7 +91,7 @@ const DESCRIPTIONS = {
     search_query: "The search query you used to find this service, or \"direct\" if you did not search.",
 };
 /** JSON Schema for the `agent_context` body property. */
-export function agentContextSchema({ searchQuery = true, required = false } = {}) {
+export function agentContextSchema({ searchQuery = true, required = true } = {}) {
     return {
         type: "object",
         description: DESCRIPTIONS.object,
@@ -114,7 +114,7 @@ export function agentContextParameters({ searchQuery = true } = {}) {
     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, required = false } = {}) {
+export function agentContextAsk({ searchQuery = true, required = true } = {}) {
     const fields = searchQuery ? "agent_type, search_query" : "agent_type";
     const query = searchQuery ? "agent_type, agent_search_query query parameters" : "agent_type query parameter";
     return `${required ? "Required before payment" : "Please add"}: agent_context {${fields}} in your paid request's JSON body (without a body: ${query}).${searchQuery ? ' search_query: share the query you used to find this service, or "direct" if you did not search.' : ""}`;

package/dist/core.d.ts

@@ -50,12 +50,13 @@ export interface ForgeOptions {
      */
     receiptExtension?: boolean;
     /**
-     * Agent context: optional, self-reported `agent_context` {agent_type, search_query} on the paid request
+     * Agent context: required, 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. 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).
-     * `{ required: true }` rejects payment-bearing requests with missing/invalid context before payment middleware.
+     * Enabled context rejects payment-bearing requests with missing/invalid context before payment middleware.
+     * `required` is retained for compatibility; `false` is ignored. Use `false` for agentContext to disable it.
      */
     agentContext?: boolean | {
         searchQuery?: boolean;

package/dist/core.js

@@ -64,6 +64,8 @@ export function checkOptions(input) {
     fallback("agentContext", boolean(raw.agentContext) || (!!raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)), "must be true, false or { searchQuery, required }");
     if (raw.agentContext && typeof raw.agentContext === "object" && !Array.isArray(raw.agentContext)) {
         const context = raw.agentContext;
+        if (context.required === false)
+            warnings.push("agentContext.required: false is no longer supported; enabled context is required on paid requests. Set agentContext: false to disable context");
         for (const key of ["required", "searchQuery"]) {
             if (context[key] !== undefined && typeof context[key] !== "boolean") {
                 errors.push(`agentContext.${key} must be a boolean`);
@@ -175,7 +177,7 @@ function enabledCore(options, configWarnings) {
     const contextOption = options.agentContext ?? true;
     const collectContext = contextOption !== false;
     const searchQuery = collectContext && (typeof contextOption !== "object" || contextOption.searchQuery !== false);
-    const requiredContext = collectContext && typeof contextOption === "object" && contextOption.required === true;
+    const requiredContext = collectContext;
     const receipts = options.receiptExtension ?? true;
     const rateHint = options.rateHint === false
         ? null

package/dist/express.js

@@ -135,7 +135,7 @@ export function createForge(options) {
             core.onError(error);
         }
         if (call.contextRequired) {
-            // Opt-in only: parse before payment middleware even when the merchant mounts express.json later.
+            // Enabled context: parse before payment middleware even when the merchant mounts express.json later.
             // The body setter above captures context and leaves only merchant fields in req.body.
             const parseError = await new Promise((resolve) => {
                 express.json({ limit: "1mb", type: ["application/json", "application/*+json"] })(req, res, resolve);

package/dist/fetch.js

@@ -1,7 +1,7 @@
 // Web-standard adapter: Request in, Response out. Works wherever handlers are (request) => Response:
 // Hono, Next.js route handlers, Cloudflare Workers, Bun, Deno. The Hono and Next adapters build on this.
 import { BODY_LIMIT, SPEC_LIMIT, createForgeCore } from "./core.js";
-/** Buffer limit; optional mode passes larger bodies through, required mode rejects oversized JSON. */
+/** Buffer limit; enabled context rejects oversized paid JSON before payment processing. */
 const JSON_LIMIT = 1024 * 1024;
 const isJson = (type) => /^application\/(?:[\w.+-]+\+)?json\b/i.test(type ?? "");
 export function toResponse(response) {
@@ -70,7 +70,7 @@ export function createForge(options) {
         return own ? toResponse(own) : null;
     }
     async function validate(request) {
-        if (!core.enabled || !options.agentContext || typeof options.agentContext !== "object" || !options.agentContext.required)
+        if (!core.enabled || options.agentContext === false)
             return null;
         const url = new URL(request.url);
         const call = core.call(forgeRequest(request, url));

package/dist/openapi.d.ts

@@ -2,7 +2,7 @@ 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;
@@ -30,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

@@ -102,6 +102,7 @@ function extendSchema(doc, schema, props) {
 const BODYLESS = new Set(["get", "head", "delete", "options", "trace"]);
 /** 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) };

package/package.json

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