@push.rocks/smartnetwork 4.5.1 → 4.6.0

package/readme.md

@@ -1,10 +1,12 @@
 # @push.rocks/smartnetwork 🌐
 
-Comprehensive network diagnostics and utilities for Node.js applications
+Comprehensive network diagnostics and intelligence for Node.js — speed tests, port scanning, ICMP ping, traceroute, DNS, IP & domain RDAP, ASN lookups, geolocation, and DNS record enrichment in a single, promise-based toolkit.
 
-## 🚀 Install
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-To install `@push.rocks/smartnetwork`, run the following command in your terminal:
+## 🚀 Install
 
 ```bash
 pnpm install @push.rocks/smartnetwork --save
@@ -12,29 +14,32 @@ pnpm install @push.rocks/smartnetwork --save
 
 ## 🎯 Overview
 
-**@push.rocks/smartnetwork** is your Swiss Army knife for network diagnostics in Node.js. Whether you're building network monitoring tools, implementing health checks, or just need to debug connectivity issues, this library has you covered with a clean, promise-based API.
+**@push.rocks/smartnetwork** is your Swiss Army knife for network diagnostics in Node.js. Whether you're building monitoring dashboards, investigating IP/domain ownership, or debugging connectivity — this library has you covered with a clean, async API and zero-config setup.
+
+Under the hood, system-level operations (ICMP ping, traceroute, raw-socket port checks, gateway detection) are powered by a bundled **Rust binary** for maximum performance and cross-platform reliability. Everything else — speed tests, DNS, public IP discovery, IP & domain intelligence, HTTP health checks — runs in pure TypeScript.
 
 ### ✨ Key Features
 
-- **🏎️ Speed Testing** - Measure download/upload speeds using Cloudflare's infrastructure
-- **🔌 Port Management** - Check local/remote port availability, find free ports (sequential or random)
-- **📡 Connectivity Testing** - Ping hosts, trace routes, check endpoints
-- **🌍 DNS Operations** - Resolve A, AAAA, and MX records with smart local/remote resolution
-- **🔍 Network Discovery** - Get network interfaces, gateways, public IPs
-- **⚡ Performance Caching** - Built-in caching for expensive operations
-- **🔧 Plugin Architecture** - Extend functionality with custom plugins
-- **📝 Full TypeScript Support** - Complete type definitions included
+| Category | Capabilities |
+|----------|-------------|
+| 🏎️ **Speed Testing** | Download/upload benchmarks via Cloudflare's global infrastructure |
+| 🔌 **Port Management** | Local/remote port checks, find free ports (sequential or random), exclusion lists |
+| 📡 **Connectivity** | ICMP ping with stats, hop-by-hop traceroute, HTTP/HTTPS health checks |
+| 🌍 **DNS** | A, AAAA, MX resolution with system-first + DoH fallback strategy |
+| 🔍 **IP Intelligence** | ASN, organization, geolocation, RDAP registration — all from free public sources |
+| 🏢 **Domain Intelligence** | RDAP registrar/registrant, nameservers, events, DNSSEC, plus DNS enrichment (A/AAAA/MX/TXT/SOA) |
+| 🖥️ **Network Discovery** | Interfaces, default gateway, public IPv4/IPv6 |
+| ⚡ **Caching** | Built-in TTL cache for expensive lookups |
+| 🔧 **Extensible** | Plugin architecture for custom functionality |
+| 📝 **TypeScript** | Full type definitions, ESM-native |
 
 ## 💻 Usage
 
 ### Basic Setup
 
-First, import and initialize SmartNetwork:
-
 ```typescript
 import { SmartNetwork } from '@push.rocks/smartnetwork';
 
-// Basic instance
 const network = new SmartNetwork();
 
 // Start the Rust bridge (auto-started on first use, but explicit start is recommended)
@@ -42,396 +47,463 @@ await network.start();
 
 // ... use the network instance ...
 
-// Clean up when done (stops the Rust bridge process)
+// Clean up when done — tears down both the Rust bridge and the smartdns backend
 await network.stop();
