blue-js-sdk 2.0.0

package/types/nodes.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Sentinel SDK — Node Types
+ *
+ * Types for querying, filtering, scoring, and displaying Sentinel dVPN nodes.
+ * Covers: online node queries, node enrichment, geographic indexing,
+ * node filtering, and display-ready objects for UI rendering.
+ */
+
+import type { PriceEntry, ChainNode } from './chain.js';
+
+// ─── Node Query Options ────────────────────────────────────────────────────
+
+/** Options for queryOnlineNodes() / listNodes(). */
+export interface ListNodesOptions {
+  /** LCD URL (default: cascading fallback across 4 endpoints) */
+  lcdUrl?: string;
+  /**
+   * Maximum nodes to probe for status (default: 100).
+   * Set higher to discover more of the network (900+ active nodes total).
+   */
+  maxNodes?: number;
+  /** Filter by service type (null = all) */
+  serviceType?: 'wireguard' | 'v2ray' | null;
+  /** Concurrency for node probing (default: 30) */
+  concurrency?: number;
+  /** Progress callback: called after each batch of nodes is probed */
+  onNodeProbed?: (progress: NodeProbeProgress) => void;
+  /** Skip quality-score sorting (default: false) */
+  skipSort?: boolean;
+  /** Bypass 5-minute node cache and force fresh scan (default: false) */
+  noCache?: boolean;
+  /** Skip cache entirely and wait for fresh results (default: false) */
+  waitForFresh?: boolean;
+}
+
+/** Progress callback data for node probing. */
+export interface NodeProbeProgress {
+  /** Total nodes to probe */
+  total: number;
+  /** Nodes probed so far */
+  probed: number;
+  /** Nodes found online so far */
+  online: number;
+}
+
+/** Options for enrichNodes(). */
+export interface EnrichNodesOptions {
+  /** Concurrency for status probes (default: 30) */
+  concurrency?: number;
+  /** Per-node probe timeout in ms (default: 8000) */
+  timeout?: number;
+  /** Progress callback */
+  onProgress?: (progress: { total: number; done: number; enriched: number }) => void;
+}
+
+// ─── Scored Node ───────────────────────────────────────────────────────────
+
+/**
+ * Node with quality scoring applied. Returned by queryOnlineNodes() and enrichNodes().
+ * Sorted by qualityScore (highest first).
+ */
+export interface ScoredNode {
+  /** sentnode1... address */
+  address: string;
+  /** Node's HTTPS remote URL */
+  remoteUrl: string;
+  /** Service type: 'wireguard' or 'v2ray' */
+  serviceType: string;
+  /** Node display name */
+  moniker: string;
+  /** Country name (as reported by node) */
+  country: string;
+  /** City name */
+  city: string;
+  /** Current peer count */
+  peers: number;
+  /**
+   * Clock drift in seconds (null if unknown).
+   * Nodes with |drift| > 120s are penalized (VMess breaks).
+   */
+  clockDriftSec: number | null;
+  /**
+   * Quality score 0-100. Higher is better.
+   * Factors: WG preferred over V2Ray, low peers, low drift, udvpn pricing.
+   */
+  qualityScore: number;
+  /** Per-GB pricing entries from LCD */
+  gigabytePrices: PriceEntry[];
+  /** Per-hour pricing entries from LCD */
+  hourlyPrices: PriceEntry[];
+}
+
+// ─── Node Filter ───────────────────────────────────────────────────────────
+
+/** Criteria for filterNodes(). All fields are optional (AND logic). */
+export interface NodeFilter {
+  /** Filter by country name or ISO code */
+  country?: string;
+  /** Filter by service type */
+  serviceType?: 'wireguard' | 'v2ray';
+  /** Maximum price in P2P per GB */
+  maxPriceDvpn?: number;
+  /** Minimum quality score (0-100) */
+  minScore?: number;
+}
+
+// ─── Node Score ────────────────────────────────────────────────────────────
+
+/** Standardized price extraction result from getNodePrices(). */
+export interface NodePrices {
+  /** Per-GB pricing */
+  gigabyte: {
+    /** Price in whole P2P tokens */
+    dvpn: number;
+    /** Price in micro-denom (udvpn) */
+    udvpn: number;
+    /** Raw chain price object (null if node has no GB pricing) */
+    raw: PriceEntry | null;
+  };
+  /** Per-hour pricing */
+  hourly: {
+    /** Price in whole P2P tokens */
+    dvpn: number;
+    /** Price in micro-denom (udvpn) */
+    udvpn: number;
+    /** Raw chain price object (null if node has no hourly pricing) */
+    raw: PriceEntry | null;
+  };
+  /** Token denomination (always 'udvpn') */
+  denom: string;
+  /** sentnode1... address */
+  nodeAddress: string;
+}
+
+// ─── Geographic Index ──────────────────────────────────────────────────────
+
+/** Geographic index from buildNodeIndex(). Enables instant country/city lookups. */
+export interface NodeIndex {
+  /** Nodes grouped by country name */
+  countries: Record<string, ScoredNode[]>;
+  /** Nodes grouped by city name */
+  cities: Record<string, ScoredNode[]>;
+  /** Summary statistics */
+  stats: {
+    totalNodes: number;
+    totalCountries: number;
+    totalCities: number;
+    byCountry: Array<{ country: string; count: number }>;
+  };
+}
+
+// ─── Network Overview ──────────────────────────────────────────────────────
+
+/** Network overview from getNetworkOverview(). Perfect for dashboards. */
+export interface NetworkOverview {
+  /** Total active nodes on the network */
+  totalNodes: number;
+  /** Node count by country */
+  byCountry: Array<{ country: string; count: number }>;
+  /** Node count by service type */
+  byType: {
+    wireguard: number;
+    v2ray: number;
+    unknown: number;
+  };
+  /** Average prices across all nodes */
+  averagePrice: {
+    /** Average per-GB price in P2P tokens */
+    gigabyteDvpn: number;
+    /** Average per-hour price in P2P tokens */
+    hourlyDvpn: number;
+  };
+  /** Raw node data */
+  nodes: unknown[];
+}
+
+// ─── Broken Nodes ──────────────────────────────────────────────────────────
+
+/** Known broken node entry from BROKEN_NODES blacklist. */
+export interface BrokenNode {
+  /** sentnode1... address */
+  address: string;
+  /** Reason the node is broken */
+  reason: string;
+  /** Date when the node was verified broken */
+  verified: string;
+}

