@clawcash/forge 0.1.7 → 0.2.0

package/README.md

@@ -2,77 +2,76 @@
 
 The fastest way to make an **existing** SaaS/API app agent-native.
 
-Define a high-level agent action on top of your backend, mount Express routes, attach x402, and register with the ClawCash gateway. Humans keep the same product; agents get a paid one-shot.
+Define a paid action on top of your backend and run an outbound worker that fulfills jobs from the ClawCash gateway. Agents discover, pay (x402/USDC), and call **the gateway** — your app adds no routes, no middleware, and no public agent surface. **Zero runtime dependencies.**
 
 Published under the [ClawCash](https://www.npmjs.com/org/clawcash) npm org.
 
-**Stack note:** `defineAgentService` / payTo / heartbeat are framework-agnostic. `mountAgentServices` is the **Express** adapter today. Next/Nest ship later as thin adapters (`@clawcash/forge/next`, etc.) — not one mega environment-agnostic package. A separate greenfield “build agent-native apps” SDK is a future product, not this one.
+```text
+agent  ->  gateway.clawca.sh/<handle>/<action>   (x402)
+               | job queued
+worker ->  claims job (outbound long-poll), runs execute(), posts result
+               |
+agent  <-  result, same request
+```
 
 ## Install
 
 ```bash
-npm install @clawcash/forge express
+npm install @clawcash/forge
 ```
 
-## Quick start (no PAY_TO env required)
+## Quick start (worker mode — the default)
+
+One self-contained file. Your web server is not touched.
 
 ```ts
-import express from "express";
-import { defineAgentService, mountAgentServices } from "@clawcash/forge";
+// src/forge/agent-worker.ts
+import { defineAgentService, forgeWorker } 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) {
-    return { resultUrl: "https://example.com/out.png" };
+  payment: { amount: "0.10", currency: "USDC", protocols: ["x402"] },
+  async execute({ imageUrl }) {
+    // call the API your product already has — loopback, hosted, or direct import
+    const res = await fetch("http://127.0.0.1:3000/api/remove", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ imageUrl }),
+    });
+    const data = await res.json();
+    return { resultUrl: data.resultUrl };
   },
 });
 
-const app = express();
-app.use(express.json());
-
-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);
+forgeWorker({ services: [removeBackground], handle: "my-app" });
 ```
 
-Resolution order: `PAY_TO` env (optional override) → live Forge API → `payToFallback`.
+```bash
+FORGE_API_KEY=fk_live_... node --import tsx src/forge/agent-worker.ts
+# [forge-worker] my-app polling https://gateway.clawca.sh/jobs/claim ...
+```
 
-Agents call `POST /agent/remove-background` and pay via x402 when challenged with HTTP 402.
+Env: `FORGE_API_KEY` (required, from the Forge dashboard), `FORGE_HANDLE` (if not passed as an option), `GATEWAY_URL` (optional override).
 
-After mount, the merchant also exposes liveliness probes:
+The worker makes outbound requests only. It runs behind NAT, on localhost, in a private subnet — anywhere with outbound HTTPS. Polling doubles as the merchant heartbeat.
 
-- `GET /forge/health` — process up + Forge mounted
-- `GET /forge/status` — readiness (`ready` needs fulfill secret + public URL + actions)
-- `GET /.well-known/clawcash.json` — discovery
+## Fetch-handler mode (inbound alternative)
 
-Default payment network is **Base mainnet** (`eip155:8453`) via the public **XPay** facilitator (`https://facilitator.xpay.sh`) — no API keys.
+For gateway-push deployments, `createForgeHandler(services)` returns a web-standard `(Request) => Promise<Response>` serving `/forge/health`, `/forge/status`, `/.well-known/clawcash.json`, and `POST /forge/fulfill/{action}` (gated by `FORGE_API_KEY`). Mounts natively in Next.js route handlers, Hono, Bun, Deno; `createForgeRequestMatcher` returns `null` on unmatched routes for fall-through mounting.
 
 ## API
 
 | Export | Purpose |
 |--------|---------|
 | `defineAgentService` | Declare name, schemas, payment, and `execute` |
-| `mountAgentServices` | Async mount agent + fulfill + health/status routes |
-| `resolvePayTo` | Resolve merchant wallet (env → Forge → fallback) |
-| `generateSkillMarkdown` | Build a `SKILL.md` for agents |
-| `waitUntil` / `context.waitUntil` | Poll until a job completes |
-| `heartbeatGateway` | Push live base URL to the ClawCash gateway |
+| `forgeWorker` | Outbound worker: claim paid jobs, execute, report results |
+| `createForgeHandler` / `createForgeRequestMatcher` | Web-standard inbound fulfillment surface |
+| `validateInput` / `checkType` | Schema validation |
+| `waitUntil` / `context.waitUntil` | Poll until a job completes inside `execute` |
+| `getForgeApiKey` / `forgeGatewayLoopbackHeaders` | Auth helpers for fulfillment traffic |
 
 ## Build