mnemospark 0.1.2

package/dist/index.d.ts

@@ -0,0 +1,595 @@
+/**
+ * OpenClaw Plugin Types (locally defined)
+ *
+ * OpenClaw's plugin SDK uses duck typing — these match the shapes
+ * expected by registerProvider() and the plugin system.
+ * Defined locally to avoid depending on internal OpenClaw paths.
+ */
+type ModelApi = "openai-completions" | "openai-responses" | "anthropic-messages" | "google-generative-ai" | "github-copilot" | "bedrock-converse-stream";
+type ModelDefinitionConfig = {
+    id: string;
+    name: string;
+    api?: ModelApi;
+    reasoning: boolean;
+    input: Array<"text" | "image">;
+    cost: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    contextWindow: number;
+    maxTokens: number;
+    headers?: Record<string, string>;
+};
+type ModelProviderConfig = {
+    baseUrl: string;
+    apiKey?: string;
+    api?: ModelApi;
+    headers?: Record<string, string>;
+    authHeader?: boolean;
+    models: ModelDefinitionConfig[];
+};
+type AuthProfileCredential = {
+    apiKey?: string;
+    type?: string;
+    [key: string]: unknown;
+};
+type ProviderAuthResult = {
+    profiles: Array<{
+        profileId: string;
+        credential: AuthProfileCredential;
+    }>;
+    configPatch?: Record<string, unknown>;
+    defaultModel?: string;
+    notes?: string[];
+};
+type WizardPrompter = {
+    text: (opts: {
+        message: string;
+        validate?: (value: string) => string | undefined;
+    }) => Promise<string | symbol>;
+    note: (message: string) => void;
+    progress: (message: string) => {
+        stop: (message?: string) => void;
+    };
+};
+type ProviderAuthContext = {
+    config: Record<string, unknown>;
+    agentDir?: string;
+    workspaceDir?: string;
+    prompter: WizardPrompter;
+    runtime: {
+        log: (message: string) => void;
+    };
+    isRemote: boolean;
+    openUrl: (url: string) => Promise<void>;
+};
+type ProviderAuthMethod = {
+    id: string;
+    label: string;
+    hint?: string;
+    kind: "oauth" | "api_key" | "token" | "device_code" | "custom";
+    run: (ctx: ProviderAuthContext) => Promise<ProviderAuthResult>;
+};
+type ProviderPlugin = {
+    id: string;
+    label: string;
+    docsPath?: string;
+    aliases?: string[];
+    envVars?: string[];
+    models?: ModelProviderConfig;
+    auth: ProviderAuthMethod[];
+    formatApiKey?: (cred: AuthProfileCredential) => string;
+};
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type OpenClawPluginService = {
+    id: string;
+    start: () => void | Promise<void>;
+    stop?: () => void | Promise<void>;
+};
+type OpenClawPluginApi = {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    source: string;
+    config: Record<string, unknown> & {
+        models?: {
+            providers?: Record<string, ModelProviderConfig>;
+        };
+        agents?: Record<string, unknown>;
+    };
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerProvider: (provider: ProviderPlugin) => void;
+    registerTool: (tool: unknown, opts?: unknown) => void;
+    registerHook: (events: string | string[], handler: unknown, opts?: unknown) => void;
+    registerHttpRoute: (params: {
+        path: string;
+        handler: unknown;
+    }) => void;
+    registerService: (service: OpenClawPluginService) => void;
+    registerCommand: (command: unknown) => void;
+    resolvePath: (input: string) => string;
+    on: (hookName: string, handler: unknown, opts?: unknown) => void;
+};
+type OpenClawPluginDefinition = {
+    id?: string;
+    name?: string;
+    description?: string;
+    version?: string;
+    register?: (api: OpenClawPluginApi) => void | Promise<void>;
+    activate?: (api: OpenClawPluginApi) => void | Promise<void>;
+};
+type PluginCommandContext = {
+    senderId?: string;
+    channel: string;
+    isAuthorizedSender: boolean;
+    args?: string;
+    commandBody: string;
+    config: Record<string, unknown>;
+};
+type PluginCommandResult = {
+    text?: string;
+    isError?: boolean;
+};
+type PluginCommandHandler = (ctx: PluginCommandContext) => PluginCommandResult | Promise<PluginCommandResult>;
+type OpenClawPluginCommandDefinition = {
+    name: string;
+    description: string;
+    acceptsArgs?: boolean;
+    requireAuth?: boolean;
+    handler: PluginCommandHandler;
+};
+
+/**
+ * Balance Monitor for ClawRouter
+ *
+ * Monitors USDC balance on Base network with intelligent caching.
+ * Provides pre-request balance checks to prevent failed payments.
+ *
+ * Caching Strategy:
+ *   - TTL: 30 seconds (balance is cached to avoid excessive RPC calls)
+ *   - Optimistic deduction: after successful payment, subtract estimated cost from cache
+ *   - Invalidation: on payment failure, immediately refresh from RPC
+ */
+/** Balance thresholds in USDC smallest unit (6 decimals) */
+declare const BALANCE_THRESHOLDS: {
+    /** Low balance warning threshold: $1.00 */
+    readonly LOW_BALANCE_MICROS: 1000000n;
+    /** Effectively zero threshold: $0.0001 (covers dust/rounding) */
+    readonly ZERO_THRESHOLD: 100n;
+};
+/** Balance information returned by checkBalance() */
+type BalanceInfo = {
+    /** Raw balance in USDC smallest unit (6 decimals) */
+    balance: bigint;
+    /** Formatted balance as "$X.XX" */
+    balanceUSD: string;
+    /** True if balance < $1.00 */
+    isLow: boolean;
+    /** True if balance < $0.0001 (effectively zero) */
+    isEmpty: boolean;
+    /** Wallet address for funding instructions */
+    walletAddress: string;
+};
+/** Result from checkSufficient() */
+type SufficiencyResult = {
+    /** True if balance >= estimated cost */
+    sufficient: boolean;
+    /** Current balance info */
+    info: BalanceInfo;
+    /** If insufficient, the shortfall as "$X.XX" */
+    shortfall?: string;
+};
+/**
+ * Monitors USDC balance on Base network.
+ *
+ * Usage:
+ *   const monitor = new BalanceMonitor("0x...");
+ *   const info = await monitor.checkBalance();
+ *   if (info.isLow) console.warn("Low balance!");
+ */
+declare class BalanceMonitor {
+    private readonly client;
+    private readonly walletAddress;
+    /** Cached balance (null = not yet fetched) */
+    private cachedBalance;
+    /** Timestamp when cache was last updated */
+    private cachedAt;
+    constructor(walletAddress: string);
+    /**
+     * Check current USDC balance.
+     * Uses cache if valid, otherwise fetches from RPC.
+     */
+    checkBalance(): Promise<BalanceInfo>;
+    /**
+     * Check if balance is sufficient for an estimated cost.
+     *
+     * @param estimatedCostMicros - Estimated cost in USDC smallest unit (6 decimals)
+     */
+    checkSufficient(estimatedCostMicros: bigint): Promise<SufficiencyResult>;
+    /**
+     * Optimistically deduct estimated cost from cached balance.
+     * Call this after a successful payment to keep cache accurate.
+     *
+     * @param amountMicros - Amount to deduct in USDC smallest unit
+     */
+    deductEstimated(amountMicros: bigint): void;
+    /**
+     * Invalidate cache, forcing next checkBalance() to fetch from RPC.
+     * Call this after a payment failure to get accurate balance.
+     */
+    invalidate(): void;
+    /**
+     * Force refresh balance from RPC (ignores cache).
+     */
+    refresh(): Promise<BalanceInfo>;
+    /**
+     * Format USDC amount (in micros) as "$X.XX".
+     */
+    formatUSDC(amountMicros: bigint): string;
+    /**
+     * Get the wallet address being monitored.
+     */
+    getWalletAddress(): string;
+    /** Fetch balance from RPC */
+    private fetchBalance;
+    /** Build BalanceInfo from raw balance */
+    private buildInfo;
+}
+
+/**
+ * Local mnemospark proxy server.
+ *
+ * This proxy only forwards mnemospark storage endpoints to the backend API and
+ * serves health checks. It does not handle chat completions or model routing.
+ */
+
+/**
+ * Get the proxy port from pre-loaded configuration.
+ * Port is validated at module load time, this just returns the cached value.
+ */
+declare function getProxyPort(): number;
+/** Callback info for low balance warning */
+type LowBalanceInfo = {
+    balanceUSD: string;
+    walletAddress: string;
+};
+/** Callback info for insufficient funds error */
+type InsufficientFundsInfo = {
+    balanceUSD: string;
+    requiredUSD: string;
+    walletAddress: string;
+};
+type ProxyOptions = {
+    walletKey: string;
+    /** Port to listen on (default: 7120) */
+    port?: number;
+    onReady?: (port: number) => void;
+    onError?: (error: Error) => void;
+    /** Called when balance drops below $1.00 (warning, request still proceeds) */
+    onLowBalance?: (info: LowBalanceInfo) => void;
+    /** Called when balance is insufficient for a request (request fails) */
+    onInsufficientFunds?: (info: InsufficientFundsInfo) => void;
+};
+type ProxyHandle = {
+    port: number;
+    baseUrl: string;
+    walletAddress: string;
+    balanceMonitor: BalanceMonitor;
+    close: () => Promise<void>;
+};
+/**
+ * Start the local mnemospark backend proxy server.
+ *
+ * If a proxy is already running on the target port, reuses it instead of failing.
+ * Port can be configured via MNEMOSPARK_PROXY_PORT environment variable.
+ *
+ * Returns a handle with the assigned port, base URL, and a close function.
+ */
+declare function startProxy(options: ProxyOptions): Promise<ProxyHandle>;
+
+/**
+ * Payment Parameter Cache
+ *
+ * Caches the 402 payment parameters (payTo, asset, network, etc.) after the first
+ * request to each endpoint. On subsequent requests, pre-signs the payment and
+ * attaches it to the first request, skipping the 402 round trip (~200ms savings).
+ */
+type CachedPaymentParams = {
+    payTo: string;
+    asset: string;
+    scheme: string;
+    network: string;
+    extra?: {
+        name?: string;
+        version?: string;
+    };
+    maxTimeoutSeconds?: number;
+    resourceUrl?: string;
+    resourceDescription?: string;
+    cachedAt: number;
+};
+declare class PaymentCache {
+    private cache;
+    private ttlMs;
+    constructor(ttlMs?: number);
+    /** Get cached payment params for an endpoint path. */
+    get(endpointPath: string): CachedPaymentParams | undefined;
+    /** Cache payment params from a 402 response. */
+    set(endpointPath: string, params: Omit<CachedPaymentParams, "cachedAt">): void;
+    /** Invalidate cache for an endpoint (e.g., if payTo changed). */
+    invalidate(endpointPath: string): void;
+}
+
+/**
+ * x402 Payment Implementation
+ *
+ * Based on BlockRun's proven implementation.
+ * Handles 402 Payment Required responses with EIP-712 signed USDC transfers.
+ *
+ * Optimizations (v0.3.0):
+ *   - Payment cache: after first 402, caches {payTo, asset, network} per endpoint.
+ *     On subsequent requests, pre-signs payment and sends with first request,
+ *     skipping the 402 round trip (~200ms savings).
+ *   - Falls back to normal 402 flow if pre-signed payment is rejected.
+ */
+
+/** Pre-auth parameters for skipping the 402 round trip. */
+type PreAuthParams = {
+    estimatedAmount: string;
+};
+/** Result from createPaymentFetch — includes the fetch wrapper and payment cache. */
+type PaymentFetchResult = {
+    fetch: (input: RequestInfo | URL, init?: RequestInit, preAuth?: PreAuthParams) => Promise<Response>;
+    cache: PaymentCache;
+};
+/**
+ * Create a fetch wrapper that handles x402 payment automatically.
+ *
+ * Supports pre-auth: if cached payment params + estimated amount are available,
+ * pre-signs and attaches payment to the first request, skipping the 402 round trip.
+ * Falls back to normal 402 flow if pre-signed payment is rejected.
+ */
+declare function createPaymentFetch(privateKey: `0x${string}`): PaymentFetchResult;
+
+/**
+ * Typed Error Classes for mnemospark
+ *
+ * Provides structured errors for balance-related failures with
+ * all necessary information for user-friendly error messages.
+ */
+/**
+ * Thrown when wallet has insufficient USDC balance for a request.
+ */
+declare class InsufficientFundsError extends Error {
+    readonly code: "INSUFFICIENT_FUNDS";
+    readonly currentBalanceUSD: string;
+    readonly requiredUSD: string;
+    readonly walletAddress: string;
+    constructor(opts: {
+        currentBalanceUSD: string;
+        requiredUSD: string;
+        walletAddress: string;
+    });
+}
+/**
+ * Thrown when wallet has no USDC balance (or effectively zero).
+ */
+declare class EmptyWalletError extends Error {
+    readonly code: "EMPTY_WALLET";
+    readonly walletAddress: string;
+    constructor(walletAddress: string);
+}
+/**
+ * Type guard to check if an error is InsufficientFundsError.
+ */
+declare function isInsufficientFundsError(error: unknown): error is InsufficientFundsError;
+/**
+ * Type guard to check if an error is EmptyWalletError.
+ */
+declare function isEmptyWalletError(error: unknown): error is EmptyWalletError;
+/**
+ * Type guard to check if an error is a balance-related error.
+ */
+declare function isBalanceError(error: unknown): error is InsufficientFundsError | EmptyWalletError;
+/**
+ * Thrown when RPC call fails (network error, node down, etc).
+ * Distinguishes infrastructure failures from actual empty wallets.
+ */
+declare class RpcError extends Error {
+    readonly code: "RPC_ERROR";
+    readonly originalError: unknown;
+    constructor(message: string, originalError?: unknown);
+}
+/**
+ * Type guard to check if an error is RpcError.
+ */
+declare function isRpcError(error: unknown): error is RpcError;
+
+/**
+ * Retry Logic for mnemospark
+ *
+ * Provides fetch wrapper with exponential backoff for transient errors.
+ * Retries on 429 (rate limit), 502, 503, 504 (server errors).
+ */
+/** Configuration for retry behavior */
+type RetryConfig = {
+    /** Maximum number of retries (default: 2) */
+    maxRetries: number;
+    /** Base delay in ms for exponential backoff (default: 500) */
+    baseDelayMs: number;
+    /** HTTP status codes that trigger a retry (default: [429, 502, 503, 504]) */
+    retryableCodes: number[];
+};
+/** Default retry configuration */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Wrap a fetch-like function with retry logic and exponential backoff.
+ *
+ * @param fetchFn - The fetch function to wrap (can be standard fetch or x402 payFetch)
+ * @param url - URL to fetch
+ * @param init - Fetch init options
+ * @param config - Retry configuration (optional, uses defaults)
+ * @returns Response from successful fetch or last failed attempt
+ *
+ * @example
+ * ```typescript
+ * const response = await fetchWithRetry(
+ *   fetch,
+ *   "https://api.example.com/endpoint",
+ *   { method: "POST", body: JSON.stringify(data) },
+ *   { maxRetries: 3 }
+ * );
+ * ```
+ */
+declare function fetchWithRetry(fetchFn: (url: string, init?: RequestInit) => Promise<Response>, url: string, init?: RequestInit, config?: Partial<RetryConfig>): Promise<Response>;
+/**
+ * Check if an error or response indicates a retryable condition.
+ */
+declare function isRetryable(errorOrResponse: Error | Response, config?: Partial<RetryConfig>): boolean;
+
+type PriceStorageQuoteRequest = {
+    wallet_address: string;
+    object_id: string;
+    object_id_hash: string;
+    gb: number;
+    provider: string;
+    region: string;
+};
+type PriceStorageQuoteResponse = {
+    timestamp: string;
+    quote_id: string;
+    storage_price: number;
+    addr: string;
+    object_id: string;
+    object_id_hash: string;
+    object_size_gb: number;
+    provider: string;
+    location: string;
+};
+type UploadPayload = {
+    mode: "inline" | "presigned";
+    content_base64?: string;
+    content_sha256: string;
+    content_length_bytes: number;
+    wrapped_dek: string;
+    encryption_algorithm: "AES-256-GCM";
+    bucket_name_hint: string;
+    key_store_path_hint: string;
+};
+type StorageUploadRequest = {
+    quote_id: string;
+    wallet_address: string;
+    object_id: string;
+    object_id_hash: string;
+    quoted_storage_price: number;
+    payload: UploadPayload;
+};
+type StorageUploadResponse = {
+    quote_id: string;
+    addr: string;
+    addr_hash?: string;
+    trans_id?: string;
+    storage_price?: number;
+    object_id: string;
+    object_key: string;
+    provider: string;
+    bucket_name: string;
+    location: string;
+    upload_url?: string;
+    upload_headers?: Record<string, string>;
+};
+type FetchLike$2 = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type ProxyQuoteOptions = {
+    proxyBaseUrl?: string;
+    fetchImpl?: FetchLike$2;
+};
+type ProxyUploadOptions = {
+    proxyBaseUrl?: string;
+    fetchImpl?: FetchLike$2;
+    idempotencyKey?: string;
+};
+
+type StorageObjectRequest = {
+    wallet_address: string;
+    object_key: string;
+    location?: string;
+};
+type StorageLsResponse = {
+    success: boolean;
+    key: string;
+    size_bytes: number;
+    bucket: string;
+    object_id?: string;
+};
+type StorageDeleteResponse = {
+    success: boolean;
+    key: string;
+    bucket: string;
+    bucket_deleted: boolean;
+};
+type StorageDownloadProxyResponse = {
+    success: boolean;
+    key: string;
+    file_path: string;
+};
+type FetchLike$1 = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type ProxyStorageOptions = {
+    proxyBaseUrl?: string;
+    fetchImpl?: FetchLike$1;
+};
+
+type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+type BackupObjectOptions = {
+    platform?: NodeJS.Platform;
+    tmpDir?: string;
+    homeDir?: string;
+    now?: () => number;
+    randomBytes?: (size: number) => Buffer;
+    availableDiskBytes?: number;
+};
+type BackupObjectResult = {
+    objectId: string;
+    objectIdHash: string;
+    objectSizeGb: string;
+    archivePath: string;
+    objectLogPath: string;
+};
+type CreateCloudCommandOptions = {
+    backupOptions?: BackupObjectOptions;
+    buildBackupObjectFn?: (targetPath: string, options?: BackupObjectOptions) => Promise<BackupObjectResult>;
+    requestPriceStorageQuoteFn?: (request: PriceStorageQuoteRequest, options?: ProxyQuoteOptions) => Promise<PriceStorageQuoteResponse>;
+    requestStorageUploadFn?: (request: StorageUploadRequest, options?: ProxyUploadOptions) => Promise<StorageUploadResponse>;
+    resolveWalletPrivateKeyFn?: (homeDir?: string) => Promise<`0x${string}`>;
+    createPaymentFetchFn?: (privateKey: `0x${string}`) => PaymentFetchResult;
+    fetchImpl?: FetchLike;
+    nowDateFn?: () => Date;
+    idempotencyKeyFn?: () => string;
+    proxyQuoteOptions?: ProxyQuoteOptions;
+    proxyUploadOptions?: ProxyUploadOptions;
+    requestStorageLsFn?: (request: StorageObjectRequest, options?: ProxyStorageOptions) => Promise<StorageLsResponse>;
+    requestStorageDownloadFn?: (request: StorageObjectRequest, options?: ProxyStorageOptions) => Promise<StorageDownloadProxyResponse>;
+    requestStorageDeleteFn?: (request: StorageObjectRequest, options?: ProxyStorageOptions) => Promise<StorageDeleteResponse>;
+    proxyStorageOptions?: ProxyStorageOptions;
+    objectLogHomeDir?: string;
+};
+declare function createCloudCommand(options?: CreateCloudCommandOptions): OpenClawPluginCommandDefinition;
+
+/**
+ * mnemospark plugin entrypoint.
+ *
+ * This plugin provides wallet and cloud storage commands and starts a local
+ * proxy that forwards mnemospark backend storage endpoints.
+ */
+
+declare const plugin: OpenClawPluginDefinition;
+
+export { BALANCE_THRESHOLDS, type BalanceInfo, BalanceMonitor, type CachedPaymentParams, DEFAULT_RETRY_CONFIG, EmptyWalletError, InsufficientFundsError, type InsufficientFundsInfo, type LowBalanceInfo, PaymentCache, type PaymentFetchResult, type PreAuthParams, type ProxyHandle, type ProxyOptions, type RetryConfig, RpcError, type SufficiencyResult, createCloudCommand, createPaymentFetch, plugin as default, fetchWithRetry, getProxyPort, isBalanceError, isEmptyWalletError, isInsufficientFundsError, isRetryable, isRpcError, startProxy };