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

package/dist/deviceManager.d.ts

@@ -0,0 +1,52 @@
+import type { CoreBridge } from './core.ts';
+import { type BotaOperation } from './errors.ts';
+import type { BrowserCapabilities, ConnectOptions, ConnectedDevice, DeviceSnapshot, ReconnectOptions } from './models.ts';
+import { type BrowserSdkStorage } from './storage.ts';
+import { type BrowserBluetoothTransport } from './transport.ts';
+import { BrowserWorkflowRuntime, type WorkflowResult } from './workflowRuntime.ts';
+interface DeviceManagerOptions {
+    runtime?: BrowserWorkflowRuntime;
+    storage?: BrowserSdkStorage | null;
+}
+export declare class DeviceManager {
+    private readonly core;
+    private readonly transport;
+    private readonly runtime;
+    private readonly storage;
+    private readonly capabilities;
+    private readonly persistenceHost;
+    private activeDevice;
+    private verifiedDevice;
+    private removeDisconnectListener;
+    private operationActive;
+    private connectionStartup;
+    private destroyed;
+    private destroyPromise;
+    constructor(core: CoreBridge, transport: BrowserBluetoothTransport, options?: DeviceManagerOptions);
+    get isSupported(): boolean;
+    get connectedDevice(): ConnectedDevice | null;
+    getCapabilities(): BrowserCapabilities;
+    adoptWorkflowConnection(result: WorkflowResult, expectedSerialNumber: string): ConnectedDevice;
+    connect(options: ConnectOptions): Promise<ConnectedDevice>;
+    reconnect(options: ReconnectOptions): Promise<ConnectedDevice>;
+    disconnect(): Promise<void>;
+    readSnapshot(): Promise<DeviceSnapshot>;
+    private verifyActiveSerialInternal;
+    destroy(): Promise<void>;
+    private destroyAfterInternal;
+    private validateConnectionRequest;
+    private claimConnectionStart;
+    private finishConnectionStart;
+    private publishConnectedDevice;
+    private installActiveDevice;
+    private cleanupFailedConnection;
+    private disconnectForIdentityMismatch;
+    private clearConnection;
+    private read;
+    private readRequiredText;
+    private readOptionalText;
+    private readCapabilities;
+}
+export declare function verifyActiveDeviceSerial(manager: DeviceManager, operation: BotaOperation): Promise<ConnectedDevice>;
+export declare function destroyDeviceManagerAfter(manager: DeviceManager, priorCleanup: Promise<unknown>): Promise<void>;
+export {};

package/dist/deviceManager.js