package/types/pricing.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Sentinel SDK — Pricing & Display Types
+ *
+ * Types for pricing display, cost estimation, country mapping,
+ * and UI builder helpers. These are NOT protocol functions --
+ * they're UX helpers that every consumer app needs.
+ */
+
+import type { PriceEntry } from './chain.js';
+
+// ─── Price Display ─────────────────────────────────────────────────────────
+
+/** Formatted node pricing for UI display. From formatNodePricing(). */
+export interface NodePricingDisplay {
+  /** Per-GB price string (e.g. '0.04 P2P/GB') or null if no GB pricing */
+  perGb: string | null;
+  /** Per-hour price string (e.g. '0.02 P2P/hr') or null if no hourly pricing */
+  perHour: string | null;
+  /** Which pricing model is cheaper (null if only one model available) */
+  cheapest: 'gb' | 'hour' | null;
+  /** Raw per-GB price in micro-denom (null if unavailable) */
+  gbRaw: number | null;
+  /** Raw per-hour price in micro-denom (null if unavailable) */
+  hrRaw: number | null;
+}
+
+/** Session cost estimate from estimateSessionPrice(). */
+export interface SessionPriceEstimate {
+  /** Formatted cost string (e.g. '0.20 P2P') or 'N/A' if pricing unavailable */
+  cost: string;
+  /** Cost in micro-denom (0 if unavailable) */
+  costUdvpn: number;
+  /** Pricing model used */
+  model: 'gb' | 'hour';
+  /** Amount (GB or hours) */
+  amount: number;
+  /** Unit label ('GB' or 'hours') */
+  unit: string;
+}
+
+// ─── Country Info ──────────────────────────────────────────────────────────
+
+/**
+ * Country name to ISO 3166-1 alpha-2 code map.
+ * Includes 80+ countries with standard names, chain variants
+ * (e.g. 'The Netherlands', 'Turkiye'), and short codes.
+ */
+export type CountryMap = Readonly<Record<string, string>>;
+
+// ─── Node Display ──────────────────────────────────────────────────────────
+
+/** Display-ready node object from buildNodeDisplay(). Ready for UI rendering. */
+export interface NodeDisplay {
+  /** sentnode1... address */
+  address: string;
+  /** Node display name (null if not probed) */
+  moniker: string | null;
+  /** Country name (null if not probed) */
+  country: string | null;
+  /** ISO 3166-1 alpha-2 country code (null if unknown) */
+  countryCode: string | null;
+  /** City name (null if not probed) */
+  city: string | null;
+  /** Flag image URL from flagcdn.com (null if no country code) */
+  flagUrl: string | null;
+  /** Emoji flag for web display (empty string if no country code) */
+  flagEmoji: string;
+  /** Service type string (null if not probed) */
+  serviceType: string | null;
+  /** Short protocol label for UI: 'WG' | 'V2' | null */
+  protocol: 'WG' | 'V2' | null;
+  /** Formatted pricing from formatNodePricing() */
+  pricing: NodePricingDisplay;
+  /** Current peer count */
+  peers: number;
+  /** Maximum peer count */
+  maxPeers: number;
+  /** Node software version */
+  version: string | null;
+  /** Whether the node responded to status probe */
+  online: boolean;
+}
+
+/** Country group for sidebar display. From groupNodesByCountry(). */
+export interface CountryGroup {
+  /** Country name */
+  country: string;
+  /** ISO country code */
+  countryCode: string;
+  /** Flag image URL */
+  flagUrl: string;
+  /** Emoji flag */
+  flagEmoji: string;
+  /** All nodes in this country */
+  nodes: NodeDisplay[];
+  /** Number of online nodes */
+  onlineCount: number;
+  /** Total nodes (online + offline) */
+  totalCount: number;
+}
+
+// ─── Pricing Reference ─────────────────────────────────────────────────────
+
+/**
+ * Static pricing reference for cost estimation UI.
+ * These are APPROXIMATE values from chain data -- actual prices vary per node.
+ * Always use estimateCost() or getNodePrices() for live data.
+ */
+export interface PricingReference {
+  /** When these values were last verified */
+  verified: string;
+  /** Disclaimer about accuracy */
+  note: string;
+  session: {
+    /** Typical session cost in P2P (0.04-0.15 per GB) */
+    typicalCostDvpn: number;
+    /** Minimum recommended wallet balance in P2P */
+    minBalanceDvpn: number;
+    /** Minimum recommended wallet balance in micro-denom */
+    minBalanceUdvpn: number;
+  };
+  gasPerMsg: {
+    /** Gas for MsgStartSession (~200k) */
+    startSession: number;
+    /** Gas for subscription + session (~250k) */
+    startSubscription: number;
+    /** Gas for MsgCreatePlan (~300k) */
+    createPlan: number;
+    /** Gas for MsgStartLease (~250k) */
+    startLease: number;
+    /** Gas for batch of 5 MsgStartSession (~800k) */
+    batchOf5: number;
+  };
+  averageNodePrices: {
+    /** Average per-GB price in micro-denom */
+    gigabyteQuoteValue: string;
+    /** Average per-hour price in micro-denom */
+    hourlyQuoteValue: string;
+    /** Typical base_value (sdk.Dec string) */
+    baseValue: string;
+  };
+}
+
+// ─── Session Duration Presets ──────────────────────────────────────────────
+
+/**
+ * Common hour options for hourly session selection UI.
+ * Values: [1, 2, 4, 8, 12, 24]
+ */
+export type HourOptions = number[];
+
+/**
+ * Common GB options for per-GB session selection UI.
+ * Values: [1, 2, 5, 10, 25, 50]
+ */
+export type GbOptions = number[];

