@forgeintel/sdk 0.3.0-beta.0 → 0.4.0-beta.1

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)
 });
 
@@ -57,7 +57,7 @@ Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require
 
 | When | What happens |
 | --- | --- |
-| 402 challenge | Appends a soft ask to the description: *After your call, please rate this service for other agents: GET …/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no)…*. On x402 v2 it also adds an `extensions["forge-feedback"]` block. Payment terms and your own extensions are never touched. |
+| 402 challenge | Appends a soft ask to the description: *After your call, please rate this service for other agents: GET …/feedback/rate?feedback_id=FEEDBACK_ID&outcome=fully (or partially, no)…*, and asks for `&issue=` when the outcome isn't `fully`, so a bad rating says why. On x402 v2 it also adds an `extensions["forge-feedback"]` block. Payment terms and your own extensions are never touched. |
 | Paid 2xx response | Adds the `Forge-Feedback-Id` header. JSON object bodies also get `feedback_id`, `feedback_url` (with `outcome=` left blank) and `rate_this_call`, unless your OpenAPI schema for that response couldn't safely take them. |
 | `GET /openapi.json` | Your document is served enriched: feedback routes documented, feedback fields added to paid response schemas, one sentence in `x-guidance`. |
 | `GET /feedback/rate` | Quick rating: `feedback_id`, `outcome`, optional `issue`. |

package/dist/ask.js

@@ -2,15 +2,15 @@
 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.",
+        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. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        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. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        extensionAsk: "After your call, please rate this service for other agents. Free, one request. When the outcome is not fully, the issue field tells the merchant what to fix.",
         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.",
+        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. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        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. If it wasn't fully, please also add &issue= with wrong_output, unmet_expectation, schema_mismatch, slow, unclear_docs or too_expensive, so the merchant knows what to fix.",
+        extensionAsk: "Step 4 of this service's flow: after the response, please rate the call for other agents. Free, one request. When the outcome is not fully, the issue field tells the merchant what to fix.",
         extensionExtras: { flow: ["402 challenge", "pay", "response", "rate"] },
     },
 };

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 /** Suggested agent names; anything else is kept as given. */
-export declare const AGENT_TYPES: readonly ["Claude Code", "Codex", "Cursor", "Grok", "Hermes", "OpenClaw", "Other", "Unknown"];
+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, …). */
@@ -45,7 +45,7 @@ export declare function agentContextSchema({ searchQuery }?: {
         } | undefined;
         agent_type: {
             type: string;
-            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok" | "Hermes" | "OpenClaw" | "Other" | "Unknown")[];
+            enum: ("Claude Code" | "Codex" | "Cursor" | "Grok" | "Hermes" | "Instinct" | "OpenClaw" | "Other" | "Unknown")[];
             description: string;
         };
         agent_type_other: {

package/dist/context.js

@@ -3,7 +3,7 @@
 // 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", "OpenClaw", "Other", "Unknown"];
+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, …). */

package/dist/core.d.ts

@@ -15,7 +15,10 @@ 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;

package/dist/core.js

@@ -1,12 +1,12 @@
 // Framework-free Forge logic. Adapters (express.ts, later fetch.ts) translate their request/response
 // objects to the small interfaces below and write out what the core returns.
-import { DEFAULT_TTL_MS, mintFeedbackId, verifyFeedbackId } from "./id.js";
+import { DEFAULT_TTL_MS, deriveSigningKey, mintFeedbackId, verifyFeedbackId } from "./id.js";
 import { createOperationIndex, enrichOpenApi } from "./openapi.js";
 import { ASK, TONES, checkAskText } from "./ask.js";
 import { agentContextAsk, parseAgentContext, takeFromBody, takeFromUrl } from "./context.js";
 import { EventReporter } from "./reporter.js";
 import { ISSUES, NOTE_MAX_LENGTH, OUTCOMES, PROTOCOL, parseSubmission } from "./values.js";
-import { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, readPaymentHeader, receiptExtension } from "./x402.js";
+import { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, readPaymentHeader, readReceipt, receiptExtension } from "./x402.js";
 export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "noindex" };
 /** Max JSON body for POST {basePath}. */
 export const BODY_LIMIT = 8 * 1024;
@@ -143,6 +143,10 @@ export function createForgeCore(input) {
 }
 function enabledCore(options, configWarnings) {
     const { apiKey, backendUrl, publicUrl } = options;
+    // Feedback IDs are signed with a key derived from the API key, never with the API key itself.
+    const signingKey = deriveSigningKey(apiKey);
+    const backendPath = new URL(backendUrl).pathname.replace(/\/+$/, "") || "/v1";
+    const backend = (name) => new URL(`${backendPath}/${name}`, backendUrl).href;
     const basePath = (options.basePath ?? "/feedback").replace(/\/+$/, "");
     const ratePath = `${basePath}/rate`;
     const rateUrl = new URL(ratePath, publicUrl).href;
@@ -181,7 +185,7 @@ function enabledCore(options, configWarnings) {
                 console.warn(`[forge-feedback] ${message}`);
             lastLogged = message;
         });
