blue-js-sdk 2.0.0

package/errors.js

@@ -0,0 +1,218 @@
+/**
+ * Sentinel SDK — Typed Error Classes
+ *
+ * Machine-readable error codes for programmatic error handling.
+ * All SDK errors extend SentinelError with a .code property.
+ *
+ * Usage:
+ *   import { SentinelError, ErrorCodes } from './errors.js';
+ *   try { await connect(opts); }
+ *   catch (e) {
+ *     if (e.code === ErrorCodes.V2RAY_ALL_FAILED) trySwitchNode();
+ *     if (e instanceof ValidationError) showFormError(e.message);
+ *   }
+ */
+
+export class SentinelError extends Error {
+  /**
+   * @param {string} code - Machine-readable error code (e.g. 'NODE_NO_UDVPN')
+   * @param {string} message - Human-readable description
+   * @param {object} details - Structured context for programmatic handling
+   */
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'SentinelError';
+    this.code = code;
+    this.details = details;
+  }
+
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message, details: this.details };
+  }
+}
+
+/** Input validation failures (bad mnemonic, invalid address, etc.) */
+export class ValidationError extends SentinelError {
+  constructor(code, message, details) {
+    super(code, message, details);
+    this.name = 'ValidationError';
+  }
+}
+
+/** Node-level failures (offline, no udvpn, clock drift, etc.) */
+export class NodeError extends SentinelError {
+  constructor(code, message, details) {
+    super(code, message, details);
+    this.name = 'NodeError';
+  }
+}
+
+/** Chain/transaction failures (broadcast failed, extract failed, etc.) */
+export class ChainError extends SentinelError {
+  constructor(code, message, details) {
+    super(code, message, details);
+    this.name = 'ChainError';
+  }
+}
+
+/** Tunnel setup failures (V2Ray all failed, WG no connectivity, etc.) */
+export class TunnelError extends SentinelError {
+  constructor(code, message, details) {
+    super(code, message, details);
+    this.name = 'TunnelError';
+  }
+}
+
+/** Security failures (TLS cert changed, etc.) */
+export class SecurityError extends SentinelError {
+  constructor(code, message, details) {
+    super(code, message, details);
+    this.name = 'SecurityError';
+  }
+}
+
+/** Error code constants — use these for switch/if checks instead of string parsing */
+export const ErrorCodes = {
+  // Validation
+  INVALID_OPTIONS: 'INVALID_OPTIONS',
+  INVALID_MNEMONIC: 'INVALID_MNEMONIC',
+  INVALID_NODE_ADDRESS: 'INVALID_NODE_ADDRESS',
+  INVALID_GIGABYTES: 'INVALID_GIGABYTES',
+  INVALID_URL: 'INVALID_URL',
+  INVALID_PLAN_ID: 'INVALID_PLAN_ID',
+
+  // Node
+  NODE_OFFLINE: 'NODE_OFFLINE',
+  NODE_NO_UDVPN: 'NODE_NO_UDVPN',
+  NODE_NOT_FOUND: 'NODE_NOT_FOUND',
+  NODE_CLOCK_DRIFT: 'NODE_CLOCK_DRIFT',
+  NODE_INACTIVE: 'NODE_INACTIVE',
+
+  // Chain
+  INSUFFICIENT_BALANCE: 'INSUFFICIENT_BALANCE',
+  BROADCAST_FAILED: 'BROADCAST_FAILED',
+  TX_FAILED: 'TX_FAILED',
+  LCD_ERROR: 'LCD_ERROR',
+  UNKNOWN_MSG_TYPE: 'UNKNOWN_MSG_TYPE',
+  ALL_ENDPOINTS_FAILED: 'ALL_ENDPOINTS_FAILED',
+
+  // Session
+  SESSION_EXISTS: 'SESSION_EXISTS',
+  SESSION_EXTRACT_FAILED: 'SESSION_EXTRACT_FAILED',
+  SESSION_POISONED: 'SESSION_POISONED',
+
+  // Tunnel
+  V2RAY_NOT_FOUND: 'V2RAY_NOT_FOUND',
+  V2RAY_ALL_FAILED: 'V2RAY_ALL_FAILED',
+  WG_NOT_AVAILABLE: 'WG_NOT_AVAILABLE',
+  WG_NO_CONNECTIVITY: 'WG_NO_CONNECTIVITY',
+  TUNNEL_SETUP_FAILED: 'TUNNEL_SETUP_FAILED',
+
+  // Security
+  TLS_CERT_CHANGED: 'TLS_CERT_CHANGED',
+
+  // Node (additional)
+  INVALID_ASSIGNED_IP: 'INVALID_ASSIGNED_IP',
+  NODE_DATABASE_CORRUPT: 'NODE_DATABASE_CORRUPT',
+
+  // Connection
+  ABORTED: 'ABORTED',
+  ALL_NODES_FAILED: 'ALL_NODES_FAILED',
+  ALREADY_CONNECTED: 'ALREADY_CONNECTED',
+  PARTIAL_CONNECTION_FAILED: 'PARTIAL_CONNECTION_FAILED',
+
+  // Chain timing
+  CHAIN_LAG: 'CHAIN_LAG',
+};
+
+// ─── Error Severity Classification ───────────────────────────────────────────
+
+/** Severity levels for each error code. Apps use this for retry/UX logic. */
+export const ERROR_SEVERITY = {
+  // Fatal — don't retry, user action needed
+  [ErrorCodes.INVALID_MNEMONIC]: 'fatal',
+  [ErrorCodes.INSUFFICIENT_BALANCE]: 'fatal',
+  [ErrorCodes.INVALID_NODE_ADDRESS]: 'fatal',
+  [ErrorCodes.INVALID_OPTIONS]: 'fatal',
+  [ErrorCodes.INVALID_GIGABYTES]: 'fatal',
+  [ErrorCodes.INVALID_URL]: 'fatal',
+  [ErrorCodes.INVALID_PLAN_ID]: 'fatal',
+  [ErrorCodes.UNKNOWN_MSG_TYPE]: 'fatal',
+  [ErrorCodes.SESSION_POISONED]: 'fatal',
+  [ErrorCodes.WG_NOT_AVAILABLE]: 'fatal',
+  [ErrorCodes.NODE_DATABASE_CORRUPT]: 'retryable',
+
+  // Retryable — node-level
+  [ErrorCodes.NODE_NOT_FOUND]: 'retryable',
+
+  // Retryable — try again, possibly different node
+  [ErrorCodes.NODE_OFFLINE]: 'retryable',
+  [ErrorCodes.NODE_NO_UDVPN]: 'retryable',
+  [ErrorCodes.NODE_CLOCK_DRIFT]: 'retryable',
+  [ErrorCodes.NODE_INACTIVE]: 'retryable',
+  [ErrorCodes.V2RAY_ALL_FAILED]: 'retryable',
+  [ErrorCodes.BROADCAST_FAILED]: 'retryable',
+  [ErrorCodes.TX_FAILED]: 'retryable',
+  [ErrorCodes.LCD_ERROR]: 'retryable',
+  [ErrorCodes.ALL_ENDPOINTS_FAILED]: 'retryable',
+  [ErrorCodes.ALL_NODES_FAILED]: 'retryable',
+  [ErrorCodes.WG_NO_CONNECTIVITY]: 'retryable',
+  [ErrorCodes.TUNNEL_SETUP_FAILED]: 'retryable',
+  [ErrorCodes.CHAIN_LAG]: 'retryable',
+
+  // Recoverable — can resume with recoverSession()
+  [ErrorCodes.SESSION_EXTRACT_FAILED]: 'recoverable',
+  [ErrorCodes.PARTIAL_CONNECTION_FAILED]: 'recoverable',
+  [ErrorCodes.SESSION_EXISTS]: 'recoverable',
+
+  // Infrastructure — check system state
+  [ErrorCodes.TLS_CERT_CHANGED]: 'infrastructure',
+  [ErrorCodes.V2RAY_NOT_FOUND]: 'infrastructure',
+};
+
+/** Check if an error should be retried. */
+export function isRetryable(error) {
+  const code = error?.code || error;
+  return ERROR_SEVERITY[code] === 'retryable';
+}
+
+/** Map SDK error to user-friendly message. */
+export function userMessage(error) {
+  const code = error?.code || error;
+  const map = {
+    [ErrorCodes.INSUFFICIENT_BALANCE]: 'Not enough P2P tokens. Fund your wallet to continue.',
+    [ErrorCodes.NODE_OFFLINE]: 'This node is offline. Try a different server.',
+    [ErrorCodes.NODE_NO_UDVPN]: 'This node does not accept P2P tokens.',
+    [ErrorCodes.NODE_CLOCK_DRIFT]: 'Node clock is out of sync. Try a different server.',
+    [ErrorCodes.NODE_INACTIVE]: 'Node went inactive. Try a different server.',
+    [ErrorCodes.V2RAY_ALL_FAILED]: 'Could not establish tunnel. Node may be overloaded.',
+    [ErrorCodes.V2RAY_NOT_FOUND]: 'V2Ray binary not found. Check your installation.',
+    [ErrorCodes.WG_NOT_AVAILABLE]: 'WireGuard is not available. Install it or use V2Ray nodes.',
+    [ErrorCodes.WG_NO_CONNECTIVITY]: 'VPN tunnel has no internet connectivity.',
+    [ErrorCodes.TUNNEL_SETUP_FAILED]: 'Tunnel setup failed. Try again or pick another server.',
+    [ErrorCodes.TLS_CERT_CHANGED]: 'Node certificate changed unexpectedly. This could indicate a security issue.',
+    [ErrorCodes.BROADCAST_FAILED]: 'Transaction failed. Check your balance and try again.',
+    [ErrorCodes.TX_FAILED]: 'Chain transaction rejected. Check balance and gas.',
+    [ErrorCodes.ALREADY_CONNECTED]: 'Already connected. Disconnect first.',
+    [ErrorCodes.ALL_NODES_FAILED]: 'All servers failed. Check your network connection.',
+    [ErrorCodes.ALL_ENDPOINTS_FAILED]: 'All chain endpoints are unreachable. Try again later.',
+    [ErrorCodes.INVALID_MNEMONIC]: 'Invalid wallet phrase. Must be 12 or 24 words.',
+    [ErrorCodes.INVALID_NODE_ADDRESS]: 'Invalid node address.',
+    [ErrorCodes.INVALID_OPTIONS]: 'Invalid connection options provided.',
+    [ErrorCodes.INVALID_GIGABYTES]: 'Invalid bandwidth amount. Must be a positive number.',
+    [ErrorCodes.INVALID_URL]: 'Invalid URL format.',
+    [ErrorCodes.INVALID_PLAN_ID]: 'Invalid plan ID.',
+    [ErrorCodes.UNKNOWN_MSG_TYPE]: 'Unknown message type. Check SDK version compatibility.',
+    [ErrorCodes.SESSION_POISONED]: 'Session is poisoned (previously failed). Start a new session.',
+    [ErrorCodes.NODE_NOT_FOUND]: 'Node not found on chain. It may be inactive.',
+    [ErrorCodes.LCD_ERROR]: 'Chain query failed. Try again later.',
+    [ErrorCodes.SESSION_EXISTS]: 'An active session already exists. Use recoverSession() to resume.',
+    [ErrorCodes.SESSION_EXTRACT_FAILED]: 'Session creation succeeded but ID extraction failed. Use recoverSession().',
+    [ErrorCodes.PARTIAL_CONNECTION_FAILED]: 'Payment succeeded but connection failed. Use recoverSession() to retry.',
+    [ErrorCodes.ABORTED]: 'Connection was cancelled.',
+    [ErrorCodes.CHAIN_LAG]: 'Session not yet confirmed on node. Wait a moment and try again.',
+    [ErrorCodes.NODE_DATABASE_CORRUPT]: 'Node has a corrupted database. Try a different server.',
+    [ErrorCodes.INVALID_ASSIGNED_IP]: 'Node returned an invalid IP address during handshake. Try a different server.',
+  };
+  return map[code] || error?.message || 'An unexpected error occurred.';
+}

