@aluvia/sdk 1.0.0

package/dist/cjs/api/geos.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGeosApi = createGeosApi;
+const errors_js_1 = require("../errors.js");
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function asErrorEnvelope(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['success'] !== false)
+        return null;
+    const error = value['error'];
+    if (!isRecord(error))
+        return null;
+    const code = error['code'];
+    const message = error['message'];
+    if (typeof code !== 'string' || typeof message !== 'string')
+        return null;
+    return { success: false, error: { code, message, details: error['details'] } };
+}
+function formatErrorDetails(details) {
+    if (details == null)
+        return '';
+    try {
+        const json = JSON.stringify(details);
+        if (!json)
+            return '';
+        return json.length > 500 ? `${json.slice(0, 500)}…` : json;
+    }
+    catch {
+        return String(details);
+    }
+}
+function unwrapSuccessArray(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['success'] === true && Array.isArray(value.data)) {
+        return value.data;
+    }
+    if (Array.isArray(value.data)) {
+        return value.data;
+    }
+    return null;
+}
+function throwForNon2xx(result) {
+    const status = result.status;
+    if (status === 401 || status === 403) {
+        throw new errors_js_1.InvalidApiKeyError(`Authentication failed (HTTP ${status}). Check token validity and that you are using an account API token for account endpoints.`);
+    }
+    const maybeError = asErrorEnvelope(result.body);
+    if (maybeError) {
+        const details = formatErrorDetails(maybeError.error.details);
+        const detailsSuffix = details ? ` details=${details}` : '';
+        throw new errors_js_1.ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
+    }
+    throw new errors_js_1.ApiError(`API request failed (HTTP ${status})`, status);
+}
+function createGeosApi(ctx) {
+    return {
+        list: async () => {
+            const result = await ctx.request({
+                method: 'GET',
+                path: '/geos',
+            });
+            if (result.status < 200 || result.status >= 300) {
+                throwForNon2xx(result);
+            }
+            const data = unwrapSuccessArray(result.body);
+            if (data == null) {
+                throw new errors_js_1.ApiError('API response missing expected success envelope data', result.status);
+            }
+            return data;
+        },
+    };
+}

