reqon-dsl 0.2.0

package/dist/auth/circuit-breaker.js

@@ -0,0 +1,267 @@
+/**
+ * Circuit Breaker implementation for HTTP requests.
+ *
+ * Prevents repeated failures from cascading by automatically detecting
+ * failure patterns and "opening" the circuit to fail fast.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit tripped, requests fail immediately
+ * - HALF_OPEN: Testing if service recovered, limited requests allowed
+ */
+const DEFAULT_CONFIG = {
+    failureThreshold: 5,
+    resetTimeout: 30000,
+    successThreshold: 2,
+    failureWindow: 60000,
+    failureStatusCodes: [500, 501, 502, 503, 504],
+    countNetworkErrors: true,
+};
+/**
+ * Error thrown when circuit breaker is open
+ */
+export class CircuitBreakerError extends Error {
+    source;
+    endpoint;
+    nextAttemptIn;
+    constructor(source, endpoint, nextAttemptIn) {
+        super(`Circuit breaker open for ${source}${endpoint ? `:${endpoint}` : ''}. ` +
+            `Next attempt in ${Math.ceil(nextAttemptIn / 1000)}s`);
+        this.source = source;
+        this.endpoint = endpoint;
+        this.nextAttemptIn = nextAttemptIn;
+        this.name = 'CircuitBreakerError';
+    }
+}
+/**
+ * Circuit breaker for managing failure detection and recovery
+ */
+export class CircuitBreaker {
+    circuits = new Map();
+    callbacks = {};
+    defaultConfig;
+    constructor(defaultConfig) {
+        this.defaultConfig = { ...DEFAULT_CONFIG, ...defaultConfig };
+    }
+    /**
+     * Configure circuit breaker for a specific source
+     */
+    configure(source, config) {
+        const key = this.getKey(source);
+        const existing = this.circuits.get(key);
+        if (existing) {
+            existing.config = { ...this.defaultConfig, ...config };
+        }
+        else {
+            this.circuits.set(key, this.createEntry({ ...this.defaultConfig, ...config }));
+        }
+    }
+    /**
+     * Set event callbacks
+     */
+    setCallbacks(callbacks) {
+        this.callbacks = callbacks;
+    }
+    /**
+     * Check if a request can proceed (throws if circuit is open)
+     */
+    canProceed(source, endpoint) {
+        const entry = this.getOrCreateEntry(source, endpoint);
+        const now = Date.now();
+        if (entry.state === 'closed') {
+            return true;
+        }
+        if (entry.state === 'open') {
+            const timeSinceOpen = now - (entry.openedAt ?? now);
+            if (timeSinceOpen >= entry.config.resetTimeout) {
+                // Transition to half-open
+                this.transitionTo(entry, 'half_open', source, endpoint);
+                return true;
+            }
+            return false;
+        }
+        // Half-open: allow the request through for testing
+        return true;
+    }
+    /**
+     * Ensure request can proceed, throwing CircuitBreakerError if not
+     */
+    ensureCanProceed(source, endpoint) {
+        if (!this.canProceed(source, endpoint)) {
+            const entry = this.getOrCreateEntry(source, endpoint);
+            const now = Date.now();
+            const nextAttemptIn = entry.config.resetTimeout - (now - (entry.openedAt ?? now));
+            this.callbacks.onRejected?.({
+                source,
+                endpoint,
+                nextAttemptIn,
+            });
+            throw new CircuitBreakerError(source, endpoint, nextAttemptIn);
+        }
+    }
+    /**
+     * Record a successful request
+     */
+    recordSuccess(source, endpoint) {
+        const entry = this.getOrCreateEntry(source, endpoint);
+        if (entry.state === 'half_open') {
+            entry.successes++;
+            if (entry.successes >= entry.config.successThreshold) {
+                // Recovery successful, close the circuit
+                this.transitionTo(entry, 'closed', source, endpoint);
+            }
+        }
+        else if (entry.state === 'closed') {
+            // Clear old failures from window
+            this.pruneOldFailures(entry);
+        }
+    }
+    /**
+     * Record a failed request
+     */
+    recordFailure(source, endpoint, statusCode, isNetworkError = false) {
+        const entry = this.getOrCreateEntry(source, endpoint);
+        const config = entry.config;
+        // Check if this failure type should be counted
+        const isFailureStatus = statusCode !== undefined && config.failureStatusCodes.includes(statusCode);
+        const shouldCount = isFailureStatus || (isNetworkError && config.countNetworkErrors);
+        if (!shouldCount) {
+            return;
+        }
+        const now = Date.now();
+        if (entry.state === 'half_open') {
+            // Any failure in half-open immediately re-opens circuit
+            this.transitionTo(entry, 'open', source, endpoint, 'Failure during recovery attempt');
+            return;
+        }
+        if (entry.state === 'closed') {
+            // Prune old failures and add new one
+            this.pruneOldFailures(entry);
+            entry.failureTimestamps.push(now);
+            entry.failures = entry.failureTimestamps.length;
+            entry.lastFailureTime = now;
+            // Check if we should open the circuit
+            if (entry.failures >= config.failureThreshold) {
+                this.transitionTo(entry, 'open', source, endpoint, `${entry.failures} failures in ${config.failureWindow}ms window`);
+            }
+        }
+    }
+    /**
+     * Get current status for a source/endpoint
+     */
+    getStatus(source, endpoint) {
+        const entry = this.getOrCreateEntry(source, endpoint);
+        const now = Date.now();
+        let nextAttemptTime;
+        if (entry.state === 'open' && entry.openedAt) {
+            const nextAttemptMs = entry.openedAt + entry.config.resetTimeout;
+            nextAttemptTime = new Date(nextAttemptMs);
+        }
+        return {
+            state: entry.state,
+            failures: entry.failures,
+            successes: entry.successes,
+            lastFailureTime: entry.lastFailureTime ? new Date(entry.lastFailureTime) : undefined,
+            nextAttemptTime,
+            isOpen: entry.state === 'open',
+        };
+    }
+    /**
+     * Force reset a circuit to closed state
+     */
+    reset(source, endpoint) {
+        const key = this.getKey(source, endpoint);
+        const entry = this.circuits.get(key);
+        if (entry) {
+            const previousState = entry.state;
+            entry.state = 'closed';
+            entry.failures = 0;
+            entry.successes = 0;
+            entry.failureTimestamps = [];
+            entry.lastFailureTime = undefined;
+            entry.openedAt = undefined;
+            if (previousState !== 'closed') {
+                this.callbacks.onClose?.({
+                    source,
+                    endpoint,
+                    state: 'closed',
+                    previousState,
+                    failures: 0,
+                    reason: 'Manual reset',
+                });
+            }
+        }
+    }
+    /**
+     * Get all circuit statuses
+     */
+    getAllStatuses() {
+        const result = new Map();
+        for (const [key, entry] of this.circuits) {
+            const [source, endpoint] = key.split(':');
+            result.set(key, this.getStatus(source, endpoint === '' ? undefined : endpoint));
+        }
+        return result;
+    }
+    getKey(source, endpoint) {
+        return endpoint ? `${source}:${endpoint}` : source;
+    }
+    createEntry(config) {
+        return {
+            state: 'closed',
+            failures: 0,
+            successes: 0,
+            failureTimestamps: [],
+            config,
+        };
+    }
+    getOrCreateEntry(source, endpoint) {
+        const key = this.getKey(source, endpoint);
+        let entry = this.circuits.get(key);
+        if (!entry) {
+            // Check for source-level config
+            const sourceEntry = this.circuits.get(source);
+            const config = sourceEntry?.config ?? this.defaultConfig;
+            entry = this.createEntry(config);
+            this.circuits.set(key, entry);
+        }
+        return entry;
+    }
+    pruneOldFailures(entry) {
+        const now = Date.now();
+        const windowStart = now - entry.config.failureWindow;
+        entry.failureTimestamps = entry.failureTimestamps.filter((ts) => ts >= windowStart);
+        entry.failures = entry.failureTimestamps.length;
+    }
+    transitionTo(entry, newState, source, endpoint, reason) {
+        const previousState = entry.state;
+        entry.state = newState;
+        const event = {
+            source,
+            endpoint,
+            state: newState,
+            previousState,
+            failures: entry.failures,
+            reason,
+        };
+        switch (newState) {
+            case 'open':
+                entry.openedAt = Date.now();
+                entry.successes = 0;
+                this.callbacks.onOpen?.(event);
+                break;
+            case 'half_open':
+                entry.successes = 0;
+                this.callbacks.onHalfOpen?.(event);
+                break;
+            case 'closed':
+                entry.failures = 0;
+                entry.successes = 0;
+                entry.failureTimestamps = [];
+                entry.lastFailureTime = undefined;
+                entry.openedAt = undefined;
+                this.callbacks.onClose?.(event);
+                break;
+        }
+    }
+}

