@plyaz/types 1.11.0 → 1.11.2

package/dist/core/index.d.ts

@@ -4,4 +4,4 @@
  *
  * @module core
  */
-export type { ApiEnvironmentConfig } from './services';
+export type { ApiEnvironmentConfig, ApiProviderProps } from './services';

package/dist/core/services.d.ts

@@ -2,6 +2,8 @@
  * 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
  *
@@ -180,3 +182,265 @@ export interface ApiEnvironmentConfig {
      */
     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
+ *
+ * **Important**:
+ * - Initialization runs ONCE on mount, regardless of prop changes
+ * - Config changes after mount are NOT supported (singleton pattern)
+ * - If you need to change config, use `ApiClientService.reinitialize()` manually
+ * - To avoid unnecessary re-renders, memoize `envConfig` and `apiConfig` in parent component
+ *
+ * @example
+ * ```tsx
+ * // Basic usage in Next.js app layout
+ * // IMPORTANT: For client components, pass sensitive config from server-side props/actions
+ * import { ApiProvider } from '@plyaz/core';
+ * import { useMemo } from 'react';
+ *
+ * export default function RootLayout({ children }) {
+ *   // Memoize configs to prevent unnecessary re-renders
+ *   const envConfig = useMemo(() => ({
+ *     env: process.env.NODE_ENV as 'production',
+ *     // ✅ OK: API keys can be public (handled by API gateway)
+ *     apiKey: process.env.NEXT_PUBLIC_API_KEY,
+ *   }), []);
+ *
+ *   const apiConfig = useMemo(() => ({
+ *     // ✅ OK: Public configuration
+ *     baseURL: process.env.NEXT_PUBLIC_API_URL!,
+ *     timeout: 30000,
+ *     retry: { attempts: 3 },
+ *   }), []);
+ *
+ *   return (
+ *     <ApiProvider envConfig={envConfig} apiConfig={apiConfig}>
+ *       {children}
+ *     </ApiProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Server-side initialization with encryption (Next.js Server Component)
+ * // Use this pattern when you need encryption keys or other sensitive config
+ * import { ApiProvider } from '@plyaz/core';
+ *
+ * export default async function RootLayout({ children }) {
+ *   // Server-only: Get encryption key from server environment
+ *   // ❌ NEVER use NEXT_PUBLIC_* for encryption keys!
+ *   const encryptionKey = process.env.ENCRYPTION_KEY; // Server-only
+ *
+ *   const envConfig = {
+ *     env: process.env.NODE_ENV as 'production',
+ *   };
+ *
+ *   const apiConfig = {
+ *     baseURL: process.env.NEXT_PUBLIC_API_URL!,
+ *     // ✅ Correct encryption key shape
+ *     encryption: {
+ *       enabled: true,
+ *       key: {
+ *         id: 'prod-key-v1',
+ *         key: encryptionKey!, // From server environment
+ *         algorithm: 'AES-GCM' as const,
+ *         format: 'raw' as const,
+ *       },
+ *       // Optional: Specify fields to encrypt
+ *       fields: [
+ *         '*.email',
+ *         '*.ssn',
+ *         'user.*.phone',
+ *         'payment.cardNumber',
+ *       ],
+ *     },
+ *   };
+ *
+ *   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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "author": "Redeemer Pace",
   "license": "ISC",
   "description": "Provides shared TypeScript types and schema utilities for validation and parsing in the @playz ecosystem.",