blue-js-sdk 2.0.0

package/types/session.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Sentinel SDK — Session Types
+ *
+ * Types for session management: state persistence, credential caching,
+ * session poisoning, payment mode tracking, and session allocation.
+ */
+
+// ─── State Persistence ─────────────────────────────────────────────────────
+
+/**
+ * Saved connection state for crash recovery.
+ * Written to ~/.sentinel-sdk/state.json after successful connection.
+ * Read on next startup by recoverOrphans() to clean up leaked resources.
+ */
+export interface SDKState {
+  /** Active session ID (numeric string) */
+  sessionId?: string;
+  /** Protocol in use */
+  serviceType?: 'wireguard' | 'v2ray';
+  /** WireGuard tunnel service name (e.g. 'sentinel0') */
+  wgTunnelName?: string;
+  /** V2Ray process PID */
+  v2rayPid?: number;
+  /** SOCKS5 proxy port */
+  socksPort?: number;
+  /** Whether system proxy was modified */
+  systemProxySet?: boolean;
+  /** Whether kill switch was enabled */
+  killSwitchEnabled?: boolean;
+  /** Connected node address (sentnode1...) */
+  nodeAddress?: string;
+  /** WireGuard config file path */
+  confPath?: string;
+  /** When state was saved (ISO timestamp) */
+  savedAt?: string;
+  /** Process ID that saved this state */
+  pid?: number;
+}
+
+/** Result from recoverOrphans(). */
+export interface RecoverResult {
+  /** Whether any orphaned state was found */
+  hadState: boolean;
+  /** List of resources that were cleaned up (e.g. 'wg:sentinel0', 'v2ray:12345') */
+  cleaned: string[];
+}
+
+/** Result from checkPidFile(). */
+export interface PidCheck {
+  /** Whether the process is still running */
+  running: boolean;
+  /** PID from the file */
+  pid?: number;
+  /** When the PID file was written (ISO timestamp) */
+  startedAt?: string;
+}
+
+// ─── Credential Cache ──────────────────────────────────────────────────────
+
+/**
+ * Saved handshake credentials for fast reconnect.
+ * Persisted to ~/.sentinel-sdk/ encrypted on disk.
+ * Enables reconnecting to a node without redoing the handshake.
+ */
+export interface SavedCredentials {
+  /** Session ID this credential belongs to */
+  sessionId: string;
+  /** Protocol type */
+  serviceType: 'wireguard' | 'v2ray';
+  /** WireGuard private key (base64, WG only) */
+  wgPrivateKey?: string;
+  /** Server's WG public key (base64, WG only) */
+  wgServerPubKey?: string;
+  /** Assigned IP addresses with CIDR (WG only) */
+  wgAssignedAddrs?: string[];
+  /** Server's WG endpoint (WG only) */
+  wgServerEndpoint?: string;
+  /** V2Ray UUID (V2Ray only) */
+  v2rayUuid?: string;
+  /** V2Ray metadata JSON (V2Ray only) */
+  v2rayConfig?: string;
+  /** When credentials were saved (ISO timestamp) */
+  savedAt: string;
+}
+
+// ─── Session Manager ───────────────────────────────────────────────────────
+
+/**
+ * Options for SessionManager constructor.
+ */
+export interface SessionManagerOptions {
+  /** Session map cache TTL in ms (default: 300000 = 5 min) */
+  mapTtl?: number;
+  /** Custom path for credential cache file */
+  credentialPath?: string;
+  /** Logger function */
+  logger?: (msg: string) => void;
+}
+
+/**
+ * Session map entry (from SessionManager.buildSessionMap).
+ * Maps node address to active session info.
+ */
+export interface SessionMapEntry {
+  /** Session ID */
+  sessionId: bigint;
+  /** Maximum bytes for this session */
+  maxBytes: number;
+  /** Bytes used so far */
+  usedBytes: number;
+}
+
+// ─── Session Allocation ────────────────────────────────────────────────────
+
+/**
+ * Session allocation stats from computeSessionAllocation() or querySessionAllocation().
+ * Shows how much bandwidth has been used and remains.
+ */
+export interface SessionAllocation {
+  /** Total bytes used (download + upload) */
+  usedBytes: number;
+  /** Maximum bytes allowed for this session */
+  maxBytes: number;
+  /** Remaining bytes before session expires */
+  remainingBytes: number;
+  /** Usage percentage (0-100, rounded to 1 decimal) */
+  usedPercent: number;
+  /** Human-readable used amount (e.g. "1.5 GB") */
+  usedDisplay: string;
+  /** Human-readable max amount (e.g. "5.0 GB") */
+  maxDisplay: string;
+  /** Human-readable remaining amount (e.g. "3.5 GB") */
+  remainingDisplay: string;
+  /** True if session is GB-based (maxDuration is "0s") */
+  isGbBased: boolean;
+  /** True if session is hourly (maxDuration > "0s") */
+  isHourlyBased: boolean;
+}
+
+/** Result from querySessionAllocation() (null if session not found). */
+export interface QuerySessionAllocationResult {
+  /** Maximum bytes allowed */
+  maxBytes: number;
+  /** Bytes used (download + upload) */
+  usedBytes: number;
+  /** Remaining bytes */
+  remainingBytes: number;
+  /** Usage percentage (0-100) */
+  percentUsed: number;
+}
+
+// ─── Session Payment Mode Tracking ─────────────────────────────────────────
+
+/**
+ * Session payment mode. The chain doesn't distinguish GB-based from hourly.
+ * This is tracked client-side so apps can show the correct pricing model.
+ *
+ * - 'gb': Paid per gigabyte (connectDirect with gigabytes param)
+ * - 'hour': Paid per hour (connectDirect with hours param)
+ * - 'plan': Started via plan subscription (connectViaPlan)
+ */
+export type SessionPaymentMode = 'gb' | 'hour' | 'plan';
+
+// ─── Session History ───────────────────────────────────────────────────────
+
+/**
+ * Session history entry. Tracks both active and poisoned sessions.
+ * Stored in ~/.sentinel-sdk/sessions.json.
+ */
+export interface SessionHistoryEntry {
+  /** sentnode1... address */
+  nodeAddress: string;
+  /** Session status */
+  status: 'active' | 'poisoned';
+  /** Error message (poisoned sessions only) */
+  error?: string;
+  /** When the entry was created/updated */
+  timestamp: string;
+}
+
+// ─── Batch Session Operations ──────────────────────────────────────────────
+
+/** Options for batchStartSessions() (operator/testing tool). */
+export interface BatchStartSessionsOptions {
+  /** BIP39 mnemonic phrase */
+  mnemonic: string;
+  /** RPC URL (default: cascading fallback) */
+  rpcUrl?: string;
+  /** LCD URL (default: cascading fallback) */
+  lcdUrl?: string;
+  /** Nodes to start sessions on */
+  nodes: Array<{
+    /** sentnode1... address */
+    nodeAddress: string;
+    /** GB to purchase (default: 1) */
+    gigabytes?: number;
+    /** Max acceptable price */
+    maxPrice?: { denom: string; base_value: string; quote_value: string };
+  }>;
+}
+
+/** Result from batchStartSessions(). */
+export interface BatchStartResult {
+  /** Transaction hash */
+  txHash: string;
+  /** Session IDs created (one per node) */
+  sessionIds: bigint[];
+}
+
+/** Status of a batch session (from waitForBatchSessions). */
+export interface BatchSessionStatus {
+  /** Session ID */
+  sessionId: bigint;
+  /** Whether the session appeared on LCD */
+  status: string;
+}
+
+/** Options for waitForBatchSessions(). */
+export interface WaitForBatchOptions {
+  /** LCD URL */
+  lcdUrl?: string;
+  /** Max wait time in ms (default: 60000) */
+  timeoutMs?: number;
+  /** Polling interval in ms (default: 5000) */
+  pollIntervalMs?: number;
+}
+
+/** Options for waitForSessionActive(). */
+export interface WaitForSessionActiveOptions {
+  /** LCD URL */
+  lcdUrl?: string;
+  /** Max wait time in ms (default: 30000) */
+  timeoutMs?: number;
+  /** Polling interval in ms (default: 3000) */
+  pollIntervalMs?: number;
+}

