@aluvia/sdk 1.0.0

package/dist/types/client/ConfigManager.d.ts

@@ -0,0 +1,100 @@
+import type { GatewayProtocol, LogLevel } from './types.js';
+/**
+ * Raw proxy configuration derived from the account-connection response and client options.
+ */
+export type RawProxyConfig = {
+    protocol: GatewayProtocol;
+    host: 'gateway.aluvia.io';
+    port: number;
+    username: string;
+    password: string;
+};
+/**
+ * Complete connection network configuration including proxy, rules, and metadata.
+ */
+export type ConnectionNetworkConfig = {
+    rawProxy: RawProxyConfig;
+    rules: string[];
+    sessionId: string | null;
+    targetGeo: string | null;
+    /**
+     * ETag returned by the API for this config snapshot (if present).
+     * Used for efficient conditional polling via If-None-Match.
+     */
+    etag: string | null;
+};
+/**
+ * Options for ConfigManager constructor.
+ */
+export type ConfigManagerOptions = {
+    apiKey: string;
+    apiBaseUrl: string;
+    pollIntervalMs: number;
+    gatewayProtocol: GatewayProtocol;
+    gatewayPort: number;
+    logLevel: LogLevel;
+    /**
+     * Optional: if provided, use /account/connections/:id.
+     * If omitted, init() will attempt POST /account/connections.
+     */
+    connectionId?: number;
+    /**
+     * Optional: strict behavior (default true).
+     *
+     * If true, init() throws when it cannot load/create a usable config.
+     * If false, init() may return without config (client proxy mode can still start
+     * and will route direct until config becomes available).
+     */
+    strict?: boolean;
+};
+/**
+ * ConfigManager handles fetching and maintaining connection configuration from the Aluvia API.
+ *
+ * Responsibilities:
+ * - Initial fetch of account connection config
+ * - Polling for updates using ETag
+ * - Providing current config to ProxyServer
+ */
+export declare class ConfigManager {
+    private config;
+    private timer;
+    private readonly logger;
+    private readonly options;
+    private readonly strict;
+    private accountConnectionId;
+    private pollInFlight;
+    constructor(options: ConfigManagerOptions);
+    /**
+     * Fetch initial configuration from the account connections API.
+     * Must be called before starting the proxy.
+     *
+     * @throws InvalidApiKeyError if apiKey is invalid (401/403)
+     * @throws ApiError for other API errors
+     */
+    init(): Promise<void>;
+    /**
+     * Start polling for configuration updates.
+     * Uses ETag for efficient conditional requests.
+     */
+    startPolling(): void;
+    /**
+     * Stop polling for configuration updates.
+     */
+    stopPolling(): void;
+    /**
+     * Get the current configuration.
+     * Returns null if init() hasn't been called or failed.
+     */
+    getConfig(): ConnectionNetworkConfig | null;
+    setConfig(body: Object): Promise<ConnectionNetworkConfig | null>;
+    /**
+     * Perform a single poll iteration.
+     * Called by the polling timer.
+     */
+    private pollOnce;
+    /**
+     * Build ConnectionNetworkConfig from API response.
+     */
+    private buildConfigFromAny;
+    private redactConfig;
+}

package/dist/types/client/ProxyServer.d.ts

@@ -0,0 +1,47 @@
+import type { ConfigManager } from './ConfigManager.js';
+import type { LogLevel } from './types.js';
+/**
+ * Result of starting the proxy server.
+ */
+export type ProxyServerInfo = {
+    host: string;
+    port: number;
+    url: string;
+};
+/**
+ * ProxyServer manages the local HTTP(S) proxy that routes traffic
+ * through Aluvia or directly based on rules.
+ */
+export declare class ProxyServer {
+    private server;
+    private readonly configManager;
+    private readonly logger;
+    private readonly bindHost;
+    private static readonly NO_CONFIG_WARN_INTERVAL_MS;
+    private lastNoConfigWarnAt;
+    private suppressedNoConfigWarnCount;
+    constructor(configManager: ConfigManager, options?: {
+        logLevel?: LogLevel;
+    });
+    /**
+     * Start the local proxy server.
+     *
+     * @param port - Optional port to listen on. If not provided, OS assigns a free port.
+     * @returns ProxyServerInfo with host, port, and url
+     * @throws ProxyStartError if server fails to start
+     */
+    start(port?: number): Promise<ProxyServerInfo>;
+    /**
+     * Stop the local proxy server.
+     */
+    stop(): Promise<void>;
+    /**
+     * Handle incoming proxy requests.
+     * Decides whether to route through Aluvia or direct.
+     */
+    private handleRequest;
+    /**
+     * Extract hostname from request parameters.
+     */
+    private extractHostname;
+}

