@kaltura-sdk/rtc-avatar 1.32.0

package/src/lib/utils/RequestsDebouncer.d.ts

@@ -0,0 +1,15 @@
+type RequestType = string;
+type Payload = Record<string, unknown>;
+type RequestExecutor<T = unknown> = (payload: Payload) => Promise<T>;
+interface Request<T = unknown> {
+    type: RequestType;
+    payload: Payload;
+    requestExecutor: RequestExecutor<T>;
+}
+export declare class RequestsDebouncer {
+    private requests;
+    addRequest<T>(request: Request<T>): Promise<T | undefined>;
+    private executeRequest;
+    private resolveRequest;
+}
+export {};

package/src/lib/utils/compressedLogger.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Streaming gzip logger that compresses log messages on-the-fly using CompressionStream API.
+ * Uses a producer-consumer pattern where write() writes to the compression stream and
+ * pumpReader() continuously reads compressed chunks into memory.
+ *
+ * @example
+ * const buffer = new CompressedLogger();
+ * buffer.write('User action\n');
+ * const blob = await buffer.snapshot(); // Get compressed logs and reset
+ * await buffer.close(); // Clean up resources
+ */
+/**
+ * Captured at module load, before any console patching. Used throughout the logging
+ * pipeline to avoid re-entering addLog() from internal code paths (infinite loop risk).
+ * Lives here because compressedLogger is the bottom of the import chain, ensuring
+ * the capture happens before LogsCollector patches console methods.
+ */
+export declare const originalConsole: {
+    readonly log: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    readonly info: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    readonly warn: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    readonly error: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    readonly debug: {
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+};
+export declare class CompressedLogger {
+    private readonly encoder;
+    private current;
+    private currentReadDone;
+    /**
+     * Next stream, active during snapshot() drain.
+     * log() routes here while the old stream is closing, eliminating any buffering window.
+     * Null outside of snapshot().
+     */
+    private next;
+    constructor();
+    private createStream;
+    /**
+     * Continuously reads compressed chunks from the stream into the given state object.
+     * Runs asynchronously in the background until the stream is closed.
+     */
+    private pumpReader;
+    /**
+     * Writes a pre-formatted line into the active compression stream.
+     * If snapshot() is in progress, routes to the next stream to avoid any buffering window.
+     *
+     * @param line - A fully formatted log line (caller is responsible for timestamps, formatting, etc.)
+     */
+    write(line: string): void;
+    /**
+     * Closes the compression stream, flushing any remaining data and writing the gzip footer.
+     * After closing, log() calls are ignored. Safe to call multiple times.
+     */
+    close(): Promise<void>;
+    /**
+     * Returns a Blob containing all compressed chunks collected so far.
+     * @returns Blob with 'text/plain' MIME type so that it works with sendBeacon()
+     */
+    getCompressedBlob(): Blob;
+    /**
+     * Returns the total size of compressed data in bytes.
+     */
+    getCompressedSize(): number;
+    /**
+     * Returns the total size of uncompressed data written so far, in bytes.
+     * Updates synchronously on every log() call, unlike getCompressedSize() which lags
+     * behind due to the async compression stream.
+     */
+    getUncompressedSize(): number;
+    /**
+     * Closes the current compression stream, returns compressed logs as a Blob,
+     * then reinitializes for continued logging. Useful for periodic log uploads.
+     *
+     * A new stream is created before the old one closes, so log() calls during
+     * the async drain go directly to the next stream with no buffering.
+     *
+     * @param contextLine - Optional context line to write at the start of the new buffer
+     * @returns Blob containing all logs since last snapshot (or construction)
+     */
+    snapshot(contextLine?: string): Promise<Blob>;
+}

package/src/lib/utils/logBuffer.d.ts

@@ -0,0 +1,47 @@
+import { originalConsole } from './compressedLogger';
+export { originalConsole };
+/**
+ * Maximum payload size for sendBeacon (64KB).
+ */
+export declare const MAX_PAYLOAD_SIZE: number;
+/**
+ * Fraction of MAX_PAYLOAD_SIZE at which logs are automatically flushed and sent.
+ */
+export declare const SEND_COMPRESSED_THRESHOLD: number;
+/**
+ * Conservative estimate of the minimum gzip compression ratio for log text.
+ * Used as a fallback threshold on the uncompressed buffer size, since getCompressedSize()
+ * lags behind due to the async compression stream. Real-world log compression is typically 5–10x.
+ */
+export declare const SEND_UNCOMPRESSED_THRESHOLD: number;
+/**
+ * Owns the dual-buffer (compressed + uncompressed) and threshold logic.
+ * Wraps CompressedLogger for gzip streaming and maintains a parallel plain-text
+ * buffer as an uncompressed fallback.
+ */
+export declare class LogBuffer {
+    private readonly compressedLogger;
+    private uncompressedBuffer;
+    constructor();
+    /**
+     * Single source of truth for log line format across both the compressed and uncompressed buffers.
+     */
+    private static formatLine;
+    /**
+     * Appends a pre-serialized log entry to both the compressed and uncompressed buffers.
+     * Returns true when a size threshold is exceeded, signaling the caller to flush.
+     */
+    addLog(level: string, message: string): boolean;
+    /**
+     * Atomically swaps out both buffers, closes the current compression stream,
+     * and returns the compressed blob alongside the captured uncompressed logs.
+     * The uncompressed buffer is swapped synchronously before the first await so
+     * that any logs written during the async drain go into the fresh buffer.
+     *
+     * @param contextLine - Optional context written at the start of the next compressed buffer.
+     */
+    flush(contextLine?: string): Promise<{
+        blob: Blob;
+        uncompressedLogs: string[];
+    }>;
+}

package/src/lib/utils/logsCollector.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Configuration for the logs collector.
+ */
+export interface LogsCollectorConfig {
+    clientID: string;
+    flowID: string;
+    logsEndpoint: string;
+    socketID: string;
+    additionalContext?: Record<string, unknown>;
+}
+/**
+ * Initializes the logs collector with the provided configuration.
+ * This is the main entry point for using the logs collector.
+ *
+ * @param config - Configuration including clientID, flowID, and logsEndpoint
+ */
+export declare function initializeLogsCollector(config: LogsCollectorConfig): void;
+/**
+ * Manually sends logs to the server.
+ *
+ * @param preventMoreSends - If true, cleans up the collector after sending (no more logs will be sent)
+ */
+export declare function sendLogs(preventMoreSends: boolean): void;
+/**
+ * Cleans up the logs collector: removes event listeners, unsubscribes interceptors, and resets state.
+ * Intended for use in tests.
+ */
+export declare function cleanupLogsCollector(): void;

package/src/lib/utils/runWithRetry.d.ts

@@ -0,0 +1,10 @@
+import { UnisphereLoggerType } from '@unisphere/core';
+/**
+ * Retry a promise-returning function with a delay between attempts.
+ *
+ * @param fn - Async function to call (use a closure to capture arguments)
+ * @param logger - Logger for retry error messages
+ * @param timeoutDuration - Delay in ms between retries (default: 3000)
+ * @param retriesNumber - Max number of attempts (default: 3)
+ */
+export declare function runWithRetry<T>(fn: () => Promise<T>, logger: UnisphereLoggerType, timeoutDuration?: number, retriesNumber?: number): Promise<T>;

package/src/lib/utils/tests/testUtils.d.ts

@@ -0,0 +1,2 @@
+export declare function tryDecompress(blob: Blob): Promise<string>;
+export declare function decompress(blob: Blob): Promise<string>;