@katlux/providers 0.1.1-alpha.129 → 0.1.1-alpha.130

package/dist/index.d.mts

@@ -1,3 +1,66 @@
+declare enum EDataFilterOperator {
+    Equal = "==",
+    NotEqual = "!=",
+    GreaterThan = ">",
+    LessThan = "<",
+    GreaterThanOrEqual = ">=",
+    LessThanOrEqual = "<=",
+    In = "in",
+    NotIn = "nin",
+    And = "and",
+    Or = "or",
+    Nand = "nand",
+    Nor = "nor"
+}
+interface IDataFilter {
+    operator: EDataFilterOperator;
+    field: TDataRow | IDataFilter | IDataFilter[];
+    active: boolean;
+}
+interface IDataSort {
+    field: string;
+    direction: 'asc' | 'desc';
+}
+
+declare enum ECacheStrategy {
+    Application = "Application",
+    ServerSession = "ServerSession",
+    BrowserSession = "BrowserSession",
+    Memory = "Memory",
+    LocalStorage = "LocalStorage",
+    IndexedDB = "IndexedDB",
+    Cookie = "Cookie"
+}
+interface ICacheEntry<T> {
+    data: T;
+    timestamp: number;
+    lifetime: number;
+    lastAccessed?: number;
+    accessCount?: number;
+}
+interface ICacheQuotaOptions {
+    maxEntries?: number;
+    maxSizeBytes?: number;
+    quotaThresholdRatio?: number;
+    fallbackToMemory?: boolean;
+}
+interface ICookieCacheOptions {
+    /** Default: 'lax'. */
+    sameSite?: 'strict' | 'lax' | 'none';
+    /**
+     * Adds the `Secure` flag. Default: auto-detected from the request protocol
+     * (https => true). Set explicitly to force it on or off.
+     */
+    secure?: boolean;
+    /**
+     * Default: true. Only effective for cookies written on the server: browsers
+     * do not allow `document.cookie` to set HttpOnly, so client writes ignore it.
+     */
+    httpOnly?: boolean;
+    /** Default: '/'. */
+    path?: string;
+}
+
 interface IEncryptedPayload {
     __encrypted: true;
     ciphertext: string;
@@ -25,192 +88,7 @@ interface IDecryptErrorInfo {
     index?: number;
 }
 declare const DECRYPT_ERROR_SENTINEL: unique symbol;
-interface IEncryptionContext {
-    url?: string;
-    method?: string;
-    isServer?: boolean;
-    /** Whether to bind the request context (URL and method as `req:${method}:${url}`) into AEAD Authenticated Additional Data (AAD) */
-    bindRequestContextAad?: boolean;
-    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
-    fields?: string[];
-    /**
-     * Enforces strict encryption validation. When true:
-     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
-     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
-     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
-     */
-    strict?: boolean;
-    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
-    allowedAlgorithms?: string[];
-    /** Whitelist of allowed Key Identifiers (kid). */
-    allowedKids?: string[];
-    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
-    keys?: Record<string, TKeyProvider | IKeyPair>;
-    /** Active key identifier from `keys` to use for all outbound encryption operations */
-    activeKid?: string;
-    /**
-     * Hook invoked whenever decryption fails for an individual field or row.
-     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
-     */
-    onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
-    key?: TKeyProvider | IKeyPair;
-    /** Optional Key Identifier for multi-role key routing and rotation */
-    kid?: string;
-    keyId?: string;
-    /**
-     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
-     * Can be static string/buffer or dynamic callback evaluated per record and field.
-     */
-    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
-    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
-    aadFields?: string[];
-    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
-    baseAad?: string;
-    /** Internal flag indicating that key derivation has already been warmed for this batch */
-    _warmedKey?: any;
-    /** Whether to encrypt/decrypt individual values while preserving JSON keys (default: true) */
-    valueEncryption?: boolean;
-    publicKey?: CryptoKey;
-    privateKey?: CryptoKey;
-    recipientPublicKey?: CryptoKey;
-    recipientPrivateKey?: CryptoKey;
-    curve?: 'P-256' | 'P-384' | 'P-521';
-    kdf?: 'none' | 'pbkdf2' | 'hkdf';
-    kdfSalt?: string | Uint8Array | ArrayBuffer;
-    kdfIterations?: number;
-    kdfHash?: 'SHA-256' | 'SHA-512';
-    info?: string | Uint8Array | ArrayBuffer;
-}
-/**
- * Context options for single scalar field encryption/decryption with bound AAD.
- */
-interface IFieldEncryptionContext extends Omit<IEncryptionContext, 'aadFields'> {
-    /** Record identifier to bind into AAD */
-    recordId?: string | number;
-    /** Target field name being encrypted/decrypted */
-    fieldName?: string;
-    /** Sibling record fields (map or array of keys) to deterministically bind into AEAD */
-    aadFields?: Record<string, any> | string[];
-    /** Optional base AAD prefix */
-    baseAad?: string;
-}
-interface IEncryptionProvider {
-    encrypt(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload | any>;
-    decrypt(payload: IEncryptedPayload | any, options?: IEncryptionContext): Promise<any>;
-    /** Encrypts a single scalar value with contextual AAD binding */
-    encryptField?(value: any, context?: IFieldEncryptionContext): Promise<IEncryptedPayload>;
-    /** Decrypts a single scalar field envelope with contextual AAD */
-    decryptField?(envelope: IEncryptedPayload, context?: IFieldEncryptionContext): Promise<any>;
-    /** Computes deterministic HMAC-SHA256 blind index hash */
-    computeBlindIndex?(value: any, hmacKey?: CryptoKey | TKeyProvider): Promise<string>;
-    warmupKey?(options?: IEncryptionContext): Promise<void>;
-    isEncrypted?(payload: any): boolean;
-    setDefaultKey?(key: TKeyProvider | IKeyPair): void;
-    setKeyring?(keys: Record<string, TKeyProvider | IKeyPair>, activeKid?: string): void;
-    getKeyring?(): Record<string, TKeyProvider | IKeyPair> | undefined;
-    setActiveKid?(kid: string): void;
-    getActiveKid?(): string | undefined;
-    clearKeys?(): void;
-    dispose?(): void;
-    [Symbol.dispose]?(): void;
-    [Symbol.asyncDispose]?(): Promise<void>;
-}
-interface IProviderEncryptionOptions {
-    /** Enable or disable encryption */
-    enabled?: boolean;
-    /** Secret key, passphrase, CryptoKey, key pair, or async key provider function */
-    key?: TKeyProvider | IKeyPair;
-    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
-    keys?: Record<string, TKeyProvider | IKeyPair>;
-    /** Active key identifier from `keys` to use for all outbound encryption operations */
-    activeKid?: string;
-    /** Optional Key Identifier for multi-role key routing and key rotation */
-    kid?: string;
-    keyId?: string;
-    /**
-     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
-     * Can be static string/buffer or dynamic callback evaluated per record and field.
-     */
-    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
-    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
-    aadFields?: string[];
-    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
-    baseAad?: string;
-    /**
-     * Whether to bind the request context (HTTP method and URL as `req:${method}:${url}`) into AEAD Authenticated Additional Data (AAD).
-     * Defaults to true when URL or method is provided in context, mitigating replay and cross-endpoint confusion attacks (BUG-015).
-     * Set to false to disable request context AAD binding.
-     */
-    bindRequestContextAad?: boolean;
-    /**
-     * Whether decryption is permitted during Server-Side Rendering (SSR).
-     * In an End-to-End (E2E) zero-trust model, defaults to false to prevent
-     * plaintext data in server memory or SSR payloads.
-     */
-    decryptOnSSR?: boolean;
-    /** Whether to encrypt/decrypt individual values while preserving JSON object keys (default: true) */
-    valueEncryption?: boolean;
-    /** Whether to defer row/item decryption to active page rendering in DataProviders */
-    lazy?: boolean;
-    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
-    fields?: string[];
-    /**
-     * Enforces strict encryption validation. When true:
-     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
-     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
-     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
-     */
-    strict?: boolean;
-    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
-    allowedAlgorithms?: string[];
-    /** Whitelist of allowed Key Identifiers (kid). */
-    allowedKids?: string[];
-    /**
-     * Hook invoked whenever decryption fails for an individual field or row.
-     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
-     */
-    onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
-    /** Enable HMAC-SHA256 blind indexing and trigram search index on encrypted fields for local DataProviders */
-    searchIndex?: boolean;
-    /**
-     * Set to true if API endpoints or data sources return pre-encrypted ciphertext envelopes.
-     * When true, DataProviders decrypt search fields during ingest to populate CSearchIndex.
-     */
-    preEncrypted?: boolean;
-    /** Optional dedicated HMAC key for search indexing (defaults to encryption key if omitted) */
-    hmacKey?: TKeyProvider;
-    /** Cryptographic algorithm identifier (defaults to 'AES-GCM') */
-    algorithm?: 'AES-GCM' | string;
-    /** Custom cipher adapter implementing IEncryptionProvider (e.g. CRSAEncryptionProvider, CECDHEncryptionProvider, CWebCryptoAESCBCProvider) */
-    customProvider?: IEncryptionProvider;
-    /** Whether to use synchronous Node.js crypto provider (CNodeCryptoEncryptionProvider) */
-    sync?: boolean;
-    /**
-     * Key Derivation Function strategy ('none' | 'pbkdf2' | 'hkdf'). Defaults to 'pbkdf2'.
-     * - 'pbkdf2': Recommended for human passphrases/passwords (OWASP recommended with work factor iterations).
-     * - 'hkdf': For deriving subkeys from high-entropy cryptographic keys or secrets (not for low-entropy human passwords).
-     * - 'none': Direct key import for raw high-entropy 256-bit symmetric keys or CryptoKeys.
-     */
-    kdf?: 'none' | 'pbkdf2' | 'hkdf';
-    /** Number of PBKDF2 iterations (default: 310,000 per OWASP recommendation) */
-    kdfIterations?: number;
-    /** Hash algorithm for PBKDF2 or HKDF ('SHA-256' | 'SHA-512', default: 'SHA-256') */
-    kdfHash?: 'SHA-256' | 'SHA-512';
-    /** Optional static salt for KDF. If omitted, a cryptographically secure random salt is generated and included in the envelope. */
-    kdfSalt?: string | Uint8Array | ArrayBuffer;
-    /** Optional public key for asymmetric providers */
-    publicKey?: CryptoKey;
-    /** Optional private key for asymmetric providers */
-    privateKey?: CryptoKey;
-    /** Optional recipient public key for asymmetric/hybrid encryption */
-    recipientPublicKey?: CryptoKey;
-    /** Optional recipient private key for asymmetric/hybrid decryption */
-    recipientPrivateKey?: CryptoKey;
-    /** Elliptic curve name for ECDH ('P-256' | 'P-384' | 'P-521') */
-    curve?: 'P-256' | 'P-384' | 'P-521';
-    /** Optional context/info string or buffer for HKDF key derivation */
-    info?: string | Uint8Array | ArrayBuffer;
-}
+
 /**
  * Public and private key pair container for asymmetric / hybrid encryption providers (RSA, ECDH).
  */
@@ -478,6 +356,194 @@ interface IVerifyAndPinResult {
     /** Public key fingerprint of the verified key */
     fingerprint: string;
 }
+
+interface IEncryptionContext {
+    url?: string;
+    method?: string;
+    isServer?: boolean;
+    /** Whether to bind the request context (URL and method as `req:${method}:${url}`) into AEAD Authenticated Additional Data (AAD) */
+    bindRequestContextAad?: boolean;
+    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
+    fields?: string[];
+    /**
+     * Enforces strict encryption validation. When true:
+     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
+     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
+     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
+     */
+    strict?: boolean;
+    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
+    allowedAlgorithms?: string[];
+    /** Whitelist of allowed Key Identifiers (kid). */
+    allowedKids?: string[];
+    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
+    keys?: Record<string, TKeyProvider | IKeyPair>;
+    /** Active key identifier from `keys` to use for all outbound encryption operations */
+    activeKid?: string;
+    /**
+     * Hook invoked whenever decryption fails for an individual field or row.
+     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
+     */
+    onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
+    key?: TKeyProvider | IKeyPair;
+    /** Optional Key Identifier for multi-role key routing and rotation */
+    kid?: string;
+    keyId?: string;
+    /**
+     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
+     * Can be static string/buffer or dynamic callback evaluated per record and field.
+     */
+    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
+    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
+    aadFields?: string[];
+    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
+    baseAad?: string;
+    /** Internal flag indicating that key derivation has already been warmed for this batch */
+    _warmedKey?: any;
+    /** Whether to encrypt/decrypt individual values while preserving JSON keys (default: true) */
+    valueEncryption?: boolean;
+    publicKey?: CryptoKey;
+    privateKey?: CryptoKey;
+    recipientPublicKey?: CryptoKey;
+    recipientPrivateKey?: CryptoKey;
+    curve?: 'P-256' | 'P-384' | 'P-521';
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    kdfIterations?: number;
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    info?: string | Uint8Array | ArrayBuffer;
+}
+/**
+ * Context options for single scalar field encryption/decryption with bound AAD.
+ */
+interface IFieldEncryptionContext extends Omit<IEncryptionContext, 'aadFields'> {
+    /** Record identifier to bind into AAD */
+    recordId?: string | number;
+    /** Target field name being encrypted/decrypted */
+    fieldName?: string;
+    /** Sibling record fields (map or array of keys) to deterministically bind into AEAD */
+    aadFields?: Record<string, any> | string[];
+    /** Optional base AAD prefix */
+    baseAad?: string;
+}
+interface IEncryptionProvider {
+    encrypt(data: any, options?: IEncryptionContext): Promise<IEncryptedPayload | any>;
+    decrypt(payload: IEncryptedPayload | any, options?: IEncryptionContext): Promise<any>;
+    /** Encrypts a single scalar value with contextual AAD binding */
+    encryptField?(value: any, context?: IFieldEncryptionContext): Promise<IEncryptedPayload>;
+    /** Decrypts a single scalar field envelope with contextual AAD */
+    decryptField?(envelope: IEncryptedPayload, context?: IFieldEncryptionContext): Promise<any>;
+    /** Computes deterministic HMAC-SHA256 blind index hash */
+    computeBlindIndex?(value: any, hmacKey?: CryptoKey | TKeyProvider): Promise<string>;
+    warmupKey?(options?: IEncryptionContext): Promise<void>;
+    isEncrypted?(payload: any): boolean;
+    setDefaultKey?(key: TKeyProvider | IKeyPair): void;
+    setKeyring?(keys: Record<string, TKeyProvider | IKeyPair>, activeKid?: string): void;
+    getKeyring?(): Record<string, TKeyProvider | IKeyPair> | undefined;
+    setActiveKid?(kid: string): void;
+    getActiveKid?(): string | undefined;
+    clearKeys?(): void;
+    dispose?(): void;
+    [Symbol.dispose]?(): void;
+    [Symbol.asyncDispose]?(): Promise<void>;
+}
+interface IProviderEncryptionOptions {
+    /** Enable or disable encryption */
+    enabled?: boolean;
+    /** Secret key, passphrase, CryptoKey, key pair, or async key provider function */
+    key?: TKeyProvider | IKeyPair;
+    /** Built-in Keyring dictionary mapping Key Identifiers (kid) to keys or key provider functions */
+    keys?: Record<string, TKeyProvider | IKeyPair>;
+    /** Active key identifier from `keys` to use for all outbound encryption operations */
+    activeKid?: string;
+    /** Optional Key Identifier for multi-role key routing and key rotation */
+    kid?: string;
+    keyId?: string;
+    /**
+     * Authenticated Additional Data (AAD) bound to the ciphertext to prevent field/record swapping.
+     * Can be static string/buffer or dynamic callback evaluated per record and field.
+     */
+    aad?: string | Uint8Array | ArrayBuffer | ((record: any, field: string) => string | Uint8Array | ArrayBuffer);
+    /** Sibling record fields to deterministically bind into AEAD additional data (e.g. ['contact_id', 'version']) */
+    aadFields?: string[];
+    /** Optional base AAD prefix when aadFields or dynamic aad is enabled */
+    baseAad?: string;
+    /**
+     * Whether to bind the request context (HTTP method and URL as `req:${method}:${url}`) into AEAD Authenticated Additional Data (AAD).
+     * Defaults to true when URL or method is provided in context, mitigating replay and cross-endpoint confusion attacks (BUG-015).
+     * Set to false to disable request context AAD binding.
+     */
+    bindRequestContextAad?: boolean;
+    /**
+     * Whether decryption is permitted during Server-Side Rendering (SSR).
+     * In an End-to-End (E2E) zero-trust model, defaults to false to prevent
+     * plaintext data in server memory or SSR payloads.
+     */
+    decryptOnSSR?: boolean;
+    /** Whether to encrypt/decrypt individual values while preserving JSON object keys (default: true) */
+    valueEncryption?: boolean;
+    /** Whether to defer row/item decryption to active page rendering in DataProviders */
+    lazy?: boolean;
+    /** Whitelist of specific field names to encrypt/decrypt (e.g. ['name', 'surname']). Any unlisted field remains plaintext. */
+    fields?: string[];
+    /**
+     * Enforces strict encryption validation. When true:
+     * 1. Any field in `fields` that is NOT an encrypted envelope triggers a decryption error.
+     * 2. Envelope algorithm MUST match `allowedAlgorithms` (defaults to ['AES-GCM']).
+     * 3. Envelope `kid` (if present) MUST match `allowedKids`.
+     */
+    strict?: boolean;
+    /** Whitelist of permitted cryptographic algorithms (e.g. ['AES-GCM']). Defaults to ['AES-GCM'] in strict mode. */
+    allowedAlgorithms?: string[];
+    /** Whitelist of allowed Key Identifiers (kid). */
+    allowedKids?: string[];
+    /**
+     * Hook invoked whenever decryption fails for an individual field or row.
+     * Can return a fallback cell value (e.g. sentinel or marker), or string/boolean.
+     */
+    onDecryptError?: ((info: IDecryptErrorInfo) => any) | boolean | string;
+    /** Enable HMAC-SHA256 blind indexing and trigram search index on encrypted fields for local DataProviders */
+    searchIndex?: boolean;
+    /**
+     * Set to true if API endpoints or data sources return pre-encrypted ciphertext envelopes.
+     * When true, DataProviders decrypt search fields during ingest to populate CSearchIndex.
+     */
+    preEncrypted?: boolean;
+    /** Optional dedicated HMAC key for search indexing (defaults to encryption key if omitted) */
+    hmacKey?: TKeyProvider;
+    /** Cryptographic algorithm identifier (defaults to 'AES-GCM') */
+    algorithm?: 'AES-GCM' | string;
+    /** Custom cipher adapter implementing IEncryptionProvider (e.g. CRSAEncryptionProvider, CECDHEncryptionProvider, CWebCryptoAESCBCProvider) */
+    customProvider?: IEncryptionProvider;
+    /** Whether to use synchronous Node.js crypto provider (CNodeCryptoEncryptionProvider) */
+    sync?: boolean;
+    /**
+     * Key Derivation Function strategy ('none' | 'pbkdf2' | 'hkdf'). Defaults to 'pbkdf2'.
+     * - 'pbkdf2': Recommended for human passphrases/passwords (OWASP recommended with work factor iterations).
+     * - 'hkdf': For deriving subkeys from high-entropy cryptographic keys or secrets (not for low-entropy human passwords).
+     * - 'none': Direct key import for raw high-entropy 256-bit symmetric keys or CryptoKeys.
+     */
+    kdf?: 'none' | 'pbkdf2' | 'hkdf';
+    /** Number of PBKDF2 iterations (default: 310,000 per OWASP recommendation) */
+    kdfIterations?: number;
+    /** Hash algorithm for PBKDF2 or HKDF ('SHA-256' | 'SHA-512', default: 'SHA-256') */
+    kdfHash?: 'SHA-256' | 'SHA-512';
+    /** Optional static salt for KDF. If omitted, a cryptographically secure random salt is generated and included in the envelope. */
+    kdfSalt?: string | Uint8Array | ArrayBuffer;
+    /** Optional public key for asymmetric providers */
+    publicKey?: CryptoKey;
+    /** Optional private key for asymmetric providers */
+    privateKey?: CryptoKey;
+    /** Optional recipient public key for asymmetric/hybrid encryption */
+    recipientPublicKey?: CryptoKey;
+    /** Optional recipient private key for asymmetric/hybrid decryption */
+    recipientPrivateKey?: CryptoKey;
+    /** Elliptic curve name for ECDH ('P-256' | 'P-384' | 'P-521') */
+    curve?: 'P-256' | 'P-384' | 'P-521';
+    /** Optional context/info string or buffer for HKDF key derivation */
+    info?: string | Uint8Array | ArrayBuffer;
+}
+
 /**
  * Lifecycle status for blind-index HMAC keys in a multi-KID keyring.
  */
@@ -653,144 +719,8 @@ interface IMigrationSummary {
     durationMs: number;
 }
 
-/**
- * types.ts — Framework-agnostic hydration and platform abstraction contracts.
- */
-interface ISSRHydrationAdapter {
-    /**
-     * Retrieve pre-hydrated SSR state for a key. Returns null if not present.
-     */
-    getSSRData<T>(key: string, context?: any): T | null;
-    /**
-     * Execute fetcher with SSR serialization/caching if in an SSR environment,
-     * or simply await fetcher() in standalone/client environments.
-     */
-    fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
-    /**
-     * Invalidate or clear SSR cache for a key (e.g. after mutations).
-     */
-    clearSSRData?(key: string, context?: any): void;
-    /**
-     * Extract SSR hydration payload dictionary (for cache initialization).
-     */
-    getSSRPayload?(context?: any): Record<string, any> | null;
-}
-interface IPlatformRouter {
-    getRoute(): {
-        query: Record<string, any>;
-        path?: string;
-    } | null;
-    getRouter(): any;
-    onReady?(cb: () => void): void;
-}
-
-type TDataProviderListener<T = any> = (provider: T) => void;
+type TDataProviderListener<T = unknown> = (provider: T) => void;
 type TUnsubscribe = () => void;
-declare enum EDataFilterOperator {
-    Equal = "==",
-    NotEqual = "!=",
-    GreaterThan = ">",
-    LessThan = "<",
-    GreaterThanOrEqual = ">=",
-    LessThanOrEqual = "<=",
-    In = "in",
-    NotIn = "nin",
-    And = "and",
-    Or = "or",
-    Nand = "nand",
-    Nor = "nor"
-}
-declare enum ECacheStrategy {
-    Application = "Application",
-    ServerSession = "ServerSession",
-    BrowserSession = "BrowserSession",
-    Memory = "Memory",
-    LocalStorage = "LocalStorage",
-    IndexedDB = "IndexedDB",
-    Cookie = "Cookie"
-}
-interface ICacheEntry<T> {
-    data: T;
-    timestamp: number;
-    lifetime: number;
-    lastAccessed?: number;
-    accessCount?: number;
-}
-interface ICacheQuotaOptions {
-    maxEntries?: number;
-    maxSizeBytes?: number;
-    quotaThresholdRatio?: number;
-    fallbackToMemory?: boolean;
-}
-interface ICookieCacheOptions {
-    /** Default: 'lax'. */
-    sameSite?: 'strict' | 'lax' | 'none';
-    /**
-     * Adds the `Secure` flag. Default: auto-detected from the request protocol
-     * (https => true). Set explicitly to force it on or off.
-     */
-    secure?: boolean;
-    /**
-     * Default: true. Only effective for cookies written on the server: browsers
-     * do not allow `document.cookie` to set HttpOnly, so client writes ignore it.
-     */
-    httpOnly?: boolean;
-    /** Default: '/'. */
-    path?: string;
-}
-interface IRequestOptions {
-    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-    body?: any;
-    headers?: Record<string, string>;
-    cacheStrategy?: ECacheStrategy;
-    lifetime?: number;
-    key?: string;
-    cacheKey?: string;
-    query?: Record<string, any>;
-    deduplicate?: boolean;
-    context?: any;
-    disableCache?: boolean;
-    queue?: boolean;
-    queueLabel?: string;
-    label?: string;
-    tags?: string[];
-    signal?: AbortSignal;
-    _generation?: number;
-    encryption?: IProviderEncryptionOptions;
-    /** If true, returns raw response without decrypting, useful for DataProvider lazy page-level decryption */
-    skipDecryption?: boolean;
-    credentials?: RequestCredentials;
-}
-/** Queue persistence backend with automatic fallback: IndexedDB → LocalStorage → Memory */
-declare enum EQueueStorage {
-    Memory = "Memory",
-    LocalStorage = "LocalStorage",
-    IndexedDB = "IndexedDB"
-}
-/** Status of an item currently in the pending queue */
-type TQueueItemStatus = 'pending' | 'flushing';
-/** A single mutation operation waiting to be sent */
-interface IQueuedOperation {
-    id: string;
-    url: string;
-    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
-    options: IRequestOptions;
-    tags: string[];
-    label?: string;
-    createdAt: number;
-    flushAttempts: number;
-    status: TQueueItemStatus;
-}
-/** An operation that failed permanently and was moved to the dead-letter store */
-interface IDeadLetterItem extends IQueuedOperation {
-    failedAt: number;
-    lastError: string;
-    httpStatus?: number;
-}
-/** Options for flush operations */
-interface IFlushOptions {
-    tag?: string;
-}
 interface IKDatatableAction {
     action: Function;
     label: string;
@@ -802,15 +732,6 @@ interface IKDatatableAction {
 type TDataRow = {
     [key: string]: any;
 };
-interface IDataFilter {
-    operator: EDataFilterOperator;
-    field: TDataRow | IDataFilter[];
-    active: boolean;
-}
-interface IDataSort {
-    field: string;
-    direction: 'asc' | 'desc';
-}
 interface IDataResult<TRow = TDataRow> {
     rowCount: number;
     rows: TRow[];
@@ -831,7 +752,7 @@ interface IDataProviderOptions {
     cacheStrategy?: ECacheStrategy;
     cacheLifetime?: number;
     deduplicate?: boolean;
-    context?: any;
+    context?: Record<string, unknown>;
     contextKey?: string;
     urlPageParam?: string;
     refreshOnMutation?: boolean;
@@ -847,7 +768,7 @@ interface IDataProviderState<TRow = TDataRow> {
     rowCount?: number;
     loading?: boolean;
     initialLoad?: boolean;
-    error?: any;
+    error?: Error | unknown;
     pageData?: TRow[];
 }
 interface IDataProviderSetStateOptions {
@@ -863,6 +784,60 @@ interface IVirtualScrollState {
     itemHeight: number;
 }
 
+interface IRequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    body?: any;
+    headers?: Record<string, string>;
+    cacheStrategy?: ECacheStrategy;
+    lifetime?: number;
+    key?: string;
+    cacheKey?: string;
+    query?: Record<string, unknown>;
+    deduplicate?: boolean;
+    context?: Record<string, unknown>;
+    disableCache?: boolean;
+    queue?: boolean;
+    queueLabel?: string;
+    label?: string;
+    tags?: string[];
+    signal?: AbortSignal;
+    _generation?: number;
+    encryption?: IProviderEncryptionOptions;
+    /** If true, returns raw response without decrypting, useful for DataProvider lazy page-level decryption */
+    skipDecryption?: boolean;
+    credentials?: RequestCredentials;
+}
+/** Queue persistence backend with automatic fallback: IndexedDB → LocalStorage → Memory */
+declare enum EQueueStorage {
+    Memory = "Memory",
+    LocalStorage = "LocalStorage",
+    IndexedDB = "IndexedDB"
+}
+/** Status of an item currently in the pending queue */
+type TQueueItemStatus = 'pending' | 'flushing';
+/** A single mutation operation waiting to be sent */
+interface IQueuedOperation {
+    id: string;
+    url: string;
+    method: 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    options: IRequestOptions;
+    tags: string[];
+    label?: string;
+    createdAt: number;
+    flushAttempts: number;
+    status: TQueueItemStatus;
+}
+/** An operation that failed permanently and was moved to the dead-letter store */
+interface IDeadLetterItem extends IQueuedOperation {
+    failedAt: number;
+    lastError: string;
+    httpStatus?: number;
+}
+/** Options for flush operations */
+interface IFlushOptions {
+    tag?: string;
+}
+
 interface ITreeNode<TRow = TDataRow> {
     data: TRow;
     id: string | number;
@@ -928,6 +903,7 @@ type TTreePageDataHandler<TRow = TDataRow> = (currentPage: number, pageSize: num
     disableCache?: boolean;
     signal?: AbortSignal;
 }) => IDataResult<TRow> | Promise<IDataResult<TRow>>;
+
 interface KProductItemData {
     id: string | number;
     title: string;
@@ -935,7 +911,7 @@ interface KProductItemData {
     price?: number;
     currency?: string;
     description?: string;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 interface KProductRowAction {
     label: string;
@@ -944,6 +920,37 @@ interface KProductRowAction {
     color?: 'primary' | 'danger' | 'success' | 'warning' | 'info' | 'light' | 'dark' | 'default';
 }
 
+/**
+ * types.ts — Framework-agnostic hydration and platform abstraction contracts.
+ */
+interface ISSRHydrationAdapter {
+    /**
+     * Retrieve pre-hydrated SSR state for a key. Returns null if not present.
+     */
+    getSSRData<T>(key: string, context?: any): T | null;
+    /**
+     * Execute fetcher with SSR serialization/caching if in an SSR environment,
+     * or simply await fetcher() in standalone/client environments.
+     */
+    fetchWithSSR<T>(key: string, fetcher: () => Promise<T>, context?: any): Promise<T | null>;
+    /**
+     * Invalidate or clear SSR cache for a key (e.g. after mutations).
+     */
+    clearSSRData?(key: string, context?: any): void;
+    /**
+     * Extract SSR hydration payload dictionary (for cache initialization).
+     */
+    getSSRPayload?(context?: any): Record<string, any> | null;
+}
+interface IPlatformRouter {
+    getRoute(): {
+        query: Record<string, any>;
+        path?: string;
+    } | null;
+    getRouter(): any;
+    onReady?(cb: () => void): void;
+}
+
 declare abstract class ADataProvider<TRow = TDataRow> {
     idKey: string;
     protected _pageData: TRow[];
@@ -1158,12 +1165,12 @@ declare class CFlatClientDataProvider<TRow = TDataRow> extends AEncryptedClientP
 
 declare abstract class ACacheProvider {
     constructor();
-    abstract getKeyList(context?: any): Array<string> | Promise<Array<string>>;
-    abstract get<T>(key: string, context?: any): Promise<T | null>;
-    abstract set<T>(key: string, data: T, lifetime: number, context?: any): Promise<void>;
-    abstract remove(key: string, context?: any): Promise<void>;
-    abstract removeByPrefix(prefix: string, context?: any): Promise<void>;
-    abstract getRemainingTime(key: string, context?: any): Promise<number | null>;
+    abstract getKeyList(context?: unknown): Array<string> | Promise<Array<string>>;
+    abstract get<T>(key: string, context?: unknown): Promise<T | null>;
+    abstract set<T>(key: string, data: T, lifetime: number, context?: unknown): Promise<void>;
+    abstract remove(key: string, context?: unknown): Promise<void>;
+    abstract removeByPrefix(prefix: string, context?: unknown): Promise<void>;
+    abstract getRemainingTime(key: string, context?: unknown): Promise<number | null>;
     abstract cleanupExpired(): Promise<void>;
 }
 
@@ -1256,9 +1263,9 @@ declare class CAPIFlatClientDataProvider<TRow = TDataRow> extends CFlatClientDat
         disableCache?: boolean;
     }): Promise<void>;
     setAPIUrl(url: string): Promise<void>;
-    create(item: any): Promise<void>;
-    update(item: any): Promise<void>;
-    delete(items: any[]): Promise<void>;
+    create(item: TRow): Promise<void>;
+    update(item: TRow): Promise<void>;
+    delete(items: TRow[]): Promise<void>;
     loadPageData(): Promise<void>;
 }
 
@@ -1297,9 +1304,9 @@ declare class CAPIFlatServerDataProvider<TRow = TDataRow> extends CFlatServerDat
         disableCache?: boolean;
     }): Promise<void>;
     setAPIUrl(url: string): Promise<void>;
-    delete(items: any[]): Promise<void>;
-    create(item: any): Promise<void>;
-    update(item: any): Promise<void>;
+    delete(items: TRow[]): Promise<void>;
+    create(item: TRow): Promise<void>;
+    update(item: TRow): Promise<void>;
 }
 
 declare class CTreeClientDataProvider<TRow extends TDataRow = TDataRow> extends CFlatClientDataProvider<TRow> implements ITreeDataProvider<TRow> {
@@ -1375,9 +1382,9 @@ declare class CAPITreeClientDataProvider<TRow extends TDataRow = TDataRow> exten
     }): Promise<void>;
     private _initialFetch;
     setAPIUrl(url: string): Promise<void>;
-    create(item: any): Promise<void>;
-    update(item: any): Promise<void>;
-    delete(items: any[]): Promise<void>;
+    create(item: TRow): Promise<void>;
+    update(item: TRow): Promise<void>;
+    delete(items: TRow[]): Promise<void>;
     loadPageData(): Promise<void>;
 }
 
@@ -1447,9 +1454,9 @@ declare class CAPITreeServerDataProvider<TRow = TDataRow> extends CTreeServerDat
         disableCache?: boolean;
     }): Promise<void>;
     setAPIUrl(url: string): Promise<void>;
-    delete(items: any[]): Promise<void>;
-    create(item: any): Promise<void>;
-    update(item: any): Promise<void>;
+    delete(items: TRow[]): Promise<void>;
+    create(item: TRow): Promise<void>;
+    update(item: TRow): Promise<void>;
 }
 
 /**