@db3.ai/app 0.1.0-beta.1

package/dist/ai/AIFailover.js

@@ -0,0 +1,96 @@
+import { AIRateLimitDeferredError } from './AIRateLimiter.js';
+import { openAIProviderError, isOpenAIQuotaError } from './OpenAIProviderError.js';
+const FAILOVERABLE_STATUS_CODES = new Set([408, 409, 429]);
+const FAILOVERABLE_ERROR_CODES = new Set([
+    'rate_limit_exceeded',
+    'insufficient_quota',
+    'billing_hard_limit_reached',
+    'overloaded',
+    'overloaded_error',
+    'server_error',
+    'service_unavailable',
+]);
+const NETWORK_ERROR_NAMES = new Set([
+    'AbortError',
+    'TimeoutError',
+    'APIConnectionError',
+    'APIConnectionTimeoutError',
+    'ConnectTimeoutError',
+    'FetchError',
+]);
+const NETWORK_ERROR_CODES = new Set([
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EPIPE',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT',
+    'UND_ERR_SOCKET',
+]);
+/**
+ * Decides whether a provider HTTP response should fail over to the next provider.
+ *
+ * Failover is reserved for transient availability problems and exhausted
+ * account capacity: rate limits, overload, 5xx, timeouts, and quota. Request
+ * problems such as validation or authentication failures stay terminal because
+ * retrying them on another provider repeats the same failure at extra cost.
+ *
+ * @param status - HTTP response status.
+ * @param payload - Parsed provider response payload.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export function isFailoverableResponse(status, payload) {
+    if (FAILOVERABLE_STATUS_CODES.has(status) || status >= 500)
+        return true;
+    if (isOpenAIQuotaError(payload))
+        return true;
+    const code = openAIProviderError(payload).code;
+    return code !== null && FAILOVERABLE_ERROR_CODES.has(code);
+}
+/**
+ * Decides whether a thrown provider or SDK failure should fail over.
+ *
+ * Local rate-limit deferrals count as failoverable because a full local bucket
+ * for one provider says nothing about the capacity of the next provider.
+ * Streaming SDK failures may carry a provider code without an HTTP status, so
+ * classification never relies on status alone.
+ *
+ * @param error - Unknown thrown value from a provider call or SDK run.
+ * @returns True when the next provider in the chain should be attempted.
+ */
+export function isFailoverableFailure(error) {
+    if (error instanceof AIRateLimitDeferredError)
+        return true;
+    if (isNetworkFailure(error))
+        return true;
+    const details = openAIProviderError(error);
+    if (details.code !== null && FAILOVERABLE_ERROR_CODES.has(details.code))
+        return true;
+    if (details.status !== null && (FAILOVERABLE_STATUS_CODES.has(details.status) || details.status >= 500))
+        return true;
+    return false;
+}
+/**
+ * Detects network, DNS, and timeout failures from fetch and SDK clients.
+ *
+ * Undici wraps socket errors inside `TypeError: fetch failed` with the real
+ * failure on `cause`, so the check walks the cause chain.
+ *
+ * @param error - Unknown thrown value.
+ * @returns True when the failure happened before a provider response arrived.
+ */
+function isNetworkFailure(error, depth = 0) {
+    if ((!(error instanceof Error) && !(error instanceof DOMException)) || depth > 4)
+        return false;
+    if (NETWORK_ERROR_NAMES.has(error.name))
+        return true;
+    if (error instanceof TypeError && error.message.includes('fetch failed'))
+        return true;
+    const code = error.code;
+    if (typeof code === 'string' && NETWORK_ERROR_CODES.has(code))
+        return true;
+    return isNetworkFailure(error.cause, depth + 1);
+}

package/dist/ai/AIProviders.d.ts

