@aluvia/sdk 1.0.0

package/dist/cjs/client/ConfigManager.js

@@ -0,0 +1,303 @@
+"use strict";
+// ConfigManager - Control plane for connection configuration
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigManager = void 0;
+const logger_js_1 = require("./logger.js");
+const errors_js_1 = require("../errors.js");
+const request_js_1 = require("../api/request.js");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function toAccountConnectionApiResponse(value) {
+    if (!isRecord(value))
+        return {};
+    const data = value['data'];
+    if (!isRecord(data))
+        return {};
+    return { data: data };
+}
+function toValidationErrors(value) {
+    if (!isRecord(value))
+        return null;
+    const apiError = value['error'];
+    if (!isRecord(apiError))
+        return null;
+    if (apiError['code'] !== 'validation_error')
+        return null;
+    const details = apiError['details'];
+    const errors = [];
+    if (isRecord(details)) {
+        for (const fieldMessages of Object.values(details)) {
+            if (Array.isArray(fieldMessages)) {
+                for (const message of fieldMessages) {
+                    if (typeof message === 'string') {
+                        errors.push(message);
+                    }
+                }
+            }
+        }
+    }
+    return errors.length ? errors : null;
+}
+/**
+ * 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
+ */
+class ConfigManager {
+    constructor(options) {
+        this.config = null;
+        this.timer = null;
+        this.pollInFlight = false;
+        this.options = options;
+        this.logger = new logger_js_1.Logger(options.logLevel);
+        this.strict = options.strict ?? true;
+    }
+    /**
+     * 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
+     */
+    async init() {
+        if (this.options.connectionId) {
+            this.accountConnectionId = this.options.connectionId ?? null;
+            this.logger.info(`Using account connection API (connection id: ${this.accountConnectionId})`);
+            let result;
+            try {
+                result = await (0, request_js_1.requestCore)({
+                    apiBaseUrl: this.options.apiBaseUrl,
+                    apiKey: this.options.apiKey,
+                    method: 'GET',
+                    path: `/account/connections/${this.accountConnectionId}`,
+                });
+            }
+            catch (err) {
+                if (err instanceof errors_js_1.ApiError)
+                    throw err;
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new errors_js_1.ApiError(`Failed to fetch account connection config: ${msg}`);
+            }
+            if (result.status === 401 || result.status === 403) {
+                throw new errors_js_1.InvalidApiKeyError(`Authentication failed with status ${result.status}`);
+            }
+            if (result.status === 200 && result.body) {
+                this.config = this.buildConfigFromAny(result.body, result.etag);
+                this.logger.info('Configuration loaded successfully');
+                this.logger.debug('Config summary:', this.redactConfig(this.config));
+                return;
+            }
+            throw new errors_js_1.ApiError(`Failed to fetch account connection config: HTTP ${result.status}`, result.status);
+        }
+        // No connectionId: create an account connection (preferred)
+        this.logger.info('No connectionId provided; creating account connection...');
+        try {
+            const created = await (0, request_js_1.requestCore)({
+                apiBaseUrl: this.options.apiBaseUrl,
+                apiKey: this.options.apiKey,
+                method: 'POST',
+                path: '/account/connections',
+                body: {},
+            });
+            if (created.status === 401 || created.status === 403) {
+                throw new errors_js_1.InvalidApiKeyError(`Authentication failed with status ${created.status}`);
+            }
+            if ((created.status === 200 || created.status === 201) && created.body) {
+                const createdResponse = toAccountConnectionApiResponse(created.body);
+                this.accountConnectionId = Number(createdResponse.data?.connection_id);
+                if (this.accountConnectionId != null) {
+                    this.logger.info(`Account connection created (connection id: ${this.accountConnectionId})`);
+                }
+                else {
+                    this.logger.info('Account connection created (connection id unavailable in response)');
+                }
+                this.config = this.buildConfigFromAny(created.body, created.etag);
+                this.logger.info('Configuration loaded successfully');
+                this.logger.debug('Config summary:', this.redactConfig(this.config));
+                return;
+            }
+            const msg = `Failed to create account connection config: HTTP ${created.status}`;
+            if (this.strict) {
+                throw new errors_js_1.ApiError(msg, created.status);
+            }
+            this.logger.warn(`${msg}; continuing without config (strict=false)`);
+            return;
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.InvalidApiKeyError)
+                throw err;
+            if (err instanceof errors_js_1.ApiError) {
+                if (this.strict)
+                    throw err;
+                this.logger.warn('Create account connection failed; continuing without config (strict=false)', err);
+                return;
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            if (this.strict) {
+                throw new errors_js_1.ApiError(`Failed to create account connection config: ${msg}`);
+            }
+            this.logger.warn('Create account connection failed; continuing without config (strict=false)', err);
+            return;
+        }
+    }
+    /**
+     * Start polling for configuration updates.
+     * Uses ETag for efficient conditional requests.
+     */
+    startPolling() {
+        // Don't start if already polling
+        if (this.timer) {
+            this.logger.debug('Polling already active, skipping startPolling()');
+            return;
+        }
+        this.logger.info(`Starting config polling every ${this.options.pollIntervalMs}ms`);
+        this.timer = setInterval(async () => {
+            if (this.pollInFlight) {
+                this.logger.debug('Previous poll still running, skipping this poll tick');
+                return;
+            }
+            this.pollInFlight = true;
+            try {
+                await this.pollOnce();
+            }
+            finally {
+                this.pollInFlight = false;
+            }
+        }, this.options.pollIntervalMs);
+    }
+    /**
+     * Stop polling for configuration updates.
+     */
+    stopPolling() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.logger.info('Config polling stopped');
+        }
+    }
+    /**
+     * Get the current configuration.
+     * Returns null if init() hasn't been called or failed.
+     */
+    getConfig() {
+        return this.config;
+    }
+    async setConfig(body) {
+        this.logger.debug(`Setting config: ${JSON.stringify(body)}`);
+        let result;
+        try {
+            result = await (0, request_js_1.requestCore)({
+                apiBaseUrl: this.options.apiBaseUrl,
+                apiKey: this.options.apiKey,
+                method: 'PATCH',
+                path: `/account/connections/${this.accountConnectionId}`,
+                body,
+            });
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.ApiError)
+                throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new errors_js_1.ApiError(`Failed to update account connection config: ${msg}`);
+        }
+        if (result.status === 401 || result.status === 403) {
+            throw new errors_js_1.InvalidApiKeyError(`Authentication failed with status ${result.status}`);
+        }
+        if (result.status === 200 && result.body) {
+            this.config = this.buildConfigFromAny(result.body, result.etag);
+            this.logger.debug('Configuration updated from API');
+            this.logger.debug('New config summary:', this.redactConfig(this.config));
+            return this.config;
+        }
+        if (result.status === 422 && result.body) {
+            const validationErrors = toValidationErrors(result.body);
+            if (validationErrors) {
+                throw new errors_js_1.ApiError(`Failed to update account connection config: ${validationErrors[0]}`, result.status);
+            }
+        }
+        throw new errors_js_1.ApiError(`Failed to update account connection config: HTTP ${result.status}`, result.status);
+    }
+    /**
+     * Perform a single poll iteration.
+     * Called by the polling timer.
+     */
+    async pollOnce() {
+        if (!this.config) {
+            this.logger.warn('No config available, skipping poll');
+            return;
+        }
+        try {
+            const result = await (0, request_js_1.requestCore)({
+                apiBaseUrl: this.options.apiBaseUrl,
+                apiKey: this.options.apiKey,
+                method: 'GET',
+                path: `/account/connections/${this.accountConnectionId}`,
+                ifNoneMatch: this.config.etag,
+            });
+            if (result.status === 304) {
+                this.logger.debug('Config unchanged (304 Not Modified)');
+                return;
+            }
+            if (result.status === 200 && result.body) {
+                this.config = this.buildConfigFromAny(result.body, result.etag);
+                this.logger.debug('Configuration updated from API');
+                this.logger.debug('New config summary:', this.redactConfig(this.config));
+                return;
+            }
+            this.logger.warn(`Poll returned unexpected status ${result.status}`);
+        }
+        catch (error) {
+            this.logger.warn('Poll failed, keeping existing config:', error);
+        }
+    }
+    /**
+     * Build ConnectionNetworkConfig from API response.
+     */
+    buildConfigFromAny(body, etag) {
+        const response = toAccountConnectionApiResponse(body);
+        const data = response.data;
+        const rules = Array.isArray(data?.rules) ? data.rules : [];
+        const sessionId = data?.session_id ?? null;
+        const targetGeo = data?.target_geo ?? null;
+        const username = data?.proxy_username ?? null;
+        const password = data?.proxy_password ?? null;
+        if (!username || !password) {
+            throw new errors_js_1.ApiError('Account connection response missing proxy credentials (data.proxy_username and data.proxy_password are required)', 500);
+        }
+        return {
+            rawProxy: {
+                protocol: this.options.gatewayProtocol,
+                host: 'gateway.aluvia.io',
+                port: this.options.gatewayPort,
+                username,
+                password,
+            },
+            rules,
+            sessionId,
+            targetGeo,
+            etag,
+        };
+    }
+    redactConfig(config) {
+        if (!config)
+            return null;
+        return {
+            rulesCount: config.rules?.length ?? 0,
+            sessionId: config.sessionId,
+            targetGeo: config.targetGeo,
+            etag: config.etag,
+            rawProxy: {
+                protocol: config.rawProxy.protocol,
+                host: config.rawProxy.host,
+                port: config.rawProxy.port,
+                username: config.rawProxy.username ? '[set]' : '[missing]',
+                password: config.rawProxy.password ? '[set]' : '[missing]',
+            },
+        };
+    }
+}
+exports.ConfigManager = ConfigManager;

