@forgeintel/sdk 0.4.0-beta.0 → 0.5.0-alpha.feedback3.b13

package/dist/x402.js

@@ -1,13 +1,48 @@
 import { ASK } from "./ask.js";
-import { PROTOCOL } from "./values.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";
+/** Key of the object the SDK adds to paid JSON response bodies: feedback_id, feedback_url, and optionally rate_this_call. */
+export const FEEDBACK_FIELD = "forge_feedback";
+const originOf = (url) => {
+    try {
+        const parsed = new URL(String(url));
+        return parsed.protocol === "https:" || parsed.protocol === "http:" ? parsed.origin : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The service origin a challenge was issued for: v2 `resource.url` (header or body), or v1 `accepts[].resource`.
+ * Used for absolute rating links when no origin is configured or registered. Never throws.
+ */
+export function challengeOrigin(challenge) {
+    try {
+        const value = typeof challenge === "string" ? JSON.parse(Buffer.from(challenge, "base64").toString("utf8")) : challenge;
+        const resource = value?.resource?.url ?? (Array.isArray(value?.accepts) ? value.accepts[0]?.resource : undefined);
+        return originOf(resource);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The service origin a payment was made for (x402 v2 `resource.url` in the payment header). Never throws. */
+export function paymentOrigin(headerValue) {
+    try {
+        return originOf(JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"))?.resource?.url);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * 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,
@@ -15,9 +50,9 @@ export function feedbackExtension(rateUrl, tone = "soft", agentContext) {
             ...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.",
+            issue: { when: "The outcome is not fully. Tells other agents what went wrong.", values: Object.keys(ISSUES) },
+            feedback_id: `In the paid response body (${FEEDBACK_FIELD}.feedback_id) and the Forge-Feedback-Id header.`,
             payment: "None. Plain GET, not an x402 endpoint.",
-            ...(agentContext ? { agent_context: agentContext } : {}),
         },
     };
 }
@@ -30,6 +65,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 other agents what went wrong.", values: Object.keys(ISSUES) },
             payment: "None. Plain GET, not an x402 endpoint.",
         },
     };
@@ -55,39 +91,59 @@ export function describeReceipt(headerValue, extension) {
     receipt.extensions = { ...extensions, [FEEDBACK_EXTENSION]: extension };
     return Buffer.from(JSON.stringify(receipt), "utf8").toString("base64");
 }
-function appendSentence(description, sentence, marker) {
+/**
+ * The longest challenge description the SDK produces. Clients copy the description into the payment payload,
+ * and the CDP facilitator rejects a payload whose resource.description exceeds 500 characters, failing the payment.
+ */
+export const MAX_DESCRIPTION = 500;
+function appendSentence(description, sentence, marker, shortSentence) {
     const current = typeof description === "string" ? description.trim() : "";
-    return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;
+    if (current.includes(marker))
+        return current;
+    for (const candidate of [sentence, shortSentence]) {
+        if (!candidate)
+            continue;
+        const next = current ? `${current} ${candidate}` : candidate;
+        if (next.length <= MAX_DESCRIPTION)
+            return next;
+    }
+    // Nothing fits: the forge-feedback extension still carries the ask.
+    return current;
 }
 /** Apply additions to a v2 PaymentRequired in place. Returns whether anything changed. */
 function addToV2(challenge, add) {
     let changed = false;
     const resource = challenge.resource;
     if (add.sentence && resource && typeof resource === "object") {
-        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence);
+        const next = appendSentence(resource.description, add.sentence, add.marker ?? add.sentence, add.shortSentence);
         if (next !== resource.description) {
             resource.description = next;
             changed = true;
         }
     }
-    if (add.extension) {
+    for (const [key, extension] of [[FEEDBACK_EXTENSION, add.extension], ["forge-agent-context", add.contextExtension]]) {
+        if (!extension)
+            continue;
         const extensions = challenge.extensions;
         if (extensions === undefined || extensions === null) {
-            challenge.extensions = { [FEEDBACK_EXTENSION]: add.extension };
+            challenge.extensions = { [key]: extension };
             changed = true;
         }
-        else if (typeof extensions === "object" && !Array.isArray(extensions) && !(FEEDBACK_EXTENSION in extensions)) {
-            // Added last, so the merchant's own extensions (e.g. bazaar) keep their order and content.
-            challenge.extensions = { ...extensions, [FEEDBACK_EXTENSION]: add.extension };
+        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.
+            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) {
@@ -120,7 +176,7 @@ export function describeChallengeBody(body, additions) {
         const marker = additions.marker ?? sentence;
         return {
             ...b,
-            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker) } : a),
+            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker, additions.shortSentence) } : a),
         };
     }
     if (b.x402Version === 2 && b.resource && typeof b.resource === "object") {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@forgeintel/sdk",
-  "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.",
+  "version": "0.5.0-alpha.feedback3.b13",
+  "description": "The Forge SDK for x402 paid APIs: agent feedback, 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": {
@@ -61,11 +61,7 @@
     "cloudflare-workers",
     "bun"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ClawCash/forge-feedback.git",
-    "directory": "packages/sdk"
-  },
+  "homepage": "https://docs.forgeintel.co",
   "scripts": {
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "test": "node -e \"require('fs').rmSync('dist-test',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test --test-reporter=spec \"dist-test/test/**/*.test.js\"",
@@ -73,7 +69,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "peerDependencies": {
     "express": ">=4.21 <6",