@@ -0,0 +1,35 @@
+import type { AIProviderAttempt, ResolveProviderChainInput } from './contracts/Providers.js';
+export type { AIProviderConfig, AIProviderAttempt, AIProviderAttemptFailure, ResolvedOpenAIConnection, ResolveProviderChainInput } from './contracts/Providers.js';
+import { type AIProvider } from './contracts/AI.js';
+/**
+ * Resolves an ordered provider selection into fully configured attempts.
+ *
+ * Providers without an API key, or non-OpenAI providers without a model, are
+ * skipped so a half-configured backup can never break the primary path. The
+ * OpenAI entry keeps using the AI service's resolved key, base URL, and model.
+ *
+ * @param input - Selection plus the resolved OpenAI connection.
+ * @returns Ordered attempts to try in sequence.
+ * @throws AIConfigurationError when no provider in the selection is usable.
+ */
+export declare function resolveProviderChain(input: ResolveProviderChainInput): AIProviderAttempt[];
+/**
+ * Reads the app-wide default provider chain from AI_PROVIDER_CHAIN.
+ *
+ * @returns Ordered provider list, or null when the variable is unset.
+ * @throws AIConfigurationError when the variable names an unknown provider.
+ */
+export declare function providerChainFromEnvironment(): AIProvider[] | null;
+/**
+ * Returns a synthetic failoverable outage for providers listed in AI_PROVIDER_OUTAGE.
+ *
+ * This is a development and testing toggle: listed providers stay in the
+ * resolved chain but every attempt fails immediately with a 503-style error
+ * that the failover classifier treats as failoverable. That exercises the real
+ * failover path, attempt auditing, and terminal behavior when no backup is
+ * configured. Use AI_PROVIDER_DISABLED instead to skip a provider entirely.
+ *
+ * @param provider - Provider about to be attempted.
+ * @returns Error to throw in place of the provider call, or null.
+ */
+export declare function simulatedProviderOutage(provider: AIProvider): Error | null;

package/dist/ai/AIProviders.js