package/types/protocol.d.ts

@@ -0,0 +1,332 @@
+/**
+ * Sentinel SDK — Protocol Types
+ *
+ * Types for the v3 node protocol: node status, handshakes,
+ * WireGuard tunnels, V2Ray configs, and transport rates.
+ *
+ * v3 differences from v2:
+ * - Node status: GET / (not GET /status)
+ * - Handshake: POST / (not POST /accounts/{addr}/sessions/{id})
+ * - field: service_type (not type), remote_addrs (array, not remote_url string)
+ * - Sessions wrapped in base_session
+ */
+
+/// <reference types="node" />
+
+// ─── Node Status ───────────────────────────────────────────────────────────
+
+/** Normalized node status from nodeStatusV3(). Combines v3 API response fields. */
+export interface NodeStatus {
+  /** sentnode1... address (may be empty if node doesn't report it) */
+  address: string;
+  /** Service type: 'wireguard' or 'v2ray' */
+  type: 'wireguard' | 'v2ray';
+  /** Node display name */
+  moniker: string;
+  /** Current peer count (active connections) */
+  peers: number;
+  /** Bandwidth capabilities */
+  bandwidth: {
+    /** Download speed in bytes/s */
+    download: number;
+    /** Upload speed in bytes/s */
+    upload: number;
+  };
+  /** Geographic location */
+  location: {
+    /** City name */
+    city: string;
+    /** Country name (as reported by node -- may be variant like "Turkiye") */
+    country: string;
+    /** ISO 3166-1 alpha-2 country code (as reported by node) */
+    country_code: string;
+    /** Latitude */
+    latitude: number;
+    /** Longitude */
+    longitude: number;
+  };
+  /** Quality of service limits */
+  qos: {
+    /** Maximum allowed peers (null if not configured) */
+    max_peers: number | null;
+  };
+  /**
+   * Clock drift in seconds between our machine and the node.
+   * Positive = node clock is ahead. null = couldn't determine.
+   * VMess AEAD fails if |drift| > 120s.
+   */
+  clockDriftSec: number | null;
+  /** Per-GB pricing (empty array -- not in v3 status, fetched from LCD) */
+  gigabyte_prices: unknown[];
+  /** Raw response object from node API */
+  _raw: unknown;
+}
+
+// ─── WireGuard ─────────────────────────────────────────────────────────────
+
+/** WireGuard Curve25519 key pair from generateWgKeyPair(). */
+export interface WgKeyPair {
+  /** Private key (32 bytes, bit-clamped per WG spec) */
+  privateKey: Buffer;
+  /** Public key (32 bytes, X25519 base point multiplication) */
+  publicKey: Buffer;
+}
+
+/** WireGuard configuration parameters for writeWgConfig(). */
+export interface WgConfigOptions {
+  /**
+   * DNS servers as comma-separated string.
+   * Default: Handshake DNS with Google/Cloudflare fallbacks.
+   */
+  dns?: string;
+  /**
+   * MTU value. Sentinel nodes use 1280.
+   * Higher values may cause packet fragmentation issues.
+   */
+  mtu?: number;
+  /**
+   * Keepalive interval in seconds (default: 15).
+   * Prevents NAT timeout on residential connections.
+   */
+  keepalive?: number;
+}
+
+// ─── Handshake Results ─────────────────────────────────────────────────────
+
+/**
+ * Result from WireGuard handshake (initHandshakeV3).
+ * Contains everything needed to configure the WG interface.
+ */
+export interface HandshakeResult {
+  /** IP addresses assigned to our WireGuard interface (e.g. ['10.8.0.2/32']) */
+  assignedAddrs: string[];
+  /** Server's WireGuard public key (base64-encoded) */
+  serverPubKey: string;
+  /** Server's WireGuard endpoint (e.g. '185.47.255.36:52618') */
+  serverEndpoint: string;
+  /** Raw JSON config string from node response */
+  config: string;
+  /** Full handshake response object */
+  result: unknown;
+}
+
+/**
+ * Result from V2Ray handshake (initHandshakeV3V2Ray).
+ * Contains metadata for building the V2Ray client config.
+ */
+export interface V2RayHandshakeResult {
+  /**
+   * JSON string of V2Ray metadata.
+   * Pass this to buildV2RayClientConfig() as the metadataJson parameter.
+   * Contains: transport type, port, service name, security settings.
+   */
+  config: string;
+  /** Full handshake response object */
+  result: unknown;
+}
+
+// ─── V2Ray Config ──────────────────────────────────────────────────────────
+
+/** Options for buildV2RayClientConfig(). */
+export interface V2RayConfigOptions {
+  /** DNS servers (comma-separated or preset name) */
+  dns?: string;
+  /** DNS preset name ('handshake', 'google', 'cloudflare') */
+  dnsPreset?: string;
+}
+
+/**
+ * V2Ray client configuration object (JSON structure).
+ * Generated by buildV2RayClientConfig(). Write this to a JSON file
+ * and pass to v2ray.exe as the config argument.
+ */
+export interface V2RayConfig {
+  /** Log configuration */
+  log: { loglevel: string };
+  /** Inbound proxy configuration (SOCKS5) */
+  inbounds: Array<{
+    tag: string;
+    protocol: string;
+    listen: string;
+    port: number;
+    settings: { auth: string; udp: boolean };
+  }>;
+  /** Outbound configurations (one per transport/metadata entry) */
+  outbounds: Array<{
+    tag: string;
+    protocol: string;
+    settings: {
+      vnext?: Array<{
+        address: string;
+        port: number;
+        users: Array<{
+          id?: string;
+          uuid?: string;
+          encryption?: string;
+          alterId?: number;
+          security?: string;
+        }>;
+      }>;
+    };
+    streamSettings?: {
+      network: string;
+      security: string;
+      tlsSettings?: Record<string, unknown>;
+      grpcSettings?: Record<string, unknown>;
+      wsSettings?: Record<string, unknown>;
+      httpSettings?: Record<string, unknown>;
+      tcpSettings?: Record<string, unknown>;
+      kcpSettings?: Record<string, unknown>;
+      quicSettings?: Record<string, unknown>;
+    };
+  }>;
+  /** Routing rules (balancer, direct, DNS) */
+  routing?: {
+    domainStrategy: string;
+    rules: Array<Record<string, unknown>>;
+    balancers?: Array<Record<string, unknown>>;
+  };
+  /** DNS configuration */
+  dns?: { servers: string[] };
+  /** Observatory for active probing */
+  observatory?: Record<string, unknown>;
+}
+
+// ─── Transport Rates ───────────────────────────────────────────────────────
+
+/** Static transport success rate (from 780-node scan). */
+export interface TransportSuccessRate {
+  /** Success rate 0.0-1.0 */
+  rate: number;
+  /** Number of nodes tested */
+  sample: number;
+  /** Human-readable note about this transport */
+  note: string;
+}
+
+/** Dynamic transport rate (runtime tracking, persisted to disk). */
+export interface DynamicTransportRate {
+  /** Success rate 0.0-1.0 */
+  rate: number;
+  /** Total samples (success + fail) */
+  sample: number;
+}
+
+// ─── Speed Testing ─────────────────────────────────────────────────────────
+
+/** Speed test result from speedtestDirect() or speedtestViaSocks5(). */
+export interface SpeedResult {
+  /** Download speed in Mbps */
+  mbps: number;
+  /** Number of chunks downloaded */
+  chunks: number;
+  /** Adaptive strategy used (e.g. 'full', 'probe-only') */
+  adaptive: string;
+  /** Total bytes downloaded */
+  totalBytes?: number;
+  /** Test duration in seconds */
+  seconds?: number;
+  /** Fallback host used (if primary failed) */
+  fallbackHost?: string;
+}
+
+/** Speed test comparison from compareSpeedTests(). */
+export interface SpeedComparison {
+  /** True if after test is faster */
+  improved: boolean;
+  /** True if after test is slower */
+  degraded: boolean;
+  /** Raw delta values */
+  delta: {
+    downloadMbps: number;
+    uploadMbps: number;
+    latencyMs: number;
+  };
+  /** Percentage change */
+  percentChange: {
+    download: number;
+    upload: number;
+  };
+}
+
+/** Speed test configuration constants. */
+export interface SpeedtestDefaults {
+  /** Bytes per chunk for download test */
+  readonly chunkBytes: number;
+  /** Number of chunks to download */
+  readonly chunkCount: number;
+  /** Bytes for initial probe */
+  readonly probeBytes: number;
+  /** Mbps threshold for full test vs probe-only */
+  readonly probeThresholdMbps: number;
+  /** Primary speed test host */
+  readonly primaryHost: string;
+  /** DNS cache TTL in ms */
+  readonly dnsCacheTtl: number;
+  /** Fallback speed test hosts */
+  readonly fallbackHosts: ReadonlyArray<{
+    host: string;
+    path: string;
+    size: number;
+  }>;
+}
+
+// ─── WireGuard Tunnel Management ───────────────────────────────────────────
+
+/** Result from watchdogCheck() -- quick tunnel health check. */
+export interface WatchdogResult {
+  /** Whether a tunnel is currently active */
+  active: boolean;
+  /** Tunnel name (e.g. 'sentinel0') */
+  name?: string;
+  /** Tunnel uptime in ms */
+  uptimeMs?: number;
+}
+
+/** Result from checkOrphanedTunnels(). */
+export interface OrphanedTunnelCheck {
+  /** Whether orphaned tunnels were found */
+  found: boolean;
+  /** Names of orphaned tunnels */
+  tunnels: string[];
+  /** Whether cleanup was performed */
+  cleaned: boolean;
+}
+
+/** Result from cleanOrphanedTunnels(). */
+export interface CleanOrphanedResult {
+  /** Number of tunnels cleaned */
+  cleaned: number;
+  /** Error messages for tunnels that couldn't be cleaned */
+  errors: string[];
+}
+
+/** Result from checkOrphanedV2Ray(). */
+export interface OrphanedV2RayCheck {
+  /** Whether orphaned V2Ray processes were found */
+  found: boolean;
+  /** PIDs of orphaned processes */
+  pids: number[];
+}
+
+/** Result from checkVpnConflicts(). */
+export interface VpnConflictCheck {
+  /** Detected VPN software that may conflict */
+  conflicts: Array<{
+    /** VPN software name */
+    name: string;
+    /** Whether it's currently running */
+    running: boolean;
+  }>;
+}
+
+/** Result from checkPortConflicts(). */
+export interface PortConflictCheck {
+  /** Ports that are in use */
+  conflicts: Array<{
+    /** Port number */
+    port: number;
+    /** Whether the port is currently in use */
+    inUse: boolean;
+  }>;
+}