@clawcash/forge 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,3 @@
-import { Application, Router, Request, Response, NextFunction } from 'express';
-
 type SchemaFieldType = "string" | "url" | "number" | "boolean";
 type InputSchema = Record<string, SchemaFieldType>;
 type OutputSchema = Record<string, SchemaFieldType>;
@@ -32,73 +30,6 @@ 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. 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;
-    /**
-     * Gateway heartbeat after mount. Only FORGE_API_KEY is required as env;
-     * the URL defaults to the ClawCash gateway, the handle is baked by Forge
-     * codegen, and the public base URL is resolved from platform vars or
-     * inferred (self-verified) from the first inbound probe.
-     */
-    gateway?: {
-        /** Defaults to https://gateway.clawca.sh (or GATEWAY_URL env). */
-        url?: string;
-        /** Merchant handle — baked by Forge codegen (or FORGE_HANDLE env). */
-        handle?: string;
-        /** @deprecated Prefer FORGE_API_KEY env — per-project key from Forge dashboard. */
-        registerSecret?: string;
-        /** Merchant public base URL. Usually omitted — resolved automatically. */
-        publicBaseUrl?: string;
-    };
-    /**
-     * Path prefix for private fulfillment (gateway → merchant after x402).
-     * Defaults to /forge/fulfill. Not end-user / x402 routes.
-     */
-    fulfillPath?: string;
-}
-interface SkillMeta {
-    name: string;
-    description: string;
-    baseUrl: string;
-    homepage?: string;
-}
 
 declare function waitUntil<T>(options: WaitUntilOptions<T>): Promise<T>;
 declare function createContext(): AgentServiceContext;
@@ -106,95 +37,82 @@ declare function createContext(): AgentServiceContext;
 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.
- * - GET /forge/health, GET /forge/status, GET /.well-known/clawcash.json — liveliness
- * - POST {basePath}/{kebab-name} — optional public x402 agent surface
- * - POST /forge/fulfill/{kebab-name} — private gateway fulfillment after payment
- *
- * payTo resolves automatically: PAY_TO env (optional) → Forge API → baked fallback.
- */
-declare function mountAgentServices(app: Application, services: DefinedAgentService[], options: MountOptions): Promise<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;
+interface ForgeWorkerOptions {
+    services: DefinedAgentService[];
+    /** Merchant handle. Defaults to FORGE_HANDLE env. */
+    handle?: string;
+    /** Per-project key from the Forge dashboard. Defaults to FORGE_API_KEY env. */
+    apiKey?: string;
+    /** Defaults to https://gateway.clawca.sh (or GATEWAY_URL env). */
+    gatewayUrl?: string;
+    /** Shown in gateway job rows. Defaults to hostname-pid. */
+    workerId?: string;
+    /** Long-poll window per claim request. Defaults to 20s (gateway caps at 25s). */
+    waitMs?: number;
+    onError?: (error: Error) => void;
+}
+interface ForgeWorkerHandle {
+    stop: () => void;
+    readonly running: boolean;
+}
+declare function forgeWorker(options: ForgeWorkerOptions): ForgeWorkerHandle;
 
-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
+ * Web-standard fetch handler — mount Forge fulfillment + liveliness on any
+ * runtime that speaks (Request) => Response: Next.js route handlers, Hono,
+ * Fastify (via adapter), Bun, Deno, plain node:http (via adapter).
+ *
+ * This surface is for gateway-push (fulfillment.mode=sdk) merchants and
+ * deploy probes. Payment lives on the gateway; prefer forgeWorker() when the
+ * merchant can run an outbound worker instead.
+ *
+ * Routes handled (anything else returns null from tryHandleForgeRequest, or
+ * 404 from the plain handler):
+ * - GET  /forge/health
+ * - GET  /forge/status
+ * - GET  /.well-known/clawcash.json
+ * - POST {fulfillPath}/{action-path}   (requires FORGE_API_KEY auth)
  */
