@clawcash/forge 0.1.0 → 0.1.4

package/README.md

@@ -10,17 +10,7 @@ Published under the [ClawCash](https://www.npmjs.com/org/clawcash) npm org.
 npm install @clawcash/forge express
 ```
 
-For local demo against the sibling folder:
-
-```json
-{
-  "dependencies": {
-    "@clawcash/forge": "file:../forge-sdk"
-  }
-}
-```
-
-## Quick start
+## Quick start (no PAY_TO env required)
 
 ```ts
 import express from "express";
@@ -37,8 +27,6 @@ const removeBackground = defineAgentService({
     protocols: ["x402"],
   },
   async execute({ imageUrl }, context) {
-    // Call your existing multi-step APIs here.
-    // Use context.waitUntil to poll jobs.
     return { resultUrl: "https://example.com/out.png" };
   },
 });
@@ -46,24 +34,32 @@ const removeBackground = defineAgentService({
 const app = express();
 app.use(express.json());
 
-mountAgentServices(app, [removeBackground], {
-  payTo: process.env.PAY_TO!,
-  facilitatorUrl: process.env.FACILITATOR_URL,
+await mountAgentServices(app, [removeBackground], {
+  // Baked in by Forge PR — works with zero host env for payments
+  payToFallback: "0xYourForgeWallet",
+  forge: {
+    owner: "acme",
+    repo: "my-app",
+    baseUrl: process.env.FORGE_URL ?? "https://forge.clawca.sh",
+  },
 });
 
 app.listen(3000);
 ```
 
+Resolution order: `PAY_TO` env (optional override) → live Forge API → `payToFallback`.
+
 Agents call `POST /agent/remove-background` and pay via x402 when challenged with HTTP 402.
 
-Default payment network is **Base Sepolia** (`eip155:84532`), which the public `https://x402.org/facilitator` supports. Override per service with `payment.network`.
+Default payment network is **Base mainnet** (`eip155:8453`) via the public **XPay** facilitator (`https://facilitator.xpay.sh`) — no API keys.
 
 ## API
 
 | Export | Purpose |
 |--------|---------|
 | `defineAgentService` | Declare name, schemas, payment, and `execute` |
-| `mountAgentServices` | Mount `POST /agent/:name` with x402 |
+| `mountAgentServices` | Async mount `POST /agent/:name` with x402 |
+| `resolvePayTo` | Resolve merchant wallet (env → Forge → fallback) |
 | `generateSkillMarkdown` | Build a `SKILL.md` for agents |
 | `waitUntil` / `context.waitUntil` | Poll until a job completes |
 

package/dist/index.cjs

@@ -24,7 +24,10 @@ __export(index_exports, {
   createForgeRouter: () => createForgeRouter,
   defineAgentService: () => defineAgentService,
   generateSkillMarkdown: () => generateSkillMarkdown,
+  heartbeatGateway: () => heartbeatGateway,
+  isZeroAddress: () => isZeroAddress,
   mountAgentServices: () => mountAgentServices,
+  resolvePayTo: () => resolvePayTo,
   toKebabCase: () => toKebabCase,
   waitUntil: () => waitUntil
 });
@@ -73,11 +76,101 @@ var import_express = require("express");
 var import_express2 = require("@x402/express");
 var import_server = require("@x402/core/server");
 var import_server2 = require("@x402/evm/exact/server");
-var DEFAULT_NETWORK = "eip155:84532";
-var DEFAULT_FACILITATOR = "https://x402.org/facilitator";
+
+// src/gateway.ts
+async function heartbeatGateway(opts) {
+  const gateway = opts.gatewayUrl.replace(/\/$/, "");
+  const res = await fetch(`${gateway}/register/heartbeat`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${opts.registerSecret}`
+    },
+    body: JSON.stringify({
+      handle: opts.handle.trim().toLowerCase(),
+      baseUrl: opts.baseUrl.replace(/\/$/, "")
+    })
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(
+      `gateway heartbeat failed (${res.status}): ${text.slice(0, 240)}`
+    );
+  }
+}
+
+// src/payto.ts
+var ZERO = /^0x0{40}$/i;
+function isZeroAddress(address) {
+  if (!address) return true;
+  return ZERO.test(address.trim());
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/$/, "");
+}
+function pickForgeBaseUrl(source) {
+  const fromEnv = process.env.FORGE_URL?.trim();
+  if (fromEnv) return normalizeBaseUrl(fromEnv);
+  const fromOpts = source?.baseUrl?.trim();
+  if (!fromOpts) return null;
+  const normalized = normalizeBaseUrl(fromOpts);
+  if (/localhost|127\.0\.0\.1/i.test(normalized) && process.env.NODE_ENV === "production") {
+    return null;
+  }
+  return normalized;
+}
+async function resolvePayTo(opts) {
+  const envOverride = process.env.PAY_TO?.trim();
+  if (envOverride && !isZeroAddress(envOverride)) {
+    return envOverride;
+  }
+  const explicit = opts.payTo?.trim();
+  if (explicit && !isZeroAddress(explicit) && !opts.forge) {
+    return explicit;
+  }
+  const baseUrl = pickForgeBaseUrl(opts.forge);
+  if (baseUrl && opts.forge) {
+    const url = `${baseUrl}/api/public/pay-to/${encodeURIComponent(opts.forge.owner)}/${encodeURIComponent(opts.forge.repo)}`;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(
+        () => controller.abort(),
+        opts.timeoutMs ?? 2500
+      );
+      const res = await fetch(url, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      clearTimeout(timer);
+      if (res.ok) {
+        const json = await res.json();
+        if (json.address && !isZeroAddress(json.address)) {
+          return json.address.trim();
+        }
+      }
+    } catch (err) {
+      console.warn("[forge] live payTo fetch failed, using fallback:", err);
+    }
+  }
+  if (explicit && !isZeroAddress(explicit)) return explicit;
+  if (opts.fallback && !isZeroAddress(opts.fallback)) return opts.fallback;
+  throw new Error(
+    "resolvePayTo: no usable address (set Forge wallet / PAY_TO, or re-run Forge PR)"
+  );
+}
+
+// src/mount.ts
+var DEFAULT_NETWORK = "eip155:8453";
+var DEFAULT_FACILITATOR_URL = "https://facilitator.xpay.sh";
 function asNetwork(value) {
   return value ?? DEFAULT_NETWORK;
 }
+function createFacilitatorClient(options) {
+  return new import_server.HTTPFacilitatorClient({
+    url: options.facilitatorUrl ?? DEFAULT_FACILITATOR_URL,
+    createAuthHeaders: options.createAuthHeaders
+  });
+}
 function validateInput(body, schema) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     return { ok: false, error: "Request body must be a JSON object" };
@@ -127,9 +220,20 @@ function formatPrice(amount) {
   const normalized = amount.startsWith("$") ? amount.slice(1) : amount;
   return `$${normalized}`;
 }
-function mountAgentServices(app, services, options) {
-  if (!options.payTo && !options.skipPayment) {
-    throw new Error("mountAgentServices: payTo is required unless skipPayment is true");
+async function mountAgentServices(app, services, options) {
+  let payTo = "";
+  if (!options.skipPayment) {
+    const fallback = options.payToFallback?.trim() || options.payTo?.trim() || "";
+    payTo = await resolvePayTo({
+      fallback,
+      payTo: options.payTo,
+      forge: options.forge
+    });
+    if (isZeroAddress(payTo)) {
+      throw new Error(
+        "mountAgentServices: resolved payTo is the zero address. Re-run Forge to provision a wallet."
+      );
+    }
   }
   const basePath = (options.basePath ?? "/agent").replace(/\/$/, "") || "/agent";
   const router = (0, import_express.Router)();
@@ -145,7 +249,7 @@ function mountAgentServices(app, services, options) {
           scheme: "exact",
           price: formatPrice(service.payment.amount),
           network,
-          payTo: options.payTo
+          payTo
         },
         description: service.description,
         mimeType: "application/json"
@@ -168,9 +272,7 @@ function mountAgentServices(app, services, options) {
     });
   }
   if (!options.skipPayment && Object.keys(routes).length > 0) {
-    const facilitator = new import_server.HTTPFacilitatorClient({
-      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR
-    });
+    const facilitator = createFacilitatorClient(options);
     const networks = new Set(
       services.map((s) => asNetwork(s.payment.network))
     );
@@ -181,6 +283,20 @@ function mountAgentServices(app, services, options) {
     app.use((0, import_express2.paymentMiddleware)(routes, resourceServer, void 0, void 0, true));
   }
   app.use(basePath, router);
+  const gatewayUrl = options.gateway?.url?.trim() || process.env.GATEWAY_URL?.trim();
+  const handle = options.gateway?.handle?.trim() || process.env.FORGE_HANDLE?.trim();
+  const registerSecret = options.gateway?.registerSecret?.trim() || process.env.GATEWAY_REGISTER_SECRET?.trim();
+  const publicBaseUrl = options.gateway?.publicBaseUrl?.trim() || process.env.PUBLIC_BASE_URL?.trim() || (process.env.RAILWAY_PUBLIC_DOMAIN ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}` : "");
+  if (gatewayUrl && handle && registerSecret && publicBaseUrl) {
+    void heartbeatGateway({
+      gatewayUrl,
+      handle,
+      baseUrl: publicBaseUrl,
+      registerSecret
+    }).catch((err) => {
+      console.warn("[forge] gateway heartbeat skipped:", err);
+    });
+  }
   return router;
 }
 function createForgeRouter(services, options) {
@@ -276,7 +392,10 @@ function generateSkillMarkdown(services, meta) {
   createForgeRouter,
   defineAgentService,
   generateSkillMarkdown,
+  heartbeatGateway,
+  isZeroAddress,
   mountAgentServices,
+  resolvePayTo,
   toKebabCase,
   waitUntil
 });

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/define.ts","../src/mount.ts","../src/skill.ts"],"sourcesContent":["export { defineAgentService, waitUntil, createContext, toKebabCase } from \"./define.js\";\nexport { mountAgentServices, createForgeRouter } from \"./mount.js\";\nexport { generateSkillMarkdown } from \"./skill.js\";\nexport type {\n  SchemaFieldType,\n  InputSchema,\n  OutputSchema,\n  PaymentConfig,\n  WaitUntilOptions,\n  AgentServiceContext,\n  AgentServiceConfig,\n  DefinedAgentService,\n  MountOptions,\n  SkillMeta,\n} from \"./types.js\";\n","import type {\n  AgentServiceConfig,\n  AgentServiceContext,\n  DefinedAgentService,\n  WaitUntilOptions,\n} from \"./types.js\";\n\nexport async function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T> {\n  const intervalMs = options.intervalMs ?? 500;\n  const timeoutMs = options.timeoutMs ?? 60_000;\n  const started = Date.now();\n\n  for (;;) {\n    const value = await options.run();\n    if (options.completedWhen(value)) {\n      return value;\n    }\n    if (Date.now() - started >= timeoutMs) {\n      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);\n    }\n    await new Promise((resolve) => setTimeout(resolve, intervalMs));\n  }\n}\n\nexport function createContext(): AgentServiceContext {\n  return {\n    waitUntil,\n  };\n}\n\n/** Convert snake_case or camelCase service name to kebab-case path segment. */\nexport function toKebabCase(name: string): string {\n  return name\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .replace(/_/g, \"-\")\n    .toLowerCase();\n}\n\nexport function defineAgentService<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> = Record<string, unknown>,\n>(\n  config: AgentServiceConfig<TInput, TOutput>,\n): DefinedAgentService<TInput, TOutput> {\n  if (!config.name?.trim()) {\n    throw new Error(\"defineAgentService: name is required\");\n  }\n  if (!config.execute) {\n    throw new Error(\"defineAgentService: execute is required\");\n  }\n\n  return {\n    ...config,\n    __forge: true,\n    path: toKebabCase(config.name),\n  };\n}\n","import type { Application, Request, Response, NextFunction, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport { paymentMiddleware, x402ResourceServer } from \"@x402/express\";\nimport type { Network } from \"@x402/express\";\nimport { HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { RoutesConfig } from \"@x402/core/server\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/server\";\nimport { createContext } from \"./define.js\";\nimport type {\n  DefinedAgentService,\n  InputSchema,\n  MountOptions,\n  SchemaFieldType,\n} from \"./types.js\";\n\n/** Base Sepolia — supported by the public x402.org facilitator for demos. */\nconst DEFAULT_NETWORK = \"eip155:84532\" as const satisfies Network;\nconst DEFAULT_FACILITATOR = \"https://x402.org/facilitator\";\n\nfunction asNetwork(value: string | undefined): Network {\n  return (value ?? DEFAULT_NETWORK) as Network;\n}\n\nfunction validateInput(\n  body: unknown,\n  schema: InputSchema,\n): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } {\n  if (!body || typeof body !== \"object\" || Array.isArray(body)) {\n    return { ok: false, error: \"Request body must be a JSON object\" };\n  }\n\n  const input = body as Record<string, unknown>;\n  const value: Record<string, unknown> = {};\n\n  for (const [key, type] of Object.entries(schema)) {\n    if (!(key in input) || input[key] === undefined || input[key] === null) {\n      return { ok: false, error: `Missing required field: ${key}` };\n    }\n    const err = checkType(key, input[key], type);\n    if (err) return { ok: false, error: err };\n    value[key] = input[key];\n  }\n\n  return { ok: true, value };\n}\n\nfunction checkType(key: string, value: unknown, type: SchemaFieldType): string | null {\n  switch (type) {\n    case \"string\":\n    case \"url\":\n      if (typeof value !== \"string\" || !value.trim()) {\n        return `Field ${key} must be a non-empty string`;\n      }\n      if (type === \"url\") {\n        try {\n          new URL(value);\n        } catch {\n          return `Field ${key} must be a valid URL`;\n        }\n      }\n      return null;\n    case \"number\":\n      if (typeof value !== \"number\" || Number.isNaN(value)) {\n        return `Field ${key} must be a number`;\n      }\n      return null;\n    case \"boolean\":\n      if (typeof value !== \"boolean\") {\n        return `Field ${key} must be a boolean`;\n      }\n      return null;\n    default:\n      return null;\n  }\n}\n\nfunction formatPrice(amount: string): string {\n  const normalized = amount.startsWith(\"$\") ? amount.slice(1) : amount;\n  return `$${normalized}`;\n}\n\n/**\n * Mount Forge agent services on an Express app.\n * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.\n */\nexport function mountAgentServices(\n  app: Application,\n  services: DefinedAgentService[],\n  options: MountOptions,\n): Router {\n  if (!options.payTo && !options.skipPayment) {\n    throw new Error(\"mountAgentServices: payTo is required unless skipPayment is true\");\n  }\n\n  const basePath = (options.basePath ?? \"/agent\").replace(/\\/$/, \"\") || \"/agent\";\n  const router = createRouter();\n  const context = createContext();\n\n  const routes: RoutesConfig = {};\n\n  for (const service of services) {\n    const routePath = `/${service.path}`;\n    const fullPath = `${basePath}${routePath}`;\n    const network = asNetwork(service.payment.network);\n\n    if (!options.skipPayment) {\n      routes[`POST ${fullPath}`] = {\n        accepts: {\n          scheme: \"exact\",\n          price: formatPrice(service.payment.amount),\n          network,\n          payTo: options.payTo,\n        },\n        description: service.description,\n        mimeType: \"application/json\",\n      };\n    }\n\n    router.post(routePath, async (req: Request, res: Response) => {\n      try {\n        const validated = validateInput(req.body, service.input);\n        if (!validated.ok) {\n          res.status(400).json({ error: validated.error });\n          return;\n        }\n\n        const output = await service.execute(validated.value, context);\n        res.json(output);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : \"Internal error\";\n        console.error(`[forge] ${service.name} failed:`, err);\n        res.status(500).json({ error: message });\n      }\n    });\n  }\n\n  if (!options.skipPayment && Object.keys(routes).length > 0) {\n    const facilitator = new HTTPFacilitatorClient({\n      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR,\n    });\n    const networks = new Set(\n      services.map((s) => asNetwork(s.payment.network)),\n    );\n    const resourceServer = new x402ResourceServer(facilitator);\n    for (const network of networks) {\n      resourceServer.register(network, new ExactEvmScheme());\n    }\n    // syncFacilitatorOnStart validates scheme/network against the facilitator\n    app.use(paymentMiddleware(routes, resourceServer, undefined, undefined, true));\n  }\n\n  app.use(basePath, router);\n  return router;\n}\n\n/** Express-compatible middleware alias used in docs. */\nexport function createForgeRouter(\n  services: DefinedAgentService[],\n  options: MountOptions,\n): (app: Application) => Router {\n  return (app) => mountAgentServices(app, services, options);\n}\n\n/** Optional no-op next for typing convenience in tests. */\nexport function forgeErrorHandler(\n  err: unknown,\n  _req: Request,\n  res: Response,\n  _next: NextFunction,\n): void {\n  const message = err instanceof Error ? err.message : \"Internal error\";\n  res.status(500).json({ error: message });\n}\n","import type { DefinedAgentService, SkillMeta } from \"./types.js\";\n\n/**\n * Generate a SKILL.md document for agents from defined Forge services.\n */\nexport function generateSkillMarkdown(\n  services: DefinedAgentService[],\n  meta: SkillMeta,\n): string {\n  const base = meta.baseUrl.replace(/\\/$/, \"\");\n  const lines: string[] = [\n    `---`,\n    `name: ${meta.name}`,\n    `description: ${meta.description}`,\n    `---`,\n    ``,\n    `# ${meta.name}`,\n    ``,\n    meta.description,\n    ``,\n  ];\n\n  if (meta.homepage) {\n    lines.push(`Homepage: ${meta.homepage}`, ``);\n  }\n\n  lines.push(\n    `## How to use`,\n    ``,\n    `1. Read this skill.`,\n    `2. Call the agent endpoint with a JSON body matching the input schema.`,\n    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,\n    `4. Use the returned output fields.`,\n    ``,\n    `## Services`,\n    ``,\n  );\n\n  for (const service of services) {\n    const path = `${base}/agent/${service.path}`;\n    const price = service.payment.amount.startsWith(\"$\")\n      ? service.payment.amount\n      : `$${service.payment.amount}`;\n\n    lines.push(\n      `### \\`${service.name}\\``,\n      ``,\n      service.description,\n      ``,\n      `- **Method:** \\`POST\\``,\n      `- **URL:** \\`${path}\\``,\n      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(\", \")}`,\n      ``,\n      `**Input**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Output**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Example**`,\n      ``,\n      \"```bash\",\n      `curl -X POST ${path} \\\\`,\n      `  -H \"Content-Type: application/json\" \\\\`,\n      `  -d '${JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [\n            k,\n            t === \"url\" ? \"https://example.com/image.png\" : `example-${k}`,\n          ]),\n        ),\n      )}'`,\n      \"```\",\n      ``,\n    );\n  }\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":["import_express","import_server","createRouter"]}
+{"version":3,"sources":["../src/index.ts","../src/define.ts","../src/mount.ts","../src/gateway.ts","../src/payto.ts","../src/skill.ts"],"sourcesContent":["export { defineAgentService, waitUntil, createContext, toKebabCase } from \"./define.js\";\nexport { mountAgentServices, createForgeRouter } from \"./mount.js\";\nexport { generateSkillMarkdown } from \"./skill.js\";\nexport { resolvePayTo, isZeroAddress } from \"./payto.js\";\nexport { heartbeatGateway } from \"./gateway.js\";\nexport type {\n  SchemaFieldType,\n  InputSchema,\n  OutputSchema,\n  PaymentConfig,\n  WaitUntilOptions,\n  AgentServiceContext,\n  AgentServiceConfig,\n  DefinedAgentService,\n  MountOptions,\n  ForgePayToSource,\n  SkillMeta,\n} from \"./types.js\";\n","import type {\n  AgentServiceConfig,\n  AgentServiceContext,\n  DefinedAgentService,\n  WaitUntilOptions,\n} from \"./types.js\";\n\nexport async function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T> {\n  const intervalMs = options.intervalMs ?? 500;\n  const timeoutMs = options.timeoutMs ?? 60_000;\n  const started = Date.now();\n\n  for (;;) {\n    const value = await options.run();\n    if (options.completedWhen(value)) {\n      return value;\n    }\n    if (Date.now() - started >= timeoutMs) {\n      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);\n    }\n    await new Promise((resolve) => setTimeout(resolve, intervalMs));\n  }\n}\n\nexport function createContext(): AgentServiceContext {\n  return {\n    waitUntil,\n  };\n}\n\n/** Convert snake_case or camelCase service name to kebab-case path segment. */\nexport function toKebabCase(name: string): string {\n  return name\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .replace(/_/g, \"-\")\n    .toLowerCase();\n}\n\nexport function defineAgentService<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> = Record<string, unknown>,\n>(\n  config: AgentServiceConfig<TInput, TOutput>,\n): DefinedAgentService<TInput, TOutput> {\n  if (!config.name?.trim()) {\n    throw new Error(\"defineAgentService: name is required\");\n  }\n  if (!config.execute) {\n    throw new Error(\"defineAgentService: execute is required\");\n  }\n\n  return {\n    ...config,\n    __forge: true,\n    path: toKebabCase(config.name),\n  };\n}\n","import type { Application, Request, Response, NextFunction, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport { paymentMiddleware, x402ResourceServer } from \"@x402/express\";\nimport type { Network } from \"@x402/express\";\nimport { HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { RoutesConfig } from \"@x402/core/server\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/server\";\nimport { createContext } from \"./define.js\";\nimport { heartbeatGateway } from \"./gateway.js\";\nimport { isZeroAddress, resolvePayTo } from \"./payto.js\";\nimport type {\n  DefinedAgentService,\n  InputSchema,\n  MountOptions,\n  SchemaFieldType,\n} from \"./types.js\";\n\n/** Base mainnet — settled via the public XPay facilitator (no API keys). */\nconst DEFAULT_NETWORK = \"eip155:8453\" as const satisfies Network;\n/** Open facilitator: Base mainnet + Sepolia, no API keys. https://github.com/xpaysh/xpay-x402 */\nconst DEFAULT_FACILITATOR_URL = \"https://facilitator.xpay.sh\";\n\nfunction asNetwork(value: string | undefined): Network {\n  return (value ?? DEFAULT_NETWORK) as Network;\n}\n\nfunction createFacilitatorClient(options: MountOptions): HTTPFacilitatorClient {\n  return new HTTPFacilitatorClient({\n    url: options.facilitatorUrl ?? DEFAULT_FACILITATOR_URL,\n    createAuthHeaders: options.createAuthHeaders,\n  });\n}\n\nfunction validateInput(\n  body: unknown,\n  schema: InputSchema,\n): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } {\n  if (!body || typeof body !== \"object\" || Array.isArray(body)) {\n    return { ok: false, error: \"Request body must be a JSON object\" };\n  }\n\n  const input = body as Record<string, unknown>;\n  const value: Record<string, unknown> = {};\n\n  for (const [key, type] of Object.entries(schema)) {\n    if (!(key in input) || input[key] === undefined || input[key] === null) {\n      return { ok: false, error: `Missing required field: ${key}` };\n    }\n    const err = checkType(key, input[key], type);\n    if (err) return { ok: false, error: err };\n    value[key] = input[key];\n  }\n\n  return { ok: true, value };\n}\n\nfunction checkType(key: string, value: unknown, type: SchemaFieldType): string | null {\n  switch (type) {\n    case \"string\":\n    case \"url\":\n      if (typeof value !== \"string\" || !value.trim()) {\n        return `Field ${key} must be a non-empty string`;\n      }\n      if (type === \"url\") {\n        try {\n          new URL(value);\n        } catch {\n          return `Field ${key} must be a valid URL`;\n        }\n      }\n      return null;\n    case \"number\":\n      if (typeof value !== \"number\" || Number.isNaN(value)) {\n        return `Field ${key} must be a number`;\n      }\n      return null;\n    case \"boolean\":\n      if (typeof value !== \"boolean\") {\n        return `Field ${key} must be a boolean`;\n      }\n      return null;\n    default:\n      return null;\n  }\n}\n\nfunction formatPrice(amount: string): string {\n  const normalized = amount.startsWith(\"$\") ? amount.slice(1) : amount;\n  return `$${normalized}`;\n}\n\n/**\n * Mount Forge agent services on an Express app.\n * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.\n *\n * payTo resolves automatically: PAY_TO env (optional) → Forge API → baked fallback.\n * Merchants should not need to configure PAY_TO on Railway for the happy path.\n */\nexport async function mountAgentServices(\n  app: Application,\n  services: DefinedAgentService[],\n  options: MountOptions,\n): Promise<Router> {\n  let payTo = \"\";\n  if (!options.skipPayment) {\n    const fallback =\n      options.payToFallback?.trim() || options.payTo?.trim() || \"\";\n    payTo = await resolvePayTo({\n      fallback,\n      payTo: options.payTo,\n      forge: options.forge,\n    });\n    if (isZeroAddress(payTo)) {\n      throw new Error(\n        \"mountAgentServices: resolved payTo is the zero address. Re-run Forge to provision a wallet.\",\n      );\n    }\n  }\n\n  const basePath = (options.basePath ?? \"/agent\").replace(/\\/$/, \"\") || \"/agent\";\n  const router = createRouter();\n  const context = createContext();\n\n  const routes: RoutesConfig = {};\n\n  for (const service of services) {\n    const routePath = `/${service.path}`;\n    const fullPath = `${basePath}${routePath}`;\n    const network = asNetwork(service.payment.network);\n\n    if (!options.skipPayment) {\n      routes[`POST ${fullPath}`] = {\n        accepts: {\n          scheme: \"exact\",\n          price: formatPrice(service.payment.amount),\n          network,\n          payTo,\n        },\n        description: service.description,\n        mimeType: \"application/json\",\n      };\n    }\n\n    router.post(routePath, async (req: Request, res: Response) => {\n      try {\n        const validated = validateInput(req.body, service.input);\n        if (!validated.ok) {\n          res.status(400).json({ error: validated.error });\n          return;\n        }\n\n        const output = await service.execute(validated.value, context);\n        res.json(output);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : \"Internal error\";\n        console.error(`[forge] ${service.name} failed:`, err);\n        res.status(500).json({ error: message });\n      }\n    });\n  }\n\n  if (!options.skipPayment && Object.keys(routes).length > 0) {\n    const facilitator = createFacilitatorClient(options);\n    const networks = new Set(\n      services.map((s) => asNetwork(s.payment.network)),\n    );\n    const resourceServer = new x402ResourceServer(facilitator);\n    for (const network of networks) {\n      resourceServer.register(network, new ExactEvmScheme());\n    }\n    app.use(paymentMiddleware(routes, resourceServer, undefined, undefined, true));\n  }\n\n  app.use(basePath, router);\n\n  // Fire-and-forget baseUrl heartbeat so gateway fulfillment stays current.\n  const gatewayUrl =\n    options.gateway?.url?.trim() || process.env.GATEWAY_URL?.trim();\n  const handle =\n    options.gateway?.handle?.trim() || process.env.FORGE_HANDLE?.trim();\n  const registerSecret =\n    options.gateway?.registerSecret?.trim() ||\n    process.env.GATEWAY_REGISTER_SECRET?.trim();\n  const publicBaseUrl =\n    options.gateway?.publicBaseUrl?.trim() ||\n    process.env.PUBLIC_BASE_URL?.trim() ||\n    (process.env.RAILWAY_PUBLIC_DOMAIN\n      ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`\n      : \"\");\n\n  if (gatewayUrl && handle && registerSecret && publicBaseUrl) {\n    void heartbeatGateway({\n      gatewayUrl,\n      handle,\n      baseUrl: publicBaseUrl,\n      registerSecret,\n    }).catch((err) => {\n      console.warn(\"[forge] gateway heartbeat skipped:\", err);\n    });\n  }\n\n  return router;\n}\n\n/** Express-compatible middleware alias used in docs. */\nexport function createForgeRouter(\n  services: DefinedAgentService[],\n  options: MountOptions,\n): (app: Application) => Promise<Router> {\n  return (app) => mountAgentServices(app, services, options);\n}\n\n/** Optional no-op next for typing convenience in tests. */\nexport function forgeErrorHandler(\n  err: unknown,\n  _req: Request,\n  res: Response,\n  _next: NextFunction,\n): void {\n  const message = err instanceof Error ? err.message : \"Internal error\";\n  res.status(500).json({ error: message });\n}\n","/**\n * Notify ClawCash gateway of this merchant's live public base URL.\n * Full action registration still happens from Forge \"Go live\".\n */\nexport async function heartbeatGateway(opts: {\n  gatewayUrl: string;\n  handle: string;\n  baseUrl: string;\n  registerSecret: string;\n}): Promise<void> {\n  const gateway = opts.gatewayUrl.replace(/\\/$/, \"\");\n  const res = await fetch(`${gateway}/register/heartbeat`, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      authorization: `Bearer ${opts.registerSecret}`,\n    },\n    body: JSON.stringify({\n      handle: opts.handle.trim().toLowerCase(),\n      baseUrl: opts.baseUrl.replace(/\\/$/, \"\"),\n    }),\n  });\n  if (!res.ok) {\n    const text = await res.text();\n    throw new Error(\n      `gateway heartbeat failed (${res.status}): ${text.slice(0, 240)}`,\n    );\n  }\n}\n","import type { ForgePayToSource } from \"./types.js\";\n\nexport type { ForgePayToSource };\n\nconst ZERO = /^0x0{40}$/i;\n\nexport function isZeroAddress(address: string | undefined | null): boolean {\n  if (!address) return true;\n  return ZERO.test(address.trim());\n}\n\nfunction normalizeBaseUrl(url: string): string {\n  return url.replace(/\\/$/, \"\");\n}\n\nfunction pickForgeBaseUrl(source?: ForgePayToSource): string | null {\n  const fromEnv = process.env.FORGE_URL?.trim();\n  if (fromEnv) return normalizeBaseUrl(fromEnv);\n\n  const fromOpts = source?.baseUrl?.trim();\n  if (!fromOpts) return null;\n\n  const normalized = normalizeBaseUrl(fromOpts);\n  // Never call a laptop Forge from a deployed merchant app.\n  if (\n    /localhost|127\\.0\\.0\\.1/i.test(normalized) &&\n    process.env.NODE_ENV === \"production\"\n  ) {\n    return null;\n  }\n  return normalized;\n}\n\n/**\n * Resolve merchant payTo with minimal host config:\n * 1. `PAY_TO` env (optional override)\n * 2. Live address from Forge public API (when reachable)\n * 3. Baked-in fallback from the Forge PR\n */\nexport async function resolvePayTo(opts: {\n  /** Baked-in address from Forge codegen (required fallback). */\n  fallback: string;\n  /** Optional explicit override (usually process.env.PAY_TO). */\n  payTo?: string;\n  forge?: ForgePayToSource;\n  /** Fetch timeout ms. Defaults to 2500. */\n  timeoutMs?: number;\n}): Promise<string> {\n  const envOverride = process.env.PAY_TO?.trim();\n  if (envOverride && !isZeroAddress(envOverride)) {\n    return envOverride;\n  }\n\n  const explicit = opts.payTo?.trim();\n  if (explicit && !isZeroAddress(explicit) && !opts.forge) {\n    return explicit;\n  }\n\n  const baseUrl = pickForgeBaseUrl(opts.forge);\n  if (baseUrl && opts.forge) {\n    const url = `${baseUrl}/api/public/pay-to/${encodeURIComponent(opts.forge.owner)}/${encodeURIComponent(opts.forge.repo)}`;\n    try {\n      const controller = new AbortController();\n      const timer = setTimeout(\n        () => controller.abort(),\n        opts.timeoutMs ?? 2500,\n      );\n      const res = await fetch(url, {\n        signal: controller.signal,\n        headers: { accept: \"application/json\" },\n      });\n      clearTimeout(timer);\n      if (res.ok) {\n        const json = (await res.json()) as { address?: string };\n        if (json.address && !isZeroAddress(json.address)) {\n          return json.address.trim();\n        }\n      }\n    } catch (err) {\n      console.warn(\"[forge] live payTo fetch failed, using fallback:\", err);\n    }\n  }\n\n  if (explicit && !isZeroAddress(explicit)) return explicit;\n  if (opts.fallback && !isZeroAddress(opts.fallback)) return opts.fallback;\n\n  throw new Error(\n    \"resolvePayTo: no usable address (set Forge wallet / PAY_TO, or re-run Forge PR)\",\n  );\n}\n","import type { DefinedAgentService, SkillMeta } from \"./types.js\";\n\n/**\n * Generate a SKILL.md document for agents from defined Forge services.\n */\nexport function generateSkillMarkdown(\n  services: DefinedAgentService[],\n  meta: SkillMeta,\n): string {\n  const base = meta.baseUrl.replace(/\\/$/, \"\");\n  const lines: string[] = [\n    `---`,\n    `name: ${meta.name}`,\n    `description: ${meta.description}`,\n    `---`,\n    ``,\n    `# ${meta.name}`,\n    ``,\n    meta.description,\n    ``,\n  ];\n\n  if (meta.homepage) {\n    lines.push(`Homepage: ${meta.homepage}`, ``);\n  }\n\n  lines.push(\n    `## How to use`,\n    ``,\n    `1. Read this skill.`,\n    `2. Call the agent endpoint with a JSON body matching the input schema.`,\n    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,\n    `4. Use the returned output fields.`,\n    ``,\n    `## Services`,\n    ``,\n  );\n\n  for (const service of services) {\n    const path = `${base}/agent/${service.path}`;\n    const price = service.payment.amount.startsWith(\"$\")\n      ? service.payment.amount\n      : `$${service.payment.amount}`;\n\n    lines.push(\n      `### \\`${service.name}\\``,\n      ``,\n      service.description,\n      ``,\n      `- **Method:** \\`POST\\``,\n      `- **URL:** \\`${path}\\``,\n      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(\", \")}`,\n      ``,\n      `**Input**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Output**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Example**`,\n      ``,\n      \"```bash\",\n      `curl -X POST ${path} \\\\`,\n      `  -H \"Content-Type: application/json\" \\\\`,\n      `  -d '${JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [\n            k,\n            t === \"url\" ? \"https://example.com/image.png\" : `example-${k}`,\n          ]),\n        ),\n      )}'`,\n      \"```\",\n      ``,\n    );\n  }\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACOA,eAAsB,UAAa,SAA0C;AAC3E,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,UAAU,KAAK,IAAI;AAEzB,aAAS;AACP,UAAM,QAAQ,MAAM,QAAQ,IAAI;AAChC,QAAI,QAAQ,cAAc,KAAK,GAAG;AAChC,aAAO;AAAA,IACT;AACA,QAAI,KAAK,IAAI,IAAI,WAAW,WAAW;AACrC,YAAM,IAAI,MAAM,6BAA6B,SAAS,IAAI;AAAA,IAC5D;AACA,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,UAAU,CAAC;AAAA,EAChE;AACF;AAEO,SAAS,gBAAqC;AACnD,SAAO;AAAA,IACL;AAAA,EACF;AACF;AAGO,SAAS,YAAY,MAAsB;AAChD,SAAO,KACJ,QAAQ,sBAAsB,OAAO,EACrC,QAAQ,MAAM,GAAG,EACjB,YAAY;AACjB;AAEO,SAAS,mBAId,QACsC;AACtC,MAAI,CAAC,OAAO,MAAM,KAAK,GAAG;AACxB,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AACA,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,IAAI,MAAM,yCAAyC;AAAA,EAC3D;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS;AAAA,IACT,MAAM,YAAY,OAAO,IAAI;AAAA,EAC/B;AACF;;;ACvDA,qBAAuC;AACvC,IAAAA,kBAAsD;AAEtD,oBAAsC;AAEtC,IAAAC,iBAA+B;;;ACF/B,eAAsB,iBAAiB,MAKrB;AAChB,QAAM,UAAU,KAAK,WAAW,QAAQ,OAAO,EAAE;AACjD,QAAM,MAAM,MAAM,MAAM,GAAG,OAAO,uBAAuB;AAAA,IACvD,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,eAAe,UAAU,KAAK,cAAc;AAAA,IAC9C;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,KAAK,OAAO,KAAK,EAAE,YAAY;AAAA,MACvC,SAAS,KAAK,QAAQ,QAAQ,OAAO,EAAE;AAAA,IACzC,CAAC;AAAA,EACH,CAAC;AACD,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,UAAM,IAAI;AAAA,MACR,6BAA6B,IAAI,MAAM,MAAM,KAAK,MAAM,GAAG,GAAG,CAAC;AAAA,IACjE;AAAA,EACF;AACF;;;ACxBA,IAAM,OAAO;AAEN,SAAS,cAAc,SAA6C;AACzE,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,KAAK,KAAK,QAAQ,KAAK,CAAC;AACjC;AAEA,SAAS,iBAAiB,KAAqB;AAC7C,SAAO,IAAI,QAAQ,OAAO,EAAE;AAC9B;AAEA,SAAS,iBAAiB,QAA0C;AAClE,QAAM,UAAU,QAAQ,IAAI,WAAW,KAAK;AAC5C,MAAI,QAAS,QAAO,iBAAiB,OAAO;AAE5C,QAAM,WAAW,QAAQ,SAAS,KAAK;AACvC,MAAI,CAAC,SAAU,QAAO;AAEtB,QAAM,aAAa,iBAAiB,QAAQ;AAE5C,MACE,0BAA0B,KAAK,UAAU,KACzC,QAAQ,IAAI,aAAa,cACzB;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAQA,eAAsB,aAAa,MAQf;AAClB,QAAM,cAAc,QAAQ,IAAI,QAAQ,KAAK;AAC7C,MAAI,eAAe,CAAC,cAAc,WAAW,GAAG;AAC9C,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,KAAK,OAAO,KAAK;AAClC,MAAI,YAAY,CAAC,cAAc,QAAQ,KAAK,CAAC,KAAK,OAAO;AACvD,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,iBAAiB,KAAK,KAAK;AAC3C,MAAI,WAAW,KAAK,OAAO;AACzB,UAAM,MAAM,GAAG,OAAO,sBAAsB,mBAAmB,KAAK,MAAM,KAAK,CAAC,IAAI,mBAAmB,KAAK,MAAM,IAAI,CAAC;AACvH,QAAI;AACF,YAAM,aAAa,IAAI,gBAAgB;AACvC,YAAM,QAAQ;AAAA,QACZ,MAAM,WAAW,MAAM;AAAA,QACvB,KAAK,aAAa;AAAA,MACpB;AACA,YAAM,MAAM,MAAM,MAAM,KAAK;AAAA,QAC3B,QAAQ,WAAW;AAAA,QACnB,SAAS,EAAE,QAAQ,mBAAmB;AAAA,MACxC,CAAC;AACD,mBAAa,KAAK;AAClB,UAAI,IAAI,IAAI;AACV,cAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,YAAI,KAAK,WAAW,CAAC,cAAc,KAAK,OAAO,GAAG;AAChD,iBAAO,KAAK,QAAQ,KAAK;AAAA,QAC3B;AAAA,MACF;AAAA,IACF,SAAS,KAAK;AACZ,cAAQ,KAAK,oDAAoD,GAAG;AAAA,IACtE;AAAA,EACF;AAEA,MAAI,YAAY,CAAC,cAAc,QAAQ,EAAG,QAAO;AACjD,MAAI,KAAK,YAAY,CAAC,cAAc,KAAK,QAAQ,EAAG,QAAO,KAAK;AAEhE,QAAM,IAAI;AAAA,IACR;AAAA,EACF;AACF;;;AFvEA,IAAM,kBAAkB;AAExB,IAAM,0BAA0B;AAEhC,SAAS,UAAU,OAAoC;AACrD,SAAQ,SAAS;AACnB;AAEA,SAAS,wBAAwB,SAA8C;AAC7E,SAAO,IAAI,oCAAsB;AAAA,IAC/B,KAAK,QAAQ,kBAAkB;AAAA,IAC/B,mBAAmB,QAAQ;AAAA,EAC7B,CAAC;AACH;AAEA,SAAS,cACP,MACA,QAC6E;AAC7E,MAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GAAG;AAC5D,WAAO,EAAE,IAAI,OAAO,OAAO,qCAAqC;AAAA,EAClE;AAEA,QAAM,QAAQ;AACd,QAAM,QAAiC,CAAC;AAExC,aAAW,CAAC,KAAK,IAAI,KAAK,OAAO,QAAQ,MAAM,GAAG;AAChD,QAAI,EAAE,OAAO,UAAU,MAAM,GAAG,MAAM,UAAa,MAAM,GAAG,MAAM,MAAM;AACtE,aAAO,EAAE,IAAI,OAAO,OAAO,2BAA2B,GAAG,GAAG;AAAA,IAC9D;AACA,UAAM,MAAM,UAAU,KAAK,MAAM,GAAG,GAAG,IAAI;AAC3C,QAAI,IAAK,QAAO,EAAE,IAAI,OAAO,OAAO,IAAI;AACxC,UAAM,GAAG,IAAI,MAAM,GAAG;AAAA,EACxB;AAEA,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAEA,SAAS,UAAU,KAAa,OAAgB,MAAsC;AACpF,UAAQ,MAAM;AAAA,IACZ,KAAK;AAAA,IACL,KAAK;AACH,UAAI,OAAO,UAAU,YAAY,CAAC,MAAM,KAAK,GAAG;AAC9C,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,UAAI,SAAS,OAAO;AAClB,YAAI;AACF,cAAI,IAAI,KAAK;AAAA,QACf,QAAQ;AACN,iBAAO,SAAS,GAAG;AAAA,QACrB;AAAA,MACF;AACA,aAAO;AAAA,IACT,KAAK;AACH,UAAI,OAAO,UAAU,YAAY,OAAO,MAAM,KAAK,GAAG;AACpD,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,aAAO;AAAA,IACT,KAAK;AACH,UAAI,OAAO,UAAU,WAAW;AAC9B,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,YAAY,QAAwB;AAC3C,QAAM,aAAa,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;AAC9D,SAAO,IAAI,UAAU;AACvB;AASA,eAAsB,mBACpB,KACA,UACA,SACiB;AACjB,MAAI,QAAQ;AACZ,MAAI,CAAC,QAAQ,aAAa;AACxB,UAAM,WACJ,QAAQ,eAAe,KAAK,KAAK,QAAQ,OAAO,KAAK,KAAK;AAC5D,YAAQ,MAAM,aAAa;AAAA,MACzB;AAAA,MACA,OAAO,QAAQ;AAAA,MACf,OAAO,QAAQ;AAAA,IACjB,CAAC;AACD,QAAI,cAAc,KAAK,GAAG;AACxB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,QAAM,YAAY,QAAQ,YAAY,UAAU,QAAQ,OAAO,EAAE,KAAK;AACtE,QAAM,aAAS,eAAAC,QAAa;AAC5B,QAAM,UAAU,cAAc;AAE9B,QAAM,SAAuB,CAAC;AAE9B,aAAW,WAAW,UAAU;AAC9B,UAAM,YAAY,IAAI,QAAQ,IAAI;AAClC,UAAM,WAAW,GAAG,QAAQ,GAAG,SAAS;AACxC,UAAM,UAAU,UAAU,QAAQ,QAAQ,OAAO;AAEjD,QAAI,CAAC,QAAQ,aAAa;AACxB,aAAO,QAAQ,QAAQ,EAAE,IAAI;AAAA,QAC3B,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,OAAO,YAAY,QAAQ,QAAQ,MAAM;AAAA,UACzC;AAAA,UACA;AAAA,QACF;AAAA,QACA,aAAa,QAAQ;AAAA,QACrB,UAAU;AAAA,MACZ;AAAA,IACF;AAEA,WAAO,KAAK,WAAW,OAAO,KAAc,QAAkB;AAC5D,UAAI;AACF,cAAM,YAAY,cAAc,IAAI,MAAM,QAAQ,KAAK;AACvD,YAAI,CAAC,UAAU,IAAI;AACjB,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,UAAU,MAAM,CAAC;AAC/C;AAAA,QACF;AAEA,cAAM,SAAS,MAAM,QAAQ,QAAQ,UAAU,OAAO,OAAO;AAC7D,YAAI,KAAK,MAAM;AAAA,MACjB,SAAS,KAAK;AACZ,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,gBAAQ,MAAM,WAAW,QAAQ,IAAI,YAAY,GAAG;AACpD,YAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,QAAQ,CAAC;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACH;AAEA,MAAI,CAAC,QAAQ,eAAe,OAAO,KAAK,MAAM,EAAE,SAAS,GAAG;AAC1D,UAAM,cAAc,wBAAwB,OAAO;AACnD,UAAM,WAAW,IAAI;AAAA,MACnB,SAAS,IAAI,CAAC,MAAM,UAAU,EAAE,QAAQ,OAAO,CAAC;AAAA,IAClD;AACA,UAAM,iBAAiB,IAAI,mCAAmB,WAAW;AACzD,eAAW,WAAW,UAAU;AAC9B,qBAAe,SAAS,SAAS,IAAI,8BAAe,CAAC;AAAA,IACvD;AACA,QAAI,QAAI,mCAAkB,QAAQ,gBAAgB,QAAW,QAAW,IAAI,CAAC;AAAA,EAC/E;AAEA,MAAI,IAAI,UAAU,MAAM;AAGxB,QAAM,aACJ,QAAQ,SAAS,KAAK,KAAK,KAAK,QAAQ,IAAI,aAAa,KAAK;AAChE,QAAM,SACJ,QAAQ,SAAS,QAAQ,KAAK,KAAK,QAAQ,IAAI,cAAc,KAAK;AACpE,QAAM,iBACJ,QAAQ,SAAS,gBAAgB,KAAK,KACtC,QAAQ,IAAI,yBAAyB,KAAK;AAC5C,QAAM,gBACJ,QAAQ,SAAS,eAAe,KAAK,KACrC,QAAQ,IAAI,iBAAiB,KAAK,MACjC,QAAQ,IAAI,wBACT,WAAW,QAAQ,IAAI,qBAAqB,KAC5C;AAEN,MAAI,cAAc,UAAU,kBAAkB,eAAe;AAC3D,SAAK,iBAAiB;AAAA,MACpB;AAAA,MACA;AAAA,MACA,SAAS;AAAA,MACT;AAAA,IACF,CAAC,EAAE,MAAM,CAAC,QAAQ;AAChB,cAAQ,KAAK,sCAAsC,GAAG;AAAA,IACxD,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAGO,SAAS,kBACd,UACA,SACuC;AACvC,SAAO,CAAC,QAAQ,mBAAmB,KAAK,UAAU,OAAO;AAC3D;;;AG7MO,SAAS,sBACd,UACA,MACQ;AACR,QAAM,OAAO,KAAK,QAAQ,QAAQ,OAAO,EAAE;AAC3C,QAAM,QAAkB;AAAA,IACtB;AAAA,IACA,SAAS,KAAK,IAAI;AAAA,IAClB,gBAAgB,KAAK,WAAW;AAAA,IAChC;AAAA,IACA;AAAA,IACA,KAAK,KAAK,IAAI;AAAA,IACd;AAAA,IACA,KAAK;AAAA,IACL;AAAA,EACF;AAEA,MAAI,KAAK,UAAU;AACjB,UAAM,KAAK,aAAa,KAAK,QAAQ,IAAI,EAAE;AAAA,EAC7C;AAEA,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,OAAO,GAAG,IAAI,UAAU,QAAQ,IAAI;AAC1C,UAAM,QAAQ,QAAQ,QAAQ,OAAO,WAAW,GAAG,IAC/C,QAAQ,QAAQ,SAChB,IAAI,QAAQ,QAAQ,MAAM;AAE9B,UAAM;AAAA,MACJ,SAAS,QAAQ,IAAI;AAAA,MACrB;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA,gBAAgB,IAAI;AAAA,MACpB,gBAAgB,KAAK,IAAI,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,UAAU,KAAK,IAAI,CAAC;AAAA,MAC7F;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,KAAK;AAAA,QACH,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AAAA,QAC7D;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,KAAK;AAAA,QACH,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,MAAM,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AAAA,QAC9D;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,gBAAgB,IAAI;AAAA,MACpB;AAAA,MACA,SAAS,KAAK;AAAA,QACZ,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM;AAAA,YAC5C;AAAA,YACA,MAAM,QAAQ,kCAAkC,WAAW,CAAC;AAAA,UAC9D,CAAC;AAAA,QACH;AAAA,MACF,CAAC;AAAA,MACD;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,IAAI;AACxB;","names":["import_express","import_server","createRouter"]}

package/dist/index.d.cts

@@ -8,7 +8,7 @@ interface PaymentConfig {
     amount: string;
     currency: "USDC";
     protocols: Array<"x402" | "mpp">;
-    /** CAIP-2 network. Defaults to Base Sepolia (`eip155:84532`). */
+    /** CAIP-2 network. Defaults to Base mainnet (`eip155:8453`). */
     network?: string;
 }
 interface WaitUntilOptions<T> {
@@ -32,15 +32,56 @@ interface DefinedAgentService<TInput extends Record<string, unknown> = Record<st
     readonly __forge: true;
     path: string;
 }
+interface FacilitatorAuthHeaders {
+    verify: Record<string, string>;
+    settle: Record<string, string>;
+    supported: Record<string, string>;
+    bazaar?: Record<string, string>;
+}
+interface ForgePayToSource {
+    owner: string;
+    repo: string;
+    /** Forge web base URL. Optional — uses FORGE_URL env when set. */
+    baseUrl?: string;
+}
 interface MountOptions {
-    /** Recipient wallet address for x402 payments */
-    payTo: string;
-    /** Facilitator URL. Defaults to https://x402.org/facilitator */
+    /**
+     * Recipient wallet. Prefer omitting and letting `forge` + baked fallback
+     * resolve automatically so merchants never set PAY_TO on their host.
+     * Still honored as override when set (or via process.env.PAY_TO).
+     */
+    payTo?: string;
+    /**
+     * Baked-in Forge wallet from codegen. Used when live Forge fetch is
+     * unavailable. Required unless skipPayment or payTo is set.
+     */
+    payToFallback?: string;
+    /**
+     * Auto-resolve payTo from Forge public API (no merchant env required).
+     */
+    forge?: ForgePayToSource;
+    /**
+     * Facilitator URL. Defaults to XPay (`https://facilitator.xpay.sh`) —
+     * Base mainnet, no API keys. Override with CDP or others if needed.
+     */
     facilitatorUrl?: string;
+    /** Optional auth header factory (e.g. CDP JWT). Not required for XPay. */
+    createAuthHeaders?: () => Promise<FacilitatorAuthHeaders>;
     /** Path prefix for agent routes. Defaults to /agent */
     basePath?: string;
     /** Skip x402 (local dev only). Defaults to false. */
     skipPayment?: boolean;
+    /**
+     * Optional gateway heartbeat after mount.
+     * Prefer env: GATEWAY_URL, FORGE_HANDLE, GATEWAY_REGISTER_SECRET, PUBLIC_BASE_URL.
+     */
+    gateway?: {
+        url?: string;
+        handle?: string;
+        registerSecret?: string;
+        /** Merchant public base URL for fulfillment. */
+        publicBaseUrl?: string;
+    };
 }
 interface SkillMeta {
     name: string;
@@ -58,14 +99,45 @@ declare function defineAgentService<TInput extends Record<string, unknown> = Rec
 /**
  * Mount Forge agent services on an Express app.
  * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.
+ *
+ * payTo resolves automatically: PAY_TO env (optional) → Forge API → baked fallback.
+ * Merchants should not need to configure PAY_TO on Railway for the happy path.
  */
-declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Router;
+declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Promise<Router>;
 /** Express-compatible middleware alias used in docs. */
-declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => Router;
+declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => Promise<Router>;
 
 /**
  * Generate a SKILL.md document for agents from defined Forge services.
  */
 declare function generateSkillMarkdown(services: DefinedAgentService[], meta: SkillMeta): string;
 
-export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, generateSkillMarkdown, mountAgentServices, toKebabCase, waitUntil };
+declare function isZeroAddress(address: string | undefined | null): boolean;
+/**
+ * Resolve merchant payTo with minimal host config:
+ * 1. `PAY_TO` env (optional override)
+ * 2. Live address from Forge public API (when reachable)
+ * 3. Baked-in fallback from the Forge PR
+ */
+declare function resolvePayTo(opts: {
+    /** Baked-in address from Forge codegen (required fallback). */
+    fallback: string;
+    /** Optional explicit override (usually process.env.PAY_TO). */
+    payTo?: string;
+    forge?: ForgePayToSource;
+    /** Fetch timeout ms. Defaults to 2500. */
+    timeoutMs?: number;
+}): Promise<string>;
+
+/**
+ * Notify ClawCash gateway of this merchant's live public base URL.
+ * Full action registration still happens from Forge "Go live".
+ */
+declare function heartbeatGateway(opts: {
+    gatewayUrl: string;
+    handle: string;
+    baseUrl: string;
+    registerSecret: string;
+}): Promise<void>;
+
+export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, type ForgePayToSource, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, generateSkillMarkdown, heartbeatGateway, isZeroAddress, mountAgentServices, resolvePayTo, toKebabCase, waitUntil };

package/dist/index.d.ts

@@ -8,7 +8,7 @@ interface PaymentConfig {
     amount: string;
     currency: "USDC";
     protocols: Array<"x402" | "mpp">;
-    /** CAIP-2 network. Defaults to Base Sepolia (`eip155:84532`). */
+    /** CAIP-2 network. Defaults to Base mainnet (`eip155:8453`). */
     network?: string;
 }
 interface WaitUntilOptions<T> {
@@ -32,15 +32,56 @@ interface DefinedAgentService<TInput extends Record<string, unknown> = Record<st
     readonly __forge: true;
     path: string;
 }
+interface FacilitatorAuthHeaders {
+    verify: Record<string, string>;
+    settle: Record<string, string>;
+    supported: Record<string, string>;
+    bazaar?: Record<string, string>;
+}
+interface ForgePayToSource {
+    owner: string;
+    repo: string;
+    /** Forge web base URL. Optional — uses FORGE_URL env when set. */
+    baseUrl?: string;
+}
 interface MountOptions {
-    /** Recipient wallet address for x402 payments */
-    payTo: string;
-    /** Facilitator URL. Defaults to https://x402.org/facilitator */
+    /**
+     * Recipient wallet. Prefer omitting and letting `forge` + baked fallback
+     * resolve automatically so merchants never set PAY_TO on their host.
+     * Still honored as override when set (or via process.env.PAY_TO).
+     */
+    payTo?: string;
+    /**
+     * Baked-in Forge wallet from codegen. Used when live Forge fetch is
+     * unavailable. Required unless skipPayment or payTo is set.
+     */
+    payToFallback?: string;
+    /**
+     * Auto-resolve payTo from Forge public API (no merchant env required).
+     */
+    forge?: ForgePayToSource;
+    /**
+     * Facilitator URL. Defaults to XPay (`https://facilitator.xpay.sh`) —
+     * Base mainnet, no API keys. Override with CDP or others if needed.
+     */
     facilitatorUrl?: string;
+    /** Optional auth header factory (e.g. CDP JWT). Not required for XPay. */
+    createAuthHeaders?: () => Promise<FacilitatorAuthHeaders>;
     /** Path prefix for agent routes. Defaults to /agent */
     basePath?: string;
     /** Skip x402 (local dev only). Defaults to false. */
     skipPayment?: boolean;
+    /**
+     * Optional gateway heartbeat after mount.
+     * Prefer env: GATEWAY_URL, FORGE_HANDLE, GATEWAY_REGISTER_SECRET, PUBLIC_BASE_URL.
+     */
+    gateway?: {
+        url?: string;
+        handle?: string;
+        registerSecret?: string;
+        /** Merchant public base URL for fulfillment. */
+        publicBaseUrl?: string;
+    };
 }
 interface SkillMeta {
     name: string;
@@ -58,14 +99,45 @@ declare function defineAgentService<TInput extends Record<string, unknown> = Rec
 /**
  * Mount Forge agent services on an Express app.
  * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.
+ *
+ * payTo resolves automatically: PAY_TO env (optional) → Forge API → baked fallback.
+ * Merchants should not need to configure PAY_TO on Railway for the happy path.
  */
-declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Router;
+declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Promise<Router>;
 /** Express-compatible middleware alias used in docs. */
-declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => Router;
+declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => Promise<Router>;
 
 /**
  * Generate a SKILL.md document for agents from defined Forge services.
  */
 declare function generateSkillMarkdown(services: DefinedAgentService[], meta: SkillMeta): string;
 
-export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, generateSkillMarkdown, mountAgentServices, toKebabCase, waitUntil };
+declare function isZeroAddress(address: string | undefined | null): boolean;
+/**
+ * Resolve merchant payTo with minimal host config:
+ * 1. `PAY_TO` env (optional override)
+ * 2. Live address from Forge public API (when reachable)
+ * 3. Baked-in fallback from the Forge PR
+ */
+declare function resolvePayTo(opts: {
+    /** Baked-in address from Forge codegen (required fallback). */
+    fallback: string;
+    /** Optional explicit override (usually process.env.PAY_TO). */
+    payTo?: string;
+    forge?: ForgePayToSource;
+    /** Fetch timeout ms. Defaults to 2500. */
+    timeoutMs?: number;
+}): Promise<string>;
+
+/**
+ * Notify ClawCash gateway of this merchant's live public base URL.
+ * Full action registration still happens from Forge "Go live".
+ */
+declare function heartbeatGateway(opts: {
+    gatewayUrl: string;
+    handle: string;
+    baseUrl: string;
+    registerSecret: string;
+}): Promise<void>;
+
+export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, type ForgePayToSource, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, generateSkillMarkdown, heartbeatGateway, isZeroAddress, mountAgentServices, resolvePayTo, toKebabCase, waitUntil };

package/dist/index.js

@@ -41,11 +41,101 @@ import { Router as createRouter } from "express";
 import { paymentMiddleware, x402ResourceServer } from "@x402/express";
 import { HTTPFacilitatorClient } from "@x402/core/server";
 import { ExactEvmScheme } from "@x402/evm/exact/server";
-var DEFAULT_NETWORK = "eip155:84532";
-var DEFAULT_FACILITATOR = "https://x402.org/facilitator";
+
+// src/gateway.ts
+async function heartbeatGateway(opts) {
+  const gateway = opts.gatewayUrl.replace(/\/$/, "");
+  const res = await fetch(`${gateway}/register/heartbeat`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${opts.registerSecret}`
+    },
+    body: JSON.stringify({
+      handle: opts.handle.trim().toLowerCase(),
+      baseUrl: opts.baseUrl.replace(/\/$/, "")
+    })
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(
+      `gateway heartbeat failed (${res.status}): ${text.slice(0, 240)}`
+    );
+  }
+}
+
+// src/payto.ts
+var ZERO = /^0x0{40}$/i;
+function isZeroAddress(address) {
+  if (!address) return true;
+  return ZERO.test(address.trim());
+}
+function normalizeBaseUrl(url) {
+  return url.replace(/\/$/, "");
+}
+function pickForgeBaseUrl(source) {
+  const fromEnv = process.env.FORGE_URL?.trim();
+  if (fromEnv) return normalizeBaseUrl(fromEnv);
+  const fromOpts = source?.baseUrl?.trim();
+  if (!fromOpts) return null;
+  const normalized = normalizeBaseUrl(fromOpts);
+  if (/localhost|127\.0\.0\.1/i.test(normalized) && process.env.NODE_ENV === "production") {
+    return null;
+  }
+  return normalized;
+}
+async function resolvePayTo(opts) {
+  const envOverride = process.env.PAY_TO?.trim();
+  if (envOverride && !isZeroAddress(envOverride)) {
+    return envOverride;
+  }
+  const explicit = opts.payTo?.trim();
+  if (explicit && !isZeroAddress(explicit) && !opts.forge) {
+    return explicit;
+  }
+  const baseUrl = pickForgeBaseUrl(opts.forge);
+  if (baseUrl && opts.forge) {
+    const url = `${baseUrl}/api/public/pay-to/${encodeURIComponent(opts.forge.owner)}/${encodeURIComponent(opts.forge.repo)}`;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(
+        () => controller.abort(),
+        opts.timeoutMs ?? 2500
+      );
+      const res = await fetch(url, {
+        signal: controller.signal,
+        headers: { accept: "application/json" }
+      });
+      clearTimeout(timer);
+      if (res.ok) {
+        const json = await res.json();
+        if (json.address && !isZeroAddress(json.address)) {
+          return json.address.trim();
+        }
+      }
+    } catch (err) {
+      console.warn("[forge] live payTo fetch failed, using fallback:", err);
+    }
+  }
+  if (explicit && !isZeroAddress(explicit)) return explicit;
+  if (opts.fallback && !isZeroAddress(opts.fallback)) return opts.fallback;
+  throw new Error(
+    "resolvePayTo: no usable address (set Forge wallet / PAY_TO, or re-run Forge PR)"
+  );
+}
+
+// src/mount.ts
+var DEFAULT_NETWORK = "eip155:8453";
+var DEFAULT_FACILITATOR_URL = "https://facilitator.xpay.sh";
 function asNetwork(value) {
   return value ?? DEFAULT_NETWORK;
 }
+function createFacilitatorClient(options) {
+  return new HTTPFacilitatorClient({
+    url: options.facilitatorUrl ?? DEFAULT_FACILITATOR_URL,
+    createAuthHeaders: options.createAuthHeaders
+  });
+}
 function validateInput(body, schema) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     return { ok: false, error: "Request body must be a JSON object" };
@@ -95,9 +185,20 @@ function formatPrice(amount) {
   const normalized = amount.startsWith("$") ? amount.slice(1) : amount;
   return `$${normalized}`;
 }
-function mountAgentServices(app, services, options) {
-  if (!options.payTo && !options.skipPayment) {
-    throw new Error("mountAgentServices: payTo is required unless skipPayment is true");
+async function mountAgentServices(app, services, options) {
+  let payTo = "";
+  if (!options.skipPayment) {
+    const fallback = options.payToFallback?.trim() || options.payTo?.trim() || "";
+    payTo = await resolvePayTo({
+      fallback,
+      payTo: options.payTo,
+      forge: options.forge
+    });
+    if (isZeroAddress(payTo)) {
+      throw new Error(
+        "mountAgentServices: resolved payTo is the zero address. Re-run Forge to provision a wallet."
+      );
+    }
   }
   const basePath = (options.basePath ?? "/agent").replace(/\/$/, "") || "/agent";
   const router = createRouter();
@@ -113,7 +214,7 @@ function mountAgentServices(app, services, options) {
           scheme: "exact",
           price: formatPrice(service.payment.amount),
           network,
-          payTo: options.payTo
+          payTo
         },
         description: service.description,
         mimeType: "application/json"
@@ -136,9 +237,7 @@ function mountAgentServices(app, services, options) {
     });
   }
   if (!options.skipPayment && Object.keys(routes).length > 0) {
-    const facilitator = new HTTPFacilitatorClient({
-      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR
-    });
+    const facilitator = createFacilitatorClient(options);
     const networks = new Set(
       services.map((s) => asNetwork(s.payment.network))
     );
@@ -149,6 +248,20 @@ function mountAgentServices(app, services, options) {
     app.use(paymentMiddleware(routes, resourceServer, void 0, void 0, true));
   }
   app.use(basePath, router);
+  const gatewayUrl = options.gateway?.url?.trim() || process.env.GATEWAY_URL?.trim();
+  const handle = options.gateway?.handle?.trim() || process.env.FORGE_HANDLE?.trim();
+  const registerSecret = options.gateway?.registerSecret?.trim() || process.env.GATEWAY_REGISTER_SECRET?.trim();
+  const publicBaseUrl = options.gateway?.publicBaseUrl?.trim() || process.env.PUBLIC_BASE_URL?.trim() || (process.env.RAILWAY_PUBLIC_DOMAIN ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}` : "");
+  if (gatewayUrl && handle && registerSecret && publicBaseUrl) {
+    void heartbeatGateway({
+      gatewayUrl,
+      handle,
+      baseUrl: publicBaseUrl,
+      registerSecret
+    }).catch((err) => {
+      console.warn("[forge] gateway heartbeat skipped:", err);
+    });
+  }
   return router;
 }
 function createForgeRouter(services, options) {
@@ -243,7 +356,10 @@ export {
   createForgeRouter,
   defineAgentService,
   generateSkillMarkdown,
+  heartbeatGateway,
+  isZeroAddress,
   mountAgentServices,
+  resolvePayTo,
   toKebabCase,
   waitUntil
 };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/define.ts","../src/mount.ts","../src/skill.ts"],"sourcesContent":["import type {\n  AgentServiceConfig,\n  AgentServiceContext,\n  DefinedAgentService,\n  WaitUntilOptions,\n} from \"./types.js\";\n\nexport async function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T> {\n  const intervalMs = options.intervalMs ?? 500;\n  const timeoutMs = options.timeoutMs ?? 60_000;\n  const started = Date.now();\n\n  for (;;) {\n    const value = await options.run();\n    if (options.completedWhen(value)) {\n      return value;\n    }\n    if (Date.now() - started >= timeoutMs) {\n      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);\n    }\n    await new Promise((resolve) => setTimeout(resolve, intervalMs));\n  }\n}\n\nexport function createContext(): AgentServiceContext {\n  return {\n    waitUntil,\n  };\n}\n\n/** Convert snake_case or camelCase service name to kebab-case path segment. */\nexport function toKebabCase(name: string): string {\n  return name\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .replace(/_/g, \"-\")\n    .toLowerCase();\n}\n\nexport function defineAgentService<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> = Record<string, unknown>,\n>(\n  config: AgentServiceConfig<TInput, TOutput>,\n): DefinedAgentService<TInput, TOutput> {\n  if (!config.name?.trim()) {\n    throw new Error(\"defineAgentService: name is required\");\n  }\n  if (!config.execute) {\n    throw new Error(\"defineAgentService: execute is required\");\n  }\n\n  return {\n    ...config,\n    __forge: true,\n    path: toKebabCase(config.name),\n  };\n}\n","import type { Application, Request, Response, NextFunction, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport { paymentMiddleware, x402ResourceServer } from \"@x402/express\";\nimport type { Network } from \"@x402/express\";\nimport { HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { RoutesConfig } from \"@x402/core/server\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/server\";\nimport { createContext } from \"./define.js\";\nimport type {\n  DefinedAgentService,\n  InputSchema,\n  MountOptions,\n  SchemaFieldType,\n} from \"./types.js\";\n\n/** Base Sepolia — supported by the public x402.org facilitator for demos. */\nconst DEFAULT_NETWORK = \"eip155:84532\" as const satisfies Network;\nconst DEFAULT_FACILITATOR = \"https://x402.org/facilitator\";\n\nfunction asNetwork(value: string | undefined): Network {\n  return (value ?? DEFAULT_NETWORK) as Network;\n}\n\nfunction validateInput(\n  body: unknown,\n  schema: InputSchema,\n): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } {\n  if (!body || typeof body !== \"object\" || Array.isArray(body)) {\n    return { ok: false, error: \"Request body must be a JSON object\" };\n  }\n\n  const input = body as Record<string, unknown>;\n  const value: Record<string, unknown> = {};\n\n  for (const [key, type] of Object.entries(schema)) {\n    if (!(key in input) || input[key] === undefined || input[key] === null) {\n      return { ok: false, error: `Missing required field: ${key}` };\n    }\n    const err = checkType(key, input[key], type);\n    if (err) return { ok: false, error: err };\n    value[key] = input[key];\n  }\n\n  return { ok: true, value };\n}\n\nfunction checkType(key: string, value: unknown, type: SchemaFieldType): string | null {\n  switch (type) {\n    case \"string\":\n    case \"url\":\n      if (typeof value !== \"string\" || !value.trim()) {\n        return `Field ${key} must be a non-empty string`;\n      }\n      if (type === \"url\") {\n        try {\n          new URL(value);\n        } catch {\n          return `Field ${key} must be a valid URL`;\n        }\n      }\n      return null;\n    case \"number\":\n      if (typeof value !== \"number\" || Number.isNaN(value)) {\n        return `Field ${key} must be a number`;\n      }\n      return null;\n    case \"boolean\":\n      if (typeof value !== \"boolean\") {\n        return `Field ${key} must be a boolean`;\n      }\n      return null;\n    default:\n      return null;\n  }\n}\n\nfunction formatPrice(amount: string): string {\n  const normalized = amount.startsWith(\"$\") ? amount.slice(1) : amount;\n  return `$${normalized}`;\n}\n\n/**\n * Mount Forge agent services on an Express app.\n * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.\n */\nexport function mountAgentServices(\n  app: Application,\n  services: DefinedAgentService[],\n  options: MountOptions,\n): Router {\n  if (!options.payTo && !options.skipPayment) {\n    throw new Error(\"mountAgentServices: payTo is required unless skipPayment is true\");\n  }\n\n  const basePath = (options.basePath ?? \"/agent\").replace(/\\/$/, \"\") || \"/agent\";\n  const router = createRouter();\n  const context = createContext();\n\n  const routes: RoutesConfig = {};\n\n  for (const service of services) {\n    const routePath = `/${service.path}`;\n    const fullPath = `${basePath}${routePath}`;\n    const network = asNetwork(service.payment.network);\n\n    if (!options.skipPayment) {\n      routes[`POST ${fullPath}`] = {\n        accepts: {\n          scheme: \"exact\",\n          price: formatPrice(service.payment.amount),\n          network,\n          payTo: options.payTo,\n        },\n        description: service.description,\n        mimeType: \"application/json\",\n      };\n    }\n\n    router.post(routePath, async (req: Request, res: Response) => {\n      try {\n        const validated = validateInput(req.body, service.input);\n        if (!validated.ok) {\n          res.status(400).json({ error: validated.error });\n          return;\n        }\n\n        const output = await service.execute(validated.value, context);\n        res.json(output);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : \"Internal error\";\n        console.error(`[forge] ${service.name} failed:`, err);\n        res.status(500).json({ error: message });\n      }\n    });\n  }\n\n  if (!options.skipPayment && Object.keys(routes).length > 0) {\n    const facilitator = new HTTPFacilitatorClient({\n      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR,\n    });\n    const networks = new Set(\n      services.map((s) => asNetwork(s.payment.network)),\n    );\n    const resourceServer = new x402ResourceServer(facilitator);\n    for (const network of networks) {\n      resourceServer.register(network, new ExactEvmScheme());\n    }\n    // syncFacilitatorOnStart validates scheme/network against the facilitator\n    app.use(paymentMiddleware(routes, resourceServer, undefined, undefined, true));\n  }\n\n  app.use(basePath, router);\n  return router;\n}\n\n/** Express-compatible middleware alias used in docs. */\nexport function createForgeRouter(\n  services: DefinedAgentService[],\n  options: MountOptions,\n): (app: Application) => Router {\n  return (app) => mountAgentServices(app, services, options);\n}\n\n/** Optional no-op next for typing convenience in tests. */\nexport function forgeErrorHandler(\n  err: unknown,\n  _req: Request,\n  res: Response,\n  _next: NextFunction,\n): void {\n  const message = err instanceof Error ? err.message : \"Internal error\";\n  res.status(500).json({ error: message });\n}\n","import type { DefinedAgentService, SkillMeta } from \"./types.js\";\n\n/**\n * Generate a SKILL.md document for agents from defined Forge services.\n */\nexport function generateSkillMarkdown(\n  services: DefinedAgentService[],\n  meta: SkillMeta,\n): string {\n  const base = meta.baseUrl.replace(/\\/$/, \"\");\n  const lines: string[] = [\n    `---`,\n    `name: ${meta.name}`,\n    `description: ${meta.description}`,\n    `---`,\n    ``,\n    `# ${meta.name}`,\n    ``,\n    meta.description,\n    ``,\n  ];\n\n  if (meta.homepage) {\n    lines.push(`Homepage: ${meta.homepage}`, ``);\n  }\n\n  lines.push(\n    `## How to use`,\n    ``,\n    `1. Read this skill.`,\n    `2. Call the agent endpoint with a JSON body matching the input schema.`,\n    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,\n    `4. Use the returned output fields.`,\n    ``,\n    `## Services`,\n    ``,\n  );\n\n  for (const service of services) {\n    const path = `${base}/agent/${service.path}`;\n    const price = service.payment.amount.startsWith(\"$\")\n      ? service.payment.amount\n      : `$${service.payment.amount}`;\n\n    lines.push(\n      `### \\`${service.name}\\``,\n      ``,\n      service.description,\n      ``,\n      `- **Method:** \\`POST\\``,\n      `- **URL:** \\`${path}\\``,\n      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(\", \")}`,\n      ``,\n      `**Input**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Output**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Example**`,\n      ``,\n      \"```bash\",\n      `curl -X POST ${path} \\\\`,\n      `  -H \"Content-Type: application/json\" \\\\`,\n      `  -d '${JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [\n            k,\n            t === \"url\" ? \"https://example.com/image.png\" : `example-${k}`,\n          ]),\n        ),\n      )}'`,\n      \"```\",\n      ``,\n    );\n  }\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/define.ts","../src/mount.ts","../src/gateway.ts","../src/payto.ts","../src/skill.ts"],"sourcesContent":["import type {\n  AgentServiceConfig,\n  AgentServiceContext,\n  DefinedAgentService,\n  WaitUntilOptions,\n} from \"./types.js\";\n\nexport async function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T> {\n  const intervalMs = options.intervalMs ?? 500;\n  const timeoutMs = options.timeoutMs ?? 60_000;\n  const started = Date.now();\n\n  for (;;) {\n    const value = await options.run();\n    if (options.completedWhen(value)) {\n      return value;\n    }\n    if (Date.now() - started >= timeoutMs) {\n      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);\n    }\n    await new Promise((resolve) => setTimeout(resolve, intervalMs));\n  }\n}\n\nexport function createContext(): AgentServiceContext {\n  return {\n    waitUntil,\n  };\n}\n\n/** Convert snake_case or camelCase service name to kebab-case path segment. */\nexport function toKebabCase(name: string): string {\n  return name\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    .replace(/_/g, \"-\")\n    .toLowerCase();\n}\n\nexport function defineAgentService<\n  TInput extends Record<string, unknown> = Record<string, unknown>,\n  TOutput extends Record<string, unknown> = Record<string, unknown>,\n>(\n  config: AgentServiceConfig<TInput, TOutput>,\n): DefinedAgentService<TInput, TOutput> {\n  if (!config.name?.trim()) {\n    throw new Error(\"defineAgentService: name is required\");\n  }\n  if (!config.execute) {\n    throw new Error(\"defineAgentService: execute is required\");\n  }\n\n  return {\n    ...config,\n    __forge: true,\n    path: toKebabCase(config.name),\n  };\n}\n","import type { Application, Request, Response, NextFunction, Router } from \"express\";\nimport { Router as createRouter } from \"express\";\nimport { paymentMiddleware, x402ResourceServer } from \"@x402/express\";\nimport type { Network } from \"@x402/express\";\nimport { HTTPFacilitatorClient } from \"@x402/core/server\";\nimport type { RoutesConfig } from \"@x402/core/server\";\nimport { ExactEvmScheme } from \"@x402/evm/exact/server\";\nimport { createContext } from \"./define.js\";\nimport { heartbeatGateway } from \"./gateway.js\";\nimport { isZeroAddress, resolvePayTo } from \"./payto.js\";\nimport type {\n  DefinedAgentService,\n  InputSchema,\n  MountOptions,\n  SchemaFieldType,\n} from \"./types.js\";\n\n/** Base mainnet — settled via the public XPay facilitator (no API keys). */\nconst DEFAULT_NETWORK = \"eip155:8453\" as const satisfies Network;\n/** Open facilitator: Base mainnet + Sepolia, no API keys. https://github.com/xpaysh/xpay-x402 */\nconst DEFAULT_FACILITATOR_URL = \"https://facilitator.xpay.sh\";\n\nfunction asNetwork(value: string | undefined): Network {\n  return (value ?? DEFAULT_NETWORK) as Network;\n}\n\nfunction createFacilitatorClient(options: MountOptions): HTTPFacilitatorClient {\n  return new HTTPFacilitatorClient({\n    url: options.facilitatorUrl ?? DEFAULT_FACILITATOR_URL,\n    createAuthHeaders: options.createAuthHeaders,\n  });\n}\n\nfunction validateInput(\n  body: unknown,\n  schema: InputSchema,\n): { ok: true; value: Record<string, unknown> } | { ok: false; error: string } {\n  if (!body || typeof body !== \"object\" || Array.isArray(body)) {\n    return { ok: false, error: \"Request body must be a JSON object\" };\n  }\n\n  const input = body as Record<string, unknown>;\n  const value: Record<string, unknown> = {};\n\n  for (const [key, type] of Object.entries(schema)) {\n    if (!(key in input) || input[key] === undefined || input[key] === null) {\n      return { ok: false, error: `Missing required field: ${key}` };\n    }\n    const err = checkType(key, input[key], type);\n    if (err) return { ok: false, error: err };\n    value[key] = input[key];\n  }\n\n  return { ok: true, value };\n}\n\nfunction checkType(key: string, value: unknown, type: SchemaFieldType): string | null {\n  switch (type) {\n    case \"string\":\n    case \"url\":\n      if (typeof value !== \"string\" || !value.trim()) {\n        return `Field ${key} must be a non-empty string`;\n      }\n      if (type === \"url\") {\n        try {\n          new URL(value);\n        } catch {\n          return `Field ${key} must be a valid URL`;\n        }\n      }\n      return null;\n    case \"number\":\n      if (typeof value !== \"number\" || Number.isNaN(value)) {\n        return `Field ${key} must be a number`;\n      }\n      return null;\n    case \"boolean\":\n      if (typeof value !== \"boolean\") {\n        return `Field ${key} must be a boolean`;\n      }\n      return null;\n    default:\n      return null;\n  }\n}\n\nfunction formatPrice(amount: string): string {\n  const normalized = amount.startsWith(\"$\") ? amount.slice(1) : amount;\n  return `$${normalized}`;\n}\n\n/**\n * Mount Forge agent services on an Express app.\n * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.\n *\n * payTo resolves automatically: PAY_TO env (optional) → Forge API → baked fallback.\n * Merchants should not need to configure PAY_TO on Railway for the happy path.\n */\nexport async function mountAgentServices(\n  app: Application,\n  services: DefinedAgentService[],\n  options: MountOptions,\n): Promise<Router> {\n  let payTo = \"\";\n  if (!options.skipPayment) {\n    const fallback =\n      options.payToFallback?.trim() || options.payTo?.trim() || \"\";\n    payTo = await resolvePayTo({\n      fallback,\n      payTo: options.payTo,\n      forge: options.forge,\n    });\n    if (isZeroAddress(payTo)) {\n      throw new Error(\n        \"mountAgentServices: resolved payTo is the zero address. Re-run Forge to provision a wallet.\",\n      );\n    }\n  }\n\n  const basePath = (options.basePath ?? \"/agent\").replace(/\\/$/, \"\") || \"/agent\";\n  const router = createRouter();\n  const context = createContext();\n\n  const routes: RoutesConfig = {};\n\n  for (const service of services) {\n    const routePath = `/${service.path}`;\n    const fullPath = `${basePath}${routePath}`;\n    const network = asNetwork(service.payment.network);\n\n    if (!options.skipPayment) {\n      routes[`POST ${fullPath}`] = {\n        accepts: {\n          scheme: \"exact\",\n          price: formatPrice(service.payment.amount),\n          network,\n          payTo,\n        },\n        description: service.description,\n        mimeType: \"application/json\",\n      };\n    }\n\n    router.post(routePath, async (req: Request, res: Response) => {\n      try {\n        const validated = validateInput(req.body, service.input);\n        if (!validated.ok) {\n          res.status(400).json({ error: validated.error });\n          return;\n        }\n\n        const output = await service.execute(validated.value, context);\n        res.json(output);\n      } catch (err) {\n        const message = err instanceof Error ? err.message : \"Internal error\";\n        console.error(`[forge] ${service.name} failed:`, err);\n        res.status(500).json({ error: message });\n      }\n    });\n  }\n\n  if (!options.skipPayment && Object.keys(routes).length > 0) {\n    const facilitator = createFacilitatorClient(options);\n    const networks = new Set(\n      services.map((s) => asNetwork(s.payment.network)),\n    );\n    const resourceServer = new x402ResourceServer(facilitator);\n    for (const network of networks) {\n      resourceServer.register(network, new ExactEvmScheme());\n    }\n    app.use(paymentMiddleware(routes, resourceServer, undefined, undefined, true));\n  }\n\n  app.use(basePath, router);\n\n  // Fire-and-forget baseUrl heartbeat so gateway fulfillment stays current.\n  const gatewayUrl =\n    options.gateway?.url?.trim() || process.env.GATEWAY_URL?.trim();\n  const handle =\n    options.gateway?.handle?.trim() || process.env.FORGE_HANDLE?.trim();\n  const registerSecret =\n    options.gateway?.registerSecret?.trim() ||\n    process.env.GATEWAY_REGISTER_SECRET?.trim();\n  const publicBaseUrl =\n    options.gateway?.publicBaseUrl?.trim() ||\n    process.env.PUBLIC_BASE_URL?.trim() ||\n    (process.env.RAILWAY_PUBLIC_DOMAIN\n      ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`\n      : \"\");\n\n  if (gatewayUrl && handle && registerSecret && publicBaseUrl) {\n    void heartbeatGateway({\n      gatewayUrl,\n      handle,\n      baseUrl: publicBaseUrl,\n      registerSecret,\n    }).catch((err) => {\n      console.warn(\"[forge] gateway heartbeat skipped:\", err);\n    });\n  }\n\n  return router;\n}\n\n/** Express-compatible middleware alias used in docs. */\nexport function createForgeRouter(\n  services: DefinedAgentService[],\n  options: MountOptions,\n): (app: Application) => Promise<Router> {\n  return (app) => mountAgentServices(app, services, options);\n}\n\n/** Optional no-op next for typing convenience in tests. */\nexport function forgeErrorHandler(\n  err: unknown,\n  _req: Request,\n  res: Response,\n  _next: NextFunction,\n): void {\n  const message = err instanceof Error ? err.message : \"Internal error\";\n  res.status(500).json({ error: message });\n}\n","/**\n * Notify ClawCash gateway of this merchant's live public base URL.\n * Full action registration still happens from Forge \"Go live\".\n */\nexport async function heartbeatGateway(opts: {\n  gatewayUrl: string;\n  handle: string;\n  baseUrl: string;\n  registerSecret: string;\n}): Promise<void> {\n  const gateway = opts.gatewayUrl.replace(/\\/$/, \"\");\n  const res = await fetch(`${gateway}/register/heartbeat`, {\n    method: \"POST\",\n    headers: {\n      \"content-type\": \"application/json\",\n      authorization: `Bearer ${opts.registerSecret}`,\n    },\n    body: JSON.stringify({\n      handle: opts.handle.trim().toLowerCase(),\n      baseUrl: opts.baseUrl.replace(/\\/$/, \"\"),\n    }),\n  });\n  if (!res.ok) {\n    const text = await res.text();\n    throw new Error(\n      `gateway heartbeat failed (${res.status}): ${text.slice(0, 240)}`,\n    );\n  }\n}\n","import type { ForgePayToSource } from \"./types.js\";\n\nexport type { ForgePayToSource };\n\nconst ZERO = /^0x0{40}$/i;\n\nexport function isZeroAddress(address: string | undefined | null): boolean {\n  if (!address) return true;\n  return ZERO.test(address.trim());\n}\n\nfunction normalizeBaseUrl(url: string): string {\n  return url.replace(/\\/$/, \"\");\n}\n\nfunction pickForgeBaseUrl(source?: ForgePayToSource): string | null {\n  const fromEnv = process.env.FORGE_URL?.trim();\n  if (fromEnv) return normalizeBaseUrl(fromEnv);\n\n  const fromOpts = source?.baseUrl?.trim();\n  if (!fromOpts) return null;\n\n  const normalized = normalizeBaseUrl(fromOpts);\n  // Never call a laptop Forge from a deployed merchant app.\n  if (\n    /localhost|127\\.0\\.0\\.1/i.test(normalized) &&\n    process.env.NODE_ENV === \"production\"\n  ) {\n    return null;\n  }\n  return normalized;\n}\n\n/**\n * Resolve merchant payTo with minimal host config:\n * 1. `PAY_TO` env (optional override)\n * 2. Live address from Forge public API (when reachable)\n * 3. Baked-in fallback from the Forge PR\n */\nexport async function resolvePayTo(opts: {\n  /** Baked-in address from Forge codegen (required fallback). */\n  fallback: string;\n  /** Optional explicit override (usually process.env.PAY_TO). */\n  payTo?: string;\n  forge?: ForgePayToSource;\n  /** Fetch timeout ms. Defaults to 2500. */\n  timeoutMs?: number;\n}): Promise<string> {\n  const envOverride = process.env.PAY_TO?.trim();\n  if (envOverride && !isZeroAddress(envOverride)) {\n    return envOverride;\n  }\n\n  const explicit = opts.payTo?.trim();\n  if (explicit && !isZeroAddress(explicit) && !opts.forge) {\n    return explicit;\n  }\n\n  const baseUrl = pickForgeBaseUrl(opts.forge);\n  if (baseUrl && opts.forge) {\n    const url = `${baseUrl}/api/public/pay-to/${encodeURIComponent(opts.forge.owner)}/${encodeURIComponent(opts.forge.repo)}`;\n    try {\n      const controller = new AbortController();\n      const timer = setTimeout(\n        () => controller.abort(),\n        opts.timeoutMs ?? 2500,\n      );\n      const res = await fetch(url, {\n        signal: controller.signal,\n        headers: { accept: \"application/json\" },\n      });\n      clearTimeout(timer);\n      if (res.ok) {\n        const json = (await res.json()) as { address?: string };\n        if (json.address && !isZeroAddress(json.address)) {\n          return json.address.trim();\n        }\n      }\n    } catch (err) {\n      console.warn(\"[forge] live payTo fetch failed, using fallback:\", err);\n    }\n  }\n\n  if (explicit && !isZeroAddress(explicit)) return explicit;\n  if (opts.fallback && !isZeroAddress(opts.fallback)) return opts.fallback;\n\n  throw new Error(\n    \"resolvePayTo: no usable address (set Forge wallet / PAY_TO, or re-run Forge PR)\",\n  );\n}\n","import type { DefinedAgentService, SkillMeta } from \"./types.js\";\n\n/**\n * Generate a SKILL.md document for agents from defined Forge services.\n */\nexport function generateSkillMarkdown(\n  services: DefinedAgentService[],\n  meta: SkillMeta,\n): string {\n  const base = meta.baseUrl.replace(/\\/$/, \"\");\n  const lines: string[] = [\n    `---`,\n    `name: ${meta.name}`,\n    `description: ${meta.description}`,\n    `---`,\n    ``,\n    `# ${meta.name}`,\n    ``,\n    meta.description,\n    ``,\n  ];\n\n  if (meta.homepage) {\n    lines.push(`Homepage: ${meta.homepage}`, ``);\n  }\n\n  lines.push(\n    `## How to use`,\n    ``,\n    `1. Read this skill.`,\n    `2. Call the agent endpoint with a JSON body matching the input schema.`,\n    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,\n    `4. Use the returned output fields.`,\n    ``,\n    `## Services`,\n    ``,\n  );\n\n  for (const service of services) {\n    const path = `${base}/agent/${service.path}`;\n    const price = service.payment.amount.startsWith(\"$\")\n      ? service.payment.amount\n      : `$${service.payment.amount}`;\n\n    lines.push(\n      `### \\`${service.name}\\``,\n      ``,\n      service.description,\n      ``,\n      `- **Method:** \\`POST\\``,\n      `- **URL:** \\`${path}\\``,\n      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(\", \")}`,\n      ``,\n      `**Input**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Output**`,\n      ``,\n      \"```json\",\n      JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`]),\n        ),\n        null,\n        2,\n      ),\n      \"```\",\n      ``,\n      `**Example**`,\n      ``,\n      \"```bash\",\n      `curl -X POST ${path} \\\\`,\n      `  -H \"Content-Type: application/json\" \\\\`,\n      `  -d '${JSON.stringify(\n        Object.fromEntries(\n          Object.entries(service.input).map(([k, t]) => [\n            k,\n            t === \"url\" ? \"https://example.com/image.png\" : `example-${k}`,\n          ]),\n        ),\n      )}'`,\n      \"```\",\n      ``,\n    );\n  }\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":";AAOA,eAAsB,UAAa,SAA0C;AAC3E,QAAM,aAAa,QAAQ,cAAc;AACzC,QAAM,YAAY,QAAQ,aAAa;AACvC,QAAM,UAAU,KAAK,IAAI;AAEzB,aAAS;AACP,UAAM,QAAQ,MAAM,QAAQ,IAAI;AAChC,QAAI,QAAQ,cAAc,KAAK,GAAG;AAChC,aAAO;AAAA,IACT;AACA,QAAI,KAAK,IAAI,IAAI,WAAW,WAAW;AACrC,YAAM,IAAI,MAAM,6BAA6B,SAAS,IAAI;AAAA,IAC5D;AACA,UAAM,IAAI,QAAQ,CAAC,YAAY,WAAW,SAAS,UAAU,CAAC;AAAA,EAChE;AACF;AAEO,SAAS,gBAAqC;AACnD,SAAO;AAAA,IACL;AAAA,EACF;AACF;AAGO,SAAS,YAAY,MAAsB;AAChD,SAAO,KACJ,QAAQ,sBAAsB,OAAO,EACrC,QAAQ,MAAM,GAAG,EACjB,YAAY;AACjB;AAEO,SAAS,mBAId,QACsC;AACtC,MAAI,CAAC,OAAO,MAAM,KAAK,GAAG;AACxB,UAAM,IAAI,MAAM,sCAAsC;AAAA,EACxD;AACA,MAAI,CAAC,OAAO,SAAS;AACnB,UAAM,IAAI,MAAM,yCAAyC;AAAA,EAC3D;AAEA,SAAO;AAAA,IACL,GAAG;AAAA,IACH,SAAS;AAAA,IACT,MAAM,YAAY,OAAO,IAAI;AAAA,EAC/B;AACF;;;ACvDA,SAAS,UAAU,oBAAoB;AACvC,SAAS,mBAAmB,0BAA0B;AAEtD,SAAS,6BAA6B;AAEtC,SAAS,sBAAsB;;;ACF/B,eAAsB,iBAAiB,MAKrB;AAChB,QAAM,UAAU,KAAK,WAAW,QAAQ,OAAO,EAAE;AACjD,QAAM,MAAM,MAAM,MAAM,GAAG,OAAO,uBAAuB;AAAA,IACvD,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,eAAe,UAAU,KAAK,cAAc;AAAA,IAC9C;AAAA,IACA,MAAM,KAAK,UAAU;AAAA,MACnB,QAAQ,KAAK,OAAO,KAAK,EAAE,YAAY;AAAA,MACvC,SAAS,KAAK,QAAQ,QAAQ,OAAO,EAAE;AAAA,IACzC,CAAC;AAAA,EACH,CAAC;AACD,MAAI,CAAC,IAAI,IAAI;AACX,UAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,UAAM,IAAI;AAAA,MACR,6BAA6B,IAAI,MAAM,MAAM,KAAK,MAAM,GAAG,GAAG,CAAC;AAAA,IACjE;AAAA,EACF;AACF;;;ACxBA,IAAM,OAAO;AAEN,SAAS,cAAc,SAA6C;AACzE,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO,KAAK,KAAK,QAAQ,KAAK,CAAC;AACjC;AAEA,SAAS,iBAAiB,KAAqB;AAC7C,SAAO,IAAI,QAAQ,OAAO,EAAE;AAC9B;AAEA,SAAS,iBAAiB,QAA0C;AAClE,QAAM,UAAU,QAAQ,IAAI,WAAW,KAAK;AAC5C,MAAI,QAAS,QAAO,iBAAiB,OAAO;AAE5C,QAAM,WAAW,QAAQ,SAAS,KAAK;AACvC,MAAI,CAAC,SAAU,QAAO;AAEtB,QAAM,aAAa,iBAAiB,QAAQ;AAE5C,MACE,0BAA0B,KAAK,UAAU,KACzC,QAAQ,IAAI,aAAa,cACzB;AACA,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAQA,eAAsB,aAAa,MAQf;AAClB,QAAM,cAAc,QAAQ,IAAI,QAAQ,KAAK;AAC7C,MAAI,eAAe,CAAC,cAAc,WAAW,GAAG;AAC9C,WAAO;AAAA,EACT;AAEA,QAAM,WAAW,KAAK,OAAO,KAAK;AAClC,MAAI,YAAY,CAAC,cAAc,QAAQ,KAAK,CAAC,KAAK,OAAO;AACvD,WAAO;AAAA,EACT;AAEA,QAAM,UAAU,iBAAiB,KAAK,KAAK;AAC3C,MAAI,WAAW,KAAK,OAAO;AACzB,UAAM,MAAM,GAAG,OAAO,sBAAsB,mBAAmB,KAAK,MAAM,KAAK,CAAC,IAAI,mBAAmB,KAAK,MAAM,IAAI,CAAC;AACvH,QAAI;AACF,YAAM,aAAa,IAAI,gBAAgB;AACvC,YAAM,QAAQ;AAAA,QACZ,MAAM,WAAW,MAAM;AAAA,QACvB,KAAK,aAAa;AAAA,MACpB;AACA,YAAM,MAAM,MAAM,MAAM,KAAK;AAAA,QAC3B,QAAQ,WAAW;AAAA,QACnB,SAAS,EAAE,QAAQ,mBAAmB;AAAA,MACxC,CAAC;AACD,mBAAa,KAAK;AAClB,UAAI,IAAI,IAAI;AACV,cAAM,OAAQ,MAAM,IAAI,KAAK;AAC7B,YAAI,KAAK,WAAW,CAAC,cAAc,KAAK,OAAO,GAAG;AAChD,iBAAO,KAAK,QAAQ,KAAK;AAAA,QAC3B;AAAA,MACF;AAAA,IACF,SAAS,KAAK;AACZ,cAAQ,KAAK,oDAAoD,GAAG;AAAA,IACtE;AAAA,EACF;AAEA,MAAI,YAAY,CAAC,cAAc,QAAQ,EAAG,QAAO;AACjD,MAAI,KAAK,YAAY,CAAC,cAAc,KAAK,QAAQ,EAAG,QAAO,KAAK;AAEhE,QAAM,IAAI;AAAA,IACR;AAAA,EACF;AACF;;;AFvEA,IAAM,kBAAkB;AAExB,IAAM,0BAA0B;AAEhC,SAAS,UAAU,OAAoC;AACrD,SAAQ,SAAS;AACnB;AAEA,SAAS,wBAAwB,SAA8C;AAC7E,SAAO,IAAI,sBAAsB;AAAA,IAC/B,KAAK,QAAQ,kBAAkB;AAAA,IAC/B,mBAAmB,QAAQ;AAAA,EAC7B,CAAC;AACH;AAEA,SAAS,cACP,MACA,QAC6E;AAC7E,MAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GAAG;AAC5D,WAAO,EAAE,IAAI,OAAO,OAAO,qCAAqC;AAAA,EAClE;AAEA,QAAM,QAAQ;AACd,QAAM,QAAiC,CAAC;AAExC,aAAW,CAAC,KAAK,IAAI,KAAK,OAAO,QAAQ,MAAM,GAAG;AAChD,QAAI,EAAE,OAAO,UAAU,MAAM,GAAG,MAAM,UAAa,MAAM,GAAG,MAAM,MAAM;AACtE,aAAO,EAAE,IAAI,OAAO,OAAO,2BAA2B,GAAG,GAAG;AAAA,IAC9D;AACA,UAAM,MAAM,UAAU,KAAK,MAAM,GAAG,GAAG,IAAI;AAC3C,QAAI,IAAK,QAAO,EAAE,IAAI,OAAO,OAAO,IAAI;AACxC,UAAM,GAAG,IAAI,MAAM,GAAG;AAAA,EACxB;AAEA,SAAO,EAAE,IAAI,MAAM,MAAM;AAC3B;AAEA,SAAS,UAAU,KAAa,OAAgB,MAAsC;AACpF,UAAQ,MAAM;AAAA,IACZ,KAAK;AAAA,IACL,KAAK;AACH,UAAI,OAAO,UAAU,YAAY,CAAC,MAAM,KAAK,GAAG;AAC9C,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,UAAI,SAAS,OAAO;AAClB,YAAI;AACF,cAAI,IAAI,KAAK;AAAA,QACf,QAAQ;AACN,iBAAO,SAAS,GAAG;AAAA,QACrB;AAAA,MACF;AACA,aAAO;AAAA,IACT,KAAK;AACH,UAAI,OAAO,UAAU,YAAY,OAAO,MAAM,KAAK,GAAG;AACpD,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,aAAO;AAAA,IACT,KAAK;AACH,UAAI,OAAO,UAAU,WAAW;AAC9B,eAAO,SAAS,GAAG;AAAA,MACrB;AACA,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,YAAY,QAAwB;AAC3C,QAAM,aAAa,OAAO,WAAW,GAAG,IAAI,OAAO,MAAM,CAAC,IAAI;AAC9D,SAAO,IAAI,UAAU;AACvB;AASA,eAAsB,mBACpB,KACA,UACA,SACiB;AACjB,MAAI,QAAQ;AACZ,MAAI,CAAC,QAAQ,aAAa;AACxB,UAAM,WACJ,QAAQ,eAAe,KAAK,KAAK,QAAQ,OAAO,KAAK,KAAK;AAC5D,YAAQ,MAAM,aAAa;AAAA,MACzB;AAAA,MACA,OAAO,QAAQ;AAAA,MACf,OAAO,QAAQ;AAAA,IACjB,CAAC;AACD,QAAI,cAAc,KAAK,GAAG;AACxB,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF;AAEA,QAAM,YAAY,QAAQ,YAAY,UAAU,QAAQ,OAAO,EAAE,KAAK;AACtE,QAAM,SAAS,aAAa;AAC5B,QAAM,UAAU,cAAc;AAE9B,QAAM,SAAuB,CAAC;AAE9B,aAAW,WAAW,UAAU;AAC9B,UAAM,YAAY,IAAI,QAAQ,IAAI;AAClC,UAAM,WAAW,GAAG,QAAQ,GAAG,SAAS;AACxC,UAAM,UAAU,UAAU,QAAQ,QAAQ,OAAO;AAEjD,QAAI,CAAC,QAAQ,aAAa;AACxB,aAAO,QAAQ,QAAQ,EAAE,IAAI;AAAA,QAC3B,SAAS;AAAA,UACP,QAAQ;AAAA,UACR,OAAO,YAAY,QAAQ,QAAQ,MAAM;AAAA,UACzC;AAAA,UACA;AAAA,QACF;AAAA,QACA,aAAa,QAAQ;AAAA,QACrB,UAAU;AAAA,MACZ;AAAA,IACF;AAEA,WAAO,KAAK,WAAW,OAAO,KAAc,QAAkB;AAC5D,UAAI;AACF,cAAM,YAAY,cAAc,IAAI,MAAM,QAAQ,KAAK;AACvD,YAAI,CAAC,UAAU,IAAI;AACjB,cAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,UAAU,MAAM,CAAC;AAC/C;AAAA,QACF;AAEA,cAAM,SAAS,MAAM,QAAQ,QAAQ,UAAU,OAAO,OAAO;AAC7D,YAAI,KAAK,MAAM;AAAA,MACjB,SAAS,KAAK;AACZ,cAAM,UAAU,eAAe,QAAQ,IAAI,UAAU;AACrD,gBAAQ,MAAM,WAAW,QAAQ,IAAI,YAAY,GAAG;AACpD,YAAI,OAAO,GAAG,EAAE,KAAK,EAAE,OAAO,QAAQ,CAAC;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACH;AAEA,MAAI,CAAC,QAAQ,eAAe,OAAO,KAAK,MAAM,EAAE,SAAS,GAAG;AAC1D,UAAM,cAAc,wBAAwB,OAAO;AACnD,UAAM,WAAW,IAAI;AAAA,MACnB,SAAS,IAAI,CAAC,MAAM,UAAU,EAAE,QAAQ,OAAO,CAAC;AAAA,IAClD;AACA,UAAM,iBAAiB,IAAI,mBAAmB,WAAW;AACzD,eAAW,WAAW,UAAU;AAC9B,qBAAe,SAAS,SAAS,IAAI,eAAe,CAAC;AAAA,IACvD;AACA,QAAI,IAAI,kBAAkB,QAAQ,gBAAgB,QAAW,QAAW,IAAI,CAAC;AAAA,EAC/E;AAEA,MAAI,IAAI,UAAU,MAAM;AAGxB,QAAM,aACJ,QAAQ,SAAS,KAAK,KAAK,KAAK,QAAQ,IAAI,aAAa,KAAK;AAChE,QAAM,SACJ,QAAQ,SAAS,QAAQ,KAAK,KAAK,QAAQ,IAAI,cAAc,KAAK;AACpE,QAAM,iBACJ,QAAQ,SAAS,gBAAgB,KAAK,KACtC,QAAQ,IAAI,yBAAyB,KAAK;AAC5C,QAAM,gBACJ,QAAQ,SAAS,eAAe,KAAK,KACrC,QAAQ,IAAI,iBAAiB,KAAK,MACjC,QAAQ,IAAI,wBACT,WAAW,QAAQ,IAAI,qBAAqB,KAC5C;AAEN,MAAI,cAAc,UAAU,kBAAkB,eAAe;AAC3D,SAAK,iBAAiB;AAAA,MACpB;AAAA,MACA;AAAA,MACA,SAAS;AAAA,MACT;AAAA,IACF,CAAC,EAAE,MAAM,CAAC,QAAQ;AAChB,cAAQ,KAAK,sCAAsC,GAAG;AAAA,IACxD,CAAC;AAAA,EACH;AAEA,SAAO;AACT;AAGO,SAAS,kBACd,UACA,SACuC;AACvC,SAAO,CAAC,QAAQ,mBAAmB,KAAK,UAAU,OAAO;AAC3D;;;AG7MO,SAAS,sBACd,UACA,MACQ;AACR,QAAM,OAAO,KAAK,QAAQ,QAAQ,OAAO,EAAE;AAC3C,QAAM,QAAkB;AAAA,IACtB;AAAA,IACA,SAAS,KAAK,IAAI;AAAA,IAClB,gBAAgB,KAAK,WAAW;AAAA,IAChC;AAAA,IACA;AAAA,IACA,KAAK,KAAK,IAAI;AAAA,IACd;AAAA,IACA,KAAK;AAAA,IACL;AAAA,EACF;AAEA,MAAI,KAAK,UAAU;AACjB,UAAM,KAAK,aAAa,KAAK,QAAQ,IAAI,EAAE;AAAA,EAC7C;AAEA,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,aAAW,WAAW,UAAU;AAC9B,UAAM,OAAO,GAAG,IAAI,UAAU,QAAQ,IAAI;AAC1C,UAAM,QAAQ,QAAQ,QAAQ,OAAO,WAAW,GAAG,IAC/C,QAAQ,QAAQ,SAChB,IAAI,QAAQ,QAAQ,MAAM;AAE9B,UAAM;AAAA,MACJ,SAAS,QAAQ,IAAI;AAAA,MACrB;AAAA,MACA,QAAQ;AAAA,MACR;AAAA,MACA;AAAA,MACA,gBAAgB,IAAI;AAAA,MACpB,gBAAgB,KAAK,IAAI,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,QAAQ,UAAU,KAAK,IAAI,CAAC;AAAA,MAC7F;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,KAAK;AAAA,QACH,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AAAA,QAC7D;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,KAAK;AAAA,QACH,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,MAAM,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC;AAAA,QAC9D;AAAA,QACA;AAAA,QACA;AAAA,MACF;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA,gBAAgB,IAAI;AAAA,MACpB;AAAA,MACA,SAAS,KAAK;AAAA,QACZ,OAAO;AAAA,UACL,OAAO,QAAQ,QAAQ,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM;AAAA,YAC5C;AAAA,YACA,MAAM,QAAQ,kCAAkC,WAAW,CAAC;AAAA,UAC9D,CAAC;AAAA,QACH;AAAA,MACF,CAAC;AAAA,MACD;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,SAAO,MAAM,KAAK,IAAI;AACxB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawcash/forge",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "ClawCash Forge — define agent-native services with x402 payments",
   "type": "module",
   "main": "./dist/index.cjs",