@thunderkiller/video-clipper 1.5.6 → 1.6.0

package/dist/utils/cache.d.ts

@@ -1,34 +1,30 @@
+import type { CacheBackend } from './cacheBackend.js';
 import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent, SegmentRefinement } from '../types/index.js';
+export type { CacheBackend };
 /**
- * Disk-backed cache for all pipeline stages.
+ * Facade that wraps a CacheBackend and implements the CacheBackend interface.
  *
- * Constructed once in runner.ts with the resolved cache directory and passed
- * down to each stage that needs caching. Pass `disabled = true` to bypass all
- * reads and writes (equivalent to --no-cache).
+ * This means `Cache` can be passed anywhere a `CacheBackend` is expected, so
+ * all pipeline consumers work whether they type their parameter as `Cache` or
+ * `CacheBackend`. The concrete backend is injected by the factory in
+ * cacheFactory.ts.
+ *
+ * Call `close()` at the end of the pipeline to release backend resources
+ * (important for the MongoDB backend which holds an open connection).
  */
-export declare class Cache {
-    private readonly cacheDir;
-    private readonly disabled;
-    constructor(cacheDir: string, disabled?: boolean);
-    private transcriptPath;
+export declare class Cache implements CacheBackend {
+    readonly backend: CacheBackend;
+    constructor(backend: CacheBackend);
     readTranscript(videoId: string): Promise<TranscriptLine[] | null>;
     writeTranscript(videoId: string, lines: TranscriptLine[]): Promise<void>;
-    private chunkPath;
     readChunk(chunk: LLMChunk, chunkAudioEvents?: AudioEvent[]): Promise<ChunkEvaluation | null>;
     writeChunk(chunk: LLMChunk, evaluation: ChunkEvaluation, chunkAudioEvents?: AudioEvent[]): Promise<void>;
-    private segmentRefinementPath;
     readSegmentRefinement(start: number, end: number, reason: string): Promise<SegmentRefinement | null>;
     writeSegmentRefinement(start: number, end: number, reason: string, refined: SegmentRefinement): Promise<void>;
-    private audioEventPath;
     readAudioEvents(videoId: string, gameProfile: string, provider: string): Promise<AudioEvent[] | null>;
     writeAudioEvents(videoId: string, gameProfile: string, provider: string, events: AudioEvent[]): Promise<void>;
-    /**
-     * Per-chunk audio cache — mirrors the LLM `chunks/` pattern.
-     * Key includes videoId, gameProfile, provider, and the exact window bounds
-     * so each 120s slice is stored independently.
-     */
-    private audioChunkPath;
     readAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number): Promise<AudioEvent[] | null>;
     writeAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number, events: AudioEvent[]): Promise<void>;
+    close(): Promise<void>;
 }
 //# sourceMappingURL=cache.d.ts.map

package/dist/utils/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AA0C3B;;;;;;GAMG;AACH,qBAAa,KAAK;IAEd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,OAAe;IAK5C,OAAO,CAAC,cAAc;IAIhB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;IAKjE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9E,OAAO,CAAC,SAAS;IASX,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAK5B,UAAU,CACd,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,eAAe,EAC3B,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,IAAI,CAAC;IAQhB,OAAO,CAAC,qBAAqB;IAIvB,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAK9B,sBAAsB,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAOhB,OAAO,CAAC,cAAc;IAQhB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAQzB,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAchB,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAQzB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;CAOjB"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,YAAY,EAAE,CAAC;AAE7B;;;;;;;;;;GAUG;AACH,qBAAa,KAAM,YAAW,YAAY;IAC5B,QAAQ,CAAC,OAAO,EAAE,YAAY;gBAArB,OAAO,EAAE,YAAY;IAIpC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;IAIjE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxE,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,gBAAgB,CAAC,EAAE,UAAU,EAAE,GAC9B,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI5B,UAAU,CACd,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,eAAe,EAC3B,gBAAgB,CAAC,EAAE,UAAU,EAAE,GAC9B,OAAO,CAAC,IAAI,CAAC;IAMV,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAI9B,sBAAsB,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAMV,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAIzB,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAMV,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAIzB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAaV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/utils/cache.js

