@bota.dev/react-native-app-sdk 2.0.0-beta.1 → 2.0.0-beta.11

package/src/encryptedUploadV2Backend.ts

@@ -0,0 +1,171 @@
+import type { BotaDeviceSDKRecordingClient, BotaEncryptedUploadV2Recording,
+  BotaEncryptedUploadV2ProfileDecision, BotaEncryptedUploadV2Progress } from './client';
+import type { ConnectedDevice } from './models/Device';
+import type { Spec } from './specs/NativeBotaUploadV2Backend';
+
+export interface EncryptedUploadV2BackendOptions {
+  /** Customer-authenticated HTTPS proxy exposing the v2 routes, e.g. https://api.example.com/v1. */
+  baseUrl: string;
+  /** Stable, non-secret account/project/environment identity. */
+  scopeKey: string;
+  accountId: string;
+  projectId: string;
+  endUserId: string;
+  environment: string;
+  /** Only needed by an organization-scoped backend bridge. */
+  organizationId?: string;
+  /** Abort permanently on logout or any account/project/binding change. */
+  signal: AbortSignal;
+  /** Return an application access token, never a Bota secret API key. */
+  getAccessToken(signal: AbortSignal): Promise<string>;
+}
+
+export interface EncryptedUploadV2SyncTarget {
+  deviceId: string;
+  bindingGeneration: number;
+  signal?: AbortSignal;
+  onProgress?: (progress: BotaEncryptedUploadV2Progress) => void;
+  /** Optional import of an existing integration's exact cloud identity. */
+  priorUpload?: { recordingId: string; sessionId?: string; ownerRevision?: number };
+}
+
+export interface EncryptedUploadV2Backend {
+  /** Reinvoking after restart/reconnect resumes the native journal for this exact recording. */
+  sync(device: ConnectedDevice, recording: BotaEncryptedUploadV2Recording,
+    target: EncryptedUploadV2SyncTarget): Promise<{ recordingId: string }>;
+  dispose(): Promise<void>;
+}
+
+/** @internal Dependency injection keeps the public facade and host tests on the same implementation. */
+export function createManagedEncryptedUploadV2Backend(
+  native: Spec | null, recordings: BotaDeviceSDKRecordingClient,
+  options: EncryptedUploadV2BackendOptions,
+): EncryptedUploadV2Backend {
+  // Capture identity once; mutating the caller's object cannot repoint an active request.
+  const config = { ...options };
+  const url = new URL(config.baseUrl);
+  const path = url.pathname.replace(/\/$/, '');
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash ||
+    !/^(\/[A-Za-z0-9_-]+)+$/.test(path) || !config.scopeKey || !config.signal) {
+    throw new Error('Invalid encrypted upload backend configuration');
+  }
+  const apiOrigin = url.origin;
+  const attempts = new Set<{ cancel(): Promise<void>; settled: Promise<void> }>();
+  let disposed = false;
+  const backend: EncryptedUploadV2Backend = {
+    async sync(device, recording, target) {
+      device = { ...device };
+      recording = { ...recording };
+      target = { ...target, priorUpload: target.priorUpload && { ...target.priorUpload } };
+      if (!native) throw new Error('Encrypted upload backend requires the matching native SDK binary');
+      if (disposed || config.signal.aborted || target.signal?.aborted) throw new Error('Encrypted upload cancelled');
+      const signal = new AbortController();
+      let operationId: string | undefined;
+      let selected: (BotaEncryptedUploadV2ProfileDecision & { recordingId: string }) | undefined;
+      let cancelTask: Promise<void> | undefined;
+      let completed = false;
+      const check = () => {
+        if (disposed || signal.signal.aborted || config.signal.aborted || target.signal?.aborted) {
+          throw new Error('Encrypted upload cancelled');
+        }
+      };
+      const cancel = () => {
+        signal.abort();
+        if (operationId) cancelTask ??= Promise.resolve().then(() => native.cancel(operationId!));
+        return cancelTask ?? Promise.resolve();
+      };
+      // Event callbacks must not create unhandled rejections; disposal awaits the same task.
+      const abort = () => { void cancel().catch(() => {}); };
+      let settle!: () => void;
+      const settled = new Promise<void>(resolve => { settle = resolve; });
+      const attempt = { cancel, settled };
+      attempts.add(attempt);
+      let subscription: { remove(): void } | undefined;
+      try {
+        config.signal.addEventListener('abort', abort, { once: true });
+        target.signal?.addEventListener('abort', abort, { once: true });
+        subscription = native.onCredentialsRequested(event => {
+          if (!operationId || event.operationId !== operationId) return;
+          void (async () => {
+            try {
+              check();
+              const token = await config.getAccessToken(signal.signal);
+              check();
+              await native.resolveCredentials(event.requestId, token);
+            } catch { await native.rejectCredentials(event.requestId).catch(() => {}); }
+          })();
+        });
+        check();
+        await recordings.syncEncryptedRecordingV2(device, recording, async context => {
+          check();
+          if (!context.operationId || (operationId && operationId !== context.operationId)) {
+            throw new Error('Encrypted upload operation changed');
+          }
+          operationId = context.operationId;
+          const value: unknown = JSON.parse(await native.prepare(JSON.stringify({
+            operationId,
+            scope: { apiOrigin, apiBasePath: path, scopeKey: config.scopeKey,
+              accountId: config.accountId, projectId: config.projectId, endUserId: config.endUserId,
+              organizationId: config.organizationId ?? '', environment: config.environment,
+              deviceId: target.deviceId, bindingGeneration: target.bindingGeneration,
+              serialNumber: device.serialNumber, nativeDeviceId: device.id },
+            recording: { uuid: context.recording.uuid, generation: context.recording.generation,
+              ciphertextLength: context.recording.ciphertextLength, ciphertextSha256: context.recording.ciphertextSha256,
+              startedAtMs: context.recording.startedAtMs, durationMs: context.recording.durationMs,
+              plaintextLength: context.recording.plaintextLength, storageFormat: context.recording.storageFormat },
+            capability: { rawValueHex: context.capability.rawValueHex, flags: context.capability.flags },
+            ...(context.checkpoint === undefined ? {} : { checkpoint: {
+              version: context.checkpoint.version, uploadSessionId: context.checkpoint.uploadSessionId,
+              ownerRevision: context.checkpoint.ownerRevision, revision: context.checkpoint.revision,
+              nextCiphertextOffset: context.checkpoint.nextCiphertextOffset, prefixSha256: context.checkpoint.prefixSha256,
+              highestContiguousSequence: context.checkpoint.highestContiguousSequence,
+              transportSessionId: context.checkpoint.transportSessionId, sinkRegistrationId: context.checkpoint.sinkRegistrationId,
+              windowPackets: context.checkpoint.windowPackets, dataPayloadBytes: context.checkpoint.dataPayloadBytes,
+            } }),
+            ...(target.priorUpload === undefined ? {} : { priorJournalEntry: {
+              recordingId: target.priorUpload.recordingId, sessionId: target.priorUpload.sessionId,
+              ownerRevision: target.priorUpload.ownerRevision } }),
+          })));
+          check();
+          const result = value as NonNullable<typeof selected>;
+          if (!result || result.profile !== 'encrypted_upload_v2' ||
+            !/^rec_[A-Za-z0-9_-]+$/.test(result.recordingId) ||
+            !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(result.uploadSessionId) ||
+            !Number.isSafeInteger(result.ownerRevision) || result.ownerRevision < 1 ||
+            !result.materialRegistrationId || !['legacy_allowed', 'v2_preferred', 'v2_required'].includes(result.securityPolicy)) {
+            throw new Error('Invalid encrypted upload backend response');
+          }
+          selected = result;
+          return { profile: result.profile, uploadSessionId: result.uploadSessionId,
+            ownerRevision: result.ownerRevision, securityPolicy: result.securityPolicy,
+            materialRegistrationId: result.materialRegistrationId };
+        }, progress => { if (!signal.signal.aborted) target.onProgress?.(progress); }, { signal: signal.signal });
+        check();
+        if (!operationId || !selected) throw new Error('Encrypted upload confirmation is missing');
+        // The native sync only resolves after signed receipt/CONFIRM. Never infer this from HTTP 2xx.
+        await native.complete(operationId);
+        completed = true;
+        return { recordingId: selected.recordingId };
+      } finally {
+        // Native complete already releases the operation. A later bridge cancellation
+        // failure must not turn confirmed device cleanup into a retryable sync failure.
+        try { if (completed) signal.abort(); else await cancel(); }
+        finally {
+          attempts.delete(attempt);
+          config.signal.removeEventListener('abort', abort);
+          target.signal?.removeEventListener('abort', abort);
+          subscription?.remove();
+          settle();
+        }
+      }
+    },
+    async dispose() {
+      disposed = true;
+      const results = await Promise.allSettled([...attempts].map(async attempt => {
+        try { await attempt.cancel(); } finally { await attempt.settled; }
+      }));
+      if (results.some(result => result.status === 'rejected')) throw new Error('Encrypted upload cancellation failed');
+    },
+  };
+  return backend;
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 import NativeBotaDeviceSDK from './specs/NativeBotaDeviceSDK';
 import { createBotaDeviceSDK } from './client';