@@ -0,0 +1,197 @@
+import { AI_PROVIDER } from './contracts/AI.js';
+import { AIConfigurationError } from './AIErrors.js';
+const AI_PROVIDER_CONFIG = {
+    [AI_PROVIDER.openai]: {
+        apiKeyEnv: 'OPENAI_API_KEY',
+        baseUrlEnv: 'OPENAI_BASE_URL',
+        modelEnv: null,
+        defaultBaseUrl: 'https://api.openai.com/v1',
+        supportsResponsesApi: true,
+    },
+    [AI_PROVIDER.openrouter]: {
+        apiKeyEnv: 'OPENROUTER_API_KEY',
+        baseUrlEnv: 'OPENROUTER_BASE_URL',
+        modelEnv: 'OPENROUTER_MODEL',
+        defaultBaseUrl: 'https://openrouter.ai/api/v1',
+        supportsResponsesApi: true,
+    },
+    [AI_PROVIDER.groq]: {
+        apiKeyEnv: 'GROQ_API_KEY',
+        baseUrlEnv: 'GROQ_BASE_URL',
+        modelEnv: 'GROQ_MODEL',
+        defaultBaseUrl: 'https://api.groq.com/openai/v1',
+        supportsResponsesApi: false,
+    },
+    [AI_PROVIDER.xai]: {
+        apiKeyEnv: 'XAI_API_KEY',
+        baseUrlEnv: 'XAI_BASE_URL',
+        modelEnv: 'XAI_MODEL',
+        defaultBaseUrl: 'https://api.x.ai/v1',
+        supportsResponsesApi: false,
+    },
+    [AI_PROVIDER.deepseek]: {
+        apiKeyEnv: 'DEEPSEEK_API_KEY',
+        baseUrlEnv: 'DEEPSEEK_BASE_URL',
+        modelEnv: 'DEEPSEEK_MODEL',
+        defaultBaseUrl: 'https://api.deepseek.com/v1',
+        supportsResponsesApi: false,
+    },
+};
+/**
+ * Resolves an ordered provider selection into fully configured attempts.
+ *
+ * Providers without an API key, or non-OpenAI providers without a model, are
+ * skipped so a half-configured backup can never break the primary path. The
+ * OpenAI entry keeps using the AI service's resolved key, base URL, and model.
+ *
+ * @param input - Selection plus the resolved OpenAI connection.
+ * @returns Ordered attempts to try in sequence.
+ * @throws AIConfigurationError when no provider in the selection is usable.
+ */
+export function resolveProviderChain(input) {
+    const entries = normalizeSelection(input.selection);
+    const disabled = providerListFromEnvironment('AI_PROVIDER_DISABLED');
+    const attempts = [];
+    let sawDisabled = false;
+    for (const [provider, model] of entries) {
+        if (disabled.includes(provider)) {
+            sawDisabled = true;
+            continue;
+        }
+        const attempt = resolveAttempt(provider, model, input.openai);
+        if (attempt)
+            attempts.push(attempt);
+    }
+    if (attempts.length === 0) {
+        throw new AIConfigurationError(sawDisabled
+            ? 'No usable AI provider remains: every provider in the selection is disabled by AI_PROVIDER_DISABLED or unconfigured.'
+            : undefined);
+    }
+    return attempts;
+}
+/**
+ * Reads the app-wide default provider chain from AI_PROVIDER_CHAIN.
+ *
+ * @returns Ordered provider list, or null when the variable is unset.
+ * @throws AIConfigurationError when the variable names an unknown provider.
+ */
+export function providerChainFromEnvironment() {
+    const chain = providerListFromEnvironment('AI_PROVIDER_CHAIN');
+    return chain.length > 0 ? chain : null;
+}
+/**
+ * Returns a synthetic failoverable outage for providers listed in AI_PROVIDER_OUTAGE.
+ *
+ * This is a development and testing toggle: listed providers stay in the
+ * resolved chain but every attempt fails immediately with a 503-style error
+ * that the failover classifier treats as failoverable. That exercises the real
+ * failover path, attempt auditing, and terminal behavior when no backup is
+ * configured. Use AI_PROVIDER_DISABLED instead to skip a provider entirely.
+ *
+ * @param provider - Provider about to be attempted.
+ * @returns Error to throw in place of the provider call, or null.
+ */
+export function simulatedProviderOutage(provider) {
+    if (!providerListFromEnvironment('AI_PROVIDER_OUTAGE').includes(provider))
+        return null;
+    return Object.assign(new Error(`Simulated outage for AI provider ${provider} (AI_PROVIDER_OUTAGE).`), {
+        code: 'service_unavailable',
+        status: 503,
+    });
+}
+/**
+ * Parses a comma-separated provider list environment variable.
+ *
+ * @param name - Environment variable name.
+ * @returns Ordered provider list, empty when the variable is unset.
+ * @throws AIConfigurationError when the variable names an unknown provider.
+ */
+function providerListFromEnvironment(name) {
+    const value = process.env[name]?.trim();
+    if (!value)
+        return [];
+    return value.split(',').map(part => {
+        const provider = part.trim();
+        if (!isKnownProvider(provider)) {
+            throw new AIConfigurationError(`Unknown AI provider "${provider}" in ${name}.`);
+        }
+        return provider;
+    });
+}
+/**
+ * Normalizes any selection shape into ordered provider/model pairs.
+ *
+ * @param selection - Provider selection, or null for the OpenAI default.
+ * @returns Ordered pairs where a null model means "use the provider default".
+ * @throws AIConfigurationError when the selection names an unknown provider.
+ */
+function normalizeSelection(selection) {
+    if (!selection)
+        return [[AI_PROVIDER.openai, null]];
+    if (typeof selection === 'string') {
+        assertKnownProvider(selection);
+        return [[selection, null]];
+    }
+    if (Array.isArray(selection)) {
+        if (selection.length === 0)
+            return [[AI_PROVIDER.openai, null]];
+        return selection.map(provider => {
+            assertKnownProvider(provider);
+            return [provider, null];
+        });
+    }
+    const entries = Object.entries(selection);
+    if (entries.length === 0)
+        return [[AI_PROVIDER.openai, null]];
+    return entries.map(([provider, model]) => {
+        assertKnownProvider(provider);
+        return [provider, model];
+    });
+}
+/**
+ * Resolves credentials and model for one provider entry.
+ *
+ * @param provider - Known provider id.
+ * @param model - Explicit model from a record selection, or null.
+ * @param openai - Resolved OpenAI connection for the openai entry.
+ * @returns Configured attempt, or null when the provider is not usable.
+ */
+function resolveAttempt(provider, model, openai) {
+    const config = AI_PROVIDER_CONFIG[provider];
+    const isOpenAI = provider === AI_PROVIDER.openai;
+    const apiKey = isOpenAI ? openai.apiKey : (process.env[config.apiKeyEnv] ?? '');
+    const baseUrl = isOpenAI
+        ? openai.baseUrl
+        : (process.env[config.baseUrlEnv] || config.defaultBaseUrl).replace(/\/+$/g, '');
+    const resolvedModel = model
+        || (isOpenAI ? openai.model : (config.modelEnv ? process.env[config.modelEnv] : undefined))
+        || null;
+    if (!apiKey || !resolvedModel)
+        return null;
+    return {
+        provider,
+        model: resolvedModel,
+        apiKey,
+        baseUrl,
+        supportsResponsesApi: config.supportsResponsesApi,
+    };
+}
+/**
+ * Narrows an arbitrary string to a known provider id.
+ *
+ * @param value - Candidate provider id.
+ * @returns True when the value is a registered provider.
+ */
+function isKnownProvider(value) {
+    return Object.prototype.hasOwnProperty.call(AI_PROVIDER_CONFIG, value);
+}
+/**
+ * Throws a configuration error for unknown provider ids in a selection.
+ *
+ * @param value - Candidate provider id.
+ */
+function assertKnownProvider(value) {
+    if (!isKnownProvider(value)) {
+        throw new AIConfigurationError(`Unknown AI provider "${value}" in provider selection.`);
+    }
+}