package/dist/types/client/adapters.d.ts

@@ -0,0 +1,26 @@
+import type { Dispatcher } from 'undici';
+import type { Agent as NodeAgent } from 'node:http';
+import type { PlaywrightProxySettings } from './types.js';
+export type NodeProxyAgents = {
+    http: NodeAgent;
+    https: NodeAgent;
+};
+export type AxiosProxyConfig = {
+    proxy: false;
+    httpAgent: NodeAgent;
+    httpsAgent: NodeAgent;
+};
+export type GotProxyOptions = {
+    agent: {
+        http: NodeAgent;
+        https: NodeAgent;
+    };
+};
+export declare function toPlaywrightProxySettings(serverUrl: string): PlaywrightProxySettings;
+export declare function toPuppeteerArgs(serverUrl: string): Array<string>;
+export declare function toSeleniumArgs(serverUrl: string): string;
+export declare function createNodeProxyAgents(serverUrl: string): NodeProxyAgents;
+export declare function toAxiosConfig(agents: NodeProxyAgents): AxiosProxyConfig;
+export declare function toGotOptions(agents: NodeProxyAgents): GotProxyOptions;
+export declare function createUndiciDispatcher(serverUrl: string): Dispatcher;
+export declare function createUndiciFetch(dispatcher: Dispatcher): typeof fetch;

package/dist/types/client/logger.d.ts

@@ -0,0 +1,33 @@
+import type { LogLevel } from './types.js';
+/**
+ * Simple logger that respects log levels.
+ *
+ * Log level hierarchy:
+ * - 'silent': only error() logs
+ * - 'info': info(), warn(), error() log
+ * - 'debug': all methods log
+ */
+export declare class Logger {
+    private readonly level;
+    constructor(level: LogLevel);
+    /**
+     * Log informational messages.
+     * Logs when level is 'info' or 'debug'.
+     */
+    info(...args: unknown[]): void;
+    /**
+     * Log debug messages.
+     * Logs only when level is 'debug'.
+     */
+    debug(...args: unknown[]): void;
+    /**
+     * Log warning messages.
+     * Logs when level is not 'silent'.
+     */
+    warn(...args: unknown[]): void;
+    /**
+     * Log error messages.
+     * Always logs regardless of level.
+     */
+    error(...args: unknown[]): void;
+}

package/dist/types/client/rules.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Match a hostname against a pattern.
+ *
+ * Supported patterns:
+ * - '*' matches any hostname
+ * - '*.example.com' matches subdomains of example.com (but not example.com itself)
+ * - 'example.com' exact match
+ * - 'google.*' matches google.com, google.co.uk, etc.
+ *
+ * @param hostname - The hostname to match
+ * @param pattern - The pattern to match against
+ * @returns true if hostname matches pattern
+ */
+export declare function matchPattern(hostname: string, pattern: string): boolean;
+/**
+ * Determine if a hostname should be proxied based on rules.
+ *
+ * Rules semantics:
+ * - [] (empty) → no proxy (return false)
+ * - ['*'] → proxy everything
+ * - ['example.com'] → proxy only example.com
+ * - ['*.google.com'] → proxy subdomains of google.com
+ * - ['*', '-example.com'] → proxy everything except example.com
+ * - ['AUTO', 'example.com'] → AUTO is placeholder (ignored), proxy example.com
+ *
+ * Negative patterns (prefixed with '-') exclude hosts from proxying.
+ * If '*' is in rules, default is to proxy unless excluded.
+ * Without '*', only explicitly matched patterns are proxied.
+ *
+ * @param hostname - The hostname to check
+ * @param rules - Array of rule patterns
+ * @returns true if the hostname should be proxied
+ */
+export declare function shouldProxy(hostname: string, rules: string[]): boolean;

