@forgeintel/sdk 0.2.0-beta.0

package/dist/x402.d.ts

@@ -0,0 +1,45 @@
+/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+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.
+ */
+export declare function feedbackExtension(rateUrl: string): {
+    info: {
+        protocol: string;
+        ask: string;
+        rate: string;
+        outcome: string[];
+        feedback_id: string;
+        payment: string;
+    };
+};
+/** 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;
+    /** Idempotency marker for the sentence. Default: the sentence itself. */
+    marker?: string;
+    /** Added as extensions["forge-feedback"] (v2 only; v1 challenges have no extensions). */
+    extension?: unknown;
+}
+/**
+ * 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.
+ * Returns undefined when the header can't be parsed or already has everything.
+ */
+export declare function describeChallenge(headerValue: string, additions: ChallengeAdditions): string | undefined;
+/**
+ * Same for a JSON-body challenge: x402 v1 ({x402Version: 1, accepts: [{description}]}, sentence only)
+ * or a v2 PaymentRequired echoed in the body. v1 servers match payments against their own requirements,
+ * so descriptions in the response are informational. Returns undefined when nothing applies.
+ */
+export declare function describeChallengeBody(body: unknown, additions: ChallengeAdditions): unknown;
+export interface PaymentFacts {
+    payer?: string;
+    network?: string;
+    amount?: string;
+}
+/** Best-effort read of the payer, network and amount from an x402 v1/v2 payment header. Never throws. */
+export declare function readPaymentHeader(headerValue: string): PaymentFacts;

package/dist/x402.js

@@ -0,0 +1,113 @@
+import { PROTOCOL } from "./values.js";
+/** Key of the Forge extension in an x402 v2 challenge's `extensions`, next to e.g. `bazaar`. */
+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.
+ */
+export function feedbackExtension(rateUrl) {
+    return {
+        info: {
+            protocol: PROTOCOL,
+            ask: "After your call, please rate this service for other agents. Free, one request.",
+            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.",
+            payment: "None. Plain GET, not an x402 endpoint.",
+        },
+    };
+}
+function appendSentence(description, sentence, marker) {
+    const current = typeof description === "string" ? description.trim() : "";
+    return current.includes(marker) ? current : current ? `${current} ${sentence}` : sentence;
+}
+/** 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);
+        if (next !== resource.description) {
+            resource.description = next;
+            changed = true;
+        }
+    }
+    if (add.extension) {
+        const extensions = challenge.extensions;
+        if (extensions === undefined || extensions === null) {
+            challenge.extensions = { [FEEDBACK_EXTENSION]: add.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 };
+            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.
+ * Returns undefined when the header can't be parsed or already has everything.
+ */
+export function describeChallenge(headerValue, additions) {
+    let challenge;
+    try {
+        challenge = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (!challenge || typeof challenge !== "object" || !challenge.resource || typeof challenge.resource !== "object")
+        return undefined;
+    if (!addToV2(challenge, additions))
+        return undefined;
+    return Buffer.from(JSON.stringify(challenge), "utf8").toString("base64");
+}
+/**
+ * Same for a JSON-body challenge: x402 v1 ({x402Version: 1, accepts: [{description}]}, sentence only)
+ * or a v2 PaymentRequired echoed in the body. v1 servers match payments against their own requirements,
+ * so descriptions in the response are informational. Returns undefined when nothing applies.
+ */
+export function describeChallengeBody(body, additions) {
+    if (!body || typeof body !== "object" || Array.isArray(body))
+        return undefined;
+    const b = body;
+    const { sentence } = additions;
+    if (b.x402Version === 1 && Array.isArray(b.accepts)) {
+        if (!sentence)
+            return undefined;
+        const marker = additions.marker ?? sentence;
+        return {
+            ...b,
+            accepts: b.accepts.map((a) => a && typeof a === "object" ? { ...a, description: appendSentence(a.description, sentence, marker) } : a),
+        };
+    }
+    if (b.x402Version === 2 && b.resource && typeof b.resource === "object") {
+        const copy = { ...b, resource: { ...b.resource } };
+        return addToV2(copy, additions) ? copy : undefined;
+    }
+    return undefined;
+}
+/** Best-effort read of the payer, network and amount from an x402 v1/v2 payment header. Never throws. */
+export function readPaymentHeader(headerValue) {
+    try {
+        const p = JSON.parse(Buffer.from(headerValue, "base64").toString("utf8"));
+        const authorization = p?.payload?.authorization;
+        const facts = {
+            payer: authorization?.from,
+            network: p?.accepted?.network ?? p?.network,
+            amount: p?.accepted?.amount ?? authorization?.value,
+        };
+        for (const key of Object.keys(facts)) {
+            if (typeof facts[key] !== "string")
+                delete facts[key];
+        }
+        return facts;
+    }
+    catch {
+        return {};
+    }
+}

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@forgeintel/sdk",
+  "version": "0.2.0-beta.0",
+  "description": "The Forge SDK for x402 paid APIs: agent feedback (feedback IDs, one-request GET ratings), OpenAPI and challenge enrichment, and passive call signals. Express adapter plus a framework-free core. Never on your critical path.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.19"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./express": {
+      "types": "./dist/express.d.ts",
+      "import": "./dist/express.js",
+      "default": "./dist/express.js"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "default": "./dist/core.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "x402",
+    "feedback",
+    "reputation",
+    "agents",
+    "openapi",
+    "express",
+    "payments",
+    "forge"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClawCash/forge-feedback.git",
+    "directory": "packages/sdk"
+  },
+  "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\"",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "peerDependencies": {
+    "express": ">=4.21 <6"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@types/express": "^5.0.3",
+    "@types/node": "^22.18.0",
+    "@x402/core": "~2.25.0",
+    "@x402/evm": "~2.25.0",
+    "@x402/express": "~2.25.0",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "express": "^5.2.1",
+    "typescript": "^5.9.2",
+    "viem": "^2.56.3",
+    "x402-express": "^1.2.0"
+  }
+}