package/dist/cjs/client/ProxyServer.js

@@ -0,0 +1,182 @@
+"use strict";
+// ProxyServer - Local HTTP proxy using proxy-chain
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyServer = void 0;
+const proxy_chain_1 = require("proxy-chain");
+const logger_js_1 = require("./logger.js");
+const errors_js_1 = require("../errors.js");
+const rules_js_1 = require("./rules.js");
+/**
+ * ProxyServer manages the local HTTP(S) proxy that routes traffic
+ * through Aluvia or directly based on rules.
+ */
+class ProxyServer {
+    constructor(configManager, options) {
+        this.server = null;
+        this.bindHost = '127.0.0.1';
+        this.lastNoConfigWarnAt = 0;
+        this.suppressedNoConfigWarnCount = 0;
+        this.configManager = configManager;
+        this.logger = new logger_js_1.Logger(options?.logLevel ?? 'info');
+    }
+    /**
+     * 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
+     */
+    async start(port) {
+        const listenPort = port ?? 0;
+        try {
+            this.server = new proxy_chain_1.Server({
+                // Security: bind to loopback only (proxy-chain defaults to 0.0.0.0 if host is omitted)
+                host: this.bindHost,
+                port: listenPort,
+                prepareRequestFunction: this.handleRequest.bind(this),
+            });
+            await this.server.listen();
+            // Get the actual port (especially important when port was 0)
+            const address = this.server.server.address();
+            const actualPort = address.port;
+            const info = {
+                host: this.bindHost,
+                port: actualPort,
+                url: `http://${this.bindHost}:${actualPort}`,
+            };
+            this.logger.info(`Proxy server listening on ${info.url}`);
+            return info;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Unknown error';
+            throw new errors_js_1.ProxyStartError(`Failed to start proxy server: ${message}`);
+        }
+    }
+    /**
+     * Stop the local proxy server.
+     */
+    async stop() {
+        if (!this.server) {
+            return;
+        }
+        try {
+            await this.server.close(true);
+            this.logger.info('Proxy server stopped');
+        }
+        finally {
+            this.server = null;
+        }
+    }
+    /**
+     * Handle incoming proxy requests.
+     * Decides whether to route through Aluvia or direct.
+     */
+    handleRequest(params) {
+        // Get current config
+        const config = this.configManager.getConfig();
+        if (!config) {
+            const now = Date.now();
+            const shouldWarn = this.lastNoConfigWarnAt === 0 ||
+                now - this.lastNoConfigWarnAt >= ProxyServer.NO_CONFIG_WARN_INTERVAL_MS;
+            if (shouldWarn) {
+                const suppressed = this.suppressedNoConfigWarnCount;
+                this.suppressedNoConfigWarnCount = 0;
+                this.lastNoConfigWarnAt = now;
+                const suffix = suppressed > 0 ? ` (suppressed ${suppressed} similar warnings)` : '';
+                this.logger.warn(`No config available, bypassing proxy (direct)${suffix}`);
+            }
+            else {
+                this.suppressedNoConfigWarnCount += 1;
+                this.logger.debug('No config available, bypassing proxy (direct)');
+            }
+            return undefined;
+        }
+        // Extract hostname
+        const hostname = this.extractHostname(params);
+        if (!hostname) {
+            this.logger.debug('Could not extract hostname, going direct');
+            return undefined;
+        }
+        // Check if we should proxy this hostname
+        const useProxy = (0, rules_js_1.shouldProxy)(hostname, config.rules);
+        if (!useProxy) {
+            this.logger.debug(`Hostname ${hostname} bypassing proxy (direct)`);
+            return undefined;
+        }
+        // Build upstream proxy URL
+        const { protocol, host, port, username, password } = config.rawProxy;
+        const upstreamProxyUrl = `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+        this.logger.debug(`Hostname ${hostname} routing through Aluvia`);
+        return { upstreamProxyUrl };
+    }
+    /**
+     * Extract hostname from request parameters.
+     */
+    extractHostname(params) {
+        // For CONNECT requests (HTTPS), hostname is provided directly
+        if (typeof params.hostname === 'string') {
+            const trimmed = params.hostname.trim();
+            if (trimmed.length > 0)
+                return trimmed;
+        }
+        const urlLikeRaw = params.request?.url;
+        if (typeof urlLikeRaw === 'string') {
+            const urlLike = urlLikeRaw.trim();
+            if (urlLike.length > 0) {
+                const fromUrlLike = (() => {
+                    try {
+                        return new URL(urlLike).hostname;
+                    }
+                    catch {
+                        // continue
+                    }
+                    if (urlLike.startsWith('//')) {
+                        try {
+                            return new URL(`http:${urlLike}`).hostname;
+                        }
+                        catch {
+                            // continue
+                        }
+                    }
+                    if (urlLike.startsWith('/')) {
+                        return null;
+                    }
+                    try {
+                        return new URL(`http://${urlLike}`).hostname;
+                    }
+                    catch {
+                        return null;
+                    }
+                })();
+                if (fromUrlLike)
+                    return fromUrlLike;
+            }
+        }
+        // For origin-form URLs, fall back to Host header if available.
+        const hostHeader = (() => {
+            const headers = params.request?.headers;
+            if (!headers)
+                return null;
+            const host = headers['host'];
+            if (Array.isArray(host))
+                return typeof host[0] === 'string' ? host[0] : null;
+            return typeof host === 'string' ? host : null;
+        })();
+        if (hostHeader) {
+            const value = hostHeader.trim();
+            if (!value)
+                return null;
+            if (value.startsWith('[')) {
+                const end = value.indexOf(']');
+                if (end > 1)
+                    return value.slice(1, end);
+                return null;
+            }
+            const hostOnly = value.split(':')[0]?.trim();
+            return hostOnly && hostOnly.length > 0 ? hostOnly : null;
+        }
+        return null;
+    }
+}
+exports.ProxyServer = ProxyServer;
+ProxyServer.NO_CONFIG_WARN_INTERVAL_MS = 30000;