@@ -1,137 +1,57 @@
-import { createHash } from 'node:crypto';
-import { promises as fs } from 'fs';
-import path from 'path';
-import { z } from 'zod';
-import { log } from './logger.js';
-import { TranscriptLineSchema, ChunkEvaluationSchema, AudioEventSchema, SegmentRefinementSchema, } from '../types/index.js';
 /**
- * Serializes audio events into a stable string for cache keying.
- * Events are sorted by time so the key is order-independent.
- */
-function audioEventsKey(events) {
-    if (events.length === 0)
-        return '';
-    const sorted = [...events].sort((a, b) => a.time - b.time);
-    return JSON.stringify(sorted);
-}
-function hashContent(input) {
-    return createHash('sha256').update(input).digest('hex');
-}
-async function readCacheFile(filePath, schema) {
-    try {
-        const raw = await fs.readFile(filePath, 'utf-8');
-        const parsed = schema.safeParse(JSON.parse(raw));
-        if (!parsed.success) {
-            log.warn(`[cache] Corrupt entry at ${filePath} — ignoring`);
-            return null;
-        }
-        return parsed.data;
-    }
-    catch {
-        // File not found or unreadable — normal cache miss, stay silent
-        return null;
-    }
-}
-async function writeCacheFile(filePath, data) {
-    try {
-        await fs.mkdir(path.dirname(filePath), { recursive: true });
-        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
-    }
-    catch (err) {
-        log.warn(`[cache] Failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-/**
- * Disk-backed cache for all pipeline stages.
+ * Facade that wraps a CacheBackend and implements the CacheBackend interface.
+ *
+ * This means `Cache` can be passed anywhere a `CacheBackend` is expected, so
+ * all pipeline consumers work whether they type their parameter as `Cache` or
+ * `CacheBackend`. The concrete backend is injected by the factory in
+ * cacheFactory.ts.
  *
- * Constructed once in runner.ts with the resolved cache directory and passed
- * down to each stage that needs caching. Pass `disabled = true` to bypass all
- * reads and writes (equivalent to --no-cache).
+ * Call `close()` at the end of the pipeline to release backend resources
+ * (important for the MongoDB backend which holds an open connection).
  */
 export class Cache {
-    cacheDir;
-    disabled;
-    constructor(cacheDir, disabled = false) {
-        this.cacheDir = cacheDir;
-        this.disabled = disabled;
-    }
-    // ---- Transcript ---------------------------------------------------------
-    transcriptPath(videoId) {
-        return path.join(this.cacheDir, 'transcript', `${hashContent(videoId)}.json`);
+    backend;
+    constructor(backend) {
+        this.backend = backend;
     }
+    // ---- Transcript -----------------------------------------------------------
     async readTranscript(videoId) {
-        if (this.disabled)
-            return null;
-        return readCacheFile(this.transcriptPath(videoId), z.array(TranscriptLineSchema));
+        return this.backend.readTranscript(videoId);
     }
     async writeTranscript(videoId, lines) {
-        if (this.disabled)
-            return;
-        await writeCacheFile(this.transcriptPath(videoId), lines);
-    }
-    // ---- LLM chunk results --------------------------------------------------
-    chunkPath(chunk, chunkAudioEvents = []) {
-        const audioKey = audioEventsKey(chunkAudioEvents);
-        return path.join(this.cacheDir, 'chunks', `${hashContent(`${chunk.start}|${chunk.end}|${chunk.text}|${audioKey}`)}.json`);
+        return this.backend.writeTranscript(videoId, lines);
     }
-    async readChunk(chunk, chunkAudioEvents = []) {
-        if (this.disabled)
-            return null;
-        return readCacheFile(this.chunkPath(chunk, chunkAudioEvents), ChunkEvaluationSchema);
+    // ---- LLM chunk results ----------------------------------------------------
+    async readChunk(chunk, chunkAudioEvents) {
+        return this.backend.readChunk(chunk, chunkAudioEvents);
     }
-    async writeChunk(chunk, evaluation, chunkAudioEvents = []) {
-        if (this.disabled)
-            return;
-        if (evaluation.status !== 'success')
-            return;
-        await writeCacheFile(this.chunkPath(chunk, chunkAudioEvents), evaluation);
-    }
-    // ---- Segment refinement -------------------------------------------------
-    segmentRefinementPath(start, end, reason) {
-        return path.join(this.cacheDir, 'segments', `${hashContent(`${start}|${end}|${reason}`)}.json`);
+    async writeChunk(chunk, evaluation, chunkAudioEvents) {
+        return this.backend.writeChunk(chunk, evaluation, chunkAudioEvents);
     }
+    // ---- Segment refinement ---------------------------------------------------
     async readSegmentRefinement(start, end, reason) {
-        if (this.disabled)
-            return null;
-        return readCacheFile(this.segmentRefinementPath(start, end, reason), SegmentRefinementSchema);
+        return this.backend.readSegmentRefinement(start, end, reason);
     }
     async writeSegmentRefinement(start, end, reason, refined) {
-        if (this.disabled)
-            return;
-        await writeCacheFile(this.segmentRefinementPath(start, end, reason), refined);
-    }
-    // ---- Audio events (whole-video) -----------------------------------------
-    audioEventPath(videoId, gameProfile, provider) {
-        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}`)}.json`);
+        return this.backend.writeSegmentRefinement(start, end, reason, refined);
     }
+    // ---- Audio events (whole-video) -------------------------------------------
     async readAudioEvents(videoId, gameProfile, provider) {
-        if (this.disabled)
-            return null;
-        return readCacheFile(this.audioEventPath(videoId, gameProfile, provider), z.array(AudioEventSchema));
+        return this.backend.readAudioEvents(videoId, gameProfile, provider);
     }
     async writeAudioEvents(videoId, gameProfile, provider, events) {
-        if (this.disabled)
-            return;
-        await writeCacheFile(this.audioEventPath(videoId, gameProfile, provider), events);
-    }
-    // ---- Audio events (per-chunk) -------------------------------------------
-    /**
-     * Per-chunk audio cache — mirrors the LLM `chunks/` pattern.
-     * Key includes videoId, gameProfile, provider, and the exact window bounds
-     * so each 120s slice is stored independently.
-     */
-    audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd) {
-        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}|${windowStart}|${windowEnd}`)}.json`);
+        return this.backend.writeAudioEvents(videoId, gameProfile, provider, events);
     }
+    // ---- Audio events (per-chunk) ---------------------------------------------
     async readAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd) {
-        if (this.disabled)
-            return null;
-        return readCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), z.array(AudioEventSchema));
+        return this.backend.readAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd);
     }
     async writeAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd, events) {
-        if (this.disabled)
-            return;
-        await writeCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), events);
+        return this.backend.writeAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd, events);
+    }
+    // ---- Lifecycle ------------------------------------------------------------
+    async close() {
+        return this.backend.close();
     }
 }
 //# sourceMappingURL=cache.js.map

package/dist/utils/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/utils/cache.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,KAAK;IACK;IAArB,YAAqB,OAAqB;QAArB,YAAO,GAAP,OAAO,CAAc;IAAG,CAAC;IAE9C,8EAA8E;IAE9E,KAAK,CAAC,cAAc,CAAC,OAAe;QAClC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAe,EAAE,KAAuB;QAC5D,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,SAAS,CACb,KAAe,EACf,gBAA+B;QAE/B,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,UAAU,CACd,KAAe,EACf,UAA2B,EAC3B,gBAA+B;QAE/B,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACtE,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,qBAAqB,CACzB,KAAa,EACb,GAAW,EACX,MAAc;QAEd,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,sBAAsB,CAC1B,KAAa,EACb,GAAW,EACX,MAAc,EACd,OAA0B;QAE1B,OAAO,IAAI,CAAC,OAAO,CAAC,sBAAsB,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1E,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,eAAe,CACnB,OAAe,EACf,WAAmB,EACnB,QAAgB;QAEhB,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;IACtE,CAAC;IAED,KAAK,CAAC,gBAAgB,CACpB,OAAe,EACf,WAAmB,EACnB,QAAgB,EAChB,MAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/E,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,cAAc,CAClB,OAAe,EACf,WAAmB,EACnB,QAAgB,EAChB,WAAmB,EACnB,SAAiB;QAEjB,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,CAAC,CAAC;IAC7F,CAAC;IAED,KAAK,CAAC,eAAe,CACnB,OAAe,EACf,WAAmB,EACnB,QAAgB,EAChB,WAAmB,EACnB,SAAiB,EACjB,MAAoB;QAEpB,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CACjC,OAAO,EACP,WAAW,EACX,QAAQ,EACR,WAAW,EACX,SAAS,EACT,MAAM,CACP,CAAC;IACJ,CAAC;IAED,8EAA8E;IAE9E,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/utils/cacheBackend.d.ts

@@ -0,0 +1,40 @@
+import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent, SegmentRefinement } from '../types/index.js';
+/**
+ * Common interface implemented by every cache backend (file-based, MongoDB, etc.).
+ *
+ * All read methods return null on a cache miss or any read error.
+ * All write methods are fire-and-forget — failures are logged but never thrown.
+ * `close()` releases any underlying resources (connections, file handles, etc.).
+ */
+export interface CacheBackend {
+    readTranscript(videoId: string): Promise<TranscriptLine[] | null>;
+    writeTranscript(videoId: string, lines: TranscriptLine[]): Promise<void>;
+    readChunk(chunk: LLMChunk, chunkAudioEvents?: AudioEvent[]): Promise<ChunkEvaluation | null>;
+    writeChunk(chunk: LLMChunk, evaluation: ChunkEvaluation, chunkAudioEvents?: AudioEvent[]): Promise<void>;
+    readSegmentRefinement(start: number, end: number, reason: string): Promise<SegmentRefinement | null>;
+    writeSegmentRefinement(start: number, end: number, reason: string, refined: SegmentRefinement): Promise<void>;
+    readAudioEvents(videoId: string, gameProfile: string, provider: string): Promise<AudioEvent[] | null>;
+    writeAudioEvents(videoId: string, gameProfile: string, provider: string, events: AudioEvent[]): Promise<void>;
+    readAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number): Promise<AudioEvent[] | null>;
+    writeAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number, events: AudioEvent[]): Promise<void>;
+    /** Release any underlying resources (DB connections, file handles, etc.). */
+    close(): Promise<void>;
+}
+/**
+ * No-op backend used when the cache is disabled (--no-cache flag).
+ * All reads return null; all writes are silent no-ops.
+ */
+export declare class DisabledCacheBackend implements CacheBackend {
+    readTranscript(_videoId: string): Promise<TranscriptLine[] | null>;
+    writeTranscript(_videoId: string, _lines: TranscriptLine[]): Promise<void>;
+    readChunk(_chunk: LLMChunk, _chunkAudioEvents?: AudioEvent[]): Promise<ChunkEvaluation | null>;
+    writeChunk(_chunk: LLMChunk, _evaluation: ChunkEvaluation, _chunkAudioEvents?: AudioEvent[]): Promise<void>;
+    readSegmentRefinement(_start: number, _end: number, _reason: string): Promise<SegmentRefinement | null>;
+    writeSegmentRefinement(_start: number, _end: number, _reason: string, _refined: SegmentRefinement): Promise<void>;
+    readAudioEvents(_videoId: string, _gameProfile: string, _provider: string): Promise<AudioEvent[] | null>;
+    writeAudioEvents(_videoId: string, _gameProfile: string, _provider: string, _events: AudioEvent[]): Promise<void>;
+    readAudioChunk(_videoId: string, _gameProfile: string, _provider: string, _windowStart: number, _windowEnd: number): Promise<AudioEvent[] | null>;
+    writeAudioChunk(_videoId: string, _gameProfile: string, _provider: string, _windowStart: number, _windowEnd: number, _events: AudioEvent[]): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=cacheBackend.d.ts.map

package/dist/utils/cacheBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheBackend.d.ts","sourceRoot":"","sources":["../../src/utils/cacheBackend.ts"],"names":[],"mappings":"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"}

package/dist/utils/cacheBackend.js

@@ -0,0 +1,28 @@
+/**
+ * No-op backend used when the cache is disabled (--no-cache flag).
+ * All reads return null; all writes are silent no-ops.
+ */
+export class DisabledCacheBackend {
+    async readTranscript(_videoId) {
+        return null;
+    }
+    async writeTranscript(_videoId, _lines) { }
+    async readChunk(_chunk, _chunkAudioEvents) {
+        return null;
+    }
+    async writeChunk(_chunk, _evaluation, _chunkAudioEvents) { }
+    async readSegmentRefinement(_start, _end, _reason) {
+        return null;
+    }
+    async writeSegmentRefinement(_start, _end, _reason, _refined) { }
+    async readAudioEvents(_videoId, _gameProfile, _provider) {
+        return null;
+    }
+    async writeAudioEvents(_videoId, _gameProfile, _provider, _events) { }
+    async readAudioChunk(_videoId, _gameProfile, _provider, _windowStart, _windowEnd) {
+        return null;
+    }
+    async writeAudioChunk(_videoId, _gameProfile, _provider, _windowStart, _windowEnd, _events) { }
+    async close() { }
+}
+//# sourceMappingURL=cacheBackend.js.map

package/dist/utils/cacheBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheBackend.js","sourceRoot":"","sources":["../../src/utils/cacheBackend.ts"],"names":[],"mappings":"AA4EA;;;GAGG;AACH,MAAM,OAAO,oBAAoB;IAC/B,KAAK,CAAC,cAAc,CAAC,QAAgB;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,eAAe,CAAC,QAAgB,EAAE,MAAwB,IAAkB,CAAC;IAEnF,KAAK,CAAC,SAAS,CACb,MAAgB,EAChB,iBAAgC;QAEhC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,UAAU,CACd,MAAgB,EAChB,WAA4B,EAC5B,iBAAgC,IAChB,CAAC;IAEnB,KAAK,CAAC,qBAAqB,CACzB,MAAc,EACd,IAAY,EACZ,OAAe;QAEf,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,sBAAsB,CAC1B,MAAc,EACd,IAAY,EACZ,OAAe,EACf,QAA2B,IACX,CAAC;IAEnB,KAAK,CAAC,eAAe,CACnB,QAAgB,EAChB,YAAoB,EACpB,SAAiB;QAEjB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,gBAAgB,CACpB,QAAgB,EAChB,YAAoB,EACpB,SAAiB,EACjB,OAAqB,IACL,CAAC;IAEnB,KAAK,CAAC,cAAc,CAClB,QAAgB,EAChB,YAAoB,EACpB,SAAiB,EACjB,YAAoB,EACpB,UAAkB;QAElB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,KAAK,CAAC,eAAe,CACnB,QAAgB,EAChB,YAAoB,EACpB,SAAiB,EACjB,YAAoB,EACpB,UAAkB,EAClB,OAAqB,IACL,CAAC;IAEnB,KAAK,CAAC,KAAK,KAAmB,CAAC;CAChC"}

package/dist/utils/cacheFactory.d.ts

@@ -0,0 +1,14 @@
+import type { CacheBackend } from './cacheBackend.js';
+import type { Config } from '../types/index.js';
+/**
+ * Creates the appropriate CacheBackend based on config.
+ *
+ * - `disabled = true`        → DisabledCacheBackend (--no-cache flag)
+ * - `CACHE_BACKEND = 'file'` → FileCacheBackend (default)
+ * - `CACHE_BACKEND = 'mongodb'` → MongoCacheBackend (requires MONGODB_URI)
+ *
+ * The caller is responsible for calling `backend.close()` when the pipeline
+ * finishes so that any open connections (e.g. MongoClient) are released.
+ */
+export declare function createCacheBackend(config: Pick<Config, 'CACHE_BACKEND' | 'CACHE_DIR' | 'MONGODB_URI' | 'MONGODB_DATABASE' | 'CACHE_TTL_SECONDS'>, disabled: boolean): Promise<CacheBackend>;
+//# sourceMappingURL=cacheFactory.d.ts.map

package/dist/utils/cacheFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheFactory.d.ts","sourceRoot":"","sources":["../../src/utils/cacheFactory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,IAAI,CACV,MAAM,EACN,eAAe,GAAG,WAAW,GAAG,aAAa,GAAG,kBAAkB,GAAG,mBAAmB,CACzF,EACD,QAAQ,EAAE,OAAO,GAChB,OAAO,CAAC,YAAY,CAAC,CAgBvB"}

package/dist/utils/cacheFactory.js

@@ -0,0 +1,31 @@
+import { MongoClient } from 'mongodb';
+import { log } from './logger.js';
+import { FileCacheBackend } from './fileCacheBackend.js';
+import { MongoCacheBackend } from './mongoCacheBackend.js';
+import { DisabledCacheBackend } from './cacheBackend.js';
+/**
+ * Creates the appropriate CacheBackend based on config.
+ *
+ * - `disabled = true`        → DisabledCacheBackend (--no-cache flag)
+ * - `CACHE_BACKEND = 'file'` → FileCacheBackend (default)
+ * - `CACHE_BACKEND = 'mongodb'` → MongoCacheBackend (requires MONGODB_URI)
+ *
+ * The caller is responsible for calling `backend.close()` when the pipeline
+ * finishes so that any open connections (e.g. MongoClient) are released.
+ */
+export async function createCacheBackend(config, disabled) {
+    if (disabled) {
+        return new DisabledCacheBackend();
+    }
+    if (config.CACHE_BACKEND === 'mongodb') {
+        // MONGODB_URI is guaranteed to be set by the superRefine in ConfigSchema
+        const uri = config.MONGODB_URI;
+        log.info(`[cache] Using MongoDB backend (${config.MONGODB_DATABASE})`);
+        const client = new MongoClient(uri);
+        await client.connect();
+        return new MongoCacheBackend(client, config.MONGODB_DATABASE, config.CACHE_TTL_SECONDS);
+    }
+    // Default: file-based backend
+    return new FileCacheBackend(config.CACHE_DIR);
+}
+//# sourceMappingURL=cacheFactory.js.map

package/dist/utils/cacheFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cacheFactory.js","sourceRoot":"","sources":["../../src/utils/cacheFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAIzD;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,MAGC,EACD,QAAiB;IAEjB,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,IAAI,oBAAoB,EAAE,CAAC;IACpC,CAAC;IAED,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACvC,yEAAyE;QACzE,MAAM,GAAG,GAAG,MAAM,CAAC,WAAqB,CAAC;QACzC,GAAG,CAAC,IAAI,CAAC,kCAAkC,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;QACvE,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,GAAG,CAAC,CAAC;QACpC,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;QACvB,OAAO,IAAI,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC1F,CAAC;IAED,8BAA8B;IAC9B,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAChD,CAAC"}

package/dist/utils/fileCacheBackend.d.ts

@@ -0,0 +1,33 @@
+import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent, SegmentRefinement } from '../types/index.js';
+import type { CacheBackend } from './cacheBackend.js';
+/**
+ * Disk-backed cache backend. Each cached item is stored as a pretty-printed
+ * JSON file under `cacheDir`, named by a SHA-256 hash of the cache key.
+ *
+ * Directory layout:
+ *   <cacheDir>/transcript/<hash>.json
+ *   <cacheDir>/chunks/<hash>.json
+ *   <cacheDir>/segments/<hash>.json
+ *   <cacheDir>/audio/<hash>.json
+ */
+export declare class FileCacheBackend implements CacheBackend {
+    private readonly cacheDir;
+    constructor(cacheDir: string);
+    private transcriptPath;
+    readTranscript(videoId: string): Promise<TranscriptLine[] | null>;
+    writeTranscript(videoId: string, lines: TranscriptLine[]): Promise<void>;
+    private chunkPath;
+    readChunk(chunk: LLMChunk, chunkAudioEvents?: AudioEvent[]): Promise<ChunkEvaluation | null>;
+    writeChunk(chunk: LLMChunk, evaluation: ChunkEvaluation, chunkAudioEvents?: AudioEvent[]): Promise<void>;
+    private segmentRefinementPath;
+    readSegmentRefinement(start: number, end: number, reason: string): Promise<SegmentRefinement | null>;
+    writeSegmentRefinement(start: number, end: number, reason: string, refined: SegmentRefinement): Promise<void>;
+    private audioEventPath;
+    readAudioEvents(videoId: string, gameProfile: string, provider: string): Promise<AudioEvent[] | null>;
+    writeAudioEvents(videoId: string, gameProfile: string, provider: string, events: AudioEvent[]): Promise<void>;
+    private audioChunkPath;
+    readAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number): Promise<AudioEvent[] | null>;
+    writeAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number, events: AudioEvent[]): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=fileCacheBackend.d.ts.map

package/dist/utils/fileCacheBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileCacheBackend.d.ts","sourceRoot":"","sources":["../../src/utils/fileCacheBackend.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkDtD;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAI7C,OAAO,CAAC,cAAc;IAIhB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;IAIjE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9E,OAAO,CAAC,SAAS;IASX,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAI5B,UAAU,CACd,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,eAAe,EAC3B,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,IAAI,CAAC;IAOhB,OAAO,CAAC,qBAAqB;IAIvB,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAI9B,sBAAsB,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAMhB,OAAO,CAAC,cAAc;IAQhB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAOzB,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAMhB,OAAO,CAAC,cAAc;IAchB,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAOzB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IASV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/utils/fileCacheBackend.js

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { z } from 'zod';
+import { log } from './logger.js';
+import { TranscriptLineSchema, ChunkEvaluationSchema, AudioEventSchema, SegmentRefinementSchema, } from '../types/index.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Serializes audio events into a stable string for cache keying.
+ * Events are sorted by time so the key is order-independent.
+ */
+function audioEventsKey(events) {
+    if (events.length === 0)
+        return '';
+    const sorted = [...events].sort((a, b) => a.time - b.time);
+    return JSON.stringify(sorted);
+}
+function hashContent(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+async function readCacheFile(filePath, schema) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = schema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            log.warn(`[cache] Corrupt entry at ${filePath} — ignoring`);
+            return null;
+        }
+        return parsed.data;
+    }
+    catch {
+        // File not found or unreadable — normal cache miss, stay silent
+        return null;
+    }
+}
+async function writeCacheFile(filePath, data) {
+    try {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (err) {
+        log.warn(`[cache] Failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// FileCacheBackend
+// ---------------------------------------------------------------------------
+/**
+ * Disk-backed cache backend. Each cached item is stored as a pretty-printed
+ * JSON file under `cacheDir`, named by a SHA-256 hash of the cache key.
+ *
+ * Directory layout:
+ *   <cacheDir>/transcript/<hash>.json
+ *   <cacheDir>/chunks/<hash>.json
+ *   <cacheDir>/segments/<hash>.json
+ *   <cacheDir>/audio/<hash>.json
+ */
+export class FileCacheBackend {
+    cacheDir;
+    constructor(cacheDir) {
+        this.cacheDir = cacheDir;
+    }
+    // ---- Transcript -----------------------------------------------------------
+    transcriptPath(videoId) {
+        return path.join(this.cacheDir, 'transcript', `${hashContent(videoId)}.json`);
+    }
+    async readTranscript(videoId) {
+        return readCacheFile(this.transcriptPath(videoId), z.array(TranscriptLineSchema));
+    }
+    async writeTranscript(videoId, lines) {
+        await writeCacheFile(this.transcriptPath(videoId), lines);
+    }
+    // ---- LLM chunk results ----------------------------------------------------
+    chunkPath(chunk, chunkAudioEvents = []) {
+        const audioKey = audioEventsKey(chunkAudioEvents);
+        return path.join(this.cacheDir, 'chunks', `${hashContent(`${chunk.start}|${chunk.end}|${chunk.text}|${audioKey}`)}.json`);
+    }
+    async readChunk(chunk, chunkAudioEvents = []) {
+        return readCacheFile(this.chunkPath(chunk, chunkAudioEvents), ChunkEvaluationSchema);
+    }
+    async writeChunk(chunk, evaluation, chunkAudioEvents = []) {
+        if (evaluation.status !== 'success')
+            return;
+        await writeCacheFile(this.chunkPath(chunk, chunkAudioEvents), evaluation);
+    }
+    // ---- Segment refinement ---------------------------------------------------
+    segmentRefinementPath(start, end, reason) {
+        return path.join(this.cacheDir, 'segments', `${hashContent(`${start}|${end}|${reason}`)}.json`);
+    }
+    async readSegmentRefinement(start, end, reason) {
+        return readCacheFile(this.segmentRefinementPath(start, end, reason), SegmentRefinementSchema);
+    }
+    async writeSegmentRefinement(start, end, reason, refined) {
+        await writeCacheFile(this.segmentRefinementPath(start, end, reason), refined);
+    }
+    // ---- Audio events (whole-video) -------------------------------------------
+    audioEventPath(videoId, gameProfile, provider) {
+        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}`)}.json`);
+    }
+    async readAudioEvents(videoId, gameProfile, provider) {
+        return readCacheFile(this.audioEventPath(videoId, gameProfile, provider), z.array(AudioEventSchema));
+    }
+    async writeAudioEvents(videoId, gameProfile, provider, events) {
+        await writeCacheFile(this.audioEventPath(videoId, gameProfile, provider), events);
+    }
+    // ---- Audio events (per-chunk) ---------------------------------------------
+    audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd) {
+        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}|${windowStart}|${windowEnd}`)}.json`);
+    }
+    async readAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd) {
+        return readCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), z.array(AudioEventSchema));
+    }
+    async writeAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd, events) {
+        await writeCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), events);
+    }
+    // ---- Lifecycle ------------------------------------------------------------
+    async close() {
+        // No-op — file handles are not kept open between operations
+    }
+}
+//# sourceMappingURL=fileCacheBackend.js.map

