@clawcash/forge 0.1.7 → 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,69 +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;
-    /**
-     * Optional gateway heartbeat after mount.
-     * Prefer env: GATEWAY_URL, FORGE_HANDLE, FORGE_API_KEY, PUBLIC_BASE_URL.
-     */
-    gateway?: {
-        url?: string;
-        handle?: string;
-        /** @deprecated Prefer FORGE_API_KEY env — per-project key from Forge dashboard. */
-        registerSecret?: string;
-        /** Merchant public base URL for fulfillment. */
-        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;
@@ -102,59 +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>;
+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;
 
 /**
- * Generate a SKILL.md document for agents from defined Forge services.
+ * 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 generateSkillMarkdown(services: DefinedAgentService[], meta: SkillMeta): string;
-
-declare function isZeroAddress(address: string | undefined | null): boolean;
+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>;
 /**
- * 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
+ * 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 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>;
+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;
@@ -162,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;
@@ -215,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, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, buildForgeSurfaceStatus, buildWellKnownDocument, createContext, createForgeRouter, defineAgentService, forgeGatewayLoopbackHeaders, forgeSdkVersion, generateSkillMarkdown, getForgeApiKey, getForgeGatewaySecret, getLastHeartbeat, heartbeatGateway, isForgeGatewayRequest, isZeroAddress, mountAgentServices, recordHeartbeatResult, requireForgeGateway, 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 };