@bota.dev/web-app-sdk 2.0.0-beta.0

package/dist/client.js

@@ -0,0 +1,153 @@
+import { ControlManager } from "./controlManager.js";
+import { destroyDeviceManagerAfter, DeviceManager, } from "./deviceManager.js";
+import { BotaSDKError } from "./errors.js";
+import { LogManager } from "./logManager.js";
+import { OTAManager } from "./otaManager.js";
+import { ProvisioningManager } from "./provisioningManager.js";
+import { validateStorageNamespace } from "./indexedDbWorkflowStore.js";
+import { RecordingManager } from "./recordingManager.js";
+import { BrowserStorageError, createDefaultBrowserStorage, } from "./storage.js";
+import { loadDefaultCore } from "./wasmCore.js";
+import { WebBluetoothTransport } from "./webBluetoothTransport.js";
+import { WiFiManager } from "./wifiManager.js";
+import { BrowserWorkflowRuntime } from "./workflowRuntime.js";
+export class BotaDeviceClient {
+    devices;
+    controls;
+    provisioning;
+    ota;
+    logs;
+    recordings;
+    wifi;
+    runtime;
+    storage;
+    destroyPromise = null;
+    constructor(runtime, storage, devices, controls, provisioning, ota, logs, recordings, wifi) {
+        this.runtime = runtime;
+        this.storage = storage;
+        this.devices = devices;
+        this.controls = controls;
+        this.provisioning = provisioning;
+        this.ota = ota;
+        this.logs = logs;
+        this.recordings = recordings;
+        this.wifi = wifi;
+    }
+    static async create(options = {}) {
+        const storage = await resolveStorage(options);
+        const core = await (options.coreLoader ?? loadDefaultCore)();
+        const transport = options.transport ?? new WebBluetoothTransport();
+        const runtime = new BrowserWorkflowRuntime(core, transport);
+        const devices = new DeviceManager(core, transport, {
+            runtime,
+            storage,
+        });
+        return new BotaDeviceClient(runtime, storage, devices, new ControlManager({
+            core,
+            transport,
+            runtime,
+            devices,
+            provider: options.providers?.recordingControl ?? null,
+        }), new ProvisioningManager({
+            core,
+            transport,
+            runtime,
+            devices,
+            storage,
+            provider: options.providers?.provisioning ?? null,
+        }), new OTAManager({
+            core,
+            transport,
+            runtime,
+            devices,
+            storage,
+            provider: options.providers?.firmwareDownload ?? null,
+        }), new LogManager({ core, runtime, devices }), new RecordingManager(core, transport, runtime, devices, storage, options.providers?.recordingUpload ?? null), new WiFiManager({
+            core,
+            transport,
+            runtime,
+            devices,
+        }));
+    }
+    async clearPersistedData() {
+        const storage = this.storage;
+        if (!storage)
+            return;
+        if (this.destroyPromise) {
+            await this.destroyPromise;
+            await clearStorage(storage);
+            return;
+        }
+        try {
+            await this.runtime.runExclusive('clear_persisted_data', async () => {
+                await clearStorage(storage);
+            });
+        }
+        catch (error) {
+            if (error instanceof BotaSDKError)
+                throw error;
+            throw storageError(error);
+        }
+    }
+    destroy() {
+        if (this.destroyPromise)
+            return this.destroyPromise;
+        const managerCleanup = joinManagerCleanup([
+            this.logs.destroy(),
+            this.ota.destroy(),
+            this.wifi.destroy(),
+            this.controls.destroy(),
+            this.provisioning.destroy(),
+            this.recordings.destroy(),
+        ]);
+        this.destroyPromise = destroyDeviceManagerAfter(this.devices, managerCleanup);
+        return this.destroyPromise;
+    }
+}
+async function joinManagerCleanup(cleanups) {
+    const results = await Promise.allSettled(cleanups);
+    const failure = results.find((result) => result.status === 'rejected');
+    if (failure)
+        throw failure.reason;
+}
+async function resolveStorage(options) {
+    if (options.storageNamespace !== undefined) {
+        try {
+            validateStorageNamespace(options.storageNamespace);
+        }
+        catch (error) {
+            throw storageError(error, 'initialize');
+        }
+    }
+    if (options.storage) {
+        if (options.storageNamespace === undefined
+            || options.storage.namespace !== options.storageNamespace) {
+            throw new BotaSDKError('invalid_input', 'initialize');
+        }
+        return options.storage;
+    }
+    if (options.storageNamespace === undefined)
+        return null;
+    try {
+        return await createDefaultBrowserStorage(options.storageNamespace);
+    }
+    catch (error) {
+        throw storageError(error, 'initialize');
+    }
+}
+async function clearStorage(storage) {
+    try {
+        await storage.clear();
+    }
+    catch (error) {
+        throw storageError(error);
+    }
+}
+function storageError(error, operation = 'clear_persisted_data') {
+    if (error instanceof BotaSDKError)
+        return error;
+    if (error instanceof BrowserStorageError) {
+        return new BotaSDKError(error.code, operation);
+    }
+    return new BotaSDKError('storage_unavailable', operation);
+}

