@plyaz/types 1.9.3 → 1.10.0

package/dist/api/config/types.d.ts

@@ -16,6 +16,7 @@ import type { NETWORK_QUALITY } from '../network';
 import type { HeaderEventHandlers, NetworkEventHandlers, ConfigEventHandlers, ClientEventHandlers, CacheEventHandlers, PerformanceEventHandlers } from '../events';
 import type { ApiClientOptions } from '../client';
 import type { DebugEventsConfig } from '../debugger';
+import type { EncryptionConfig } from '../encryption';
 /**
  * HTTP Methods - extend from fetchff but uppercase
  */
@@ -246,6 +247,61 @@ export interface ApiConfig extends Partial<Omit<FetchffRequestConfig, 'retry' |
      * ```
      */
     enrichedHeaders?: EnrichedHeadersOptions;
+    /**
+     * Request/response encryption configuration for sensitive data
+     * Automatically encrypts specified fields in body, query params, or headers
+     * Supports AES-GCM, AES-CBC, and ChaCha20-Poly1305 algorithms
+     *
+     * **Primary Use Case: Per-Request via serviceOptions**
+     * ```typescript
+     * // In hooks/services - most common pattern
+     * const { data } = useCampaigns(
+     *   ['campaigns'],
+     *   { status: 'active' },
+     *   {
+     *     apiConfig: {
+     *       encryption: {
+     *         enabled: true,
+     *         fields: ['participants.*.email', 'rewards.*.wallet'],
+     *         key: encryptionKey
+     *       }
+     *     }
+     *   }
+     * );
+     *
+     * // Or in service functions
+     * const campaign = await fetchCampaign('id', {
+     *   apiConfig: {
+     *     encryption: {
+     *       enabled: true,
+     *       algorithm: 'AES-GCM',
+     *       fields: ['user.ssn', 'payment.cardNumber'],
+     *       target: ['body', 'query'],
+     *       key: {
+     *         id: 'prod-key-v1',
+     *         key: await getEncryptionKey(),
+     *         algorithm: 'AES-GCM'
+     *       }
+     *     }
+     *   }
+     * });
+     * ```
+     *
+     * **Global Client Configuration (Less Common)**
+     * ```typescript
+     * const api = createApiClient({
+     *   encryption: {
+     *     enabled: true,
+     *     fields: ['*.ssn', '*.cardNumber'], // All ssn/cardNumber fields
+     *     key: () => getEncryptionKey(), // Dynamic key provider
+     *     autoDecrypt: true
+     *   }
+     * });
+     * ```
+     *
+     * @see EncryptionConfig for full configuration options
+     */
+    encryption?: EncryptionConfig;
     /**
      * Event handlers for header changes, conflicts, and overrides
      * Track all header modifications throughout the request lifecycle

package/dist/api/debugger/enums.d.ts

@@ -82,6 +82,7 @@ export declare const DEBUGGER_CONFIG_SOURCES: {
     readonly USER_HEADERS: "userHeaders";
     readonly INTERCEPTOR: "interceptor";
     readonly CONTEXT_HEADERS: "contextHeaders";
+    readonly ENCRYPTION: "encryption";
 };
 /**
  * Debug history entry types

package/dist/api/encryption/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Encryption Module
+ * Exports for encryption types and interfaces
+ */
+export type * from './types';

package/dist/api/encryption/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Encryption Types
+ * Types for automatic request/response encryption
+ */
+/**
+ * Supported encryption algorithms
+ * Using Web Crypto API compatible algorithms
+ */
+export type EncryptionAlgorithm = 'AES-GCM' | 'AES-CBC' | 'ChaCha20-Poly1305';
+/**
+ * Key format for encryption
+ */
+export type KeyFormat = 'raw' | 'jwk' | 'base64';
+/**
+ * Encryption key configuration
+ */
+export interface EncryptionKey {
+    /**
+     * Key identifier for key rotation
+     * Used to identify which key was used for encryption
+     */
+    id: string;
+    /**
+     * The encryption key
+     * Can be CryptoKey, base64 string, or JWK
+     */
+    key: CryptoKey | string | JsonWebKey;
+    /**
+     * Key format (defaults to 'raw' for strings)
+     */
+    format?: KeyFormat;
+    /**
+     * Algorithm this key is used for
+     */
+    algorithm: EncryptionAlgorithm;
+}
+/**
+ * Key provider function for dynamic key retrieval
+ * Useful for key rotation and multi-tenant scenarios
+ */
+export type KeyProvider = (context?: EncryptionContext) => Promise<EncryptionKey> | EncryptionKey;
+/**
+ * Context passed to key provider
+ */
+export interface EncryptionContext {
+    /**
+     * Request URL (optional if not available)
+     */
+    url?: string;
+    /**
+     * HTTP method (optional if not available)
+     */
+    method?: string;
+    /**
+     * Tenant ID (for multi-tenant)
+     */
+    tenantId?: string;
+    /**
+     * User ID
+     */
+    userId?: string;
+    /**
+     * Custom metadata
+     */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Field path specification for nested objects
+ * Examples: 'user.ssn', 'payment.cardNumber', 'data.*.sensitive'
+ */
+export type FieldPath = string;
+/**
+ * Target for encryption (where to apply encryption)
+ */
+export type EncryptionTarget = 'body' | 'params' | 'headers' | 'all';
+/**
+ * Encrypted field metadata
+ */
+export interface EncryptedFieldMetadata {
+    /**
+     * Indicates this field is encrypted
+     */
+    encrypted: true;
+    /**
+     * Algorithm used
+     */
+    algorithm: EncryptionAlgorithm;
+    /**
+     * Key ID used for encryption (for key rotation)
+     */
+    keyId: string;
+    /**
+     * Initialization vector (base64)
+     */
+    iv: string;
+    /**
+     * Encrypted value (base64)
+     */
+    value: string;
+    /**
+     * Optional auth tag for authenticated encryption (base64)
+     */
+    authTag?: string;
+}
+/**
+ * Encryption configuration for API requests
+ */
+export interface EncryptionConfig {
+    /**
+     * Enable encryption
+     */
+    enabled: boolean;
+    /**
+     * Encryption algorithm to use
+     * @default 'AES-GCM'
+     */
+    algorithm?: EncryptionAlgorithm;
+    /**
+     * Encryption key or key provider
+     * For key rotation, use KeyProvider function
+     */
+    key: EncryptionKey | KeyProvider;
+    /**
+     * Fields to encrypt (supports dot notation for nested fields)
+     * Examples:
+     * - ['ssn', 'cardNumber'] - encrypts these fields in body
+     * - ['user.password', 'data.sensitive'] - nested fields
+     * - ['*.ssn'] - all ssn fields at any level
+     *
+     * If not specified, encrypts entire payload
+     */
+    fields?: FieldPath[];
+    /**
+     * Where to apply encryption
+     * @default 'body'
+     */
+    target?: EncryptionTarget | EncryptionTarget[];
+    /**
+     * Automatically decrypt responses
+     * Looks for fields with EncryptedFieldMetadata structure
+     * @default true
+     */
+    autoDecrypt?: boolean;
+    /**
+     * Include metadata in encrypted fields
+     * If true, replaces field value with EncryptedFieldMetadata object
+     * If false, replaces with encrypted string only
+     * @default true
+     */
+    includeMetadata?: boolean;
+    /**
+     * Skip encryption for specific fields
+     * Useful when encrypting 'all' but want to exclude some fields
+     */
+    excludeFields?: FieldPath[];
+    /**
+     * Custom encryption function
+     * Override default encryption logic
+     */
+    encrypt?: (data: unknown, key: EncryptionKey, context?: EncryptionContext) => Promise<string | EncryptedFieldMetadata>;
+    /**
+     * Custom decryption function
+     * Override default decryption logic
+     */
+    decrypt?: (encrypted: string | EncryptedFieldMetadata, key: EncryptionKey, context?: EncryptionContext) => Promise<unknown>;
+    /**
+     * Error handling strategy
+     * - 'throw': Throw error on encryption failure
+     * - 'skip': Skip encryption on error, send plain data
+     * - 'placeholder': Replace with placeholder on error
+     * @default 'throw'
+     */
+    onError?: 'throw' | 'skip' | 'placeholder';
+    /**
+     * Placeholder value when onError is 'placeholder'
+     * @default '[ENCRYPTION_FAILED]'
+     */
+    errorPlaceholder?: string;
+}
+/**
+ * Encryption statistics and metrics
+ */
+export interface EncryptionMetrics {
+    /**
+     * Total fields encrypted
+     */
+    fieldsEncrypted: number;
+    /**
+     * Total fields decrypted
+     */
+    fieldsDecrypted: number;
+    /**
+     * Encryption time in milliseconds
+     */
+    encryptionTime: number;
+    /**
+     * Decryption time in milliseconds
+     */
+    decryptionTime: number;
+    /**
+     * Key ID used
+     */
+    keyId: string;
+    /**
+     * Algorithm used
+     */
+    algorithm: EncryptionAlgorithm;
+    /**
+     * Errors encountered
+     */
+    errors: Array<{
+        field: string;
+        error: string;
+    }>;
+}
+/**
+ * Result of encryption operation
+ */
+export interface EncryptionResult<T = unknown> {
+    /**
+     * Encrypted data
+     */
+    data: T;
+    /**
+     * Encryption metrics
+     */
+    metrics: EncryptionMetrics;
+    /**
+     * Original data (for debugging, only in dev mode)
+     */
+    original?: T;
+}

package/dist/api/index.cjs

@@ -876,7 +876,8 @@ var DEBUGGER_CONFIG_SOURCES = {
   ENRICHED_HEADERS: "enrichedHeaders",
   USER_HEADERS: "userHeaders",
   INTERCEPTOR: "interceptor",
-  CONTEXT_HEADERS: "contextHeaders"
+  CONTEXT_HEADERS: "contextHeaders",
+  ENCRYPTION: "encryption"
 };
 var HISTORY_TYPES = {
   CONFIG: "config",