package/dist/types/client/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Protocol used to connect to the Aluvia gateway.
+ */
+export type GatewayProtocol = 'http' | 'https';
+/**
+ * Log level for the client.
+ */
+export type LogLevel = 'silent' | 'info' | 'debug';
+export type PlaywrightProxySettings = {
+    server: string;
+    username?: string;
+    password?: string;
+};
+/**
+ * Options for creating an AluviaClient instance.
+ */
+export type AluviaClientOptions = {
+    /**
+     * Required: user API apiKey (Bearer).
+     * This is the apiKey for a single Aluvia user/agent.
+     */
+    apiKey: string;
+    /**
+     * Optional: base URL for the Aluvia API.
+     * Default: 'https://api.aluvia.io/v1'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Optional: polling interval for refreshing account connection config.
+     * Default: 5000 ms.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Optional: request timeout for API calls made via `client.api`.
+     * Default: 30000 ms.
+     */
+    timeoutMs?: number;
+    /**
+     * Optional: how the client talks to the Aluvia gateway.
+     *
+     * - 'http'  -> gatewayPort defaults to 8080
+     * - 'https' -> gatewayPort defaults to 8443
+     *
+     * Default: 'http'.
+     */
+    gatewayProtocol?: GatewayProtocol;
+    /**
+     * Optional: upstream Aluvia gateway port.
+     *
+     * If omitted:
+     *   - 8080 is used when gatewayProtocol === 'http'
+     *   - 8443 is used when gatewayProtocol === 'https'
+     */
+    gatewayPort?: number;
+    /**
+     * Optional: local port for the agent's *local* proxy (127.0.0.1:<localPort>).
+     *
+     * If omitted, the client will pick a free port automatically by binding to port 0.
+     */
+    localPort?: number;
+    /**
+     * Optional: logging verbosity for the client.
+     */
+    logLevel?: LogLevel;
+    /**
+     * Optional: use an existing account connection by ID.
+     *
+     * If provided, the client retrieves config via:
+     *   GET /account/connections/:connection_id
+     *
+     * If omitted, the client will attempt to create a new account connection via:
+     *   POST /account/connections
+     */
+    connectionId?: number;
+    /**
+     * Optional: enable local proxy mode (client proxy mode).
+     *
+     * If true (default): start the local proxy (127.0.0.1:<port>) and route traffic dynamically.
+     * If false: do NOT start a local proxy; adapters return gateway proxy settings
+     * from the account connection API response for direct use by Playwright/Axios/etc.
+     */
+    localProxy?: boolean;
+    /**
+     * Optional: strict startup behavior.
+     *
+     * If true (default): `client.start()` throws if the SDK cannot load/create
+     * an account connection config (proxy credentials + rules). This prevents
+     * "silent direct routing" where the local proxy starts but bypasses Aluvia.
+     *
+     * If false: in client proxy mode, the SDK may still start a local proxy and
+     * route traffic directly when config is unavailable.
+     */
+    strict?: boolean;
+};
+/**
+ * Represents an active Aluvia Client connection.
+ */
+export type AluviaClientConnection = {
+    /**
+     * Proxy host to configure in your client.
+     *
+     * - In client proxy mode (localProxy: true): this is the local proxy host ('127.0.0.1').
+     * - In gateway mode: this is the Aluvia gateway host (typically 'gateway.aluvia.io').
+     */
+    host: string;
+    /**
+     * Proxy port to configure in your client.
+     *
+     * - In client proxy mode (localProxy: true): this is the local proxy port.
+     * - In gateway mode: this is the Aluvia gateway port (typically 8080 or 8443).
+     */
+    port: number;
+    /**
+     * Convenience URL for the proxy server endpoint (without embedding credentials).
+     *
+     * - In client proxy mode (localProxy: true): 'http://127.0.0.1:<port>'
+     * - In gateway mode: '<protocol>://gateway.aluvia.io:<port>'
+     *
+     * (The local proxy itself is always HTTP; it may tunnel to an HTTP or HTTPS
+     * gateway upstream based on gatewayProtocol/gatewayPort.)
+     */
+    url: string;
+    /**
+     * Returns a credential-embedded proxy URL intended for clients that require auth in the URL.
+     *
+     * Note: This value contains secrets (proxy username/password). Avoid logging it or putting it
+     * in places that may be exposed (e.g., process args).
+     */
+    getUrl(): string;
+    /**
+     * Playwright adapter for chromium/firefox/webkit launch options.
+     */
+    asPlaywright(): PlaywrightProxySettings;
+    /**
+     * Puppeteer adapter for launch args.
+     */
+    asPuppeteer(): Array<string>;
+    /**
+     * Selenium adapter for launch args.
+     */
+    asSelenium(): string;
+    /**
+     * Node HTTP(S) proxy agents for libraries that accept per-protocol agents.
+     *
+     * Useful for: Axios, got, node-fetch (legacy).
+     */
+    asNodeAgents(): {
+        http: import('node:http').Agent;
+        https: import('node:http').Agent;
+    };
+    /**
+     * Axios adapter config.
+     *
+     * Returns `{ proxy: false, httpAgent, httpsAgent }` so Axios uses the provided agents
+     * instead of its built-in proxy option handling.
+     */
+    asAxiosConfig(): {
+        proxy: false;
+        httpAgent: import('node:http').Agent;
+        httpsAgent: import('node:http').Agent;
+    };
+    /**
+     * got adapter options.
+     *
+     * Returns `{ agent: { http, https } }`.
+     */
+    asGotOptions(): {
+        agent: {
+            http: import('node:http').Agent;
+            https: import('node:http').Agent;
+        };
+    };
+    /**
+     * undici proxy dispatcher (for undici fetch / undici clients).
+     */
+    asUndiciDispatcher(): import('undici').Dispatcher;
+    /**
+     * Returns a `fetch` function powered by undici that uses the proxy dispatcher per request.
+     *
+     * Note: Node's built-in `fetch()` does not accept a Node `Agent`. Use this for proxying
+     * fetch calls through Aluvia.
+     */
+    asUndiciFetch(): typeof fetch;
+    /**
+     * Stop this proxy instance:
+     * - Close the local proxy server.
+     * - Stop using it for new connections.
+     */
+    stop(): Promise<void>;
+    /**
+     * Alias for stop().
+     */
+    close(): Promise<void>;
+};