package/dist/cjs/client/adapters.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPlaywrightProxySettings = toPlaywrightProxySettings;
+exports.toPuppeteerArgs = toPuppeteerArgs;
+exports.toSeleniumArgs = toSeleniumArgs;
+exports.createNodeProxyAgents = createNodeProxyAgents;
+exports.toAxiosConfig = toAxiosConfig;
+exports.toGotOptions = toGotOptions;
+exports.createUndiciDispatcher = createUndiciDispatcher;
+exports.createUndiciFetch = createUndiciFetch;
+const http_proxy_agent_1 = require("http-proxy-agent");
+const https_proxy_agent_1 = require("https-proxy-agent");
+const undici_1 = require("undici");
+function toPlaywrightProxySettings(serverUrl) {
+    return { server: serverUrl };
+}
+function toPuppeteerArgs(serverUrl) {
+    // Puppeteer wants --proxy-server=<server> without embedding creds.
+    return [`--proxy-server=${serverUrl}`];
+}
+function toSeleniumArgs(serverUrl) {
+    // Selenium/Chromium wants --proxy-server=<server> without embedding creds.
+    return `--proxy-server=${serverUrl}`;
+}
+function createNodeProxyAgents(serverUrl) {
+    return {
+        http: new http_proxy_agent_1.HttpProxyAgent(serverUrl),
+        https: new https_proxy_agent_1.HttpsProxyAgent(serverUrl),
+    };
+}
+function toAxiosConfig(agents) {
+    return {
+        proxy: false,
+        httpAgent: agents.http,
+        httpsAgent: agents.https,
+    };
+}
+function toGotOptions(agents) {
+    return { agent: { http: agents.http, https: agents.https } };
+}
+function createUndiciDispatcher(serverUrl) {
+    return new undici_1.ProxyAgent(serverUrl);
+}
+function createUndiciFetch(dispatcher) {
+    return ((input, init) => {
+        const nextInit = init ? { ...init, dispatcher } : { dispatcher };
+        return (0, undici_1.fetch)(input, nextInit);
+    });
+}

