@plyaz/types 1.11.1 → 1.11.2

package/dist/core/services.d.ts

@@ -195,26 +195,75 @@ export interface ApiEnvironmentConfig {
  * - 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 }) {
- *   const envConfig = {
+ *   // 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: process.env.NEXT_PUBLIC_ENCRYPTION_KEY!,
- *         algorithm: 'AES-GCM',
- *         format: 'raw'
- *       }
+ *         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',
+ *       ],
  *     },
  *   };
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plyaz/types",
-  "version": "1.11.1",
+  "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.",