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

package/dist/wifiManager.js

@@ -0,0 +1,528 @@
+import { BotaSDKError, CoreBridgeError, normalizeCoreError, } from "./errors.js";
+import { BOTA_WIFI_CONFIG_SERVICE, DEVICE_INFORMATION_SERVICE, SERIAL_NUMBER_CHARACTERISTIC, WIFI_CREDENTIAL_CHARACTERISTIC, WIFI_GRANT_CHARACTERISTIC, WIFI_SCAN_CHARACTERISTIC, WIFI_STATUS_CHARACTERISTIC, canonicalGattUuid, } from "./gatt.js";
+import { BrowserTransportError, } from "./transport.js";
+const DEFAULT_OPERATION_TIMEOUT_MS = 30_000;
+export class WiFiManager {
+    core;
+    transport;
+    runtime;
+    devices;
+    operationTimeoutMs;
+    removeDisconnectListener;
+    activeOperation = null;
+    statusOwner = null;
+    destroyed = false;
+    destroyPromise = null;
+    constructor(options) {
+        this.core = options.core;
+        this.transport = options.transport;
+        this.runtime = options.runtime;
+        this.devices = options.devices;
+        this.operationTimeoutMs =
+            options.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
+        this.removeDisconnectListener = this.runtime.onDeviceDisconnected((deviceId) => {
+            const owner = this.statusOwner;
+            if (owner?.deviceId === deviceId) {
+                void this.closeStatusOwner(owner);
+            }
+        });
+    }
+    async scanNetworks() {
+        this.requireUsable();
+        let command;
+        try {
+            command = this.core.encodeWiFiScanCommand();
+        }
+        catch (error) {
+            throw managerError(error, 'wifi');
+        }
+        try {
+            return await this.runManaged(async (signal) => {
+                const device = await this.verifyConnectedDevice(signal);
+                const result = deferred();
+                let resultWindowOpen = false;
+                let resultReceived = false;
+                return await withSubscription({
+                    runtime: this.runtime,
+                    transport: this.transport,
+                    device,
+                    serviceUuid: BOTA_WIFI_CONFIG_SERVICE,
+                    characteristicUuid: WIFI_SCAN_CHARACTERISTIC,
+                    operation: 'wifi',
+                    signal,
+                    listener: (notification) => {
+                        if (!resultWindowOpen
+                            || resultReceived
+                            || !isCharacteristic(notification, WIFI_SCAN_CHARACTERISTIC))
+                            return;
+                        try {
+                            const update = this.core.decodeWiFiScanUpdate(notification.value);
+                            if (update.kind === 'pending')
+                                return;
+                            resultReceived = true;
+                            result.resolve(publicScanResult(update));
+                        }
+                        catch (error) {
+                            resultReceived = true;
+                            result.reject(error);
+                        }
+                    },
+                    body: async () => {
+                        await gattStep(this.transport.write(device, BOTA_WIFI_CONFIG_SERVICE, WIFI_SCAN_CHARACTERISTIC, command, true), signal, 'wifi');
+                        resultWindowOpen = true;
+                        return await resultWithDeadline(result.promise, signal, this.operationTimeoutMs, 'wifi');
+                    },
+                });
+            });
+        }
+        catch (error) {
+            throw await this.normalizeFailure(error);
+        }
+        finally {
+            command.fill(0);
+        }
+    }
+    async configure(credentials, grant) {
+        this.requireUsable();
+        if (typeof credentials !== 'object'
+            || credentials === null
+            || typeof credentials.ssid !== 'string'
+            || typeof credentials.password !== 'string'
+            || typeof grant !== 'string') {
+            throw new BotaSDKError('invalid_input', 'wifi');
+        }
+        let encodedGrant = null;
+        let encodedCredentials = null;
+        try {
+            try {
+                encodedCredentials = this.core.encodeWiFiCredentials(credentials.ssid, credentials.password);
+                encodedGrant = this.core.encodeWiFiGrant(grant, this.transport.maximumWriteValueLength);
+            }
+            catch (error) {
+                throw managerError(error, 'wifi');
+            }
+            if (!encodedCredentials || !encodedGrant) {
+                throw new BotaSDKError('internal_error', 'wifi');
+            }
+            const operationCredentials = encodedCredentials;
+            const operationGrant = encodedGrant;
+            try {
+                return await this.runManaged(async (signal) => {
+                    const device = await this.verifyConnectedDevice(signal);
+                    return await this.configureWithSubscription(device, operationCredentials, signal, async () => {
+                        await gattStep(this.transport.write(device, BOTA_WIFI_CONFIG_SERVICE, WIFI_GRANT_CHARACTERISTIC, operationGrant, true), signal, 'wifi');
+                    });
+                });
+            }
+            catch (error) {
+                throw await this.normalizeFailure(error);
+            }
+        }
+        finally {
+            encodedGrant?.fill(0);
+            encodedCredentials?.fill(0);
+        }
+    }
+    async disconnect() {
+        this.requireUsable();
+        let command;
+        try {
+            command = this.core.encodeWiFiCredentials('', '');
+        }
+        catch (error) {
+            throw managerError(error, 'wifi');
+        }
+        try {
+            return await this.runManaged(async (signal) => {
+                const device = await this.verifyConnectedDevice(signal);
+                return await this.configureWithSubscription(device, command, signal);
+            });
+        }
+        catch (error) {
+            throw await this.normalizeFailure(error);
+        }
+        finally {
+            command.fill(0);
+        }
+    }
+    async readStatus() {
+        this.requireUsable();
+        try {
+            return await this.runManaged(async (signal) => {
+                const device = await this.verifyConnectedDevice(signal);
+                const encoded = await gattStep(this.transport.read(device, BOTA_WIFI_CONFIG_SERVICE, WIFI_STATUS_CHARACTERISTIC), signal, 'wifi');
+                return publicStatus(this.core.decodeWiFiStatus(encoded));
+            });
+        }
+        catch (error) {
+            throw await this.normalizeFailure(error);
+        }
+    }
+    async subscribeToStatus(listener) {
+        this.requireUsable();
+        if (typeof listener !== 'function') {
+            throw new BotaSDKError('invalid_input', 'wifi');
+        }
+        try {
+            return await this.runManaged(async (signal) => {
+                const device = await this.verifyConnectedDevice(signal);
+                return await this.subscribeToVerifiedStatus(device, listener);
+            });
+        }
+        catch (error) {
+            throw await this.normalizeFailure(error);
+        }
+    }
+    async subscribeToVerifiedStatus(device, listener) {
+        let lease;
+        try {
+            lease = this.runtime.claimCharacteristicLease('wifi', device, BOTA_WIFI_CONFIG_SERVICE, WIFI_STATUS_CHARACTERISTIC);
+        }
+        catch (error) {
+            throw managerError(error, 'wifi');
+        }
+        let owner = null;
+        const pendingNotifications = [];
+        const deliverNotification = (notification) => {
+            const currentOwner = owner;
+            if (!currentOwner) {
+                pendingNotifications.push({
+                    characteristicUuid: notification.characteristicUuid,
+                    value: notification.value.slice(),
+                });
+                return;
+            }
+            if (currentOwner.closing
+                || this.destroyed
+                || !isCharacteristic(notification, WIFI_STATUS_CHARACTERISTIC))
+                return;
+            try {
+                const status = publicStatus(this.core.decodeWiFiStatus(notification.value));
+                const completion = listener(status);
+                if (isPromiseLike(completion)) {
+                    void Promise.resolve(completion).catch(() => {
+                        void this.closeStatusOwner(currentOwner);
+                    });
+                }
+            }
+            catch {
+                void this.closeStatusOwner(currentOwner);
+            }
+        };
+        let subscriptionPromise;
+        try {
+            subscriptionPromise = this.transport.subscribe(device, BOTA_WIFI_CONFIG_SERVICE, WIFI_STATUS_CHARACTERISTIC, deliverNotification);
+        }
+        catch (error) {
+            lease.release();
+            throw managerError(error, 'wifi');
+        }
+        owner = {
+            deviceId: device.id,
+            lease,
+            subscriptionPromise,
+            closing: false,
+            closePromise: null,
+        };
+        this.statusOwner = owner;
+        for (const notification of pendingNotifications.splice(0)) {
+            deliverNotification(notification);
+        }
+        try {
+            await subscriptionPromise;
+            if (this.destroyed || owner.closing) {
+                await this.closeStatusOwner(owner);
+                throw new BotaSDKError('cancelled', 'wifi');
+            }
+            return {
+                remove: async () => await this.closeStatusOwner(owner),
+            };
+        }
+        catch (error) {
+            await this.closeStatusOwner(owner);
+            throw managerError(error, 'wifi');
+        }
+    }
+    destroy() {
+        if (this.destroyPromise)
+            return this.destroyPromise;
+        this.destroyed = true;
+        this.removeDisconnectListener();
+        const operation = this.activeOperation;
+        operation?.controller.abort();
+        const statusOwner = this.statusOwner;
+        this.destroyPromise = Promise.all([
+            operation?.settled ?? Promise.resolve(),
+            statusOwner
+                ? this.closeStatusOwner(statusOwner)
+                : Promise.resolve(),
+        ]).then(() => undefined);
+        return this.destroyPromise;
+    }
+    async configureWithSubscription(device, credentials, signal, beforeSubscribe) {
+        const result = deferred();
+        let resultWindowOpen = false;
+        let resultReceived = false;
+        return await withSubscription({
+            runtime: this.runtime,
+            transport: this.transport,
+            device,
+            serviceUuid: BOTA_WIFI_CONFIG_SERVICE,
+            characteristicUuid: WIFI_STATUS_CHARACTERISTIC,
+            operation: 'wifi',
+            signal,
+            beforeSubscribe,
+            listener: (notification) => {
+                if (!resultWindowOpen
+                    || resultReceived
+                    || !isCharacteristic(notification, WIFI_STATUS_CHARACTERISTIC))
+                    return;
+                try {
+                    resultReceived = true;
+                    result.resolve(publicConfigResult(this.core.decodeWiFiConfigResult(notification.value)));
+                }
+                catch (error) {
+                    resultReceived = true;
+                    result.reject(error);
+                }
+            },
+            body: async () => {
+                await gattStep(this.transport.write(device, BOTA_WIFI_CONFIG_SERVICE, WIFI_CREDENTIAL_CHARACTERISTIC, credentials, true), signal, 'wifi');
+                resultWindowOpen = true;
+                return await resultWithDeadline(result.promise, signal, this.operationTimeoutMs, 'wifi');
+            },
+        });
+    }
+    async runManaged(body) {
+        if (this.activeOperation) {
+            throw new BotaSDKError('operation_in_progress', 'wifi');
+        }
+        let settle;
+        const active = {
+            controller: new AbortController(),
+            settled: new Promise((resolve) => {
+                settle = resolve;
+            }),
+            settle: () => settle(),
+        };
+        this.activeOperation = active;
+        try {
+            return await this.runtime.runExclusive('wifi', async (runtimeSignal) => await withCombinedSignal(runtimeSignal, active.controller.signal, body));
+        }
+        finally {
+            if (this.activeOperation === active)
+                this.activeOperation = 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', 'wifi');
+        }
+        const encoded = await gattStep(this.transport.read(device, DEVICE_INFORMATION_SERVICE, SERIAL_NUMBER_CHARACTERISTIC), signal, 'wifi');
+        if (decodeSerial(encoded) !== connected.serialNumber) {
+            throw new BotaSDKError('identity_mismatch', 'wifi');
+        }
+        return device;
+    }
+    requireConnectedDevice() {
+        const connected = this.devices.connectedDevice;
+        const device = this.runtime.connectedDeviceHandle;
+        if (!connected || !device || connected.id !== device.id) {
+            throw new BotaSDKError('device_disconnected', 'wifi');
+        }
+        return device;
+    }
+    async normalizeFailure(error) {
+        const normalized = managerError(error, 'wifi');
+        if (normalized.code === 'identity_mismatch') {
+            await this.devices.disconnect().catch(() => undefined);
+        }
+        return normalized;
+    }
+    closeStatusOwner(owner) {
+        if (owner.closePromise)
+            return owner.closePromise;
+        owner.closing = true;
+        owner.closePromise = (async () => {
+            const subscription = await settled(owner.subscriptionPromise);
+            if (subscription.kind === 'completed') {
+                await subscription.value.remove().catch(() => undefined);
+            }
+            owner.lease.release();
+            if (this.statusOwner === owner)
+                this.statusOwner = null;
+        })();
+        return owner.closePromise;
+    }
+    requireUsable() {
+        if (this.destroyed)
+            throw new BotaSDKError('cancelled', 'wifi');
+    }
+}
+export async function withSubscription(options) {
+    const lease = options.runtime.claimCharacteristicLease(options.operation, options.device, options.serviceUuid, options.characteristicUuid);
+    let subscription = null;
+    try {
+        await options.beforeSubscribe?.();
+        throwIfAborted(options.signal, options.operation);
+        const setup = await settled(options.transport.subscribe(options.device, options.serviceUuid, options.characteristicUuid, options.listener));
+        if (setup.kind === 'failed')
+            throw setup.error;
+        subscription = setup.value;
+        throwIfAborted(options.signal, options.operation);
+        return await options.body();
+    }
+    finally {
+        if (subscription)
+            await subscription.remove().catch(() => undefined);
+        lease.release();
+    }
+}
+function publicScanResult(update) {
+    return {
+        networks: update.networks.map((network) => ({ ...network })),
+        currentSsid: update.currentSsid,
+    };
+}
+function publicStatus(status) {
+    return {
+        status: status.status,
+        statusRaw: status.statusRaw,
+        ...(typeof status.signalStrength === 'number'
+            ? { signalStrength: status.signalStrength }
+            : {}),
+        ...(typeof status.ssid === 'string' ? { ssid: status.ssid } : {}),
+        ...(typeof status.lastError === 'string'
+            ? { lastError: status.lastError }
+            : {}),
+    };
+}
+function publicConfigResult(result) {
+    if (result.success)
+        return { success: true };
+    const error = result.error === 'invalid_grant'
+        || result.error === 'grant_expired'
+        || result.error === 'decryption_error'
+        || result.error === 'storage_error'
+        ? result.error
+        : 'unknown';
+    return {
+        success: false,
+        error,
+        ...(typeof result.errorRaw === 'number'
+            ? { errorRaw: result.errorRaw }
+            : {}),
+    };
+}
+async function gattStep(promise, signal, operation) {
+    const outcome = await settled(promise);
+    if (outcome.kind === 'failed')
+        throw outcome.error;
+    throwIfAborted(signal, operation);
+    return outcome.value;
+}
+async function resultWithDeadline(result, signal, timeoutMs, operation) {
+    throwIfAborted(signal, operation);
+    let timer = null;
+    let cancel;
+    const cancellation = new Promise((_resolve, reject) => {
+        cancel = () => reject(new BotaSDKError('cancelled', operation));
+    });
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            reject(new BotaSDKError('connection_failed', operation, {
+                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);
+    }
+    if (error instanceof CoreBridgeError
+        && (error.code === 'invalid_input' || error.code === 'payload_too_large')) {
+        return new BotaSDKError('invalid_input', 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', 'wifi');
+    }
+}
+function isCharacteristic(notification, characteristicUuid) {
+    return canonicalGattUuid(notification.characteristicUuid)
+        === canonicalGattUuid(characteristicUuid);
+}
+function throwIfAborted(signal, operation) {
+    if (signal.aborted)
+        throw new BotaSDKError('cancelled', operation);
+}
+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 }));
+}
+function isPromiseLike(value) {
+    return typeof value === 'object'
+        && value !== null
+        && typeof value.then === 'function';
+}

