blue-js-sdk 2.0.0

package/ai-path/examples/autonomous-agent.mjs

@@ -0,0 +1,220 @@
+/**
+ * Autonomous Agent — Production VPN Pattern
+ *
+ * A complete autonomous AI agent that:
+ *   1. Creates or loads a wallet
+ *   2. Checks balance, warns if low
+ *   3. Connects to VPN with retry logic
+ *   4. Performs work (HTTP requests through the tunnel)
+ *   5. Monitors connection health
+ *   6. Auto-reconnects on failure
+ *   7. Gracefully disconnects when done
+ *
+ * Run: node examples/autonomous-agent.mjs
+ */
+
+import 'dotenv/config';
+import { connect, disconnect, status, isVpnActive, createWallet, getBalance } from '../index.js';
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+const MAX_RETRIES = 3;
+const RETRY_DELAY_MS = 5000;
+const HEALTH_CHECK_INTERVAL_MS = 30000;
+const WORK_CYCLES = 5;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function log(level, msg) {
+  const ts = new Date().toISOString().slice(11, 19);
+  const prefix = { info: '\x1b[36m[INFO]\x1b[0m', warn: '\x1b[33m[WARN]\x1b[0m', err: '\x1b[31m[ERR]\x1b[0m', ok: '\x1b[32m[ OK ]\x1b[0m' };
+  console.log(`${ts} ${prefix[level] || prefix.info} ${msg}`);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Step 1: Wallet Setup ───────────────────────────────────────────────────
+
+async function ensureWallet() {
+  let mnemonic = process.env.MNEMONIC;
+
+  if (!mnemonic) {
+    log('warn', 'No MNEMONIC in .env — generating a new wallet');
+    const wallet = await createWallet();
+    mnemonic = wallet.mnemonic;
+    log('ok', `Wallet created: ${wallet.address}`);
+    log('warn', 'SAVE YOUR MNEMONIC — it will not be shown again.');
+    log('warn', `Add to .env: MNEMONIC=<your ${mnemonic.split(' ').length} words>`);
+    // SECURITY: Never log the full mnemonic. Write directly to .env file instead.
+    const { writeFileSync } = await import('fs');
+    writeFileSync('.env', `MNEMONIC=${mnemonic}\n`, { mode: 0o600 });
+  }
+
+  return mnemonic;
+}
+
+// ─── Step 2: Balance Check ──────────────────────────────────────────────────
+
+async function checkFunds(mnemonic) {
+  log('info', 'Checking wallet balance...');
+  const bal = await getBalance(mnemonic);
+  log('info', `Address: ${bal.address}`);
+  log('info', `Balance: ${bal.p2p} (${bal.udvpn.toLocaleString()} udvpn)`);
+
+  if (!bal.funded) {
+    log('err', 'Insufficient balance. Fund your wallet with P2P tokens.');
+    log('info', `Send tokens to: ${bal.address}`);
+    process.exit(1);
+  }
+
+  log('ok', 'Wallet funded and ready');
+  return bal;
+}
+
+// ─── Step 3: Connect with Retries ───────────────────────────────────────────
+
+async function connectWithRetry(mnemonic) {
+  for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+    log('info', `Connection attempt ${attempt}/${MAX_RETRIES}...`);
+
+    try {
+      const vpn = await connect({
+        mnemonic,
+        protocol: 'v2ray',
+        onProgress: (stage, detail) => log('info', `  [${stage}] ${detail}`),
+      });
+
+      log('ok', `Connected via ${vpn.protocol} to ${vpn.nodeAddress}`);
+      if (vpn.ip) log('ok', `Public IP: ${vpn.ip}`);
+      return vpn;
+    } catch (err) {
+      log('err', `Attempt ${attempt} failed: ${err.message}`);
+
+      if (attempt < MAX_RETRIES) {
+        const delay = RETRY_DELAY_MS * attempt;
+        log('info', `Retrying in ${delay / 1000}s...`);
+        await sleep(delay);
+      }
+    }
+  }
+
+  log('err', `Failed after ${MAX_RETRIES} attempts`);
+  process.exit(1);
+}
+
+// ─── Step 4: Perform Work ───────────────────────────────────────────────────
+
+async function doWork(cycleNum) {
+  // Simulated work — replace with your actual task
+  // (web scraping, API calls, data collection, etc.)
+  log('info', `Work cycle ${cycleNum}: making request through VPN tunnel...`);
+
+  try {
+    // Use dynamic import so this example works without axios installed
+    const { default: axios } = await import('axios');
+    const res = await axios.get('https://api.ipify.org?format=json', {
+      timeout: 15000,
+      adapter: 'http',
+    });
+    log('ok', `Work cycle ${cycleNum}: response from IP ${res.data.ip}`);
+  } catch (err) {
+    log('warn', `Work cycle ${cycleNum}: request failed — ${err.message}`);
+    return false;
+  }
+
+  return true;
+}
+
+// ─── Step 5: Health Monitor ─────────────────────────────────────────────────
+
+function startHealthMonitor(mnemonic) {
+  const intervalId = setInterval(async () => {
+    if (!isVpnActive()) {
+      log('warn', 'VPN connection lost — reconnecting...');
+      clearInterval(intervalId);
+
+      try {
+        await connectWithRetry(mnemonic);
+        startHealthMonitor(mnemonic);
+      } catch (err) {
+        log('err', `Auto-reconnect failed: ${err.message}`);
+      }
+    } else {
+      const s = status();
+      log('info', `Health check: connected, uptime ${s.uptimeFormatted || 'unknown'}`);
+    }
+  }, HEALTH_CHECK_INTERVAL_MS);
+
+  return intervalId;
+}
+
+// ─── Main Agent Loop ────────────────────────────────────────────────────────
+
+async function main() {
+  log('info', 'Autonomous agent starting...');
+  console.log('');
+
+  // 1. Wallet
+  const mnemonic = await ensureWallet();
+
+  // 2. Funds
+  await checkFunds(mnemonic);
+  console.log('');
+
+  // 3. Connect
+  await connectWithRetry(mnemonic);
+  console.log('');
+
+  // 4. Health monitor
+  const monitorId = startHealthMonitor(mnemonic);
+
+  // 5. Work loop
+  let failures = 0;
+  for (let i = 1; i <= WORK_CYCLES; i++) {
+    const success = await doWork(i);
+    if (!success) failures++;
+
+    // If too many consecutive failures, reconnect
+    if (failures >= 2) {
+      log('warn', 'Multiple work failures — reconnecting...');
+      await disconnect().catch(() => {});
+      await connectWithRetry(mnemonic);
+      failures = 0;
+    }
+
+    // Pause between work cycles
+    if (i < WORK_CYCLES) {
+      await sleep(3000);
+    }
+  }
+
+  // 6. Cleanup
+  console.log('');
+  log('info', 'Work complete. Disconnecting...');
+  clearInterval(monitorId);
+
+  try {
+    await disconnect();
+    log('ok', 'Disconnected. Agent finished.');
+  } catch (err) {
+    log('warn', `Disconnect error: ${err.message}`);
+  }
+
+  process.exit(0);
+}
+
+// ─── Graceful Shutdown ──────────────────────────────────────────────────────
+
+process.on('SIGINT', async () => {
+  console.log('');
+  log('info', 'Interrupted — shutting down...');
+  try { await disconnect(); } catch { /* best effort */ }
+  process.exit(0);
+});
+
+main().catch((err) => {
+  log('err', `Fatal: ${err.message}`);
+  process.exit(1);
+});

