@aluvia/sdk 1.0.0

package/dist/esm/client/ProxyServer.js

@@ -0,0 +1,178 @@
+// ProxyServer - Local HTTP proxy using proxy-chain
+import { Server as ProxyChainServer } from 'proxy-chain';
+import { Logger } from './logger.js';
+import { ProxyStartError } from '../errors.js';
+import { shouldProxy } from './rules.js';
+/**
+ * ProxyServer manages the local HTTP(S) proxy that routes traffic
+ * through Aluvia or directly based on rules.
+ */
+export 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(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 ProxyChainServer({
+                // 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 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 = 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;
+    }
+}
+ProxyServer.NO_CONFIG_WARN_INTERVAL_MS = 30000;

package/dist/esm/client/adapters.js

@@ -0,0 +1,39 @@
+import { HttpProxyAgent } from 'http-proxy-agent';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { ProxyAgent as UndiciProxyAgent, fetch as undiciFetch } from 'undici';
+export function toPlaywrightProxySettings(serverUrl) {
+    return { server: serverUrl };
+}
+export function toPuppeteerArgs(serverUrl) {
+    // Puppeteer wants --proxy-server=<server> without embedding creds.
+    return [`--proxy-server=${serverUrl}`];
+}
+export function toSeleniumArgs(serverUrl) {
+    // Selenium/Chromium wants --proxy-server=<server> without embedding creds.
+    return `--proxy-server=${serverUrl}`;
+}
+export function createNodeProxyAgents(serverUrl) {
+    return {
+        http: new HttpProxyAgent(serverUrl),
+        https: new HttpsProxyAgent(serverUrl),
+    };
+}
+export function toAxiosConfig(agents) {
+    return {
+        proxy: false,
+        httpAgent: agents.http,
+        httpsAgent: agents.https,
+    };
+}
+export function toGotOptions(agents) {
+    return { agent: { http: agents.http, https: agents.https } };
+}
+export function createUndiciDispatcher(serverUrl) {
+    return new UndiciProxyAgent(serverUrl);
+}
+export function createUndiciFetch(dispatcher) {
+    return ((input, init) => {
+        const nextInit = init ? { ...init, dispatcher } : { dispatcher };
+        return undiciFetch(input, nextInit);
+    });
+}

package/dist/esm/client/logger.js

@@ -0,0 +1,48 @@
+// Logger utility for Aluvia Client
+/**
+ * Simple logger that respects log levels.
+ *
+ * Log level hierarchy:
+ * - 'silent': only error() logs
+ * - 'info': info(), warn(), error() log
+ * - 'debug': all methods log
+ */
+export 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);
+    }
+}

package/dist/esm/client/rules.js