package/dist/auth/credentials.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Credentials resolver with dotenv support
+ *
+ * Supports loading credentials from:
+ * - Environment variables (via .env files or process.env)
+ * - JSON config files with env var interpolation
+ *
+ * Env var reference patterns:
+ * - $VAR_NAME
+ * - ${VAR_NAME}
+ * - ${VAR_NAME:-default}  (with default value)
+ */
+export interface CredentialsConfig {
+    /** Path to .env file (default: .env in cwd) */
+    envFile?: string;
+    /** Additional .env files to load (loaded in order, later files override) */
+    envFiles?: string[];
+    /** Whether to load from process.env (default: true) */
+    useProcessEnv?: boolean;
+    /** Base directory for resolving relative paths */
+    baseDir?: string;
+}
+export interface LoadEnvResult {
+    /** Whether any .env files were loaded */
+    loaded: boolean;
+    /** Paths of loaded .env files */
+    files: string[];
+    /** Number of variables loaded */
+    count: number;
+}
+/**
+ * Load environment variables from .env files
+ */
+export declare function loadEnv(options?: CredentialsConfig): LoadEnvResult;
+/**
+ * Resolve environment variable references in a string
+ *
+ * Supports:
+ * - $VAR_NAME
+ * - ${VAR_NAME}
+ * - ${VAR_NAME:-default}
+ */
+export declare function resolveEnvString(value: string): string;
+/**
+ * Check if a string contains env var references
+ */
+export declare function hasEnvReference(value: string): boolean;
+/**
+ * Recursively resolve all env var references in an object
+ */
+export declare function resolveCredentials<T>(config: T): T;
+/**
+ * Auth configuration types that can be resolved from env vars
+ */
+export interface AuthCredentials {
+    [sourceName: string]: SourceCredentials;
+}
+export interface SourceCredentials {
+    type: 'bearer' | 'oauth2' | 'api_key' | 'basic';
+    /** Bearer token (for type: bearer) */
+    token?: string;
+    /** Access token (for type: oauth2) */
+    accessToken?: string;
+    /** Refresh token (for type: oauth2) */
+    refreshToken?: string;
+    /** Token endpoint URL (for type: oauth2) */
+    tokenEndpoint?: string;
+    /** OAuth2 client ID */
+    clientId?: string;
+    /** OAuth2 client secret */
+    clientSecret?: string;
+    /** API key value (for type: api_key) */
+    apiKey?: string;
+    /** API key header name (default: X-API-Key) */
+    headerName?: string;
+    /** Username (for type: basic) */
+    username?: string;
+    /** Password (for type: basic) */
+    password?: string;
+}
+/**
+ * Load and resolve credentials from a JSON file with env var interpolation
+ */
+export declare function loadCredentials(config: Record<string, unknown>, options?: CredentialsConfig): AuthCredentials;
+/**
+ * Build credentials directly from environment variables using a naming convention
+ *
+ * Convention: REQON_{SOURCE}_{FIELD}
+ * Example: REQON_GITHUB_TOKEN, REQON_XERO_CLIENT_ID
+ */
+export declare function credentialsFromEnv(sourceNames: string[]): AuthCredentials;