package/ai-path/examples/multi-region.mjs

@@ -0,0 +1,174 @@
+/**
+ * Multi-Region Rotation
+ *
+ * Connect to VPN nodes in different countries sequentially.
+ * Each hop: connect -> perform work -> disconnect -> next country.
+ *
+ * Use cases:
+ *   - Data collection from different geographic perspectives
+ *   - Verifying geo-restricted content availability
+ *   - Testing regional API responses
+ *   - Distributing requests across exit regions
+ *
+ * Run: node examples/multi-region.mjs
+ */
+
+import 'dotenv/config';
+import { connect, disconnect, isVpnActive } from '../index.js';
+
+// ─── Configuration ──────────────────────────────────────────────────────────
+
+const REGIONS = [
+  { country: 'DE', label: 'Germany' },
+  { country: 'JP', label: 'Japan' },
+  { country: 'US', label: 'United States' },
+];
+
+const SETTLE_DELAY_MS = 3000;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function log(level, msg) {
+  const ts = new Date().toISOString().slice(11, 19);
+  const prefix = { info: '\x1b[36m[INFO]\x1b[0m', warn: '\x1b[33m[WARN]\x1b[0m', err: '\x1b[31m[ERR]\x1b[0m', ok: '\x1b[32m[ OK ]\x1b[0m' };
+  console.log(`${ts} ${prefix[level] || prefix.info} ${msg}`);
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── Work Function ──────────────────────────────────────────────────────────
+
+/**
+ * Perform work through the VPN tunnel.
+ * Replace this with your actual task (scraping, API calls, etc.).
+ */
+async function doWork(region) {
+  log('info', `[${region.label}] Performing work through tunnel...`);
+
+  try {
+    const { default: axios } = await import('axios');
+
+    // Verify we have a new IP
+    const ipRes = await axios.get('https://api.ipify.org?format=json', {
+      timeout: 15000,
+      adapter: 'http',
+    });
+    log('ok', `[${region.label}] Exit IP: ${ipRes.data.ip}`);
+
+    // Example: fetch region-specific data
+    const geoRes = await axios.get(`https://ipapi.co/${ipRes.data.ip}/json/`, {
+      timeout: 15000,
+      adapter: 'http',
+    });
+    const geo = geoRes.data;
+    log('ok', `[${region.label}] Geo: ${geo.country_name || '?'}, ${geo.city || '?'}, ${geo.org || '?'}`);
+
+    return {
+      region: region.label,
+      ip: ipRes.data.ip,
+      country: geo.country_name || null,
+      city: geo.city || null,
+      org: geo.org || null,
+    };
+  } catch (err) {
+    log('warn', `[${region.label}] Work failed: ${err.message}`);
+    return { region: region.label, ip: null, error: err.message };
+  }
+}
+
+// ─── Main Loop ──────────────────────────────────────────────────────────────
+
+async function main() {
+  const mnemonic = process.env.MNEMONIC;
+  if (!mnemonic) {
+    log('err', 'No MNEMONIC in .env file. Run: sentinel-ai wallet create');
+    process.exit(1);
+  }
+
+  log('info', `Multi-region rotation: ${REGIONS.map(r => r.label).join(' -> ')}`);
+  console.log('');
+
+  const results = [];
+
+  for (let i = 0; i < REGIONS.length; i++) {
+    const region = REGIONS[i];
+    const step = `[${i + 1}/${REGIONS.length}]`;
+
+    // ── Connect ──
+    log('info', `${step} Connecting to ${region.label} (${region.country})...`);
+
+    try {
+      const vpn = await connect({
+        mnemonic,
+        country: region.country,
+        protocol: 'v2ray',
+        onProgress: (stage, detail) => log('info', `  [${stage}] ${detail}`),
+      });
+
+      log('ok', `${step} Connected via ${vpn.protocol}, IP: ${vpn.ip || 'checking...'}`);
+
+      // Let the tunnel settle
+      await sleep(SETTLE_DELAY_MS);
+
+      // ── Work ──
+      const result = await doWork(region);
+      results.push(result);
+
+    } catch (err) {
+      log('err', `${step} Failed to connect to ${region.label}: ${err.message}`);
+      results.push({ region: region.label, ip: null, error: err.message });
+    }
+
+    // ── Disconnect ──
+    if (isVpnActive()) {
+      log('info', `${step} Disconnecting from ${region.label}...`);
+      try {
+        await disconnect();
+        log('ok', `${step} Disconnected`);
+      } catch (err) {
+        log('warn', `${step} Disconnect error: ${err.message}`);
+      }
+    }
+
+    // Pause between regions (let chain state settle)
+    if (i < REGIONS.length - 1) {
+      log('info', 'Waiting before next region...');
+      await sleep(SETTLE_DELAY_MS);
+    }
+
+    console.log('');
+  }
+
+  // ─── Summary ────────────────────────────────────────────────────────────
+
+  console.log('\x1b[1m  Region Rotation Summary\x1b[0m');
+  console.log(`  ${'─'.repeat(60)}`);
+
+  for (const r of results) {
+    if (r.error) {
+      console.log(`  \x1b[31mx\x1b[0m ${r.region.padEnd(20)} Failed: ${r.error}`);
+    } else {
+      console.log(`  \x1b[32m+\x1b[0m ${r.region.padEnd(20)} IP: ${r.ip}  (${r.country || '?'}, ${r.city || '?'})`);
+    }
+  }
+
+  console.log('');
+  const ok = results.filter(r => !r.error).length;
+  log('info', `Done. ${ok}/${results.length} regions connected successfully.`);
+}
+
+// ─── Graceful Shutdown ──────────────────────────────────────────────────────
+
+process.on('SIGINT', async () => {
+  console.log('');
+  log('info', 'Interrupted — disconnecting...');
+  try { await disconnect(); } catch { /* best effort */ }
+  process.exit(0);
+});
+
+main().catch((err) => {
+  log('err', `Fatal: ${err.message}`);
+  process.exit(1);
+});

package/ai-path/examples/one-shot.mjs

@@ -0,0 +1,31 @@
+/**
+ * One-Shot VPN Connection
+ *
+ * The absolute minimum code to connect to Sentinel dVPN.
+ * 10 lines. That's it.
+ *
+ * Prerequisites:
+ *   1. .env file with MNEMONIC=<your 24-word phrase>
+ *   2. Funded wallet (P2P tokens)
+ *   3. V2Ray or WireGuard installed (run: sentinel-ai setup)
+ *
+ * Run: node examples/one-shot.mjs
+ */
+
+import 'dotenv/config';
+import { connect, disconnect } from '../index.js';
+
+const vpn = await connect({
+  mnemonic: process.env.MNEMONIC,
+  onProgress: (step, detail) => console.log(`[${step}] ${detail}`),
+});
+
+console.log(`Connected! Protocol: ${vpn.protocol}, IP: ${vpn.ip}`);
+console.log('Press Ctrl+C to disconnect.');
+
+process.on('SIGINT', async () => {
+  await disconnect();
+  process.exit(0);
+});
+
+await new Promise(() => {});

package/ai-path/index.js

@@ -0,0 +1,60 @@
+/**
+ * Sentinel AI Path — Decentralized VPN for AI Agents
+ *
+ * Complete agent flow:
+ *
+ *   1. Setup:    await setup()           → { os, node, v2ray, wireguard, admin }
+ *   2. Wallet:   await createWallet()    → { mnemonic, address }
+ *   3. Fund:     await getBalance(m)     → { p2p, funded }
+ *   4. Discover: await discoverNodes()   → [{ address, country, protocol, price, score }]
+ *   5. Estimate: await estimateCost(opts) → { perGb, perHour, forBudget }
+ *   6. Connect:  await connect(opts)     → { sessionId, protocol, ip, socksPort }
+ *   7. Verify:   await verify()          → { connected, ip, latency }
+ *   8. Monitor:  onEvent(callback)       → unsubscribe function
+ *   9. Disconnect: await disconnect()    → { disconnected: true }
+ */
+
+// ─── Phase 1: Setup & Environment ────────────────────────────────────────────
+
+export { setup, getEnvironment } from './environment.js';
+
+// ─── Phase 2-3: Wallet & Funding ─────────────────────────────────────────────
+
+export { createWallet, importWallet, getBalance } from './wallet.js';
+
+// ─── Phase 4: Node Discovery ─────────────────────────────────────────────────
+
+export { discoverNodes, getNodeInfo, getNetworkStats } from './discover.js';
+
+// ─── Phase 5: Cost Estimation ────────────────────────────────────────────────
+
+export { estimateCost, PRICING } from './pricing.js';
+
+// ─── Phase 5.5: Decision Engine ───────────────────────────────────────────────
+
+export { recommend } from './recommend.js';
+
+// ─── Phase 6-7: Connect, Verify, Monitor ─────────────────────────────────────
+
+export { connect, disconnect, status, isVpnActive, verify, verifySplitTunnel, onEvent } from './connect.js';
+
+// ─── Error Handling ─────────────────────────────────────────────────────────
+
+export { AiPathError, AiPathErrorCodes } from './errors.js';
+
+// ─── SDK Internals (advanced — for agents that need typed access) ───────────
+
+export {
+  // v1.5.0: Typed event parsers (structured TX event handling)
+  extractSessionIdTyped,
+  NodeEventCreateSession,
+  SubscriptionEventCreateSession,
+  searchEvent,
+  // v1.5.0: TYPE_URLS constants (canonical Sentinel message type URLs)
+  TYPE_URLS,
+  // v1.5.0: RPC queries (protobuf, ~10x faster than LCD)
+  createRpcQueryClientWithFallback,
+  rpcQueryNodes,
+  rpcQueryBalance,
+  rpcQueryNode,
+} from '../index.js';

package/ai-path/pricing.js

@@ -0,0 +1,136 @@
+/**
+ * Sentinel AI Path — Cost Estimation & Budget Planning
+ *
+ * An AI agent uses these to estimate costs before committing tokens.
+ */
+
+import {
+  estimateSessionCost,
+  estimateSessionPrice,
+  formatP2P,
+  PRICING_REFERENCE,
+  DENOM,
+} from '../index.js';
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+/**
+ * Reference pricing from the SDK. Based on network-wide observations.
+ *
+ * @type {{
+ *   typicalPerGb: { udvpn: number, p2p: string },
+ *   minBalance: { udvpn: number, p2p: string },
+ *   gasCost: { udvpn: number, p2p: string },
+ *   denom: string,
+ * }}
+ */
+/**
+ * Reference pricing sampled from chain data (2026-03-26, 1030 nodes).
+ * THESE ARE APPROXIMATE — node operators set their own prices and can change
+ * them at any time. Use estimateCost({ nodeAddress }) for live per-node pricing.
+ *   Median: ~40 P2P/GB (40152030 udvpn at sample time)
+ *   Cheapest: ~0.68 P2P/GB (680000 udvpn at sample time)
+ */
+export const PRICING = {
+  medianPerGb: {
+    udvpn: 40152030,
+    p2p: formatP2P(40152030),
+  },
+  cheapestPerGb: {
+    udvpn: 680000,
+    p2p: formatP2P(680000),
+  },
+  typicalPerGb: {
+    udvpn: 40152030,
+    p2p: formatP2P(40152030),
+  },
+  minBalance: {
+    udvpn: 50000000, // 50 P2P — enough for 1 GB on median node + gas
+    p2p: formatP2P(50000000),
+  },
+  gasCost: {
+    udvpn: 40000,
+    p2p: formatP2P(40000),
+  },
+  denom: DENOM || 'udvpn',
+};
+
+// ─── estimateCost() ──────────────────────────────────────────────────────────
+
+/**
+ * Estimate connection cost before committing tokens.
+ *
+ * @param {object} opts
+ * @param {number} [opts.gigabytes=1] - Planned data usage in GB
+ * @param {number} [opts.hours] - Planned session duration in hours (alternative to GB)
+ * @param {number} [opts.budget] - Available budget in udvpn — calculates how much you can get
+ * @param {string} [opts.nodeAddress] - Specific node for exact pricing (queries chain)
+ * @returns {Promise<{
+ *   perGb: { udvpn: number, p2p: string },
+ *   total: { udvpn: number, p2p: string },
+ *   gas: { udvpn: number, p2p: string },
+ *   grandTotal: { udvpn: number, p2p: string },
+ *   forBudget?: { gigabytes: number, hours: number|null },
+ *   mode: 'per-gb'|'hourly'|'estimate',
+ * }>}
+ */
+export async function estimateCost(opts = {}) {
+  if (opts && typeof opts !== 'object') {
+    throw new Error('estimateCost(): opts must be an object or undefined');
+  }
+  const gb = opts.gigabytes || 1;
+  const gasCost = 40000; // ~0.04 P2P per TX
+
+  // If specific node given, get exact price
+  if (opts.nodeAddress) {
+    try {
+      const price = await estimateSessionPrice(opts.nodeAddress, gb);
+      const total = price.udvpn || price.amount || 0;
+      const grandTotal = total + gasCost;
+
+      const result = {
+        perGb: { udvpn: Math.round(total / gb), p2p: formatP2P(Math.round(total / gb)) },
+        total: { udvpn: total, p2p: formatP2P(total) },
+        gas: { udvpn: gasCost, p2p: formatP2P(gasCost) },
+        grandTotal: { udvpn: grandTotal, p2p: formatP2P(grandTotal) },
+        mode: opts.hours ? 'hourly' : 'per-gb',
+      };
+
+      if (opts.budget) {
+        const usable = opts.budget - gasCost;
+        const pricePerGb = Math.round(total / gb);
+        result.forBudget = {
+          gigabytes: pricePerGb > 0 ? Math.floor(usable / pricePerGb) : 0,
+          hours: null,
+        };
+      }
+
+      return result;
+    } catch {
+      // Fall through to estimate
+    }
+  }
+
+  // Network-wide estimate based on real chain pricing (median across 1030 nodes)
+  const typicalPerGb = PRICING.typicalPerGb.udvpn;
+  const total = typicalPerGb * gb;
+  const grandTotal = total + gasCost;
+
+  const result = {
+    perGb: { udvpn: typicalPerGb, p2p: formatP2P(typicalPerGb) },
+    total: { udvpn: total, p2p: formatP2P(total) },
+    gas: { udvpn: gasCost, p2p: formatP2P(gasCost) },
+    grandTotal: { udvpn: grandTotal, p2p: formatP2P(grandTotal) },
+    mode: 'estimate',
+  };
+
+  if (opts.budget) {
+    const usable = opts.budget - gasCost;
+    result.forBudget = {
+      gigabytes: typicalPerGb > 0 ? Math.floor(usable / typicalPerGb) : 0,
+      hours: null,
+    };
+  }
+
+  return result;
+}