@bota.dev/react-native-app-sdk 2.0.0-beta.0 → 2.0.0-beta.10

package/src/managers/NativeUploadQueue.ts

@@ -0,0 +1,330 @@
+import EventEmitter from 'eventemitter3';
+import type { BotaDeviceSDKRecordingClient, BotaRecordingTransferProgress } from '../client';
+import type { UploadInfo, UploadRecoveryProvider, UploadTask } from '../models/Recording';
+import type { RecordingManagerEvents } from '../models/Status';
+import { persistedUploadQueue, restoreUploadQueue } from './uploadRecoveryMetadata';
+
+const journalOperations = new WeakMap<object, Promise<unknown>>();
+const journalOwners = new WeakMap<object, NativeUploadQueue>();
+const retryDelays = [30_000, 120_000, 600_000, 3_600_000, 14_400_000];
+const cancelled = () => new Error('Upload cancelled');
+const dispose = (info: UploadInfo | null | undefined) => {
+  try { info?.dispose?.(); } catch { /* Cleanup cannot change an acknowledged result. */ }
+};
+
+type Attempt = {
+  controller: AbortController;
+  nativeId: string;
+  promise: Promise<void>;
+};
+
+/** Races application callbacks, not native teardown. Late credentials still release their lease. */
+const abortable = <T>(promise: Promise<T>, signal: AbortSignal, late?: (value: T) => void): Promise<T> =>
+  new Promise((resolve, reject) => {
+    let settled = false;
+    const abort = () => { if (!settled) { settled = true; reject(cancelled()); } };
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) abort();
+    void promise.then(value => {
+      signal.removeEventListener('abort', abort);
+      if (settled) { late?.(value); return; }
+      settled = true;
+      resolve(value);
+    }, error => {
+      signal.removeEventListener('abort', abort);
+      if (!settled) { settled = true; reject(error); }
+    });
+  });
+
+/** Only metadata crosses this owner. Native hosts retain and upload every byte. */
+export class NativeUploadQueue extends EventEmitter<RecordingManagerEvents> {
+  private tasks: UploadTask[] = [];
+  private readonly active = new Map<string, Attempt>();
+  private readonly credentials = new Map<string, UploadInfo>();
+  private readonly cancelledTasks = new Set<string>();
+  private paused = false;
+  private destroyed = false;
+  private initialized = false;
+  private initialization?: Promise<void>;
+  private timer?: ReturnType<typeof setTimeout>;
+
+  constructor(
+    private readonly client: BotaDeviceSDKRecordingClient,
+    private readonly provider?: UploadRecoveryProvider
+  ) { super(); }
+
+  initialize(): Promise<void> {
+    if (this.initialization) return this.initialization;
+    if (this.destroyed) return Promise.reject(cancelled());
+    const owner = journalOwners.get(this.client);
+    if (owner && owner !== this) return Promise.reject(new Error('Upload recovery journal is already owned by another RecordingManager'));
+    journalOwners.set(this.client, this);
+    this.initialization = this.serialize(async () => {
+      this.checkAlive();
+      const loaded = await this.client.loadUploadQueue();
+      this.checkAlive();
+      const restored = restoreUploadQueue(loaded);
+      if (restored.length > 0) await this.client.saveUploadQueue(restored);
+      this.checkAlive();
+      this.tasks = restored;
+      this.initialized = true;
+    }).then(() => {
+      for (const task of this.tasks.filter(value => value.status === 'completed')) {
+        void this.release(task).catch(() => undefined);
+      }
+      this.schedule();
+    }).catch(error => {
+      if (journalOwners.get(this.client) === this) journalOwners.delete(this.client);
+      throw error;
+    });
+    return this.initialization;
+  }
+
+  all(): UploadTask[] { return this.tasks.map(task => ({ ...task, createdAt: new Date(task.createdAt), updatedAt: new Date(task.updatedAt) })); }
+  get(id: string): UploadTask | undefined { return this.all().find(task => task.id === id); }
+
+  async add(task: UploadTask, info: UploadInfo): Promise<void> {
+    await this.mutate(tasks => [...tasks, ...persistedUploadQueue([task])]);
+    this.credentials.set(task.id, info);
+  }
+
+  offerCredentials(id: string, info: UploadInfo): boolean {
+    if (this.active.has(id) || this.get(id)?.status === 'completed' || this.paused) return false;
+    this.discardCredentials(id);
+    this.credentials.set(id, info);
+    return true;
+  }
+
+  async update(id: string, patch: Partial<UploadTask>, check?: () => void): Promise<void> {
+    await this.mutate(tasks => {
+      check?.();
+      if (!tasks.some(task => task.id === id) || this.cancelledTasks.has(id)) throw cancelled();
+      return tasks.map(task => task.id === id ? { ...task, ...patch, updatedAt: new Date() } : task);
+    });
+    const info = this.credentials.get(id);
+    if (info && patch.relayUpload === false) this.credentials.set(id, { ...info, relay: undefined });
+  }
+
+  run(id: string, onProgress?: (value: BotaRecordingTransferProgress) => void): Promise<void> {
+    if (this.active.has(id)) return this.active.get(id)!.promise;
+    if (this.get(id)?.status === 'completed') return Promise.resolve();
+    if (this.paused || this.destroyed || this.cancelledTasks.has(id)) return Promise.reject(cancelled());
+    const attempt: Attempt = {
+      controller: new AbortController(),
+      nativeId: `${id}_${Date.now()}_${Math.random().toString(36).slice(2)}`,
+      promise: Promise.resolve(),
+    };
+    this.active.set(id, attempt);
+    attempt.promise = this.perform(id, attempt, onProgress).finally(() => {
+      if (this.active.get(id) === attempt) this.active.delete(id);
+      this.schedule();
+    });
+    return attempt.promise;
+  }
+
+  private async perform(id: string, attempt: Attempt, onProgress?: (value: BotaRecordingTransferProgress) => void): Promise<void> {
+    const signal = attempt.controller.signal;
+    const check = () => {
+      if (this.destroyed || signal.aborted || this.cancelledTasks.has(id) || !this.get(id) || this.active.get(id) !== attempt) throw cancelled();
+    };
+    let info: UploadInfo | null | undefined;
+    let hostAbort: (() => void) | undefined;
+    let initialSignal: AbortSignal | undefined;
+    const initialAbort = () => attempt.controller.abort();
+    let nativeStarted = false;
+    let nativeCancellation: Promise<void> | undefined;
+    const cancelNative = () => {
+      if (nativeStarted && !nativeCancellation) {
+        nativeCancellation = this.client.cancelRecordingUpload(attempt.nativeId);
+        void nativeCancellation.catch(() => undefined);
+      }
+    };
+    signal.addEventListener('abort', cancelNative);
+    try {
+      check();
+      const task = this.get(id)!;
+      info = this.credentials.get(id);
+      this.credentials.delete(id);
+      initialSignal = info?.signal;
+      initialSignal?.addEventListener('abort', initialAbort, { once: true });
+      if (initialSignal?.aborted) initialAbort();
+      check();
+      if (info?.expiresAt && info.expiresAt.getTime() <= Date.now() && !info.alreadyUploaded && this.provider && !info.signal?.aborted) {
+        dispose(info);
+        info = undefined;
+      }
+      if (!info) {
+        if (!this.provider || !task.recordingUuid) throw new Error('Upload recovery requires a provider and recordingUuid');
+        info = await abortable(Promise.resolve().then(() => {
+          check();
+          return this.provider!({
+            taskId: id, recordingId: task.recordingId, deviceId: task.deviceId,
+            recordingUuid: task.recordingUuid!, recoveryScope: task.recoveryScope,
+            fileSizeBytes: task.fileSizeBytes, relayUpload: !!task.relayUpload,
+            contentType: task.contentType, contentSha256: task.contentSha256, signal,
+          });
+        }), signal, dispose);
+      }
+      check();
+      if (!info) {
+        await this.update(id, { status: 'pending', nextAttemptAt: Date.now() + 30_000 }, check);
+        throw new Error('Upload waiting for its original account');
+      }
+      if (info.recordingId !== task.recordingId || info.recoveryScope !== task.recoveryScope) {
+        throw new Error('Upload recovery identity changed');
+      }
+      if (!info.alreadyUploaded && !!info.relay !== !!task.relayUpload) throw new Error('Upload recovery route changed');
+      hostAbort = () => attempt.controller.abort();
+      info.signal?.addEventListener('abort', hostAbort, { once: true });
+      if (info.signal?.aborted) hostAbort();
+      check();
+      if (info.expiresAt && info.expiresAt.getTime() <= Date.now() && !info.alreadyUploaded) throw new Error('Upload credentials expired');
+      await this.update(id, { status: 'uploading', errorMessage: undefined, nextAttemptAt: undefined }, check);
+      check();
+      this.emit('uploadStarted', id);
+      check();
+      if (!info.alreadyUploaded) {
+        nativeStarted = true;
+        await this.client.uploadRecordingFile({
+          ...task, id: attempt.nativeId, uploadUrl: info.uploadUrl,
+          contentType: info.contentType ?? task.contentType,
+          uploadToken: info.complete ? undefined : info.uploadToken,
+          completeUrl: info.complete ? undefined : info.completeUrl,
+          relay: info.relay,
+        }, value => {
+          try { check(); } catch { return; }
+          onProgress?.(value);
+          this.emit('uploadProgress', id, value.totalBytes > 0 ? Math.min(value.completedBytes / value.totalBytes, 1) : 0);
+        });
+        check();
+      }
+      if (info.complete) {
+        if (task.fileSizeBytes === undefined) throw new Error('Upload completion requires known file size');
+        await abortable(Promise.resolve().then(() => {
+          check();
+          return info!.complete!({ fileSizeBytes: task.fileSizeBytes!, contentSha256: task.contentSha256, signal });
+        }), signal);
+      } else if (info.alreadyUploaded || (this.provider && !info.relay && !(info.completeUrl && info.uploadToken))) {
+        throw new Error('Recoverable upload requires durable host completion acknowledgement');
+      }
+      check();
+      await this.update(id, { status: 'completed', errorMessage: undefined, nextAttemptAt: undefined }, check);
+      check();
+      await this.release(this.get(id)!).catch(() => undefined);
+      check();
+      this.emit('uploadCompleted', id, task.recordingId);
+    } catch (error) {
+      if (!this.destroyed && !this.cancelledTasks.has(id) && this.get(id)?.status !== 'completed') {
+        const task = this.get(id)!;
+        const parked = info === null || signal.aborted;
+        const retry = !!this.provider && task.retryCount < 6 && Date.now() - task.createdAt.getTime() < 86_400_000;
+        await this.update(id, {
+          status: parked || retry ? 'pending' : 'failed',
+          retryCount: task.retryCount + (parked ? 0 : 1),
+          nextAttemptAt: parked ? Date.now() + 30_000 : retry ? Date.now() + retryDelays[Math.min(task.retryCount, 4)] : undefined,
+          errorMessage: parked ? 'Upload waiting for its original account' : 'Upload attempt failed',
+        }).catch(() => { this.pause(); });
+        if (!this.destroyed) this.emit('uploadFailed', id, new Error(parked ? 'Upload paused' : 'Upload attempt failed'));
+      }
+      throw error;
+    } finally {
+      signal.removeEventListener('abort', cancelNative);
+      initialSignal?.removeEventListener('abort', initialAbort);
+      if (hostAbort) info?.signal?.removeEventListener('abort', hostAbort);
+      // Credential-only legacy callers can explicitly retry during this process.
+      if (!this.provider && info && !info.dispose && !info.signal && !this.destroyed && !this.cancelledTasks.has(id) && this.get(id)?.status !== 'completed') this.credentials.set(id, info);
+      dispose(info);
+      await nativeCancellation?.catch(() => { this.pause(); });
+    }
+  }
+
+  private async release(task: UploadTask): Promise<void> {
+    this.checkAlive();
+    await this.client.releaseRecordingFile(task.id, task.localPath);
+  }
+
+  async cancel(id: string): Promise<void> {
+    this.cancelledTasks.add(id);
+    const active = this.active.get(id);
+    active?.controller.abort();
+    this.discardCredentials(id);
+    if (!active) await this.client.cancelRecordingUpload(id);
+    await this.mutate(tasks => tasks.filter(task => task.id !== id));
+  }
+
+  discardCredentials(id: string): void {
+    const credential = this.credentials.get(id);
+    this.credentials.delete(id);
+    dispose(credential);
+  }
+
+  async clearCompleted(): Promise<void> {
+    const snapshot = this.all().filter(value => value.status === 'completed');
+    for (const task of snapshot) await this.release(task);
+    await this.mutate(tasks => tasks.filter(task => !snapshot.some(released =>
+      task.status === 'completed' && task.id === released.id && task.localPath === released.localPath &&
+      task.recordingId === released.recordingId && task.deviceId === released.deviceId &&
+      task.recordingUuid === released.recordingUuid && task.recoveryScope === released.recoveryScope
+    )));
+  }
+
+  async clearAll(): Promise<void> { for (const task of this.all()) await this.cancel(task.id); }
+
+  async retryFailed(): Promise<void> {
+    const retry = this.all().filter(task => (task.status === 'failed' || (task.status === 'pending' && task.nextAttemptAt)) && !this.active.has(task.id) && !!task.localPath);
+    for (const task of retry) await this.update(task.id, { status: 'pending', retryCount: 0, nextAttemptAt: undefined, createdAt: new Date() });
+    if (!this.paused) for (const task of retry) await this.run(task.id).catch(() => undefined);
+  }
+
+  pause(): void { this.paused = true; if (this.timer) clearTimeout(this.timer); }
+  resume(): void { this.checkAlive(); this.paused = false; this.schedule(); }
+
+  destroy(): void {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (journalOwners.get(this.client) === this) {
+      // New owners must read only after old persistence and native stop have settled.
+      const stopped = this.client.destroyCompatibilityOperations();
+      void stopped.catch(() => undefined);
+      void this.serialize(() => stopped).catch(() => undefined);
+      journalOwners.delete(this.client);
+    }
+    this.pause();
+    for (const attempt of this.active.values()) attempt.controller.abort();
+    for (const info of this.credentials.values()) dispose(info);
+    this.credentials.clear();
+    this.removeAllListeners();
+  }
+
+  private schedule(): void {
+    if (!this.initialized || this.destroyed || this.paused) return;
+    if (this.timer) clearTimeout(this.timer);
+    let wake = Infinity;
+    for (const task of this.tasks) {
+      if (task.status !== 'pending' || !task.localPath || this.active.has(task.id) || this.cancelledTasks.has(task.id) || (!this.provider && !this.credentials.has(task.id))) continue;
+      if ((task.nextAttemptAt ?? 0) > Date.now()) { wake = Math.min(wake, task.nextAttemptAt!); continue; }
+      if (this.active.size >= 2) continue;
+      void this.run(task.id).catch(() => undefined);
+    }
+    if (Number.isFinite(wake)) this.timer = setTimeout(() => this.schedule(), Math.max(1, wake - Date.now()));
+  }
+
+  private serialize<T>(operation: () => Promise<T>): Promise<T> {
+    const next = (journalOperations.get(this.client) ?? Promise.resolve()).catch(() => undefined).then(operation);
+    journalOperations.set(this.client, next.catch(() => undefined));
+    return next;
+  }
+
+  private mutate(change: (tasks: UploadTask[]) => UploadTask[]): Promise<void> {
+    return this.serialize(async () => {
+      this.checkAlive();
+      const next = change(this.tasks);
+      await this.client.saveUploadQueue(persistedUploadQueue(next));
+      this.checkAlive();
+      this.tasks = next;
+      this.emit('queueUpdated', this.all());
+    });
+  }
+
+  private checkAlive(): void { if (this.destroyed) throw cancelled(); }
+}