package/dist/auth/credentials.js

@@ -0,0 +1,169 @@
+/**
+ * Credentials resolver with dotenv support
+ *
+ * Supports loading credentials from:
+ * - Environment variables (via .env files or process.env)
+ * - JSON config files with env var interpolation
+ *
+ * Env var reference patterns:
+ * - $VAR_NAME
+ * - ${VAR_NAME}
+ * - ${VAR_NAME:-default}  (with default value)
+ */
+import { config as dotenvConfig } from 'dotenv';
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+/**
+ * Load environment variables from .env files
+ */
+export function loadEnv(options = {}) {
+    const baseDir = options.baseDir || process.cwd();
+    const files = [];
+    let totalCount = 0;
+    // Determine which .env files to load
+    const envFilePaths = [];
+    if (options.envFiles) {
+        envFilePaths.push(...options.envFiles.map((f) => resolve(baseDir, f)));
+    }
+    else if (options.envFile) {
+        envFilePaths.push(resolve(baseDir, options.envFile));
+    }
+    else {
+        // Default: look for .env, .env.local in order
+        const defaultFiles = ['.env', '.env.local'];
+        for (const file of defaultFiles) {
+            const path = resolve(baseDir, file);
+            if (existsSync(path)) {
+                envFilePaths.push(path);
+            }
+        }
+    }
+    // Load each file (later files override earlier ones)
+    for (const envPath of envFilePaths) {
+        if (existsSync(envPath)) {
+            const result = dotenvConfig({ path: envPath, override: true });
+            if (!result.error && result.parsed) {
+                files.push(envPath);
+                totalCount += Object.keys(result.parsed).length;
+            }
+        }
+    }
+    return {
+        loaded: files.length > 0,
+        files,
+        count: totalCount,
+    };
+}
+/**
+ * Resolve environment variable references in a string
+ *
+ * Supports:
+ * - $VAR_NAME
+ * - ${VAR_NAME}
+ * - ${VAR_NAME:-default}
+ */
+export function resolveEnvString(value) {
+    // Pattern for ${VAR:-default} or ${VAR}
+    const bracketPattern = /\$\{([^}:]+)(?::-([^}]*))?\}/g;
+    // Pattern for $VAR (word characters only, not followed by {)
+    const simplePattern = /\$([A-Za-z_][A-Za-z0-9_]*)/g;
+    let result = value;
+    // First resolve ${VAR} and ${VAR:-default} patterns
+    result = result.replace(bracketPattern, (_match, varName, defaultValue) => {
+        const envValue = process.env[varName];
+        if (envValue !== undefined) {
+            return envValue;
+        }
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        // Return empty string if no value and no default
+        return '';
+    });
+    // Then resolve $VAR patterns (only if not already resolved)
+    result = result.replace(simplePattern, (_match, varName) => {
+        const envValue = process.env[varName];
+        return envValue !== undefined ? envValue : '';
+    });
+    return result;
+}
+/**
+ * Check if a string contains env var references
+ */
+export function hasEnvReference(value) {
+    return /\$\{?[A-Za-z_][A-Za-z0-9_]*/.test(value);
+}
+/**
+ * Recursively resolve all env var references in an object
+ */
+export function resolveCredentials(config) {
+    if (config === null || config === undefined) {
+        return config;
+    }
+    if (typeof config === 'string') {
+        return resolveEnvString(config);
+    }
+    if (Array.isArray(config)) {
+        return config.map((item) => resolveCredentials(item));
+    }
+    if (typeof config === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(config)) {
+            result[key] = resolveCredentials(value);
+        }
+        return result;
+    }
+    return config;
+}
+/**
+ * Load and resolve credentials from a JSON file with env var interpolation
+ */
+export function loadCredentials(config, options = {}) {
+    // Load .env files first
+    loadEnv(options);
+    // Resolve env var references in the config
+    return resolveCredentials(config);
+}
+/**
+ * Build credentials directly from environment variables using a naming convention
+ *
+ * Convention: REQON_{SOURCE}_{FIELD}
+ * Example: REQON_GITHUB_TOKEN, REQON_XERO_CLIENT_ID
+ */
+export function credentialsFromEnv(sourceNames) {
+    const credentials = {};
+    for (const sourceName of sourceNames) {
+        const prefix = `REQON_${sourceName.toUpperCase()}_`;
+        const sourceCredentials = {};
+        // Map env var suffixes to credential fields
+        const fieldMappings = {
+            TYPE: 'type',
+            TOKEN: 'token',
+            ACCESS_TOKEN: 'accessToken',
+            REFRESH_TOKEN: 'refreshToken',
+            TOKEN_ENDPOINT: 'tokenEndpoint',
+            CLIENT_ID: 'clientId',
+            CLIENT_SECRET: 'clientSecret',
+            API_KEY: 'apiKey',
+            HEADER_NAME: 'headerName',
+            USERNAME: 'username',
+            PASSWORD: 'password',
+        };
+        for (const [suffix, field] of Object.entries(fieldMappings)) {
+            const envVar = `${prefix}${suffix}`;
+            const value = process.env[envVar];
+            if (value !== undefined) {
+                sourceCredentials[field] = value;
+            }
+        }
+        // Only add if we found at least a type or token
+        if (sourceCredentials.type || sourceCredentials.token || sourceCredentials.accessToken) {
+            // Default to bearer if we have a token but no type
+            if (!sourceCredentials.type && sourceCredentials.token) {
+                sourceCredentials.type = 'bearer';
+            }
+            credentials[sourceName] = sourceCredentials;
+        }
+    }
+    return credentials;
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,5 @@
+export type { AuthProvider, TokenInfo, OAuth2Tokens, TokenStore, OAuth2Config, RateLimitInfo, RateLimiter, RateLimitStatus, RateLimitConfig, RateLimitCallbacks, RateLimitEvent, RateLimitStrategy, } from './types.js';
+export { AdaptiveRateLimiter, parseRateLimitHeaders, RateLimitError, RateLimitTimeoutError, } from './rate-limiter.js';
+export { InMemoryTokenStore, FileTokenStore } from './token-store.js';
+export { OAuth2AuthProvider, BearerTokenProvider, ApiKeyProvider } from './oauth2-provider.js';
+export { CircuitBreaker, CircuitBreakerError, type CircuitBreakerConfig, type CircuitBreakerStatus, type CircuitBreakerEvent, type CircuitBreakerCallbacks, type CircuitState, } from './circuit-breaker.js';

package/dist/auth/index.js

@@ -0,0 +1,8 @@
+// Rate limiting
+export { AdaptiveRateLimiter, parseRateLimitHeaders, RateLimitError, RateLimitTimeoutError, } from './rate-limiter.js';
+// Token stores
+export { InMemoryTokenStore, FileTokenStore } from './token-store.js';
+// Auth providers
+export { OAuth2AuthProvider, BearerTokenProvider, ApiKeyProvider } from './oauth2-provider.js';
+// Circuit breaker
+export { CircuitBreaker, CircuitBreakerError, } from './circuit-breaker.js';

package/dist/auth/oauth2-provider.d.ts

@@ -0,0 +1,41 @@
+import type { AuthProvider, TokenInfo, TokenStore, OAuth2Config } from './types.js';
+/**
+ * OAuth2 auth provider with automatic token refresh
+ */
+export declare class OAuth2AuthProvider implements AuthProvider {
+    private connectionId;
+    private store;
+    private config;
+    private refreshBuffer;
+    private refreshPromise;
+    constructor(options: {
+        connectionId: string;
+        store: TokenStore;
+        config: OAuth2Config;
+    });
+    getToken(): Promise<string>;
+    refreshToken(): Promise<string>;
+    private doRefresh;
+    private shouldRefresh;
+    getTokenInfo(): TokenInfo;
+}
+/**
+ * Simple bearer token provider (no refresh)
+ */
+export declare class BearerTokenProvider implements AuthProvider {
+    private token;
+    constructor(token: string);
+    getToken(): Promise<string>;
+    getTokenInfo(): TokenInfo;
+}
+/**
+ * API key provider
+ */
+export declare class ApiKeyProvider implements AuthProvider {
+    private apiKey;
+    private headerName;
+    constructor(apiKey: string, headerName?: string);
+    getToken(): Promise<string>;
+    getHeaderName(): string;
+    getTokenInfo(): TokenInfo;
+}