@forgeintel/sdk 0.5.0-beta.6 → 0.5.0-beta.8

package/README.md

@@ -84,7 +84,7 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | Option | Default | |
 | --- | --- | --- |
 | `apiKey` | required | Merchant key. Also the HMAC key for IDs. |
-| `backendUrl` | Forge production collector | Optional override for a different Forge environment. |
+| `backendUrl` | `https://dev-api.forgeintel.co/api/sdk/v2` | Optional collector override. |
 | `publicUrl` | Same-origin paths | Optional public origin for absolute rating URLs. Never infer it from request headers. |
 | `feedback` | `true` | Master switch for rating prompts, IDs, response additions and feedback routes. `false` leaves telemetry, client headers and independent agent context on. |
 | `basePath` | `/feedback` | Feedback routes (`/feedback`, `/feedback/rate`, `/feedback/summary`). |
@@ -118,7 +118,7 @@ const forge = createForge({
 });
 ```
 
-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.
+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. Any agent name is accepted; known spellings are normalized (`Claude` and `claude-code` become `Claude Code`). Send the search query, or `"direct"`. When the merchant declares a `bazaar` extension, Forge adds the same field there (schema and example), so agents that discover the service through Bazaar see it too. `{ 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.
 

package/dist/bazaar.d.ts

@@ -0,0 +1,7 @@
+import { type ContextOptions } from "./context.js";
+/**
+ * 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;

package/dist/bazaar.js

@@ -0,0 +1,58 @@
+import { CONTEXT_FIELD, agentContextExample, agentContextQuerySchema, agentContextSchema } from "./context.js";
+const isObj = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+/** Keywords whose meaning an added property could change; such schemas are left alone. */
+const COMPOSED = ["$ref", "allOf", "anyOf", "oneOf", "not", "if", "then", "else", "dependentSchemas", "patternProperties"];
+function declarable(schema) {
+    if (!isObj(schema) || COMPOSED.some((key) => key in schema))
+        return false;
+    if (schema.type !== undefined && schema.type !== "object")
+        return false;
+    if (schema.properties !== undefined && !isObj(schema.properties))
+        return false;
+    return schema.required === undefined || Array.isArray(schema.required);
+}
+/**
+ * Add properties to one part of the Bazaar input (`body` or `queryParams`): the JSON Schema in `schema` and
+ * the example in `info`, together. Facilitators index the Bazaar copy a client echoes with its payment only
+ * when `info` validates against `schema`, so declaring a required field without an example drops the listing.
+ * `@x402/core` checks the echo as a superset of what the server advertised, so adding keys keeps payments valid.
+ */
+function extend(schemas, info, key, properties, required, example) {
+    const schema = schemas[key];
+    if (!declarable(schema))
+        return false;
+    const current = info[key];
+    if (current !== undefined && !isObj(current))
+        return false;
+    const declared = isObj(schema.properties) ? schema.properties : {};
+    const listed = (schema.required ?? []);
+    // The merchant already describes these fields: their declaration wins.
+    if (Object.keys(properties).some((name) => name in declared || listed.includes(name) || (isObj(current) && name in current)))
+        return false;
+    schema.properties = { ...declared, ...properties };
+    if (required.length)
+        schema.required = [...new Set([...listed, ...required])];
+    info[key] = { ...current, ...example };
+    return true;
+}
+/**
+ * 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 function addContextToBazaar(bazaar, options) {
+    if (!isObj(bazaar) || !isObj(bazaar.info) || !isObj(bazaar.info.input) || !isObj(bazaar.schema))
+        return false;
+    const inputSchema = bazaar.schema.properties?.input;
+    if (!isObj(inputSchema) || !isObj(inputSchema.properties))
+        return false;
+    const info = bazaar.info.input;
+    const required = options.required !== false;
+    if (info.bodyType !== undefined || "body" in inputSchema.properties) {
+        if (info.bodyType !== "json")
+            return false;
+        return extend(inputSchema.properties, info, "body", { [CONTEXT_FIELD]: agentContextSchema(options) }, required ? [CONTEXT_FIELD] : [], { [CONTEXT_FIELD]: agentContextExample(options) });
+    }
+    const query = agentContextQuerySchema(options);
+    return extend(inputSchema.properties, info, "queryParams", query.properties, query.required, agentContextExample(options, "query"));
+}

package/dist/context.d.ts

@@ -1,5 +1,13 @@
 /** Suggested agent names; anything else is kept as given. */
 export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok Bot", "Muse", "Hermes", "Instinct", "OpenClaw", "Others"];
+/**
+ * Example values for discovery documents that need one (Bazaar's `info`). Agents sometimes copy examples
+ * verbatim, so they are placeholders, and an unedited placeholder is recorded as missing rather than as a name.
+ */
+export declare const CONTEXT_PLACEHOLDERS: {
+    readonly agent_type: "your agent name";
+    readonly search_query: "your search query, or direct";
+};
 /** 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, …). */
@@ -45,11 +53,6 @@ export declare function agentContextSchema({ searchQuery, required }?: ContextOp
             maxLength: number;
         } | undefined;
         agent_type: {
-            type: string;
-            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok Bot" | "Muse" | "Hermes" | "Instinct" | "OpenClaw" | "Others")[];
-            description: string;
-        };
-        agent_type_other: {
             description: string;
             minLength?: number | undefined;
             type: string;
@@ -60,7 +63,7 @@ export declare function agentContextSchema({ searchQuery, required }?: ContextOp
     type: string;
     description: string;
 };
-/** The optional query parameters, for operations without a request body. */
+/** The query parameters, for operations without a request body. */
 export declare function agentContextParameters({ searchQuery }?: {
     searchQuery?: boolean;
 }): {
@@ -68,7 +71,16 @@ export declare function agentContextParameters({ searchQuery }?: {
     description: string;
     schema: Record<string, unknown>;
 }[];
-/** One line for the forge-feedback extension, so clients that only inspect the 402 learn about it too. */
+/** The same parameters as JSON Schema properties, for discovery documents that describe a query object (Bazaar). */
+export declare function agentContextQuerySchema({ searchQuery, required }?: ContextOptions): {
+    properties: Record<string, Record<string, unknown>>;
+    required: string[];
+};
+/** Placeholder values matching agentContextSchema (body) or agentContextQuerySchema (query). */
+export declare function agentContextExample({ searchQuery }?: ContextOptions, where?: "body" | "query"): {
+    [x: string]: "your agent name" | "your search query, or direct";
+};
+/** One line for the forge-agent-context extension, so clients that only inspect the 402 learn about it too. */
 export declare function agentContextAsk({ searchQuery, required }?: ContextOptions): string;
 /** Validate the original values, before lenient parsing can truncate or discard them. */
 export declare function contextIssues(raw: Record<string, unknown>, { searchQuery }: ContextOptions): string[];

package/dist/context.js

@@ -2,6 +2,20 @@
 // 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"];
+/** Spellings agents use for the suggested names, compared lowercase with only letters and digits kept. */
+const AGENT_ALIASES = {
+    claude: "Claude Code", claudecode: "Claude Code", claudecodecli: "Claude Code", anthropicclaudecode: "Claude Code",
+    codex: "Codex", codexcli: "Codex", openaicodex: "Codex",
+    cursor: "Cursor", cursoragent: "Cursor", cursorai: "Cursor",
+    grok: "Grok Bot", grokbot: "Grok Bot",
+    muse: "Muse", hermes: "Hermes", hermesagent: "Hermes", instinct: "Instinct", openclaw: "OpenClaw",
+    other: "Others", others: "Others", othersspecify: "Others", unknown: "Others",
+};
+/**
+ * Example values for discovery documents that need one (Bazaar's `info`). Agents sometimes copy examples
+ * verbatim, so they are placeholders, and an unedited placeholder is recorded as missing rather than as a name.
+ */
+export const CONTEXT_PLACEHOLDERS = { agent_type: "your agent name", search_query: "your search query, or direct" };
 /** Suggested x402 clients; anything else is kept as given. */
 export const CLIENTS = ["agentcash", "awal", "pay.sh", "other", "unknown"];
 /** JSON body field (POST, PUT, …). */
@@ -29,15 +43,13 @@ export function parseAgentContext(input, { searchQuery = true } = {}) {
         let text = raw.replace(/[\u0000-\u001f\u007f]+/g, " ").trim().slice(0, LIMITS[key]);
         if (!text)
             continue;
-        if (key === "agent_type") {
-            if (/^grok(?: bot)?$/i.test(text))
-                text = "Grok Bot";
-            if (/^(?:others?(?: \(specify\))?|unknown)$/i.test(text))
-                text = "Others";
-        }
+        if ((key === "agent_type" || key === "search_query") && text.toLowerCase() === CONTEXT_PLACEHOLDERS[key])
+            continue;
+        if (key === "agent_type")
+            text = AGENT_ALIASES[text.toLowerCase().replace(/[^a-z0-9]/g, "")] ?? text;
         if (key === "search_query" && /^direct$/i.test(text))
             text = "direct";
-        const known = key === "agent_type" ? AGENT_TYPES : key === "client" ? CLIENTS : null;
+        const known = key === "client" ? CLIENTS : null;
         context[key] = known?.find((v) => v.toLowerCase() === text.toLowerCase()) ?? text;
     }
     return Object.keys(context).length ? context : undefined;
@@ -86,8 +98,7 @@ export function takeFromUrl(url) {
 }
 const DESCRIPTIONS = {
     object: "information about the calling agent and how it found this service.",
-    agent_type: "Which agent are you? Choose Others if yours is not listed and share its name in agent_type_other.",
-    agent_type_other: "Your agent's name, when agent_type is Others.",
+    agent_type: `Your agent's name, for example ${AGENT_TYPES.filter((name) => name !== "Others").join(", ")}. Any name works.`,
     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. */
@@ -97,23 +108,36 @@ export function agentContextSchema({ searchQuery = true, required = true } = {})
         description: DESCRIPTIONS.object,
         ...(required ? { required: ["agent_type", ...(searchQuery ? ["search_query"] : [])] } : {}),
         properties: {
-            agent_type: { type: "string", enum: [...AGENT_TYPES], description: DESCRIPTIONS.agent_type },
-            agent_type_other: { type: "string", maxLength: LIMITS.agent_type_other, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.agent_type_other },
+            agent_type: { type: "string", maxLength: LIMITS.agent_type, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.agent_type },
             ...(searchQuery ? { search_query: { type: "string", maxLength: LIMITS.search_query, ...(required ? { minLength: 1 } : {}), description: DESCRIPTIONS.search_query } } : {}),
         },
     };
 }
-/** The optional query parameters, for operations without a request body. */
+/** The 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.agent_type, description: DESCRIPTIONS.agent_type, schema: { type: "string", maxLength: LIMITS.agent_type } },
     ];
     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. */
+/** The same parameters as JSON Schema properties, for discovery documents that describe a query object (Bazaar). */
+export function agentContextQuerySchema({ searchQuery = true, required = true } = {}) {
+    const properties = {};
+    for (const p of agentContextParameters({ searchQuery }))
+        properties[p.name] = { ...p.schema, ...(required ? { minLength: 1 } : {}), description: p.description };
+    return { properties, required: required ? Object.keys(properties) : [] };
+}
+/** Placeholder values matching agentContextSchema (body) or agentContextQuerySchema (query). */
+export function agentContextExample({ searchQuery = true } = {}, where = "body") {
+    const names = where === "query" ? { agent_type: CONTEXT_QUERY.agent_type, search_query: CONTEXT_QUERY.search_query } : { agent_type: "agent_type", search_query: "search_query" };
+    return {
+        [names.agent_type]: CONTEXT_PLACEHOLDERS.agent_type,
+        ...(searchQuery ? { [names.search_query]: CONTEXT_PLACEHOLDERS.search_query } : {}),
+    };
+}
+/** One line for the forge-agent-context extension, so clients that only inspect the 402 learn about it too. */
 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";
@@ -128,12 +152,6 @@ export function contextIssues(raw, { searchQuery = true }) {
             issues.push(`${key} must be a non-empty string of at most ${LIMITS[key]} characters`);
         }
     }
-    const parsed = parseAgentContext(raw);
-    if (parsed?.agent_type && !AGENT_TYPES.includes(parsed.agent_type)) {
-        issues.push("agent_type must be a listed agent name, or Others with agent_type_other");
-    }
-    if (raw.agent_type_other !== undefined && (typeof raw.agent_type_other !== "string" || !raw.agent_type_other.trim() || raw.agent_type_other.length > 80)) {
-        issues.push("agent_type_other must be a non-empty string of at most 80 characters");
-    }
+    // Any name is accepted: known spellings are normalized by parseAgentContext, others are kept as given.
     return issues;
 }

package/dist/core.d.ts

@@ -178,7 +178,7 @@ export declare const FEEDBACK_HEADERS: {
 export declare const BODY_LIMIT: number;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export declare const SPEC_LIMIT: number;
-export declare const DEFAULT_BACKEND_URL = "https://app-api.forgeintel.co/api/sdk/v2";
+export declare const DEFAULT_BACKEND_URL = "https://dev-api.forgeintel.co/api/sdk/v2";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.

package/dist/core.js

@@ -14,7 +14,7 @@ export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "
 export const BODY_LIMIT = 8 * 1024;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export const SPEC_LIMIT = 10 * 1024 * 1024;
-export const DEFAULT_BACKEND_URL = "https://app-api.forgeintel.co/api/sdk/v2";
+export const DEFAULT_BACKEND_URL = "https://dev-api.forgeintel.co/api/sdk/v2";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.
@@ -212,10 +212,12 @@ function enabledCore(options, configWarnings) {
     const challengeMarker = challengeSentence.includes(rateUrl) ? rateUrl : challengeSentence;
     const challengeAdditions = {
         ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
-        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone, collectContext ? agentContextAsk({ searchQuery, required: requiredContext }) : undefined) }),
+        ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone) }),
     };
-    if (!feedback && collectContext)
+    if (collectContext)
         challengeAdditions.contextExtension = { info: { agent_context: agentContextAsk({ searchQuery, required: requiredContext }), optional: !requiredContext } };
+    if (collectContext)
+        challengeAdditions.bazaarContext = { searchQuery, required: requiredContext };
     const touchChallenges = Boolean(challengeAdditions.sentence || challengeAdditions.extension || challengeAdditions.contextExtension);
     // Set once a document has been enriched; lets body injection respect strict response schemas.
     let allowInjection = null;

package/dist/x402.d.ts

@@ -1,14 +1,14 @@
 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";
 /**
  * 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: {
@@ -50,13 +50,15 @@ export interface ChallengeAdditions {
     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,13 +1,14 @@
 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";
 /**
  * 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,
@@ -18,7 +19,6 @@ export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
             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.",
             payment: "None. Plain GET, not an x402 endpoint.",
-            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
@@ -81,17 +81,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) {

package/package.json

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