@clawcash/forge 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# @clawcash/forge
+
+Define agent-native services on top of an existing backend. Forge wraps a high-level action, handles polling helpers, mounts Express routes, and attaches x402 payment.
+
+Published under the [ClawCash](https://www.npmjs.com/org/clawcash) npm org.
+
+## Install
+
+```bash
+npm install @clawcash/forge express
+```
+
+For local demo against the sibling folder:
+
+```json
+{
+  "dependencies": {
+    "@clawcash/forge": "file:../forge-sdk"
+  }
+}
+```
+
+## Quick start
+
+```ts
+import express from "express";
+import { defineAgentService, mountAgentServices } from "@clawcash/forge";
+
+const removeBackground = defineAgentService({
+  name: "remove_background",
+  description: "Remove the background from an image.",
+  input: { imageUrl: "url" },
+  output: { resultUrl: "url" },
+  payment: {
+    amount: "0.10",
+    currency: "USDC",
+    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" };
+  },
+});
+
+const app = express();
+app.use(express.json());
+
+mountAgentServices(app, [removeBackground], {
+  payTo: process.env.PAY_TO!,
+  facilitatorUrl: process.env.FACILITATOR_URL,
+});
+
+app.listen(3000);
+```
+
+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`.
+
+## API
+
+| Export | Purpose |
+|--------|---------|
+| `defineAgentService` | Declare name, schemas, payment, and `execute` |
+| `mountAgentServices` | Mount `POST /agent/:name` with x402 |
+| `generateSkillMarkdown` | Build a `SKILL.md` for agents |
+| `waitUntil` / `context.waitUntil` | Poll until a job completes |
+
+## Build
+
+```bash
+npm install
+npm run build
+```

package/dist/index.cjs

@@ -0,0 +1,283 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  createContext: () => createContext,
+  createForgeRouter: () => createForgeRouter,
+  defineAgentService: () => defineAgentService,
+  generateSkillMarkdown: () => generateSkillMarkdown,
+  mountAgentServices: () => mountAgentServices,
+  toKebabCase: () => toKebabCase,
+  waitUntil: () => waitUntil
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/define.ts
+async function waitUntil(options) {
+  const intervalMs = options.intervalMs ?? 500;
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const started = Date.now();
+  for (; ; ) {
+    const value = await options.run();
+    if (options.completedWhen(value)) {
+      return value;
+    }
+    if (Date.now() - started >= timeoutMs) {
+      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+function createContext() {
+  return {
+    waitUntil
+  };
+}
+function toKebabCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
+}
+function defineAgentService(config) {
+  if (!config.name?.trim()) {
+    throw new Error("defineAgentService: name is required");
+  }
+  if (!config.execute) {
+    throw new Error("defineAgentService: execute is required");
+  }
+  return {
+    ...config,
+    __forge: true,
+    path: toKebabCase(config.name)
+  };
+}
+
+// src/mount.ts
+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";
+function asNetwork(value) {
+  return value ?? DEFAULT_NETWORK;
+}
+function validateInput(body, schema) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, error: "Request body must be a JSON object" };
+  }
+  const input = body;
+  const value = {};
+  for (const [key, type] of Object.entries(schema)) {
+    if (!(key in input) || input[key] === void 0 || input[key] === null) {
+      return { ok: false, error: `Missing required field: ${key}` };
+    }
+    const err = checkType(key, input[key], type);
+    if (err) return { ok: false, error: err };
+    value[key] = input[key];
+  }
+  return { ok: true, value };
+}
+function checkType(key, value, type) {
+  switch (type) {
+    case "string":
+    case "url":
+      if (typeof value !== "string" || !value.trim()) {
+        return `Field ${key} must be a non-empty string`;
+      }
+      if (type === "url") {
+        try {
+          new URL(value);
+        } catch {
+          return `Field ${key} must be a valid URL`;
+        }
+      }
+      return null;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return `Field ${key} must be a number`;
+      }
+      return null;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return `Field ${key} must be a boolean`;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+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");
+  }
+  const basePath = (options.basePath ?? "/agent").replace(/\/$/, "") || "/agent";
+  const router = (0, import_express.Router)();
+  const context = createContext();
+  const routes = {};
+  for (const service of services) {
+    const routePath = `/${service.path}`;
+    const fullPath = `${basePath}${routePath}`;
+    const network = asNetwork(service.payment.network);
+    if (!options.skipPayment) {
+      routes[`POST ${fullPath}`] = {
+        accepts: {
+          scheme: "exact",
+          price: formatPrice(service.payment.amount),
+          network,
+          payTo: options.payTo
+        },
+        description: service.description,
+        mimeType: "application/json"
+      };
+    }
+    router.post(routePath, async (req, res) => {
+      try {
+        const validated = validateInput(req.body, service.input);
+        if (!validated.ok) {
+          res.status(400).json({ error: validated.error });
+          return;
+        }
+        const output = await service.execute(validated.value, context);
+        res.json(output);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Internal error";
+        console.error(`[forge] ${service.name} failed:`, err);
+        res.status(500).json({ error: message });
+      }
+    });
+  }
+  if (!options.skipPayment && Object.keys(routes).length > 0) {
+    const facilitator = new import_server.HTTPFacilitatorClient({
+      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR
+    });
+    const networks = new Set(
+      services.map((s) => asNetwork(s.payment.network))
+    );
+    const resourceServer = new import_express2.x402ResourceServer(facilitator);
+    for (const network of networks) {
+      resourceServer.register(network, new import_server2.ExactEvmScheme());
+    }
+    app.use((0, import_express2.paymentMiddleware)(routes, resourceServer, void 0, void 0, true));
+  }
+  app.use(basePath, router);
+  return router;
+}
+function createForgeRouter(services, options) {
+  return (app) => mountAgentServices(app, services, options);
+}
+
+// src/skill.ts
+function generateSkillMarkdown(services, meta) {
+  const base = meta.baseUrl.replace(/\/$/, "");
+  const lines = [
+    `---`,
+    `name: ${meta.name}`,
+    `description: ${meta.description}`,
+    `---`,
+    ``,
+    `# ${meta.name}`,
+    ``,
+    meta.description,
+    ``
+  ];
+  if (meta.homepage) {
+    lines.push(`Homepage: ${meta.homepage}`, ``);
+  }
+  lines.push(
+    `## How to use`,
+    ``,
+    `1. Read this skill.`,
+    `2. Call the agent endpoint with a JSON body matching the input schema.`,
+    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,
+    `4. Use the returned output fields.`,
+    ``,
+    `## Services`,
+    ``
+  );
+  for (const service of services) {
+    const path = `${base}/agent/${service.path}`;
+    const price = service.payment.amount.startsWith("$") ? service.payment.amount : `$${service.payment.amount}`;
+    lines.push(
+      `### \`${service.name}\``,
+      ``,
+      service.description,
+      ``,
+      `- **Method:** \`POST\``,
+      `- **URL:** \`${path}\``,
+      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(", ")}`,
+      ``,
+      `**Input**`,
+      ``,
+      "```json",
+      JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`])
+        ),
+        null,
+        2
+      ),
+      "```",
+      ``,
+      `**Output**`,
+      ``,
+      "```json",
+      JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`])
+        ),
+        null,
+        2
+      ),
+      "```",
+      ``,
+      `**Example**`,
+      ``,
+      "```bash",
+      `curl -X POST ${path} \\`,
+      `  -H "Content-Type: application/json" \\`,
+      `  -d '${JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.input).map(([k, t]) => [
+            k,
+            t === "url" ? "https://example.com/image.png" : `example-${k}`
+          ])
+        )
+      )}'`,
+      "```",
+      ``
+    );
+  }
+  return lines.join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createContext,
+  createForgeRouter,
+  defineAgentService,
+  generateSkillMarkdown,
+  mountAgentServices,
+  toKebabCase,
+  waitUntil
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +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"]}

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { Application, Router } from 'express';
+
+type SchemaFieldType = "string" | "url" | "number" | "boolean";
+type InputSchema = Record<string, SchemaFieldType>;
+type OutputSchema = Record<string, SchemaFieldType>;
+interface PaymentConfig {
+    /** Dollar amount as a string, e.g. "0.10" */
+    amount: string;
+    currency: "USDC";
+    protocols: Array<"x402" | "mpp">;
+    /** CAIP-2 network. Defaults to Base Sepolia (`eip155:84532`). */
+    network?: string;
+}
+interface WaitUntilOptions<T> {
+    run: () => Promise<T>;
+    completedWhen: (value: T) => boolean;
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+interface AgentServiceContext {
+    waitUntil: <T>(options: WaitUntilOptions<T>) => Promise<T>;
+}
+interface AgentServiceConfig<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    input: InputSchema;
+    output: OutputSchema;
+    payment: PaymentConfig;
+    execute: (input: TInput, context: AgentServiceContext) => Promise<TOutput>;
+}
+interface DefinedAgentService<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>> extends AgentServiceConfig<TInput, TOutput> {
+    readonly __forge: true;
+    path: string;
+}
+interface MountOptions {
+    /** Recipient wallet address for x402 payments */
+    payTo: string;
+    /** Facilitator URL. Defaults to https://x402.org/facilitator */
+    facilitatorUrl?: string;
+    /** Path prefix for agent routes. Defaults to /agent */
+    basePath?: string;
+    /** Skip x402 (local dev only). Defaults to false. */
+    skipPayment?: boolean;
+}
+interface SkillMeta {
+    name: string;
+    description: string;
+    baseUrl: string;
+    homepage?: string;
+}
+
+declare function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T>;
+declare function createContext(): AgentServiceContext;
+/** Convert snake_case or camelCase service name to kebab-case path segment. */
+declare function toKebabCase(name: string): string;
+declare function defineAgentService<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>>(config: AgentServiceConfig<TInput, TOutput>): DefinedAgentService<TInput, TOutput>;
+
+/**
+ * Mount Forge agent services on an Express app.
+ * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.
+ */
+declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Router;
+/** Express-compatible middleware alias used in docs. */
+declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => 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 };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+import { Application, Router } from 'express';
+
+type SchemaFieldType = "string" | "url" | "number" | "boolean";
+type InputSchema = Record<string, SchemaFieldType>;
+type OutputSchema = Record<string, SchemaFieldType>;
+interface PaymentConfig {
+    /** Dollar amount as a string, e.g. "0.10" */
+    amount: string;
+    currency: "USDC";
+    protocols: Array<"x402" | "mpp">;
+    /** CAIP-2 network. Defaults to Base Sepolia (`eip155:84532`). */
+    network?: string;
+}
+interface WaitUntilOptions<T> {
+    run: () => Promise<T>;
+    completedWhen: (value: T) => boolean;
+    intervalMs?: number;
+    timeoutMs?: number;
+}
+interface AgentServiceContext {
+    waitUntil: <T>(options: WaitUntilOptions<T>) => Promise<T>;
+}
+interface AgentServiceConfig<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>> {
+    name: string;
+    description: string;
+    input: InputSchema;
+    output: OutputSchema;
+    payment: PaymentConfig;
+    execute: (input: TInput, context: AgentServiceContext) => Promise<TOutput>;
+}
+interface DefinedAgentService<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>> extends AgentServiceConfig<TInput, TOutput> {
+    readonly __forge: true;
+    path: string;
+}
+interface MountOptions {
+    /** Recipient wallet address for x402 payments */
+    payTo: string;
+    /** Facilitator URL. Defaults to https://x402.org/facilitator */
+    facilitatorUrl?: string;
+    /** Path prefix for agent routes. Defaults to /agent */
+    basePath?: string;
+    /** Skip x402 (local dev only). Defaults to false. */
+    skipPayment?: boolean;
+}
+interface SkillMeta {
+    name: string;
+    description: string;
+    baseUrl: string;
+    homepage?: string;
+}
+
+declare function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T>;
+declare function createContext(): AgentServiceContext;
+/** Convert snake_case or camelCase service name to kebab-case path segment. */
+declare function toKebabCase(name: string): string;
+declare function defineAgentService<TInput extends Record<string, unknown> = Record<string, unknown>, TOutput extends Record<string, unknown> = Record<string, unknown>>(config: AgentServiceConfig<TInput, TOutput>): DefinedAgentService<TInput, TOutput>;
+
+/**
+ * Mount Forge agent services on an Express app.
+ * Each service is exposed as POST {basePath}/{kebab-name} with optional x402.
+ */
+declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Router;
+/** Express-compatible middleware alias used in docs. */
+declare function createForgeRouter(services: DefinedAgentService[], options: MountOptions): (app: Application) => 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 };