package/examples/README.md

@@ -0,0 +1,64 @@
+# Sentinel dVPN SDK Examples
+
+Runnable examples showing how to use the SDK. Each file is self-contained.
+
+## Prerequisites
+
+- Node.js 18+
+- `npm install sentinel-dvpn-sdk`
+- For wallet/connection examples: set `MNEMONIC` environment variable (12 or 24-word BIP39 phrase)
+- For WireGuard nodes: run as admin/root. Without admin, only V2Ray nodes are available (~70% of the network).
+
+## Examples
+
+| File | Description | Needs Wallet? |
+|------|-------------|:---:|
+| `connect-direct.mjs` | Complete VPN flow: wallet, balance, find nodes, connect, verify IP, disconnect | Yes |
+| `query-nodes.mjs` | Browse nodes, filter by country/protocol/price, display table | No |
+| `wallet-basics.mjs` | Generate a new wallet or import existing, check balance | Optional |
+| `connect-plan.mjs` | Connect via a subscription plan (operator-managed node bundles) | Yes |
+| `error-handling.mjs` | Typed error codes, severity levels, retry logic patterns | Yes |
+
+## Quick Start
+
+```bash
+# Browse the network (no wallet needed)
+node query-nodes.mjs
+node query-nodes.mjs --country germany --protocol wireguard
+
+# Generate a new wallet
+node wallet-basics.mjs
+
+# Check balance of an existing wallet
+MNEMONIC="your twelve word phrase here ..." node wallet-basics.mjs
+
+# Connect to VPN (simplest)
+MNEMONIC="your twelve word phrase here ..." node connect-direct.mjs
+
+# Connect to a specific country
+MNEMONIC="your twelve word phrase here ..." node connect-direct.mjs --country finland
+
+# Connect via a plan
+MNEMONIC="your twelve word phrase here ..." node connect-plan.mjs --plan-id 42
+
+# Explore error handling
+MNEMONIC="your twelve word phrase here ..." node error-handling.mjs
+```
+
+## Token Info
+
+- Display name: **P2P**
+- Chain denom: `udvpn` (micro denomination)
+- 1 P2P = 1,000,000 udvpn
+- Typical session cost: ~0.04-0.15 P2P per GB
+- Minimum recommended balance: 1 P2P
+
+## Key Concepts
+
+**connectAuto vs connectDirect**: `connectAuto` scans nodes, filters, retries on failure. `connectDirect` connects to one specific node address. Start with `connectAuto`.
+
+**WireGuard vs V2Ray**: WireGuard is faster but requires admin. V2Ray works without admin and supports more transport types. The SDK picks the best available.
+
+**Plans vs Direct**: Direct connections pay per GB/hour to individual nodes. Plans are operator bundles with fixed pricing and optional fee grants (operator pays gas for subscribers).
+
+**Error severity**: `fatal` = user must fix, `retryable` = try another node, `recoverable` = call `recoverSession()`, `infrastructure` = check system setup.