-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>;
-
+interface ForgeHandlerOptions {
+    /** Merchant handle — FORGE_HANDLE env when omitted. */
+    handle?: string;
+    /** Per-project key. FORGE_API_KEY env when omitted. */
+    apiKey?: string;
+    /** Defaults to /forge/fulfill. */
+    fulfillPath?: string;
+    /** Reported in /forge/status. Optional. */
+    publicBaseUrl?: string;
+    /** Reported in /forge/status. Defaults to GATEWAY_URL env or the ClawCash gateway. */
+    gatewayUrl?: string;
+}
+type ForgeFetchHandler = (request: Request) => Promise<Response>;
 /**
- * Public base URL resolution, in trust order:
- * 1. PUBLIC_BASE_URL env — explicit override.
- * 2. Platform-provided vars (Railway, Render, Vercel, Fly, Heroku) — set by
- *    the host, not by request input, so safe to trust as-is.
- * 3. Lazy inference from the first inbound request to the Forge surface
- *    (X-Forwarded-Proto + Host). Host is attacker-controlled, so a candidate
- *    is only accepted after self-verification: we fetch our own
- *    /forge/health at the candidate URL and check it returns this
- *    instance's boot nonce.
+ * Returns a Response when the request targets a Forge route, else null so
+ * the host app can fall through to its own routing.
  */
-declare function resolveBaseUrlFromEnv(explicit?: string): string | null;
-declare class PublicBaseUrlResolver {
-    /** Per-boot nonce, echoed by /forge/health for self-verification. */
-    readonly instanceNonce: string;
-    private resolved;
-    private verifying;
-    private rejected;
-    private attempts;
-    private onResolved;
-    constructor(opts: {
-        /** URL already known from env/platform vars (trusted, no verification). */
-        initial: string | null;
-        /** Called once when a base URL first becomes known via inference. */
-        onResolved?: (baseUrl: string) => void;
-    });
-    get(): string | null;
-    /**
-     * Feed an inbound Forge-surface request. No-op once resolved. Kicks off
-     * async self-verification of the candidate URL derived from the request.
-     */
-    considerRequest(req: Request): void;
-    /** Fetch our own /forge/health at the candidate and match the boot nonce. */
-    private verify;
-}
+declare function createForgeRequestMatcher(services: DefinedAgentService[], options?: ForgeHandlerOptions): (request: Request) => Promise<Response | null>;
+/** Like createForgeRequestMatcher, but 404s instead of returning null. */
+declare function createForgeHandler(services: DefinedAgentService[], options?: ForgeHandlerOptions): ForgeFetchHandler;
 
 /**
- * Notify ClawCash gateway of this merchant's live public base URL.
- * Full action registration still happens from Forge "Go live".
+ * Framework-free input validation shared by every execution surface
+ * (Express mount, fetch handler, worker).
  */
-declare function heartbeatGateway(opts: {
-    gatewayUrl: string;
-    handle: string;
-    baseUrl: string;
-    registerSecret: string;
-}): Promise<void>;
+type ValidationResult = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+declare function validateInput(body: unknown, schema: InputSchema): ValidationResult;
+declare function checkType(key: string, value: unknown, type: SchemaFieldType): string | null;
 
 /**
- * Merchant-side Forge surface status — public probes for deploy / go-live checks.
+ * Merchant-side Forge surface status — public probes for deploy / go-live
+ * checks when running the fetch handler. Worker-mode merchants report
+ * liveness by polling the gateway instead.
  */
