@aluvia/sdk 1.0.0

package/dist/esm/client/AluviaClient.js

@@ -0,0 +1,321 @@
+// AluviaClient - Main public class for Aluvia Client
+import { ConfigManager } from './ConfigManager.js';
+import { ProxyServer } from './ProxyServer.js';
+import { ApiError, MissingApiKeyError } from '../errors.js';
+import { createNodeProxyAgents, createUndiciDispatcher, createUndiciFetch, toAxiosConfig, toGotOptions, toPlaywrightProxySettings, toPuppeteerArgs, toSeleniumArgs, } from './adapters.js';
+import { Logger } from './logger.js';
+import { AluviaApi } from '../api/AluviaApi.js';
+/**
+ * AluviaClient is the main entry point for the Aluvia Client.
+ *
+ * It manages the local proxy server and configuration polling.
+ */
+export class AluviaClient {
+    constructor(options) {
+        this.connection = null;
+        this.started = false;
+        this.startPromise = null;
+        const apiKey = String(options.apiKey ?? '').trim();
+        if (!apiKey) {
+            throw new MissingApiKeyError('Aluvia apiKey is required');
+        }
+        const localProxy = options.localProxy ?? true;
+        const strict = options.strict ?? true;
+        this.options = { ...options, apiKey, localProxy, strict };
+        const connectionId = Number(options.connectionId) ?? null;
+        const apiBaseUrl = options.apiBaseUrl ?? 'https://api.aluvia.io/v1';
+        const pollIntervalMs = options.pollIntervalMs ?? 5000;
+        const timeoutMs = options.timeoutMs;
+        const gatewayProtocol = options.gatewayProtocol ?? 'http';
+        const gatewayPort = options.gatewayPort ?? (gatewayProtocol === 'https' ? 8443 : 8080);
+        const logLevel = options.logLevel ?? 'info';
+        this.logger = new Logger(logLevel);
+        // Create ConfigManager
+        this.configManager = new ConfigManager({
+            apiKey,
+            apiBaseUrl,
+            pollIntervalMs,
+            gatewayProtocol,
+            gatewayPort,
+            logLevel,
+            connectionId,
+            strict,
+        });
+        // Create ProxyServer
+        this.proxyServer = new ProxyServer(this.configManager, { logLevel });
+        this.api = new AluviaApi({
+            apiKey,
+            apiBaseUrl,
+            timeoutMs,
+        });
+    }
+    /**
+     * Start the Aluvia Client connection:
+     * - Fetch initial account connection config from Aluvia.
+     * - Start polling for config updates.
+     * - If localProxy is enabled (default): start a local HTTP proxy on 127.0.0.1:<localPort or free port>.
+     * - If localProxy is disabled: do NOT start a local proxy; adapters use gateway proxy settings.
+     *
+     * Returns the active connection with host/port/url and a stop() method.
+     */
+    async start() {
+        // Return existing connection if already started
+        if (this.started && this.connection) {
+            return this.connection;
+        }
+        // If a start is already in-flight, await it.
+        if (this.startPromise) {
+            return this.startPromise;
+        }
+        this.startPromise = (async () => {
+            const localProxyEnabled = this.options.localProxy === true;
+            // Fetch initial configuration (may throw InvalidApiKeyError or ApiError)
+            await this.configManager.init();
+            // Gateway mode cannot function without proxy credentials/config, so fail fast.
+            if (!localProxyEnabled && !this.configManager.getConfig()) {
+                throw new ApiError('Failed to load account connection config; cannot start in gateway mode without proxy credentials', 500);
+            }
+            if (!localProxyEnabled) {
+                this.logger.debug('localProxy disabled — local proxy will not start');
+                let nodeAgents = null;
+                let undiciDispatcher = null;
+                let undiciFetchFn = null;
+                const cfgAtStart = this.configManager.getConfig();
+                const serverUrlAtStart = (() => {
+                    if (!cfgAtStart)
+                        return '';
+                    const { protocol, host, port } = cfgAtStart.rawProxy;
+                    return `${protocol}://${host}:${port}`;
+                })();
+                const getProxyUrlForHttpClients = () => {
+                    const cfg = this.configManager.getConfig();
+                    if (!cfg)
+                        return 'http://127.0.0.1';
+                    const { protocol, host, port, username, password } = cfg.rawProxy;
+                    return `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+                };
+                const getNodeAgents = () => {
+                    if (!nodeAgents) {
+                        nodeAgents = createNodeProxyAgents(getProxyUrlForHttpClients());
+                    }
+                    return nodeAgents;
+                };
+                const getUndiciDispatcher = () => {
+                    if (!undiciDispatcher) {
+                        undiciDispatcher = createUndiciDispatcher(getProxyUrlForHttpClients());
+                    }
+                    return undiciDispatcher;
+                };
+                const closeUndiciDispatcher = async () => {
+                    const d = undiciDispatcher;
+                    if (!d)
+                        return;
+                    try {
+                        if (typeof d.close === 'function') {
+                            await d.close();
+                        }
+                        else if (typeof d.destroy === 'function') {
+                            d.destroy();
+                        }
+                    }
+                    finally {
+                        undiciDispatcher = null;
+                    }
+                };
+                const stop = async () => {
+                    this.configManager.stopPolling();
+                    nodeAgents?.http?.destroy?.();
+                    nodeAgents?.https?.destroy?.();
+                    nodeAgents = null;
+                    await closeUndiciDispatcher();
+                    undiciFetchFn = null;
+                    this.connection = null;
+                    this.started = false;
+                };
+                // Build connection object
+                const connection = {
+                    host: cfgAtStart?.rawProxy.host ?? '127.0.0.1',
+                    port: cfgAtStart?.rawProxy.port ?? 0,
+                    url: serverUrlAtStart,
+                    getUrl: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return '';
+                        const { protocol, host, port, username, password } = cfg.rawProxy;
+                        return `${protocol}://${encodeURIComponent(username)}:${encodeURIComponent(password)}@${host}:${port}`;
+                    },
+                    asPlaywright: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return { server: '' };
+                        const { protocol, host, port, username, password } = cfg.rawProxy;
+                        return {
+                            ...toPlaywrightProxySettings(`${protocol}://${host}:${port}`),
+                            username,
+                            password,
+                        };
+                    },
+                    asPuppeteer: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return [];
+                        const { protocol, host, port } = cfg.rawProxy;
+                        return toPuppeteerArgs(`${protocol}://${host}:${port}`);
+                    },
+                    asSelenium: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return '';
+                        const { protocol, host, port } = cfg.rawProxy;
+                        return toSeleniumArgs(`${protocol}://${host}:${port}`);
+                    },
+                    asNodeAgents: () => getNodeAgents(),
+                    asAxiosConfig: () => toAxiosConfig(getNodeAgents()),
+                    asGotOptions: () => toGotOptions(getNodeAgents()),
+                    asUndiciDispatcher: () => getUndiciDispatcher(),
+                    asUndiciFetch: () => {
+                        if (!undiciFetchFn) {
+                            undiciFetchFn = createUndiciFetch(getUndiciDispatcher());
+                        }
+                        return undiciFetchFn;
+                    },
+                    stop,
+                    close: stop,
+                };
+                this.connection = connection;
+                this.started = true;
+                return connection;
+            }
+            // In client proxy mode, keep config fresh so routing decisions update without restarting.
+            this.configManager.startPolling();
+            // localProxy === true
+            const { host, port, url } = await this.proxyServer.start(this.options.localPort);
+            let nodeAgents = null;
+            let undiciDispatcher = null;
+            let undiciFetchFn = null;
+            const getNodeAgents = () => {
+                if (!nodeAgents) {
+                    nodeAgents = createNodeProxyAgents(url);
+                }
+                return nodeAgents;
+            };
+            const getUndiciDispatcher = () => {
+                if (!undiciDispatcher) {
+                    undiciDispatcher = createUndiciDispatcher(url);
+                }
+                return undiciDispatcher;
+            };
+            const closeUndiciDispatcher = async () => {
+                const d = undiciDispatcher;
+                if (!d)
+                    return;
+                try {
+                    if (typeof d.close === 'function') {
+                        await d.close();
+                    }
+                    else if (typeof d.destroy === 'function') {
+                        d.destroy();
+                    }
+                }
+                finally {
+                    undiciDispatcher = null;
+                }
+            };
+            const stop = async () => {
+                await this.proxyServer.stop();
+                this.configManager.stopPolling();
+                nodeAgents?.http?.destroy?.();
+                nodeAgents?.https?.destroy?.();
+                nodeAgents = null;
+                await closeUndiciDispatcher();
+                undiciFetchFn = null;
+                this.connection = null;
+                this.started = false;
+            };
+            // Build connection object
+            const connection = {
+                host,
+                port,
+                url,
+                getUrl: () => url,
+                asPlaywright: () => toPlaywrightProxySettings(url),
+                asPuppeteer: () => toPuppeteerArgs(url),
+                asSelenium: () => toSeleniumArgs(url),
+                asNodeAgents: () => getNodeAgents(),
+                asAxiosConfig: () => toAxiosConfig(getNodeAgents()),
+                asGotOptions: () => toGotOptions(getNodeAgents()),
+                asUndiciDispatcher: () => getUndiciDispatcher(),
+                asUndiciFetch: () => {
+                    if (!undiciFetchFn) {
+                        undiciFetchFn = createUndiciFetch(getUndiciDispatcher());
+                    }
+                    return undiciFetchFn;
+                },
+                stop,
+                close: stop,
+            };
+            this.connection = connection;
+            this.started = true;
+            return connection;
+        })();
+        try {
+            return await this.startPromise;
+        }
+        finally {
+            this.startPromise = null;
+        }
+    }
+    /**
+     * Global cleanup:
+     * - Stop the local proxy server (if running).
+     * - Stop config polling.
+     */
+    async stop() {
+        // If start is in-flight, wait for it to settle so we don't leave a running proxy behind.
+        if (this.startPromise) {
+            try {
+                await this.startPromise;
+            }
+            catch {
+                // ignore startup errors; if startup failed there is nothing to stop
+            }
+        }
+        if (!this.started) {
+            return;
+        }
+        // Only stop proxy if it was potentially started.
+        if (this.options.localProxy) {
+            await this.proxyServer.stop();
+        }
+        this.configManager.stopPolling();
+        this.connection = null;
+        this.started = false;
+    }
+    /**
+     * Update the filtering rules used by the proxy.
+     * @param rules
+     */
+    async updateRules(rules) {
+        await this.configManager.setConfig({ rules: rules });
+    }
+    /**
+     * Update the upstream session_id.
+     * @param sessionId
+     */
+    async updateSessionId(sessionId) {
+        await this.configManager.setConfig({ session_id: sessionId });
+    }
+    /**
+     * Update the upstream target_geo (geo targeting).
+     *
+     * Pass null to clear geo targeting.
+     */
+    async updateTargetGeo(targetGeo) {
+        if (targetGeo === null) {
+            await this.configManager.setConfig({ target_geo: null });
+            return;
+        }
+        const trimmed = targetGeo.trim();
+        await this.configManager.setConfig({ target_geo: trimmed.length > 0 ? trimmed : null });
+    }
+}