-
-// With caching enabled (60 seconds TTL)
-const cachedNetwork = new SmartNetwork({ cacheTtl: 60000 });
 ```
 
-### 🏎️ Network Speed Testing
-
-Measure your network performance using Cloudflare's global infrastructure:
+Enable caching for repeated lookups:
 
 ```typescript
-const speedTest = async () => {
-  // Quick speed test
-  const result = await network.getSpeed();
-  console.log(`Download: ${result.downloadSpeed} Mbps`);
-  console.log(`Upload: ${result.uploadSpeed} Mbps`);
-
-  // Advanced configuration
-  const advancedResult = await network.getSpeed({ 
-    parallelStreams: 3,  // Number of concurrent connections
-    duration: 5          // Test duration in seconds
-  });
-  console.log(`Download: ${advancedResult.downloadSpeed} Mbps`);
-  console.log(`Upload: ${advancedResult.uploadSpeed} Mbps`);
-};
+const network = new SmartNetwork({ cacheTtl: 60000 }); // 60s TTL
 ```
 
-### 🔌 Port Management
+---
 
-#### Check Local Port Availability
+### 🕵️ IP Intelligence
 
-Verify if a port is available on your local machine (checks both IPv4 and IPv6):
+Get ASN, organization, geolocation, and RDAP registration data for any IPv4 address. Combines three free public data sources in parallel:
 
-```typescript
-const checkLocalPort = async (port: number) => {
-  const isUnused = await network.isLocalPortUnused(port);
-  if (isUnused) {
-    console.log(`✅ Port ${port} is available`);
-  } else {
-    console.log(`❌ Port ${port} is in use`);
-  }
-};
+- **RDAP** — direct queries to RIRs (RIPE, ARIN, APNIC, LACNIC, AFRINIC) for authoritative registration data
+- **Team Cymru DNS** — fast ASN resolution via DNS TXT records
+- **MaxMind GeoLite2** — in-memory MMDB databases (auto-downloaded from CDN, periodically refreshed)
 
-await checkLocalPort(8080);
+```typescript
+const intel = await network.getIpIntelligence('8.8.8.8');
+
+console.log(intel);
+// {
+//   asn: 15169,
+//   asnOrg: 'Google LLC',
+//   registrantOrg: 'Google LLC',
+//   registrantCountry: 'United States',
+//   networkRange: '8.8.8.0/24',
+//   abuseContact: null,
+//   country: null,
+//   countryCode: 'US',
+//   city: null,
+//   latitude: 37.751,
+//   longitude: -97.822,
+//   accuracyRadius: null,
+//   timezone: 'America/Chicago'
+// }
 ```
 
-#### Find Free Port in Range
+Works great for your own IP too:
 
-Automatically discover available ports:
+```typescript
+const publicIps = await network.getPublicIps();
+if (publicIps.v4) {
+  const myIntel = await network.getIpIntelligence(publicIps.v4);
+  console.log(`You're on AS${myIntel.asn} (${myIntel.asnOrg}) in ${myIntel.city}, ${myIntel.countryCode}`);
+}
+```
+
+The `IIpIntelligenceResult` interface:
 
 ```typescript