package/dist/utils/fileCacheBackend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileCacheBackend.js","sourceRoot":"","sources":["../../src/utils/fileCacheBackend.ts"],"names":[],"mappings":"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"}

package/dist/utils/mongoCacheBackend.d.ts

@@ -0,0 +1,51 @@
+import type { MongoClient } from 'mongodb';
+import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent, SegmentRefinement } from '../types/index.js';
+import type { CacheBackend } from './cacheBackend.js';
+/**
+ * MongoDB-backed cache backend.
+ *
+ * Each cache category maps to one collection. Documents have the shape:
+ *   { cacheKey: string, data: <payload>, createdAt: Date }
+ *
+ * Indexes created on first use (idempotent):
+ *   - Unique index on `cacheKey` for O(1) lookups
+ *   - TTL index on `createdAt` when `ttlSeconds > 0`
+ *
+ * All reads validate the stored payload through the same zod schemas used by
+ * the file backend, giving identical runtime safety guarantees.
+ *
+ * Pass `ttlSeconds = 0` (or omit) to disable TTL expiration.
+ */
+export declare class MongoCacheBackend implements CacheBackend {
+    private readonly client;
+    private readonly db;
+    private readonly ttlSeconds;
+    /** Track which collections already have their indexes created this session. */
+    private readonly indexedCollections;
+    constructor(client: MongoClient, databaseName: string, ttlSeconds?: number);
+    /**
+     * Ensures indexes exist for a collection. Called lazily on first access per
+     * collection name. `createIndex` is idempotent so concurrent calls are safe.
+     */
+    private ensureIndexes;
+    private readDoc;
+    private writeDoc;
+    private static readonly TRANSCRIPTS;
+    readTranscript(videoId: string): Promise<TranscriptLine[] | null>;
+    writeTranscript(videoId: string, lines: TranscriptLine[]): Promise<void>;
+    private static readonly CHUNKS;
+    private chunkKey;
+    readChunk(chunk: LLMChunk, chunkAudioEvents?: AudioEvent[]): Promise<ChunkEvaluation | null>;
+    writeChunk(chunk: LLMChunk, evaluation: ChunkEvaluation, chunkAudioEvents?: AudioEvent[]): Promise<void>;
+    private static readonly SEGMENTS;
+    readSegmentRefinement(start: number, end: number, reason: string): Promise<SegmentRefinement | null>;
+    writeSegmentRefinement(start: number, end: number, reason: string, refined: SegmentRefinement): Promise<void>;
+    private static readonly AUDIO_EVENTS;
+    readAudioEvents(videoId: string, gameProfile: string, provider: string): Promise<AudioEvent[] | null>;
+    writeAudioEvents(videoId: string, gameProfile: string, provider: string, events: AudioEvent[]): Promise<void>;
+    private static readonly AUDIO_CHUNKS;
+    readAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number): Promise<AudioEvent[] | null>;
+    writeAudioChunk(videoId: string, gameProfile: string, provider: string, windowStart: number, windowEnd: number, events: AudioEvent[]): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mongoCacheBackend.d.ts.map