package/dist/cjs/client/logger.js

@@ -0,0 +1,52 @@
+"use strict";
+// Logger utility for Aluvia Client
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+/**
+ * Simple logger that respects log levels.
+ *
+ * Log level hierarchy:
+ * - 'silent': only error() logs
+ * - 'info': info(), warn(), error() log
+ * - 'debug': all methods log
+ */
+class Logger {
+    constructor(level) {
+        this.level = level;
+    }
+    /**
+     * Log informational messages.
+     * Logs when level is 'info' or 'debug'.
+     */
+    info(...args) {
+        if (this.level === 'info' || this.level === 'debug') {
+            console.log('[aluvia][info]', ...args);
+        }
+    }
+    /**
+     * Log debug messages.
+     * Logs only when level is 'debug'.
+     */
+    debug(...args) {
+        if (this.level === 'debug') {
+            console.debug('[aluvia][debug]', ...args);
+        }
+    }
+    /**
+     * Log warning messages.
+     * Logs when level is not 'silent'.
+     */
+    warn(...args) {
+        if (this.level !== 'silent') {
+            console.warn('[aluvia][warn]', ...args);
+        }
+    }
+    /**
+     * Log error messages.
+     * Always logs regardless of level.
+     */
+    error(...args) {
+        console.error('[aluvia][error]', ...args);
+    }
+}
+exports.Logger = Logger;