import * as v from 'valibot'; import * as react from 'react'; import { ComponentType, ReactNode, ReactElement } from 'react'; import { FieldValues } from 'react-hook-form'; import { TFunction, i18n, InitOptions } from 'i18next'; import { TransProps, useTranslation as useTranslation$1 } from 'react-i18next'; import * as zustand from 'zustand'; import { StoreApi, UseBoundStore } from 'zustand'; import { PersistOptions } from 'zustand/middleware'; import { MutationOptions, QueryClient, QueryClientProvider, QueryClientProviderProps, QueryFunction, QueryKey, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, useQueryClient } from '@tanstack/react-query'; export { MutationOptions, QueryClient, QueryClientProvider, QueryClientProviderProps, QueryFunction, QueryKey, UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, useQueryClient } from '@tanstack/react-query'; import * as react_jsx_runtime from 'react/jsx-runtime'; import { DISPLAY, BUTTON_VARIANT } from '@donotdev/components'; /** * @fileoverview AI Constants * @description Provider IDs, model lists, roles, defaults for AI feature. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** Supported AI providers */ declare const AI_PROVIDERS: { readonly ANTHROPIC: "anthropic"; readonly OPENAI: "openai"; readonly GOOGLE: "google"; }; /** Message roles */ declare const AI_ROLES: { readonly USER: "user"; readonly ASSISTANT: "assistant"; readonly SYSTEM: "system"; }; /** Default models per provider */ declare const AI_MODELS: { readonly anthropic: { readonly default: "claude-sonnet-4-6"; readonly models: readonly ["claude-sonnet-4-6", "claude-sonnet-4-20250514", "claude-haiku-4-5-20251001", "claude-opus-4-6", "claude-opus-4-20250514"]; }; readonly openai: { readonly default: "gpt-4o"; readonly models: readonly ["gpt-4o", "gpt-4o-mini", "gpt-4.1", "gpt-4.1-mini", "o3-mini"]; }; readonly google: { readonly default: "gemini-2.0-flash"; readonly models: readonly ["gemini-2.0-flash", "gemini-2.5-pro", "gemini-2.5-flash"]; }; }; /** Default AI configuration */ declare const DEFAULT_AI_CONFIG: { readonly maxTokens: 4096; readonly temperature: 0.7; readonly stream: true; }; /** AI error codes */ declare const AI_ERROR_CODES: { readonly UNKNOWN: "unknown"; readonly UNAUTHENTICATED: "unauthenticated"; readonly INVALID_API_KEY: "invalid_api_key"; readonly RATE_LIMIT_EXCEEDED: "rate_limit_exceeded"; readonly PROVIDER_ERROR: "provider_error"; readonly TOKEN_LIMIT_EXCEEDED: "token_limit_exceeded"; readonly STREAM_INTERRUPTED: "stream_interrupted"; }; /** AI model tiers - SSOT for tier-based model resolution */ declare const AI_TIERS: { readonly FAST: { readonly id: "fast"; readonly defaultModel: "claude-haiku-4-5-20251001"; }; readonly STANDARD: { readonly id: "standard"; readonly defaultModel: "claude-sonnet-4-6"; }; readonly PREMIUM: { readonly id: "premium"; readonly defaultModel: "claude-opus-4-6"; }; }; /** AI tier identifier derived from AI_TIERS constant. */ type AITierId = (typeof AI_TIERS)[keyof typeof AI_TIERS]['id']; /** Default markup multiplier (provider cost x 4 = billed cost) */ declare const DEFAULT_AI_MARKUP = 4; /** * Token pricing per model (USD per 1M tokens). * SSOT - imported by both client (cost display) and server (cost recording). */ declare const AI_TOKEN_PRICING: Record; /** * @fileoverview AI Schemas * @description Valibot schemas for AI request/response validation. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** Schema for a single AI message */ declare const AIMessageSchema: v.ObjectSchema<{ readonly role: v.PicklistSchema<["user", "assistant", "system"], undefined>; readonly content: v.SchemaWithPipe, v.MinLengthAction]>; readonly id: v.OptionalSchema, undefined>; readonly createdAt: v.OptionalSchema, undefined>; }, undefined>; /** Schema for an AI tool definition */ declare const AIToolDefinitionSchema: v.ObjectSchema<{ readonly description: v.SchemaWithPipe, v.MinLengthAction]>; readonly parameters: v.ObjectSchema<{ readonly type: v.LiteralSchema<"object", undefined>; readonly properties: v.RecordSchema, v.GenericSchema, undefined>; readonly required: v.OptionalSchema, undefined>, undefined>; }, undefined>; }, undefined>; /** Schema for a tool call result */ declare const AIToolCallSchema: v.ObjectSchema<{ readonly id: v.StringSchema; readonly name: v.StringSchema; readonly args: v.RecordSchema, v.UnknownSchema, undefined>; }, undefined>; /** Schema for AI chat request (client → server) */ declare const AIChatRequestSchema: v.ObjectSchema<{ readonly messages: v.SchemaWithPipe; readonly content: v.SchemaWithPipe, v.MinLengthAction]>; readonly id: v.OptionalSchema, undefined>; readonly createdAt: v.OptionalSchema, undefined>; }, undefined>, undefined>, v.MinLengthAction<{ role: "user" | "assistant" | "system"; content: string; id?: string | undefined; createdAt?: string | undefined; }[], 1, undefined>]>; readonly provider: v.OptionalSchema, undefined>; readonly model: v.OptionalSchema, undefined>; readonly maxTokens: v.OptionalSchema, v.IntegerAction, v.MinValueAction]>, undefined>; readonly temperature: v.OptionalSchema, v.MinValueAction, v.MaxValueAction]>, undefined>; readonly systemPrompt: v.OptionalSchema, undefined>; readonly stream: v.OptionalSchema, undefined>; readonly tools: v.OptionalSchema, v.ObjectSchema<{ readonly description: v.SchemaWithPipe, v.MinLengthAction]>; readonly parameters: v.ObjectSchema<{ readonly type: v.LiteralSchema<"object", undefined>; readonly properties: v.RecordSchema, v.GenericSchema, undefined>; readonly required: v.OptionalSchema, undefined>, undefined>; }, undefined>; }, undefined>, undefined>, undefined>; }, undefined>; /** Schema for AI token usage */ declare const AIUsageSchema: v.ObjectSchema<{ readonly promptTokens: v.NumberSchema; readonly completionTokens: v.NumberSchema; readonly totalTokens: v.NumberSchema; }, undefined>; /** Schema for AI chat response (server → client, non-streaming) */ declare const AIChatResponseSchema: v.ObjectSchema<{ readonly message: v.ObjectSchema<{ readonly role: v.PicklistSchema<["user", "assistant", "system"], undefined>; readonly content: v.SchemaWithPipe, v.MinLengthAction]>; readonly id: v.OptionalSchema, undefined>; readonly createdAt: v.OptionalSchema, undefined>; }, undefined>; readonly usage: v.OptionalSchema; readonly completionTokens: v.NumberSchema; readonly totalTokens: v.NumberSchema; }, undefined>, undefined>; readonly finishReason: v.OptionalSchema, undefined>; readonly toolCalls: v.OptionalSchema; readonly name: v.StringSchema; readonly args: v.RecordSchema, v.UnknownSchema, undefined>; }, undefined>, undefined>, undefined>; }, undefined>; /** Schema for AI provider configuration (consumer's _shared/aiConfig.ts) */ declare const AIProviderConfigSchema: v.ObjectSchema<{ readonly provider: v.PicklistSchema<["anthropic", "openai", "google"], undefined>; readonly model: v.OptionalSchema, undefined>; readonly maxTokens: v.OptionalSchema, v.IntegerAction, v.MinValueAction]>, undefined>; readonly temperature: v.OptionalSchema, v.MinValueAction, v.MaxValueAction]>, undefined>; readonly systemPrompt: v.OptionalSchema, undefined>; }, undefined>; /** A single message in an AI chat conversation. */ type AIMessage = v.InferOutput; /** Request payload for an AI chat completion. */ type AIChatRequest = v.InferOutput; /** Token usage statistics for an AI completion. */ type AIUsage = v.InferOutput; /** Response payload from an AI chat completion. */ type AIChatResponse = v.InferOutput; /** Configuration for an AI provider backend. */ type AIProviderConfig = v.InferOutput; declare function validateAIChatRequest(data: unknown): v.SafeParseResult; readonly content: v.SchemaWithPipe, v.MinLengthAction]>; readonly id: v.OptionalSchema, undefined>; readonly createdAt: v.OptionalSchema, undefined>; }, undefined>, undefined>, v.MinLengthAction<{ role: "user" | "assistant" | "system"; content: string; id?: string | undefined; createdAt?: string | undefined; }[], 1, undefined>]>; readonly provider: v.OptionalSchema, undefined>; readonly model: v.OptionalSchema, undefined>; readonly maxTokens: v.OptionalSchema, v.IntegerAction, v.MinValueAction]>, undefined>; readonly temperature: v.OptionalSchema, v.MinValueAction, v.MaxValueAction]>, undefined>; readonly systemPrompt: v.OptionalSchema, undefined>; readonly stream: v.OptionalSchema, undefined>; readonly tools: v.OptionalSchema, v.ObjectSchema<{ readonly description: v.SchemaWithPipe, v.MinLengthAction]>; readonly parameters: v.ObjectSchema<{ readonly type: v.LiteralSchema<"object", undefined>; readonly properties: v.RecordSchema, v.GenericSchema, undefined>; readonly required: v.OptionalSchema, undefined>, undefined>; }, undefined>; }, undefined>, undefined>, undefined>; }, undefined>>; declare function validateAIChatResponse(data: unknown): v.SafeParseResult; readonly content: v.SchemaWithPipe, v.MinLengthAction]>; readonly id: v.OptionalSchema, undefined>; readonly createdAt: v.OptionalSchema, undefined>; }, undefined>; readonly usage: v.OptionalSchema; readonly completionTokens: v.NumberSchema; readonly totalTokens: v.NumberSchema; }, undefined>, undefined>; readonly finishReason: v.OptionalSchema, undefined>; readonly toolCalls: v.OptionalSchema; readonly name: v.StringSchema; readonly args: v.RecordSchema, v.UnknownSchema, undefined>; }, undefined>, undefined>, undefined>; }, undefined>>; /** AI provider type */ type AIProvider = (typeof AI_PROVIDERS)[keyof typeof AI_PROVIDERS]; /** AI error code type (derived from AI_ERROR_CODES constant) */ type AIErrorCode = (typeof AI_ERROR_CODES)[keyof typeof AI_ERROR_CODES]; /** Configuration for AI feature (consumer-facing) */ interface AIConfig { provider: AIProvider; model?: string; maxTokens?: number; temperature?: number; systemPrompt?: string; } /** Per-model token pricing */ interface AIModelPricing { /** Cost per 1M input tokens in USD */ promptPer1M: number; /** Cost per 1M output tokens in USD */ completionPer1M: number; /** Currency code */ currency: 'usd'; } /** Cost calculation result */ interface AICostResult { /** Raw provider cost in USD (server-side only, never expose to end users) */ providerCost: number; /** Marked-up cost for consumer billing (what users owe) */ billedCost: number; /** Markup multiplier applied */ markup: number; /** Breakdown */ breakdown: { promptTokens: number; completionTokens: number; promptCost: number; completionCost: number; }; } /** Consumer-facing cost configuration */ interface AICostConfig { /** Markup multiplier for rebilling (provider cost x markup = billed cost) */ markup: number; /** Monthly token budget per user (0 = unlimited) */ monthlyBudgetTokens: number; /** Whether to show cost to end users (false = admin only) */ showCostToUsers: boolean; /** Currency for display */ displayCurrency: string; } /** Server-side cost record (written per AI request) */ interface AICostRecord { userId: string; model: string; provider: string; usage: AIUsage; providerCost: number; billedCost: number; markup: number; timestamp: string; requestId: string; } /** Real-time cost event for billing integration */ interface AICostEvent { type: 'cost_update'; requestId: string; cost: AICostResult; cumulative: AICostResult; } /** JSON Schema property definition for AI tool parameters */ interface AIToolParameter { /** JSON Schema type */ type: 'string' | 'number' | 'boolean' | 'array' | 'object'; /** Parameter description (sent to the model) */ description?: string; /** Enum constraint */ enum?: string[]; /** Array items schema */ items?: AIToolParameter; /** Object properties */ properties?: Record; /** Required property names (for object type) */ required?: string[]; } /** AI tool definition - JSON Schema based, provider-agnostic */ interface AIToolDefinition { /** Tool description (sent to the model) */ description: string; /** Tool parameters as JSON Schema object */ parameters: { type: 'object'; properties: Record; required?: string[]; }; } /** Result of a tool call made by the model */ interface AIToolCall { /** Tool call ID (from provider) */ id: string; /** Tool name */ name: string; /** Parsed arguments */ args: Record; } /** AI API surface - returned by useAIChat, degraded when @donotdev/ai not installed */ interface AIAPI { /** Conversation messages */ messages: AIMessage[]; /** Send a message */ append: (content: string) => void; /** Stop current stream */ stop: () => void; /** Whether a response is streaming */ isLoading: boolean; /** Current error */ error: Error | undefined; /** Clear conversation */ clearMessages: () => void; /** Whether AI is available (auth + consent) */ isAvailable: boolean; /** Current input value (controlled) */ input: string; /** Set input value */ setInput: (value: string) => void; /** Submit the current input */ handleSubmit: (e?: any) => void; /** Cost tracking (billed cost only - provider cost is server-side only) */ cost: { lastCost: AICostResult | null; sessionCost: AICostResult; formattedBilledCost: string; }; /** Tool calls from the latest assistant response */ toolCalls: AIToolCall[]; } /** Rate limit configuration for AI handler */ interface AIRateLimitConfig { /** Maximum requests per window */ maxRequests: number; /** Window duration in milliseconds */ windowMs: number; } /** AI route configuration (server-side) */ interface AIRouteConfig { /** AI provider */ provider: AIProvider; /** Model ID */ model?: string; /** Max output tokens */ maxTokens?: number; /** Temperature */ temperature?: number; /** System prompt */ systemPrompt?: string; /** Cost configuration */ cost?: AICostConfig; /** Rate limit configuration */ rateLimitConfig?: AIRateLimitConfig; /** Tool definitions available to the model */ tools?: Record; } /** * @fileoverview Partners Constants * @description Constants for partners domain. Defines partner icon mappings and partner-related constants. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Partner icon constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const PARTNER_ICONS: { readonly apple: "apple"; readonly discord: "discord"; readonly emailLink: "emailLink"; readonly facebook: "facebook"; readonly github: "github"; readonly google: "google"; readonly linkedin: "linkedin"; readonly microsoft: "microsoft"; readonly password: "password"; readonly reddit: "reddit"; readonly spotify: "spotify"; readonly twitch: "twitch"; readonly twitter: "twitter"; readonly yahoo: "yahoo"; readonly notion: "notion"; readonly slack: "slack"; readonly medium: "medium"; readonly mastodon: "mastodon"; readonly youtube: "youtube"; }; /** * Partner icon ID type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PartnerIconId = keyof typeof PARTNER_ICONS; /** * @fileoverview Schema Definition for All Authentication and OAuth Partners * @description Single source of truth for all auth and OAuth configurations. Defines Valibot schemas for partner configurations, authentication partners, and OAuth partners. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Partner type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PartnerType = 'auth' | 'oauth' | 'both'; declare const authPartnerSchema: v.ObjectSchema<{ readonly type: v.PicklistSchema<["auth", "both"], undefined>; readonly scopes: v.OptionalSchema, undefined>, undefined>; readonly firebaseProviderId: v.OptionalSchema, undefined>; readonly name: v.StringSchema; readonly color: v.StringSchema; readonly icon: v.StringSchema; readonly customParameters: v.OptionalSchema, v.StringSchema, undefined>, undefined>; readonly button: v.ObjectSchema<{ readonly backgroundColor: v.StringSchema; readonly textColor: v.StringSchema; readonly borderColor: v.StringSchema; readonly hoverBackgroundColor: v.StringSchema; readonly focusOutlineColor: v.StringSchema; readonly fontWeight: v.OptionalSchema, "500">; readonly textKey: v.OptionalSchema, undefined>; }, undefined>; }, undefined>; /** * Authentication partners configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const AUTH_PARTNERS: { readonly apple: { readonly name: "Apple"; readonly color: "#000000"; readonly icon: "apple"; readonly type: "both"; readonly scopes: readonly ["email", "name"]; readonly firebaseProviderId: "apple.com"; readonly customParameters: { readonly prompt: "login"; }; readonly button: { readonly backgroundColor: "#000000"; readonly textColor: "#ffffff"; readonly borderColor: "#000000"; readonly hoverBackgroundColor: "#1a1a1a"; readonly focusOutlineColor: "#333333"; readonly fontWeight: "500"; readonly textKey: "buttons.apple"; }; }; readonly discord: { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: readonly ["identify", "email"]; readonly firebaseProviderId: "discord.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.discord"; }; }; readonly emailLink: { readonly name: "Email Link"; readonly color: "#10B981"; readonly icon: "emailLink"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "emailLink"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#10B981"; readonly textColor: "#ffffff"; readonly borderColor: "#10B981"; readonly hoverBackgroundColor: "#059669"; readonly focusOutlineColor: "#059669"; readonly fontWeight: "500"; readonly textKey: "buttons.emailLink"; }; }; readonly facebook: { readonly name: "Facebook"; readonly color: "#1877F2"; readonly icon: "facebook"; readonly type: "both"; readonly scopes: readonly ["email", "public_profile"]; readonly firebaseProviderId: "facebook.com"; readonly customParameters: { readonly auth_type: "reauthenticate"; }; readonly button: { readonly backgroundColor: "#1877F2"; readonly textColor: "#ffffff"; readonly borderColor: "#1877F2"; readonly hoverBackgroundColor: "#166FE5"; readonly focusOutlineColor: "#166FE5"; readonly fontWeight: "600"; readonly textKey: "buttons.facebook"; }; }; readonly github: { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: readonly ["read:user", "user:email"]; readonly firebaseProviderId: "github.com"; readonly customParameters: { readonly allow_signup: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.github"; }; }; readonly google: { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: readonly ["email", "profile"]; readonly firebaseProviderId: "google.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.google"; }; }; readonly linkedin: { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "both"; readonly scopes: readonly ["r_liteprofile", "r_emailaddress"]; readonly firebaseProviderId: "linkedin.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.linkedin"; }; }; readonly microsoft: { readonly name: "Microsoft"; readonly color: "#00A4EF"; readonly icon: "microsoft"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "microsoft.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.microsoft"; }; }; readonly password: { readonly name: "Email & Password"; readonly color: "#6B7280"; readonly icon: "password"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "password"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#374151"; readonly borderColor: "#D1D5DB"; readonly hoverBackgroundColor: "#F9FAFB"; readonly focusOutlineColor: "#3B82F6"; readonly fontWeight: "500"; readonly textKey: "buttons.password"; }; }; readonly reddit: { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: readonly ["identity"]; readonly firebaseProviderId: "reddit.com"; readonly customParameters: { readonly duration: "permanent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.reddit"; }; }; readonly spotify: { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: readonly ["user-read-email", "user-read-private"]; readonly firebaseProviderId: "spotify.com"; readonly customParameters: { readonly show_dialog: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.spotify"; }; }; readonly twitch: { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: readonly ["user:read:email"]; readonly firebaseProviderId: "twitch.tv"; readonly customParameters: { readonly force_verify: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitch"; }; }; readonly twitter: { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "both"; readonly scopes: readonly []; readonly firebaseProviderId: "twitter.com"; readonly customParameters: { readonly force_login: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitter"; }; }; readonly yahoo: { readonly name: "Yahoo"; readonly color: "#5F01D1"; readonly icon: "yahoo"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "yahoo.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.yahoo"; }; }; }; /** * OAuth partners configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const OAUTH_PARTNERS: { readonly google: { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["openid", "profile", "email"]; readonly 'api-access': readonly ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/gmail.readonly"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/oauth2/v3/userinfo"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly github: { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["read:user", "user:email"]; readonly 'api-access': readonly ["repo", "user", "read:org", "gist", "notifications"]; }; readonly endpoints: { readonly authUrl: "https://github.com/login/oauth/authorize"; readonly tokenUrl: "https://github.com/login/oauth/access_token"; readonly profileUrl: "https://api.github.com/user"; readonly revokeUrl: "https://api.github.com/applications/CLIENT_ID/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly discord: { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identify", "email"]; readonly 'api-access': readonly ["guilds", "guilds.members.read", "bot", "messages.read"]; }; readonly endpoints: { readonly authUrl: "https://discord.com/api/oauth2/authorize"; readonly tokenUrl: "https://discord.com/api/oauth2/token"; readonly profileUrl: "https://discord.com/api/users/@me"; readonly revokeUrl: "https://discord.com/api/oauth2/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly spotify: { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user-read-email", "user-read-private"]; readonly 'api-access': readonly ["user-read-playback-state", "user-modify-playback-state", "user-read-currently-playing", "playlist-read-private", "playlist-modify-public", "user-library-read"]; }; readonly endpoints: { readonly authUrl: "https://accounts.spotify.com/authorize"; readonly tokenUrl: "https://accounts.spotify.com/api/token"; readonly profileUrl: "https://api.spotify.com/v1/me"; readonly revokeUrl: "https://accounts.spotify.com/api/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly twitch: { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user:read:email"]; readonly 'api-access': readonly ["channel:read:subscriptions", "bits:read", "channel:manage:broadcast", "channel:read:stream_key", "user:read:follows"]; }; readonly endpoints: { readonly authUrl: "https://id.twitch.tv/oauth2/authorize"; readonly tokenUrl: "https://id.twitch.tv/oauth2/token"; readonly profileUrl: "https://api.twitch.tv/helix/users"; readonly revokeUrl: "https://id.twitch.tv/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly reddit: { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identity"]; readonly 'api-access': readonly ["read", "submit", "vote", "mysubreddits", "subscribe"]; }; readonly endpoints: { readonly authUrl: "https://www.reddit.com/api/v1/authorize"; readonly tokenUrl: "https://www.reddit.com/api/v1/access_token"; readonly profileUrl: "https://oauth.reddit.com/api/v1/me"; readonly revokeUrl: "https://www.reddit.com/api/v1/revoke_token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly linkedin: { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["r_liteprofile", "r_emailaddress", "w_member_social", "r_organization_social"]; }; readonly endpoints: { readonly authUrl: "https://www.linkedin.com/oauth/v2/authorization"; readonly tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken"; readonly profileUrl: "https://api.linkedin.com/v2/me"; readonly revokeUrl: "https://www.linkedin.com/oauth/v2/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly slack: { readonly name: "Slack"; readonly color: "#E01E5A"; readonly icon: "slack"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["channels:read", "chat:write", "users:read", "files:read", "im:read"]; }; readonly endpoints: { readonly authUrl: "https://slack.com/oauth/v2/authorize"; readonly tokenUrl: "https://slack.com/api/oauth.v2.access"; readonly profileUrl: "https://slack.com/api/users.identity"; readonly revokeUrl: "https://slack.com/api/auth.revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly notion: { readonly name: "Notion"; readonly color: "#000000"; readonly icon: "notion"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write"]; }; readonly endpoints: { readonly authUrl: "https://api.notion.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.notion.com/v1/oauth/token"; readonly profileUrl: "https://api.notion.com/v1/users/me"; readonly revokeUrl: "https://api.notion.com/v1/oauth/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly medium: { readonly name: "Medium"; readonly color: "#000000"; readonly icon: "medium"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["basicProfile", "publishPost", "listPublications"]; }; readonly endpoints: { readonly authUrl: "https://medium.com/m/oauth/authorize"; readonly tokenUrl: "https://medium.com/v1/tokens"; readonly profileUrl: "https://medium.com/v1/me"; readonly revokeUrl: "https://medium.com/v1/tokens/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly twitter: { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["tweet.read", "users.read", "follows.read", "tweet.write", "like.write"]; }; readonly endpoints: { readonly authUrl: "https://twitter.com/i/oauth2/authorize"; readonly tokenUrl: "https://api.twitter.com/2/oauth2/token"; readonly profileUrl: "https://api.twitter.com/2/users/me"; readonly revokeUrl: "https://api.twitter.com/2/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly mastodon: { readonly name: "Mastodon"; readonly color: "#6364FF"; readonly icon: "mastodon"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write", "follow", "push"]; }; readonly endpoints: { readonly authUrl: ""; readonly tokenUrl: ""; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly youtube: { readonly name: "YouTube"; readonly color: "#FF0000"; readonly icon: "youtube"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["https://www.googleapis.com/auth/youtube.readonly", "https://www.googleapis.com/auth/youtube.upload", "https://www.googleapis.com/auth/youtube.force-ssl"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/youtube/v3/channels"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; readonly supabase: { readonly name: "Supabase"; readonly color: "#3ECF8E"; readonly icon: "supabase"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["auth:read", "auth:write", "database:read", "database:write", "domains:read", "domains:write", "edge_functions:read", "edge_functions:write", "environment:read", "environment:write", "organizations:read", "projects:read", "projects:write", "rest:read", "rest:write", "secrets:read", "secrets:write", "storage:read"]; }; readonly endpoints: { readonly authUrl: "https://api.supabase.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.supabase.com/v1/oauth/token"; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#F1F3F5"; readonly textColor: "#11181C"; readonly borderColor: "#E6E8EB"; readonly hoverBackgroundColor: "#E6E8EB"; readonly focusOutlineColor: "#3ECF8E"; readonly fontWeight: "500"; }; }; readonly vercel: { readonly name: "Vercel"; readonly color: "#000000"; readonly icon: "vercel"; readonly type: "oauth"; readonly scopes: { readonly authentication: readonly ["openid", "email", "profile", "offline_access"]; readonly 'api-access': readonly ["project", "project-env-vars", "deployment", "team", "user"]; }; readonly endpoints: { readonly authUrl: "https://vercel.com/oauth/authorize"; readonly tokenUrl: "https://api.vercel.com/login/oauth/token"; readonly profileUrl: "https://api.vercel.com/login/oauth/userinfo"; readonly revokeUrl: "https://api.vercel.com/login/oauth/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; }; }; /** * Validates authentication partners configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateAuthPartners(): v.SafeParseResult, v.ObjectSchema<{ readonly type: v.PicklistSchema<["auth", "both"], undefined>; readonly scopes: v.OptionalSchema, undefined>, undefined>; readonly firebaseProviderId: v.OptionalSchema, undefined>; readonly name: v.StringSchema; readonly color: v.StringSchema; readonly icon: v.StringSchema; readonly customParameters: v.OptionalSchema, v.StringSchema, undefined>, undefined>; readonly button: v.ObjectSchema<{ readonly backgroundColor: v.StringSchema; readonly textColor: v.StringSchema; readonly borderColor: v.StringSchema; readonly hoverBackgroundColor: v.StringSchema; readonly focusOutlineColor: v.StringSchema; readonly fontWeight: v.OptionalSchema, "500">; readonly textKey: v.OptionalSchema, undefined>; }, undefined>; }, undefined>, undefined>>; /** * Validates OAuth partners configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateOAuthPartners(): v.SafeParseResult, v.ObjectSchema<{ readonly type: v.PicklistSchema<["oauth", "both"], undefined>; readonly scopes: v.ObjectSchema<{ readonly authentication: v.OptionalSchema, undefined>, undefined>; readonly 'api-access': v.ArraySchema, undefined>; }, undefined>; readonly endpoints: v.ObjectSchema<{ readonly authUrl: v.UnionSchema<[v.LiteralSchema<"", undefined>, v.SchemaWithPipe, v.UrlAction]>], undefined>; readonly tokenUrl: v.UnionSchema<[v.LiteralSchema<"", undefined>, v.SchemaWithPipe, v.UrlAction]>], undefined>; readonly profileUrl: v.UnionSchema<[v.LiteralSchema<"", undefined>, v.SchemaWithPipe, v.UrlAction]>], undefined>; readonly revokeUrl: v.OptionalSchema, v.SchemaWithPipe, v.UrlAction]>], undefined>, undefined>; }, undefined>; readonly capabilities: v.OptionalSchema, false>; readonly codeChallengeMethod: v.OptionalSchema, "S256">; }, undefined>, undefined>; readonly name: v.StringSchema; readonly color: v.StringSchema; readonly icon: v.StringSchema; readonly customParameters: v.OptionalSchema, v.StringSchema, undefined>, undefined>; readonly button: v.ObjectSchema<{ readonly backgroundColor: v.StringSchema; readonly textColor: v.StringSchema; readonly borderColor: v.StringSchema; readonly hoverBackgroundColor: v.StringSchema; readonly focusOutlineColor: v.StringSchema; readonly fontWeight: v.OptionalSchema, "500">; readonly textKey: v.OptionalSchema, undefined>; }, undefined>; }, undefined>, undefined>>; /** * Authentication partner ID type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthPartnerId = keyof typeof AUTH_PARTNERS; /** * OAuth partner ID type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthPartnerId = keyof typeof OAUTH_PARTNERS; /** * Partner ID type (auth or OAuth) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PartnerId = AuthPartnerId | OAuthPartnerId; /** * Authentication partner type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthPartner = v.InferOutput; /** * OAuth partner type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthPartner = (typeof OAUTH_PARTNERS)[OAuthPartnerId]; /** * Checks if a partner ID is an authentication partner * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isAuthPartnerId(id: PartnerId): id is AuthPartnerId; /** * Checks if a partner ID is an OAuth partner * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isOAuthPartnerId(id: PartnerId): id is OAuthPartnerId; /** * @fileoverview Types for Authentication Partners * @description Extends existing auth types with partner-based authentication. Defines partner result types, connection states, partner buttons, and partner-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Shared primitives for auth and oauth partner flows * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PartnerResult { success: boolean; error?: string; userInfo?: { id: string; name?: string; username?: string; email?: string; photoURL?: string; }; } /** * Partner connection state interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PartnerConnectionState { isConnecting: boolean; isConnected: boolean; error: Error | null; } /** * @fileoverview Authentication Constants * @description Constants for authentication domain. Defines token status types, user roles, subscription tiers, features, permissions, and authentication-related constants. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Token status possible values * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type TokenStatus = 'valid' | 'expiring-soon' | 'expired' | 'error' | 'not-initialized'; /** * Authentication status type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthStatus = 'authenticated' | 'unauthenticated' | 'loading'; /** * Standard user role names * Apps can override these by providing their own role constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const USER_ROLES: { readonly GUEST: "guest"; readonly USER: "user"; readonly ADMIN: "admin"; readonly SUPER: "super"; }; /** * Override user roles for custom app needs * @example * ```typescript * // In your app's config * overrideUserRoles({ * GUEST: 'visitor', * USER: 'member', * ADMIN: 'moderator' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overrideUserRoles(customRoles: Partial): void; /** * Type for user role names * Apps can extend this with their own custom roles * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES] | string; /** * Standard subscription tier names * Apps can override these by providing their own tier constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const SUBSCRIPTION_TIERS: { readonly FREE: "free"; readonly PRO: "pro"; readonly PREMIUM: "premium"; }; /** * Override subscription tiers for custom app needs * @example * ```typescript * // In your app's config * overrideSubscriptionTiers({ * FREE: 'basic', * PRO: 'professional', * PREMIUM: 'enterprise' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overrideSubscriptionTiers(customTiers: Partial): void; /** * Type for subscription tier names * Apps can extend this with their own custom tiers * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type SubscriptionTier = (typeof SUBSCRIPTION_TIERS)[keyof typeof SUBSCRIPTION_TIERS] | string; /** * Standard feature names * Apps can override these by providing their own feature constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const FEATURES: { readonly BASIC_ACCESS: "basic_access"; readonly ADVANCED_FEATURES: "advanced_features"; readonly API_ACCESS: "api_access"; readonly PRIORITY_SUPPORT: "priority_support"; }; /** * Override features for custom app needs * @example * ```typescript * // In your app's config * overrideFeatures({ * BASIC_ACCESS: 'read_access', * ADVANCED_FEATURES: 'write_access', * API_ACCESS: 'api_calls', * PRIORITY_SUPPORT: 'dedicated_support' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overrideFeatures(customFeatures: Partial): void; /** * Type for feature names * Apps can extend this with their own custom features * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeatureId = (typeof FEATURES)[keyof typeof FEATURES] | string; /** * Standard permission names * Apps can override these by providing their own permission constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const PERMISSIONS: { readonly READ_PUBLIC: "read_public"; readonly READ_OWN_DATA: "read_own_data"; readonly WRITE_OWN_DATA: "write_own_data"; readonly READ_ALL_DATA: "read_all_data"; readonly MANAGE_USERS: "manage_users"; }; /** * Override permissions for custom app needs * @example * ```typescript * // In your app's config * overridePermissions({ * READ_PUBLIC: 'view_public', * READ_OWN_DATA: 'view_profile', * WRITE_OWN_DATA: 'edit_profile', * READ_ALL_DATA: 'view_all', * MANAGE_USERS: 'admin_users' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overridePermissions(customPermissions: Partial): void; /** * Type for permission names * Apps can extend this with their own custom permissions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Permission = (typeof PERMISSIONS)[keyof typeof PERMISSIONS] | string; /** * A map containing instances of authentication providers. * Uses schema discovery to support all AUTH_PARTNERS automatically. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ProviderInstances = Record; /** * @fileoverview Schema Definitions for Authentication and User Management * @description Single source of truth for all auth-related data validation. Defines validation schemas for authentication, user management, and related data structures. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Schema for authenticated user data * Uses constants for enum values to ensure consistency * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const AuthUserSchema: v.ObjectSchema<{ readonly id: v.StringSchema; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly emailVerified: v.OptionalSchema, undefined>; readonly lastLoginAt: v.OptionalSchema, undefined>; readonly providerData: v.OptionalSchema; readonly uid: v.StringSchema; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly phoneNumber: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>, undefined>; readonly role: v.OptionalSchema, undefined>; readonly customClaims: v.OptionalSchema, v.AnySchema, undefined>, undefined>; }, undefined>; /** * Schema for user subscription data * Uses constants for enum values to ensure consistency * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const UserSubscriptionSchema: v.ObjectSchema<{ readonly userId: v.StringSchema; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>; /** * Schema for Firebase Auth custom claims * Uses constants for enum values to ensure consistency * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CustomClaimsSchema: v.ObjectSchema<{ readonly role: v.OptionalSchema, undefined>; readonly subscription: v.OptionalSchema; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly permissions: v.OptionalSchema, undefined>, undefined>; readonly githubAccess: v.OptionalSchema, undefined>; readonly teamAccess: v.OptionalSchema, undefined>, undefined>; readonly repoAccess: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>; }, undefined>; /** * Type for authenticated user data * Automatically derived from schema * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthUser = v.InferOutput; /** * Type for user subscription data * Automatically derived from schema * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type UserSubscription = v.InferOutput; /** * Type for Firebase Auth custom claims * Automatically derived from schema * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CustomClaims = v.InferOutput; /** * Validate auth user data * @param data - Data to validate * @returns Validation result with success/error information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateAuthUser(data: unknown): v.SafeParseResult; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly emailVerified: v.OptionalSchema, undefined>; readonly lastLoginAt: v.OptionalSchema, undefined>; readonly providerData: v.OptionalSchema; readonly uid: v.StringSchema; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly phoneNumber: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>, undefined>; readonly role: v.OptionalSchema, undefined>; readonly customClaims: v.OptionalSchema, v.AnySchema, undefined>, undefined>; }, undefined>>; /** * Validate user subscription data * @param data - Data to validate * @returns Validation result with success/error information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateUserSubscription(data: unknown): v.SafeParseResult; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>>; /** * Validate custom claims data * @param data - Data to validate * @returns Validation result with success/error information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCustomClaims(data: unknown): v.SafeParseResult, undefined>; readonly subscription: v.OptionalSchema; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly permissions: v.OptionalSchema, undefined>, undefined>; readonly githubAccess: v.OptionalSchema, undefined>; readonly teamAccess: v.OptionalSchema, undefined>, undefined>; readonly repoAccess: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>; }, undefined>>; /** * Validate that all schemas are properly configured * Only runs when explicitly called during development * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateAuthSchemas(): { success: boolean; results: { authUser: v.SafeParseResult; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly emailVerified: v.OptionalSchema, undefined>; readonly lastLoginAt: v.OptionalSchema, undefined>; readonly providerData: v.OptionalSchema; readonly uid: v.StringSchema; readonly email: v.OptionalSchema, v.EmailAction]>, undefined>, undefined>; readonly displayName: v.OptionalSchema, undefined>, undefined>; readonly photoURL: v.OptionalSchema, v.UrlAction]>, undefined>, undefined>; readonly phoneNumber: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>, undefined>; readonly role: v.OptionalSchema, undefined>; readonly customClaims: v.OptionalSchema, v.AnySchema, undefined>, undefined>; }, undefined>>; userSubscription: v.SafeParseResult; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>>; customClaims: v.SafeParseResult, undefined>; readonly subscription: v.OptionalSchema; readonly tier: v.PicklistSchema<[string, ...string[]], undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly isActive: v.OptionalSchema, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly subscriptionId: v.NullableSchema, undefined>; readonly customerId: v.StringSchema; readonly subscriptionEnd: v.NullableSchema, v.IsoTimestampAction]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema; readonly updatedAt: v.SchemaWithPipe, v.IsoTimestampAction]>; }, undefined>, undefined>; readonly features: v.OptionalSchema, undefined>, undefined>; readonly permissions: v.OptionalSchema, undefined>, undefined>; readonly githubAccess: v.OptionalSchema, undefined>; readonly teamAccess: v.OptionalSchema, undefined>, undefined>; readonly repoAccess: v.OptionalSchema, undefined>, undefined>; }, undefined>, undefined>; }, undefined>>; getUserAuthStatus: v.SafeParseResult, v.MinLengthAction]>; }, undefined>>; getCustomClaims: v.SafeParseResult, v.MinLengthAction]>; readonly claimKeys: v.OptionalSchema, undefined>, undefined>; }, undefined>>; setCustomClaims: v.SafeParseResult, v.MinLengthAction]>; readonly claims: v.RecordSchema, v.AnySchema, undefined>; readonly merge: v.OptionalSchema, false>; }, undefined>>; removeCustomClaims: v.SafeParseResult, v.MinLengthAction]>; readonly claimKeys: v.SchemaWithPipe, undefined>, v.MinLengthAction]>; }, undefined>>; }; }; /** * @fileoverview Server Auth Adapter Interface * @description Provider-agnostic interface for server-side authentication. * Token verification, user lookup, and custom claims management. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** Result of token verification */ interface VerifiedToken { /** The user's unique identifier */ uid: string; /** Optional: email from the token */ email?: string; /** Optional: additional claims embedded in the token */ claims?: Record; } /** Server-side user record (minimal) */ interface ServerUserRecord { uid: string; email?: string; displayName?: string; customClaims?: Record; } /** * Provider-agnostic server-side auth adapter. * * Implementations: * - `FirebaseServerAuthAdapter` (Firebase Admin SDK) * - Future: Supabase server auth, Auth.js, custom JWT adapters * * @version 0.1.0 * @since 0.5.0 */ interface IServerAuthAdapter { /** Verify an auth token and return the decoded user info. Throws on invalid token. */ verifyToken(token: string): Promise; /** Get a user record by UID. Returns null if not found. */ getUser(uid: string): Promise; /** Set custom claims on a user (merge semantics — existing claims are preserved unless overwritten). */ setCustomClaims(uid: string, claims: Record): Promise; } /** * @fileoverview Layout Constants * @description Shared constants and derived types used by both layoutTypes and presetConfig. * Extracted to break circular dependency. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Default layout preset - single source of truth * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const DEFAULT_LAYOUT_PRESET: "landing"; /** * Footer mode constants - DRY single source of truth * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const FOOTER_MODE: { readonly FIXED: "fixed"; readonly SCROLL: "scroll"; }; /** * Footer mode type - auto-derived from constants */ type FooterMode = (typeof FOOTER_MODE)[keyof typeof FOOTER_MODE]; /** * Layout preset constants - DRY single source of truth * Use these instead of hardcoded strings throughout the codebase * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const LAYOUT_PRESET: { readonly ADMIN: "admin"; readonly BLOG: "blog"; readonly DOCS: "docs"; readonly GAME: "game"; readonly LANDING: "landing"; readonly MOOLTI: "moolti"; readonly PLAIN: "plain"; }; /** * Layout preset type - auto-derived from constants, with string fallback * Accepts known presets OR any string (runtime validates and defaults to 'landing') * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type LayoutPreset = (typeof LAYOUT_PRESET)[keyof typeof LAYOUT_PRESET] | string; /** * @fileoverview Preset Configuration Types * @description Config-based preset system types. Presets are configuration objects * that declare what components go in which slots, replacing the component-based approach. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Slot content function - returns ReactNode or null * * Presets use functions that return ReactNode, same API as consumers. * Return null to explicitly hide the slot. */ type SlotContent = () => ReactNode | null; /** * Header zone configuration * * Grid-based layout with start/center/end areas. * - start: start-aligned (typically branding: AppIcon, AppTitle) * - center: absolutely centered (overlay, regardless of start/end content) * - end: end-aligned (typically actions: GoTo, Auth, Language, Theme) */ interface HeaderZoneConfig { /** Start slot - start-aligned, typically branding (AppIcon, AppTitle) */ start?: SlotContent; /** Center slot - absolutely centered overlay, optional (navigation, search) */ center?: SlotContent; /** End slot - end-aligned, typically actions (GoTo, Auth, Language, Theme) */ end?: SlotContent; } /** * Sidebar zone configuration * * Vertical layout with top/content/bottom areas. * All sidebars use ResizableSidebar wrapper. */ interface SidebarZoneConfig { /** Top slot - branding, search */ top?: SlotContent; /** Content slot - main scrollable area (defaults to NavigationMenu) */ content?: SlotContent; /** Bottom slot - user profile, settings */ bottom?: SlotContent; /** Default sidebar width in pixels */ defaultWidth?: number; /** Minimum width when resizing */ minWidth?: number; /** Maximum width when resizing */ maxWidth?: number; } /** * Footer zone configuration * * Simple footer: Copyright (left) | LegalLinks + DoNotDev (right) * - `null`: Hide footer * - `undefined`: Use defaults (copyright + legal links + DoNotDev) * - `{ copyright?: ..., legalLinks?: ... }`: Custom configuration */ interface FooterConfig { /** Copyright configuration * - `null`: Hide copyright * - `undefined`: Use default (© YEAR appName. All rights reserved) * - `string`: Custom copyright text */ copyright?: null | string; /** Legal links configuration * - `null`: Hide legal links * - `Array<{ path, label }>`: Custom legal links * - `undefined`: Use framework defaults */ legalLinks?: null | Array<{ path: string; label: string; }>; } /** * Footer zone configuration * * - `FooterConfig` object: configure DnDevFooter (copyright, legal links) * - `SlotContent` function: replace DnDevFooter with custom component * - `null`: hide footer * - `undefined`: use defaults */ type FooterZoneConfig = FooterConfig | SlotContent | null; /** * MergedBar configuration for mobile * * Fixed trigger bar that opens a Sheet with navigation content. * Each slot is customizable per-preset, with smart defaults. */ interface MergedBarConfig { /** Position of the trigger bar */ position: 'top' | 'bottom'; /** Height of the trigger bar (default: 64px for top, 48px for bottom) */ height?: string; /** Trigger bar content (default: header.start for top, footer-like for bottom) */ trigger?: SlotContent; /** Sheet top slot */ top?: SlotContent; /** Sheet content slot - scrollable (default: sidebar.content) */ content?: SlotContent; /** Sheet bottom slot (default: sidebar.bottom) */ bottom?: SlotContent; } /** * Mobile behavior configuration * * Defines how the layout adapts on mobile/tablet breakpoints. */ interface MobileBehaviorConfig { /** Breakpoint at which mobile behavior activates (default: 1024px) */ breakpoint?: number; /** Header slot overrides for mobile (overrides desktop header slots) */ header?: HeaderZoneConfig; /** Sidebar slot overrides for mobile (overrides desktop sidebar slots) */ sidebar?: SidebarZoneConfig; /** MergedBar configuration - replaces header/footer with sheet trigger */ mergedBar?: MergedBarConfig; } /** * Complete preset configuration * * Declarative configuration for a layout preset. * Uses function-based slots, same API as consumers. * * @example * ```typescript * const landingPreset: PresetConfig = { * name: 'landing', * header: { * start: () => , * center: () => null, * end: () => ( * <> * * * * ), * }, * mobile: { * header: { * end: () => {desktop end content}, * }, * }, * }; * ``` */ interface PresetConfig { /** Preset identifier (must match LayoutPreset type) */ name: LayoutPreset; /** Header zone configuration (undefined = use defaults, object = override slots, function = custom mode) */ header?: HeaderZoneConfig | SlotContent; /** Sidebar zone configuration (undefined = use defaults, object = override slots, function = custom mode) */ sidebar?: SidebarZoneConfig | SlotContent; /** Footer zone configuration (undefined = use defaults, object = override) */ footer?: FooterZoneConfig; /** Footer scroll behavior override for this preset */ footerMode?: FooterMode; /** Mobile behavior configuration */ mobile?: MobileBehaviorConfig; } /** * Preset registry type * * Maps preset names to their configurations. */ type PresetRegistry = Record; /** * @fileoverview Layout Types * @description Type definitions for layout system. Defines layout presets, layout configuration, zone configuration, and layout-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Layout preset string literals * * Each preset provides a different layout configuration optimized for specific use cases: * - 'landing': Marketing site with header and footer (default) * - 'admin': Admin panel with header, sidebar, and footer * - 'docs': Documentation with header, sidebar, and footer * - 'blog': Blog with header, sidebar, and footer * - 'moolti': SaaS app with sidebar only * - 'game': Mobile gaming with fixed header/footer (64px/24px) * - 'plain': Minimal layout with no UI chrome */ /** * Layout slot configuration for customizing layout zones * * Provides a clean, typed interface for customizing different areas of the layout * without prop drilling. Each preset uses only the slots it supports. * * Slots are functions that return ReactNode - this ensures hooks run after * providers are ready, preventing timing issues with feature-gated components. * Functions are called when the framework renders, ensuring all providers * and stores are initialized before component hooks execute. * * @example * ```typescript * const layout: LayoutConfig = { * header: { * start: () => , * end: () => * }, * footer: () => * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Layout override function - lazy component renderer * * Consumers use this to override layout zones/slots. * Function ensures components load lazily, not in provider tree. * Return `null` to explicitly hide the slot. */ type DnDevOverride = () => ReactNode | null; /** * Main content wrapper component * * Wraps the page content (`children` / ``) inside `
`. * Use to add custom chrome around page content without modifying the framework layout: * split panes, floating panels, contextual sidebars, terminal docking, etc. * * Receives page content as `children`. Breadcrumbs, debug tools, and footer * remain outside the wrapper (framework-managed). * * Works identically with Vite (``) and Next.js (`{children}`). * * @example * ```tsx * // Vite — split pane with terminal * ( * }> * {children} * * ), * }} * /> * * // Next.js — admin panel with contextual sidebar * ( * }>{children} * ), * }} * /> * ``` */ type DnDevWrapper = (props: { children: ReactNode; }) => ReactNode | null; /** * Layout configuration - simple API for consumers * * @example * ```typescript * layout={{ * preset: 'admin', * header: { end: () => } * }} * ``` */ interface LayoutConfig { /** Breadcrumbs display behavior */ breadcrumbs?: 'smart' | 'always' | 'never'; /** * Footer scroll behavior * - 'fixed': Footer stays at viewport bottom (default on desktop) * - 'scroll': Footer scrolls with content (default on mobile, optional on desktop) */ footerMode?: FooterMode; /** Header override - full component or slot overrides */ header?: DnDevOverride | { start?: DnDevOverride; center?: DnDevOverride; end?: DnDevOverride; }; /** Footer override - full component only */ footer?: DnDevOverride; /** Sidebar override - full component or slot overrides */ sidebar?: DnDevOverride | { top?: DnDevOverride; content?: DnDevOverride; bottom?: DnDevOverride; }; /** MergedBar override - full component or slot overrides */ mergedbar?: DnDevOverride | { trigger?: DnDevOverride; top?: DnDevOverride; content?: DnDevOverride; bottom?: DnDevOverride; }; /** * Main content wrapper — wraps page content inside `
` * * Add custom chrome around page content (split panes, floating panels, * terminal docking) without modifying the framework layout. * Breadcrumbs, debug tools, and footer remain outside the wrapper. * * Works with both Vite and Next.js routing. * * @example * ```tsx * layout={{ * wrapper: ({ children }) => ( * }>{children} * ), * }} * ``` */ wrapper?: DnDevWrapper; /** Mobile-specific overrides */ mobile?: { /** Mobile header slot overrides (overrides desktop header on mobile) */ header?: { start?: DnDevOverride; center?: DnDevOverride; end?: DnDevOverride; }; /** Mobile sidebar slot overrides (overrides desktop sidebar on mobile) */ sidebar?: { top?: DnDevOverride; content?: DnDevOverride; bottom?: DnDevOverride; }; }; } /** * App metadata and branding configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AppMetadata { /** Application name */ name?: string; /** Short application name for mobile/compact displays (defaults to name if not set) */ shortName?: string; /** Application description */ description?: string; /** Social and external links */ links?: { /** GitHub repository URL */ github?: string; /** Twitter/X profile URL */ twitter?: string; /** LinkedIn profile URL */ linkedin?: string; /** Support/contact URL */ support?: string; /** Documentation URL */ docs?: string; /** Blog URL */ blog?: string; }; /** Footer configuration * - `null`: Explicitly hide footer * - `undefined`: Use framework default footer * - `{ copyright?: ..., legalLinks?: ... }`: Custom footer configuration */ footer?: { /** Copyright configuration * - `null`: Hide copyright * - `undefined`: Use default (© YEAR appName. All rights reserved) * - `string`: Custom copyright text */ copyright?: null | string; /** Legal links configuration * - `null`: Hide legal links * - `Array<{ path, label }>`: Custom legal links (labels can be i18n keys via maybeTranslate) * - `undefined`: Use framework defaults (Privacy Policy, Terms of Service with i18n labels) */ legalLinks?: null | Array<{ path: string; label: string; }>; } | null; /** Additional application metadata */ metadata?: Record; } /** * Authentication route configuration * * Configure redirect routes for authentication and authorization failures. * Also configures AuthHeader UI behavior (login page, user menu, etc.). * All routes are optional with security-first defaults. * * @example * ```typescript * const authConfig: AuthConfig = { * authRoute: '/signin', * roleRoute: '/403', * tierRoute: '/pricing', * loginPath: '/login', // Optional: links to login page (undefined = show providers in header) * profilePath: '/account', * authMenuPaths: ['/dashboard', '/settings'] * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthConfig { /** Route to redirect when authentication required (default: '/') */ authRoute?: string; /** Route to redirect when role insufficient (default: '/404') */ roleRoute: string; /** Route to redirect when tier insufficient (default: '/404') */ tierRoute: string; /** Optional: Path to login page. If provided, AuthHeader links to login page. If undefined (default), shows providers in header */ loginPath?: string; /** Optional: Path to password reset callback page (default: '/auth/reset-password'). Framework auto-handles the route. */ resetPasswordPath?: string; /** Optional: Path to profile page (default: '/profile') */ profilePath?: string; /** * Optional: Custom menu items for authenticated user menu dropdown. * Supports route-based items with paths (auto-creates Link). * Icons are auto-resolved from route discovery (PageMeta.icon) if not provided. * For items with onClick handlers, use AuthMenu customItems prop instead. * * @example * ```typescript * authMenuItems: [ * { path: '/dashboard' }, // icon auto-resolved from route * { path: '/settings', label: 'Settings' }, // override label, icon from route * { path: '/billing', icon: 'CreditCard' } // override icon * ] * ``` */ authMenuItems?: Array<{ /** Route path (creates Link automatically) */ path: string; /** Optional label (falls back to navigation item label or path segment) */ label?: string; /** Optional Lucide icon name (string) - overrides route discovery icon */ icon?: string; }>; /** * Optional function to handle custom data deletion before account removal * Framework will try/catch this - failures won't block account deletion * * @example * ```typescript * deleteUserFunction: async (userId: string) => { * // Cancel Stripe subscriptions * await fetch('/api/billing/cancel', { method: 'POST' }); * * // Delete Firestore user data * await deleteDoc(doc(db, 'users', userId)); * * // Custom cleanup * await myCustomCleanup(userId); * } * ``` */ deleteUserFunction?: (userId: string) => Promise; } /** * SEO configuration * * Configure automatic SEO meta tags and social sharing. * * @example * ```typescript * const seoConfig: SEOConfig = { * baseUrl: 'https://example.com', * defaultImage: '/og-image.png', * twitterHandle: 'mycompany' * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SEOConfig { /** Enable automatic SEO (default: true) */ enabled?: boolean; /** Base URL for SEO files (robots.txt, sitemap.xml) - reads from VITE_APP_URL/NEXT_PUBLIC_APP_URL env var */ baseUrl?: string; /** Site name for SEO - defaults to APP_NAME from app.ts */ siteName?: string; /** Crawl delay for robots.txt (default: 1) */ crawlDelay?: number; /** Generate robots.txt (default: true) */ generateRobotsTxt?: boolean; /** Generate sitemap.xml (default: true) */ generateSitemap?: boolean; /** Default namespace for i18n translations (default: 'home') */ defaultNamespace?: string; /** Default image for social sharing */ defaultImage?: string; /** Twitter handle (without @) */ twitterHandle?: string; /** Additional static meta tags */ staticTags?: Record; /** URL redirect rules - generates platform-specific 301/302 redirects at build time */ redirects?: Array<{ /** Source path (supports :param syntax, e.g. '/old-blog/:slug') */ from: string; /** Destination path (supports :param syntax, e.g. '/blog/:slug') */ to: string; /** true = 301 permanent (default), false = 302 temporary */ permanent?: boolean; }>; /** * AI crawler management in robots.txt (default: 'recommended') * - 'recommended': Block training bots (GPTBot, Google-Extended, CCBot, ClaudeBot), * allow search/retrieval bots (OAI-SearchBot, ChatGPT-User, Claude-SearchBot, etc.) * - 'block-all': Block all AI bots * - 'allow-all': Allow all AI bots * - false: No AI crawler directives */ aiCrawlers?: 'recommended' | 'block-all' | 'allow-all' | false; /** Generate llms.txt per llmstxt.org spec (default: true). Set to false to disable. */ llmsTxt?: boolean; /** Inject Speculation Rules API for prefetch/prerender of internal links (default: true). Set to false to disable. */ speculationRules?: boolean; /** Emit hreflang alternate links when i18n has 2+ languages (default: true). No-op for monolingual apps. Set to false to disable. */ hreflang?: boolean; /** Auto-generate BreadcrumbList JSON-LD from URL path segments (default: true). Set to false to disable. */ breadcrumbSchema?: boolean; /** Auto-generate WebSite JSON-LD with SearchAction for sitelinks search box (default: true). Set to false to disable. */ websiteSchema?: boolean; /** Auto-generate Organization JSON-LD on homepage from app.links (default: true). Set to false to disable. */ organizationSchema?: boolean; } /** * Favicon and PWA configuration * * Configure automatic favicon generation and PWA manifest icons. * * @example * ```typescript * const faviconConfig: FaviconConfig = { * appName: 'My App', * themeColor: '#000000', * backgroundColor: '#ffffff' * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FaviconConfig { /** Enable automatic favicon system (default: true) */ enabled?: boolean; /** App name for PWA manifest */ appName?: string; /** Theme color for mobile browsers */ themeColor?: string; /** Background color for splash screens */ backgroundColor?: string; /** Include PWA manifest icons */ includeManifestIcons?: boolean; /** Include Microsoft tile icons */ includeMSIcons?: boolean; } /** * Feature flags and debug configuration * * Controls app behavior and GDPR compliance. * Feature availability is auto-detected via env vars/packages. * * @example * ```typescript * const featuresConfig: FeaturesConfig = { * debug: true, * offlineTrustEnabled: true, * requiredCookies: ['necessary', 'analytics'] * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FeaturesConfig { /** Enable debug tools (default: false in production, true in development) */ debug?: boolean; /** * Enable offline trust for cached claims (default: false) * * When true: * - Online: Always verify with server (don't trust cache) * - Offline: Use cached claims (graceful degradation) * * When false: * - Online: Always verify with server * - Offline: Reject (throw error, require network) * * @default false */ offlineTrustEnabled?: boolean; /** * Cookie consent categories to display in GDPR banner * * Controls which cookie categories users can consent to. * Framework always includes 'necessary' (cannot be disabled). * * @example * ```typescript * features: { * requiredCookies: ['necessary', 'functional', 'analytics'] * } * ``` * * @default ['necessary'] */ requiredCookies?: string[]; } /** * Complete application configuration * * Consolidates all app-level configuration with smart defaults. * Pass only what you need to override - everything has sensible defaults. * * @example * ```typescript * // Minimal configuration * const config: AppConfig = { * app: { name: 'My App' } * }; * * // Full configuration * const config: AppConfig = { * app: { * name: 'My App', * description: 'Professional app' * }, * auth: { * authRoute: '/signin', * roleRoute: '/403', * tierRoute: '/pricing' * }, * seo: { * defaultImage: '/og.png' * }, * preset: 'landing', * features: { * debug: true * } * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Query cache configuration * * Configure default TanStack Query cache behavior for your app. * These settings apply to all queries unless overridden per-query. * * **Framework Defaults (Infinite Cache):** * - `staleTime: Infinity` (data never becomes stale) * - `refetchOnWindowFocus: false` (manual refresh only) * - `refetchOnReconnect: false` (manual refresh only) * * This default strategy minimizes API costs and is ideal for: * - Single-admin apps * - Apps with manual refresh buttons * - Cost-optimized scenarios * * @example * ```typescript * // Use framework defaults (infinite cache, no auto-refetch) * // No query config needed - defaults are optimal * ``` * * @example * ```typescript * // Override to short cache with auto-refetch * query: { * staleTime: 1000 * 60 * 5, // 5 minutes * refetchOnWindowFocus: true, * refetchOnReconnect: true, * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface QueryConfig { /** Time until data is considered stale (default: Infinity = never stale) */ staleTime?: number; /** Time until inactive data is garbage collected (default: 30 minutes) */ gcTime?: number; /** Number of retry attempts for failed queries (default: 1) */ retry?: number; /** Whether to refetch when window regains focus (default: false = manual refresh only) */ refetchOnWindowFocus?: boolean; /** Whether to refetch on reconnect (default: false = manual refresh only) */ refetchOnReconnect?: boolean; /** Mutation retry attempts (default: 1) */ mutationRetry?: number; /** Mutation retry delay function (default: exponential backoff) */ mutationRetryDelay?: (attemptIndex: number) => number; } /** Top-level application configuration passed to DoNotDevProvider. */ interface AppConfig { /** App metadata and branding */ app?: AppMetadata; /** Authentication routes - partial override of defaults */ auth?: Partial | false; /** SEO configuration (set to false to disable) */ seo?: SEOConfig | false; /** Favicon configuration (set to false to disable) */ favicon?: FaviconConfig | false; /** Layout preset for store initialization (defaults to 'landing' if invalid/empty) */ preset?: string; /** Custom presets — same shape as built-in presets, keyed by name */ customPresets?: Record; /** Feature flags */ features?: FeaturesConfig; /** Query cache configuration (defaults: 5min staleTime, refetch on focus/reconnect) */ query?: QueryConfig; /** * Server-side rendering (Next adapter). **Defaults to `true`** — generated page * wrappers render directly and the provider tree renders on the server, so page * content is present in the initial HTML (real, crawlable SSR). Set to `false` * to opt OUT and restore the legacy client-only render (content appears only * after hydration). The provider tree is store-driven, so SSR routes render * dynamically at request time. */ ssr?: boolean; } /** * Custom store configuration for app-specific stores * * Allows apps to register custom Zustand stores with the framework's * store initialization system. Custom stores benefit from: * - Shell loader integration (critical stores block render) * - Retry logic and error handling * - Unified initialization flow * * @example * ```typescript * const customStores: CustomStoreConfig[] = [{ * name: 'dndop', * type: 'critical', * store: useDndopStore, * }]; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CustomStoreConfig { /** Store name for logging and debugging */ name: string; /** * Store initialization priority * - 'critical': Blocks render until ready, shell loader stays visible * - 'regular': Initializes in background after critical stores */ type: 'critical' | 'regular'; /** * Zustand store reference (hook) * Can be called as a hook with a selector: `store((state) => state.isReady)` * Also has a .getState() method for direct state access */ store: { (selector: (state: any) => any): any; getState: () => { initialize?: () => Promise; [key: string]: any; }; subscribe: (listener: () => void) => () => void; }; } /** * AppProviders props interface with slot-based layout customization */ /** * Application providers props * * Clean, minimal API for configuring application providers with smart defaults. * * @example * ```typescript * // Minimal configuration * * * // Full configuration * }, * footer: () => * }} * /> * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AppProvidersProps { /** * Consolidated application configuration * * All configuration is optional with smart defaults. * Pass only what you need to override. */ config?: AppConfig; /** * Layout configuration - simple API for customizing layout * * @example * ```typescript * // Preset only * layout={{ preset: 'admin' }} * * // Slot override * layout={{ header: { end: () => } }} * * // Full override * layout={{ header: () => }} * ``` */ layout?: LayoutConfig; /** * Child components * * Custom routing content. When provided, overrides framework routing. */ children?: ReactNode; /** * Custom store configurations * * Register Zustand stores to benefit from shell loader, retry logic, * error handling. Critical stores block render. * * @example * ```typescript * customStores={[{ * name: 'dndop', * type: 'critical', * store: useDndopStore, * }]} * ``` */ customStores?: CustomStoreConfig[]; } /** * Resolved layout configuration interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ResolvedLayoutConfig { /** Current preset name */ preset: LayoutPreset; /** Resolved app configuration */ app: { name: string; metadata: Record; }; } /** * @fileoverview DoNotDev Framework - Unified Types & Constants * @description Single source of truth for all framework types and constants * @package @donotdev/types * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * @remarks * This file consolidates all framework types and constants to prevent unnecessary splitting * and ensure DRY principles. All magic strings are replaced with typed constants. */ /** * Supported platform identifiers * @constant */ declare const PLATFORMS: { readonly VITE: "vite"; readonly NEXTJS: "nextjs"; readonly EXPO: "expo"; readonly REACT_NATIVE: "react-native"; readonly UNKNOWN: "unknown"; }; /** * Platform type derived from PLATFORMS constant */ type Platform = (typeof PLATFORMS)[keyof typeof PLATFORMS]; /** * Supported environment modes * @constant */ declare const ENVIRONMENTS: { readonly DEVELOPMENT: "development"; readonly PRODUCTION: "production"; readonly TEST: "test"; }; /** * Environment mode type derived from ENVIRONMENTS constant */ type EnvironmentMode = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS]; /** * Supported execution contexts * @constant */ declare const CONTEXTS: { readonly CLIENT: "client"; readonly SERVER: "server"; readonly BUILD: "build"; }; /** * Context type derived from CONTEXTS constant */ type Context = (typeof CONTEXTS)[keyof typeof CONTEXTS]; /** * Platform detection confidence thresholds * @constant */ declare const CONFIDENCE_LEVELS: { readonly HIGH: 0.95; readonly MEDIUM: 0.8; readonly LOW: 0.7; readonly MINIMUM: 0.3; }; /** * Confidence level type derived from CONFIDENCE_LEVELS constant */ type ConfidenceLevel = (typeof CONFIDENCE_LEVELS)[keyof typeof CONFIDENCE_LEVELS]; /** * Unified feature status for all feature packages * Replaces combinatorial boolean flags (initialized, authStateChecked, loading) with single-source-of-truth enum. * * **Status values:** * - `initializing`: Feature is loading/initializing (show skeleton/loader, DON'T redirect yet) * - `ready`: Feature fully operational (check user state, redirect if needed) * - `degraded`: Feature unavailable but app continues (protected routes redirect with error, public routes allow access) * - `error`: Feature encountered recoverable error (protected routes redirect with error) * * **Usage in guards:** * - Protected routes with `degraded` status redirect to auth route with `?error=auth_unavailable` * - Protected routes with `error` status redirect to auth route with `?error=auth_error` * - `initializing` shows loader, doesn't redirect * - `ready` performs normal auth checks * * @example * ```typescript * switch (status) { * case FEATURE_STATUS.INITIALIZING: return ; * case FEATURE_STATUS.DEGRADED: * // Protected route → redirect with error * // Public route → allow access * return authRequired ? : children; * case FEATURE_STATUS.READY: return user ? children : ; * case FEATURE_STATUS.ERROR: return ; * } * ``` */ declare const FEATURE_STATUS: { readonly INITIALIZING: "initializing"; readonly READY: "ready"; readonly DEGRADED: "degraded"; readonly ERROR: "error"; }; /** * Feature status type derived from FEATURE_STATUS constant */ type FeatureStatus = (typeof FEATURE_STATUS)[keyof typeof FEATURE_STATUS]; /** * Supported storage backend types * @constant */ declare const STORAGE_TYPES: { readonly LOCAL: "localStorage"; readonly SESSION: "sessionStorage"; readonly INDEXED_DB: "indexedDB"; readonly MEMORY: "memory"; }; /** * Storage type derived from STORAGE_TYPES constant */ type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES]; /** * Storage scope levels for data isolation * @constant */ declare const STORAGE_SCOPES: { readonly USER: "user"; readonly GLOBAL: "global"; readonly SESSION: "session"; }; /** * Storage scope type derived from STORAGE_SCOPES constant */ type StorageScope = (typeof STORAGE_SCOPES)[keyof typeof STORAGE_SCOPES]; /** * PWA display modes * @constant */ declare const PWA_DISPLAY_MODES: { readonly STANDALONE: "standalone"; readonly FULLSCREEN: "fullscreen"; readonly MINIMAL_UI: "minimal-ui"; readonly BROWSER: "browser"; }; /** * PWA display mode type derived from PWA_DISPLAY_MODES constant */ type PWADisplayMode = (typeof PWA_DISPLAY_MODES)[keyof typeof PWA_DISPLAY_MODES]; /** * PWA asset types * @constant */ declare const PWA_ASSET_TYPES: { readonly MANIFEST: "manifest"; readonly SERVICE_WORKER: "service-worker"; readonly ICON: "icon"; }; /** * PWA asset type derived from PWA_ASSET_TYPES constant */ type PWAAssetType = (typeof PWA_ASSET_TYPES)[keyof typeof PWA_ASSET_TYPES]; /** * Route discovery sources * @constant */ declare const ROUTE_SOURCES: { readonly AUTO: "auto-discovery"; readonly MANUAL: "manual"; readonly HYBRID: "hybrid"; }; /** * Route source type derived from ROUTE_SOURCES constant */ type RouteSource = (typeof ROUTE_SOURCES)[keyof typeof ROUTE_SOURCES]; /** * Generic ID type used throughout the application * @description Currently a string, but typed for future flexibility */ type ID = string; /** * Generic timestamp format for dates and times * @description ISO 8601 string format (e.g., "2025-01-15T10:30:00.000Z") */ type Timestamp = string; /** * Generic pagination options for fetching paginated data */ interface PaginationOptions { /** The page number (1-indexed) */ page: number; /** The number of items per page */ pageSize: number; } /** * Generic API response format for consistent error handling * @template T - The type of data in the response */ interface ApiResponse { /** Indicates whether the operation was successful */ success: boolean; /** The data returned by the operation (if successful) */ data?: T; /** Error information (if the operation failed) */ error?: { /** A machine-readable error code */ code: string; /** A human-readable error message */ message: string; }; } /** * Basic user information that can be shared in various contexts */ interface BasicUserInfo { /** The unique identifier for the user */ id: ID; /** The user's display name (if available) */ displayName?: string | null; /** The user's email address (if available) */ email?: string | null; /** The URL of the user's profile photo (if available) */ photoURL?: string | null; } /** * Basic document with ID and timestamps * @description All entity documents in the system should extend this interface */ interface BaseDocument { /** The unique identifier for the document */ id: ID; /** When the document was created */ createdAt: Timestamp; /** When the document was last updated */ updatedAt: Timestamp; /** The ID of the user who created the document (if available) */ createdById?: ID; /** The ID of the user who last updated the document (if available) */ updatedById?: ID; } /** * Page-level authentication requirements * @description Used in PageMeta and NavigationRoute for route-level auth */ type PageAuth = boolean | { /** Whether authentication is required */ required?: boolean; /** Required user role */ role?: UserRole; /** Required subscription tier */ tier?: SubscriptionTier; /** Custom validation function */ validate?: (role: string, tier: string) => boolean; }; /** * Page metadata interface for route discovery and configuration * * @remarks * **ALL PROPERTIES ARE OPTIONAL** - Framework provides smart defaults: * * - `auth`: false (public) by default - YOU must specify auth requirements explicitly * - `title`: Auto-extracted from filename (ShowcasePage → "Showcase") * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase") * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form") * - `route`: Only needed for custom paths or dynamic routes like :id, :slug * * @example Simple page (no meta needed): * ```tsx * export function HomePage() { * return ...; * } * // Framework provides: auth=false, title from home.title, entity=home * ``` * * @example Dynamic route (string format - explicit path): * ```tsx * export const meta: PageMeta = { * route: '/blog/:slug' // Creates /blog/:slug * }; * // Framework provides: auth=false, title from blog.title, entity=blog * ``` * * @example Dynamic route (object format - auto-generates base path): * ```tsx * export const meta: PageMeta = { * route: { params: ['id'] } // Creates /myRoute/:id (base path from file location) * }; * // For file at pages/myRoute/DetailPage.tsx → route becomes /myRoute/:id * ``` * * @example Auth-required (developer must be explicit): * ```tsx * export const meta: PageMeta = { * auth: { required: true } // YOU decide what needs auth * }; * ``` */ /** * SEO metadata for a page * @description Controls ``, meta description, Open Graph, and Twitter Cards. * All fields default to i18n lookup when undefined. * * @example i18n-first (default) * ```tsx * export const meta: PageMeta = { * namespace: 'pricing', // Uses pricing:title, pricing:description * }; * ``` * * @example Full title control (escape "Page | App" format) * ```tsx * export const meta: PageMeta = { * namespace: 'home', * seo: { fullTitle: 'DoNotDev - Build Apps in Minutes' }, * }; * ``` * * @example siteName only * ```tsx * export const meta: PageMeta = { * seo: { title: null }, // → "AppName" * }; * ``` * * @version 0.2.0 * @since 0.2.0 * @author AMBROISE PARK Consulting */ interface SeoMeta { /** * Page title segment (appears as "title | siteName") * @description * - `undefined` → i18n lookup (`ns:title`) * - `string` → literal value + siteName suffix * - `null` → siteName only (no page title) */ title?: string | null; /** * Full title override (no suffix appended) * @description Escapes the "Page | App" format entirely. * Takes priority over `title` when set. */ fullTitle?: string; /** * Meta description * @description * - `undefined` → i18n lookup (`ns:description`) * - `string` → literal value * - `null` → omit meta description */ description?: string | null; /** Open Graph image URL (relative or absolute) */ image?: string; /** Keywords for meta tag */ keywords?: string[]; /** Page type for Open Graph */ type?: 'website' | 'article' | 'product'; /** Exclude from search engine indexing */ noindex?: boolean; } /** Page-level metadata for route discovery, auth, SEO, and navigation. */ interface PageMeta { /** Authentication requirements for this route */ auth?: PageAuth; /** Route configuration - just define the exact path you want */ route?: string | { params?: string[]; }; /** Page title (optional - framework auto-extracts from filename if not provided) */ title?: string; /** * Translation/SEO namespace for this page * @description Used for meta tags and translations */ namespace?: string; /** * Icon for navigation (optional - framework provides smart defaults) * @description **ONLY lucide-react JSX components** - extracted as component name string at build time for tree-shaking. * * **RESTRICTIONS:** * - ✅ Only: `<Rocket />`, `<ShoppingCart />`, `<Home />` (lucide-react JSX components) * - ❌ NOT: Emojis (`"🚀"`), strings (`"Rocket"`), or custom ReactNode * * **Why?** This is for build-time extraction and tree-shaking. The component name is extracted and stored as a string. * * **For flexible icons** (emojis, strings, custom components), use the `Icon` component directly in your JSX, not in PageMeta. * * @example * ```tsx * import { Rocket } from 'lucide-react'; * export const meta: PageMeta = { * icon: <Rocket /> // ✅ Correct - lucide-react component * }; * ``` * * @example * ```tsx * // ❌ WRONG - Don't use emojis or strings in PageMeta * export const meta: PageMeta = { * icon: "🚀" // ❌ Not supported in PageMeta * }; * ``` */ icon?: ReactNode; /** * Hide from navigation menu (default: false - shows in navigation) * @description Set to true to exclude this route from navigation menus * @default false * @example * ```tsx * export const meta: PageMeta = { * hideFromMenu: true // Won't appear in HeaderNavigation, Sidebar, etc. * }; * ``` */ hideFromMenu?: boolean; /** * Hide breadcrumbs on this page (default: false) * @description Set to true to hide framework breadcrumbs on this route * @default false */ hideBreadcrumbs?: boolean; /** * Layout preset override for this route * @description When set, overrides the app's default layout preset for this route only. * When absent, the app's `appConfig.preset` is used. * The override is transient — navigating away restores the next route's preset or the app default. * * @example * ```tsx * export const meta: PageMeta = { * preset: 'admin', // This route uses admin layout (sidebar, compact density) * auth: true, * }; * ``` */ preset?: LayoutPreset; /** * SEO metadata override * @description Fine-grained control over `<title>`, meta description, and Open Graph tags. * When omitted, SEO uses i18n lookup based on `namespace` (i18n-first by default). * * @example Escape "Page | App" format * ```tsx * export const meta: PageMeta = { * namespace: 'home', * seo: { fullTitle: 'DoNotDev - Build Apps in Minutes' }, * }; * ``` * * @example siteName only (no page title) * ```tsx * export const meta: PageMeta = { * seo: { title: null }, * }; * ``` */ seo?: SeoMeta; /** * User-facing category for sidebar/menu grouping * @description Groups routes into collapsible sections in navigation. Unlike * auto-discovered `entity` (parent-dir name), `category` is author-declared * and typically maps to a higher-level folder (e.g., `Analyzers`, `Tools`). * Routes without `category` render ungrouped at the top of the menu. * * @example * ```tsx * export const meta: PageMeta = { * namespace: 'budgetPlanner', * category: 'Analyzers', * icon: <WalletIcon />, * }; * ``` */ category?: string; } /** * Route metadata (discovery-generated) * @description Complete route metadata including auto-discovered fields from RouteDiscovery * * This extends PageMeta with fields that are automatically discovered from file paths: * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase") * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form") * * These fields are always present in discovered routes but cannot be set in PageMeta. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RouteMeta extends PageMeta { /** Entity/domain grouping - auto-discovered from file path (not user-configurable) */ entity?: string; /** Action type for route categorization - auto-discovered from filename patterns (not user-configurable) */ action?: string | null; /** File path where route was discovered */ file?: string; } /** * Navigation route interface * @description Single source of truth for all navigation routes */ interface NavigationRoute { /** Route path */ path: string; /** Display label for navigation */ label: string; /** Optional icon identifier or component */ icon?: string | ReactNode; /** Whether route is external */ external?: boolean; /** Whether route is disabled */ disabled?: boolean; /** Badge content for notifications */ badge?: string | number; /** Authentication configuration */ auth?: PageAuth; /** Route metadata (includes auto-discovered fields) */ meta?: RouteMeta; /** Nested child routes */ children?: NavigationRoute[]; } /** * Storage options for get/set operations */ interface StorageOptions { /** * Whether to encrypt the data * @default false for most data, true for sensitive data */ encryption?: boolean; /** * Time in seconds after which the data expires * @description Set to 0 for no expiration * @default 0 */ expiry?: number; /** * Storage scope for data isolation * @description * - 'user': User-specific data, tied to user ID (requires auth) * - 'global': Application-wide data, not tied to specific user * - 'session': Session-only data, cleared on logout/browser close * @default 'user' */ scope?: StorageScope; } /** * Storage manager interface * @description Main interface for all storage operations */ interface IStorageManager { /** * Retrieve data from storage * @param key - Storage key * @param options - Storage options * @returns Promise resolving to the stored data or null if not found */ get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Store data * @param key - Storage key * @param value - Data to store * @param options - Storage options * @returns Promise resolving when data is stored */ set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Remove data from storage * @param key - Storage key * @returns Promise resolving when data is removed */ remove(key: string): Promise<void>; /** * Clear all data in the specified scope * @param scope - Scope to clear, or all scopes if not specified * @returns Promise resolving when data is cleared */ clear(scope?: StorageScope): Promise<void>; /** * Store sensitive data with encryption * @description Shorthand for set() with encryption=true * @param key - Storage key * @param value - Data to store * @param options - Storage options (encryption will be set to true) * @returns Promise resolving when data is stored */ setSecure<T>(key: string, value: T, options?: Omit<StorageOptions, 'encryption'>): Promise<void>; /** * Retrieve sensitive data with decryption * @description Shorthand for get() with encryption=true * @param key - Storage key * @param options - Storage options (encryption will be set to true) * @returns Promise resolving to the decrypted data or null if not found */ getSecure<T>(key: string, options?: Omit<StorageOptions, 'encryption'>): Promise<T | null>; } /** * Storage strategy interface * @description Used by StorageManager to delegate storage operations */ interface IStorageStrategy { /** * Retrieve data from storage * @param key - Storage key * @param options - Storage options * @returns Promise resolving to the stored data or null if not found */ get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Store data * @param key - Storage key * @param value - Data to store * @param options - Storage options * @returns Promise resolving when data is stored */ set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Remove data from storage * @param key - Storage key * @returns Promise resolving when data is removed */ remove(key: string): Promise<void>; /** * Clear all data in the specified scope * @param scope - Scope to clear, or all scopes if not specified * @returns Promise resolving when data is cleared */ clear(scope?: StorageScope): Promise<void>; } /** * i18n Plugin Configuration * @description Configuration for internationalization system */ interface I18nPluginConfig { /** Mapping of language → namespace → loader function */ mapping: Record<string, Record<string, () => Promise<any>>>; /** List of available language codes */ languages: string[]; /** List of eagerly loaded namespace identifiers */ eager: string[]; /** Fallback language code */ fallback: string; /** Preloaded translation content for eager namespaces (optional) */ content?: Record<string, Record<string, any>>; /** Lazy loader functions — static import() calls generated by Vite plugin (optional, not serializable) */ loaders?: Record<string, Record<string, () => Promise<any>>>; /** Storage configuration */ storage: { /** Storage backend type */ type: StorageType; /** Storage key prefix */ prefix: string; /** Time-to-live in seconds */ ttl: number; /** Whether to encrypt stored data */ encryption: boolean; /** Maximum storage size in bytes */ maxSize: number; }; /** Performance configuration */ performance: { /** Maximum cache size */ cacheSize: number; /** Error cache TTL in seconds */ errorCacheTTL: number; }; /** Discovery manifest metadata */ manifest: { /** Total number of translation files */ totalFiles: number; /** Total number of namespaces */ totalNamespaces: number; /** Total number of languages */ totalLanguages: number; /** Number of eagerly loaded namespaces */ eagerNamespaces: number; /** ISO timestamp of generation */ generatedAt: string; }; /** Whether debug mode is enabled */ debug: boolean; } /** * Routes Plugin Configuration * @description Complete route configuration populated by discovery system */ interface RoutesPluginConfig { /** * Array of discovered routes * @description All routes discovered by the route discovery system */ mapping: Array<{ /** * URL path for the route (platform-agnostic) * @description The URL path that users see in their browser * @example '/showcase/layouts', '/users/:id', '/dashboard' */ path: string; /** * Lazy component reference (Vite-specific) * @description React.lazy() component for code splitting * @example lazy(() => import("/src/pages/showcase/LayoutsPage")) */ component: any; /** * Absolute file system path (Next.js-specific) * @description The absolute path to the component file * @example '/src/pages/showcase/LayoutsPage.tsx' */ importPath: string; /** * Export name for named exports * @example 'HomePage', 'AboutPage' */ exportName?: string; /** * Authentication configuration (platform-agnostic) * @description Defines whether the route requires authentication */ auth: PageAuth; /** * Route metadata (platform-agnostic) * @description Additional information about the route, including auto-discovered fields */ meta: RouteMeta; }>; /** * Discovery metadata and statistics * @description Information about the route discovery process */ manifest: { /** Total number of discovered routes */ totalRoutes: number; /** Number of routes requiring authentication */ authRequired: number; /** Number of public routes */ publicRoutes: number; /** Source of routes (auto-discovery vs manual) */ source: RouteSource; /** ISO timestamp when routes were generated */ generatedAt: string; }; } /** * Themes Plugin Configuration * @description Configuration for theme discovery and management */ interface ThemesPluginConfig { /** Mapping of theme names to theme configurations */ mapping: Record<string, any>; /** Array of discovered themes */ discovered: Array<{ /** Theme identifier */ name: string; /** Human-readable theme name */ displayName: string; /** Whether this is a dark theme */ isDark: boolean; /** Theme metadata */ meta: { /** Icon identifier */ icon: string; /** Theme description */ description?: string; /** Theme category */ category?: string; /** Theme author */ author?: string; /** Additional metadata */ [key: string]: any; }; /** Source file path */ source: string; /** Whether theme is essential (cannot be disabled) */ essential: boolean; }>; /** CSS custom property variables */ variables: Record<string, string>; /** Utility class mappings */ utilities: Record<string, Record<string, string>>; /** Discovery manifest metadata */ manifest: { /** Total number of discovered themes */ totalThemes: number; /** Total number of CSS variables */ totalVariables: number; /** Total number of utility classes */ totalUtilities: number; /** ISO timestamp of generation */ generatedAt: string; }; } /** * Assets Plugin Configuration * @description Configuration for static asset management */ interface AssetsPluginConfig { /** Mapping of asset paths to asset metadata */ mapping: Record<string, any>; /** SVG content of logo.svg for inline rendering with CSS variable theming */ logoSvgContent?: string | null; /** Discovery manifest metadata */ manifest: { /** Total number of discovered assets */ totalAssets: number; /** ISO timestamp of generation */ generatedAt: string; }; } /** * PWA Plugin Configuration * @description Configuration for Progressive Web App features */ interface PWAPluginConfig { /** Array of PWA assets */ assets: Array<{ /** Type of PWA asset */ type: PWAAssetType; /** Asset file path */ path: string; /** Asset file size in bytes */ size?: number; /** Asset content (for inline assets) */ content?: any; /** Asset format (for images) */ format?: string; /** Asset purpose (for icons) */ purpose?: string; }>; /** PWA manifest configuration */ manifest: { /** Application name */ name: string; /** Short application name */ short_name: string; /** Application description */ description: string; /** Start URL */ start_url: string; /** Display mode */ display: PWADisplayMode; /** Background color */ background_color: string; /** Theme color */ theme_color: string; /** Array of app icons */ icons: Array<{ /** Icon source path */ src: string; /** Icon sizes (e.g., '192x192') */ sizes: string; /** Icon MIME type */ type: string; /** Icon purpose (e.g., 'any', 'maskable') */ purpose: string; }>; }; /** Discovery manifest metadata */ manifestInfo: { /** Total number of PWA assets */ totalAssets: number; /** Total number of icons */ totalIcons: number; /** Whether service worker is present */ hasServiceWorker: boolean; /** ISO timestamp of generation */ generatedAt: string; }; } /** * Features Plugin Configuration * @description Configuration for feature discovery and enablement * * @remarks * This interface defines the structure for feature discovery data that is populated * at build time and made available at runtime for feature availability checking. * * @example * ```typescript * // Generated by feature discovery system * const featuresConfig: FeaturesPluginConfig = { * available: ['auth', 'billing', 'i18n', 'oauth'], * enabled: ['auth', 'i18n'], * overridden: false * }; * ``` */ interface FeaturesPluginConfig { /** * List of all available features discovered in packages/features/ * @example ['auth', 'billing', 'i18n', 'oauth'] */ available: string[]; } /** * Complete DoNotDev framework configuration structure * @description Single source of truth for all framework configuration * * @remarks * All discovery plugins add their data to this unified config. * Available at runtime via globalThis._DNDEV_CONFIG_ or window._DNDEV_CONFIG_ */ interface DndevFrameworkConfig { /** Framework platform (Vite or Next.js) */ platform: Platform; /** Current environment mode */ mode: EnvironmentMode; /** Framework version */ version: string; /** Execution context */ context: Context; /** Unix timestamp of config generation */ timestamp: number; /** i18n plugin configuration (optional) */ i18n?: I18nPluginConfig; /** Routes plugin configuration (optional) */ routes?: RoutesPluginConfig; /** Themes plugin configuration (optional) */ themes?: ThemesPluginConfig; /** Assets plugin configuration (optional) */ assets?: AssetsPluginConfig; /** PWA plugin configuration (optional) */ pwa?: PWAPluginConfig; /** Features plugin configuration (optional) */ features?: FeaturesPluginConfig; /** Environment variables (VITE_* variables from .env files) */ env?: Record<string, string>; } /** * @fileoverview Billing Constants * @description Constants for billing domain. Defines subscription status values, Stripe modes, and billing-related constants. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Standard subscription status values from billing providers * Apps can override these by providing their own status constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const SUBSCRIPTION_STATUS: { readonly ACTIVE: "active"; readonly CANCELED: "canceled"; readonly INCOMPLETE: "incomplete"; readonly INCOMPLETE_EXPIRED: "incomplete_expired"; readonly PAST_DUE: "past_due"; readonly TRIALING: "trialing"; readonly UNPAID: "unpaid"; }; /** * Override subscription status for custom app needs * @example * ```typescript * // In your app's config * overrideSubscriptionStatus({ * ACTIVE: 'subscribed', * CANCELED: 'cancelled', * TRIALING: 'trial' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overrideSubscriptionStatus(customStatus: Partial<typeof SUBSCRIPTION_STATUS>): void; /** * Type for subscription status names * Apps can extend this with their own custom statuses * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type SubscriptionStatus = (typeof SUBSCRIPTION_STATUS)[keyof typeof SUBSCRIPTION_STATUS] | string; /** * Standard payment mode values for Stripe checkout * Apps can override these by providing their own mode constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const STRIPE_MODES: { readonly PAYMENT: "payment"; readonly SUBSCRIPTION: "subscription"; }; /** * Override payment modes for custom app needs * @example * ```typescript * // In your app's config * overridePaymentModes({ * PAYMENT: 'one_time', * SUBSCRIPTION: 'recurring' * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function overridePaymentModes(customModes: Partial<typeof STRIPE_MODES>): void; /** * Type for payment mode names * Apps can extend this with their own custom modes * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PaymentMode = (typeof STRIPE_MODES)[keyof typeof STRIPE_MODES] | string; /** * Standard subscription duration values * Apps can override these by providing their own duration constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const SUBSCRIPTION_DURATIONS: { readonly ONE_MONTH: "1month"; readonly THREE_MONTHS: "3months"; readonly SIX_MONTHS: "6months"; readonly ONE_YEAR: "1year"; readonly TWO_YEARS: "2years"; readonly LIFETIME: "lifetime"; }; /** * Type for subscription duration names * Apps can extend this with their own custom durations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type SubscriptionDuration = (typeof SUBSCRIPTION_DURATIONS)[keyof typeof SUBSCRIPTION_DURATIONS] | string; /** * Common subscription features that apps can reference * Apps can use these or define their own custom features * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CommonSubscriptionFeatures = 'basic-usage' | 'limited-storage' | 'standard-support' | 'cloud-sync' | 'advanced-analytics' | 'priority-support' | 'custom-branding' | 'team-collaboration' | 'ai-assistant' | 'custom-models' | 'unlimited-generations' | 'advanced-integrations'; /** * Subscription claims stored in Firebase Auth custom claims * Type definition - schema in schemas.ts validates against this structure */ type SubscriptionClaims = { tier: string; subscriptionId: string | null; customerId: string; status: SubscriptionStatus; subscriptionEnd: string | null; cancelAtPeriodEnd: boolean; updatedAt: string; isDefault?: boolean; }; /** * Factory function to create default subscription claims * @param userId - User ID for the subscription * @returns Default subscription claims for free tier * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createDefaultSubscriptionClaims(userId: string): SubscriptionClaims; /** * Generic subscription configuration interface * Apps define their specific subscription tiers and features * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SubscriptionConfig { /** Subscription tiers with their features and hierarchy */ tiers: Record<string, { /** Features available for this tier */ features: string[]; /** Tier level for comparison (higher = more access) */ level: number; }>; } /** * Common tier configurations that apps can use as a starting point * Apps can extend this or create their own completely custom configs * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const COMMON_TIER_CONFIGS: { free: { features: string[]; level: number; }; pro: { features: string[]; level: number; }; ai: { features: string[]; level: number; }; }; /** * Default subscription for new users (free tier) * Framework consumers can override these defaults * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const DEFAULT_SUBSCRIPTION: SubscriptionClaims; /** * @fileoverview Schema Definitions for Billing and Subscription Management * @description Single source of truth for all billing-related data validation. Defines Valibot schemas for billing, subscriptions, checkout sessions, and related data structures. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Schema for creating a checkout session request * Uses constants for enum values to ensure consistency * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CreateCheckoutSessionRequestSchema: v.SchemaWithPipe<readonly [v.ObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Stripe price ID (fixed pricing mode) */ readonly priceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Amount in cents (dynamic pricing mode) */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name shown on Stripe checkout (dynamic pricing mode) */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Currency code, defaults to 'eur' (dynamic pricing mode) */ readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, undefined>; readonly successUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly cancelUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly customerEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly userEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly mode: v.OptionalSchema<v.PicklistSchema<["payment", "subscription"], undefined>, undefined>; }, undefined>, v.CheckAction<{ userId?: string | undefined; productId?: string | undefined; priceId?: string | undefined; unitAmount?: number | undefined; productName?: string | undefined; currency?: string | undefined; successUrl: string; cancelUrl: string; customerEmail?: string | undefined; userEmail?: string | undefined; metadata?: { [x: string]: string; } | undefined; allowPromotionCodes?: boolean | undefined; mode?: "payment" | "subscription" | undefined; }, "Either priceId or (unitAmount + productName) is required">]>; /** * Schema for creating a checkout session response * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CreateCheckoutSessionResponseSchema: v.ObjectSchema<{ readonly sessionId: v.StringSchema<undefined>; readonly sessionUrl: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>, undefined>; }, undefined>; /** * Schema for subscription data from billing providers * Uses constants for enum values to ensure consistency * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const SubscriptionDataSchema: v.ObjectSchema<{ readonly userId: v.StringSchema<undefined>; readonly tier: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>; /** * Schema for subscription claims stored in Firebase Auth custom claims * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const SubscriptionClaimsSchema: v.ObjectSchema<{ readonly tier: v.StringSchema<undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; readonly isDefault: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; }, undefined>; /** * Schema for webhook event data * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const WebhookEventSchema: v.ObjectSchema<{ readonly id: v.StringSchema<undefined>; readonly type: v.StringSchema<undefined>; readonly data: v.ObjectSchema<{ readonly object: v.AnySchema; }, undefined>; readonly created: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>; /** * Schema for Stripe checkout session metadata * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CheckoutSessionMetadataSchema: v.LooseObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly firebaseUid: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productType: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>; /** * Create checkout session request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CreateCheckoutSessionRequest = v.InferOutput<typeof CreateCheckoutSessionRequestSchema>; /** * Create checkout session response type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CreateCheckoutSessionResponse = v.InferOutput<typeof CreateCheckoutSessionResponseSchema>; /** * Subscription data type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type SubscriptionData = v.InferOutput<typeof SubscriptionDataSchema>; /** * Subscription claims type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Webhook event type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type WebhookEvent = v.InferOutput<typeof WebhookEventSchema>; /** * Checkout session metadata type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CheckoutSessionMetadata = v.InferOutput<typeof CheckoutSessionMetadataSchema>; /** * Stripe payment type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripePayment = v.InferOutput<typeof StripePaymentSchema> & { onPurchaseSuccess?: (userId: string, metadata: any) => Promise<void>; onPurchaseFailure?: (userId: string, metadata: any) => Promise<void>; }; /** * Stripe subscription type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripeSubscription = v.InferOutput<typeof StripeSubscriptionSchema> & { onSubscriptionCreated?: (userId: string, metadata: any) => Promise<void>; onSubscriptionRenewed?: (userId: string, metadata: any) => Promise<void>; onSubscriptionCancelled?: (userId: string, metadata: any) => Promise<void>; onPaymentFailed?: (userId: string, metadata: any) => Promise<void>; }; /** * Product declaration type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ProductDeclaration = v.InferOutput<typeof ProductDeclarationSchema> & { onPurchaseSuccess?: (userId: string, metadata: any) => Promise<void>; onPurchaseFailure?: (userId: string, metadata: any) => Promise<void>; onSubscriptionCreated?: (userId: string, metadata: any) => Promise<void>; onSubscriptionRenewed?: (userId: string, metadata: any) => Promise<void>; onSubscriptionCancelled?: (userId: string, metadata: any) => Promise<void>; onPaymentFailed?: (userId: string, metadata: any) => Promise<void>; }; /** * Validate create checkout session request * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCreateCheckoutSessionRequest(data: unknown): v.SafeParseResult<v.SchemaWithPipe<readonly [v.ObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Stripe price ID (fixed pricing mode) */ readonly priceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Amount in cents (dynamic pricing mode) */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name shown on Stripe checkout (dynamic pricing mode) */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Currency code, defaults to 'eur' (dynamic pricing mode) */ readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, undefined>; readonly successUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly cancelUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly customerEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly userEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly mode: v.OptionalSchema<v.PicklistSchema<["payment", "subscription"], undefined>, undefined>; }, undefined>, v.CheckAction<{ userId?: string | undefined; productId?: string | undefined; priceId?: string | undefined; unitAmount?: number | undefined; productName?: string | undefined; currency?: string | undefined; successUrl: string; cancelUrl: string; customerEmail?: string | undefined; userEmail?: string | undefined; metadata?: { [x: string]: string; } | undefined; allowPromotionCodes?: boolean | undefined; mode?: "payment" | "subscription" | undefined; }, "Either priceId or (unitAmount + productName) is required">]>>; /** * Validate create checkout session response * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCreateCheckoutSessionResponse(data: unknown): v.SafeParseResult<v.ObjectSchema<{ readonly sessionId: v.StringSchema<undefined>; readonly sessionUrl: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>, undefined>; }, undefined>>; /** * Validate subscription data * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateSubscriptionData(data: unknown): v.SafeParseResult<v.ObjectSchema<{ readonly userId: v.StringSchema<undefined>; readonly tier: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>>; /** * Validate subscription claims * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateSubscriptionClaims(data: unknown): v.SafeParseResult<v.ObjectSchema<{ readonly tier: v.StringSchema<undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; readonly isDefault: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; }, undefined>>; /** * Validate webhook event * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateWebhookEvent(data: unknown): v.SafeParseResult<v.ObjectSchema<{ readonly id: v.StringSchema<undefined>; readonly type: v.StringSchema<undefined>; readonly data: v.ObjectSchema<{ readonly object: v.AnySchema; }, undefined>; readonly created: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>>; /** * Validate checkout session metadata * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCheckoutSessionMetadata(data: unknown): v.SafeParseResult<v.LooseObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly firebaseUid: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productType: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>>; /** * Schema for one-time payment products * Core fields only - no assumptions about integrations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const StripePaymentSchema: v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripePayment", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID (fixed pricing). Optional when using dynamic pricing. */ readonly priceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>, undefined>; /** Default amount in cents (dynamic pricing). Used when no priceId. */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name for Stripe checkout (dynamic pricing). */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Maximum allowed unit amount in cents. Security cap for client-provided amounts. */ readonly maxUnitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Duration is required">]>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>; /** * Schema for recurring subscription products * Core fields only - no assumptions about integrations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const StripeSubscriptionSchema: v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripeSubscription", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID. Required for subscriptions (price_data not supported for recurring). */ readonly priceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.PicklistSchema<["1month", "3months", "6months", "1year", "2years", "lifetime"], undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>; /** * Union schema for all product types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const ProductDeclarationSchema: v.VariantSchema<"type", [v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripePayment", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID (fixed pricing). Optional when using dynamic pricing. */ readonly priceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>, undefined>; /** Default amount in cents (dynamic pricing). Used when no priceId. */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name for Stripe checkout (dynamic pricing). */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Maximum allowed unit amount in cents. Security cap for client-provided amounts. */ readonly maxUnitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Duration is required">]>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>, v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripeSubscription", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID. Required for subscriptions (price_data not supported for recurring). */ readonly priceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.PicklistSchema<["1month", "3months", "6months", "1year", "2years", "lifetime"], undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>], undefined>; /** * Schema for product declarations object * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const ProductDeclarationsSchema: v.RecordSchema<v.StringSchema<undefined>, v.VariantSchema<"type", [v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripePayment", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID (fixed pricing). Optional when using dynamic pricing. */ readonly priceId: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>, undefined>; /** Default amount in cents (dynamic pricing). Used when no priceId. */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name for Stripe checkout (dynamic pricing). */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Maximum allowed unit amount in cents. Security cap for client-provided amounts. */ readonly maxUnitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Duration is required">]>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>, v.ObjectSchema<{ readonly type: v.LiteralSchema<"StripeSubscription", undefined>; readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Product name is required">]>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, "EUR">; /** Stripe price ID. Required for subscriptions (price_data not supported for recurring). */ readonly priceId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Stripe price ID is required">]>; readonly tier: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Tier is required">]>; readonly duration: v.PicklistSchema<["1month", "3months", "6months", "1year", "2years", "lifetime"], undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; }, undefined>], undefined>, undefined>; /** * Schema for frontend billing configuration (display only) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const StripeFrontConfigSchema: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{ readonly name: v.StringSchema<undefined>; readonly price: v.StringSchema<undefined>; readonly currency: v.StringSchema<undefined>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly features: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; /** Stripe price ID (fixed pricing). Optional for dynamic pricing products. */ readonly priceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Amount in cents (dynamic pricing). For display purposes. */ readonly unitAmount: v.OptionalSchema<v.NumberSchema<undefined>, undefined>; /** Product name (dynamic pricing). For display purposes. */ readonly productName: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; }, undefined>, undefined>; /** * Schema for backend billing configuration (with hooks) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const StripeBackConfigSchema: v.RecordSchema<v.StringSchema<undefined>, v.ObjectSchema<{ readonly type: v.PicklistSchema<["StripePayment", "StripeSubscription"], undefined>; readonly name: v.StringSchema<undefined>; readonly price: v.NumberSchema<undefined>; readonly currency: v.StringSchema<undefined>; /** Stripe price ID (fixed pricing). Optional for dynamic pricing products. */ readonly priceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Default amount in cents (dynamic pricing). */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name for Stripe checkout (dynamic pricing). */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Maximum allowed unit amount in cents. Security cap. */ readonly maxUnitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; readonly tier: v.StringSchema<undefined>; readonly duration: v.StringSchema<undefined>; readonly description: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; }, undefined>, undefined>; /** * Helper to validate frontend config at runtime * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateStripeFrontConfig(config: unknown): { [x: string]: { name: string; price: string; currency: string; description?: string | undefined; features?: string[] | undefined; priceId?: string | undefined; unitAmount?: number | undefined; productName?: string | undefined; allowPromotionCodes?: boolean | undefined; }; }; /** * Helper to validate backend config at runtime * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateStripeBackConfig(config: unknown): { [x: string]: { type: "StripePayment" | "StripeSubscription"; name: string; price: number; currency: string; priceId?: string | undefined; unitAmount?: number | undefined; productName?: string | undefined; maxUnitAmount?: number | undefined; tier: string; duration: string; description?: string | undefined; metadata?: { [x: string]: string; } | undefined; allowPromotionCodes?: boolean | undefined; }; }; /** * Validate all billing schemas * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateBillingSchemas(): { success: boolean; results: { createCheckoutSessionRequest: v.SafeParseResult<v.SchemaWithPipe<readonly [v.ObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Stripe price ID (fixed pricing mode) */ readonly priceId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Amount in cents (dynamic pricing mode) */ readonly unitAmount: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, undefined>; /** Product name shown on Stripe checkout (dynamic pricing mode) */ readonly productName: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>, undefined>; /** Currency code, defaults to 'eur' (dynamic pricing mode) */ readonly currency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.LengthAction<string, 3, "Currency must be 3-letter ISO code">]>, undefined>; readonly successUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly cancelUrl: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>; readonly customerEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly userEmail: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>, undefined>; readonly metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>; readonly allowPromotionCodes: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly mode: v.OptionalSchema<v.PicklistSchema<["payment", "subscription"], undefined>, undefined>; }, undefined>, v.CheckAction<{ userId?: string | undefined; productId?: string | undefined; priceId?: string | undefined; unitAmount?: number | undefined; productName?: string | undefined; currency?: string | undefined; successUrl: string; cancelUrl: string; customerEmail?: string | undefined; userEmail?: string | undefined; metadata?: { [x: string]: string; } | undefined; allowPromotionCodes?: boolean | undefined; mode?: "payment" | "subscription" | undefined; }, "Either priceId or (unitAmount + productName) is required">]>>; createCheckoutSessionResponse: v.SafeParseResult<v.ObjectSchema<{ readonly sessionId: v.StringSchema<undefined>; readonly sessionUrl: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>, undefined>; }, undefined>>; subscriptionData: v.SafeParseResult<v.ObjectSchema<{ readonly userId: v.StringSchema<undefined>; readonly tier: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>>; subscriptionClaims: v.SafeParseResult<v.ObjectSchema<{ readonly tier: v.StringSchema<undefined>; readonly subscriptionId: v.NullableSchema<v.StringSchema<undefined>, undefined>; readonly customerId: v.StringSchema<undefined>; readonly status: v.PicklistSchema<[string, ...string[]], undefined>; readonly subscriptionEnd: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>, undefined>; readonly cancelAtPeriodEnd: v.BooleanSchema<undefined>; readonly updatedAt: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; readonly isDefault: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; }, undefined>>; webhookEvent: v.SafeParseResult<v.ObjectSchema<{ readonly id: v.StringSchema<undefined>; readonly type: v.StringSchema<undefined>; readonly data: v.ObjectSchema<{ readonly object: v.AnySchema; }, undefined>; readonly created: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, undefined>]>; }, undefined>>; checkoutSessionMetadata: v.SafeParseResult<v.LooseObjectSchema<{ readonly userId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly firebaseUid: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly productType: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>>; }; }; /** * @fileoverview Billing Types * @description Type definitions for billing domain. Defines billing provider types, checkout modes, billing adapter interfaces, subscription types, and billing-related interfaces. * Uses unified FeatureStatus enum for feature state management. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** Billing provider types - Stripe only * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingProvider = 'stripe'; /** Unified checkout mode type used everywhere * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CheckoutMode = 'payment' | 'subscription'; /** Billing adapter interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BillingAdapter { createCheckoutSession(request: CreateCheckoutSessionRequest): Promise<CreateCheckoutSessionResponse>; getProvider(): Promise<BillingProvider>; isAvailable(): Promise<boolean>; } /** Billing event types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingEvent = { type: 'subscription_updated'; data: unknown; } | { type: 'payment_succeeded'; data: unknown; } | { type: 'payment_failed'; data: unknown; }; /** Payment method types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PaymentMethodType = 'card' | 'bank_account' | 'paypal' | 'apple_pay' | 'google_pay'; /** Payment method interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PaymentMethod { id: string; userId: string; type: PaymentMethodType; isDefault: boolean; last4?: string; brand?: string; expiryMonth?: number; expiryYear?: number; createdAt: string; updatedAt: string; } /** Billing provider configuration interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BillingProviderConfig { provider: BillingProvider; apiKey?: string; webhookSecret?: string; publishableKey?: string; testMode?: boolean; } /** Invoice interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Invoice { id: string; userId: string; amount: number; currency: string; status: 'draft' | 'open' | 'paid' | 'void' | 'uncollectible'; createdAt: string; dueDate?: string; paidAt?: string; description?: string; items: InvoiceItem[]; } /** * Invoice item interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface InvoiceItem { id: string; description: string; amount: number; quantity: number; unitPrice: number; } /** * Subscription interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Subscription { id: string; userId: string; status: 'active' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'past_due' | 'trialing' | 'unpaid'; currentPeriodStart: string; currentPeriodEnd: string; cancelAtPeriodEnd: boolean; canceledAt?: string; trialStart?: string; trialEnd?: string; createdAt: string; updatedAt: string; } /** * Stripe webhook event data * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeWebhookEvent { id: string; type: string; data: { /** Raw Stripe object payload — shape depends on event type */ object: Record<string, unknown>; }; created: number; livemode: boolean; pending_webhooks: number; request?: { id: string; idempotency_key?: string; }; } /** * Schema for creating checkout session */ /** * Schema for processing payment success */ /** * Checkout session creation request */ /** * Checkout session response */ /** * Refresh subscription request * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RefreshSubscriptionRequest { userId: string; } /** * Stripe provider interface for billing operations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeProvider { createCheckoutSession(params: { priceId?: string; /** Amount in cents (dynamic pricing mode, used with price_data) */ unitAmount?: number; /** Product name for Stripe checkout (dynamic pricing mode) */ productName?: string; /** Currency code, defaults to 'eur' */ currency?: string; userId: string; successUrl: string; cancelUrl: string; metadata?: Record<string, string>; customerEmail?: string; allowPromotionCodes?: boolean; }): Promise<CreateCheckoutSessionResponse>; getSubscription(userId: string): Promise<Subscription | null>; cancelSubscription(subscriptionId: string): Promise<boolean>; updateSubscription(subscriptionId: string, updates: Partial<Subscription>): Promise<Subscription>; } /** * Refresh subscription response * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RefreshSubscriptionResponse { success: boolean; subscription: Subscription; } /** * Process payment success request * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ProcessPaymentSuccessRequest { sessionId: string; } /** * Process payment success response * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ProcessPaymentSuccessResponse { success: boolean; sessionId: string; } /** * Billing-specific error codes for functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingErrorCode = 'unknown' | 'unauthenticated' | 'invalid_request' | 'stripe_error' | 'subscription_not_found' | 'checkout_session_not_found' | 'webhook_verification_failed' | 'rate_limit_exceeded' | 'insufficient_permissions' | 'invalid_webhook_signature' | 'checkout_blocked'; /** * Stripe checkout session creation request * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeCheckoutRequest { /** Stripe price ID (fixed pricing mode) */ priceId?: string; /** Amount in cents (dynamic pricing mode, used with price_data) */ unitAmount?: number; /** Product name for Stripe checkout (dynamic pricing mode) */ productName?: string; /** Currency code, defaults to 'eur' (dynamic pricing mode) */ currency?: string; /** User email for the subscription */ userEmail: string; /** URL to redirect to on successful payment */ successUrl: string; /** URL to redirect to on cancelled payment */ cancelUrl: string; /** Optional metadata to attach to the session */ metadata?: Record<string, string>; /** Customer email address */ customerEmail?: string; /** Whether to allow promotion codes */ allowPromotionCodes?: boolean; /** Trial period in days */ trialPeriodDays?: number; /** Collection method for the subscription */ collectionMethod?: 'charge_automatically' | 'send_invoice'; /** Payment method types to allow */ paymentMethodTypes?: string[]; /** Billing address collection requirement */ billingAddressCollection?: 'auto' | 'required'; /** Tax ID collection requirement */ taxIdCollection?: { enabled: boolean; }; /** Checkout mode - payment or subscription */ mode?: CheckoutMode; } /** * Stripe checkout session response * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeCheckoutResponse { /** Stripe session ID */ sessionId: string; /** URL to redirect the user to complete payment */ sessionUrl: string | null; /** Whether the session was created successfully */ success: boolean; /** Error message if creation failed */ error?: string; } /** * Stripe subscription data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeSubscriptionData { /** Stripe subscription ID */ id: string; /** Customer ID */ customer: string; /** Subscription status */ status: 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid'; /** Current period start timestamp */ current_period_start: number; /** Current period end timestamp */ current_period_end: number; /** Whether the subscription will cancel at period end */ cancel_at_period_end: boolean; /** When the subscription was canceled */ canceled_at?: number; /** Trial start timestamp */ trial_start?: number; /** Trial end timestamp */ trial_end?: number; /** When the subscription was created */ created: number; /** When the subscription was last updated */ updated: number; /** Subscription items */ items: { data: Array<{ id: string; price: { id: string; unit_amount: number; currency: string; recurring: { interval: 'day' | 'week' | 'month' | 'year'; interval_count: number; }; product: string; }; quantity: number; }>; }; /** Default payment method */ default_payment_method?: string; /** Collection method */ collection_method: 'charge_automatically' | 'send_invoice'; /** Days until due for invoices */ days_until_due?: number; /** Subscription metadata */ metadata: Record<string, string>; } /** * Stripe payment method data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripePaymentMethod { /** Stripe payment method ID */ id: string; /** Customer ID */ customer: string; /** Payment method type */ type: 'card' | 'bank_account' | 'us_bank_account' | 'sepa_debit' | 'ideal' | 'sofort' | 'bancontact' | 'p24' | 'giropay' | 'eps' | 'alipay' | 'wechat_pay'; /** Card details (if type is 'card') */ card?: { brand: 'amex' | 'diners' | 'discover' | 'jcb' | 'mastercard' | 'unionpay' | 'visa' | 'unknown'; country: string; exp_month: number; exp_year: number; fingerprint: string; funding: 'credit' | 'debit' | 'prepaid' | 'unknown'; last4: string; three_d_secure_usage?: { supported: boolean; }; wallet?: { type: 'amex_express_checkout' | 'apple_pay' | 'google_pay' | 'masterpass' | 'samsung_pay' | 'visa_checkout'; dynamic_last4?: string; }; }; /** Bank account details (if type is 'bank_account') */ bank_account?: { account_holder_type: 'individual' | 'company'; bank_name: string; country: string; currency: string; fingerprint: string; last4: string; routing_number: string; status: 'new' | 'validated' | 'verified' | 'verification_failed' | 'errored'; }; /** Billing details */ billing_details: { address?: { city?: string; country?: string; line1?: string; line2?: string; postal_code?: string; state?: string; }; email?: string; name?: string; phone?: string; }; /** When the payment method was created */ created: number; /** Whether this is the default payment method */ is_default?: boolean; /** Payment method metadata */ metadata: Record<string, string>; } /** * Stripe invoice data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeInvoice { /** Stripe invoice ID */ id: string; /** Customer ID */ customer: string; /** Invoice amount */ amount_due: number; /** Invoice amount paid */ amount_paid: number; /** Invoice amount remaining */ amount_remaining: number; /** Currency code */ currency: string; /** Invoice status */ status: 'draft' | 'open' | 'paid' | 'void' | 'uncollectible'; /** When the invoice was created */ created: number; /** When the invoice is due */ due_date?: number; /** When the invoice was paid */ paid_at?: number; /** When the invoice was voided */ voided_at?: number; /** Invoice description */ description?: string; /** Invoice line items */ lines: { data: Array<{ id: string; amount: number; currency: string; description?: string; quantity: number; unit_amount: number; price?: { id: string; unit_amount: number; currency: string; recurring?: { interval: 'day' | 'week' | 'month' | 'year'; interval_count: number; }; product: string; }; }>; }; /** Invoice metadata */ metadata: Record<string, string>; /** Subscription ID (if applicable) */ subscription?: string; /** Total amount */ total: number; /** Tax amount */ tax?: number; /** Tax rate applied */ tax_rate?: number; } /** * Stripe customer data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeCustomer { /** Stripe customer ID */ id: string; /** Customer email */ email?: string; /** Customer name */ name?: string; /** Customer description */ description?: string; /** Customer phone */ phone?: string; /** Customer address */ address?: { city?: string; country?: string; line1?: string; line2?: string; postal_code?: string; state?: string; }; /** Customer balance */ balance: number; /** Currency code */ currency?: string; /** When the customer was created */ created: number; /** When the customer was last updated */ updated: number; /** Customer metadata */ metadata: Record<string, string>; /** Default payment method */ default_source?: string; /** Whether the customer is deleted */ deleted?: boolean; /** Customer tax IDs */ tax_ids?: { data: Array<{ id: string; type: 'eu_vat' | 'br_cnpj' | 'br_cpf' | 'gb_vat' | 'nz_gst' | 'au_abn' | 'au_arn' | 'in_gst' | 'no_vat' | 'za_vat' | 'ch_vat' | 'mx_rfc' | 'sg_uen' | 'ru_inn' | 'ru_kpp' | 'ca_bn' | 'hk_br' | 'es_cif' | 'tw_vat' | 'th_vat' | 'jp_cn' | 'jp_rn' | 'li_uid' | 'my_itn' | 'us_ein' | 'kr_brn' | 'ca_gst_hst' | 'ca_qst' | 'ca_pst_bc' | 'ca_pst_mb' | 'ca_pst_sk' | 'my_sst' | 'sg_gst' | 'ae_trn' | 'cl_tin' | 'sa_vat' | 'id_npwp'; value: string; }>; }; } /** * Stripe product data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeProduct { /** Stripe product ID */ id: string; /** Product name */ name: string; /** Product description */ description?: string; /** Product images */ images: string[]; /** Product metadata */ metadata: Record<string, string>; /** Whether the product is active */ active: boolean; /** When the product was created */ created: number; /** When the product was last updated */ updated: number; /** Product type */ type: 'service' | 'good'; /** Product URL */ url?: string; /** Product statement descriptor */ statement_descriptor?: string; /** Product unit label */ unit_label?: string; /** Product tax code */ tax_code?: string; } /** * Stripe price data structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripePrice { /** Stripe price ID */ id: string; /** Product ID */ product: string; /** Price amount in cents */ unit_amount: number; /** Currency code */ currency: string; /** Price type */ type: 'one_time' | 'recurring'; /** Recurring interval (if type is 'recurring') */ recurring?: { interval: 'day' | 'week' | 'month' | 'year'; interval_count: number; trial_period_days?: number; usage_type: 'licensed' | 'metered'; }; /** Whether the price is active */ active: boolean; /** When the price was created */ created: number; /** When the price was last updated */ updated: number; /** Price metadata */ metadata: Record<string, string>; /** Price nickname */ nickname?: string; /** Price tiers (for graduated pricing) */ tiers?: Array<{ up_to: number | 'inf'; unit_amount: number; flat_amount?: number; }>; /** Price tiers mode */ tiers_mode?: 'graduated' | 'volume'; /** Price transform quantity */ transform_quantity?: { divide_by: number; round: 'up' | 'down'; }; /** Price lookup key */ lookup_key?: string; } /** * Result of a beforeCheckout hook invocation. * Allows blocking checkout or overriding pricing before Stripe session creation. */ interface BeforeCheckoutResult { /** Whether checkout is allowed to proceed */ allowed: boolean; /** Reason for blocking (shown in error response) */ reason?: string; /** Optional overrides applied to checkout options before Stripe session creation */ overrides?: Partial<Pick<CheckoutOptions, 'unitAmount' | 'productName'>>; } /** * Hook called before Stripe checkout session creation. * Use for ownership checks, status validation, server-resolved pricing. * * @param userId - Authenticated user ID * @param options - Checkout options from the client request * @param metadata - Request metadata (sanitized) * @returns Whether to allow checkout, optional reason, optional overrides */ type BeforeCheckoutHook = (userId: string, options: CheckoutOptions, metadata: Record<string, string>) => Promise<BeforeCheckoutResult>; /** * Checkout options for Stripe checkout session * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CheckoutOptions { /** Stripe price ID (fixed pricing mode) */ priceId?: string; /** Amount in cents (dynamic pricing mode) */ unitAmount?: number; /** Product name for Stripe checkout (dynamic pricing mode) */ productName?: string; /** Currency code, defaults to 'eur' (dynamic pricing mode) */ currency?: string; mode: 'payment' | 'subscription'; successUrl?: string; cancelUrl?: string; metadata?: Record<string, string>; allowPromotionCodes?: boolean; } /** * Billing API type - complete interface for useStripeBilling hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BillingAPI { /** * Unified feature status - single source of truth for billing state. * Replaces deprecated `loading` boolean flag. * - `initializing`: Billing is loading/initializing * - `ready`: Billing fully operational * - `degraded`: Billing unavailable (feature not installed/consent not given) * - `error`: Billing encountered error */ status: FeatureStatus; error: string | null; /** * Whether a billing operation is in progress. * For redirect operations (checkout, portal), the hook automatically shows * a fullscreen overlay with operation-specific messaging. */ loading: boolean; checkout: (options: CheckoutOptions) => Promise<StripeCheckoutResponse>; cancelSubscription: () => Promise<{ success: boolean; endsAt: string; }>; changePlan: (newPriceId: string, billingConfigKey: string) => Promise<{ success: boolean; }>; refreshStatus: () => Promise<void>; openCustomerPortal: (returnUrl?: string) => Promise<void>; clearError: () => void; isAvailable: boolean; } /** * Frontend billing configuration type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripeFrontConfig = v.InferOutput<typeof StripeFrontConfigSchema>; /** * Backend billing configuration type with hooks * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripeBackConfig = { [key: string]: { type: 'StripePayment' | 'StripeSubscription'; name: string; price: number; currency: string; /** Stripe price ID (fixed pricing). Optional for dynamic pricing products. */ priceId?: string; /** Default amount in cents (dynamic pricing). */ unitAmount?: number; /** Product name for Stripe checkout (dynamic pricing). */ productName?: string; /** Maximum allowed unit amount in cents. Security cap for client-provided amounts. */ maxUnitAmount?: number; tier: string; duration: string; description?: string; metadata?: Record<string, string>; allowPromotionCodes?: boolean; onPurchaseSuccess?: (userId: string, metadata: Record<string, string>) => Promise<void>; onPurchaseFailure?: (userId: string, metadata: Record<string, string>) => Promise<void>; onSubscriptionCreated?: (userId: string, metadata: Record<string, string>) => Promise<void>; onSubscriptionRenewed?: (userId: string, metadata: Record<string, string>) => Promise<void>; onSubscriptionCancelled?: (userId: string, metadata: Record<string, string>) => Promise<void>; onPaymentFailed?: (userId: string, metadata: Record<string, string>) => Promise<void>; /** Hook called before Stripe checkout session creation. Can block or override pricing. */ beforeCheckout?: BeforeCheckoutHook; }; }; /** * Stripe configuration interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeConfig { /** Stripe secret key for server-side operations */ secretKey: string; /** Stripe publishable key for client-side operations */ publishableKey: string; /** Stripe webhook secret for webhook verification */ webhookSecret: string; /** Whether to use test mode */ testMode: boolean; /** API version to use */ apiVersion?: string; /** Maximum number of retries for failed requests */ maxNetworkRetries?: number; /** Request timeout in milliseconds */ timeout?: number; /** Additional configuration options */ options?: { /** Whether to enable telemetry */ telemetry?: boolean; /** App information */ appInfo?: { name: string; version: string; url?: string; }; }; } /** * @fileoverview Authentication Types * @description Type definitions for authentication domain. Defines authentication partner types, user types, session types, and authentication-related interfaces. * Uses unified FeatureStatus enum for feature state management. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Authentication method type * 'popup' - Opens OAuth popup window (better for dev/localhost) * 'redirect' - Redirects to OAuth provider (better for production) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthMethod = 'redirect' | 'popup'; /** * Email verification status type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type EmailVerificationStatus = 'verified' | 'pending' | 'error'; /** * Email verification status constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const EMAIL_VERIFICATION_STATUS: { readonly VERIFIED: "verified"; readonly PENDING: "pending"; readonly ERROR: "error"; }; /** * Auth partner result interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthPartnerResult extends PartnerResult { partnerId: AuthPartnerId; metadata?: Record<string, any>; } /** * Partner state constants - Single source of truth for partner states * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const AUTH_PARTNER_STATE: { readonly IDLE: "idle"; readonly LOADING: "loading"; readonly ERROR: "error"; readonly AUTHENTICATED: "authenticated"; }; /** * Auth partner state type - simple string constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthPartnerState = (typeof AUTH_PARTNER_STATE)[keyof typeof AUTH_PARTNER_STATE]; /** * Error type that supports Firebase errors and custom errors with code property * Note: DoNotDevError is avoided for account linking to preserve Firebase error codes * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthError = (Error & { code?: string; }) | null; /** * Contains authorization and user preference information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UserProfile { /** The user's unique identifier (matches AuthUser.id) */ userId: string; /** The user's display name */ displayName?: string; /** The user's email address */ email?: string; /** The user's profile photo URL */ photoURL?: string; /** Additional profile data */ [key: string]: unknown; } /** * Factory function to create default user profile * @param userId - User ID for the profile * @returns Default user profile with minimal required fields * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createDefaultUserProfile(userId: string): UserProfile; /** * Provides a unified interface for accessing all user data * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UserContext { /** Core authentication data */ auth: AuthUser; /** User profile information */ profile: UserProfile; /** Subscription information */ subscription: UserSubscription; } /** * Extends SubscriptionClaims with calculated or derived subscription status information. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SubscriptionInfo extends SubscriptionClaims { /** Indicates if the subscription is currently active (typically based on subscriptionEnd) */ isActive: boolean; /** Number of days remaining in the subscription, or null if not applicable */ daysRemaining: number | null; /** Array of feature IDs available to the user based on their subscription */ features: string[]; } /** * Result type for the useAuthPartner hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthPartnerHookResult { /** Current authentication state from the partner */ partnerState: AuthPartnerState; /** Whether a connection operation is in progress */ isConnecting: boolean; /** Whether the partner is currently connected */ isConnected: boolean; /** Current error message, or null if no error */ error: Error | null; /** Function to connect to this partner */ connect: (options?: { redirectUri?: string; onSuccess?: (result: AuthPartnerResult) => void; onError?: (error: Error) => void; }) => Promise<void>; /** Function to disconnect from this partner */ disconnect: () => Promise<boolean>; } /** * Result type for the useAuthCore hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthCoreHookResult { user: AuthUser | null; authenticated: boolean; loading: boolean; error: string | null; signIn: (email: string, password: string) => Promise<void>; signUp: (email: string, password: string) => Promise<void>; signOut: () => Promise<void>; resetPassword: (email: string) => Promise<void>; updateProfile: (updates: Partial<AuthUser>) => Promise<void>; } /** * Result type for the useAuthToken hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthTokenHookResult { token: string | null; status: TokenStatus; expiresAt: Date | null; refreshToken: () => Promise<string | null>; getAccessToken: () => Promise<string | null>; } /** * Result type for the useSubscription hook * NOTE: subscription is now always present * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SubscriptionHookResult { subscription: SubscriptionInfo; refreshSubscription: () => Promise<void>; hasFeature: (featureId: string) => boolean; hasTier: (requiredTier: string) => boolean; } /** * Result type for the useAdminCheck hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AdminCheckHookResult { isAdmin: boolean; isLoading: boolean; } /** * Result type for the useNetworkStatus hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface NetworkStatusHookResult { online: boolean; connectionType: string; } /** * Options for redirect behavior * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthRedirectOptions { /** If true, only allow admin users */ adminOnly?: boolean; /** If true, require email verification */ requireEmailVerification?: boolean; /** If true, require subscription */ requireSubscription?: boolean; /** Redirect URL if conditions not met */ redirectTo?: string; } /** * Result type for the useAuthRedirect hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthRedirectHookResult { authenticated: boolean; isAdmin: boolean; isEmailVerified: boolean; hasSubscription: boolean; shouldRedirect: boolean; redirectTo?: string; } /** * Result type for the useEmailVerification hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EmailVerificationHookResult { isVerified: boolean; isLoading: boolean; error: string | null; sendVerificationEmail: () => Promise<void>; checkVerificationStatus: () => Promise<void>; } /** * Result type for the useFeatureAccess hook * NOTE: subscription is now always present * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FeatureAccessHookResult { hasFeature: (featureId: string) => boolean; hasTier: (requiredTier: string) => boolean; subscription: SubscriptionInfo; } /** * Result type for the useFeature hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FeatureHookResult { enabled: boolean; } /** * Result type for the useTierAccess hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TierAccessHookResult { enabled: boolean; } /** * Represents a feature that can be enabled or disabled for users, * often tied to a specific subscription tier. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Feature { /** Unique identifier for the feature */ id: string; /** Human-readable name for the feature */ name: string; /** Description of what the feature does */ description?: string; /** Whether the feature is currently enabled */ enabled: boolean; /** Required subscription tier for this feature */ requiredTier?: string; } /** * Stores information specific to a user's identity from a particular authentication provider. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UserProviderData { /** The unique identifier for the authentication provider (e.g., 'google.com') */ providerId: string; /** The user's unique identifier within this provider */ uid: string; /** The user's email address from this provider */ email?: string | null; /** The user's display name from this provider */ displayName?: string | null; /** The user's photo URL from this provider */ photoURL?: string | null; /** The user's phone number from this provider */ phoneNumber?: string | null; /** Additional provider-specific data */ [key: string]: any; } /** * Defines custom claims specifically for administrative users. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AdminClaims { /** Flag indicating if the user has administrative privileges */ isAdmin: boolean; /** Optional role or permission level */ role?: string; /** Optional department or team */ department?: string; /** Additional admin-specific claims */ [key: string]: any; } /** * Information stored in sessionStorage for account linking flow * Firebase 12.3 stores credentials, we only store UI state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AccountLinkingInfo { email: string; existingProvider: AuthPartnerId; newProvider: string; timestamp: number; } /** * Represents the outcome of an attempt to link an additional authentication provider. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AccountLinkResult { /** Indicates whether the overall linking process was successful */ success: boolean; /** The provider that was linked */ provider: string; /** Error message if the linking failed */ error?: string; /** Additional data about the linked account */ data?: Record<string, any>; } /** * Authentication state interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthState { user: AuthUser | null; authenticated: boolean; userId: string | null; loading: boolean; error: AuthError; userProfile: UserProfile | null; userSubscription: UserSubscription | null; partnerStates: Record<AuthPartnerId, AuthPartnerState>; partnerError: { partnerId: AuthPartnerId; error: AuthError; } | null; emailVerification: { status: EmailVerificationStatus; error?: string; }; /** * Password reset recovery mode. * Set by provider when PASSWORD_RECOVERY event fires (Supabase) * or when oobCode is detected in URL (Firebase). * Components use this to show the "set new password" UI. */ passwordResetPending: boolean; authService: unknown; /** * Unified feature status - single source of truth for auth state. * Replaces deprecated boolean flags (initialized, authStateChecked). * * **Lifecycle timeline:** * 1. Store created → `status: 'initializing'` (show loader) * 2. Auth service init + first callback → `status: 'ready'` (normal operation) * 3. If feature disabled/unavailable → `status: 'degraded'` (protected routes redirect with error) * 4. If init fails → `status: 'error'` (protected routes redirect with error) * * **Guard behavior:** * - `degraded` + protected route → redirect to auth route with `?error=auth_unavailable` * - `error` + protected route → redirect to auth route with `?error=auth_error` * - `initializing` → show loader, don't redirect * - `ready` → perform normal auth checks * * @see FEATURE_STATUS for possible values */ status: FeatureStatus; } /** * Authentication actions interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthActions { setPartnerState: (partnerId: AuthPartnerId, state: AuthPartnerState, error?: AuthError) => void; getPartnerState: (partnerId: AuthPartnerId) => AuthPartnerState; clearAllPartnerStates: () => void; setAuthenticated: (user: AuthUser, subscription: UserSubscription, profile: UserProfile) => void; setUnauthenticated: () => void; setAuthLoading: (loading: boolean) => void; setAuthError: (error: AuthError) => void; clearAuthError: () => void; /** Set unified status - single source of truth */ setStatus: (status: FeatureStatus) => void; getCustomClaim: (claim: string) => unknown; getCustomClaims: () => Record<string, unknown>; emailVerification: { status: EmailVerificationStatus; error?: string; }; setPasswordResetPending: (pending: boolean) => void; setLoading: (loading: boolean) => void; setError: (error: AuthError) => void; clearError: () => void; reset: () => void; setAuthService: (authService: unknown) => void; getCustomClaimLocal: (claim: string) => unknown; getCustomClaimsLocal: () => Record<string, unknown>; setEmailVerificationStatus: (status: EmailVerificationStatus, error?: string) => void; setUserProfile: (profile: UserProfile) => void; setUserSubscription: (subscription: UserSubscription) => void; } /** * Authentication context value interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthContextValue { /** The currently authenticated user object, or null if unauthenticated */ user: AuthUser | null; /** Whether the user is currently authenticated */ authenticated: boolean; /** Whether an authentication operation is in progress */ loading: boolean; /** Current error message, or null if no error */ error: string | null; /** The user's role */ role: UserRole; /** The user's subscription information, or null if unauthenticated or not yet loaded */ subscription: SubscriptionInfo | null; /** Current authentication token */ token: string | null; /** Token status */ tokenStatus: TokenStatus; /** When the token expires */ tokenExpiresAt: Date | null; /** Sign in with email and password */ signIn: (email: string, password: string) => Promise<void>; /** Sign up with email and password */ signUp: (email: string, password: string) => Promise<void>; /** Sign out the current user */ signOut: () => Promise<void>; /** Reset password for email */ resetPassword: (email: string) => Promise<void>; /** Update user profile */ updateProfile: (updates: Partial<AuthUser>) => Promise<void>; /** Refresh the authentication token */ refreshToken: () => Promise<string | null>; /** Get the current access token */ getAccessToken: () => Promise<string | null>; /** Check if user has a specific role */ hasRole: (role: UserRole) => boolean; /** Check if user has access to a feature */ hasFeature: (featureId: string) => boolean; /** Check if user has access to a tier */ hasTier: (requiredTier: string) => boolean; } /** * Props for the AuthProvider component * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthProviderProps { /** Child components that will have access to the authentication context */ children: ReactNode; } /** * Result of an authentication operation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthResult { /** The authenticated user */ user: AuthUser; /** Whether the operation was successful */ success: boolean; /** Whether this is a new user (for sign-up operations) */ isNewUser?: boolean; /** Error message if the operation failed */ error?: string; } /** * Get user auth status response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface GetUserAuthStatusResponse { userId: string; isAuthenticated: boolean; customClaims: Record<string, any>; hasClaims: boolean; claimCount: number; } /** * Get custom claims response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface GetCustomClaimsResponse { claims: Record<string, any>; userId: string; } /** * Set custom claims response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SetCustomClaimsResponse { success: boolean; userId: string; claims: Record<string, any>; } /** * Remove custom claims response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RemoveCustomClaimsResponse { success: boolean; userId: string; removedClaims: string[]; remainingClaims: Record<string, any>; } /** * Function to unsubscribe from auth state changes * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type UnsubscribeFn = () => void; /** * Optional metadata passed to signup methods. * Stored in provider-specific user metadata (Supabase `raw_user_meta_data`, Firebase user doc). */ interface SignUpMetadata { /** ISO-8601 timestamp of GDPR consent acceptance */ gdpr_consent_at?: string; /** Version identifier of the ToS document accepted */ gdpr_tos_version?: string; /** Extensible for consumer-specific fields */ [key: string]: unknown; } /** * Authentication provider interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthProvider { /** * Initialize the auth provider */ initialize(): Promise<void>; /** * Get the current user */ getCurrentUser(): Promise<AuthUser | null>; /** * Sign in with email and password */ signInWithEmailAndPassword(email: string, password: string): Promise<AuthUser>; /** * Sign up with email and password */ createUserWithEmailAndPassword(email: string, password: string, metadata?: SignUpMetadata): Promise<AuthUser>; /** * Sign out the current user */ signOut(): Promise<void>; /** * Reset password for email */ sendPasswordResetEmail(email: string): Promise<void>; /** * Update user profile */ updateUserProfile(updates: Partial<AuthUser>): Promise<void>; /** * Get the current access token */ getAccessToken(): Promise<string | null>; /** * Refresh the authentication token */ refreshToken(): Promise<string | null>; /** * Subscribe to auth state changes */ onAuthStateChanged(callback: (user: AuthUser | null) => void): UnsubscribeFn; /** * Check if user has a specific role */ hasRole(role: UserRole): Promise<boolean>; /** * Check if user has access to a feature */ hasFeature(featureId: string): Promise<boolean>; /** * Check if user has access to a tier */ hasTier(requiredTier: string): Promise<boolean>; signInWithEmail(email: string, password: string): Promise<AuthResult | null>; createUserWithEmail(email: string, password: string, metadata?: SignUpMetadata): Promise<AuthResult | null>; signInWithPartner(partnerId: AuthPartnerId, method?: AuthMethod): Promise<AuthResult | null>; linkWithPartner(partnerId: AuthPartnerId, method?: AuthMethod): Promise<AuthResult | null>; signInWithGoogleCredential(credential: string): Promise<AuthResult | null>; updatePassword(newPassword: string): Promise<void>; /** * Verify a password reset code from the email callback link. * Returns the email address associated with the code. * @returns email address, or null if code is invalid/expired */ verifyPasswordResetCode?(code: string): Promise<string | null>; /** * Confirm a password reset with the code from the email and the new password. * After success, user can sign in with the new password. */ confirmPasswordReset?(code: string, newPassword: string): Promise<void>; /** * Get the password reset redirect path for this provider. * Used to build the redirect URL in password reset emails. */ getPasswordResetRedirectUrl?(): string; sendEmailVerification(): Promise<void>; sendSignInLinkToEmail(email: string, actionCodeSettings?: { url: string; handleCodeInApp: boolean; }): Promise<void>; signInWithEmailLink(email: string, emailLink?: string): Promise<AuthResult | null>; isSignInWithEmailLink(emailLink?: string): boolean; getEmailVerificationStatus(): Promise<{ status: string; }>; isEmailVerificationEnabled(): Promise<boolean>; reauthenticateWithPassword(password: string): Promise<void>; reauthenticateWithProvider(partnerId: AuthPartnerId, method?: AuthMethod): Promise<void>; deleteAccount(password?: string): Promise<void>; /** * Set session persistence (remember me). * Provider-specific: Firebase uses browserLocal/browserSession persistence, * Supabase uses cookie duration, etc. * No-op if the provider doesn't support persistence control. * * @param remember - true for persistent session, false for session-only */ setRememberMe?(remember: boolean): Promise<void>; } /** * Information about a token including its status and expiration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TokenInfo { /** The actual token string or null if not available */ token: string | null; /** Current status of the token */ status: TokenStatus; /** When the token expires, or null if not available */ expiresAt: Date | null; /** When the token was last refreshed */ lastRefreshed?: Date; /** Number of seconds until expiration */ expiresIn?: number; } /** * Auth API type - complete interface for useAuth hook * * This interface defines all properties available through useAuth('propertyName'). * Properties are categorized by their behavior: * - **State** (reactive): Re-renders when value changes * - **Methods** (stable): Never re-renders, always same reference * - **Computed** (derived): Re-renders when dependencies change * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthAPI { user: AuthUser | null; userProfile: UserProfile | null; userSubscription: UserSubscription | null; loading: boolean; error: AuthError | null; emailVerification: { status: string; error?: string; }; passwordResetPending: boolean; partnerError: { partnerId: AuthPartnerId; error: string; } | null; /** * Unified feature status - single source of truth for auth state. * Replaces deprecated boolean flags. See AuthState.status for detailed lifecycle. */ status: FeatureStatus; getPartnerState: (partnerId: AuthPartnerId) => string; setPartnerState: (partnerId: AuthPartnerId, state: string, error?: string) => void; hasRole: (role: string) => Promise<boolean>; hasTier: (tier: string) => Promise<boolean>; hasFeature: (feature: string) => Promise<boolean>; getCustomClaims: () => Record<string, unknown>; getCustomClaim: (claim: string) => unknown; signInWithEmail: (email: string, password: string) => Promise<AuthResult | null>; createUserWithEmail: (email: string, password: string, metadata?: SignUpMetadata) => Promise<AuthResult | null>; signInWithPartner: (partnerId: AuthPartnerId, method?: string) => Promise<AuthResult | null>; linkWithPartner: (partnerId: AuthPartnerId, method?: string) => Promise<AuthResult | null>; signInWithGoogleCredential: (credential: string) => Promise<AuthResult | null>; signOut: () => Promise<void>; sendPasswordResetEmail: (email: string) => Promise<void>; updatePassword: (newPassword: string) => Promise<void>; verifyPasswordResetCode: (code: string) => Promise<string | null>; confirmPasswordReset: (code: string, newPassword: string) => Promise<void>; sendEmailVerification: () => Promise<void>; getEmailVerificationStatus: () => Promise<{ status: string; }>; isEmailVerificationEnabled: () => Promise<boolean>; sendSignInLinkToEmail: (email: string, settings?: any) => Promise<void>; signInWithEmailLink: (email: string, link?: string) => Promise<AuthResult | null>; isSignInWithEmailLink: (link?: string) => boolean; getCurrentUser: () => Promise<AuthUser | null>; reauthenticateWithPassword: (password: string) => Promise<void>; reauthenticateWithProvider: (partnerId: AuthPartnerId, method?: AuthMethod) => Promise<void>; deleteAccount: (password?: string) => Promise<void>; setRememberMe: (remember: boolean) => Promise<void>; isAuthenticated: boolean; userRole: string; userTier: string; /** * Capability-based access control object. * Usage: `const can = useAuth('can'); if (can.edit('licenses')) { ... }` */ can: CanAPI; isAvailable: boolean; } /** * Capability-based access control API * * Provides granular permission checks based on resources and custom capabilities. * Permissions are derived from userProfile.permissions array (format: "resource:action") * and user role (admin bypasses all checks). * * @example * ```typescript * const can = useAuth('can'); * if (can.view('dashboard')) { ... } * if (can.edit('licenses')) { ... } * if (can.perform('approve-budget', { amount: 5000 })) { ... } * ``` * * @version 0.1.0 * @since 0.0.3 * @author AMBROISE PARK Consulting */ interface CanAPI { /** Check if user can navigate to a route (replaces canAccess) */ navigate: (config: PageAuth | false) => boolean; /** Check if user can view a resource */ view: (resource: string) => boolean; /** Check if user can edit a resource */ edit: (resource: string) => boolean; /** Check if user can delete a resource */ delete: (resource: string) => boolean; /** Check if user can create a resource */ create: (resource: string) => boolean; /** Check custom capability with optional context */ perform: (action: string, context?: Record<string, any>) => boolean; /** Check if user has specific permission string */ has: (permission: string) => boolean; } /** * @fileoverview CRUD Constants * @description Constants for CRUD domain. Defines visibility levels for entity fields and supported field types for entities. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Visibility levels for entity fields (runtime constants) * Controls who can SEE this field in responses * Matches USER_ROLES hierarchy + technical + hidden + owner * * - guest: Everyone (even unauthenticated) * - user: Authenticated users (users see guest + user fields) * - admin: Admins only (admins see guest + user + admin fields) * - super: Super admins only (see all non-technical fields) * - technical: System fields (shown as read-only in edit forms, admins+ only) * - hidden: Never exposed to client (passwords, tokens, API keys) * - owner: Visible only when request.auth.uid matches one of entity.ownership.ownerFields on the document */ declare const VISIBILITY: { readonly GUEST: "guest"; readonly USER: "user"; readonly ADMIN: "admin"; readonly SUPER: "super"; readonly TECHNICAL: "technical"; readonly HIDDEN: "hidden"; readonly OWNER: "owner"; }; /** * Editable levels for entity fields (runtime constants) * Controls who can MODIFY this field * - true: Anyone who can see the field * - false: Nobody (read-only) * - 'user': Authenticated users+ (role hierarchy) * - 'admin': Admins+ (role hierarchy) * - 'super': Super admins only * - 'create-only': Editable on create, read-only after * - 'generated': DB-generated (excluded from forms and write schemas) * - 'computed': UI-computed (excluded from forms, included in writes) */ declare const EDITABLE: { /** Anyone who can see the field (follows visibility) */ readonly TRUE: true; /** Read-only display in forms */ readonly FALSE: false; /** Authenticated users+ */ readonly USER: "user"; /** Admin+ */ readonly ADMIN: "admin"; /** Super only */ readonly SUPER: "super"; /** Editable on create, read-only after */ readonly CREATE_ONLY: "create-only"; /** DB-generated column (PostgreSQL GENERATED ALWAYS) — excluded from forms and write schemas */ readonly GENERATED: "generated"; /** UI-computed field (derived from other fields) — excluded from forms, included in writes */ readonly COMPUTED: "computed"; }; /** * Default access levels for entity operations * Opinionated framework defaults: * - Read is public by default (Level 0) * - Write operations require Admin by default (Level 2) */ declare const DEFAULT_ENTITY_ACCESS: { readonly create: "admin"; readonly read: "guest"; readonly update: "admin"; readonly delete: "admin"; }; /** * Supported field types for entities (runtime constants) * Useful for UI renderers and documentation. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Supported filter operators for query where clauses. * Use these in framework code for consistency. Consumers can use string literals * (e.g. operator: 'in') — CrudOperator accepts them; no need to import CRUD_OPERATORS. */ declare const CRUD_OPERATORS: { readonly EQ: "=="; readonly NEQ: "!="; readonly LT: "<"; readonly LTE: "<="; readonly GT: ">"; readonly GTE: ">="; readonly IN: "in"; readonly NOT_IN: "not-in"; readonly ARRAY_CONTAINS: "array-contains"; readonly ARRAY_CONTAINS_ANY: "array-contains-any"; }; /** Union of operator string literals. Consumer apps may use e.g. operator: 'in' without importing CRUD_OPERATORS. */ type CrudOperator = (typeof CRUD_OPERATORS)[keyof typeof CRUD_OPERATORS]; /** Order direction for query orderBy */ declare const ORDER_DIRECTION: { readonly ASC: "asc"; readonly DESC: "desc"; }; /** Sort direction for query orderBy clauses. */ type OrderDirection = (typeof ORDER_DIRECTION)[keyof typeof ORDER_DIRECTION]; /** Schema type for list queries (list vs listCard) */ declare const LIST_SCHEMA_TYPE: { readonly LIST: "list"; readonly LIST_CARD: "listCard"; }; /** Schema variant for list queries (table vs card grid). */ type ListSchemaType = (typeof LIST_SCHEMA_TYPE)[keyof typeof LIST_SCHEMA_TYPE]; declare const FIELD_TYPES: readonly ["address", "array", "avatar", "badge", "boolean", "checkbox", "color", "combobox", "date", "datetime-local", "document", "documents", "duration", "email", "field-array", "file", "files", "gdprConsent", "geopoint", "hidden", "iban", "image", "images", "map", "month", "multiselect", "number", "currency", "price", "password", "radio", "reference", "range", "rating", "reset", "richtext", "select", "submit", "switch", "tel", "text", "textarea", "time", "timestamp", "url", "week", "year"]; /** * @fileoverview Condition Types * @description Pure type definitions for the condition engine. * Runtime evaluation and builder logic live in @donotdev/utils. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** Supported comparison operators */ type ConditionOperator = 'equals' | 'notEquals' | 'in' | 'notIn' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'exists' | 'notExists' | 'contains'; /** A single condition: field + operator + value */ interface ConditionNode { readonly type: 'condition'; readonly field: string; readonly operator: ConditionOperator; readonly value?: unknown; } /** Logical group of conditions */ interface ConditionGroup { readonly type: 'group'; readonly logic: 'and' | 'or'; readonly conditions: ReadonlyArray<ConditionExpression>; } /** A condition expression — the serializable data model for conditions */ type ConditionExpression = ConditionNode | ConditionGroup; /** Result of evaluating all conditions for a field */ interface ConditionResult { /** Whether the field should be visible (default: true) */ visible: boolean; /** Whether the field should be disabled (default: false) */ disabled: boolean; /** Whether the field is required (default: false, overrides static validation.required) */ required: boolean; /** Whether the field is readonly (default: false) */ readonly: boolean; } /** * Structural interface satisfied by ConditionBuilder (defined in @donotdev/utils). * Allows types to reference builders without depending on the runtime class. */ interface ConditionBuilderLike { readonly expression: ConditionExpression; } /** Accepted condition input — either a raw expression or a ConditionBuilder */ type ConditionInput = ConditionExpression | ConditionBuilderLike; /** Conditions that can be attached to a field */ interface ConditionalBehavior { /** Condition for field visibility — if false, field is hidden and excluded from validation */ visible?: ConditionInput; /** Condition for field disabled state */ disabled?: ConditionInput; /** Condition for dynamic required — evaluated at runtime */ required?: ConditionInput; /** Condition for readonly state */ readonly?: ConditionInput; } /** * @fileoverview Schema-Related Type Definitions * @description Types for schema validation using Valibot. Defines entity schemas, field types, and validation rules. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Visibility level for entity fields * Controls who can SEE a field - hierarchical (each level sees levels below) * * Hierarchy: guest < user < admin < super * * - 'guest': Everyone (even unauthenticated) * - 'user': Authenticated users (see guest + user fields) * - 'admin': Admins (see guest + user + admin fields) * - 'super': Super admins (see guest + user + admin + super fields) * - 'technical': System fields (admins+ only, shown as read-only in forms) * - 'hidden': Never exposed to client (passwords, tokens, API keys) * * Override with `editable` for write permissions. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Visibility = (typeof VISIBILITY)[keyof typeof VISIBILITY]; /** * Editable level for entity fields * Controls who can MODIFY a field * - true: Anyone who can see the field * - false: Nobody (read-only, still shown in form) * - 'admin': Admin+ can edit (role hierarchy) * - 'super': Super only * - 'create-only': Editable on create, read-only after * - 'generated': DB-generated — hidden from forms, stripped from writes * - 'computed': UI-computed (derived from other fields) — hidden from forms, included in writes * * Custom role strings (e.g. future hierarchy keys) are accepted the same way as * {@link FieldType}: `(string & {})` keeps known literals distinguishable for * narrowing; plain `| string` would collapse to `boolean | string` and break * comparisons to `EDITABLE.GENERATED` / `EDITABLE.COMPUTED`. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Editable = (typeof EDITABLE)[keyof typeof EDITABLE] | (string & {}); /** * Entity-level access configuration * Controls who can perform CRUD operations on the entity * * Uses role hierarchy: guest (0) < user (1) < admin (2) < super (3) * Higher roles inherit access to lower-level operations. * * @default DEFAULT_ENTITY_ACCESS (read: 'guest', create/update/delete: 'admin') * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EntityAccessConfig { /** Minimum role required to create entities */ create?: UserRole; /** Minimum role required to read entities (field visibility still applies) */ read?: UserRole; /** Minimum role required to update entities */ update?: UserRole; /** Minimum role required to delete entities */ delete?: UserRole; } /** Type derived from DEFAULT_ENTITY_ACCESS for type safety */ type EntityAccessDefaults = typeof DEFAULT_ENTITY_ACCESS; /** * Single condition for public read/update in Firestore rules. * Joined with && when publicCondition is an array. */ interface EntityOwnershipPublicCondition { field: string; op: string; value: string | boolean | number; } /** * Ownership configuration for stakeholder access (marketplace-style entities). * When set, drives Firestore rule condition generation, list/listCard query constraints, * and visibility: 'owner' field masking. * * @example * ```typescript * ownership: { * ownerFields: ['providerId', 'customerId'], * publicCondition: [ * { field: 'status', op: '==', value: 'available' }, * { field: 'isApproved', op: '==', value: true }, * ], * } * ``` */ interface EntityOwnershipConfig { /** Document fields whose value is a user id (e.g. providerId, customerId) */ ownerFields: string[]; /** Conditions joined with && for "public" read (e.g. status == 'available') */ publicCondition?: EntityOwnershipPublicCondition[]; } /** * Supported field types for entities * These determine the UI components and validation rules used for each field * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FieldType = (typeof FIELD_TYPES)[number] | (string & {}); /** * Built-in field type union (same as FieldType). Used internally to distinguish * framework field types from custom types registered via registerFieldType(). */ type BuiltInFieldType = (typeof FIELD_TYPES)[number]; /** * Map of custom field type names to their option shapes for `options.fieldSpecific`. * Augment this interface in your app so entity definitions get typed options for custom types. * * @example * ```ts * // In your app (e.g. types/crud.d.ts or next to your entity): * import '@donotdev/core'; * declare module '@donotdev/core' { * interface CustomFieldOptionsMap { * 'custom-address': { extractZipCode?: boolean }; * 'repairOperations': { maxItems?: number }; * } * } * ``` * Then in entity fields: `type: 'custom-address'`, `options: { fieldSpecific: { extractZipCode: true } }` is type-checked. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CustomFieldOptionsMap { } /** * Additional UI-specific options for field rendering * @template T - The field type (built-in or custom string). Custom types use CustomFieldOptionsMap for fieldSpecific. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UIFieldOptions<T extends string = FieldType> { /** The section under which this field should be grouped */ section?: string; /** Placeholder text */ placeholder?: string; /** Whether to show a clear button */ clearable?: boolean; /** Additional classes to apply to the field */ className?: string; /** Icon to show before the field */ prefixIcon?: ComponentType; /** Icon to show after the field */ suffixIcon?: ComponentType; /** Custom validation message overrides */ messages?: { required?: string; pattern?: string; min?: string; max?: string; minLength?: string; maxLength?: string; }; /** Step value for numeric inputs */ step?: T extends 'number' | 'range' ? number : never; /** * i18n key for display formatting. Replaces the raw value in lists/cards/display views. * The formatter calls `t(displayKey, { value })`. Supports i18next array-key fallback. * Use `{{value}}` in key names for dynamic lookup (interpolated before `t()` call). * * @example Single key: `displayKey: 'fields.size_display'` → locale `"{{value}}m²"` → "20m²" * @example Array fallback: `displayKey: ['floor_{{value}}', 'fields.floor_display']` * → tries `floor_4`, falls back to `fields.floor_display`: `"{{value}}th floor"` → "4th floor" */ displayKey?: string | string[]; /** * Custom display value resolver. Overrides type formatter and displayKey for display views. * Receives the field value, the full item, and the translation function — * useful for cross-field conditional display with i18n. * Return `null` to hide the field for that item. Return a string to display it. * * @example * ```typescript * // Hide date for reserved/signed, show "Available" for past dates * displayValue: (value, item, t) => { * if (item.status === 'reserved' || item.status === 'signed') return null; * return value <= today ? t('status.available_now') : String(value); * } * ``` */ displayValue?: (value: unknown, item: Record<string, unknown>, t: (key: string, options?: Record<string, unknown>) => string) => string | null; /** Whether to show value label for range inputs */ showValue?: T extends 'range' ? boolean : never; /** Field specific options based on field type. Custom types: augment CustomFieldOptionsMap. */ fieldSpecific?: T extends keyof CustomFieldOptionsMap ? CustomFieldOptionsMap[T] : T extends 'file' | 'image' | 'files' | 'images' | 'document' | 'documents' ? { /** File types to accept (e.g., 'image/*', '.pdf') */ accept?: string; /** Maximum file size in bytes */ maxSize?: number; /** Whether to allow multiple files */ multiple?: boolean; /** Storage path prefix for uploads (e.g., 'apartments') */ storagePath?: string; } : T extends 'geopoint' ? { /** Default zoom level for map */ defaultZoom?: number; /** Default center position for map */ defaultCenter?: { lat: number; lng: number; }; } : T extends 'map' ? { /** Label for the key input */ keyLabel?: string; /** Label for the value input */ valueLabel?: string; /** Label for the add button */ addLabel?: string; } : T extends 'reference' ? { /** Field to display from the referenced entity */ displayField?: string; /** Multiple fields to join as label (e.g. ['first_name', 'last_name'] → "John Doe") */ labelFields?: string[]; /** Fields to search in the referenced entity */ searchFields?: string[]; /** Maximum number of items to preload */ preloadLimit?: number; } : T extends 'tel' ? { /** Default country code */ defaultCountry?: string; /** Whether to show country flags */ showFlags?: boolean; /** Preferred country codes to show at the top of the list (e.g., ['FR', 'US', 'GB']) */ preferredCountries?: string[]; /** Custom list of country codes to show (if provided, only these countries are shown) */ countries?: string[]; } : T extends 'address' ? { /** * Whether to enable Google Maps autocomplete (default: false) * Requires env var: VITE_GOOGLE_MAPS_API_KEY (Vite) or NEXT_PUBLIC_GOOGLE_MAPS_API_KEY (Next.js) */ enableGoogleMaps?: boolean; /** Whether to extract district code for Paris addresses */ extractDistrictCode?: boolean; } : T extends 'combobox' ? { /** Enable creating new values by typing */ creatable?: boolean; } : T extends 'switch' ? { /** Label shown when switch is off/unchecked */ uncheckedLabel?: string; /** Label shown when switch is on/checked */ checkedLabel?: string; /** Value stored when switch is off (default: false) */ uncheckedValue?: string | boolean; /** Value stored when switch is on (default: true) */ checkedValue?: string | boolean; } : T extends 'gdprConsent' ? { /** Path to privacy policy page (default: '/legal/privacy') */ privacyPolicyPath?: string; /** Path to terms of use page (default: '/legal/terms') */ termsPath?: string; } : Record<string, unknown>; } /** * Picture type for image fields * Represents uploaded image with full and thumbnail URLs */ interface Picture { fullUrl: string; thumbUrl: string; } /** * FileAsset type for generic file uploads (documents, any files) * Used by FileFieldComponent and DocumentFieldComponent */ interface FileAsset { /** Download URL for the file */ url: string; /** Original filename */ filename: string; /** File size in bytes */ size: number; /** MIME type (e.g., 'application/pdf') */ mimeType?: string; /** ISO timestamp when uploaded */ uploadedAt?: string; } /** * Maps field types to their corresponding TypeScript types * Used for type-safe form handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FieldTypeToValue = { address: { formatted_address: string; latitude: number; longitude: number; [key: string]: any; }; array: any[]; avatar: string; badge: string; boolean: boolean; checkbox: boolean; combobox: string; color: string; date: string; 'datetime-local': string; document: FileAsset | null; documents: FileAsset[]; email: string; 'field-array': Record<string, unknown>[]; file: FileAsset | null; files: FileAsset[]; geopoint: { lat: number; lng: number; }; hidden: string; iban: string; image: Picture | null; images: Picture[]; map: Record<string, any>; month: string; multiselect: string[]; number: number; price: { amount: number; currency?: string; vatIncluded?: boolean; discountPercent?: number; }; password: string; radio: string; reference: string; range: number; reset: never; select: string; submit: never; tel: string; text: string; textarea: string; time: string; timestamp: string; switch: string | boolean; url: string; week: string; year: number; }; /** * Gets the value type for a specific field type * @template T - The field type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ValueTypeForField<T extends string> = T extends keyof FieldTypeToValue ? FieldTypeToValue[T] : unknown; /** * Any valid field value - includes built-in types plus custom registered types * Uses `unknown` since consumers can register custom field types via RegisterFieldType */ type AnyFieldValue = unknown; /** * Entity record type - a record where values are valid field values * Accepts unknown since consumers can register custom field types */ type EntityRecord = Record<string, AnyFieldValue>; /** * Enhanced validation rules with type checking * @template T - The field type * * @example * ```typescript * // Select field with dropdown options * validation: { * required: true, * options: [ * { value: 'active', label: 'Active' }, * { value: 'inactive', label: 'Inactive' } * ] * } * * // Text field with length validation * validation: { * required: true, * minLength: 3, * maxLength: 100 * } * * // Number field with range validation * validation: { * required: true, * min: 0, * max: 1000 * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ValidationRules<T extends string = FieldType> { /** Whether the field is required */ required?: boolean; /** Minimum value (for number fields) */ min?: T extends 'number' | 'range' | 'year' ? number : never; /** Maximum value (for number fields) */ max?: T extends 'number' | 'range' | 'year' ? number : never; /** Minimum length (for text fields) */ minLength?: T extends 'text' | 'textarea' | 'password' | 'email' | 'url' | 'tel' | 'iban' ? number : never; /** Maximum length (for text fields) */ maxLength?: T extends 'text' | 'textarea' | 'password' | 'email' | 'url' | 'tel' | 'iban' ? number : never; /** Regex pattern (for text fields) */ pattern?: T extends 'text' | 'textarea' | 'password' | 'email' | 'url' | 'tel' | 'iban' ? string : never; /** * Options for select, multiselect, and radio fields. * Can be: * - An array of option objects * - A function that returns an array (receives form values for dynamic options) * * For year fields, use `type: 'year'`: * ```typescript * year: { * type: 'year', * visibility: 'guest', * validation: { * required: true, * min: 1900, // Optional: defaults to 1900 * max: 2100 // Optional: defaults to current year + 10 * } * } * ``` * * @example * ```typescript * // Static array * options: [ * { value: 'active', label: 'Active' }, * { value: 'inactive', label: 'Inactive' } * ] * * // Dynamic function (depends on other field values) * options: (formValues) => { * return getModelsForMake(formValues.make); * } * ``` */ options?: T extends 'select' | 'multiselect' | 'radio' | 'combobox' ? Array<{ value: string; label: string; }> | ((formValues?: Record<string, any>) => Array<{ value: string; label: string; }>) : never; /** Collection name for reference fields */ reference?: T extends 'reference' ? string : never; /** Whether the field is nullable */ nullable?: boolean; /** * Custom Valibot schema for this field * * When provided, this schema is used directly instead of the registry lookup. * This makes the entity the single source of truth for custom field schemas, * working everywhere (client + server) without separate registrations. * * @example * ```typescript * repairs: { * type: 'repairOperations', * visibility: 'admin', * validation: { * schema: v.array(v.object({ * operation: v.string(), * cost: v.number() * })) * } * } * ``` */ schema?: v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>; } /** * Form step configuration for multi-step forms * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FormStep { /** Step title displayed in navigation */ title: string; /** Step description (optional) */ description?: string; /** Fields to include in this step */ fields: string[]; /** Whether this step is required */ required?: boolean; /** Custom validation for this step */ validation?: { /** Custom validation function */ validate?: (data: any) => boolean | string; /** Error message if validation fails */ message?: string; }; } /** * Condition for dynamic field visibility * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FieldCondition { /** Field name to check */ field: string; /** Comparison operator */ operator: 'equals' | 'not-equals' | 'contains' | 'greater-than' | 'less-than' | 'exists' | 'not-exists'; /** Value to compare against */ value?: any; /** For complex conditions, use a function */ evaluate?: (formData: any) => boolean; } /** * Dynamic form rule for showing/hiding fields * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DynamicFormRule { /** Condition that triggers this rule */ condition: FieldCondition | FieldCondition[]; /** Fields to show when condition is met */ showFields?: string[]; /** Fields to hide when condition is met */ hideFields?: string[]; /** Fields to disable when condition is met */ disableFields?: string[]; /** Fields to enable when condition is met */ enableFields?: string[]; } /** * Form configuration for advanced form features * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FormConfig { /** Form type */ type?: 'single' | 'multi-step' | 'dynamic' | 'wizard'; /** Steps for multi-step forms */ steps?: FormStep[]; /** Dynamic field rules */ rules?: DynamicFormRule[]; /** Whether to persist form state (auto-save drafts) */ persist?: boolean; /** Persistence configuration */ persistence?: { /** Storage key prefix */ key?: string; /** Auto-save interval in milliseconds */ autoSaveInterval?: number; /** Whether to show save indicator */ showSaveIndicator?: boolean; }; /** Form layout configuration */ layout?: { /** Number of columns for field layout */ columns?: 1 | 2 | 3; /** Whether to show field labels */ showLabels?: boolean; /** Whether to show field hints */ showHints?: boolean; /** Custom CSS classes */ className?: string; }; /** Form behavior configuration */ behavior?: { /** Whether to show progress indicator */ showProgress?: boolean; /** Whether to allow step navigation */ allowStepNavigation?: boolean; /** Whether to validate on step change */ validateOnStepChange?: boolean; /** Whether to show step numbers */ showStepNumbers?: boolean; }; } /** * Definition of a single entity field * @template T - The field type for type-safe validation and value inference * * @example * ```typescript * // Text field - TypeScript knows value is string * name: { * type: 'text', * visibility: 'user', * validation: { required: true, minLength: 3 } * } * * // Select field with dropdown options * status: { * type: 'select', * visibility: 'user', * validation: { * required: true, * options: [ * { value: 'active', label: 'Active' }, * { value: 'inactive', label: 'Inactive' } * ] * } * } * ``` * * **Note:** For `select`, `multiselect`, and `radio` fields, dropdown options must be defined in `validation.options` as an array of `{ value: string, label: string }` objects. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EntityField<T extends string = FieldType> { /** Field identifier - required for form binding */ name: string; /** The field type, which determines the UI component and validation */ type: T; /** * Who can SEE this field * - 'guest': Everyone (even unauthenticated) * - 'user': Authenticated users only (users see both guest and user fields) * - 'admin': Admins only * - 'technical': Internal/system fields (shown as read-only in edit forms) * - 'hidden': Never shown in UI, only exists in DB (passwords, tokens, API keys) */ visibility: Visibility; /** * Who can MODIFY this field * - true: Anyone who can see the field (default) * - false: Nobody (read-only display) * - 'admin': Only admins can edit * - 'create-only': Editable on create, read-only after */ editable?: Editable; /** Validation rules for this field. For select/multiselect/radio fields, include `options` array here. */ validation?: ValidationRules<T>; /** Whether the field is internationalized */ i18n?: boolean; /** Display label for the field */ label: string; /** Hint text to display under the field */ hint?: string; /** Field dependencies for dynamic forms */ dependsOn?: { /** Field name this field depends on */ field: string; /** Value that should trigger this field to show */ value?: ValueTypeForField<FieldType>; /** Custom condition function */ condition?: (formData: Record<string, unknown>) => boolean; }; /** Field grouping for layout */ group?: { /** Group name */ name: string; /** Group title */ title?: string; /** Group description */ description?: string; /** Whether group is collapsible */ collapsible?: boolean; /** Whether group is collapsed by default */ collapsed?: boolean; }; /** * Dynamic conditions for field behavior based on other field values. * Controls visibility, disabled, required, and readonly states at runtime. * * @example * ```typescript * conditions: { * visible: when('productType').equals('car'), * required: when('productType').equals('car'), * } * ``` */ conditions?: ConditionalBehavior; /** UI-specific configuration for field rendering */ options?: UIFieldOptions<T>; } /** * Base fields that all entities should have * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseEntityFields { /** Unique identifier for the entity */ id: EntityField<'text'>; /** When the entity was created */ createdAt: EntityField<'timestamp'>; /** When the entity was last updated */ updatedAt: EntityField<'timestamp'>; /** Who created the entity */ createdById: EntityField<'reference'>; /** Who last updated the entity */ updatedById: EntityField<'reference'>; /** * Publication status for draft/publish/delete workflow * - 'draft': Document is incomplete, hidden from non-admin * - 'available': Document is published and visible (default) * - 'deleted': Soft-deleted, hidden from non-admin * - Consumer can extend with additional statuses (e.g., 'reserved', 'sold') */ status: EntityField<'select'>; } /** * Consumer `fields` merged with {@link BaseEntityFields} — same keys {@link defineEntity} returns. * * @version 0.1.0 * @since 0.2.0 */ type MergedEntityFieldMap<F extends Record<string, EntityField>> = F & BaseEntityFields; /** * Merged field map with `readonly` stripped from keys — improves assignability of * `defineEntity` results to widened {@link AnyEntity} props. * * @version 0.1.0 * @since 0.2.0 */ type MutableMergedEntityFieldMap<F extends Record<string, EntityField>> = { -readonly [K in keyof MergedEntityFieldMap<F>]: MergedEntityFieldMap<F>[K]; }; /** * Default merged field map when an entity is not parameterized with a literal field map. * * @version 0.1.0 * @since 0.2.0 */ type EntityFieldMapDefault = Record<string, EntityField> & BaseEntityFields; /** * CRUD/cache document row inferred from an entity `fields` map (SSOT with `defineEntity` literals). * Intersects {@link Record} so rows satisfy `T extends Record<string, unknown>` (bulk, PII, adapters). * * @version 0.1.0 * @since 0.2.0 */ type EntityRowFromFields<F extends Record<string, EntityField>> = { [K in keyof F]: F[K] extends EntityField<infer FT> ? FT extends keyof FieldTypeToValue ? FieldTypeToValue[FT] : unknown : unknown; } & Record<string, unknown>; /** * Unique key constraint definition for entity deduplication * Enables automatic checking for duplicates on create/update operations * * @example * ```typescript * // Single field unique key with findOrCreate * uniqueKeys: [{ fields: ['email'], findOrCreate: true }] * * // Composite unique key * uniqueKeys: [{ fields: ['vin', 'make'], skipForDrafts: true }] * * // Multiple keys (OR logic - either can identify) * uniqueKeys: [ * { fields: ['email'], findOrCreate: true }, * { fields: ['phone'], findOrCreate: true } * ] * ``` * * @version 0.1.0 * @since 0.0.5 * @author AMBROISE PARK Consulting */ interface UniqueKeyDefinition { /** Field names that together form the unique key (single or composite) */ fields: string[]; /** Custom error message when duplicate is found */ errorMessage?: string; /** Skip validation for draft documents (default: false) */ skipForDrafts?: boolean; /** * Return existing document instead of throwing error on duplicate (default: false) * When true, create operations will return the existing document if a match is found */ findOrCreate?: boolean; } /** * SOC2 security configuration for an entity. * Zero-config path: omit this entirely for MVP — add it when going to production/SOC2 audit. * * When a `SecurityContext` is passed to `CrudService`, these options control: * - Which fields are encrypted at rest (PII) * - Whether CRUD mutations are audit-logged (default: true) * - Entity-level rate limit overrides * - MFA requirement for a given role tier * - Data retention for automated purge scheduling * * @example * ```typescript * security: { * piiFields: ['email', 'phone', 'ssn'], * requireMfa: 'admin', * retention: { days: 365 }, * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SecurityEntityConfig { /** * Field names to encrypt at rest using AES-256-GCM. * Requires `piiSecret` in `DndevSecurityConfig`. * Only string field values are encrypted; other types are skipped silently. */ piiFields?: string[]; /** * Whether to emit audit log entries for all CRUD mutations on this entity. * @default true (when SecurityContext is provided) */ auditLog?: boolean; /** * Override rate limits for this entity (uses global defaults if omitted). */ rateLimit?: { writes?: number; reads?: number; windowSeconds?: number; }; /** * Enforce MFA for users at or above this role attempting mutations. * The adapter must verify MFA status from the auth token/session. */ requireMfa?: UserRole; /** * Data retention policy — documents older than `days` are flagged for purge. * Integrate with `PrivacyManager.shouldPurge()` in a scheduled function. */ retention?: { days: number; }; } /** * Multi-tenancy scope configuration for entities * Enables automatic scoping of data by tenant/company/workspace * * @example * ```typescript * const clientEntity = defineEntity({ * name: 'Client', * collection: 'clients', * scope: { field: 'companyId', provider: 'company' }, * fields: { ... } // No need to manually define companyId * }); * ``` * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ interface ScopeConfig { /** * Field name that stores the scope ID (e.g., 'companyId', 'tenantId', 'workspaceId') * This field will be auto-added to the entity with type 'reference' */ field: string; /** * Name of the scope provider registered with registerScopeProvider() * The provider function returns the current scope ID from app state * @example 'company', 'tenant', 'workspace' */ provider: string; /** * Collection being referenced (optional, defaults to field name without 'Id' suffix + 's') * @example 'companies' for field 'companyId' */ collection?: string; } /** * Slot-based card layout for listCardFields. * Maps entity field names to card slots (title, subtitle, content, footer). */ interface ListCardLayout { /** Fields rendered as the card title (joined with titleSeparator) */ title?: string[]; /** * Separator used to join multiple title field values. * @default ' ' * @example `titleSeparator: ' - '` → "Paris 20e arr. - 20m²" */ titleSeparator?: string; /** Fields rendered as the card subtitle */ subtitle?: string[]; /** Fields rendered in the card body (supports images) */ content?: string[]; /** Fields rendered in the card footer */ footer?: string[]; } /** * Definition of a business entity without base fields * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BusinessEntity<out F extends Record<string, EntityField> = Record<string, EntityField>> { /** Name of the entity */ name: string; /** Firestore collection name */ collection: string; /** * i18n namespace for translations (defaults to `entity-${name.toLowerCase()}`) * @example "entity-car", "entity-product" * @default `entity-${name.toLowerCase()}` */ namespace?: string; /** * Multi-tenancy scope configuration (optional) * When set, the scope field is auto-added and CRUD operations auto-inject/filter by scope * * @example * ```typescript * scope: { field: 'companyId', provider: 'company' } * ``` */ scope?: ScopeConfig; /** * Stakeholder ownership configuration (optional). * When set, drives Firestore rule condition (read/update), list/listCard query constraints, * and visibility: 'owner' field masking. Use for marketplace-style entities (e.g. schedules: * public when available, private to partner/customer when booked). * * @example * ```typescript * ownership: { * ownerFields: ['providerId', 'customerId'], * publicCondition: [{ field: 'status', op: '==', value: 'available' }], * } * ``` */ ownership?: EntityOwnershipConfig; /** Field definitions - name and label are required */ fields: F; /** Form configuration for advanced forms */ form?: FormConfig; /** * Fields to include in admin list responses (optional). * Used by EntityList for optimized admin table queries. * If not specified, all visible fields are returned. * 'id' is always included automatically. * * @example * ```typescript * listFields: ['id', 'make', 'model', 'status', 'createdAt'] * ``` */ listFields?: string[]; /** * Fields to include in public card list responses. * Accepts a flat array (auto-layout) or a slot-based `ListCardLayout` object. * * Each field value is formatted via `formatValue()` using its registered display formatter. * For `'number'` fields, use `unit` and `suffix` field options for rich display — no custom * type needed: * - `unit: 'm²'` → "20m²" (appended directly, no space) * - `suffix: 'fields.rent_suffix'` → "700€ charges comprises" (i18n key, space-separated) * * Use `titleSeparator` in `ListCardLayout` to control how multiple title fields are joined * (default `' '`). * * @example * ```typescript * // Flat — auto-slots first field as title, rest as content * listCardFields: ['images', 'make', 'price', 'year'] * * // Slot-based — explicit card layout with separator * listCardFields: { * titleSeparator: ' - ', * title: ['district_code', 'size'], // e.g. "Paris 20e arr. - 20m²" * subtitle: ['rent'], // e.g. "700€ charges comprises" * content: ['pictures', 'nearby_stations'], * } * ``` */ listCardFields?: string[] | ListCardLayout; /** * Entity-level access control configuration. * Defines minimum role required for each CRUD operation. * Uses role hierarchy: guest (0) < user (1) < admin (2) < super (3) * * Defaults (via defineEntity): * - read: 'guest' (public read, field visibility handles sensitive data) * - create/update/delete: 'admin' * * @example * ```typescript * // Public inquiry form * access: { create: 'guest', read: 'admin' } * * // Members-only content * access: { read: 'user' } * ``` */ access?: EntityAccessConfig; /** * Unique key constraints for deduplication * Checked during create/update operations * * - Single field: `[{ fields: ['email'] }]` * - Composite: `[{ fields: ['vin', 'make'] }]` * - Multiple keys (OR): `[{ fields: ['email'] }, { fields: ['phone'] }]` * * @example * ```typescript * // Customer: email OR phone identifies (findOrCreate behavior) * uniqueKeys: [ * { fields: ['email'], findOrCreate: true }, * { fields: ['phone'], findOrCreate: true } * ] * * // Car: VIN is unique, skip for drafts * uniqueKeys: [{ fields: ['vin'], skipForDrafts: true }] * ``` */ uniqueKeys?: UniqueKeyDefinition[]; /** * SOC2 security configuration for this entity (optional — zero-config MVP path). * When a `SecurityContext` is provided to `CrudService`, these settings control * PII encryption, audit logging, rate limits, MFA enforcement, and retention. * * @example * ```typescript * security: { * piiFields: ['email', 'phone'], * requireMfa: 'admin', * retention: { days: 365 }, * } * ``` */ security?: SecurityEntityConfig; /** * Client-side search config for `useCrudList`/`useCrudCardList` `searchQuery` option. * If omitted, all text-like visible fields are searched automatically. * * @example * ```typescript * search: { fields: ['name', 'description', 'sku'] } * ``` */ search?: { fields?: string[]; }; /** * Default client-side sort for list hooks. * Applied when no explicit `clientSort` option is passed and no `orderBy` in `queryOptions`. * Pass `clientSort: null` in hook options to disable. * * @example * ```typescript * defaultSort: { field: 'createdAt', direction: 'desc' } * ``` */ defaultSort?: { field: string; direction?: 'asc' | 'desc'; }; } /** * Complete entity definition including base fields * Created by defineEntity() which merges defaults * * Extends BusinessEntity but overrides optional properties to required: * - namespace: always computed (defaults to `entity-${name.toLowerCase()}`) * - access: always merged with defaults * - fields: includes base fields (id, createdAt, etc.) * - scope: preserved if provided (for multi-tenancy) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Entity<out F extends Record<string, EntityField> = EntityFieldMapDefault> extends Omit<BusinessEntity<F>, 'access' | 'namespace'> { /** Field definitions including base fields */ fields: F; /** Access configuration with defaults applied (always present after defineEntity) */ access: Required<EntityAccessConfig>; /** i18n namespace for translations (always present after defineEntity, defaults to `entity-${name.toLowerCase()}`) */ namespace: string; /** Multi-tenancy scope configuration (preserved from BusinessEntity if provided) */ scope?: ScopeConfig; } /** * Document row type for an entity from {@link defineEntity} — use with `useCrud`, `bulk`, and list hooks. * * @version 0.1.0 * @since 0.2.0 */ /** * Widened entity type for props and APIs that accept any `defineEntity()` result * without casting to default {@link Entity}. * * @version 0.1.0 * @since 0.2.0 */ type AnyEntity = Entity<Record<string, EntityField>>; /** * Inferred document row for an entity. Always includes `id` so rows are valid for * lists, keys, and `Record<string, any>`-shaped component props even when `E` is * the widened {@link AnyEntity} (`fields` is only a string index signature). */ type InferEntityRow<E extends AnyEntity> = EntityRowFromFields<E['fields']> & { id: string; }; /** * Unified metadata structure for all schemas (CRUD, Functions, etc.) * Consolidates different metadata patterns into one DRY interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SchemaMetadata { /** Firestore collection name */ collection: string; /** Entity name (for CRUD schemas) */ entity?: string; /** Form configuration (for CRUD schemas) */ form?: FormConfig; /** Fields that should be unique within the collection (for function validation) */ uniqueFields?: Array<{ field: string; errorMessage?: string; }>; /** * Unique key constraints from entity definition * Used by backend CRUD functions for deduplication */ uniqueKeys?: UniqueKeyDefinition[]; /** Custom validation function (for function validation) */ customValidate?: (data: Record<string, any>, operation: 'create' | 'update') => Promise<void>; } /** * Unified schema type that includes DoNotDev metadata * @template T - The entity/data type * * Unified schema type for all DoNotDev schemas * Uses Valibot's BaseSchema for validation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type dndevSchema<T> = v.BaseSchema<unknown, T, v.BaseIssue<unknown>> & { metadata: SchemaMetadata; }; /** * Interface for database uniqueness validation * This abstraction allows for plugging in any database implementation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UniqueConstraintValidator { /** * Checks if a value would cause a duplicate in a given collection * @param collection - The collection/table name * @param field - The field name to check * @param value - The field value to check for uniqueness * @param currentDocId - The current document ID (for updates) * @returns Whether a duplicate exists */ checkDuplicate: (collection: string, field: string, value: any, currentDocId?: string) => Promise<boolean>; } /** * Schema for creating an entity * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const createEntitySchema: v.ObjectSchema<{ readonly collection: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Collection name is required">]>; readonly data: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; readonly idempotencyKey: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>; /** * Schema for getting an entity * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const getEntitySchema: v.ObjectSchema<{ readonly collection: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Collection name is required">]>; readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Entity ID is required">]>; }, undefined>; /** * Schema for updating an entity * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const updateEntitySchema: v.ObjectSchema<{ readonly collection: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Collection name is required">]>; readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Entity ID is required">]>; readonly data: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; readonly merge: v.OptionalSchema<v.BooleanSchema<undefined>, false>; }, undefined>; /** * Schema for deleting an entity * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const deleteEntitySchema: v.ObjectSchema<{ readonly collection: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Collection name is required">]>; readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Entity ID is required">]>; }, undefined>; /** * Schema for listing entities. * * Default limit is **1000** (server-enforced max: 1000). * For collections larger than 1000 items, use server-side pagination * (`pagination='server'` on EntityList, or cursor-based `startAfter` in hooks). * * @example * // Fetch up to 1000 items (default) * { collection: 'products' } * * @example * // Fetch 200 items * { collection: 'products', limit: 200 } * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const listEntitiesSchema: v.ObjectSchema<{ readonly collection: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Collection name is required">]>; readonly limit: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 1000, undefined>]>, 1000>; readonly offset: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, 0>; readonly orderBy: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly orderDirection: v.OptionalSchema<v.PicklistSchema<["asc", "desc"], undefined>, "desc">; readonly where: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{ readonly field: v.StringSchema<undefined>; readonly operator: v.PicklistSchema<["==", "!=", "<", "<=", ">", ">=", "array-contains", "in", "not-in"], undefined>; readonly value: v.UnknownSchema; }, undefined>, undefined>, undefined>; }, undefined>; /** * Create entity request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CreateEntityRequest = v.InferOutput<typeof createEntitySchema>; /** * Get entity request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type GetEntityRequest = v.InferOutput<typeof getEntitySchema>; /** * Update entity request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type UpdateEntityRequest = v.InferOutput<typeof updateEntitySchema>; /** * Delete entity request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type DeleteEntityRequest = v.InferOutput<typeof deleteEntitySchema>; /** * List entities request type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ListEntitiesRequest = v.InferOutput<typeof listEntitiesSchema>; /** * Create entity response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CreateEntityResponse { success: boolean; id: string; data: Record<string, any>; } /** * Get entity response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface GetEntityResponse { success: boolean; data: Record<string, any> | null; } /** * Update entity response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UpdateEntityResponse { success: boolean; id: string; data: Record<string, any>; } /** * Delete entity response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DeleteEntityResponse { success: boolean; id: string; } /** * List entities response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ListEntitiesResponse { success: boolean; data: Record<string, any>[]; total: number; hasMore: boolean; } /** * @fileoverview CRUD Types * @description Type definitions for CRUD domain. Defines entity types, field types, and CRUD-related interfaces. * Uses unified FeatureStatus enum for feature state management. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Payload for create flows (`add`, bulk `inserts`) before the document has a * stable `id` (server- or client-generated). Matches runtime: optimistic add * mints a temp id; the create schema validates this shape. * * @version 0.1.0 * @since 0.2.0 */ type CrudCreateInput<T> = T extends Record<string, unknown> ? Omit<T, 'id'> : Record<string, unknown>; /** * CRUD API type - complete interface for useCrud hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CrudAPI<T = unknown> { /** * Unified feature status - single source of truth for CRUD state. * - `initializing`: CRUD is loading/initializing * - `ready`: CRUD fully operational * - `degraded`: CRUD unavailable (feature not installed/consent not given) * - `error`: CRUD encountered error */ status: FeatureStatus; /** Current data (from get/subscribe) */ data: T | null; /** Loading state for async operations */ loading: boolean; /** Last error encountered */ error: Error | null; /** Fetch single document by ID */ get: (id: string) => Promise<T | null>; /** Set/replace document by ID */ set: (id: string, data: T, options?: { showSuccessToast?: boolean; }) => Promise<void>; /** Partial update document by ID */ update: (id: string, data: Partial<T>, options?: { showSuccessToast?: boolean; }) => Promise<void>; /** Delete document by ID */ delete: (id: string, options?: { showSuccessToast?: boolean; }) => Promise<void>; /** Add new document (auto-generated ID) */ add: (data: CrudCreateInput<T>, options?: { showSuccessToast?: boolean; }) => Promise<string>; /** Query collection with filters */ query: (options: QueryOptions) => Promise<T[]>; /** Subscribe to document changes */ subscribe: (id: string, callback: (data: T | null, error?: Error) => void) => () => void; /** Subscribe to collection changes */ subscribeToCollection: (options: QueryOptions, callback: (data: T[], error?: Error) => void) => () => void; /** Invalidate cache for this collection (TanStack Query) */ invalidate: () => Promise<void>; /** Whether CRUD is available and operational */ isAvailable: boolean; /** * Cross-collection atomic bulk write. One optimistic pass, one toast, * coordinated rollback. Batches with `dependsOn` run after their * dependencies; independent batches run in parallel. */ bulkAcross?: (batches: BulkAcrossBatch[], options?: { showSuccessToast?: boolean; }) => Promise<BulkAcrossResult>; } /** * Base props for entity templates * @template T - The form values type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EntityTemplateProps<T extends FieldValues> { /** The DoNotDev schema for the entity */ schema: dndevSchema<T>; /** Optional overrides for field configuration */ fieldOverrides?: Partial<Record<keyof T, Partial<EntityField>>>; } /** * Column definition for list views * @template T - The item type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ColumnDef<T extends FieldValues> { /** Key in the data object */ key: keyof T; /** Display label */ label: string; /** Optional custom render function */ render?: (value: T[keyof T], row: T) => ReactNode; } /** * Input shape for a bulk CRUD operation. All three fields are optional — callers * include only the buckets they need. Items are processed in input order per * bucket and returned in the same order in {@link BulkResult}. * * Semantics (enforced by the service, not the adapter): * - Atomic: all ops succeed or none do. * - Collision rejection: an id appearing in both `updates` and `deletes`, or both * `inserts` and `updates`, fails up-front with {@link BulkCollisionError}. * - Empty bulk (`{}`) is a no-op that returns a zeroed {@link BulkResult} * without hitting the adapter. * * @template T - Entity type for the collection. Must be an object so PII * encryption, cache merging and adapter mapping can treat each row as a * `Record<string, unknown>`. * * @example * const ops: BulkOperations<Event> = { * inserts: [{ title: 'A' }, { title: 'B' }], * updates: [{ id: 'e1', patch: { title: 'renamed' } }], * deletes: ['e2', 'e3'], * }; * * @version 0.1.0 * @since 0.2.0 * @author AMBROISE PARK Consulting */ interface BulkOperations<T extends Record<string, unknown>> { /** New rows to insert. IDs are server-assigned and returned in {@link BulkResult.insertedIds}. */ inserts?: CrudCreateInput<T>[]; /** Partial updates keyed by id. `patch` is a shallow merge on top of the stored row. */ updates?: Array<{ id: string; patch: Partial<T>; }>; /** IDs to delete. */ deletes?: string[]; } /** * Result of a bulk CRUD operation. Each id list preserves the input order of the * corresponding bucket in {@link BulkOperations}. * * @example * const r: BulkResult = await adapter.bulk('events', { * inserts: [{ title: 'A' }], * deletes: ['x'], * }); * r.insertedIds; // ['evt_123'] * r.deletedIds; // ['x'] * * @version 0.1.0 * @since 0.2.0 * @author AMBROISE PARK Consulting */ interface BulkResult { /** Server-assigned IDs for `inserts`, in input order. */ insertedIds: string[]; /** IDs that were updated, in input order. */ updatedIds: string[]; /** IDs that were deleted, in input order. */ deletedIds: string[]; } /** * One collection's worth of operations inside a {@link bulkAcross} call. * * Inserts may include a caller-provided `id` for cross-collection pre-minting: * mint the ID client-side, use it in both collections, and pass `dependsOn` to * ensure write order. * * @template T - Entity type for this batch's collection. * * @example * const customerId = generateUUID(); * await bulkAcross([ * { * collection: 'customers', * inserts: [{ id: customerId, ...customerData }], * schemas: { create: customerCreateSchema }, * }, * { * collection: 'inquiries', * inserts: [{ customerId, ...inquiryData }], * schemas: { create: inquiryCreateSchema }, * dependsOn: ['customers'], * }, * ]); * * @version 0.1.0 * @since 0.3.0 * @author AMBROISE PARK Consulting */ interface BulkAcrossBatch<T extends Record<string, unknown> = Record<string, unknown>> { /** Target collection name. */ collection: string; /** Rows to insert. May include a caller-provided `id` for pre-minting. */ inserts?: Array<CrudCreateInput<T> & { id?: string; }>; /** Rows to update (partial patches). */ updates?: Array<{ id: string; patch: Partial<T>; }>; /** Document IDs to delete. */ deletes?: string[]; /** Schemas for insert validation + PII resolution. */ schemas: { create?: dndevSchema<T>; draft?: dndevSchema<T>; update?: dndevSchema<T>; }; /** * Collections that must be written first. * Batches with no `dependsOn` run in parallel with other dependency-free batches. */ dependsOn?: string[]; } /** * Result of a {@link bulkAcross} call. Per-collection results keyed by collection name. * * @version 0.1.0 * @since 0.3.0 * @author AMBROISE PARK Consulting */ interface BulkAcrossResult { /** Per-collection {@link BulkResult}, keyed by collection name. */ results: Record<string, BulkResult>; } /** Single where clause for a query. operator accepts CrudOperator or string so consumer code can use variables or literals ('in', '==', etc.) without importing CRUD_OPERATORS. */ interface QueryWhereClause { field: string; operator: CrudOperator; value: unknown; } /** Order-by clause for a query. direction accepts 'asc' | 'desc' or string so consumer code can use variables. */ interface QueryOrderBy { field: string; direction?: OrderDirection; } /** * Query options for collection queries. * Provider-agnostic — each adapter maps these to its native query API. * * Default `limit` is **1000** (server max: 1000). For collections > 1000 items, * use server-side pagination with `startAfter` cursor. * * @example * // Fetch all (up to 1000) * { where: [{ field: 'status', operator: '==', value: 'available' }] } * * @example * // Paginate server-side * { limit: 50, startAfter: lastCursorId } */ interface QueryOptions { where?: QueryWhereClause[]; orderBy?: QueryOrderBy[]; /** Max items to fetch. Default: 1000, max: 1000. Use server pagination for larger collections. */ limit?: number; /** Opaque cursor for pagination — value of the first orderBy field from the previous page's lastVisible */ startAfter?: string | null; } /** * Paginated query result returned by adapter.query(). * @template T - The entity type */ interface PaginatedQueryResult<T> { items: T[]; total?: number; hasMore?: boolean; /** Opaque cursor for the next page */ lastVisible?: string | null; } /** * Return shape of the CRUD list-query option builder * (`CrudService.getListQueryOptions` / `getListQueryOptionsImpl`). * * This is the TanStack-compatible descriptor handed to `useQuery()`. Lifted * into `@donotdev/core` so the CRUD facade and its impl can both annotate * their return types against a single source — the inferred-only shape * caused circular type inference (TS7023) after the 1949-LOC CrudService * split. * * **Invariant:** `queryKey[3]` is `JSON.stringify(queryOptions)` — list and * listCard views share the same key, yielding one network read. * * @template T - The entity type in list items */ interface CrudListQuery<T> { readonly queryKey: readonly ['crud', string, 'query', string]; readonly queryFn: () => Promise<PaginatedQueryResult<T>>; readonly staleTime: number; } /** * Return shape of the CRUD single-document query option builder * (`CrudService.getDocQueryOptions` / `getDocQueryOptionsImpl`). * * TanStack-compatible descriptor for `useQuery()`. See `CrudListQuery` for * the rationale behind promoting this shape into core types. * * @template T - The document entity type */ interface CrudDocQuery<T> { readonly queryKey: readonly ['crud', string, 'get', string]; readonly queryFn: () => Promise<T | null>; readonly staleTime: number; } /** Callback for single-document subscriptions */ type DocumentSubscriptionCallback<T> = (data: T | null, error?: Error) => void; /** Callback for collection subscriptions */ type CollectionSubscriptionCallback<T> = (data: T[], error?: Error) => void; /** Options for CRUD operations */ interface CrudOperationOptions { /** AbortSignal to cancel the operation */ signal?: AbortSignal; } /** * @fileoverview CRUD Adapter Interface * @description Provider-agnostic interface for CRUD data access. * Any backend (Firestore, Supabase, REST, Postgres) must implement this contract. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** * Provider-agnostic CRUD adapter interface. * * Implementations: * - `FirestoreAdapter` (Firestore direct) * - `FunctionsAdapter` (Firebase callable functions) * - Future: Supabase, REST, Postgres adapters * * @template All methods accept `dndevSchema` for validation/transformation. * Adapters that don't need schema can ignore it. * * @version 0.1.0 * @since 0.5.0 */ interface ICrudAdapter { /** * When true, this adapter enforces field-level security server-side. * Only server-side adapters may access entities with restricted field visibility. * Defaults to false (direct/client-side adapters). */ readonly serverSideOnly?: boolean; /** * When true, field-level and row-level security is enforced at the database layer * (e.g. Supabase RLS + column grants). The framework visibility gate is bypassed * because the DB rejects unauthorized reads before any data leaves the server. * * **Supabase:** requires RLS enabled on every table + column-level grants per role. * **Firestore:** Rules are row-level only — field-level filtering needs FunctionsAdapter. */ readonly dbLevelSecurity?: boolean; /** Fetch a single document by ID. Returns null if not found. */ get<T>(collection: string, id: string, schema?: dndevSchema<unknown>, options?: CrudOperationOptions): Promise<T | null>; /** Create a new document with auto-generated ID. Returns the ID + parsed data. */ add<T>(collection: string, data: T, schema?: dndevSchema<T>, options?: CrudOperationOptions): Promise<{ id: string; data: Record<string, unknown>; }>; /** * Execute a bulk transactional operation. * - All ops commit atomically. One transaction/writeBatch. * - One round-trip where the transport supports it. * - Empty ops returns a zeroed BulkResult without wire contact. * - Throws on partial failure; never leaves store in mixed state. * * @example * const r = await adapter.bulk('events', { inserts: [{ title: 'A' }], deletes: ['x'] }); * r.insertedIds; r.deletedIds; */ bulk<T extends Record<string, unknown>>(collection: string, ops: BulkOperations<T>, schema?: dndevSchema<T>, options?: CrudOperationOptions): Promise<BulkResult>; /** Set/replace a document by ID (upsert semantics). */ set<T>(collection: string, id: string, data: T, schema?: dndevSchema<T>, options?: CrudOperationOptions): Promise<void>; /** Partial update a document by ID. */ update<T>(collection: string, id: string, data: Partial<T>, options?: CrudOperationOptions): Promise<void>; /** Delete a document by ID. */ delete(collection: string, id: string, options?: CrudOperationOptions): Promise<void>; /** Query a collection with filters, ordering, and pagination. schemaType accepts 'list' | 'listCard' or string. */ query<T>(collection: string, options: QueryOptions, schema?: dndevSchema<unknown>, schemaType?: ListSchemaType | string, operationOptions?: CrudOperationOptions): Promise<PaginatedQueryResult<T>>; /** * Subscribe to real-time changes on a single document. * Optional — adapters that don't support real-time can throw or return a no-op unsubscribe. */ subscribe?<T>(collection: string, id: string, callback: DocumentSubscriptionCallback<T>, schema?: dndevSchema<unknown>): () => void; /** * Subscribe to real-time changes on a collection query. * Optional — adapters that don't support real-time can throw or return a no-op unsubscribe. */ subscribeToCollection?<T>(collection: string, options: QueryOptions, callback: CollectionSubscriptionCallback<T>, schema?: dndevSchema<unknown>): () => void; } /** Supported aggregation operations */ declare const AGGREGATE_OPERATIONS: { readonly COUNT: "count"; readonly SUM: "sum"; readonly AVG: "avg"; readonly MIN: "min"; readonly MAX: "max"; }; /** Aggregation operation type derived from AGGREGATE_OPERATIONS constant. */ type AggregateOperation = (typeof AGGREGATE_OPERATIONS)[keyof typeof AGGREGATE_OPERATIONS]; /** Filter operators for aggregation (subset of CRUD_OPERATORS) */ declare const AGGREGATE_FILTER_OPERATORS: { readonly EQ: "=="; readonly NEQ: "!="; readonly LT: "<"; readonly LTE: "<="; readonly GT: ">"; readonly GTE: ">="; }; /** Filter operator type for aggregation queries. */ type AggregateFilterOperator = (typeof AGGREGATE_FILTER_OPERATORS)[keyof typeof AGGREGATE_FILTER_OPERATORS]; /** * Single metric definition for aggregation * * @example * ```typescript * // Count all documents * { field: '*', operation: 'count', as: 'total' } * * // Sum a numeric field * { field: 'price', operation: 'sum', as: 'totalValue' } * * // Count with filter * { * field: '*', * operation: 'count', * as: 'availableCount', * filter: { field: 'status', operator: '==', value: 'available' } * } * ``` */ interface MetricDefinition { /** Field to aggregate ('*' for count all) */ field: string; /** Aggregation operation */ operation: AggregateOperation; /** Output name for this metric */ as: string; /** Optional filter for this metric */ filter?: { field: string; operator: AggregateFilterOperator; value: any; }; } /** * Group by definition for aggregation * * @example * ```typescript * { * field: 'status', * metrics: [ * { field: '*', operation: 'count', as: 'count' }, * { field: 'price', operation: 'sum', as: 'value' }, * ] * } * ``` */ interface GroupByDefinition { /** Field to group by */ field: string; /** Metrics to compute per group */ metrics: MetricDefinition[]; } /** * Aggregation configuration for entity analytics * * @example * ```typescript * const carsAnalyticsConfig: AggregateConfig = { * metrics: [ * { field: '*', operation: 'count', as: 'total' }, * { field: 'price', operation: 'sum', as: 'totalValue' }, * { field: 'price', operation: 'avg', as: 'avgPrice' }, * ], * groupBy: [ * { * field: 'status', * metrics: [ * { field: '*', operation: 'count', as: 'count' }, * { field: 'price', operation: 'sum', as: 'value' }, * ], * }, * ], * where: [['isActive', '==', true]], * }; * ``` */ interface AggregateConfig { /** Top-level metrics (computed on entire collection) */ metrics?: MetricDefinition[]; /** Group by configurations */ groupBy?: GroupByDefinition[]; /** Optional global filters */ where?: Array<[string, AggregateFilterOperator | string, unknown]>; } /** * Request payload for aggregate function calls */ interface AggregateRequest { /** Optional runtime filters (merged with config filters) */ where?: Array<[string, AggregateFilterOperator | string, unknown]>; /** Optional date range filter */ dateRange?: { field: string; start?: string; end?: string; }; } /** * Response from aggregate function */ interface AggregateResponse { /** Computed top-level metrics */ metrics: Record<string, number | null>; /** Grouped metrics by field */ groups: Record<string, Record<string, Record<string, number | null>>>; /** Metadata about the aggregation */ meta: { collection: string; totalDocs: number; computedAt: string; }; } /** * @fileoverview CRUD Component Props Types * @description Shared prop types for CRUD components used across UI, Templates, and CRUD packages * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Shared base props for entity browsing components (table and card grid). * Both fetch the same data — just render differently based on entity field config. */ interface EntityBrowseBaseProps { /** The entity definition */ entity: AnyEntity; /** * Base path for view. Default: `/${collection}`. View = `${basePath}/${id}`. */ basePath?: string; /** * Called when user clicks a row/card. If provided, overrides default navigation to basePath/:id (e.g. open sheet). */ onClick?: (id: string) => void; /** Hide filters section (default: false) */ hideFilters?: boolean; /** Current user role (for UI toggle only - backend enforces security) */ userRole?: string; /** Optional query constraints (server-side filtering via adapter) */ queryOptions?: QueryOptions; /** Cache stale time in ms */ staleTime?: number; /** * Tone for the filter and results Section wrappers. * Use 'base' or 'muted' when the app has an image background so sections are readable. * @default 'ghost' (transparent — inherits parent background) */ tone?: 'ghost' | 'base' | 'muted' | 'contrast' | 'accent'; /** * Static data for design-time preview. * When provided, the component renders this data directly instead of * fetching from the CRUD backend. All interactive elements (edit, delete, * create, filters, favorites, navigation) are rendered but disabled. * * No CrudProvider or backend connection required. * Hooks are never called - rendering delegates to a standalone preview component. * * @example * ```tsx * // Design preview with mock data * <EntityCardList entity={productEntity} preview={mockProducts} /> * * // Spec chat: entity generated from user description * <EntityList entity={specEntity} preview={generateMockData(specEntity, 6)} /> * ``` */ preview?: (Record<string, unknown> & { id: string; })[]; } /** Props for the entity data table component with server/client pagination. */ interface EntityListProps extends EntityBrowseBaseProps { /** * Pagination mode: * - `'auto'` (default) — fetches up to 1000 client-side. Auto-switches to server if total > 1000. * - `'client'` — forces client-side (all data in memory, instant search/sort/filter). * - `'server'` — forces server-side (cursor pagination, one page at a time). */ pagination?: 'auto' | 'client' | 'server'; /** Page size - passed to DataTable. If not provided, DataTable uses its default (12) */ pageSize?: number; /** * Enable export to CSV functionality * @default true (admin tables typically need export) */ exportable?: boolean; } /** Props for the entity card grid component with filtering and sorting. */ interface EntityCardListProps extends EntityBrowseBaseProps { /** Grid columns (responsive) - defaults to [1, 2, 3, 4] */ cols?: number | [number, number, number, number]; /** Optional filter function to filter items client-side */ filter?: (item: Record<string, unknown> & { id: string; }) => boolean; /** * Custom label for the results section title. * Receives the current item count so you can handle pluralization and empty state. * When not provided, defaults to the built-in i18n label ("Found N occurrences"). * * @param count - Number of items after all filters are applied * @returns The string to display as the results section title * * @example * ```tsx * // Simple override * <EntityCardList * entity={apartmentEntity} * resultLabel={(count) => * count === 0 * ? 'No apartments available' * : count === 1 * ? 'Your future home is right here' * : `Your future home is among these ${count} apartments` * } * /> * ``` */ resultLabel?: (count: number) => string; /** Render a custom overlay on each card (e.g. status stamp). Receives the item. */ renderCardOverlay?: (item: EntityRecord & { id: string; }) => ReactNode; /** Client-side sort: field config, comparator function, or null to disable. Defaults to entity.defaultSort. */ clientSort?: { field: string; direction?: 'asc' | 'desc'; } | ((a: any, b: any) => number) | null; /** Make filter/results sections collapsible. @default false */ collapsible?: boolean; /** Initial open state when collapsible. Only relevant when `collapsible` is true. */ defaultOpen?: boolean; } /** * Props for CrudCard — presentational card built from entity + item + field slots. * Not route-aware: parent (e.g. EntityCardList) provides detailHref or onClick. * For a11y/SEO prefer detailHref so the card is wrapped in a Link. */ interface CrudCardProps { /** The list item (must have id) */ item: EntityRecord & { id: string; }; /** The entity definition (for entity.fields and formatting) */ entity: AnyEntity; /** * Called when card is clicked (e.g. open sheet instead of navigating). * Navigation via Link is handled by the parent wrapper (CrudCardLink), not by CrudCard itself. */ onClick?: (id: string) => void; /** Field names for card title (values joined with space) */ titleFields?: string[]; /** Field names for subtitle */ subtitleFields?: string[]; /** Field names for content body (label + value rows) */ contentFields?: string[]; /** Field names for footer */ footerFields?: string[]; /** When true, show delete button with confirm dialog */ showDelete?: boolean; /** Optional actions slot (e.g. favorites heart) rendered in card corner */ renderActions?: ReactNode; /** Optional overlay rendered over the full image area (position absolute, centered, pointer-events none) */ renderOverlay?: ReactNode; /** Optional className for the card wrapper */ className?: string; } /** Props for the entity form renderer with create/edit modes, validation, and navigation. */ interface EntityFormRendererProps<T extends EntityRecord = EntityRecord> { /** Entity definition - pass the full entity from defineEntity() */ entity: AnyEntity; /** Form submission handler */ onSubmit: (data: T) => void | Promise<void>; /** Translation function */ t?: (key: string, options?: Record<string, unknown>) => string; /** Additional CSS classes */ className?: string; /** Submit button text */ submitText?: string; /** * Whether form data is loading (shows loading overlay) * Use this when fetching existing entity data for edit mode */ loading?: boolean; /** Initial form values */ defaultValues?: Partial<T>; /** Submit button variant */ submitVariant?: 'primary' | 'destructive' | 'outline' | 'ghost' | 'link'; /** Secondary button text */ secondaryButtonText?: string; /** Secondary button variant */ secondaryButtonVariant?: 'primary' | 'destructive' | 'outline' | 'ghost' | 'link'; /** Secondary button submission handler */ onSecondarySubmit?: (data: T) => void | Promise<void>; /** * Current viewer's role for editability checks. * Auto-detected from auth when not provided. Pass explicitly to override (e.g. View-As preview). * Fallback chain: prop → useAuthSafe('userRole') → 'guest' */ viewerRole?: string; /** * Form operation type * @default 'create' (or 'edit' if defaultValues provided) */ operation?: 'create' | 'edit'; /** * Optional form ID for tracking loading state. * If not provided, one will be generated automatically. */ formId?: string; /** * Cancel button text. If provided, shows a cancel button. * If not provided but onCancel is provided, shows default "Cancel" text. * Set to null to explicitly hide cancel button. */ cancelText?: string | null; /** * Success path - full path to navigate after successful submit (e.g., `/products`). * If not provided, stays on page (edit) or relies on onSubmit to navigate (create). */ successPath?: string; /** * Cancel path - full path (e.g., `/products`). If not provided, navigates back. * If onCancel callback is provided, it takes precedence over cancelPath. */ cancelPath?: string; /** * Callback when cancel is clicked (after confirmation if dirty). * If not provided, cancel navigates to cancelPath or `/${collection}`. * If provided, cancel button will show (with cancelText or default "Cancel"). */ onCancel?: () => void; /** * Hide visibility indicators (badges + View As toggle). * When false (default), shows badge next to non-guest fields and View As role selector. * @default false */ hideVisibilityInfo?: boolean; /** * Explicit form instance key for isolation between records. * When provided, React remounts the form whenever this value changes — * ensuring clean state when navigating between entities (e.g. `/cars/:id`). * * Pass the route ID: `instanceKey={id}` * * @example * ```tsx * // Automatically isolates form state per car — no manual reset needed * <EntityFormRenderer entity={carEntity} instanceKey={id} defaultValues={carData} /> * ``` */ instanceKey?: string; } /** Props for the entity recommendations section (e.g. "Similar items"). */ interface EntityRecommendationsProps { /** The entity definition */ entity: AnyEntity; /** Query constraints — caller defines "related by what" (where, limit, etc.) */ queryOptions: QueryOptions; /** Section title (e.g. "Similar apartments") */ title?: string; /** Base path for card links. Default: `/${entity.collection}` */ basePath?: string; /** Grid columns — default `[1,1,3,3]` */ cols?: number | [number, number, number, number]; /** * Tone for the Section wrapper. * Use 'base' or 'muted' when the app has an image background so the section is readable. * @default 'ghost' (transparent — inherits parent background) */ tone?: 'ghost' | 'base' | 'muted' | 'contrast' | 'accent'; /** Additional className on wrapper Section */ className?: string; } /** Props for the read-only entity detail renderer with role-based visibility. */ interface EntityDisplayRendererProps<T extends EntityRecord = EntityRecord> { /** Entity definition - pass the full entity from defineEntity() */ entity: AnyEntity; /** Entity ID to fetch. Not required when `preview` is provided. */ id?: string; /** Translation function (optional - auto-generated if not provided) */ t?: (key: string, options?: Record<string, unknown>) => string; /** Additional CSS classes */ className?: string; /** Custom loading message */ loadingMessage?: string; /** Custom not found message */ notFoundMessage?: string; /** * Current viewer's role for visibility checks. * Auto-detected from auth when not provided. Pass explicitly to override. * Fallback chain: prop → useAuthSafe('userRole') → 'guest' */ viewerRole?: string; /** * Field names to exclude from rendering. * Use when the page already displays certain fields in a custom hero/header section. */ excludeFields?: string[]; /** * Static data for design-time preview. * When provided, renders this record directly instead of fetching by id. * The `id` prop becomes unnecessary (ignored when preview is set). * * @example * ```tsx * <EntityDisplayRenderer entity={productEntity} preview={mockProduct} /> * ``` */ preview?: Partial<T>; } /** * @fileoverview CRUD Error Classes * @description Error classes raised by the CRUD service and adapters. * Each error is a plain {@link Error} subclass so consumers can `instanceof` them. * * @version 0.1.0 * @since 0.2.0 * @author AMBROISE PARK Consulting */ /** * Thrown when a {@link BulkOperations} payload contains the same id in two * mutually-exclusive buckets. The service rejects these up-front, before any * write is attempted, so partial state is impossible. * * @example * try { * await crud.bulk({ * updates: [{ id: 'a', patch: {} }], * deletes: ['a'], * }); * } catch (err) { * if (err instanceof BulkCollisionError) { * // err.collidingIds === ['a'] * // err.where === 'updates-deletes' * } * } * * @version 0.1.0 * @since 0.2.0 */ declare class BulkCollisionError extends Error { /** IDs that appear in both buckets. Preserves the order they were detected. */ readonly collidingIds: string[]; /** Which two buckets collided. */ readonly where: 'updates-deletes' | 'inserts-updates'; /** * @param collidingIds - IDs present in both buckets. * @param where - The pair of buckets that produced the collision. */ constructor(collidingIds: string[], where: 'updates-deletes' | 'inserts-updates'); } /** * Thrown by {@link bulkAcross} before any side effect when `dependsOn` * relationships form a cycle. The `cycle` array lists the collection names * that form the circular dependency chain. * * @example * try { * await crud.bulkAcross([ * { collection: 'a', dependsOn: ['b'], ... }, * { collection: 'b', dependsOn: ['a'], ... }, * ]); * } catch (err) { * if (err instanceof BulkAcrossCycleError) { * console.error(err.cycle); // ['a', 'b'] * } * } * * @version 0.1.0 * @since 0.3.0 */ declare class BulkAcrossCycleError extends Error { /** Collection names that form the cycle. */ readonly cycle: string[]; constructor(cycle: string[]); } /** * Thrown by an adapter whose `bulk()` method has not yet been implemented. * Lets the interface stay required across all providers while individual * adapters can land their implementation incrementally. * * @example * // Inside an adapter stub: * async bulk() { * throw new BulkNotImplementedError('restcrud'); * } * * @version 0.1.0 * @since 0.2.0 */ declare class BulkNotImplementedError extends Error { /** Adapter identifier (e.g. `'firebase-firestore'`, `'supabase'`). */ readonly adapterName: string; /** * @param adapterName - Name of the adapter that has not implemented `bulk()`. */ constructor(adapterName: string); } /** * @fileoverview Email Constants * @description Provider IDs, error codes, and defaults for email feature. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** Supported email providers */ declare const EMAIL_PROVIDERS: { readonly RESEND: "resend"; }; /** Email error codes */ declare const EMAIL_ERROR_CODES: { readonly UNKNOWN: "unknown"; readonly UNAUTHENTICATED: "unauthenticated"; readonly INVALID_REQUEST: "invalid_request"; readonly PROVIDER_ERROR: "provider_error"; readonly TEMPLATE_NOT_FOUND: "template_not_found"; readonly RATE_LIMIT_EXCEEDED: "rate_limit_exceeded"; readonly MISSING_API_KEY: "missing_api_key"; }; /** * @fileoverview Email Schemas * @description Valibot schemas for email request/response validation. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** Schema for send email request (caller → handler) */ declare const SendEmailRequestSchema: v.ObjectSchema<{ /** Template ID from the registry */ readonly templateId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; /** Recipient email address */ readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>; /** Template data (shape depends on template) */ readonly data: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; /** Locale for i18n rendering (default: 'fr') */ readonly locale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 2, undefined>, v.MaxLengthAction<string, 5, undefined>]>, "fr">; /** Override "from" address */ readonly from: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Override reply-to address */ readonly replyTo: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>; /** Schema for send email response */ declare const SendEmailResponseSchema: v.ObjectSchema<{ /** Whether the email was sent successfully */ readonly success: v.BooleanSchema<undefined>; /** Provider message ID (for tracking) */ readonly messageId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Error message if sending failed */ readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>; /** Request payload for sending an email. */ type SendEmailRequest = v.InferOutput<typeof SendEmailRequestSchema>; /** Response payload after sending an email. */ type SendEmailResponse = v.InferOutput<typeof SendEmailResponseSchema>; declare function validateSendEmailRequest(data: unknown): v.SafeParseResult<v.ObjectSchema<{ /** Template ID from the registry */ readonly templateId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; /** Recipient email address */ readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.EmailAction<string, undefined>]>; /** Template data (shape depends on template) */ readonly data: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; /** Locale for i18n rendering (default: 'fr') */ readonly locale: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 2, undefined>, v.MaxLengthAction<string, 5, undefined>]>, "fr">; /** Override "from" address */ readonly from: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Override reply-to address */ readonly replyTo: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>>; declare function validateSendEmailResponse(data: unknown): v.SafeParseResult<v.ObjectSchema<{ /** Whether the email was sent successfully */ readonly success: v.BooleanSchema<undefined>; /** Provider message ID (for tracking) */ readonly messageId: v.OptionalSchema<v.StringSchema<undefined>, undefined>; /** Error message if sending failed */ readonly error: v.OptionalSchema<v.StringSchema<undefined>, undefined>; }, undefined>>; /** * @fileoverview Email Types * @description Type definitions for email feature. Provider abstraction, template registry, route config. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** Email provider type */ type EmailProvider = (typeof EMAIL_PROVIDERS)[keyof typeof EMAIL_PROVIDERS]; /** Email error code type */ type EmailErrorCode = (typeof EMAIL_ERROR_CODES)[keyof typeof EMAIL_ERROR_CODES]; /** * Email template with i18n support. * Templates render subject + HTML body from typed data and locale. * * @template TData - Shape of the template data */ interface EmailTemplate<TData extends Record<string, unknown> = Record<string, unknown>> { /** Render email subject for a given locale */ subject: (data: TData, locale: string) => string; /** Render email HTML body for a given locale */ html: (data: TData, locale: string) => string; } /** * Registry of named email templates. * Each key is a template ID used in send requests. */ type EmailTemplateRegistry = Record<string, EmailTemplate<any>>; /** Configuration for email feature (consumer-facing) */ interface EmailConfig { /** Email provider */ provider: EmailProvider; /** Default "from" address */ defaultFrom: string; /** Default reply-to address */ replyTo?: string; } /** Email route configuration (server-side) */ interface EmailRouteConfig { /** Email provider */ provider: EmailProvider; /** Default "from" address (e.g., "Frabled <noreply@frabled.com>") */ defaultFrom: string; /** Default reply-to address */ replyTo?: string; /** Registered templates */ templates: EmailTemplateRegistry; } /** * @fileoverview Error Types Used Throughout the DoNotDev Platform * @description Centralized definition of error types to ensure consistency across packages. Defines standard error codes, error classes, and error handling types. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Error types used throughout the DoNotDev platform * Single source of truth: const objects + derived types. */ /** * Standard error codes used within the DoNotDev platform. * Mapped to HTTP status codes or used for specific error handling logic. */ declare const ERROR_CODES: { readonly ALREADY_EXISTS: "already-exists"; readonly CANCELLED: "cancelled"; readonly DEADLINE_EXCEEDED: "deadline-exceeded"; readonly DELETE_ACCOUNT_REQUIRES_SERVER: "DELETE_ACCOUNT_REQUIRES_SERVER"; readonly INTERNAL: "internal"; readonly INVALID_ARGUMENT: "invalid-argument"; readonly NOT_FOUND: "not-found"; readonly PERMISSION_DENIED: "permission-denied"; readonly RATE_LIMIT_EXCEEDED: "rate-limit-exceeded"; readonly TIMEOUT: "timeout"; readonly UNAUTHENTICATED: "unauthenticated"; readonly UNAVAILABLE: "unavailable"; readonly UNIMPLEMENTED: "unimplemented"; readonly UNKNOWN: "unknown"; readonly VALIDATION_FAILED: "validation-failed"; }; /** Standardized error code derived from ERROR_CODES constant. */ type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES]; /** * Severity levels for error notifications and logging */ declare const ERROR_SEVERITY: { readonly ERROR: "error"; readonly WARNING: "warning"; readonly INFO: "info"; readonly SUCCESS: "success"; }; /** Error severity level for notifications and logging. */ type ErrorSeverity = (typeof ERROR_SEVERITY)[keyof typeof ERROR_SEVERITY]; /** * Error types used in entity hooks */ declare const ENTITY_HOOK_ERRORS: { readonly INTERNAL_ERROR: "INTERNAL_ERROR"; readonly VALIDATION_ERROR: "VALIDATION_ERROR"; readonly PERMISSION_DENIED: "PERMISSION_DENIED"; readonly NOT_FOUND: "NOT_FOUND"; readonly ALREADY_EXISTS: "ALREADY_EXISTS"; readonly NETWORK_ERROR: "NETWORK_ERROR"; }; /** Error type for entity hook operations (CRUD mutations). */ type EntityHookErrors = (typeof ENTITY_HOOK_ERRORS)[keyof typeof ENTITY_HOOK_ERRORS]; /** * Maps Firebase error codes to entity hook error types * Used for consistent error handling across the platform * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const FIREBASE_ERROR_MAP: Record<string, { type: EntityHookErrors; message: string; }>; /** * Error class for standardized entity hook errors * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class EntityHookError extends Error { type: EntityHookErrors; originalError?: unknown; constructor(type: EntityHookErrors, message: string, originalError?: unknown); } /** * Error source types for tracking where errors originate */ declare const ERROR_SOURCE: { readonly AUTH: "auth"; readonly OAUTH: "oauth"; readonly FIREBASE: "firebase"; readonly API: "api"; readonly VALIDATION: "validation"; readonly ENTITY: "entity"; readonly UI: "ui"; readonly UNKNOWN: "unknown"; }; /** Origin of an error for tracking and reporting. */ type ErrorSource = (typeof ERROR_SOURCE)[keyof typeof ERROR_SOURCE]; /** * Standardized error class for the DoNotDev platform * Single source of truth with optional fields for all use cases * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class DoNotDevError extends Error { /** The error code categorizing this error */ readonly code: ErrorCode; /** Optional additional details or context about the error */ readonly details?: Record<string, any>; /** The source system where the error originated */ readonly source?: ErrorSource; /** Original error if this is wrapping another error */ readonly originalError?: Error; /** Additional context for the error */ readonly context?: Record<string, any>; /** Whether this error should be displayed to the user */ readonly displayable?: boolean; /** Flag to track if a user message has been provided */ readonly userMessageProvided?: boolean; constructor(message: string, code?: ErrorCode, options?: { details?: Record<string, any>; source?: ErrorSource; originalError?: Error; context?: Record<string, any>; displayable?: boolean; userMessageProvided?: boolean; }); toString(): string; toJSON(): object; } /** * @fileoverview Security Types * @description Core security interface definitions. Implemented by @donotdev/security. * Keeping these in @donotdev/core avoids circular deps between packages. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Audit event types (SOC2 CC6, CC7, C1, P1-P8). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuditEventType = 'auth.login.success' | 'auth.login.failure' | 'auth.logout' | 'auth.locked' | 'auth.unlocked' | 'auth.mfa.enrolled' | 'auth.mfa.challenged' | 'auth.session.expired' | 'auth.password.reset' | 'auth.signup.consent' | 'auth.role.changed' | 'crud.create' | 'crud.read' | 'crud.update' | 'crud.delete' | 'crud.bulk' | 'pii.access' | 'pii.export' | 'pii.erase' | 'rate_limit.exceeded' | 'anomaly.detected' | 'config.changed'; /** * A single structured audit log entry. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuditEvent { type: AuditEventType; timestamp: string; userId?: string; collection?: string; docId?: string; ip?: string; userAgent?: string; metadata?: Record<string, string | number | boolean>; } /** * Persistence-backed rate limit config (server-side: maxAttempts / windowMs / blockDurationMs). * Used by RateLimitBackend implementations (Firestore, Postgres, Redis). * Distinct from the client-side RateLimitConfig in @donotdev/types/utils. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ServerRateLimitConfig { /** Max requests allowed within the window. */ maxAttempts: number; /** Window duration in milliseconds. */ windowMs: number; /** Block duration in milliseconds after limit is exceeded. */ blockDurationMs: number; } /** * Result from a server-side rate limit check. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ServerRateLimitResult { allowed: boolean; remaining: number; resetAt: Date | null; blockRemainingSeconds: number | null; } /** * Pluggable rate limit backend for DndevSecurity. * Implement to swap the default in-memory limiter with Firestore, Postgres, Redis, etc. * * @example * ```typescript * import { checkRateLimitWithFirestore } from '@donotdev/functions/shared'; * const security = new DndevSecurity({ * rateLimitBackend: { check: (key, cfg) => checkRateLimitWithFirestore(key, cfg) }, * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimitBackend { check(key: string, config: ServerRateLimitConfig): Promise<ServerRateLimitResult>; } /** * Minimal auth hardening interface exposed by SecurityContext. * Auth adapters delegate lockout to this when security is injected, * ensuring a single lockout source of truth that respects user config. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthHardeningContext { /** @throws if identifier is currently locked out */ checkLockout(identifier: string): void; /** Record a failed auth attempt; may trigger lockout */ recordFailure(identifier: string): void; /** Clear failure counter on successful auth */ recordSuccess(identifier: string): void; } /** * Security context interface consumed by CrudService and auth adapters. * Implemented by DndevSecurity in @donotdev/security/server. * * Pass an instance via CrudService.setSecurity() or auth adapter constructors. * When not provided, no audit logging, rate limiting, or encryption is applied. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SecurityContext { /** Emit a structured audit event */ audit(event: Omit<AuditEvent, 'timestamp'>): void | Promise<void>; /** * Check rate limit for a key + operation. * @throws {Error} when threshold is exceeded */ checkRateLimit(key: string, operation: 'read' | 'write'): Promise<void>; /** Encrypt named PII fields in a data object (returns new object) */ encryptPii<T extends Record<string, unknown>>(data: T, piiFields: string[]): T; /** Decrypt named PII fields in a data object (returns new object) */ decryptPii<T extends Record<string, unknown>>(data: T, piiFields: string[]): T; /** * Auth hardening — when present, auth adapters delegate brute-force lockout here * instead of using their own hardcoded Maps, ensuring injected config is respected. */ authHardening?: AuthHardeningContext; /** * Record a behavioral anomaly event (e.g. bulk deletes, bulk reads, auth failures). * Optional — no-op when not implemented. CrudService calls this after write mutations * so the anomaly detector can fire alerts when thresholds are breached. * * @param type - Anomaly type string (must match AnomalyType in @donotdev/security) * @param userId - User who triggered the anomaly (undefined = system / anonymous) */ recordAnomaly?(type: string, userId?: string): void; } /** * @fileoverview Auth Events * @description Event constants and types for auth EDA system. Defines authentication-related event names and types for event-driven architecture. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Authentication event constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const AUTH_EVENTS: { readonly AUTH_STATE_CHANGED: "auth.state.changed"; readonly USER_SIGNED_IN: "auth.user.signed_in"; readonly USER_SIGNED_OUT: "auth.user.signed_out"; readonly USER_UPDATED: "auth.user.updated"; readonly TOKEN_REFRESHED: "auth.token.refreshed"; readonly SUBSCRIPTION_UPDATED: "auth.subscription.updated"; readonly SUBSCRIPTION_CHANGED: "auth.subscription.changed"; readonly SUBSCRIPTION_CANCELLED: "auth.subscription.cancelled"; readonly SUBSCRIPTION_EXPIRED: "auth.subscription.expired"; readonly PERMISSIONS_UPDATED: "auth.permissions.updated"; readonly ACCOUNT_LINKED: "auth.account.linked"; readonly ACCOUNT_UNLINKED: "auth.account.unlinked"; readonly ACCOUNT_LINKING_REQUIRED: "auth.account.linking_required"; readonly AUTH_SUCCESS: "auth.success"; readonly EMAIL_VERIFICATION_SENT: "auth.email.verification_sent"; readonly PASSWORD_RESET_SENT: "auth.password.reset_sent"; readonly AUTH_ERROR: "auth.error"; }; /** * Type for authentication event keys * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthEventKey = keyof typeof AUTH_EVENTS; /** * Type for authentication event names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthEventName = (typeof AUTH_EVENTS)[AuthEventKey]; /** * Authentication event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthEventData { userId?: string; authUser?: any; userProfile?: any; subscription?: any; token?: string; permissions?: string[]; partnerId?: string; error?: string; errorCode?: string; isLoading?: boolean; timestamp: Date; metadata?: Record<string, any>; } /** * @fileoverview Billing Events * @description Event constants and types for billing EDA system. Defines billing-related event names and types for event-driven architecture. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Billing event constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const BILLING_EVENTS: { readonly BILLING_INITIALIZED: "billing.initialized"; readonly BILLING_ERROR: "billing.error"; readonly CHECKOUT_SESSION_CREATED: "billing.checkout_session.created"; readonly CHECKOUT_SESSION_FAILED: "billing.checkout_session.failed"; readonly SUBSCRIPTION_CREATED: "billing.subscription.created"; readonly SUBSCRIPTION_UPDATED: "billing.subscription.updated"; readonly SUBSCRIPTION_CANCELLED: "billing.subscription.cancelled"; readonly SUBSCRIPTION_RENEWED: "billing.subscription.renewed"; readonly SUBSCRIPTION_EXPIRED: "billing.subscription.expired"; readonly SUBSCRIPTION_TRIAL_ENDED: "billing.subscription.trial_ended"; readonly PAYMENT_SUCCEEDED: "billing.payment.succeeded"; readonly PAYMENT_FAILED: "billing.payment.failed"; readonly PAYMENT_REFUNDED: "billing.payment.refunded"; readonly PAYMENT_METHOD_ADDED: "billing.payment_method.added"; readonly PAYMENT_METHOD_UPDATED: "billing.payment_method.updated"; readonly PAYMENT_METHOD_REMOVED: "billing.payment_method.removed"; readonly PAYMENT_METHOD_DEFAULT_CHANGED: "billing.payment_method.default_changed"; readonly INVOICE_CREATED: "billing.invoice.created"; readonly INVOICE_UPDATED: "billing.invoice.updated"; readonly INVOICE_PAID: "billing.invoice.paid"; readonly INVOICE_FAILED: "billing.invoice.failed"; readonly WEBHOOK_RECEIVED: "billing.webhook.received"; readonly WEBHOOK_PROCESSED: "billing.webhook.processed"; readonly WEBHOOK_ERROR: "billing.webhook.error"; }; /** * Type for billing event keys * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingEventKey = keyof typeof BILLING_EVENTS; /** * Type for billing event names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingEventName = (typeof BILLING_EVENTS)[BillingEventKey]; /** * Billing event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BillingEventData { provider?: string; config?: Record<string, unknown>; invoice?: Record<string, unknown>; paymentMethod?: Record<string, unknown>; timestamp: Date; metadata?: Record<string, unknown>; } /** * Subscription event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface SubscriptionEventData { subscription: Record<string, unknown>; previousSubscription?: Record<string, unknown>; reason?: string; timestamp: Date; metadata?: Record<string, unknown>; } /** * Payment event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PaymentEventData { paymentId: string; amount: number; currency: string; status: 'succeeded' | 'failed' | 'pending' | 'refunded'; subscription?: Record<string, unknown>; invoice?: Record<string, unknown>; timestamp: Date; metadata?: Record<string, unknown>; } /** * Webhook event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface WebhookEventData { provider: string; eventType: string; data: Record<string, unknown>; signature?: string; timestamp: Date; } /** * @fileoverview OAuth Events * @description Event constants and types for OAuth EDA system. Defines OAuth-related event names and types for event-driven architecture. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * OAuth event constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const OAUTH_EVENTS: { readonly OAUTH_STARTED: "oauth.started"; readonly OAUTH_SUCCESS: "oauth.success"; readonly OAUTH_ERROR: "oauth.error"; readonly OAUTH_CANCELLED: "oauth.cancelled"; readonly OAUTH_TOKEN_EXCHANGED: "oauth.token.exchanged"; readonly OAUTH_TOKEN_REFRESHED: "oauth.token.refreshed"; readonly OAUTH_PARTNER_LINKED: "oauth.partner.linked"; readonly OAUTH_PARTNER_UNLINKED: "oauth.partner.unlinked"; }; /** * Type for OAuth event keys * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthEventKey = keyof typeof OAUTH_EVENTS; /** * Type for OAuth event names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthEventName = (typeof OAUTH_EVENTS)[OAuthEventKey]; /** * OAuth event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthEventData { userId?: string; partnerId?: string; token?: string; error?: any; timestamp: Date; metadata?: Record<string, any>; } /** * @fileoverview Payload CMS Events * @description Event constants and types for Payload CMS webhook events. Defines Payload CMS-related event names and types for event-driven architecture. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Payload CMS event constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const PAYLOAD_EVENTS: { readonly DOCUMENT_CREATED: "payload.document.created"; readonly DOCUMENT_UPDATED: "payload.document.updated"; readonly DOCUMENT_DELETED: "payload.document.deleted"; readonly MEDIA_CREATED: "payload.media.created"; readonly MEDIA_UPDATED: "payload.media.updated"; readonly MEDIA_DELETED: "payload.media.deleted"; readonly GLOBAL_UPDATED: "payload.global.updated"; readonly USER_CREATED: "payload.user.created"; readonly USER_UPDATED: "payload.user.updated"; readonly USER_DELETED: "payload.user.deleted"; readonly CACHE_INVALIDATED: "payload.cache.invalidated"; readonly PAGE_REGENERATED: "payload.page.regenerated"; }; /** * Type for Payload event keys * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PayloadEventKey = keyof typeof PAYLOAD_EVENTS; /** * Type for Payload event names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type PayloadEventName = (typeof PAYLOAD_EVENTS)[PayloadEventKey]; /** * Payload document event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadDocumentEventData { collection: string; documentId: string; operation: string; doc: any; previousDoc?: any; req: any; timestamp: string; } /** * Payload media event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadMediaEventData { mediaId: string; operation: string; media: any; previousMedia?: any; req: any; timestamp: string; } /** * Payload global event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadGlobalEventData { globalSlug: string; doc: any; previousDoc?: any; req: any; affectedPages: string[]; timestamp: string; } /** * Payload user event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadUserEventData { userId: string; operation: string; user: any; req: any; timestamp: string; } /** * Payload cache event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadCacheEventData { reason: string; scope: string; tags: string[]; priority: string; timestamp: string; } /** * Payload page regeneration event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadPageRegenerationEventData { paths: string[]; reason: string; priority: string; seoImpact: boolean; timestamp: string; } /** * Payload document interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadDocument { id: string; [key: string]: any; } /** * Payload request interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PayloadRequest { method: string; url: string; headers: Record<string, string>; body?: any; user?: any; timestamp: string; } /** * @fileoverview Stripe Events * @description Event constants and types for Stripe webhook events. Defines Stripe-related event names and types for event-driven architecture. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Stripe event constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const STRIPE_EVENTS: { readonly PAYMENT_INTENT_SUCCEEDED: "stripe.payment_intent.succeeded"; readonly PAYMENT_INTENT_FAILED: "stripe.payment_intent.payment_failed"; readonly CHECKOUT_SESSION_COMPLETED: "stripe.checkout.session.completed"; readonly CUSTOMER_CREATED: "stripe.customer.created"; readonly CUSTOMER_UPDATED: "stripe.customer.updated"; readonly CUSTOMER_DELETED: "stripe.customer.deleted"; readonly INVOICE_CREATED: "stripe.invoice.created"; readonly INVOICE_PAID: "stripe.invoice.paid"; readonly INVOICE_PAYMENT_FAILED: "stripe.invoice.payment_failed"; readonly SUBSCRIPTION_CREATED: "stripe.subscription.created"; readonly SUBSCRIPTION_UPDATED: "stripe.subscription.updated"; readonly SUBSCRIPTION_DELETED: "stripe.subscription.deleted"; }; /** * Type for Stripe event keys * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripeEventKey = keyof typeof STRIPE_EVENTS; /** * Type for Stripe event names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StripeEventName = (typeof STRIPE_EVENTS)[StripeEventKey]; /** * Stripe payment intent event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripePaymentIntentEventData { paymentIntentId: string; customerId?: string; amount: number; currency: string; status: string; metadata?: Record<string, string>; timestamp: string; } /** * Stripe checkout session event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeCheckoutSessionEventData { sessionId: string; customerId?: string; paymentIntentId?: string; amount?: number; currency?: string; customerEmail?: string; metadata?: Record<string, string>; timestamp: string; } /** * Stripe customer event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeCustomerEventData { customerId: string; email?: string; name?: string; metadata?: Record<string, string>; timestamp: string; } /** * Stripe invoice event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeInvoiceEventData { invoiceId: string; customerId: string; amount: number; currency: string; status: string; hostedInvoiceUrl?: string; metadata?: Record<string, string>; timestamp: string; } /** * Stripe webhook event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeWebhookEventData { eventId: string; eventType: string; data: any; livemode: boolean; timestamp: string; } /** * Stripe event data interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StripeEventData { eventId?: string; eventType?: string; customerId?: string; subscriptionId?: string; amount?: number; currency?: string; status?: string; metadata?: Record<string, any>; timestamp: string; } /** * @fileoverview Firebase Types * @description Type definitions for Firebase integration. Defines Firestore timestamp interface and date value types for Firebase compatibility without requiring the Firebase Admin SDK. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Interface mimicking Firebase Timestamp for type compatibility * without requiring the actual Firebase Admin SDK * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FirestoreTimestamp { seconds: number; nanoseconds: number; toDate(): Date; toMillis(): number; isEqual(other: FirestoreTimestamp): boolean; valueOf(): string; } /** * Represents a date value in various formats accepted by Firebase. * Can be a JavaScript Date, a Firestore Timestamp, or an ISO 8601 string. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type DateValue = Date | FirestoreTimestamp | string; /** * Firebase configuration object * Contains the configuration needed to initialize a Firebase app * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FirebaseConfig { /** Firebase API key */ apiKey: string; /** Firebase authentication domain */ authDomain: string; /** Firebase project ID */ projectId: string; /** Firebase storage bucket URL (optional) */ storageBucket?: string; /** Firebase messaging sender ID (optional) */ messagingSenderId?: string; /** Firebase app ID (optional) */ appId?: string; /** Firebase measurement ID for analytics (optional) */ measurementId?: string; } /** * Options for Firebase functions call with abort support * Allows for cancellable Firebase function calls * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FirebaseCallOptions { /** Optional key for the abort controller */ abortKey?: string; /** Optional external abort signal to link with internal controller */ externalSignal?: AbortSignal; /** Flag for public function calls */ public?: boolean; /** HTTP callable timeout in milliseconds */ timeout?: number; } /** * Interface for Firebase uniqueness validation * Used to check if a value would create a duplicate in a collection * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FirestoreUniqueConstraintValidator { /** * Checks if a value would cause a duplicate in a given collection * * @param collection - The collection to check * @param field - The field to check * @param value - The value to check * @param currentDocId - The ID of the current document (for updates) * @returns A promise that resolves to true if a duplicate exists */ checkDuplicate: (collection: string, field: string, value: any, currentDocId?: string) => Promise<boolean>; } /** * @fileoverview Hook Types * @description Type definitions for hook types. Defines options for listing operations, pagination, filtering, and sorting used by hooks. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Options for listing operations. * Used to customize the behavior of list hooks. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ListOptions { /** The page number (1-indexed) to fetch */ page?: number; /** The number of items per page */ pageSize?: number; /** Filters to apply to the list */ filters?: Record<string, any>; /** Sorting options */ sort?: { /** The field to sort by */ field: string; /** The direction to sort in */ direction: 'asc' | 'desc'; }; } /** * Standard response for list operations. * Used by list hooks to return paginated data. * @template T - The type of items in the list * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ListResponse<T> { /** The items in the current page */ items: T[]; /** The total number of items across all pages */ total: number; /** The current page number */ page: number; /** The number of items per page */ pageSize: number; /** Whether there are more pages to fetch */ hasMore: boolean; } /** * Standard response for mutations. * Used by create, update, and delete hooks to return the result of the operation. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface MutationResponse { /** The ID of the affected entity */ id: string; /** Additional fields that may be returned by the mutation */ [key: string]: any; } /** * @fileoverview Function Types * @description Type definitions for function types. Defines schema metadata, function request/response types, and function-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Valid operators for database queries * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type WhereOperator = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'array-contains-any' | 'in' | 'not-in'; /** * Firestore where clause tuple * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type WhereClause = [string, WhereOperator, any]; /** * Firestore orderBy clause tuple * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OrderByClause = [string, 'asc' | 'desc']; /** * Represents a reference to another document. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Reference { /** The collection containing the referenced document */ collection: string; /** The ID of the referenced document */ document: string; /** The field in the referenced document */ field: string; } /** * Metadata fields for an entity. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EntityMetadata { /** ISO 8601 timestamp when the entity was created */ createdAt: string; /** ISO 8601 timestamp when the entity was last updated */ updatedAt: string; /** ID of the user who created the entity */ createdById: string; /** ID of the user who last updated the entity */ updatedById: string; } /** * Utility type that adds metadata to a document. * @template T - The base document type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type WithMetadata<T> = T & EntityMetadata; /** * Data required for creating an entity * @template T - The entity type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CreateEntityData<T extends Record<string, any>> { /** The schema to validate against */ schema: dndevSchema<T>; /** The entity data to create */ payload: T; /** Optional idempotency key for preventing duplicate operations */ idempotencyKey?: string; } /** * Data required for updating an entity * @template T - The entity type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UpdateEntityData<T extends Record<string, any>> { /** The schema to validate against */ schema: dndevSchema<T>; /** The ID of the entity to update */ id: string; /** The partial entity data to update */ payload: Partial<T>; /** Optional idempotency key for preventing duplicate operations */ idempotencyKey?: string; } /** * Data required for getting an entity * @template T - The entity type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface GetEntityData<T extends Record<string, any>> { /** The schema to validate against */ schema: dndevSchema<T>; /** The ID of the entity to get */ id: string; } /** * Data required for listing entities * @template T - The entity type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ListEntityData<T extends Record<string, any>> extends ListOptions { /** The schema to validate against */ schema: dndevSchema<T>; } /** * Supported function platforms * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FunctionPlatform = 'firebase' | 'vercel' | 'aws' | 'custom'; /** * Function call configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionCallConfig { /** Platform to use for function calls */ platform: FunctionPlatform; /** Region for the function (platform-specific) */ region?: string; /** Default timeout in milliseconds */ timeout?: number; /** Number of retry attempts */ retries?: number; /** Base URL for custom platforms */ baseUrl?: string; } /** * Function call options * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionCallOptions { /** Whether this is a public function call (no auth required) */ public?: boolean; /** Request timeout in milliseconds */ timeout?: number; /** Number of retry attempts */ retries?: number; /** Abort signal for request cancellation */ signal?: AbortSignal; /** Whether to cache the response */ cache?: boolean; /** Cache stale time in milliseconds */ staleTime?: number; /** Custom headers */ headers?: Record<string, string>; } /** * Function response wrapper * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionResponse<T = any> { /** Response data */ data: T; /** Whether the call was successful */ success: boolean; /** Error message if any */ error?: string; /** Response metadata */ metadata?: { platform: FunctionPlatform; duration: number; cached: boolean; timestamp: string; }; } /** * Function error details * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionError { /** Error code */ code: string; /** Error message */ message: string; /** Additional error details */ details?: any; /** Platform-specific error information */ platform?: { name: FunctionPlatform; errorCode?: string; errorMessage?: string; }; } /** * Function call result * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FunctionCallResult<T> = { success: true; data: T; error?: never; } | { success: false; data?: never; error: FunctionError; }; /** * Function client interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionClient { /** Call a function */ callFunction<TData>(functionName: string, params?: object, schema?: v.BaseSchema<unknown, TData, v.BaseIssue<unknown>>, options?: FunctionCallOptions): Promise<TData>; /** Get client configuration */ getConfig(): FunctionCallConfig; /** Update client configuration */ updateConfig(config: Partial<FunctionCallConfig>): void; } /** * Function loader interface for lazy loading * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionLoader { /** Load the functions system */ load(): Promise<FunctionSystem>; /** Check if system is loaded */ isLoaded(): boolean; /** Get loaded system (throws if not loaded) */ getSystem(): FunctionSystem; } /** * Result type for useFunctionsQuery hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseFunctionsQueryResult<TData> { /** Query data */ data: TData | undefined; /** Whether the query is loading */ isLoading: boolean; /** Whether the query encountered an error */ isError: boolean; /** Error details if any */ error: FunctionError | null; /** Whether the query is currently fetching (includes background refetch) */ isFetching: boolean; /** Refetch the query */ refetch: () => Promise<void>; } /** * Result type for useFunctionsMutation hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseFunctionsMutationResult<TData, TVariables> { /** Execute the mutation */ mutate: (variables: TVariables) => void; /** Execute the mutation and return a promise */ mutateAsync: (variables: TVariables) => Promise<TData>; /** Whether the mutation is in progress */ isLoading: boolean; /** Whether the mutation encountered an error */ isError: boolean; /** Whether the mutation succeeded */ isSuccess: boolean; /** Error details if any */ error: FunctionError | null; /** Mutation result data */ data: TData | undefined; /** Reset the mutation state */ reset: () => void; } /** * Result type for useFunctionsCall hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseFunctionsCallResult<TData> { /** Execute the function call */ call: (params?: object) => Promise<TData>; /** Whether the call is in progress */ isLoading: boolean; /** Whether the call encountered an error */ isError: boolean; /** Error details if any */ error: FunctionError | null; /** Call result data */ data: TData | undefined; } /** * Complete functions system interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionSystem { /** Function client */ client: FunctionClient; /** React Query hooks */ hooks: { useFunctionsQuery: <TData = unknown>(functionName: string, params?: object, schema?: v.BaseSchema<unknown, TData, v.BaseIssue<unknown>>, options?: UseFunctionsQueryOptions<TData>) => UseFunctionsQueryResult<TData>; useFunctionsMutation: <TData = unknown, TVariables = object>(functionName: string, schema?: v.BaseSchema<unknown, TData, v.BaseIssue<unknown>>, options?: UseFunctionsMutationOptions<TData, TVariables>) => UseFunctionsMutationResult<TData, TVariables>; useFunctionsCall: <TData = unknown>(functionName: string, options?: FunctionCallOptions) => UseFunctionsCallResult<TData>; }; /** Direct call function */ callFunction: FunctionClient['callFunction']; } /** * React Query options for functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseFunctionsQueryOptions<TData> { /** Whether the query is enabled */ enabled?: boolean; /** Time until data is considered stale */ staleTime?: number; /** Time until inactive data is garbage collected */ gcTime?: number; /** Number of retry attempts */ retry?: number; /** Whether to keep previous data while fetching */ keepPreviousData?: boolean; /** Whether to refetch on window focus */ refetchOnWindowFocus?: boolean; /** Callback for successful queries */ onSuccess?: (data: TData) => void; /** Callback for failed queries */ onError?: (error: FunctionError) => void; } /** * React Query mutation options for functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseFunctionsMutationOptions<TData, TVariables> { /** Number of retry attempts */ retry?: number; /** Callback before mutation */ onMutate?: (variables: TVariables) => void | Promise<void>; /** Callback for successful mutations */ onSuccess?: (data: TData, variables: TVariables) => void; /** Callback for failed mutations */ onError?: (error: FunctionError, variables: TVariables) => void; /** Callback after mutation (success or failure) */ onSettled?: (data: TData | undefined, error: FunctionError | null, variables: TVariables) => void; } /** * Function schema definition * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionSchema<TInput = any, TOutput = any> { /** Input validation schema */ input?: v.BaseSchema<unknown, TInput, v.BaseIssue<unknown>>; /** Output validation schema */ output?: v.BaseSchema<unknown, TOutput, v.BaseIssue<unknown>>; /** Function name */ name: string; /** Whether this is a public function */ public?: boolean; /** Function description */ description?: string; } /** * Predefined function schemas * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionSchemas { /** Auth-related functions */ auth: { getUserProfile: FunctionSchema<{ userId: string; }, Record<string, unknown>>; updateUserProfile: FunctionSchema<Record<string, unknown>, Record<string, unknown>>; refreshToken: FunctionSchema<Record<string, never>, Record<string, unknown>>; }; /** Billing-related functions */ billing: { createCheckoutSession: FunctionSchema<Record<string, unknown>, Record<string, unknown>>; refreshSubscriptionStatus: FunctionSchema<Record<string, never>, Record<string, unknown>>; processPaymentSuccess: FunctionSchema<Record<string, unknown>, Record<string, unknown>>; }; /** Generic CRUD functions */ crud: { createEntity: FunctionSchema<Record<string, unknown>, Record<string, unknown>>; updateEntity: FunctionSchema<Record<string, unknown>, Record<string, unknown>>; deleteEntity: FunctionSchema<{ id: string; }, Record<string, unknown>>; getEntity: FunctionSchema<{ id: string; }, Record<string, unknown>>; listEntities: FunctionSchema<Record<string, unknown>, Record<string, unknown>[]>; }; } /** * Function call context * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionCallContext { /** User authentication token */ token?: string; /** User ID */ userId?: string; /** Request ID for tracking */ requestId?: string; /** Additional context data */ metadata?: Record<string, any>; } /** * Function client factory options * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionClientFactoryOptions { /** Default configuration */ config?: Partial<FunctionCallConfig>; /** Authentication token provider */ getToken?: () => Promise<string | null>; /** Error handler */ onError?: (error: FunctionError) => void; /** Request interceptor */ onRequest?: (functionName: string, params: any) => void; /** Response interceptor */ onResponse?: (functionName: string, response: any) => void; } /** * Memory allocation options for Cloud Functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FunctionMemory = '128MB' | '256MB' | '512MB' | '1GB' | '2GB' | '4GB' | '8GB'; /** * Function trigger types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FunctionTrigger = 'callable' | 'http' | 'pubsub' | 'firestore' | 'auth' | 'storage' | 'scheduled'; /** * Function-level deployment metadata * @description Per-function configuration for Firebase deployment (like PageMeta for pages) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionMeta { /** Custom entry point name (defaults to export name) */ entryPoint?: string; /** Deployment regions (overrides app defaults) */ region?: string[]; /** Platform version */ platform?: 'gcfv1' | 'gcfv2'; /** Category label for organization */ category?: 'auth' | 'crud' | 'analytics' | 'scheduled' | 'webhook' | string; /** Additional labels */ labels?: Record<string, string>; /** Trigger type (defaults to 'callable') */ trigger?: FunctionTrigger; /** For scheduled functions - cron expression */ schedule?: string; /** Memory allocation */ memory?: FunctionMemory; /** Timeout in seconds */ timeoutSeconds?: number; /** Minimum instances (for cold start optimization) */ minInstances?: number; /** Maximum instances */ maxInstances?: number; /** Secret environment variable names (synced via sync-secrets, read via defineSecret) */ secrets?: string[]; } /** * CRUD entity configuration for auto-generation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CrudConfig { /** Entity collection names to generate CRUD for */ entities: string[]; /** Override defaults for all CRUD functions */ defaults?: Partial<FunctionMeta>; } /** * App-level defaults for all functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionDefaults { /** Default deployment regions */ region?: string[]; /** Default platform version */ platform?: 'gcfv1' | 'gcfv2'; /** App label for all functions */ labels?: Record<string, string>; /** Default memory allocation */ memory?: FunctionMemory; /** Default timeout in seconds */ timeoutSeconds?: number; } /** * Complete functions configuration for an app * @description Single config file pattern for functions.yaml generation * * @example * ```typescript * export const functionsConfig: FunctionsConfig = { * defaults: { * region: ['europe-west1'], * platform: 'gcfv2', * labels: { app: 'myapp' }, * }, * functions: { * setCustomClaims: { category: 'auth' }, * getDashboardMetrics: { category: 'analytics', memory: '512MB' }, * }, * crud: { * entities: ['car', 'customer', 'inquiry'], * }, * }; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionsConfig { /** App-level defaults applied to all functions */ defaults?: FunctionDefaults; /** Static functions configuration (non-CRUD) */ functions?: Record<string, FunctionMeta>; /** CRUD auto-generation configuration */ crud?: CrudConfig; } /** * Generated function endpoint entry (for YAML output) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FunctionEndpoint { /** Function name (key in endpoints object) */ name: string; /** Deployment regions */ region: string[]; /** Platform version */ platform: 'gcfv1' | 'gcfv2'; /** Trigger configuration */ callableTrigger?: Record<string, never>; httpsTrigger?: Record<string, never>; scheduleTrigger?: { schedule: string; }; /** Entry point in bundled code */ entryPoint: string; /** Labels for organization */ labels: Record<string, string>; /** Memory allocation */ memory?: string; /** Timeout */ timeoutSeconds?: number; /** Min instances */ minInstances?: number; /** Max instances */ maxInstances?: number; /** Secret environment variables */ secretEnvironmentVariables?: Array<{ key: string; }>; } /** * @fileoverview I18n Types * @description Type definitions for internationalization. Defines entity translations, i18n configuration types, and translation-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Entity translation interface * Maps entity field names to their translated labels and hints * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EntityTranslations { /** Translated field labels */ fields: Record<string, string>; /** Translated field hints/descriptions */ hints: Record<string, string>; /** Translated validation error messages */ validations?: Record<string, string>; /** Translated placeholder text */ placeholders?: Record<string, string>; } /** * Common translation interface for shared UI elements * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CommonTranslations { /** Action button translations */ actions: { create: string; update: string; delete: string; cancel: string; confirm: string; }; /** Error message translations */ errors: Record<string, string>; /** Common label translations */ labels: Record<string, string>; } /** * Translation options interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TranslationOptions { /** Language code (e.g., 'en', 'fr') */ lng: string; /** Optional namespace array */ ns?: string[]; /** Fallback language code */ fallbackLng?: string; } /** * Supported language codes * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type SupportedLanguage = string; /** * Interface for language information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LanguageInfo$1 { /** ISO 639-1 language code (e.g., 'en', 'fr') */ code: string; /** Native name of the language (e.g., 'English', 'Français') */ name: string; } /** * Language data type — single source of truth for language metadata. * Used by i18n constants, language store, and language selector components. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LanguageData { /** BCP-47 language code (e.g., 'en', 'fr', 'ar-ma') */ id: string; /** English display name */ name: string; /** Native script display name */ nativeName: string; /** Override flag code when it differs from the language id */ flagCode?: string; /** ISO 3166-1 alpha-2 country code */ countryCode?: string; /** International dialing code (e.g., '+33') */ dialCode?: string; /** Human-readable country name for display labels */ countryName?: string; } /** * Interface for configurations to initialize the i18n system * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface I18nConfig { /** Patterns for eager namespaces */ eagerPatterns: string[]; /** Patterns for lazy namespaces */ lazyPatterns: string[]; /** App namespace patterns (eagerly loaded) */ eagerNamespaces: string[]; /** Custom namespace patterns for arbitrary use cases (lazily loaded) */ lazyNamespaces: string[]; /** Performance options */ performance: { /** Maximum number of translations to keep in memory cache */ cacheSize: number; /** Time to live for cached errors in milliseconds */ errorCacheTTL: number; /** Timeout for loading operations in milliseconds */ loadTimeout: number; }; /** Language options */ languages: { /** List of supported language codes */ supported: string[]; /** Default language code */ default: string; /** Fallback language code */ fallback: string; }; /** Debug mode flag */ debug: boolean; /** Protocol name for virtual loader (default: 'virtual') */ virtualProtocol: string; /** Additional i18next initialization options */ i18nextOptions: Partial<InitOptions>; /** Force production mode */ forceProduction: boolean; /** Force development mode */ forceDevelopment: boolean; } /** * Interface representing the structure of a translations resource * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TranslationResource { /** Language code (e.g., 'en', 'fr') */ [language: string]: { /** Namespace (e.g., 'common', 'auth') */ [namespace: string]: Record<string, any>; }; } /** * Enhanced options for useTranslation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type UseTranslationOptionsEnhanced<KPrefix> = Parameters<typeof useTranslation$1>[1] & { /** Whether this namespace is an app namespace */ appNamespace?: boolean; }; /** * Props for the I18nProvider component * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface I18nProviderProps { /** Child components to render */ children: ReactNode; /** Initial configuration */ config?: Partial<I18nConfig>; /** Initial language to use */ fallbackLng?: string; /** Pre-initialized i18n instance */ i18n?: any; /** Optional callback when i18n initialization completes */ onInitialized?: (i18n: any) => void; /** Health monitoring flag (defaults to true) */ healthMonitoring?: boolean; /** Loading component to display while initializing */ loadingComponent?: ReactNode; /** Error component to display if initialization fails */ errorComponent?: ReactNode; } /** * Information about a cached error * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CachedError { /** The error object */ error: Error; /** Timestamp when the error occurred */ timestamp: number; } /** * Custom read callback for i18next backend * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ReadCallback = (err: any, data: any) => void; /** * @fileoverview Breakpoint Types * @description Breakpoint type definitions for responsive design. Defines the standard breakpoints used throughout the framework for responsive layout and component behavior. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Breakpoint type definition for responsive design * * Defines the standard breakpoints used throughout the framework * for responsive layout and component behavior. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Breakpoint = 'mobile' | 'tablet' | 'laptop' | 'desktop'; /** * Breakpoint pixel values * * Standard breakpoint thresholds used for responsive design. * These values match the CSS variables in layout-variables.css * and are used by the theme store and layout system. */ /** * Breakpoint threshold values for calculation * * These are the actual breakpoint boundaries used for responsive logic. * Each value represents the minimum width for that breakpoint. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const BREAKPOINT_THRESHOLDS: { readonly mobile: 0; readonly tablet: 768; readonly laptop: 1024; readonly desktop: 1440; }; /** * Breakpoint pixel ranges * * Defines the pixel ranges for each breakpoint to help with * responsive design calculations and media queries. * These ranges match the CSS media queries and store logic. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const BREAKPOINT_RANGES: Record<Breakpoint, { min: number; max: number; }>; /** * Breakpoint utilities interface * * Provides computed breakpoint state and helper methods * for responsive design logic. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BreakpointUtils { /** Current active breakpoint */ current: Breakpoint; /** Current window width in pixels */ width: number; /** Current window height in pixels */ height: number; /** Whether current viewport is mobile (0-767px) */ isMobile: boolean; /** Whether current viewport is tablet (768-1023px) */ isTablet: boolean; /** Whether current viewport is laptop (1024-1439px) */ isLaptop: boolean; /** Whether current viewport is desktop (1440px+) */ isDesktop: boolean; /** Whether current viewport is mobile OR tablet (< 1024px) */ isMobileOrTablet: boolean; /** Whether current viewport is laptop OR desktop (>= 1024px) */ isLaptopOrDesktop: boolean; } /** * Get breakpoint from window width * * @param width - Window width in pixels * @returns The corresponding breakpoint * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getBreakpointFromWidth(width: number): Breakpoint; /** * Check if a breakpoint matches the current width * * @param width - Window width in pixels * @param breakpoint - Target breakpoint to check * @returns Whether the width matches the breakpoint * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isBreakpoint(width: number, breakpoint: Breakpoint): boolean; /** * Get breakpoint utilities from window dimensions * * @param width - Window width in pixels * @param height - Window height in pixels * @returns Computed breakpoint utilities * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getBreakpointUtils(width: number, height: number): BreakpointUtils; /** * @fileoverview Legal Configuration Types * @description Type definitions for legal pages configuration (Terms, Privacy, Legal Notice) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Company/Publisher Information * * Information about the company or individual publishing the website */ interface LegalCompanyInfo { /** * Full legal name of the company or individual * @example "AMBROISE PARK Consulting" * @example "John Doe" */ name: string; /** * Short name or abbreviation * @example "APC" * @example "ACME Inc." */ shortName?: string; /** * Legal status/form of the company * @example "SARL" (France - Limited Liability Company) * @example "SAS" (France - Simplified Joint-Stock Company) * @example "LLC" (USA - Limited Liability Company) * @example "GmbH" (Germany) * @example "Ltd" (UK) */ legalStatus?: string; /** * Company registration number * @description Required in many countries for legal compliance * @example "123 456 789 00010" (France - SIRET number) * @example "12345678" (UK - Company Number) * @example "123-45-6789" (USA - EIN) */ registrationNumber?: string; /** * VAT/Tax identification number * @description Required for EU businesses and many other jurisdictions * @example "FR12345678901" (France) * @example "DE123456789" (Germany) * @example "GB123456789" (UK) */ vatNumber?: string; /** * Share capital (for companies) * @description Required to be disclosed in some jurisdictions (e.g., France) * @example "10,000 EUR" * @example "50,000 USD" */ shareCapital?: string; } /** * Contact Information * * Various contact points for legal, support, and privacy inquiries */ interface LegalContactInfo { /** * Registered office address * @description Physical address where the company is legally registered * @example "123 rue de la Paix, 75001 Paris, France" * @example "1 Main Street, Suite 100, New York, NY 10001, USA" */ address: string; /** * General legal contact email * @description For legal inquiries and notices * @example "legal@company.com" */ email: string; /** * Contact phone number * @description Optional but recommended for legal compliance * @example "+33 1 23 45 67 89" * @example "+1 (555) 123-4567" */ phone?: string; /** * Support email for customer inquiries * @example "support@company.com" */ supportEmail: string; /** * Privacy-specific email * @description For privacy policy and data protection inquiries * @example "privacy@company.com" */ privacyEmail: string; /** * Data Protection Officer (DPO) email * @description Required for GDPR compliance if you process significant personal data * @example "dpo@company.com" */ dpoEmail: string; } /** * Publication Director Information * * Information about the person responsible for the website's content * Required by law in France ("Directeur de la publication") */ interface LegalDirectorInfo { /** * Full name of the publication director * @description The person legally responsible for the website's content * @example "John Doe" * @example "Jane Smith" */ name: string; /** * Role/title of the publication director * @example "CEO" * @example "Directeur Général" * @example "Managing Director" */ role?: string; } /** * Hosting Provider Information * * Information about where and how the website is hosted * Required by law in many jurisdictions including France */ interface LegalHostingInfo { /** * Name of the hosting provider * @example "Firebase Hosting by Google" * @example "AWS (Amazon Web Services)" * @example "OVH" */ provider: string; /** * Hosting provider's address * @description Physical address of the hosting company * @example "Google LLC, 1600 Amphitheatre Parkway, Mountain View, CA 94043, USA" */ address?: string; /** * Hosting provider contact information * @description URL or email to contact the hosting provider * @example "https://firebase.google.com/support" * @example "support@hostingprovider.com" */ contact?: string; } /** * Legal Jurisdiction Information * * Information about the legal jurisdiction and dispute resolution */ interface LegalJurisdictionInfo { /** * Country or jurisdiction where the company operates * @example "France" * @example "United States" * @example "United Kingdom" */ country: string; /** * Arbitration organization for dispute resolution * @example "Centre de Médiation et d'Arbitrage de Paris" * @example "American Arbitration Association" * @example "International Chamber of Commerce" */ arbitrationOrg?: string; /** * Location where arbitration would take place * @example "Paris, France" * @example "New York, NY" */ arbitrationLocation?: string; } /** * Website Information */ interface LegalWebsiteInfo { /** * Main website URL * @example "https://company.com" * @example "https://www.example.com" */ url: string; } /** * Optional Sections Configuration for Legal Pages */ interface LegalSectionsConfig { /** * Terms of Service optional sections */ terms?: { /** Include children-specific provisions (COPPA, etc.) */ children?: boolean; /** Include international users provisions */ international?: boolean; /** Include California-specific provisions (CCPA, etc.) */ california?: boolean; /** Include EU-specific provisions */ eu?: boolean; }; /** * Privacy Policy optional sections */ privacy?: { /** Include children's privacy provisions (COPPA, etc.) */ children?: boolean; /** Include international data transfer provisions */ international?: boolean; /** Include California privacy rights (CCPA, etc.) */ california?: boolean; /** Include EU privacy provisions (GDPR) */ eu?: boolean; }; /** * Legal Notice optional sections */ legalNotice?: { /** Include intellectual property notice */ intellectualProperty?: boolean; /** Include personal data reference/link to privacy policy */ personalData?: boolean; /** Include cookies reference/link to privacy policy */ cookies?: boolean; }; } /** * Complete Legal Configuration * * @description * Centralized configuration for all legal pages (Terms, Privacy, Legal Notice). * Configure this once in your app's config/legal.ts file. * * @example * ```typescript * import type { LegalConfig } from '@donotdev/types'; * * export const legalConfig: LegalConfig = { * company: { * name: 'ACME Corporation', * legalStatus: 'LLC', * registrationNumber: '123456789', * vatNumber: 'US123456789', * }, * contact: { * address: '123 Main St, City, State 12345, Country', * email: 'legal@acme.com', * supportEmail: 'support@acme.com', * privacyEmail: 'privacy@acme.com', * dpoEmail: 'dpo@acme.com', * }, * director: { * name: 'John Doe', * role: 'CEO', * }, * hosting: { * provider: 'Firebase Hosting by Google', * contact: 'https://firebase.google.com/support', * }, * jurisdiction: { * country: 'United States', * }, * website: { * url: 'https://acme.com', * }, * }; * ``` */ interface LegalConfig { /** Company/Publisher information */ company: LegalCompanyInfo; /** Contact information */ contact: LegalContactInfo; /** Publication director information */ director: LegalDirectorInfo; /** Hosting provider information */ hosting: LegalHostingInfo; /** Legal jurisdiction information */ jurisdiction: LegalJurisdictionInfo; /** Website information */ website: LegalWebsiteInfo; /** Sections configuration for legal pages */ sections: LegalSectionsConfig; /** Last updated dates (ISO strings) for each legal page */ lastUpdated?: { /** Terms of Service last updated date (ISO string) */ terms?: string; /** Privacy Policy last updated date (ISO string) */ privacy?: string; /** Legal Notice last updated date (ISO string) */ legalNotice?: string; }; } /** * @fileoverview OAuth Constants * @description Constants for OAuth domain. Defines GitHub repository permission levels and OAuth-related constants. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * GitHub repository permission levels (runtime constants) * Keep in sync with GitHub API scopes/permissions. */ declare const GITHUB_PERMISSION_LEVELS: readonly ["pull", "push", "admin", "maintain", "triage"]; /** * OAuth purpose type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthPurpose = 'authentication' | 'api-access'; /** * @fileoverview OAuth Schema Definitions * @description Schema definitions for OAuth domain. Defines Valibot schemas for GitHub repository configuration, permission levels, and OAuth-related data structures. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Schema for GitHub repository configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const githubRepoConfigSchema: v.ObjectSchema<{ readonly owner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository owner is required">]>; readonly repo: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository name is required">]>; }, undefined>; /** * Schema for GitHub access permission levels * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const githubPermissionSchema: v.PicklistSchema<[string, ...string[]], undefined>; /** * Schema for granting GitHub repository access * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const grantGitHubAccessSchema: v.ObjectSchema<{ readonly userId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "User ID is required">]>; readonly githubUsername: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "GitHub username is required">]>; readonly repoConfig: v.ObjectSchema<{ readonly owner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository owner is required">]>; readonly repo: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository name is required">]>; }, undefined>; readonly permission: v.OptionalSchema<v.PicklistSchema<[string, ...string[]], undefined>, "push">; readonly customClaims: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.AnySchema, undefined>, undefined>; }, undefined>; /** * Schema for revoking GitHub repository access * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const revokeGitHubAccessSchema: v.ObjectSchema<{ readonly userId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "User ID is required">]>; readonly githubUsername: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "GitHub username is required">]>; readonly repoConfig: v.ObjectSchema<{ readonly owner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository owner is required">]>; readonly repo: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository name is required">]>; }, undefined>; }, undefined>; /** * Schema for checking GitHub repository access * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const checkGitHubAccessSchema: v.ObjectSchema<{ readonly userId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "User ID is required">]>; readonly githubUsername: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "GitHub username is required">]>; readonly repoConfig: v.ObjectSchema<{ readonly owner: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository owner is required">]>; readonly repo: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Repository name is required">]>; }, undefined>; }, undefined>; /** * TypeScript type exports for GitHub access schemas * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type GrantGitHubAccessRequest = v.InferOutput<typeof grantGitHubAccessSchema>; /** * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type RevokeGitHubAccessRequest = v.InferOutput<typeof revokeGitHubAccessSchema>; /** * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CheckGitHubAccessRequest = v.InferOutput<typeof checkGitHubAccessSchema>; /** * Schema for OAuth token exchange requests * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const exchangeTokenSchema: v.ObjectSchema<{ readonly provider: v.BaseSchema<unknown, OAuthPartnerId, v.BaseIssue<unknown>>; readonly purpose: v.BaseSchema<unknown, OAuthPurpose, v.BaseIssue<unknown>>; readonly code: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Authorization code is required">]>; readonly redirectUri: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, "Valid redirect URI is required">]>; readonly codeVerifier: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly state: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly instance: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>, undefined>; }, undefined>; /** * Schema for refreshing OAuth token * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const refreshTokenSchema: v.ObjectSchema<{ readonly provider: v.BaseSchema<unknown, OAuthPartnerId, v.BaseIssue<unknown>>; readonly refreshToken: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "Refresh token is required">]>; readonly redirectUri: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, "Valid redirect URI is required">]>; }, undefined>; /** * Schema for disconnecting OAuth * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const disconnectOAuthSchema: v.ObjectSchema<{ readonly provider: v.BaseSchema<unknown, OAuthPartnerId, v.BaseIssue<unknown>>; }, undefined>; /** * Schema for getting OAuth connections * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const getConnectionsSchema: v.ObjectSchema<{ readonly userId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "User ID is required">]>; }, undefined>; /** * @fileoverview OAuth Types * @description Type definitions for OAuth domain. Defines base credentials, user profiles, OAuth partner types, and OAuth-related interfaces. * Uses unified FeatureStatus enum for feature state management. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Base credentials interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseCredentials { expiresAt?: number; scope?: string[]; } /** * Base user profile interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseUserProfile { id: string; name?: string; username?: string; email?: string; photoURL?: string; } /** * Base partner state interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BasePartnerState { config: any; error: Error | null; } /** * OAuth credentials interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthCredentials extends BaseCredentials { accessToken: string; refreshToken?: string; idToken?: string; tokenType?: string; expiresIn?: number; } /** * OAuth partner result interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthPartnerResult extends PartnerResult { partnerId: OAuthPartnerId; purpose: OAuthPurpose; credentials?: OAuthCredentials; } /** * OAuth partner state interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthPartnerState extends PartnerConnectionState { partnerId: OAuthPartnerId; config: OAuthPartner; credentials: OAuthCredentials | null; } /** * OAuth API request options interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthApiRequestOptions extends RequestInit { autoRefresh?: boolean; requireConnection?: boolean; } /** * OAuth connection status type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error' | 'expired'; /** * OAuth result type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthResult = { success: true; partner: string; accessToken: string; refreshToken?: string; idToken?: string; expiresIn?: number; scope?: string; tokenType?: string; profile?: Record<string, any>; } | { success: false; error: string; errorDescription?: string; attemptedPartner?: string; }; /** * Exchange token parameters interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ExchangeTokenParams { provider: OAuthPartnerId; purpose: OAuthPurpose; code: string; redirectUri: string; codeVerifier?: string; } /** * OAuth connection info interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthConnectionInfo { id: string; userId: string; provider: OAuthPartnerId; purpose: OAuthPurpose; connected: boolean; createdAt: string; updatedAt: string; lastUsed?: string; credentials?: OAuthCredentials; profile?: BaseUserProfile; } /** * OAuth connection interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthConnection { partnerId: OAuthPartnerId; status: OAuthConnectionStatus; connectedAt?: Date; lastError?: string; userData?: any; lastTokenUpdate?: Date; } /** * OAuth connection request interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthConnectionRequest { provider: OAuthPartnerId; purpose: OAuthPurpose; credentials: OAuthCredentials; profile?: BaseUserProfile; } /** * OAuth partner hook result interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthPartnerHookResult { partnerState: OAuthPartnerState; isConnecting: boolean; isConnected: boolean; error: Error | null; credentials: OAuthCredentials | null; connect: (options?: { purpose?: OAuthPurpose; redirectUri?: string; scopes?: string[]; additionalParams?: Record<string, string>; onSuccess?: (result: OAuthPartnerResult) => void; onError?: (error: Error) => void; }) => Promise<void>; disconnect: () => Promise<boolean>; refreshToken: () => Promise<OAuthCredentials | null>; request: <T = any>(url: string, options?: OAuthApiRequestOptions) => Promise<T>; } /** * OAuth callback hook result interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthCallbackHookResult { isCallback: boolean; processing: boolean; result: OAuthResult | null; partnerName: string | null; success: boolean; error: Error | null; } /** * Exchange token request interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ExchangeTokenRequest { provider: OAuthPartnerId; purpose: OAuthPurpose; code: string; redirectUri: string; codeVerifier?: string; state?: string; instance?: string; idempotencyKey?: string; } /** * Token response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TokenResponse { access_token: string; token_type?: string; expires_in?: number; refresh_token?: string; scope?: string; id_token?: string; created_at?: number; } /** * OAuth refresh request interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthRefreshRequest { provider: OAuthPartnerId; refreshToken: string; redirectUri: string; } /** * OAuth refresh response interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthRefreshResponse { access_token: string; token_type?: string; expires_in?: number; refresh_token?: string; scope?: string; } /** * GitHub repository configuration type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type GitHubRepoConfig = v.InferOutput<typeof githubRepoConfigSchema>; /** * GitHub permission type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type GitHubPermission = v.InferOutput<typeof githubPermissionSchema>; /** * Options for `useOAuth('connect')`. * Allows scope customization and extra auth URL parameters. * * @example * ```typescript * const connect = useOAuth('connect'); * // Simple (defaults): * await connect('github'); * // With scope override: * await connect('github', { purpose: 'api-access', scopes: ['repo', 'user:email'] }); * ``` * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ interface ConnectOptions { /** OAuth purpose — defaults to 'api-access' */ purpose?: OAuthPurpose; /** Override default scopes from schema. Only these scopes will be requested. */ scopes?: string[]; /** Extra query parameters to append to the auth URL */ additionalParams?: Record<string, string>; } /** * Normalized response from server-side token exchange. * Callable providers (Firebase, Supabase) return this shape. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ interface ExchangeTokenResponse { success: boolean; credentials: OAuthCredentials; profile?: BaseUserProfile; } /** * OAuth API type - complete interface for useOAuth hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthAPI { /** * Unified feature status - single source of truth for OAuth state. * Replaces deprecated `loading` boolean flag. * - `initializing`: OAuth is loading/initializing * - `ready`: OAuth fully operational * - `degraded`: OAuth unavailable (feature not installed/consent not given) * - `error`: OAuth encountered error */ status: FeatureStatus; error: string | null; partners: Record<OAuthPartnerId, any>; connectedPartners: OAuthPartnerId[]; connect: (partnerId: OAuthPartnerId, options?: ConnectOptions) => Promise<void>; disconnect: (partnerId: OAuthPartnerId) => Promise<void>; isConnected: (partnerId: OAuthPartnerId) => boolean; getCredentials: (partnerId: OAuthPartnerId) => OAuthCredentials | null; handleCallback: (partnerId: OAuthPartnerId, code: string, state?: string) => Promise<void>; isAvailable: boolean; } /** * @fileoverview Callable Provider Interface * @description Provider-agnostic interface for invoking server-side functions. * Firebase uses `httpsCallable`; Supabase uses `functions.invoke()`. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** * Provider-agnostic interface for calling server-side functions. * * @example * ```typescript * const callable: ICallableProvider = new SupabaseCallableProvider(client); * const result = await callable.call<{ userId: string }, { success: boolean }>( * 'delete-account', * { userId: '123' } * ); * ``` * * @version 0.1.0 * @since 0.5.0 */ interface ICallableProvider { call<TReq, TRes>(functionName: string, data: TReq): Promise<TRes>; } /** * @fileoverview Storage Adapter Interface * @description Provider-agnostic interface for file/image storage. * Any storage backend (Firebase Storage, S3, Cloudflare R2, Supabase Storage) must implement this contract. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** Progress callback for upload operations (0-100) */ type UploadProgressCallback = (percent: number) => void; /** Options for file upload */ interface UploadOptions { /** Folder path within the storage bucket (e.g. 'photos/2024'). Omit to upload to bucket root. */ storagePath?: string; /** Custom filename override */ filename?: string; /** Progress callback */ onProgress?: UploadProgressCallback; /** AbortSignal to cancel the upload */ signal?: AbortSignal; } /** Result of an upload operation */ interface UploadResult { /** Public URL of the uploaded file */ url: string; /** Storage path of the uploaded file (for deletion) */ path: string; } /** * Provider-agnostic storage adapter interface. * * Implementations: * - `FirebaseStorageAdapter` (Firebase Storage) * - Future: S3, Cloudflare R2, Supabase Storage adapters * * @version 0.1.0 * @since 0.5.0 */ interface IStorageAdapter { /** Upload a file or blob to storage. Returns the public URL and storage path. */ upload(file: File | Blob, options?: UploadOptions): Promise<UploadResult>; /** Delete a file by its URL or storage path. */ delete(urlOrPath: string, options?: { signal?: AbortSignal; }): Promise<void>; /** Get the public download URL for a storage path. */ getUrl(path: string): Promise<string>; } /** * @fileoverview Provider Registry Types * @description Types for pluggable backends (CRUD, auth, storage, callable). * Consumers call `configureProviders()` once at app startup; `useCrud` and auth hooks * use these providers. Import `config/providers` from main.tsx before any CRUD usage. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** * All pluggable providers for the DoNotDev framework. * * - **crud** (required): CRUD adapter. Required for `useCrud` and entity operations. * - **auth** (optional): Client auth. Omit if using external auth. * - **storage** (optional): File/image storage. Omit if no uploads. * - **serverAuth** (optional): Server-side token verification. * - **callable** (optional): Server function invocation (e.g. Supabase Edge Functions). * * @example Firebase * ```typescript * configureProviders({ * crud: new FirestoreAdapter(), * auth: new FirebaseAuth(), * storage: new FirebaseStorageAdapter(), * }); * ``` * * @example Supabase * ```typescript * configureProviders({ * crud: new SupabaseCrudAdapter(supabase), * auth: new SupabaseAuth(supabase), * storage: new SupabaseStorageAdapter(supabase, 'your-bucket'), * }); * ``` * * @version 0.1.0 * @since 0.5.0 */ interface DndevProviders { /** Client-side authentication provider */ auth?: AuthProvider; /** Server-side token verification and user management */ serverAuth?: IServerAuthAdapter; /** Database / CRUD operations (required) */ crud: ICrudAdapter; /** File and image storage */ storage?: IStorageAdapter; /** Server-side function invocation (Edge Functions, Cloud Functions, API routes) */ callable?: ICallableProvider; } /** * @fileoverview Network-Related Type Definitions * @description Centralized types for network connectivity, status tracking, and monitoring. Defines network connection types, network state, and network-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Possible network connection types based on the Network Information API * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type NetworkConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown'; /** * Effective connection speed types from the Network Information API * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g' | 'unknown'; /** * Represents the network connectivity status. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface NetworkStatus { /** * Indicates whether the device has an active internet connection. * This is the primary status that authentication and other critical systems should check. */ online: boolean; /** * The general type of the current network connection. * Based on the Network Information API. */ connectionType: NetworkConnectionType; /** * The effective connection type based on measured performance. * Based on the Network Information API, might be 'unknown' if unavailable. */ effectiveType?: EffectiveConnectionType | string; /** The timestamp when the network status was last checked or updated. */ lastChecked: Date; } /** * Network state specifically for store usage * Variant of NetworkStatus with string timestamp for serialization * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface NetworkState$1 { /** Whether the device is currently online */ online: boolean; /** * Type of network connection if available * Uses the full range of network connection types from the Network Information API */ connectionType: NetworkConnectionType; /** * The effective connection type based on measured performance. * Based on the Network Information API, might be 'unknown' if unavailable. */ effectiveType?: EffectiveConnectionType | string; /** ISO date string of when network status was last checked */ lastChecked: string; } /** * Configuration options for the NetworkManager. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface NetworkCheckConfig { /** * URL to ping (using a HEAD request) to verify actual internet connectivity. * Defaults to a reliable Google endpoint. Set to null or empty string to disable pinging. * @default "https://www.gstatic.com/generate_204" */ pingEndpoint?: string | null; /** * Timeout in milliseconds for the ping request. * @default 5000 */ pingTimeout?: number; /** * Interval in milliseconds for periodically checking network connectivity via ping. * @default 30000 (30 seconds) */ checkInterval?: number; /** * Debounce time in milliseconds for processing browser online/offline events * to avoid rapid status fluctuations. * @default 300 */ debounceTime?: number; } /** * Function signature for network reconnection callbacks * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type NetworkReconnectCallback = () => void; /** * Generic observable interface to avoid circular dependencies * This allows us to define the interface without depending on Subject implementation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface Observable<T> { subscribe: (next: (value: T) => void, error?: (error: any) => void, complete?: () => void) => { unsubscribe: () => void; }; } /** * Network manager interface for observing and controlling network status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface INetworkManager { /** Get the current network status */ getStatus(): NetworkStatus; /** * Observe network status changes * @returns An observable of NetworkStatus updates */ observeStatus(): Observable<NetworkStatus>; /** * Register a callback for reconnection events * @param callback Function to execute when network reconnects * @returns Unsubscribe function */ onReconnect(callback: NetworkReconnectCallback): () => void; /** * Manually check connectivity * @param url Optional custom URL to check * @returns Promise resolving to true if online, false otherwise */ checkConnectivity(url?: string): Promise<boolean>; /** Clean up resources */ destroy(): void; } /** * @fileoverview Rate Limiter Types * @description Type definitions for rate limiting. Defines rate limit configuration, rate limit state, rate limit result, and rate limiting-related interfaces. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Configuration options for rate limiting * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimitConfig { /** Maximum number of allowed attempts within the window */ maxAttempts: number; /** Time window in milliseconds */ windowMs: number; /** Duration to block after maxAttempts is reached (ms) */ blockDurationMs: number; /** * Whether to increase block duration exponentially for repeated blocks * @default true */ useExponentialBackoff?: boolean; /** * Key for storage - should be unique per application or feature * @default "dndev_auth_ratelimit" */ storageKey: string; /** * Maximum block duration in milliseconds * @default 86400000 (24 hours) */ maxBlockDurationMs?: number; } /** * Result of a rate limit check * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimitResult { /** Whether the operation is allowed */ allowed: boolean; /** Number of attempts remaining before being rate limited */ remaining: number; /** When the rate limit window or block will reset */ resetAt: Date | null; /** Seconds remaining in block (null if not blocked) */ blockRemainingSeconds: number | null; } /** * Internal structure used by RateLimiter to store attempt timestamps and block info. * @private * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AttemptRecord { /** Array of attempts with timestamps and optional identifiers */ attempts: Array<{ /** When the attempt was made */ timestamp: number; /** Optional identifier (e.g., email, username) */ identifier?: string; }>; /** Timestamp when the block expires, or null if not blocked */ blockUntil: number | null; /** Number of consecutive times blocking occurred (for exponential backoff) */ blockCount: number; } /** * Rate limiter interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimiter { /** * Check if an operation is allowed and record an attempt * @param identifier Optional identifier (e.g. email, username) * @returns Rate limit result */ consume(identifier?: string): RateLimitResult; /** * Check rate limit without recording an attempt * @param identifier Optional identifier * @returns Rate limit result */ check(identifier?: string): RateLimitResult; /** * Reset rate limiting state */ reset(): void; /** * Reset rate limiting for a specific identifier * @param identifier The identifier to reset */ resetForIdentifier(identifier: string): void; } /** * Rate limiting state for a specific operation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimitState { /** Number of attempts made in the current window */ attempts: number; /** ISO date string when the current rate limit window started */ windowStart: string; /** ISO date string when the block expires, or null if not blocked */ blockUntil: string | null; } /** * Rate limit manager interface for application-wide use * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RateLimitManager { /** * Get a rate limiter for a specific operation * @param operation Operation to rate limit * @param config Optional configuration overrides */ getLimiter(operation: string, config?: Partial<RateLimitConfig>): RateLimiter; /** * Reset all rate limiters */ resetAll(): void; } /** * @fileoverview Store Types * @description Type definitions for store system. Defines store API types, state types, and store-related interfaces for managing application state. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * DoNotDev store API interface without direct Zustand dependency. * Renamed from StoreApi to avoid shadowing Zustand's StoreApi. * @template T - The store state type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DndevStoreApi<T> { /** Returns the current state */ getState: () => T; /** Updates the store state */ setState: (partial: Partial<T> | ((state: T) => Partial<T>), replace?: boolean) => void; /** Subscribes to state changes */ subscribe: (listener: (state: T, prevState: T) => void) => () => void; } /** * Base store state that all stores should implement * Provides common properties for loading, error handling, and readiness * * **Lifecycle Timeline:** * 1. Store created → `isReady: false`, `isDataResolved: false` * 2. Service init complete → `isReady: true`, `isDataResolved: false` * 3. First async callback → `isReady: true`, `isDataResolved: true` * * @property isReady - Service is initialized and methods can be called * @property isDataResolved - First async data callback has fired (user/data resolved) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseStoreState { /** Whether the store is ready to be used by components */ isReady: boolean; /** Whether the store is currently loading */ isLoading: boolean; /** Current error message, or null if no error */ error: string | null; /** * Whether Zustand persist middleware has finished rehydrating from storage. * Only present on stores created with persistOptions. * `false` before rehydration, `true` after. Non-persisted stores: undefined. */ _hasHydrated?: boolean; /** * Whether the first async data callback has fired. * Optional - only needed for stores with async data sources (e.g., auth, realtime). * * For AuthStore: equivalent to `authStateChecked` (first onAuthStateChanged) * For other stores: set when initial data load completes */ isDataResolved?: boolean; } /** * Base store actions that all stores should implement * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseStoreActions { /** Set the store readiness state */ setReady: (ready: boolean) => void; /** Set the loading state */ setLoading: (loading: boolean) => void; /** Set the error state */ setError: (error: string | null) => void; /** Clear the current error */ clearError: () => void; /** Reset the store to initial state */ reset: () => void; /** * Set the data resolved state (optional). * Only implement for stores with async data sources. * * For AuthStore: call when first onAuthStateChanged fires * For other stores: call when initial data load completes */ setDataResolved?: (resolved: boolean) => void; } /** * Base UI state for an entity. * @template T - The entity type. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseState<T> extends BaseStoreState { /** Currently selected item */ selected?: T; /** Active filters */ filters: Record<string, any>; /** Current sort configuration */ sort?: { field: keyof T; direction: 'asc' | 'desc'; }; } /** * Base actions for UI state management. * @template T - The entity type. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BaseActions<T> extends BaseStoreActions { /** Select or deselect an item */ select: (item?: T) => void; /** Update active filters */ setFilters: (filters: Record<string, any>) => void; /** Set the sorting configuration */ setSort: (field: keyof T, direction: 'asc' | 'desc') => void; } /** * Combined store type including state and actions. * @template T - The entity type. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Store<T> = BaseState<T> & BaseActions<T>; /** * Authentication token state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TokenState { /** The authentication token string or null if not authenticated */ token: string | null; /** ISO date string of when the token expires */ expiresAt: string | null; /** Current status of the token */ status: TokenStatus; } /** * OAuth store state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthStoreState { connections: Record<OAuthPartnerId, OAuthPartnerState>; loading: boolean; error: Error | null; } /** * Simple auth state store interface - only state, no mechanisms * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AuthStateStore { authenticated: boolean; userId: string | null; user: AuthUser | null; role: UserRole; token: { token: string | null; expiresAt: Date | null; status: TokenStatus; }; network: { online: boolean; connectionType: NetworkConnectionType; lastChecked: string; }; rateLimit: Record<string, RateLimitState>; error: string | null; errorCode: string | undefined; loading: boolean; initialized: boolean; subscription: { tier: string; isActive: boolean; expiresAt: Date | null; features: string[]; daysRemaining: number | null; }; setAuthenticated: (authenticated: boolean, userId?: string | null) => void; setUser: (user: AuthUser | null) => void; setRole: (role: UserRole) => void; setToken: (token: string | null, expiresAt?: Date | null) => void; updateTokenStatus: (status: TokenStatus) => void; setNetworkStatus: (online: boolean, connectionType?: NetworkConnectionType) => void; setError: (error: string | null, errorCode?: string) => void; setLoading: (loading: boolean) => void; setSubscription: (subscription: { tier: string; isActive: boolean; expiresAt: Date | null; features: string[]; daysRemaining: number | null; }) => void; setInitialized: (initialized: boolean) => void; clearError: () => void; reset: () => void; } /** * OAuth store actions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface OAuthStoreActions { setLoading: (loading: boolean) => void; setGlobalError: (error: Error | null) => void; reset: () => void; isConnected: (partnerId: OAuthPartnerId, purpose?: OAuthPurpose) => boolean; getCredentials: (partnerId: OAuthPartnerId) => OAuthCredentials | null; } /** * @fileoverview UI Types * @description Type definitions for UI system. Defines UI-related interfaces and form field types. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Theme information structure with enhanced metadata * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ThemeInfo { /** Unique theme identifier */ name: string; /** User-friendly display name */ displayName: string; /** Theme description */ description?: string; /** Whether this is a dark theme */ isDark: boolean; /** CSS variables for this theme */ variables?: Record<string, string>; /** Enhanced theme metadata */ meta: { /** Icon identifier for UI (e.g., 'SunIcon', 'MoonIcon') */ icon: string; /** Optional theme description for UI */ description?: string; /** Optional category for grouping themes */ category?: string; /** Optional author information */ author?: string; /** Additional metadata */ [key: string]: any; }; } /** * Theme mode setting * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ThemeMode = 'light' | 'dark' | 'auto'; /** * Theme state in the store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ThemeState { /** Currently active theme */ currentTheme: string; /** List of available themes */ availableThemes: ThemeInfo[]; /** Whether dark mode is currently active */ isDarkMode: boolean; /** User's theme mode preference */ themeMode: ThemeMode; /** Loading state for theme operations */ isLoading: boolean; /** Error state for theme operations */ error: string | null; } /** * Enhanced theme actions for the store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ThemeActions { /** Set the current theme with DOM application and persistence */ setTheme: (theme: string) => Promise<void>; /** Update the list of available themes */ setAvailableThemes: (themes: ThemeInfo[]) => void; /** Set dark mode state */ setDarkMode: (isDark: boolean) => void; /** Set theme mode preference */ setThemeMode: (mode: ThemeMode) => void; /** Set loading state */ setLoading: (isLoading: boolean) => void; /** Set error state */ setError: (error: string | null) => void; /** Clear error */ clearError: () => void; /** Check if a theme is available */ isThemeAvailable: (themeName: string) => boolean; /** Reset theme settings to defaults */ resetTheme: () => void; /** Get theme info for the current theme */ getCurrentThemeInfo: () => ThemeInfo | null; /** Switch to the next available theme */ switchToNextTheme: () => void; /** Toggle between light and dark theme variants */ toggleDarkMode: () => void; /** * Initialize theme system with discovery data and user config * @param appConfig - Full AppConfig from AppConfigProvider (store extracts what it needs) */ initialize: (appConfig?: AppConfig) => Promise<boolean>; } /** * Modal state and actions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ModalState { /** Whether the modal is currently open */ isOpen: boolean; /** Modal content */ content: ReactNode | null; } /** * Modal actions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ModalActions { /** Open the modal with content */ openModal: (content: ReactNode) => void; /** Close the modal */ closeModal: () => void; } /** * Phase of the redirect overlay progression * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type RedirectOverlayPhase = 'connecting' | 'preparing' | 'redirecting' | 'timeout'; /** * Billing-specific redirect operations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BillingRedirectOperation = 'stripe-checkout' | 'stripe-portal'; /** * Auth partner redirect operations - DRY derived from AUTH_PARTNERS schema * Format: `oauth-${partnerId}` for OAuth partners, `auth-${partnerId}` for auth-only * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AuthRedirectOperation = `oauth-${AuthPartnerId}` | `auth-${AuthPartnerId}`; /** * OAuth partner redirect operations - DRY derived from OAUTH_PARTNERS schema * Format: `oauth-api-${partnerId}` for API-only OAuth partners * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OAuthRedirectOperation = `oauth-api-${OAuthPartnerId}`; /** * All redirect operations - Union of billing, auth, and OAuth operations * Extensible via string intersection for custom operations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type RedirectOperation = BillingRedirectOperation | AuthRedirectOperation | OAuthRedirectOperation | (string & {}); /** * Configuration for redirect overlay (optional overrides) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RedirectOverlayConfig { /** i18n namespace to use (default: inferred from operation) */ namespace?: string; /** Custom title (overrides i18n) */ title?: string; /** Custom message (overrides i18n) */ message?: string; /** Custom subtitle (overrides i18n) */ subtitle?: string; /** Icon type: 'lock' for payments, 'shield' for auth (default: inferred) */ icon?: 'lock' | 'shield' | 'none'; /** Timeout in ms before showing cancel button (default: 10000) */ cancelTimeout?: number; } /** * Redirect overlay state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RedirectOverlayState { /** Whether the redirect overlay is visible */ isRedirectOverlayOpen: boolean; /** Current operation being performed */ redirectOperation: RedirectOperation | null; /** Current phase of the redirect */ redirectPhase: RedirectOverlayPhase; /** Whether cancel button should be shown */ showCancelButton: boolean; /** Configuration overrides */ redirectConfig: RedirectOverlayConfig | null; /** Timestamp when overlay was shown (for phase progression) */ redirectStartTime: number | null; } /** * Redirect overlay actions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface RedirectOverlayActions { /** Show the redirect overlay */ showRedirectOverlay: (operation: RedirectOperation, config?: RedirectOverlayConfig) => void; /** Hide the redirect overlay */ hideRedirectOverlay: () => void; /** Update the current phase (internal use) */ setRedirectPhase: (phase: RedirectOverlayPhase) => void; /** Show/hide cancel button (internal use) */ setShowCancelButton: (show: boolean) => void; } /** * Loading state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LoadingState { /** Whether a data fetch operation is in progress */ isLoading: boolean; /** Whether a background fetch operation is in progress */ isFetching: boolean; } /** * Loading actions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LoadingActions { /** Set the loading state */ setLoading: (isLoading: boolean) => void; /** Set the fetching state */ setFetching: (isFetching: boolean) => void; } /** * Cookie options for setting cookies * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CookieOptions { /** Cookie expiration in days (default: 365) */ expires?: number; /** Cookie path (default: '/') */ path?: string; /** Cookie domain */ domain?: string; /** Secure flag (default: true) */ secure?: boolean; /** SameSite attribute (default: 'strict') */ sameSite?: 'strict' | 'lax' | 'none'; /** Cookie priority (Chrome 99+) */ priority?: 'low' | 'medium' | 'high'; /** Partitioned flag (Chrome 114+) */ partitioned?: boolean; } /** * Consent category constants - DRY single source of truth * Use these instead of hardcoded strings throughout the codebase * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CONSENT_CATEGORY: { readonly NECESSARY: "necessary"; readonly FUNCTIONAL: "functional"; readonly ANALYTICS: "analytics"; readonly MARKETING: "marketing"; }; /** * Consent category type - auto-derived from constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ConsentCategory = (typeof CONSENT_CATEGORY)[keyof typeof CONSENT_CATEGORY]; /** * Density constants - DRY single source of truth * Used for spacing and typography presets via data-density attribute * CSS uses these string values directly, but TypeScript code should use constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const DENSITY: { readonly COMPACT: "compact"; readonly STANDARD: "standard"; readonly EXPRESSIVE: "expressive"; }; /** * Density type - auto-derived from constants * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Density = (typeof DENSITY)[keyof typeof DENSITY]; /** * Cookie consent categories * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DoNotDevCookieCategories { /** Always granted, cannot be declined - core functionality */ necessary: boolean; /** Requires consent - Firebase Auth, user preferences */ functional: boolean; /** Requires consent - analytics, performance monitoring */ analytics: boolean; /** Requires consent - marketing, ads, remarketing */ marketing: boolean; } /** * App cookie categories type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type AppCookieCategories = Partial<DoNotDevCookieCategories> & { necessary: boolean; }; /** * Consent state interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ConsentState { /** Whether user has made a consent choice */ hasConsented: boolean; /** Individual category permissions - only includes categories that are actually required */ categories: AppCookieCategories; /** When consent was last updated */ timestamp: string | null; /** Consent version for future migrations */ version: string; } /** * Consent actions interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ConsentActions { /** Accept all optional categories */ acceptAll: () => void; /** Decline all optional categories */ declineAll: () => void; /** Update specific category */ updateCategory: (category: keyof DoNotDevCookieCategories, value: boolean) => void; /** Check if category is granted */ hasCategory: (category: keyof DoNotDevCookieCategories) => boolean; /** Reset consent (for testing) */ reset: () => void; /** Save consent to cookie */ saveConsent: () => void; /** Show cookie banner (for cookie settings link) */ showCookieBanner: () => void; } /** * Consent API - All available properties and methods from consent store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ConsentAPI extends ConsentState, ConsentActions { /** Whether banner should be shown */ showBanner: boolean; } /** * Feature/Consent Matrix * * Single source of truth for: * - Which features exist in the framework * - What consent each feature requires * - Type-safe feature names across codebase * * Uses CONSENT_CATEGORY constants for DRY compliance * * @example * ```typescript * // SaaS app (Auth + Billing) * features: ['auth', 'billing'] // No consent required (both necessary) * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const FEATURE_CONSENT_MATRIX: { /** Authentication - Firebase Auth, user sessions */ readonly auth: { readonly requiresConsent: null; }; /** OAuth - Third-party authentication (Google, GitHub, etc.) */ readonly oauth: { readonly requiresConsent: null; }; /** Billing - Stripe subscriptions, payments */ readonly billing: { readonly requiresConsent: null; }; /** Analytics - Usage tracking, performance monitoring */ readonly analytics: { readonly requiresConsent: "analytics"; }; /** Marketing - Advertising, retargeting */ readonly marketing: { readonly requiresConsent: "marketing"; }; }; /** * Feature name type - auto-derived from matrix * TypeScript ensures only valid features are used * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeatureName = keyof typeof FEATURE_CONSENT_MATRIX; /** * Get consent requirement for a specific feature * * @example * ```typescript * type AuthConsent = FeatureConsentRequirement<'auth'>; // 'functional' * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeatureConsentRequirement<F extends FeatureName> = (typeof FEATURE_CONSENT_MATRIX)[F]['requiresConsent']; /** * Get all features requiring a specific consent category * * @example * ```typescript * type FunctionalFeatures = FeaturesRequiringConsent<'functional'>; * // 'auth' | 'oauth' | 'billing' * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeaturesRequiringConsent<C extends keyof DoNotDevCookieCategories> = { [K in FeatureName]: FeatureConsentRequirement<K> extends C ? K : never; }[FeatureName]; /** * Features that require any consent (excludes null) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeaturesRequiringAnyConsent = { [K in FeatureName]: FeatureConsentRequirement<K> extends null ? never : K; }[FeatureName]; /** * Features that don't require consent * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeaturesWithoutConsent = { [K in FeatureName]: FeatureConsentRequirement<K> extends null ? K : never; }[FeatureName]; /** * @fileoverview Canvas catalog types * @description TypeScript-only types describing widget definitions and the * shape stored in the catalog registry. Runtime validation lives in * `@donotdev/schemas` (see `schemas/common/canvas.ts`). This file is * purely structural and isomorphic (no React imports). * * The React component side of the registered widget is a concern of * `@donotdev/canvas` (the UI package). Server-side consumers (validators, * brokers) only need the definition shape, not the rendered component. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** * Which surface a widget is allowed to render on. * * - `household` — any authenticated member. * - `private` — member-scoped (mail, 2nd-brain, homework). * - `meta` — framing widgets (TextBlock, Composite, ProgressCanvas, Confirmation). */ type CanvasSurface = 'household' | 'private' | 'meta'; /** * A valibot schema with an inferable output type. Accepts the generic base * schema shape used across the monorepo without locking to a specific issue type. */ type AnyValibotSchema = v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>; /** * Declarative widget definition — the static metadata a widget module * exports before it is paired with its React component for registration. * * Discriminator: `kind` (string literal, unique in the catalog). * * - `schema` validates the block `payload` for this kind. * - `actions` is a record of action-name -> schema validating that action's event payload. * - `surface` controls policy-layer gating. * - `defaultLifetime` is used by the agent-side emitter when the agent does not override it. */ interface WidgetDef<Kind extends string = string, PayloadSchema extends AnyValibotSchema = AnyValibotSchema, Actions extends Record<string, AnyValibotSchema> = Record<string, AnyValibotSchema>> { readonly kind: Kind; readonly schema: PayloadSchema; readonly actions: Actions; readonly surface: CanvasSurface; readonly defaultLifetime?: CanvasLifetime; } /** * Canvas block lifetime. Kept as a type alias here — the runtime schema * `CanvasLifetimeSchema` lives in `@donotdev/schemas`. * * - `ephemeral` — vanishes with the current turn (default). * - `session` — pinned to the current chat thread. * - `persistent` — lives on the PWA dashboard until manually removed. */ type CanvasLifetime = 'ephemeral' | 'session' | 'persistent'; /** * Optional display hints attached to a canvas block. */ interface CanvasWidgetMetadata { readonly title?: string; readonly pinnable?: boolean; readonly preferredHeight?: number; } /** * Envelope for a single canvas block emitted by the agent. * * `payload` is intentionally `unknown` at the envelope level — it is * validated against the registered widget's payload schema inside * `validateBlock`. Do not trust `payload` without that check. */ interface CanvasBlock { readonly id: string; readonly kind: string; readonly lifetime: CanvasLifetime; readonly metadata?: CanvasWidgetMetadata; readonly payload: unknown; } /** * Envelope for a user interaction event emitted back to the agent. * * `payload` is validated against the widget's per-action schema inside * `validateEvent`. */ interface CanvasEvent { readonly widgetId: string; readonly action: string; readonly payload: unknown; } /** * Caller access tier passed to `validateBlock` for surface gating. * * Mirrors the gontrand access model. `kid` and `null` fail closed for any * non-`meta` surface at the canvas boundary. */ type CanvasCallerAccess = 'admin' | 'member' | 'kid' | null; /** * Optional options for `validateBlock`. When `caller` is present, the * widget's `surface` is matched against the caller's access tier after * envelope / kind / payload checks pass. */ interface ValidateBlockOptions { readonly caller?: { readonly access: CanvasCallerAccess; }; } /** * Props every widget component receives from `CanvasHost`. The React * component shape itself lives in `@donotdev/canvas` (UI package). */ interface CanvasWidgetProps { readonly payload: unknown; readonly emit: (action: string, payload: unknown) => void; } /** * @fileoverview Types package exports * @description Centralized type definitions for DoNotDev framework * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map declare const index_d$5_AGGREGATE_FILTER_OPERATORS: typeof AGGREGATE_FILTER_OPERATORS; declare const index_d$5_AGGREGATE_OPERATIONS: typeof AGGREGATE_OPERATIONS; type index_d$5_AIAPI = AIAPI; type index_d$5_AIChatRequest = AIChatRequest; declare const index_d$5_AIChatRequestSchema: typeof AIChatRequestSchema; type index_d$5_AIChatResponse = AIChatResponse; declare const index_d$5_AIChatResponseSchema: typeof AIChatResponseSchema; type index_d$5_AIConfig = AIConfig; type index_d$5_AICostConfig = AICostConfig; type index_d$5_AICostEvent = AICostEvent; type index_d$5_AICostRecord = AICostRecord; type index_d$5_AICostResult = AICostResult; type index_d$5_AIErrorCode = AIErrorCode; type index_d$5_AIMessage = AIMessage; declare const index_d$5_AIMessageSchema: typeof AIMessageSchema; type index_d$5_AIModelPricing = AIModelPricing; type index_d$5_AIProvider = AIProvider; type index_d$5_AIProviderConfig = AIProviderConfig; declare const index_d$5_AIProviderConfigSchema: typeof AIProviderConfigSchema; type index_d$5_AIRateLimitConfig = AIRateLimitConfig; type index_d$5_AIRouteConfig = AIRouteConfig; type index_d$5_AITierId = AITierId; type index_d$5_AIToolCall = AIToolCall; declare const index_d$5_AIToolCallSchema: typeof AIToolCallSchema; type index_d$5_AIToolDefinition = AIToolDefinition; declare const index_d$5_AIToolDefinitionSchema: typeof AIToolDefinitionSchema; type index_d$5_AIToolParameter = AIToolParameter; type index_d$5_AIUsage = AIUsage; declare const index_d$5_AIUsageSchema: typeof AIUsageSchema; declare const index_d$5_AI_ERROR_CODES: typeof AI_ERROR_CODES; declare const index_d$5_AI_MODELS: typeof AI_MODELS; declare const index_d$5_AI_PROVIDERS: typeof AI_PROVIDERS; declare const index_d$5_AI_ROLES: typeof AI_ROLES; declare const index_d$5_AI_TIERS: typeof AI_TIERS; declare const index_d$5_AI_TOKEN_PRICING: typeof AI_TOKEN_PRICING; declare const index_d$5_AUTH_EVENTS: typeof AUTH_EVENTS; declare const index_d$5_AUTH_PARTNERS: typeof AUTH_PARTNERS; declare const index_d$5_AUTH_PARTNER_STATE: typeof AUTH_PARTNER_STATE; type index_d$5_AccountLinkResult = AccountLinkResult; type index_d$5_AccountLinkingInfo = AccountLinkingInfo; type index_d$5_AdminCheckHookResult = AdminCheckHookResult; type index_d$5_AdminClaims = AdminClaims; type index_d$5_AggregateConfig = AggregateConfig; type index_d$5_AggregateFilterOperator = AggregateFilterOperator; type index_d$5_AggregateOperation = AggregateOperation; type index_d$5_AggregateRequest = AggregateRequest; type index_d$5_AggregateResponse = AggregateResponse; type index_d$5_AnyEntity = AnyEntity; type index_d$5_AnyFieldValue = AnyFieldValue; type index_d$5_AnyValibotSchema = AnyValibotSchema; type index_d$5_ApiResponse<T> = ApiResponse<T>; type index_d$5_AppConfig = AppConfig; type index_d$5_AppCookieCategories = AppCookieCategories; type index_d$5_AppMetadata = AppMetadata; type index_d$5_AppProvidersProps = AppProvidersProps; type index_d$5_AssetsPluginConfig = AssetsPluginConfig; type index_d$5_AttemptRecord = AttemptRecord; type index_d$5_AuditEvent = AuditEvent; type index_d$5_AuditEventType = AuditEventType; type index_d$5_AuthAPI = AuthAPI; type index_d$5_AuthActions = AuthActions; type index_d$5_AuthConfig = AuthConfig; type index_d$5_AuthContextValue = AuthContextValue; type index_d$5_AuthCoreHookResult = AuthCoreHookResult; type index_d$5_AuthError = AuthError; type index_d$5_AuthEventData = AuthEventData; type index_d$5_AuthEventKey = AuthEventKey; type index_d$5_AuthEventName = AuthEventName; type index_d$5_AuthHardeningContext = AuthHardeningContext; type index_d$5_AuthMethod = AuthMethod; type index_d$5_AuthPartner = AuthPartner; type index_d$5_AuthPartnerHookResult = AuthPartnerHookResult; type index_d$5_AuthPartnerId = AuthPartnerId; type index_d$5_AuthPartnerResult = AuthPartnerResult; type index_d$5_AuthPartnerState = AuthPartnerState; type index_d$5_AuthProvider = AuthProvider; type index_d$5_AuthProviderProps = AuthProviderProps; type index_d$5_AuthRedirectHookResult = AuthRedirectHookResult; type index_d$5_AuthRedirectOperation = AuthRedirectOperation; type index_d$5_AuthRedirectOptions = AuthRedirectOptions; type index_d$5_AuthResult = AuthResult; type index_d$5_AuthState = AuthState; type index_d$5_AuthStateStore = AuthStateStore; type index_d$5_AuthStatus = AuthStatus; type index_d$5_AuthTokenHookResult = AuthTokenHookResult; type index_d$5_AuthUser = AuthUser; declare const index_d$5_AuthUserSchema: typeof AuthUserSchema; declare const index_d$5_BILLING_EVENTS: typeof BILLING_EVENTS; declare const index_d$5_BREAKPOINT_RANGES: typeof BREAKPOINT_RANGES; declare const index_d$5_BREAKPOINT_THRESHOLDS: typeof BREAKPOINT_THRESHOLDS; type index_d$5_BaseActions<T> = BaseActions<T>; type index_d$5_BaseCredentials = BaseCredentials; type index_d$5_BaseDocument = BaseDocument; type index_d$5_BaseEntityFields = BaseEntityFields; type index_d$5_BasePartnerState = BasePartnerState; type index_d$5_BaseState<T> = BaseState<T>; type index_d$5_BaseStoreActions = BaseStoreActions; type index_d$5_BaseStoreState = BaseStoreState; type index_d$5_BaseUserProfile = BaseUserProfile; type index_d$5_BasicUserInfo = BasicUserInfo; type index_d$5_BeforeCheckoutHook = BeforeCheckoutHook; type index_d$5_BeforeCheckoutResult = BeforeCheckoutResult; type index_d$5_BillingAPI = BillingAPI; type index_d$5_BillingAdapter = BillingAdapter; type index_d$5_BillingErrorCode = BillingErrorCode; type index_d$5_BillingEvent = BillingEvent; type index_d$5_BillingEventData = BillingEventData; type index_d$5_BillingEventKey = BillingEventKey; type index_d$5_BillingEventName = BillingEventName; type index_d$5_BillingProvider = BillingProvider; type index_d$5_BillingProviderConfig = BillingProviderConfig; type index_d$5_BillingRedirectOperation = BillingRedirectOperation; type index_d$5_Breakpoint = Breakpoint; type index_d$5_BreakpointUtils = BreakpointUtils; type index_d$5_BuiltInFieldType = BuiltInFieldType; type index_d$5_BulkAcrossBatch<T extends Record<string, unknown> = Record<string, unknown>> = BulkAcrossBatch<T>; type index_d$5_BulkAcrossCycleError = BulkAcrossCycleError; declare const index_d$5_BulkAcrossCycleError: typeof BulkAcrossCycleError; type index_d$5_BulkAcrossResult = BulkAcrossResult; type index_d$5_BulkCollisionError = BulkCollisionError; declare const index_d$5_BulkCollisionError: typeof BulkCollisionError; type index_d$5_BulkNotImplementedError = BulkNotImplementedError; declare const index_d$5_BulkNotImplementedError: typeof BulkNotImplementedError; type index_d$5_BulkOperations<T extends Record<string, unknown>> = BulkOperations<T>; type index_d$5_BulkResult = BulkResult; type index_d$5_BusinessEntity<out F extends Record<string, EntityField> = Record<string, EntityField>> = BusinessEntity<F>; declare const index_d$5_COMMON_TIER_CONFIGS: typeof COMMON_TIER_CONFIGS; declare const index_d$5_CONFIDENCE_LEVELS: typeof CONFIDENCE_LEVELS; declare const index_d$5_CONSENT_CATEGORY: typeof CONSENT_CATEGORY; declare const index_d$5_CONTEXTS: typeof CONTEXTS; declare const index_d$5_CRUD_OPERATORS: typeof CRUD_OPERATORS; type index_d$5_CachedError = CachedError; type index_d$5_CanAPI = CanAPI; type index_d$5_CanvasBlock = CanvasBlock; type index_d$5_CanvasCallerAccess = CanvasCallerAccess; type index_d$5_CanvasEvent = CanvasEvent; type index_d$5_CanvasLifetime = CanvasLifetime; type index_d$5_CanvasSurface = CanvasSurface; type index_d$5_CanvasWidgetMetadata = CanvasWidgetMetadata; type index_d$5_CanvasWidgetProps = CanvasWidgetProps; type index_d$5_CheckGitHubAccessRequest = CheckGitHubAccessRequest; type index_d$5_CheckoutMode = CheckoutMode; type index_d$5_CheckoutOptions = CheckoutOptions; type index_d$5_CheckoutSessionMetadata = CheckoutSessionMetadata; declare const index_d$5_CheckoutSessionMetadataSchema: typeof CheckoutSessionMetadataSchema; type index_d$5_CollectionSubscriptionCallback<T> = CollectionSubscriptionCallback<T>; type index_d$5_ColumnDef<T extends FieldValues> = ColumnDef<T>; type index_d$5_CommonSubscriptionFeatures = CommonSubscriptionFeatures; type index_d$5_CommonTranslations = CommonTranslations; type index_d$5_ConditionBuilderLike = ConditionBuilderLike; type index_d$5_ConditionExpression = ConditionExpression; type index_d$5_ConditionGroup = ConditionGroup; type index_d$5_ConditionInput = ConditionInput; type index_d$5_ConditionNode = ConditionNode; type index_d$5_ConditionOperator = ConditionOperator; type index_d$5_ConditionResult = ConditionResult; type index_d$5_ConditionalBehavior = ConditionalBehavior; type index_d$5_ConfidenceLevel = ConfidenceLevel; type index_d$5_ConnectOptions = ConnectOptions; type index_d$5_ConsentAPI = ConsentAPI; type index_d$5_ConsentActions = ConsentActions; type index_d$5_ConsentCategory = ConsentCategory; type index_d$5_ConsentState = ConsentState; type index_d$5_Context = Context; type index_d$5_CookieOptions = CookieOptions; type index_d$5_CreateCheckoutSessionRequest = CreateCheckoutSessionRequest; declare const index_d$5_CreateCheckoutSessionRequestSchema: typeof CreateCheckoutSessionRequestSchema; type index_d$5_CreateCheckoutSessionResponse = CreateCheckoutSessionResponse; declare const index_d$5_CreateCheckoutSessionResponseSchema: typeof CreateCheckoutSessionResponseSchema; type index_d$5_CreateEntityData<T extends Record<string, any>> = CreateEntityData<T>; type index_d$5_CreateEntityRequest = CreateEntityRequest; type index_d$5_CreateEntityResponse = CreateEntityResponse; type index_d$5_CrudAPI<T = unknown> = CrudAPI<T>; type index_d$5_CrudCardProps = CrudCardProps; type index_d$5_CrudConfig = CrudConfig; type index_d$5_CrudCreateInput<T> = CrudCreateInput<T>; type index_d$5_CrudDocQuery<T> = CrudDocQuery<T>; type index_d$5_CrudListQuery<T> = CrudListQuery<T>; type index_d$5_CrudOperationOptions = CrudOperationOptions; type index_d$5_CrudOperator = CrudOperator; type index_d$5_CustomClaims = CustomClaims; declare const index_d$5_CustomClaimsSchema: typeof CustomClaimsSchema; type index_d$5_CustomFieldOptionsMap = CustomFieldOptionsMap; type index_d$5_CustomStoreConfig = CustomStoreConfig; declare const index_d$5_DEFAULT_AI_CONFIG: typeof DEFAULT_AI_CONFIG; declare const index_d$5_DEFAULT_AI_MARKUP: typeof DEFAULT_AI_MARKUP; declare const index_d$5_DEFAULT_ENTITY_ACCESS: typeof DEFAULT_ENTITY_ACCESS; declare const index_d$5_DEFAULT_LAYOUT_PRESET: typeof DEFAULT_LAYOUT_PRESET; declare const index_d$5_DEFAULT_SUBSCRIPTION: typeof DEFAULT_SUBSCRIPTION; declare const index_d$5_DENSITY: typeof DENSITY; type index_d$5_DateValue = DateValue; type index_d$5_DeleteEntityRequest = DeleteEntityRequest; type index_d$5_DeleteEntityResponse = DeleteEntityResponse; type index_d$5_Density = Density; type index_d$5_DnDevOverride = DnDevOverride; type index_d$5_DnDevWrapper = DnDevWrapper; type index_d$5_DndevFrameworkConfig = DndevFrameworkConfig; type index_d$5_DndevProviders = DndevProviders; type index_d$5_DndevStoreApi<T> = DndevStoreApi<T>; type index_d$5_DoNotDevCookieCategories = DoNotDevCookieCategories; type index_d$5_DoNotDevError = DoNotDevError; declare const index_d$5_DoNotDevError: typeof DoNotDevError; type index_d$5_DocumentSubscriptionCallback<T> = DocumentSubscriptionCallback<T>; type index_d$5_DynamicFormRule = DynamicFormRule; declare const index_d$5_EDITABLE: typeof EDITABLE; declare const index_d$5_EMAIL_ERROR_CODES: typeof EMAIL_ERROR_CODES; declare const index_d$5_EMAIL_PROVIDERS: typeof EMAIL_PROVIDERS; declare const index_d$5_EMAIL_VERIFICATION_STATUS: typeof EMAIL_VERIFICATION_STATUS; declare const index_d$5_ENTITY_HOOK_ERRORS: typeof ENTITY_HOOK_ERRORS; declare const index_d$5_ENVIRONMENTS: typeof ENVIRONMENTS; declare const index_d$5_ERROR_CODES: typeof ERROR_CODES; declare const index_d$5_ERROR_SEVERITY: typeof ERROR_SEVERITY; declare const index_d$5_ERROR_SOURCE: typeof ERROR_SOURCE; type index_d$5_Editable = Editable; type index_d$5_EffectiveConnectionType = EffectiveConnectionType; type index_d$5_EmailConfig = EmailConfig; type index_d$5_EmailErrorCode = EmailErrorCode; type index_d$5_EmailProvider = EmailProvider; type index_d$5_EmailRouteConfig = EmailRouteConfig; type index_d$5_EmailTemplate<TData extends Record<string, unknown> = Record<string, unknown>> = EmailTemplate<TData>; type index_d$5_EmailTemplateRegistry = EmailTemplateRegistry; type index_d$5_EmailVerificationHookResult = EmailVerificationHookResult; type index_d$5_EmailVerificationStatus = EmailVerificationStatus; type index_d$5_Entity<out F extends Record<string, EntityField> = EntityFieldMapDefault> = Entity<F>; type index_d$5_EntityAccessConfig = EntityAccessConfig; type index_d$5_EntityAccessDefaults = EntityAccessDefaults; type index_d$5_EntityBrowseBaseProps = EntityBrowseBaseProps; type index_d$5_EntityCardListProps = EntityCardListProps; type index_d$5_EntityDisplayRendererProps<T extends EntityRecord = EntityRecord> = EntityDisplayRendererProps<T>; type index_d$5_EntityField<T extends string = FieldType> = EntityField<T>; type index_d$5_EntityFieldMapDefault = EntityFieldMapDefault; type index_d$5_EntityFormRendererProps<T extends EntityRecord = EntityRecord> = EntityFormRendererProps<T>; type index_d$5_EntityHookError = EntityHookError; declare const index_d$5_EntityHookError: typeof EntityHookError; type index_d$5_EntityHookErrors = EntityHookErrors; type index_d$5_EntityListProps = EntityListProps; type index_d$5_EntityMetadata = EntityMetadata; type index_d$5_EntityOwnershipConfig = EntityOwnershipConfig; type index_d$5_EntityOwnershipPublicCondition = EntityOwnershipPublicCondition; type index_d$5_EntityRecommendationsProps = EntityRecommendationsProps; type index_d$5_EntityRecord = EntityRecord; type index_d$5_EntityRowFromFields<F extends Record<string, EntityField>> = EntityRowFromFields<F>; type index_d$5_EntityTemplateProps<T extends FieldValues> = EntityTemplateProps<T>; type index_d$5_EntityTranslations = EntityTranslations; type index_d$5_EnvironmentMode = EnvironmentMode; type index_d$5_ErrorCode = ErrorCode; type index_d$5_ErrorSeverity = ErrorSeverity; type index_d$5_ErrorSource = ErrorSource; type index_d$5_ExchangeTokenParams = ExchangeTokenParams; type index_d$5_ExchangeTokenRequest = ExchangeTokenRequest; type index_d$5_ExchangeTokenResponse = ExchangeTokenResponse; declare const index_d$5_FEATURES: typeof FEATURES; declare const index_d$5_FEATURE_CONSENT_MATRIX: typeof FEATURE_CONSENT_MATRIX; declare const index_d$5_FEATURE_STATUS: typeof FEATURE_STATUS; declare const index_d$5_FIELD_TYPES: typeof FIELD_TYPES; declare const index_d$5_FIREBASE_ERROR_MAP: typeof FIREBASE_ERROR_MAP; declare const index_d$5_FOOTER_MODE: typeof FOOTER_MODE; type index_d$5_FaviconConfig = FaviconConfig; type index_d$5_Feature = Feature; type index_d$5_FeatureAccessHookResult = FeatureAccessHookResult; type index_d$5_FeatureConsentRequirement<F extends FeatureName> = FeatureConsentRequirement<F>; type index_d$5_FeatureHookResult = FeatureHookResult; type index_d$5_FeatureId = FeatureId; type index_d$5_FeatureName = FeatureName; type index_d$5_FeatureStatus = FeatureStatus; type index_d$5_FeaturesConfig = FeaturesConfig; type index_d$5_FeaturesPluginConfig = FeaturesPluginConfig; type index_d$5_FeaturesRequiringAnyConsent = FeaturesRequiringAnyConsent; type index_d$5_FeaturesRequiringConsent<C extends keyof DoNotDevCookieCategories> = FeaturesRequiringConsent<C>; type index_d$5_FeaturesWithoutConsent = FeaturesWithoutConsent; type index_d$5_FieldCondition = FieldCondition; type index_d$5_FieldType = FieldType; type index_d$5_FieldTypeToValue = FieldTypeToValue; type index_d$5_FileAsset = FileAsset; type index_d$5_FirebaseCallOptions = FirebaseCallOptions; type index_d$5_FirebaseConfig = FirebaseConfig; type index_d$5_FirestoreTimestamp = FirestoreTimestamp; type index_d$5_FirestoreUniqueConstraintValidator = FirestoreUniqueConstraintValidator; type index_d$5_FooterConfig = FooterConfig; type index_d$5_FooterMode = FooterMode; type index_d$5_FooterZoneConfig = FooterZoneConfig; type index_d$5_FormConfig = FormConfig; type index_d$5_FormStep = FormStep; type index_d$5_FunctionCallConfig = FunctionCallConfig; type index_d$5_FunctionCallContext = FunctionCallContext; type index_d$5_FunctionCallOptions = FunctionCallOptions; type index_d$5_FunctionCallResult<T> = FunctionCallResult<T>; type index_d$5_FunctionClient = FunctionClient; type index_d$5_FunctionClientFactoryOptions = FunctionClientFactoryOptions; type index_d$5_FunctionDefaults = FunctionDefaults; type index_d$5_FunctionEndpoint = FunctionEndpoint; type index_d$5_FunctionError = FunctionError; type index_d$5_FunctionLoader = FunctionLoader; type index_d$5_FunctionMemory = FunctionMemory; type index_d$5_FunctionMeta = FunctionMeta; type index_d$5_FunctionPlatform = FunctionPlatform; type index_d$5_FunctionResponse<T = any> = FunctionResponse<T>; type index_d$5_FunctionSchema<TInput = any, TOutput = any> = FunctionSchema<TInput, TOutput>; type index_d$5_FunctionSchemas = FunctionSchemas; type index_d$5_FunctionSystem = FunctionSystem; type index_d$5_FunctionTrigger = FunctionTrigger; type index_d$5_FunctionsConfig = FunctionsConfig; declare const index_d$5_GITHUB_PERMISSION_LEVELS: typeof GITHUB_PERMISSION_LEVELS; type index_d$5_GetCustomClaimsResponse = GetCustomClaimsResponse; type index_d$5_GetEntityData<T extends Record<string, any>> = GetEntityData<T>; type index_d$5_GetEntityRequest = GetEntityRequest; type index_d$5_GetEntityResponse = GetEntityResponse; type index_d$5_GetUserAuthStatusResponse = GetUserAuthStatusResponse; type index_d$5_GitHubPermission = GitHubPermission; type index_d$5_GitHubRepoConfig = GitHubRepoConfig; type index_d$5_GrantGitHubAccessRequest = GrantGitHubAccessRequest; type index_d$5_GroupByDefinition = GroupByDefinition; type index_d$5_HeaderZoneConfig = HeaderZoneConfig; type index_d$5_I18nConfig = I18nConfig; type index_d$5_I18nPluginConfig = I18nPluginConfig; type index_d$5_I18nProviderProps = I18nProviderProps; type index_d$5_ICallableProvider = ICallableProvider; type index_d$5_ICrudAdapter = ICrudAdapter; type index_d$5_ID = ID; type index_d$5_INetworkManager = INetworkManager; type index_d$5_IServerAuthAdapter = IServerAuthAdapter; type index_d$5_IStorageAdapter = IStorageAdapter; type index_d$5_IStorageManager = IStorageManager; type index_d$5_IStorageStrategy = IStorageStrategy; type index_d$5_InferEntityRow<E extends AnyEntity> = InferEntityRow<E>; type index_d$5_Invoice = Invoice; type index_d$5_InvoiceItem = InvoiceItem; declare const index_d$5_LAYOUT_PRESET: typeof LAYOUT_PRESET; declare const index_d$5_LIST_SCHEMA_TYPE: typeof LIST_SCHEMA_TYPE; type index_d$5_LanguageData = LanguageData; type index_d$5_LayoutConfig = LayoutConfig; type index_d$5_LayoutPreset = LayoutPreset; type index_d$5_LegalCompanyInfo = LegalCompanyInfo; type index_d$5_LegalConfig = LegalConfig; type index_d$5_LegalContactInfo = LegalContactInfo; type index_d$5_LegalDirectorInfo = LegalDirectorInfo; type index_d$5_LegalHostingInfo = LegalHostingInfo; type index_d$5_LegalJurisdictionInfo = LegalJurisdictionInfo; type index_d$5_LegalSectionsConfig = LegalSectionsConfig; type index_d$5_LegalWebsiteInfo = LegalWebsiteInfo; type index_d$5_ListCardLayout = ListCardLayout; type index_d$5_ListEntitiesRequest = ListEntitiesRequest; type index_d$5_ListEntitiesResponse = ListEntitiesResponse; type index_d$5_ListEntityData<T extends Record<string, any>> = ListEntityData<T>; type index_d$5_ListOptions = ListOptions; type index_d$5_ListResponse<T> = ListResponse<T>; type index_d$5_ListSchemaType = ListSchemaType; type index_d$5_LoadingActions = LoadingActions; type index_d$5_LoadingState = LoadingState; type index_d$5_MergedBarConfig = MergedBarConfig; type index_d$5_MergedEntityFieldMap<F extends Record<string, EntityField>> = MergedEntityFieldMap<F>; type index_d$5_MetricDefinition = MetricDefinition; type index_d$5_MobileBehaviorConfig = MobileBehaviorConfig; type index_d$5_ModalActions = ModalActions; type index_d$5_ModalState = ModalState; type index_d$5_MutableMergedEntityFieldMap<F extends Record<string, EntityField>> = MutableMergedEntityFieldMap<F>; type index_d$5_MutationResponse = MutationResponse; type index_d$5_NavigationRoute = NavigationRoute; type index_d$5_NetworkCheckConfig = NetworkCheckConfig; type index_d$5_NetworkConnectionType = NetworkConnectionType; type index_d$5_NetworkReconnectCallback = NetworkReconnectCallback; type index_d$5_NetworkStatus = NetworkStatus; type index_d$5_NetworkStatusHookResult = NetworkStatusHookResult; declare const index_d$5_OAUTH_EVENTS: typeof OAUTH_EVENTS; declare const index_d$5_OAUTH_PARTNERS: typeof OAUTH_PARTNERS; type index_d$5_OAuthAPI = OAuthAPI; type index_d$5_OAuthApiRequestOptions = OAuthApiRequestOptions; type index_d$5_OAuthCallbackHookResult = OAuthCallbackHookResult; type index_d$5_OAuthConnection = OAuthConnection; type index_d$5_OAuthConnectionInfo = OAuthConnectionInfo; type index_d$5_OAuthConnectionRequest = OAuthConnectionRequest; type index_d$5_OAuthConnectionStatus = OAuthConnectionStatus; type index_d$5_OAuthCredentials = OAuthCredentials; type index_d$5_OAuthEventData = OAuthEventData; type index_d$5_OAuthEventKey = OAuthEventKey; type index_d$5_OAuthEventName = OAuthEventName; type index_d$5_OAuthPartner = OAuthPartner; type index_d$5_OAuthPartnerHookResult = OAuthPartnerHookResult; type index_d$5_OAuthPartnerId = OAuthPartnerId; type index_d$5_OAuthPartnerResult = OAuthPartnerResult; type index_d$5_OAuthPartnerState = OAuthPartnerState; type index_d$5_OAuthPurpose = OAuthPurpose; type index_d$5_OAuthRedirectOperation = OAuthRedirectOperation; type index_d$5_OAuthRefreshRequest = OAuthRefreshRequest; type index_d$5_OAuthRefreshResponse = OAuthRefreshResponse; type index_d$5_OAuthResult = OAuthResult; type index_d$5_OAuthStoreActions = OAuthStoreActions; type index_d$5_OAuthStoreState = OAuthStoreState; declare const index_d$5_ORDER_DIRECTION: typeof ORDER_DIRECTION; type index_d$5_Observable<T> = Observable<T>; type index_d$5_OrderByClause = OrderByClause; type index_d$5_OrderDirection = OrderDirection; declare const index_d$5_PARTNER_ICONS: typeof PARTNER_ICONS; declare const index_d$5_PAYLOAD_EVENTS: typeof PAYLOAD_EVENTS; declare const index_d$5_PERMISSIONS: typeof PERMISSIONS; declare const index_d$5_PLATFORMS: typeof PLATFORMS; type index_d$5_PWAAssetType = PWAAssetType; type index_d$5_PWADisplayMode = PWADisplayMode; type index_d$5_PWAPluginConfig = PWAPluginConfig; declare const index_d$5_PWA_ASSET_TYPES: typeof PWA_ASSET_TYPES; declare const index_d$5_PWA_DISPLAY_MODES: typeof PWA_DISPLAY_MODES; type index_d$5_PageAuth = PageAuth; type index_d$5_PageMeta = PageMeta; type index_d$5_PaginatedQueryResult<T> = PaginatedQueryResult<T>; type index_d$5_PaginationOptions = PaginationOptions; type index_d$5_PartnerConnectionState = PartnerConnectionState; type index_d$5_PartnerIconId = PartnerIconId; type index_d$5_PartnerId = PartnerId; type index_d$5_PartnerResult = PartnerResult; type index_d$5_PartnerType = PartnerType; type index_d$5_PayloadCacheEventData = PayloadCacheEventData; type index_d$5_PayloadDocument = PayloadDocument; type index_d$5_PayloadDocumentEventData = PayloadDocumentEventData; type index_d$5_PayloadEventKey = PayloadEventKey; type index_d$5_PayloadEventName = PayloadEventName; type index_d$5_PayloadGlobalEventData = PayloadGlobalEventData; type index_d$5_PayloadMediaEventData = PayloadMediaEventData; type index_d$5_PayloadPageRegenerationEventData = PayloadPageRegenerationEventData; type index_d$5_PayloadRequest = PayloadRequest; type index_d$5_PayloadUserEventData = PayloadUserEventData; type index_d$5_PaymentEventData = PaymentEventData; type index_d$5_PaymentMethod = PaymentMethod; type index_d$5_PaymentMethodType = PaymentMethodType; type index_d$5_PaymentMode = PaymentMode; type index_d$5_Permission = Permission; type index_d$5_Picture = Picture; type index_d$5_Platform = Platform; type index_d$5_PresetConfig = PresetConfig; type index_d$5_PresetRegistry = PresetRegistry; type index_d$5_ProcessPaymentSuccessRequest = ProcessPaymentSuccessRequest; type index_d$5_ProcessPaymentSuccessResponse = ProcessPaymentSuccessResponse; type index_d$5_ProductDeclaration = ProductDeclaration; declare const index_d$5_ProductDeclarationSchema: typeof ProductDeclarationSchema; declare const index_d$5_ProductDeclarationsSchema: typeof ProductDeclarationsSchema; type index_d$5_ProviderInstances = ProviderInstances; type index_d$5_QueryConfig = QueryConfig; type index_d$5_QueryOptions = QueryOptions; type index_d$5_QueryOrderBy = QueryOrderBy; type index_d$5_QueryWhereClause = QueryWhereClause; declare const index_d$5_ROUTE_SOURCES: typeof ROUTE_SOURCES; type index_d$5_RateLimitBackend = RateLimitBackend; type index_d$5_RateLimitConfig = RateLimitConfig; type index_d$5_RateLimitManager = RateLimitManager; type index_d$5_RateLimitResult = RateLimitResult; type index_d$5_RateLimitState = RateLimitState; type index_d$5_RateLimiter = RateLimiter; type index_d$5_ReadCallback = ReadCallback; type index_d$5_RedirectOperation = RedirectOperation; type index_d$5_RedirectOverlayActions = RedirectOverlayActions; type index_d$5_RedirectOverlayConfig = RedirectOverlayConfig; type index_d$5_RedirectOverlayPhase = RedirectOverlayPhase; type index_d$5_RedirectOverlayState = RedirectOverlayState; type index_d$5_Reference = Reference; type index_d$5_RefreshSubscriptionRequest = RefreshSubscriptionRequest; type index_d$5_RefreshSubscriptionResponse = RefreshSubscriptionResponse; type index_d$5_RemoveCustomClaimsResponse = RemoveCustomClaimsResponse; type index_d$5_ResolvedLayoutConfig = ResolvedLayoutConfig; type index_d$5_RevokeGitHubAccessRequest = RevokeGitHubAccessRequest; type index_d$5_RouteMeta = RouteMeta; type index_d$5_RouteSource = RouteSource; type index_d$5_RoutesPluginConfig = RoutesPluginConfig; type index_d$5_SEOConfig = SEOConfig; declare const index_d$5_STORAGE_SCOPES: typeof STORAGE_SCOPES; declare const index_d$5_STORAGE_TYPES: typeof STORAGE_TYPES; declare const index_d$5_STRIPE_EVENTS: typeof STRIPE_EVENTS; declare const index_d$5_STRIPE_MODES: typeof STRIPE_MODES; declare const index_d$5_SUBSCRIPTION_DURATIONS: typeof SUBSCRIPTION_DURATIONS; declare const index_d$5_SUBSCRIPTION_STATUS: typeof SUBSCRIPTION_STATUS; declare const index_d$5_SUBSCRIPTION_TIERS: typeof SUBSCRIPTION_TIERS; type index_d$5_SchemaMetadata = SchemaMetadata; type index_d$5_ScopeConfig = ScopeConfig; type index_d$5_SecurityContext = SecurityContext; type index_d$5_SecurityEntityConfig = SecurityEntityConfig; type index_d$5_SendEmailRequest = SendEmailRequest; declare const index_d$5_SendEmailRequestSchema: typeof SendEmailRequestSchema; type index_d$5_SendEmailResponse = SendEmailResponse; declare const index_d$5_SendEmailResponseSchema: typeof SendEmailResponseSchema; type index_d$5_SeoMeta = SeoMeta; type index_d$5_ServerRateLimitConfig = ServerRateLimitConfig; type index_d$5_ServerRateLimitResult = ServerRateLimitResult; type index_d$5_ServerUserRecord = ServerUserRecord; type index_d$5_SetCustomClaimsResponse = SetCustomClaimsResponse; type index_d$5_SidebarZoneConfig = SidebarZoneConfig; type index_d$5_SignUpMetadata = SignUpMetadata; type index_d$5_SlotContent = SlotContent; type index_d$5_StorageOptions = StorageOptions; type index_d$5_StorageScope = StorageScope; type index_d$5_StorageType = StorageType; type index_d$5_Store<T> = Store<T>; type index_d$5_StripeBackConfig = StripeBackConfig; declare const index_d$5_StripeBackConfigSchema: typeof StripeBackConfigSchema; type index_d$5_StripeCheckoutRequest = StripeCheckoutRequest; type index_d$5_StripeCheckoutResponse = StripeCheckoutResponse; type index_d$5_StripeCheckoutSessionEventData = StripeCheckoutSessionEventData; type index_d$5_StripeConfig = StripeConfig; type index_d$5_StripeCustomer = StripeCustomer; type index_d$5_StripeCustomerEventData = StripeCustomerEventData; type index_d$5_StripeEventData = StripeEventData; type index_d$5_StripeEventKey = StripeEventKey; type index_d$5_StripeEventName = StripeEventName; type index_d$5_StripeFrontConfig = StripeFrontConfig; declare const index_d$5_StripeFrontConfigSchema: typeof StripeFrontConfigSchema; type index_d$5_StripeInvoice = StripeInvoice; type index_d$5_StripeInvoiceEventData = StripeInvoiceEventData; type index_d$5_StripePayment = StripePayment; type index_d$5_StripePaymentIntentEventData = StripePaymentIntentEventData; type index_d$5_StripePaymentMethod = StripePaymentMethod; declare const index_d$5_StripePaymentSchema: typeof StripePaymentSchema; type index_d$5_StripePrice = StripePrice; type index_d$5_StripeProduct = StripeProduct; type index_d$5_StripeProvider = StripeProvider; type index_d$5_StripeSubscription = StripeSubscription; type index_d$5_StripeSubscriptionData = StripeSubscriptionData; declare const index_d$5_StripeSubscriptionSchema: typeof StripeSubscriptionSchema; type index_d$5_StripeWebhookEvent = StripeWebhookEvent; type index_d$5_StripeWebhookEventData = StripeWebhookEventData; type index_d$5_Subscription = Subscription; type index_d$5_SubscriptionClaims = SubscriptionClaims; declare const index_d$5_SubscriptionClaimsSchema: typeof SubscriptionClaimsSchema; type index_d$5_SubscriptionConfig = SubscriptionConfig; type index_d$5_SubscriptionData = SubscriptionData; declare const index_d$5_SubscriptionDataSchema: typeof SubscriptionDataSchema; type index_d$5_SubscriptionDuration = SubscriptionDuration; type index_d$5_SubscriptionEventData = SubscriptionEventData; type index_d$5_SubscriptionHookResult = SubscriptionHookResult; type index_d$5_SubscriptionInfo = SubscriptionInfo; type index_d$5_SubscriptionStatus = SubscriptionStatus; type index_d$5_SubscriptionTier = SubscriptionTier; type index_d$5_SupportedLanguage = SupportedLanguage; type index_d$5_ThemeActions = ThemeActions; type index_d$5_ThemeInfo = ThemeInfo; type index_d$5_ThemeMode = ThemeMode; type index_d$5_ThemeState = ThemeState; type index_d$5_ThemesPluginConfig = ThemesPluginConfig; type index_d$5_TierAccessHookResult = TierAccessHookResult; type index_d$5_Timestamp = Timestamp; type index_d$5_TokenInfo = TokenInfo; type index_d$5_TokenResponse = TokenResponse; type index_d$5_TokenState = TokenState; type index_d$5_TokenStatus = TokenStatus; type index_d$5_TranslationOptions = TranslationOptions; type index_d$5_TranslationResource = TranslationResource; type index_d$5_UIFieldOptions<T extends string = FieldType> = UIFieldOptions<T>; declare const index_d$5_USER_ROLES: typeof USER_ROLES; type index_d$5_UniqueConstraintValidator = UniqueConstraintValidator; type index_d$5_UniqueKeyDefinition = UniqueKeyDefinition; type index_d$5_UnsubscribeFn = UnsubscribeFn; type index_d$5_UpdateEntityData<T extends Record<string, any>> = UpdateEntityData<T>; type index_d$5_UpdateEntityRequest = UpdateEntityRequest; type index_d$5_UpdateEntityResponse = UpdateEntityResponse; type index_d$5_UploadOptions = UploadOptions; type index_d$5_UploadProgressCallback = UploadProgressCallback; type index_d$5_UploadResult = UploadResult; type index_d$5_UseFunctionsCallResult<TData> = UseFunctionsCallResult<TData>; type index_d$5_UseFunctionsMutationOptions<TData, TVariables> = UseFunctionsMutationOptions<TData, TVariables>; type index_d$5_UseFunctionsMutationResult<TData, TVariables> = UseFunctionsMutationResult<TData, TVariables>; type index_d$5_UseFunctionsQueryOptions<TData> = UseFunctionsQueryOptions<TData>; type index_d$5_UseFunctionsQueryResult<TData> = UseFunctionsQueryResult<TData>; type index_d$5_UseTranslationOptionsEnhanced<KPrefix> = UseTranslationOptionsEnhanced<KPrefix>; type index_d$5_UserContext = UserContext; type index_d$5_UserProfile = UserProfile; type index_d$5_UserProviderData = UserProviderData; type index_d$5_UserRole = UserRole; type index_d$5_UserSubscription = UserSubscription; declare const index_d$5_UserSubscriptionSchema: typeof UserSubscriptionSchema; declare const index_d$5_VISIBILITY: typeof VISIBILITY; type index_d$5_ValidateBlockOptions = ValidateBlockOptions; type index_d$5_ValidationRules<T extends string = FieldType> = ValidationRules<T>; type index_d$5_ValueTypeForField<T extends string> = ValueTypeForField<T>; type index_d$5_VerifiedToken = VerifiedToken; type index_d$5_Visibility = Visibility; type index_d$5_WebhookEvent = WebhookEvent; type index_d$5_WebhookEventData = WebhookEventData; declare const index_d$5_WebhookEventSchema: typeof WebhookEventSchema; type index_d$5_WhereClause = WhereClause; type index_d$5_WhereOperator = WhereOperator; type index_d$5_WidgetDef<Kind extends string = string, PayloadSchema extends AnyValibotSchema = AnyValibotSchema, Actions extends Record<string, AnyValibotSchema> = Record<string, AnyValibotSchema>> = WidgetDef<Kind, PayloadSchema, Actions>; type index_d$5_WithMetadata<T> = WithMetadata<T>; declare const index_d$5_checkGitHubAccessSchema: typeof checkGitHubAccessSchema; declare const index_d$5_createDefaultSubscriptionClaims: typeof createDefaultSubscriptionClaims; declare const index_d$5_createDefaultUserProfile: typeof createDefaultUserProfile; declare const index_d$5_createEntitySchema: typeof createEntitySchema; declare const index_d$5_deleteEntitySchema: typeof deleteEntitySchema; declare const index_d$5_disconnectOAuthSchema: typeof disconnectOAuthSchema; type index_d$5_dndevSchema<T> = dndevSchema<T>; declare const index_d$5_exchangeTokenSchema: typeof exchangeTokenSchema; declare const index_d$5_getBreakpointFromWidth: typeof getBreakpointFromWidth; declare const index_d$5_getBreakpointUtils: typeof getBreakpointUtils; declare const index_d$5_getConnectionsSchema: typeof getConnectionsSchema; declare const index_d$5_getEntitySchema: typeof getEntitySchema; declare const index_d$5_githubPermissionSchema: typeof githubPermissionSchema; declare const index_d$5_githubRepoConfigSchema: typeof githubRepoConfigSchema; declare const index_d$5_grantGitHubAccessSchema: typeof grantGitHubAccessSchema; declare const index_d$5_isAuthPartnerId: typeof isAuthPartnerId; declare const index_d$5_isBreakpoint: typeof isBreakpoint; declare const index_d$5_isOAuthPartnerId: typeof isOAuthPartnerId; declare const index_d$5_listEntitiesSchema: typeof listEntitiesSchema; declare const index_d$5_overrideFeatures: typeof overrideFeatures; declare const index_d$5_overridePaymentModes: typeof overridePaymentModes; declare const index_d$5_overridePermissions: typeof overridePermissions; declare const index_d$5_overrideSubscriptionStatus: typeof overrideSubscriptionStatus; declare const index_d$5_overrideSubscriptionTiers: typeof overrideSubscriptionTiers; declare const index_d$5_overrideUserRoles: typeof overrideUserRoles; declare const index_d$5_refreshTokenSchema: typeof refreshTokenSchema; declare const index_d$5_revokeGitHubAccessSchema: typeof revokeGitHubAccessSchema; declare const index_d$5_updateEntitySchema: typeof updateEntitySchema; declare const index_d$5_validateAIChatRequest: typeof validateAIChatRequest; declare const index_d$5_validateAIChatResponse: typeof validateAIChatResponse; declare const index_d$5_validateAuthPartners: typeof validateAuthPartners; declare const index_d$5_validateAuthSchemas: typeof validateAuthSchemas; declare const index_d$5_validateAuthUser: typeof validateAuthUser; declare const index_d$5_validateBillingSchemas: typeof validateBillingSchemas; declare const index_d$5_validateCheckoutSessionMetadata: typeof validateCheckoutSessionMetadata; declare const index_d$5_validateCreateCheckoutSessionRequest: typeof validateCreateCheckoutSessionRequest; declare const index_d$5_validateCreateCheckoutSessionResponse: typeof validateCreateCheckoutSessionResponse; declare const index_d$5_validateCustomClaims: typeof validateCustomClaims; declare const index_d$5_validateOAuthPartners: typeof validateOAuthPartners; declare const index_d$5_validateSendEmailRequest: typeof validateSendEmailRequest; declare const index_d$5_validateSendEmailResponse: typeof validateSendEmailResponse; declare const index_d$5_validateStripeBackConfig: typeof validateStripeBackConfig; declare const index_d$5_validateStripeFrontConfig: typeof validateStripeFrontConfig; declare const index_d$5_validateSubscriptionClaims: typeof validateSubscriptionClaims; declare const index_d$5_validateSubscriptionData: typeof validateSubscriptionData; declare const index_d$5_validateUserSubscription: typeof validateUserSubscription; declare const index_d$5_validateWebhookEvent: typeof validateWebhookEvent; declare namespace index_d$5 { export { index_d$5_AGGREGATE_FILTER_OPERATORS as AGGREGATE_FILTER_OPERATORS, index_d$5_AGGREGATE_OPERATIONS as AGGREGATE_OPERATIONS, index_d$5_AIChatRequestSchema as AIChatRequestSchema, index_d$5_AIChatResponseSchema as AIChatResponseSchema, index_d$5_AIMessageSchema as AIMessageSchema, index_d$5_AIProviderConfigSchema as AIProviderConfigSchema, index_d$5_AIToolCallSchema as AIToolCallSchema, index_d$5_AIToolDefinitionSchema as AIToolDefinitionSchema, index_d$5_AIUsageSchema as AIUsageSchema, index_d$5_AI_ERROR_CODES as AI_ERROR_CODES, index_d$5_AI_MODELS as AI_MODELS, index_d$5_AI_PROVIDERS as AI_PROVIDERS, index_d$5_AI_ROLES as AI_ROLES, index_d$5_AI_TIERS as AI_TIERS, index_d$5_AI_TOKEN_PRICING as AI_TOKEN_PRICING, index_d$5_AUTH_EVENTS as AUTH_EVENTS, index_d$5_AUTH_PARTNERS as AUTH_PARTNERS, index_d$5_AUTH_PARTNER_STATE as AUTH_PARTNER_STATE, index_d$5_AuthUserSchema as AuthUserSchema, index_d$5_BILLING_EVENTS as BILLING_EVENTS, index_d$5_BREAKPOINT_RANGES as BREAKPOINT_RANGES, index_d$5_BREAKPOINT_THRESHOLDS as BREAKPOINT_THRESHOLDS, index_d$5_BulkAcrossCycleError as BulkAcrossCycleError, index_d$5_BulkCollisionError as BulkCollisionError, index_d$5_BulkNotImplementedError as BulkNotImplementedError, index_d$5_COMMON_TIER_CONFIGS as COMMON_TIER_CONFIGS, index_d$5_CONFIDENCE_LEVELS as CONFIDENCE_LEVELS, index_d$5_CONSENT_CATEGORY as CONSENT_CATEGORY, index_d$5_CONTEXTS as CONTEXTS, index_d$5_CRUD_OPERATORS as CRUD_OPERATORS, index_d$5_CheckoutSessionMetadataSchema as CheckoutSessionMetadataSchema, index_d$5_CreateCheckoutSessionRequestSchema as CreateCheckoutSessionRequestSchema, index_d$5_CreateCheckoutSessionResponseSchema as CreateCheckoutSessionResponseSchema, index_d$5_CustomClaimsSchema as CustomClaimsSchema, index_d$5_DEFAULT_AI_CONFIG as DEFAULT_AI_CONFIG, index_d$5_DEFAULT_AI_MARKUP as DEFAULT_AI_MARKUP, index_d$5_DEFAULT_ENTITY_ACCESS as DEFAULT_ENTITY_ACCESS, index_d$5_DEFAULT_LAYOUT_PRESET as DEFAULT_LAYOUT_PRESET, index_d$5_DEFAULT_SUBSCRIPTION as DEFAULT_SUBSCRIPTION, index_d$5_DENSITY as DENSITY, index_d$5_DoNotDevError as DoNotDevError, index_d$5_EDITABLE as EDITABLE, index_d$5_EMAIL_ERROR_CODES as EMAIL_ERROR_CODES, index_d$5_EMAIL_PROVIDERS as EMAIL_PROVIDERS, index_d$5_EMAIL_VERIFICATION_STATUS as EMAIL_VERIFICATION_STATUS, index_d$5_ENTITY_HOOK_ERRORS as ENTITY_HOOK_ERRORS, index_d$5_ENVIRONMENTS as ENVIRONMENTS, index_d$5_ERROR_CODES as ERROR_CODES, index_d$5_ERROR_SEVERITY as ERROR_SEVERITY, index_d$5_ERROR_SOURCE as ERROR_SOURCE, index_d$5_EntityHookError as EntityHookError, index_d$5_FEATURES as FEATURES, index_d$5_FEATURE_CONSENT_MATRIX as FEATURE_CONSENT_MATRIX, index_d$5_FEATURE_STATUS as FEATURE_STATUS, index_d$5_FIELD_TYPES as FIELD_TYPES, index_d$5_FIREBASE_ERROR_MAP as FIREBASE_ERROR_MAP, index_d$5_FOOTER_MODE as FOOTER_MODE, index_d$5_GITHUB_PERMISSION_LEVELS as GITHUB_PERMISSION_LEVELS, index_d$5_LAYOUT_PRESET as LAYOUT_PRESET, index_d$5_LIST_SCHEMA_TYPE as LIST_SCHEMA_TYPE, index_d$5_OAUTH_EVENTS as OAUTH_EVENTS, index_d$5_OAUTH_PARTNERS as OAUTH_PARTNERS, index_d$5_ORDER_DIRECTION as ORDER_DIRECTION, index_d$5_PARTNER_ICONS as PARTNER_ICONS, index_d$5_PAYLOAD_EVENTS as PAYLOAD_EVENTS, index_d$5_PERMISSIONS as PERMISSIONS, index_d$5_PLATFORMS as PLATFORMS, index_d$5_PWA_ASSET_TYPES as PWA_ASSET_TYPES, index_d$5_PWA_DISPLAY_MODES as PWA_DISPLAY_MODES, index_d$5_ProductDeclarationSchema as ProductDeclarationSchema, index_d$5_ProductDeclarationsSchema as ProductDeclarationsSchema, index_d$5_ROUTE_SOURCES as ROUTE_SOURCES, index_d$5_STORAGE_SCOPES as STORAGE_SCOPES, index_d$5_STORAGE_TYPES as STORAGE_TYPES, index_d$5_STRIPE_EVENTS as STRIPE_EVENTS, index_d$5_STRIPE_MODES as STRIPE_MODES, index_d$5_SUBSCRIPTION_DURATIONS as SUBSCRIPTION_DURATIONS, index_d$5_SUBSCRIPTION_STATUS as SUBSCRIPTION_STATUS, index_d$5_SUBSCRIPTION_TIERS as SUBSCRIPTION_TIERS, index_d$5_SendEmailRequestSchema as SendEmailRequestSchema, index_d$5_SendEmailResponseSchema as SendEmailResponseSchema, index_d$5_StripeBackConfigSchema as StripeBackConfigSchema, index_d$5_StripeFrontConfigSchema as StripeFrontConfigSchema, index_d$5_StripePaymentSchema as StripePaymentSchema, index_d$5_StripeSubscriptionSchema as StripeSubscriptionSchema, index_d$5_SubscriptionClaimsSchema as SubscriptionClaimsSchema, index_d$5_SubscriptionDataSchema as SubscriptionDataSchema, index_d$5_USER_ROLES as USER_ROLES, index_d$5_UserSubscriptionSchema as UserSubscriptionSchema, index_d$5_VISIBILITY as VISIBILITY, index_d$5_WebhookEventSchema as WebhookEventSchema, index_d$5_checkGitHubAccessSchema as checkGitHubAccessSchema, index_d$5_createDefaultSubscriptionClaims as createDefaultSubscriptionClaims, index_d$5_createDefaultUserProfile as createDefaultUserProfile, index_d$5_createEntitySchema as createEntitySchema, index_d$5_deleteEntitySchema as deleteEntitySchema, index_d$5_disconnectOAuthSchema as disconnectOAuthSchema, index_d$5_exchangeTokenSchema as exchangeTokenSchema, index_d$5_getBreakpointFromWidth as getBreakpointFromWidth, index_d$5_getBreakpointUtils as getBreakpointUtils, index_d$5_getConnectionsSchema as getConnectionsSchema, index_d$5_getEntitySchema as getEntitySchema, index_d$5_githubPermissionSchema as githubPermissionSchema, index_d$5_githubRepoConfigSchema as githubRepoConfigSchema, index_d$5_grantGitHubAccessSchema as grantGitHubAccessSchema, index_d$5_isAuthPartnerId as isAuthPartnerId, index_d$5_isBreakpoint as isBreakpoint, index_d$5_isOAuthPartnerId as isOAuthPartnerId, index_d$5_listEntitiesSchema as listEntitiesSchema, index_d$5_overrideFeatures as overrideFeatures, index_d$5_overridePaymentModes as overridePaymentModes, index_d$5_overridePermissions as overridePermissions, index_d$5_overrideSubscriptionStatus as overrideSubscriptionStatus, index_d$5_overrideSubscriptionTiers as overrideSubscriptionTiers, index_d$5_overrideUserRoles as overrideUserRoles, index_d$5_refreshTokenSchema as refreshTokenSchema, index_d$5_revokeGitHubAccessSchema as revokeGitHubAccessSchema, index_d$5_updateEntitySchema as updateEntitySchema, index_d$5_validateAIChatRequest as validateAIChatRequest, index_d$5_validateAIChatResponse as validateAIChatResponse, index_d$5_validateAuthPartners as validateAuthPartners, index_d$5_validateAuthSchemas as validateAuthSchemas, index_d$5_validateAuthUser as validateAuthUser, index_d$5_validateBillingSchemas as validateBillingSchemas, index_d$5_validateCheckoutSessionMetadata as validateCheckoutSessionMetadata, index_d$5_validateCreateCheckoutSessionRequest as validateCreateCheckoutSessionRequest, index_d$5_validateCreateCheckoutSessionResponse as validateCreateCheckoutSessionResponse, index_d$5_validateCustomClaims as validateCustomClaims, index_d$5_validateOAuthPartners as validateOAuthPartners, index_d$5_validateSendEmailRequest as validateSendEmailRequest, index_d$5_validateSendEmailResponse as validateSendEmailResponse, index_d$5_validateStripeBackConfig as validateStripeBackConfig, index_d$5_validateStripeFrontConfig as validateStripeFrontConfig, index_d$5_validateSubscriptionClaims as validateSubscriptionClaims, index_d$5_validateSubscriptionData as validateSubscriptionData, index_d$5_validateUserSubscription as validateUserSubscription, index_d$5_validateWebhookEvent as validateWebhookEvent }; export type { index_d$5_AIAPI as AIAPI, index_d$5_AIChatRequest as AIChatRequest, index_d$5_AIChatResponse as AIChatResponse, index_d$5_AIConfig as AIConfig, index_d$5_AICostConfig as AICostConfig, index_d$5_AICostEvent as AICostEvent, index_d$5_AICostRecord as AICostRecord, index_d$5_AICostResult as AICostResult, index_d$5_AIErrorCode as AIErrorCode, index_d$5_AIMessage as AIMessage, index_d$5_AIModelPricing as AIModelPricing, index_d$5_AIProvider as AIProvider, index_d$5_AIProviderConfig as AIProviderConfig, index_d$5_AIRateLimitConfig as AIRateLimitConfig, index_d$5_AIRouteConfig as AIRouteConfig, index_d$5_AITierId as AITierId, index_d$5_AIToolCall as AIToolCall, index_d$5_AIToolDefinition as AIToolDefinition, index_d$5_AIToolParameter as AIToolParameter, index_d$5_AIUsage as AIUsage, index_d$5_AccountLinkResult as AccountLinkResult, index_d$5_AccountLinkingInfo as AccountLinkingInfo, index_d$5_AdminCheckHookResult as AdminCheckHookResult, index_d$5_AdminClaims as AdminClaims, index_d$5_AggregateConfig as AggregateConfig, index_d$5_AggregateFilterOperator as AggregateFilterOperator, index_d$5_AggregateOperation as AggregateOperation, index_d$5_AggregateRequest as AggregateRequest, index_d$5_AggregateResponse as AggregateResponse, index_d$5_AnyEntity as AnyEntity, index_d$5_AnyFieldValue as AnyFieldValue, index_d$5_AnyValibotSchema as AnyValibotSchema, index_d$5_ApiResponse as ApiResponse, index_d$5_AppConfig as AppConfig, index_d$5_AppCookieCategories as AppCookieCategories, index_d$5_AppMetadata as AppMetadata, index_d$5_AppProvidersProps as AppProvidersProps, index_d$5_AssetsPluginConfig as AssetsPluginConfig, index_d$5_AttemptRecord as AttemptRecord, index_d$5_AuditEvent as AuditEvent, index_d$5_AuditEventType as AuditEventType, index_d$5_AuthAPI as AuthAPI, index_d$5_AuthActions as AuthActions, index_d$5_AuthConfig as AuthConfig, index_d$5_AuthContextValue as AuthContextValue, index_d$5_AuthCoreHookResult as AuthCoreHookResult, index_d$5_AuthError as AuthError, index_d$5_AuthEventData as AuthEventData, index_d$5_AuthEventKey as AuthEventKey, index_d$5_AuthEventName as AuthEventName, index_d$5_AuthHardeningContext as AuthHardeningContext, index_d$5_AuthMethod as AuthMethod, index_d$5_AuthPartner as AuthPartner, index_d$5_AuthPartnerHookResult as AuthPartnerHookResult, index_d$5_AuthPartnerId as AuthPartnerId, index_d$5_AuthPartnerResult as AuthPartnerResult, index_d$5_AuthPartnerState as AuthPartnerState, index_d$5_AuthProvider as AuthProvider, index_d$5_AuthProviderProps as AuthProviderProps, index_d$5_AuthRedirectHookResult as AuthRedirectHookResult, index_d$5_AuthRedirectOperation as AuthRedirectOperation, index_d$5_AuthRedirectOptions as AuthRedirectOptions, index_d$5_AuthResult as AuthResult, index_d$5_AuthState as AuthState, index_d$5_AuthStateStore as AuthStateStore, index_d$5_AuthStatus as AuthStatus, index_d$5_AuthTokenHookResult as AuthTokenHookResult, index_d$5_AuthUser as AuthUser, index_d$5_BaseActions as BaseActions, index_d$5_BaseCredentials as BaseCredentials, index_d$5_BaseDocument as BaseDocument, index_d$5_BaseEntityFields as BaseEntityFields, index_d$5_BasePartnerState as BasePartnerState, index_d$5_BaseState as BaseState, index_d$5_BaseStoreActions as BaseStoreActions, index_d$5_BaseStoreState as BaseStoreState, index_d$5_BaseUserProfile as BaseUserProfile, index_d$5_BasicUserInfo as BasicUserInfo, index_d$5_BeforeCheckoutHook as BeforeCheckoutHook, index_d$5_BeforeCheckoutResult as BeforeCheckoutResult, index_d$5_BillingAPI as BillingAPI, index_d$5_BillingAdapter as BillingAdapter, index_d$5_BillingErrorCode as BillingErrorCode, index_d$5_BillingEvent as BillingEvent, index_d$5_BillingEventData as BillingEventData, index_d$5_BillingEventKey as BillingEventKey, index_d$5_BillingEventName as BillingEventName, index_d$5_BillingProvider as BillingProvider, index_d$5_BillingProviderConfig as BillingProviderConfig, index_d$5_BillingRedirectOperation as BillingRedirectOperation, index_d$5_Breakpoint as Breakpoint, index_d$5_BreakpointUtils as BreakpointUtils, index_d$5_BuiltInFieldType as BuiltInFieldType, index_d$5_BulkAcrossBatch as BulkAcrossBatch, index_d$5_BulkAcrossResult as BulkAcrossResult, index_d$5_BulkOperations as BulkOperations, index_d$5_BulkResult as BulkResult, index_d$5_BusinessEntity as BusinessEntity, index_d$5_CachedError as CachedError, index_d$5_CanAPI as CanAPI, index_d$5_CanvasBlock as CanvasBlock, index_d$5_CanvasCallerAccess as CanvasCallerAccess, index_d$5_CanvasEvent as CanvasEvent, index_d$5_CanvasLifetime as CanvasLifetime, index_d$5_CanvasSurface as CanvasSurface, index_d$5_CanvasWidgetMetadata as CanvasWidgetMetadata, index_d$5_CanvasWidgetProps as CanvasWidgetProps, index_d$5_CheckGitHubAccessRequest as CheckGitHubAccessRequest, index_d$5_CheckoutMode as CheckoutMode, index_d$5_CheckoutOptions as CheckoutOptions, index_d$5_CheckoutSessionMetadata as CheckoutSessionMetadata, index_d$5_CollectionSubscriptionCallback as CollectionSubscriptionCallback, index_d$5_ColumnDef as ColumnDef, index_d$5_CommonSubscriptionFeatures as CommonSubscriptionFeatures, index_d$5_CommonTranslations as CommonTranslations, index_d$5_ConditionBuilderLike as ConditionBuilderLike, index_d$5_ConditionExpression as ConditionExpression, index_d$5_ConditionGroup as ConditionGroup, index_d$5_ConditionInput as ConditionInput, index_d$5_ConditionNode as ConditionNode, index_d$5_ConditionOperator as ConditionOperator, index_d$5_ConditionResult as ConditionResult, index_d$5_ConditionalBehavior as ConditionalBehavior, index_d$5_ConfidenceLevel as ConfidenceLevel, index_d$5_ConnectOptions as ConnectOptions, index_d$5_ConsentAPI as ConsentAPI, index_d$5_ConsentActions as ConsentActions, index_d$5_ConsentCategory as ConsentCategory, index_d$5_ConsentState as ConsentState, index_d$5_Context as Context, index_d$5_CookieOptions as CookieOptions, index_d$5_CreateCheckoutSessionRequest as CreateCheckoutSessionRequest, index_d$5_CreateCheckoutSessionResponse as CreateCheckoutSessionResponse, index_d$5_CreateEntityData as CreateEntityData, index_d$5_CreateEntityRequest as CreateEntityRequest, index_d$5_CreateEntityResponse as CreateEntityResponse, index_d$5_CrudAPI as CrudAPI, index_d$5_CrudCardProps as CrudCardProps, index_d$5_CrudConfig as CrudConfig, index_d$5_CrudCreateInput as CrudCreateInput, index_d$5_CrudDocQuery as CrudDocQuery, index_d$5_CrudListQuery as CrudListQuery, index_d$5_CrudOperationOptions as CrudOperationOptions, index_d$5_CrudOperator as CrudOperator, index_d$5_CustomClaims as CustomClaims, index_d$5_CustomFieldOptionsMap as CustomFieldOptionsMap, index_d$5_CustomStoreConfig as CustomStoreConfig, index_d$5_DateValue as DateValue, index_d$5_DeleteEntityRequest as DeleteEntityRequest, index_d$5_DeleteEntityResponse as DeleteEntityResponse, index_d$5_Density as Density, index_d$5_DnDevOverride as DnDevOverride, index_d$5_DnDevWrapper as DnDevWrapper, index_d$5_DndevFrameworkConfig as DndevFrameworkConfig, index_d$5_DndevProviders as DndevProviders, index_d$5_DndevStoreApi as DndevStoreApi, index_d$5_DoNotDevCookieCategories as DoNotDevCookieCategories, index_d$5_DocumentSubscriptionCallback as DocumentSubscriptionCallback, index_d$5_DynamicFormRule as DynamicFormRule, index_d$5_Editable as Editable, index_d$5_EffectiveConnectionType as EffectiveConnectionType, index_d$5_EmailConfig as EmailConfig, index_d$5_EmailErrorCode as EmailErrorCode, index_d$5_EmailProvider as EmailProvider, index_d$5_EmailRouteConfig as EmailRouteConfig, index_d$5_EmailTemplate as EmailTemplate, index_d$5_EmailTemplateRegistry as EmailTemplateRegistry, index_d$5_EmailVerificationHookResult as EmailVerificationHookResult, index_d$5_EmailVerificationStatus as EmailVerificationStatus, index_d$5_Entity as Entity, index_d$5_EntityAccessConfig as EntityAccessConfig, index_d$5_EntityAccessDefaults as EntityAccessDefaults, index_d$5_EntityBrowseBaseProps as EntityBrowseBaseProps, index_d$5_EntityCardListProps as EntityCardListProps, index_d$5_EntityDisplayRendererProps as EntityDisplayRendererProps, index_d$5_EntityField as EntityField, index_d$5_EntityFieldMapDefault as EntityFieldMapDefault, index_d$5_EntityFormRendererProps as EntityFormRendererProps, index_d$5_EntityHookErrors as EntityHookErrors, index_d$5_EntityListProps as EntityListProps, index_d$5_EntityMetadata as EntityMetadata, index_d$5_EntityOwnershipConfig as EntityOwnershipConfig, index_d$5_EntityOwnershipPublicCondition as EntityOwnershipPublicCondition, index_d$5_EntityRecommendationsProps as EntityRecommendationsProps, index_d$5_EntityRecord as EntityRecord, index_d$5_EntityRowFromFields as EntityRowFromFields, index_d$5_EntityTemplateProps as EntityTemplateProps, index_d$5_EntityTranslations as EntityTranslations, index_d$5_EnvironmentMode as EnvironmentMode, index_d$5_ErrorCode as ErrorCode, index_d$5_ErrorSeverity as ErrorSeverity, index_d$5_ErrorSource as ErrorSource, index_d$5_ExchangeTokenParams as ExchangeTokenParams, index_d$5_ExchangeTokenRequest as ExchangeTokenRequest, index_d$5_ExchangeTokenResponse as ExchangeTokenResponse, index_d$5_FaviconConfig as FaviconConfig, index_d$5_Feature as Feature, index_d$5_FeatureAccessHookResult as FeatureAccessHookResult, index_d$5_FeatureConsentRequirement as FeatureConsentRequirement, index_d$5_FeatureHookResult as FeatureHookResult, index_d$5_FeatureId as FeatureId, index_d$5_FeatureName as FeatureName, index_d$5_FeatureStatus as FeatureStatus, index_d$5_FeaturesConfig as FeaturesConfig, index_d$5_FeaturesPluginConfig as FeaturesPluginConfig, index_d$5_FeaturesRequiringAnyConsent as FeaturesRequiringAnyConsent, index_d$5_FeaturesRequiringConsent as FeaturesRequiringConsent, index_d$5_FeaturesWithoutConsent as FeaturesWithoutConsent, index_d$5_FieldCondition as FieldCondition, index_d$5_FieldType as FieldType, index_d$5_FieldTypeToValue as FieldTypeToValue, index_d$5_FileAsset as FileAsset, index_d$5_FirebaseCallOptions as FirebaseCallOptions, index_d$5_FirebaseConfig as FirebaseConfig, index_d$5_FirestoreTimestamp as FirestoreTimestamp, index_d$5_FirestoreUniqueConstraintValidator as FirestoreUniqueConstraintValidator, index_d$5_FooterConfig as FooterConfig, index_d$5_FooterMode as FooterMode, index_d$5_FooterZoneConfig as FooterZoneConfig, index_d$5_FormConfig as FormConfig, index_d$5_FormStep as FormStep, index_d$5_FunctionCallConfig as FunctionCallConfig, index_d$5_FunctionCallContext as FunctionCallContext, index_d$5_FunctionCallOptions as FunctionCallOptions, index_d$5_FunctionCallResult as FunctionCallResult, index_d$5_FunctionClient as FunctionClient, index_d$5_FunctionClientFactoryOptions as FunctionClientFactoryOptions, index_d$5_FunctionDefaults as FunctionDefaults, index_d$5_FunctionEndpoint as FunctionEndpoint, index_d$5_FunctionError as FunctionError, index_d$5_FunctionLoader as FunctionLoader, index_d$5_FunctionMemory as FunctionMemory, index_d$5_FunctionMeta as FunctionMeta, index_d$5_FunctionPlatform as FunctionPlatform, index_d$5_FunctionResponse as FunctionResponse, index_d$5_FunctionSchema as FunctionSchema, index_d$5_FunctionSchemas as FunctionSchemas, index_d$5_FunctionSystem as FunctionSystem, index_d$5_FunctionTrigger as FunctionTrigger, index_d$5_FunctionsConfig as FunctionsConfig, index_d$5_GetCustomClaimsResponse as GetCustomClaimsResponse, index_d$5_GetEntityData as GetEntityData, index_d$5_GetEntityRequest as GetEntityRequest, index_d$5_GetEntityResponse as GetEntityResponse, index_d$5_GetUserAuthStatusResponse as GetUserAuthStatusResponse, index_d$5_GitHubPermission as GitHubPermission, index_d$5_GitHubRepoConfig as GitHubRepoConfig, index_d$5_GrantGitHubAccessRequest as GrantGitHubAccessRequest, index_d$5_GroupByDefinition as GroupByDefinition, index_d$5_HeaderZoneConfig as HeaderZoneConfig, index_d$5_I18nConfig as I18nConfig, index_d$5_I18nPluginConfig as I18nPluginConfig, index_d$5_I18nProviderProps as I18nProviderProps, index_d$5_ICallableProvider as ICallableProvider, index_d$5_ICrudAdapter as ICrudAdapter, index_d$5_ID as ID, index_d$5_INetworkManager as INetworkManager, index_d$5_IServerAuthAdapter as IServerAuthAdapter, index_d$5_IStorageAdapter as IStorageAdapter, index_d$5_IStorageManager as IStorageManager, index_d$5_IStorageStrategy as IStorageStrategy, index_d$5_InferEntityRow as InferEntityRow, index_d$5_Invoice as Invoice, index_d$5_InvoiceItem as InvoiceItem, index_d$5_LanguageData as LanguageData, LanguageInfo$1 as LanguageInfo, index_d$5_LayoutConfig as LayoutConfig, index_d$5_LayoutPreset as LayoutPreset, index_d$5_LegalCompanyInfo as LegalCompanyInfo, index_d$5_LegalConfig as LegalConfig, index_d$5_LegalContactInfo as LegalContactInfo, index_d$5_LegalDirectorInfo as LegalDirectorInfo, index_d$5_LegalHostingInfo as LegalHostingInfo, index_d$5_LegalJurisdictionInfo as LegalJurisdictionInfo, index_d$5_LegalSectionsConfig as LegalSectionsConfig, index_d$5_LegalWebsiteInfo as LegalWebsiteInfo, index_d$5_ListCardLayout as ListCardLayout, index_d$5_ListEntitiesRequest as ListEntitiesRequest, index_d$5_ListEntitiesResponse as ListEntitiesResponse, index_d$5_ListEntityData as ListEntityData, index_d$5_ListOptions as ListOptions, index_d$5_ListResponse as ListResponse, index_d$5_ListSchemaType as ListSchemaType, index_d$5_LoadingActions as LoadingActions, index_d$5_LoadingState as LoadingState, index_d$5_MergedBarConfig as MergedBarConfig, index_d$5_MergedEntityFieldMap as MergedEntityFieldMap, index_d$5_MetricDefinition as MetricDefinition, index_d$5_MobileBehaviorConfig as MobileBehaviorConfig, index_d$5_ModalActions as ModalActions, index_d$5_ModalState as ModalState, index_d$5_MutableMergedEntityFieldMap as MutableMergedEntityFieldMap, index_d$5_MutationResponse as MutationResponse, index_d$5_NavigationRoute as NavigationRoute, index_d$5_NetworkCheckConfig as NetworkCheckConfig, index_d$5_NetworkConnectionType as NetworkConnectionType, index_d$5_NetworkReconnectCallback as NetworkReconnectCallback, NetworkState$1 as NetworkState, index_d$5_NetworkStatus as NetworkStatus, index_d$5_NetworkStatusHookResult as NetworkStatusHookResult, index_d$5_OAuthAPI as OAuthAPI, index_d$5_OAuthApiRequestOptions as OAuthApiRequestOptions, index_d$5_OAuthCallbackHookResult as OAuthCallbackHookResult, index_d$5_OAuthConnection as OAuthConnection, index_d$5_OAuthConnectionInfo as OAuthConnectionInfo, index_d$5_OAuthConnectionRequest as OAuthConnectionRequest, index_d$5_OAuthConnectionStatus as OAuthConnectionStatus, index_d$5_OAuthCredentials as OAuthCredentials, index_d$5_OAuthEventData as OAuthEventData, index_d$5_OAuthEventKey as OAuthEventKey, index_d$5_OAuthEventName as OAuthEventName, index_d$5_OAuthPartner as OAuthPartner, index_d$5_OAuthPartnerHookResult as OAuthPartnerHookResult, index_d$5_OAuthPartnerId as OAuthPartnerId, index_d$5_OAuthPartnerResult as OAuthPartnerResult, index_d$5_OAuthPartnerState as OAuthPartnerState, index_d$5_OAuthPurpose as OAuthPurpose, index_d$5_OAuthRedirectOperation as OAuthRedirectOperation, index_d$5_OAuthRefreshRequest as OAuthRefreshRequest, index_d$5_OAuthRefreshResponse as OAuthRefreshResponse, index_d$5_OAuthResult as OAuthResult, index_d$5_OAuthStoreActions as OAuthStoreActions, index_d$5_OAuthStoreState as OAuthStoreState, index_d$5_Observable as Observable, index_d$5_OrderByClause as OrderByClause, index_d$5_OrderDirection as OrderDirection, index_d$5_PWAAssetType as PWAAssetType, index_d$5_PWADisplayMode as PWADisplayMode, index_d$5_PWAPluginConfig as PWAPluginConfig, index_d$5_PageAuth as PageAuth, index_d$5_PageMeta as PageMeta, index_d$5_PaginatedQueryResult as PaginatedQueryResult, index_d$5_PaginationOptions as PaginationOptions, index_d$5_PartnerConnectionState as PartnerConnectionState, index_d$5_PartnerIconId as PartnerIconId, index_d$5_PartnerId as PartnerId, index_d$5_PartnerResult as PartnerResult, index_d$5_PartnerType as PartnerType, index_d$5_PayloadCacheEventData as PayloadCacheEventData, index_d$5_PayloadDocument as PayloadDocument, index_d$5_PayloadDocumentEventData as PayloadDocumentEventData, index_d$5_PayloadEventKey as PayloadEventKey, index_d$5_PayloadEventName as PayloadEventName, index_d$5_PayloadGlobalEventData as PayloadGlobalEventData, index_d$5_PayloadMediaEventData as PayloadMediaEventData, index_d$5_PayloadPageRegenerationEventData as PayloadPageRegenerationEventData, index_d$5_PayloadRequest as PayloadRequest, index_d$5_PayloadUserEventData as PayloadUserEventData, index_d$5_PaymentEventData as PaymentEventData, index_d$5_PaymentMethod as PaymentMethod, index_d$5_PaymentMethodType as PaymentMethodType, index_d$5_PaymentMode as PaymentMode, index_d$5_Permission as Permission, index_d$5_Picture as Picture, index_d$5_Platform as Platform, index_d$5_PresetConfig as PresetConfig, index_d$5_PresetRegistry as PresetRegistry, index_d$5_ProcessPaymentSuccessRequest as ProcessPaymentSuccessRequest, index_d$5_ProcessPaymentSuccessResponse as ProcessPaymentSuccessResponse, index_d$5_ProductDeclaration as ProductDeclaration, index_d$5_ProviderInstances as ProviderInstances, index_d$5_QueryConfig as QueryConfig, index_d$5_QueryOptions as QueryOptions, index_d$5_QueryOrderBy as QueryOrderBy, index_d$5_QueryWhereClause as QueryWhereClause, index_d$5_RateLimitBackend as RateLimitBackend, index_d$5_RateLimitConfig as RateLimitConfig, index_d$5_RateLimitManager as RateLimitManager, index_d$5_RateLimitResult as RateLimitResult, index_d$5_RateLimitState as RateLimitState, index_d$5_RateLimiter as RateLimiter, index_d$5_ReadCallback as ReadCallback, index_d$5_RedirectOperation as RedirectOperation, index_d$5_RedirectOverlayActions as RedirectOverlayActions, index_d$5_RedirectOverlayConfig as RedirectOverlayConfig, index_d$5_RedirectOverlayPhase as RedirectOverlayPhase, index_d$5_RedirectOverlayState as RedirectOverlayState, index_d$5_Reference as Reference, index_d$5_RefreshSubscriptionRequest as RefreshSubscriptionRequest, index_d$5_RefreshSubscriptionResponse as RefreshSubscriptionResponse, index_d$5_RemoveCustomClaimsResponse as RemoveCustomClaimsResponse, index_d$5_ResolvedLayoutConfig as ResolvedLayoutConfig, index_d$5_RevokeGitHubAccessRequest as RevokeGitHubAccessRequest, index_d$5_RouteMeta as RouteMeta, index_d$5_RouteSource as RouteSource, index_d$5_RoutesPluginConfig as RoutesPluginConfig, index_d$5_SEOConfig as SEOConfig, index_d$5_SchemaMetadata as SchemaMetadata, index_d$5_ScopeConfig as ScopeConfig, index_d$5_SecurityContext as SecurityContext, index_d$5_SecurityEntityConfig as SecurityEntityConfig, index_d$5_SendEmailRequest as SendEmailRequest, index_d$5_SendEmailResponse as SendEmailResponse, index_d$5_SeoMeta as SeoMeta, index_d$5_ServerRateLimitConfig as ServerRateLimitConfig, index_d$5_ServerRateLimitResult as ServerRateLimitResult, index_d$5_ServerUserRecord as ServerUserRecord, index_d$5_SetCustomClaimsResponse as SetCustomClaimsResponse, index_d$5_SidebarZoneConfig as SidebarZoneConfig, index_d$5_SignUpMetadata as SignUpMetadata, index_d$5_SlotContent as SlotContent, index_d$5_StorageOptions as StorageOptions, index_d$5_StorageScope as StorageScope, index_d$5_StorageType as StorageType, index_d$5_Store as Store, index_d$5_StripeBackConfig as StripeBackConfig, index_d$5_StripeCheckoutRequest as StripeCheckoutRequest, index_d$5_StripeCheckoutResponse as StripeCheckoutResponse, index_d$5_StripeCheckoutSessionEventData as StripeCheckoutSessionEventData, index_d$5_StripeConfig as StripeConfig, index_d$5_StripeCustomer as StripeCustomer, index_d$5_StripeCustomerEventData as StripeCustomerEventData, index_d$5_StripeEventData as StripeEventData, index_d$5_StripeEventKey as StripeEventKey, index_d$5_StripeEventName as StripeEventName, index_d$5_StripeFrontConfig as StripeFrontConfig, index_d$5_StripeInvoice as StripeInvoice, index_d$5_StripeInvoiceEventData as StripeInvoiceEventData, index_d$5_StripePayment as StripePayment, index_d$5_StripePaymentIntentEventData as StripePaymentIntentEventData, index_d$5_StripePaymentMethod as StripePaymentMethod, index_d$5_StripePrice as StripePrice, index_d$5_StripeProduct as StripeProduct, index_d$5_StripeProvider as StripeProvider, index_d$5_StripeSubscription as StripeSubscription, index_d$5_StripeSubscriptionData as StripeSubscriptionData, index_d$5_StripeWebhookEvent as StripeWebhookEvent, index_d$5_StripeWebhookEventData as StripeWebhookEventData, index_d$5_Subscription as Subscription, index_d$5_SubscriptionClaims as SubscriptionClaims, index_d$5_SubscriptionConfig as SubscriptionConfig, index_d$5_SubscriptionData as SubscriptionData, index_d$5_SubscriptionDuration as SubscriptionDuration, index_d$5_SubscriptionEventData as SubscriptionEventData, index_d$5_SubscriptionHookResult as SubscriptionHookResult, index_d$5_SubscriptionInfo as SubscriptionInfo, index_d$5_SubscriptionStatus as SubscriptionStatus, index_d$5_SubscriptionTier as SubscriptionTier, index_d$5_SupportedLanguage as SupportedLanguage, index_d$5_ThemeActions as ThemeActions, index_d$5_ThemeInfo as ThemeInfo, index_d$5_ThemeMode as ThemeMode, index_d$5_ThemeState as ThemeState, index_d$5_ThemesPluginConfig as ThemesPluginConfig, index_d$5_TierAccessHookResult as TierAccessHookResult, index_d$5_Timestamp as Timestamp, index_d$5_TokenInfo as TokenInfo, index_d$5_TokenResponse as TokenResponse, index_d$5_TokenState as TokenState, index_d$5_TokenStatus as TokenStatus, index_d$5_TranslationOptions as TranslationOptions, index_d$5_TranslationResource as TranslationResource, index_d$5_UIFieldOptions as UIFieldOptions, index_d$5_UniqueConstraintValidator as UniqueConstraintValidator, index_d$5_UniqueKeyDefinition as UniqueKeyDefinition, index_d$5_UnsubscribeFn as UnsubscribeFn, index_d$5_UpdateEntityData as UpdateEntityData, index_d$5_UpdateEntityRequest as UpdateEntityRequest, index_d$5_UpdateEntityResponse as UpdateEntityResponse, index_d$5_UploadOptions as UploadOptions, index_d$5_UploadProgressCallback as UploadProgressCallback, index_d$5_UploadResult as UploadResult, index_d$5_UseFunctionsCallResult as UseFunctionsCallResult, index_d$5_UseFunctionsMutationOptions as UseFunctionsMutationOptions, index_d$5_UseFunctionsMutationResult as UseFunctionsMutationResult, index_d$5_UseFunctionsQueryOptions as UseFunctionsQueryOptions, index_d$5_UseFunctionsQueryResult as UseFunctionsQueryResult, index_d$5_UseTranslationOptionsEnhanced as UseTranslationOptionsEnhanced, index_d$5_UserContext as UserContext, index_d$5_UserProfile as UserProfile, index_d$5_UserProviderData as UserProviderData, index_d$5_UserRole as UserRole, index_d$5_UserSubscription as UserSubscription, index_d$5_ValidateBlockOptions as ValidateBlockOptions, index_d$5_ValidationRules as ValidationRules, index_d$5_ValueTypeForField as ValueTypeForField, index_d$5_VerifiedToken as VerifiedToken, index_d$5_Visibility as Visibility, index_d$5_WebhookEvent as WebhookEvent, index_d$5_WebhookEventData as WebhookEventData, index_d$5_WhereClause as WhereClause, index_d$5_WhereOperator as WhereOperator, index_d$5_WidgetDef as WidgetDef, index_d$5_WithMetadata as WithMetadata, index_d$5_dndevSchema as dndevSchema }; } /** * @fileoverview Auth Method Resolution * @description Resolves the authentication method (popup vs redirect) based on * explicit preference or environment detection. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Get auth method (single source of truth) * - If method is provided: use it * - If method is null/undefined: isDev() ? 'popup' : 'redirect' * @param method - Auth method ('popup' or 'redirect') * @returns 'popup' or 'redirect' * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAuthMethod(method?: AuthMethod | null): AuthMethod; /** * @fileoverview Provider color utility * @description Returns the brand color for an authentication provider * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Returns the primary brand color associated with the specified authentication provider. * Uses schema discovery to support all AUTH_PARTNERS automatically. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * If the provider color is not found, it returns a default color. * * @param {AuthPartnerId} provider - The identifier for the authentication provider (e.g., 'google', 'facebook'). * @returns {string} The brand color as a hexadecimal string (e.g., '#1877F2'). */ declare function getProviderColor(provider: AuthPartnerId): string; /** * @fileoverview Token manager * @description Manages authentication tokens lifecycle and auto-refresh * * This module provides comprehensive token management including automatic * refresh, expiration monitoring, and secure storage. It handles the complete * token lifecycle from acquisition to refresh and cleanup. * * **Key Features:** * - Automatic token refresh before expiration * - Secure token storage and retrieval * - Token expiration monitoring * - Event-driven architecture for token updates * - Support for multiple token types (access, refresh, ID) * - Configurable refresh strategies * * **Token Types:** * - Access tokens for API authentication * - Refresh tokens for token renewal * - ID tokens for user identification * * **Security Features:** * - Secure storage with encryption * - Automatic cleanup of expired tokens * - Token validation and verification * - Protection against token leakage * * **Usage Pattern:** * ```typescript * import { tokenManager } from '@donotdev/utils'; * * // Set token * await tokenManager.setToken('access_token', tokenData); * * // Listen to token updates * tokenManager.on('tokenRefreshed', (newToken) => { * console.log('Token refreshed:', newToken); * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Shape of a user object that can refresh its own token. * Accepts Firebase User or any compatible auth user. */ interface AuthUserLike { getIdToken?: (forceRefresh?: boolean) => Promise<string>; getIdTokenResult?: (forceRefresh?: boolean) => Promise<{ token: string; expirationTime: string; }>; } /** * Extended token information structure * Extends the base TokenInfo from @donotdev/types with additional fields * Note: Base TokenInfo is available from @donotdev/types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ExtendedTokenInfo extends TokenInfo { /** Optional error when status is 'error' */ error?: Error; /** Optional refresh token */ refreshToken?: string | null; /** Optional ID token (for OAuth/OIDC flows) */ idToken?: string | null; } /** * Configuration options for TokenManager * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface TokenManagerOptions { /** * Buffer time in milliseconds before expiration to consider a token as "expiring soon" * @default 120000 (2 minutes) */ refreshBufferMs?: number; /** * Whether to automatically refresh tokens that are expiring soon * @default true */ autoRefresh?: boolean; /** * Maximum number of refresh attempts before failing * @default 3 */ maxRefreshAttempts?: number; /** * Callback when the token expires and cannot be refreshed */ onTokenExpired?: () => void; /** * Callback when a fatal error occurs */ onFatalError?: (error: Error) => void; } /** * TokenManager handles authentication token lifecycle including * storage, automatic refresh, expiration detection, and status tracking * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class TokenManager { private refreshTimerId; private refreshAttempts; private refreshBuffer; private maxRefreshAttempts; private autoRefresh; private authInstance; private onTokenExpired?; private onFatalError?; private refreshCallback?; private tokenInfo; /** * Creates a new TokenManager * * @param authInstance Optional auth instance for automatic refresh * @param options Configuration options */ constructor(authInstance?: unknown, options?: TokenManagerOptions); /** * Initialize token management with token information * * @param tokenInfo Initial token information */ initialize(tokenInfo: Omit<ExtendedTokenInfo, 'status'>): void; /** * Get the current token information * * @returns Current token information */ getTokenInfo(): ExtendedTokenInfo; /** * Reset the token manager * Clears token information and cancels scheduled refreshes */ reset(): void; /** * Force an immediate token refresh * * @param user Auth user with getIdToken/getIdTokenResult methods * @returns Promise resolving to the refreshed token or null */ forceRefresh(user?: AuthUserLike | null): Promise<string | null>; /** * Get a valid token, automatically refreshing if needed * * @returns Promise resolving to a valid token or null */ getValidToken(): Promise<string | null>; /** * Register a callback for token refresh * * @param callback Function that returns a promise resolving to success status * @returns Unsubscribe function */ onRefreshNeeded(callback: () => Promise<boolean>): () => void; /** * Update token information and emit the change * * @param tokenInfo New token information (partial) */ private updateTokenInfo; /** * Calculate token status based on expiration time * * @param expiresAt Token expiration date * @returns Current token status */ private calculateTokenStatus; /** * Schedule token refresh based on expiration time * * @param expiresAt Token expiration date */ private scheduleRefresh; /** * Handle errors during token refresh * * @param error Error that occurred */ private handleRefreshError; /** * Handle general errors * * @param error Error that occurred */ private handleError; /** * Clear the refresh timer */ private clearRefreshTimer; } declare const getTokenManager: () => TokenManager; /** * Claims cache options interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ClaimsCacheOptions { /** Enable offline trust (default: false) */ offlineTrustEnabled?: boolean; /** Storage key prefix (default: 'dndev-claims') */ storageKey?: string; /** User ID for scoped storage */ userId?: string | null; } /** * Claims cache result interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ClaimsCacheResult<T> { claims: T; source: 'network' | 'cache' | 'server-default'; timestamp: number; } /** * Claims type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type Claims = Record<string, any>; /** * ClaimsCache service * * Handles offline claims caching with graceful degradation: * - Server: Returns {} (safe default, no claims checking on server) * - Online: Always verify with server, update cache * - Offline: Use cached claims if offlineTrustEnabled=true * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class ClaimsCache { private offlineTrustEnabled; private storageKey; private userId; private storage; constructor(options?: ClaimsCacheOptions); /** * CSR/SSR safe client detection */ private isClient; /** * CSR/SSR safe network detection * Server: Returns false (can't detect network) * Client: Returns navigator.onLine */ private isOnline; /** * Get claims with graceful degradation * * Server: Returns {} (safe default, no claims checking on server) * Online: Always verify with server, update cache * Offline: Use cached claims if offlineTrustEnabled=true * * @param verifyFn - Function to verify claims with server * @returns Claims object */ getClaims<T extends Claims = Claims>(verifyFn: () => Promise<T>): Promise<T>; /** * Get cached claims from storage */ private getCachedClaims; /** * Set claims in cache */ setClaims<T extends Claims = Claims>(claims: T): Promise<void>; /** * Clear cached claims */ clearClaims(): Promise<void>; /** * Get storage key with user scoping */ private getStorageKey; /** * Update user ID (for user-scoped storage) */ setUserId(userId: string | null): void; /** * Update offline trust setting */ setOfflineTrustEnabled(enabled: boolean): void; } /** Options for the handleError utility. */ interface HandleErrorOptions { userMessage?: string; context?: Record<string, any>; log?: boolean; reportToSentry?: boolean; showNotification?: boolean; severity?: 'error' | 'warning' | 'info' | 'success'; notificationTimeout?: number; } /** * Universal error handler for DoNotDev applications * * Handles errors from any source, converting them to standardized DoNotDevError * objects, logging appropriately, and optionally adding to UI notification system. * * @param error - The original error from any source * @param optionsOrMessage - Optional configuration or user-friendly message * @returns Standardized DoNotDevError * * @example * try { * await fetchData(); * } catch (error) { * throw handleError(error, 'Failed to fetch data'); * } * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function handleError(error: unknown, optionsOrMessage?: HandleErrorOptions | string): DoNotDevError; /** * Creates a wrapped function that handles errors automatically * * @param fn - Function to wrap with error handling * @param options - Error handling options or user message * @returns Wrapped function with error handling * * @example * const safeFetchData = withErrorHandling(fetchData, 'Failed to fetch data'); * await safeFetchData(); * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function withErrorHandling<T extends (...args: any[]) => any>(fn: T, options?: HandleErrorOptions | string): (...args: Parameters<T>) => Promise<ReturnType<T>>; /** * Display a notification message (client-only) * This is a stub - actual implementation should be in client-side code * that imports toast directly from @donotdev/components * * @param message Message to display * @param severity Severity level * @param timeout Optional timeout in milliseconds * @returns ID of the notification * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function showNotification(message: string, severity?: 'error' | 'warning' | 'info' | 'success', timeout?: number): string; /** * @fileoverview Error source detection module * @description Automatically detects the source of errors to apply appropriate handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Detects the source of an error based on its properties and structure * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param error - The error to analyze * @returns The detected error source */ declare function detectErrorSource(error: unknown): ErrorSource; /** * Default error messages for standard error codes * These provide a fallback when no specific message is available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const DEFAULT_ERROR_MESSAGES: Record<ErrorCode, string>; /** * Maps an error from any source to a standardized DoNotDevError * * This is the central error mapping function that routes errors to the appropriate * handler based on the detected source. * * @param error - The original error * @param source - The detected error source * @param userMessage - Optional user-friendly message * @returns A standardized DoNotDevError * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function mapToDoNotDevError(error: unknown, source: ErrorSource, userMessage?: string): DoNotDevError; /** * @fileoverview Sentry integration module * @description Handles capturing errors to Sentry with appropriate context. * Works universally on both client and server - uses globalThis.Sentry which * is set by both @sentry/react and @sentry/node when initialized. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Captures an error to Sentry with additional context * Works on both client (@sentry/react) and server (@sentry/node) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param error - The error to capture * @param source - The detected error source * @param context - Additional context to include */ declare function captureErrorToSentry(error: DoNotDevError, source: ErrorSource, context?: Record<string, any>): void; /** * @fileoverview Standard error handling factory * @description Creates error handlers that map any source error to DoNotDevError format * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Type for error handler functions * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ErrorHandlerFunction = (error: unknown, userMessage?: string) => DoNotDevError; /** * Core configuration for error handlers * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ErrorHandlerConfig { errorSource: ErrorSource; defaultErrorCode: ErrorCode; defaultErrorMessage: string; errorCodeMapping?: Record<string, ErrorCode>; friendlyMessageMapping?: Record<string, string>; extractErrorCode?: (error: unknown) => string | undefined; extractErrorMessage?: (error: unknown) => string | undefined; processMetadata?: (error: unknown) => Record<string, any>; } /** * Creates an error handler that converts any type of error to DoNotDevError format * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param config Configuration for the error handler * @returns A function that converts errors to DoNotDevErrors */ declare function createErrorHandler(config: ErrorHandlerConfig): ErrorHandlerFunction; /** * Common error code mappings for most services * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const commonErrorCodeMappings: Record<string, ErrorCode>; /** * Initialize Sentry if configured * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Promise<boolean> - true if Sentry was initialized, false otherwise */ declare function initSentry(): Promise<boolean>; /** * Capture error with Sentry * @param error Error to capture * @param context Additional context * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function captureError(error: Error, context?: Record<string, any>): void; /** * Capture message with Sentry * @param message Message to capture * @param level Log level * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function captureMessage(message: string, level?: 'info' | 'warning' | 'error'): void; /** * Safely cleans up Sentry resources. */ declare function cleanupSentry(): Promise<void>; /** * Available framework features * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const FRAMEWORK_FEATURES: { readonly AUTH: "auth"; readonly OAUTH: "oauth"; readonly I18N: "i18n"; readonly BILLING: "billing"; readonly ROUTES: "routes"; readonly THEMES: "themes"; readonly COMPONENTS: "components"; readonly CRUD: "crud"; readonly FORMS: "forms"; readonly REALTIME: "realtime"; readonly STORAGE: "storage"; readonly AI: "ai"; }; /** * Framework feature type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FrameworkFeature = (typeof FRAMEWORK_FEATURES)[keyof typeof FRAMEWORK_FEATURES]; /** * Feature availability map * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type FeatureAvailability = Record<FrameworkFeature, boolean>; /** * Check if a specific feature is available and configured * @param feature The feature to check * @returns True if the feature is available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isFeatureAvailable(feature: FrameworkFeature): boolean; /** * Get all available features * @returns Array of available feature names * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAvailableFeatures(): FrameworkFeature[]; /** * Check if multiple features are available * @param features Array of features to check * @returns True if all features are available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function areFeaturesAvailable(features: FrameworkFeature[]): boolean; /** * Get feature availability summary * @returns Object with feature availability status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getFeatureSummary(): Record<FrameworkFeature, boolean>; /** * Clear feature cache (useful for testing or dynamic config changes) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function clearFeatureCache(): void; /** * @fileoverview Consent Level Constants * @description Cookie consent category constants for GDPR compliance * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Consent category constants * Must match CONSENT_CATEGORY from @donotdev/types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const CONSENT_LEVELS: { readonly NECESSARY: "necessary"; readonly FUNCTIONAL: "functional"; readonly ANALYTICS: "analytics"; readonly MARKETING: "marketing"; }; /** * Consent level type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type ConsentLevel = (typeof CONSENT_LEVELS)[keyof typeof CONSENT_LEVELS]; /** * Safe context hook with error handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useSafeContext<T>(context: T | undefined, name: string): T; /** * Get only valid auth partner IDs (pure discovery, no static structure) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getValidAuthPartnerIds(): AuthPartnerId[]; /** * Get only valid OAuth partner IDs (pure discovery, no static structure) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getValidOAuthPartnerIds(): OAuthPartnerId[]; /** * Dynamic config getter with validation (no static structure recreation) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getValidAuthPartnerConfig(partnerId: AuthPartnerId): { readonly name: "Apple"; readonly color: "#000000"; readonly icon: "apple"; readonly type: "both"; readonly scopes: readonly ["email", "name"]; readonly firebaseProviderId: "apple.com"; readonly customParameters: { readonly prompt: "login"; }; readonly button: { readonly backgroundColor: "#000000"; readonly textColor: "#ffffff"; readonly borderColor: "#000000"; readonly hoverBackgroundColor: "#1a1a1a"; readonly focusOutlineColor: "#333333"; readonly fontWeight: "500"; readonly textKey: "buttons.apple"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: readonly ["identify", "email"]; readonly firebaseProviderId: "discord.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.discord"; }; } | { readonly name: "Email Link"; readonly color: "#10B981"; readonly icon: "emailLink"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "emailLink"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#10B981"; readonly textColor: "#ffffff"; readonly borderColor: "#10B981"; readonly hoverBackgroundColor: "#059669"; readonly focusOutlineColor: "#059669"; readonly fontWeight: "500"; readonly textKey: "buttons.emailLink"; }; } | { readonly name: "Facebook"; readonly color: "#1877F2"; readonly icon: "facebook"; readonly type: "both"; readonly scopes: readonly ["email", "public_profile"]; readonly firebaseProviderId: "facebook.com"; readonly customParameters: { readonly auth_type: "reauthenticate"; }; readonly button: { readonly backgroundColor: "#1877F2"; readonly textColor: "#ffffff"; readonly borderColor: "#1877F2"; readonly hoverBackgroundColor: "#166FE5"; readonly focusOutlineColor: "#166FE5"; readonly fontWeight: "600"; readonly textKey: "buttons.facebook"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: readonly ["read:user", "user:email"]; readonly firebaseProviderId: "github.com"; readonly customParameters: { readonly allow_signup: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.github"; }; } | { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: readonly ["email", "profile"]; readonly firebaseProviderId: "google.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.google"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "both"; readonly scopes: readonly ["r_liteprofile", "r_emailaddress"]; readonly firebaseProviderId: "linkedin.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.linkedin"; }; } | { readonly name: "Microsoft"; readonly color: "#00A4EF"; readonly icon: "microsoft"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "microsoft.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.microsoft"; }; } | { readonly name: "Email & Password"; readonly color: "#6B7280"; readonly icon: "password"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "password"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#374151"; readonly borderColor: "#D1D5DB"; readonly hoverBackgroundColor: "#F9FAFB"; readonly focusOutlineColor: "#3B82F6"; readonly fontWeight: "500"; readonly textKey: "buttons.password"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: readonly ["identity"]; readonly firebaseProviderId: "reddit.com"; readonly customParameters: { readonly duration: "permanent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.reddit"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: readonly ["user-read-email", "user-read-private"]; readonly firebaseProviderId: "spotify.com"; readonly customParameters: { readonly show_dialog: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.spotify"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: readonly ["user:read:email"]; readonly firebaseProviderId: "twitch.tv"; readonly customParameters: { readonly force_verify: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitch"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "both"; readonly scopes: readonly []; readonly firebaseProviderId: "twitter.com"; readonly customParameters: { readonly force_login: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitter"; }; } | { readonly name: "Yahoo"; readonly color: "#5F01D1"; readonly icon: "yahoo"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "yahoo.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.yahoo"; }; } | undefined; /** * Dynamic config getter with validation (no static structure recreation) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getValidOAuthPartnerConfig(partnerId: OAuthPartnerId): { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["openid", "profile", "email"]; readonly 'api-access': readonly ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/gmail.readonly"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/oauth2/v3/userinfo"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["read:user", "user:email"]; readonly 'api-access': readonly ["repo", "user", "read:org", "gist", "notifications"]; }; readonly endpoints: { readonly authUrl: "https://github.com/login/oauth/authorize"; readonly tokenUrl: "https://github.com/login/oauth/access_token"; readonly profileUrl: "https://api.github.com/user"; readonly revokeUrl: "https://api.github.com/applications/CLIENT_ID/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identify", "email"]; readonly 'api-access': readonly ["guilds", "guilds.members.read", "bot", "messages.read"]; }; readonly endpoints: { readonly authUrl: "https://discord.com/api/oauth2/authorize"; readonly tokenUrl: "https://discord.com/api/oauth2/token"; readonly profileUrl: "https://discord.com/api/users/@me"; readonly revokeUrl: "https://discord.com/api/oauth2/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user-read-email", "user-read-private"]; readonly 'api-access': readonly ["user-read-playback-state", "user-modify-playback-state", "user-read-currently-playing", "playlist-read-private", "playlist-modify-public", "user-library-read"]; }; readonly endpoints: { readonly authUrl: "https://accounts.spotify.com/authorize"; readonly tokenUrl: "https://accounts.spotify.com/api/token"; readonly profileUrl: "https://api.spotify.com/v1/me"; readonly revokeUrl: "https://accounts.spotify.com/api/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user:read:email"]; readonly 'api-access': readonly ["channel:read:subscriptions", "bits:read", "channel:manage:broadcast", "channel:read:stream_key", "user:read:follows"]; }; readonly endpoints: { readonly authUrl: "https://id.twitch.tv/oauth2/authorize"; readonly tokenUrl: "https://id.twitch.tv/oauth2/token"; readonly profileUrl: "https://api.twitch.tv/helix/users"; readonly revokeUrl: "https://id.twitch.tv/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identity"]; readonly 'api-access': readonly ["read", "submit", "vote", "mysubreddits", "subscribe"]; }; readonly endpoints: { readonly authUrl: "https://www.reddit.com/api/v1/authorize"; readonly tokenUrl: "https://www.reddit.com/api/v1/access_token"; readonly profileUrl: "https://oauth.reddit.com/api/v1/me"; readonly revokeUrl: "https://www.reddit.com/api/v1/revoke_token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["r_liteprofile", "r_emailaddress", "w_member_social", "r_organization_social"]; }; readonly endpoints: { readonly authUrl: "https://www.linkedin.com/oauth/v2/authorization"; readonly tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken"; readonly profileUrl: "https://api.linkedin.com/v2/me"; readonly revokeUrl: "https://www.linkedin.com/oauth/v2/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Slack"; readonly color: "#E01E5A"; readonly icon: "slack"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["channels:read", "chat:write", "users:read", "files:read", "im:read"]; }; readonly endpoints: { readonly authUrl: "https://slack.com/oauth/v2/authorize"; readonly tokenUrl: "https://slack.com/api/oauth.v2.access"; readonly profileUrl: "https://slack.com/api/users.identity"; readonly revokeUrl: "https://slack.com/api/auth.revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Notion"; readonly color: "#000000"; readonly icon: "notion"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write"]; }; readonly endpoints: { readonly authUrl: "https://api.notion.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.notion.com/v1/oauth/token"; readonly profileUrl: "https://api.notion.com/v1/users/me"; readonly revokeUrl: "https://api.notion.com/v1/oauth/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Medium"; readonly color: "#000000"; readonly icon: "medium"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["basicProfile", "publishPost", "listPublications"]; }; readonly endpoints: { readonly authUrl: "https://medium.com/m/oauth/authorize"; readonly tokenUrl: "https://medium.com/v1/tokens"; readonly profileUrl: "https://medium.com/v1/me"; readonly revokeUrl: "https://medium.com/v1/tokens/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["tweet.read", "users.read", "follows.read", "tweet.write", "like.write"]; }; readonly endpoints: { readonly authUrl: "https://twitter.com/i/oauth2/authorize"; readonly tokenUrl: "https://api.twitter.com/2/oauth2/token"; readonly profileUrl: "https://api.twitter.com/2/users/me"; readonly revokeUrl: "https://api.twitter.com/2/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Mastodon"; readonly color: "#6364FF"; readonly icon: "mastodon"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write", "follow", "push"]; }; readonly endpoints: { readonly authUrl: ""; readonly tokenUrl: ""; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "YouTube"; readonly color: "#FF0000"; readonly icon: "youtube"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["https://www.googleapis.com/auth/youtube.readonly", "https://www.googleapis.com/auth/youtube.upload", "https://www.googleapis.com/auth/youtube.force-ssl"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/youtube/v3/channels"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Supabase"; readonly color: "#3ECF8E"; readonly icon: "supabase"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["auth:read", "auth:write", "database:read", "database:write", "domains:read", "domains:write", "edge_functions:read", "edge_functions:write", "environment:read", "environment:write", "organizations:read", "projects:read", "projects:write", "rest:read", "rest:write", "secrets:read", "secrets:write", "storage:read"]; }; readonly endpoints: { readonly authUrl: "https://api.supabase.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.supabase.com/v1/oauth/token"; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#F1F3F5"; readonly textColor: "#11181C"; readonly borderColor: "#E6E8EB"; readonly hoverBackgroundColor: "#E6E8EB"; readonly focusOutlineColor: "#3ECF8E"; readonly fontWeight: "500"; }; } | { readonly name: "Vercel"; readonly color: "#000000"; readonly icon: "vercel"; readonly type: "oauth"; readonly scopes: { readonly authentication: readonly ["openid", "email", "profile", "offline_access"]; readonly 'api-access': readonly ["project", "project-env-vars", "deployment", "team", "user"]; }; readonly endpoints: { readonly authUrl: "https://vercel.com/oauth/authorize"; readonly tokenUrl: "https://api.vercel.com/login/oauth/token"; readonly profileUrl: "https://api.vercel.com/login/oauth/userinfo"; readonly revokeUrl: "https://api.vercel.com/login/oauth/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | undefined; /** * Get enabled auth partners from environment variables * Computed once on first call, then cached permanently (like isDev/isClient) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Array of enabled auth partners */ declare function getEnabledAuthPartners(): AuthPartnerId[]; /** * Get enabled OAuth partners from environment variables * @returns Array of enabled OAuth partners * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getEnabledOAuthPartners(): OAuthPartnerId[]; /** * Get auth partner configuration (only if valid) * Lazily validates the partner before returning configuration * * @param partnerId Partner identifier * @returns Auth partner configuration or undefined if not found/invalid * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAuthPartnerConfig(partnerId: AuthPartnerId): { readonly name: "Apple"; readonly color: "#000000"; readonly icon: "apple"; readonly type: "both"; readonly scopes: readonly ["email", "name"]; readonly firebaseProviderId: "apple.com"; readonly customParameters: { readonly prompt: "login"; }; readonly button: { readonly backgroundColor: "#000000"; readonly textColor: "#ffffff"; readonly borderColor: "#000000"; readonly hoverBackgroundColor: "#1a1a1a"; readonly focusOutlineColor: "#333333"; readonly fontWeight: "500"; readonly textKey: "buttons.apple"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: readonly ["identify", "email"]; readonly firebaseProviderId: "discord.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.discord"; }; } | { readonly name: "Email Link"; readonly color: "#10B981"; readonly icon: "emailLink"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "emailLink"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#10B981"; readonly textColor: "#ffffff"; readonly borderColor: "#10B981"; readonly hoverBackgroundColor: "#059669"; readonly focusOutlineColor: "#059669"; readonly fontWeight: "500"; readonly textKey: "buttons.emailLink"; }; } | { readonly name: "Facebook"; readonly color: "#1877F2"; readonly icon: "facebook"; readonly type: "both"; readonly scopes: readonly ["email", "public_profile"]; readonly firebaseProviderId: "facebook.com"; readonly customParameters: { readonly auth_type: "reauthenticate"; }; readonly button: { readonly backgroundColor: "#1877F2"; readonly textColor: "#ffffff"; readonly borderColor: "#1877F2"; readonly hoverBackgroundColor: "#166FE5"; readonly focusOutlineColor: "#166FE5"; readonly fontWeight: "600"; readonly textKey: "buttons.facebook"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: readonly ["read:user", "user:email"]; readonly firebaseProviderId: "github.com"; readonly customParameters: { readonly allow_signup: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.github"; }; } | { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: readonly ["email", "profile"]; readonly firebaseProviderId: "google.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.google"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "both"; readonly scopes: readonly ["r_liteprofile", "r_emailaddress"]; readonly firebaseProviderId: "linkedin.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.linkedin"; }; } | { readonly name: "Microsoft"; readonly color: "#00A4EF"; readonly icon: "microsoft"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "microsoft.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.microsoft"; }; } | { readonly name: "Email & Password"; readonly color: "#6B7280"; readonly icon: "password"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "password"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#374151"; readonly borderColor: "#D1D5DB"; readonly hoverBackgroundColor: "#F9FAFB"; readonly focusOutlineColor: "#3B82F6"; readonly fontWeight: "500"; readonly textKey: "buttons.password"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: readonly ["identity"]; readonly firebaseProviderId: "reddit.com"; readonly customParameters: { readonly duration: "permanent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.reddit"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: readonly ["user-read-email", "user-read-private"]; readonly firebaseProviderId: "spotify.com"; readonly customParameters: { readonly show_dialog: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.spotify"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: readonly ["user:read:email"]; readonly firebaseProviderId: "twitch.tv"; readonly customParameters: { readonly force_verify: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitch"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "both"; readonly scopes: readonly []; readonly firebaseProviderId: "twitter.com"; readonly customParameters: { readonly force_login: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitter"; }; } | { readonly name: "Yahoo"; readonly color: "#5F01D1"; readonly icon: "yahoo"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "yahoo.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.yahoo"; }; } | undefined; /** * Get OAuth partner configuration (only if valid) * Lazily validates the partner before returning configuration * * @param partnerId Partner identifier * @returns OAuth partner configuration or undefined if not found/invalid * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getOAuthPartnerConfig(partnerId: OAuthPartnerId): { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["openid", "profile", "email"]; readonly 'api-access': readonly ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/gmail.readonly"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/oauth2/v3/userinfo"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["read:user", "user:email"]; readonly 'api-access': readonly ["repo", "user", "read:org", "gist", "notifications"]; }; readonly endpoints: { readonly authUrl: "https://github.com/login/oauth/authorize"; readonly tokenUrl: "https://github.com/login/oauth/access_token"; readonly profileUrl: "https://api.github.com/user"; readonly revokeUrl: "https://api.github.com/applications/CLIENT_ID/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identify", "email"]; readonly 'api-access': readonly ["guilds", "guilds.members.read", "bot", "messages.read"]; }; readonly endpoints: { readonly authUrl: "https://discord.com/api/oauth2/authorize"; readonly tokenUrl: "https://discord.com/api/oauth2/token"; readonly profileUrl: "https://discord.com/api/users/@me"; readonly revokeUrl: "https://discord.com/api/oauth2/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user-read-email", "user-read-private"]; readonly 'api-access': readonly ["user-read-playback-state", "user-modify-playback-state", "user-read-currently-playing", "playlist-read-private", "playlist-modify-public", "user-library-read"]; }; readonly endpoints: { readonly authUrl: "https://accounts.spotify.com/authorize"; readonly tokenUrl: "https://accounts.spotify.com/api/token"; readonly profileUrl: "https://api.spotify.com/v1/me"; readonly revokeUrl: "https://accounts.spotify.com/api/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user:read:email"]; readonly 'api-access': readonly ["channel:read:subscriptions", "bits:read", "channel:manage:broadcast", "channel:read:stream_key", "user:read:follows"]; }; readonly endpoints: { readonly authUrl: "https://id.twitch.tv/oauth2/authorize"; readonly tokenUrl: "https://id.twitch.tv/oauth2/token"; readonly profileUrl: "https://api.twitch.tv/helix/users"; readonly revokeUrl: "https://id.twitch.tv/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identity"]; readonly 'api-access': readonly ["read", "submit", "vote", "mysubreddits", "subscribe"]; }; readonly endpoints: { readonly authUrl: "https://www.reddit.com/api/v1/authorize"; readonly tokenUrl: "https://www.reddit.com/api/v1/access_token"; readonly profileUrl: "https://oauth.reddit.com/api/v1/me"; readonly revokeUrl: "https://www.reddit.com/api/v1/revoke_token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["r_liteprofile", "r_emailaddress", "w_member_social", "r_organization_social"]; }; readonly endpoints: { readonly authUrl: "https://www.linkedin.com/oauth/v2/authorization"; readonly tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken"; readonly profileUrl: "https://api.linkedin.com/v2/me"; readonly revokeUrl: "https://www.linkedin.com/oauth/v2/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Slack"; readonly color: "#E01E5A"; readonly icon: "slack"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["channels:read", "chat:write", "users:read", "files:read", "im:read"]; }; readonly endpoints: { readonly authUrl: "https://slack.com/oauth/v2/authorize"; readonly tokenUrl: "https://slack.com/api/oauth.v2.access"; readonly profileUrl: "https://slack.com/api/users.identity"; readonly revokeUrl: "https://slack.com/api/auth.revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Notion"; readonly color: "#000000"; readonly icon: "notion"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write"]; }; readonly endpoints: { readonly authUrl: "https://api.notion.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.notion.com/v1/oauth/token"; readonly profileUrl: "https://api.notion.com/v1/users/me"; readonly revokeUrl: "https://api.notion.com/v1/oauth/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Medium"; readonly color: "#000000"; readonly icon: "medium"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["basicProfile", "publishPost", "listPublications"]; }; readonly endpoints: { readonly authUrl: "https://medium.com/m/oauth/authorize"; readonly tokenUrl: "https://medium.com/v1/tokens"; readonly profileUrl: "https://medium.com/v1/me"; readonly revokeUrl: "https://medium.com/v1/tokens/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["tweet.read", "users.read", "follows.read", "tweet.write", "like.write"]; }; readonly endpoints: { readonly authUrl: "https://twitter.com/i/oauth2/authorize"; readonly tokenUrl: "https://api.twitter.com/2/oauth2/token"; readonly profileUrl: "https://api.twitter.com/2/users/me"; readonly revokeUrl: "https://api.twitter.com/2/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Mastodon"; readonly color: "#6364FF"; readonly icon: "mastodon"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write", "follow", "push"]; }; readonly endpoints: { readonly authUrl: ""; readonly tokenUrl: ""; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "YouTube"; readonly color: "#FF0000"; readonly icon: "youtube"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["https://www.googleapis.com/auth/youtube.readonly", "https://www.googleapis.com/auth/youtube.upload", "https://www.googleapis.com/auth/youtube.force-ssl"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/youtube/v3/channels"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Supabase"; readonly color: "#3ECF8E"; readonly icon: "supabase"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["auth:read", "auth:write", "database:read", "database:write", "domains:read", "domains:write", "edge_functions:read", "edge_functions:write", "environment:read", "environment:write", "organizations:read", "projects:read", "projects:write", "rest:read", "rest:write", "secrets:read", "secrets:write", "storage:read"]; }; readonly endpoints: { readonly authUrl: "https://api.supabase.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.supabase.com/v1/oauth/token"; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#F1F3F5"; readonly textColor: "#11181C"; readonly borderColor: "#E6E8EB"; readonly hoverBackgroundColor: "#E6E8EB"; readonly focusOutlineColor: "#3ECF8E"; readonly fontWeight: "500"; }; } | { readonly name: "Vercel"; readonly color: "#000000"; readonly icon: "vercel"; readonly type: "oauth"; readonly scopes: { readonly authentication: readonly ["openid", "email", "profile", "offline_access"]; readonly 'api-access': readonly ["project", "project-env-vars", "deployment", "team", "user"]; }; readonly endpoints: { readonly authUrl: "https://vercel.com/oauth/authorize"; readonly tokenUrl: "https://api.vercel.com/login/oauth/token"; readonly profileUrl: "https://api.vercel.com/login/oauth/userinfo"; readonly revokeUrl: "https://api.vercel.com/login/oauth/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | undefined; /** * Check if a partner is enabled for authentication * * @param partnerId Partner identifier * @returns True if the partner is enabled for authentication * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isAuthPartnerEnabled(partnerId: AuthPartnerId): boolean; /** * Check if a partner is enabled for OAuth API access * * @param partnerId Partner identifier * @returns True if the partner is enabled for OAuth API access * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isOAuthPartnerEnabled(partnerId: OAuthPartnerId): boolean; /** * Get partner configuration based on ID, regardless of type * * @param partnerId Partner identifier (auth or OAuth) * @returns Partner configuration or undefined if not found * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getPartnerConfig(partnerId: PartnerId): { readonly name: "Apple"; readonly color: "#000000"; readonly icon: "apple"; readonly type: "both"; readonly scopes: readonly ["email", "name"]; readonly firebaseProviderId: "apple.com"; readonly customParameters: { readonly prompt: "login"; }; readonly button: { readonly backgroundColor: "#000000"; readonly textColor: "#ffffff"; readonly borderColor: "#000000"; readonly hoverBackgroundColor: "#1a1a1a"; readonly focusOutlineColor: "#333333"; readonly fontWeight: "500"; readonly textKey: "buttons.apple"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: readonly ["identify", "email"]; readonly firebaseProviderId: "discord.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.discord"; }; } | { readonly name: "Email Link"; readonly color: "#10B981"; readonly icon: "emailLink"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "emailLink"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#10B981"; readonly textColor: "#ffffff"; readonly borderColor: "#10B981"; readonly hoverBackgroundColor: "#059669"; readonly focusOutlineColor: "#059669"; readonly fontWeight: "500"; readonly textKey: "buttons.emailLink"; }; } | { readonly name: "Facebook"; readonly color: "#1877F2"; readonly icon: "facebook"; readonly type: "both"; readonly scopes: readonly ["email", "public_profile"]; readonly firebaseProviderId: "facebook.com"; readonly customParameters: { readonly auth_type: "reauthenticate"; }; readonly button: { readonly backgroundColor: "#1877F2"; readonly textColor: "#ffffff"; readonly borderColor: "#1877F2"; readonly hoverBackgroundColor: "#166FE5"; readonly focusOutlineColor: "#166FE5"; readonly fontWeight: "600"; readonly textKey: "buttons.facebook"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: readonly ["read:user", "user:email"]; readonly firebaseProviderId: "github.com"; readonly customParameters: { readonly allow_signup: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.github"; }; } | { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: readonly ["email", "profile"]; readonly firebaseProviderId: "google.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.google"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "both"; readonly scopes: readonly ["r_liteprofile", "r_emailaddress"]; readonly firebaseProviderId: "linkedin.com"; readonly customParameters: { readonly prompt: "consent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.linkedin"; }; } | { readonly name: "Microsoft"; readonly color: "#00A4EF"; readonly icon: "microsoft"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "microsoft.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.microsoft"; }; } | { readonly name: "Email & Password"; readonly color: "#6B7280"; readonly icon: "password"; readonly type: "auth"; readonly scopes: readonly []; readonly firebaseProviderId: "password"; readonly customParameters: {}; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#374151"; readonly borderColor: "#D1D5DB"; readonly hoverBackgroundColor: "#F9FAFB"; readonly focusOutlineColor: "#3B82F6"; readonly fontWeight: "500"; readonly textKey: "buttons.password"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: readonly ["identity"]; readonly firebaseProviderId: "reddit.com"; readonly customParameters: { readonly duration: "permanent"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.reddit"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: readonly ["user-read-email", "user-read-private"]; readonly firebaseProviderId: "spotify.com"; readonly customParameters: { readonly show_dialog: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.spotify"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: readonly ["user:read:email"]; readonly firebaseProviderId: "twitch.tv"; readonly customParameters: { readonly force_verify: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitch"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "both"; readonly scopes: readonly []; readonly firebaseProviderId: "twitter.com"; readonly customParameters: { readonly force_login: "true"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.twitter"; }; } | { readonly name: "Yahoo"; readonly color: "#5F01D1"; readonly icon: "yahoo"; readonly type: "both"; readonly scopes: readonly ["openid", "email", "profile"]; readonly firebaseProviderId: "yahoo.com"; readonly customParameters: { readonly prompt: "select_account"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; readonly textKey: "buttons.yahoo"; }; } | { readonly name: "Google"; readonly color: "#4285F4"; readonly icon: "google"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["openid", "profile", "email"]; readonly 'api-access': readonly ["https://www.googleapis.com/auth/drive.readonly", "https://www.googleapis.com/auth/userinfo.profile", "https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/gmail.readonly"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/oauth2/v3/userinfo"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "GitHub"; readonly color: "#24292E"; readonly icon: "github"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["read:user", "user:email"]; readonly 'api-access': readonly ["repo", "user", "read:org", "gist", "notifications"]; }; readonly endpoints: { readonly authUrl: "https://github.com/login/oauth/authorize"; readonly tokenUrl: "https://github.com/login/oauth/access_token"; readonly profileUrl: "https://api.github.com/user"; readonly revokeUrl: "https://api.github.com/applications/CLIENT_ID/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Discord"; readonly color: "#5865F2"; readonly icon: "discord"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identify", "email"]; readonly 'api-access': readonly ["guilds", "guilds.members.read", "bot", "messages.read"]; }; readonly endpoints: { readonly authUrl: "https://discord.com/api/oauth2/authorize"; readonly tokenUrl: "https://discord.com/api/oauth2/token"; readonly profileUrl: "https://discord.com/api/users/@me"; readonly revokeUrl: "https://discord.com/api/oauth2/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Spotify"; readonly color: "#1DB954"; readonly icon: "spotify"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user-read-email", "user-read-private"]; readonly 'api-access': readonly ["user-read-playback-state", "user-modify-playback-state", "user-read-currently-playing", "playlist-read-private", "playlist-modify-public", "user-library-read"]; }; readonly endpoints: { readonly authUrl: "https://accounts.spotify.com/authorize"; readonly tokenUrl: "https://accounts.spotify.com/api/token"; readonly profileUrl: "https://api.spotify.com/v1/me"; readonly revokeUrl: "https://accounts.spotify.com/api/token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Twitch"; readonly color: "#9146FF"; readonly icon: "twitch"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["user:read:email"]; readonly 'api-access': readonly ["channel:read:subscriptions", "bits:read", "channel:manage:broadcast", "channel:read:stream_key", "user:read:follows"]; }; readonly endpoints: { readonly authUrl: "https://id.twitch.tv/oauth2/authorize"; readonly tokenUrl: "https://id.twitch.tv/oauth2/token"; readonly profileUrl: "https://api.twitch.tv/helix/users"; readonly revokeUrl: "https://id.twitch.tv/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Reddit"; readonly color: "#FF4500"; readonly icon: "reddit"; readonly type: "both"; readonly scopes: { readonly authentication: readonly ["identity"]; readonly 'api-access': readonly ["read", "submit", "vote", "mysubreddits", "subscribe"]; }; readonly endpoints: { readonly authUrl: "https://www.reddit.com/api/v1/authorize"; readonly tokenUrl: "https://www.reddit.com/api/v1/access_token"; readonly profileUrl: "https://oauth.reddit.com/api/v1/me"; readonly revokeUrl: "https://www.reddit.com/api/v1/revoke_token"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "LinkedIn"; readonly color: "#0077B5"; readonly icon: "linkedin"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["r_liteprofile", "r_emailaddress", "w_member_social", "r_organization_social"]; }; readonly endpoints: { readonly authUrl: "https://www.linkedin.com/oauth/v2/authorization"; readonly tokenUrl: "https://www.linkedin.com/oauth/v2/accessToken"; readonly profileUrl: "https://api.linkedin.com/v2/me"; readonly revokeUrl: "https://www.linkedin.com/oauth/v2/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Slack"; readonly color: "#E01E5A"; readonly icon: "slack"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["channels:read", "chat:write", "users:read", "files:read", "im:read"]; }; readonly endpoints: { readonly authUrl: "https://slack.com/oauth/v2/authorize"; readonly tokenUrl: "https://slack.com/api/oauth.v2.access"; readonly profileUrl: "https://slack.com/api/users.identity"; readonly revokeUrl: "https://slack.com/api/auth.revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Notion"; readonly color: "#000000"; readonly icon: "notion"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write"]; }; readonly endpoints: { readonly authUrl: "https://api.notion.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.notion.com/v1/oauth/token"; readonly profileUrl: "https://api.notion.com/v1/users/me"; readonly revokeUrl: "https://api.notion.com/v1/oauth/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Medium"; readonly color: "#000000"; readonly icon: "medium"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["basicProfile", "publishPost", "listPublications"]; }; readonly endpoints: { readonly authUrl: "https://medium.com/m/oauth/authorize"; readonly tokenUrl: "https://medium.com/v1/tokens"; readonly profileUrl: "https://medium.com/v1/me"; readonly revokeUrl: "https://medium.com/v1/tokens/revoke"; }; readonly capabilities: { readonly pkce: false; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "X"; readonly color: "#000000"; readonly icon: "twitter"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["tweet.read", "users.read", "follows.read", "tweet.write", "like.write"]; }; readonly endpoints: { readonly authUrl: "https://twitter.com/i/oauth2/authorize"; readonly tokenUrl: "https://api.twitter.com/2/oauth2/token"; readonly profileUrl: "https://api.twitter.com/2/users/me"; readonly revokeUrl: "https://api.twitter.com/2/oauth2/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Mastodon"; readonly color: "#6364FF"; readonly icon: "mastodon"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["read", "write", "follow", "push"]; }; readonly endpoints: { readonly authUrl: ""; readonly tokenUrl: ""; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "YouTube"; readonly color: "#FF0000"; readonly icon: "youtube"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["https://www.googleapis.com/auth/youtube.readonly", "https://www.googleapis.com/auth/youtube.upload", "https://www.googleapis.com/auth/youtube.force-ssl"]; }; readonly endpoints: { readonly authUrl: "https://accounts.google.com/o/oauth2/v2/auth"; readonly tokenUrl: "https://oauth2.googleapis.com/token"; readonly profileUrl: "https://www.googleapis.com/youtube/v3/channels"; readonly revokeUrl: "https://oauth2.googleapis.com/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | { readonly name: "Supabase"; readonly color: "#3ECF8E"; readonly icon: "supabase"; readonly type: "oauth"; readonly scopes: { readonly 'api-access': readonly ["auth:read", "auth:write", "database:read", "database:write", "domains:read", "domains:write", "edge_functions:read", "edge_functions:write", "environment:read", "environment:write", "organizations:read", "projects:read", "projects:write", "rest:read", "rest:write", "secrets:read", "secrets:write", "storage:read"]; }; readonly endpoints: { readonly authUrl: "https://api.supabase.com/v1/oauth/authorize"; readonly tokenUrl: "https://api.supabase.com/v1/oauth/token"; readonly profileUrl: ""; readonly revokeUrl: ""; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#F1F3F5"; readonly textColor: "#11181C"; readonly borderColor: "#E6E8EB"; readonly hoverBackgroundColor: "#E6E8EB"; readonly focusOutlineColor: "#3ECF8E"; readonly fontWeight: "500"; }; } | { readonly name: "Vercel"; readonly color: "#000000"; readonly icon: "vercel"; readonly type: "oauth"; readonly scopes: { readonly authentication: readonly ["openid", "email", "profile", "offline_access"]; readonly 'api-access': readonly ["project", "project-env-vars", "deployment", "team", "user"]; }; readonly endpoints: { readonly authUrl: "https://vercel.com/oauth/authorize"; readonly tokenUrl: "https://api.vercel.com/login/oauth/token"; readonly profileUrl: "https://api.vercel.com/login/oauth/userinfo"; readonly revokeUrl: "https://api.vercel.com/login/oauth/token/revoke"; }; readonly capabilities: { readonly pkce: true; readonly codeChallengeMethod: "S256"; }; readonly button: { readonly backgroundColor: "#ffffff"; readonly textColor: "#000000"; readonly borderColor: "#d1d5db"; readonly hoverBackgroundColor: "#f9fafb"; readonly focusOutlineColor: "#3b82f6"; readonly fontWeight: "500"; }; } | undefined; /** * Get OAuth client ID from environment variables * * @param partnerId Partner identifier * @returns Client ID or undefined if not configured * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getOAuthClientId(partnerId: OAuthPartnerId): string | undefined; /** * Get OAuth redirect URI from environment variables or use default * Simple, secure approach with single source of truth * * @param partnerId Partner identifier * @returns Redirect URI to use for OAuth flow * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getOAuthRedirectUri(partnerId: OAuthPartnerId): string; /** * Clear partner cache (useful for testing or when environment variables change) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function clearPartnerCache(): void; /** * Get cache status for debugging * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getPartnerCacheStatus(): { authPartnersCached: boolean; oauthPartnersCached: boolean; authPartners: ("google" | "apple" | "discord" | "emailLink" | "facebook" | "github" | "linkedin" | "microsoft" | "password" | "reddit" | "spotify" | "twitch" | "twitter" | "yahoo")[] | null; oauthPartners: ("google" | "discord" | "github" | "linkedin" | "reddit" | "spotify" | "twitch" | "twitter" | "notion" | "slack" | "medium" | "mastodon" | "youtube" | "supabase" | "vercel")[] | null; }; /** * Get AuthPartnerId from Firebase provider ID * Uses AUTH_PARTNERS schema as single source of truth (DRY) * * @param firebaseProviderId - Firebase provider ID (e.g., 'google.com', 'github.com') * @returns AuthPartnerId or null if not found * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAuthPartnerIdByFirebaseId(firebaseProviderId: string): AuthPartnerId | null; /** * Generate a secure, non-extractable encryption key. * * The key is marked `extractable: false` so the raw key material can never * be exported by JavaScript code, defeating the C-OLD-2 vulnerability. * * @returns Promise resolving to the generated key * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function generateEncryptionKey(): Promise<CryptoKey>; /** * Get or create the encryption key. * * Keys are stored in IndexedDB as native CryptoKey objects (not exported raw * bytes), so the key material is never written to localStorage or any * JavaScript-accessible string. * * @returns Promise resolving to the encryption key * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getEncryptionKey(): Promise<CryptoKey>; /** * Encrypt data using AES-GCM * @param data Data to encrypt (will be JSON stringified) * @returns Promise resolving to encrypted string (base64) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function encryptData(data: string | object | number | boolean): Promise<string>; /** * Decrypt data using AES-GCM * @param encryptedData Encrypted string (base64) * @returns Promise resolving to decrypted data (parsed from JSON) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function decryptData(encryptedData: string): Promise<string | object | number | boolean | null>; /** * @fileoverview Storage manager * @description Main storage manager implementation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Storage manager implementation * Handles storage operations with automatic strategy selection based on user tier * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class StorageManager implements IStorageManager { /** * Current storage strategy */ private strategy; private initialized; private userId; private isPro; /** * Create a new StorageManager * @param initialStrategy Initial storage strategy */ constructor(initialStrategy?: IStorageStrategy); /** * Lazily initialize the event listeners */ private initialize; /** * Set the storage strategy * @param strategy New storage strategy */ setStrategy(strategy: IStorageStrategy): void; /** * Update user information and select appropriate strategy * @param userId User ID or null * @param isPro Whether user has pro/enterprise tier */ updateUser(userId: string | null, isPro: boolean): void; private updateStrategy; /** * Retrieve data from storage */ get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Store data */ set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Remove data from storage */ remove(key: string): Promise<void>; /** * Clear all data in the specified scope */ clear(scope?: 'user' | 'global' | 'session'): Promise<void>; /** * Store sensitive data with encryption */ setSecure<T>(key: string, value: T, options?: Omit<StorageOptions, 'encryption'>): Promise<void>; /** * Retrieve sensitive data with decryption */ getSecure<T>(key: string, options?: Omit<StorageOptions, 'encryption'>): Promise<T | null>; } declare const getStorageManager: () => StorageManager; /** * React hook for using StorageManager * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns StorageManager instance */ declare function useStorageManager(): IStorageManager; /** * @fileoverview Base storage strategy * @description Abstract base class for storage strategies * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Abstract base class for storage strategies * Provides common functionality and defines interface for concrete strategies * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare abstract class BaseStorageStrategy implements IStorageStrategy { /** * Build a storage key with proper namespacing and scoping * @param key Base key * @param scope Storage scope * @param userId User ID for user scope * @param allowMissingUserId If true, returns null instead of throwing when userId is missing (for graceful degradation during sign out) * @returns Properly formatted storage key, or null if userId is missing and allowMissingUserId is true */ protected buildKey(key: string, scope: 'user' | 'global' | 'session', userId?: string | null, allowMissingUserId?: boolean): string | null; /** * Abstract method to retrieve data from storage */ abstract get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Abstract method to store data */ abstract set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Abstract method to remove data from storage */ abstract remove(key: string): Promise<void>; /** * Abstract method to clear all data in the specified scope */ abstract clear(scope?: 'user' | 'global' | 'session'): Promise<void>; } /** * @fileoverview Hybrid storage strategy * @description Implementation of storage strategy combining localStorage with cloud storage * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Hybrid storage strategy that combines local and cloud storage * Premium users get both local caching and cloud persistence * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class HybridStorageStrategy implements IStorageStrategy { /** * Local storage strategy for caching and fallback */ private localStrategy; /** * User ID for scoped storage */ private userId; /** * API endpoint for cloud storage */ private apiEndpoint; /** * Optional auth token getter for authenticated cloud requests */ private getAuthToken?; /** * Create a new HybridStorageStrategy * @param userId User ID for user-scoped storage (required) * @param apiEndpoint Optional API endpoint for cloud storage * @param getAuthToken Optional async function that returns the current auth token */ constructor(userId: string, apiEndpoint?: string, getAuthToken?: () => Promise<string | null>); /** * Build headers for cloud API requests, including Authorization if available */ private buildHeaders; /** * Retrieve data from storage * First checks local storage for cached data, then falls back to cloud if needed */ get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Store data in both local and cloud storage. * * Local storage is the source of truth - writes always succeed locally first. * Cloud sync is fire-and-forget: failures are logged as warnings, never thrown. * This ensures offline/degraded network never crashes the consumer's app. * * **Do NOT await cloud writes here.** Same pattern as {@link remove}. */ set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Remove data from both local and cloud storage */ remove(key: string): Promise<void>; /** * Clear all data in the specified scope from both local and cloud storage */ clear(scope?: 'user' | 'global' | 'session'): Promise<void>; /** * Build a storage key with proper namespacing and scoping * @param key Base key * @param scope Storage scope * @param userId User ID for user scope * @param allowMissingUserId If true, returns null instead of throwing when userId is missing (for graceful degradation during sign out) * @returns Properly formatted storage key, or null if userId is missing and allowMissingUserId is true */ private buildKey; /** * Get data from cloud storage * @private */ private getFromCloud; /** * Store data in cloud storage * @private */ private setToCloud; /** * Remove data from cloud storage * @private */ private removeFromCloud; /** * Clear all data in the specified scope from cloud storage * @private */ private clearFromCloud; } /** * @fileoverview Local storage strategy * @description Implementation of storage strategy using browser's localStorage * * This strategy provides client-side storage using the browser's localStorage API. * It's available to all users regardless of subscription tier and provides * basic data persistence with optional encryption support. * * **Key Features:** * - Browser localStorage integration * - User-scoped and global storage support * - Optional data encryption * - Error handling and validation * - Memory-efficient storage management * * **Storage Scopes:** * - `user`: User-specific data (requires userId) * - `global`: Shared data across all users * - `session`: Temporary data (not implemented in this strategy) * * **Security:** * - Optional encryption for sensitive data * - User isolation for user-scoped data * - Input validation and sanitization * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Storage strategy using browser's localStorage * * Provides client-side storage using the browser's localStorage API. * Available to all users regardless of subscription tier. * * **Capabilities:** * - User-scoped storage (when userId is provided) * - Global storage for shared data * - Optional encryption for sensitive data * - Automatic key scoping and validation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * **Limitations:** * - Limited by browser storage quotas * - Data is lost when localStorage is cleared * - No cloud synchronization * - No cross-device data sharing */ declare class LocalStorageStrategy extends BaseStorageStrategy { /** * User ID for user-scoped storage * Can be null for non-authenticated users (only global/session storage available) */ private userId; /** * Create a new LocalStorageStrategy * @param userId Optional user ID for user-scoped storage */ constructor(userId?: string | null); /** * Set the current user ID * @param userId User ID or null */ setUserId(userId: string | null): void; /** * Retrieve data from localStorage */ get<T>(key: string, options?: StorageOptions): Promise<T | null>; /** * Store data in localStorage */ set<T>(key: string, value: T, options?: StorageOptions): Promise<void>; /** * Remove data from localStorage */ remove(key: string): Promise<void>; /** * Clear all data in the specified scope */ clear(scope?: 'user' | 'global' | 'session'): Promise<void>; } /** * @fileoverview Safe Storage Utilities - SSR-compatible storage access * @description Provides safe access to browser storage APIs with SSR guards * Imperative API for use outside React (workers, init code, callbacks, utilities). * For reactive storage in components, use useLocalStorage hook instead. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Safe sessionStorage access with SSR compatibility * Handles cases where window is undefined (SSR) or storage is unavailable * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const safeSessionStorage: { getItem: (key: string) => string | null; setItem: (key: string, value: string) => void; removeItem: (key: string) => void; }; /** * Safe localStorage access with SSR compatibility * Handles cases where window is undefined (SSR) or storage is unavailable * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const safeLocalStorage: { getItem: (key: string) => string | null; setItem: (key: string, value: string) => void; removeItem: (key: string) => void; }; /** * @fileoverview Timing utilities * @description Debounce, throttle, and cooldown utilities for function execution control * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Creates a debounced function that delays invoking the provided function * until after the specified wait time has elapsed since the last invocation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param func The function to debounce * @param wait The number of milliseconds to delay * @param immediate Whether to invoke the function on the leading edge instead of trailing * @returns A debounced version of the function */ declare function debounce<T extends (...args: any[]) => any>(func: T, wait?: number, immediate?: boolean): (...args: Parameters<T>) => void; /** * Creates a throttled function that only invokes the provided function * at most once per every specified wait milliseconds. * * @param func The function to throttle * @param wait The number of milliseconds to throttle invocations to * @param trailing Whether to invoke on the trailing edge of the wait * @returns A throttled version of the function * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function throttle<T extends (...args: any[]) => any>(func: T, wait?: number, trailing?: boolean): (...args: Parameters<T>) => void; /** * Creates a function that executes once and then ignores subsequent calls * for the specified amount of time. * * @param func The function to rate-limit * @param wait The number of milliseconds to cool down * @returns A rate-limited function * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function cooldown<T extends (...args: any[]) => any>(func: T, wait?: number): (...args: Parameters<T>) => void; /** * Execute a function after a specified delay * * @param func Function to execute * @param delay Delay in milliseconds * @returns A function that when called will execute after the delay * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function delay<T extends (...args: any[]) => any>(func: T, delay?: number): (...args: Parameters<T>) => void; /** * Index of all timing utility functions for easy reference * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const timingUtils: { debounce: typeof debounce; throttle: typeof throttle; cooldown: typeof cooldown; delay: typeof delay; }; /** * @fileoverview Browser Detection and Compatibility Utilities * @description Comprehensive browser detection, feature support, and compatibility checking * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BrowserType = 'chrome' | 'firefox' | 'safari' | 'edge' | 'opera' | 'ie' | 'unknown'; /** * Browser engine type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type BrowserEngine = 'blink' | 'gecko' | 'webkit' | 'trident' | 'edgehtml' | 'unknown'; /** * Operating system type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type OS = 'windows' | 'macos' | 'linux' | 'android' | 'ios' | 'unknown'; /** * Browser information interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface BrowserInfo { type: BrowserType; version: string; engine: BrowserEngine; os: OS; isMobile: boolean; isTablet: boolean; isLaptop: boolean; userAgent: string; language: string; languages: string[]; cookieEnabled: boolean; onLine: boolean; doNotTrack: boolean; hardwareConcurrency: number; maxTouchPoints: number; deviceMemory?: number; connection?: { effectiveType: string; downlink: number; rtt: number; }; } /** * Feature support interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FeatureSupport { es6: boolean; es2017: boolean; es2020: boolean; modules: boolean; dynamicImport: boolean; webWorkers: boolean; serviceWorkers: boolean; pushNotifications: boolean; geolocation: boolean; webRTC: boolean; webGL: boolean; webGL2: boolean; localStorage: boolean; sessionStorage: boolean; indexedDB: boolean; webAudio: boolean; webVideo: boolean; getUserMedia: boolean; cssGrid: boolean; cssFlexbox: boolean; cssCustomProperties: boolean; cssContainerQueries: boolean; webp: boolean; avif: boolean; webpLossless: boolean; webpAnimation: boolean; intersectionObserver: boolean; resizeObserver: boolean; mutationObserver: boolean; performanceObserver: boolean; manifest: boolean; beforeInstallPrompt: boolean; standalone: boolean; crypto: boolean; subtleCrypto: boolean; secureContext: boolean; } /** * Compatibility report interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface CompatibilityReport { browser: BrowserInfo; features: FeatureSupport; issues: string[]; warnings: string[]; recommendations: string[]; score: number; } /** * Detect browser information from user agent and navigator * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function detectBrowser(): BrowserInfo; /** * Detect feature support * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function detectFeatures(): FeatureSupport; /** * Generate compatibility report * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function generateCompatibilityReport(): CompatibilityReport; /** * Check if browser supports a specific feature * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function supportsFeature(feature: keyof FeatureSupport): boolean; /** * Get browser recommendations * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getBrowserRecommendations(): string[]; /** * @fileoverview Cookie utility functions * @description Browser cookie management utilities * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Set a cookie with the specified options * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function setCookie(name: string, value: string, options?: CookieOptions): void; /** * Get a cookie value by name * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getCookie(name: string): string | null; /** * Delete a cookie by setting it to expire in the past * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function deleteCookie(name: string, options?: Partial<CookieOptions>): void; /** Metadata for a single cookie used by the consent banner. */ interface CookieInfo { name: string; category: 'necessary' | 'functional' | 'analytics' | 'marketing'; purpose: string; provider: string; } /** * Get all cookies being used based on detected features */ declare function getActiveCookies(): CookieInfo[]; /** * Get cookies by category */ declare function getCookiesByCategory(category: 'necessary' | 'functional' | 'analytics' | 'marketing'): CookieInfo[]; /** * Check if app uses any optional cookies (functional/analytics/marketing) */ declare function hasOptionalCookies(): boolean; /** * Get human-readable cookie list for a category */ declare function formatCookieList(category: 'necessary' | 'functional' | 'analytics' | 'marketing'): string; /** * Get cookie examples for banner display (short version) */ declare function getCookieExamples(category: 'necessary' | 'functional' | 'analytics' | 'marketing'): string; /** * @fileoverview Intersection Observer Utilities * @description Reusable intersection observer logic for the framework * @package @donotdev/utils * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Intersection Observer options * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface IntersectionObserverOptions { threshold?: number | number[]; rootMargin?: string; root?: Element | null; } /** * Intersection observer callback function * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => void; /** * Cleanup function returned by observeElement * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type CleanupFunction = () => void; /** * Observe an element with intersection observer * * @param element - Element to observe * @param callback - Callback when intersection changes * @param options - Intersection observer options * @returns Cleanup function * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function observeElement(element: Element, callback: IntersectionObserverCallback, options?: IntersectionObserverOptions): CleanupFunction; /** * Check if IntersectionObserver is supported * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isIntersectionObserverSupported(): boolean; /** * @fileoverview Viewport Detection Utilities * @description Reusable viewport detection logic for the framework * @package @donotdev/utils * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Viewport detection options * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ViewportDetectionOptions { /** * Intersection threshold (0-1) * @default 0.1 */ threshold?: number; /** * Root margin for intersection observer * @default '50px' */ rootMargin?: string; /** * Whether to trigger only once * @default false */ once?: boolean; /** * Whether to track individual items * @default true */ trackItems?: boolean; } /** * Viewport detection result * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface ViewportDetectionResult { /** * Whether the container is visible */ isVisible: boolean; /** * Whether the container has been triggered at least once */ hasTriggered: boolean; /** * Set of visible item indices */ visibleItems: Set<number>; } /** * Viewport handler class * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class ViewportHandler { private options; private visibleItems; private hasTriggered; constructor(options?: ViewportDetectionOptions); /** * Handle intersection observer entry */ handleIntersection(entry: IntersectionObserverEntry, container?: Element): ViewportDetectionResult; /** * Handle scroll event for item tracking */ handleScroll(container: Element): ViewportDetectionResult; /** * Update visible items based on container children */ private updateVisibleItems; /** * Check if element is in viewport */ private isElementInViewport; } /** * Create a viewport handler instance * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createViewportHandler(options?: ViewportDetectionOptions): ViewportHandler; /** * Check if element is in viewport * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isElementInViewport(element: Element, threshold?: number): boolean; /** * Get visible items from a container * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getVisibleItems(container: Element, threshold?: number): Set<number>; /** * Safe localStorage.getItem with error handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param key - localStorage key * @param defaultValue - Default value if key doesn't exist or error occurs * @returns Stored value or default value */ declare function getLocalStorageItem<T = string>(key: string, defaultValue: T): T; /** * Safe localStorage.setItem with error handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param key - localStorage key * @param value - Value to store * @returns Success boolean or StorageError object */ declare function setLocalStorageItem<T>(key: string, value: T): boolean | StorageError; /** * Safe localStorage.removeItem with error handling * @param key - localStorage key * @returns Whether the operation was successful * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function removeLocalStorageItem(key: string): boolean; /** * Safe localStorage.clear with error handling * @returns Whether the operation was successful * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function clearLocalStorage(): boolean; /** * Storage error type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type StorageErrorType = 'quota_exceeded' | 'security_error' | 'unavailable' | 'unknown'; /** * Storage error interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface StorageError { type: StorageErrorType; message: string; originalError?: unknown; } /** * Detect storage error type from exception * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function detectStorageError(error: unknown): StorageError; /** * Check if localStorage is available * @returns Whether localStorage is available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isLocalStorageAvailable(): boolean; /** * Platform information interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface PlatformInfo { platform: Platform; version?: string; mode: EnvironmentMode; context: Context; metadata?: { nextjsRuntime?: string; viteHmrPort?: number; detectedAt?: number; }; } /** * @fileoverview Platform detection utilities * @description Simple platform detection for Vite and Next.js * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Simple platform detection * * Detects the current platform (Vite or Next.js) and environment mode. * Provides cached results for performance. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function detectPlatform(): Platform; /** * Detailed platform detection with unified config integration * Cached after first call for optimal performance * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function detectPlatformInfo(): PlatformInfo; /** * Check if running on a specific platform * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param targetPlatform - Platform to check for * @returns True if running on the specified platform */ /** * Check if current platform matches target platform * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Check if current platform matches target * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isPlatform(targetPlatform: Platform): boolean; /** * Check if running on Next.js platform * Checks config first (source of truth), then falls back to detection * Caches result after first successful detection * * Enhanced detection for SSR/client reliability: * - Checks Next.js environment variables (NEXT_RUNTIME) * - Checks Next.js globals (__NEXT_DATA__) * - Falls back to config and full platform detection * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running on Next.js */ declare function isNextJs(): boolean; /** * Check if running on Vite platform * Checks config first (source of truth), then falls back to detection * Caches result after first successful detection * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running on Vite */ declare function isVite(): boolean; /** * Check if running in client context * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running in browser/client environment */ declare function isClient(): boolean; /** * Check if running in test environment * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running in test environment (Jest, etc.) */ declare function isTest(): boolean; /** * Check if running in server context * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running in Node.js/server environment */ declare function isServer(): boolean; /** * Initialize platform detection and set unified config * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Framework configuration object with platform information */ declare function initializePlatformDetection(): DndevFrameworkConfig; /** * Check if running on Expo platform * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running on Expo */ declare function isExpo(): boolean; /** * Check if running on React Native platform * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns True if running on React Native */ declare function isReactNative(): boolean; /** * Debug platform detection * Development helper to log platform detection details * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function debugPlatformDetection(): void; /** * @fileoverview Config Utilities * @description Low-level config access utilities (no platform dependencies) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Get DnDev config data synchronously * * Data is populated at build time and immediately available at runtime. * No async needed - config is always there when the app starts. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getDndevConfig(): DndevFrameworkConfig | null; /** * @fileoverview Cross-platform config access utilities * @description Provides unified access to DnDev config data across Vite and Next.js platforms * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Get specific config section * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getConfigSection<T>(section: keyof DndevFrameworkConfig): T | null; /** * Get themes configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getThemesConfig(): ThemesPluginConfig | null; /** * Get i18n configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getI18nConfig(): I18nPluginConfig | null; /** * Get routes configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getRoutesConfig(): unknown; /** * Get assets configuration * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAssetsConfig(): unknown; /** * Check if config is available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isConfigAvailable(): boolean; /** * Get config source information * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getConfigSource(): { platform: string; source: string; available: boolean; }; /** * Initialize config if not available (fallback only) * Config should be populated at build time - this is just a safety net */ declare function initializeConfig(): DndevFrameworkConfig | null; /** * Get Vite environment variable * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getViteEnvVar(name: string): string | undefined; /** * Get Next.js environment variable * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getNextEnvVar(name: string): string | undefined; /** * Platform-agnostic environment variable access * Handles both Vite (VITE_) and Next.js (NEXT_PUBLIC_) naming conventions * * Forgiving API: Accepts both prefixed and unprefixed names * - 'VITE_APP_VERSION' or 'APP_VERSION' both work for Vite * - 'NEXT_PUBLIC_APP_URL' or 'APP_URL' both work for Next.js * * @version 0.1.0 * @author AMBROISE PARK Consulting * @param baseName - The environment variable name (with or without prefix, e.g., 'COMPANY_NAME' or 'VITE_COMPANY_NAME') * @returns The value or undefined if not found */ declare function getPlatformEnvVar(baseName: string, platform?: Platform): string | undefined; /** * Get the OAuth redirect URL used by the framework. * * Single source of truth for OAuth callback endpoint construction. * Reads from VITE_APP_URL/NEXT_PUBLIC_APP_URL env var (set at build time from appConfig.app.url). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param baseUrl - Optional base URL. If not provided, reads from env var (set from appConfig.app.url at build time). * @returns Absolute OAuth redirect URL (e.g., 'https://example.com/oauth/callback') */ declare function getOAuthRedirectUrl(baseUrl?: string): string; /** * Get Firebase Auth domain (host only) * * Firebase Console always returns `projectId.firebaseapp.com` in SDK config, * but for custom domains in production, we need `yourdomain.com`. * * Logic: * - If APP_URL is set and not localhost → use APP_URL hostname (production custom domain) * - Otherwise → use FIREBASE_AUTH_DOMAIN (localhost/dev uses Firebase default) * * - Normalizes by stripping protocol and trailing slashes * - Lowercases the host * - No memoization; computed on each call similar to isDev() * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAuthDomain(): string; /** * Platform-agnostic development mode check * Uses framework's environment access to work in Vite, Next.js, SSR/CSR. * * Precedence: * 1) Vite's import.meta.env.DEV (true when command === 'serve', regardless of mode) * 2) Vite's import.meta.env.MODE !== 'production' (handles custom modes like 'test') * 3) APP_ENV (framework-level) * 4) NODE_ENV (platform-level) * Defaults to 'development' when unknown. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isDev(): boolean; /** * Get the application short name with proper fallback * Priority: app.shortName prop → app.name prop → default fallback * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param appConfig - Optional app metadata object * @param fallback - Default fallback value (default: 'App') * @returns The resolved app short name */ declare function getAppShortName(appConfig?: AppMetadata, fallback?: string): string; /** * Resolve complete app metadata with all fallbacks * * @version 0.1.0 * @author AMBROISE PARK Consulting * @param appConfig - Optional app metadata object * @returns Complete resolved app metadata */ declare function resolveAppConfig(appConfig?: AppMetadata): Required<Omit<AppMetadata, 'footer'>> & { footer?: AppMetadata['footer']; }; /** * Type for low-level event handler functions (internal use) * * Used internally for type safety while maintaining flexibility for any number of arguments. */ type InternalEventHandler = (...args: any[]) => void; /** * Event listener interface for TypeScript type checking * * Represents a single event listener with its handler function, configuration, * and optional context for binding. * * **Properties:** * - handler: Function to call when event is emitted * - once: Whether listener should be removed after first call * - context: Optional context to bind handler to * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface EventListener<T = any> { /** * Handler function for the event */ handler: InternalEventHandler; /** * Whether this is a one-time listener */ once: boolean; /** * Optional context for the handler */ context?: T; } /** * Enhanced EventEmitter implementation with type safety, event caching, and additional features * * This EventEmitter provides a robust event system with: * - Type safety for event handlers * - One-time listeners with automatic cleanup * - Context binding for handlers * - Listener count warnings for debugging * - Error handling for handler exceptions * - Memory leak prevention * - Event caching for race condition handling * - Automatic cache cleanup * * **Key Features:** * - Subscribe/unsubscribe to events * - One-time listeners (auto-remove after first call) * - Context binding for method handlers * - Listener count monitoring and warnings * - Error isolation (one handler error doesn't affect others) * - Memory leak prevention with proper cleanup * - Event caching to handle initialization race conditions * - Automatic cache cleanup (3-minute TTL) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * **Event Caching:** * Events are automatically cached when emitted to handle race conditions during * feature initialization. Listeners can retrieve cached events on startup to * ensure they don't miss events that occurred before they were initialized. * * **Usage Pattern:** * ```typescript * const emitter = new EventEmitter(); * * // Subscribe to event * const unsubscribe = emitter.on('myEvent', (data) => { * console.log('Event received:', data); * }); * * // Emit event (automatically cached) * emitter.emit('myEvent', { message: 'Hello' }); * * // Get cached events for race condition handling * const cachedEvents = emitter.getCachedEvents('myEvent'); * * // Unsubscribe * unsubscribe(); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class EventEmitter { /** * Map of event names to arrays of handlers * @private */ private events; /** * Map of event names to cached event data for race condition handling * @private */ private eventCache; /** * Maximum number of listeners per event before warnings * @private */ private maxListeners; /** * Cache TTL in milliseconds (3 minutes) * @private */ private readonly cacheTTL; /** * Subscribes to an event with optional context binding * * **Usage:** * ```typescript * // Basic subscription * const unsubscribe = emitter.on('myEvent', (data) => { * console.log('Event received:', data); * }); * * // With context binding * const unsubscribe = emitter.on('myEvent', handler, this); * ``` * * **Features:** * - Returns unsubscribe function for easy cleanup * - Supports context binding for method handlers * - Validates handler is a function * - Monitors listener count for debugging * * @param eventName - Name of the event to listen for * @param handler - Function to call when event is emitted * @param context - Optional context to bind handler to * @returns Function to unsubscribe from the event * @throws TypeError if handler is not a function */ on<T = any>(eventName: string, handler: InternalEventHandler, context?: T): () => void; /** * Subscribes to an event for a single emission (auto-removes after first call) * * **Usage:** * ```typescript * // One-time listener * const unsubscribe = emitter.once('myEvent', (data) => { * console.log('Event received once:', data); * }); * * // With context binding * const unsubscribe = emitter.once('myEvent', handler, this); * ``` * * **Features:** * - Automatically removes listener after first call * - Returns unsubscribe function (though not needed for one-time) * - Supports context binding for method handlers * - Useful for initialization events or one-time callbacks * * @param eventName - Name of the event to listen for * @param handler - Function to call when event is emitted * @param context - Optional context to bind handler to * @returns Function to unsubscribe from the event (though auto-removes) * @throws TypeError if handler is not a function */ once<T = any>(eventName: string, handler: InternalEventHandler, context?: T): () => void; /** * Unsubscribe from an event * * @param eventName Event name * @param handler Event handler function to remove * @returns Whether the handler was removed */ off(eventName: string, handler: InternalEventHandler): boolean; /** * Emits an event with arguments to all registered handlers and caches the event * * **Usage:** * ```typescript * // Emit with data (automatically cached) * emitter.emit('myEvent', { message: 'Hello' }); * * // Emit with multiple arguments (all arguments cached) * emitter.emit('myEvent', data1, data2, data3); * ``` * * **Features:** * - Calls all registered handlers for the event * - Handles one-time listeners (auto-removes after call) * - Isolates errors (one handler error doesn't affect others) * - Returns whether any handlers were called * - Supports any number of arguments * - Automatically caches event data for race condition handling * - Performs automatic cache cleanup * * **Event Caching:** * Events are automatically cached when emitted to handle race conditions during * feature initialization. The cache has a 3-minute TTL and is automatically * cleaned up to prevent memory leaks. * * **Error Handling:** * - Individual handler errors are caught and logged * - Errors don't prevent other handlers from being called * - Console errors are logged for debugging * - Cache operations are isolated from handler errors * * @param eventName - Name of the event to emit * @param args - Arguments to pass to all handlers and cache * @returns True if any handlers were called, false if no handlers exist */ emit(eventName: string, ...args: any[]): boolean; /** * Check if an event has subscribers * * @param eventName Event name * @returns Whether the event has subscribers */ hasListeners(eventName: string): boolean; /** * Get the number of subscribers for an event * * @param eventName Event name * @returns Number of subscribers */ listenerCount(eventName: string): number; /** * Get all registered event names * * @returns Array of event names */ eventNames(): string[]; /** * Get all listeners for an event * * @param eventName Event name * @returns Array of handler functions */ listeners(eventName: string): InternalEventHandler[]; /** * Remove all event listeners * * @param eventName Optional event name to remove listeners for */ removeAllListeners(eventName?: string): void; /** * Set the maximum number of listeners per event before warnings * * @param n Maximum number of listeners * @returns This instance for chaining */ setMaxListeners(n: number): this; /** * Get the maximum number of listeners per event * * @returns Maximum number of listeners */ getMaxListeners(): number; /** * Get or create the listener array for an event * * @param eventName Event name * @returns Array of listeners * @private */ private getListeners; /** * Check if we have too many listeners and warn if necessary * * @param eventName Event name * @private */ private checkListenerCount; /** * Cache an event for race condition handling during feature initialization * * **Purpose:** * Events are cached when emitted to handle race conditions where listeners * might be initialized after events have already been emitted. This ensures * that listeners can retrieve missed events during their initialization. * * **Automatic Cleanup:** * The cache automatically removes events older than the TTL (3 minutes) to * prevent memory leaks and ensure only recent events are available. * * **Usage:** * This method is called automatically by the `emit()` method. Manual usage * is typically not required unless implementing custom event handling. * * @param eventName - Name of the event to cache * @param eventData - Event data to cache (array of arguments) * @private */ private cacheEvent; /** * Get cached events for a specific event type * * **Purpose:** * Retrieves events that were emitted before a listener was initialized, * allowing listeners to catch up on missed events during startup. * * **Use Case:** * This is primarily used by BaseListener implementations during their * initialization to process events that occurred before they were ready. * * **Cache Behavior:** * - Returns events from the last 3 minutes * - Automatically excludes expired events * - Returns empty array if no cached events exist * * **Usage:** * ```typescript * // In BaseListener.initialize() * const cachedEvents = this.eventEmitter.getCachedEvents('MY_EVENT'); * cachedEvents.forEach(eventData => { * this.handleEvent('MY_EVENT', eventData); * }); * ``` * * @param eventName - Name of the event to retrieve cached data for * @returns Array of cached event data (array of arguments for each event) */ getCachedEvents(eventName: string): any[][]; /** * Clear cached events for a specific event type * * **Purpose:** * Manually clears cached events for a specific event type. This is useful * for memory management or when cached events are no longer needed. * * **Use Cases:** * - Memory cleanup after processing cached events * - Resetting event state during testing * - Manual cache management for specific events * * **Usage:** * ```typescript * // Clear cached events after processing * const cachedEvents = emitter.getCachedEvents('MY_EVENT'); * // Process events... * emitter.clearCachedEvents('MY_EVENT'); * ``` * * @param eventName - Name of the event to clear cache for */ clearCachedEvents(eventName: string): void; /** * Clear all cached events * * **Purpose:** * Clears all cached events across all event types. This is useful for * complete cache reset or memory cleanup. * * **Use Cases:** * - Complete cache reset during testing * - Memory cleanup in low-memory environments * - Application state reset * * **Usage:** * ```typescript * // Clear all cached events * emitter.clearAllCachedEvents(); * ``` */ clearAllCachedEvents(): void; /** * Get cache statistics for monitoring and debugging * * **Purpose:** * Provides information about the current cache state for monitoring, * debugging, and performance analysis. * * **Returns:** * Object containing cache statistics including event counts, memory usage * estimates, and cache health information. * * **Usage:** * ```typescript * const stats = emitter.getCacheStats(); * console.log(`Cache has ${stats.totalEvents} events across ${stats.eventTypes} types`); * ``` * * @returns Object containing cache statistics */ getCacheStats(): { totalEvents: number; eventTypes: number; oldestEvent: number | null; newestEvent: number | null; memoryEstimate: string; }; /** * Clean up expired events from the cache * * **Purpose:** * Removes events older than the TTL (3 minutes) from the cache to prevent * memory leaks and ensure only recent events are available. * * **Automatic Execution:** * This method is called automatically during event caching and retrieval * to maintain cache health. Manual calls are typically not required. * * @param eventName - Name of the event to clean up (optional, cleans all if not provided) * @private */ private cleanupCache; } /** * Global event emitter instance for framework-wide event communication * * This singleton instance is used throughout the framework for: * - Cross-component communication * - Feature initialization coordination * - State synchronization * - Error propagation * * **Usage:** * ```typescript * import { globalEmitter } from '@donotdev/utils'; * * // Emit framework events * globalEmitter.emit('FEATURE_INITIALIZED', { feature: 'auth' }); * * // Listen for framework events * globalEmitter.on('FEATURE_INITIALIZED', (data) => { * console.log('Feature initialized:', data); * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const globalEmitter: EventEmitter; /** * Safely redirect to an external URL * * SSR-safe utility for redirecting to external URLs (Stripe, OAuth providers, etc.) * Handles validation, error cases, and provides proper error feedback. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param url - External URL to redirect to * @param options - Redirect options * @returns Promise that resolves when redirect is initiated * * @example * ```tsx * try { * await redirectToExternalUrl('https://checkout.stripe.com/pay/...'); * } catch (error) { * // Handle redirect failure * handleError(error, { * userMessage: 'Failed to redirect to payment page', * showNotification: true, * }); * } * ``` */ declare function redirectToExternalUrl(url: string, options?: { /** Whether to open in new tab instead of redirecting */ openInNewTab?: boolean; /** Whether to validate URL format */ validateUrl?: boolean; }): Promise<void>; /** * Safely redirect to an external URL with automatic error handling * * Convenience function that automatically handles errors with toast notifications. * Use this when you want automatic error feedback without manual error handling. * * @param url - External URL to redirect to * @param options - Redirect options * @param errorMessage - Custom error message for toast * * @example * ```tsx * // Automatic error handling with toast * await redirectToExternalUrlWithErrorHandling( * 'https://checkout.stripe.com/pay/...', * {}, * 'Failed to redirect to payment page' * ); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function redirectToExternalUrlWithErrorHandling(url: string, options?: Parameters<typeof redirectToExternalUrl>[1], errorMessage?: string): Promise<void>; /** * Check if external redirects are available * * Useful for conditional rendering or fallback behavior. * * @returns True if external redirects are available (client-side) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function canRedirectExternally(): boolean; /** * Get current origin for redirect URL construction * * SSR-safe way to get the current origin for building redirect URLs. * * @returns Current origin or null if not available * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getCurrentOrigin(): string | null; /** * @fileoverview Degraded API Constants * @description Centralized degraded API objects for all feature packages (auth, billing, crud, oauth). * Used when features are not installed or consent not given, ensuring graceful degradation. * * **Each degraded API:** * - Returns safe defaults (null, empty arrays, no-op functions) * - Sets `status: 'degraded'` for guards to handle * - Guards redirect protected routes to auth route with error message * - Public routes continue to work normally * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Auth store keys - keys that come from Zustand store (reactive state) */ declare const AUTH_STORE_KEYS: Set<keyof AuthAPI>; /** * Auth computed keys - keys that are computed from store state */ declare const AUTH_COMPUTED_KEYS: Set<keyof AuthAPI>; /** * Billing store keys - keys that come from local state (useState, not Zustand) * Note: `status` is computed, not stored */ declare const BILLING_STORE_KEYS: Set<keyof BillingAPI>; /** * OAuth store keys - keys that come from Zustand store (reactive state) */ declare const OAUTH_STORE_KEYS: Set<keyof OAuthAPI>; /** * Degraded Auth API - returned when @donotdev/auth is not installed or not available */ declare const DEGRADED_AUTH_API: AuthAPI; /** * Degraded Billing API - returned when @donotdev/billing is not installed or not available */ declare const DEGRADED_BILLING_API: BillingAPI; /** * Degraded AI API - returned when @donotdev/ai is not installed or not available */ declare const DEGRADED_AI_API: AIAPI; /** * Degraded CRUD API - returned when @donotdev/crud is not installed or not available */ declare const DEGRADED_CRUD_API: CrudAPI; /** * Degraded OAuth API - returned when @donotdev/oauth is not installed or not available */ declare const DEGRADED_OAUTH_API: OAuthAPI; /** * Check if email verification should be shown to users * * Email verification is only relevant when: * 1. Email authentication is enabled (user can sign up with email/password) * 2. Firebase email verification is enabled in the project settings * * @returns boolean - true if email verification should be shown * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function shouldShowEmailVerification(): boolean; /** * Check if email verification is required for the current user * * @param user - The current user object * @returns boolean - true if email verification is required * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isEmailVerificationRequired(user: any): boolean; /** * @fileoverview Adapter Error Utilities * @description Utility functions for wrapping errors in adapter implementations. * These utilities help maintain consistent error handling across all adapters without * requiring inheritance or base classes. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Wraps an error from a CRUD adapter operation. * Maps common database/API errors to DoNotDevError with appropriate codes. * * @param error - The original error from the adapter * @param context - Context about the operation (e.g., "FirestoreAdapter.get", "SupabaseAdapter.add") * @param operation - The operation name (e.g., "get", "add", "query") * @param collection - The collection/table name * @param id - Optional document ID * @returns A DoNotDevError wrapping the original error * * @example * ```typescript * try { * return await this.client.from('users').select().eq('id', id).single(); * } catch (error) { * throw wrapCrudError(error, 'SupabaseCrudAdapter.get', 'get', 'users', id); * } * ``` */ declare function wrapCrudError(error: unknown, context: string, operation: string, collection: string, id?: string): DoNotDevError; /** * Wraps an error from a storage adapter operation. * * @param error - The original error from the adapter * @param context - Context about the operation (e.g., "FirebaseStorageAdapter.upload") * @param operation - The operation name (e.g., "upload", "delete", "getUrl") * @param path - The storage path or URL * @returns A DoNotDevError wrapping the original error * * @example * ```typescript * try { * return await this.bucket.upload(file, { destination: path }); * } catch (error) { * throw wrapStorageError(error, 'S3StorageAdapter.upload', 'upload', path); * } * ``` */ declare function wrapStorageError(error: unknown, context: string, operation: string, path: string): DoNotDevError; /** * Wraps an error from an auth adapter operation. * * @param error - The original error from the adapter * @param context - Context about the operation (e.g., "FirebaseAuth.signInWithEmail") * @param operation - The operation name (e.g., "signInWithEmail", "linkWithPartner") * @param details - Optional additional details (e.g., email, partnerId) * @returns A DoNotDevError wrapping the original error * * @example * ```typescript * try { * return await this.sdk.signInWithEmailAndPassword(email, password); * } catch (error) { * throw wrapAuthError(error, 'CustomAuth.signInWithEmail', 'signInWithEmail', { email }); * } * ``` */ declare function wrapAuthError(error: unknown, context: string, operation: string, details?: Record<string, unknown>): DoNotDevError; /** * Validates data against a schema, throwing a DoNotDevError if validation fails. * Use this in adapter methods to ensure data conforms to expected schemas. * * @param schema - The Valibot schema to validate against * @param data - The data to validate * @param context - Context for error messages (e.g., "FirestoreAdapter.add") * @returns The validated and parsed data * @throws DoNotDevError if validation fails * * @example * ```typescript * async add<T>(collection: string, data: T, schema?: dndevSchema<T>): Promise<{ id: string; data: Record<string, unknown> }> { * if (schema) { * data = validateWithSchema(schema, data, 'MyAdapter.add'); * } * // ... proceed with validated data * } * ``` */ declare function validateWithSchema<T>(schema: dndevSchema<T>, data: unknown, context: string): T; /** * Safely validates data against a schema, returning null if validation fails instead of throwing. * Useful when you want to handle validation errors gracefully. * * @param schema - The Valibot schema to validate against * @param data - The data to validate * @returns The validated data, or null if validation fails * * @example * ```typescript * const validated = safeValidate(schema, rawData); * if (!validated) { * console.warn('Data validation failed, skipping...'); * return null; * } * ``` */ declare function safeValidate<T>(schema: dndevSchema<T>, data: unknown): T | null; /** * Creates a spreadable object from validated data, ensuring it can be safely spread. * Use this when you need to spread validated data and add additional properties (like `id`). * * @param data - The validated data (should be an object) * @returns A Record that can be safely spread * * @example * ```typescript * const parsed = validateWithSchema(schema, data, 'MyAdapter.get'); * return { ...ensureSpreadable(parsed), id } as T; * ``` */ declare function ensureSpreadable<T>(data: T): Record<string, unknown>; /** * @fileoverview Array translation utilities * @description Provides utilities for handling array translations with indexed keys * * This module provides utilities to simplify the common pattern of accessing * array translations using indexed keys instead of returnObjects. * * **Why This Pattern?** * - Performance: Indexed access is faster than object parsing * - Consistency: Matches the framework's established patterns * - Reliability: Works across all i18n modes (standalone, UI, EDA) * - Filtering: Easy to filter out missing translations (returns key when missing) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * **Usage Pattern:** * ```typescript * import { translateArray } from '@donotdev/utils'; * * const benefits = translateArray(t, 'benefits', 6); // Gets benefits.0 through benefits.5 * const features = translateArray(t, 'features.list', 3); // Gets features.list.0 through features.list.2 * ``` */ /** * Translates an array using indexed keys and filters out missing translations * * **IMPORTANT:** This works with JSON arrays directly. i18next automatically treats * array indices as object keys, so `t('items.0')` works when JSON has `"items": ["value1", ...]` * * @param t - Translation function from useTranslation hook * @param keyPrefix - Base key prefix for the array (e.g., 'benefits', 'features.list') * @param maxIndex - Maximum index to check (exclusive, so 6 means indices 0-5) * @param options - Additional options for filtering * @returns Array of translated strings with missing translations filtered out * * @example * // JSON: { "benefits": ["value1", "value2", "value3"] } * const benefits = translateArray(t, 'benefits', 6); * // Result: ["value1", "value2", "value3"] * // Works because i18next treats arrays as objects with numeric keys * * @example * // JSON: { "features": { "list": ["feature1", "feature2"] } } * const features = translateArray(t, 'features.list', 5); * // Result: ["feature1", "feature2"] * * @example * // JSON: { "items": ["a", "b", "c", "d"] } * // Usage with List component: * <List items={translateArray(t, 'items', 10)} /> * // i18next accesses items.0, items.1, etc. automatically * * @example * // With custom filtering * const items = translateArray(t, 'items', 10, { * minLength: 2, // Only include items with at least 2 characters * excludeEmpty: true // Exclude empty strings * }); * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function translateArray(t: TFunction, keyPrefix: string, maxIndex: number, options?: { minLength?: number; excludeEmpty?: boolean; customFilter?: (item: string, index: number) => boolean; }): string[]; /** * Translates an array of objects using indexed keys * * @param t - Translation function from useTranslation hook * @param keyPrefix - Base key prefix for the array (e.g., 'cases', 'items') * @param maxIndex - Maximum index to check (exclusive, so 4 means indices 0-3) * @param keys - Array of property keys to extract from each object (e.g., ['useCase', 'bestFit', 'dndev', 'reason']) * @returns Array of translated objects with missing translations filtered out * * @example * // JSON: { "cases": { "0": { "useCase": "...", "bestFit": "..." }, "1": {...} } } * const cases = translateObjectArray(t, 'cases', 4, ['useCase', 'bestFit', 'dndev', 'reason']); * // Result: [{ useCase: "...", bestFit: "...", dndev: "...", reason: "..." }, ...] * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function translateObjectArray<K extends string, T extends Record<K, string> = Record<K, string>>(t: TFunction, keyPrefix: string, maxIndex: number, keys: readonly K[]): T[]; /** * Translates an array with a specific range of indices * * @param t - Translation function from useTranslation hook * @param keyPrefix - Base key prefix for the array * @param startIndex - Starting index (inclusive) * @param endIndex - Ending index (exclusive) * @param options - Additional options for filtering * @returns Array of translated strings with missing translations filtered out * * @example * // Get items 2-5 (indices 2, 3, 4) * const items = translateArrayRange(t, 'items', 2, 5); * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function translateArrayRange(t: TFunction, keyPrefix: string, startIndex: number, endIndex: number, options?: { minLength?: number; excludeEmpty?: boolean; customFilter?: (item: string, index: number) => boolean; }): string[]; /** * Translates an array and returns both the items and their original indices * Useful when you need to maintain the original index information * * @param t - Translation function from useTranslation hook * @param keyPrefix - Base key prefix for the array * @param maxIndex - Maximum index to check (exclusive) * @param options - Additional options for filtering * @returns Array of objects with item and originalIndex properties * * @example * // Get benefits with their original indices * const benefitsWithIndices = translateArrayWithIndices(t, 'benefits', 6); * // Result: [ * // { item: "value1", originalIndex: 0 }, * // { item: "value2", originalIndex: 1 }, * // { item: "value3", originalIndex: 2 } * // ] * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function translateArrayWithIndices(t: TFunction, keyPrefix: string, maxIndex: number, options?: { minLength?: number; excludeEmpty?: boolean; customFilter?: (item: string, index: number) => boolean; }): Array<{ item: string; originalIndex: number; }>; /** * @fileoverview Create document metadata utility * @description Creates metadata for a new document with timestamps and user IDs * * This utility provides a standardized way to create document metadata * for database operations, ensuring consistency across the application. * * **Metadata Fields:** * - `createdAt`: ISO timestamp when document was created * - `updatedAt`: ISO timestamp when document was last updated * - `createdById`: User ID who created the document * - `updatedById`: User ID who last updated the document * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * **Usage Pattern:** * ```typescript * const metadata = createMetadata(userId); * const document = { ...data, ...metadata }; * ``` * * **Database Integration:** * - Compatible with Firestore document structure * - Supports audit trails and user tracking * - Consistent timestamp format across all documents */ /** * Creates metadata for a new document with audit trail information * * **Purpose:** Provides standardized metadata for database documents * including creation timestamps and user tracking for audit purposes. * * **Features:** * - ISO timestamp format for consistency * - User ID tracking for audit trails * - Both creation and update fields initialized * - Ready for immediate database insertion * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param userId - The ID of the user creating the document * @returns Metadata object with timestamps and user IDs * * @example * ```typescript * const user = { id: 'user123', name: 'John Doe' }; * const metadata = createMetadata(user.id); * * const newPost = { * title: 'My Post', * content: 'Post content...', * ...metadata * }; * * await firestore.collection('posts').add(newPost); * ``` */ declare function createMetadata(userId: string): { createdAt: string; updatedAt: string; createdById: string; updatedById: string; }; /** * @fileoverview Currency Formatting Utilities * @description Single mapping of ISO 4217 currency codes to locale and symbol. Top ~50 currencies. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** Entry: 3-letter code → locale (for Intl) and display symbol */ interface CurrencyEntry { locale: string; symbol: string; } /** * Top ~50 currencies: 3-letter code, locale, symbol. * Unknown codes: getCurrencyLocale → 'en-US', getCurrencySymbol → code as-is. */ declare const CURRENCY_MAP: Record<string, CurrencyEntry>; /** * Returns the locale for a currency code (for Intl formatting). * Unknown codes → 'en-US'. * * @param currencyCode - ISO 4217 currency code (e.g. 'EUR', 'USD') * @returns Locale string */ declare function getCurrencyLocale(currencyCode: string): string; /** * Returns the symbol for a currency code (e.g. EUR → '€'). * Unknown codes → code as-is (no validation). * * @param currencyCode - ISO 4217 currency code or any string * @returns Symbol string or the code itself */ declare function getCurrencySymbol(currencyCode: string): string; /** * Format currency value with proper locale based on currency code * * @param value - Numeric value to format * @param currencyCode - ISO 4217 currency code * @param options - Additional Intl.NumberFormat options * @returns Formatted currency string * * @example * ```typescript * formatCurrency(12345, 'EUR') // → "12 345 €" * formatCurrency(12345, 'USD') // → "$12,345" * ``` */ declare function formatCurrency(value: number | null | undefined, currencyCode: string, options?: Intl.NumberFormatOptions): string; /** * @fileoverview Date utilities for consistent timestamp handling * @description Provides standardized date utilities for ISO string timestamps. * All date values in the framework should be ISO strings. Use these utilities to normalize any date input. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Convert compact date format (YYYYMMDD:HHMM) to ISO string * Format: 20251225:0000 → 2025-12-25T00:00:00.000Z * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param compactDate - Date in YYYYMMDD:HHMM format * @returns ISO string representation * @throws Error if format is invalid */ declare function compactToISOString(compactDate: string): string; /** * Convert ISO string to compact date format (YYYYMMDD:HHMM) * Format: 2025-12-25T00:00:00.000Z → 20251225:0000 * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param isoString - ISO date string * @returns Compact date string in YYYYMMDD:HHMM format * @throws Error if ISO string is invalid */ declare function isoToCompactString(isoString: string): string; /** * Check if a string is in compact date format (YYYYMMDD:HHMM) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param value - String to check * @returns True if string matches YYYYMMDD:HHMM format */ declare function isCompactDateString(value: string): boolean; /** * Normalize any date value to ISO string * Handles Date objects, ISO strings, compact format (YYYYMMDD:HHMM), timestamps (numbers), and Firestore Timestamps * This is the single source of truth for date normalization across the entire framework * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param date - Date value in any format (Date, string, number, FirestoreTimestamp) * @returns ISO string representation * @throws Error if date is invalid */ declare function normalizeToISOString(date: DateValue | number | null | undefined): string; /** * Get current timestamp as ISO string * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Current timestamp in ISO string format */ declare function getCurrentTimestamp(): string; /** * Convert Date object to ISO string * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param date - Date object to convert * @returns ISO string representation */ declare function toISOString(date: Date): string; /** * Convert timestamp (number) to ISO string * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param timestamp - Timestamp in milliseconds * @returns ISO string representation */ declare function timestampToISOString(timestamp: number): string; /** * Calculate week number from ISO date string * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param isoString - ISO date string * @returns Week number and year as string (e.g., "Week 15, 2024") */ declare function getWeekFromISOString(isoString: string): string; /** * Format a date as relative time (e.g., "5 minutes ago", "in 2 hours") * Uses native Intl.RelativeTimeFormat for locale-aware formatting. * Falls back to formatDate for dates older than threshold. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param date - Date value (ISO string, Date object, timestamp, or null/undefined) * @param locale - Locale string (e.g., "en", "fr", "de"). Defaults to "en" * @param options - Configuration options * @param options.style - "long" | "short" | "narrow". Defaults to "long" * @param options.numeric - "always" | "auto". Defaults to "auto" (allows "yesterday" instead of "1 day ago") * @param options.fallbackThreshold - Seconds after which to fall back to formatDate. Defaults to 1 week * @returns Localized relative time string or formatted date for old dates */ declare function formatRelativeTime(date: DateValue | number | null | undefined, locale?: string, options?: { style?: 'long' | 'short' | 'narrow'; numeric?: 'always' | 'auto'; fallbackThreshold?: number; }): string; /** Date format presets for common use cases */ type DateFormatPreset = 'full' | 'long' | 'medium' | 'short' | 'date-only' | 'time-only' | 'datetime'; /** Custom format options for fine-grained control */ interface DateFormatOptions { year?: 'numeric' | '2-digit'; month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow'; day?: 'numeric' | '2-digit'; weekday?: 'long' | 'short' | 'narrow'; hour?: 'numeric' | '2-digit'; minute?: 'numeric' | '2-digit'; second?: 'numeric' | '2-digit'; hour12?: boolean; timeZone?: string; timeZoneName?: 'long' | 'short'; } /** * Format date to localized string with preset or custom options * Uses native Intl.DateTimeFormat for proper locale-aware formatting. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param date - Date value (ISO string, Date object, timestamp, FirestoreTimestamp, or null/undefined) * @param locale - Locale string (e.g., "en", "fr", "de"). Defaults to "en" * @param format - Preset name or custom options. Defaults to "long" * @returns Localized formatted date string, or empty string if date is invalid * * @example * formatDate('2025-05-05T00:00:00.000Z', 'en', 'full') // "Monday, May 5, 2025" * formatDate('2025-05-05T00:00:00.000Z', 'fr', 'long') // "5 mai 2025" * formatDate('2025-05-05T14:30:00.000Z', 'en', 'datetime') // "May 5, 2025, 02:30 PM" * formatDate(new Date(), 'de', { month: 'short', day: 'numeric' }) // "5. Mai" */ declare function formatDate(date: DateValue | number | string | null | undefined, locale?: string, format?: DateFormatPreset | DateFormatOptions): string; /** * Leniently parse any date value to ISO string. * Accepts Date objects, ISO strings, timestamps, Firestore Timestamps, and common date formats. * Returns undefined for invalid/unparseable dates (never throws). * * Use this for form inputs, API responses, or any external data where format is uncertain. * For strict validation, use normalizeToISOString() which throws on invalid input. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param value - Any value that might be a date * @returns ISO string if parseable, undefined otherwise * * @example * parseDate(new Date()) // "2025-12-28T10:30:00.000Z" * parseDate('2025-12-28') // "2025-12-28T00:00:00.000Z" * parseDate('Dec 28, 2025') // "2025-12-28T00:00:00.000Z" * parseDate(1735384200000) // "2025-12-28T10:30:00.000Z" * parseDate({ toDate: () => new Date() }) // "2025-12-28T10:30:00.000Z" (Firestore) * parseDate('not a date') // undefined * parseDate(null) // undefined */ declare function parseDate(value: unknown): string | undefined; /** * Convert date-only string to ISO with time set to noon UTC. * Useful for date inputs where you want to avoid timezone edge cases. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param dateString - Date string (e.g., "2025-12-28") * @returns ISO string with time set to 12:00:00.000Z, or undefined if invalid * * @example * parseDateToNoonUTC('2025-12-28') // "2025-12-28T12:00:00.000Z" */ declare function parseDateToNoonUTC(dateString: string): string | undefined; /** * Extract date-only part from any date value (YYYY-MM-DD format). * Strips time component for date comparisons or display. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param date - Date value (ISO string, Date object, timestamp, or null/undefined) * @returns Date string in YYYY-MM-DD format, or empty string if invalid * * @example * toDateOnly('2025-12-28T14:30:00.000Z') // "2025-12-28" * toDateOnly(new Date()) // "2025-12-28" */ declare function toDateOnly(date: DateValue | number | string | null | undefined): string; /** * @fileoverview Firestore rule condition generator for stakeholder ownership * @description Given EntityOwnershipConfig, returns a rule condition string suitable for * allow read and allow update. Use the same condition for both (owners can read and update). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Generates a Firestore rule condition for read and update based on ownership config. * Use the returned string in firestore.rules like: * * allow read, update: if <generated>; * * The condition is: (publicCondition AND ...) OR request.auth.uid == resource.data.<ownerField1> OR ... * * @param ownership - Entity ownership config (ownerFields + optional publicCondition array) * @returns Rule condition expression string */ declare function generateFirestoreRuleCondition(ownership: EntityOwnershipConfig): string; /** * @fileoverview Smart translation helper * @description Auto-detects translation keys vs raw strings * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Smart translation helper - auto-detects translation keys vs raw strings * * **How it works:** * - If string has no dots/colons → return as-is (plain string) * - If string has namespace prefix (e.g. "purchase:products.x") → try to translate * - If string has dots but no namespace → try to translate (i18next fallback returns original if missing) * * **Namespace handling:** * - "purchase:products.earlyBird.name" → translates from purchase namespace * - "products.earlyBird.name" → translates from current namespace * - "Early Bird Lifetime" → returns as-is * * **Use cases:** * 1. Simple apps: Pass plain strings, they render as-is * 2. i18n apps: Pass translation keys with namespace prefix * 3. Edge cases: "Dr. Smith" with dot → tries t(), fallback returns original ✅ * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * @example * ```tsx * // Simple app * maybeTranslate(t, "Early Bird Lifetime") // → "Early Bird Lifetime" * * // i18n app with namespace * maybeTranslate(t, "purchase:products.earlyBird.name") // → "Accès Anticipé à Vie" (if FR) * * // i18n app without namespace * maybeTranslate(t, "products.earlyBird.name") // → "Accès Anticipé à Vie" (if FR) * * // Missing translation * maybeTranslate(t, "products.missing.key") // → "products.missing.key" (debug!) * ``` */ declare function maybeTranslate(t: any, value?: string): string; /** * @fileoverview PKCE (Proof Key for Code Exchange) utilities * @description Implements PKCE for OAuth 2.0 flows to enhance security * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Generate a cryptographically random code verifier * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Base64URL-encoded code verifier */ declare function generateCodeVerifier(): string; /** * Generate a code challenge from a code verifier * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param verifier The code verifier * @returns Promise resolving to Base64URL-encoded code challenge */ declare function generateCodeChallenge(verifier: string): Promise<string>; /** * Generate a PKCE pair (code verifier and challenge) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @returns Promise resolving to PKCE pair */ declare function generatePKCEPair(): Promise<{ codeVerifier: string; codeChallenge: string; }>; /** * Check if PKCE is supported by the current environment * @returns True if PKCE is supported * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isPKCESupported(): boolean; /** * Validate a code verifier format * @param verifier The code verifier to validate * @returns True if the verifier is valid * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCodeVerifier(verifier: string): boolean; /** * Validate a code challenge format * @param challenge The code challenge to validate * @returns True if the challenge is valid * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateCodeChallenge(challenge: string): boolean; /** * @fileoverview Graceful initialization utilities * @description Wraps initialization with graceful error handling and degradation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Wraps initialization with graceful error handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param init - Async initialization function * @param fallback - Fallback function on error * @param featureName - Name of feature for logging * @returns Result or false on error */ declare function withGracefulDegradation<T>(init: () => Promise<T>, fallback: () => void, featureName: string): Promise<T | false>; /** * Lazy import with caching * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param importFn - Dynamic import function * @param cacheKey - Cache key for this import * @returns Cached or fresh import result */ declare function lazyImport<T>(importFn: () => Promise<T>, cacheKey: string): Promise<T>; /** * @fileoverview Role Hierarchy Utilities * @description Provides role-based access control with hierarchical permissions. * Implements a 4-level hierarchy: guest (0) < user (1) < admin (2) < super (3). * * **Hierarchy Rules:** * - Super can access: super, admin, user, and guest routes * - Admin can access: admin, user, and guest routes * - User can access: user and guest routes * - Guest can access: guest routes only * * **CSR/SSR/Server Safe:** * Pure function with no browser APIs or React dependencies. * Safe for use in Firebase Functions, API routes, and server-side rendering. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Check if a user role has access to a required role based on hierarchy. * * Uses a 4-level hierarchy where higher roles inherit access to lower roles: * - Super (level 3) can access super, admin, user, and guest routes * - Admin (level 2) can access admin, user, and guest routes * - User (level 1) can access user and guest routes * - Guest (level 0) can access guest routes only * * Unknown roles default to level -1 (denied) for security. * Unknown required roles default to Infinity (always denied). * * @param userRole - The user's current role (e.g., 'super', 'admin', 'user', 'guest') * @param requiredRole - The role required to access the resource * @returns True if user has sufficient role level, false otherwise * * @example * ```typescript * // Admin accessing user route * hasRoleAccess('admin', 'user') // true * * // User accessing admin route * hasRoleAccess('user', 'admin') // false * * // Super accessing admin route * hasRoleAccess('super', 'admin') // true * ``` * * @version 0.1.0 * @since 0.0.1 */ declare function hasRoleAccess(userRole: string | undefined, requiredRole: string): boolean; /** * Extract canonical role from auth claims * * Handles: * - 'role' claim (primary) * - Boolean flags (isAdmin, isSuper) (legacy/convenience) * - Fallbacks to USER_ROLES.USER * * @param claims - Auth claims object * @returns Canonical role string */ declare function getRoleFromClaims(claims: Record<string, any>): string; /** * @fileoverview Tier Hierarchy Utilities * @description Provides subscription tier-based access control with hierarchical permissions. * Uses tier levels from SubscriptionConfig (apps define their own) with COMMON_TIER_CONFIGS as fallback. * * **Hierarchy Rules:** * Higher tier levels inherit access to lower tier levels: * - Tier with level 2 can access tiers with level 2, 1, and 0 * - Tier with level 1 can access tiers with level 1 and 0 * - Tier with level 0 can access tier with level 0 only * * **CSR/SSR/Server Safe:** * Pure function with no browser APIs or React dependencies. * Safe for use in Firebase Functions, API routes, and server-side rendering. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Check if a user tier has access to a required tier based on hierarchy. * * Uses tier levels from the provided config (or COMMON_TIER_CONFIGS as fallback). * Higher tier levels inherit access to lower tier levels. * * Unknown tiers default to level -1 (denied) for security. * Unknown required tiers default to Infinity (always denied). * * @param userTier - The user's current tier (e.g., 'pro', 'free', 'ai') * @param requiredTier - The tier required to access the resource * @param tierConfig - Optional custom tier configuration. If not provided, uses COMMON_TIER_CONFIGS * @returns True if user has sufficient tier level, false otherwise * * @example * ```typescript * // Pro accessing free route * hasTierAccess('pro', 'free') // true * * // Free accessing pro route * hasTierAccess('free', 'pro') // false * * // With custom config * const customConfig = { * basic: { features: [], level: 0 }, * premium: { features: [], level: 1 } * }; * hasTierAccess('premium', 'basic', customConfig) // true * ``` * * @version 0.1.0 * @since 0.0.1 */ declare function hasTierAccess(userTier: string | undefined, requiredTier: string, tierConfig?: SubscriptionConfig['tiers']): boolean; /** * @fileoverview Provider Registry * @description Central registration point for all pluggable backends (CRUD, auth, storage). * Call `configureProviders()` once at app startup so that `useCrud`, auth, and storage work. * All framework code uses `getProvider()` — no direct backend imports in app code. * * **Required:** Import your `config/providers` module from the root component (e.g. App.tsx) * before any component that uses `useCrud`, auth, or storage. * * @example Firebase (Vite) * ```typescript * // App.tsx * import './config/providers'; * // ... * ``` * ```typescript * // config/providers.ts * import { configureProviders } from '@donotdev/core'; * import { FirestoreAdapter, FirebaseAuth, FirebaseStorageAdapter } from '@donotdev/firebase'; * configureProviders({ * crud: new FirestoreAdapter(), * auth: new FirebaseAuth(), * storage: new FirebaseStorageAdapter(), * }); * ``` * * @example Supabase * ```typescript * import { configureProviders } from '@donotdev/core'; * import { SupabaseCrudAdapter, SupabaseAuth, SupabaseStorageAdapter } from '@donotdev/supabase'; * const supabase = createClient(url, anonKey); * configureProviders({ * crud: new SupabaseCrudAdapter(supabase), * auth: new SupabaseAuth(supabase), * storage: new SupabaseStorageAdapter(supabase, 'your-bucket'), * }); * ``` * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** * Configure all providers for the framework. * Must be called once at app startup, before any component uses `useCrud`, auth, or storage. * Typically called from a dedicated module (e.g. `config/providers.ts`) imported by main.tsx. * * @param providers - At least `crud`; optionally `auth`, `storage`, `serverAuth`, `callable` * @throws Does not throw; logs a warning if called more than once (use `resetProviders()` in tests) */ declare function configureProviders(providers: DndevProviders): void; /** * Get a configured provider by key. * * @param key - The provider key ('crud', 'auth', 'storage', 'serverAuth', 'callable') * @returns The provider instance * @throws If provider not configured */ declare function getProvider<K extends keyof DndevProviders>(key: K): NonNullable<DndevProviders[K]>; /** * Check if a provider is configured. * * @param key - The provider key to check * @returns true if the provider is configured */ declare function hasProvider(key: keyof DndevProviders): boolean; /** * Reset all providers. **Only for testing.** */ declare function resetProviders(): void; /** * Get or create a singleton backed by `globalThis.__DNDEV_SINGLETONS__`. * * Use this for singletons that must be shared across packages or survive * bundler chunk splits (Vite pre-bundling, esbuild code-splitting, HMR). * * Module-level `let` singletons break when a bundler evaluates the same * module in two separate chunks - each gets its own `let`. `globalThis` * is process-wide and survives all of that. * * **When to use:** * - Registries shared between consumer code and framework internals * (e.g. FieldRegistry, providers, auth instance) * - Any singleton where `registerX()` happens in one package and * `getX()` happens in another * * **When NOT to use:** * - Server-only singletons (functions/, tooling/, mcp-server/) - no chunk splits * - File-local caches that are only read in the same file * * @param key - Unique key for this singleton (e.g. 'field-registry') * @param factory - Factory function called once to create the instance * @returns The singleton instance (existing or newly created) * * @example * ```typescript * // In FieldRegistry.ts * import { getGlobalSingleton } from '@donotdev/core'; * * export function getFieldRegistry(): FieldRegistry { * return getGlobalSingleton('field-registry', () => new FieldRegistry()); * } * * // In providers.ts * let _providers = getGlobalSingleton('providers', () => ({ current: null })); * ``` */ declare function getGlobalSingleton<T>(key: string, factory: () => T): T; /** * Clear a global singleton. **Only for testing.** * * @param key - The singleton key to clear */ declare function clearGlobalSingleton(key: string): void; /** * Creates a singleton getter function for a class or factory function * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param ClassOrFactory - Class constructor or factory function * @param args - Constructor arguments (if ClassOrFactory is a class) * @returns Function that returns the singleton instance */ declare function createSingleton<T>(ClassOrFactory: (new (...args: any[]) => T) | (() => T), ...args: any[]): () => T; /** * Creates a singleton getter function for a class with parameters * This version allows passing parameters to the constructor * * @param ClassOrFactory - Class constructor or factory function * @returns Function that returns the singleton instance with parameters * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createSingletonWithParams<T>(ClassOrFactory: (new (...args: any[]) => T) | ((...args: any[]) => T)): (...args: any[]) => T; /** * Creates an async singleton getter function for async factory functions * * @param asyncFactory - Async factory function that returns a Promise<T> * @returns Function that returns a Promise<T> for the singleton instance * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createAsyncSingleton<T>(asyncFactory: () => Promise<T>): () => Promise<T>; /** * Creates a method proxy for a singleton getter * This allows direct method access without calling getInstance() first * * @param getInstance - Singleton getter function * @param methods - Array of method names to proxy * @returns Proxy object with direct method access * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createMethodProxy<T extends object>(getInstance: () => T, methods: (keyof T)[]): T; /** * Singleton manager for complex initialization scenarios * Provides async initialization with proper error handling * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare class SingletonManager { private static instances; private static initializing; private static initialized; /** * Get or create a singleton instance with async initialization * * @param key - Unique key for the singleton * @param factory - Factory function that returns the instance * @param options - Initialization options * @returns Promise that resolves to the singleton instance * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ static getOrCreate<T>(key: string, factory: () => Promise<T> | T, options?: { ssrSafe?: boolean; timeout?: number; cacheFailures?: boolean; fallbackFactory?: () => T; }): Promise<T>; /** * Check if a singleton is initialized * * @param key - Singleton key * @returns True if initialized * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ static isInitialized(key: string): boolean; /** * Clear a singleton instance (for testing) * * @param key - Singleton key * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ static clear(key: string): void; /** * Clear all singleton instances (for testing) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ static clearAll(): void; } /** * @fileoverview Update document metadata utility * @description Creates update metadata for an existing document * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Creates update metadata for an existing document * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param userId - The ID of the user updating the document * @returns An object with update timestamp and user ID */ declare function updateMetadata(userId: string): { updatedAt: string; updatedById: string; }; /** * @fileoverview Field visibility utility * @description Extracts visible field names from a Valibot schema based on user role. * * Uses 6-level hierarchical visibility system (leverages hasRoleAccess): * * Hierarchy: guest < user < admin < super * * - `guest`: Everyone (including unauthenticated) * - `user`: Authenticated users (see guest + user) * - `admin`: Admins (see guest + user + admin) * - `super`: Super admins (see guest + user + admin + super) * - `technical`: System fields (admins+ only, read-only in forms) * - `hidden`: Never exposed to client * - `owner`: Visible only when request.auth.uid matches one of entity.ownership.ownerFields on the document (requires options) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Determines if a field should be visible based on its visibility setting * and the user's role. * * Uses hasRoleAccess for hierarchical check: * - guest < user < admin < super * * Special cases: * - `technical`: Visible to admin and super only (read-only in forms) * - `hidden`: Never visible * - undefined: Treated as `guest` (visible to all) * * @param visibility - The field's visibility setting * @param userRole - The current user's role * @returns True if the field should be visible */ declare function isFieldVisible(visibility: Visibility | undefined, userRole: UserRole): boolean; /** * Options for owner-level visibility (per-document check). */ interface GetVisibleFieldsOptions { documentData?: Record<string, unknown>; uid?: string; ownership?: EntityOwnershipConfig; } /** * Extracts the names of all fields from a Valibot object schema that should be visible * based on the user's role and optional ownership context (for visibility: 'owner'). * * @param schema - The Valibot schema, expected to be an object schema (v.object) * @param userRole - The current user's role (guest, user, admin, super) * @param options - Optional: documentData, uid, ownership for owner-level visibility * @returns An array of visible field names */ declare function getVisibleFields(schema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>> | dndevSchema<any>, userRole: UserRole, options?: GetVisibleFieldsOptions): string[]; /** * @fileoverview Field visibility filter utility * @description Filters document fields based on visibility and user role using a Valibot schema. * * Uses 6-level hierarchical visibility system: * * Hierarchy: guest < user < admin < super * * - `guest`: Everyone (including unauthenticated) * - `user`: Authenticated users (see guest + user) * - `admin`: Admins (see guest + user + admin) * - `super`: Super admins (see guest + user + admin + super) * - `technical`: System fields (admins+ only, read-only in forms) * - `hidden`: Never exposed to client * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Options for owner-level visibility (per-document check). * Pass documentData, uid, and ownership so fields with visibility: 'owner' are included when uid matches an owner field. */ type FilterVisibleFieldsOptions = GetVisibleFieldsOptions; /** * Filters the fields of a data object based on visibility rules defined * in a Valibot schema and the user's role. When options (documentData, uid, ownership) * are provided, fields with visibility: 'owner' are included only if uid matches * one of ownership.ownerFields in documentData. * * @template T - The expected type of the data object * @param data - The document data object to filter * @param schema - The Valibot schema with visibility metadata on each field * @param userRole - The current user's role (guest, user, admin, super) * @param options - Optional: documentData, uid, ownership for owner-level visibility * @returns A new object containing only the fields visible to the user */ declare function filterVisibleFields<T extends Record<string, any>>(data: T | null | undefined, schema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>> | dndevSchema<any>, userRole: UserRole, options?: FilterVisibleFieldsOptions): Partial<T>; /** * @fileoverview Extract flat field names for card queries/schemas. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * SSOT for card field resolution. Returns a flat, deduplicated field name list. * * Fallback chain: `listCardFields` → `listFields` → all entity field keys. * * - `string[]` → returned as-is * - `ListCardLayout` → all slot arrays merged (deduplicated) * - `undefined` → falls back to `listFields`, then `Object.keys(fields)` */ declare function getListCardFieldNames(entity: { listCardFields?: string[] | ListCardLayout; listFields?: string[]; fields?: Record<string, unknown>; }): string[]; /** * @fileoverview Restricted visibility detection utility * @description Checks if any field in a schema has visibility more restrictive than 'guest'. * Used by CrudService to gate direct adapter access for non-public entities. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Returns true if any field in the schema declares a visibility level more * restrictive than 'guest' (i.e. 'user', 'owner', 'admin', 'super', 'technical', 'hidden'). * Used by CrudService to gate direct adapter access for non-public entities. * * Handles wrapped schemas (pipe, nullable, optional, union) by traversing the * schema tree to find the underlying object entries. Returns false for schemas * that cannot be introspected (lazy, custom). * * @param schema - A Valibot schema or dndevSchema to inspect * @returns true if any field has restricted visibility * * @example * // Public entity — all fields guest visibility * hasRestrictedVisibility(PublicPostSchema) // false * * @example * // Private entity — email field is 'user' visibility * hasRestrictedVisibility(UserProfileSchema) // true * * @version 0.1.0 * @since 0.0.1 */ declare function hasRestrictedVisibility(schema: v.BaseSchema<unknown, any, v.BaseIssue<unknown>> | dndevSchema<any>): boolean; /** * @fileoverview AuthHardening * @description Brute-force lockout + session timeout enforcement. * Covers SOC2 CC6.1 (authentication), CC6.2 (account lockout). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LockoutEntry { attempts: number; lastAttempt: number; /** null = not locked; number = locked until this timestamp */ lockedUntil: number | null; } /** Configuration for brute-force lockout and session timeout enforcement. */ interface AuthHardeningConfig { /** * Max consecutive failed sign-in attempts before lockout. * @default 5 */ maxAttempts?: number; /** * Lockout duration in milliseconds. * @default 900_000 (15 minutes) */ lockoutMs?: number; /** * Idle session timeout in milliseconds. After this period of inactivity, * the session is considered expired. * @default 28_800_000 (8 hours) */ sessionTimeoutMs?: number; } /** Result of a lockout status check for an identifier. */ interface LockoutResult { attempts: number; locked: boolean; lockedUntil: number | null; } declare class AuthHardening implements AuthHardeningContext { private readonly store; private readonly maxAttempts; private readonly lockoutMs; /** Expose for auth adapters to enforce idle session timeout */ readonly sessionTimeoutMs: number; constructor(config?: AuthHardeningConfig); /** * Call BEFORE a sign-in attempt. * @throws {Error} if the identifier is currently locked. */ checkLockout(identifier: string): void; /** * Call AFTER a failed sign-in attempt. * @returns current attempt count and whether the account is now locked. */ recordFailure(identifier: string): LockoutResult; private _evictExpired; /** * Call AFTER a successful sign-in — resets the failure counter. */ recordSuccess(identifier: string): void; /** * Check if a session has expired based on last activity timestamp. * @param lastActivityMs - `Date.now()` at last activity */ isSessionExpired(lastActivityMs: number): boolean; /** Current entry for an identifier (for audit logging). */ getEntry(identifier: string): LockoutEntry | undefined; } /** * @fileoverview Condition Builder Engine * @description Fluent API for building field conditions and evaluating them at runtime. * Used for dynamic field visibility, disabled state, required state, and readonly state. * * @example * ```typescript * import { when, evaluateCondition } from '@donotdev/core'; * * // Simple condition * const condition = when('productType').equals('car'); * evaluateCondition(condition, { productType: 'car' }); // true * * // Combined conditions * const combined = when('type').equals('corporate') * .or(when('groupSize').greaterThan(10)); * evaluateCondition(combined, { type: 'individual', groupSize: 15 }); // true * * // On entity fields * { name: 'licensePlate', type: 'text', visibility: 'user', * conditions: { * visible: when('productType').equals('car'), * required: when('productType').equals('car'), * } * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Evaluate a condition expression (node or group) against form values. * * @param condition - The condition expression or ConditionBuilder to evaluate * @param formValues - Current form values (flat object or nested for workflows) * @returns Whether the condition is satisfied * * @example * ```typescript * const cond = when('status').equals('active'); * const result = evaluateCondition(cond, { status: 'active' }); // true * ``` */ declare function evaluateCondition(condition: ConditionInput, formValues: Record<string, unknown>): boolean; /** * Evaluate all conditions for a field and return the computed state. * * @param behavior - The ConditionalBehavior from the field definition * @param formValues - Current form values * @returns ConditionResult with visible/disabled/required/readonly booleans */ declare function evaluateFieldConditions(behavior: ConditionalBehavior | undefined, formValues: Record<string, unknown>): ConditionResult; /** * Chainable condition builder. * Wraps a ConditionExpression and provides .or()/.and() combinators. * Implements ConditionBuilderLike from @donotdev/types. */ declare class ConditionBuilder { /** The underlying condition expression (serializable data) */ readonly expression: ConditionExpression; constructor(expression: ConditionExpression); /** The discriminant for ConditionExpression — delegates to inner expression */ get type(): ConditionExpression['type']; /** Combine with OR logic */ or(other: ConditionExpression | ConditionBuilder): ConditionBuilder; /** Combine with AND logic */ and(other: ConditionExpression | ConditionBuilder): ConditionBuilder; } /** Intermediate builder returned by when(field) — provides operator methods */ interface WhenFieldBuilder { /** Field equals value */ equals(value: unknown): ConditionBuilder; /** Field does not equal value */ notEquals(value: unknown): ConditionBuilder; /** Field value is in array */ in(values: unknown[]): ConditionBuilder; /** Field value is not in array */ notIn(values: unknown[]): ConditionBuilder; /** Field value is greater than */ greaterThan(value: number): ConditionBuilder; /** Field value is less than */ lessThan(value: number): ConditionBuilder; /** Field value is greater than or equal */ greaterThanOrEqual(value: number): ConditionBuilder; /** Field value is less than or equal */ lessThanOrEqual(value: number): ConditionBuilder; /** Field has a truthy value (not null, not empty, not false) */ exists(): ConditionBuilder; /** Field has no value (null, empty, or false) */ notExists(): ConditionBuilder; /** Field contains value (string includes or array includes) */ contains(value: unknown): ConditionBuilder; } /** * Start building a condition for a field. * * @param field - Field name to evaluate (supports dot notation for nested/cross-step: 'step.field') * @returns Builder with operator methods * * @example * ```typescript * // Simple * when('type').equals('car') * * // Combined * when('type').equals('corporate').or(when('size').greaterThan(10)) * * // Cross-step (workflows) * when('basics.productType').equals('physical') * ``` */ declare function when(field: string): WhenFieldBuilder; /** * Extract all field names referenced by a condition expression. * Useful for building dependency graphs and optimizing re-evaluation. * * @param condition - The condition expression or builder to analyze * @returns Set of field names (may include dot-notated paths) */ declare function getConditionDependencies(condition: ConditionExpression | ConditionBuilder): Set<string>; /** * Sanitize a URL for use in href attributes. * Blocks javascript:, data:, vbscript: and other dangerous schemes. * Allows safe schemes and relative URLs. * * @param href - The URL to sanitize * @returns The original URL if safe, empty string if dangerous */ declare function sanitizeHref(href: string): string; /** * @fileoverview Safari-safe UUID v4 generator * @description Generates RFC 4122 compliant v4 UUIDs using `crypto.getRandomValues()`, * which is available in ALL modern browsers (Safari 11+, Chrome 11+, Firefox 26+). * * `crypto.randomUUID()` requires Safari 15.4+ and a secure context. * This utility works everywhere `crypto.getRandomValues()` is available, * which covers every browser we support. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** * Generate a cryptographically random UUID v4. * * Uses `crypto.getRandomValues()` (universal) instead of `crypto.randomUUID()` * (Safari 15.4+ only) for maximum browser compatibility. * * @returns UUID v4 string (e.g. "550e8400-e29b-41d4-a716-446655440000") * * @version 0.1.0 * @since 0.1.0 */ declare function generateUUID(): string; /** * @fileoverview Timeout and abort utilities for async operations * @description Wraps promises with timeout and AbortSignal support. * Used by CRUD and storage adapters to enforce operation deadlines. * * @version 0.1.0 * @since 0.5.0 * @author AMBROISE PARK Consulting */ /** Default timeout for upload operations (30 seconds) */ declare const DEFAULT_UPLOAD_TIMEOUT = 30000; /** Default timeout for CRUD operations (15 seconds) */ declare const DEFAULT_CRUD_TIMEOUT = 15000; /** * Wrap a promise with a timeout and optional AbortSignal. * * - If timeout expires: rejects with a TimeoutError * - If signal aborts: rejects with an AbortError * - If promise resolves/rejects first: returns that result * - Cleans up all listeners on completion * * @param promise - The promise to wrap * @param timeoutMs - Timeout in milliseconds (0 or negative = no timeout) * @param signal - Optional AbortSignal * @returns The promise result */ declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<T>; /** * @fileoverview Utils package * @description Utility functions for DoNotDev framework * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map declare const index_d$4_AUTH_COMPUTED_KEYS: typeof AUTH_COMPUTED_KEYS; declare const index_d$4_AUTH_STORE_KEYS: typeof AUTH_STORE_KEYS; type index_d$4_AuthHardening = AuthHardening; declare const index_d$4_AuthHardening: typeof AuthHardening; type index_d$4_AuthHardeningConfig = AuthHardeningConfig; type index_d$4_AuthUserLike = AuthUserLike; declare const index_d$4_BILLING_STORE_KEYS: typeof BILLING_STORE_KEYS; type index_d$4_BaseStorageStrategy = BaseStorageStrategy; declare const index_d$4_BaseStorageStrategy: typeof BaseStorageStrategy; type index_d$4_BrowserEngine = BrowserEngine; type index_d$4_BrowserInfo = BrowserInfo; type index_d$4_BrowserType = BrowserType; declare const index_d$4_CONSENT_LEVELS: typeof CONSENT_LEVELS; declare const index_d$4_CURRENCY_MAP: typeof CURRENCY_MAP; type index_d$4_Claims = Claims; type index_d$4_ClaimsCache = ClaimsCache; declare const index_d$4_ClaimsCache: typeof ClaimsCache; type index_d$4_ClaimsCacheOptions = ClaimsCacheOptions; type index_d$4_ClaimsCacheResult<T> = ClaimsCacheResult<T>; type index_d$4_CleanupFunction = CleanupFunction; type index_d$4_CompatibilityReport = CompatibilityReport; type index_d$4_ConditionBuilder = ConditionBuilder; declare const index_d$4_ConditionBuilder: typeof ConditionBuilder; type index_d$4_ConsentLevel = ConsentLevel; type index_d$4_CookieInfo = CookieInfo; type index_d$4_CurrencyEntry = CurrencyEntry; declare const index_d$4_DEFAULT_CRUD_TIMEOUT: typeof DEFAULT_CRUD_TIMEOUT; declare const index_d$4_DEFAULT_ERROR_MESSAGES: typeof DEFAULT_ERROR_MESSAGES; declare const index_d$4_DEFAULT_UPLOAD_TIMEOUT: typeof DEFAULT_UPLOAD_TIMEOUT; declare const index_d$4_DEGRADED_AI_API: typeof DEGRADED_AI_API; declare const index_d$4_DEGRADED_AUTH_API: typeof DEGRADED_AUTH_API; declare const index_d$4_DEGRADED_BILLING_API: typeof DEGRADED_BILLING_API; declare const index_d$4_DEGRADED_CRUD_API: typeof DEGRADED_CRUD_API; declare const index_d$4_DEGRADED_OAUTH_API: typeof DEGRADED_OAUTH_API; type index_d$4_DateFormatOptions = DateFormatOptions; type index_d$4_DateFormatPreset = DateFormatPreset; type index_d$4_DoNotDevError = DoNotDevError; declare const index_d$4_DoNotDevError: typeof DoNotDevError; type index_d$4_ErrorHandlerConfig = ErrorHandlerConfig; type index_d$4_ErrorHandlerFunction = ErrorHandlerFunction; type index_d$4_EventEmitter = EventEmitter; declare const index_d$4_EventEmitter: typeof EventEmitter; type index_d$4_EventListener<T = any> = EventListener<T>; declare const index_d$4_FRAMEWORK_FEATURES: typeof FRAMEWORK_FEATURES; type index_d$4_FeatureAvailability = FeatureAvailability; type index_d$4_FeatureSupport = FeatureSupport; type index_d$4_FilterVisibleFieldsOptions = FilterVisibleFieldsOptions; type index_d$4_FrameworkFeature = FrameworkFeature; type index_d$4_GetVisibleFieldsOptions = GetVisibleFieldsOptions; type index_d$4_HandleErrorOptions = HandleErrorOptions; type index_d$4_HybridStorageStrategy = HybridStorageStrategy; declare const index_d$4_HybridStorageStrategy: typeof HybridStorageStrategy; type index_d$4_IStorageManager = IStorageManager; type index_d$4_IntersectionObserverCallback = IntersectionObserverCallback; type index_d$4_IntersectionObserverOptions = IntersectionObserverOptions; type index_d$4_LocalStorageStrategy = LocalStorageStrategy; declare const index_d$4_LocalStorageStrategy: typeof LocalStorageStrategy; type index_d$4_LockoutResult = LockoutResult; declare const index_d$4_OAUTH_STORE_KEYS: typeof OAUTH_STORE_KEYS; type index_d$4_OS = OS; type index_d$4_PlatformInfo = PlatformInfo; type index_d$4_SingletonManager = SingletonManager; declare const index_d$4_SingletonManager: typeof SingletonManager; type index_d$4_StorageError = StorageError; type index_d$4_StorageErrorType = StorageErrorType; type index_d$4_StorageManager = StorageManager; declare const index_d$4_StorageManager: typeof StorageManager; type index_d$4_StorageOptions = StorageOptions; type index_d$4_TokenManager = TokenManager; declare const index_d$4_TokenManager: typeof TokenManager; type index_d$4_TokenManagerOptions = TokenManagerOptions; type index_d$4_ViewportDetectionOptions = ViewportDetectionOptions; type index_d$4_ViewportDetectionResult = ViewportDetectionResult; type index_d$4_ViewportHandler = ViewportHandler; declare const index_d$4_ViewportHandler: typeof ViewportHandler; declare const index_d$4_areFeaturesAvailable: typeof areFeaturesAvailable; declare const index_d$4_canRedirectExternally: typeof canRedirectExternally; declare const index_d$4_captureError: typeof captureError; declare const index_d$4_captureErrorToSentry: typeof captureErrorToSentry; declare const index_d$4_captureMessage: typeof captureMessage; declare const index_d$4_cleanupSentry: typeof cleanupSentry; declare const index_d$4_clearFeatureCache: typeof clearFeatureCache; declare const index_d$4_clearGlobalSingleton: typeof clearGlobalSingleton; declare const index_d$4_clearLocalStorage: typeof clearLocalStorage; declare const index_d$4_clearPartnerCache: typeof clearPartnerCache; declare const index_d$4_commonErrorCodeMappings: typeof commonErrorCodeMappings; declare const index_d$4_compactToISOString: typeof compactToISOString; declare const index_d$4_configureProviders: typeof configureProviders; declare const index_d$4_cooldown: typeof cooldown; declare const index_d$4_createAsyncSingleton: typeof createAsyncSingleton; declare const index_d$4_createErrorHandler: typeof createErrorHandler; declare const index_d$4_createMetadata: typeof createMetadata; declare const index_d$4_createMethodProxy: typeof createMethodProxy; declare const index_d$4_createSingleton: typeof createSingleton; declare const index_d$4_createSingletonWithParams: typeof createSingletonWithParams; declare const index_d$4_createViewportHandler: typeof createViewportHandler; declare const index_d$4_debounce: typeof debounce; declare const index_d$4_debugPlatformDetection: typeof debugPlatformDetection; declare const index_d$4_decryptData: typeof decryptData; declare const index_d$4_delay: typeof delay; declare const index_d$4_deleteCookie: typeof deleteCookie; declare const index_d$4_detectBrowser: typeof detectBrowser; declare const index_d$4_detectErrorSource: typeof detectErrorSource; declare const index_d$4_detectFeatures: typeof detectFeatures; declare const index_d$4_detectPlatform: typeof detectPlatform; declare const index_d$4_detectPlatformInfo: typeof detectPlatformInfo; declare const index_d$4_detectStorageError: typeof detectStorageError; declare const index_d$4_encryptData: typeof encryptData; declare const index_d$4_ensureSpreadable: typeof ensureSpreadable; declare const index_d$4_evaluateCondition: typeof evaluateCondition; declare const index_d$4_evaluateFieldConditions: typeof evaluateFieldConditions; declare const index_d$4_filterVisibleFields: typeof filterVisibleFields; declare const index_d$4_formatCookieList: typeof formatCookieList; declare const index_d$4_formatCurrency: typeof formatCurrency; declare const index_d$4_formatDate: typeof formatDate; declare const index_d$4_formatRelativeTime: typeof formatRelativeTime; declare const index_d$4_generateCodeChallenge: typeof generateCodeChallenge; declare const index_d$4_generateCodeVerifier: typeof generateCodeVerifier; declare const index_d$4_generateCompatibilityReport: typeof generateCompatibilityReport; declare const index_d$4_generateEncryptionKey: typeof generateEncryptionKey; declare const index_d$4_generateFirestoreRuleCondition: typeof generateFirestoreRuleCondition; declare const index_d$4_generatePKCEPair: typeof generatePKCEPair; declare const index_d$4_generateUUID: typeof generateUUID; declare const index_d$4_getActiveCookies: typeof getActiveCookies; declare const index_d$4_getAppShortName: typeof getAppShortName; declare const index_d$4_getAssetsConfig: typeof getAssetsConfig; declare const index_d$4_getAuthDomain: typeof getAuthDomain; declare const index_d$4_getAuthMethod: typeof getAuthMethod; declare const index_d$4_getAuthPartnerConfig: typeof getAuthPartnerConfig; declare const index_d$4_getAuthPartnerIdByFirebaseId: typeof getAuthPartnerIdByFirebaseId; declare const index_d$4_getAvailableFeatures: typeof getAvailableFeatures; declare const index_d$4_getBrowserRecommendations: typeof getBrowserRecommendations; declare const index_d$4_getConditionDependencies: typeof getConditionDependencies; declare const index_d$4_getConfigSection: typeof getConfigSection; declare const index_d$4_getConfigSource: typeof getConfigSource; declare const index_d$4_getCookie: typeof getCookie; declare const index_d$4_getCookieExamples: typeof getCookieExamples; declare const index_d$4_getCookiesByCategory: typeof getCookiesByCategory; declare const index_d$4_getCurrencyLocale: typeof getCurrencyLocale; declare const index_d$4_getCurrencySymbol: typeof getCurrencySymbol; declare const index_d$4_getCurrentOrigin: typeof getCurrentOrigin; declare const index_d$4_getCurrentTimestamp: typeof getCurrentTimestamp; declare const index_d$4_getDndevConfig: typeof getDndevConfig; declare const index_d$4_getEnabledAuthPartners: typeof getEnabledAuthPartners; declare const index_d$4_getEnabledOAuthPartners: typeof getEnabledOAuthPartners; declare const index_d$4_getEncryptionKey: typeof getEncryptionKey; declare const index_d$4_getFeatureSummary: typeof getFeatureSummary; declare const index_d$4_getGlobalSingleton: typeof getGlobalSingleton; declare const index_d$4_getI18nConfig: typeof getI18nConfig; declare const index_d$4_getListCardFieldNames: typeof getListCardFieldNames; declare const index_d$4_getLocalStorageItem: typeof getLocalStorageItem; declare const index_d$4_getNextEnvVar: typeof getNextEnvVar; declare const index_d$4_getOAuthClientId: typeof getOAuthClientId; declare const index_d$4_getOAuthPartnerConfig: typeof getOAuthPartnerConfig; declare const index_d$4_getOAuthRedirectUri: typeof getOAuthRedirectUri; declare const index_d$4_getOAuthRedirectUrl: typeof getOAuthRedirectUrl; declare const index_d$4_getPartnerCacheStatus: typeof getPartnerCacheStatus; declare const index_d$4_getPartnerConfig: typeof getPartnerConfig; declare const index_d$4_getPlatformEnvVar: typeof getPlatformEnvVar; declare const index_d$4_getProvider: typeof getProvider; declare const index_d$4_getProviderColor: typeof getProviderColor; declare const index_d$4_getRoleFromClaims: typeof getRoleFromClaims; declare const index_d$4_getRoutesConfig: typeof getRoutesConfig; declare const index_d$4_getStorageManager: typeof getStorageManager; declare const index_d$4_getThemesConfig: typeof getThemesConfig; declare const index_d$4_getTokenManager: typeof getTokenManager; declare const index_d$4_getValidAuthPartnerConfig: typeof getValidAuthPartnerConfig; declare const index_d$4_getValidAuthPartnerIds: typeof getValidAuthPartnerIds; declare const index_d$4_getValidOAuthPartnerConfig: typeof getValidOAuthPartnerConfig; declare const index_d$4_getValidOAuthPartnerIds: typeof getValidOAuthPartnerIds; declare const index_d$4_getVisibleFields: typeof getVisibleFields; declare const index_d$4_getVisibleItems: typeof getVisibleItems; declare const index_d$4_getViteEnvVar: typeof getViteEnvVar; declare const index_d$4_getWeekFromISOString: typeof getWeekFromISOString; declare const index_d$4_globalEmitter: typeof globalEmitter; declare const index_d$4_handleError: typeof handleError; declare const index_d$4_hasOptionalCookies: typeof hasOptionalCookies; declare const index_d$4_hasProvider: typeof hasProvider; declare const index_d$4_hasRestrictedVisibility: typeof hasRestrictedVisibility; declare const index_d$4_hasRoleAccess: typeof hasRoleAccess; declare const index_d$4_hasTierAccess: typeof hasTierAccess; declare const index_d$4_initSentry: typeof initSentry; declare const index_d$4_initializeConfig: typeof initializeConfig; declare const index_d$4_initializePlatformDetection: typeof initializePlatformDetection; declare const index_d$4_isAuthPartnerEnabled: typeof isAuthPartnerEnabled; declare const index_d$4_isClient: typeof isClient; declare const index_d$4_isCompactDateString: typeof isCompactDateString; declare const index_d$4_isConfigAvailable: typeof isConfigAvailable; declare const index_d$4_isDev: typeof isDev; declare const index_d$4_isElementInViewport: typeof isElementInViewport; declare const index_d$4_isEmailVerificationRequired: typeof isEmailVerificationRequired; declare const index_d$4_isExpo: typeof isExpo; declare const index_d$4_isFeatureAvailable: typeof isFeatureAvailable; declare const index_d$4_isFieldVisible: typeof isFieldVisible; declare const index_d$4_isIntersectionObserverSupported: typeof isIntersectionObserverSupported; declare const index_d$4_isLocalStorageAvailable: typeof isLocalStorageAvailable; declare const index_d$4_isNextJs: typeof isNextJs; declare const index_d$4_isOAuthPartnerEnabled: typeof isOAuthPartnerEnabled; declare const index_d$4_isPKCESupported: typeof isPKCESupported; declare const index_d$4_isPlatform: typeof isPlatform; declare const index_d$4_isReactNative: typeof isReactNative; declare const index_d$4_isServer: typeof isServer; declare const index_d$4_isTest: typeof isTest; declare const index_d$4_isVite: typeof isVite; declare const index_d$4_isoToCompactString: typeof isoToCompactString; declare const index_d$4_lazyImport: typeof lazyImport; declare const index_d$4_mapToDoNotDevError: typeof mapToDoNotDevError; declare const index_d$4_maybeTranslate: typeof maybeTranslate; declare const index_d$4_normalizeToISOString: typeof normalizeToISOString; declare const index_d$4_observeElement: typeof observeElement; declare const index_d$4_parseDate: typeof parseDate; declare const index_d$4_parseDateToNoonUTC: typeof parseDateToNoonUTC; declare const index_d$4_redirectToExternalUrl: typeof redirectToExternalUrl; declare const index_d$4_redirectToExternalUrlWithErrorHandling: typeof redirectToExternalUrlWithErrorHandling; declare const index_d$4_removeLocalStorageItem: typeof removeLocalStorageItem; declare const index_d$4_resetProviders: typeof resetProviders; declare const index_d$4_resolveAppConfig: typeof resolveAppConfig; declare const index_d$4_safeLocalStorage: typeof safeLocalStorage; declare const index_d$4_safeSessionStorage: typeof safeSessionStorage; declare const index_d$4_safeValidate: typeof safeValidate; declare const index_d$4_sanitizeHref: typeof sanitizeHref; declare const index_d$4_setCookie: typeof setCookie; declare const index_d$4_setLocalStorageItem: typeof setLocalStorageItem; declare const index_d$4_shouldShowEmailVerification: typeof shouldShowEmailVerification; declare const index_d$4_showNotification: typeof showNotification; declare const index_d$4_supportsFeature: typeof supportsFeature; declare const index_d$4_throttle: typeof throttle; declare const index_d$4_timestampToISOString: typeof timestampToISOString; declare const index_d$4_timingUtils: typeof timingUtils; declare const index_d$4_toDateOnly: typeof toDateOnly; declare const index_d$4_toISOString: typeof toISOString; declare const index_d$4_translateArray: typeof translateArray; declare const index_d$4_translateArrayRange: typeof translateArrayRange; declare const index_d$4_translateArrayWithIndices: typeof translateArrayWithIndices; declare const index_d$4_translateObjectArray: typeof translateObjectArray; declare const index_d$4_updateMetadata: typeof updateMetadata; declare const index_d$4_useSafeContext: typeof useSafeContext; declare const index_d$4_useStorageManager: typeof useStorageManager; declare const index_d$4_validateCodeChallenge: typeof validateCodeChallenge; declare const index_d$4_validateCodeVerifier: typeof validateCodeVerifier; declare const index_d$4_validateWithSchema: typeof validateWithSchema; declare const index_d$4_when: typeof when; declare const index_d$4_withErrorHandling: typeof withErrorHandling; declare const index_d$4_withGracefulDegradation: typeof withGracefulDegradation; declare const index_d$4_withTimeout: typeof withTimeout; declare const index_d$4_wrapAuthError: typeof wrapAuthError; declare const index_d$4_wrapCrudError: typeof wrapCrudError; declare const index_d$4_wrapStorageError: typeof wrapStorageError; declare namespace index_d$4 { export { index_d$4_AUTH_COMPUTED_KEYS as AUTH_COMPUTED_KEYS, index_d$4_AUTH_STORE_KEYS as AUTH_STORE_KEYS, index_d$4_AuthHardening as AuthHardening, index_d$4_BILLING_STORE_KEYS as BILLING_STORE_KEYS, index_d$4_BaseStorageStrategy as BaseStorageStrategy, index_d$4_CONSENT_LEVELS as CONSENT_LEVELS, index_d$4_CURRENCY_MAP as CURRENCY_MAP, index_d$4_ClaimsCache as ClaimsCache, index_d$4_ConditionBuilder as ConditionBuilder, index_d$4_DEFAULT_CRUD_TIMEOUT as DEFAULT_CRUD_TIMEOUT, index_d$4_DEFAULT_ERROR_MESSAGES as DEFAULT_ERROR_MESSAGES, index_d$4_DEFAULT_UPLOAD_TIMEOUT as DEFAULT_UPLOAD_TIMEOUT, index_d$4_DEGRADED_AI_API as DEGRADED_AI_API, index_d$4_DEGRADED_AUTH_API as DEGRADED_AUTH_API, index_d$4_DEGRADED_BILLING_API as DEGRADED_BILLING_API, index_d$4_DEGRADED_CRUD_API as DEGRADED_CRUD_API, index_d$4_DEGRADED_OAUTH_API as DEGRADED_OAUTH_API, index_d$4_DoNotDevError as DoNotDevError, index_d$4_EventEmitter as EventEmitter, index_d$4_FRAMEWORK_FEATURES as FRAMEWORK_FEATURES, index_d$4_HybridStorageStrategy as HybridStorageStrategy, index_d$4_LocalStorageStrategy as LocalStorageStrategy, index_d$4_OAUTH_STORE_KEYS as OAUTH_STORE_KEYS, index_d$4_SingletonManager as SingletonManager, index_d$4_StorageManager as StorageManager, index_d$4_TokenManager as TokenManager, index_d$4_ViewportHandler as ViewportHandler, index_d$4_areFeaturesAvailable as areFeaturesAvailable, index_d$4_canRedirectExternally as canRedirectExternally, index_d$4_captureError as captureError, index_d$4_captureErrorToSentry as captureErrorToSentry, index_d$4_captureMessage as captureMessage, index_d$4_cleanupSentry as cleanupSentry, index_d$4_clearFeatureCache as clearFeatureCache, index_d$4_clearGlobalSingleton as clearGlobalSingleton, index_d$4_clearLocalStorage as clearLocalStorage, index_d$4_clearPartnerCache as clearPartnerCache, index_d$4_commonErrorCodeMappings as commonErrorCodeMappings, index_d$4_compactToISOString as compactToISOString, index_d$4_configureProviders as configureProviders, index_d$4_cooldown as cooldown, index_d$4_createAsyncSingleton as createAsyncSingleton, index_d$4_createErrorHandler as createErrorHandler, index_d$4_createMetadata as createMetadata, index_d$4_createMethodProxy as createMethodProxy, index_d$4_createSingleton as createSingleton, index_d$4_createSingletonWithParams as createSingletonWithParams, index_d$4_createViewportHandler as createViewportHandler, index_d$4_debounce as debounce, index_d$4_debugPlatformDetection as debugPlatformDetection, index_d$4_decryptData as decryptData, index_d$4_delay as delay, index_d$4_deleteCookie as deleteCookie, index_d$4_detectBrowser as detectBrowser, index_d$4_detectErrorSource as detectErrorSource, index_d$4_detectFeatures as detectFeatures, index_d$4_detectPlatform as detectPlatform, index_d$4_detectPlatformInfo as detectPlatformInfo, index_d$4_detectStorageError as detectStorageError, index_d$4_encryptData as encryptData, index_d$4_ensureSpreadable as ensureSpreadable, index_d$4_evaluateCondition as evaluateCondition, index_d$4_evaluateFieldConditions as evaluateFieldConditions, index_d$4_filterVisibleFields as filterVisibleFields, index_d$4_formatCookieList as formatCookieList, index_d$4_formatCurrency as formatCurrency, index_d$4_formatDate as formatDate, index_d$4_formatRelativeTime as formatRelativeTime, index_d$4_generateCodeChallenge as generateCodeChallenge, index_d$4_generateCodeVerifier as generateCodeVerifier, index_d$4_generateCompatibilityReport as generateCompatibilityReport, index_d$4_generateEncryptionKey as generateEncryptionKey, index_d$4_generateFirestoreRuleCondition as generateFirestoreRuleCondition, index_d$4_generatePKCEPair as generatePKCEPair, index_d$4_generateUUID as generateUUID, index_d$4_getActiveCookies as getActiveCookies, index_d$4_getAppShortName as getAppShortName, index_d$4_getAssetsConfig as getAssetsConfig, index_d$4_getAuthDomain as getAuthDomain, index_d$4_getAuthMethod as getAuthMethod, index_d$4_getAuthPartnerConfig as getAuthPartnerConfig, index_d$4_getAuthPartnerIdByFirebaseId as getAuthPartnerIdByFirebaseId, index_d$4_getAvailableFeatures as getAvailableFeatures, index_d$4_getBrowserRecommendations as getBrowserRecommendations, index_d$4_getConditionDependencies as getConditionDependencies, index_d$4_getConfigSection as getConfigSection, index_d$4_getConfigSource as getConfigSource, index_d$4_getCookie as getCookie, index_d$4_getCookieExamples as getCookieExamples, index_d$4_getCookiesByCategory as getCookiesByCategory, index_d$4_getCurrencyLocale as getCurrencyLocale, index_d$4_getCurrencySymbol as getCurrencySymbol, index_d$4_getCurrentOrigin as getCurrentOrigin, index_d$4_getCurrentTimestamp as getCurrentTimestamp, index_d$4_getDndevConfig as getDndevConfig, index_d$4_getEnabledAuthPartners as getEnabledAuthPartners, index_d$4_getEnabledOAuthPartners as getEnabledOAuthPartners, index_d$4_getEncryptionKey as getEncryptionKey, index_d$4_getFeatureSummary as getFeatureSummary, index_d$4_getGlobalSingleton as getGlobalSingleton, index_d$4_getI18nConfig as getI18nConfig, index_d$4_getListCardFieldNames as getListCardFieldNames, index_d$4_getLocalStorageItem as getLocalStorageItem, index_d$4_getNextEnvVar as getNextEnvVar, index_d$4_getOAuthClientId as getOAuthClientId, index_d$4_getOAuthPartnerConfig as getOAuthPartnerConfig, index_d$4_getOAuthRedirectUri as getOAuthRedirectUri, index_d$4_getOAuthRedirectUrl as getOAuthRedirectUrl, index_d$4_getPartnerCacheStatus as getPartnerCacheStatus, index_d$4_getPartnerConfig as getPartnerConfig, index_d$4_getPlatformEnvVar as getPlatformEnvVar, index_d$4_getProvider as getProvider, index_d$4_getProviderColor as getProviderColor, index_d$4_getRoleFromClaims as getRoleFromClaims, index_d$4_getRoutesConfig as getRoutesConfig, index_d$4_getStorageManager as getStorageManager, index_d$4_getThemesConfig as getThemesConfig, index_d$4_getTokenManager as getTokenManager, index_d$4_getValidAuthPartnerConfig as getValidAuthPartnerConfig, index_d$4_getValidAuthPartnerIds as getValidAuthPartnerIds, index_d$4_getValidOAuthPartnerConfig as getValidOAuthPartnerConfig, index_d$4_getValidOAuthPartnerIds as getValidOAuthPartnerIds, index_d$4_getVisibleFields as getVisibleFields, index_d$4_getVisibleItems as getVisibleItems, index_d$4_getViteEnvVar as getViteEnvVar, index_d$4_getWeekFromISOString as getWeekFromISOString, index_d$4_globalEmitter as globalEmitter, index_d$4_handleError as handleError, index_d$4_hasOptionalCookies as hasOptionalCookies, index_d$4_hasProvider as hasProvider, index_d$4_hasRestrictedVisibility as hasRestrictedVisibility, index_d$4_hasRoleAccess as hasRoleAccess, index_d$4_hasTierAccess as hasTierAccess, index_d$4_initSentry as initSentry, index_d$4_initializeConfig as initializeConfig, index_d$4_initializePlatformDetection as initializePlatformDetection, index_d$4_isAuthPartnerEnabled as isAuthPartnerEnabled, index_d$4_isClient as isClient, index_d$4_isCompactDateString as isCompactDateString, index_d$4_isConfigAvailable as isConfigAvailable, index_d$4_isDev as isDev, index_d$4_isElementInViewport as isElementInViewport, index_d$4_isEmailVerificationRequired as isEmailVerificationRequired, index_d$4_isExpo as isExpo, index_d$4_isFeatureAvailable as isFeatureAvailable, index_d$4_isFieldVisible as isFieldVisible, index_d$4_isIntersectionObserverSupported as isIntersectionObserverSupported, index_d$4_isLocalStorageAvailable as isLocalStorageAvailable, index_d$4_isNextJs as isNextJs, index_d$4_isOAuthPartnerEnabled as isOAuthPartnerEnabled, index_d$4_isPKCESupported as isPKCESupported, index_d$4_isPlatform as isPlatform, index_d$4_isReactNative as isReactNative, index_d$4_isServer as isServer, index_d$4_isTest as isTest, index_d$4_isVite as isVite, index_d$4_isoToCompactString as isoToCompactString, index_d$4_lazyImport as lazyImport, index_d$4_mapToDoNotDevError as mapToDoNotDevError, index_d$4_maybeTranslate as maybeTranslate, index_d$4_normalizeToISOString as normalizeToISOString, index_d$4_observeElement as observeElement, index_d$4_parseDate as parseDate, index_d$4_parseDateToNoonUTC as parseDateToNoonUTC, index_d$4_redirectToExternalUrl as redirectToExternalUrl, index_d$4_redirectToExternalUrlWithErrorHandling as redirectToExternalUrlWithErrorHandling, index_d$4_removeLocalStorageItem as removeLocalStorageItem, index_d$4_resetProviders as resetProviders, index_d$4_resolveAppConfig as resolveAppConfig, index_d$4_safeLocalStorage as safeLocalStorage, index_d$4_safeSessionStorage as safeSessionStorage, index_d$4_safeValidate as safeValidate, index_d$4_sanitizeHref as sanitizeHref, index_d$4_setCookie as setCookie, index_d$4_setLocalStorageItem as setLocalStorageItem, index_d$4_shouldShowEmailVerification as shouldShowEmailVerification, index_d$4_showNotification as showNotification, index_d$4_supportsFeature as supportsFeature, index_d$4_throttle as throttle, index_d$4_timestampToISOString as timestampToISOString, index_d$4_timingUtils as timingUtils, index_d$4_toDateOnly as toDateOnly, index_d$4_toISOString as toISOString, index_d$4_translateArray as translateArray, index_d$4_translateArrayRange as translateArrayRange, index_d$4_translateArrayWithIndices as translateArrayWithIndices, index_d$4_translateObjectArray as translateObjectArray, index_d$4_updateMetadata as updateMetadata, index_d$4_useSafeContext as useSafeContext, index_d$4_useStorageManager as useStorageManager, index_d$4_validateCodeChallenge as validateCodeChallenge, index_d$4_validateCodeVerifier as validateCodeVerifier, index_d$4_validateWithSchema as validateWithSchema, index_d$4_when as when, index_d$4_withErrorHandling as withErrorHandling, index_d$4_withGracefulDegradation as withGracefulDegradation, index_d$4_withTimeout as withTimeout, index_d$4_wrapAuthError as wrapAuthError, index_d$4_wrapCrudError as wrapCrudError, index_d$4_wrapStorageError as wrapStorageError }; export type { index_d$4_AuthHardeningConfig as AuthHardeningConfig, index_d$4_AuthUserLike as AuthUserLike, index_d$4_BrowserEngine as BrowserEngine, index_d$4_BrowserInfo as BrowserInfo, index_d$4_BrowserType as BrowserType, index_d$4_Claims as Claims, index_d$4_ClaimsCacheOptions as ClaimsCacheOptions, index_d$4_ClaimsCacheResult as ClaimsCacheResult, index_d$4_CleanupFunction as CleanupFunction, index_d$4_CompatibilityReport as CompatibilityReport, index_d$4_ConsentLevel as ConsentLevel, index_d$4_CookieInfo as CookieInfo, index_d$4_CurrencyEntry as CurrencyEntry, index_d$4_DateFormatOptions as DateFormatOptions, index_d$4_DateFormatPreset as DateFormatPreset, index_d$4_ErrorHandlerConfig as ErrorHandlerConfig, index_d$4_ErrorHandlerFunction as ErrorHandlerFunction, index_d$4_EventListener as EventListener, index_d$4_FeatureAvailability as FeatureAvailability, index_d$4_FeatureSupport as FeatureSupport, index_d$4_FilterVisibleFieldsOptions as FilterVisibleFieldsOptions, index_d$4_FrameworkFeature as FrameworkFeature, index_d$4_GetVisibleFieldsOptions as GetVisibleFieldsOptions, index_d$4_HandleErrorOptions as HandleErrorOptions, index_d$4_IStorageManager as IStorageManager, index_d$4_IntersectionObserverCallback as IntersectionObserverCallback, index_d$4_IntersectionObserverOptions as IntersectionObserverOptions, index_d$4_LockoutResult as LockoutResult, index_d$4_OS as OS, index_d$4_PlatformInfo as PlatformInfo, index_d$4_StorageError as StorageError, index_d$4_StorageErrorType as StorageErrorType, index_d$4_StorageOptions as StorageOptions, index_d$4_TokenManagerOptions as TokenManagerOptions, index_d$4_ViewportDetectionOptions as ViewportDetectionOptions, index_d$4_ViewportDetectionResult as ViewportDetectionResult }; } /** * DoNotDev store interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DoNotDevStore extends BaseStoreActions, BaseStoreState { readonly isReady: boolean; readonly _hasHydrated?: boolean; initialize(data?: Record<string, unknown>): Promise<boolean>; cleanup?(): void; } /** * Configuration for creating a DoNotDev store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface DoNotDevStoreConfig<T> { name: string; createStore: (set: (partial: Partial<T & DoNotDevStore> | ((state: T & DoNotDevStore) => Partial<T & DoNotDevStore>)) => void, get: () => T & DoNotDevStore, api: StoreApi<T & DoNotDevStore>) => T; initialize?: (data?: Record<string, unknown>) => Promise<boolean>; cleanup?: () => void; /** * Optional persist configuration * When provided, store state is persisted to storage * * @since 0.0.1 */ persistOptions?: Omit<PersistOptions<T & DoNotDevStore, Partial<T & DoNotDevStore>>, 'name'> & { /** Storage key name (required) */ name: string; }; } /** * Creates a DoNotDev store with framework conventions * * ## Usage Rules — READ vs CALL * * **Reading state (reactive):** Use selector hooks — component re-renders when value changes. * ```ts * const user = useAuthStore((s) => s.user); // ✅ Reactive state * const isReady = useFormStore((s) => s.isReady); // ✅ Reactive state * ``` * * **Calling actions (imperative):** Use `getState()` — no subscription, stable reference. * ```ts * useEffect(() => { * useFormStore.getState().setIsDirty(formId, true); // ✅ Action via getState * return () => { * useUploadStore.getState().unregisterUpload(id); // ✅ Cleanup via getState * }; * }, [formId]); * ``` * * **NEVER** select actions via hooks or put them in dependency arrays: * ```ts * const setDirty = useFormStore((s) => s.setIsDirty); // ❌ Creates subscription * useEffect(() => { setDirty(id, true); }, [setDirty]); // ❌ Infinite loop risk * * const store = useUploadStore(); // ❌ Entire store = new ref every update * useEffect(() => { ... }, [store]); // ❌ Infinite loop * ``` * * Middleware (devtools, persist) can break action reference stability, * making `getState()` the only safe pattern for imperative store access. * * @remarks * The `Record<string, any>` constraint on `T` is intentional. Using `unknown` instead of `any` * breaks all consumer store definitions because TypeScript's mapped types and index signatures * are incompatible with `unknown` in this position. Specifically, store state types use index * signatures (e.g., `[key: string]: ...`) that require `any` to satisfy the constraint. * This is a known TypeScript limitation — not a code quality issue. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function createDoNotDevStore<T extends Record<string, any>>(config: DoNotDevStoreConfig<T>): UseBoundStore<StoreApi<T & DoNotDevStore>>; /** * Type guard to check if a store is a DoNotDev store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isDoNotDevStore(store: unknown): store is DoNotDevStore; /** * Extract the state type from a DoNotDev store * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type DoNotDevStoreState<T> = T extends (...args: any[]) => infer R ? R extends DoNotDevStore ? R : never : never; /** * Hook for accessing network state * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useNetwork(): { reset: () => void; status: NetworkStatus; isOnline: boolean; isReconnected: boolean; isConnectionLost: boolean; connectionType: NetworkConnectionType; effectiveType: string | undefined; lastChecked: Date; }; /** * Selector hook for network status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useNetworkStatus(): NetworkStatus; /** * Selector hook for online status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useNetworkOnline(): boolean; /** * Selector hook for connection type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useNetworkConnectionType(): NetworkConnectionType; declare function useRateLimit(): { checkLimit: () => boolean; resetLimit: () => void; }; interface AbortControllerState { controllers: Map<string, AbortController>; createController: (key: string) => AbortController; abortController: (key: string) => void; abortAll: () => void; } /** * Abort controller store for managing request cancellation * * **Architecture:** * This store provides centralized management of AbortController instances * for canceling HTTP requests and other async operations. It ensures * proper cleanup and prevents memory leaks from abandoned requests. * * **State Management:** * - `controllers`: Map of active AbortController instances keyed by request ID * - `isReady`: Store initialization state * * **Integration Points:** * - HTTP request cancellation * - Async operation cleanup * - Component unmount handling * - Framework request management * * **Performance Features:** * - Efficient controller management with Map-based storage * - Automatic cleanup of abandoned controllers * - Memory leak prevention * - Zustand optimization for state management * * **SSR Compatibility:** * - Initializes with safe default values * - No client-only dependencies in store definition * - Hydration-safe state transitions * * @example * ```tsx * // Create controller for request * const { createController } = useAbortControllerStore(); * const controller = createController('user-fetch'); * * // Cancel specific request * const { abortController } = useAbortControllerStore(); * abortController('user-fetch'); * * // Cancel all requests * const { abortAll } = useAbortControllerStore(); * abortAll(); * ``` */ declare const useAbortControllerStore: zustand.UseBoundStore<zustand.StoreApi<AbortControllerState & DoNotDevStore>>; /** * Consent store hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useConsentStore: zustand.UseBoundStore<zustand.StoreApi<ConsentAPI & DoNotDevStore>>; declare function useConsent<K extends keyof ConsentAPI>(key: K): ConsentAPI[K]; /** * Hook to check if consent store is ready * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useConsentReady: () => boolean; /** * Hook to get functional consent status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useFunctionalConsent: () => boolean; /** * Hook to get analytics consent status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useAnalyticsConsent: () => boolean; /** * Hook to get marketing consent status * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useMarketingConsent: () => boolean; /** * Hook to check if user has consented * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useHasConsented: () => boolean; /** * Hook for checking feature availability * * Now only checks if feature is available via env vars/package installation. * Consent is separate - only for cookies/tracking (GDPR). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useFeatureConsent(feature: string): boolean; /** * Extended overlay actions interface */ interface ExtendedOverlayActions extends ModalActions, RedirectOverlayActions { /** Open a modal with content */ openModal: (content: ReactNode) => void; /** Close the current modal */ closeModal: () => void; /** Open a sheet */ openSheet: () => void; /** Close the current sheet */ closeSheet: () => void; /** Open the command dialog (GlobalGoTo) with optional initial search value */ openCommandDialog: (initialSearch?: string) => void; /** Close the command dialog (GlobalGoTo) */ closeCommandDialog: () => void; /** Close all overlays (modals, sheets, etc.) */ closeAll: () => void; } /** * Overlay state interface */ interface OverlayState extends ModalState, RedirectOverlayState { /** Whether a sheet is currently open */ isSheetOpen: boolean; /** Whether the command dialog (GlobalSearch) is currently open */ isCommandDialogOpen: boolean; /** Initial search value to pass to command dialog */ commandDialogInitialSearch?: string; } /** * Overlay store for managing all overlay types (modals, sheets, etc.) * * **Architecture:** * This store provides centralized overlay management for the application. * It handles modal state, sheet state, and provides a simple API for * opening and closing overlays throughout the application. * * **State Management:** * - `isOpen`: Whether a modal is currently open * - `content`: The React content to display in the modal * - `isSheetOpen`: Whether a sheet is currently open * - `isCommandDialogOpen`: Whether the command dialog (GlobalGoTo) is currently open * - `isReady`: Store initialization state * * **Integration Points:** * - Modal components that subscribe to this store * - Sheet components that subscribe to this store * - Application components that need to show overlays * - Framework overlay system integration * - Navigation cleanup (automatically closes all overlays) * * **Performance Features:** * - Efficient state updates with minimal re-renders * - Automatic cleanup when overlays are closed * - Zustand optimization for state management * * **SSR Compatibility:** * - Initializes with safe default values * - No client-only dependencies in store definition * - Hydration-safe state transitions * * @example * ```tsx * // Open a modal * const openModal = useOverlayStore((state) => state.openModal); * openModal(<MyModalContent />); * * // Close modal * const closeModal = useOverlayStore((state) => state.closeModal); * closeModal(); * * // Open/close sheet * const isSheetOpen = useOverlayStore((state) => state.isSheetOpen); * const openSheet = useOverlayStore((state) => state.openSheet); * const closeSheet = useOverlayStore((state) => state.closeSheet); * * // Open/close command dialog (GlobalGoTo) * const isCommandDialogOpen = useOverlayStore((state) => state.isCommandDialogOpen); * const openCommandDialog = useOverlayStore((state) => state.openCommandDialog); * const closeCommandDialog = useOverlayStore((state) => state.closeCommandDialog); * * // Close all overlays (useful for navigation cleanup) * const closeAll = useOverlayStore((state) => state.closeAll); * closeAll(); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useOverlayStore: zustand.UseBoundStore<zustand.StoreApi<OverlayState & ExtendedOverlayActions & DoNotDevStore>>; /** * Overlay API type - complete interface for useOverlay * * Maps each property of OverlayState & ExtendedOverlayActions to its value type * for fine-grained selectors. Components only subscribe to the specific property they need. * * @example * ```typescript * // Subscribe only to modal open state * const isOpen = useOverlay('isOpen'); * * // Subscribe only to showRedirectOverlay method * const showRedirectOverlay = useOverlay('showRedirectOverlay'); * * // Subscribe only to redirect overlay state * const isRedirectOverlayOpen = useOverlay('isRedirectOverlayOpen'); * ``` */ type OverlayAPI = OverlayState & ExtendedOverlayActions; /** * Hook for accessing overlay state and actions * Fine-grained selectors - subscribe only to the property you need * * @param key - Property key from OverlayAPI to subscribe to * @returns The value of the requested property * * @example * ```typescript * // Subscribe only to modal open state * const isOpen = useOverlay('isOpen'); * * // Subscribe only to showRedirectOverlay method * const showRedirectOverlay = useOverlay('showRedirectOverlay'); * showRedirectOverlay('stripe-checkout'); * * // Subscribe only to redirect overlay state * const isRedirectOverlayOpen = useOverlay('isRedirectOverlayOpen'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useOverlay<K extends keyof OverlayAPI>(key: K): OverlayAPI[K]; /** * Cached navigation data keyed by auth state * @interface NavigationCache * @since 0.0.1 */ interface NavigationCache { /** All discovered routes (unfiltered) */ allRoutes: NavigationRoute[]; /** Routes filtered by auth state, keyed by cache key */ filteredRoutes: Map<string, NavigationRoute[]>; /** Route groups organized by entity */ routeGroups: Map<string, { label: string; routes: NavigationRoute[]; }>; /** Route manifest metadata */ manifest: Record<string, unknown> | null; /** Last cache update timestamp */ lastUpdated: number; } /** * Navigation store state interface * @interface NavigationState * @since 0.0.1 */ interface NavigationState { /** Cached navigation data */ cache: NavigationCache; /** Favorite route paths (persisted per computer) */ favorites: string[]; /** Recent route paths (persisted per computer, max 8) */ recent: string[]; /** Invalidate cache and force refresh */ invalidateCache: () => void; /** Get all routes without filtering */ getAllRoutes: () => NavigationRoute[]; /** Get routes filtered by auth state with caching */ getFilteredRoutes: (authState: { authenticated: boolean; role: string; }) => NavigationRoute[]; /** Get route groups organized by entity */ getRouteGroups: () => Array<{ label: string; routes: NavigationRoute[]; }>; /** Get route manifest metadata */ getManifest: () => Record<string, unknown> | null; /** Toggle favorite status for a route */ toggleFavorite: (path: string) => void; /** Check if a route is favorited */ isFavorite: (path: string) => boolean; /** Get all favorite route paths */ getFavorites: () => string[]; /** Add route to recent history */ addRecent: (path: string) => void; /** Get recent route paths */ getRecent: () => string[]; /** Update cache data (internal) */ setCacheData: (data: Partial<NavigationCache>) => void; /** Set partial state (internal) */ setState: (partial: Partial<NavigationState>) => void; } /** * Navigation Store * * Provides centralized management of navigation routes with intelligent caching * and auth-based filtering. Integrates with route discovery system and provides * optimized data access for UI components. * * **Key Features:** * - Route discovery integration via globalThis._DNDEV_CONFIG_ * - Automatic filtering of dynamic routes (/:id, /users/:userId) from navigation * - Auth-based route filtering with intelligent caching * - Route grouping by entity/domain for organized menus * - Performance optimization through memoization * - SSR-safe initialization patterns * * **Route Filtering:** * - Dynamic routes (containing `:`) are excluded from navigation menus * - Auth-based filtering applied per user permissions * - Routes cached by auth state key (authenticated-role) * - Groups computed once and reused across components * - Cache invalidation on route discovery changes * * **Performance:** * - Routes cached after first access * - Auth filtering memoized by state key * - Groups computed once at initialization * - Minimal re-renders with Zustand selectors * * @constant * @type {UseBoundStore<StoreApi<NavigationState & DoNotDevStore>>} * @since 0.0.1 * * @example * ```typescript * // Get all routes * const allRoutes = useNavigationStore((state) => state.getAllRoutes()); * * // Get filtered routes by auth * const routes = useNavigationStore((state) => * state.getFilteredRoutes({ authenticated: true, role: 'admin' }) * ); * * // Get route groups * const groups = useNavigationStore((state) => state.getRouteGroups()); * ``` */ declare const useNavigationStore: zustand.UseBoundStore<zustand.StoreApi<NavigationState & DoNotDevStore>>; /** * Network store state interface */ interface NetworkState { status: NetworkStatus; isReconnected: boolean; isConnectionLost: boolean; setStatus: (status: NetworkStatus) => void; setReconnected: () => void; setConnectionLost: () => void; } /** * Network store for DoNotDev framework * * **Architecture:** * This store provides centralized network state management for the application. * It monitors network connectivity, connection quality, and provides real-time * updates about network status changes. * * **State Management:** * - `status`: Current network status including online state and connection type * - `isReconnected`: Whether the connection was recently restored * - `isConnectionLost`: Whether the connection was recently lost * - `isReady`: Store initialization state * * **Integration Points:** * - Network monitoring components * - Offline/online state management * - Connection quality indicators * - Framework network utilities * * **Performance Features:** * - Efficient state updates with minimal re-renders * - Real-time network status monitoring * - Zustand optimization for state management * * **SSR Compatibility:** * - Initializes with safe default values * - No client-only dependencies in store definition * - Hydration-safe state transitions * * @example * ```tsx * // Check network status * const { status, isReconnected } = useNetworkStore(); * * // Monitor connection changes * const { setStatus } = useNetworkStore(); * setStatus({ online: true, connectionType: 'wifi' }); * * // Handle reconnection * const { setReconnected } = useNetworkStore(); * setReconnected(); * ``` */ declare const useNetworkStore: zustand.UseBoundStore<zustand.StoreApi<NetworkState & DoNotDevStore>>; /** * @fileoverview Route Configuration Utilities * @description Utilities for route configuration and metadata. Provides functions for smart defaults, route manifest generation, and route data management. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Route data type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type RouteData = RoutesPluginConfig['mapping'][0]; /** * Route manifest type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type RouteManifest = RoutesPluginConfig['manifest']; /** * Smart defaults for pages without explicit meta configuration * Uses convention-over-configuration approach * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getSmartDefaults(path: string, pageModule: any): Partial<RouteData['meta']>; /** * Merge page meta with smart defaults * Only uses defaults for missing properties * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function resolvePageMeta(path: string, pageModule: any): RouteData['meta']; /** * Determine auth requirements with simple defaults * Default: false (public) - developer must explicitly specify auth requirements * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function resolveAuthConfig(path: string, pageModule: any): RouteData['auth']; /** * Get route data from globals (following i18n pattern) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getRoutes(): RouteData[]; /** * Get route manifest from globals (following i18n pattern) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getRouteManifest(): RouteManifest | null; /** * Get route source from globals * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getRouteSource(): string; /** * Build route path with dynamic parameters * @param basePath - Base path from file structure (e.g., '/blog') * @param params - Route parameters (e.g., ['slug']) * @returns Complete route path (e.g., '/blog/:slug') * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function buildRoutePath(basePath: string, params?: string[]): string; /** * Extract route path from page meta export * @param pageModule - Imported page module * @returns Route path string or undefined * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function extractRoutePath(pageModule: any): string | undefined; /** * Language state interface */ interface LanguageState { /** Current BCP-47 language code */ currentLanguage: string; /** Available languages from config */ availableLanguages: LanguageData[]; /** Whether current language is RTL */ isRTL: boolean; } /** * Language actions interface */ interface LanguageActions { /** Change the current language — validates, syncs i18next, updates DOM */ setLanguage: (lng: string) => Promise<void>; /** Set available languages (called during init) */ setAvailableLanguages: (languages: LanguageData[]) => void; } /** * Language store for managing language state as a first-class zustand concern. * * **Architecture:** * - Bidirectional sync with i18next: store → i18n via setLanguage(), i18n → store via languageChanged listener * - Persist: only `currentLanguage` is persisted (replaces async getUserLanguage/saveUserLanguage flow) * - RTL detection: inlined, no @donotdev/components dependency * - i18n instance: injected via initialize(), stored in module-level closure * * @example * ```tsx * // Fine-grained hook * const currentLanguage = useLanguage('currentLanguage'); * const isRTL = useLanguage('isRTL'); * * // Change language * useLanguageStore.getState().setLanguage('fr'); * * // Check readiness * const isReady = useLanguageReady(); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useLanguageStore: zustand.UseBoundStore<zustand.StoreApi<LanguageState & LanguageActions & DoNotDevStore>>; /** * Language API type — complete interface for useLanguage */ type LanguageAPI = LanguageState & LanguageActions; /** * Hook for accessing language state and actions * Fine-grained selectors — subscribe only to the property you need * * @param key - Property key from LanguageAPI to subscribe to * @returns The value of the requested property * * @example * ```typescript * const currentLanguage = useLanguage('currentLanguage'); * const isRTL = useLanguage('isRTL'); * const setLanguage = useLanguage('setLanguage'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useLanguage<K extends keyof LanguageAPI>(key: K): LanguageAPI[K]; /** * Convenience hook to check if LanguageStore is ready * Consistent with useThemeReady() / useConsentReady() pattern * * @returns true when LanguageStore has finished initialization * * @example * ```tsx * const isReady = useLanguageReady(); * if (!isReady) return <Loading />; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useLanguageReady: () => boolean; /** * Get all available themes from build-time detection * Zero runtime cost - data injected by Vite plugin * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAvailableThemes(): ThemeInfo[]; /** * Get theme names only - derives from getAvailableThemes() * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getAvailableThemeNames(): string[]; /** * Get theme metadata for a given theme name * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getThemeInfo(themeName: string): ThemeInfo | null; /** * Check if a theme is valid * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function isValidTheme(themeName: string): boolean; /** * Apply theme to document with proper dark mode detection * Returns whether the applied theme is dark * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function applyTheme(themeName: string): boolean; /** * Extended theme state with layout and breakpoint management */ interface ExtendedThemeState extends ThemeState { /** Current layout preset - single source of truth */ layoutPreset: LayoutPreset | null; /** App configuration for layout */ layoutApp: AppMetadata | null; /** Loading state for layout operations */ isLayoutLoading: boolean; /** Current breakpoint state */ breakpoint: BreakpointUtils; /** Whether the store is ready to be used by components */ isReady: boolean; /** Game layout title (i18n key) - only used by GameLayout preset */ gameTitle: string | null; /** Game layout subtitle (i18n key) - only used by GameLayout preset */ gameSubtitle: string | null; /** Game layout i18n namespace - only used by GameLayout preset */ gameNamespace: string; /** Current sidebar width in pixels (48-400) */ sidebarWidth: number; /** * Per-route preset override (transient, NOT persisted) * Set by LayoutRoute wrapper on navigation. null = use app default. */ routePresetOverride: LayoutPreset | null; /** * Per-route breadcrumb hide override (transient, NOT persisted) * Set by LayoutRoute wrapper on navigation. false = show breadcrumbs normally. */ routeHideBreadcrumbs: boolean; } /** * Breakpoint actions */ interface BreakpointActions { /** Initialize breakpoint detection (single resize listener) */ _initializeBreakpoints: () => void; /** Update breakpoint state (internal) */ _updateBreakpoint: (breakpoint: Breakpoint, width?: number, height?: number) => void; } /** * Simple layout actions */ interface LayoutActions { /** Initialize layout with preset and app config */ initializeLayout: (preset: LayoutPreset, app?: AppMetadata) => Promise<void>; /** Set the selected layout preset (validates input, keeps current if invalid) */ setLayoutPreset: (preset: string | LayoutPreset) => void; /** Set layout loading state */ setLayoutLoading: (loading: boolean) => void; /** Set the store readiness state */ setReady: (ready: boolean) => void; /** Set game layout title (i18n key) - only used by GameLayout preset */ setGameTitle: (title: string | null) => void; /** Set game layout subtitle (i18n key) - only used by GameLayout preset */ setGameSubtitle: (subtitle: string | null) => void; /** Set game layout i18n namespace - only used by GameLayout preset */ setGameNamespace: (namespace: string) => void; /** Set sidebar width in pixels (48-400) */ setSidebarWidth: (width: number) => void; /** * Set per-route preset override (transient, NOT persisted) * Called by LayoutRoute wrapper on every navigation. * Pass null to clear override and use app default. */ setRoutePresetOverride: (preset: LayoutPreset | null) => void; /** Set per-route breadcrumb hide override (transient) */ setRouteHideBreadcrumbs: (hide: boolean) => void; } /** * Simplified Theme Store - Clean Architecture * * SIMPLIFIED APPROACH: * - Store only stores the current preset name and app config * - CSS file handles all visual styling via [data-layout] selectors * - layoutConfigs.tsx maps presets to components * - DnDevLayout renders components directly * - No complex matrix logic or CSS variable management in JS */ declare const useThemeStore: zustand.UseBoundStore<zustand.StoreApi<ExtendedThemeState & ThemeActions & LayoutActions & BreakpointActions & DoNotDevStore>>; /** * Layout API type - complete interface for useLayout * * Maps all layout-related state and actions for fine-grained selectors. * Components only subscribe to the specific property they need. */ type LayoutAPI = Pick<ExtendedThemeState & LayoutActions, 'layoutPreset' | 'layoutApp' | 'isLayoutLoading' | 'gameTitle' | 'gameSubtitle' | 'gameNamespace' | 'sidebarWidth' | 'routePresetOverride' | 'initializeLayout' | 'setLayoutPreset' | 'setLayoutLoading' | 'setGameTitle' | 'setGameSubtitle' | 'setGameNamespace' | 'setSidebarWidth' | 'setRoutePresetOverride' | 'routeHideBreadcrumbs' | 'setRouteHideBreadcrumbs'>; /** * Hook for accessing layout state and actions * Fine-grained selectors - subscribe only to the property you need * * @param key - Property key from LayoutAPI to subscribe to * @returns The value of the requested property * * @example * ```typescript * // Subscribe only to layout preset * const preset = useLayout('layoutPreset'); * * // Subscribe only to setLayoutPreset method * const setLayoutPreset = useLayout('setLayoutPreset'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useLayout<K extends keyof LayoutAPI>(key: K): LayoutAPI[K]; /** * Breakpoint API type - complete interface for useBreakpoint * * Maps each property of BreakpointUtils to its value type for fine-grained selectors. * Components only subscribe to the specific property they need. * * @example * ```typescript * // Subscribe only to current breakpoint string * const current = useBreakpoint('current'); * * // Subscribe only to width number * const width = useBreakpoint('width'); * * // Subscribe only to isMobile boolean * const isMobile = useBreakpoint('isMobile'); * ``` */ type BreakpointAPI = BreakpointUtils; /** * Hook for accessing breakpoint state * Fine-grained selectors - subscribe only to the property you need * - Next.js SSR: Zustand handles SSR automatically * - Vite CSR: Uses store state (initialized with actual window size) * - Both: Store handles resize updates reactively * * @param key - Property key from BreakpointUtils to subscribe to * @returns The value of the requested property * * @example * ```typescript * // Subscribe only to current breakpoint * const current = useBreakpoint('current'); * * // Subscribe only to isMobile boolean * const isMobile = useBreakpoint('isMobile'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useBreakpoint<K extends keyof BreakpointAPI>(key: K): BreakpointAPI[K]; /** * Theme API type - complete interface for useTheme * * Maps all theme-related state and actions for fine-grained selectors. * Components only subscribe to the specific property they need. */ type ThemeAPI = ThemeState & ThemeActions; /** * Hook for accessing theme state and actions * Fine-grained selectors - subscribe only to the property you need * * @param key - Property key from ThemeAPI to subscribe to * @returns The value of the requested property * * @example * ```typescript * // Subscribe only to current theme * const currentTheme = useTheme('currentTheme'); * * // Subscribe only to isDarkMode * const isDarkMode = useTheme('isDarkMode'); * * // Subscribe only to setTheme method * const setTheme = useTheme('setTheme'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useTheme<K extends keyof ThemeAPI>(key: K): ThemeAPI[K]; /** * Convenience hook to check if ThemeStore is ready * Consistent with useI18nReady() pattern * * @returns true when ThemeStore has finished initialization (themes loaded) * * @example * ```tsx * const isReady = useThemeReady(); * if (!isReady) return <Loading />; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const useThemeReady: () => boolean; /** * @fileoverview Core stores package * @description Zustand stores for DoNotDev framework state management * All stores must be Client Components in Next.js * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map type index_d$3_BreakpointAPI = BreakpointAPI; type index_d$3_DoNotDevStore = DoNotDevStore; type index_d$3_DoNotDevStoreConfig<T> = DoNotDevStoreConfig<T>; type index_d$3_DoNotDevStoreState<T> = DoNotDevStoreState<T>; type index_d$3_LanguageAPI = LanguageAPI; type index_d$3_LayoutAPI = LayoutAPI; type index_d$3_OverlayAPI = OverlayAPI; type index_d$3_RouteData = RouteData; type index_d$3_RouteManifest = RouteManifest; type index_d$3_ThemeAPI = ThemeAPI; declare const index_d$3_applyTheme: typeof applyTheme; declare const index_d$3_buildRoutePath: typeof buildRoutePath; declare const index_d$3_createDoNotDevStore: typeof createDoNotDevStore; declare const index_d$3_extractRoutePath: typeof extractRoutePath; declare const index_d$3_getAvailableThemeNames: typeof getAvailableThemeNames; declare const index_d$3_getAvailableThemes: typeof getAvailableThemes; declare const index_d$3_getRouteManifest: typeof getRouteManifest; declare const index_d$3_getRouteSource: typeof getRouteSource; declare const index_d$3_getRoutes: typeof getRoutes; declare const index_d$3_getSmartDefaults: typeof getSmartDefaults; declare const index_d$3_getThemeInfo: typeof getThemeInfo; declare const index_d$3_isDoNotDevStore: typeof isDoNotDevStore; declare const index_d$3_isValidTheme: typeof isValidTheme; declare const index_d$3_resolveAuthConfig: typeof resolveAuthConfig; declare const index_d$3_resolvePageMeta: typeof resolvePageMeta; declare const index_d$3_useAbortControllerStore: typeof useAbortControllerStore; declare const index_d$3_useAnalyticsConsent: typeof useAnalyticsConsent; declare const index_d$3_useBreakpoint: typeof useBreakpoint; declare const index_d$3_useConsent: typeof useConsent; declare const index_d$3_useConsentReady: typeof useConsentReady; declare const index_d$3_useConsentStore: typeof useConsentStore; declare const index_d$3_useFeatureConsent: typeof useFeatureConsent; declare const index_d$3_useFunctionalConsent: typeof useFunctionalConsent; declare const index_d$3_useHasConsented: typeof useHasConsented; declare const index_d$3_useLanguage: typeof useLanguage; declare const index_d$3_useLanguageReady: typeof useLanguageReady; declare const index_d$3_useLanguageStore: typeof useLanguageStore; declare const index_d$3_useLayout: typeof useLayout; declare const index_d$3_useMarketingConsent: typeof useMarketingConsent; declare const index_d$3_useNavigationStore: typeof useNavigationStore; declare const index_d$3_useNetwork: typeof useNetwork; declare const index_d$3_useNetworkConnectionType: typeof useNetworkConnectionType; declare const index_d$3_useNetworkOnline: typeof useNetworkOnline; declare const index_d$3_useNetworkStatus: typeof useNetworkStatus; declare const index_d$3_useNetworkStore: typeof useNetworkStore; declare const index_d$3_useOverlay: typeof useOverlay; declare const index_d$3_useOverlayStore: typeof useOverlayStore; declare const index_d$3_useRateLimit: typeof useRateLimit; declare const index_d$3_useTheme: typeof useTheme; declare const index_d$3_useThemeReady: typeof useThemeReady; declare const index_d$3_useThemeStore: typeof useThemeStore; declare namespace index_d$3 { export { index_d$3_applyTheme as applyTheme, index_d$3_buildRoutePath as buildRoutePath, index_d$3_createDoNotDevStore as createDoNotDevStore, index_d$3_extractRoutePath as extractRoutePath, index_d$3_getAvailableThemeNames as getAvailableThemeNames, index_d$3_getAvailableThemes as getAvailableThemes, index_d$3_getRouteManifest as getRouteManifest, index_d$3_getRouteSource as getRouteSource, index_d$3_getRoutes as getRoutes, index_d$3_getSmartDefaults as getSmartDefaults, index_d$3_getThemeInfo as getThemeInfo, index_d$3_isDoNotDevStore as isDoNotDevStore, index_d$3_isValidTheme as isValidTheme, index_d$3_resolveAuthConfig as resolveAuthConfig, index_d$3_resolvePageMeta as resolvePageMeta, index_d$3_useAbortControllerStore as useAbortControllerStore, index_d$3_useAnalyticsConsent as useAnalyticsConsent, index_d$3_useBreakpoint as useBreakpoint, index_d$3_useConsent as useConsent, index_d$3_useConsentReady as useConsentReady, index_d$3_useConsentStore as useConsentStore, index_d$3_useFeatureConsent as useFeatureConsent, index_d$3_useFunctionalConsent as useFunctionalConsent, index_d$3_useHasConsented as useHasConsented, index_d$3_useLanguage as useLanguage, index_d$3_useLanguageReady as useLanguageReady, index_d$3_useLanguageStore as useLanguageStore, index_d$3_useLayout as useLayout, index_d$3_useMarketingConsent as useMarketingConsent, index_d$3_useNavigationStore as useNavigationStore, index_d$3_useNetwork as useNetwork, index_d$3_useNetworkConnectionType as useNetworkConnectionType, index_d$3_useNetworkOnline as useNetworkOnline, index_d$3_useNetworkStatus as useNetworkStatus, index_d$3_useNetworkStore as useNetworkStore, index_d$3_useOverlay as useOverlay, index_d$3_useOverlayStore as useOverlayStore, index_d$3_useRateLimit as useRateLimit, index_d$3_useTheme as useTheme, index_d$3_useThemeReady as useThemeReady, index_d$3_useThemeStore as useThemeStore }; export type { index_d$3_BreakpointAPI as BreakpointAPI, index_d$3_DoNotDevStore as DoNotDevStore, index_d$3_DoNotDevStoreConfig as DoNotDevStoreConfig, index_d$3_DoNotDevStoreState as DoNotDevStoreState, index_d$3_LanguageAPI as LanguageAPI, index_d$3_LayoutAPI as LayoutAPI, index_d$3_OverlayAPI as OverlayAPI, index_d$3_RouteData as RouteData, index_d$3_RouteManifest as RouteManifest, index_d$3_ThemeAPI as ThemeAPI }; } /** * @fileoverview Schema enhancement utility * @description Enhances a Valibot schema with additional metadata * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Enhances a Valibot schema with additional metadata. * * @param schema - The base Valibot schema * @param metadata - The metadata to attach * @returns The enhanced schema * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function enhanceSchema<T>(schema: v.BaseSchema<unknown, T, v.BaseIssue<unknown>>, metadata: SchemaMetadata): dndevSchema<T>; /** * @fileoverview Schema type generation utility * @description Creates Valibot schemas via registry - extensible for custom types * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Schema generator function type */ type CustomSchemaGenerator = (field: EntityField<FieldType>) => v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>> | null; /** * Register a schema generator for a field type */ declare function registerSchemaGenerator(type: string, generator: CustomSchemaGenerator): void; /** * Check if a schema generator is registered */ declare function hasCustomSchemaGenerator(type: string): boolean; /** * Get all registered schema types */ declare function getRegisteredSchemaTypes(): string[]; /** * Clear all schema generators (testing) */ declare function clearSchemaGenerators(): void; /** * Schema generators exported for unified registry * These are also auto-registered below for backward compatibility */ declare const textSchema: CustomSchemaGenerator; declare const emailSchema: CustomSchemaGenerator; declare const passwordSchema: CustomSchemaGenerator; declare const urlSchema: CustomSchemaGenerator; declare const numberSchema: CustomSchemaGenerator; declare const booleanSchema: CustomSchemaGenerator; declare const dateSchema: CustomSchemaGenerator; declare const fileSchema: CustomSchemaGenerator; declare const filesSchema: CustomSchemaGenerator; declare const pictureSchema: CustomSchemaGenerator; declare const picturesSchema: CustomSchemaGenerator; declare const geopointSchema: CustomSchemaGenerator; declare const addressSchema: CustomSchemaGenerator; declare const mapSchema: CustomSchemaGenerator; declare const arraySchema: CustomSchemaGenerator; declare const selectSchema: CustomSchemaGenerator; declare const multiselectSchema: CustomSchemaGenerator; declare const referenceSchema: CustomSchemaGenerator; declare const stringSchema: CustomSchemaGenerator; declare const telSchema: CustomSchemaGenerator; declare const ibanSchema: CustomSchemaGenerator; declare const neverSchema: CustomSchemaGenerator; declare const switchSchema: CustomSchemaGenerator; declare const gdprConsentSchema: CustomSchemaGenerator; declare const priceSchema: CustomSchemaGenerator; /** * Get Valibot schema for an entity field * * Priority order: * 1. field.validation?.schema (custom schema defined directly in entity) * 2. Registry lookup (built-in or registered custom types) * 3. Fallback to v.unknown() for unregistered types */ declare function getSchemaType(field: EntityField<FieldType>): v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>>; /** * Recursively validates that all string values that look like potential dates * within an object adhere to the ISO 8601 format (YYYY-MM-DDTHH:mm:ss.sssZ). * * @param data - The object or data structure to validate * @param {string} [currentPath=''] - Internal tracking of the object path for error messages * @throws Error if any string resembling a date is not in the correct ISO format * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateDates(data: Record<string, unknown> | unknown[], currentPath?: string): void; /** * Validates a document against the schema, including uniqueness and custom validations. * @param schema - The enhanced schema. * @param data - The document data. * @param operation - 'create' or 'update'. * @param currentDocId - Optional current document ID for update operations. * @throws DoNotDevError if validation fails. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateDocument<T>(schema: dndevSchema<T>, data: Record<string, unknown>, operation: 'create' | 'update', currentDocId?: string): Promise<void>; /** * @fileoverview Unique field validation utility * @description Validates uniqueness constraints for schema fields * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Registers a validator for uniqueness constraints * * @param validator - The validator implementation * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function registerUniqueConstraintValidator(validator: UniqueConstraintValidator): void; /** * Validates unique fields for a document across environments. * * @param schema - The Valibot schema with metadata. * @param data - The document data. * @param currentDocId - Optional ID of the current document (for updates). * @throws Error if a unique constraint is violated. * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function validateUniqueFields<T>(schema: dndevSchema<T>, data: Record<string, unknown>, currentDocId?: string): Promise<void>; /** * @fileoverview Schema Utilities * @description Common utility functions for working with schemas. Provides helper functions for schema metadata checking and manipulation. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Checks if an object has schema metadata (works with Valibot schemas) * * @param obj - The object to check * @returns Whether the object has schema metadata * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function hasMetadata(obj: unknown): obj is dndevSchema<unknown>; /** * Gets the collection name from a schema * * @param schema - The schema to get the collection name from * @returns The collection name * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getCollectionName(schema: dndevSchema<unknown>): string; /** * @fileoverview The 4 Field Families * @description Every entity in the framework is composed of 4 families * * ## The 4 Families * * ``` * Entity = Technical Fields + Status Field + User Fields (Framework Types or Custom Types) * ``` * * ### Family 1: TECHNICAL_FIELDS (Backend-Generated) * **Members**: `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById` * * **Rules**: * - ✓ Always present (framework adds automatically) * - ✗ Users cannot set (stripped from submissions) * - ✓ Read-only in edit forms * - ✓ Auto-generated by server * * ### Family 2: STATUS_FIELD (Lifecycle Management) * **Member**: `status` * * **Default Values**: `'draft'`, `'available'`, `'deleted'` * * **Rules**: * - ✓ Always present (framework adds) * - ✓ Users must set value * - ✓ Users can add custom values (`'reserved'`, `'sold'`) * - ✗ Cannot remove default values * - ✓ Draft mode (`status === 'draft'`) relaxes validation * * ### Family 3: FRAMEWORK_TYPES (~30 Built-in) * **Available Types**: * - Text: `text`, `textarea`, `email`, `tel`, `url`, `password` * - Numbers: `number`, `range` * - Dates: `date`, `datetime-local`, `time`, `timestamp` * - Choices: `select`, `multiselect`, `radio`, `checkbox`, `combobox`, `switch` * - Media: `image`, `images`, `file` * - Special: `reference`, `geopoint`, `address`, `map` * * ### Family 4: CUSTOM_TYPES (User-Registered) * **What**: Custom field types registered via `registerFieldType()` * * **Examples**: `repairOperations`, `ratp`, custom widgets * * ## Complete Example * * ```typescript * import { defineEntity } from '@donotdev/core'; * import { registerFieldType } from '@donotdev/crud'; * * // Register custom type (Family 4) * registerFieldType('repairOperations', { * schema: (field) => v.array(v.object({ operation: v.string(), cost: v.number() })), * component: RepairOperationsField * }); * * // Define entity * const carEntity = defineEntity({ * name: 'Car', * collection: 'cars', * fields: { * // User fields using FRAMEWORK_TYPES (Family 3) * make: { type: 'text', validation: { required: true } }, * year: { type: 'number' }, * images: { type: 'images' }, * fuelType: { type: 'select', validation: { options: [...] } }, * * // User field using CUSTOM_TYPES (Family 4) * repairs: { type: 'repairOperations', visibility: 'admin' }, * * // Extend STATUS_FIELD (Family 2) * status: { * validation: { * options: [ * { value: 'reserved', label: 'Reserved' }, * { value: 'sold', label: 'Sold' } * ] * } * } * * // TECHNICAL_FIELDS (Family 1) auto-added by framework * } * }); * ``` * * **Result**: * - Family 1 (Technical): `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById` * - Family 2 (Status): `status` with `draft/available/deleted/reserved/sold` * - User fields: `make`, `year`, `images`, `fuelType`, `repairs` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Type-safe base fields that all entities inherit * Each field has its specific type for proper TypeScript inference */ interface TypedBaseFields { id: EntityField<'text'>; createdAt: EntityField<'timestamp'>; updatedAt: EntityField<'timestamp'>; createdById: EntityField<'reference'>; updatedById: EntityField<'reference'>; status: EntityField<'select'>; } /** * Default status options for draft/publish/delete workflow * Framework provides 'draft', 'available', 'deleted' - consumers can extend * * Translation fallback order: entity-{name} → crud (never dndev) * - Framework defaults: crud:status.draft, crud:status.available, crud:status.deleted * - User overrides: entity-{name}_*.json files (e.g., entity-inquiry_en.json: "status.draft": "New") * * CRUD is optional and shouldn't pollute core framework (dndev) namespace */ declare const DEFAULT_STATUS_OPTIONS: readonly [{ readonly value: "draft"; readonly label: "crud:status.draft"; }, { readonly value: "available"; readonly label: "crud:status.available"; }, { readonly value: "deleted"; readonly label: "crud:status.deleted"; }]; /** * Default status value for new documents (visible immediately). * Forms use 'draft' explicitly for save-and-finish-later flows. */ declare const DEFAULT_STATUS_VALUE: "available"; /** * Statuses that are hidden from non-admin users */ declare const HIDDEN_STATUSES: readonly ["draft", "deleted"]; /** * Fields that are TRULY backend-generated (cannot be set by user) * These are stripped from create operations - backend creates them automatically * * @category Field Families * @constant BACKEND_GENERATED_FIELD_NAMES */ declare const BACKEND_GENERATED_FIELD_NAMES: readonly ["id", "createdAt", "updatedAt", "createdById", "updatedById"]; /** * List of technical field names that are auto-generated by the backend * Includes backend-generated fields + status field * * These fields are optional in create schemas (backend creates them automatically). * They can be updated in update operations if provided. * * **Note**: Status is included here for visibility/editability logic but is NOT stripped * from form submissions since users MUST set it. Use BACKEND_GENERATED_FIELD_NAMES for stripping. * * @category Field Families * @constant TECHNICAL_FIELD_NAMES */ declare const TECHNICAL_FIELD_NAMES: readonly ["id", "createdAt", "updatedAt", "createdById", "updatedById", "status"]; /** * TypeScript Helper Types for Field Families * @category Field Families */ /** Type for backend-generated field names */ type BackendGeneratedField = (typeof BACKEND_GENERATED_FIELD_NAMES)[number]; /** Type for the status field */ type StatusField = 'status'; /** Type for all technical field names */ type TechnicalField = (typeof TECHNICAL_FIELD_NAMES)[number]; /** * Type guard to check if a field name is a framework-managed field * @param fieldName - Field name to check * @returns True if field is in TECHNICAL_FIELD_NAMES * * @example * ```typescript * if (isFrameworkField('status')) { * // Field is framework-managed (cannot remove) * } * ``` */ declare function isFrameworkField(fieldName: string): fieldName is TechnicalField; /** * Type guard to check if a field is backend-generated * @param fieldName - Field name to check * @returns True if field is auto-generated by backend * * @example * ```typescript * if (isBackendGeneratedField('createdAt')) { * // Field is backend-generated (should be stripped on create) * } * ``` */ declare function isBackendGeneratedField(fieldName: string): fieldName is BackendGeneratedField; declare const baseFields: TypedBaseFields; /** * Defines an entity with validation and default configuration * * Automatically adds technical fields (`id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`) * with `visibility: 'technical'`. User-defined technical fields are merged with defaults, allowing * customization (e.g., `editable: 'admin'`, custom `label`, additional `validation`). * * @param entity - The business entity definition * @returns The validated and configured entity * * @example * ```typescript * export const productEntity = defineEntity({ * name: 'Product', * collection: 'products', * fields: { * name: { * type: 'text', * visibility: 'user', * validation: { required: true, minLength: 3 } * }, * // Customize technical field (optional) * createdAt: { * editable: 'admin', * label: 'Created Date' * } * }, * // Override access defaults (optional) * access: { create: 'guest' } // Public inquiry form * }); * ``` * * **Technical Fields:** * - Automatically added: `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`, `status` * - Default: `visibility: 'technical'`, read-only in edit forms * - Customizable: Can override `editable`, `label`, `hint`, `validation` (merged with defaults) * * **Access Configuration:** * - Defaults: `{ read: 'guest', create: 'admin', update: 'admin', delete: 'admin' }` * - Uses role hierarchy: guest (0) < user (1) < admin (2) < super (3) * - Override individual operations: `access: { create: 'guest' }` for public forms * - Field visibility still applies for sensitive data filtering * * **Status Field (Draft/Publish/Delete):** * - Auto-added with `visibility: 'admin'` and options: `['draft', 'available', 'deleted']` * - Default value: `'available'` (new documents are published by default) * - `draft` and `deleted` statuses hidden from non-admin users (server-side filtering) * - `validation.required` on other fields only enforced when status !== 'draft' * - Extend options: `status: { validation: { options: [{ value: 'sold', label: 'sold' }] } }` * - Hide field: `status: { visibility: 'technical' }` if you don't want it in forms * * **Dropdown Options Format:** * - For `select`, `multiselect`, and `radio` field types, options must be defined in `validation.options` * - Options must be an array of objects with `value` (string) and `label` (string) * - Labels can use i18n keys (e.g., `'entities.product.status.active'`) for translation * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function defineEntity<const F extends Record<string, EntityField>>(entity: Omit<BusinessEntity<F>, 'fields'> & { fields: F; }): Entity<MutableMergedEntityFieldMap<F>>; /** * @fileoverview Unified Schema Generation * @description Creates Valibot schemas from entity definitions with visibility metadata. * * Entity → Schema (with visibility) → Used everywhere (frontend + backend) * * Isomorphic code (works in both client and server environments). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Valibot schema with visibility metadata attached */ interface SchemaWithVisibility extends v.BaseSchema<unknown, unknown, v.BaseIssue<unknown>> { visibility?: Visibility; } /** * Operation-specific schemas generated from entity */ interface OperationSchemas { /** Create: excludes technical fields, enforces required */ create: dndevSchema<unknown>; /** Draft: excludes technical fields, all optional except status='draft' */ draft: dndevSchema<unknown>; /** Update: excludes technical fields, all optional */ update: dndevSchema<unknown>; /** Get: includes all fields with visibility metadata */ get: dndevSchema<unknown>; /** List: optimized for admin table (uses listFields) */ list: dndevSchema<unknown>; /** ListCard: optimized for public cards (uses listCardFields, falls back to listFields) */ listCard: dndevSchema<unknown>; /** Delete: just { id: string } */ delete: dndevSchema<unknown>; } /** * Creates all operation-specific schemas from an entity definition * * Each schema field has `.visibility` attached for backend filtering. * * @param entity - Entity definition * @returns Operation-specific schemas with visibility metadata * * @example * ```typescript * const schemas = createSchemas(carEntity); * // schemas.create - for creating documents * // schemas.draft - for saving incomplete * // schemas.update - for partial updates * // schemas.get - for reading (includes technical fields) * // schemas.list - array of get * // schemas.delete - just { id } * ``` */ declare function createSchemas(entity: AnyEntity): OperationSchemas; /** * @fileoverview Option generation helpers for select fields * @description Simple utilities to generate options arrays for select/dropdown fields. * These are isomorphic and can be used in entity definitions (shared by client and server). * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** Standard option format for select fields */ interface SelectOption { value: string; label: string; } /** * Generates numeric range options for a select field. * * @param start - First number in the range * @param end - Last number in the range * @param step - Increment between numbers (default: 1) * @param descending - Whether to sort descending (default: false) * @returns Array of options with value and label * * @example * ```ts * // Quantities 1-10 * options: rangeOptions(1, 10) * * // Percentages 0-100 by 10 * options: rangeOptions(0, 100, 10) * ``` */ declare function rangeOptions(start: number, end: number, step?: number, descending?: boolean): SelectOption[]; /** * @fileoverview Scope Provider Registry for Multi-Tenancy * @description Global registry for scope providers that supply tenant/company/workspace IDs * to CRUD operations. Apps register providers once, entities declare which provider to use. * * @example * ```typescript * // 1. App registers scope provider (once, at startup) * import { registerScopeProvider } from '@donotdev/core'; * import { useCurrentCompanyStore } from './stores/currentCompanyStore'; * * registerScopeProvider('company', () => * useCurrentCompanyStore.getState().currentCompanyId * ); * * // 2. Entity declares scope * const clientEntity = defineEntity({ * name: 'Client', * collection: 'clients', * scope: { field: 'companyId', provider: 'company' }, * fields: { ... } * }); * * // 3. CRUD operations auto-inject/filter by scope (transparent) * const { add } = useCrud(clientEntity); * await add({ name: 'Acme' }); // companyId auto-injected * ``` * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ /** * Function that returns the current scope ID from app state * Returns null if no scope is currently selected (e.g., no company selected) */ type ScopeProviderFn = () => string | null; /** * Register a scope provider function * * Call this once at app startup to register scope providers. * The provider function should return the current scope ID from your app's state. * * @param name - Provider name (e.g., 'company', 'tenant', 'workspace') * @param provider - Function that returns the current scope ID * * @example * ```typescript * // Using Zustand store * registerScopeProvider('company', () => * useCurrentCompanyStore.getState().currentCompanyId * ); * * // Using React context (via ref) * const companyIdRef = { current: null }; * registerScopeProvider('company', () => companyIdRef.current); * // Update ref in your context provider * ``` * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function registerScopeProvider(name: string, provider: ScopeProviderFn): void; /** * Unregister a scope provider (for testing or cleanup) * * @param name - Provider name to unregister * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function unregisterScopeProvider(name: string): void; /** * Get the current scope value from a registered provider * * Used internally by CRUD operations to inject/filter by scope. * * @param providerName - Name of the registered provider * @returns Current scope ID, or null if not available * * @example * ```typescript * const companyId = getScopeValue('company'); * if (!companyId) { * throw new Error('No company selected'); * } * ``` * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function getScopeValue(providerName: string): string | null; /** * Check if a scope provider is registered * * @param providerName - Name of the provider to check * @returns True if provider is registered * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function hasScopeProvider(providerName: string): boolean; /** * Get all registered scope provider names (for debugging) * * @returns Array of registered provider names * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function getRegisteredScopeProviders(): string[]; /** * Clear all scope providers (for testing) * * @version 0.1.0 * @since 0.0.4 * @author AMBROISE PARK Consulting */ declare function clearScopeProviders(): void; /** * @fileoverview Bulk CRUD wire schemas * @description Valibot schemas for the transactional bulk endpoint * `POST /api/crud/:collection/bulk`. These are on-the-wire validators only — * row shapes are kept opaque (`record<string, unknown>`) because per-entity * validation is performed upstream by the CRUD service against the entity's * generated `create` / `update` schemas. Isomorphic (client + server). * * @version 0.1.0 * @since 0.2.0 * @author AMBROISE PARK Consulting */ /** * Opaque insert row schema. * * The bulk endpoint does not know the entity at parse time; per-field * validation is delegated to the CRUD service using the entity's `create` * schema. We only enforce the structural invariant: each insert is an object. * * @example * import * as v from 'valibot'; * import { BulkInsertSchema } from '@donotdev/schemas'; * * v.parse(BulkInsertSchema, { name: 'Alice', age: 30 }); */ declare const BulkInsertSchema: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; /** * Opaque update row schema: `{ id, patch }`. * * `patch` keeps field-level validation deferred to the entity's `update` * schema, mirroring how single-row `update()` accepts a partial payload. * * @example * import * as v from 'valibot'; * import { BulkUpdateSchema } from '@donotdev/schemas'; * * v.parse(BulkUpdateSchema, { id: 'abc', patch: { name: 'Bob' } }); */ declare const BulkUpdateSchema: v.ObjectSchema<{ readonly id: v.StringSchema<undefined>; readonly patch: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; }, undefined>; /** * Opaque delete-id schema — a single document id. * * @example * import * as v from 'valibot'; * import { BulkDeleteIdSchema } from '@donotdev/schemas'; * * v.parse(BulkDeleteIdSchema, 'doc-123'); */ declare const BulkDeleteIdSchema: v.StringSchema<undefined>; /** * Wire schema for `POST /:collection/bulk` request body. * * All three op arrays are optional so clients can submit any subset. * An empty object `{}` is a valid no-op payload — the service short-circuits * and returns empty arrays without hitting the database. * * Per the bulk contract (see `BULK_CRUD_TODO.md`): * 1. Atomic — all ops succeed or none do. * 2. One round-trip. * 3. Validation up-front (per-entity schemas in CRUD service). * 4. Collision rejection (see `detectBulkCollisions`). * * @example * import * as v from 'valibot'; * import { BulkRequestSchema } from '@donotdev/schemas'; * * const body = v.parse(BulkRequestSchema, { * inserts: [{ name: 'Alice' }], * updates: [{ id: 'a', patch: { name: 'Bob' } }], * deletes: ['c'], * }); */ declare const BulkRequestSchema: v.ObjectSchema<{ readonly inserts: v.OptionalSchema<v.ArraySchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>, undefined>; readonly updates: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{ readonly id: v.StringSchema<undefined>; readonly patch: v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>; }, undefined>, undefined>, undefined>; readonly deletes: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>; }, undefined>; /** * Wire schema for `POST /:collection/bulk` response body. * * Arrays preserve input order so consumers can zip the echoed ids back onto * the client-side op list (e.g. to reconcile optimistic cache entries). * * @example * import * as v from 'valibot'; * import { BulkResponseSchema } from '@donotdev/schemas'; * * const result = v.parse(BulkResponseSchema, { * insertedIds: ['new-1'], * updatedIds: ['a'], * deletedIds: ['c'], * }); */ declare const BulkResponseSchema: v.ObjectSchema<{ readonly insertedIds: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly updatedIds: v.ArraySchema<v.StringSchema<undefined>, undefined>; readonly deletedIds: v.ArraySchema<v.StringSchema<undefined>, undefined>; }, undefined>; /** * Inferred request type for the bulk endpoint. * * @example * import type { BulkRequest } from '@donotdev/schemas'; * * const req: BulkRequest = { deletes: ['a'] }; */ type BulkRequest = v.InferOutput<typeof BulkRequestSchema>; /** * Inferred response type for the bulk endpoint. * * @example * import type { BulkResponse } from '@donotdev/schemas'; * * const res: BulkResponse = { insertedIds: [], updatedIds: [], deletedIds: [] }; */ type BulkResponse = v.InferOutput<typeof BulkResponseSchema>; /** * Report returned by {@link detectBulkCollisions}. * * `where` identifies the first category of collision encountered. `collisions` * lists the offending ids for that category. Callers decide how to surface * this (the CRUD service throws; server handlers return 400). * * @since 0.2.0 */ interface BulkCollisionReport { /** Ids that appear in both collided sets. Empty iff `where === null`. */ collisions: string[]; /** Which pair collided, or `null` when no collision was found. */ where: 'updates-deletes' | 'inserts-updates' | null; } /** * Detects id collisions that must reject a bulk op before any write. * * Separated from the Valibot parse so the wire schema stays purely structural * and callers can surface a precise error (which ids, which pair). Pure, no * side effects — the caller throws. * * Collision rules (see `BULK_CRUD_TODO.md` §7): * - Same id in `updates` and `deletes` → ambiguous intent, reject. * - Same id in `inserts` (if the client supplies an explicit `id`) and * `updates` → ambiguous intent, reject. * - Inserts without an explicit id never collide (server mints the id). * * Checks run in order: `updates-deletes` first, then `inserts-updates`. The * first collision found short-circuits — one clear error per request. * * @param ops - The bulk ops to inspect. All three arrays are optional. * @returns A report; `where === null` means no collision. * * @example * import { detectBulkCollisions } from '@donotdev/schemas'; * * detectBulkCollisions({ updates: [{ id: 'a', patch: {} }], deletes: ['a'] }); * // => { collisions: ['a'], where: 'updates-deletes' } */ declare function detectBulkCollisions(ops: { inserts?: Array<{ id?: string; [k: string]: unknown; }>; updates?: Array<{ id: string; patch: unknown; }>; deletes?: string[]; }): BulkCollisionReport; /** * @fileoverview Canvas base schemas + catalog + validators * @description Valibot schemas for the two canvas contracts (agent -> canvas * render, canvas -> agent event), plus the process-local widget registry * and the two validation entry points (`validateBlock`, `validateEvent`). * * The catalog is the single trust boundary between untrusted * LLM-originated payloads and the renderer. Unknown kinds, missing * actions, and schema mismatches are all reported as `{ ok: false }`; * callers never receive malformed data. * * This file is isomorphic (no React). The React host + component * registration helpers live in `@donotdev/canvas`. * * @version 0.1.0 * @since 0.1.0 * @author AMBROISE PARK Consulting */ /** * Box-proxied image URL. Covers, avatars, thumbnails — every image in a * canvas widget MUST resolve through the box proxy. * * Accepted forms: * - `/proxy/...` — absolute proxy path on the same origin. * - `data:image/...` — inline data URI (agent-generated thumbnails). */ declare const ProxiedImageUrlSchema: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.CheckAction<string, "Image URL must be box-proxied (/proxy/...) or an inline data:image URI.">]>; declare const CanvasLifetimeSchema: v.PicklistSchema<["ephemeral", "session", "persistent"], undefined>; declare const CanvasWidgetMetadataSchema: v.ObjectSchema<{ readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly pinnable: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly preferredHeight: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>; }, undefined>; declare const CanvasBlockSchema: v.ObjectSchema<{ readonly id: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; readonly kind: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; readonly lifetime: v.OptionalSchema<v.PicklistSchema<["ephemeral", "session", "persistent"], undefined>, "ephemeral">; readonly metadata: v.OptionalSchema<v.ObjectSchema<{ readonly title: v.OptionalSchema<v.StringSchema<undefined>, undefined>; readonly pinnable: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>; readonly preferredHeight: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>; }, undefined>, undefined>; readonly payload: v.UnknownSchema; }, undefined>; declare const CanvasEventSchema: v.ObjectSchema<{ readonly widgetId: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; readonly action: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, undefined>]>; readonly payload: v.UnknownSchema; }, undefined>; /** * A widget as it lives in the registry. Widened to accept an arbitrary * component attachment so the UI package can register React components * without this module importing React. */ interface RegisteredWidgetBase<Kind extends string = string, PayloadSchema extends AnyValibotSchema = AnyValibotSchema, Actions extends Record<string, AnyValibotSchema> = Record<string, AnyValibotSchema>> extends WidgetDef<Kind, PayloadSchema, Actions> { readonly component: unknown; } declare function registerWidget(widget: RegisteredWidgetBase): void; declare function getWidget(kind: string): RegisteredWidgetBase | undefined; declare function listWidgets(): readonly RegisteredWidgetBase[]; type ValidateResult<T> = { readonly ok: true; readonly value: T; readonly widget: RegisteredWidgetBase; } | { readonly ok: false; readonly reason: string; }; /** * Validate an incoming canvas block end-to-end: envelope shape, kind is * in the allowlist, payload conforms to the widget's payload schema, and * (optionally) the widget's surface is reachable by the caller's access tier. * * Failure ordering: envelope → kind → payload → surface. Surface-rejection * reasons are prefixed `surface_forbidden: ` so callers can distinguish * policy rejection from schema rejection. */ declare function validateBlock(block: unknown, opts?: ValidateBlockOptions): ValidateResult<CanvasBlock>; declare function validateEvent(event: unknown, widgetKind: string): ValidateResult<CanvasEvent>; /** * @fileoverview Schemas package exports * @description Schema definitions and validation utilities * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map declare const index_d$2_BACKEND_GENERATED_FIELD_NAMES: typeof BACKEND_GENERATED_FIELD_NAMES; type index_d$2_BackendGeneratedField = BackendGeneratedField; type index_d$2_BulkCollisionReport = BulkCollisionReport; declare const index_d$2_BulkDeleteIdSchema: typeof BulkDeleteIdSchema; declare const index_d$2_BulkInsertSchema: typeof BulkInsertSchema; type index_d$2_BulkRequest = BulkRequest; declare const index_d$2_BulkRequestSchema: typeof BulkRequestSchema; type index_d$2_BulkResponse = BulkResponse; declare const index_d$2_BulkResponseSchema: typeof BulkResponseSchema; declare const index_d$2_BulkUpdateSchema: typeof BulkUpdateSchema; declare const index_d$2_CanvasBlockSchema: typeof CanvasBlockSchema; declare const index_d$2_CanvasEventSchema: typeof CanvasEventSchema; declare const index_d$2_CanvasLifetimeSchema: typeof CanvasLifetimeSchema; declare const index_d$2_CanvasWidgetMetadataSchema: typeof CanvasWidgetMetadataSchema; type index_d$2_CustomSchemaGenerator = CustomSchemaGenerator; declare const index_d$2_DEFAULT_STATUS_OPTIONS: typeof DEFAULT_STATUS_OPTIONS; declare const index_d$2_DEFAULT_STATUS_VALUE: typeof DEFAULT_STATUS_VALUE; declare const index_d$2_HIDDEN_STATUSES: typeof HIDDEN_STATUSES; type index_d$2_OperationSchemas = OperationSchemas; declare const index_d$2_ProxiedImageUrlSchema: typeof ProxiedImageUrlSchema; type index_d$2_RegisteredWidgetBase<Kind extends string = string, PayloadSchema extends AnyValibotSchema = AnyValibotSchema, Actions extends Record<string, AnyValibotSchema> = Record<string, AnyValibotSchema>> = RegisteredWidgetBase<Kind, PayloadSchema, Actions>; type index_d$2_SchemaWithVisibility = SchemaWithVisibility; type index_d$2_ScopeProviderFn = ScopeProviderFn; type index_d$2_SelectOption = SelectOption; type index_d$2_StatusField = StatusField; declare const index_d$2_TECHNICAL_FIELD_NAMES: typeof TECHNICAL_FIELD_NAMES; type index_d$2_TechnicalField = TechnicalField; type index_d$2_TypedBaseFields = TypedBaseFields; type index_d$2_ValidateResult<T> = ValidateResult<T>; declare const index_d$2_addressSchema: typeof addressSchema; declare const index_d$2_arraySchema: typeof arraySchema; declare const index_d$2_baseFields: typeof baseFields; declare const index_d$2_booleanSchema: typeof booleanSchema; declare const index_d$2_clearSchemaGenerators: typeof clearSchemaGenerators; declare const index_d$2_clearScopeProviders: typeof clearScopeProviders; declare const index_d$2_createSchemas: typeof createSchemas; declare const index_d$2_dateSchema: typeof dateSchema; declare const index_d$2_defineEntity: typeof defineEntity; declare const index_d$2_detectBulkCollisions: typeof detectBulkCollisions; declare const index_d$2_emailSchema: typeof emailSchema; declare const index_d$2_enhanceSchema: typeof enhanceSchema; declare const index_d$2_fileSchema: typeof fileSchema; declare const index_d$2_filesSchema: typeof filesSchema; declare const index_d$2_gdprConsentSchema: typeof gdprConsentSchema; declare const index_d$2_geopointSchema: typeof geopointSchema; declare const index_d$2_getCollectionName: typeof getCollectionName; declare const index_d$2_getRegisteredSchemaTypes: typeof getRegisteredSchemaTypes; declare const index_d$2_getRegisteredScopeProviders: typeof getRegisteredScopeProviders; declare const index_d$2_getSchemaType: typeof getSchemaType; declare const index_d$2_getScopeValue: typeof getScopeValue; declare const index_d$2_getWidget: typeof getWidget; declare const index_d$2_hasCustomSchemaGenerator: typeof hasCustomSchemaGenerator; declare const index_d$2_hasMetadata: typeof hasMetadata; declare const index_d$2_hasScopeProvider: typeof hasScopeProvider; declare const index_d$2_ibanSchema: typeof ibanSchema; declare const index_d$2_isBackendGeneratedField: typeof isBackendGeneratedField; declare const index_d$2_isFrameworkField: typeof isFrameworkField; declare const index_d$2_listWidgets: typeof listWidgets; declare const index_d$2_mapSchema: typeof mapSchema; declare const index_d$2_multiselectSchema: typeof multiselectSchema; declare const index_d$2_neverSchema: typeof neverSchema; declare const index_d$2_numberSchema: typeof numberSchema; declare const index_d$2_passwordSchema: typeof passwordSchema; declare const index_d$2_pictureSchema: typeof pictureSchema; declare const index_d$2_picturesSchema: typeof picturesSchema; declare const index_d$2_priceSchema: typeof priceSchema; declare const index_d$2_rangeOptions: typeof rangeOptions; declare const index_d$2_referenceSchema: typeof referenceSchema; declare const index_d$2_registerSchemaGenerator: typeof registerSchemaGenerator; declare const index_d$2_registerScopeProvider: typeof registerScopeProvider; declare const index_d$2_registerUniqueConstraintValidator: typeof registerUniqueConstraintValidator; declare const index_d$2_registerWidget: typeof registerWidget; declare const index_d$2_selectSchema: typeof selectSchema; declare const index_d$2_stringSchema: typeof stringSchema; declare const index_d$2_switchSchema: typeof switchSchema; declare const index_d$2_telSchema: typeof telSchema; declare const index_d$2_textSchema: typeof textSchema; declare const index_d$2_unregisterScopeProvider: typeof unregisterScopeProvider; declare const index_d$2_urlSchema: typeof urlSchema; declare const index_d$2_validateBlock: typeof validateBlock; declare const index_d$2_validateDates: typeof validateDates; declare const index_d$2_validateDocument: typeof validateDocument; declare const index_d$2_validateEvent: typeof validateEvent; declare const index_d$2_validateUniqueFields: typeof validateUniqueFields; declare namespace index_d$2 { export { index_d$2_BACKEND_GENERATED_FIELD_NAMES as BACKEND_GENERATED_FIELD_NAMES, index_d$2_BulkDeleteIdSchema as BulkDeleteIdSchema, index_d$2_BulkInsertSchema as BulkInsertSchema, index_d$2_BulkRequestSchema as BulkRequestSchema, index_d$2_BulkResponseSchema as BulkResponseSchema, index_d$2_BulkUpdateSchema as BulkUpdateSchema, index_d$2_CanvasBlockSchema as CanvasBlockSchema, index_d$2_CanvasEventSchema as CanvasEventSchema, index_d$2_CanvasLifetimeSchema as CanvasLifetimeSchema, index_d$2_CanvasWidgetMetadataSchema as CanvasWidgetMetadataSchema, index_d$2_DEFAULT_STATUS_OPTIONS as DEFAULT_STATUS_OPTIONS, index_d$2_DEFAULT_STATUS_VALUE as DEFAULT_STATUS_VALUE, index_d$2_HIDDEN_STATUSES as HIDDEN_STATUSES, index_d$2_ProxiedImageUrlSchema as ProxiedImageUrlSchema, index_d$2_TECHNICAL_FIELD_NAMES as TECHNICAL_FIELD_NAMES, index_d$2_addressSchema as addressSchema, index_d$2_arraySchema as arraySchema, index_d$2_baseFields as baseFields, index_d$2_booleanSchema as booleanSchema, index_d$2_clearSchemaGenerators as clearSchemaGenerators, index_d$2_clearScopeProviders as clearScopeProviders, index_d$2_createSchemas as createSchemas, index_d$2_dateSchema as dateSchema, index_d$2_defineEntity as defineEntity, index_d$2_detectBulkCollisions as detectBulkCollisions, index_d$2_emailSchema as emailSchema, index_d$2_enhanceSchema as enhanceSchema, index_d$2_fileSchema as fileSchema, index_d$2_filesSchema as filesSchema, index_d$2_gdprConsentSchema as gdprConsentSchema, index_d$2_geopointSchema as geopointSchema, index_d$2_getCollectionName as getCollectionName, index_d$2_getRegisteredSchemaTypes as getRegisteredSchemaTypes, index_d$2_getRegisteredScopeProviders as getRegisteredScopeProviders, index_d$2_getSchemaType as getSchemaType, index_d$2_getScopeValue as getScopeValue, index_d$2_getWidget as getWidget, index_d$2_hasCustomSchemaGenerator as hasCustomSchemaGenerator, index_d$2_hasMetadata as hasMetadata, index_d$2_hasScopeProvider as hasScopeProvider, index_d$2_ibanSchema as ibanSchema, index_d$2_isBackendGeneratedField as isBackendGeneratedField, index_d$2_isFrameworkField as isFrameworkField, index_d$2_listWidgets as listWidgets, index_d$2_mapSchema as mapSchema, index_d$2_multiselectSchema as multiselectSchema, index_d$2_neverSchema as neverSchema, index_d$2_numberSchema as numberSchema, index_d$2_passwordSchema as passwordSchema, index_d$2_pictureSchema as pictureSchema, index_d$2_picturesSchema as picturesSchema, index_d$2_priceSchema as priceSchema, index_d$2_rangeOptions as rangeOptions, index_d$2_referenceSchema as referenceSchema, index_d$2_registerSchemaGenerator as registerSchemaGenerator, index_d$2_registerScopeProvider as registerScopeProvider, index_d$2_registerUniqueConstraintValidator as registerUniqueConstraintValidator, index_d$2_registerWidget as registerWidget, index_d$2_selectSchema as selectSchema, index_d$2_stringSchema as stringSchema, index_d$2_switchSchema as switchSchema, index_d$2_telSchema as telSchema, index_d$2_textSchema as textSchema, index_d$2_unregisterScopeProvider as unregisterScopeProvider, index_d$2_urlSchema as urlSchema, index_d$2_validateBlock as validateBlock, index_d$2_validateDates as validateDates, index_d$2_validateDocument as validateDocument, index_d$2_validateEvent as validateEvent, index_d$2_validateUniqueFields as validateUniqueFields }; export type { index_d$2_BackendGeneratedField as BackendGeneratedField, index_d$2_BulkCollisionReport as BulkCollisionReport, index_d$2_BulkRequest as BulkRequest, index_d$2_BulkResponse as BulkResponse, index_d$2_CustomSchemaGenerator as CustomSchemaGenerator, index_d$2_OperationSchemas as OperationSchemas, index_d$2_RegisteredWidgetBase as RegisteredWidgetBase, index_d$2_SchemaWithVisibility as SchemaWithVisibility, index_d$2_ScopeProviderFn as ScopeProviderFn, index_d$2_SelectOption as SelectOption, index_d$2_StatusField as StatusField, index_d$2_TechnicalField as TechnicalField, index_d$2_TypedBaseFields as TypedBaseFields, index_d$2_ValidateResult as ValidateResult }; } /** * @fileoverview React Query client configuration (SSR-safe) * @description QueryClient factory with proper SSR isolation * * **SSR Safety:** * - On server: Creates new QueryClient per request (isolates user data) * - On client: Reuses singleton (preserves cache between navigations) * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Get or create QueryClient (SSR-safe) * * - Server: Always creates new instance (per-request isolation) * - Browser: Reuses singleton (cache persistence) * * @version 0.1.0 * @since 0.0.3 * @author AMBROISE PARK Consulting * * @example * ```tsx * // In your root layout/provider * function Providers({ children }) { * const queryClient = getQueryClient(); * return ( * <QueryClientProvider client={queryClient}> * {children} * </QueryClientProvider> * ); * } * ``` */ declare function getQueryClient(queryConfig?: QueryConfig): QueryClient; /** * Enhanced useQuery hook with framework defaults and error handling * * **Framework Defaults Applied:** * - `staleTime: Infinity` (data never becomes stale - manual refresh only) * - `retry: 1` (one retry attempt on failure) * - `refetchOnWindowFocus: false` (no automatic refetch on focus) * - `refetchOnReconnect: false` (no automatic refetch on reconnect) * * **Error Handling:** * - Errors are automatically wrapped with handleError() * - User-friendly error messages * - Optional notification display * * **SSR Safety:** * - Automatically disables queries on server if `ssr: false` is set * - Preserves SSR behavior by default * * @template TData - Query data type * @template TError - Error type (defaults to Error) * @param options - Query options (framework defaults merged with user options) * @returns Query result with reactive loading states * * @example * ```tsx * const { data, isLoading, error } = useQuery({ * queryKey: ['users', userId], * queryFn: () => fetchUser(userId), * }); * ``` * * @example * ```tsx * // With custom error handling * const { data } = useQuery({ * queryKey: ['users', userId], * queryFn: () => fetchUser(userId), * userMessage: 'Failed to load user', * showNotification: true, * onError: (error) => { * console.error('Custom error handler', error); * }, * }); * ``` * * @example * ```tsx * // Disable SSR for client-only queries * const { data } = useQuery({ * queryKey: ['client-only'], * queryFn: () => fetchClientData(), * ssr: false, // Won't run on server * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseQueryOptionsWithErrorHandling<TData, TError = Error> extends UseQueryOptions<TData, TError> { /** User-friendly error message (optional) */ userMessage?: string; /** Show toast notification on error (default: false) */ showNotification?: boolean; /** Disable query on server (default: false, preserves SSR) */ ssr?: boolean; /** Custom error handler (optional) */ onError?: (error: TError) => void; } declare function useQuery<TData = unknown, TError = Error>(options: UseQueryOptionsWithErrorHandling<TData, TError>): UseQueryResult<TData, TError>; /** * Enhanced useMutation hook with framework defaults and error handling * * **Framework Defaults Applied:** * - `retry: 1` (one retry attempt on failure) * - `retryDelay: exponential backoff` (1s, 2s, 4s, ... max 30s) * * **Error Handling:** * - Errors are automatically wrapped with handleError() * - User-friendly error messages * - Optional notification display * * @template TData - Mutation data type * @template TError - Error type (defaults to Error) * @template TVariables - Variables type * @template TContext - Context type for optimistic updates * @param options - Mutation options (framework defaults merged with user options) * @returns Mutation result with reactive loading states * * @example * ```tsx * const { mutate, isPending, error } = useMutation({ * mutationFn: (data) => createUser(data), * }); * ``` * * @example * ```tsx * // With custom error handling * const { mutate } = useMutation({ * mutationFn: (data) => createUser(data), * userMessage: 'Failed to create user', * showNotification: true, * onError: (error) => { * console.error('Custom error handler', error); * }, * }); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseMutationOptionsWithErrorHandling<TData, TError = Error, TVariables = void, TContext = unknown> extends UseMutationOptions<TData, TError, TVariables, TContext> { /** User-friendly error message (optional) */ userMessage?: string; /** Show toast notification on error (default: false) */ showNotification?: boolean; } declare function useMutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown>(options: UseMutationOptionsWithErrorHandling<TData, TError, TVariables, TContext>): UseMutationResult<TData, TError, TVariables, TContext>; /** * Options for useClickOutside hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseClickOutsideOptions { /** * Event types to listen for * @default ['mousedown', 'touchstart'] */ events?: string[]; /** * Whether the hook is enabled * @default true */ enabled?: boolean; /** * Additional elements to ignore (e.g., triggers) */ ignoreElements?: (Element | null)[]; } /** * Return type for useClickOutside hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseClickOutsideReturn { /** * Ref to attach to the element to monitor */ ref: React.RefObject<HTMLElement | null>; /** * Whether the element is currently being clicked outside */ isClickOutside: boolean; } /** * useClickOutside - Outside Click Detection Hook * * High-performance hook for detecting clicks outside of elements with support * for multiple elements and configurable event types. Perfect for dropdowns, * modals, and popover components. * * @param callback - Function to call when clicking outside * @param options - Configuration options for click outside detection * @returns Object containing ref and click outside state * * @example Basic dropdown * ```tsx * function Dropdown() { * const [isOpen, setIsOpen] = useState(false); * const { ref } = useClickOutside(() => setIsOpen(false)); * * return ( * <div className="relative"> * <button onClick={() => setIsOpen(!isOpen)}> * Toggle * </button> * {isOpen && ( * <div className="absolute top-full left-0 bg-white shadow-lg"> * Dropdown content * </div> * )} * </div> * ); * } * ``` * * @example Modal with outside click * ```tsx * function Modal({ isOpen, onClose, children }) { * const { ref } = useClickOutside(onClose, { * enabled: isOpen * }); * * if (!isOpen) return null; * * return ( * <div className="fixed inset-0 bg-black bg-opacity-50 flex items-center justify-center"> * <div className="bg-white p-6 rounded-lg"> * {children} * </div> * </div> * ); * } * ``` * * @example Multiple elements * ```tsx * function ComplexComponent() { * const [isOpen, setIsOpen] = useState(false); * const triggerRef = useRef<HTMLButtonElement>(null); * const { ref } = useClickOutside(() => setIsOpen(false), { * ignoreElements: [triggerRef.current] * }); * * return ( * <div> * <button ref={triggerRef} onClick={() => setIsOpen(!isOpen)}> * Toggle * </button> * {isOpen && ( * <div className="popover"> * Content * </div> * )} * </div> * ); * } * ``` * * @example Custom events * ```tsx * function CustomEvents() { * const { ref } = useClickOutside(() => console.log('Outside click'), { * events: ['mousedown', 'keydown'], * enabled: true * }); * * return ( * <div> * Click outside or press any key * </div> * ); * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useClickOutside(callback: () => void, options?: UseClickOutsideOptions): UseClickOutsideReturn; /** * Options for useDebounce hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseDebounceOptions<T = any> { /** * Debounce delay in milliseconds * @default 500 */ delay?: number; /** * Whether to execute immediately on first call * @default false */ immediate?: boolean; /** * Initial value for SSR */ initialValue?: T; } /** * useDebounce - Debounced Value Management Hook * * High-performance hook for debouncing values with configurable delay and * immediate execution options. Perfect for search inputs, API calls, and * expensive computations. * * @template T - Type of the value being debounced * @param value - Value to debounce * @param options - Configuration options for debouncing * @returns Debounced value * * @example Search input debouncing * ```tsx * function SearchInput() { * const [query, setQuery] = useState(''); * const debouncedQuery = useDebounce(query, { delay: 300 }); * * useEffect(() => { * if (debouncedQuery) { * // Perform search API call * searchAPI(debouncedQuery); * } * }, [debouncedQuery]); * * return ( * <input * type="text" * value={query} * onChange={(e) => setQuery(e.target.value)} * placeholder="Search..." * /> * ); * } * ``` * * @example API call debouncing * ```tsx * function ApiComponent() { * const [data, setData] = useState(null); * const [loading, setLoading] = useState(false); * const debouncedId = useDebounce(id, { delay: 500 }); * * useEffect(() => { * if (debouncedId) { * setLoading(true); * fetchData(debouncedId).then(setData).finally(() => setLoading(false)); * } * }, [debouncedId]); * * return ( * <div> * {loading && <Spinner />} * {data && <DataDisplay data={data} />} * </div> * ); * } * ``` * * @example Form validation debouncing * ```tsx * function FormInput() { * const [value, setValue] = useState(''); * const [error, setError] = useState(''); * const debouncedValue = useDebounce(value, { delay: 300 }); * * useEffect(() => { * if (debouncedValue) { * validateInput(debouncedValue).then(setError); * } * }, [debouncedValue]); * * return ( * <div> * <input * value={value} * onChange={(e) => setValue(e.target.value)} * className={error ? 'border-red-500' : 'border-gray-300'} * /> * {error && <p className="text-red-500">{error}</p>} * </div> * ); * } * ``` * * @example Immediate execution * ```tsx * function ImmediateDebounce() { * const [value, setValue] = useState(''); * const debouncedValue = useDebounce(value, { * delay: 200, * immediate: true * }); * * // Executes immediately on first call, then debounces * useEffect(() => { * console.log('Value changed:', debouncedValue); * }, [debouncedValue]); * * return ( * <input * value={value} * onChange={(e) => setValue(e.target.value)} * /> * ); * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useDebounce<T>(value: T, options?: UseDebounceOptions): T; /** * Options for useEventListener hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseEventListenerOptions<TTarget extends EventTarget = Window> { /** * Whether the event listener is enabled * @default true */ enabled?: boolean; /** * Event listener options * @default { passive: true } */ options?: AddEventListenerOptions; /** * Element to attach listener to * @default window */ target?: TTarget | null; } /** * Return type for useEventListener hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseEventListenerReturn { /** * Whether the event listener is active */ isActive: boolean; } /** * useEventListener - Enterprise-Grade Event Listener Hook * * Uses React's battle-tested useEffect pattern. * Boring code that just works. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * @param eventType - Type of event to listen for * @param handler - Event handler function * @param options - Configuration options for event listener * @returns Object containing listener state * * @example Basic usage * ```tsx * function WindowEvent() { * const [scrollY, setScrollY] = useState(0); * * useEventListener('scroll', () => { * setScrollY(window.scrollY); * }); * * return <p>Scroll position: {scrollY}px</p>; * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useEventListener<TEvent extends Event = Event, TTarget extends EventTarget = Window>(eventType: string, handler: (event: TEvent) => void, options?: UseEventListenerOptions<TTarget>): UseEventListenerReturn; /** * Options for useIntersectionObserver hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseIntersectionObserverOptions { threshold?: number | number[]; root?: Element | null; rootMargin?: string; once?: boolean; fallbackIntersecting?: boolean; } /** * Return type for useIntersectionObserver hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseIntersectionObserverReturn<T extends Element = Element> { ref: React.RefObject<T | null>; isIntersecting: boolean; hasTriggered: boolean; entry: IntersectionObserverEntry | null; } /** * useIntersectionObserver - Basic Intersection Observation Hook (React 19 Optimized) * * Lightweight hook for basic intersection observation with optimal performance. * Uses React 19's useSyncExternalStore pattern for automatic cleanup, proper * SSR handling, and tearing prevention in concurrent rendering. * * @param options - Configuration options for intersection observation * @returns Object containing ref, isIntersecting state, and entry * * @example Basic intersection detection * ```tsx * function IntersectionComponent() { * const { ref, isIntersecting } = useIntersectionObserver(); * * return ( * <div ref={ref} className={isIntersecting ? 'visible' : 'hidden'}> * Content that appears when intersecting * </div> * ); * } * ``` * * @example With custom threshold * ```tsx * function ThresholdComponent() { * const { ref, isIntersecting } = useIntersectionObserver({ * threshold: 0.5, * rootMargin: '50px' * }); * * return ( * <div ref={ref}> * {isIntersecting ? '50% visible' : 'Not visible enough'} * </div> * ); * } * ``` * * @example Once-only triggering (React 19 optimized) * ```tsx * function OnceComponent() { * const { ref, isIntersecting } = useIntersectionObserver({ once: true }); * * return ( * <div ref={ref}> * {isIntersecting && <ExpensiveComponent />} * </div> * ); * } * ``` * * @example SSR-safe implementation * ```tsx * function SSRComponent() { * const { ref, isIntersecting } = useIntersectionObserver({ * fallbackIntersecting: true // Shows content during SSR * }); * * return ( * <div ref={ref}> * {isIntersecting ? 'Client-side' : 'SSR fallback'} * </div> * ); * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useIntersectionObserver<T extends Element = Element>(options?: UseIntersectionObserverOptions): UseIntersectionObserverReturn<T>; /** * SSR-safe React hook for client detection * Uses useSyncExternalStore to prevent hydration mismatches in Next.js * * Use this in React components instead of isClient() to avoid hydration errors. * For non-React code (stores, utils), use isClient() function from @donotdev/utils. * * @returns boolean indicating if running in browser/client environment * * @example * ```tsx * function MyComponent() { * const isClient = useIsClient(); * if (!isClient) return null; * return <div>Client-only content</div>; * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useIsClient(): boolean; /** * Options for useLocalStorage hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseLocalStorageOptions<T> { /** * Default value for SSR or when key doesn't exist */ defaultValue: T; /** * Whether to sync with other tabs * @default true */ syncAcrossTabs?: boolean; /** * Custom serializer function */ serializer?: { serialize: (value: T) => string; deserialize: (value: string) => T; }; } /** * Return type for useLocalStorage hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseLocalStorageReturn<T> { /** * Current value from localStorage */ value: T; /** * Set value in localStorage */ setValue: (value: T | ((prev: T) => T)) => void; /** * Remove value from localStorage */ removeValue: () => void; /** * Whether the value is loaded from localStorage */ isLoaded: boolean; /** * Whether localStorage is available */ isAvailable: boolean; } /** * useLocalStorage - Local Storage Management Hook * * High-performance hook for managing localStorage with type safety and SSR support. * Perfect for persisting user preferences, settings, and application state. * * @param key - localStorage key * @param options - Configuration options for localStorage management * @returns Object containing value, setters, and status * * @example Basic usage * ```tsx * function Preferences() { * const { value: theme, setValue: setTheme } = useLocalStorage('theme', { * defaultValue: 'light' * }); * * return ( * <div> * <p>Current theme: {theme}</p> * <button onClick={() => setTheme('dark')}> * Switch to dark * </button> * </div> * ); * } * ``` * * @example Complex object storage * ```tsx * function UserSettings() { * const { value: settings, setValue: setSettings } = useLocalStorage('userSettings', { * defaultValue: { * notifications: true, * language: 'en', * fontSize: 14 * } * }); * * const updateSetting = (key: string, value: any) => { * setSettings(prev => ({ ...prev, [key]: value })); * }; * * return ( * <div> * <label> * <input * type="checkbox" * checked={settings.notifications} * onChange={(e) => updateSetting('notifications', e.target.checked)} * /> * Notifications * </label> * </div> * ); * } * ``` * * @example Array storage * ```tsx * function TodoList() { * const { value: todos, setValue: setTodos } = useLocalStorage('todos', { * defaultValue: [] * }); * * const addTodo = (text: string) => { * setTodos(prev => [...prev, { id: Date.now(), text, completed: false }]); * }; * * return ( * <div> * {todos.map(todo => ( * <div key={todo.id}>{todo.text}</div> * ))} * </div> * ); * } * ``` * * @example Custom serializer * ```tsx * function CustomStorage() { * const { value: data, setValue: setData } = useLocalStorage('customData', { * defaultValue: { count: 0 }, * serializer: { * serialize: (value) => btoa(JSON.stringify(value)), * deserialize: (value) => JSON.parse(atob(value)) * } * }); * * return ( * <div> * <p>Count: {data.count}</p> * <button onClick={() => setData(prev => ({ count: prev.count + 1 }))}> * Increment * </button> * </div> * ); * } * ``` * * @example SSR-safe implementation * ```tsx * function SSRComponent() { * const { value: user, setValue: setUser, isLoaded } = useLocalStorage('user', { * defaultValue: null, * syncAcrossTabs: true * }); * * if (!isLoaded) { * return <div>Loading...</div>; * } * * return ( * <div> * {user ? `Welcome ${user.name}` : 'Please login'} * </div> * ); * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useLocalStorage<T>(key: string, options: UseLocalStorageOptions<T>): UseLocalStorageReturn<T>; /** * Options for useScriptLoader hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseScriptLoaderOptions { /** * Whether the script should be loaded * @default true */ enabled?: boolean; /** * Whether to load script immediately or wait for idle * @default false (load immediately) */ loadOnIdle?: boolean; /** * Timeout for script loading in milliseconds * @default 10000 (10 seconds) */ timeout?: number; /** * Whether to retry on failure * @default true */ retry?: boolean; /** * Number of retry attempts * @default 3 */ retryAttempts?: number; /** * Delay between retries in milliseconds * @default 1000 (1 second) */ retryDelay?: number; /** * CSP nonce for script security */ nonce?: string; /** * Script attributes */ attributes?: Record<string, string>; /** * Callback when script loads successfully */ onLoad?: () => void; /** * Callback when script fails to load */ onError?: (error: Error) => void; /** * Whether to check if script is already loaded * @default true */ checkExisting?: boolean; /** * Function to check if script is already available * @default checks for script.src in document */ isLoaded?: () => boolean; /** * Manual loading mode - script only loads when load() is called * @default false (auto-load when enabled) */ manual?: boolean; } /** * Return type for useScriptLoader hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseScriptLoaderReturn { /** * Whether the script is currently loading */ isLoading: boolean; /** * Whether the script has loaded successfully */ isLoaded: boolean; /** * Error if script loading failed */ error: Error | null; /** * Whether the script is ready to use */ isReady: boolean; /** * Manually trigger script loading */ load: () => void; /** * Manually retry loading */ retry: () => void; /** * Reset loading state */ reset: () => void; /** * Whether load() has been called (tracks manual trigger) */ loadTriggered: boolean; } /** * useScriptLoader - External Script Loading Hook * * High-performance hook for loading external scripts with proper error handling, * retry logic, and cleanup. Perfect for loading third-party SDKs like Google, * Stripe, analytics, or any external JavaScript libraries. * * @param src - Script source URL * @param options - Configuration options for script loading * @returns Object containing loading state, error, and control functions * * @example Basic script loading * ```tsx * function GoogleAnalytics() { * const { isLoading, isLoaded, error } = useScriptLoader( * 'https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID' * ); * * if (isLoading) return <div>Loading Google Analytics...</div>; * if (error) return <div>Failed to load: {error.message}</div>; * if (isLoaded) return <div>Google Analytics loaded!</div>; * * return null; * } * ``` * * @example Advanced configuration * ```tsx * function StripeIntegration() { * const { isLoading, isLoaded, error, retry } = useScriptLoader( * 'https://js.stripe.com/v3/', * { * loadOnIdle: true, * retry: true, * retryAttempts: 5, * timeout: 15000, * onLoad: () => console.log('Stripe loaded'), * onError: (error) => console.error('Stripe failed:', error), * attributes: { * 'data-stripe-publishable-key': 'pk_test_...' * } * } * ); * * return ( * <div> * {isLoading && <Spinner />} * {error && ( * <div> * <p>Failed to load Stripe</p> * <button onClick={retry}>Retry</button> * </div> * )} * {isLoaded && <StripeCheckout />} * </div> * ); * } * ``` * * @example Conditional loading * ```tsx * function ConditionalScript() { * const [shouldLoad, setShouldLoad] = useState(false); * * const { isLoading, isLoaded } = useScriptLoader( * 'https://example.com/script.js', * { * enabled: shouldLoad, * loadOnIdle: true * } * ); * * return ( * <div> * <button onClick={() => setShouldLoad(true)}> * Load Script * </button> * {isLoading && <div>Loading...</div>} * {isLoaded && <div>Script ready!</div>} * </div> ); * } * ``` * * @example Custom loaded check * ```tsx * function CustomScript() { * const { isLoaded } = useScriptLoader( * 'https://accounts.google.com/gsi/client', * { * isLoaded: () => !!window.google?.accounts?.id, * onLoad: () => console.log('Google Identity Services ready') * } * ); * * return isLoaded ? <GoogleSignIn /> : <div>Loading Google...</div>; * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useScriptLoader(src: string, options?: UseScriptLoaderOptions): UseScriptLoaderReturn; /** * Options for useViewportVisibility hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseViewportVisibilityOptions { /** * Intersection threshold (0-1) * @default 0.1 */ threshold?: number; /** * Root margin for intersection observer * @default '50px' */ rootMargin?: string; /** * Whether to trigger only once * @default false */ once?: boolean; /** * Whether to track individual items * @default true */ trackItems?: boolean; /** * Whether to enable scroll listener for item tracking * @default true */ enableScrollListener?: boolean; } /** * Return type for useViewportVisibility hook * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseViewportVisibilityReturn { /** * Ref to attach to the container element */ ref: React.RefObject<HTMLDivElement | null>; /** * Whether the container is visible */ isVisible: boolean; /** * Whether the container has been triggered at least once */ hasTriggered: boolean; /** * Set of visible item indices */ visibleItems: Set<number>; /** * Whether a specific item is visible */ isItemVisible: (index: number) => boolean; } /** * useViewportVisibility - Advanced Viewport Detection Hook * * High-performance hook for advanced viewport visibility tracking with item-level detection. * Perfect for complex animations, staggered reveals, and dynamic scroll-based effects. * * @param options - Configuration options for viewport visibility tracking * @returns Object containing ref, visibility state, and item tracking utilities * * @example Staggered animations (Reveal component) * ```tsx * function StaggeredAnimation() { * const { ref, isVisible, visibleItems, isItemVisible } = useViewportVisibility({ * threshold: 0.1, * trackItems: true, * enableScrollListener: true * }); * * return ( * <div> * {items.map((item, index) => ( * <div * key={index} * className={`transition-all duration-500 ${ * isItemVisible(index) ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-4' * }`} * style={{ transitionDelay: `${index * 100}ms` }} * > * {item} * </div> * ))} * </div> * ); * } * ``` * * @example Progressive reveal (StackedCards) * ```tsx * function ProgressiveReveal() { * const { ref, visibleItems } = useViewportVisibility({ * threshold: 0.3, * rootMargin: '-70% 0px -30% 0px', * trackItems: true * }); * * return ( * <div> * {cards.map((card, index) => ( * <div * key={index} * className={`card ${visibleItems.has(index) ? 'revealed' : 'hidden'}`} * > * {card} * </div> * ))} * </div> * ); * } * ``` * * @example Lazy loading with scroll optimization * ```tsx * function LazyLoadSection() { * const { ref, isVisible, visibleItems } = useViewportVisibility({ * threshold: 0.1, * trackItems: true, * enableScrollListener: true, * once: false // Allow re-triggering * }); * * return ( * <div> * {isVisible ? ( * <ExpensiveComponent /> * ) : ( * <div className="h-96 bg-gray-200 dndev-animate-pulse" /> * )} * </div> * ); * } * ``` * * @example Scroll-triggered effects * ```tsx * function ScrollTrigger() { * const { ref, isVisible, visibleItems } = useViewportVisibility({ * threshold: 0.5, * rootMargin: '50px', * trackItems: false, * enableScrollListener: true * }); * * return ( * <div className="scroll-trigger"> * {isVisible && <AnimatedContent />} * </div> * ); * } * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useViewportVisibility(options?: UseViewportVisibilityOptions): UseViewportVisibilityReturn; interface UseBreathingTimerProps { duration: number; onComplete: () => void; } /** * Hook for managing a breathing timer with wake lock support * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useBreathingTimer({ duration, onComplete, }: UseBreathingTimerProps): { status: "active" | "idle" | "paused" | "complete"; timeRemaining: number; start: () => void; togglePause: () => void; restart: () => void; formatTime: (seconds: number) => string; }; /** * QueryProviders - TanStack Query Provider Component * * Wraps your app with TanStack Query (React Query) context. * Provides QueryClient with SSR safety and configurable cache defaults. * * **SSR Safety:** * - Uses getQueryClient() which creates new instance on server per-request * - Reuses singleton on client for cache persistence * * **Configuration:** * - Reads `query` config from `AppConfig` if available * - Applies config to QueryClient defaults * - Config is applied on first call (browser singleton) * * ⚠️ OPTIONAL: Only use this if your app needs CRUD operations * React Query is a large package - don't load it unless needed! * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const QueryProviders: React.ComponentType<{ children: ReactNode; }>; /** * Application configuration context * @internal - Use `useAppConfig()` hook instead of accessing context directly * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const AppConfigContext: react.Context<AppConfig | null>; /** * App config provider props interface * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface AppConfigProviderProps { /** User-provided configuration (merged with smart defaults) */ config?: AppConfig; /** Platform for platform-specific defaults */ platform?: Platform; /** Child components */ children: ReactNode; } /** * AppConfigProvider * * Centralized configuration provider with smart defaults and platform awareness. * Handles all configuration merging in one place - no prop drilling needed. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting * * @example * ```tsx * // Minimal - uses all defaults * <AppConfigProvider platform="vite"> * <App /> * </AppConfigProvider> * * // Partial override * <AppConfigProvider * config={{ app: { name: 'My App' } }} * platform="vite" * > * <App /> * </AppConfigProvider> * ``` */ declare function AppConfigProvider({ config, platform, children, }: AppConfigProviderProps): react_jsx_runtime.JSX.Element; /** * useAppConfig hook * * Access the complete application configuration or a specific property. * * @example * ```tsx * // Get full config * const config = useAppConfig(); * console.log(config.app?.name); * * // Get app metadata object * const app = useAppConfig('app'); * * // Get specific property (shorthand) * const url = useAppConfig('url'); * const name = useAppConfig('name'); * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useAppConfig(): AppConfig; declare function useAppConfig(key: 'app'): AppMetadata | undefined; declare function useAppConfig(key: 'name' | 'shortName' | 'description'): string; /** * useAuthConfig hook * * Access authentication routes with defaults. * * @example * ```tsx * const auth = useAuthConfig(); * navigate(auth.authRoute); // Always has default * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useAuthConfig(): AuthConfig; /** * useSeoConfig hook * * Access SEO configuration. * * @example * ```tsx * const seo = useSeoConfig(); * if (!seo) return null; // Disabled * return <meta property="og:image" content={seo.defaultImage} />; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useSeoConfig(): SEOConfig | false | undefined; /** * useFaviconConfig hook * * Access favicon configuration. * * @example * ```tsx * const favicon = useFaviconConfig(); * if (!favicon) return null; * return <meta name="theme-color" content={favicon.themeColor} />; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useFaviconConfig(): FaviconConfig | false | undefined; /** * useFeaturesConfig hook * * Access feature flags with defaults. * * @example * ```tsx * const features = useFeaturesConfig(); * if (features.debug) return <DebugTools />; * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useFeaturesConfig(): FeaturesConfig; /** * @fileoverview Core hooks package * @description React hooks for DoNotDev framework * All hooks must be Client Components in Next.js * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map declare const index_d$1_AppConfigContext: typeof AppConfigContext; declare const index_d$1_AppConfigProvider: typeof AppConfigProvider; type index_d$1_AppConfigProviderProps = AppConfigProviderProps; declare const index_d$1_MutationOptions: typeof MutationOptions; declare const index_d$1_QueryClient: typeof QueryClient; declare const index_d$1_QueryClientProvider: typeof QueryClientProvider; declare const index_d$1_QueryClientProviderProps: typeof QueryClientProviderProps; declare const index_d$1_QueryFunction: typeof QueryFunction; declare const index_d$1_QueryKey: typeof QueryKey; declare const index_d$1_QueryProviders: typeof QueryProviders; type index_d$1_UseClickOutsideOptions = UseClickOutsideOptions; type index_d$1_UseClickOutsideReturn = UseClickOutsideReturn; type index_d$1_UseDebounceOptions<T = any> = UseDebounceOptions<T>; type index_d$1_UseEventListenerOptions<TTarget extends EventTarget = Window> = UseEventListenerOptions<TTarget>; type index_d$1_UseEventListenerReturn = UseEventListenerReturn; type index_d$1_UseIntersectionObserverOptions = UseIntersectionObserverOptions; type index_d$1_UseIntersectionObserverReturn<T extends Element = Element> = UseIntersectionObserverReturn<T>; type index_d$1_UseLocalStorageOptions<T> = UseLocalStorageOptions<T>; type index_d$1_UseLocalStorageReturn<T> = UseLocalStorageReturn<T>; declare const index_d$1_UseMutationOptions: typeof UseMutationOptions; type index_d$1_UseMutationOptionsWithErrorHandling<TData, TError = Error, TVariables = void, TContext = unknown> = UseMutationOptionsWithErrorHandling<TData, TError, TVariables, TContext>; declare const index_d$1_UseMutationResult: typeof UseMutationResult; declare const index_d$1_UseQueryOptions: typeof UseQueryOptions; type index_d$1_UseQueryOptionsWithErrorHandling<TData, TError = Error> = UseQueryOptionsWithErrorHandling<TData, TError>; declare const index_d$1_UseQueryResult: typeof UseQueryResult; type index_d$1_UseScriptLoaderOptions = UseScriptLoaderOptions; type index_d$1_UseScriptLoaderReturn = UseScriptLoaderReturn; type index_d$1_UseViewportVisibilityOptions = UseViewportVisibilityOptions; type index_d$1_UseViewportVisibilityReturn = UseViewportVisibilityReturn; declare const index_d$1_getQueryClient: typeof getQueryClient; declare const index_d$1_useAppConfig: typeof useAppConfig; declare const index_d$1_useAuthConfig: typeof useAuthConfig; declare const index_d$1_useBreathingTimer: typeof useBreathingTimer; declare const index_d$1_useClickOutside: typeof useClickOutside; declare const index_d$1_useDebounce: typeof useDebounce; declare const index_d$1_useEventListener: typeof useEventListener; declare const index_d$1_useFaviconConfig: typeof useFaviconConfig; declare const index_d$1_useFeaturesConfig: typeof useFeaturesConfig; declare const index_d$1_useIntersectionObserver: typeof useIntersectionObserver; declare const index_d$1_useIsClient: typeof useIsClient; declare const index_d$1_useLocalStorage: typeof useLocalStorage; declare const index_d$1_useMutation: typeof useMutation; declare const index_d$1_useQuery: typeof useQuery; declare const index_d$1_useQueryClient: typeof useQueryClient; declare const index_d$1_useScriptLoader: typeof useScriptLoader; declare const index_d$1_useSeoConfig: typeof useSeoConfig; declare const index_d$1_useViewportVisibility: typeof useViewportVisibility; declare namespace index_d$1 { export { index_d$1_AppConfigContext as AppConfigContext, index_d$1_AppConfigProvider as AppConfigProvider, index_d$1_MutationOptions as MutationOptions, index_d$1_QueryClient as QueryClient, index_d$1_QueryClientProvider as QueryClientProvider, index_d$1_QueryClientProviderProps as QueryClientProviderProps, index_d$1_QueryFunction as QueryFunction, index_d$1_QueryKey as QueryKey, index_d$1_QueryProviders as QueryProviders, index_d$1_UseMutationOptions as UseMutationOptions, index_d$1_UseMutationResult as UseMutationResult, index_d$1_UseQueryOptions as UseQueryOptions, index_d$1_UseQueryResult as UseQueryResult, index_d$1_getQueryClient as getQueryClient, index_d$1_useAppConfig as useAppConfig, index_d$1_useAuthConfig as useAuthConfig, index_d$1_useBreathingTimer as useBreathingTimer, index_d$1_useClickOutside as useClickOutside, index_d$1_useDebounce as useDebounce, index_d$1_useEventListener as useEventListener, index_d$1_useFaviconConfig as useFaviconConfig, index_d$1_useFeaturesConfig as useFeaturesConfig, index_d$1_useIntersectionObserver as useIntersectionObserver, index_d$1_useIsClient as useIsClient, index_d$1_useLocalStorage as useLocalStorage, index_d$1_useMutation as useMutation, index_d$1_useQuery as useQuery, index_d$1_useQueryClient as useQueryClient, index_d$1_useScriptLoader as useScriptLoader, index_d$1_useSeoConfig as useSeoConfig, index_d$1_useViewportVisibility as useViewportVisibility }; export type { index_d$1_AppConfigProviderProps as AppConfigProviderProps, index_d$1_UseClickOutsideOptions as UseClickOutsideOptions, index_d$1_UseClickOutsideReturn as UseClickOutsideReturn, index_d$1_UseDebounceOptions as UseDebounceOptions, index_d$1_UseEventListenerOptions as UseEventListenerOptions, index_d$1_UseEventListenerReturn as UseEventListenerReturn, index_d$1_UseIntersectionObserverOptions as UseIntersectionObserverOptions, index_d$1_UseIntersectionObserverReturn as UseIntersectionObserverReturn, index_d$1_UseLocalStorageOptions as UseLocalStorageOptions, index_d$1_UseLocalStorageReturn as UseLocalStorageReturn, index_d$1_UseMutationOptionsWithErrorHandling as UseMutationOptionsWithErrorHandling, index_d$1_UseQueryOptionsWithErrorHandling as UseQueryOptionsWithErrorHandling, index_d$1_UseScriptLoaderOptions as UseScriptLoaderOptions, index_d$1_UseScriptLoaderReturn as UseScriptLoaderReturn, index_d$1_UseViewportVisibilityOptions as UseViewportVisibilityOptions, index_d$1_UseViewportVisibilityReturn as UseViewportVisibilityReturn }; } /** * Translation hook result interface * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface UseTranslationResult { /** Translation function with interpolation support */ t: TFunction; /** i18next instance for advanced usage */ i18n: any; /** Whether translations are ready for use */ ready: boolean; /** Whether language switching is in progress */ isLoading: boolean; /** Whether i18n system is initializing */ isInitializing: boolean; } /** * Primary translation hook for DoNotDev framework * * **Architecture**: Uses singleton pattern for clean instance management. * The singleton handles all initialization, this hook just provides the translation function. * * **SSR Safety**: Uses useIsClient hook to prevent hydration mismatches in Next.js. * Server always returns fallbacks, client provides actual translations. * * **Performance**: Stable references, minimal re-renders, efficient memoization. * * @param namespace - Translation namespace (defaults to 'dndev' for framework components) * @returns Translation function, i18next instance, and ready state * * @example * ```tsx * // Framework components - use default 'dndev' namespace * const { t } = useTranslation(); * return <button>{t('actions.save')}</button>; // → 'Save' * ``` * * @example * ```tsx * // Application components - specify namespace * const { t } = useTranslation('products'); * return <h1>{t('catalog.title')}</h1>; // → 'Product Catalog' * ``` * * @example * ```tsx * // Interpolation and fallbacks * const { t } = useTranslation('user'); * return ( * <span> * {t('greeting', { name: 'John', defaultValue: 'Hello {{name}}' })} * </span> * ); // → 'Hello John' * ``` * * @example * ```tsx * // Array translations - use indexed access * const { t } = useTranslation('features'); * const benefits = [0, 1, 2] * .map(i => t(`benefits.${i}`)) * .filter(text => text && !text.startsWith('[')); * ``` * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useTranslation(namespace?: string | string[]): UseTranslationResult; /** * Hook to check if i18n is ready for use * Useful for conditional rendering based on translation readiness * * @returns boolean indicating if translations are ready * * @example * ```tsx * function MyComponent() { * const isReady = useI18nReady(); * * if (!isReady) { * return <Skeleton />; * } * * return <TranslatedContent />; * } * ``` * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useI18nReady(): boolean; /** * Creates the i18next instance with all configuration and initialization * Uses the framework's singleton pattern for clean instance management * * HMR-safe: Store instance globally to survive module reloads */ declare const getI18nInstance: () => i18n; //# sourceMappingURL=instance.vite.d.ts.map /** * Props for LanguageSelector component * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LanguageSelectorProps { /** * Display - controls language selector presentation in preset layouts * - 'compact': Icon-only button (dropdown trigger) * - 'full': Flag + language name + ">" (labeled button) * - 'auto': Responsive (default) * @default 'auto' */ display?: (typeof DISPLAY)[keyof typeof DISPLAY]; /** * Button variant for the language selector trigger. * @default 'outline' */ variant?: (typeof BUTTON_VARIANT)[keyof typeof BUTTON_VARIANT]; /** Whether to show flag icons in the selector */ showFlags?: boolean; /** Whether to show language names or just language codes */ showNames?: boolean; /** Additional CSS classes */ className?: string; } /** * Header/nav language selector with dropdown presentation. * * Adapts to the number of available languages: * - **0-1 languages:** Hidden * - **2 languages:** Toggle button (swap on click) * - **3+ languages:** Dropdown menu * * For mobile-first bottom sheet selection, use `LanguageFAB` instead. * * @example * ```tsx * // Basic dropdown (compact) * <LanguageSelector /> * * // Dropdown with flags and names * <LanguageSelector * showFlags={true} * showNames={true} * className="custom-class" * /> * ``` * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const LanguageSelector: ({ display, variant, showFlags, showNames, className, }: LanguageSelectorProps) => react_jsx_runtime.JSX.Element | null; /** * Label format for the pill trigger * @public */ type LanguageFABFormat = 'code' | 'name' | 'native'; /** * Props for LanguageFAB component * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LanguageFABProps { /** Accessibility label for the pill */ 'aria-label'?: string; /** Additional CSS classes */ className?: string; /** Show flag in the pill trigger @default true */ showFlag?: boolean; /** Show flags in the language list @default true */ showFlags?: boolean; /** Pill label format @default 'code' */ format?: LanguageFABFormat; } /** * Fixed floating language pill (top-end) with dropdown selector. * * - **0-1 languages:** Hidden * - **2 languages:** Tapping toggles directly * - **3+ languages:** Dropdown menu * * @example * ```tsx * <LanguageFAB /> * <LanguageFAB format="native" showFlag={false} /> * ``` * * @public */ declare const LanguageFAB: ({ "aria-label": ariaLabel, className, showFlag, showFlags, format, }: LanguageFABProps) => react_jsx_runtime.JSX.Element | null; /** * Orientation for the toggle group * @public */ type ToggleOrientation = 'horizontal' | 'vertical'; /** * Size variants for the toggle group * @public */ type ToggleSize = 'sm' | 'md' | 'lg'; /** * Props for LanguageToggleGroup component * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface LanguageToggleGroupProps { /** Array of language codes to display */ languages?: string[]; /** Orientation of the toggle group */ orientation?: ToggleOrientation; /** Size variant */ size?: ToggleSize; /** Whether to show flag icons */ showFlags?: boolean; /** Whether to show language names or just codes */ showNames?: boolean; /** Additional CSS classes */ className?: string; /** Whether to show loading state */ showLoading?: boolean; /** Custom variant for the toggle buttons */ variant?: 'primary' | 'outline' | 'ghost'; } /** * Inline segmented toggle buttons for language selection. * * Compact button group — each language gets a button, active one is highlighted. * For mobile-first bottom sheet selection, use `LanguageFAB` instead. * * @example * ```tsx * // Basic horizontal toggle * <LanguageToggleGroup * languages={['en', 'es', 'fr']} * orientation="horizontal" * /> * * // Vertical with flags and names * <LanguageToggleGroup * languages={['en', 'es', 'fr', 'de']} * orientation="vertical" * showFlags={true} * showNames={true} * /> * * // Compact header style * <LanguageToggleGroup * languages={['en', 'es']} * variant="ghost" * /> * ``` * * @public */ declare const LanguageToggleGroup: ({ languages, orientation, size, showFlags, showNames, className, showLoading, variant, }: LanguageToggleGroupProps) => react_jsx_runtime.JSX.Element | null; /** Props for the FAQ accordion section with i18n support. */ interface FAQSectionProps { /** Translation function from useTranslation hook */ t: TFunction; /** Base key prefix for the FAQ items (e.g., 'faqs.items') */ keyPrefix: string; /** Maximum number of FAQ items to check (exclusive, so 50 means indices 0-49) */ maxIndex?: number; /** CSS class name for the container */ className?: string; /** CSS class name for each accordion item */ itemClassName?: string; /** ARIA label for the FAQ section */ 'aria-label'?: string; } /** * FAQSection component for displaying frequently asked questions * Handles translations internally using translateObjectArray * * @example * // Basic usage * const { t } = useTranslation(['faq']); * <FAQSection t={t} keyPrefix="faqs.items" maxIndex={30} /> * * @example * // With custom styling * <FAQSection * t={t} * keyPrefix="faqs.items" * maxIndex={30} * className="mx-auto" style={{ maxWidth: '56rem' }} * aria-label="Frequently Asked Questions" * /> */ declare function FAQSection({ t, keyPrefix, maxIndex, className, 'aria-label': ariaLabel, }: FAQSectionProps): react_jsx_runtime.JSX.Element | null; interface TranslatedTextProps { /** Translation key (e.g., 'dashboard.title') */ i18nKey: string; /** Namespace to use (defaults to 'common') */ namespace?: string; /** Fallback text if translation is missing */ fallback?: string; /** Values for interpolation (e.g., { name: 'John' }) */ values?: Record<string, any>; /** HTML element to render (defaults to 'span') */ component?: React.ElementType; /** CSS class name */ className?: string; /** ARIA label for accessibility (overrides translated text) */ 'aria-label'?: string; /** ARIA described-by for accessibility */ 'aria-describedby'?: string; /** ARIA live region for dynamic content */ 'aria-live'?: 'off' | 'polite' | 'assertive'; /** Screen reader only text (hidden visually) */ srOnly?: boolean; /** Additional props passed to the component */ [key: string]: any; } /** * TranslatedText component for dynamic translations * 100% Lighthouse accessibility compliant with proper ARIA support * * @example * // Basic usage * <TranslatedText i18nKey="welcome.message" fallback="Welcome!" /> * * @example * // With accessibility * <TranslatedText * i18nKey="user.greeting" * values={{ name: 'John' }} * fallback="Hello {{name}}" * aria-live="polite" * /> * * @example * // Screen reader only * <TranslatedText * i18nKey="instructions.screen_reader" * fallback="Navigate using arrow keys" * srOnly * /> * * @example * // Interactive elements * <TranslatedText * i18nKey="button.save" * component="button" * aria-label="Save document" * fallback="Save" * /> */ declare function TranslatedText({ i18nKey, namespace, fallback, values, component: Component, className, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, 'aria-live': ariaLive, srOnly, ...props }: TranslatedTextProps): react_jsx_runtime.JSX.Element; /** * Trans component props - extends i18next TransProps */ type DoNotDevTransProps = Omit<TransProps<string>, 'components' | 'ns'> & { /** Namespace - accepts any string */ ns?: string; /** Additional custom components (merged with predefined ones) */ components?: Record<string, ReactElement>; }; /** * Rich text translation component with predefined styling tags. * * Use this instead of `t()` when you need inline styling in translations. * Plain `t()` returns raw string with tags visible as text. * * @example * ```tsx * // Translation: "<accent>MVP</accent> in 2 weeks" * <Trans ns={NAMESPACE} i18nKey="hero.title" /> * * // With custom components * <Trans * ns={NAMESPACE} * i18nKey="hero.title" * components={{ highlight: <mark /> }} * /> * ``` */ declare function Trans({ components, ...props }: DoNotDevTransProps): react_jsx_runtime.JSX.Element; /** * List of available predefined tags for documentation/AI reference */ declare const TRANS_TAGS: readonly ["accent", "primary", "muted", "success", "warning", "error", "bold", "code"]; /** Allowed tag names for the Trans component's rich text interpolation. */ type TransTag = (typeof TRANS_TAGS)[number]; /** * Language selector utility hook * * Provides shared logic for all language selector components including * language list, current language detection, language switching, and * loading state management. * * Uses the zustand language store when initialized, with transparent * fallback to direct i18next access for resilience. * * @returns Language selector state and actions * * @example * ```tsx * const { languages, currentLanguage, changeLanguage, isLoading } = useLanguageSelector(); * * return ( * <select onChange={(e) => changeLanguage(e.target.value)}> * {languages.map(lang => ( * <option key={lang.code} value={lang.code}> * {lang.name} * </option> * ))} * </select> * ); * ``` * * @public * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function useLanguageSelector(): { /** Array of supported languages with code, name, flag, and native name */ languages: LanguageData[]; /** Current active language code */ currentLanguage: any; /** Function to change the current language */ changeLanguage: (lng: string) => Promise<void>; /** Whether a language change is in progress */ isLoading: boolean; /** Selector mode: 'none' (0-1 langs), 'toggle' (2 langs), 'dropdown' (3+ langs) */ mode: string; /** For toggle mode: the inactive language to switch to */ otherLanguage: LanguageData | null; }; /** * Complete language data array with all information * Single source of truth for all language-related data * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare const LANGUAGES: readonly LanguageData[]; /** Country metadata for phone inputs and country selectors. */ type CountryData = { code: string; dialCode: string; flagCode: string; /** Display name for the country in the current UI language */ name: string; }; /** * Get countries from languages that have country codes * Reuses existing language/flag mapping, just adds country code and dial code */ declare function getCountries(): CountryData[]; declare const COUNTRIES: readonly CountryData[]; /** * Language information type * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ type LanguageInfo = LanguageData; /** * Get supported languages with flags and native names * * Returns an array of language objects with id, name, flag emoji, * and native name. Only includes languages that are enabled in config. * * @returns Array of language information objects * * @example * ```tsx * const languages = getSupportedLanguages(); * // Returns: [{ id: 'en', name: 'English', flag: '🇺🇸', nativeName: 'English' }, ...] * ``` * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ declare function getSupportedLanguages(): LanguageInfo[]; /** * @fileoverview Flag Base Component Factory * @description Base component factory and type definitions for creating flag components with consistent sizing and styling. * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ /** * Props for flag base components * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ interface FlagBaseProps { className?: string; style?: React.CSSProperties; title?: string; } declare function Flag({ code, className, style, title, }: { code: string; } & FlagBaseProps): react_jsx_runtime.JSX.Element; declare function getFlagCodes(): string[]; declare function hasFlag(code: string): boolean; /** * @fileoverview i18n package * @description Internationalization utilities and components * * @version 0.1.0 * @since 0.0.1 * @author AMBROISE PARK Consulting */ //# sourceMappingURL=index.d.ts.map declare const index_d_COUNTRIES: typeof COUNTRIES; type index_d_CountryData = CountryData; type index_d_DoNotDevTransProps = DoNotDevTransProps; declare const index_d_FAQSection: typeof FAQSection; type index_d_FAQSectionProps = FAQSectionProps; declare const index_d_Flag: typeof Flag; declare const index_d_LANGUAGES: typeof LANGUAGES; type index_d_LanguageData = LanguageData; declare const index_d_LanguageFAB: typeof LanguageFAB; type index_d_LanguageFABFormat = LanguageFABFormat; type index_d_LanguageFABProps = LanguageFABProps; declare const index_d_LanguageSelector: typeof LanguageSelector; type index_d_LanguageSelectorProps = LanguageSelectorProps; declare const index_d_LanguageToggleGroup: typeof LanguageToggleGroup; type index_d_LanguageToggleGroupProps = LanguageToggleGroupProps; declare const index_d_TRANS_TAGS: typeof TRANS_TAGS; type index_d_ToggleOrientation = ToggleOrientation; type index_d_ToggleSize = ToggleSize; declare const index_d_Trans: typeof Trans; type index_d_TransTag = TransTag; declare const index_d_TranslatedText: typeof TranslatedText; declare const index_d_getCountries: typeof getCountries; declare const index_d_getFlagCodes: typeof getFlagCodes; declare const index_d_getI18nInstance: typeof getI18nInstance; declare const index_d_getSupportedLanguages: typeof getSupportedLanguages; declare const index_d_hasFlag: typeof hasFlag; declare const index_d_useI18nReady: typeof useI18nReady; declare const index_d_useLanguageSelector: typeof useLanguageSelector; declare const index_d_useTranslation: typeof useTranslation; declare namespace index_d { export { index_d_COUNTRIES as COUNTRIES, index_d_FAQSection as FAQSection, index_d_Flag as Flag, index_d_LANGUAGES as LANGUAGES, index_d_LanguageFAB as LanguageFAB, index_d_LanguageSelector as LanguageSelector, index_d_LanguageToggleGroup as LanguageToggleGroup, index_d_TRANS_TAGS as TRANS_TAGS, index_d_Trans as Trans, index_d_TranslatedText as TranslatedText, index_d_getCountries as getCountries, index_d_getFlagCodes as getFlagCodes, index_d_getI18nInstance as getI18nInstance, index_d_getSupportedLanguages as getSupportedLanguages, index_d_hasFlag as hasFlag, index_d_useI18nReady as useI18nReady, index_d_useLanguageSelector as useLanguageSelector, index_d_useTranslation as useTranslation }; export type { index_d_CountryData as CountryData, index_d_DoNotDevTransProps as DoNotDevTransProps, index_d_FAQSectionProps as FAQSectionProps, index_d_LanguageData as LanguageData, index_d_LanguageFABFormat as LanguageFABFormat, index_d_LanguageFABProps as LanguageFABProps, index_d_LanguageSelectorProps as LanguageSelectorProps, index_d_LanguageToggleGroupProps as LanguageToggleGroupProps, index_d_ToggleOrientation as ToggleOrientation, index_d_ToggleSize as ToggleSize, index_d_TransTag as TransTag }; } export { AGGREGATE_FILTER_OPERATORS, AGGREGATE_OPERATIONS, AIChatRequestSchema, AIChatResponseSchema, AIMessageSchema, AIProviderConfigSchema, AIToolCallSchema, AIToolDefinitionSchema, AIUsageSchema, AI_ERROR_CODES, AI_MODELS, AI_PROVIDERS, AI_ROLES, AI_TIERS, AI_TOKEN_PRICING, AUTH_COMPUTED_KEYS, AUTH_EVENTS, AUTH_PARTNERS, AUTH_PARTNER_STATE, AUTH_STORE_KEYS, AppConfigContext, AppConfigProvider, AuthHardening, AuthUserSchema, BACKEND_GENERATED_FIELD_NAMES, BILLING_EVENTS, BILLING_STORE_KEYS, BREAKPOINT_RANGES, BREAKPOINT_THRESHOLDS, BaseStorageStrategy, BulkAcrossCycleError, BulkCollisionError, BulkDeleteIdSchema, BulkInsertSchema, BulkNotImplementedError, BulkRequestSchema, BulkResponseSchema, BulkUpdateSchema, COMMON_TIER_CONFIGS, CONFIDENCE_LEVELS, CONSENT_CATEGORY, CONSENT_LEVELS, CONTEXTS, COUNTRIES, CRUD_OPERATORS, CURRENCY_MAP, CanvasBlockSchema, CanvasEventSchema, CanvasLifetimeSchema, CanvasWidgetMetadataSchema, CheckoutSessionMetadataSchema, ClaimsCache, ConditionBuilder, CreateCheckoutSessionRequestSchema, CreateCheckoutSessionResponseSchema, CustomClaimsSchema, DEFAULT_AI_CONFIG, DEFAULT_AI_MARKUP, DEFAULT_CRUD_TIMEOUT, DEFAULT_ENTITY_ACCESS, DEFAULT_ERROR_MESSAGES, DEFAULT_LAYOUT_PRESET, DEFAULT_STATUS_OPTIONS, DEFAULT_STATUS_VALUE, DEFAULT_SUBSCRIPTION, DEFAULT_UPLOAD_TIMEOUT, DEGRADED_AI_API, DEGRADED_AUTH_API, DEGRADED_BILLING_API, DEGRADED_CRUD_API, DEGRADED_OAUTH_API, DENSITY, DoNotDevError, EDITABLE, EMAIL_ERROR_CODES, EMAIL_PROVIDERS, EMAIL_VERIFICATION_STATUS, ENTITY_HOOK_ERRORS, ENVIRONMENTS, ERROR_CODES, ERROR_SEVERITY, ERROR_SOURCE, EntityHookError, EventEmitter, FAQSection, FEATURES, FEATURE_CONSENT_MATRIX, FEATURE_STATUS, FIELD_TYPES, FIREBASE_ERROR_MAP, FOOTER_MODE, FRAMEWORK_FEATURES, Flag, GITHUB_PERMISSION_LEVELS, HIDDEN_STATUSES, index_d$1 as Hooks, HybridStorageStrategy, index_d as I18n, LANGUAGES, LAYOUT_PRESET, LIST_SCHEMA_TYPE, LanguageFAB, LanguageSelector, LanguageToggleGroup, LocalStorageStrategy, OAUTH_EVENTS, OAUTH_PARTNERS, OAUTH_STORE_KEYS, ORDER_DIRECTION, PARTNER_ICONS, PAYLOAD_EVENTS, PERMISSIONS, PLATFORMS, PWA_ASSET_TYPES, PWA_DISPLAY_MODES, ProductDeclarationSchema, ProductDeclarationsSchema, ProxiedImageUrlSchema, QueryProviders, ROUTE_SOURCES, STORAGE_SCOPES, STORAGE_TYPES, STRIPE_EVENTS, STRIPE_MODES, SUBSCRIPTION_DURATIONS, SUBSCRIPTION_STATUS, SUBSCRIPTION_TIERS, index_d$2 as Schemas, SendEmailRequestSchema, SendEmailResponseSchema, SingletonManager, StorageManager, index_d$3 as Stores, StripeBackConfigSchema, StripeFrontConfigSchema, StripePaymentSchema, StripeSubscriptionSchema, SubscriptionClaimsSchema, SubscriptionDataSchema, TECHNICAL_FIELD_NAMES, TRANS_TAGS, TokenManager, Trans, TranslatedText, index_d$5 as Types, USER_ROLES, UserSubscriptionSchema, index_d$4 as Utils, VISIBILITY, ViewportHandler, WebhookEventSchema, addressSchema, applyTheme, areFeaturesAvailable, arraySchema, baseFields, booleanSchema, buildRoutePath, canRedirectExternally, captureError, captureErrorToSentry, captureMessage, checkGitHubAccessSchema, cleanupSentry, clearFeatureCache, clearGlobalSingleton, clearLocalStorage, clearPartnerCache, clearSchemaGenerators, clearScopeProviders, commonErrorCodeMappings, compactToISOString, configureProviders, cooldown, createAsyncSingleton, createDefaultSubscriptionClaims, createDefaultUserProfile, createDoNotDevStore, createEntitySchema, createErrorHandler, createMetadata, createMethodProxy, createSchemas, createSingleton, createSingletonWithParams, createViewportHandler, dateSchema, debounce, debugPlatformDetection, decryptData, defineEntity, delay, deleteCookie, deleteEntitySchema, detectBrowser, detectBulkCollisions, detectErrorSource, detectFeatures, detectPlatform, detectPlatformInfo, detectStorageError, disconnectOAuthSchema, emailSchema, encryptData, enhanceSchema, ensureSpreadable, evaluateCondition, evaluateFieldConditions, exchangeTokenSchema, extractRoutePath, fileSchema, filesSchema, filterVisibleFields, formatCookieList, formatCurrency, formatDate, formatRelativeTime, gdprConsentSchema, generateCodeChallenge, generateCodeVerifier, generateCompatibilityReport, generateEncryptionKey, generateFirestoreRuleCondition, generatePKCEPair, generateUUID, geopointSchema, getActiveCookies, getAppShortName, getAssetsConfig, getAuthDomain, getAuthMethod, getAuthPartnerConfig, getAuthPartnerIdByFirebaseId, getAvailableFeatures, getAvailableThemeNames, getAvailableThemes, getBreakpointFromWidth, getBreakpointUtils, getBrowserRecommendations, getCollectionName, getConditionDependencies, getConfigSection, getConfigSource, getConnectionsSchema, getCookie, getCookieExamples, getCookiesByCategory, getCountries, getCurrencyLocale, getCurrencySymbol, getCurrentOrigin, getCurrentTimestamp, getDndevConfig, getEnabledAuthPartners, getEnabledOAuthPartners, getEncryptionKey, getEntitySchema, getFeatureSummary, getFlagCodes, getGlobalSingleton, getI18nConfig, getI18nInstance, getListCardFieldNames, getLocalStorageItem, getNextEnvVar, getOAuthClientId, getOAuthPartnerConfig, getOAuthRedirectUri, getOAuthRedirectUrl, getPartnerCacheStatus, getPartnerConfig, getPlatformEnvVar, getProvider, getProviderColor, getQueryClient, getRegisteredSchemaTypes, getRegisteredScopeProviders, getRoleFromClaims, getRouteManifest, getRouteSource, getRoutes, getRoutesConfig, getSchemaType, getScopeValue, getSmartDefaults, getStorageManager, getSupportedLanguages, getThemeInfo, getThemesConfig, getTokenManager, getValidAuthPartnerConfig, getValidAuthPartnerIds, getValidOAuthPartnerConfig, getValidOAuthPartnerIds, getVisibleFields, getVisibleItems, getViteEnvVar, getWeekFromISOString, getWidget, githubPermissionSchema, githubRepoConfigSchema, globalEmitter, grantGitHubAccessSchema, handleError, hasCustomSchemaGenerator, hasFlag, hasMetadata, hasOptionalCookies, hasProvider, hasRestrictedVisibility, hasRoleAccess, hasScopeProvider, hasTierAccess, ibanSchema, initSentry, initializeConfig, initializePlatformDetection, isAuthPartnerEnabled, isAuthPartnerId, isBackendGeneratedField, isBreakpoint, isClient, isCompactDateString, isConfigAvailable, isDev, isDoNotDevStore, isElementInViewport, isEmailVerificationRequired, isExpo, isFeatureAvailable, isFieldVisible, isFrameworkField, isIntersectionObserverSupported, isLocalStorageAvailable, isNextJs, isOAuthPartnerEnabled, isOAuthPartnerId, isPKCESupported, isPlatform, isReactNative, isServer, isTest, isValidTheme, isVite, isoToCompactString, lazyImport, listEntitiesSchema, listWidgets, mapSchema, mapToDoNotDevError, maybeTranslate, multiselectSchema, neverSchema, normalizeToISOString, numberSchema, observeElement, overrideFeatures, overridePaymentModes, overridePermissions, overrideSubscriptionStatus, overrideSubscriptionTiers, overrideUserRoles, parseDate, parseDateToNoonUTC, passwordSchema, pictureSchema, picturesSchema, priceSchema, rangeOptions, redirectToExternalUrl, redirectToExternalUrlWithErrorHandling, referenceSchema, refreshTokenSchema, registerSchemaGenerator, registerScopeProvider, registerUniqueConstraintValidator, registerWidget, removeLocalStorageItem, resetProviders, resolveAppConfig, resolveAuthConfig, resolvePageMeta, revokeGitHubAccessSchema, safeLocalStorage, safeSessionStorage, safeValidate, sanitizeHref, selectSchema, setCookie, setLocalStorageItem, shouldShowEmailVerification, showNotification, stringSchema, supportsFeature, switchSchema, telSchema, textSchema, throttle, timestampToISOString, timingUtils, toDateOnly, toISOString, translateArray, translateArrayRange, translateArrayWithIndices, translateObjectArray, unregisterScopeProvider, updateEntitySchema, updateMetadata, urlSchema, useAbortControllerStore, useAnalyticsConsent, useAppConfig, useAuthConfig, useBreakpoint, useBreathingTimer, useClickOutside, useConsent, useConsentReady, useConsentStore, useDebounce, useEventListener, useFaviconConfig, useFeatureConsent, useFeaturesConfig, useFunctionalConsent, useHasConsented, useI18nReady, useIntersectionObserver, useIsClient, useLanguage, useLanguageReady, useLanguageSelector, useLanguageStore, useLayout, useLocalStorage, useMarketingConsent, useMutation, useNavigationStore, useNetwork, useNetworkConnectionType, useNetworkOnline, useNetworkStatus, useNetworkStore, useOverlay, useOverlayStore, useQuery, useRateLimit, useSafeContext, useScriptLoader, useSeoConfig, useStorageManager, useTheme, useThemeReady, useThemeStore, useTranslation, useViewportVisibility, validateAIChatRequest, validateAIChatResponse, validateAuthPartners, validateAuthSchemas, validateAuthUser, validateBillingSchemas, validateBlock, validateCheckoutSessionMetadata, validateCodeChallenge, validateCodeVerifier, validateCreateCheckoutSessionRequest, validateCreateCheckoutSessionResponse, validateCustomClaims, validateDates, validateDocument, validateEvent, validateOAuthPartners, validateSendEmailRequest, validateSendEmailResponse, validateStripeBackConfig, validateStripeFrontConfig, validateSubscriptionClaims, validateSubscriptionData, validateUniqueFields, validateUserSubscription, validateWebhookEvent, validateWithSchema, when, withErrorHandling, withGracefulDegradation, withTimeout, wrapAuthError, wrapCrudError, wrapStorageError }; export type { AIAPI, AIChatRequest, AIChatResponse, AIConfig, AICostConfig, AICostEvent, AICostRecord, AICostResult, AIErrorCode, AIMessage, AIModelPricing, AIProvider, AIProviderConfig, AIRateLimitConfig, AIRouteConfig, AITierId, AIToolCall, AIToolDefinition, AIToolParameter, AIUsage, AccountLinkResult, AccountLinkingInfo, AdminCheckHookResult, AdminClaims, AggregateConfig, AggregateFilterOperator, AggregateOperation, AggregateRequest, AggregateResponse, AnyEntity, AnyFieldValue, AnyValibotSchema, ApiResponse, AppConfig, AppConfigProviderProps, AppCookieCategories, AppMetadata, AppProvidersProps, AssetsPluginConfig, AttemptRecord, AuditEvent, AuditEventType, AuthAPI, AuthActions, AuthConfig, AuthContextValue, AuthCoreHookResult, AuthError, AuthEventData, AuthEventKey, AuthEventName, AuthHardeningConfig, AuthHardeningContext, AuthMethod, AuthPartner, AuthPartnerHookResult, AuthPartnerId, AuthPartnerResult, AuthPartnerState, AuthProvider, AuthProviderProps, AuthRedirectHookResult, AuthRedirectOperation, AuthRedirectOptions, AuthResult, AuthState, AuthStateStore, AuthStatus, AuthTokenHookResult, AuthUser, AuthUserLike, BackendGeneratedField, BaseActions, BaseCredentials, BaseDocument, BaseEntityFields, BasePartnerState, BaseState, BaseStoreActions, BaseStoreState, BaseUserProfile, BasicUserInfo, BeforeCheckoutHook, BeforeCheckoutResult, BillingAPI, BillingAdapter, BillingErrorCode, BillingEvent, BillingEventData, BillingEventKey, BillingEventName, BillingProvider, BillingProviderConfig, BillingRedirectOperation, Breakpoint, BreakpointAPI, BreakpointUtils, BrowserEngine, BrowserInfo, BrowserType, BuiltInFieldType, BulkAcrossBatch, BulkAcrossResult, BulkCollisionReport, BulkOperations, BulkRequest, BulkResponse, BulkResult, BusinessEntity, CachedError, CanAPI, CanvasBlock, CanvasCallerAccess, CanvasEvent, CanvasLifetime, CanvasSurface, CanvasWidgetMetadata, CanvasWidgetProps, CheckGitHubAccessRequest, CheckoutMode, CheckoutOptions, CheckoutSessionMetadata, Claims, ClaimsCacheOptions, ClaimsCacheResult, CleanupFunction, CollectionSubscriptionCallback, ColumnDef, CommonSubscriptionFeatures, CommonTranslations, CompatibilityReport, ConditionBuilderLike, ConditionExpression, ConditionGroup, ConditionInput, ConditionNode, ConditionOperator, ConditionResult, ConditionalBehavior, ConfidenceLevel, ConnectOptions, ConsentAPI, ConsentActions, ConsentCategory, ConsentLevel, ConsentState, Context, CookieInfo, CookieOptions, CountryData, CreateCheckoutSessionRequest, CreateCheckoutSessionResponse, CreateEntityData, CreateEntityRequest, CreateEntityResponse, CrudAPI, CrudCardProps, CrudConfig, CrudCreateInput, CrudDocQuery, CrudListQuery, CrudOperationOptions, CrudOperator, CurrencyEntry, CustomClaims, CustomFieldOptionsMap, CustomSchemaGenerator, CustomStoreConfig, DateFormatOptions, DateFormatPreset, DateValue, DeleteEntityRequest, DeleteEntityResponse, Density, DnDevOverride, DnDevWrapper, DndevFrameworkConfig, DndevProviders, DndevStoreApi, DoNotDevCookieCategories, DoNotDevStore, DoNotDevStoreConfig, DoNotDevStoreState, DoNotDevTransProps, DocumentSubscriptionCallback, DynamicFormRule, Editable, EffectiveConnectionType, EmailConfig, EmailErrorCode, EmailProvider, EmailRouteConfig, EmailTemplate, EmailTemplateRegistry, EmailVerificationHookResult, EmailVerificationStatus, Entity, EntityAccessConfig, EntityAccessDefaults, EntityBrowseBaseProps, EntityCardListProps, EntityDisplayRendererProps, EntityField, EntityFieldMapDefault, EntityFormRendererProps, EntityHookErrors, EntityListProps, EntityMetadata, EntityOwnershipConfig, EntityOwnershipPublicCondition, EntityRecommendationsProps, EntityRecord, EntityRowFromFields, EntityTemplateProps, EntityTranslations, EnvironmentMode, ErrorCode, ErrorHandlerConfig, ErrorHandlerFunction, ErrorSeverity, ErrorSource, EventListener, ExchangeTokenParams, ExchangeTokenRequest, ExchangeTokenResponse, FAQSectionProps, FaviconConfig, Feature, FeatureAccessHookResult, FeatureAvailability, FeatureConsentRequirement, FeatureHookResult, FeatureId, FeatureName, FeatureStatus, FeatureSupport, FeaturesConfig, FeaturesPluginConfig, FeaturesRequiringAnyConsent, FeaturesRequiringConsent, FeaturesWithoutConsent, FieldCondition, FieldType, FieldTypeToValue, FileAsset, FilterVisibleFieldsOptions, FirebaseCallOptions, FirebaseConfig, FirestoreTimestamp, FirestoreUniqueConstraintValidator, FooterConfig, FooterMode, FooterZoneConfig, FormConfig, FormStep, FrameworkFeature, FunctionCallConfig, FunctionCallContext, FunctionCallOptions, FunctionCallResult, FunctionClient, FunctionClientFactoryOptions, FunctionDefaults, FunctionEndpoint, FunctionError, FunctionLoader, FunctionMemory, FunctionMeta, FunctionPlatform, FunctionResponse, FunctionSchema, FunctionSchemas, FunctionSystem, FunctionTrigger, FunctionsConfig, GetCustomClaimsResponse, GetEntityData, GetEntityRequest, GetEntityResponse, GetUserAuthStatusResponse, GetVisibleFieldsOptions, GitHubPermission, GitHubRepoConfig, GrantGitHubAccessRequest, GroupByDefinition, HandleErrorOptions, HeaderZoneConfig, I18nConfig, I18nPluginConfig, I18nProviderProps, ICallableProvider, ICrudAdapter, ID, INetworkManager, IServerAuthAdapter, IStorageAdapter, IStorageManager, IStorageStrategy, InferEntityRow, IntersectionObserverCallback, IntersectionObserverOptions, Invoice, InvoiceItem, LanguageAPI, LanguageData, LanguageFABFormat, LanguageFABProps, LanguageInfo$1 as LanguageInfo, LanguageSelectorProps, LanguageToggleGroupProps, LayoutAPI, LayoutConfig, LayoutPreset, LegalCompanyInfo, LegalConfig, LegalContactInfo, LegalDirectorInfo, LegalHostingInfo, LegalJurisdictionInfo, LegalSectionsConfig, LegalWebsiteInfo, ListCardLayout, ListEntitiesRequest, ListEntitiesResponse, ListEntityData, ListOptions, ListResponse, ListSchemaType, LoadingActions, LoadingState, LockoutResult, MergedBarConfig, MergedEntityFieldMap, MetricDefinition, MobileBehaviorConfig, ModalActions, ModalState, MutableMergedEntityFieldMap, MutationResponse, NavigationRoute, NetworkCheckConfig, NetworkConnectionType, NetworkReconnectCallback, NetworkState$1 as NetworkState, NetworkStatus, NetworkStatusHookResult, OAuthAPI, OAuthApiRequestOptions, OAuthCallbackHookResult, OAuthConnection, OAuthConnectionInfo, OAuthConnectionRequest, OAuthConnectionStatus, OAuthCredentials, OAuthEventData, OAuthEventKey, OAuthEventName, OAuthPartner, OAuthPartnerHookResult, OAuthPartnerId, OAuthPartnerResult, OAuthPartnerState, OAuthPurpose, OAuthRedirectOperation, OAuthRefreshRequest, OAuthRefreshResponse, OAuthResult, OAuthStoreActions, OAuthStoreState, OS, Observable, OperationSchemas, OrderByClause, OrderDirection, OverlayAPI, PWAAssetType, PWADisplayMode, PWAPluginConfig, PageAuth, PageMeta, PaginatedQueryResult, PaginationOptions, PartnerConnectionState, PartnerIconId, PartnerId, PartnerResult, PartnerType, PayloadCacheEventData, PayloadDocument, PayloadDocumentEventData, PayloadEventKey, PayloadEventName, PayloadGlobalEventData, PayloadMediaEventData, PayloadPageRegenerationEventData, PayloadRequest, PayloadUserEventData, PaymentEventData, PaymentMethod, PaymentMethodType, PaymentMode, Permission, Picture, Platform, PlatformInfo, PresetConfig, PresetRegistry, ProcessPaymentSuccessRequest, ProcessPaymentSuccessResponse, ProductDeclaration, ProviderInstances, QueryConfig, QueryOptions, QueryOrderBy, QueryWhereClause, RateLimitBackend, RateLimitConfig, RateLimitManager, RateLimitResult, RateLimitState, RateLimiter, ReadCallback, RedirectOperation, RedirectOverlayActions, RedirectOverlayConfig, RedirectOverlayPhase, RedirectOverlayState, Reference, RefreshSubscriptionRequest, RefreshSubscriptionResponse, RegisteredWidgetBase, RemoveCustomClaimsResponse, ResolvedLayoutConfig, RevokeGitHubAccessRequest, RouteData, RouteManifest, RouteMeta, RouteSource, RoutesPluginConfig, SEOConfig, SchemaMetadata, SchemaWithVisibility, ScopeConfig, ScopeProviderFn, SecurityContext, SecurityEntityConfig, SelectOption, SendEmailRequest, SendEmailResponse, SeoMeta, ServerRateLimitConfig, ServerRateLimitResult, ServerUserRecord, SetCustomClaimsResponse, SidebarZoneConfig, SignUpMetadata, SlotContent, StatusField, StorageError, StorageErrorType, StorageOptions, StorageScope, StorageType, Store, StripeBackConfig, StripeCheckoutRequest, StripeCheckoutResponse, StripeCheckoutSessionEventData, StripeConfig, StripeCustomer, StripeCustomerEventData, StripeEventData, StripeEventKey, StripeEventName, StripeFrontConfig, StripeInvoice, StripeInvoiceEventData, StripePayment, StripePaymentIntentEventData, StripePaymentMethod, StripePrice, StripeProduct, StripeProvider, StripeSubscription, StripeSubscriptionData, StripeWebhookEvent, StripeWebhookEventData, Subscription, SubscriptionClaims, SubscriptionConfig, SubscriptionData, SubscriptionDuration, SubscriptionEventData, SubscriptionHookResult, SubscriptionInfo, SubscriptionStatus, SubscriptionTier, SupportedLanguage, TechnicalField, ThemeAPI, ThemeActions, ThemeInfo, ThemeMode, ThemeState, ThemesPluginConfig, TierAccessHookResult, Timestamp, ToggleOrientation, ToggleSize, TokenInfo, TokenManagerOptions, TokenResponse, TokenState, TokenStatus, TransTag, TranslationOptions, TranslationResource, TypedBaseFields, UIFieldOptions, UniqueConstraintValidator, UniqueKeyDefinition, UnsubscribeFn, UpdateEntityData, UpdateEntityRequest, UpdateEntityResponse, UploadOptions, UploadProgressCallback, UploadResult, UseClickOutsideOptions, UseClickOutsideReturn, UseDebounceOptions, UseEventListenerOptions, UseEventListenerReturn, UseFunctionsCallResult, UseFunctionsMutationOptions, UseFunctionsMutationResult, UseFunctionsQueryOptions, UseFunctionsQueryResult, UseIntersectionObserverOptions, UseIntersectionObserverReturn, UseLocalStorageOptions, UseLocalStorageReturn, UseMutationOptionsWithErrorHandling, UseQueryOptionsWithErrorHandling, UseScriptLoaderOptions, UseScriptLoaderReturn, UseTranslationOptionsEnhanced, UseViewportVisibilityOptions, UseViewportVisibilityReturn, UserContext, UserProfile, UserProviderData, UserRole, UserSubscription, ValidateBlockOptions, ValidateResult, ValidationRules, ValueTypeForField, VerifiedToken, ViewportDetectionOptions, ViewportDetectionResult, Visibility, WebhookEvent, WebhookEventData, WhereClause, WhereOperator, WidgetDef, WithMetadata, dndevSchema };