blue-js-sdk 2.0.0

package/ai-path/discover.js

@@ -0,0 +1,178 @@
+/**
+ * Sentinel AI Path — Node Discovery & Selection
+ *
+ * An AI agent uses these functions to find the best node for its needs:
+ * budget, location, protocol, speed.
+ */
+
+import {
+  queryOnlineNodes,
+  fetchActiveNodes,
+  filterNodes,
+  getNodePrices,
+  getNetworkOverview,
+  groupNodesByCountry,
+  formatP2P,
+  TRANSPORT_SUCCESS_RATES,
+  LCD_ENDPOINTS,
+  tryWithFallback,
+  // v1.5.0: RPC queries (protobuf via ABCI, ~10x faster than LCD for node lists)
+  createRpcQueryClientWithFallback,
+  rpcQueryNodes,
+} from '../index.js';
+
+// ─── discoverNodes() ─────────────────────────────────────────────────────────
+
+/**
+ * Discover all available nodes on the Sentinel network.
+ * Returns every active node with address, protocol, pricing, and remote URL.
+ *
+ * By default queries the blockchain directly (fast, returns ALL nodes).
+ * Set opts.probe = true to individually probe each node for live status.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.country] - Filter by country name or code (e.g. 'Germany', 'DE')
+ * @param {string} [opts.protocol] - Filter by protocol: 'wireguard' or 'v2ray'
+ * @param {number} [opts.maxPrice] - Max price in udvpn per GB (filter expensive nodes)
+ * @param {number} [opts.limit] - Max nodes to return (default: all)
+ * @param {boolean} [opts.probe] - If true, probe each node individually for live status (slow). Default: false
+ * @param {function} [opts.onProgress] - Progress callback: ({ total, probed, online }) => void
+ * @returns {Promise<Array<{
+ *   address: string,
+ *   country: string|null,
+ *   protocol: string,
+ *   pricePerGb: { udvpn: number, p2p: string }|null,
+ *   pricePerHour: { udvpn: number, p2p: string }|null,
+ *   score: number,
+ *   peers: number,
+ *   remoteUrl: string,
+ * }>>}
+ */
+export async function discoverNodes(opts = {}) {
+  if (opts && typeof opts !== 'object') {
+    throw new Error('discoverNodes(): opts must be an object or undefined');
+  }
+
+  let nodes;
+
+  if (opts.probe) {
+    // Slow path: probe each node for live status, peers, location
+    const maxNodes = opts.limit ? opts.limit * 3 : 3000;
+    nodes = await queryOnlineNodes({
+      maxNodes,
+      onNodeProbed: opts.onProgress || undefined,
+    });
+  } else {
+    // Fast path: query blockchain for all active nodes
+    // v1.5.0: Try RPC first (protobuf, ~10x faster), fall back to LCD
+    try {
+      const rpcClient = await createRpcQueryClientWithFallback();
+      nodes = await rpcQueryNodes(rpcClient, { status: 1, limit: 5000 });
+    } catch {
+      // RPC failed — fall back to LCD
+      const { result } = await tryWithFallback(
+        LCD_ENDPOINTS,
+        fetchActiveNodes,
+        'discoverNodes',
+      );
+      nodes = result;
+    }
+  }
+
+  // Apply filters
+  if (opts.country) {
+    nodes = filterNodes(nodes, { country: opts.country });
+  }
+  if (opts.protocol) {
+    nodes = nodes.filter(n => {
+      const type = String(n.serviceType || n.service_type || '').toLowerCase();
+      return type === opts.protocol;
+    });
+  }
+
+  // Enrich with clean structure
+  const enriched = nodes.map(n => {
+    const gbPrices = n.gigabyte_prices || [];
+    const hrPrices = n.hourly_prices || [];
+    const udvpnGb = gbPrices.find(p => p.denom === 'udvpn');
+    const udvpnHr = hrPrices.find(p => p.denom === 'udvpn');
+
+    const pricePerGb = udvpnGb ? {
+      udvpn: parseInt(udvpnGb.quote_value || udvpnGb.amount || '0', 10),
+      p2p: formatP2P(parseInt(udvpnGb.quote_value || udvpnGb.amount || '0', 10)),
+    } : null;
+
+    const pricePerHour = udvpnHr ? {
+      udvpn: parseInt(udvpnHr.quote_value || udvpnHr.amount || '0', 10),
+      p2p: formatP2P(parseInt(udvpnHr.quote_value || udvpnHr.amount || '0', 10)),
+    } : null;
+
+    return {
+      address: n.address || n.acc_address,
+      country: n.country || n.location?.country || null,
+      protocol: (() => {
+        const t = String(n.serviceType || n.service_type || '').toLowerCase();
+        return t === 'wireguard' || t === 'v2ray' ? t : null;
+      })(),
+      pricePerGb,
+      pricePerHour,
+      score: n.qualityScore ?? n.score ?? 0,
+      peers: n.peers ?? null,
+      remoteUrl: n.remote_url || n.remote_addrs?.[0] || '',
+    };
+  });
+
+  // Filter by max price
+  if (opts.maxPrice && opts.maxPrice > 0) {
+    const filtered = enriched.filter(n =>
+      n.pricePerGb && n.pricePerGb.udvpn <= opts.maxPrice
+    );
+    if (filtered.length > 0) {
+      const sorted = filtered.sort((a, b) => (b.score || 0) - (a.score || 0));
+      return opts.limit ? sorted.slice(0, opts.limit) : sorted;
+    }
+  }
+
+  // Sort by score descending
+  const sorted = enriched.sort((a, b) => (b.score || 0) - (a.score || 0));
+  return opts.limit ? sorted.slice(0, opts.limit) : sorted;
+}
+
+// ─── getNodeInfo() ───────────────────────────────────────────────────────────
+
+/**
+ * Get detailed info for a specific node including pricing.
+ *
+ * @param {string} nodeAddress - sentnode1... address
+ * @returns {Promise<{ address: string, prices: object, online: boolean, country: string|null }>}
+ */
+export async function getNodeInfo(nodeAddress) {
+  const prices = await getNodePrices(nodeAddress);
+  return {
+    address: nodeAddress,
+    prices,
+    online: true, // If getNodePrices didn't throw, node is reachable
+  };
+}
+
+// ─── getNetworkStats() ───────────────────────────────────────────────────────
+
+/**
+ * Get network-wide statistics for an AI agent to understand the landscape.
+ *
+ * @returns {Promise<{
+ *   totalNodes: number,
+ *   byCountry: Record<string, number>,
+ *   byProtocol: { wireguard: number, v2ray: number },
+ *   transportReliability: Record<string, number>,
+ * }>}
+ */
+export async function getNetworkStats() {
+  const overview = await getNetworkOverview();
+  return {
+    totalNodes: overview.totalNodes || overview.total || 0,
+    byCountry: overview.byCountry || {},
+    byProtocol: overview.byType || overview.byProtocol || { wireguard: 0, v2ray: 0 },
+    transportReliability: { ...TRANSPORT_SUCCESS_RATES },
+  };
+}