package/examples/connect-direct.mjs

@@ -0,0 +1,106 @@
+/**
+ * connect-direct.mjs — Connect to Sentinel dVPN in ~60 lines
+ *
+ * The complete flow: wallet -> balance check -> find nodes -> connect -> verify -> disconnect.
+ * Uses connectAuto() which handles node selection, retries, and fallback automatically.
+ *
+ * Prerequisites:
+ *   - Node.js 18+
+ *   - npm install sentinel-dvpn-sdk
+ *   - Set MNEMONIC env var (12 or 24-word BIP39 phrase)
+ *   - Run as admin/root for WireGuard support (otherwise V2Ray nodes only)
+ *
+ * Usage:
+ *   MNEMONIC="word1 word2 ... word12" node connect-direct.mjs
+ *   MNEMONIC="word1 word2 ..." node connect-direct.mjs --country germany
+ */
+
+import {
+  createWallet,
+  getBalance,
+  createClient,
+  formatP2P,
+  connectAuto,
+  disconnect,
+  verifyConnection,
+  registerCleanupHandlers,
+  queryOnlineNodes,
+  filterNodes,
+  DEFAULT_RPC,
+  DEFAULT_LCD,
+} from 'sentinel-dvpn-sdk';
+
+const MNEMONIC = process.env.MNEMONIC;
+if (!MNEMONIC) {
+  console.error('Set MNEMONIC environment variable (12 or 24 BIP39 words)');
+  process.exit(1);
+}
+
+// Parse optional --country flag
+const countryArg = process.argv.includes('--country')
+  ? process.argv[process.argv.indexOf('--country') + 1]
+  : null;
+
+async function main() {
+  // 1. Register cleanup handlers (ensures VPN tunnel is torn down on exit)
+  registerCleanupHandlers();
+
+  // 2. Create wallet from mnemonic
+  const { account } = await createWallet(MNEMONIC);
+  console.log(`Wallet: ${account.address}`);
+
+  // 3. Check balance
+  const client = await createClient(MNEMONIC);
+  const balance = await getBalance(client, account.address);
+  console.log(`Balance: ${formatP2P(balance.udvpn)}`);
+
+  if (balance.udvpn < 1_000_000) {
+    console.error('Insufficient balance. Need at least 1 P2P (~1,000,000 udvpn).');
+    process.exit(1);
+  }
+
+  // 4. Preview available nodes (optional — connectAuto does this internally)
+  const nodes = await queryOnlineNodes({ maxNodes: 20 });
+  const filtered = countryArg ? filterNodes(nodes, { country: countryArg }) : nodes;
+  console.log(`Found ${filtered.length} nodes${countryArg ? ` in ${countryArg}` : ''}`);
+  for (const n of filtered.slice(0, 5)) {
+    console.log(`  ${n.address.slice(0, 20)}... | ${n.country || '?'} | ${n.serviceType} | score: ${n.qualityScore}`);
+  }
+
+  // 5. Connect — handles node selection, payment, handshake, and tunnel setup
+  console.log('\nConnecting...');
+  const result = await connectAuto({
+    mnemonic: MNEMONIC,
+    countries: countryArg ? [countryArg] : undefined,
+    maxAttempts: 3,
+    gigabytes: 1,
+    log: (msg) => console.log(msg),
+    onProgress: (step, detail) => console.log(`  [${step}] ${detail}`),
+  });
+
+  console.log(`\nConnected to ${result.nodeAddress}`);
+  console.log(`  Session ID: ${result.sessionId}`);
+  console.log(`  Protocol: ${result.protocol}`);
+
+  // 6. Verify VPN is working (check external IP)
+  const check = await verifyConnection();
+  if (check.working) {
+    console.log(`  VPN IP: ${check.vpnIp}`);
+  } else {
+    console.warn('  IP check failed — tunnel may still be working');
+  }
+
+  // 7. Keep connected for 30 seconds, then disconnect
+  console.log('\nVPN active. Press Ctrl+C to disconnect (auto-disconnect in 30s)...');
+  await new Promise((r) => setTimeout(r, 30_000));
+
+  // 8. Disconnect cleanly (ends session on-chain, tears down tunnel)
+  await disconnect();
+  console.log('Disconnected.');
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  if (err.code) console.error(`  Code: ${err.code}`);
+  process.exit(1);
+});

