@clawcash/forge 0.1.5 → 0.1.8

package/dist/index.d.cts

@@ -72,14 +72,19 @@ interface MountOptions {
     /** 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 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 for fulfillment. */
+        /** Merchant public base URL. Usually omitted — resolved automatically. */
         publicBaseUrl?: string;
     };
     /**
@@ -103,6 +108,7 @@ declare function defineAgentService<TInput extends Record<string, unknown> = Rec
 
 /**
  * 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
  *
@@ -133,6 +139,42 @@ declare function resolvePayTo(opts: {
     timeoutMs?: number;
 }): Promise<string>;
 
+/**
+ * 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.
+ */
+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;
+}
+
 /**
  * Notify ClawCash gateway of this merchant's live public base URL.
  * Full action registration still happens from Forge "Go live".
@@ -145,9 +187,82 @@ declare function heartbeatGateway(opts: {
 }): Promise<void>;
 
 /**
- * Shared secret auth for ClawCash gateway → merchant fulfillment.
- * Same secret as GATEWAY_REGISTER_SECRET (Forge go-live / heartbeat).
+ * Merchant-side Forge surface status — public probes for deploy / go-live checks.
+ */
+type ForgeHeartbeatState = {
+    attempted: boolean;
+    ok: boolean | null;
+    at: string | null;
+    error: string | null;
+};
+type ForgeSurfaceStatus = {
+    ok: boolean;
+    forge: true;
+    version: string;
+    handle: string | null;
+    publicBaseUrl: string | null;
+    gatewayUrl: string | null;
+    /** True when FORGE_API_KEY is set so /forge/fulfill is mounted. */
+    fulfillMounted: boolean;
+    fulfillPath: string;
+    agentBasePath: string;
+    skipPayment: boolean;
+    actions: Array<{
+        name: string;
+        path: string;
+        price: string;
+    }>;
+    /** Env + fulfill ready — 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;
+        price: string;
+    }>;
+}): ForgeSurfaceStatus;
+declare function buildWellKnownDocument(status: ForgeSurfaceStatus): {
+    forge: true;
+    version: string;
+    health: string;
+    status: string;
+    handle: string | null;
+    ready: boolean;
+};
+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).
+ *
+ * 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. */
@@ -156,4 +271,4 @@ declare function requireForgeGateway(secret?: string | null): (req: Request, res
 /** 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 ForgePayToSource, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, forgeGatewayLoopbackHeaders, generateSkillMarkdown, getForgeGatewaySecret, heartbeatGateway, isForgeGatewayRequest, isZeroAddress, mountAgentServices, requireForgeGateway, resolvePayTo, toKebabCase, waitUntil };
+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 };

package/dist/index.d.ts

@@ -72,14 +72,19 @@ interface MountOptions {
     /** 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 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 for fulfillment. */
+        /** Merchant public base URL. Usually omitted — resolved automatically. */
         publicBaseUrl?: string;
     };
     /**
@@ -103,6 +108,7 @@ declare function defineAgentService<TInput extends Record<string, unknown> = Rec
 
 /**
  * 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
  *
@@ -133,6 +139,42 @@ declare function resolvePayTo(opts: {
     timeoutMs?: number;
 }): Promise<string>;
 
+/**
+ * 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.
+ */
+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;
+}
+
 /**
  * Notify ClawCash gateway of this merchant's live public base URL.
  * Full action registration still happens from Forge "Go live".
@@ -145,9 +187,82 @@ declare function heartbeatGateway(opts: {
 }): Promise<void>;
 
 /**
- * Shared secret auth for ClawCash gateway → merchant fulfillment.
- * Same secret as GATEWAY_REGISTER_SECRET (Forge go-live / heartbeat).
+ * Merchant-side Forge surface status — public probes for deploy / go-live checks.
+ */
+type ForgeHeartbeatState = {
+    attempted: boolean;
+    ok: boolean | null;
+    at: string | null;
+    error: string | null;
+};
+type ForgeSurfaceStatus = {
+    ok: boolean;
+    forge: true;
+    version: string;
+    handle: string | null;
+    publicBaseUrl: string | null;
+    gatewayUrl: string | null;
+    /** True when FORGE_API_KEY is set so /forge/fulfill is mounted. */
+    fulfillMounted: boolean;
+    fulfillPath: string;
+    agentBasePath: string;
+    skipPayment: boolean;
+    actions: Array<{
+        name: string;
+        path: string;
+        price: string;
+    }>;
+    /** Env + fulfill ready — 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;
+        price: string;
+    }>;
+}): ForgeSurfaceStatus;
+declare function buildWellKnownDocument(status: ForgeSurfaceStatus): {
+    forge: true;
+    version: string;
+    health: string;
+    status: string;
+    handle: string | null;
+    ready: boolean;
+};
+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).
+ *
+ * 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. */
@@ -156,4 +271,4 @@ declare function requireForgeGateway(secret?: string | null): (req: Request, res
 /** 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 ForgePayToSource, type InputSchema, type MountOptions, type OutputSchema, type PaymentConfig, type SchemaFieldType, type SkillMeta, type WaitUntilOptions, createContext, createForgeRouter, defineAgentService, forgeGatewayLoopbackHeaders, generateSkillMarkdown, getForgeGatewaySecret, heartbeatGateway, isForgeGatewayRequest, isZeroAddress, mountAgentServices, requireForgeGateway, resolvePayTo, toKebabCase, waitUntil };
+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 };