package/ai-path/environment.js

@@ -0,0 +1,266 @@
+/**
+ * Sentinel AI Path — Environment Detection & Setup
+ *
+ * Detects OS, checks all dependencies, reports what's available.
+ * An AI agent calls setup() first to understand what it can do.
+ */
+
+import {
+  verifyDependencies,
+  IS_ADMIN,
+  WG_AVAILABLE,
+  V2RAY_VERSION,
+  preflight,
+} from '../index.js';
+import { existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ─── V2Ray Detection (comprehensive) ────────────────────────────────────────
+
+/**
+ * Find V2Ray binary by checking every known location.
+ * This is the authoritative detection — covers env var, SDK paths, system paths.
+ */
+function findV2Ray() {
+  const binary = process.platform === 'win32' ? 'v2ray.exe' : 'v2ray';
+
+  // 1. V2RAY_PATH env var (highest priority)
+  if (process.env.V2RAY_PATH && existsSync(process.env.V2RAY_PATH)) {
+    return process.env.V2RAY_PATH;
+  }
+
+  // 2. Use Node.js module resolution to find the SDK, then derive bin/ path
+  try {
+    const sdkMain = import.meta.resolve('sentinel-dvpn-sdk');
+    const sdkDir = dirname(fileURLToPath(sdkMain));
+    const sdkBin = resolve(sdkDir, 'bin', binary);
+    if (existsSync(sdkBin)) return sdkBin;
+  } catch {}
+
+  // 3. Walk up from __dirname looking for sentinel-dvpn-sdk/bin/
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    const candidate = resolve(dir, 'node_modules', 'sentinel-dvpn-sdk', 'bin', binary);
+    if (existsSync(candidate)) return candidate;
+    const sibling = resolve(dir, '..', 'sentinel-dvpn-sdk', 'bin', binary);
+    if (existsSync(sibling)) return sibling;
+    dir = resolve(dir, '..');
+  }
+
+  // 4. Local bin/
+  const localBin = resolve(__dirname, 'bin', binary);
+  if (existsSync(localBin)) return localBin;
+
+  // 5. Parent bin/ (monorepo layout)
+  const parentBin = resolve(__dirname, '..', 'bin', binary);
+  if (existsSync(parentBin)) return parentBin;
+
+  // 5. System paths
+  const systemPaths = process.platform === 'win32'
+    ? ['C:\\Program Files\\V2Ray\\v2ray.exe', 'C:\\Program Files (x86)\\V2Ray\\v2ray.exe']
+    : ['/usr/local/bin/v2ray', '/usr/bin/v2ray', '/opt/homebrew/bin/v2ray'];
+  for (const p of systemPaths) {
+    if (existsSync(p)) return p;
+  }
+
+  // 6. System PATH
+  try {
+    const cmd = process.platform === 'win32' ? 'where v2ray.exe' : 'which v2ray';
+    const result = execSync(cmd, { encoding: 'utf8', stdio: 'pipe' }).trim();
+    if (result) return result.split('\n')[0];
+  } catch { /* not in PATH */ }
+
+  return null;
+}
+
+// ─── WireGuard Detection (comprehensive) ─────────────────────────────────────
+
+function findWireGuard() {
+  if (process.platform === 'win32') {
+    const paths = [
+      'C:\\Program Files\\WireGuard\\wireguard.exe',
+      'C:\\Program Files (x86)\\WireGuard\\wireguard.exe',
+    ];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  } else {
+    const paths = ['/usr/bin/wg', '/usr/local/bin/wg', '/opt/homebrew/bin/wg'];
+    for (const p of paths) {
+      if (existsSync(p)) return p;
+    }
+  }
+  try {
+    const cmd = process.platform === 'win32' ? 'where wireguard.exe' : 'which wg';
+    const result = execSync(cmd, { encoding: 'utf8', stdio: 'pipe' }).trim();
+    if (result) return result.split('\n')[0];
+  } catch { /* not in PATH */ }
+  return null;
+}
+
+// ─── getEnvironment() ────────────────────────────────────────────────────────
+
+/**
+ * Detect the current environment without changing anything.
+ * Uses comprehensive detection — checks env vars, SDK paths, system paths, PATH.
+ *
+ * @returns {{
+ *   os: string,
+ *   arch: string,
+ *   platform: string,
+ *   nodeVersion: string,
+ *   admin: boolean,
+ *   v2ray: { available: boolean, version: string|null, path: string|null },
+ *   wireguard: { available: boolean, path: string|null, requiresAdmin: true },
+ *   capabilities: string[],
+ *   recommended: string[],
+ * }}
+ */
+export function getEnvironment() {
+  const os = process.platform === 'win32' ? 'windows'
+    : process.platform === 'darwin' ? 'macos'
+    : process.platform === 'linux' ? 'linux'
+    : process.platform;
+
+  // V2Ray: our own comprehensive detection (not just SDK's verifyDependencies)
+  const v2rayPath = findV2Ray();
+  let v2rayVersion = null;
+  if (v2rayPath) {
+    try {
+      const out = execSync(`"${v2rayPath}" version`, { encoding: 'utf8', stdio: 'pipe', timeout: 5000 });
+      const match = out.match(/V2Ray\s+(\d+\.\d+\.\d+)/);
+      v2rayVersion = match ? match[1] : null;
+    } catch { /* version check optional */ }
+  }
+
+  const v2ray = {
+    available: !!v2rayPath,
+    version: v2rayVersion,
+    path: v2rayPath,
+  };
+
+  // WireGuard: our own comprehensive detection
+  const wgPath = findWireGuard();
+  const wireguard = {
+    available: !!wgPath,
+    path: wgPath,
+    requiresAdmin: true,
+  };
+
+  // What this environment can do
+  const capabilities = [];
+  if (v2ray.available) capabilities.push('v2ray');
+  if (wireguard.available && IS_ADMIN) capabilities.push('wireguard');
+  if (wireguard.available && !IS_ADMIN) capabilities.push('wireguard-needs-admin');
+
+  // What we recommend installing
+  const recommended = [];
+  if (!v2ray.available) recommended.push('v2ray — run: node setup.js');
+  if (!wireguard.available && os === 'windows') {
+    recommended.push('wireguard — run setup.js as admin for auto-install');
+  }
+  if (!wireguard.available && os === 'macos') {
+    recommended.push('wireguard — run: brew install wireguard-tools');
+  }
+  if (!wireguard.available && os === 'linux') {
+    recommended.push('wireguard — run: sudo apt install wireguard-tools');
+  }
+  if (wireguard.available && !IS_ADMIN) {
+    recommended.push('run as admin to use WireGuard nodes (faster, more reliable)');
+  }
+
+  return {
+    os,
+    arch: process.arch,
+    platform: `${os}-${process.arch}`,
+    nodeVersion: process.versions.node,
+    admin: IS_ADMIN,
+    v2ray,
+    wireguard,
+    capabilities,
+    recommended,
+  };
+}
+
+// ─── setup() ─────────────────────────────────────────────────────────────────
+
+/**
+ * Full environment setup: check deps, install missing ones, report status.
+ * Runs preflight checks that verify everything needed for a VPN connection.
+ *
+ * Returns a FLAT structure — agents access .os, .v2ray, .wireguard directly.
+ * No nested .environment wrapper to misread.
+ *
+ * @returns {Promise<{
+ *   ready: boolean,
+ *   os: string,
+ *   arch: string,
+ *   platform: string,
+ *   nodeVersion: string,
+ *   admin: boolean,
+ *   v2ray: boolean,
+ *   v2rayVersion: string|null,
+ *   v2rayPath: string|null,
+ *   wireguard: boolean,
+ *   wireguardPath: string|null,
+ *   capabilities: string[],
+ *   recommended: string[],
+ *   preflight: object|null,
+ *   issues: string[],
+ * }>}
+ */
+export async function setup() {
+  const env = getEnvironment();
+  const issues = [];
+
+  // Run preflight checks — pass already-detected V2Ray path to avoid contradiction (BUG-1 fix)
+  let preflightResult = null;
+  try {
+    const preflightOpts = {};
+    if (env.v2ray?.path) preflightOpts.v2rayExePath = env.v2ray.path;
+    preflightResult = await preflight(preflightOpts);
+  } catch (err) {
+    issues.push(`Preflight failed: ${err.message}`);
+  }
+
+  // Check critical requirements
+  const nodeMajor = parseInt(process.versions.node.split('.')[0], 10);
+  if (nodeMajor < 20) {
+    issues.push(`Node.js ${process.versions.node} too old — need >= 20`);
+  }
+
+  if (!env.v2ray.available && !env.wireguard.available) {
+    issues.push('No tunnel protocol available — install V2Ray or WireGuard');
+  }
+
+  if (env.v2ray.available && env.v2ray.version && env.v2ray.version !== V2RAY_VERSION) {
+    issues.push(`V2Ray version ${env.v2ray.version} — need exactly ${V2RAY_VERSION} (5.44.1+ has bugs)`);
+  }
+
+  const ready = issues.length === 0 && env.capabilities.length > 0;
+
+  // Flat return — agent accesses .os, .v2ray, .admin directly
+  return {
+    ready,
+    os: env.os,
+    arch: env.arch,
+    platform: env.platform,
+    nodeVersion: env.nodeVersion,
+    admin: env.admin,
+    v2ray: env.v2ray.available,
+    v2rayVersion: env.v2ray.version,
+    v2rayPath: env.v2ray.path,
+    wireguard: env.wireguard.available,
+    wireguardPath: env.wireguard.path,
+    capabilities: env.capabilities,
+    recommended: env.recommended,
+    preflight: preflightResult,
+    issues,
+    // Backward compat — keep nested .environment for existing consumers
+    environment: env,
+  };
+}

