@useagentpay/sdk 0.1.2 → 0.1.3

package/dist/index.d.cts

@@ -197,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);
@@ -294,6 +307,75 @@ interface ApprovalResult {
  */
 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;
 }
@@ -354,6 +436,11 @@ declare class AgentPay {
             remaining: number;
         };
     };
+    get config(): {
+        get: () => AgentPayConfig;
+        setMobileMode: (enabled: boolean) => AgentPayConfig;
+        save: (config: AgentPayConfig) => void;
+    };
     get transactions(): {
         propose: (options: ProposeOptions) => Transaction;
         get: (txId: string) => Transaction | undefined;
@@ -369,6 +456,7 @@ declare class AgentPay {
             passphrase?: string;
             reason?: string;
         }>;
+        requestMobileApproval: (txId: string, notify: NotifyOptions) => Promise<MobileApprovalResult>;
         execute: (txId: string) => Promise<Receipt>;
         getReceipt: (txId: string) => Receipt | undefined;
     };
@@ -382,9 +470,10 @@ declare class AgentPay {
         pending: Transaction[];
         recent: Transaction[];
         isSetup: boolean;
+        mobileMode: boolean;
     };
 }
 
 declare const VERSION: string;
 
-export { AgentPay, type AgentPayOptions, AlreadyExecutedError, type ApprovalResult, AuditLogger, type BillingCredentials, type BrowserProvider, 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, type SetupResult, 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, openBrowser, promptConfirm, promptInput, promptPassphrase, promptPassphraseSafe, requestBrowserApproval, requestBrowserSetup, saveKeyPair, saveVault, startServer as startDashboardServer, 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

@@ -197,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);
@@ -294,6 +307,75 @@ interface ApprovalResult {
  */
 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;
 }
@@ -354,6 +436,11 @@ declare class AgentPay {
             remaining: number;
         };
     };
+    get config(): {
+        get: () => AgentPayConfig;
+        setMobileMode: (enabled: boolean) => AgentPayConfig;
+        save: (config: AgentPayConfig) => void;
+    };
     get transactions(): {
         propose: (options: ProposeOptions) => Transaction;
         get: (txId: string) => Transaction | undefined;
@@ -369,6 +456,7 @@ declare class AgentPay {
             passphrase?: string;
             reason?: string;
         }>;
+        requestMobileApproval: (txId: string, notify: NotifyOptions) => Promise<MobileApprovalResult>;
         execute: (txId: string) => Promise<Receipt>;
         getReceipt: (txId: string) => Receipt | undefined;
     };
@@ -382,9 +470,10 @@ declare class AgentPay {
         pending: Transaction[];
         recent: Transaction[];
         isSetup: boolean;
+        mobileMode: boolean;
     };
 }
 
 declare const VERSION: string;
 
-export { AgentPay, type AgentPayOptions, AlreadyExecutedError, type ApprovalResult, AuditLogger, type BillingCredentials, type BrowserProvider, 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, type SetupResult, 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, openBrowser, promptConfirm, promptInput, promptPassphrase, promptPassphraseSafe, requestBrowserApproval, requestBrowserSetup, saveKeyPair, saveVault, startServer as startDashboardServer, 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 };