package/dist/index.js

@@ -0,0 +1,250 @@
+// src/define.ts
+async function waitUntil(options) {
+  const intervalMs = options.intervalMs ?? 500;
+  const timeoutMs = options.timeoutMs ?? 6e4;
+  const started = Date.now();
+  for (; ; ) {
+    const value = await options.run();
+    if (options.completedWhen(value)) {
+      return value;
+    }
+    if (Date.now() - started >= timeoutMs) {
+      throw new Error(`waitUntil timed out after ${timeoutMs}ms`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+}
+function createContext() {
+  return {
+    waitUntil
+  };
+}
+function toKebabCase(name) {
+  return name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
+}
+function defineAgentService(config) {
+  if (!config.name?.trim()) {
+    throw new Error("defineAgentService: name is required");
+  }
+  if (!config.execute) {
+    throw new Error("defineAgentService: execute is required");
+  }
+  return {
+    ...config,
+    __forge: true,
+    path: toKebabCase(config.name)
+  };
+}
+
+// src/mount.ts
+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";
+function asNetwork(value) {
+  return value ?? DEFAULT_NETWORK;
+}
+function validateInput(body, schema) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, error: "Request body must be a JSON object" };
+  }
+  const input = body;
+  const value = {};
+  for (const [key, type] of Object.entries(schema)) {
+    if (!(key in input) || input[key] === void 0 || input[key] === null) {
+      return { ok: false, error: `Missing required field: ${key}` };
+    }
+    const err = checkType(key, input[key], type);
+    if (err) return { ok: false, error: err };
+    value[key] = input[key];
+  }
+  return { ok: true, value };
+}
+function checkType(key, value, type) {
+  switch (type) {
+    case "string":
+    case "url":
+      if (typeof value !== "string" || !value.trim()) {
+        return `Field ${key} must be a non-empty string`;
+      }
+      if (type === "url") {
+        try {
+          new URL(value);
+        } catch {
+          return `Field ${key} must be a valid URL`;
+        }
+      }
+      return null;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return `Field ${key} must be a number`;
+      }
+      return null;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return `Field ${key} must be a boolean`;
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+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");
+  }
+  const basePath = (options.basePath ?? "/agent").replace(/\/$/, "") || "/agent";
+  const router = createRouter();
+  const context = createContext();
+  const routes = {};
+  for (const service of services) {
+    const routePath = `/${service.path}`;
+    const fullPath = `${basePath}${routePath}`;
+    const network = asNetwork(service.payment.network);
+    if (!options.skipPayment) {
+      routes[`POST ${fullPath}`] = {
+        accepts: {
+          scheme: "exact",
+          price: formatPrice(service.payment.amount),
+          network,
+          payTo: options.payTo
+        },
+        description: service.description,
+        mimeType: "application/json"
+      };
+    }
+    router.post(routePath, async (req, res) => {
+      try {
+        const validated = validateInput(req.body, service.input);
+        if (!validated.ok) {
+          res.status(400).json({ error: validated.error });
+          return;
+        }
+        const output = await service.execute(validated.value, context);
+        res.json(output);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : "Internal error";
+        console.error(`[forge] ${service.name} failed:`, err);
+        res.status(500).json({ error: message });
+      }
+    });
+  }
+  if (!options.skipPayment && Object.keys(routes).length > 0) {
+    const facilitator = new HTTPFacilitatorClient({
+      url: options.facilitatorUrl ?? DEFAULT_FACILITATOR
+    });
+    const networks = new Set(
+      services.map((s) => asNetwork(s.payment.network))
+    );
+    const resourceServer = new x402ResourceServer(facilitator);
+    for (const network of networks) {
+      resourceServer.register(network, new ExactEvmScheme());
+    }
+    app.use(paymentMiddleware(routes, resourceServer, void 0, void 0, true));
+  }
+  app.use(basePath, router);
+  return router;
+}
+function createForgeRouter(services, options) {
+  return (app) => mountAgentServices(app, services, options);
+}
+
+// src/skill.ts
+function generateSkillMarkdown(services, meta) {
+  const base = meta.baseUrl.replace(/\/$/, "");
+  const lines = [
+    `---`,
+    `name: ${meta.name}`,
+    `description: ${meta.description}`,
+    `---`,
+    ``,
+    `# ${meta.name}`,
+    ``,
+    meta.description,
+    ``
+  ];
+  if (meta.homepage) {
+    lines.push(`Homepage: ${meta.homepage}`, ``);
+  }
+  lines.push(
+    `## How to use`,
+    ``,
+    `1. Read this skill.`,
+    `2. Call the agent endpoint with a JSON body matching the input schema.`,
+    `3. If you receive HTTP 402, pay via x402 (USDC) and retry with the payment header.`,
+    `4. Use the returned output fields.`,
+    ``,
+    `## Services`,
+    ``
+  );
+  for (const service of services) {
+    const path = `${base}/agent/${service.path}`;
+    const price = service.payment.amount.startsWith("$") ? service.payment.amount : `$${service.payment.amount}`;
+    lines.push(
+      `### \`${service.name}\``,
+      ``,
+      service.description,
+      ``,
+      `- **Method:** \`POST\``,
+      `- **URL:** \`${path}\``,
+      `- **Price:** ${price} ${service.payment.currency} via ${service.payment.protocols.join(", ")}`,
+      ``,
+      `**Input**`,
+      ``,
+      "```json",
+      JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.input).map(([k, t]) => [k, `<${t}>`])
+        ),
+        null,
+        2
+      ),
+      "```",
+      ``,
+      `**Output**`,
+      ``,
+      "```json",
+      JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.output).map(([k, t]) => [k, `<${t}>`])
+        ),
+        null,
+        2
+      ),
+      "```",
+      ``,
+      `**Example**`,
+      ``,
+      "```bash",
+      `curl -X POST ${path} \\`,
+      `  -H "Content-Type: application/json" \\`,
+      `  -d '${JSON.stringify(
+        Object.fromEntries(
+          Object.entries(service.input).map(([k, t]) => [
+            k,
+            t === "url" ? "https://example.com/image.png" : `example-${k}`
+          ])
+        )
+      )}'`,
+      "```",
+      ``
+    );
+  }
+  return lines.join("\n");
+}
+export {
+  createContext,
+  createForgeRouter,
+  defineAgentService,
+  generateSkillMarkdown,
+  mountAgentServices,
+  toKebabCase,
+  waitUntil
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@clawcash/forge",
+  "version": "0.1.0",
+  "description": "ClawCash Forge — define agent-native services with x402 payments",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "clawcash",
+    "forge",
+    "x402",
+    "agents",
+    "mcp"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "express": ">=4.0.0"
+  },
+  "dependencies": {
+    "@x402/core": "^2.18.0",
+    "@x402/evm": "^2.18.0",
+    "@x402/express": "^2.18.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/node": "^22.10.0",
+    "express": "^5.2.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.0"
+  }
+}