@forgeintel/sdk 0.2.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Forge Intel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @forgeintel/sdk
+
+> **Beta.** Install with `npm install @forgeintel/sdk@beta`. The API may change before 1.0.
+
+The Forge SDK for x402 paid APIs. Paid responses carry a `feedback_id`, the 402 challenge asks agents to rate the call, a rating is one free GET, and every call is reported to your Forge dashboard in the background. Never on your critical path: no network calls while your API serves a request, and it fails open. Aware of x402 v1 and v2, and of OpenAPI 2.0 through 3.2. Every change is additive, and anything it doesn't understand passes through untouched.
+
+## Express
+
+```js
+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
+  publicUrl: "https://api.example.com",      // your public origin (never taken from the Host header)
+});
+
+app.use(forge.middleware());                        // 1. first: before payments and your /openapi.json route
+app.use(paymentMiddleware(routes, resourceServer)); // 2. your existing x402 setup, unchanged
+```
+
+Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5.
+
+## Any other framework
+
+`@forgeintel/sdk/core` is the same logic without a framework. Call `forge.route()` first, then `forge.call()` per paid request, and `call.headers()` / `call.json()` / `call.finish()` where you build the 402 and the paid response. See the [core integration guide](https://github.com/ClawCash/forge-feedback/tree/main/examples/node-http-core) for a complete `node:http` + `@x402/core` example.
+
+Zero runtime dependencies. Node ≥ 20.19. Works from both `import` and `require()`.
+
+## What it does
+
+| 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. |
+| 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`. |
+| `POST /feedback` | Same fields, plus an optional `note` (≤ 280 chars). |
+| `GET /feedback`, `GET /feedback/summary` | The form description, and public aggregate ratings. |
+| Every 402 and paid call | Sends a challenge or interaction event to the backend in the background. |
+
+IDs are minted locally with an HMAC, so the paid path makes no network call. If the backend is down, paid calls still work, and ratings return `503 feedback_unavailable`.
+
+## Compatibility
+
+| | x402 v1 (`x402-express` 1.x) | x402 v2 (`@x402/express` 2.x, `@x402/core`) |
+| --- | --- | --- |
+| Challenge | JSON body, `accepts[].description` | `PAYMENT-REQUIRED` header: `resource.description` and `extensions` |
+| Payment header | `X-PAYMENT` | `PAYMENT-SIGNATURE` |
+| Why the changes are safe | Servers match payments against their own requirements | Payments match on `accepts`; `@x402/core` only validates echoed extensions the server advertised |
+
+OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared components are never edited; strict schemas get the header only; idempotent; YAML and anything unexpected pass through byte-for-byte.
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `apiKey` | required | Merchant key. Also the HMAC key for IDs. |
+| `backendUrl` | required | Forge backend origin. |
+| `publicUrl` | required | This service's public origin. Used in rating URLs. |
+| `basePath` | `/feedback` | Feedback routes (`/feedback`, `/feedback/rate`, `/feedback/summary`). |
+| `describeChallenges` | `true` | Append the sentence to 402 challenges. |
+| `challengeSentence` | built-in | Override for wording experiments. `{rate_url}` and `{summary_url}` are substituted. |
+| `challengeExtension` | `true` | Add the `forge-feedback` extension to x402 v2 challenges. |
+| `injectBody` | `true` | Add `feedback_id` / `feedback_url` to paid JSON bodies. |
+| `rateHint` | built-in | The `rate_this_call` field. A string overrides it (`{feedback_url}` is substituted); `false` removes it. |
+| `injectText` | `false` | Append a two-line trailer to paid `text/plain` bodies. |
+| `openapi` | intercept `/openapi.json` | `false` to disable, or `{ paths, document, isPaidOperation, describeOperations }`. |
+| `ttlMs` | 24h | Local pre-check; keep in sync with the backend. |
+| `flushIntervalMs` | `2000` | Event batching interval. |
+| `onError` | `console.warn` | Called for internal errors. Business requests are never affected. |
+
+`forge.diagnostics()` returns counters and the last OpenAPI report. `forge.enrichOpenApi(doc)` is available for build-time use. Call `await forge.shutdown()` in your shutdown handler to flush pending events.
+
+Source, examples and design notes: [github.com/ClawCash/forge-feedback](https://github.com/ClawCash/forge-feedback).

package/dist/core.d.ts

@@ -0,0 +1,147 @@
+import { type EnrichReport } from "./openapi.js";
+export interface OpenApiOptions {
+    /** Paths where your OpenAPI JSON is served. Default ["/openapi.json"]. */
+    paths?: string[];
+    /** Serve this document (enriched) instead of intercepting your own route. May be an async provider. */
+    document?: unknown | (() => unknown | Promise<unknown>);
+    /** Override paid-operation detection. Default: the operation declares a 402 response or x-payment-info. */
+    isPaidOperation?: (method: string, path: string, operation: Record<string, any>) => boolean;
+    /** Append the rating sentence to paid operation descriptions. Default true. */
+    describeOperations?: boolean;
+}
+/** @deprecated Renamed to ForgeOptions. */
+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 */
+    backendUrl: string;
+    /** This service's public origin, e.g. https://pixels.gateway.clawca.sh. Never derived from the Host header. */
+    publicUrl: string;
+    /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
+    basePath?: string;
+    /** Append the rating sentence to x402 challenges (v2 header, v1 JSON body). Default true. */
+    describeChallenges?: boolean;
+    /** Override the appended sentence, for wording experiments. "{rate_url}" and "{summary_url}" are substituted. */
+    challengeSentence?: string;
+    /**
+     * Add a structured `forge-feedback` extension to x402 v2 challenges (next to e.g. `bazaar`), which clients
+     * that inspect the 402 print as its own block. Default true; `false` turns it off. v1 challenges have no extensions.
+     */
+    challengeExtension?: boolean;
+    /** Add feedback_id and feedback_url to JSON object bodies of paid responses. Default true. */
+    injectBody?: boolean;
+    /**
+     * The `rate_this_call` sentence added to paid JSON bodies: a soft, one-request ask next to the data the agent paid for.
+     * On by default; a string overrides the wording ("{feedback_url}" and "{summary_url}" are substituted); `false` turns it off.
+     */
+    rateHint?: boolean | string;
+    /**
+     * Append a two-line "feedback_id: … / feedback_url: …" trailer to text/plain paid responses. Default false.
+     * Changes the business payload, so enable it only when agents can't otherwise see the ID (e.g. awal shows
+     * the model the body but never headers).
+     */
+    injectText?: boolean;
+    /** Enrich your OpenAPI document. Default: intercept GET /openapi.json. `false` disables. */
+    openapi?: false | OpenApiOptions;
+    /** Must match the backend's FEEDBACK_TTL_HOURS; only used to reject stale IDs before a network call. */
+    ttlMs?: number;
+    flushIntervalMs?: number;
+    onError?: (error: unknown) => void;
+    fetch?: typeof fetch;
+    /**
+     * Throw on invalid options instead of warning and running disabled. Default false: a misconfigured Forge
+     * logs a warning, reports it in diagnostics(), and leaves your API running unchanged. Use true in CI.
+     */
+    strict?: boolean;
+}
+/** An incoming request, as the core needs to see it. */
+export interface ForgeRequest {
+    method: string;
+    /** Path relative to where Forge is mounted, without the query string. */
+    path: string;
+    header(name: string): string | undefined;
+    /** A query parameter; arrays are fine (the first value is used). */
+    query(name: string): unknown;
+    /** Parse the JSON body. Only called for POST {basePath}. Throw on invalid JSON or bodies over BODY_LIMIT. */
+    json(): Promise<unknown>;
+}
+/** A response the core produces itself (rating routes, a served spec). `body` is JSON; absent for 405. */
+export interface ForgeResponse {
+    status: number;
+    headers: Record<string, string>;
+    body?: unknown;
+}
+/** One request to a merchant route. Every method is fail-safe: on any error it returns the input unchanged. */
+export interface ForgeCall {
+    /** Set when the request carried a payment header (x402 v2 PAYMENT-SIGNATURE or v1 X-PAYMENT). */
+    readonly feedbackId: string | undefined;
+    /** A JSON body about to be sent: 402 challenges get the rating ask, paid 2xx objects get the feedback fields. */
+    json(status: number, body: unknown): unknown;
+    /** A text body about to be sent: gets the two-line trailer on paid 2xx text/plain when injectText is on. */
+    text(status: number, contentType: string, body: string): string;
+    /** Headers to set once the final status is known: a rewritten PAYMENT-REQUIRED on 402, Forge-Feedback-Id on paid 2xx. */
+    headers(status: number, paymentRequired: string | undefined): Record<string, string>;
+    /**
+     * Report the challenge / interaction events after the response is sent. A 402 counts as a challenge when
+     * headers() saw a PAYMENT-REQUIRED value or json() saw a challenge body; pass true if you know of one otherwise.
+     */
+    finish(status: number, hadChallengeHeader?: boolean): void;
+}
+export interface ForgeDiagnostics {
+    /** False when invalid options turned Forge off; the API runs unchanged. */
+    enabled: boolean;
+    /** Why Forge is disabled (invalid required options). */
+    configErrors: string[];
+    /** Invalid optional values that were replaced by their defaults. */
+    configWarnings: string[];
+    minted: number;
+    challengesDescribed: number;
+    eventsSent: number;
+    eventsDropped: number;
+    openapi: EnrichReport | null;
+    lastError?: string;
+}
+export interface ForgeCore {
+    /** False when invalid options turned Forge off. Every method then passes everything through. */
+    readonly enabled: boolean;
+    /** The sentence appended to x402 challenges and OpenAPI guidance. */
+    readonly challengeSentence: string;
+    /** Handle Forge's own routes ({basePath}, /rate, /summary, a static openapi.document). Null when not ours. */
+    route(request: ForgeRequest): Promise<ForgeResponse | null>;
+    /** Whether this is a GET for the merchant's own OpenAPI route, which the adapter should buffer and pass to enrichOpenApi. */
+    isSpecRequest(method: string, path: string): boolean;
+    /** Enrich an OpenAPI document (pure; the input is never mutated). Also lets body injection respect its schemas. */
+    enrichOpenApi(document: unknown): {
+        document: unknown;
+        report: EnrichReport;
+    };
+    /** Start observing a request to a merchant route. `path` is the full request path (used for route names). */
+    call(request: Pick<ForgeRequest, "method" | "path" | "header">): ForgeCall;
+    onError(error: unknown): void;
+    diagnostics(): ForgeDiagnostics;
+    /** Flush pending events. Call from your shutdown handler. */
+    shutdown(): Promise<void>;
+}
+export declare const FEEDBACK_HEADERS: {
+    "Cache-Control": string;
+    "X-Robots-Tag": string;
+};
+/** Max JSON body for POST {basePath}. */
+export declare const BODY_LIMIT: number;
+/** Max OpenAPI document an adapter should buffer for enrichment. */
+export declare const SPEC_LIMIT: number;
+/**
+ * Check options without throwing. Invalid required options are errors (Forge runs disabled);
+ * invalid optional values are warnings and fall back to their defaults.
+ */
+export declare function checkOptions(input: unknown): {
+    errors: string[];
+    warnings: string[];
+    options: ForgeOptions;
+};
+/**
+ * Never throws (unless `strict`): invalid required options log one warning and return a disabled core
+ * that passes everything through, so a misconfigured Forge can't take down your API or server.
+ */
+export declare function createForgeCore(input: ForgeOptions): ForgeCore;