package/dist/ai/AIQuotaDeferredError.d.ts

@@ -0,0 +1,19 @@
+import { QueueRetryLaterError } from '@db3.ai/app/queue';
+/**
+ * Queue-compatible deferral raised while OpenAI account quota is unavailable.
+ */
+export declare class AIQuotaDeferredError extends QueueRetryLaterError {
+    readonly retryAt: Date;
+    readonly retryUntil: Date;
+    readonly deferralCount: number;
+    /**
+     * Creates one bounded quota deferral.
+     *
+     * @param delaySeconds - Seconds before the queued job should retry.
+     * @param retryAt - Absolute time of the scheduled retry.
+     * @param retryUntil - Absolute time after which quota retries become terminal.
+     * @param deferralCount - Number of quota deferrals recorded for this request.
+     * @param message - Provider failure message.
+     */
+    constructor(delaySeconds: number, retryAt: Date, retryUntil: Date, deferralCount: number, message: string);
+}

package/dist/ai/AIQuotaDeferredError.js

@@ -0,0 +1,25 @@
+import { QueueRetryLaterError } from '@db3.ai/app/queue';
+/**
+ * Queue-compatible deferral raised while OpenAI account quota is unavailable.
+ */
+export class AIQuotaDeferredError extends QueueRetryLaterError {
+    retryAt;
+    retryUntil;
+    deferralCount;
+    /**
+     * Creates one bounded quota deferral.
+     *
+     * @param delaySeconds - Seconds before the queued job should retry.
+     * @param retryAt - Absolute time of the scheduled retry.
+     * @param retryUntil - Absolute time after which quota retries become terminal.
+     * @param deferralCount - Number of quota deferrals recorded for this request.
+     * @param message - Provider failure message.
+     */
+    constructor(delaySeconds, retryAt, retryUntil, deferralCount, message) {
+        super(delaySeconds, message);
+        this.retryAt = retryAt;
+        this.retryUntil = retryUntil;
+        this.deferralCount = deferralCount;
+        this.name = 'AIQuotaDeferredError';
+    }
+}

package/dist/ai/AIRateLimiter.d.ts

