@plyaz/types 1.10.0 → 1.11.1

package/dist/core/services.d.ts

@@ -0,0 +1,397 @@
+/**
+ * Service Layer Types for @plyaz/core
+ * Types specific to core package services
+ */
+import type { ReactNode } from 'react';
+import type { ApiClientOptions } from '../api/client';
+/**
+ * Environment configuration for API client initialization
+ *
+ * Contains ONLY environment-level metadata used to determine configuration defaults.
+ * API-specific configuration (baseURL, encryption, timeout) should be passed separately
+ * via the `apiConfig` parameter when initializing the client.
+ *
+ * **Purpose**:
+ * - Determines which environment defaults to apply (production/staging/development)
+ * - Provides environment-specific metadata (API keys, rate limits)
+ * - Controls whether the client is set as the default for services/hooks
+ *
+ * **Configuration Merge Priority**:
+ * 1. Environment defaults (lowest priority) - from @plyaz/config based on `env`
+ * 2. Environment metadata (medium priority) - from this `envConfig` object
+ * 3. API configuration (highest priority) - from the separate `apiConfig` parameter
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - production with API key
+ * const envConfig: ApiEnvironmentConfig = {
+ *   env: 'production',
+ *   apiKey: process.env.API_KEY
+ * };
+ *
+ * await ApiClientService.init(envConfig, {
+ *   baseURL: 'https://api.example.com',
+ *   encryption: { key: encryptionKey }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Multiple clients - main API set as default
+ * const mainEnv: ApiEnvironmentConfig = {
+ *   env: 'production',
+ *   setAsDefault: true  // Services/hooks use this automatically
+ * };
+ *
+ * const analyticsEnv: ApiEnvironmentConfig = {
+ *   env: 'production',
+ *   setAsDefault: false  // Must pass explicitly via ServiceOptions
+ * };
+ *
+ * const mainClient = await ApiClientService.init(mainEnv, mainConfig);
+ * const analyticsClient = await ApiClientService.init(analyticsEnv, analyticsConfig);
+ *
+ * // Use default client
+ * const campaigns = await fetchCampaigns({ page: 1 });
+ *
+ * // Use custom client via ServiceOptions
+ * const analytics = await fetchAnalytics(
+ *   { date: '2025-10-16' },
+ *   { apiClient: analyticsClient }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Development with rate limiting (reserved for future use)
+ * const envConfig: ApiEnvironmentConfig = {
+ *   env: 'development',
+ *   apiKey: 'dev-key',
+ *   rateLimit: {
+ *     maxRequests: 100,
+ *     windowMs: 60000  // 1 minute
+ *   }
+ * };
+ * ```
+ *
+ * @see ServiceOptions from @plyaz/types/api - For per-request configuration overrides
+ * @since 1.1.0
+ */
+export interface ApiEnvironmentConfig {
+    /**
+     * Environment name - determines which default configuration to apply
+     *
+     * **Environment Defaults**:
+     * - `production`: Aggressive retries (5), encryption required, telemetry enabled
+     * - `staging`: Mirrors production for accurate testing
+     * - `development`: Conservative retries (1), encryption optional, full debug mode
+     * - `test`: Same as development
+     *
+     * @example
+     * ```typescript
+     * env: process.env.NODE_ENV as 'production'
+     * ```
+     */
+    env: 'development' | 'staging' | 'production' | 'test';
+    /**
+     * API authentication key for the environment
+     *
+     * When provided, automatically added to request headers as `X-API-Key`.
+     * Useful for API gateway authentication or environment-specific keys.
+     *
+     * @example
+     * ```typescript
+     * apiKey: process.env.NEXT_PUBLIC_API_KEY
+     * ```
+     *
+     * @optional
+     */
+    apiKey?: string;
+    /**
+     * Rate limiting configuration per environment
+     *
+     * **Note**: Currently reserved for future use. Rate limiting is typically
+     * handled at the server/API gateway level rather than the HTTP client.
+     * This field is preserved in the interface for future client-side rate
+     * limiting implementation if needed.
+     *
+     * @example
+     * ```typescript
+     * rateLimit: {
+     *   maxRequests: 100,   // Maximum requests per window
+     *   windowMs: 60000     // Time window in milliseconds (1 minute)
+     * }
+     * ```
+     *
+     * @optional
+     * @future
+     */
+    rateLimit?: {
+        /** Maximum number of requests allowed within the time window */
+        maxRequests: number;
+        /** Time window in milliseconds for rate limiting */
+        windowMs: number;
+    };
+    /**
+     * Whether to set the created client as the default for @plyaz/api services and hooks
+     *
+     * **Default behavior**: `true` (if not specified)
+     *
+     * **When `true` (recommended for most apps)**:
+     * - Services and hooks from @plyaz/api automatically use this client
+     * - No need to pass `apiClient` in `ServiceOptions`
+     * - Simplifies usage across the entire application
+     *
+     * **When `false` (advanced use cases)**:
+     * - Client is NOT set as the default
+     * - Must explicitly pass client via `ServiceOptions.apiClient`
+     * - Useful for multiple API clients (main API, analytics API, etc.)
+     * - Useful for testing with mock clients
+     * - Useful for per-tenant API configurations
+     *
+     * @example
+     * ```typescript
+     * // Set as default (most common)
+     * await ApiClientService.init(
+     *   { env: 'production', setAsDefault: true },
+     *   apiConfig
+     * );
+     *
+     * // Now all services use this client automatically
+     * const campaigns = await fetchCampaigns({ page: 1 });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Don't set as default (multiple clients)
+     * const analyticsClient = await ApiClientService.init(
+     *   { env: 'production', setAsDefault: false },
+     *   analyticsConfig
+     * );
+     *
+     * // Must pass client explicitly via ServiceOptions
+     * const analytics = await fetchAnalytics(
+     *   { date: '2025-10-16' },
+     *   { apiClient: analyticsClient }
+     * );
+     * ```
+     *
+     * @default true
+     * @optional
+     * @see ServiceOptions.apiClient from @plyaz/types/api - For passing custom client per request
+     */
+    setAsDefault?: boolean;
+}
+/**
+ * Props for ApiProvider component
+ *
+ * React provider component that initializes the API client service for React/Next.js applications.
+ * Wraps your app to ensure the API client is ready before rendering children.
+ *
+ * **Features**:
+ * - Automatic API client initialization on mount
+ * - Loading state management during initialization
+ * - Error handling with customizable error UI
+ * - Success/error callbacks for integration with state management
+ * - Singleton pattern - only initializes once per app lifecycle
+ *
+ * @example
+ * ```tsx
+ * // Basic usage in Next.js app layout
+ * import { ApiProvider } from '@plyaz/core';
+ *
+ * export default function RootLayout({ children }) {
+ *   const envConfig = {
+ *     env: process.env.NODE_ENV as 'production',
+ *     apiKey: process.env.NEXT_PUBLIC_API_KEY,
+ *   };
+ *
+ *   const apiConfig = {
+ *     baseURL: process.env.NEXT_PUBLIC_API_URL!,
+ *     encryption: {
+ *       key: {
+ *         id: 'prod-key-v1',
+ *         key: process.env.NEXT_PUBLIC_ENCRYPTION_KEY!,
+ *         algorithm: 'AES-GCM',
+ *         format: 'raw'
+ *       }
+ *     },
+ *   };
+ *
+ *   return (
+ *     <ApiProvider envConfig={envConfig} apiConfig={apiConfig}>
+ *       {children}
+ *     </ApiProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom loading and error components
+ * <ApiProvider
+ *   envConfig={envConfig}
+ *   apiConfig={apiConfig}
+ *   loadingComponent={
+ *     <div className="loading">
+ *       <Spinner />
+ *       <p>Initializing API client...</p>
+ *     </div>
+ *   }
+ *   errorComponent={(error) => (
+ *     <div className="error">
+ *       <h2>API Initialization Failed</h2>
+ *       <p>{error.message}</p>
+ *       <button onClick={() => window.location.reload()}>Retry</button>
+ *     </div>
+ *   )}
+ *   onInitialized={() => {
+ *     console.log('[App] API client ready');
+ *   }}
+ *   onError={(error) => {
+ *     console.error('[App] API initialization error:', error);
+ *   }}
+ * >
+ *   {children}
+ * </ApiProvider>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With state management integration
+ * <ApiProvider
+ *   envConfig={envConfig}
+ *   apiConfig={{
+ *     ...apiConfig,
+ *     clientEvents: {
+ *       onRequestStart: (event) => {
+ *         apiStore.setState({ loading: true, requestId: event.data.id });
+ *       },
+ *       onResponseReceived: (event) => {
+ *         apiStore.setState({ loading: false, lastResponse: event.data });
+ *       },
+ *     },
+ *   }}
+ *   onInitialized={() => {
+ *     appStore.setState({ apiReady: true });
+ *   }}
+ * >
+ *   {children}
+ * </ApiProvider>
+ * ```
+ *
+ * @see {@link ApiEnvironmentConfig} - Environment configuration options
+ * @see {@link ApiClientOptions} from @plyaz/types/api - Full API configuration options
+ * @since 1.1.0
+ */
+export interface ApiProviderProps {
+    /**
+     * React children to render after successful initialization
+     *
+     * Children are only rendered once the API client is fully initialized and ready.
+     * If initialization fails, the error component is rendered instead.
+     */
+    children: ReactNode;
+    /**
+     * Environment configuration
+     *
+     * Contains environment-level metadata (env, apiKey, rateLimit, setAsDefault).
+     * Determines which default configuration to apply from @plyaz/config.
+     *
+     * @see {@link ApiEnvironmentConfig} - Full configuration options
+     */
+    envConfig: ApiEnvironmentConfig;
+    /**
+     * API configuration
+     *
+     * Contains API-specific settings (baseURL, encryption, timeout, event handlers).
+     * All options from @plyaz/api's `ApiClientOptions` interface are supported.
+     *
+     * **Required fields**:
+     * - `baseURL`: API base URL
+     *
+     * **Commonly configured**:
+     * - `encryption`: Encryption configuration with key
+     * - `timeout`: Request timeout in milliseconds
+     * - `clientEvents`: Event handlers for monitoring
+     * - `retry`: Retry strategy configuration
+     *
+     * @see {@link ApiClientOptions} from @plyaz/types/api - Complete options reference
+     */
+    apiConfig: Partial<ApiClientOptions>;
+    /**
+     * Loading component to show while initializing
+     *
+     * Rendered while the API client is being initialized. If not provided,
+     * a default loading message is shown.
+     *
+     * @optional
+     *
+     * @example
+     * ```tsx
+     * loadingComponent={
+     *   <div className="loading">
+     *     <Spinner size="large" />
+     *     <p>Setting up API connection...</p>
+     *   </div>
+     * }
+     * ```
+     */
+    loadingComponent?: ReactNode;
+    /**
+     * Error component to show if initialization fails
+     *
+     * Rendered when API client initialization fails. Receives the error as a parameter.
+     * If not provided, a default error message is shown.
+     *
+     * @optional
+     *
+     * @example
+     * ```tsx
+     * errorComponent={(error) => (
+     *   <ErrorBoundary error={error}>
+     *     <button onClick={() => window.location.reload()}>
+     *       Retry
+     *     </button>
+     *   </ErrorBoundary>
+     * )}
+     * ```
+     */
+    errorComponent?: (error: Error) => ReactNode;
+    /**
+     * Callback when initialization completes successfully
+     *
+     * Called once the API client is fully initialized and ready to use.
+     * Useful for tracking initialization success or triggering post-init logic.
+     *
+     * @optional
+     *
+     * @example
+     * ```tsx
+     * onInitialized={() => {
+     *   console.log('[App] API client initialized');
+     *   analytics.track('api_client_ready');
+     *   appStore.setState({ apiReady: true });
+     * }}
+     * ```
+     */
+    onInitialized?: () => void;
+    /**
+     * Callback when initialization fails
+     *
+     * Called if API client initialization throws an error.
+     * Useful for error tracking, logging, or showing user notifications.
+     *
+     * @optional
+     *
+     * @example
+     * ```tsx
+     * onError={(error) => {
+     *   console.error('[App] API initialization failed:', error);
+     *   Sentry.captureException(error);
+     *   toast.error('Failed to connect to API');
+     * }}
+     * ```
+     */
+    onError?: (error: Error) => void;
+}