@aluvia/sdk 1.0.0

package/dist/cjs/client/rules.js

@@ -0,0 +1,128 @@
+"use strict";
+// Rule engine for hostname matching and proxy decision
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchPattern = matchPattern;
+exports.shouldProxy = shouldProxy;
+/**
+ * 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
+ */
+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
+ */
+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/cjs/client/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// Public types for Aluvia Client Node
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/errors.js

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

package/dist/cjs/index.js

@@ -0,0 +1,16 @@
+"use strict";
+// Aluvia Client Node
+// Main entry point
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProxyStartError = exports.ApiError = exports.InvalidApiKeyError = exports.MissingApiKeyError = exports.AluviaApi = exports.AluviaClient = void 0;
+// Public class
+var AluviaClient_js_1 = require("./client/AluviaClient.js");
+Object.defineProperty(exports, "AluviaClient", { enumerable: true, get: function () { return AluviaClient_js_1.AluviaClient; } });
+var AluviaApi_js_1 = require("./api/AluviaApi.js");
+Object.defineProperty(exports, "AluviaApi", { enumerable: true, get: function () { return AluviaApi_js_1.AluviaApi; } });
+// Public error classes
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "MissingApiKeyError", { enumerable: true, get: function () { return errors_js_1.MissingApiKeyError; } });
+Object.defineProperty(exports, "InvalidApiKeyError", { enumerable: true, get: function () { return errors_js_1.InvalidApiKeyError; } });
+Object.defineProperty(exports, "ApiError", { enumerable: true, get: function () { return errors_js_1.ApiError; } });
+Object.defineProperty(exports, "ProxyStartError", { enumerable: true, get: function () { return errors_js_1.ProxyStartError; } });

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/api/AluviaApi.js

@@ -0,0 +1,47 @@
+import { requestCore } from './request.js';
+import { createAccountApi } from './account.js';
+import { createGeosApi } from './geos.js';
+import { MissingApiKeyError } from '../errors.js';
+export class AluviaApi {
+    constructor(options) {
+        const apiKey = String(options.apiKey ?? '').trim();
+        if (!apiKey) {
+            throw new MissingApiKeyError('Aluvia apiKey is required');
+        }
+        this.apiKey = apiKey;
+        this.apiBaseUrl = options.apiBaseUrl ?? 'https://api.aluvia.io/v1';
+        this.timeoutMs = options.timeoutMs;
+        this.fetchImpl = options.fetch;
+        const ctx = {
+            request: async (args) => {
+                return await requestCore({
+                    apiBaseUrl: this.apiBaseUrl,
+                    apiKey: this.apiKey,
+                    method: args.method,
+                    path: args.path,
+                    query: args.query,
+                    body: args.body,
+                    headers: args.headers,
+                    ifNoneMatch: args.etag,
+                    timeoutMs: this.timeoutMs,
+                    fetch: this.fetchImpl,
+                });
+            },
+        };
+        this.account = createAccountApi(ctx);
+        this.geos = createGeosApi(ctx);
+    }
+    async request(args) {
+        return await requestCore({
+            apiBaseUrl: this.apiBaseUrl,
+            apiKey: this.apiKey,
+            method: args.method,
+            path: args.path,
+            query: args.query,
+            body: args.body,
+            headers: args.headers,
+            timeoutMs: this.timeoutMs,
+            fetch: this.fetchImpl,
+        });
+    }
+}

package/dist/esm/api/account.js

@@ -0,0 +1,152 @@
+import { ApiError, InvalidApiKeyError } from '../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 unwrapSuccess(value) {
+    if (!isRecord(value))
+        return null;
+    if (value['success'] === true && 'data' in value) {
+        return value.data;
+    }
+    if ('data' in value) {
+        return value.data;
+    }
+    return null;
+}
+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 throwForNon2xx(result) {
+    const status = result.status;
+    if (status === 401 || status === 403) {
+        throw new 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 ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
+    }
+    throw new ApiError(`API request failed (HTTP ${status})`, status);
+}
+async function requestAndUnwrap(ctx, args) {
+    const result = await ctx.request(args);
+    if (result.status < 200 || result.status >= 300) {
+        throwForNon2xx(result);
+    }
+    const data = unwrapSuccess(result.body);
+    if (data == null) {
+        throw new ApiError('API response missing expected success envelope data', result.status);
+    }
+    return { data, etag: result.etag };
+}
+export function createAccountApi(ctx) {
+    return {
+        get: async () => {
+            const { data } = await requestAndUnwrap(ctx, {
+                method: 'GET',
+                path: '/account',
+            });
+            return data;
+        },
+        usage: {
+            get: async (params = {}) => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'GET',
+                    path: '/account/usage',
+                    query: {
+                        start: params.start,
+                        end: params.end,
+                    },
+                });
+                return data;
+            },
+        },
+        payments: {
+            list: async (params = {}) => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'GET',
+                    path: '/account/payments',
+                    query: {
+                        start: params.start,
+                        end: params.end,
+                    },
+                });
+                return data;
+            },
+        },
+        connections: {
+            list: async () => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'GET',
+                    path: '/account/connections',
+                });
+                return data;
+            },
+            create: async (body) => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'POST',
+                    path: '/account/connections',
+                    body,
+                });
+                return data;
+            },
+            get: async (connectionId, options = {}) => {
+                const result = await ctx.request({
+                    method: 'GET',
+                    path: `/account/connections/${String(connectionId)}`,
+                    etag: options.etag ?? null,
+                });
+                if (result.status === 304)
+                    return null;
+                if (result.status < 200 || result.status >= 300) {
+                    throwForNon2xx(result);
+                }
+                const data = unwrapSuccess(result.body);
+                if (data == null) {
+                    throw new ApiError('API response missing expected success envelope data', result.status);
+                }
+                return data;
+            },
+            patch: async (connectionId, body) => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'PATCH',
+                    path: `/account/connections/${String(connectionId)}`,
+                    body,
+                });
+                return data;
+            },
+            delete: async (connectionId) => {
+                const { data } = await requestAndUnwrap(ctx, {
+                    method: 'DELETE',
+                    path: `/account/connections/${String(connectionId)}`,
+                });
+                return data;
+            },
+        },
+    };
+}

package/dist/esm/api/geos.js

@@ -0,0 +1,73 @@
+import { ApiError, InvalidApiKeyError } from '../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 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 ApiError(`API request failed (HTTP ${status}) code=${maybeError.error.code} message=${maybeError.error.message}${detailsSuffix}`, status);
+    }
+    throw new ApiError(`API request failed (HTTP ${status})`, status);
+}
+export 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 ApiError('API response missing expected success envelope data', result.status);
+            }
+            return data;
+        },
+    };
+}

package/dist/esm/api/request.js

@@ -0,0 +1,81 @@
+import { ApiError } from '../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');
+}
+export 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 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/esm/api/types.js

@@ -0,0 +1 @@
+export {};