@forgeintel/sdk 0.5.0-beta.4 → 0.5.0-beta.6

package/README.md

@@ -1,6 +1,6 @@
 # @forgeintel/sdk
 
-> **Beta.** Install with `npm install @forgeintel/sdk@beta`. The API may change before 1.0.
+> **Beta.** Install with `npm install @forgeintel/sdk`. 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.
 
@@ -10,9 +10,9 @@ 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_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)
+  apiKey: process.env.FORGE_API_KEY,
+  agentContext: false,
+  feedback: true,
 });
 
 app.use(forge.middleware());                        // 1. first: before payments and your /openapi.json route
@@ -26,7 +26,7 @@ Works with `@x402/express` (v2) and `x402-express` (v1), on Express 4.21+ or 5.
 ```ts
 import { createForge } from "@forgeintel/sdk/hono";
 
-const forge = createForge({ apiKey, backendUrl, publicUrl });
+const forge = createForge({ apiKey, agentContext: false, feedback: true });
 app.use(forge.middleware());                        // before paymentMiddleware from @x402/hono
 app.use(paymentMiddleware(routes, resourceServer));
 ```
@@ -36,7 +36,7 @@ app.use(paymentMiddleware(routes, resourceServer));
 ```ts
 import { createForge } from "@forgeintel/sdk/next";
 
-export const forge = createForge({ apiKey, backendUrl, publicUrl });
+export const forge = createForge({ apiKey, agentContext: false, feedback: true });
 // app/api/…/route.ts: Forge outermost, around @x402/next's withX402
 export const POST = forge.withForge(withX402(handler, route, resourceServer));
 // app/feedback/[[...path]]/route.ts: Forge's own routes
@@ -84,8 +84,8 @@ OpenAPI: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. Additive only; shared compone
 | 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. |
+| `backendUrl` | Forge production collector | Optional override for a different Forge environment. |
+| `publicUrl` | Same-origin paths | Optional public origin for absolute rating URLs. Never infer it from request headers. |
 | `feedback` | `true` | Master switch for rating prompts, IDs, response additions and feedback routes. `false` leaves telemetry, client headers and independent agent context on. |
 | `basePath` | `/feedback` | Feedback routes (`/feedback`, `/feedback/rate`, `/feedback/summary`). |
 | `tone` | `"soft"` | `"lifecycle"` describes this service's flow as four steps (402, pay, response, rate). Both stay soft asks. |
@@ -114,8 +114,6 @@ Client headers are captured automatically at discovery, challenge, payment, and
 ```ts
 const forge = createForge({
   apiKey: process.env.FORGE_API_KEY!,
-  backendUrl: "https://your-forge-backend.example/api/sdk/v2",
-  publicUrl: "https://api.example.com",
   agentContext: true,
 });
 ```

package/dist/core.d.ts

@@ -16,12 +16,12 @@ export interface ForgeOptions {
     /** Merchant API key issued by the Forge backend. Also the HMAC key for feedback IDs. */
     apiKey: string;
     /**
-     * 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.
+     * Optional collector override. Defaults to Forge's production /api/sdk/v2 collector.
+     * An origin-only override uses its /v1 routes; a URL with a path 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;
+    backendUrl?: string;
+    /** Optional public origin for absolute feedback links. By default links use same-origin paths. Never derived from the Host header. */
+    publicUrl?: string;
     /** Enable rating prompts, feedback IDs and feedback routes. Default true. Telemetry and agent context are independent. */
     feedback?: boolean;
     /** Path for the feedback routes. Default "/feedback" (quick rating at "/feedback/rate"). */
@@ -178,6 +178,7 @@ export declare const FEEDBACK_HEADERS: {
 export declare const BODY_LIMIT: number;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export declare const SPEC_LIMIT: number;
+export declare const DEFAULT_BACKEND_URL = "https://app-api.forgeintel.co/api/sdk/v2";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.

package/dist/core.js

@@ -14,6 +14,7 @@ export const FEEDBACK_HEADERS = { "Cache-Control": "no-store", "X-Robots-Tag": "
 export const BODY_LIMIT = 8 * 1024;
 /** Max OpenAPI document an adapter should buffer for enrichment. */
 export const SPEC_LIMIT = 10 * 1024 * 1024;
+export const DEFAULT_BACKEND_URL = "https://app-api.forgeintel.co/api/sdk/v2";
 /**
  * Check options without throwing. Invalid required options are errors (Forge runs disabled);
  * invalid optional values are warnings and fall back to their defaults.
@@ -36,10 +37,12 @@ export function checkOptions(input) {
     };
     if (typeof raw.apiKey !== "string" || !raw.apiKey.trim())
         errors.push("apiKey is missing (set it to your merchant key, ffk_…)");
-    if (!absoluteUrl(raw.backendUrl))
+    if (raw.backendUrl === undefined)
+        options.backendUrl = DEFAULT_BACKEND_URL;
+    else if (!absoluteUrl(raw.backendUrl))
         errors.push(`backendUrl must be an absolute http(s) URL (got ${JSON.stringify(raw.backendUrl ?? null)})`);
-    if (!absoluteUrl(raw.publicUrl))
-        errors.push(`publicUrl must be an absolute http(s) URL, this service's public origin (got ${JSON.stringify(raw.publicUrl ?? null)})`);
+    if (raw.publicUrl !== undefined && !absoluteUrl(raw.publicUrl))
+        errors.push(`publicUrl must be an absolute http(s) URL (got ${JSON.stringify(raw.publicUrl ?? null)})`);
     const fallback = (key, ok, expected) => {
         if (raw[key] === undefined || ok)
             return;
@@ -156,17 +159,19 @@ export function createForgeCore(input) {
     }
 }
 function enabledCore(options, configWarnings) {
-    const { apiKey, backendUrl, publicUrl } = options;
+    const { apiKey, publicUrl } = options;
+    const backendUrl = options.backendUrl ?? DEFAULT_BACKEND_URL;
     // 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;
-    const formUrl = new URL(basePath, publicUrl).href;
+    const sameOriginUrl = (path) => publicUrl ? new URL(path, publicUrl).href : path;
+    const rateUrl = sameOriginUrl(ratePath);
+    const formUrl = sameOriginUrl(basePath);
     const summaryPath = `${basePath}/summary`;
-    const summaryUrl = new URL(summaryPath, publicUrl).href;
+    const summaryUrl = sameOriginUrl(summaryPath);
     const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
     const fetchImpl = options.fetch ?? fetch;
     const feedback = options.feedback !== false;

package/dist/openapi.d.ts

@@ -4,8 +4,8 @@ export type ResponseSupport = "extended" | "incompatible" | "undocumented";
 export interface EnrichOptions {
     /** Disable all feedback additions while retaining enabled agent context. */
     feedback?: boolean;
-    /** Merchant public origin, e.g. https://api.example.com */
-    publicUrl: string;
+    /** Optional merchant public origin. Without it, feedback links use same-origin paths. */
+    publicUrl?: string;
     /** Public path of the feedback routes, e.g. /feedback */
     basePath: string;
     /** Sentence appended to x-guidance and paid operation descriptions. */

package/dist/openapi.js

@@ -46,7 +46,7 @@ function feedbackProperties(rateUrl, hintField = false) {
         },
         feedback_url: {
             type: "string",
-            format: "uri",
+            format: "uri-reference",
             description: `Quick-rating URL with outcome left blank; outcome values: ${Object.keys(OUTCOMES).join(", ")}. Base: ${rateUrl}`,
         },
     };
@@ -170,20 +170,21 @@ function appendSentence(text, sentence, marker) {
 }
 /** Work out the path prefix document paths are relative to, and whether it's this service's origin. */
 function serverBase(doc, version, publicUrl) {
-    const origin = new URL(publicUrl).origin;
+    const origin = publicUrl ? new URL(publicUrl).origin : undefined;
+    const baseUrl = publicUrl ?? "https://forge.invalid";
     try {
         if (version === "2.0") {
-            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(publicUrl).protocol.slice(0, -1);
+            const scheme = Array.isArray(doc.schemes) && doc.schemes[0] ? doc.schemes[0] : new URL(baseUrl).protocol.slice(0, -1);
             const base = typeof doc.basePath === "string" ? doc.basePath : "";
-            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", publicUrl);
-            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+            const url = typeof doc.host === "string" ? new URL(`${scheme}://${doc.host}${base}`) : new URL(base || "/", baseUrl);
+            return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
         }
         const server = Array.isArray(doc.servers) ? doc.servers[0] : undefined;
         if (!isObj(server) || typeof server.url !== "string")
             return { prefix: "", sameOrigin: true };
         const raw = server.url.replace(/\{([^}]+)\}/g, (_, name) => server.variables?.[name]?.default ?? "");
-        const url = new URL(raw, publicUrl);
-        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: url.origin === origin };
+        const url = new URL(raw, baseUrl);
+        return { prefix: url.pathname.replace(/\/+$/, ""), sameOrigin: !origin || url.origin === origin };
     }
     catch {
         return { prefix: "", sameOrigin: false };
@@ -262,7 +263,7 @@ export function enrichOpenApi(input, options) {
     }
     try {
         const doc = clone(original);
-        const origin = new URL(options.publicUrl).origin;
+        const origin = options.publicUrl ? new URL(options.publicUrl).origin : "";
         const base = options.basePath.replace(/\/+$/, "");
         const rateUrl = `${origin}${base}/rate`;
         const formUrl = `${origin}${base}`;
@@ -377,7 +378,7 @@ export function enrichOpenApi(input, options) {
         }
         else {
             const ops = feedbackOperations(version, formUrl, rateUrl, operationIds);
-            const servers = inPrefix ? {} : { servers: [{ url: origin }] };
+            const servers = inPrefix ? {} : { servers: [{ url: origin || "/" }] };
             paths[docBase] = { ...servers, get: ops.form, post: ops.submit };
             paths[`${docBase}/rate`] = { ...servers, get: ops.rate };
             paths[`${docBase}/summary`] = { ...servers, get: ops.summary };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeintel/sdk",
-  "version": "0.5.0-beta.4",
+  "version": "0.5.0-beta.6",
   "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",
@@ -73,7 +73,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "tag": "beta"
+    "tag": "latest"
   },
   "peerDependencies": {
     "express": ">=4.21 <6",