@@ -0,0 +1,124 @@
+// Rule engine for hostname matching and proxy decision
+/**
+ * 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 function matchPattern(hostname, pattern) {
+    // Normalize inputs to lowercase
+    const normalizedHostname = hostname.trim().toLowerCase();
+    const normalizedPattern = pattern.trim().toLowerCase();
+    if (!normalizedHostname)
+        return false;
+    if (!normalizedPattern)
+        return false;
+    // Universal wildcard matches everything
+    if (normalizedPattern === '*') {
+        return true;
+    }
+    // Exact match
+    if (normalizedHostname === normalizedPattern) {
+        return true;
+    }
+    // Prefix wildcard: *.example.com matches subdomains
+    if (normalizedPattern.startsWith('*.')) {
+        const suffix = normalizedPattern.slice(1); // '.example.com'
+        // Must end with the suffix and have something before it
+        if (normalizedHostname.endsWith(suffix)) {
+            const prefix = normalizedHostname.slice(0, -suffix.length);
+            // Prefix must not be empty. This matches any subdomain depth (for example, foo.example.com and foo.bar.example.com).
+            return prefix.length > 0;
+        }
+        return false;
+    }
+    // Suffix wildcard: google.* matches google.com, google.co.uk, etc.
+    if (normalizedPattern.endsWith('.*')) {
+        const prefix = normalizedPattern.slice(0, -2); // 'google'
+        // Must start with prefix followed by a dot
+        if (normalizedHostname.startsWith(prefix + '.')) {
+            return true;
+        }
+        return false;
+    }
+    return false;
+}
+/**
+ * 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 function shouldProxy(hostname, rules) {
+    const normalizedHostname = hostname.trim();
+    if (!normalizedHostname)
+        return false;
+    // Empty rules means no proxy
+    if (!rules || rules.length === 0) {
+        return false;
+    }
+    const normalizedRules = rules
+        .filter((r) => typeof r === 'string')
+        .map((r) => r.trim())
+        .filter((r) => r.length > 0);
+    // Filter out AUTO placeholder
+    const effectiveRules = normalizedRules.filter((r) => r.toUpperCase() !== 'AUTO');
+    // If no effective rules after filtering, no proxy
+    if (effectiveRules.length === 0) {
+        return false;
+    }
+    // Separate positive and negative rules
+    const negativeRules = [];
+    const positiveRules = [];
+    for (const rule of effectiveRules) {
+        if (rule.startsWith('-')) {
+            const neg = rule.slice(1).trim(); // Remove the '-' prefix
+            if (neg.length > 0)
+                negativeRules.push(neg);
+        }
+        else {
+            positiveRules.push(rule);
+        }
+    }
+    // Check if hostname matches any negative rule
+    for (const negRule of negativeRules) {
+        if (matchPattern(normalizedHostname, negRule)) {
+            // Excluded by negative rule
+            return false;
+        }
+    }
+    // Check if we have a catch-all '*'
+    const hasCatchAll = positiveRules.includes('*');
+    if (hasCatchAll) {
+        // With catch-all, proxy everything not excluded by negative rules
+        return true;
+    }
+    // Without catch-all, check if hostname matches any positive rule
+    for (const posRule of positiveRules) {
+        if (matchPattern(normalizedHostname, posRule)) {
+            return true;
+        }
+    }
+    // No match found
+    return false;
+}

package/dist/esm/client/types.js

@@ -0,0 +1,2 @@
+// Public types for Aluvia Client Node
+export {};

package/dist/esm/errors.js

@@ -0,0 +1,42 @@
+// Error classes for Aluvia Client
+/**
+ * Thrown when the apiKey is not provided to AluviaClient.
+ */
+export class MissingApiKeyError extends Error {
+    constructor(message = 'Aluvia connection apiKey is required') {
+        super(message);
+        this.name = 'MissingApiKeyError';
+        Object.setPrototypeOf(this, MissingApiKeyError.prototype);
+    }
+}
+/**
+ * Thrown when the API returns 401 or 403, indicating the apiKey is invalid.
+ */
+export class InvalidApiKeyError extends Error {
+    constructor(message = 'Invalid or expired Aluvia connection apiKey') {
+        super(message);
+        this.name = 'InvalidApiKeyError';
+        Object.setPrototypeOf(this, InvalidApiKeyError.prototype);
+    }
+}
+/**
+ * Thrown for general API errors (non-2xx responses other than auth errors).
+ */
+export class ApiError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.name = 'ApiError';
+        this.statusCode = statusCode;
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+/**
+ * Thrown when the local proxy server fails to start.
+ */
+export class ProxyStartError extends Error {
+    constructor(message = 'Failed to start local proxy server') {
+        super(message);
+        this.name = 'ProxyStartError';
+        Object.setPrototypeOf(this, ProxyStartError.prototype);
+    }
+}

package/dist/esm/index.js

@@ -0,0 +1,7 @@
+// Aluvia Client Node
+// Main entry point
+// Public class
+export { AluviaClient } from './client/AluviaClient.js';
+export { AluviaApi } from './api/AluviaApi.js';
+// Public error classes
+export { MissingApiKeyError, InvalidApiKeyError, ApiError, ProxyStartError, } from './errors.js';

package/dist/types/api/AluviaApi.d.ts

