@plyaz/types 1.19.3 → 1.19.5

package/dist/core/frontend/types.d.ts

@@ -0,0 +1,318 @@
+/**
+ * Base Frontend Service Types
+ *
+ * Type definitions for frontend domain services with store integration.
+ */
+import type { ReactNode } from 'react';
+import type { StoreKey } from '../../store';
+import type { CoreBaseDomainServiceInterface } from '../domain';
+import type { CoreAppEnvironment, CoreAppContext } from '../modules';
+import type { FeatureFlagValue, FeatureFlagContext } from '../../features';
+import type { CoreBaseDomainServiceConfig } from '../domain';
+import type { CoreBaseServiceConfig, CoreBaseMapperInstance, CoreBaseValidatorInstance } from '../domain';
+import type { CoreDomainServiceInstance, CoreServiceEntry } from '../init';
+/**
+ * Base store interface for frontend services.
+ * Stores must implement at least setData/setFlags.
+ * Loading and error setters are optional.
+ */
+export interface CoreBaseFrontendStore<TData = Record<string, unknown>> {
+    /** Set/replace all data in the store */
+    setData?(data: TData): void;
+    /** Update/merge data in the store (optional) */
+    updateData?(data: Partial<TData>): void;
+    /** Set loading state (optional) */
+    setLoading?(isLoading: boolean): void;
+    /** Set error state (optional) */
+    setError?(error: unknown): void;
+}
+/**
+ * Configuration for frontend domain services
+ */
+export interface CoreBaseFrontendServiceConfig<TData = Record<string, unknown>, TStore extends CoreBaseFrontendStore<TData> = CoreBaseFrontendStore<TData>> extends CoreBaseDomainServiceConfig {
+    /** Single store to connect on initialization */
+    store?: TStore;
+    /** Multiple stores to connect on initialization */
+    stores?: TStore[];
+    /**
+     * Store keys this service should connect to.
+     * Must be a subset of the service's `allowedStoreKeys`.
+     * If not specified, no stores are connected (warning logged).
+     */
+    storeKeys?: StoreKey[];
+}
+/**
+ * Base interface for frontend domain services with store integration.
+ *
+ * Extends BaseDomainServiceInterface with store management capabilities.
+ * All frontend domain services implement this.
+ *
+ * @typeParam TStore - Store interface type
+ */
+export interface CoreBaseFrontendServiceInterface<TStore extends CoreBaseFrontendStore = CoreBaseFrontendStore> extends CoreBaseDomainServiceInterface {
+    /** Connect a store to receive updates */
+    connectStore(store: TStore): void;
+    /** Disconnect a store from receiving updates */
+    disconnectStore(store: TStore): void;
+    /** Disconnect all connected stores */
+    disconnectAllStores(): void;
+    /** Number of connected stores */
+    readonly connectedStoreCount: number;
+    /** Whether any stores are connected */
+    readonly hasConnectedStores: boolean;
+}
+/**
+ * API configuration for the Plyaz provider
+ */
+export interface CorePlyazApiConfig {
+    /** API base URL (required) */
+    baseURL: string;
+    /** Environment (production, staging, development) */
+    env?: CoreAppEnvironment;
+    /** API key for authentication */
+    apiKey?: string;
+    /** Request timeout in ms */
+    timeout?: number;
+    /** Additional headers */
+    headers?: Record<string, string>;
+    /** Retry configuration */
+    retry?: {
+        attempts?: number;
+        delay?: number;
+    };
+    /** Enable encryption */
+    encryption?: {
+        enabled: boolean;
+        key?: string;
+    };
+}
+/**
+ * Frontend feature flag provider types
+ *
+ * Frontend-safe providers (no server-side dependencies):
+ * - 'memory': In-memory storage, resets on page refresh
+ * - 'api': Fetches flags from API endpoint
+ */
+export type FrontendFeatureFlagProvider = 'memory' | 'api';
+/**
+ * Feature flag configuration for frontend
+ */
+export interface CorePlyazFeatureFlagConfig {
+    /**
+     * Provider type for feature flags
+     * - 'memory': Flags stored in memory (default)
+     * - 'api': Flags fetched from API endpoint
+     */
+    provider?: FrontendFeatureFlagProvider;
+    /** Auto-refresh interval in ms (only for 'api' provider) */
+    refreshInterval?: number;
+    /** Default flag values */
+    defaults?: Record<string, boolean>;
+    /** API endpoint for flag fetching (default: '/feature-flags') */
+    apiEndpoint?: string;
+}
+/**
+ * Store integration configuration
+ */
+export interface CorePlyazStoreConfig {
+    /**
+     * Whether to auto-initialize the feature flag store
+     * When true, creates a fetchFn that uses ServiceRegistry's featureFlags service
+     */
+    autoInitFeatureFlags?: boolean;
+    /** Polling configuration for feature flags */
+    polling?: {
+        enabled?: boolean;
+        interval?: number;
+    };
+    /** Default feature flag values */
+    defaults?: Record<string, FeatureFlagValue>;
+    /** Callback when a flag value changes */
+    onFlagChange?: (key: string, prevValue: FeatureFlagValue | undefined, newValue: FeatureFlagValue) => void;
+}
+/**
+ * Full provider configuration
+ */
+export interface CorePlyazConfig {
+    /** API client configuration */
+    api: CorePlyazApiConfig;
+    /** Feature flag configuration */
+    featureFlags?: CorePlyazFeatureFlagConfig;
+    /**
+     * Domain services to auto-initialize via ServiceRegistry.
+     */
+    services?: CoreServiceEntry[];
+    /**
+     * Store integration configuration.
+     */
+    store?: CorePlyazStoreConfig;
+    /** App context (webapp, backoffice, mobile) */
+    appContext?: CoreAppContext;
+    /** Enable verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Interface for services that can provide feature flags.
+ */
+export interface CoreFeatureFlagServiceLike extends CoreDomainServiceInstance {
+    evaluateAll(context?: FeatureFlagContext): Promise<Record<string, unknown>>;
+    isEnabled(key: string, context?: FeatureFlagContext): Promise<boolean>;
+    getValue<T = FeatureFlagValue>(key: string, context?: FeatureFlagContext): Promise<T>;
+    refresh(): Promise<void>;
+}
+/**
+ * Options for creating a feature flag fetcher.
+ */
+export interface CoreFeatureFlagFetcherOptions {
+    /** Service key in the registry (default: 'featureFlags') */
+    serviceKey?: string;
+    /** Default context for evaluations */
+    context?: FeatureFlagContext;
+    /** Transform the response before returning */
+    transform?: (flags: Record<string, unknown>) => Record<string, FeatureFlagValue>;
+}
+/**
+ * Configuration for feature flag store initialization.
+ */
+export interface CoreFeatureFlagStoreInitConfig {
+    /** Fetch function to get flags */
+    fetchFn: () => Promise<Record<string, FeatureFlagValue>>;
+    /** Default flag values */
+    defaults?: Record<string, FeatureFlagValue>;
+    /** Polling configuration */
+    polling?: {
+        enabled?: boolean;
+        interval?: number;
+    };
+    /** Callback when a flag value changes */
+    onFlagChange?: (key: string, prevValue: FeatureFlagValue | undefined, newValue: FeatureFlagValue) => void;
+    /** Callback when an error occurs */
+    onError?: (error: unknown) => void;
+}
+/**
+ * Base service config for frontend services (constructor config)
+ */
+export interface CoreBaseFrontendServiceConstructorConfig<TConfig extends CoreBaseFrontendServiceConfig<TData, TStore>, TStore extends CoreBaseFrontendStore<TData>, TData = Record<string, unknown>, TMapper extends CoreBaseMapperInstance = CoreBaseMapperInstance, TValidator extends CoreBaseValidatorInstance = CoreBaseValidatorInstance> extends CoreBaseServiceConfig<TConfig, TMapper, TValidator> {
+    /** Data key used for store sync (e.g., 'flags', 'items', 'data') */
+    storeDataKey?: string;
+}
+/**
+ * Props for initialization error component
+ */
+export interface CoreInitializationErrorProps {
+    /** The error that occurred */
+    error: Error;
+    /** Custom error component override */
+    errorComponent?: (error: Error) => ReactNode;
+}
+/**
+ * Props for initialization loading component
+ */
+export interface CoreInitializationLoadingProps {
+    /** Custom loading component override */
+    loading?: ReactNode;
+}
+/**
+ * Abstract API client interface for provider context.
+ * Implementations provide the concrete ApiClientService.
+ */
+export interface CoreApiClientLike {
+    /** Check if the client is initialized */
+    isInitialized(): boolean;
+    /** Get the underlying HTTP client */
+    getClient(): unknown;
+}
+/**
+ * Abstract event manager interface for provider context.
+ * Implementations provide the concrete CoreEventManager.
+ */
+export interface CoreEventManagerLike {
+    /** Subscribe to an event */
+    on(event: string, handler: (event: unknown) => void): () => void;
+    /** Emit an event */
+    emit(event: string, data?: unknown): void;
+    /** Unsubscribe from an event */
+    off(event: string, handler: (event: unknown) => void): void;
+}
+/**
+ * Abstract Core initializer interface for provider context.
+ * Implementations provide the concrete Core class.
+ */
+export interface CoreInitializerLike {
+    /** Check if Core is initialized */
+    readonly isInitialized: boolean;
+    /** Get current app context */
+    readonly appContext: CoreAppContext;
+    /** Reset Core state */
+    reset(): Promise<void>;
+}
+/**
+ * Services available through the Plyaz provider
+ */
+export interface CorePlyazServices {
+    /** Feature flags interface */
+    featureFlags: {
+        get: (key: string, defaultValue?: boolean) => boolean;
+        getAll: () => Record<string, boolean>;
+        refresh: () => Promise<void>;
+    };
+    /** App context */
+    appContext: CoreAppContext;
+    /** Current environment */
+    environment: CoreAppEnvironment;
+    /**
+     * Get a domain service by key.
+     * Services must be registered in the `services` config.
+     */
+    getService: <T extends CoreDomainServiceInstance>(key: string) => T;
+    /**
+     * Get a domain service by key with async initialization if needed.
+     * Use this for lazy-initialized services.
+     */
+    getServiceAsync: <T extends CoreDomainServiceInstance>(key: string) => Promise<T>;
+    /**
+     * Check if a service is registered
+     */
+    hasService: (key: string) => boolean;
+    /**
+     * Get all initialized service keys
+     */
+    getServiceKeys: () => string[];
+}
+/**
+ * Context value provided to Plyaz consumers.
+ * Extends CorePlyazServices with implementation-specific service references.
+ */
+export interface CorePlyazContextValue extends CorePlyazServices {
+    /** API client for making HTTP requests (null until initialized) */
+    api: CoreApiClientLike | null;
+    /** Event manager for pub/sub */
+    events: CoreEventManagerLike;
+    /** Core initializer reference */
+    core: CoreInitializerLike;
+    /** Whether services are initialized and ready */
+    isReady: boolean;
+    /** Initialization error if any */
+    error: Error | null;
+    /** Re-initialize services */
+    reinitialize: () => Promise<void>;
+}
+/**
+ * Props for PlyazProvider component
+ */
+export interface CorePlyazProviderProps {
+    /** Child components */
+    children: ReactNode;
+    /** Configuration */
+    config: CorePlyazConfig;
+    /** Loading component to show while initializing */
+    loading?: ReactNode;
+    /** Error component to show on initialization failure */
+    error?: (error: Error) => ReactNode;
+    /** Callback when services are ready */
+    onReady?: (services: CorePlyazServices) => void;
+    /** Callback on initialization error */
+    onError?: (error: Error) => void;
+    /** Skip showing loading state (render children immediately) */
+    skipLoadingState?: boolean;
+}

package/dist/core/index.d.ts

@@ -4,9 +4,9 @@
  *
  * @module core
  */
-export type { ApiEnvironmentConfig, ApiProviderProps } from './services';
+export type { CoreApiEnvironmentConfig, CoreApiProviderProps } from './services';
 export type { CoreIdempotencyStoreType, CoreInMemoryIdempotencyAdapterConfig, CoreRedisIdempotencyAdapterConfig, CoreIdempotencyStoreOptions, CoreIdempotencyStoreConfig, } from './idempotency';
-export type { CoreServices, CoreRouteContext, CoreRouteHandler, CoreRouteDefinition, CoreModuleConfigSchema, CoreServiceFactory, CoreModuleLifecycle, CoreModuleDefinition, CoreRegisteredModule, CoreConfiguredModule, CoreModuleFactory, CoreFrameworkType, CoreServerConfig, CoreFrameworkAdapter, CoreAdapterFactory, CoreRuntimeEnvironment, CoreRuntimeContext, CoreNextJsHandlerContext, CoreNextJsHandlerResult, CoreNextJsHandler, CoreNextJsHandlerOptions, CoreEnvVars, CoreAppEnvironment, CoreApiInitOptions, CoreInitOptions, CoreServicesResult, CoreNestJsModuleOptions, CoreNestJsModuleAsyncOptions, CoreAppContext, CoreServiceRuntime, CoreDomainServiceConfig, } from './modules';
+export type { CoreServices, CoreRouteContext, CoreRouteHandler, CoreRouteDefinition, CoreModuleConfigSchema, CoreServiceFactory, CoreModuleLifecycle, CoreModuleDefinition, CoreRegisteredModule, CoreConfiguredModule, CoreModuleFactory, CoreFrameworkType, CoreServerConfig, CoreFrameworkAdapter, CoreAdapterFactory, CoreRuntimeEnvironment, CoreRuntimeContext, CoreNextJsHandlerContext, CoreNextJsHandlerResult, CoreNextJsHandler, CoreNextJsHandlerOptions, CoreEnvVars, CoreAppEnvironment, CoreApiInitOptions, CoreInitOptions, CoreServicesResult, CoreNestJsModuleOptions, CoreNestJsModuleAsyncOptions, CoreNestJsCoreModuleAsyncOptions, CoreAppContext, CoreServiceRuntime, CoreDomainServiceConfig, } from './modules';
 export { BACKEND_RUNTIMES, FRONTEND_RUNTIMES, UNIVERSAL_RUNTIMES, APP_CONTEXTS } from './modules';
 export * from './tables/enum';
 export type * from './auth/types';
@@ -15,3 +15,7 @@ export * from './featureFlag/enums';
 export * from './featureFlag/constants';
 export * from './events';
 export type * from './types';
+export type * from './domain';
+export type * from './init';
+export type * from './services';
+export type * from './frontend';

package/dist/core/init/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Core Init Types
+ * Service registry and initialization type definitions
+ */
+export type { CoreDomainServiceInstance, CoreServiceInitConfig, CoreServiceCreateOptions, CoreInitializableDomainService, CoreServiceEntry, CoreServiceRegistryConfig, CoreExtractServiceConfig, CoreExtractServiceInstance, CoreFeatureFlagInitConfig, CoreErrorHandlerInitConfig, CoreInitOptionsBase, CoreServicesResultBase, } from './types';

package/dist/core/init/types.d.ts

@@ -0,0 +1,347 @@
+/**
+ * Service Registry Types
+ *
+ * Defines interfaces for the frontend service registry pattern.
+ * Services must implement these interfaces to be auto-initialized.
+ */
+import type { ApiClientOptions } from '../../api';
+import type { StoreKey } from '../../store';
+import type { FeatureFlagValue, FeatureFlagPollingConfig } from '../../features';
+import type { PackageErrorLike } from '../../errors';
+import type { GlobalErrorHandlerConfig } from '../../errors/middleware';
+import type { CoreAppEnvironment, CoreAppContext, CoreRuntimeEnvironment } from '../modules';
+import type { CoreDbServiceConfig } from '../services';
+/**
+ * Base interface that all domain service instances must implement.
+ * This allows the registry to manage services generically.
+ */
+export interface CoreDomainServiceInstance {
+    /** Unique service name/key */
+    readonly serviceName: string;
+    /** Whether the service is enabled */
+    readonly isServiceEnabled: boolean;
+    /** Whether the service is initialized and ready */
+    readonly isInitialized: boolean;
+    /** Check if service is available (configured and ready) */
+    isAvailable(): boolean;
+    /** Dispose/cleanup the service */
+    dispose(): void;
+}
+/**
+ * Base configuration for service initialization
+ */
+export interface CoreServiceInitConfig {
+    /** Whether the service is enabled (default: true) */
+    enabled?: boolean;
+    /**
+     * Store keys this service should connect to.
+     *
+     * Each frontend service can specify which stores it needs access to.
+     * The service's `allowedStoreKeys` static property defines valid options.
+     * If not specified, no stores will be connected (warning logged).
+     *
+     * @example
+     * ```typescript
+     * // Service that uses error and featureFlags stores
+     * { service: MyService, config: { storeKeys: ['error', 'featureFlags'] } }
+     *
+     * // Service that only uses error store
+     * { service: AnotherService, config: { storeKeys: ['error'] } }
+     * ```
+     */
+    storeKeys?: StoreKey[];
+    /**
+     * When to initialize the service:
+     * - 'immediate': Initialize during Core.initialize() (default)
+     * - 'lazy': Initialize on first access
+     * - function: Initialize when function returns true
+     */
+    initWhen?: 'immediate' | 'lazy' | (() => boolean | Promise<boolean>);
+    /**
+     * Whether to create a singleton instance (default: true).
+     *
+     * - `true`: One shared instance per service key (default)
+     * - `false`: Create a new instance each time `ServiceRegistry.create()` is called
+     *
+     * Singletons are stored in the registry and disposed on `disposeAll()`.
+     * Non-singletons must be managed by the caller.
+     *
+     * @example
+     * ```typescript
+     * // Singleton (default) - same instance returned each time
+     * { service: MyService, config: { singleton: true } }
+     * const svc1 = ServiceRegistry.get('myService');
+     * const svc2 = ServiceRegistry.get('myService');
+     * svc1 === svc2; // true
+     *
+     * // Non-singleton - new instance each time via create()
+     * { service: MyService, config: { singleton: false } }
+     * const svc1 = await ServiceRegistry.create('myService');
+     * const svc2 = await ServiceRegistry.create('myService');
+     * svc1 === svc2; // false
+     * ```
+     */
+    singleton?: boolean;
+    /**
+     * Create a dedicated API client instance for this service.
+     *
+     * By default, services share the global API client. Use this option when
+     * a service needs its own isolated API client (e.g., different base URL,
+     * separate rate limiting, different auth).
+     *
+     * - `false` or `undefined`: Use global shared API client (default)
+     * - `true`: Create dedicated instance using global config
+     * - `ApiClientOptions`: Create dedicated instance with custom config
+     *
+     * @example
+     * ```typescript
+     * // Use global shared client (default)
+     * { service: UserService, config: { enabled: true } }
+     *
+     * // Create dedicated client with global config
+     * { service: PaymentService, config: { dedicatedApiClient: true } }
+     *
+     * // Create dedicated client with custom config
+     * {
+     *   service: ExternalApiService,
+     *   config: {
+     *     dedicatedApiClient: {
+     *       baseURL: 'https://external-api.com',
+     *       headers: { static: { 'X-API-Key': 'xxx' } },
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    dedicatedApiClient?: boolean | ApiClientOptions;
+    /**
+     * Create a dedicated database instance for this service.
+     *
+     * By default, services share the global database connection. Use this when
+     * a service needs its own isolated DB connection (e.g., different database,
+     * separate connection pool, read replica).
+     *
+     * - `false` or `undefined`: Use global shared database (default)
+     * - `true`: Create dedicated instance using global config
+     * - `DbServiceConfig`: Create dedicated instance with custom config
+     *
+     * Note: This is typically only used in backend/Node.js contexts.
+     *
+     * @example
+     * ```typescript
+     * // Use global shared database (default)
+     * { service: UserService, config: { enabled: true } }
+     *
+     * // Create dedicated DB with global config (e.g., separate connection pool)
+     * { service: ReportService, config: { dedicatedDb: true } }
+     *
+     * // Create dedicated DB with different connection
+     * {
+     *   service: AnalyticsService,
+     *   config: {
+     *     dedicatedDb: {
+     *       adapter: 'sql',
+     *       sql: { connectionString: process.env.ANALYTICS_DB_URL },
+     *     },
+     *   },
+     * }
+     * ```
+     */
+    dedicatedDb?: boolean | Partial<CoreDbServiceConfig>;
+}
+/**
+ * Options passed to the service factory method
+ */
+export interface CoreServiceCreateOptions {
+    /**
+     * API client configuration and mode.
+     */
+    apiClient?: {
+        /**
+         * Whether to use a dedicated (isolated) API client instance.
+         * - `false`: Use global shared instance (default)
+         * - `true`: Create dedicated instance
+         */
+        dedicated: boolean;
+        /**
+         * API client options (merged global + per-service config).
+         * Used to create dedicated instance or configure global.
+         */
+        options?: ApiClientOptions;
+    };
+    /**
+     * Database configuration and mode.
+     */
+    db?: {
+        /**
+         * Whether to use a dedicated (isolated) database instance.
+         * - `false`: Use global shared instance (default)
+         * - `true`: Create dedicated instance
+         */
+        dedicated: boolean;
+        /**
+         * Database config (merged global + per-service config).
+         * Used to create dedicated instance or configure global.
+         */
+        config?: Partial<CoreDbServiceConfig>;
+    };
+    /** Logger prefix */
+    loggerPrefix?: string;
+    /** Whether this is a singleton instance */
+    isSingleton?: boolean;
+    /**
+     * Store keys this service should connect to.
+     * Passed from the service config to the create method.
+     */
+    storeKeys?: StoreKey[];
+}
+/**
+ * Static interface that service classes must implement.
+ * This enables the registry to call ServiceClass.create(config) generically.
+ *
+ * @example
+ * ```typescript
+ * class MyDomainService extends BaseDomainService implements DomainServiceInstance {
+ *   static readonly serviceKey = 'myService';
+ *
+ *   static async create(
+ *     config: MyServiceConfig,
+ *     options?: ServiceCreateOptions
+ *   ): Promise<MyDomainService> {
+ *     const service = new MyDomainService(config);
+ *     await service.initialize();
+ *     return service;
+ *   }
+ * }
+ * ```
+ */
+export interface CoreInitializableDomainService<TConfig extends CoreServiceInitConfig = CoreServiceInitConfig, TInstance extends CoreDomainServiceInstance = CoreDomainServiceInstance> {
+    /** Unique key for this service (e.g., 'featureFlags', 'example') */
+    readonly serviceKey: string;
+    /**
+     * Factory method to create and initialize the service instance.
+     *
+     * @param config - Service-specific configuration
+     * @param options - Global options from the registry
+     * @returns Promise resolving to the initialized service instance
+     */
+    create(config: TConfig, options?: CoreServiceCreateOptions): Promise<TInstance>;
+}
+/**
+ * Entry for a single service in the registry config.
+ * Pairs a service class with its configuration.
+ */
+export interface CoreServiceEntry<TConfig extends CoreServiceInitConfig = CoreServiceInitConfig, TInstance extends CoreDomainServiceInstance = CoreDomainServiceInstance> {
+    /** The service class (must have static create method) */
+    service: CoreInitializableDomainService<TConfig, TInstance>;
+    /** Configuration for this service */
+    config: TConfig;
+}
+/**
+ * Configuration for the service registry.
+ *
+ * @example
+ * ```typescript
+ * const registryConfig: ServiceRegistryConfig = {
+ *   apiClient: { baseURL: '/api' },
+ *   db: { adapter: 'sql', sql: { connectionString: '...' } },
+ *   services: [
+ *     { service: FeatureFlagDomainService, config: { enabled: true } },
+ *     { service: ExampleDomainService, config: { enabled: true, useRealApi: false } },
+ *     // Per-service override
+ *     { service: PaymentService, config: {
+ *       enabled: true,
+ *       apiClient: { baseURL: 'https://payments.api.com' },
+ *     }},
+ *   ],
+ * };
+ * ```
+ */
+export interface CoreServiceRegistryConfig {
+    /** Global API client options (shared by all services unless overridden) */
+    apiClient?: ApiClientOptions;
+    /** Global database config (shared by all services unless overridden) */
+    db?: Partial<CoreDbServiceConfig>;
+    /** Services to register and initialize */
+    services: CoreServiceEntry[];
+}
+/**
+ * Extract the config type from a service class
+ */
+export type CoreExtractServiceConfig<T> = T extends CoreInitializableDomainService<infer C, CoreDomainServiceInstance> ? C : never;
+/**
+ * Extract the instance type from a service class
+ */
+export type CoreExtractServiceInstance<T> = T extends CoreInitializableDomainService<CoreServiceInitConfig, infer I> ? I : never;
+/**
+ * Feature flag initialization configuration
+ */
+export interface CoreFeatureFlagInitConfig {
+    /** Whether to enable feature flags (default: true) */
+    enabled?: boolean;
+    /** Default flag values */
+    defaults?: Record<string, FeatureFlagValue>;
+    /** Polling configuration */
+    polling?: FeatureFlagPollingConfig;
+    /** API endpoint for fetching flags (default: '/feature-flags') */
+    apiEndpoint?: string;
+    /** Callback when a flag value changes */
+    onFlagChange?: (key: string, prevValue: FeatureFlagValue | undefined, newValue: FeatureFlagValue) => void;
+    /** Callback when an error occurs */
+    onError?: (error: PackageErrorLike) => void;
+}
+/**
+ * Error handler initialization configuration
+ */
+export interface CoreErrorHandlerInitConfig extends Omit<GlobalErrorHandlerConfig, 'serialize'> {
+    /**
+     * Whether to enable auto-initialization of global error handler (default: true).
+     * Set to false to use your own error handling.
+     */
+    enabled?: boolean;
+}
+/**
+ * Base core initialization options
+ * Extended by @plyaz/core's CoreInitOptions with specific types
+ */
+export interface CoreInitOptionsBase<TDb = unknown, TApi = unknown> {
+    /** Path to .env file (backend only) */
+    envPath?: string;
+    /** Global environment (production, staging, development) */
+    environment?: CoreAppEnvironment;
+    /** App context (webapp, backoffice, mobile) */
+    appContext?: CoreAppContext;
+    /** Direct env vars (merged with loaded) */
+    env?: Record<string, string | undefined>;
+    /** Database configuration */
+    db?: TDb;
+    /** API client configuration */
+    api?: TApi;
+    /** Skip database initialization */
+    skipDb?: boolean;
+    /** Skip API client initialization */
+    skipApi?: boolean;
+    /** Enable verbose logging */
+    verbose?: boolean;
+    /** Error handler configuration */
+    errorHandler?: CoreErrorHandlerInitConfig;
+    /** Feature flags configuration */
+    featureFlags?: CoreFeatureFlagInitConfig;
+    /** Domain services to auto-initialize */
+    services?: CoreServiceEntry[];
+}
+/**
+ * Core services result from initialization
+ */
+export interface CoreServicesResultBase<TDb = unknown, TApi = unknown> {
+    /** Database service instance (null if skipped or on frontend) */
+    db: TDb | null;
+    /** API client service class */
+    api: TApi | null;
+    /** Loaded environment variables */
+    env: Record<string, string | undefined>;
+    /** Detected runtime environment */
+    runtime: CoreRuntimeEnvironment;
+    /** App context */
+    appContext: CoreAppContext;
+}