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

package/README.md

@@ -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)…*, 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. |
+| 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. The description never exceeds 500 characters (the CDP facilitator rejects longer ones): a shorter ask is used when the full one doesn't fit, and none when neither does. |
 | 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.d.ts

@@ -8,6 +8,8 @@ export declare const TONES: readonly Tone[];
 export interface AskTexts {
     /** Appended to 402 challenge descriptions. "{rate_url}" and "{summary_url}" are substituted. */
     challengeSentence: string;
+    /** Used instead when the full sentence would push the description past MAX_DESCRIPTION. "{rate_url}" is substituted. */
+    shortChallengeSentence: 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). */

package/dist/ask.js

@@ -3,12 +3,14 @@ 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. 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.",
+        shortChallengeSentence: "After your call, please rate it for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free.",
         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. 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.",
+        shortChallengeSentence: "Step 4 of 4: rate the call for other agents: GET {rate_url}?feedback_id=FEEDBACK_ID&outcome=fully. Free.",
         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/core.js

@@ -210,8 +210,10 @@ function enabledCore(options, configWarnings) {
     const challengeSentence = feedback ? (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;
+    // The short form always contains the rate URL, so the marker still recognizes a described challenge.
+    const shortChallengeSentence = ASK[tone].shortChallengeSentence.replaceAll("{rate_url}", rateUrl);
     const challengeAdditions = {
-        ...(describe ? { sentence: challengeSentence, marker: challengeMarker } : {}),
+        ...(describe ? { sentence: challengeSentence, marker: challengeMarker, ...(challengeMarker === rateUrl ? { shortSentence: shortChallengeSentence } : {}) } : {}),
         ...(!feedback || options.challengeExtension === false ? {} : { extension: feedbackExtension(rateUrl, tone) }),
     };
     if (collectContext)

package/dist/x402.d.ts

@@ -42,10 +42,17 @@ export declare function receiptExtension(rateUrl: string, feedbackId: string, to
  * Returns undefined when the header can't be parsed, settlement failed, or the extension is already there.
  */
 export declare function describeReceipt(headerValue: string, extension: unknown): string | undefined;
+/**
+ * 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 declare const MAX_DESCRIPTION = 500;
 /** What the SDK adds to a challenge. Each part is skipped when already present. */
 export interface ChallengeAdditions {
     /** Appended to the description (v2 resource.description, v1 accepts[].description). */
     sentence?: string;
+    /** Appended instead when `sentence` would pass MAX_DESCRIPTION; the description is left alone when this doesn't fit either. */
+    shortSentence?: string;
     /** Idempotency marker for the sentence. Default: the sentence itself. */
     marker?: string;
     /** Added as extensions["forge-feedback"] (v2 only; v1 challenges have no extensions). */

package/dist/x402.js

@@ -57,16 +57,31 @@ 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;
@@ -127,7 +142,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,6 +1,6 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.8",
+  "version": "0.5.0-beta.9",
   "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",