@@ -0,0 +1,103 @@
+import type { AIRateLimitAcquireInput, AIRateLimitLease, AIRateLimitSnapshot, AIProviderResponseMetadata } from './contracts/RateLimits.js';
+export type { AIRateLimitAcquireInput, AIRateLimitLease, AIRateLimitSnapshot, AIProviderResponseMetadata } from './contracts/RateLimits.js';
+import { QueueRetryLaterError } from '@db3.ai/app/queue';
+import { type AiRateLimitEndpoint } from './AiRateLimitBucket.js';
+import { type AIProvider } from './contracts/AI.js';
+/**
+ * Coordinates OpenAI provider calls against the latest observed rate-limit state.
+ */
+export declare class AIRateLimiter {
+    /**
+     * Reserves capacity for one provider request.
+     *
+     * @param input - Provider endpoint, model, and estimated request size.
+     * @returns Reservation lease that must be observed or released after the call.
+     */
+    acquire(input: AIRateLimitAcquireInput): Promise<AIRateLimitLease>;
+    /**
+     * Updates bucket state from provider response headers and releases the lease.
+     *
+     * @param lease - Reservation returned from acquire().
+     * @param metadata - Parsed response header metadata.
+     */
+    observe(lease: AIRateLimitLease | null, metadata: AIProviderResponseMetadata): Promise<void>;
+    /**
+     * Releases a lease without changing bucket state.
+     *
+     * @param lease - Reservation returned from acquire().
+     */
+    release(lease: AIRateLimitLease | null): Promise<void>;
+    /**
+     * Finds or creates a bucket row in the current database scope.
+     *
+     * @param input - Stable bucket identity.
+     * @returns Persisted bucket row.
+     */
+    private findOrCreateBucket;
+}
+/**
+ * Rate-limit deferral that also satisfies the framework queue retry-later contract.
+ */
+export declare class AIRateLimitDeferredError extends QueueRetryLaterError {
+    readonly bucketKey: string;
+    readonly resetAt: Date | null;
+    /**
+     * Create a provider rate-limit deferral.
+     *
+     * @param delaySeconds - Number of seconds before retrying the provider call.
+     * @param bucketKey - Rate-limit bucket that caused the deferral.
+     * @param resetAt - Absolute provider reset time, when known.
+     * @param message - Human-readable explanation.
+     */
+    constructor(delaySeconds: number, bucketKey: string, resetAt: Date | null, message: string);
+}
+/**
+ * Builds the stable bucket key used to separate provider endpoint families.
+ *
+ * @param provider - AI provider id.
+ * @param endpoint - Provider endpoint family.
+ * @param limitKey - Model or shared-limit key.
+ * @returns Stable bucket key.
+ */
+export declare function aiRateLimitBucketKey(provider: AIProvider, endpoint: AiRateLimitEndpoint, limitKey: string): string;
+/**
+ * Extracts request-id and rate-limit metadata from provider response headers.
+ *
+ * @param headers - HTTP response headers.
+ * @param observedAt - Time the response was observed.
+ * @returns Parsed provider metadata.
+ */
+export declare function providerResponseMetadata(headers: Headers, observedAt?: Date): AIProviderResponseMetadata;
+/**
+ * Parses OpenAI x-ratelimit response headers into a JSON-safe snapshot.
+ *
+ * @param headers - HTTP response headers.
+ * @param observedAt - Time the response was observed.
+ * @returns Parsed snapshot, or null when no rate-limit headers are present.
+ */
+export declare function parseAIRateLimitHeaders(headers: Headers, observedAt?: Date): AIRateLimitSnapshot | null;
+/**
+ * Parses OpenAI reset duration headers such as "1s", "6m0s", or "250ms".
+ *
+ * @param value - Header duration value.
+ * @returns Duration in milliseconds, or null when unparseable.
+ */
+export declare function parseRateLimitResetMs(value: string | null): number | null;
+/**
+ * Returns the endpoint constant for Responses API calls.
+ *
+ * @returns Responses endpoint value.
+ */
+export declare function responsesRateLimitEndpoint(): AiRateLimitEndpoint;
+/**
+ * Returns the endpoint constant for Embeddings API calls.
+ *
+ * @returns Embeddings endpoint value.
+ */
+export declare function embeddingsRateLimitEndpoint(): AiRateLimitEndpoint;
+/**
+ * Returns the endpoint constant for Images API calls.
+ *
+ * @returns Images endpoint value.
+ */
+export declare function imagesRateLimitEndpoint(): AiRateLimitEndpoint;