@mcpsovereign/sdk 0.1.0 → 0.2.0

package/dist/wallet/wizard.js

@@ -0,0 +1,498 @@
+/**
+ * Wallet Setup Wizard
+ *
+ * Interactive guide for setting up Lightning wallet
+ * MUST be completed before buying/selling (browsing is free)
+ */
+import { WALLET_PROVIDERS } from './types.js';
+import { verifyLightningAddress, parseLightningAddress, formatSats } from './lightning.js';
+import { quickSetupLND } from './lnd-setup.js';
+// ============================================================
+// ASCII ART
+// ============================================================
+const WALLET_BANNER = `
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║         ⚡ LIGHTNING WALLET SETUP ⚡                              ║
+║                                                                   ║
+║     mcpSovereign runs on Bitcoin Lightning Network               ║
+║     Fast, cheap, global payments for AI agents                    ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+`;
+const SELF_HOSTED_BANNER = `
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║         🖥️  SELF-HOSTED LIGHTNING NODE  🖥️                        ║
+║                                                                   ║
+║     Run your own Lightning node using Neutrino                    ║
+║     No Bitcoin Core required - syncs in minutes!                  ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+`;
+const SUCCESS_BANNER = `
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║         ✅ WALLET CONNECTED! ✅                                   ║
+║                                                                   ║
+║     You can now:                                                  ║
+║       💳 Buy credits with Lightning                              ║
+║       💰 Sell products and earn sats                             ║
+║       🏦 Withdraw earnings anytime                               ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+`;
+// ============================================================
+// WALLET SETUP WIZARD
+// ============================================================
+export class WalletSetupWizard {
+    progress;
+    outputHandler;
+    inputHandler;
+    config = null;
+    constructor(outputHandler = console.log, inputHandler) {
+        this.outputHandler = outputHandler;
+        this.inputHandler = inputHandler;
+        this.progress = this.loadProgress();
+    }
+    // ============================================================
+    // OUTPUT HELPERS
+    // ============================================================
+    print(message) {
+        this.outputHandler(message);
+    }
+    printDivider() {
+        this.print('\n' + '─'.repeat(60) + '\n');
+    }
+    printHeader(emoji, title) {
+        this.print(`\n${'═'.repeat(60)}`);
+        this.print(`  ${emoji}  ${title.toUpperCase()}`);
+        this.print('═'.repeat(60) + '\n');
+    }
+    // ============================================================
+    // PROGRESS MANAGEMENT
+    // ============================================================
+    loadProgress() {
+        return {
+            currentStep: 0,
+            completed: false,
+            verified: false,
+            skipped: false
+        };
+    }
+    saveProgress() {
+        // In real implementation, save to ~/.mcpsovereign/wallet-config.json
+    }
+    // ============================================================
+    // STEP: INTRODUCTION
+    // ============================================================
+    async runIntro() {
+        this.print(WALLET_BANNER);
+        this.print('Why Lightning? ⚡\n');
+        this.print('  • Instant payments (seconds, not days)');
+        this.print('  • Near-zero fees (~1 sat for any amount)');
+        this.print('  • Global (no banks, no borders)');
+        this.print('  • Perfect for AI agents trading value\n');
+        this.print('What you need:\n');
+        this.print('  📱 A Lightning wallet with a Lightning Address');
+        this.print('  💳 Some sats to buy credits (or earn by selling)\n');
+        this.print('Don\'t have a wallet yet? No problem!');
+        this.print('We\'ll help you set one up in about 2 minutes.\n');
+        this.print('┌────────────────────────────────────────────────────────┐');
+        this.print('│  🆓 BROWSING THE MARKETPLACE IS ALWAYS FREE            │');
+        this.print('│  💳 Wallet only needed to BUY or SELL                  │');
+        this.print('└────────────────────────────────────────────────────────┘\n');
+        await this.waitForContinue();
+        this.progress.currentStep = 1;
+    }
+    // ============================================================
+    // STEP: CHOOSE PATH
+    // ============================================================
+    async runChoosePath() {
+        this.printHeader('🛤️', 'Choose Your Path');
+        this.print('How do you want to connect to Lightning?\n');
+        this.print('  1. 📱 HOSTED WALLET (Recommended for most agents)');
+        this.print('     Use a service like Alby or Wallet of Satoshi');
+        this.print('     ✓ Ready in 2 minutes');
+        this.print('     ✓ No technical setup');
+        this.print('     ✓ Works on phone or browser\n');
+        this.print('  2. 🖥️  SELF-HOSTED NODE (For power users)');
+        this.print('     Run your own LND node in Docker');
+        this.print('     ✓ Full sovereignty');
+        this.print('     ✓ No custodial risk');
+        this.print('     ✓ Neutrino mode (no full Bitcoin node needed)\n');
+        this.print('  3. ⏭️  SKIP FOR NOW');
+        this.print('     Browse the marketplace without a wallet');
+        this.print('     You can set up later when ready to buy/sell\n');
+        const choice = await this.getChoice('Enter your choice (1-3):', 3);
+        switch (choice) {
+            case 1: return 'hosted';
+            case 2: return 'self-hosted';
+            case 3: return 'skip';
+            default: return 'hosted';
+        }
+    }
+    // ============================================================
+    // STEP: HOSTED WALLET SETUP
+    // ============================================================
+    async runHostedWalletSetup() {
+        this.printHeader('📱', 'Choose a Wallet Provider');
+        this.print('Pick a Lightning wallet. All of these support Lightning Addresses:\n');
+        const recommended = Object.entries(WALLET_PROVIDERS)
+            .filter(([_, p]) => p.recommended && p.id !== 'custom');
+        const others = Object.entries(WALLET_PROVIDERS)
+            .filter(([_, p]) => !p.recommended && p.id !== 'custom');
+        this.print('⭐ RECOMMENDED (easiest to set up):\n');
+        recommended.forEach(([key, provider], index) => {
+            this.print(`  ${index + 1}. ${provider.emoji} ${provider.name}`);
+            this.print(`     ${provider.description}`);
+            this.print(`     Type: ${provider.type} | Difficulty: ${provider.difficulty}`);
+            this.print(`     Platforms: ${provider.platforms.join(', ')}\n`);
+        });
+        this.print('OTHER OPTIONS:\n');
+        others.forEach(([key, provider], index) => {
+            this.print(`  ${recommended.length + index + 1}. ${provider.emoji} ${provider.name}`);
+            this.print(`     ${provider.description}`);
+            this.print(`     Type: ${provider.type} | Difficulty: ${provider.difficulty}\n`);
+        });
+        this.print(`  ${recommended.length + others.length + 1}. 🔧 I already have a Lightning Address\n`);
+        const allProviders = [...recommended, ...others];
+        const choice = await this.getChoice(`Enter your choice (1-${allProviders.length + 1}):`, allProviders.length + 1);
+        if (choice === allProviders.length + 1) {
+            // Already has a wallet
+            return 'custom';
+        }
+        const selectedProvider = allProviders[choice - 1][0];
+        const providerInfo = WALLET_PROVIDERS[selectedProvider];
+        this.progress.provider = selectedProvider;
+        // Show setup instructions
+        await this.showProviderSetup(providerInfo);
+        return selectedProvider;
+    }
+    /**
+     * Show setup instructions for a specific provider
+     */
+    async showProviderSetup(provider) {
+        this.printHeader('🛠️', `Setting Up ${provider.name}`);
+        this.print(`Let's set up your ${provider.emoji} ${provider.name} wallet!\n`);
+        switch (provider.id) {
+            case 'alby':
+                this.print('STEP 1: Install Alby Browser Extension');
+                this.print(`  → Go to: ${provider.setupUrl}`);
+                this.print('  → Click "Add to Chrome/Firefox/etc."\n');
+                this.print('STEP 2: Create Your Account');
+                this.print('  → Click the Alby icon in your browser');
+                this.print('  → Sign up with email or Nostr\n');
+                this.print('STEP 3: Get Your Lightning Address');
+                this.print('  → Your address will be: yourname@getalby.com');
+                this.print('  → Find it in Settings → Lightning Address\n');
+                break;
+            case 'walletofsatoshi':
+                this.print('STEP 1: Download the App');
+                this.print(`  → Go to: ${provider.setupUrl}`);
+                this.print('  → Available on iOS and Android\n');
+                this.print('STEP 2: Open the App');
+                this.print('  → No account needed! Just open and you\'re ready\n');
+                this.print('STEP 3: Get Your Lightning Address');
+                this.print('  → Tap "Receive"');
+                this.print('  → Your address: yourname@walletofsatoshi.com\n');
+                break;
+            case 'phoenix':
+                this.print('STEP 1: Download Phoenix');
+                this.print(`  → Go to: ${provider.setupUrl}`);
+                this.print('  → Available on iOS and Android\n');
+                this.print('STEP 2: Create Your Wallet');
+                this.print('  → Write down your 12-word seed phrase!');
+                this.print('  → This is your backup - keep it safe!\n');
+                this.print('STEP 3: Get Your Lightning Address');
+                this.print('  → Go to Settings → Lightning Address');
+                this.print('  → Format: yourname@phoenix.acinq.co\n');
+                break;
+            default:
+                this.print(`STEP 1: Go to ${provider.setupUrl}`);
+                this.print('STEP 2: Follow their setup instructions');
+                this.print('STEP 3: Get your Lightning Address\n');
+        }
+        this.print('┌────────────────────────────────────────────────────────┐');
+        this.print('│  💡 TIP: Your Lightning Address looks like an email:   │');
+        this.print('│     yourname@getalby.com                               │');
+        this.print('│     yourname@walletofsatoshi.com                       │');
+        this.print('└────────────────────────────────────────────────────────┘\n');
+        await this.waitForContinue('Press Enter when you have your Lightning Address...');
+    }
+    // ============================================================
+    // STEP: SELF-HOSTED NODE SETUP
+    // ============================================================
+    async runSelfHostedSetup() {
+        this.print(SELF_HOSTED_BANNER);
+        this.print('Self-hosting gives you full control over your Bitcoin.\n');
+        this.print('What you\'ll get:');
+        this.print('  🖥️  Your own LND Lightning node');
+        this.print('  ⚡ Neutrino mode (syncs in minutes, not days)');
+        this.print('  🐳 Runs in Docker (easy management)');
+        this.print('  🔐 Your keys, your Bitcoin\n');
+        this.print('Requirements:');
+        this.print('  • Docker installed and running');
+        this.print('  • ~5GB disk space');
+        this.print('  • Internet connection\n');
+        const proceed = await this.getInput('Run automated setup? (yes/no): ');
+        if (proceed.toLowerCase() !== 'yes' && proceed.toLowerCase() !== 'y') {
+            this.print('\nSetup cancelled. You can run it later with:');
+            this.print('  npx @mcpsovereign/sdk setup-lnd\n');
+            return false;
+        }
+        this.print('\n🚀 Starting automated LND setup...\n');
+        // Run the setup
+        const result = await quickSetupLND();
+        if (!result.success) {
+            this.print(`\n❌ Setup failed: ${result.error}`);
+            this.print('\nLogs:');
+            result.logs.slice(-10).forEach(log => this.print(`  ${log}`));
+            return false;
+        }
+        // Show success and seed
+        this.print('\n✅ LND node is running!\n');
+        if (result.walletSeed) {
+            this.print('┌────────────────────────────────────────────────────────┐');
+            this.print('│  🔐 IMPORTANT: BACKUP YOUR SEED PHRASE!                │');
+            this.print('├────────────────────────────────────────────────────────┤');
+            this.print('│  Write these 24 words down and store them safely:     │');
+            this.print('│                                                        │');
+            for (let i = 0; i < 24; i += 4) {
+                const words = result.walletSeed.slice(i, i + 4);
+                const line = words.map((w, j) => `${i + j + 1}. ${w}`).join('  ');
+                this.print(`│  ${line.padEnd(54)}│`);
+            }
+            this.print('│                                                        │');
+            this.print('│  ⚠️  If you lose these words, you lose your Bitcoin!   │');
+            this.print('└────────────────────────────────────────────────────────┘\n');
+        }
+        if (result.credentials) {
+            this.config = {
+                provider: 'zeus', // Self-hosted
+                nodeUri: `${result.credentials.restHost}`,
+                setupComplete: true,
+                verified: true,
+                verifiedAt: new Date().toISOString(),
+                createdAt: new Date().toISOString()
+            };
+            this.print('Node connection info:');
+            this.print(`  REST: ${result.credentials.restHost}`);
+            this.print(`  gRPC: ${result.credentials.grpcHost}\n`);
+        }
+        this.progress.verified = true;
+        this.progress.provider = 'zeus';
+        return true;
+    }
+    // ============================================================
+    // STEP: ENTER LIGHTNING ADDRESS
+    // ============================================================
+    async runEnterAddress() {
+        this.printHeader('📧', 'Enter Your Lightning Address');
+        this.print('Your Lightning Address is like an email for Bitcoin.\n');
+        this.print('Examples:');
+        this.print('  • myagent@getalby.com');
+        this.print('  • satoshi@walletofsatoshi.com');
+        this.print('  • agent007@phoenix.acinq.co\n');
+        const address = await this.getInput('Your Lightning Address: ');
+        if (!address) {
+            this.print('\n⚠️  No address entered.');
+            return null;
+        }
+        // Validate format
+        const parsed = parseLightningAddress(address);
+        if (!parsed || !parsed.valid) {
+            this.print('\n❌ Invalid format. Lightning addresses look like: username@domain.com');
+            return null;
+        }
+        this.progress.lightningAddress = parsed.address;
+        return parsed.address;
+    }
+    // ============================================================
+    // STEP: VERIFY ADDRESS
+    // ============================================================
+    async runVerifyAddress(address) {
+        this.printHeader('✅', 'Verifying Your Wallet');
+        this.print(`Verifying: ${address}\n`);
+        this.print('Checking if your wallet can receive payments...\n');
+        const result = await verifyLightningAddress(address);
+        if (!result.valid) {
+            this.print(`❌ Verification failed: ${result.error}`);
+            this.print('\nPossible issues:');
+            this.print('  • The address might be typed incorrectly');
+            this.print('  • The wallet service might be down');
+            this.print('  • The account might not be fully set up yet\n');
+            return false;
+        }
+        this.print('✅ Wallet verified successfully!\n');
+        if (result.info?.metadata) {
+            this.print('Wallet details:');
+            if (result.info.metadata.description) {
+                this.print(`  📝 ${result.info.metadata.description}`);
+            }
+            if (result.info.metadata.minSendable) {
+                this.print(`  📉 Min receive: ${formatSats(result.info.metadata.minSendable / 1000)}`);
+            }
+            if (result.info.metadata.maxSendable) {
+                this.print(`  📈 Max receive: ${formatSats(result.info.metadata.maxSendable / 1000)}`);
+            }
+            this.print('');
+        }
+        // Save config
+        this.config = {
+            provider: this.progress.provider || 'custom',
+            lightningAddress: address,
+            setupComplete: true,
+            verified: true,
+            verifiedAt: new Date().toISOString(),
+            createdAt: new Date().toISOString()
+        };
+        this.progress.verified = true;
+        return true;
+    }
+    // ============================================================
+    // STEP: COMPLETE
+    // ============================================================
+    async runComplete() {
+        this.print(SUCCESS_BANNER);
+        this.print('Your wallet setup:\n');
+        this.print('┌────────────────────────────────────────────────────────┐');
+        if (this.config?.lightningAddress) {
+            this.print(`│  📧 Address: ${this.config.lightningAddress.padEnd(40)}│`);
+        }
+        if (this.config?.provider) {
+            const provider = WALLET_PROVIDERS[this.config.provider];
+            this.print(`│  ${provider.emoji} Provider: ${provider.name.padEnd(39)}│`);
+        }
+        this.print(`│  ✅ Verified: ${this.config?.verified ? 'Yes' : 'No'}                                     │`);
+        this.print('└────────────────────────────────────────────────────────┘\n');
+        this.print('What happens next:\n');
+        this.print('  1. Complete onboarding to set up your store');
+        this.print('  2. Buy credits with Lightning to start trading');
+        this.print('  3. Create products and earn sats!\n');
+        this.print('Credit packages:\n');
+        this.print('  💰 1,000 credits = 10,000 sats (~$5)');
+        this.print('  💰 5,000 credits = 50,000 sats (~$25)');
+        this.print('  💰 10,000 credits = 100,000 sats (~$50)\n');
+        this.progress.completed = true;
+        this.saveProgress();
+    }
+    // ============================================================
+    // STEP: SKIP
+    // ============================================================
+    async runSkip() {
+        this.printHeader('⏭️', 'Skipping Wallet Setup');
+        this.print('No problem! You can browse the marketplace without a wallet.\n');
+        this.print('What you CAN do without a wallet:');
+        this.print('  🔍 Browse products');
+        this.print('  👀 View prices and reviews');
+        this.print('  📖 Read documentation');
+        this.print('  🏪 Set up your store locally (FREE)\n');
+        this.print('What you\'ll need a wallet for:');
+        this.print('  💳 Buying credits');
+        this.print('  💰 Receiving payments from sales');
+        this.print('  📤 Publishing to marketplace\n');
+        this.print('You can set up your wallet anytime with:');
+        this.print('  npx @mcpsovereign/sdk setup-wallet\n');
+        this.progress.skipped = true;
+        this.progress.completed = true;
+        this.saveProgress();
+    }
+    // ============================================================
+    // MAIN RUN METHOD
+    // ============================================================
+    async run() {
+        // Step 1: Introduction
+        await this.runIntro();
+        // Step 2: Choose path
+        const path = await this.runChoosePath();
+        if (path === 'skip') {
+            await this.runSkip();
+            return { config: null, skipped: true };
+        }
+        if (path === 'self-hosted') {
+            // Self-hosted LND setup
+            const success = await this.runSelfHostedSetup();
+            if (success) {
+                await this.runComplete();
+                return { config: this.config, skipped: false };
+            }
+            // Fall back to hosted option
+            this.print('\nFalling back to hosted wallet option...\n');
+        }
+        // Hosted wallet setup
+        const provider = await this.runHostedWalletSetup();
+        if (!provider) {
+            await this.runSkip();
+            return { config: null, skipped: true };
+        }
+        // Get Lightning Address
+        let address = null;
+        let verified = false;
+        while (!verified) {
+            address = await this.runEnterAddress();
+            if (!address) {
+                const retry = await this.getInput('Try again? (yes/no): ');
+                if (retry.toLowerCase() !== 'yes' && retry.toLowerCase() !== 'y') {
+                    await this.runSkip();
+                    return { config: null, skipped: true };
+                }
+                continue;
+            }
+            verified = await this.runVerifyAddress(address);
+            if (!verified) {
+                const retry = await this.getInput('Try a different address? (yes/no): ');
+                if (retry.toLowerCase() !== 'yes' && retry.toLowerCase() !== 'y') {
+                    // Allow proceeding with unverified (user's choice)
+                    const proceed = await this.getInput('Proceed with unverified address? (yes/no): ');
+                    if (proceed.toLowerCase() === 'yes' || proceed.toLowerCase() === 'y') {
+                        this.config = {
+                            provider: provider,
+                            lightningAddress: address,
+                            setupComplete: true,
+                            verified: false,
+                            createdAt: new Date().toISOString()
+                        };
+                        break;
+                    }
+                }
+            }
+        }
+        await this.runComplete();
+        return { config: this.config, skipped: false };
+    }
+    // ============================================================
+    // INPUT HELPERS
+    // ============================================================
+    async waitForContinue(prompt = 'Press Enter to continue...') {
+        await this.getInput(prompt);
+    }
+    async getInput(prompt) {
+        if (this.inputHandler) {
+            return await this.inputHandler(prompt);
+        }
+        this.print(prompt);
+        return '';
+    }
+    async getChoice(prompt, max) {
+        if (this.inputHandler) {
+            const options = Array.from({ length: max }, (_, i) => (i + 1).toString());
+            const response = await this.inputHandler(prompt, options);
+            const num = parseInt(response);
+            if (num >= 1 && num <= max) {
+                return num;
+            }
+        }
+        return 1;
+    }
+    // ============================================================
+    // GETTERS
+    // ============================================================
+    getConfig() {
+        return this.config;
+    }
+    getProgress() {
+        return { ...this.progress };
+    }
+}
+export default WalletSetupWizard;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcpsovereign/sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for mcpSovereign - The AI Agent Marketplace",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,9 @@
     "dev": "tsc --watch",
     "postinstall": "node dist/setup.js setup 2>/dev/null || echo 'Run: npx mcpsovereign setup'"
   },
-  "dependencies": {},
+  "dependencies": {
+    "@mcpsovereign/types": "workspace:*"
+  },
   "devDependencies": {
     "@types/node": "^22.10.7",
     "typescript": "^5.7.3"
@@ -49,7 +51,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/mcpsovereign/mcpsovereign-sdk"
+    "url": "https://github.com/mcpsovereign/sdk"
   },
   "homepage": "https://mcpsovereign.com",
   "license": "MIT"