package/src/managers/RecordingManager.ts

@@ -16,7 +16,9 @@ import type {
   UploadTask,
 } from '../models/Recording';
 import type { RecordingManagerEvents } from '../models/Status';
-import type { UploadInfoProvider } from './types';
+import type { RecordingManagerOptions, UploadInfoProvider } from './types';
+import { NativeUploadQueue } from './NativeUploadQueue';
+import { rejectRecordingDataStore } from './uploadRecoveryMetadata';
 import {
   StreamingSession,
   setStreamingSessionTerminalHandler,
@@ -85,26 +87,30 @@ const observeProgress = <T>(
 
 export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
   private readonly client: BotaDeviceSDKClient;
-  private tasks: UploadTask[] = [];
+  private readonly queue: NativeUploadQueue;
   private initialized = false;
-  private paused = false;
   private destroyed = false;
   private activeStreamingSession: StreamingSession | null = null;
 
-  constructor() {
+  constructor();
+  constructor(options: RecordingManagerOptions);
+  constructor(options: RecordingManagerOptions = {}) {
     super();
+    rejectRecordingDataStore(options.recordingDataStore);
     this.client = getCompatibilityClient();
+    this.queue = new NativeUploadQueue(this.client.recordings, options.uploadRecoveryProvider);
+    this.queue.on('queueUpdated', tasks => this.emit('queueUpdated', tasks));
+    this.queue.on('uploadStarted', id => this.emit('uploadStarted', id));
+    this.queue.on('uploadProgress', (id, progress) => this.emit('uploadProgress', id, progress));
+    this.queue.on('uploadCompleted', (id, recordingId) => this.emit('uploadCompleted', id, recordingId));
+    this.queue.on('uploadFailed', (id, error) => this.emit('uploadFailed', id, error));
   }
 
   async initialize(): Promise<void> {
     if (this.initialized) return;
     this.assertAlive();
-    this.tasks = (await this.client.recordings.loadUploadQueue()).map((task) => ({
-      ...task,
-      createdAt: new Date(task.createdAt),
-      updatedAt: new Date(task.updatedAt),
-      status: task.status === 'uploading' ? 'pending' : task.status,
-    }));
+    await this.queue.initialize();
+    this.assertAlive();
     this.initialized = true;
   }
 
@@ -133,6 +139,10 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
     uploadInfo: UploadInfo
   ): AsyncGenerator<SyncProgress> {
     this.assertReady();
+    if (uploadInfo.signal?.aborted) {
+      uploadInfo.dispose?.();
+      throw new Error('Upload authorization context cancelled');
+    }
     this.emit('syncStarted', recording.uuid);
     const sinkId = createOpaqueId();
     const now = new Date();
@@ -140,6 +150,9 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
       id: createTaskId(),
       recordingId: uploadInfo.recordingId,
       deviceId: device.id,
+      recordingUuid: recording.uuid,
+      recoveryScope: uploadInfo.recoveryScope,
+      fileSizeBytes: recording.fileSizeBytes,
       localPath: '',
       uploadUrl: uploadInfo.uploadUrl,
       ...(uploadInfo.uploadToken ? { uploadToken: uploadInfo.uploadToken } : {}),
@@ -150,10 +163,33 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
       createdAt: now,
       updatedAt: now,
     };
-    this.tasks.push(task);
-    await this.persistTasks();
-    this.emitQueueUpdated();
+    const recovered = uploadInfo.recoveryScope && this.queue.all().find(value =>
+      value.recoveryScope === uploadInfo.recoveryScope && value.recordingId === uploadInfo.recordingId &&
+      value.deviceId === device.id && value.recordingUuid === recording.uuid && !!value.localPath
+    );
+    if (recovered) {
+      const adopted = this.queue.offerCredentials(recovered.id, uploadInfo);
+      try {
+        await this.queue.run(recovered.id);
+        this.assertReady();
+        if (uploadInfo.signal?.aborted) throw new Error('Upload authorization context cancelled');
+        await this.client.recordings.confirmRecording(device, recording.uuid);
+        this.assertReady();
+        yield this.emitSyncProgress(recording.uuid, { stage: 'completed', progress: 1, recordingId: recovered.recordingId, contentSha256: recovered.contentSha256 });
+        this.emit('syncCompleted', recording.uuid, recovered.recordingId);
+      } finally {
+        if (!adopted) uploadInfo.dispose?.();
+      }
+      return;
+    }
+    try {
+      await this.queue.add(task, uploadInfo);
+    } catch (error) {
+      uploadInfo.dispose?.();
+      throw error;
+    }
 
+    let uploadAttempted = false;
     try {
       yield this.emitSyncProgress(recording.uuid, {
         stage: 'preparing',
@@ -193,10 +229,19 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
           'Device delivered encrypted recording data without an upload relay'
         );
       }
-      await this.updateTask(task.id, {
+      this.assertReady();
+      if (uploadInfo.signal?.aborted || !this.queue.get(task.id)) throw new Error('Upload cancelled');
+      const nativeSize = 'fileSizeBytes' in transferResult && typeof transferResult.fileSizeBytes === 'number'
+        ? transferResult.fileSizeBytes : undefined;
+      if (nativeSize !== undefined && (!Number.isSafeInteger(nativeSize) || nativeSize < 0)) throw new Error('Invalid native recording file size');
+      if (nativeSize === undefined && uploadInfo.complete) throw new Error('Host completion requires actual native recording file size');
+      // Route selection comes from native transfer metadata, never list flags.
+      uploadInfo = { ...uploadInfo, relay: transferResult.e2eEncrypted ? uploadInfo.relay : undefined };
+      await this.queue.update(task.id, {
         localPath: transferResult.localPath,
+        fileSizeBytes: nativeSize ?? (transferResult.e2eEncrypted ? undefined : recording.fileSizeBytes),
         contentSha256: transferResult.contentSha256,
-        relay: transferResult.e2eEncrypted ? uploadInfo.relay : undefined,
+        relayUpload: transferResult.e2eEncrypted,
       });
 
       yield this.emitSyncProgress(recording.uuid, {
@@ -206,8 +251,9 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
         totalBytes: recording.fileSizeBytes,
         contentSha256: transferResult.contentSha256,
       });
+      uploadAttempted = true;
       const upload = observeProgress((onProgress) =>
-        this.runUpload(task.id, onProgress)
+        this.queue.run(task.id, onProgress)
       );
       while (true) {
         const value = await upload.next();
@@ -228,7 +274,10 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
         stage: 'completing',
         progress: 0.5,
       });
+      this.assertReady();
+      if (uploadInfo.signal?.aborted || !this.queue.get(task.id)) throw new Error('Upload cancelled');
       await this.client.recordings.confirmRecording(device, recording.uuid);
+      this.assertReady();
       const completed = this.emitSyncProgress(recording.uuid, {
         stage: 'completed',
         progress: 1,
@@ -239,12 +288,13 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
       this.emit('syncCompleted', recording.uuid, uploadInfo.recordingId);
     } catch (error) {
       const failure = error instanceof Error ? error : new Error(String(error));
-      if (this.requireTask(task.id).status !== 'completed') {
-        await this.updateTask(task.id, {
+      if (!this.destroyed && this.queue.get(task.id)?.status === 'pending' && !this.queue.get(task.id)?.localPath) {
+        await this.queue.update(task.id, {
           status: 'failed',
-          errorMessage: failure.message,
+          errorMessage: 'Recording transfer failed',
         });
       }
+      if (this.destroyed) throw failure;
       yield this.emitSyncProgress(recording.uuid, {
         stage: 'failed',
         progress: 0,
@@ -252,6 +302,8 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
       });
       this.emit('syncFailed', recording.uuid, failure);
       throw failure;
+    } finally {
+      if (!uploadAttempted) this.queue.discardCredentials(task.id);
     }
   }
 
@@ -392,13 +444,13 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
   }
 
   getPendingUploads(): UploadTask[] {
-    return this.tasks.filter(
+    return this.queue.all().filter(
       (task) => task.status === 'pending' || task.status === 'uploading'
     );
   }
 
   getAllUploads(): UploadTask[] {
-    return this.tasks.map((task) => ({ ...task }));
+    return this.queue.all();
   }
 
   startStreamingSync(
@@ -435,99 +487,43 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
   }
 
   async cancelUpload(taskId: string): Promise<void> {
-    await this.client.recordings.cancelRecordingUpload(taskId);
-    this.tasks = this.tasks.filter((task) => task.id !== taskId);
-    await this.persistTasks();
-    this.emitQueueUpdated();
+    this.assertReady();
+    await this.queue.cancel(taskId);
   }
 
   async retryFailedUploads(): Promise<void> {
     this.assertReady();
-    if (this.paused) return;
-    for (const task of this.tasks.filter((value) => value.status === 'failed')) {
-      await this.updateTask(task.id, {
-        status: 'pending',
-        retryCount: task.retryCount + 1,
-        errorMessage: undefined,
-      });
-      try {
-        await this.runUpload(task.id);
-      } catch {
-        // Keep failed tasks available for the next explicit retry.
-      }
-    }
+    await this.queue.retryFailed();
   }
 
   async clearCompletedUploads(): Promise<void> {
-    this.tasks = this.tasks.filter((task) => task.status !== 'completed');
-    await this.persistTasks();
-    this.emitQueueUpdated();
+    this.assertReady();
+    await this.queue.clearCompleted();
   }
 
   async clearAllUploads(): Promise<void> {
-    const ids = this.tasks.map((task) => task.id);
-    await Promise.all(
-      ids.map((taskId) =>
-        this.client.recordings.cancelRecordingUpload(taskId).catch(() => undefined)
-      )
-    );
-    this.tasks = [];
-    await this.persistTasks();
-    this.emitQueueUpdated();
+    this.assertReady();
+    await this.queue.clearAll();
   }
 
   pauseUploads(): void {
-    this.paused = true;
+    this.queue.pause();
   }
 
   resumeUploads(): void {
-    this.paused = false;
-    void this.retryFailedUploads();
+    this.queue.resume();
   }
 
   destroy(): void {
     if (this.destroyed) return;
     this.destroyed = true;
+    this.queue.destroy();
     this.activeStreamingSession?.abort();
     this.activeStreamingSession = null;
-    void this.client.recordings.destroyCompatibilityOperations().catch(() => undefined);
     this.removeAllListeners();
     this.initialized = false;
   }
 
-  private async runUpload(
-    taskId: string,
-    onProgress?: (progress: BotaRecordingTransferProgress) => void
-  ): Promise<void> {
-    if (this.paused) throw new Error('Upload queue is paused');
-    const task = this.requireTask(taskId);
-    await this.updateTask(taskId, { status: 'uploading', errorMessage: undefined });
-    this.emit('uploadStarted', taskId);
-    try {
-      await this.client.recordings.uploadRecordingFile(
-        this.requireTask(taskId),
-        (progress) => {
-          onProgress?.(progress);
-          const ratio =
-            progress.totalBytes > 0
-              ? Math.min(progress.completedBytes / progress.totalBytes, 1)
-              : 0;
-          this.emit('uploadProgress', taskId, ratio);
-        }
-      );
-      await this.updateTask(taskId, { status: 'completed', errorMessage: undefined });
-      this.emit('uploadCompleted', taskId, task.recordingId);
-    } catch (error) {
-      const failure = error instanceof Error ? error : new Error(String(error));
-      await this.updateTask(taskId, {
-        status: 'failed',
-        errorMessage: failure.message,
-      });
-      this.emit('uploadFailed', taskId, failure);
-      throw failure;
-    }
-  }
-
   private emitSyncProgress(
     recordingUuid: string,
     progress: SyncProgress
@@ -536,35 +532,6 @@ export class RecordingManager extends EventEmitter<RecordingManagerEvents> {
     return progress;
   }
 
-  private requireTask(taskId: string): UploadTask {
-    const task = this.tasks.find((value) => value.id === taskId);
-    if (!task) throw new Error(`Upload task not found: ${taskId}`);
-    return task;
-  }
-
-  private async updateTask(
-    taskId: string,
-    patch: Partial<UploadTask>
-  ): Promise<void> {
-    const index = this.tasks.findIndex((task) => task.id === taskId);
-    if (index < 0) throw new Error(`Upload task not found: ${taskId}`);
-    this.tasks[index] = {
-      ...this.tasks[index],
-      ...patch,
-      updatedAt: new Date(),
-    };
-    await this.persistTasks();
-    this.emitQueueUpdated();
-  }
-
-  private async persistTasks(): Promise<void> {
-    await this.client.recordings.saveUploadQueue(this.tasks);
-  }
-
-  private emitQueueUpdated(): void {
-    this.emit('queueUpdated', this.getAllUploads());
-  }
-
   private assertReady(): void {
     this.assertAlive();
     if (!this.initialized) {

package/src/managers/types.ts

@@ -1,4 +1,10 @@
-import type { DeviceRecording, UploadInfo } from '../models/Recording';
+import type { DeviceRecording, RecordingDataStore, UploadInfo, UploadRecoveryProvider } from '../models/Recording';
+
+export interface RecordingManagerOptions {
+  uploadRecoveryProvider?: UploadRecoveryProvider;
+  /** Unsupported: recording bytes remain native-owned. Configuration throws. */
+  recordingDataStore?: RecordingDataStore;
+}
 
 export type UploadInfoProvider = (
   recording: DeviceRecording