package/examples/connect-plan.mjs

@@ -0,0 +1,125 @@
+/**
+ * connect-plan.mjs — Connect to Sentinel dVPN via a subscription plan
+ *
+ * Plans are created by operators who bundle nodes at a fixed rate.
+ * Subscribers get access to all nodes in the plan. Operators can pay gas
+ * on behalf of subscribers via fee grants (making it free for end users).
+ *
+ * Prerequisites:
+ *   - Node.js 18+
+ *   - npm install sentinel-dvpn-sdk
+ *   - Set MNEMONIC env var
+ *   - Run as admin/root for WireGuard support
+ *
+ * Usage:
+ *   MNEMONIC="word1 word2 ..." node connect-plan.mjs                 # Auto-discover plans
+ *   MNEMONIC="word1 word2 ..." node connect-plan.mjs --plan-id 42    # Specific plan
+ */
+
+import {
+  createWallet,
+  createClient,
+  getBalance,
+  formatP2P,
+  discoverPlans,
+  queryPlanNodes,
+  connectViaPlan,
+  disconnect,
+  verifyConnection,
+  registerCleanupHandlers,
+  formatPriceP2P,
+  DEFAULT_LCD,
+} from 'sentinel-dvpn-sdk';
+
+const MNEMONIC = process.env.MNEMONIC;
+if (!MNEMONIC) {
+  console.error('Set MNEMONIC environment variable (12 or 24 BIP39 words)');
+  process.exit(1);
+}
+
+const planIdArg = process.argv.includes('--plan-id')
+  ? process.argv[process.argv.indexOf('--plan-id') + 1]
+  : null;
+
+async function main() {
+  registerCleanupHandlers();
+
+  // 1. Wallet and balance
+  const { account } = await createWallet(MNEMONIC);
+  const client = await createClient(MNEMONIC);
+  const balance = await getBalance(client, account.address);
+  console.log(`Wallet: ${account.address} | Balance: ${formatP2P(balance.udvpn)}\n`);
+
+  let planId;
+  let nodeAddress;
+
+  if (planIdArg) {
+    // 2a. Use the specified plan
+    planId = parseInt(planIdArg, 10);
+    console.log(`Using plan ${planId}`);
+  } else {
+    // 2b. Discover available plans
+    console.log('Discovering plans (probing IDs 1-100, may take 10-20s)...');
+    const plans = await discoverPlans(DEFAULT_LCD, { maxId: 100 });
+
+    if (plans.length === 0) {
+      console.error('No plans found. Try a specific plan ID with --plan-id.');
+      process.exit(1);
+    }
+
+    // Show available plans
+    console.log(`\nFound ${plans.length} plans:\n`);
+    console.log('  ID'.padEnd(8), 'Subscribers'.padEnd(14), 'Nodes'.padEnd(8), 'Price');
+    console.log('  ' + '-'.repeat(50));
+    for (const p of plans) {
+      const price = p.price ? `${formatPriceP2P(p.price.amount || '0')} P2P` : 'N/A';
+      console.log(
+        `  ${String(p.id).padEnd(8)}${String(p.subscribers).padEnd(14)}${String(p.nodeCount).padEnd(8)}${price}`,
+      );
+    }
+
+    // Pick the plan with the most nodes
+    const best = plans.sort((a, b) => b.nodeCount - a.nodeCount)[0];
+    planId = best.id;
+    console.log(`\nSelected plan ${planId} (${best.nodeCount} nodes, ${best.subscribers} subscribers)`);
+  }
+
+  // 3. Get nodes in the plan
+  const { items: planNodes } = await queryPlanNodes(planId);
+  if (planNodes.length === 0) {
+    console.error(`Plan ${planId} has no nodes. Try a different plan.`);
+    process.exit(1);
+  }
+  nodeAddress = planNodes[0].address;
+  console.log(`Plan has ${planNodes.length} nodes. Connecting to ${nodeAddress}...`);
+
+  // 4. Connect via the plan
+  const result = await connectViaPlan({
+    mnemonic: MNEMONIC,
+    planId,
+    nodeAddress,
+    log: (msg) => console.log(msg),
+    onProgress: (step, detail) => console.log(`  [${step}] ${detail}`),
+  });
+
+  console.log(`\nConnected via plan ${planId}`);
+  console.log(`  Session: ${result.sessionId}`);
+  console.log(`  Protocol: ${result.protocol}`);
+
+  // 5. Verify
+  const check = await verifyConnection();
+  if (check.working) console.log(`  VPN IP: ${check.vpnIp}`);
+
+  // 6. Stay connected
+  console.log('\nVPN active. Press Ctrl+C to disconnect (auto-disconnect in 30s)...');
+  await new Promise((r) => setTimeout(r, 30_000));
+
+  await disconnect();
+  console.log('Disconnected.');
+}
+
+main().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  if (err.code) console.error(`  Code: ${err.code}`);
+  process.exit(1);
+});