@@ -0,0 +1,29 @@
+import { createAccountApi } from './account.js';
+import { createGeosApi } from './geos.js';
+export type AluviaApiOptions = {
+    apiKey: string;
+    apiBaseUrl?: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+export type AluviaApiRequestArgs = {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+};
+export declare class AluviaApi {
+    private readonly apiKey;
+    private readonly apiBaseUrl;
+    private readonly timeoutMs?;
+    private readonly fetchImpl?;
+    readonly account: ReturnType<typeof createAccountApi>;
+    readonly geos: ReturnType<typeof createGeosApi>;
+    constructor(options: AluviaApiOptions);
+    request(args: AluviaApiRequestArgs): Promise<{
+        status: number;
+        etag: string | null;
+        body: unknown | null;
+    }>;
+}

package/dist/types/api/account.d.ts

@@ -0,0 +1,41 @@
+import type { Account, AccountConnection, AccountConnectionDeleteResult, AccountPayment, AccountUsage } from './types.js';
+export type ApiRequestArgs = {
+    method: 'GET' | 'POST' | 'PATCH' | 'DELETE';
+    path: string;
+    query?: Record<string, string | number | boolean | null | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    etag?: string | null;
+};
+export type ApiRequestResult = {
+    status: number;
+    etag: string | null;
+    body: unknown | null;
+};
+export type ApiContext = {
+    request: (args: ApiRequestArgs) => Promise<ApiRequestResult>;
+};
+export declare function createAccountApi(ctx: ApiContext): {
+    get: () => Promise<Account>;
+    usage: {
+        get: (params?: {
+            start?: string;
+            end?: string;
+        }) => Promise<AccountUsage>;
+    };
+    payments: {
+        list: (params?: {
+            start?: string;
+            end?: string;
+        }) => Promise<Array<AccountPayment>>;
+    };
+    connections: {
+        list: () => Promise<Array<AccountConnection>>;
+        create: (body: Record<string, unknown>) => Promise<AccountConnection>;
+        get: (connectionId: string | number, options?: {
+            etag?: string | null;
+        }) => Promise<AccountConnection | null>;
+        patch: (connectionId: string | number, body: Record<string, unknown>) => Promise<AccountConnection>;
+        delete: (connectionId: string | number) => Promise<AccountConnectionDeleteResult>;
+    };
+};

package/dist/types/api/geos.d.ts

@@ -0,0 +1,5 @@
+import type { Geo } from './types.js';
+import type { ApiContext } from './account.js';
+export declare function createGeosApi(ctx: ApiContext): {
+    list: () => Promise<Array<Geo>>;
+};

package/dist/types/api/request.d.ts

@@ -0,0 +1,20 @@
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export type RequestQuery = Record<string, string | number | boolean | null | undefined | Array<string | number | boolean>>;
+export type RequestCoreOptions = {
+    apiBaseUrl: string;
+    apiKey: string;
+    method: HttpMethod;
+    path: string;
+    query?: RequestQuery;
+    body?: unknown;
+    headers?: Record<string, string>;
+    ifNoneMatch?: string | null;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+};
+export type RequestCoreResult = {
+    status: number;
+    etag: string | null;
+    body: unknown | null;
+};
+export declare function requestCore(options: RequestCoreOptions): Promise<RequestCoreResult>;

package/dist/types/api/types.d.ts

@@ -0,0 +1,30 @@
+export type SuccessEnvelope<T> = {
+    success: true;
+    data: T;
+};
+export type ErrorEnvelope = {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+};
+export type Envelope<T> = SuccessEnvelope<T> | ErrorEnvelope;
+export type Account = Record<string, unknown>;
+export type AccountUsage = Record<string, unknown>;
+export type AccountPayment = Record<string, unknown>;
+export type AccountConnection = {
+    id?: string | number;
+    connection_id?: string;
+    proxy_username?: string;
+    proxy_password?: string;
+    rules?: string[];
+    session_id?: string | null;
+    target_geo?: string | null;
+} & Record<string, unknown>;
+export type AccountConnectionDeleteResult = {
+    connection_id: string;
+    deleted: boolean;
+};
+export type Geo = Record<string, unknown>;

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

@@ -0,0 +1,50 @@
+import type { AluviaClientConnection, AluviaClientOptions } from './types.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 declare class AluviaClient {
+    private readonly options;
+    private readonly configManager;
+    private readonly proxyServer;
+    private connection;
+    private started;
+    private startPromise;
+    private readonly logger;
+    readonly api: AluviaApi;
+    constructor(options: AluviaClientOptions);
+    /**
+     * 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.
+     */
+    start(): Promise<AluviaClientConnection>;
+    /**
+     * Global cleanup:
+     * - Stop the local proxy server (if running).
+     * - Stop config polling.
+     */
+    stop(): Promise<void>;
+    /**
+     * Update the filtering rules used by the proxy.
+     * @param rules
+     */
+    updateRules(rules: Array<string>): Promise<void>;
+    /**
+     * Update the upstream session_id.
+     * @param sessionId
+     */
+    updateSessionId(sessionId: string): Promise<void>;
+    /**
+     * Update the upstream target_geo (geo targeting).
+     *
+     * Pass null to clear geo targeting.
+     */
+    updateTargetGeo(targetGeo: string | null): Promise<void>;
+}