package/dist/controlManager.d.ts

@@ -0,0 +1,38 @@
+import type { CoreBridge } from './core.ts';
+import { DeviceManager } from './deviceManager.ts';
+import type { RecordingControlRequest, RecordingControlResult } from './models.ts';
+import type { RecordingControlProvider } from './providers.ts';
+import { type BrowserBluetoothTransport } from './transport.ts';
+import { BrowserWorkflowRuntime } from './workflowRuntime.ts';
+interface ControlManagerOptions {
+    core: CoreBridge;
+    transport: BrowserBluetoothTransport;
+    runtime: BrowserWorkflowRuntime;
+    devices: DeviceManager;
+    provider?: RecordingControlProvider | null | undefined;
+    resultTimeoutMs?: number | undefined;
+    delay?: ((milliseconds: number) => Promise<void>) | undefined;
+}
+export declare class ControlManager {
+    private readonly core;
+    private readonly transport;
+    private readonly runtime;
+    private readonly devices;
+    private readonly provider;
+    private readonly resultTimeoutMs;
+    private readonly delay;
+    private activeControl;
+    private destroyed;
+    private destroyPromise;
+    constructor(options: ControlManagerOptions);
+    startRecording(request: RecordingControlRequest): Promise<RecordingControlResult>;
+    stopRecording(request: RecordingControlRequest): Promise<RecordingControlResult>;
+    destroy(): Promise<void>;
+    private recordingControl;
+    private executeControl;
+    private controlDelay;
+    private runManaged;
+    private verifyConnectedDevice;
+    private validateRequest;
+}
+export {};

package/dist/controlManager.js