-const findFreePort = async () => {
-  // Find a free port between 3000 and 3100 (sequential - returns first available)
-  const freePort = await network.findFreePort(3000, 3100);
-  
-  if (freePort) {
-    console.log(`🎉 Found free port: ${freePort}`);
-  } else {
-    console.log('😢 No free ports available in range');
-  }
-  
-  // Find a random free port in range (useful to avoid port conflicts)
-  const randomPort = await network.findFreePort(3000, 3100, { randomize: true });
-  console.log(`🎲 Random free port: ${randomPort}`);
-  
-  // Exclude specific ports from the search
-  const portWithExclusions = await network.findFreePort(3000, 3100, {
-    exclude: [3000, 3001, 3005]  // Skip these ports even if they're free
-  });
-  console.log(`🚫 Free port (excluding specific ports): ${portWithExclusions}`);
-  
-  // Combine randomize with exclude options
-  const randomWithExclusions = await network.findFreePort(3000, 3100, {
-    randomize: true,
-    exclude: [3000, 3001, 3005]
-  });
-  console.log(`🎲🚫 Random free port (with exclusions): ${randomWithExclusions}`);
-};
+interface IIpIntelligenceResult {
+  // ASN (Team Cymru primary, MaxMind fallback)
+  asn: number | null;
+  asnOrg: string | null;
+
+  // Registration (RDAP)
+  registrantOrg: string | null;
+  registrantCountry: string | null;
+  networkRange: string | null;       // CIDR or range
+  abuseContact: string | null;       // abuse email from RDAP
+
+  // Geolocation (MaxMind GeoLite2)
+  country: string | null;
+  countryCode: string | null;        // ISO 3166-1 alpha-2
+  city: string | null;
+  latitude: number | null;
+  longitude: number | null;
+  accuracyRadius: number | null;     // km
+  timezone: string | null;           // IANA timezone
+}
 ```
 
-#### Check Remote Port Availability
+> 💡 The GeoLite2 databases are fetched into memory from jsDelivr CDN on first use (~32 MB total). They auto-refresh in the background every 7 days (configurable via `IpIntelligence` options). No disk I/O, no API keys, no rate limits.
 
-Test if services are accessible on remote servers:
+---
 
-```typescript
-// Method 1: Using "host:port" syntax
-const isOpen1 = await network.isRemotePortAvailable('example.com:443');
+### 🏢 Domain Intelligence
 
-// Method 2: Using separate host and port
-const isOpen2 = await network.isRemotePortAvailable('example.com', 443);
+Get comprehensive domain registration and DNS data. Runs an **RDAP layer** and a **DNS layer** in parallel, then merges results:
 
