@useagentpay/sdk 0.1.1 → 0.1.3

package/dist/index.d.cts

@@ -1,3 +1,6 @@
+import { Stagehand } from '@browserbasehq/stagehand';
+import { createServer } from 'node:http';
+
 interface BillingCredentials {
     card: {
         number: string;
@@ -82,15 +85,27 @@ interface ProposeOptions {
     url: string;
 }
 
+/**
+ * Abstraction over how a Stagehand browser instance is created.
+ * Implement this interface to plug in a custom browser backend
+ * (e.g. Browserbase, cloud Playwright, etc.).
+ */
+interface BrowserProvider {
+    createStagehand(modelApiKey?: string): Stagehand;
+    close(): Promise<void>;
+}
+
 interface CheckoutResult {
     success: boolean;
     confirmationId?: string;
     error?: string;
 }
 interface ExecutorConfig {
-    browserbaseApiKey?: string;
-    browserbaseProjectId?: string;
+    /** Custom browser provider. Defaults to LocalBrowserProvider (local Chromium). */
+    provider?: BrowserProvider;
+    /** LLM API key for Stagehand's AI-driven navigation (e.g. ANTHROPIC_API_KEY). */
     modelApiKey?: string;
+    proxyUrl?: string;
 }
 
 declare class NotSetupError extends Error {
@@ -182,6 +197,19 @@ declare class BudgetManager {
     initWallet(budget: number, limitPerTx?: number): void;
 }
 
+interface AgentPayConfig {
+    /** When true, approval links are tunneled via Cloudflare for mobile access */
+    mobileMode: boolean;
+    /** Shell command to send notification. {{url}} is replaced with the approval URL. */
+    notifyCommand?: string;
+    /** Webhook URL to POST approval payload to */
+    notifyWebhook?: string;
+}
+
+declare function loadConfig(home?: string): AgentPayConfig;
+declare function saveConfig(config: AgentPayConfig, home?: string): void;
+declare function setMobileMode(enabled: boolean, home?: string): AgentPayConfig;
+
 declare class TransactionManager {
     private txPath;
     constructor(txPath?: string);
@@ -220,8 +248,11 @@ interface DiscoverResult {
     productName: string;
 }
 declare class PurchaseExecutor {
-    private config;
+    private provider;
+    private modelApiKey?;
     private stagehand;
+    private proxyUrl;
+    private originalBaseUrl;
     constructor(config?: ExecutorConfig);
     private createStagehand;
     /**
@@ -263,6 +294,121 @@ declare const PLACEHOLDER_MAP: {
 declare function getPlaceholderVariables(): Record<string, string>;
 declare function credentialsToSwapMap(creds: BillingCredentials): Record<string, string>;
 
+interface ApprovalResult {
+    action: 'approved' | 'rejected';
+    passphrase?: string;
+    reason?: string;
+}
+/**
+ * Launch an ephemeral HTTP server on localhost, open a browser page
+ * where the human can approve or deny the transaction.
+ * On approve: server-side signing is performed, passphrase returned in result.
+ * On deny: transaction is rejected.
+ */
+declare function requestBrowserApproval(tx: Transaction, tm: TransactionManager, audit: AuditLogger, home?: string): Promise<ApprovalResult>;
+
+interface NotifyOptions {
+    /** Shell command to run. `{{url}}` is replaced with the approval URL. */
+    command?: string;
+    /** Webhook URL to POST `{ url, txId, merchant, amount }` to. */
+    webhookUrl?: string;
+}
+interface NotifyPayload {
+    url: string;
+    txId: string;
+    merchant: string;
+    amount: number;
+}
+/**
+ * Send a notification about a pending mobile approval.
+ *
+ * Supports two delivery methods (both can be used simultaneously):
+ * - `command`: Shell command with `{{url}}` placeholder (e.g. send via iMessage, Telegram, etc.)
+ * - `webhookUrl`: HTTP POST endpoint that receives JSON payload
+ *
+ * Returns an array of results (one per delivery method attempted).
+ */
+declare function sendNotification(payload: NotifyPayload, options: NotifyOptions): Promise<{
+    method: string;
+    success: boolean;
+    error?: string;
+}[]>;
+
+interface MobileApprovalOptions {
+    /** Notification delivery options */
+    notify: NotifyOptions;
+    /** AgentPay home directory */
+    home?: string;
+}
+interface MobileApprovalResult extends ApprovalResult {
+    /** Public URL that was sent to the user */
+    approvalUrl: string;
+    /** Notification delivery results */
+    notifyResults: {
+        method: string;
+        success: boolean;
+        error?: string;
+    }[];
+}
+/**
+ * Request approval via a publicly accessible URL.
+ *
+ * Flow:
+ * 1. Start the local approval server (no browser opened)
+ * 2. Open a tunnel to expose it publicly
+ * 3. Send the tunnel URL to the user via configured notification method
+ * 4. Wait for the user to approve/reject (same as browser flow)
+ * 5. Clean up tunnel when done
+ */
+declare function requestMobileApproval(tx: Transaction, tm: TransactionManager, audit: AuditLogger, options: MobileApprovalOptions): Promise<MobileApprovalResult>;
+
+interface TunnelHandle {
+    url: string;
+    close: () => void;
+}
+/**
+ * Expose a local port via a public HTTPS tunnel using Cloudflare Quick Tunnels.
+ *
+ * Requires `cloudflared` to be installed on the system. No Cloudflare account
+ * needed — quick tunnels generate a random `*.trycloudflare.com` URL.
+ *
+ * The tunnel process is spawned as a child process and killed when `close()` is called.
+ */
+declare function openTunnel(port: number): Promise<TunnelHandle>;
+
+interface SetupResult {
+    completed: boolean;
+}
+/**
+ * Launch an ephemeral HTTP server on localhost, open a browser page
+ * where the human fills in credentials, passphrase, and budget.
+ * All sensitive data stays in the browser->server HTTP request on localhost.
+ * Never touches stdout/terminal.
+ */
+declare function requestBrowserSetup(home?: string): Promise<SetupResult>;
+
+declare function startServer(port: number): Promise<ReturnType<typeof createServer>>;
+
+declare function openBrowser(url: string): void;
+
+interface PassphraseContext {
+    action: 'buy' | 'approve';
+    merchant?: string;
+    amount?: number;
+    description?: string;
+    txId?: string;
+}
+
+declare function promptInput(question: string): Promise<string>;
+declare function promptPassphrase(prompt?: string): Promise<string>;
+declare function promptConfirm(question: string): Promise<boolean>;
+/**
+ * Collect passphrase safely: uses terminal prompt when stdin is a TTY,
+ * otherwise opens a browser page so the human can enter it directly
+ * (keeping the passphrase out of the agent's context).
+ */
+declare function promptPassphraseSafe(context?: PassphraseContext): Promise<string>;
+
 interface AgentPayOptions {
     home?: string;
     passphrase?: string;
@@ -289,13 +435,11 @@ declare class AgentPay {
             limitPerTx: number;
             remaining: number;
         };
-        generateFundingQR: (options?: {
-            suggestedBudget?: number;
-            message?: string;
-        }) => Promise<{
-            url: string;
-            qrDataUrl: string;
-        }>;
+    };
+    get config(): {
+        get: () => AgentPayConfig;
+        setMobileMode: (enabled: boolean) => AgentPayConfig;
+        save: (config: AgentPayConfig) => void;
     };
     get transactions(): {
         propose: (options: ProposeOptions) => Transaction;
@@ -307,6 +451,12 @@ declare class AgentPay {
             status: "approved" | "rejected";
             reason?: string;
         }>;
+        requestApproval: (txId: string) => Promise<{
+            action: "approved" | "rejected";
+            passphrase?: string;
+            reason?: string;
+        }>;
+        requestMobileApproval: (txId: string, notify: NotifyOptions) => Promise<MobileApprovalResult>;
         execute: (txId: string) => Promise<Receipt>;
         getReceipt: (txId: string) => Receipt | undefined;
     };
@@ -320,9 +470,10 @@ declare class AgentPay {
         pending: Transaction[];
         recent: Transaction[];
         isSetup: boolean;
+        mobileMode: boolean;
     };
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION: string;
 
-export { AgentPay, type AgentPayOptions, AlreadyExecutedError, AuditLogger, type BillingCredentials, BudgetManager, CheckoutFailedError, type CheckoutResult, DecryptError, type EncryptedVault, ExceedsTxLimitError, type ExecutorConfig, InsufficientBalanceError, InvalidMandateError, type KeyPair, NotApprovedError, NotSetupError, PLACEHOLDER_MAP, type ProposeOptions, PurchaseExecutor, type PurchaseMandate, type Receipt, TimeoutError, type Transaction, type TransactionDetails, TransactionManager, type TransactionStatus, VERSION, type Wallet, createMandate, credentialsToSwapMap, decrypt, encrypt, formatCurrency, formatStatus, formatTable, formatTimestamp, generateKeyPair, generateTxId, getAuditPath, getCredentialsPath, getHomePath, getKeysPath, getPlaceholderVariables, getTransactionsPath, getWalletPath, loadPrivateKey, loadPublicKey, loadVault, saveKeyPair, saveVault, verifyMandate, waitForApproval };
+export { AgentPay, type AgentPayConfig, type AgentPayOptions, AlreadyExecutedError, type ApprovalResult, AuditLogger, type BillingCredentials, type BrowserProvider, BudgetManager, CheckoutFailedError, type CheckoutResult, DecryptError, type EncryptedVault, ExceedsTxLimitError, type ExecutorConfig, InsufficientBalanceError, InvalidMandateError, type KeyPair, type MobileApprovalOptions, type MobileApprovalResult, NotApprovedError, NotSetupError, type NotifyOptions, type NotifyPayload, PLACEHOLDER_MAP, type ProposeOptions, PurchaseExecutor, type PurchaseMandate, type Receipt, type SetupResult, TimeoutError, type Transaction, type TransactionDetails, TransactionManager, type TransactionStatus, type TunnelHandle, VERSION, type Wallet, createMandate, credentialsToSwapMap, decrypt, encrypt, formatCurrency, formatStatus, formatTable, formatTimestamp, generateKeyPair, generateTxId, getAuditPath, getCredentialsPath, getHomePath, getKeysPath, getPlaceholderVariables, getTransactionsPath, getWalletPath, loadConfig, loadPrivateKey, loadPublicKey, loadVault, openBrowser, openTunnel, promptConfirm, promptInput, promptPassphrase, promptPassphraseSafe, requestBrowserApproval, requestBrowserSetup, requestMobileApproval, saveConfig, saveKeyPair, saveVault, sendNotification, setMobileMode, startServer as startDashboardServer, verifyMandate, waitForApproval };

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { Stagehand } from '@browserbasehq/stagehand';
+import { createServer } from 'node:http';
+
 interface BillingCredentials {
     card: {
         number: string;
@@ -82,15 +85,27 @@ interface ProposeOptions {
     url: string;
 }
 
+/**
+ * Abstraction over how a Stagehand browser instance is created.
+ * Implement this interface to plug in a custom browser backend
+ * (e.g. Browserbase, cloud Playwright, etc.).
+ */
+interface BrowserProvider {
+    createStagehand(modelApiKey?: string): Stagehand;
+    close(): Promise<void>;
+}
+
 interface CheckoutResult {
     success: boolean;
     confirmationId?: string;
     error?: string;
 }
 interface ExecutorConfig {
-    browserbaseApiKey?: string;
-    browserbaseProjectId?: string;
+    /** Custom browser provider. Defaults to LocalBrowserProvider (local Chromium). */
+    provider?: BrowserProvider;
+    /** LLM API key for Stagehand's AI-driven navigation (e.g. ANTHROPIC_API_KEY). */
     modelApiKey?: string;
+    proxyUrl?: string;
 }
 
 declare class NotSetupError extends Error {
@@ -182,6 +197,19 @@ declare class BudgetManager {
     initWallet(budget: number, limitPerTx?: number): void;
 }
 
+interface AgentPayConfig {
+    /** When true, approval links are tunneled via Cloudflare for mobile access */
+    mobileMode: boolean;
+    /** Shell command to send notification. {{url}} is replaced with the approval URL. */
+    notifyCommand?: string;
+    /** Webhook URL to POST approval payload to */
+    notifyWebhook?: string;
+}
+
+declare function loadConfig(home?: string): AgentPayConfig;
+declare function saveConfig(config: AgentPayConfig, home?: string): void;
+declare function setMobileMode(enabled: boolean, home?: string): AgentPayConfig;
+
 declare class TransactionManager {
     private txPath;
     constructor(txPath?: string);
@@ -220,8 +248,11 @@ interface DiscoverResult {
     productName: string;
 }
 declare class PurchaseExecutor {
-    private config;
+    private provider;
+    private modelApiKey?;
     private stagehand;
+    private proxyUrl;
+    private originalBaseUrl;
     constructor(config?: ExecutorConfig);
     private createStagehand;
     /**
@@ -263,6 +294,121 @@ declare const PLACEHOLDER_MAP: {
 declare function getPlaceholderVariables(): Record<string, string>;
 declare function credentialsToSwapMap(creds: BillingCredentials): Record<string, string>;
 
+interface ApprovalResult {
+    action: 'approved' | 'rejected';
+    passphrase?: string;
+    reason?: string;
+}
+/**
+ * Launch an ephemeral HTTP server on localhost, open a browser page
+ * where the human can approve or deny the transaction.
+ * On approve: server-side signing is performed, passphrase returned in result.
+ * On deny: transaction is rejected.
+ */
+declare function requestBrowserApproval(tx: Transaction, tm: TransactionManager, audit: AuditLogger, home?: string): Promise<ApprovalResult>;
+
+interface NotifyOptions {
+    /** Shell command to run. `{{url}}` is replaced with the approval URL. */
+    command?: string;
+    /** Webhook URL to POST `{ url, txId, merchant, amount }` to. */
+    webhookUrl?: string;
+}
+interface NotifyPayload {
+    url: string;
+    txId: string;
+    merchant: string;
+    amount: number;
+}
+/**
+ * Send a notification about a pending mobile approval.
+ *
+ * Supports two delivery methods (both can be used simultaneously):
+ * - `command`: Shell command with `{{url}}` placeholder (e.g. send via iMessage, Telegram, etc.)
+ * - `webhookUrl`: HTTP POST endpoint that receives JSON payload
+ *
+ * Returns an array of results (one per delivery method attempted).
+ */
+declare function sendNotification(payload: NotifyPayload, options: NotifyOptions): Promise<{
+    method: string;
+    success: boolean;
+    error?: string;
+}[]>;
+
+interface MobileApprovalOptions {
+    /** Notification delivery options */
+    notify: NotifyOptions;
+    /** AgentPay home directory */
+    home?: string;
+}
+interface MobileApprovalResult extends ApprovalResult {
+    /** Public URL that was sent to the user */
+    approvalUrl: string;
+    /** Notification delivery results */
+    notifyResults: {
+        method: string;
+        success: boolean;
+        error?: string;
+    }[];
+}
+/**
+ * Request approval via a publicly accessible URL.
+ *
+ * Flow:
+ * 1. Start the local approval server (no browser opened)
+ * 2. Open a tunnel to expose it publicly
+ * 3. Send the tunnel URL to the user via configured notification method
+ * 4. Wait for the user to approve/reject (same as browser flow)
+ * 5. Clean up tunnel when done
+ */
+declare function requestMobileApproval(tx: Transaction, tm: TransactionManager, audit: AuditLogger, options: MobileApprovalOptions): Promise<MobileApprovalResult>;
+
+interface TunnelHandle {
+    url: string;
+    close: () => void;
+}
+/**
+ * Expose a local port via a public HTTPS tunnel using Cloudflare Quick Tunnels.
+ *
+ * Requires `cloudflared` to be installed on the system. No Cloudflare account
+ * needed — quick tunnels generate a random `*.trycloudflare.com` URL.
+ *
+ * The tunnel process is spawned as a child process and killed when `close()` is called.
+ */
+declare function openTunnel(port: number): Promise<TunnelHandle>;
+
+interface SetupResult {
+    completed: boolean;
+}
+/**
+ * Launch an ephemeral HTTP server on localhost, open a browser page
+ * where the human fills in credentials, passphrase, and budget.
+ * All sensitive data stays in the browser->server HTTP request on localhost.
+ * Never touches stdout/terminal.
+ */
+declare function requestBrowserSetup(home?: string): Promise<SetupResult>;
+
+declare function startServer(port: number): Promise<ReturnType<typeof createServer>>;
+
+declare function openBrowser(url: string): void;
+
+interface PassphraseContext {
+    action: 'buy' | 'approve';
+    merchant?: string;
+    amount?: number;
+    description?: string;
+    txId?: string;
+}
+
+declare function promptInput(question: string): Promise<string>;
+declare function promptPassphrase(prompt?: string): Promise<string>;
+declare function promptConfirm(question: string): Promise<boolean>;
+/**
+ * Collect passphrase safely: uses terminal prompt when stdin is a TTY,
+ * otherwise opens a browser page so the human can enter it directly
+ * (keeping the passphrase out of the agent's context).
+ */
+declare function promptPassphraseSafe(context?: PassphraseContext): Promise<string>;
+
 interface AgentPayOptions {
     home?: string;
     passphrase?: string;
@@ -289,13 +435,11 @@ declare class AgentPay {
             limitPerTx: number;
             remaining: number;
         };
-        generateFundingQR: (options?: {
-            suggestedBudget?: number;
-            message?: string;
-        }) => Promise<{
-            url: string;
-            qrDataUrl: string;
-        }>;
+    };
+    get config(): {
+        get: () => AgentPayConfig;
+        setMobileMode: (enabled: boolean) => AgentPayConfig;
+        save: (config: AgentPayConfig) => void;
     };
     get transactions(): {
         propose: (options: ProposeOptions) => Transaction;
@@ -307,6 +451,12 @@ declare class AgentPay {
             status: "approved" | "rejected";
             reason?: string;
         }>;
+        requestApproval: (txId: string) => Promise<{
+            action: "approved" | "rejected";
+            passphrase?: string;
+            reason?: string;
+        }>;
+        requestMobileApproval: (txId: string, notify: NotifyOptions) => Promise<MobileApprovalResult>;
         execute: (txId: string) => Promise<Receipt>;
         getReceipt: (txId: string) => Receipt | undefined;
     };
@@ -320,9 +470,10 @@ declare class AgentPay {
         pending: Transaction[];
         recent: Transaction[];
         isSetup: boolean;
+        mobileMode: boolean;
     };
 }
 
-declare const VERSION = "0.1.0";
+declare const VERSION: string;
 
-export { AgentPay, type AgentPayOptions, AlreadyExecutedError, AuditLogger, type BillingCredentials, BudgetManager, CheckoutFailedError, type CheckoutResult, DecryptError, type EncryptedVault, ExceedsTxLimitError, type ExecutorConfig, InsufficientBalanceError, InvalidMandateError, type KeyPair, NotApprovedError, NotSetupError, PLACEHOLDER_MAP, type ProposeOptions, PurchaseExecutor, type PurchaseMandate, type Receipt, TimeoutError, type Transaction, type TransactionDetails, TransactionManager, type TransactionStatus, VERSION, type Wallet, createMandate, credentialsToSwapMap, decrypt, encrypt, formatCurrency, formatStatus, formatTable, formatTimestamp, generateKeyPair, generateTxId, getAuditPath, getCredentialsPath, getHomePath, getKeysPath, getPlaceholderVariables, getTransactionsPath, getWalletPath, loadPrivateKey, loadPublicKey, loadVault, saveKeyPair, saveVault, verifyMandate, waitForApproval };
+export { AgentPay, type AgentPayConfig, type AgentPayOptions, AlreadyExecutedError, type ApprovalResult, AuditLogger, type BillingCredentials, type BrowserProvider, BudgetManager, CheckoutFailedError, type CheckoutResult, DecryptError, type EncryptedVault, ExceedsTxLimitError, type ExecutorConfig, InsufficientBalanceError, InvalidMandateError, type KeyPair, type MobileApprovalOptions, type MobileApprovalResult, NotApprovedError, NotSetupError, type NotifyOptions, type NotifyPayload, PLACEHOLDER_MAP, type ProposeOptions, PurchaseExecutor, type PurchaseMandate, type Receipt, type SetupResult, TimeoutError, type Transaction, type TransactionDetails, TransactionManager, type TransactionStatus, type TunnelHandle, VERSION, type Wallet, createMandate, credentialsToSwapMap, decrypt, encrypt, formatCurrency, formatStatus, formatTable, formatTimestamp, generateKeyPair, generateTxId, getAuditPath, getCredentialsPath, getHomePath, getKeysPath, getPlaceholderVariables, getTransactionsPath, getWalletPath, loadConfig, loadPrivateKey, loadPublicKey, loadVault, openBrowser, openTunnel, promptConfirm, promptInput, promptPassphrase, promptPassphraseSafe, requestBrowserApproval, requestBrowserSetup, requestMobileApproval, saveConfig, saveKeyPair, saveVault, sendNotification, setMobileMode, startServer as startDashboardServer, verifyMandate, waitForApproval };