clawdentials-mcp 0.1.0 → 0.7.2

package/dist/services/payments/alby.js

@@ -0,0 +1,239 @@
+/**
+ * Alby Payment Service - Bitcoin on Lightning
+ *
+ * Uses Alby API with Nostr Wallet Connect (NWC) for self-custodial Lightning payments.
+ * Docs: https://guides.getalby.com/developer-guide
+ * Fee: ~0% (just Lightning network fees)
+ */
+// Configuration
+// NWC connection string format: nostr+walletconnect://pubkey?relay=wss://...&secret=...
+const ALBY_NWC_URL = process.env.ALBY_NWC_URL || '';
+const ALBY_WEBHOOK_URL = process.env.ALBY_WEBHOOK_URL || '';
+// Alby API (for account-based operations)
+const ALBY_API_KEY = process.env.ALBY_API_KEY || '';
+const API_BASE = 'https://api.getalby.com';
+// Exchange rate (sats per USD) - in production, fetch from API
+const SATS_PER_USD = parseInt(process.env.ALBY_SATS_PER_USD || '1000', 10);
+/**
+ * Convert USD to sats
+ */
+function usdToSats(usd) {
+    return Math.floor(usd * SATS_PER_USD);
+}
+/**
+ * Convert sats to USD
+ */
+function satsToUsd(sats) {
+    return sats / SATS_PER_USD;
+}
+/**
+ * Make API request to Alby
+ */
+async function apiRequest(endpoint, method = 'POST', data) {
+    if (!ALBY_API_KEY) {
+        throw new Error('ALBY_API_KEY not configured');
+    }
+    const response = await fetch(`${API_BASE}${endpoint}`, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${ALBY_API_KEY}`,
+        },
+        body: data ? JSON.stringify(data) : undefined,
+    });
+    if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Alby API error: ${error}`);
+    }
+    return response.json();
+}
+/**
+ * Create a Lightning invoice for BTC deposit
+ */
+export async function createAlbyDeposit(request) {
+    if (!ALBY_API_KEY) {
+        return {
+            success: false,
+            error: 'ALBY_API_KEY not configured. Get one at https://getalby.com',
+        };
+    }
+    try {
+        const amountSats = usdToSats(request.amount);
+        const result = await apiRequest('/invoices', 'POST', {
+            amount: amountSats,
+            description: request.description || `Clawdentials deposit for ${request.agentId}`,
+            memo: request.agentId, // Store agentId in memo for webhook processing
+        });
+        // Alby invoices expire in 1 hour by default
+        const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
+        return {
+            success: true,
+            deposit: {
+                id: `alby_${result.payment_hash}`,
+                agentId: request.agentId,
+                amount: request.amount,
+                currency: 'BTC',
+                network: 'lightning',
+                status: 'pending',
+                provider: 'alby',
+                externalId: result.payment_hash,
+                paymentAddress: result.payment_request, // bolt11 invoice
+                paymentUrl: null,
+                createdAt: new Date(),
+                expiresAt,
+                completedAt: null,
+                txHash: null,
+            },
+            invoice: {
+                paymentHash: result.payment_hash,
+                paymentRequest: result.payment_request,
+                amountSats,
+                expiresAt,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to create Lightning invoice',
+        };
+    }
+}
+/**
+ * Check invoice status
+ */
+export async function getInvoiceStatus(paymentHash) {
+    if (!ALBY_API_KEY) {
+        return { success: false, error: 'ALBY_API_KEY not configured' };
+    }
+    try {
+        const result = await apiRequest(`/invoices/${paymentHash}`, 'GET');
+        return {
+            success: true,
+            status: result.state, // CREATED, SETTLED, CANCELED
+            paid: result.state === 'SETTLED',
+            amountSats: result.amount,
+            amountUsd: satsToUsd(result.amount),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get invoice status',
+        };
+    }
+}
+/**
+ * Process webhook callback from Alby
+ */
+export function parseWebhookPayload(body) {
+    return {
+        paymentHash: body.payment_hash,
+        status: body.state,
+        amountSats: body.amount,
+        amountUsd: satsToUsd(body.amount),
+        memo: body.memo || body.description || '',
+    };
+}
+/**
+ * Send Lightning payment (for withdrawals)
+ */
+export async function sendAlbyPayment(destination, // Lightning invoice or Lightning Address
+amountUsd) {
+    if (!ALBY_API_KEY) {
+        return { success: false, error: 'ALBY_API_KEY not configured' };
+    }
+    try {
+        // Check if it's a Lightning Address (contains @)
+        if (destination.includes('@')) {
+            // Pay to Lightning Address
+            const amountSats = usdToSats(amountUsd);
+            const result = await apiRequest('/payments/lnaddress', 'POST', {
+                lnaddress: destination,
+                amount: amountSats,
+                comment: 'Clawdentials withdrawal',
+            });
+            return {
+                success: true,
+                paymentHash: result.payment_hash,
+            };
+        }
+        else {
+            // Pay bolt11 invoice directly
+            const result = await apiRequest('/payments/bolt11', 'POST', {
+                invoice: destination,
+            });
+            return {
+                success: true,
+                paymentHash: result.payment_hash,
+            };
+        }
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to send payment',
+        };
+    }
+}
+/**
+ * Get wallet balance
+ */
+export async function getWalletBalance() {
+    if (!ALBY_API_KEY) {
+        return { success: false, error: 'ALBY_API_KEY not configured' };
+    }
+    try {
+        const result = await apiRequest('/balance', 'GET');
+        return {
+            success: true,
+            balanceSats: result.balance,
+            balanceUsd: satsToUsd(result.balance),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get balance',
+        };
+    }
+}
+/**
+ * Decode a Lightning invoice to get amount and details
+ */
+export async function decodeInvoice(invoice) {
+    try {
+        // Use Alby's decode endpoint or a local decoder
+        const result = await apiRequest('/decode/bolt11', 'POST', { invoice });
+        return {
+            success: true,
+            amountSats: result.amount,
+            amountUsd: satsToUsd(result.amount),
+            description: result.description,
+            paymentHash: result.payment_hash,
+            expiresAt: result.expires_at ? new Date(result.expires_at * 1000) : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to decode invoice',
+        };
+    }
+}
+export const albyService = {
+    createDeposit: createAlbyDeposit,
+    getInvoiceStatus,
+    parseWebhookPayload,
+    sendPayment: sendAlbyPayment,
+    getWalletBalance,
+    decodeInvoice,
+    usdToSats,
+    satsToUsd,
+    config: {
+        configured: !!ALBY_API_KEY,
+        nwcConfigured: !!ALBY_NWC_URL,
+        webhookUrl: ALBY_WEBHOOK_URL,
+        satsPerUsd: SATS_PER_USD,
+    },
+};