package/dist/esm/client/ConfigManager.js

@@ -0,0 +1,299 @@
+// ConfigManager - Control plane for connection configuration
+import { Logger } from './logger.js';
+import { InvalidApiKeyError, ApiError } from '../errors.js';
+import { requestCore } from '../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
+ */
+export class ConfigManager {
+    constructor(options) {
+        this.config = null;
+        this.timer = null;
+        this.pollInFlight = false;
+        this.options = options;
+        this.logger = new 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 requestCore({
+                    apiBaseUrl: this.options.apiBaseUrl,
+                    apiKey: this.options.apiKey,
+                    method: 'GET',
+                    path: `/account/connections/${this.accountConnectionId}`,
+                });
+            }
+            catch (err) {
+                if (err instanceof ApiError)
+                    throw err;
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new ApiError(`Failed to fetch account connection config: ${msg}`);
+            }
+            if (result.status === 401 || result.status === 403) {
+                throw new 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 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 requestCore({
+                apiBaseUrl: this.options.apiBaseUrl,
+                apiKey: this.options.apiKey,
+                method: 'POST',
+                path: '/account/connections',
+                body: {},
+            });
+            if (created.status === 401 || created.status === 403) {
+                throw new 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 ApiError(msg, created.status);
+            }
+            this.logger.warn(`${msg}; continuing without config (strict=false)`);
+            return;
+        }
+        catch (err) {
+            if (err instanceof InvalidApiKeyError)
+                throw err;
+            if (err instanceof 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 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 requestCore({
+                apiBaseUrl: this.options.apiBaseUrl,
+                apiKey: this.options.apiKey,
+                method: 'PATCH',
+                path: `/account/connections/${this.accountConnectionId}`,
+                body,
+            });
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                throw err;
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new ApiError(`Failed to update account connection config: ${msg}`);
+        }
+        if (result.status === 401 || result.status === 403) {
+            throw new 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 ApiError(`Failed to update account connection config: ${validationErrors[0]}`, result.status);
+            }
+        }
+        throw new 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 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 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]',
+            },
+        };
+    }
+}