package/ai-path/errors.js

@@ -0,0 +1,86 @@
+/**
+ * Sentinel AI Path — Error Types
+ *
+ * Typed errors with machine-readable codes for AI agent error handling.
+ * Every error includes a `nextAction` field telling the agent what to do.
+ */
+
+// ─── Error Codes ────────────────────────────────────────────────────────────
+
+export const AiPathErrorCodes = {
+  // Wallet
+  MISSING_MNEMONIC: 'MISSING_MNEMONIC',
+  INVALID_MNEMONIC: 'INVALID_MNEMONIC',
+  INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
+
+  // Environment
+  SETUP_FAILED: 'SETUP_FAILED',
+  ENVIRONMENT_NOT_READY: 'ENVIRONMENT_NOT_READY',
+  V2RAY_NOT_FOUND: 'V2RAY_NOT_FOUND',
+  WIREGUARD_NOT_FOUND: 'WIREGUARD_NOT_FOUND',
+  ADMIN_REQUIRED: 'ADMIN_REQUIRED',
+
+  // Connection
+  CONNECT_FAILED: 'CONNECT_FAILED',
+  DISCONNECT_FAILED: 'DISCONNECT_FAILED',
+  ALREADY_CONNECTED: 'ALREADY_CONNECTED',
+  ALL_NODES_FAILED: 'ALL_NODES_FAILED',
+  NO_NODES_IN_COUNTRY: 'NO_NODES_IN_COUNTRY',
+  NODE_OFFLINE: 'NODE_OFFLINE',
+  HANDSHAKE_FAILED: 'HANDSHAKE_FAILED',
+  TUNNEL_FAILED: 'TUNNEL_FAILED',
+  TIMEOUT: 'TIMEOUT',
+
+  // Validation
+  INVALID_OPTIONS: 'INVALID_OPTIONS',
+
+  // Discovery
+  DISCOVERY_FAILED: 'DISCOVERY_FAILED',
+  WALLET_FAILED: 'WALLET_FAILED',
+  BALANCE_FAILED: 'BALANCE_FAILED',
+  VERIFY_FAILED: 'VERIFY_FAILED',
+};
+
+// ─── Next Actions (machine-readable) ────────────────────────────────────────
+
+export const NextActions = {
+  CREATE_WALLET: 'create_wallet',
+  FUND_WALLET: 'fund_wallet',
+  RUN_SETUP: 'run_setup',
+  RUN_AS_ADMIN: 'run_as_admin',
+  TRY_DIFFERENT_NODE: 'try_different_node',
+  TRY_DIFFERENT_COUNTRY: 'try_different_country',
+  TRY_V2RAY: 'try_v2ray',
+  TRY_WIREGUARD: 'try_wireguard',
+  DISCONNECT_FIRST: 'disconnect',
+  RETRY: 'retry',
+  NONE: 'none',
+};
+
+// ─── Error Class ────────────────────────────────────────────────────────────
+
+export class AiPathError extends Error {
+  /**
+   * @param {string} code - Machine-readable error code from AiPathErrorCodes
+   * @param {string} message - Human-readable message
+   * @param {object} [details] - Extra context for the agent
+   * @param {string} [nextAction] - What the agent should do next (from NextActions)
+   */
+  constructor(code, message, details = null, nextAction = NextActions.RETRY) {
+    super(message);
+    this.name = 'AiPathError';
+    this.code = code;
+    this.details = details;
+    this.nextAction = nextAction;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      details: this.details,
+      nextAction: this.nextAction,
+    };
+  }
+}