package/dist/cjs/api/request.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestCore = requestCore;
+const errors_js_1 = require("../errors.js");
+const DEFAULT_TIMEOUT_MS = 30000;
+function joinUrl(baseUrl, path) {
+    const base = baseUrl.replace(/\/+$/, '');
+    const p = path.startsWith('/') ? path : `/${path}`;
+    return `${base}${p}`;
+}
+function buildQueryString(query) {
+    if (!query)
+        return '';
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value == null)
+            continue;
+        if (Array.isArray(value)) {
+            for (const v of value)
+                params.append(key, String(v));
+            continue;
+        }
+        params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+function isJsonResponse(contentType) {
+    if (!contentType)
+        return false;
+    return contentType.toLowerCase().includes('application/json');
+}
+async function requestCore(options) {
+    const url = `${joinUrl(options.apiBaseUrl, options.path)}${buildQueryString(options.query)}`;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (typeof fetchImpl !== 'function') {
+        throw new Error('globalThis.fetch is not available; Node 18+ is required');
+    }
+    const headers = {
+        Accept: 'application/json',
+        Authorization: `Bearer ${options.apiKey}`,
+        ...(options.headers ?? {}),
+    };
+    if (options.ifNoneMatch)
+        headers['If-None-Match'] = options.ifNoneMatch;
+    const hasJsonBody = options.body !== undefined && options.body !== null;
+    if (hasJsonBody)
+        headers['Content-Type'] = 'application/json';
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        let response;
+        try {
+            response = await fetchImpl(url, {
+                method: options.method,
+                headers,
+                body: hasJsonBody ? JSON.stringify(options.body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                throw new errors_js_1.ApiError(`Request timed out after ${timeoutMs}ms`, 408);
+            }
+            throw err;
+        }
+        const etag = response.headers.get('etag');
+        if (response.status === 204 || response.status === 304) {
+            return { status: response.status, etag, body: null };
+        }
+        const contentType = response.headers.get('content-type');
+        if (!isJsonResponse(contentType)) {
+            return { status: response.status, etag, body: null };
+        }
+        const text = await response.text();
+        if (!text)
+            return { status: response.status, etag, body: null };
+        return { status: response.status, etag, body: JSON.parse(text) };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/dist/cjs/api/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/client/AluviaClient.js

@@ -0,0 +1,325 @@
+"use strict";
+// AluviaClient - Main public class for Aluvia Client
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AluviaClient = void 0;
+const ConfigManager_js_1 = require("./ConfigManager.js");
+const ProxyServer_js_1 = require("./ProxyServer.js");
+const errors_js_1 = require("../errors.js");
+const adapters_js_1 = require("./adapters.js");
+const logger_js_1 = require("./logger.js");
+const AluviaApi_js_1 = require("../api/AluviaApi.js");
+/**
+ * AluviaClient is the main entry point for the Aluvia Client.
+ *
+ * It manages the local proxy server and configuration polling.
+ */
+class AluviaClient {
+    constructor(options) {
+        this.connection = null;
+        this.started = false;
+        this.startPromise = null;
+        const apiKey = String(options.apiKey ?? '').trim();
+        if (!apiKey) {
+            throw new errors_js_1.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_js_1.Logger(logLevel);
+        // Create ConfigManager
+        this.configManager = new ConfigManager_js_1.ConfigManager({
+            apiKey,
+            apiBaseUrl,
+            pollIntervalMs,
+            gatewayProtocol,
+            gatewayPort,
+            logLevel,
+            connectionId,
+            strict,
+        });
+        // Create ProxyServer
+        this.proxyServer = new ProxyServer_js_1.ProxyServer(this.configManager, { logLevel });
+        this.api = new AluviaApi_js_1.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 errors_js_1.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 = (0, adapters_js_1.createNodeProxyAgents)(getProxyUrlForHttpClients());
+                    }
+                    return nodeAgents;
+                };
+                const getUndiciDispatcher = () => {
+                    if (!undiciDispatcher) {
+                        undiciDispatcher = (0, adapters_js_1.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 {
+                            ...(0, adapters_js_1.toPlaywrightProxySettings)(`${protocol}://${host}:${port}`),
+                            username,
+                            password,
+                        };
+                    },
+                    asPuppeteer: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return [];
+                        const { protocol, host, port } = cfg.rawProxy;
+                        return (0, adapters_js_1.toPuppeteerArgs)(`${protocol}://${host}:${port}`);
+                    },
+                    asSelenium: () => {
+                        const cfg = this.configManager.getConfig();
+                        if (!cfg)
+                            return '';
+                        const { protocol, host, port } = cfg.rawProxy;
+                        return (0, adapters_js_1.toSeleniumArgs)(`${protocol}://${host}:${port}`);
+                    },
+                    asNodeAgents: () => getNodeAgents(),
+                    asAxiosConfig: () => (0, adapters_js_1.toAxiosConfig)(getNodeAgents()),
+                    asGotOptions: () => (0, adapters_js_1.toGotOptions)(getNodeAgents()),
+                    asUndiciDispatcher: () => getUndiciDispatcher(),
+                    asUndiciFetch: () => {
+                        if (!undiciFetchFn) {
+                            undiciFetchFn = (0, adapters_js_1.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 = (0, adapters_js_1.createNodeProxyAgents)(url);
+                }
+                return nodeAgents;
+            };
+            const getUndiciDispatcher = () => {
+                if (!undiciDispatcher) {
+                    undiciDispatcher = (0, adapters_js_1.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: () => (0, adapters_js_1.toPlaywrightProxySettings)(url),
+                asPuppeteer: () => (0, adapters_js_1.toPuppeteerArgs)(url),
+                asSelenium: () => (0, adapters_js_1.toSeleniumArgs)(url),
+                asNodeAgents: () => getNodeAgents(),
+                asAxiosConfig: () => (0, adapters_js_1.toAxiosConfig)(getNodeAgents()),
+                asGotOptions: () => (0, adapters_js_1.toGotOptions)(getNodeAgents()),
+                asUndiciDispatcher: () => getUndiciDispatcher(),
+                asUndiciFetch: () => {
+                    if (!undiciFetchFn) {
+                        undiciFetchFn = (0, adapters_js_1.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 });
+    }
+}
+exports.AluviaClient = AluviaClient;