@@ -0,0 +1,344 @@
+import { BotaSDKError, normalizeCoreError, } from "./errors.js";
+import { BOTA_CONTROL_SERVICE, DEVICE_COMMAND_CHARACTERISTIC, DEVICE_INFORMATION_SERVICE, RECORDING_CONTROL_CHARACTERISTIC, RECORDING_STATUS_CHARACTERISTIC, SERIAL_NUMBER_CHARACTERISTIC, canonicalGattUuid, } from "./gatt.js";
+import { awaitProviderCall } from "./providerCancellation.js";
+import { BrowserTransportError, } from "./transport.js";
+import { withSubscription } from "./wifiManager.js";
+const DEFAULT_RESULT_TIMEOUT_MS = 30_000;
+const STOP_SEQUENCE_DELAY_MS = 50;
+export class ControlManager {
+    core;
+    transport;
+    runtime;
+    devices;
+    provider;
+    resultTimeoutMs;
+    delay;
+    activeControl = null;
+    destroyed = false;
+    destroyPromise = null;
+    constructor(options) {
+        this.core = options.core;
+        this.transport = options.transport;
+        this.runtime = options.runtime;
+        this.devices = options.devices;
+        this.provider = options.provider ?? null;
+        this.resultTimeoutMs = options.resultTimeoutMs ?? DEFAULT_RESULT_TIMEOUT_MS;
+        this.delay = options.delay ?? delay;
+    }
+    startRecording(request) {
+        return this.recordingControl('start', request);
+    }
+    stopRecording(request) {
+        return this.recordingControl('stop', request);
+    }
+    destroy() {
+        if (this.destroyPromise)
+            return this.destroyPromise;
+        this.destroyed = true;
+        const active = this.activeControl;
+        active?.controller.abort();
+        this.destroyPromise = active?.settled ?? Promise.resolve();
+        return this.destroyPromise;
+    }
+    async recordingControl(action, request) {
+        const operationId = this.validateRequest(request);
+        if (!this.provider) {
+            throw new BotaSDKError('unsupported_capability', 'recording_control');
+        }
+        let command;
+        try {
+            command = this.core.encodeRecordingControlCommand(action);
+        }
+        catch (error) {
+            throw managerError(error, 'recording_control');
+        }
+        try {
+            return await this.runManaged(request.signal, async (signal) => {
+                const { device, serialNumber } = await this.verifyConnectedDevice(signal);
+                let grant = null;
+                try {
+                    let prepared;
+                    const pending = this.provider.prepare({
+                        operationId,
+                        serialNumber,
+                        action,
+                        authorityId: request.authorityId,
+                        signal,
+                    });
+                    try {
+                        prepared = await awaitProviderCall(pending, signal, 'recording_control');
+                    }
+                    catch (error) {
+                        if (signal.aborted) {
+                            void pending.then(scrubLateGrant).catch(() => undefined);
+                        }
+                        if (error instanceof BotaSDKError
+                            && (error.code === 'authorization_expired'
+                                || error.code === 'cancelled'))
+                            throw error;
+                        throw new BotaSDKError('internal_error', 'recording_control');
+                    }
+                    if (!(prepared.grant instanceof Uint8Array)
+                        || prepared.grant.byteLength === 0) {
+                        throw new BotaSDKError('internal_error', 'recording_control');
+                    }
+                    grant = prepared.grant;
+                    throwIfAborted(signal);
+                    return await this.executeControl(action, device, grant, command, signal);
+                }
+                finally {
+                    grant?.fill(0);
+                }
+            });
+        }
+        catch (error) {
+            const normalized = managerError(error, 'recording_control');
+            if (normalized.code === 'identity_mismatch') {
+                await this.devices.disconnect().catch(() => undefined);
+            }
+            throw normalized;
+        }
+        finally {
+            command.fill(0);
+        }
+    }
+    async executeControl(action, device, grant, command, signal) {
+        const result = deferred();
+        let resultWindowOpen = false;
+        let resultReceived = false;
+        return await withSubscription({
+            runtime: this.runtime,
+            transport: this.transport,
+            device,
+            serviceUuid: BOTA_CONTROL_SERVICE,
+            characteristicUuid: RECORDING_STATUS_CHARACTERISTIC,
+            operation: 'recording_control',
+            signal,
+            beforeSubscribe: async () => {
+                await gattStep(this.transport.write(device, BOTA_CONTROL_SERVICE, DEVICE_COMMAND_CHARACTERISTIC, grant, true), signal);
+                if (action === 'stop')
+                    await this.controlDelay(signal);
+            },
+            listener: (notification) => {
+                if (!resultWindowOpen
+                    || resultReceived
+                    || !isCharacteristic(notification, RECORDING_STATUS_CHARACTERISTIC))
+                    return;
+                try {
+                    const decoded = publicControlResult(this.core.decodeRecordingControlResult(notification.value));
+                    resultReceived = true;
+                    result.resolve(decoded);
+                }
+                catch (error) {
+                    resultReceived = true;
+                    result.reject(error);
+                }
+            },
+            body: async () => {
+                if (action === 'stop')
+                    await this.controlDelay(signal);
+                await gattStep(this.transport.write(device, BOTA_CONTROL_SERVICE, RECORDING_CONTROL_CHARACTERISTIC, command, true), signal);
+                resultWindowOpen = true;
+                return await resultWithDeadline(result.promise, signal, this.resultTimeoutMs);
+            },
+        });
+    }
+    async controlDelay(signal) {
+        await this.delay(STOP_SEQUENCE_DELAY_MS);
+        throwIfAborted(signal);
+    }
+    async runManaged(requestSignal, body) {
+        if (this.activeControl) {
+            throw new BotaSDKError('operation_in_progress', 'recording_control');
+        }
+        let settle;
+        const active = {
+            controller: new AbortController(),
+            settled: new Promise((resolve) => {
+                settle = resolve;
+            }),
+            settle: () => settle(),
+        };
+        this.activeControl = active;
+        const abort = () => active.controller.abort();
+        requestSignal?.addEventListener('abort', abort, { once: true });
+        if (requestSignal?.aborted)
+            abort();
+        try {
+            return await this.runtime.runExclusive('recording_control', async (runtimeSignal) => await withCombinedSignal(runtimeSignal, active.controller.signal, body));
+        }
+        finally {
+            requestSignal?.removeEventListener('abort', abort);
+            if (this.activeControl === active)
+                this.activeControl = null;
+            active.settle();
+        }
+    }
+    async verifyConnectedDevice(signal) {
+        const connected = this.devices.connectedDevice;
+        const device = this.runtime.connectedDeviceHandle;
+        if (!connected || !device || connected.id !== device.id) {
+            throw new BotaSDKError('device_disconnected', 'recording_control');
+        }
+        const encoded = await gattStep(this.transport.read(device, DEVICE_INFORMATION_SERVICE, SERIAL_NUMBER_CHARACTERISTIC), signal);
+        const serialNumber = decodeSerial(encoded);
+        if (serialNumber !== connected.serialNumber) {
+            throw new BotaSDKError('identity_mismatch', 'recording_control');
+        }
+        return { device, serialNumber };
+    }
+    validateRequest(request) {
+        if (this.destroyed) {
+            throw new BotaSDKError('cancelled', 'recording_control');
+        }
+        if (!request
+            || typeof request.authorityId !== 'string'
+            || request.authorityId.length === 0
+            || (request.operationId !== undefined
+                && (typeof request.operationId !== 'string'
+                    || request.operationId.length === 0))) {
+            throw new BotaSDKError('invalid_input', 'recording_control');
+        }
+        if (request.signal?.aborted) {
+            throw new BotaSDKError('cancelled', 'recording_control');
+        }
+        return request.operationId ?? `recording_control:${crypto.randomUUID()}`;
+    }
+}
+function publicControlResult(result) {
+    if (result.success)
+        return { success: true };
+    if (result.error === 'grant_expired') {
+        throw new BotaSDKError('authorization_expired', 'recording_control');
+    }
+    const error = result.error === 'already_recording'
+        || result.error === 'not_recording'
+        || result.error === 'invalid_grant'
+        || result.error === 'invalid_state'
+        || result.error === 'invalid_response'
+        ? result.error
+        : 'unknown_error';
+    return {
+        success: false,
+        error,
+        ...(typeof result.errorRaw === 'number'
+            ? { errorRaw: result.errorRaw }
+            : {}),
+    };
+}
+async function gattStep(promise, signal) {
+    const outcome = await settled(promise);
+    if (outcome.kind === 'failed')
+        throw outcome.error;
+    throwIfAborted(signal);
+    return outcome.value;
+}
+async function resultWithDeadline(result, signal, timeoutMs) {
+    throwIfAborted(signal);
+    let timer = null;
+    let cancel;
+    const cancellation = new Promise((_resolve, reject) => {
+        cancel = () => reject(new BotaSDKError('cancelled', 'recording_control'));
+    });
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new BotaSDKError('connection_failed', 'recording_control', {
+                retryable: true,
+            }));
+        }, timeoutMs);
+    });
+    signal.addEventListener('abort', cancel, { once: true });
+    try {
+        return await Promise.race([result, cancellation, timeout]);
+    }
+    finally {
+        signal.removeEventListener('abort', cancel);
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function withCombinedSignal(primary, secondary, body) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    primary.addEventListener('abort', abort, { once: true });
+    secondary.addEventListener('abort', abort, { once: true });
+    if (primary.aborted || secondary.aborted)
+        controller.abort();
+    try {
+        return await body(controller.signal);
+    }
+    finally {
+        primary.removeEventListener('abort', abort);
+        secondary.removeEventListener('abort', abort);
+    }
+}
+function managerError(error, operation) {
+    if (error instanceof BotaSDKError) {
+        return new BotaSDKError(error.code, operation, {
+            retryable: error.retryable,
+            protocolStatus: error.protocolStatus,
+        });
+    }
+    if (error instanceof BrowserTransportError) {
+        const code = error.code === 'disconnected'
+            ? 'device_disconnected'
+            : error.code === 'permission_denied'
+                ? 'permission_denied'
+                : 'bluetooth_unavailable';
+        return new BotaSDKError(code, operation);
+    }
+    const normalized = normalizeCoreError(error, operation);
+    return new BotaSDKError(normalized.code, operation, {
+        retryable: normalized.retryable,
+        protocolStatus: normalized.protocolStatus,
+    });
+}
+function decodeSerial(value) {
+    try {
+        const serial = new TextDecoder('utf-8', { fatal: true })
+            .decode(value)
+            .replace(/^[\0\s]+|[\0\s]+$/g, '');
+        if (!serial)
+            throw new Error('empty');
+        return serial;
+    }
+    catch {
+        throw new BotaSDKError('protocol_error', 'recording_control');
+    }
+}
+function isCharacteristic(notification, characteristicUuid) {
+    return canonicalGattUuid(notification.characteristicUuid)
+        === canonicalGattUuid(characteristicUuid);
+}
+function throwIfAborted(signal) {
+    if (signal.aborted) {
+        throw new BotaSDKError('cancelled', 'recording_control');
+    }
+}
+function scrubLateGrant(value) {
+    try {
+        if (typeof value !== 'object' || value === null)
+            return;
+        const grant = value.grant;
+        if (grant instanceof Uint8Array)
+            grant.fill(0);
+    }
+    catch {
+        // Application-owned late values are untrusted and already ignored.
+    }
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function deferred() {
+    let resolve;
+    let reject;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+        resolve = resolvePromise;
+        reject = rejectPromise;
+    });
+    return { promise, resolve, reject };
+}
+async function settled(promise) {
+    return await promise.then((value) => ({ kind: 'completed', value }), (error) => ({ kind: 'failed', error }));
+}