package/dist/workflowRuntime.d.ts

@@ -0,0 +1,115 @@
+import type { CoreBridge, CoreEffectEnvelope, CoreHostEvent, CoreNotification } from './core.ts';
+import { type BotaOperation } from './errors.ts';
+import { type BrowserSdkStorage } from './storage.ts';
+import { type BrowserBluetoothTransport, type BrowserDeviceHandle } from './transport.ts';
+export interface WorkflowResult {
+    notifications: CoreNotification[];
+}
+export interface WorkflowEffectContext {
+    operationId: string;
+    cancellationId: Uint8Array;
+    signal: AbortSignal;
+    dispatch(event: CoreHostEvent): Promise<void>;
+    addCleanup(cleanup: () => Promise<void>): void;
+}
+export interface WorkflowEffectHost {
+    execute(effect: CoreEffectEnvelope, context: WorkflowEffectContext): Promise<CoreHostEvent | readonly CoreHostEvent[] | null>;
+    cancel(): Promise<void>;
+    confirmationAttemptedOrClaimCancellation?(cancellationId: Uint8Array): Promise<boolean>;
+}
+export interface WorkflowObserver {
+    onNotification?(notification: CoreNotification): void;
+    onProgress?(completedUnits: bigint, totalUnits: bigint): void;
+    onRunning?(): void;
+}
+export interface WorkflowEffectHosts {
+    persistence: WorkflowEffectHost;
+    recordingSink?: WorkflowEffectHost;
+    network?: WorkflowEffectHost;
+    firmwareBlob?: WorkflowEffectHost;
+    hostMaterial?: WorkflowEffectHost;
+    encryptedUploadV2?: WorkflowEffectHost;
+}
+export type WorkflowCompletionHandoff = (result: WorkflowResult) => Promise<void>;
+export interface CharacteristicLease {
+    release(): void;
+}
+export declare class BrowserWorkflowRuntime {
+    private readonly core;
+    private readonly transport;
+    private readonly devices;
+    private readonly characteristicLeases;
+    private readonly disconnectListeners;
+    private activeOwner;
+    private connectedDevice;
+    private poisonedDeviceId;
+    private destroyed;
+    private destroyPromise;
+    private coreDispatchTail;
+    private nextConnectionAttempt;
+    private readonly connectionAttempts;
+    private readonly pendingConnectionSettlements;
+    constructor(core: CoreBridge, transport: BrowserBluetoothTransport);
+    get connectedDeviceHandle(): BrowserDeviceHandle | null;
+    registerDevice(device: BrowserDeviceHandle): void;
+    registeredDevice(deviceId: string): BrowserDeviceHandle | null;
+    waitForPendingConnection(deviceId: string): Promise<void>;
+    unregisterDevice(deviceId: string): void;
+    markDeviceDisconnected(deviceId: string): void;
+    poisonBleOwnership(deviceId: string): void;
+    onDeviceDisconnected(listener: (deviceId: string) => void): () => void;
+    claimCharacteristicLease(operation: BotaOperation, device: BrowserDeviceHandle, serviceUuid: string, characteristicUuid: string): CharacteristicLease;
+    run(operationId: string, cancellationId: Uint8Array, start: () => CoreEffectEnvelope[], hosts: WorkflowEffectHosts, observer?: WorkflowObserver, completionHandoff?: WorkflowCompletionHandoff): Promise<WorkflowResult>;
+    cancel(operationId: string): Promise<void>;
+    runExclusive<T>(operation: BotaOperation, body: (signal: AbortSignal) => Promise<T>): Promise<T>;
+    destroy(): Promise<void>;
+    private enqueueEffects;
+    private dispatchDeviceDisconnected;
+    private validateEnvelope;
+    private ensurePump;
+    private pump;
+    private finishFromCoreStatus;
+    private executeEffect;
+    private effectContext;
+    private dispatchFromContext;
+    private startAuthorizedScan;
+    private connectDevice;
+    private discoverServices;
+    private disconnectDevice;
+    private readCharacteristic;
+    private writeCharacteristic;
+    private subscribe;
+    private unsubscribe;
+    private scheduleTimer;
+    private cancelTimer;
+    private executeHost;
+    private awaitOwnerStep;
+    private trackGattSetup;
+    private settlePendingGattSetups;
+    private settlePendingGattWrites;
+    private trackExternalOperation;
+    private trackExternalSettlement;
+    private settlePendingExternalOperations;
+    private ownerSignal;
+    private handleNotification;
+    private reportProgress;
+    private reportFirmwareProgress;
+    private dispatchBleFailure;
+    private serializedCoreCall;
+    private dispatchCurrentOwnerEvent;
+    private hasCompletionEvidence;
+    private enterCancellation;
+    private cancelOwner;
+    private finishSuccess;
+    private finishCancelled;
+    private failOwner;
+    private cancelAfterFailure;
+    private executeCancellationEffects;
+    private finishFailure;
+    private beginCancellation;
+    private confirmationAttemptedOrClaimCancellation;
+    private cleanupAndSettle;
+    private cleanupOwner;
+    private releaseOwner;
+}
+export declare function createBrowserPersistenceHost(storage: BrowserSdkStorage | null, now?: () => number): WorkflowEffectHost;