-type ForgeHeartbeatState = {
-    attempted: boolean;
-    ok: boolean | null;
-    at: string | null;
-    error: string | null;
-};
 type ForgeSurfaceStatus = {
     ok: boolean;
     forge: true;
@@ -202,42 +120,29 @@ type ForgeSurfaceStatus = {
     handle: string | null;
     publicBaseUrl: string | null;
     gatewayUrl: string | null;
-    /** True when FORGE_API_KEY is set so /forge/fulfill is mounted. */
+    /** True when FORGE_API_KEY is set so fulfillment is accepted. */
     fulfillMounted: boolean;
     fulfillPath: string;
-    agentBasePath: string;
-    skipPayment: boolean;
     actions: Array<{
         name: string;
         path: string;
         price: string;
     }>;
-    /** Env + fulfill ready — merchant can accept gateway fulfillment. */
+    /** Key + actions present — merchant can accept gateway fulfillment. */
     ready: boolean;
-    heartbeat: ForgeHeartbeatState;
     endpoints: {
         health: string;
         status: string;
         wellKnown: string;
         fulfill: string;
-        agent: string;
     };
 };
-declare function recordHeartbeatResult(result: {
-    ok: true;
-} | {
-    ok: false;
-    error: string;
-}): void;
-declare function getLastHeartbeat(): ForgeHeartbeatState;
 declare function buildForgeSurfaceStatus(opts: {
     handle: string | null;
     publicBaseUrl: string | null;
     gatewayUrl: string | null;
     fulfillMounted: boolean;
     fulfillPath: string;
-    agentBasePath: string;
-    skipPayment: boolean;
     actions: Array<{
         name: string;
         path: string;
@@ -255,20 +160,19 @@ declare function buildWellKnownDocument(status: ForgeSurfaceStatus): {
 declare function forgeSdkVersion(): string;
 
 /**
- * Per-project Forge API key for gateway → merchant fulfillment.
- * Merchants set FORGE_API_KEY from the Forge dashboard (never the shared
- * GATEWAY_REGISTER_SECRET — that is Forge↔gateway platform auth only).
+ * Per-project Forge API key helpers — framework-free.
+ *
+ * Merchants set FORGE_API_KEY from the Forge dashboard. The worker uses it
+ * to claim jobs from the gateway; the fetch handler uses it to gate
+ * gateway-push fulfillment; execute() can use forgeGatewayLoopbackHeaders()
+ * so the merchant's own API middleware can recognize fulfillment traffic.
  *
  * GATEWAY_REGISTER_SECRET is accepted as a deprecated fallback for older deploys.
  */
 declare function getForgeApiKey(explicit?: string | null): string | null;
-/** @deprecated Use getForgeApiKey */
-declare function getForgeGatewaySecret(explicit?: string | null): string | null;
-declare function isForgeGatewayRequest(req: Request, secret?: string | null): boolean;
-/** Synthetic user id for DB rows created by gateway-driven fulfillment. */
+/** Synthetic user id for DB rows created by fulfillment traffic. */
 declare const FORGE_GATEWAY_USER_ID = "forge_gateway_agent";
-declare function requireForgeGateway(secret?: string | null): (req: Request, res: Response, next: NextFunction) => void;
 /** Headers merchant execute() should send on loopback calls during fulfillment. */
 declare function forgeGatewayLoopbackHeaders(secret?: string | null): Record<string, string>;
 
-export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, FORGE_GATEWAY_USER_ID, type ForgeHeartbeatState, type ForgePayToSource, type ForgeSurfaceStatus, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, PublicBaseUrlResolver, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, buildForgeSurfaceStatus, buildWellKnownDocument, createContext, createForgeRouter, defineAgentService, forgeGatewayLoopbackHeaders, forgeSdkVersion, generateSkillMarkdown, getForgeApiKey, getForgeGatewaySecret, getLastHeartbeat, heartbeatGateway, isForgeGatewayRequest, isZeroAddress, mountAgentServices, recordHeartbeatResult, requireForgeGateway, resolveBaseUrlFromEnv, resolvePayTo, toKebabCase, waitUntil };
+export { type AgentServiceConfig, type AgentServiceContext, type DefinedAgentService, FORGE_GATEWAY_USER_ID, type ForgeFetchHandler, type ForgeHandlerOptions, type ForgeSurfaceStatus, type ForgeWorkerHandle, type ForgeWorkerOptions, type InputSchema, type OutputSchema, type PaymentConfig, type SchemaFieldType, type ValidationResult, type WaitUntilOptions, buildForgeSurfaceStatus, buildWellKnownDocument, checkType, createContext, createForgeHandler, createForgeRequestMatcher, defineAgentService, forgeGatewayLoopbackHeaders, forgeSdkVersion, forgeWorker, getForgeApiKey, toKebabCase, validateInput, waitUntil };