@@ -0,0 +1,491 @@
+import { detectBrowserCapabilities } from "./capabilities.js";
+import { BotaSDKError, normalizeCoreError } from "./errors.js";
+import { BOTA_CONTROL_SERVICE, BOTA_STORAGE_SERVICE, DEVICE_INFORMATION_SERVICE, DEVICE_STATUS_CHARACTERISTIC, FIRMWARE_REVISION_CHARACTERISTIC, HARDWARE_REVISION_CHARACTERISTIC, MODEL_NUMBER_CHARACTERISTIC, SERIAL_NUMBER_CHARACTERISTIC, STORAGE_TRANSFER_CAPABILITIES_V2_CHARACTERISTIC, } from "./gatt.js";
+import { BrowserStorageError, } from "./storage.js";
+import { BrowserTransportError, } from "./transport.js";
+import { BrowserWorkflowRuntime, createBrowserPersistenceHost, } from "./workflowRuntime.js";
+const SERIAL_PATTERN = /^[A-Za-z0-9]{1,64}$/;
+const CONNECTION_TIMEOUT_MS = 15000n;
+export class DeviceManager {
+    core;
+    transport;
+    runtime;
+    storage;
+    capabilities;
+    persistenceHost;
+    activeDevice = null;
+    verifiedDevice = null;
+    removeDisconnectListener = null;
+    operationActive = false;
+    connectionStartup = null;
+    destroyed = false;
+    destroyPromise = null;
+    constructor(core, transport, options = {}) {
+        this.core = core;
+        this.transport = transport;
+        this.runtime = options.runtime ?? new BrowserWorkflowRuntime(core, transport);
+        this.storage = options.storage ?? null;
+        this.capabilities = detectBrowserCapabilities(transport);
+        this.persistenceHost = createBrowserPersistenceHost(this.storage);
+    }
+    get isSupported() {
+        return this.transport.isSupported;
+    }
+    get connectedDevice() {
+        return this.verifiedDevice;
+    }
+    getCapabilities() {
+        return this.capabilities;
+    }
+    adoptWorkflowConnection(result, expectedSerialNumber) {
+        return this.publishConnectedDevice(result, expectedSerialNumber, 'update_firmware');
+    }
+    async connect(options) {
+        this.validateConnectionRequest(options.expectedSerialNumber, 'connect');
+        if (!this.isSupported) {
+            throw new BotaSDKError('unsupported_browser', 'connect');
+        }
+        this.claimConnectionStart('connect');
+        let selected = null;
+        try {
+            const picked = await this.transport.requestDevice().catch((error) => {
+                throw pickerError(error);
+            });
+            selected = picked;
+            if (this.destroyed)
+                throw new BotaSDKError('cancelled', 'connect');
+            this.runtime.registerDevice(picked);
+            this.installActiveDevice(picked);
+            const cancellationId = randomCancellationId();
+            const result = await this.runtime.run(operationId('connect', cancellationId), cancellationId, () => this.core.startExactConnection({
+                expectedSerialNumber: options.expectedSerialNumber,
+                peripheralId: picked.id,
+                name: picked.name,
+                cancellationId,
+            }), { persistence: this.persistenceHost });
+            return this.publishConnectedDevice(result, options.expectedSerialNumber, 'connect');
+        }
+        catch (error) {
+            const lifecycleCancelled = this.destroyed;
+            if (lifecycleCancelled && this.activeDevice) {
+                await this.runtime.waitForPendingConnection(this.activeDevice.id);
+            }
+            await this.cleanupFailedConnection(this.activeDevice ? null : selected);
+            if (lifecycleCancelled) {
+                throw new BotaSDKError('cancelled', 'connect', { cause: error });
+            }
+            throw normalizeManagerError(error, 'connect');
+        }
+        finally {
+            this.finishConnectionStart();
+        }
+    }
+    async reconnect(options) {
+        this.validateConnectionRequest(options.expectedSerialNumber, 'reconnect');
+        if (!this.isSupported) {
+            throw new BotaSDKError('unsupported_browser', 'reconnect');
+        }
+        if (!this.transport.supportsAuthorizedDevices) {
+            throw new BotaSDKError('picker_required', 'reconnect');
+        }
+        if (!this.storage)
+            throw new BotaSDKError('picker_required', 'reconnect');
+        this.claimConnectionStart('reconnect');
+        let attemptedDeviceId = null;
+        try {
+            const hint = await this.storage.loadVerifiedDevice(options.expectedSerialNumber);
+            if (!hint)
+                throw new BotaSDKError('picker_required', 'reconnect');
+            if (this.destroyed)
+                throw new BotaSDKError('cancelled', 'reconnect');
+            const hintedDevice = {
+                id: hint.browserDeviceId,
+                name: hint.name,
+            };
+            attemptedDeviceId = hintedDevice.id;
+            this.activeDevice = hintedDevice;
+            this.runtime.registerDevice(hintedDevice);
+            const cancellationId = randomCancellationId();
+            const result = await this.runtime.run(operationId('reconnect', cancellationId), cancellationId, () => this.core.startReconnect({
+                expectedSerialNumber: options.expectedSerialNumber,
+                hint: {
+                    storedPeripheralId: hint.browserDeviceId,
+                    advertisedAddress: null,
+                    storedName: hint.name,
+                    scanTimeoutMs: CONNECTION_TIMEOUT_MS,
+                    connectionTimeoutMs: CONNECTION_TIMEOUT_MS,
+                },
+                cancellationId,
+            }), { persistence: this.persistenceHost });
+            return this.publishConnectedDevice(result, options.expectedSerialNumber, 'reconnect');
+        }
+        catch (error) {
+            const lifecycleCancelled = this.destroyed;
+            if (lifecycleCancelled && attemptedDeviceId) {
+                await this.runtime.waitForPendingConnection(attemptedDeviceId);
+            }
+            await this.cleanupFailedConnection();
+            if (lifecycleCancelled) {
+                throw new BotaSDKError('cancelled', 'reconnect', { cause: error });
+            }
+            throw normalizeManagerError(error, 'reconnect');
+        }
+        finally {
+            this.finishConnectionStart();
+        }
+    }
+    async disconnect() {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', 'disconnect');
+        if (this.operationActive) {
+            throw new BotaSDKError('operation_in_progress', 'disconnect');
+        }
+        const device = this.runtime.connectedDeviceHandle ?? this.activeDevice;
+        if (!device) {
+            this.clearConnection();
+            return;
+        }
+        try {
+            await this.runtime.runExclusive('disconnect', async (signal) => {
+                this.runtime.markDeviceDisconnected(device.id);
+                this.clearConnection();
+                await awaitDirectStep(this.transport.disconnect(device), signal, 'disconnect');
+            });
+        }
+        catch (error) {
+            throw normalizeManagerError(error, 'disconnect');
+        }
+    }
+    async readSnapshot() {
+        if (this.destroyed) {
+            throw new BotaSDKError('cancelled', 'read_snapshot');
+        }
+        if (this.operationActive) {
+            throw new BotaSDKError('operation_in_progress', 'read_snapshot');
+        }
+        const device = this.activeDevice;
+        const connected = this.verifiedDevice;
+        if (!device
+            || !connected
+            || this.runtime.connectedDeviceHandle?.id !== device.id) {
+            throw new BotaSDKError('device_disconnected', 'read_snapshot');
+        }
+        try {
+            return await this.runtime.runExclusive('read_snapshot', async (signal) => {
+                const serialNumber = await this.readRequiredText(device, DEVICE_INFORMATION_SERVICE, SERIAL_NUMBER_CHARACTERISTIC, signal);
+                if (serialNumber !== connected.serialNumber) {
+                    await this.disconnectForIdentityMismatch(device);
+                    throw new BotaSDKError('identity_mismatch', 'read_snapshot');
+                }
+                const modelNumber = await this.readOptionalText(device, DEVICE_INFORMATION_SERVICE, MODEL_NUMBER_CHARACTERISTIC, signal);
+                const hardwareRevision = await this.readOptionalText(device, DEVICE_INFORMATION_SERVICE, HARDWARE_REVISION_CHARACTERISTIC, signal);
+                const firmwareRevision = await this.readOptionalText(device, DEVICE_INFORMATION_SERVICE, FIRMWARE_REVISION_CHARACTERISTIC, signal);
+                const statusBytes = await this.read(device, BOTA_CONTROL_SERVICE, DEVICE_STATUS_CHARACTERISTIC, signal);
+                const status = this.core.decodeDeviceStatus(statusBytes);
+                const encryptedUploadV2 = await this.readCapabilities(device, signal);
+                return {
+                    identity: {
+                        serialNumber,
+                        modelNumber,
+                        hardwareRevision,
+                        firmwareRevision,
+                    },
+                    status,
+                    capabilities: { encryptedUploadV2 },
+                    capturedAt: new Date(),
+                };
+            });
+        }
+        catch (error) {
+            throw snapshotError(error);
+        }
+    }
+    async verifyActiveSerialInternal(operation) {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', operation);
+        const connected = this.verifiedDevice;
+        const device = this.activeDevice;
+        if (!connected
+            || !device
+            || connected.id !== device.id
+            || this.runtime.connectedDeviceHandle?.id !== device.id) {
+            throw new BotaSDKError('device_disconnected', operation);
+        }
+        try {
+            return await this.runtime.runExclusive(operation, async (signal) => {
+                const encoded = await awaitDirectStep(this.transport.read(device, DEVICE_INFORMATION_SERVICE, SERIAL_NUMBER_CHARACTERISTIC), signal, operation);
+                const serialNumber = decodeRequiredText(encoded, operation);
+                if (serialNumber !== connected.serialNumber) {
+                    await this.disconnectForIdentityMismatch(device);
+                    throw new BotaSDKError('identity_mismatch', operation);
+                }
+                return connected;
+            });
+        }
+        catch (error) {
+            throw normalizeManagerError(error, operation);
+        }
+    }
+    destroy() {
+        return this.destroyAfterInternal(Promise.resolve());
+    }
+    destroyAfterInternal(priorCleanup) {
+        if (this.destroyPromise)
+            return this.destroyPromise;
+        this.destroyed = true;
+        const connectionSettlement = this.connectionStartup?.settled
+            ?? Promise.resolve();
+        this.destroyPromise = (async () => {
+            const failures = [];
+            await collectTeardownFailure(() => priorCleanup, failures);
+            await collectTeardownFailure(() => this.runtime.destroy(), failures);
+            await collectTeardownFailure(() => connectionSettlement, failures);
+            const connected = this.runtime.connectedDeviceHandle ?? this.activeDevice;
+            if (connected) {
+                this.runtime.markDeviceDisconnected(connected.id);
+                this.clearConnection();
+                await collectTeardownFailure(() => this.transport.disconnect(connected), failures);
+            }
+            else {
+                this.clearConnection();
+            }
+            const failure = failures[0];
+            if (failure)
+                throw normalizeManagerError(failure, 'disconnect');
+        })();
+        return this.destroyPromise;
+    }
+    validateConnectionRequest(expectedSerialNumber, operation) {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', operation);
+        if (!SERIAL_PATTERN.test(expectedSerialNumber)) {
+            throw new BotaSDKError('invalid_input', operation);
+        }
+    }
+    claimConnectionStart(operation) {
+        if (this.operationActive || this.activeDevice) {
+            throw new BotaSDKError('operation_in_progress', operation);
+        }
+        this.operationActive = true;
+        let settle;
+        const settled = new Promise((resolve) => {
+            settle = resolve;
+        });
+        this.connectionStartup = { settled, settle };
+    }
+    finishConnectionStart() {
+        this.operationActive = false;
+        const startup = this.connectionStartup;
+        this.connectionStartup = null;
+        startup?.settle();
+    }
+    publishConnectedDevice(result, expectedSerialNumber, operation) {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', operation);
+        const established = [...result.notifications].reverse().find((notification) => notification.kind === 'connection_established');
+        if (!established || established.kind !== 'connection_established') {
+            throw new BotaSDKError('internal_error', operation);
+        }
+        if (established.serialNumber !== expectedSerialNumber) {
+            throw new BotaSDKError('identity_mismatch', operation);
+        }
+        const device = this.runtime.registeredDevice(established.candidate.peripheralId);
+        if (!device || this.runtime.connectedDeviceHandle?.id !== device.id) {
+            throw new BotaSDKError('internal_error', operation);
+        }
+        this.installActiveDevice(device);
+        this.verifiedDevice = {
+            id: device.id,
+            name: device.name,
+            serialNumber: established.serialNumber,
+        };
+        return this.verifiedDevice;
+    }
+    installActiveDevice(device) {
+        this.removeDisconnectListener?.();
+        this.activeDevice = device;
+        this.removeDisconnectListener = this.transport.onDisconnected(device, () => {
+            if (this.activeDevice?.id !== device.id)
+                return;
+            this.runtime.markDeviceDisconnected(device.id);
+            this.clearConnection();
+        });
+    }
+    async cleanupFailedConnection(candidate = null) {
+        const connected = this.runtime.connectedDeviceHandle;
+        if (connected) {
+            this.runtime.markDeviceDisconnected(connected.id);
+            await this.transport.disconnect(connected).catch(() => undefined);
+        }
+        else if (candidate) {
+            await this.transport.disconnect(candidate).catch(() => undefined);
+        }
+        this.clearConnection();
+    }
+    async disconnectForIdentityMismatch(device) {
+        this.runtime.markDeviceDisconnected(device.id);
+        this.clearConnection();
+        await this.transport.disconnect(device).catch(() => undefined);
+    }
+    clearConnection() {
+        const deviceId = this.activeDevice?.id;
+        this.removeDisconnectListener?.();
+        this.removeDisconnectListener = null;
+        this.activeDevice = null;
+        this.verifiedDevice = null;
+        if (deviceId)
+            this.runtime.unregisterDevice(deviceId);
+    }
+    async read(device, serviceUuid, characteristicUuid, signal) {
+        try {
+            return await awaitDirectStep(this.transport.read(device, serviceUuid, characteristicUuid), signal, 'read_snapshot');
+        }
+        catch (error) {
+            if (error instanceof BrowserTransportError
+                && error.code === 'disconnected') {
+                this.runtime.markDeviceDisconnected(device.id);
+                this.clearConnection();
+            }
+            throw error;
+        }
+    }
+    async readRequiredText(device, serviceUuid, characteristicUuid, signal) {
+        const value = await this.read(device, serviceUuid, characteristicUuid, signal);
+        try {
+            const decoded = new TextDecoder('utf-8', { fatal: true })
+                .decode(value)
+                .replace(/^[\0\s]+|[\0\s]+$/g, '');
+            if (!decoded)
+                throw new Error('empty');
+            return decoded;
+        }
+        catch (error) {
+            throw new BotaSDKError('protocol_error', 'read_snapshot', { cause: error });
+        }
+    }
+    async readOptionalText(device, serviceUuid, characteristicUuid, signal) {
+        try {
+            return await this.readRequiredText(device, serviceUuid, characteristicUuid, signal);
+        }
+        catch (error) {
+            if (error instanceof BrowserTransportError
+                && error.code === 'characteristic_not_found') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async readCapabilities(device, signal) {
+        try {
+            const bytes = await this.read(device, BOTA_STORAGE_SERVICE, STORAGE_TRANSFER_CAPABILITIES_V2_CHARACTERISTIC, signal);
+            return this.core.decodeEncryptedUploadV2Capabilities(bytes);
+        }
+        catch (error) {
+            if (error instanceof BrowserTransportError
+                && error.code === 'characteristic_not_found') {
+                return null;
+            }
+            throw error;
+        }
+    }
+}
+function randomCancellationId() {
+    const cancellationId = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(cancellationId);
+    return cancellationId;
+}
+function operationId(operation, cancellationId) {
+    const suffix = [...cancellationId]
+        .map((value) => value.toString(16).padStart(2, '0'))
+        .join('');
+    return `${operation}:${suffix}`;
+}
+async function awaitDirectStep(promise, signal, operation) {
+    const settled = promise.then((value) => ({ kind: 'completed', value }), (error) => ({ kind: 'failed', error }));
+    const result = await settled;
+    if (signal.aborted)
+        throw new BotaSDKError('cancelled', operation);
+    if (result.kind === 'failed')
+        throw result.error;
+    return result.value;
+}
+export async function verifyActiveDeviceSerial(manager, operation) {
+    return await manager.verifyActiveSerialInternal(operation);
+}
+export function destroyDeviceManagerAfter(manager, priorCleanup) {
+    return manager.destroyAfterInternal(priorCleanup);
+}
+async function collectTeardownFailure(cleanup, failures) {
+    try {
+        await cleanup();
+    }
+    catch (error) {
+        failures.push(error);
+    }
+}
+function decodeRequiredText(value, operation) {
+    try {
+        const decoded = new TextDecoder('utf-8', { fatal: true })
+            .decode(value)
+            .replace(/^[\0\s]+|[\0\s]+$/g, '');
+        if (!decoded)
+            throw new Error('empty');
+        return decoded;
+    }
+    catch (error) {
+        throw new BotaSDKError('protocol_error', operation, { cause: error });
+    }
+}
+function pickerError(error) {
+    if (error instanceof BrowserTransportError) {
+        if (error.code === 'picker_cancelled') {
+            return new BotaSDKError('picker_cancelled', 'connect', { cause: error });
+        }
+        if (error.code === 'permission_denied') {
+            return new BotaSDKError('permission_denied', 'connect', { cause: error });
+        }
+    }
+    const name = typeof error === 'object' && error !== null && 'name' in error
+        ? String(error.name)
+        : '';
+    if (name === 'NotFoundError' || name === 'AbortError') {
+        return new BotaSDKError('picker_cancelled', 'connect', { cause: error });
+    }
+    if (name === 'NotAllowedError' || name === 'SecurityError') {
+        return new BotaSDKError('permission_denied', 'connect', { cause: error });
+    }
+    return new BotaSDKError('bluetooth_unavailable', 'connect', { cause: error });
+}
+function normalizeManagerError(error, operation) {
+    if (error instanceof BotaSDKError)
+        return error;
+    if (error instanceof BrowserStorageError) {
+        return new BotaSDKError(error.code, operation, { cause: error });
+    }
+    if (error instanceof BrowserTransportError) {
+        const code = error.code === 'disconnected'
+            ? 'device_disconnected'
+            : error.code === 'permission_denied'
+                ? 'permission_denied'
+                : 'bluetooth_unavailable';
+        return new BotaSDKError(code, operation, { cause: error });
+    }
+    return normalizeCoreError(error, operation);
+}
+function snapshotError(error) {
+    if (error instanceof BotaSDKError)
+        return error;
+    if (error instanceof BrowserTransportError) {
+        if (error.code === 'disconnected') {
+            return new BotaSDKError('device_disconnected', 'read_snapshot', {
+                cause: error,
+            });
+        }
+        if (error.code === 'unavailable') {
+            return new BotaSDKError('bluetooth_unavailable', 'read_snapshot', {
+                cause: error,
+            });
+        }
+    }
+    return normalizeCoreError(error, 'read_snapshot');
+}