-    const reporter = new EventReporter(new URL("/v1/events", backendUrl).href, apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
+    const reporter = new EventReporter(backend("events"), apiKey, fetchImpl, onError, options.flushIntervalMs ?? 2000);
     const challengeSentence = (options.challengeSentence ?? ASK[tone].challengeSentence).replaceAll("{rate_url}", rateUrl).replaceAll("{summary_url}", summaryUrl);
     // Idempotency marker: the rate URL when the sentence contains it, otherwise the sentence itself.
     const challengeMarker = challengeSentence.includes(rateUrl) ? rateUrl : challengeSentence;
@@ -247,11 +251,11 @@ function enabledCore(options, configWarnings) {
         if (!parsed.ok)
             return badRequest(parsed.error);
         // Cheap local check so garbage and expired IDs never reach the backend.
-        if (!verifyFeedbackId(apiKey, parsed.value.feedback_id, { ttlMs }).valid) {
+        if (!verifyFeedbackId(signingKey, parsed.value.feedback_id, { ttlMs }).valid) {
             return reply(404, { recorded: false, error: "unknown_or_expired_feedback_id" });
         }
         try {
-            const upstream = await fetchImpl(new URL("/v1/feedback", backendUrl).href, {
+            const upstream = await fetchImpl(backend("feedback"), {
                 method: "POST",
                 headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
                 body: JSON.stringify({ ...parsed.value, via, user_agent: request.header("user-agent") ?? null }),
@@ -270,7 +274,7 @@ function enabledCore(options, configWarnings) {
     async function summary() {
         if (!summaryCache || Date.now() - summaryCache.at > 30_000) {
             try {
-                const upstream = await fetchImpl(new URL("/v1/summary", backendUrl).href, {
+                const upstream = await fetchImpl(backend("summary"), {
                     headers: { authorization: `Bearer ${apiKey}` },
                     signal: AbortSignal.timeout(3000),
                 });
@@ -349,13 +353,14 @@ function enabledCore(options, configWarnings) {
         const route = `${request.method} ${request.path}`;
         const userAgent = request.header("user-agent") ?? undefined;
         const paymentHeader = request.header("payment-signature") ?? request.header("x-payment"); // x402 v2 / v1
-        const feedbackId = paymentHeader ? mintFeedbackId(apiKey) : undefined;
+        const feedbackId = paymentHeader ? mintFeedbackId(signingKey) : undefined;
         if (feedbackId)
             stats.minted++;
         const feedbackUrl = feedbackId ? `${rateUrl}?feedback_id=${feedbackId}&outcome=` : "";
         let bodyChallenge = false;
         let headerChallenge = false;
         let context;
+        let receiptFacts = {};
         const remember = (raw) => {
             if (!collectContext)
                 return;
@@ -421,6 +426,8 @@ function enabledCore(options, configWarnings) {
                     }
                     if (feedbackId && ok(status)) {
                         set["Forge-Feedback-Id"] = feedbackId;
+                        if (paymentResponse)
+                            receiptFacts = readReceipt(paymentResponse);
                         const receipt = receipts && paymentResponse ? describeReceipt(paymentResponse, receiptExtension(rateUrl, feedbackId, tone)) : undefined;
                         if (receipt)
                             set["PAYMENT-RESPONSE"] = receipt;
@@ -471,7 +478,7 @@ function enabledCore(options, configWarnings) {
                 reporter.push({ type: "challenge", route, ts, user_agent: userAgent, ...(context ? { agent_context: context } : {}) });
             }
             if (feedbackId) {
-                const facts = readPaymentHeader(paymentHeader);
+                const facts = { ...readPaymentHeader(paymentHeader), ...receiptFacts };
                 reporter.push({
                     type: "interaction",
                     feedback_id: feedbackId,

package/dist/id.d.ts

@@ -1,5 +1,10 @@
 export declare const FEEDBACK_ID_PATTERN: RegExp;
 export declare const DEFAULT_TTL_MS: number;
+/**
+ * The key feedback IDs are signed with, derived from the merchant's API key. Backends keep this (encrypted)
+ * instead of the API key itself, or derive it from the Bearer key on each request.
+ */
+export declare function deriveSigningKey(apiKey: string): string;
 export declare function mintFeedbackId(key: string, now?: number): string;
 export type FeedbackIdCheck = {
     valid: true;

package/dist/id.js

@@ -5,6 +5,13 @@ export const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
 const HEAD_BYTES = 10;
 const TAG_BYTES = 6;
 const CLOCK_SKEW_MS = 5 * 60 * 1000;
+/**
+ * The key feedback IDs are signed with, derived from the merchant's API key. Backends keep this (encrypted)
+ * instead of the API key itself, or derive it from the Bearer key on each request.
+ */
+export function deriveSigningKey(apiKey) {
+    return createHmac("sha256", apiKey).update("forge-feedback-id/v1").digest("base64url");
+}
 function tag(key, head) {
     return createHmac("sha256", key).update(head).digest().subarray(0, TAG_BYTES);
 }

package/dist/index.d.ts

@@ -4,11 +4,11 @@ export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js
 export type { ForgeCall, ForgeCore, ForgeDiagnostics, ForgeFeedbackOptions, ForgeOptions, ForgeRequest, ForgeResponse, OpenApiOptions } from "./core.js";
 export { enrichOpenApi, detectVersion } from "./openapi.js";
 export type { EnrichOptions, EnrichReport, OperationReport, ResponseSupport, SpecVersion } from "./openapi.js";
-export { mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
+export { deriveSigningKey, mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
 export type { FeedbackIdCheck } from "./id.js";
 export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
 export type { Outcome, Issue, Submission } from "./values.js";
-export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader, readReceipt } from "./x402.js";
 export { ASK, TONES, checkAskText } from "./ask.js";
 export { AGENT_TYPES, CLIENTS, CONTEXT_FIELD, CONTEXT_QUERY, agentContextSchema, parseAgentContext } from "./context.js";
 export type { AgentContext } from "./context.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 export { createForge, createForgeFeedback } from "./express.js";
 export { createForgeCore, checkOptions, BODY_LIMIT, SPEC_LIMIT } from "./core.js";
 export { enrichOpenApi, detectVersion } from "./openapi.js";
-export { mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
+export { deriveSigningKey, mintFeedbackId, verifyFeedbackId, FEEDBACK_ID_PATTERN, DEFAULT_TTL_MS } from "./id.js";
 export { OUTCOMES, ISSUES, NOTE_MAX_LENGTH, PROTOCOL, parseSubmission } from "./values.js";
-export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader } from "./x402.js";
+export { describeChallenge, describeChallengeBody, describeReceipt, feedbackExtension, receiptExtension, FEEDBACK_EXTENSION, readPaymentHeader, readReceipt } from "./x402.js";
 export { ASK, TONES, checkAskText } from "./ask.js";
 export { AGENT_TYPES, CLIENTS, CONTEXT_FIELD, CONTEXT_QUERY, agentContextSchema, parseAgentContext } from "./context.js";

package/dist/reporter.d.ts

@@ -14,6 +14,10 @@ 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;

package/dist/x402.d.ts

@@ -11,6 +11,10 @@ export declare function feedbackExtension(rateUrl: string, tone?: Tone, agentCon
         agent_context?: string | undefined;
         rate: string;
         outcome: string[];
+        issue: {
+            when: string;
+            values: string[];
+        };
         feedback_id: string;
         payment: string;
         protocol: string;
@@ -25,6 +29,10 @@ export declare function receiptExtension(rateUrl: string, feedbackId: string, to
         feedback_id: string;
         rate: string;
         outcome: string[];
+        issue: {
+            when: string;
+            values: string[];
+        };
         payment: string;
     };
 };
@@ -60,6 +68,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,5 +1,5 @@
 import { ASK } from "./ask.js";
-import { PROTOCOL } from "./values.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";
 /**
@@ -15,6 +15,7 @@ export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
             ...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.",
             payment: "None. Plain GET, not an x402 endpoint.",
             ...(agentContext ? { agent_context: agentContext } : {}),
@@ -30,6 +31,7 @@ export function receiptExtension(rateUrl, feedbackId, tone = "soft") {
             feedback_id: feedbackId,
             rate: `GET ${rateUrl}?feedback_id=${feedbackId}&outcome=fully`,
             outcome: ["fully", "partially", "no"],
+            issue: { when: "The outcome is not fully. Tells the merchant what to fix.", values: Object.keys(ISSUES) },
             payment: "None. Plain GET, not an x402 endpoint.",
         },
     };
@@ -129,7 +131,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"));
@@ -138,6 +140,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")
@@ -149,3 +153,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,6 +1,6 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.3.0-beta.0",
+  "version": "0.4.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.",
   "license": "MIT",
   "type": "module",