package/types/settings.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Sentinel SDK — Settings & App Configuration Types
+ *
+ * Types for app settings persistence, app type definitions,
+ * DNS presets, and app configuration validation.
+ */
+
+// ─── App Settings ──────────────────────────────────────────────────────────
+
+/**
+ * Persisted app settings. Stored at ~/.sentinel-sdk/app-settings.json.
+ * Every field has a sane default -- apps can use this out of the box.
+ * Mutate the object, then call saveAppSettings() to persist.
+ */
+export interface AppSettings {
+  // ── Network ──
+  /** DNS preset: 'handshake' | 'google' | 'cloudflare' | 'custom' */
+  dnsPreset: 'handshake' | 'google' | 'cloudflare' | 'custom';
+  /** Custom DNS IPs, comma-separated (only used when dnsPreset is 'custom') */
+  customDns: string;
+
+  // ── Tunnel ──
+  /** Route all traffic through VPN (default: true) */
+  fullTunnel: boolean;
+  /** Set OS SOCKS proxy for V2Ray (default: false) */
+  systemProxy: boolean;
+  /** Block all traffic if tunnel drops (default: false) */
+  killSwitch: boolean;
+  /** WireGuard MTU -- Sentinel nodes use 1280 (default: 1280) */
+  wgMtu: number;
+  /** WireGuard keepalive in seconds -- safe for all NAT routers (default: 15) */
+  wgKeepalive: number;
+
+  // ── Session ──
+  /** Default GB amount for per-GB sessions (default: 1) */
+  defaultGigabytes: number;
+  /** Default hour amount for hourly sessions (default: 1) */
+  defaultHours: number;
+  /** Prefer hourly pricing when available (default: false) */
+  preferHourly: boolean;
+  /** Protocol preference: 'auto' picks best, 'wireguard'/'v2ray' forces one */
+  protocolPreference: 'auto' | 'wireguard' | 'v2ray';
+
+  // ── Polling intervals (seconds) ──
+  /** Connection status check interval (default: 3) */
+  statusPollSec: number;
+  /** Public IP check interval (default: 60) */
+  ipCheckSec: number;
+  /** Wallet balance refresh interval (default: 300 = 5 min) */
+  balanceCheckSec: number;
+  /** Session allocation refresh interval (default: 120 = 2 min) */
+  allocationCheckSec: number;
+
+  // ── Plan ──
+  /** Max plan ID to probe in discoverPlans (default: 500) */
+  planProbeMax: number;
+
+  // ── Favorites ──
+  /** Array of sentnode1... addresses marked as favorite */
+  favoriteNodes: string[];
+
+  // ── Last connection ──
+  /** Last connected node address for quick reconnect (null if none) */
+  lastNodeAddress: string | null;
+  /** Last service type used */
+  lastServiceType: 'wireguard' | 'v2ray' | null;
+}
+
+// ─── DNS Presets ───────────────────────────────────────────────────────────
+
+/** DNS server preset configuration. */
+export interface DnsPreset {
+  /** Display name (e.g. 'Handshake') */
+  name: string;
+  /** DNS server IP addresses */
+  servers: string[];
+  /** Human-readable description */
+  description: string;
+}
+
+/** Available DNS preset names. */
+export type DnsPresetName = 'handshake' | 'google' | 'cloudflare';
+
+/** All DNS presets (frozen object). */
+export type DnsPresets = Readonly<Record<DnsPresetName, DnsPreset>>;
+
+// ─── App Types ─────────────────────────────────────────────────────────────
+
+/**
+ * The three types of Sentinel dVPN applications.
+ * Choose based on how users pay for VPN access.
+ */
+export type AppType = 'white_label' | 'direct_p2p' | 'all_in_one';
+
+/** App type string constants. */
+export interface AppTypeConstants {
+  /** Branded app with pre-loaded plan. Users click "Connect", done. */
+  readonly WHITE_LABEL: 'white_label';
+  /** Users browse nodes, pick pricing, pay per session. */
+  readonly DIRECT_P2P: 'direct_p2p';
+  /** Plan subscriptions + direct P2P. Full flexibility. */
+  readonly ALL_IN_ONE: 'all_in_one';
+}
+
+/** UI screens configuration for an app type. */
+export interface AppTypeScreens {
+  /** Welcome/onboarding screen */
+  welcome: boolean;
+  /** Browse available plans */
+  planBrowser: boolean;
+  /** Browse individual nodes */
+  nodeBrowser: boolean;
+  /** Duration/amount picker (GB or hours) */
+  durationPicker: boolean;
+  /** Price display before connecting */
+  pricingDisplay: boolean;
+  /** Main connect button */
+  connect: boolean;
+  /** Settings screen */
+  settings: boolean;
+}
+
+/** Complete configuration requirements and flow for an app type. */
+export interface AppTypeConfig {
+  /** Human-readable description */
+  description: string;
+  /** Required configuration keys (must be non-null at startup) */
+  requiredConfig: string[];
+  /** Optional configuration keys */
+  optionalConfig: string[];
+  /** Recommended connect function name */
+  connectFunction: string;
+  /** Whether the user pays gas (false for white-label with fee grants) */
+  userPaysGas: boolean;
+  /** Whether the user picks a specific node */
+  userPicksNode: boolean;
+  /** Whether the user picks duration/amount */
+  userPicksDuration: boolean;
+  /** Whether pricing is shown to the user */
+  userSeesPricing: boolean;
+  /** Which UI screens to build */
+  screens: AppTypeScreens;
+  /** Step-by-step user flow description */
+  flow: string[];
+  /** SDK functions to use for this app type */
+  sdkFunctions: string[];
+}
+
+// ─── App Config Validation ─────────────────────────────────────────────────
+
+/** Result from validateAppConfig(). Run at app startup. */
+export interface AppConfigValidation {
+  /** Whether the config is valid (no errors) */
+  valid: boolean;
+  /** Critical errors that must be fixed */
+  errors: string[];
+  /** Non-critical warnings */
+  warnings: string[];
+  /** The resolved app type config (null if type is invalid) */
+  type: AppTypeConfig | null;
+}
+
+// ─── VPN Settings (Legacy) ─────────────────────────────────────────────────
+
+/**
+ * Legacy VPN settings from loadVpnSettings() / saveVpnSettings().
+ * Stored at ~/.sentinel-sdk/settings.json.
+ * Use loadAppSettings() instead for new code.
+ */
+export type VpnSettings = Record<string, unknown>;
+
+// ─── Disk Cache ────────────────────────────────────────────────────────────
+
+/** Cache entry metadata from cacheInfo(). */
+export interface CacheInfo {
+  /** Age of the cached data in ms */
+  ageMs: number;
+  /** Whether there is data in the cache */
+  hasData: boolean;
+  /** Whether a fetch is currently in flight */
+  inflight: boolean;
+}
+
+/** Disk cache load result from diskLoad(). */
+export interface DiskCacheEntry<T = unknown> {
+  /** The cached data */
+  data: T;
+  /** When the data was saved (Date.now() timestamp) */
+  savedAt: number;
+  /** Whether the data exceeds maxAgeMs */
+  stale: boolean;
+}