package/dist/utils/mongoCacheBackend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mongoCacheBackend.d.ts","sourceRoot":"","sources":["../../src/utils/mongoCacheBackend.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAS3C,OAAO,KAAK,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EACf,UAAU,EACV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAqCtD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAOlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,+EAA+E;IAC/E,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAqB;gBAGrC,MAAM,EAAE,WAAW,EACpC,YAAY,EAAE,MAAM,EACpB,UAAU,SAAI;IAUhB;;;OAGG;YACW,aAAa;YAuBb,OAAO;YAyBP,QAAQ;IAoBtB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAiB;IAE9C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC;IAQjE,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ9E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAEpD,OAAO,CAAC,QAAQ;IAKV,SAAS,CACb,KAAK,EAAE,QAAQ,EACf,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQ5B,UAAU,CACd,KAAK,EAAE,QAAQ,EACf,UAAU,EAAE,eAAe,EAC3B,gBAAgB,GAAE,UAAU,EAAO,GAClC,OAAO,CAAC,IAAI,CAAC;IAchB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAwB;IAElD,qBAAqB,CACzB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAQ9B,sBAAsB,CAC1B,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC;IAYhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAiB;IAE/C,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAQzB,gBAAgB,CACpB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAYhB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAiB;IAE/C,cAAc,CAClB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC;IAQzB,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,UAAU,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC;IAYV,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAS7B"}