package/examples/error-handling.mjs

@@ -0,0 +1,109 @@
+/**
+ * error-handling.mjs — Typed error handling with the Sentinel SDK
+ *
+ * The SDK uses typed errors with machine-readable codes, severity levels,
+ * and user-friendly messages. This example shows how to handle errors
+ * programmatically instead of just catching strings.
+ *
+ * Usage:
+ *   MNEMONIC="word1 word2 ..." node error-handling.mjs
+ */
+
+import {
+  SentinelError,
+  ValidationError,
+  NodeError,
+  ChainError,
+  TunnelError,
+  ErrorCodes,
+  ERROR_SEVERITY,
+  isRetryable,
+  userMessage,
+  connectAuto,
+  registerCleanupHandlers,
+  disconnect,
+} from 'sentinel-dvpn-sdk';
+
+const MNEMONIC = process.env.MNEMONIC;
+if (!MNEMONIC) {
+  console.error('Set MNEMONIC environment variable');
+  process.exit(1);
+}
+
+// --- Show the error taxonomy ---
+console.log('Sentinel SDK Error Codes:\n');
+console.log('  Code'.padEnd(32), 'Severity'.padEnd(16), 'Retryable?');
+console.log('  ' + '-'.repeat(60));
+for (const [name, code] of Object.entries(ErrorCodes)) {
+  const severity = ERROR_SEVERITY[code] || 'unknown';
+  const retry = isRetryable(code) ? 'yes' : 'no';
+  console.log(`  ${code.padEnd(32)}${severity.padEnd(16)}${retry}`);
+}
+
+// --- Demonstrate real error handling ---
+console.log('\n\nAttempting connection with full error handling...\n');
+
+async function main() {
+  registerCleanupHandlers();
+
+  try {
+    const result = await connectAuto({
+      mnemonic: MNEMONIC,
+      maxAttempts: 2,
+      log: (msg) => console.log(msg),
+    });
+    console.log(`Connected to ${result.nodeAddress}`);
+    await disconnect();
+  } catch (err) {
+    // 1. Check if it is a typed SDK error
+    if (!(err instanceof SentinelError)) {
+      console.error('Unexpected error (not from SDK):', err.message);
+      return;
+    }
+
+    // 2. Use the error code for programmatic handling
+    console.log(`SDK Error: ${err.code}`);
+    console.log(`  Class:    ${err.constructor.name}`);
+    console.log(`  Message:  ${err.message}`);
+    console.log(`  Severity: ${ERROR_SEVERITY[err.code] || 'unknown'}`);
+    console.log(`  User msg: ${userMessage(err)}`);
+
+    // 3. Severity-based logic
+    const severity = ERROR_SEVERITY[err.code];
+
+    if (severity === 'fatal') {
+      // User must fix something (bad mnemonic, no balance, etc.)
+      console.log('\n  Action: Show error to user, do not retry.');
+    } else if (severity === 'retryable') {
+      // Transient failure — try again with a different node
+      console.log('\n  Action: Retry with a different node or wait and try again.');
+    } else if (severity === 'recoverable') {
+      // Partial success — session exists but tunnel failed
+      console.log('\n  Action: Call recoverSession() to resume without re-paying.');
+    } else if (severity === 'infrastructure') {
+      // System-level issue (missing binary, cert mismatch)
+      console.log('\n  Action: Check system dependencies.');
+    }
+
+    // 4. Type-specific handling
+    if (err instanceof ValidationError) {
+      console.log('\n  Input validation failed. Check your parameters.');
+    } else if (err instanceof NodeError) {
+      console.log(`\n  Node-level issue. Details: ${JSON.stringify(err.details)}`);
+    } else if (err instanceof ChainError) {
+      console.log('\n  Chain/transaction issue. Check balance and gas.');
+    } else if (err instanceof TunnelError) {
+      console.log('\n  Tunnel setup failed. Try another node or check WireGuard/V2Ray.');
+    }
+
+    // 5. Structured details are always available
+    if (Object.keys(err.details).length > 0) {
+      console.log(`\n  Details: ${JSON.stringify(err.details, null, 2)}`);
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Unhandled:', err);
+  process.exit(1);
+});