-// Method 3: With advanced options
-const isOpen3 = await network.isRemotePortAvailable('example.com', {
-  port: 443,
-  protocol: 'tcp',     // Only TCP is supported
-  retries: 3,          // Number of connection attempts
-  timeout: 5000        // Timeout per attempt in ms
-});
+- **RDAP** — queries the correct registry RDAP server (discovered via the [IANA DNS bootstrap](https://data.iana.org/rdap/dns.json)) for registrar, registrant, events, status flags, DNSSEC, and abuse contacts
+- **DNS** — queries A, AAAA, NS, MX, TXT, and SOA records via `@push.rocks/smartdns` (system resolver first, DoH fallback)
 
-// Note: UDP is not supported
-try {
-  await network.isRemotePortAvailable('example.com', { 
-    port: 53, 
-    protocol: 'udp' 
-  });
-} catch (e) {
-  console.error('UDP not supported:', e.code); // ENOTSUP
-}
+For gTLDs (`.com`, `.org`, `.net`, etc.) you get the full picture from both layers. For ccTLDs without RDAP support (`.de`, `.fr`, `.nl`, etc.), the DNS layer fills in nameservers, resolved IPs, MX, TXT, and SOA — so you still get useful intelligence even when RDAP isn't available.
+
+```typescript
+const info = await network.getDomainIntelligence('google.com');
+
+console.log(info);
+// {
+//   domain: 'google.com',
+//   handle: '2138514_DOMAIN_COM-VRSN',
+//   status: ['client delete prohibited', 'server transfer prohibited', ...],
+//   registrationDate: '1997-09-15T04:00:00Z',
+//   expirationDate: '2028-09-14T04:00:00Z',
+//   lastChangedDate: '2019-09-09T15:39:04Z',
+//   registrarName: 'MarkMonitor Inc.',
+//   registrarIanaId: 292,
+//   registrantOrg: null,           // often redacted under GDPR
+//   registrantCountry: null,
+//   abuseEmail: 'abusecomplaints@markmonitor.com',
+//   abusePhone: '+1.2086851750',
+//   nameservers: ['ns1.google.com', 'ns2.google.com', 'ns3.google.com', 'ns4.google.com'],
+//   dnssec: false,
+//   nameserversSource: 'rdap',
+//   resolvedIpv4: ['142.251.20.102', '142.251.20.113', ...],
+//   resolvedIpv6: ['2a00:1450:4001:c15::8b', ...],
+//   mxRecords: [{ priority: 10, exchange: 'smtp.google.com' }],
+//   txtRecords: ['v=spf1 include:_spf.google.com ~all', ...],
+//   soaRecord: 'ns1.google.com dns-admin.google.com 895796075 900 900 1800 60'
+// }
 ```
 
-### 📡 Network Connectivity
+Works with ccTLDs that don't have RDAP (like `.de`):
 
-#### Ping Operations
+```typescript
+const deInfo = await network.getDomainIntelligence('bund.de');
+console.log(deInfo.registrarName);       // null (no .de RDAP)
+console.log(deInfo.nameservers);         // ['bamberg.bund.de', 'argon.bund.de', ...]
+console.log(deInfo.nameserversSource);   // 'dns' — nameservers came from DNS, not RDAP
+console.log(deInfo.resolvedIpv4);        // ['80.245.156.34']
+console.log(deInfo.mxRecords);           // [{priority: 10, exchange: 'mx1.bund.de'}, ...]
+```
 
-Test connectivity and measure latency:
+Handles IDN (internationalized domain names) automatically:
 
 ```typescript
-// Simple ping
-const pingResult = await network.ping('google.com');
-console.log(`Host alive: ${pingResult.alive}`);
-console.log(`RTT: ${pingResult.time} ms`);
-
-// Detailed ping statistics
-const pingStats = await network.ping('google.com', { 
-  count: 5,          // Number of pings
-  timeout: 1000      // Timeout per ping in ms
-});
+const idn = await network.getDomainIntelligence('münchen.de');
+console.log(idn.domain); // 'xn--mnchen-3ya.de' — normalized to punycode
+```
 
-console.log(`📊 Ping Statistics:`);
-console.log(`  Packet loss: ${pingStats.packetLoss}%`);
-console.log(`  Min: ${pingStats.min} ms`);
-console.log(`  Max: ${pingStats.max} ms`);
-console.log(`  Avg: ${pingStats.avg.toFixed(2)} ms`);
-console.log(`  Stddev: ${pingStats.stddev.toFixed(2)} ms`);
+The `IDomainIntelligenceResult` interface:
+
+```typescript
+interface IDomainIntelligenceResult {
+  domain: string | null;              // normalized ASCII form
+  handle: string | null;              // registry handle
+  status: string[] | null;            // EPP status codes
+
+  // Registration lifecycle (ISO 8601)
+  registrationDate: string | null;
+  expirationDate: string | null;
+  lastChangedDate: string | null;
+
+  // Registrar
+  registrarName: string | null;
+  registrarIanaId: number | null;
+
+  // Registrant (often redacted under GDPR)
+  registrantOrg: string | null;
+  registrantCountry: string | null;
+
+  // Abuse contact
+  abuseEmail: string | null;
+  abusePhone: string | null;
+
+  // Technical
+  nameservers: string[] | null;
+  dnssec: boolean | null;             // secureDNS.delegationSigned from RDAP
+  nameserversSource: 'rdap' | 'dns' | null;
+
+  // DNS enrichment
+  resolvedIpv4: string[] | null;      // A records
+  resolvedIpv6: string[] | null;      // AAAA records
+  mxRecords: { priority: number | null; exchange: string }[] | null;
+  txtRecords: string[] | null;        // SPF, DKIM, site verification, etc.
+  soaRecord: string | null;           // raw SOA value
+}
 ```
 
-#### Traceroute
+> 💡 **RDAP vs DNS nameservers**: When RDAP is available (most gTLDs), `nameservers` comes from the registry's authoritative parent-zone delegation (`nameserversSource: 'rdap'`). When RDAP is unavailable (many ccTLDs), the DNS layer fills in nameservers via NS record resolution (`nameserversSource: 'dns'`). The `nameserversSource` field tells you which source won.
 
-Analyze network paths hop-by-hop:
+---
 
-```typescript
-const hops = await network.traceroute('google.com', { 
-  maxHops: 10,      // Maximum number of hops
-  timeout: 5000     // Timeout in ms
-});
+### 🏎️ Speed Testing
 
-console.log('🛤️ Route to destination:');
-hops.forEach(hop => {
-  const rtt = hop.rtt === null ? '*' : `${hop.rtt} ms`;
-  console.log(`  ${hop.ttl}\t${hop.ip}\t${rtt}`);
+Measure network performance via Cloudflare's global infrastructure:
+
+```typescript
+const result = await network.getSpeed();
+console.log(`⬇️  Download: ${result.downloadSpeed} Mbps`);
+console.log(`⬆️  Upload: ${result.uploadSpeed} Mbps`);
+
+// Advanced: parallel streams + fixed duration
+const advanced = await network.getSpeed({
+  parallelStreams: 3,
+  duration: 5,
 });
 ```
 
-*Note: Falls back to a single-hop stub if the `traceroute` binary is unavailable.*
+---
 
-### 🌍 DNS Operations
+### 🔌 Port Management
 
-Resolve various DNS record types using @push.rocks/smartdns with intelligent resolution strategy:
+#### Check Local Port Availability
 
-```typescript
-const dnsRecords = await network.resolveDns('example.com');
+Checks both IPv4 and IPv6:
 
-console.log('🔍 DNS Records:');
-console.log('  A records:', dnsRecords.A);        // IPv4 addresses
-console.log('  AAAA records:', dnsRecords.AAAA);  // IPv6 addresses
+```typescript
+const isUnused = await network.isLocalPortUnused(8080);
+console.log(isUnused ? '✅ Port 8080 is free' : '❌ Port 8080 is in use');
+```
 
-// MX records include priority
-dnsRecords.MX.forEach(mx => {
-  console.log(`  📧 Mail server: ${mx.exchange} (priority: ${mx.priority})`);
-});
+#### Find Free Port in Range
 
-// Properly handles local hostnames (localhost, etc.)
-const localDns = await network.resolveDns('localhost');
-console.log('  Localhost:', localDns.A);  // Returns ['127.0.0.1']
-```
+```typescript
+// First available
+const port = await network.findFreePort(3000, 3100);
 
-*DNS resolution uses a `prefer-system` strategy: tries system resolver first (respects /etc/hosts and local DNS), with automatic fallback to Cloudflare DoH for external domains.*
+// Random pick (avoids clustering)
+const randomPort = await network.findFreePort(3000, 3100, { randomize: true });
 
-### 🏥 HTTP/HTTPS Health Checks
+// With exclusions
+const port2 = await network.findFreePort(3000, 3100, {
+  randomize: true,
+  exclude: [3000, 3001, 3005],
+});
+```
 
-Monitor endpoint availability and response times:
+#### Check Remote Port
 
 ```typescript
-const health = await network.checkEndpoint('https://api.example.com/health', {
-  timeout: 5000  // Request timeout in ms
-});
+// Simple
+const isOpen = await network.isRemotePortAvailable('example.com', 443);
 
-console.log(`🩺 Endpoint Health:`);
-console.log(`  Status: ${health.status}`);
-console.log(`  RTT: ${health.rtt} ms`);
-console.log(`  Headers:`, health.headers);
+// With retries and timeout
+const isOpen2 = await network.isRemotePortAvailable('example.com', {
+  port: 443,
+  retries: 3,
+  timeout: 5000,
+});
 ```
 
-### 🖥️ Network Interface Information
-
-#### Get All Network Interfaces
+---
 
-List all network adapters on the system:
+### 📡 Ping & Traceroute
 
 ```typescript
-const gateways = await network.getGateways();
+// Simple ping
+const ping = await network.ping('google.com');
+console.log(`Alive: ${ping.alive}, RTT: ${ping.time} ms`);
 
-Object.entries(gateways).forEach(([name, interfaces]) => {
-  console.log(`🔌 Interface: ${name}`);
-  interfaces.forEach(iface => {
-    console.log(`  ${iface.family}: ${iface.address}`);
-    console.log(`  Netmask: ${iface.netmask}`);
-    console.log(`  MAC: ${iface.mac}`);
-  });
+// Multi-ping with statistics
+const stats = await network.ping('google.com', { count: 10, timeout: 2000 });
+console.log(`📊 min=${stats.min} avg=${stats.avg.toFixed(1)} max=${stats.max} loss=${stats.packetLoss}%`);
+
+// Traceroute
+const hops = await network.traceroute('google.com', { maxHops: 20 });
+hops.forEach(hop => {
+  const rtt = hop.rtt === null ? '*' : `${hop.rtt} ms`;
+  console.log(`  ${hop.ttl}\t${hop.ip}\t${rtt}`);
 });
 ```
 
-#### Get Default Gateway
+> ⚠️ ICMP ping requires `CAP_NET_RAW` or appropriate `ping_group_range` sysctl on Linux.
 
-Retrieve the primary network interface:
+---
 
-```typescript
-const defaultGateway = await network.getDefaultGateway();
+### 🌍 DNS Resolution
 
-if (defaultGateway) {
-  console.log('🌐 Default Gateway:');
-  console.log('  IPv4:', defaultGateway.ipv4.address);
-  console.log('  IPv6:', defaultGateway.ipv6.address);
-}
+Uses `@push.rocks/smartdns` with a system-first strategy and automatic DoH (DNS-over-HTTPS) fallback:
+
+```typescript
+const dns = await network.resolveDns('example.com');
+console.log('A records:', dns.A);       // ['93.184.216.34']
+console.log('AAAA records:', dns.AAAA); // ['2606:2800:220:1:248:1893:25c8:1946']
+dns.MX.forEach(mx => {
+  console.log(`📧 ${mx.exchange} (priority ${mx.priority})`);
+});
 ```
 
-### 🌎 Public IP Discovery
+---
 
-Discover your public-facing IP addresses:
+### 🏥 HTTP/HTTPS Health Checks
 
 ```typescript
-const publicIps = await network.getPublicIps();
-
-console.log(`🌍 Public IPs:`);
-console.log(`  IPv4: ${publicIps.v4 || 'Not available'}`);
-console.log(`  IPv6: ${publicIps.v6 || 'Not available'}`);
+const health = await network.checkEndpoint('https://api.example.com/health', {
+  timeout: 5000,
+  rejectUnauthorized: true,
+});
+console.log(`Status: ${health.status}, RTT: ${health.rtt.toFixed(0)} ms`);
 ```
 
-### ⚡ Performance Caching
+---
 
-Reduce network calls with built-in caching:
+### 🖥️ Network Interfaces & Public IPs
 
 ```typescript
-// Create instance with 60-second cache TTL
-const cachedNetwork = new SmartNetwork({ cacheTtl: 60000 });
+// All interfaces
+const gateways = await network.getGateways();
+Object.entries(gateways).forEach(([name, ifaces]) => {
+  console.log(`🔌 ${name}:`);
+  ifaces.forEach(i => console.log(`  ${i.family}: ${i.address}`));
+});
 
-// First call fetches from network
-const gateways1 = await cachedNetwork.getGateways();
-const publicIps1 = await cachedNetwork.getPublicIps();
+// Default gateway
+const gw = await network.getDefaultGateway();
+if (gw) {
+  console.log(`🌐 Gateway IPv4: ${gw.ipv4.address}`);
+}
 
-// Subsequent calls within 60 seconds use cache
-const gateways2 = await cachedNetwork.getGateways();    // From cache ⚡
-const publicIps2 = await cachedNetwork.getPublicIps();  // From cache ⚡
+// Public IPs (multiple fallback services: ipify, ident.me, seeip, icanhazip)
+const publicIps = await network.getPublicIps();
+console.log(`🌍 IPv4: ${publicIps.v4 || 'N/A'}`);
+console.log(`🌍 IPv6: ${publicIps.v6 || 'N/A'}`);
 ```
 
-### 🔧 Plugin Architecture
-
-Extend SmartNetwork with custom functionality:
+---
 
-```typescript
-// Define your plugin
-class CustomNetworkPlugin {
-  constructor(private smartNetwork: SmartNetwork) {}
-  
-  async customMethod() {
-    // Your custom network logic here
-    return 'Custom result';
-  }
-}
+### ⚡ Caching
 
-// Register the plugin
-SmartNetwork.registerPlugin('customPlugin', CustomNetworkPlugin);
+Caching applies to `getGateways()`, `getPublicIps()`, `getIpIntelligence()`, and `getDomainIntelligence()`:
 
-// Use the plugin
-const network = new SmartNetwork();
-const PluginClass = SmartNetwork.pluginsRegistry.get('customPlugin');
-const plugin = new PluginClass(network);
-await plugin.customMethod();
+```typescript
+const network = new SmartNetwork({ cacheTtl: 60000 }); // 60s
 
-// Clean up when done
-SmartNetwork.unregisterPlugin('customPlugin');
+const ips1 = await network.getPublicIps();  // fetches
+const ips2 = await network.getPublicIps();  // cache hit ⚡
 ```
 
-### 🚨 Error Handling
+---
 
-Handle network errors gracefully with custom error types:
+### 🚨 Error Handling
 
 ```typescript
-import { NetworkError } from '@push.rocks/smartnetwork';
+import { SmartNetwork, NetworkError, TimeoutError } from '@push.rocks/smartnetwork';
 
 try {
   await network.isRemotePortAvailable('example.com', { protocol: 'udp' });
 } catch (error) {
   if (error instanceof NetworkError) {
-    console.error(`❌ Network error: ${error.message}`);
-    console.error(`   Error code: ${error.code}`);
+    console.error(`${error.message} (code: ${error.code})`); // ENOTSUP
   }
 }
 ```
 
-### 📚 TypeScript Support
+Error codes: `EINVAL` (invalid argument), `ENOTSUP` (not supported), `ETIMEOUT` (timeout).
+
+---
 
-This package is written in TypeScript and provides comprehensive type definitions:
+### 🔧 Plugin Architecture
 
 ```typescript
-interface SmartNetworkOptions {
-  cacheTtl?: number;  // Cache TTL in milliseconds
+class MyPlugin {
+  constructor(private network: SmartNetwork) {}
+  async doStuff() { /* ... */ }
 }
 
-interface IFindFreePortOptions {
-  randomize?: boolean;  // If true, returns a random free port instead of the first one
-  exclude?: number[];   // Array of port numbers to exclude from the search
-}
+SmartNetwork.registerPlugin('myPlugin', MyPlugin);
 
-interface Hop {
-  ttl: number;        // Time to live
-  ip: string;         // IP address of the hop
-  rtt: number | null; // Round trip time in ms
-}
+const PluginClass = SmartNetwork.pluginsRegistry.get('myPlugin');
+const plugin = new PluginClass(network);
+await plugin.doStuff();
 
-// ... and many more types for complete type safety
+SmartNetwork.unregisterPlugin('myPlugin');
 ```
 
-## 🛠️ Advanced Examples
+---
 
-### Building a Network Monitor
+### 📝 Custom Logging
+
+Replace the default `console` logger:
 
 ```typescript
-const monitorNetwork = async () => {
+import { setLogger } from '@push.rocks/smartnetwork';
+
+setLogger({
+  debug: (msg) => myLogger.debug(msg),
+  info: (msg) => myLogger.info(msg),
+  warn: (msg) => myLogger.warn(msg),
+  error: (msg) => myLogger.error(msg),
+});
+```
+
+---
+
+## 🛠️ Advanced Example: Network Monitor
+
+```typescript
+const monitor = async () => {
   const network = new SmartNetwork({ cacheTtl: 30000 });
-  
+
   // Check critical services
   const services = [
-    { name: 'Web Server', host: 'example.com', port: 443 },
-    { name: 'Database', host: 'db.internal', port: 5432 },
-    { name: 'Cache', host: 'redis.internal', port: 6379 }
+    { name: 'Web', host: 'example.com', port: 443 },
+    { name: 'DB', host: 'db.internal', port: 5432 },
   ];
-  
-  for (const service of services) {
-    const isUp = await network.isRemotePortAvailable(service.host, service.port);
-    console.log(`${service.name}: ${isUp ? '✅ UP' : '❌ DOWN'}`);
+
+  for (const svc of services) {
+    const up = await network.isRemotePortAvailable(svc.host, svc.port);
+    console.log(`${svc.name}: ${up ? '✅ UP' : '❌ DOWN'}`);
   }
-  
-  // Check internet connectivity
+
+  // Internet connectivity + latency
   const ping = await network.ping('8.8.8.8');
-  console.log(`Internet: ${ping.alive ? '✅ Connected' : '❌ Disconnected'}`);
-  
-  // Measure network performance
+  console.log(`Internet: ${ping.alive ? '✅' : '❌'} (${ping.time} ms)`);
+
+  // Speed
   const speed = await network.getSpeed();
-  console.log(`Speed: ⬇️ ${speed.downloadSpeed} Mbps / ⬆️ ${speed.uploadSpeed} Mbps`);
-};
+  console.log(`Speed: ⬇️ ${speed.downloadSpeed} / ⬆️ ${speed.uploadSpeed} Mbps`);
 
-// Run monitor every minute
-setInterval(monitorNetwork, 60000);
-```
+  // Who am I?
+  const ips = await network.getPublicIps();
+  if (ips.v4) {
+    const intel = await network.getIpIntelligence(ips.v4);
+    console.log(`AS${intel.asn} (${intel.asnOrg}) — ${intel.city || intel.countryCode}`);
+  }
 
-### Service Discovery
+  // Domain recon
+  const domain = await network.getDomainIntelligence('example.com');
+  console.log(`Registrar: ${domain.registrarName}, expires: ${domain.expirationDate}`);
+  console.log(`Nameservers (${domain.nameserversSource}):`, domain.nameservers);
 
-```typescript
-const discoverServices = async () => {
-  const network = new SmartNetwork();
-  const commonPorts = [22, 80, 443, 3000, 3306, 5432, 6379, 8080, 9200];
-  
-  console.log('🔍 Scanning local services...');
-  
-  for (const port of commonPorts) {
-    const isUsed = !(await network.isLocalPortUnused(port));
-    if (isUsed) {
-      console.log(`  Port ${port}: In use (possible service running)`);
-    }
-  }
+  await network.stop();
 };
 ```
 
+## 📋 Full API Reference
+
+| Method | Description | Requires Rust |
+|--------|-------------|:---:|
+| `start()` / `stop()` | Start/stop the Rust bridge and smartdns backend | — |
+| `getSpeed(opts?)` | Cloudflare speed test (download + upload) | No |
+| `ping(host, opts?)` | ICMP ping with optional multi-ping stats | Yes |
+| `traceroute(host, opts?)` | Hop-by-hop network path analysis | Yes |
+| `isLocalPortUnused(port)` | Check if local port is free (IPv4+IPv6) | Yes |
+| `findFreePort(start, end, opts?)` | Find available port in range | Yes |
+| `isRemotePortAvailable(target, opts?)` | TCP port check on remote host | Yes |
+| `getGateways()` | List all network interfaces | No |
+| `getDefaultGateway()` | Get default gateway info | Yes |
+| `getPublicIps()` | Discover public IPv4/IPv6 (4 fallback services) | No |
+| `resolveDns(host)` | Resolve A, AAAA, MX records | No |
+| `checkEndpoint(url, opts?)` | HTTP/HTTPS health check with RTT | No |
+| `getIpIntelligence(ip)` | ASN + org + geo + RDAP registration | No |
+| `getDomainIntelligence(domain)` | Registrar, nameservers, events, DNS records, DNSSEC | No |
+
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
 Task Venture Capital GmbH  
-Registered at District court Bremen HRB 35230 HB, Germany
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.