+import NativeBotaUploadV2Backend from './specs/NativeBotaUploadV2Backend';
+import { createManagedEncryptedUploadV2Backend } from './encryptedUploadV2Backend';
+import type { EncryptedUploadV2BackendOptions } from './encryptedUploadV2Backend';
 import { setDefaultCompatibilityClient } from './compatibility/runtime';
 
 export {
@@ -7,6 +10,8 @@ export {
   createBotaDeviceSDK,
 } from './client';
 export type {
+  BotaClientPresenceContext,
+  BotaClientPresence,
   BotaAsyncEventSubscription,
   BotaDeviceSDKCapabilities,
   BotaDeviceSDKClient,
@@ -19,6 +24,8 @@ export type {
   BotaEncryptedUploadV2ProgressPhase,
   BotaEncryptedUploadV2ProviderContext,
   BotaEncryptedUploadV2Recording,
+  BotaEncryptedUploadV2PendingRecording,
+  BotaEncryptedUploadV2SyncOptions,
   BotaEncryptedUploadV2SecurityPolicy,
   BotaDeprovisionResult,
   BotaDeviceSDKDeviceClient,
@@ -48,9 +55,16 @@ export type {
 } from './client';
 
 export const BotaDeviceSDK = createBotaDeviceSDK(NativeBotaDeviceSDK);
+export const createEncryptedUploadV2Backend = (options: EncryptedUploadV2BackendOptions) =>
+  createManagedEncryptedUploadV2Backend(NativeBotaUploadV2Backend, BotaDeviceSDK.recordings, options);
+export type { EncryptedUploadV2BackendOptions, EncryptedUploadV2Backend, EncryptedUploadV2SyncTarget } from './encryptedUploadV2Backend';
 setDefaultCompatibilityClient(BotaDeviceSDK);
 
 export { BotaClient } from './BotaClient';
+export type { ClientPresence, SdkClientContext } from './clientPresence';
+export { readClientPresenceObservation } from './clientPresence';
+export { createUploadRecoveryProvider } from './uploadRecovery';
+export type { UploadRecoveryBackend } from './uploadRecovery';
 
 export type {
   BleFactoryResetResult,
@@ -62,6 +76,10 @@ export type {
   DeviceConnectionSettings,
   DeviceFlags,
   DeviceLogEvent,
+  DeviceDiagnosticEvent,
+  DeviceDiagnosticEventType,
+  DeviceDiagnosticReasonCode,
+  DeviceDiagnosticsBatch,
   DeviceState,
   DeviceStatus,
   DeviceType,
@@ -87,6 +105,9 @@ export type {
 export type {
   AudioCodec,
   DeviceRecording,
+  RecordingDataStore,
+  UploadRecoveryContext,
+  UploadRecoveryProvider,
   StreamingSessionEvents,
   StreamingState,
   StreamingSyncOptions,
@@ -118,13 +139,16 @@ export type {
   FirmwareInfo,
   OtaProgress,
   OtaStage,
+  RecordingManagerOptions,
   UploadInfoProvider,
 } from './managers/types';
 
 export { DeviceLogDecoder } from './ble/deviceLogs';
+export { DeviceDiagnosticsDecoder, diagnosticEventIdCommand } from './ble/deviceDiagnostics';
 export { DeviceManager } from './managers/DeviceManager';
 export { OTAManager } from './managers/OTAManager';
 export { RecordingManager } from './managers/RecordingManager';
+export const UPLOAD_RECOVERY_VERSION = 1;
 export { StreamingSession } from './managers/StreamingSession';
 export {
   BotaError,

package/src/managers/DeviceManager.ts

@@ -1,4 +1,5 @@
 import EventEmitter from 'eventemitter3';
+import type { ClientPresence } from '../clientPresence';
 
 import type {
   BotaAsyncEventSubscription,
@@ -16,6 +17,7 @@ import type {
   ConnectedDevice,
   DeviceConnectionSettings,
   DeviceLogEvent,
+  DeviceDiagnosticsBatch,
   DeviceStatus,
   DeviceWiFiScanResult,
   DiscoveredDevice,
@@ -54,6 +56,17 @@ type CacheListener = (
 ) => void;
 
 export class DeviceManager extends EventEmitter<DeviceManagerEvents> {
+  readonly clientPresence: ClientPresence = {
+    nextReport: async (deviceId) => {
+      if (this.destroyed) return null;
+      const report = await this.client.clientPresence.nextReport(deviceId);
+      if (this.destroyed || !report || (report.platform !== 'ios' && report.platform !== 'android')) return null;
+      return {
+        schema_version: 1, session_id: report.sessionId, sequence: report.sequence,
+        platform: report.platform, sdk_package: report.sdkPackage, sdk_version: report.sdkVersion,
+      };
+    },
+  };
   private readonly client: BotaDeviceSDKClient;
   private readonly discoveredDevices = new Map<string, DiscoveredDevice>();
   private readonly connectedDevices = new Map<string, ConnectedDevice>();
@@ -485,6 +498,16 @@ export class DeviceManager extends EventEmitter<DeviceManagerEvents> {
     });
   }
 
+  async readDiagnosticEvents(device: ConnectedDevice): Promise<DeviceDiagnosticsBatch> {
+    this.requireConnected(device.id);
+    return this.client.logs.readDiagnosticEvents(device);
+  }
+
+  async acknowledgeDiagnosticEvents(device: ConnectedDevice, acceptedEventIds: string[]): Promise<void> {
+    this.requireConnected(device.id);
+    await this.client.logs.acknowledgeDiagnosticEvents(device, acceptedEventIds);
+  }
+
   async readConnectionSettings(
     device: ConnectedDevice
   ): Promise<DeviceConnectionSettings> {

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(); }
+}