package/dist/services/payments/breez.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Breez SDK Payment Service - Bitcoin on Lightning (Nodeless/Liquid)
+ *
+ * Uses Breez SDK Liquid for self-custodial Lightning payments.
+ * Docs: https://sdk-doc-liquid.breez.technology/
+ * Fee: Network fees only (no platform fee)
+ *
+ * Requirements:
+ * - Node.js v22+
+ * - Breez API key (free, request at https://breez.technology/sdk/)
+ * - 12-word mnemonic for self-custody
+ */
+import type { Deposit } from '../../types/index.js';
+export interface BreezPaymentRequest {
+    amount: number;
+    agentId: string;
+    description?: string;
+}
+export interface BreezPaymentResponse {
+    success: boolean;
+    deposit?: Partial<Deposit>;
+    invoice?: {
+        bolt11: string;
+        amountSats: number;
+        expiresAt: Date;
+    };
+    error?: string;
+}
+/**
+ * Convert USD to sats
+ */
+declare function usdToSats(usd: number): number;
+/**
+ * Convert sats to USD
+ */
+declare function satsToUsd(sats: number): number;
+/**
+ * Create a Lightning invoice for BTC deposit
+ */
+export declare function createBreezDeposit(request: BreezPaymentRequest): Promise<BreezPaymentResponse>;
+/**
+ * Send Lightning payment (for withdrawals)
+ */
+export declare function sendBreezPayment(destination: string, // bolt11 invoice or Lightning Address
+amountUsd: number): Promise<{
+    success: boolean;
+    txId?: string;
+    error?: string;
+}>;
+/**
+ * Get wallet balance
+ */
+export declare function getWalletBalance(): Promise<{
+    success: boolean;
+    balanceSats?: number;
+    balanceUsd?: number;
+    error?: string;
+}>;
+/**
+ * List recent payments
+ */
+export declare function listPayments(limit?: number): Promise<{
+    success: boolean;
+    payments?: any[];
+    error?: string;
+}>;
+/**
+ * Disconnect from SDK (cleanup)
+ */
+export declare function disconnect(): Promise<void>;
+/**
+ * Generate a new mnemonic (for initial setup)
+ */
+export declare function generateMnemonic(): string;
+export declare const breezService: {
+    createDeposit: typeof createBreezDeposit;
+    sendPayment: typeof sendBreezPayment;
+    getWalletBalance: typeof getWalletBalance;
+    listPayments: typeof listPayments;
+    disconnect: typeof disconnect;
+    usdToSats: typeof usdToSats;
+    satsToUsd: typeof satsToUsd;
+    config: {
+        configured: boolean;
+        apiKeySet: boolean;
+        mnemonicSet: boolean;
+        network: string;
+        satsPerUsd: number;
+    };
+};
+export {};

package/dist/services/payments/breez.js

@@ -0,0 +1,267 @@
+/**
+ * Breez SDK Payment Service - Bitcoin on Lightning (Nodeless/Liquid)
+ *
+ * Uses Breez SDK Liquid for self-custodial Lightning payments.
+ * Docs: https://sdk-doc-liquid.breez.technology/
+ * Fee: Network fees only (no platform fee)
+ *
+ * Requirements:
+ * - Node.js v22+
+ * - Breez API key (free, request at https://breez.technology/sdk/)
+ * - 12-word mnemonic for self-custody
+ */
+// Configuration
+const BREEZ_API_KEY = process.env.BREEZ_API_KEY || '';
+const BREEZ_MNEMONIC = process.env.BREEZ_MNEMONIC || '';
+const BREEZ_WORKING_DIR = process.env.BREEZ_WORKING_DIR || './breez-data';
+const BREEZ_NETWORK = process.env.BREEZ_NETWORK || 'mainnet'; // 'mainnet' or 'testnet'
+// Exchange rate (sats per USD) - in production, fetch from API
+const SATS_PER_USD = parseInt(process.env.BREEZ_SATS_PER_USD || '1000', 10);
+// SDK instance (lazy loaded)
+let sdkInstance = null;
+let sdkInitPromise = null;
+/**
+ * Convert USD to sats
+ */
+function usdToSats(usd) {
+    return Math.floor(usd * SATS_PER_USD);
+}
+/**
+ * Convert sats to USD
+ */
+function satsToUsd(sats) {
+    return sats / SATS_PER_USD;
+}
+/**
+ * Initialize and connect to Breez SDK
+ */
+async function getSDK() {
+    if (sdkInstance) {
+        return sdkInstance;
+    }
+    if (sdkInitPromise) {
+        return sdkInitPromise;
+    }
+    if (!BREEZ_API_KEY) {
+        throw new Error('BREEZ_API_KEY not configured. Request one at https://breez.technology/sdk/');
+    }
+    if (!BREEZ_MNEMONIC) {
+        throw new Error('BREEZ_MNEMONIC not configured. Generate a 12-word mnemonic for self-custody.');
+    }
+    sdkInitPromise = (async () => {
+        try {
+            // Dynamic import for the Breez SDK
+            const breezModule = await import('@breeztech/breez-sdk-liquid');
+            // Network type is a string literal: "mainnet" | "testnet" | "regtest"
+            const network = BREEZ_NETWORK;
+            const config = breezModule.defaultConfig(network, BREEZ_API_KEY);
+            config.workingDir = BREEZ_WORKING_DIR;
+            sdkInstance = await breezModule.connect({
+                mnemonic: BREEZ_MNEMONIC,
+                config,
+            });
+            return sdkInstance;
+        }
+        catch (error) {
+            sdkInitPromise = null;
+            throw error;
+        }
+    })();
+    return sdkInitPromise;
+}
+/**
+ * Create a Lightning invoice for BTC deposit
+ */
+export async function createBreezDeposit(request) {
+    if (!BREEZ_API_KEY || !BREEZ_MNEMONIC) {
+        return {
+            success: false,
+            error: !BREEZ_API_KEY
+                ? 'BREEZ_API_KEY not configured. Request one at https://breez.technology/sdk/'
+                : 'BREEZ_MNEMONIC not configured. Set a 12-word mnemonic for self-custody.',
+        };
+    }
+    try {
+        const sdk = await getSDK();
+        const amountSats = usdToSats(request.amount);
+        // Fetch limits first
+        const limits = await sdk.fetchLightningLimits();
+        if (amountSats < limits.receive.minSat) {
+            return {
+                success: false,
+                error: `Minimum deposit: ${limits.receive.minSat} sats (~$${satsToUsd(limits.receive.minSat).toFixed(2)})`,
+            };
+        }
+        if (amountSats > limits.receive.maxSat) {
+            return {
+                success: false,
+                error: `Maximum deposit: ${limits.receive.maxSat} sats (~$${satsToUsd(limits.receive.maxSat).toFixed(2)})`,
+            };
+        }
+        // Prepare the receive payment
+        const prepareResponse = await sdk.prepareReceivePayment({
+            paymentMethod: 'bolt11Invoice',
+            amount: {
+                type: 'bitcoin',
+                payerAmountSat: amountSats,
+            },
+        });
+        // Create the invoice
+        const description = request.description || `Clawdentials deposit for ${request.agentId}`;
+        const result = await sdk.receivePayment({
+            prepareResponse,
+            description,
+        });
+        // Invoice expires in 1 hour typically
+        const expiresAt = new Date(Date.now() + 60 * 60 * 1000);
+        return {
+            success: true,
+            deposit: {
+                id: `breez_${Date.now()}_${Math.random().toString(36).substring(7)}`,
+                agentId: request.agentId,
+                amount: request.amount,
+                currency: 'BTC',
+                network: 'lightning',
+                status: 'pending',
+                provider: 'breez',
+                externalId: null,
+                paymentAddress: result.destination, // bolt11 invoice
+                paymentUrl: null,
+                createdAt: new Date(),
+                expiresAt,
+                completedAt: null,
+                txHash: null,
+            },
+            invoice: {
+                bolt11: result.destination,
+                amountSats,
+                expiresAt,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to create Lightning invoice',
+        };
+    }
+}
+/**
+ * Send Lightning payment (for withdrawals)
+ */
+export async function sendBreezPayment(destination, // bolt11 invoice or Lightning Address
+amountUsd) {
+    if (!BREEZ_API_KEY || !BREEZ_MNEMONIC) {
+        return { success: false, error: 'Breez SDK not configured' };
+    }
+    try {
+        const sdk = await getSDK();
+        // Prepare the payment
+        const prepareResponse = await sdk.prepareSendPayment({
+            destination,
+        });
+        // Check fees are acceptable
+        const feesSat = prepareResponse.feesSat;
+        console.log(`Breez payment fees: ${feesSat} sats`);
+        // Send the payment
+        const result = await sdk.sendPayment({
+            prepareResponse,
+        });
+        return {
+            success: true,
+            txId: result.payment?.txId || result.payment?.id,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to send payment',
+        };
+    }
+}
+/**
+ * Get wallet balance
+ */
+export async function getWalletBalance() {
+    if (!BREEZ_API_KEY || !BREEZ_MNEMONIC) {
+        return { success: false, error: 'Breez SDK not configured' };
+    }
+    try {
+        const sdk = await getSDK();
+        const info = await sdk.getInfo();
+        return {
+            success: true,
+            balanceSats: info.balanceSat,
+            balanceUsd: satsToUsd(info.balanceSat),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get balance',
+        };
+    }
+}
+/**
+ * List recent payments
+ */
+export async function listPayments(limit = 10) {
+    if (!BREEZ_API_KEY || !BREEZ_MNEMONIC) {
+        return { success: false, error: 'Breez SDK not configured' };
+    }
+    try {
+        const sdk = await getSDK();
+        const payments = await sdk.listPayments({
+            limit,
+        });
+        return {
+            success: true,
+            payments,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to list payments',
+        };
+    }
+}
+/**
+ * Disconnect from SDK (cleanup)
+ */
+export async function disconnect() {
+    if (sdkInstance) {
+        try {
+            await sdkInstance.disconnect();
+        }
+        catch (e) {
+            // Ignore disconnect errors
+        }
+        sdkInstance = null;
+        sdkInitPromise = null;
+    }
+}
+/**
+ * Generate a new mnemonic (for initial setup)
+ */
+export function generateMnemonic() {
+    // In production, use a proper BIP39 library
+    // This is a placeholder - the actual mnemonic should be generated securely
+    throw new Error('Generate mnemonic using a BIP39 library or wallet. Do not use this in production.');
+}
+export const breezService = {
+    createDeposit: createBreezDeposit,
+    sendPayment: sendBreezPayment,
+    getWalletBalance,
+    listPayments,
+    disconnect,
+    usdToSats,
+    satsToUsd,
+    config: {
+        configured: !!(BREEZ_API_KEY && BREEZ_MNEMONIC),
+        apiKeySet: !!BREEZ_API_KEY,
+        mnemonicSet: !!BREEZ_MNEMONIC,
+        network: BREEZ_NETWORK,
+        satsPerUsd: SATS_PER_USD,
+    },
+};