package/dist/types/errors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Thrown when the apiKey is not provided to AluviaClient.
+ */
+export declare class MissingApiKeyError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when the API returns 401 or 403, indicating the apiKey is invalid.
+ */
+export declare class InvalidApiKeyError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown for general API errors (non-2xx responses other than auth errors).
+ */
+export declare class ApiError extends Error {
+    readonly statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * Thrown when the local proxy server fails to start.
+ */
+export declare class ProxyStartError extends Error {
+    constructor(message?: string);
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { AluviaClient } from './client/AluviaClient.js';
+export { AluviaApi } from './api/AluviaApi.js';
+export { MissingApiKeyError, InvalidApiKeyError, ApiError, ProxyStartError, } from './errors.js';
+export type { GatewayProtocol, LogLevel, AluviaClientOptions, AluviaClientConnection, PlaywrightProxySettings, } from './client/types.js';
+export type { Account, AccountUsage, AccountPayment, AccountConnection, AccountConnectionDeleteResult, Geo, SuccessEnvelope, ErrorEnvelope, Envelope, } from './api/types.js';

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@aluvia/sdk",
+  "version": "1.0.0",
+  "description": "Aluvia SDK for Node.js - local smart proxy for automation workloads and AI agents",
+  "license": "MIT",
+  "author": "Aluvia",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aluvia-connect/sdk-node.git"
+  },
+  "homepage": "https://aluvia.io",
+  "bugs": {
+    "url": "https://github.com/aluvia-connect/sdk-node/issues"
+  },
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node -e \"require('fs').mkdirSync('dist/cjs',{recursive:true});require('fs').writeFileSync('dist/cjs/package.json','{\\\"type\\\":\\\"commonjs\\\"}')\"",
+    "prepare": "npm run build",
+    "test": "node --import tsx --test test/integration.test.ts",
+    "lint": "prettier --check src test",
+    "lint:fix": "prettier --write src test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "proxy",
+    "ai-agent",
+    "playwright",
+    "puppeteer",
+    "aluvia"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.10.2",
+    "axios": "^1.13.2",
+    "prettier": "^3.4.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "http-proxy-agent": "^7.0.2",
+    "https-proxy-agent": "^7.0.6",
+    "proxy-chain": "^2.6.1",
+    "undici": "^6.22.0"
+  }
+}