@digilogiclabs/platform-core 1.4.0 → 1.5.1

package/dist/index.d.ts

@@ -2,10 +2,11 @@ import { p as ILogger, q as IMetrics, I as IPlatform, P as PlatformHealthStatus,
 export { aI as AIChatChoice, br as AIConfigSchema, aO as AIError, aN as AIErrorCode, aC as AIErrorMessages, aJ as AIFinishReason, aF as AIMessage, bk as AIProviderSchema, aE as AIRole, aM as AIRouterConfig, aH as AITool, aG as AIToolCall, aK as AIUsageInfo, am as BackoffOptions, by as BulkheadConfigSchema, bI as CacheConfig, bn as CacheConfigSchema, be as CacheProviderSchema, aS as ChunkingConfig, aQ as ChunkingPresets, aR as ChunkingStrategy, bw as CircuitBreakerConfigSchema, C as ConsoleEmail, h as ConsoleLogger, aX as CryptoAlgorithm, bP as CryptoConfig, bt as CryptoConfigSchema, aW as CryptoKeyStatus, bH as DatabaseConfig, bm as DatabaseConfigSchema, bd as DatabaseProviderSchema, b7 as EmailAddress, b8 as EmailAttachment, bK as EmailConfig, bp as EmailConfigSchema, bg as EmailProviderSchema, E as EnvSecrets, aw as GetSecretOptions, as as HistogramStats, ah as ICacheOptions, r as ISecrets, b1 as ISpan, b0 as ITracing, aj as JobContext, ak as JobEvent, ai as JobResult, ap as LogEntry, an as LogLevel, bj as LogLevelSchema, ao as LogMeta, aq as LoggerConfig, bA as LoggingConfigSchema, aD as MemoryAI, a as MemoryCache, M as MemoryDatabase, c as MemoryEmail, i as MemoryMetrics, d as MemoryQueue, aP as MemoryRAG, f as MemorySecrets, b as MemoryStorage, a_ as MemoryTracing, ar as MetricTags, bB as MetricsConfigSchema, bO as MiddlewareConfig, bE as MiddlewareConfigSchema, N as NoopLogger, j as NoopMetrics, a$ as NoopTracing, bN as ObservabilityConfig, bD as ObservabilityConfigSchema, bG as PlatformConfig, bF as PlatformConfigSchema, bL as QueueConfig, bq as QueueConfigSchema, bh as QueueProviderSchema, al as QueueStats, bs as RAGConfigSchema, aU as RAGFilter, aV as RAGPipelineStep, bl as RAGProviderSchema, bM as ResilienceConfig, bz as ResilienceConfigSchema, bv as RetryConfigSchema, ay as RotateSecretOptions, az as RotationResult, aL as RoutingStrategy, aT as SearchMode, au as Secret, av as SecretMetadata, bQ as SecurityConfig, bu as SecurityConfigSchema, ax as SetSecretOptions, b2 as SpanContext, bc as SpanEvent, b5 as SpanKind, b3 as SpanOptions, b4 as SpanStatus, bb as SpanStatusCode, bJ as StorageConfig, bo as StorageConfigSchema, bf as StorageProviderSchema, bx as TimeoutConfigSchema, at as TimingStats, b6 as TracingConfig, bC as TracingConfigSchema, bi as TracingProviderSchema, b9 as calculateBackoff, aA as createAIError, g as createPlatform, aY as createPlatformAsync, aZ as createScopedMetrics, ba as generateJobId, bU as getDefaultConfig, aB as isAIError, bR as loadConfig, bT as safeValidateConfig, bS as validateConfig } from './ConsoleEmail-ubSVWgTa.js';
 export { t as IMigrationDatabase, I as IMigrator, n as Migration, o as MigrationRecord, p as MigrationResult, q as MigrationStatus, M as Migrator, r as MigratorConfig, S as SQL, f as createDomainVerificationsTable, c as createMigration, b as createSsoOidcConfigsTable, m as createSsoSessionsTable, k as createTenantInvitationsTable, j as createTenantMembersTable, l as createTenantUsageTable, i as createTenantsTable, h as createVerifiedDomainsTable, d as defineMigration, e as enterpriseMigrations, g as generateVersion, a as getEnterpriseMigrations, s as sqlMigration } from './index-CepDdu7h.js';
 export { NextHeaderEntry, SecurityHeaderPresets, SecurityHeadersConfig, generateSecurityHeaders } from './security-headers.js';
+export { AllowlistConfig, ApiSecurityConfig, ApiSecurityContext, AuditRequest, AuthCookiesConfig, AuthMethod, CommonRateLimits, DateRangeInput, DateRangeSchema, DeploymentStage, EmailInput, EmailSchema, FlagDefinition, FlagDefinitions, FlagValue, KEYCLOAK_DEFAULT_ROLES, KeycloakCallbacksConfig, KeycloakConfig, KeycloakJwtFields, KeycloakTokenSet, LoginInput, LoginSchema, OpsAuditActor, OpsAuditEvent, OpsAuditLoggerOptions, OpsAuditRecord, OpsAuditResource, PaginationInput, PaginationSchema, PasswordSchema, PersonNameSchema, PhoneSchema, RateLimitCheckResult, RateLimitOptions, RateLimitPreset, RateLimitRule, RateLimitStore, RedirectCallbackConfig, ResolvedFlags, RouteAuditConfig, SearchQueryInput, SearchQuerySchema, SecuritySession, SignupInput, SignupSchema, SlugSchema, StandardAuditActionType, StandardAuditActions, StandardRateLimitPresets, TokenRefreshResult, WrapperPresets, buildAllowlist, buildAuthCookies, buildErrorBody, buildKeycloakCallbacks, buildRateLimitHeaders, buildRateLimitResponseHeaders, buildRedirectCallback, buildTokenRefreshParams, checkRateLimit, createAuditActor, createAuditLogger, createFeatureFlags, createMemoryRateLimitStore, createSafeTextSchema, detectStage, extractAuditIp, extractAuditRequestId, extractAuditUserAgent, extractClientIp, getEndSessionEndpoint, getRateLimitStatus, getTokenEndpoint, hasAllRoles, hasAnyRole, hasRole, isAllowlisted, isTokenExpired, parseKeycloakRoles, refreshKeycloakToken, resetRateLimitForKey, resolveIdentifier, resolveRateLimitIdentifier } from './auth.js';
 import { SupabaseClient } from '@supabase/supabase-js';
 import { Pool } from 'pg';
 import { Redis } from '@upstash/redis';
-import { Redis as Redis$1 } from 'ioredis';
+import Redis$2, { Redis as Redis$1 } from 'ioredis';
 import { S3Client } from '@aws-sdk/client-s3';
 import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
 import { Resend } from 'resend';
@@ -9236,7 +9237,6 @@ declare const runWithContext: <T>(data: CorrelationData, fn: () => T) => T;
 declare const runWithContextAsync: <T>(data: CorrelationData, fn: () => Promise<T>) => Promise<T>;
 declare const getContext: () => CorrelationData | undefined;
 declare const getTraceId: () => string | undefined;
-declare const getCorrelationId: () => string | undefined;
 declare const getRequestId: () => string | undefined;
 declare const getUserId: () => string | undefined;
 declare const getTenantId: () => string | undefined;
@@ -10188,8 +10188,9 @@ declare const FallbackStrategies: {
 /**
  * Security Utilities
  *
- * HTML escaping, input detection, and sanitization helpers
- * for safe rendering of user content in emails, templates, and HTML output.
+ * HTML escaping, input detection, sanitization helpers,
+ * timing-safe comparison, error sanitization, and request
+ * correlation for safe, consistent security across all apps.
  */
 /** Regex for protocol-prefixed URLs */
 declare const URL_PROTOCOL_PATTERN: RegExp;
@@ -10218,6 +10219,58 @@ declare function defangUrl(str: string): string;
  * Escapes HTML entities AND defangs any URLs that slipped through validation.
  */
 declare function sanitizeForEmail(str: string): string;
+/**
+ * Constant-time string comparison to prevent timing side-channel attacks.
+ * Use for comparing secrets, tokens, API keys, HMAC signatures, etc.
+ *
+ * Returns false (not throws) for length mismatches — still constant-time
+ * relative to the shorter string to avoid leaking length info.
+ *
+ * @example
+ * ```typescript
+ * if (!constantTimeEqual(providedToken, expectedSecret)) {
+ *   return { status: 401, error: 'Invalid token' }
+ * }
+ * ```
+ */
+declare function constantTimeEqual(a: string, b: string): boolean;
+/**
+ * Sanitize an error for client-facing API responses.
+ *
+ * - 4xx errors: returns the actual message (client needs to know what went wrong)
+ * - 5xx errors: returns a generic message (never leak internals to clients)
+ * - Development mode: optionally includes stack trace for debugging
+ *
+ * @example
+ * ```typescript
+ * catch (error) {
+ *   const { message, code } = sanitizeApiError(error, 500)
+ *   return Response.json({ error: message, code }, { status: 500 })
+ * }
+ * ```
+ */
+declare function sanitizeApiError(error: unknown, statusCode: number, isDevelopment?: boolean): {
+    message: string;
+    code?: string;
+    stack?: string;
+};
+/**
+ * Extract a correlation/request ID from standard headers, or generate one.
+ *
+ * Checks (in order): X-Request-ID, X-Correlation-ID, then falls back to
+ * crypto.randomUUID(). Works with any headers-like object (plain object,
+ * Headers API, or a getter function).
+ *
+ * @example
+ * ```typescript
+ * // With Next.js request
+ * const id = getCorrelationId((name) => request.headers.get(name))
+ *
+ * // With plain object
+ * const id = getCorrelationId({ 'x-request-id': 'abc-123' })
+ * ```
+ */
+declare function getCorrelationId(headers: Record<string, string | string[] | undefined> | ((name: string) => string | null | undefined)): string;
 
 /**
  * API Utilities
@@ -13158,4 +13211,224 @@ declare class PostgresTenant implements ITenant {
     private mapRowToInvitation;
 }
 
-export { AIChatRequest, AIChatResponse, AICompletionRequest, AICompletionResponse, AIConfig, AIEmbeddingRequest, AIEmbeddingResponse, AIModelConfig, AIModelType, AIProvider, AIStreamCallback, AIStreamChunk, type AIUsageConfig, type AccountCapabilities, type AccountLink, type AccountType, type Address, type AlertType, AnthropicAdapter, type AnthropicAdapterConfig, type ApiAuthentication, type ApiChangelog, type ApiDocumentation, type ApiEndpoint, ApiError, ApiErrorCode, type ApiErrorCodeType, type ApiExample, type ApiKey, type ApiKeyStatus, type ApiKeyType, type ApiKeyValidationResult, type ApiPaginatedResponse, type ApiParameter, type ApiResponse, type ApiSchema, type ApiSchemaProperty, type ApiSuccessResponse, type ApiUsageStats, type ApiUsageTimeSeries, AssembledContext, type AuditActor, type AuditCategory, type AuditEvent, AuditEvents, type AuditEvidence, type AuditLogConfig, type AuditOutcome, type AuditQuery, type AuditQueryResult, type AuditRetentionPolicy, type AuditStats, type AuditTarget, type AuthConfig, type AuthError, type AuthErrorCode, AuthErrorMessages, type AuthEventType, type AuthResult, type AuthSession, type AuthStateChangeCallback, type AuthStorage, type AuthUser, type Balance, type BalanceAmount, type BankAccountDetails, type BatchNotificationOptions, type BillingConfig, type BillingDetails, type BillingPeriod, type Breadcrumb, type Budget, type BudgetStatus, BulkIngestionResult, Bulkhead, type BulkheadOptions, BulkheadRegistry, BulkheadRejectedError, type BulkheadStats, type BullMQConfig, BullMQQueue, type BusinessProfile, type CancelationReason, type CaptureOptions, type CapturePaymentIntentOptions, type CardBrand, type CardDetails, type ChainExecutionResult, CircuitBreaker, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type CommandStatus, CommonApiErrors, type ComplianceConfig, type ComplianceReport, type ConfirmPaymentIntentOptions, type ConnectedAccount, type ConnectedAccountStatus, type ConsentPreferences, type ConsentPurpose, type ConsentRecord, type ConsentStatus, ContextAssemblyConfig, type ControlFramework, type ControlStatus, type CorrelationData, type CostBreakdown, type Coupon, type CreateAccountLinkOptions, type CreateApiKeyOptions, CreateCollectionOptions, type CreateConnectedAccountOptions, type CreateCustomerOptions, type CreateDsarOptions, type CreatePaymentIntentOptions, type CreatePayoutOptions, type CreateRefundOptions, type CreateSandboxOptions, type CreateScheduleOptions, type CreateTenantOptions, type CreateTransferOptions, type CreateWebhookOptions, type CreditBalance, type CreditTransaction, type CreditType, type CronExpression, CronPresets, CryptoKeyMetadata, type Currency, type Customer, DEFAULT_BULKHEAD_OPTIONS, DEFAULT_CIRCUIT_BREAKER_OPTIONS, DEFAULT_RETRY_OPTIONS, type DataBreachRecord, type DataCategory, type DataInventoryItem, type DataMap, type DataSensitivity, type DataSubjectRequest, type DataType, DatabaseAIUsage, type DatabaseAIUsageConfig, DatabaseAuditLog, type DatabaseAuditLogConfig, DatabaseBilling, type DatabaseBillingConfig, DatabaseCompliance, DatabaseErrorReporter, type DatabaseErrorReporterConfig, DatabaseNotification, type DatabaseNotificationConfig, DatabasePromptStore, type DatabasePromptStoreConfig, DefaultTimeouts, type DeleteAccountOptions, type DeleteHookContext, type DeliveryAttempt, type DeliveryQuery, type DeliveryStatus, type DetailedHealthResponse, DeterministicEncryptedField, type DevPortalConfig, type DeveloperMetrics, type Device, type DeviceAuthMethod, type DeviceCommand, type DeviceConfig, type DeviceConnectionState, type DeviceCredentials, type DeviceGroup, type DeviceGroupQuery, type DeviceLocation, type DeviceQuery, type DeviceQueryResult, type DeviceShadow, type DeviceStatus, type DirectoryAttributeMapping, type DirectoryConfig, DocumentStatus, type DsarAttachment, type DsarNote, type DsarStatus, type DsarType, type DunningActionType, type DunningAttempt, type DunningConfig, type EmailHookContext, EmailMessage, EmailResult, EncryptOptions, EncryptedField, type EnrollMfaOptions, type EnrollMfaResult, type ErrorContext, type ErrorHookContext, type ErrorLevel, type ErrorReport, type ErrorReporterConfig, type EvidenceType, type ExperimentMetrics, type FallbackOptions, type FallbackResult, FallbackStrategies, type FirmwareStatus, type FirmwareUpdate, type FirmwareVersion, type GeneratedSdk, GenericOIDCAuthSSO, type GenericOIDCConfig, GoogleAIAdapter, type GoogleAIAdapterConfig, HTML_TAG_PATTERN, type HealthCheckResult, type HealthEndpoints, type HealthEndpointsOptions, type HealthStatus, type HookRegistry, type HttpMethod, HttpWebhook, type HttpWebhookConfig, IAI, type IAIUsage, type IAuditLog, type IAuth, type IAuthSSO, type IBilling, ICache, type ICompliance, ICrypto, IDatabase, type IDevPortal, type IDevice, IEmail, type IErrorReporter, type IHealth, type IHealthCheckable, ILogger, IMetrics, type INotification, type IPayment, IPlatform, type IPromptStore, IQueryBuilder, IQueue, IRAG, type IScheduler, IStorage, type ITenant, type IWebhook, type InboundWebhookConfig, type InboundWebhookContext, IngestionOptions, IngestionResult, type InsertHookContext, type InviteMemberOptions, type Invoice, type InvoiceLineItem, type InvoiceQuery, type InvoiceStatus, Job, JobEventHandler, JobEventType, type JobHookContext, JobOptions, JobState, KeyRotationResult, type ListTenantsOptions, type LivenessResponse, MemoryAIUsage, MemoryAuditLog, type MemoryAuditLogConfig, MemoryAuth, MemoryAuthSSO, MemoryBilling, MemoryCompliance, MemoryCrypto, MemoryDevPortal, MemoryDevice, MemoryErrorReporter, type MemoryErrorReporterConfig, MemoryNotification, type MemoryNotificationConfig, MemoryPayment, MemoryPromptStore, MemoryRateLimiterStorage, MemoryScheduler, type MemorySchedulerConfig, MemoryTenant, MemoryWebhook, type MemoryWebhookConfig, type Meter, type MetricsEndpoint, type MetricsEndpointOptions, MetricsSummary, type MfaChallenge, type MfaFactor, type MfaFactorType, type Middleware, type MiddlewareChain, type MiddlewareChainOptions, type MiddlewareContext, NodeCrypto, type NodeCryptoConfig, type NotificationAction, type NotificationCategory, type NotificationChannel, type NotificationConfig, type NotificationData, type NotificationPreferences, type NotificationPriority, type NotificationQuery, type NotificationResult, type NotificationStats, type NotificationStatus, type NotificationTarget, NotificationTemplates, type OAuthOptions, type OAuthProvider, type OAuthResult, type OidcAuthRequest, type OidcAuthResponse, type OidcClaimMapping, type OidcIdpConfig, OpenAIAdapter, type OpenAIAdapterConfig, PG_ERROR_MAP, type ParameterLocation, type PaymentConfig, type PaymentError, type PaymentErrorCode, PaymentErrorMessages, type PaymentEventType, type PaymentIntent, type PaymentMethod, type PaymentMethodType, type PaymentStatus, type PaymentWebhookEvent, type Payout, type PayoutStatus, type PiaMitigation, type PiaRisk, type PiaStatus, PineconeRAG, type PineconeRAGConfig, type PlatformHealthResult, PlatformHealthStatus, type PlatformHooks, type PostgresConfig, PostgresDatabase, PostgresTenant, type PostgresTenantConfig, type Price, type PricingModel, type PricingTier, type PrivacyImpactAssessment, type Product, type Prompt, type PromptChain, type PromptChainStep, type PromptExperiment, type PromptQuery, type PromptQueryResult, type PromptStatus, type PromptStoreConfig, type PromptType, type PromptUsageRecord, type PromptUsageStats, type PromptVariable, type PromptVariant, type PromptVersion, type ProvisioningConfig, type ProvisioningRequest, type ProvisioningResult, type ProvisioningStatus, type PushSubscription, type QueryHookContext, QueryResult, QueueScheduler, type QueueSchedulerConfig, type Quota, type QuotaStatus, type QuotaType, RAGChunk, RAGCollection, RAGConfig, RAGDocument, RAGPipeline, RAGSearchQuery, RAGSearchResponse, RAGSearchResult, type RateLimitAlgorithm, RateLimitError, type RateLimitInfo, type RateLimitOptions, RateLimitPresets, type RateLimiterStorage, type ReadinessResponse, type RecordConsentOptions, RedisCache, type RedisConfig, type Refund, type RefundReason, type RefundStatus, type RenderOptions, type RenderedPrompt, RepeatOptions, ResendEmail, type ResetPasswordOptions, type RetentionAction, type RetentionExecution, type RetentionPolicy, RetryConfigs, type RetryOptions, RetryPredicates, type RetryResult, type RevenueMetrics, type RiskLevel, S3Storage, type SamlAssertion, type SamlAttributeMapping, type SamlAuthRequest, type SamlAuthResponse, type SamlIdpConfig, type SamlNameIdFormat, type SamlSpConfig, type Sandbox, type SandboxConfig, type SandboxLimits, type SandboxStatus, type SandboxUsage, type ScheduleContext, type ScheduleExecution, type ScheduleHandler, type ScheduleQuery, type ScheduleState, type ScheduleUpdateOptions, type ScheduledJob, type SchedulerConfig, type SchedulerStats, type ScimConfig, type ScimUser, type SdkConfig, type SdkFile, type SdkLanguage, type SendCommandOptions, type SendNotificationOptions, type ServiceHealth, type ShadowDelta, type ShadowMetadata, type ShadowUpdate, type SignInWithEmailOptions, type SignInWithMagicLinkOptions, type SignInWithPhoneOptions, type SignUpWithEmailOptions, type SignatureAlgorithm, type SlidingWindowRateLimitOptions, type SmtpConfig, SmtpEmail, type SsoSession, type StartupResponse, StorageFile, type StoredAuditEvent, type StoredNotification, StripePayment, type StripePaymentConfig, type Subscription, type SubscriptionDiscount, type SubscriptionItem, type SubscriptionMetrics, type SubscriptionQuery, type SubscriptionStatus, SupabaseAuth, type SupabaseAuthConfig, SupabaseDatabase, SupabaseStorage, type SupabaseStorageConfig, type TaxBreakdown, type TelemetryMessage, type TelemetryQuery, type TelemetryResult, type Tenant, type TenantBranding, type TenantContext, type TenantDatabaseConfig, type TenantInvitation, type TenantIsolationModel, type TenantMember, type TenantMemberStatus, type TenantQuotas, type TenantResolutionOptions, type TenantResolutionStrategy, type TenantRole, type TenantSecuritySettings, type TenantSettings, type TenantStatus, type TenantUsage, TimeoutError, type TimeoutOptions, type TokenBucketOptions, type TosAcceptance, type Transfer, type TransferStatus, URL_DOMAIN_PATTERN, URL_PROTOCOL_PATTERN, type Unsubscribe, type UpdateCustomerOptions, type UpdateHookContext, type UpdatePasswordOptions, type UpdatePaymentIntentOptions, type UpdateScheduleOptions, type UpdateStatus, type UpdateTenantOptions, type UpdateUserOptions, type UpdateWebhookOptions, type UploadHookContext, UploadOptions, UpstashCache, type UsageAlert, type UsageCategory, type UsageEvent, type UsageInterval, type UsageInvoice, type UsageInvoiceItem, type UsageQuery, type UsageQueryResult, type UsageRecord, type UsageSummary, type UsageSummaryRecord, type UsageTrend, type VerificationResult, type VerifyMfaOptions, type VerifyPhoneOtpOptions, type VerifyWebhookOptions, WeaviateRAG, type WeaviateRAGConfig, type WebhookConfig, type WebhookDelivery, type WebhookEndpoint, type WebhookEvent, WebhookEventTypes, type WebhookQuery, type WebhookState, type WebhookStats, type WebhookTestEndpoint, type WebhookTestEvent, buildPagination, calculateRetryDelay, classifyError, composeHookRegistries, containsHtml, containsUrls, correlationContext, createAnthropicAdapter, createAuthError, createBulkhead, createCacheMiddleware, createCachedFallback, createCircuitBreaker, createDefaultPreferences, createErrorReport, createExpressHealthHandlers, createExpressMetricsHandler, createGoogleAIAdapter, createHealthEndpoints, createHealthServer, createHookRegistry, createIpKeyGenerator, createJobContext, createLoggingMiddleware, createMetricsEndpoint, createMetricsMiddleware, createMetricsServer, createMiddlewareChain, createMiddlewareContext, createObservabilityServer, createOpenAIAdapter, createPaymentError, createPineconeRAG, createRateLimitMiddleware, createRequestContext, createRequestIdMiddleware, createSlowQueryMiddleware, createTenantMiddleware, createTimeoutMiddleware, createUserKeyGenerator, createWeaviateRAG, defangUrl, describeCron, escapeHtml, filterChannelsByPreferences, formatAmount, generateAuditId, generateChecksum, generateDeliveryId, generateErrorId, generateEventId, generateFingerprint, generateNotificationId, generatePaymentId, generateScheduleId, generateSecureToken, generateWebhookId, generateWebhookSecret, getContext, getCorrelationId, getLogMeta, getNextCronRun, getRequestId, getTenantId, getTraceId, getUserId, isApiError, isAuthError, isInContext, isInQuietHours, isPaymentError, isValidCron, matchAction, matchEventType, raceTimeout, retryable, runWithContext, runWithContextAsync, sanitizeForEmail, stripHtml, timedHealthCheck, toHealthCheckResult, withCorrelation, withCorrelationAsync, withFallback, withFallbackChain, withFallbackResult, withRetry, withRetryResult, withTimeout, withTimeoutWrapper };
+/**
+ * Environment Variable Helpers
+ *
+ * Type-safe, fail-fast utilities for reading environment variables.
+ * Every app needs these — extracted from DLL, WIAN, and OSS patterns.
+ *
+ * @example
+ * ```typescript
+ * import { getRequiredEnv, getOptionalEnv, getBoolEnv, validateEnvVars } from '@digilogiclabs/platform-core'
+ *
+ * const config = {
+ *   stripe: { secretKey: getRequiredEnv('STRIPE_SECRET_KEY') },
+ *   redis: { url: getOptionalEnv('REDIS_URL', '') },
+ *   features: { debug: getBoolEnv('DEBUG', false) },
+ * }
+ *
+ * // Validate at startup
+ * validateEnvVars({
+ *   required: ['STRIPE_SECRET_KEY', 'DATABASE_URL'],
+ *   requireOneOf: [['DATABASE_URL', 'SUPABASE_URL']], // at least one
+ *   validators: {
+ *     DATABASE_URL: (v) => v.startsWith('postgres') || 'must start with postgres://',
+ *     ADMIN_SECRET: (v) => v.length >= 32 || 'must be at least 32 characters',
+ *   },
+ * })
+ * ```
+ */
+/**
+ * Get a required environment variable.
+ * Throws immediately if not set — fail-fast at startup.
+ */
+declare function getRequiredEnv(key: string): string;
+/**
+ * Get an optional environment variable with a default value.
+ */
+declare function getOptionalEnv(key: string, defaultValue: string): string;
+/**
+ * Get a boolean environment variable.
+ * Treats "true" and "1" as true, everything else as false.
+ */
+declare function getBoolEnv(key: string, defaultValue?: boolean): boolean;
+/**
+ * Get a numeric environment variable with a default.
+ */
+declare function getIntEnv(key: string, defaultValue: number): number;
+/**
+ * Configuration for environment validation.
+ */
+interface EnvValidationConfig {
+    /** Variables that must be set (non-empty) */
+    required?: string[];
+    /** Groups where at least one must be set (e.g., DATABASE_URL or SUPABASE_URL) */
+    requireOneOf?: string[][];
+    /** Custom validators — return true or an error message */
+    validators?: Record<string, (value: string) => true | string>;
+}
+/**
+ * Validation result with categorized errors.
+ */
+interface EnvValidationResult {
+    valid: boolean;
+    missing: string[];
+    invalid: {
+        key: string;
+        reason: string;
+    }[];
+    missingOneOf: string[][];
+}
+/**
+ * Validate environment variables against a configuration.
+ *
+ * @throws Error with details about all missing/invalid variables
+ */
+declare function validateEnvVars(config: EnvValidationConfig): void;
+/**
+ * Check environment variables without throwing.
+ * Returns a result object for custom error handling.
+ */
+declare function checkEnvVars(config: EnvValidationConfig): EnvValidationResult;
+/**
+ * Get a redacted config summary for debugging.
+ * Shows which variables are configured without exposing values.
+ */
+declare function getEnvSummary(keys: string[]): Record<string, boolean>;
+
+/**
+ * Application Logger
+ *
+ * Structured logger with child loggers, request correlation,
+ * and operation timing. Builds on ConsoleLogger but adds the
+ * patterns every app needs: component loggers, request loggers,
+ * job loggers, and timing wrappers.
+ *
+ * @example
+ * ```typescript
+ * import { createAppLogger } from '@digilogiclabs/platform-core'
+ *
+ * const logger = createAppLogger({ service: 'my-app' })
+ *
+ * // Child loggers for components
+ * const authLogger = logger.child({ component: 'auth' })
+ * authLogger.info('User signed in', { userId: '123' })
+ *
+ * // Request-scoped logger with correlation ID
+ * const reqLogger = logger.forRequest(request, 'create-server')
+ * reqLogger.info('Processing request')
+ *
+ * // Timed operations
+ * const result = await logger.timed('fetchArticles', () => fetchArticles(), { count: 10 })
+ * ```
+ */
+interface AppLogContext {
+    [key: string]: unknown;
+}
+/**
+ * Structured logger interface shared across all apps.
+ */
+interface AppLogger {
+    debug(message: string, context?: AppLogContext): void;
+    info(message: string, context?: AppLogContext): void;
+    warn(message: string, context?: AppLogContext): void;
+    error(message: string, context?: AppLogContext): void;
+    /** Create a child logger with additional persistent context */
+    child(context: AppLogContext): AppLogger;
+    /** Create a request-scoped logger with correlation ID */
+    forRequest(request: Request, operation: string): AppLogger;
+    /** Create a job-scoped logger */
+    forJob(jobType: string, jobId: string, context?: AppLogContext): AppLogger;
+    /**
+     * Execute an async operation with automatic timing.
+     * Logs start (debug), success with duration (info), or failure with duration (error).
+     */
+    timed<T>(operation: string, fn: () => Promise<T>, context?: AppLogContext): Promise<T>;
+}
+interface AppLoggerOptions {
+    /** Service/app name for log context */
+    service: string;
+    /** Minimum log level (default: 'debug' in dev, 'info' in production) */
+    minLevel?: "debug" | "info" | "warn" | "error";
+    /** Custom output handler (default: console with JSON in prod, pretty in dev) */
+    output?: (level: string, message: string, context: AppLogContext) => void;
+    /** Error reporter callback — called on error() logs */
+    onError?: (message: string, context: AppLogContext) => void;
+}
+/**
+ * Create an application logger.
+ *
+ * @param options - Logger configuration
+ * @returns Structured logger with child, request, job, and timing support
+ */
+declare function createAppLogger(options: AppLoggerOptions): AppLogger;
+
+/**
+ * Redis Client Factory
+ *
+ * Shared ioredis singleton factory with retry strategy and graceful
+ * degradation. All self-hosted apps need a Redis client for rate
+ * limiting, caching, audit logging, webhook deduplication, etc.
+ *
+ * This provides a raw ioredis client — for higher-level cache
+ * operations, use RedisCache from the adapters module.
+ *
+ * @example
+ * ```typescript
+ * import { createRedisClient, getSharedRedis } from '@digilogiclabs/platform-core'
+ *
+ * // Option 1: Shared singleton (recommended for most apps)
+ * const redis = getSharedRedis() // null if REDIS_URL not set
+ *
+ * // Option 2: Custom client with options
+ * const redis = createRedisClient({
+ *   url: process.env.REDIS_URL,
+ *   keyPrefix: 'myapp:',
+ *   maxRetries: 5,
+ * })
+ * ```
+ */
+
+interface RedisClientOptions {
+    /** Redis connection URL (redis://...) */
+    url: string;
+    /** Key prefix for namespace isolation (e.g., 'dll:', 'wian:') */
+    keyPrefix?: string;
+    /** Max retries per request (default: 3) */
+    maxRetries?: number;
+    /** Use lazy connect — don't connect until first command (default: true) */
+    lazyConnect?: boolean;
+    /** Logger for connection events (default: console) */
+    logger?: {
+        error: (msg: string, meta?: Record<string, unknown>) => void;
+        info?: (msg: string, meta?: Record<string, unknown>) => void;
+    };
+    /** Suppress connection error logs (useful for tests) */
+    silent?: boolean;
+}
+/**
+ * Create a new ioredis client with sensible defaults.
+ *
+ * Features:
+ * - Exponential backoff retry strategy (200ms, 400ms, 600ms)
+ * - Automatic reconnection
+ * - Optional key prefix for multi-app isolation
+ * - Connection error logging (suppressible)
+ */
+declare function createRedisClient(options: RedisClientOptions): Redis$2;
+/**
+ * Get the shared Redis client singleton.
+ *
+ * Returns null if REDIS_URL is not configured — callers should
+ * handle this gracefully (fail-open pattern).
+ *
+ * Reads from `REDIS_URL` and optionally `REDIS_KEY_PREFIX`.
+ */
+declare function getSharedRedis(): Redis$2 | null;
+/**
+ * Close the shared Redis client.
+ * Call during graceful shutdown.
+ */
+declare function closeSharedRedis(): Promise<void>;
+
+export { AIChatRequest, AIChatResponse, AICompletionRequest, AICompletionResponse, AIConfig, AIEmbeddingRequest, AIEmbeddingResponse, AIModelConfig, AIModelType, AIProvider, AIStreamCallback, AIStreamChunk, type AIUsageConfig, type AccountCapabilities, type AccountLink, type AccountType, type Address, type AlertType, AnthropicAdapter, type AnthropicAdapterConfig, type ApiAuthentication, type ApiChangelog, type ApiDocumentation, type ApiEndpoint, ApiError, ApiErrorCode, type ApiErrorCodeType, type ApiExample, type ApiKey, type ApiKeyStatus, type ApiKeyType, type ApiKeyValidationResult, type ApiPaginatedResponse, type ApiParameter, type ApiResponse, type ApiSchema, type ApiSchemaProperty, type ApiSuccessResponse, type ApiUsageStats, type ApiUsageTimeSeries, type AppLogContext, type AppLogger, type AppLoggerOptions, AssembledContext, type AuditActor, type AuditCategory, type AuditEvent, AuditEvents, type AuditEvidence, type AuditLogConfig, type AuditOutcome, type AuditQuery, type AuditQueryResult, type AuditRetentionPolicy, type AuditStats, type AuditTarget, type AuthConfig, type AuthError, type AuthErrorCode, AuthErrorMessages, type AuthEventType, type AuthResult, type AuthSession, type AuthStateChangeCallback, type AuthStorage, type AuthUser, type Balance, type BalanceAmount, type BankAccountDetails, type BatchNotificationOptions, type BillingConfig, type BillingDetails, type BillingPeriod, type Breadcrumb, type Budget, type BudgetStatus, BulkIngestionResult, Bulkhead, type BulkheadOptions, BulkheadRegistry, BulkheadRejectedError, type BulkheadStats, type BullMQConfig, BullMQQueue, type BusinessProfile, type CancelationReason, type CaptureOptions, type CapturePaymentIntentOptions, type CardBrand, type CardDetails, type ChainExecutionResult, CircuitBreaker, type CircuitBreakerOptions, CircuitBreakerRegistry, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type CommandStatus, CommonApiErrors, type ComplianceConfig, type ComplianceReport, type ConfirmPaymentIntentOptions, type ConnectedAccount, type ConnectedAccountStatus, type ConsentPreferences, type ConsentPurpose, type ConsentRecord, type ConsentStatus, ContextAssemblyConfig, type ControlFramework, type ControlStatus, type CorrelationData, type CostBreakdown, type Coupon, type CreateAccountLinkOptions, type CreateApiKeyOptions, CreateCollectionOptions, type CreateConnectedAccountOptions, type CreateCustomerOptions, type CreateDsarOptions, type CreatePaymentIntentOptions, type CreatePayoutOptions, type CreateRefundOptions, type CreateSandboxOptions, type CreateScheduleOptions, type CreateTenantOptions, type CreateTransferOptions, type CreateWebhookOptions, type CreditBalance, type CreditTransaction, type CreditType, type CronExpression, CronPresets, CryptoKeyMetadata, type Currency, type Customer, DEFAULT_BULKHEAD_OPTIONS, DEFAULT_CIRCUIT_BREAKER_OPTIONS, DEFAULT_RETRY_OPTIONS, type DataBreachRecord, type DataCategory, type DataInventoryItem, type DataMap, type DataSensitivity, type DataSubjectRequest, type DataType, DatabaseAIUsage, type DatabaseAIUsageConfig, DatabaseAuditLog, type DatabaseAuditLogConfig, DatabaseBilling, type DatabaseBillingConfig, DatabaseCompliance, DatabaseErrorReporter, type DatabaseErrorReporterConfig, DatabaseNotification, type DatabaseNotificationConfig, DatabasePromptStore, type DatabasePromptStoreConfig, DefaultTimeouts, type DeleteAccountOptions, type DeleteHookContext, type DeliveryAttempt, type DeliveryQuery, type DeliveryStatus, type DetailedHealthResponse, DeterministicEncryptedField, type DevPortalConfig, type DeveloperMetrics, type Device, type DeviceAuthMethod, type DeviceCommand, type DeviceConfig, type DeviceConnectionState, type DeviceCredentials, type DeviceGroup, type DeviceGroupQuery, type DeviceLocation, type DeviceQuery, type DeviceQueryResult, type DeviceShadow, type DeviceStatus, type DirectoryAttributeMapping, type DirectoryConfig, DocumentStatus, type DsarAttachment, type DsarNote, type DsarStatus, type DsarType, type DunningActionType, type DunningAttempt, type DunningConfig, type EmailHookContext, EmailMessage, EmailResult, EncryptOptions, EncryptedField, type EnrollMfaOptions, type EnrollMfaResult, type EnvValidationConfig, type EnvValidationResult, type ErrorContext, type ErrorHookContext, type ErrorLevel, type ErrorReport, type ErrorReporterConfig, type EvidenceType, type ExperimentMetrics, type FallbackOptions, type FallbackResult, FallbackStrategies, type FirmwareStatus, type FirmwareUpdate, type FirmwareVersion, type GeneratedSdk, GenericOIDCAuthSSO, type GenericOIDCConfig, GoogleAIAdapter, type GoogleAIAdapterConfig, HTML_TAG_PATTERN, type HealthCheckResult, type HealthEndpoints, type HealthEndpointsOptions, type HealthStatus, type HookRegistry, type HttpMethod, HttpWebhook, type HttpWebhookConfig, IAI, type IAIUsage, type IAuditLog, type IAuth, type IAuthSSO, type IBilling, ICache, type ICompliance, ICrypto, IDatabase, type IDevPortal, type IDevice, IEmail, type IErrorReporter, type IHealth, type IHealthCheckable, ILogger, IMetrics, type INotification, type IPayment, IPlatform, type IPromptStore, IQueryBuilder, IQueue, IRAG, type IScheduler, IStorage, type ITenant, type IWebhook, type InboundWebhookConfig, type InboundWebhookContext, IngestionOptions, IngestionResult, type InsertHookContext, type InviteMemberOptions, type Invoice, type InvoiceLineItem, type InvoiceQuery, type InvoiceStatus, Job, JobEventHandler, JobEventType, type JobHookContext, JobOptions, JobState, KeyRotationResult, type ListTenantsOptions, type LivenessResponse, MemoryAIUsage, MemoryAuditLog, type MemoryAuditLogConfig, MemoryAuth, MemoryAuthSSO, MemoryBilling, MemoryCompliance, MemoryCrypto, MemoryDevPortal, MemoryDevice, MemoryErrorReporter, type MemoryErrorReporterConfig, MemoryNotification, type MemoryNotificationConfig, MemoryPayment, MemoryPromptStore, MemoryRateLimiterStorage, MemoryScheduler, type MemorySchedulerConfig, MemoryTenant, MemoryWebhook, type MemoryWebhookConfig, type Meter, type MetricsEndpoint, type MetricsEndpointOptions, MetricsSummary, type MfaChallenge, type MfaFactor, type MfaFactorType, type Middleware, type MiddlewareChain, type MiddlewareChainOptions, type MiddlewareContext, NodeCrypto, type NodeCryptoConfig, type NotificationAction, type NotificationCategory, type NotificationChannel, type NotificationConfig, type NotificationData, type NotificationPreferences, type NotificationPriority, type NotificationQuery, type NotificationResult, type NotificationStats, type NotificationStatus, type NotificationTarget, NotificationTemplates, type OAuthOptions, type OAuthProvider, type OAuthResult, type OidcAuthRequest, type OidcAuthResponse, type OidcClaimMapping, type OidcIdpConfig, OpenAIAdapter, type OpenAIAdapterConfig, PG_ERROR_MAP, type ParameterLocation, type PaymentConfig, type PaymentError, type PaymentErrorCode, PaymentErrorMessages, type PaymentEventType, type PaymentIntent, type PaymentMethod, type PaymentMethodType, type PaymentStatus, type PaymentWebhookEvent, type Payout, type PayoutStatus, type PiaMitigation, type PiaRisk, type PiaStatus, PineconeRAG, type PineconeRAGConfig, type PlatformHealthResult, PlatformHealthStatus, type PlatformHooks, type PostgresConfig, PostgresDatabase, PostgresTenant, type PostgresTenantConfig, type Price, type PricingModel, type PricingTier, type PrivacyImpactAssessment, type Product, type Prompt, type PromptChain, type PromptChainStep, type PromptExperiment, type PromptQuery, type PromptQueryResult, type PromptStatus, type PromptStoreConfig, type PromptType, type PromptUsageRecord, type PromptUsageStats, type PromptVariable, type PromptVariant, type PromptVersion, type ProvisioningConfig, type ProvisioningRequest, type ProvisioningResult, type ProvisioningStatus, type PushSubscription, type QueryHookContext, QueryResult, QueueScheduler, type QueueSchedulerConfig, type Quota, type QuotaStatus, type QuotaType, RAGChunk, RAGCollection, RAGConfig, RAGDocument, RAGPipeline, RAGSearchQuery, RAGSearchResponse, RAGSearchResult, type RateLimitAlgorithm, RateLimitError, type RateLimitInfo, RateLimitPresets, type RateLimiterStorage, type ReadinessResponse, type RecordConsentOptions, RedisCache, type RedisClientOptions, type RedisConfig, type Refund, type RefundReason, type RefundStatus, type RenderOptions, type RenderedPrompt, RepeatOptions, ResendEmail, type ResetPasswordOptions, type RetentionAction, type RetentionExecution, type RetentionPolicy, RetryConfigs, type RetryOptions, RetryPredicates, type RetryResult, type RevenueMetrics, type RiskLevel, S3Storage, type SamlAssertion, type SamlAttributeMapping, type SamlAuthRequest, type SamlAuthResponse, type SamlIdpConfig, type SamlNameIdFormat, type SamlSpConfig, type Sandbox, type SandboxConfig, type SandboxLimits, type SandboxStatus, type SandboxUsage, type ScheduleContext, type ScheduleExecution, type ScheduleHandler, type ScheduleQuery, type ScheduleState, type ScheduleUpdateOptions, type ScheduledJob, type SchedulerConfig, type SchedulerStats, type ScimConfig, type ScimUser, type SdkConfig, type SdkFile, type SdkLanguage, type SendCommandOptions, type SendNotificationOptions, type ServiceHealth, type ShadowDelta, type ShadowMetadata, type ShadowUpdate, type SignInWithEmailOptions, type SignInWithMagicLinkOptions, type SignInWithPhoneOptions, type SignUpWithEmailOptions, type SignatureAlgorithm, type SlidingWindowRateLimitOptions, type SmtpConfig, SmtpEmail, type SsoSession, type StartupResponse, StorageFile, type StoredAuditEvent, type StoredNotification, StripePayment, type StripePaymentConfig, type Subscription, type SubscriptionDiscount, type SubscriptionItem, type SubscriptionMetrics, type SubscriptionQuery, type SubscriptionStatus, SupabaseAuth, type SupabaseAuthConfig, SupabaseDatabase, SupabaseStorage, type SupabaseStorageConfig, type TaxBreakdown, type TelemetryMessage, type TelemetryQuery, type TelemetryResult, type Tenant, type TenantBranding, type TenantContext, type TenantDatabaseConfig, type TenantInvitation, type TenantIsolationModel, type TenantMember, type TenantMemberStatus, type TenantQuotas, type TenantResolutionOptions, type TenantResolutionStrategy, type TenantRole, type TenantSecuritySettings, type TenantSettings, type TenantStatus, type TenantUsage, TimeoutError, type TimeoutOptions, type TokenBucketOptions, type TosAcceptance, type Transfer, type TransferStatus, URL_DOMAIN_PATTERN, URL_PROTOCOL_PATTERN, type Unsubscribe, type UpdateCustomerOptions, type UpdateHookContext, type UpdatePasswordOptions, type UpdatePaymentIntentOptions, type UpdateScheduleOptions, type UpdateStatus, type UpdateTenantOptions, type UpdateUserOptions, type UpdateWebhookOptions, type UploadHookContext, UploadOptions, UpstashCache, type UsageAlert, type UsageCategory, type UsageEvent, type UsageInterval, type UsageInvoice, type UsageInvoiceItem, type UsageQuery, type UsageQueryResult, type UsageRecord, type UsageSummary, type UsageSummaryRecord, type UsageTrend, type VerificationResult, type VerifyMfaOptions, type VerifyPhoneOtpOptions, type VerifyWebhookOptions, WeaviateRAG, type WeaviateRAGConfig, type WebhookConfig, type WebhookDelivery, type WebhookEndpoint, type WebhookEvent, WebhookEventTypes, type WebhookQuery, type WebhookState, type WebhookStats, type WebhookTestEndpoint, type WebhookTestEvent, buildPagination, calculateRetryDelay, checkEnvVars, classifyError, closeSharedRedis, composeHookRegistries, constantTimeEqual, containsHtml, containsUrls, correlationContext, createAnthropicAdapter, createAppLogger, createAuthError, createBulkhead, createCacheMiddleware, createCachedFallback, createCircuitBreaker, createDefaultPreferences, createErrorReport, createExpressHealthHandlers, createExpressMetricsHandler, createGoogleAIAdapter, createHealthEndpoints, createHealthServer, createHookRegistry, createIpKeyGenerator, createJobContext, createLoggingMiddleware, createMetricsEndpoint, createMetricsMiddleware, createMetricsServer, createMiddlewareChain, createMiddlewareContext, createObservabilityServer, createOpenAIAdapter, createPaymentError, createPineconeRAG, createRateLimitMiddleware, createRedisClient, createRequestContext, createRequestIdMiddleware, createSlowQueryMiddleware, createTenantMiddleware, createTimeoutMiddleware, createUserKeyGenerator, createWeaviateRAG, defangUrl, describeCron, escapeHtml, filterChannelsByPreferences, formatAmount, generateAuditId, generateChecksum, generateDeliveryId, generateErrorId, generateEventId, generateFingerprint, generateNotificationId, generatePaymentId, generateScheduleId, generateSecureToken, generateWebhookId, generateWebhookSecret, getBoolEnv, getContext, getCorrelationId, getEnvSummary, getIntEnv, getLogMeta, getNextCronRun, getOptionalEnv, getRequestId, getRequiredEnv, getSharedRedis, getTenantId, getTraceId, getUserId, isApiError, isAuthError, isInContext, isInQuietHours, isPaymentError, isValidCron, matchAction, matchEventType, raceTimeout, retryable, runWithContext, runWithContextAsync, sanitizeApiError, sanitizeForEmail, stripHtml, timedHealthCheck, toHealthCheckResult, validateEnvVars, withCorrelation, withCorrelationAsync, withFallback, withFallbackChain, withFallbackResult, withRetry, withRetryResult, withTimeout, withTimeoutWrapper };