about-system 0.0.16 → 0.0.18

package/dist/system-info-api.d.ts

@@ -0,0 +1,259 @@
+import { SystemInfo } from './systeminfo-types.js';
+import { SystemInfoOptions } from './systeminfo-types.js';
+
+/**
+ * Cache storage structure
+ * @interface Cache
+ */
+declare interface Cache {
+    [key: string]: CacheEntry;
+}
+
+/**
+ * Represents a cached value with timestamp
+ * @interface CacheEntry
+ */
+declare interface CacheEntry {
+    /** The cached value */
+    value: any;
+    /** Unix timestamp when the value was cached */
+    timestamp: number;
+}
+
+/**
+ * Get all system information as a clean JSON object
+ * @param options Configuration options
+ * @returns Promise resolving to SystemInfo object
+ */
+export declare function getSystemInfo(options?: SystemInfoOptions): Promise<SystemInfo>;
+
+/**
+ * Context object passed to info collection functions
+ * @interface InfoContext
+ */
+declare interface InfoContext {
+    /** Cache storage */
+    cache: Cache;
+    /** IP information from external API */
+    ipInfo?: IPInfo;
+}
+
+/**
+ * System information collection functions
+ * Each function returns a clean string value without formatting
+ * @namespace infoFunctions
+ */
+export declare const infoFunctions: {
+    /**
+     * Gets the current username
+     * @returns Current system username
+     */
+    user(): string;
+    /**
+     * Gets the system hostname
+     * @returns Computer hostname/network name
+     */
+    hostname(): string;
+    /**
+     * Gets public IP address from ipinfo.io
+     * @param context - Info context with cache and IP info
+     * @returns Public IPv4 address or empty string
+     * @example "203.0.113.42"
+     */
+    ip(context: InfoContext): Promise<string>;
+    /**
+     * Gets local/private IP address(es)
+     * Tries ifconfig and ip commands on Linux, falls back to Node.js API
+     * @returns Space-separated local IP addresses (RFC 1918 ranges)
+     * @example "192.168.1.100" or "10.0.0.50 192.168.1.100"
+     */
+    iplocal(): string;
+    /**
+     * Gets geographic city based on public IP
+     * @param context - Info context with IP geolocation data
+     * @returns City name or empty string
+     * @example "San Francisco", "New York", "London"
+     */
+    city(context: InfoContext): Promise<string>;
+    /**
+     * Gets reverse DNS hostname with HTTP prefix
+     * @param context - Info context with IP info
+     * @returns Domain with http:// prefix or empty string
+     * @example "http://example.com", "http://host-203-0-113-42.example.net"
+     */
+    domain(context: InfoContext): Promise<string>;
+    /**
+     * Gets Internet Service Provider name
+     * Strips AS number prefix from organization string
+     * @param context - Info context with IP info
+     * @returns ISP name or empty string
+     * @example "Comcast Cable", "Verizon Business", "Cloudflare Inc"
+     */
+    isp(context: InfoContext): Promise<string>;
+    /**
+     * Gets operating system name and version
+     * Platform-specific detection for Windows, macOS, and Linux
+     * @param context - Info context with cache
+     * @returns OS name and version string
+     * @example "Windows 11 Pro", "macOS Ventura 13.2.1", "Ubuntu 22.04.3 LTS"
+     */
+    os(context: InfoContext): string;
+    /**
+     * Gets CPU model name and specifications
+     * Uses platform-specific commands (wmic/lscpu/cpuinfo)
+     * Automatically strips "with Radeon Graphics" and similar suffixes
+     * @param context - Info context with cache
+     * @returns CPU model string or empty string
+     * @example "Intel Core i7-12700K", "AMD Ryzen 9 5900HX", "Apple M2 Pro"
+     */
+    cpu(context: InfoContext): string;
+    /**
+     * Gets graphics card model name
+     * Extracts GPU info from lspci (Linux) or WMI (Windows)
+     * Filters out basic/generic display adapters
+     * @param context - Info context with cache
+     * @returns GPU model string or empty string
+     * @example "NVIDIA GeForce RTX 4070", "AMD Radeon RX 6800 XT"
+     */
+    gpu(context: InfoContext): string;
+    /**
+     * Gets root filesystem disk usage percentage
+     * Uses df command on Linux/Android
+     * @param context - Info context with cache
+     * @returns Percentage string or empty string
+     * @example "45%", "78%"
+     */
+    disk_used(context: InfoContext): string;
+    /**
+     * Gets memory usage in gigabytes
+     * Reads from /proc/meminfo on Linux, falls back to os.totalmem()
+     * @param context - Info context with cache
+     * @returns Memory usage as "used/total GB"
+     * @example "12/32GB", "6/16GB"
+     */
+    ram_used(context: InfoContext): string;
+    /**
+     * Gets the highest CPU-consuming process
+     * Uses ps command to find top process by CPU usage (Linux only)
+     * @param context - Info context with cache
+     * @returns Process info as "percentage processname" or empty string
+     * @example "8% firefox", "15% chrome", "3% systemd"
+     */
+    top_process(context: InfoContext): string;
+    /**
+     * Gets system uptime since last boot
+     * @returns Uptime formatted as "Xd Yh Zm"
+     * @example "2d 14h 23m", "0d 3h 45m"
+     */
+    uptime(): string;
+    /**
+     * Gets device or computer model name
+     * Uses WMI on Windows, DMI on Linux, getprop on Android
+     * @param context - Info context with cache
+     * @returns Device model name or empty string
+     * @example "Dell OptiPlex 7090", "MacBook Pro 16-inch", "Valve Steam Deck"
+     */
+    device(context: InfoContext): string;
+    /**
+     * Gets kernel version string
+     * Returns the operating system kernel version from os.release()
+     * @param context - Info context with cache
+     * @returns Kernel version string
+     * @example "5.15.0-56-generic", "6.11.11-valve12-1-neptune"
+     */
+    kernel(context: InfoContext): string;
+    /**
+     * Gets the current shell name
+     * Uses ps command to find parent process shell (Linux/Unix only)
+     * @returns Shell name or empty string on Windows
+     * @example "bash", "zsh", "fish", "nu"
+     */
+    shell(): string;
+    /**
+     * Gets available package managers and development tools
+     * Checks for package managers (apt, yum, npm, etc.) and editors (nvim, hx)
+     * @param context - Info context with cache
+     * @returns Space-separated list of available commands
+     * @example "apt npm docker nvim", "yay pacman bun hx"
+     */
+    pacman(context: InfoContext): string;
+    /**
+     * Gets open TCP ports with service names
+     * Uses lsof to find listening TCP ports (Linux only)
+     * @param context - Info context with cache
+     * @returns Space-separated port+process pairs or empty string
+     * @example "80http 443http 22ssh", "3000node 5432post"
+     */
+    ports(context: InfoContext): string;
+    /**
+     * Gets running Docker container names
+     * Lists active Docker containers with their names
+     * @param context - Info context with cache
+     * @returns Space-separated container names or empty string
+     * @example "nginx redis postgres", "web-app db-server"
+     */
+    containers(context: InfoContext): string;
+    /**
+     * Gets available memory in gigabytes
+     * Reads MemAvailable from /proc/meminfo (Linux only)
+     * @returns Available memory with "GB available" suffix or empty string
+     * @example "12GB available", "4GB available"
+     */
+    memory_available(): string;
+    /**
+     * Gets swap memory usage
+     * Calculates swap usage from /proc/meminfo (Linux only)
+     * @returns Swap usage as "percentage (size MB) swap" or empty string
+     * @example "15% (512MB) swap", "0% (0MB) swap"
+     */
+    swap_used(): string;
+    /**
+     * Gets system load averages
+     * Reads 1, 5, and 15 minute load averages from /proc/loadavg (Linux only)
+     * @returns Space-separated load averages (1m 5m 15m) or empty string
+     * @example "0.52 0.58 0.59", "2.10 1.95 1.88"
+     */
+    load_average(): string;
+    /**
+     * Gets number of logged in users
+     * Uses who command to count active user sessions (Linux only)
+     * @returns User count with "users" suffix or empty string
+     * @example "3 users", "1 users"
+     */
+    users_logged_in(): string;
+    network_interfaces(context: InfoContext): string;
+    mount_points(context: InfoContext): string;
+    services_running(context: InfoContext): string;
+    temperature(context: InfoContext): string;
+    battery(context: InfoContext): string;
+    screen_resolution(): string;
+};
+
+/**
+ * IP information from ipinfo.io API
+ * @interface IPInfo
+ */
+declare interface IPInfo {
+    /** Public IP address */
+    ip?: string;
+    /** City location */
+    city?: string;
+    /** Reverse DNS hostname */
+    hostname?: string;
+    /** ISP organization string (includes AS number) */
+    org?: string;
+}
+
+/**
+ * Loads cache from disk
+ * @returns {Cache} Cached data or empty object if cache doesn't exist or is corrupted
+ */
+export declare function loadCache(): Cache;
+
+/**
+ * Saves cache to disk
+ * @param {Cache} cache - Cache object to save
+ */
+export declare function saveCache(cache: Cache): void;
+
+export { }