@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/redact.js

@@ -0,0 +1,189 @@
+// Redaction — strip sensitive identifiers from any value before it is logged,
+// serialized into a receipt, or written to a bundle.
+//
+// The sensitive CLASSES (draft §Oracle #1, round-5 auth semantics): ICCID, IMSI,
+// EID, SIM PIN, SIM PUK, and APN / connection passwords, PLUS the GNSS coordinate
+// class below. Redaction is KEY-BASED and RECURSIVE: it walks nested objects and
+// arrays and replaces the value under any sensitive key with a fixed marker, no
+// matter how deep — e.g. a password at `policy.connection.auth.password`, or an
+// `iccid` inside an array of SIM slots.
+/** The marker substituted for every redacted value. */
+export const REDACTED = '[redacted]';
+// Leaf key names carrying a sensitive value, matched case-insensitively. The match
+// is EXACT (or exact on the last dotted segment), so NM-style keys like
+// `gsm.password` are caught while non-secret siblings like `gsm.password-flags`
+// (a "0"/"4" flag, not a secret) are not.
+const SENSITIVE_KEYS = new Set([
+    'iccid',
+    'imsi',
+    'eid',
+    'imei',
+    'equipmentidentifier',
+    'equipment-identifier',
+    'equipment_identifier',
+    'pin',
+    'pin2',
+    'newpin',
+    'puk',
+    'puk2',
+    'password',
+    'passwd',
+    'subscriptionid',
+]);
+// GNSS coordinate keys. A fix says where the operator physically is, so it is
+// sensitive for a reason none of the keys above share, and it gets its own set so
+// the privacy fence stays readable: the GPS module keeps a fix in memory for a
+// live display and NEVER persists, uploads, or logs one.
+//
+// Scoped to a GNSS fix on purpose. `3gpp-lac-ci` (coarse cell location) is NOT
+// here — it is the existing cell-info module's deliberate, separately-gated output,
+// and silently blanking it would break a surface that already ships.
+const LOCATION_KEYS = new Set([
+    'latitude',
+    'longitude',
+    'altitude',
+    'lat',
+    'lon',
+    'lng',
+    'nmea',
+    'nmeasentences',
+    'coordinates',
+]);
+/**
+ * SMS content is its own key class, and it may NOT be folded into
+ * `SENSITIVE_KEYS` above. That set matches a leaf name exactly (or the last
+ * dotted segment), so adding `text` / `number` / `sender` to it would redact
+ * every unrelated `text` and `number` in the package — a receipt's reason text,
+ * a slot number, a signal reading. These keys are matched WHOLE after case- AND
+ * separator-folding, so only a key that genuinely names message content or an
+ * originator is scrubbed.
+ *
+ * A message body routinely carries a one-time code (the bench SIM's inbox holds
+ * a literal "Tu pin es: …") and a sender number identifies the subscriber, so
+ * both are treated exactly like a PIN: never rendered anywhere.
+ *
+ * This mirrors CeraUI's `isSmsSensitiveKey` (`helpers/logger.ts`) key-for-key.
+ * It is a Rule-D MIRROR, never a shared import — the two halves are kept honest
+ * by their tests, not by a path.
+ */
+const SMS_SENSITIVE_KEYS = new Set([
+    'smstext',
+    'smsbody',
+    'smsfrom',
+    'smssender',
+    'smsnumber',
+    'messagetext',
+    'messagebody',
+    'msisdn',
+    'sender',
+    'sms.content.text',
+    'sms.content.number',
+]);
+/** Whole-key SMS-content test, case- and separator-insensitive. */
+export function isSmsSensitiveKey(key) {
+    return SMS_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_-]/g, ''));
+}
+/**
+ * USSD carrier text — its own class, for the same reason SMS is: `reply`,
+ * `command`, and `response` are far too common to redact by leaf name, so these
+ * are matched WHOLE after case- and separator-folding.
+ *
+ * BOTH DIRECTIONS are sensitive, not just the reply. A USSD dialogue is how a
+ * subscriber tops up a prepaid line, so the COMMAND routinely carries a voucher
+ * code (`*123*<16 digits>#`) and the reply carries a balance, a subscriber
+ * number, or a one-time code. `NetworkNotification` / `NetworkRequest` are
+ * ModemManager's own property names for network-initiated USSD text and are
+ * included so a raw property dump cannot leak what the call path masks.
+ *
+ * This is why the USSD module names its carrier-text fields `ussdCommand`,
+ * `ussdResponse`, and `ussdReply` rather than the shorter names that read better:
+ * redaction here is key-based, so the FIELD NAME is the guarantee.
+ */
+const USSD_SENSITIVE_KEYS = new Set([
+    'ussd',
+    'ussdcommand',
+    'ussdreply',
+    'ussdresponse',
+    'ussdtext',
+    'networknotification',
+    'networkrequest',
+]);
+/** Whole-key USSD-content test, case- and separator-insensitive. */
+export function isUssdSensitiveKey(key) {
+    return USSD_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_-]/g, ''));
+}
+/**
+ * The SIM's OWN number (MSISDN) — its own class, matched WHOLE after case-,
+ * separator- AND dot-folding so ModemManager's `Modem.OwnNumbers` and mmcli's
+ * `modem.generic.own-numbers` are both caught by one rule.
+ *
+ * It cannot join `SENSITIVE_KEYS`: that set matches a leaf name, and `number` /
+ * `numbers` are far too common — a slot number and a band count would both
+ * vanish. `msisdn` stays in the SMS set (its historical home) and is not
+ * duplicated here.
+ *
+ * It is DISPLAYED to the operator behind an explicit reveal. That is a
+ * rendering decision about a surface the subscriber already owns; it does not
+ * make the value loggable, so it is redacted exactly like a PIN.
+ */
+const OWN_NUMBER_SENSITIVE_KEYS = new Set([
+    'ownnumber',
+    'ownnumbers',
+    'phonenumber',
+    'phonenumbers',
+    'simnumber',
+    'subscribernumber',
+    'modemgenericownnumbers',
+    'modemownnumbers',
+]);
+/** Whole-key own-number test, case-, separator- and dot-insensitive. */
+export function isOwnNumberSensitiveKey(key) {
+    return OWN_NUMBER_SENSITIVE_KEYS.has(key.toLowerCase().replace(/[_.-]/g, ''));
+}
+function isSensitiveKey(key) {
+    const lower = key.toLowerCase();
+    if (SENSITIVE_KEYS.has(lower) || LOCATION_KEYS.has(lower)) {
+        return true;
+    }
+    if (isSmsSensitiveKey(key) || isUssdSensitiveKey(key) || isOwnNumberSensitiveKey(key)) {
+        return true;
+    }
+    const dot = lower.lastIndexOf('.');
+    if (dot < 0) {
+        return false;
+    }
+    const leaf = lower.slice(dot + 1);
+    return SENSITIVE_KEYS.has(leaf) || LOCATION_KEYS.has(leaf);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function redactValue(value, underSensitiveKey) {
+    if (underSensitiveKey) {
+        return REDACTED;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, false));
+    }
+    if (isPlainObject(value)) {
+        const out = {};
+        for (const [key, child] of Object.entries(value)) {
+            out[key] = redactValue(child, isSensitiveKey(key));
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Return a deep copy of `value` with every sensitive field redacted. Plain objects
+ * and arrays are walked recursively; all other values (primitives, and opaque
+ * objects like `Date` / `Set` / `Map`) are returned unchanged. The input is never
+ * mutated.
+ */
+export function redact(value) {
+    return redactValue(value, false);
+}

package/dist/safety/composition-root.d.ts

@@ -0,0 +1,28 @@
+import { ModemActor, type QuiesceHook } from '../backend/modem-actor.js';
+import type { PhysicalModemId } from '../domain/index.js';
+import type { MutationAdmissionPort, ResourceOwnershipPort, ResourceOwnershipRequest, ResourceOwnershipResult, UhubctlPort } from '../ports/index.js';
+export declare class CompositionRootAlreadyExistsError extends Error {
+    readonly name = "CompositionRootAlreadyExistsError";
+    constructor();
+}
+export type ModemControlCompositionRootOptions = {
+    readonly admission: MutationAdmissionPort;
+    readonly ownership: ResourceOwnershipPort | undefined;
+    readonly quiesce?: QuiesceHook;
+    readonly uhubctl?: UhubctlPort;
+};
+export declare class ModemControlCompositionRoot {
+    #private;
+    readonly admission: MutationAdmissionPort;
+    readonly ownership: ResourceOwnershipPort;
+    readonly uhubctl: UhubctlPort | undefined;
+    constructor(options: ModemControlCompositionRootOptions);
+    actorFor(modemId: PhysicalModemId): ModemActor;
+    acquireOwnership(request: ResourceOwnershipRequest): Promise<ResourceOwnershipResult>;
+    dispose(): Promise<void>;
+}
+export declare class MissingResourceOwnershipPortError extends Error {
+    readonly name = "MissingResourceOwnershipPortError";
+    constructor();
+}
+export declare function createModemControlCompositionRoot(options: ModemControlCompositionRootOptions): ModemControlCompositionRoot;

package/dist/safety/composition-root.js

@@ -0,0 +1,65 @@
+import { ModemActor } from '../backend/modem-actor.js';
+let compositionRootExists = false;
+export class CompositionRootAlreadyExistsError extends Error {
+    name = 'CompositionRootAlreadyExistsError';
+    constructor() {
+        super('a modem-control composition root already exists in this process');
+    }
+}
+export class ModemControlCompositionRoot {
+    admission;
+    ownership;
+    uhubctl;
+    #quiesce;
+    #actors = new Map();
+    #ownershipLeases = [];
+    #disposed = false;
+    constructor(options) {
+        if (compositionRootExists)
+            throw new CompositionRootAlreadyExistsError();
+        if (options.ownership === undefined)
+            throw new MissingResourceOwnershipPortError();
+        compositionRootExists = true;
+        this.admission = options.admission;
+        this.ownership = options.ownership;
+        this.#quiesce = options.quiesce;
+        this.uhubctl = options.uhubctl;
+    }
+    actorFor(modemId) {
+        const existing = this.#actors.get(modemId);
+        if (existing !== undefined)
+            return existing;
+        const actor = new ModemActor(this.#quiesce);
+        this.#actors.set(modemId, actor);
+        return actor;
+    }
+    async acquireOwnership(request) {
+        const result = await this.ownership.acquire(request);
+        if (result.status === 'acquired')
+            this.#ownershipLeases.push(result.lease);
+        return result;
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        try {
+            for (const lease of this.#ownershipLeases.splice(0).reverse()) {
+                await lease.release();
+            }
+        }
+        finally {
+            this.#actors.clear();
+            compositionRootExists = false;
+        }
+    }
+}
+export class MissingResourceOwnershipPortError extends Error {
+    name = 'MissingResourceOwnershipPortError';
+    constructor() {
+        super('a ResourceOwnershipPort is required; no pass-through default exists');
+    }
+}
+export function createModemControlCompositionRoot(options) {
+    return new ModemControlCompositionRoot(options);
+}

package/dist/safety/flock-resource-ownership.d.ts

@@ -0,0 +1,11 @@
+import type { ResourceOwnershipPort } from '../ports/index.js';
+export type FlockResourceOwnershipOptions = {
+    readonly lockPath: string;
+    readonly flockBinary?: string;
+};
+export declare class FlockResourceOwnershipError extends Error {
+    readonly detail: string;
+    readonly name = "FlockResourceOwnershipError";
+    constructor(detail: string);
+}
+export declare function createFlockResourceOwnershipPort(options: FlockResourceOwnershipOptions): ResourceOwnershipPort;

package/dist/safety/flock-resource-ownership.js

@@ -0,0 +1,151 @@
+import { spawn } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+const LOCK_HELPER = String.raw `
+import { writeFileSync } from 'node:fs';
+const lockPath = process.env.CERALIVE_MODEM_CONTROL_LOCK_PATH;
+if (!lockPath) process.exit(64);
+const holder = { pid: process.pid, startedAtEpochMs: Date.now() };
+writeFileSync(lockPath, JSON.stringify(holder) + '\n', { mode: 0o600 });
+process.stdout.write(JSON.stringify({ type: 'acquired', holder }) + '\n');
+process.stdin.resume();
+`;
+export class FlockResourceOwnershipError extends Error {
+    detail;
+    name = 'FlockResourceOwnershipError';
+    constructor(detail) {
+        super(`flock ownership failed: ${detail}`);
+        this.detail = detail;
+    }
+}
+export function createFlockResourceOwnershipPort(options) {
+    return {
+        async acquire() {
+            const child = spawn(options.flockBinary ?? 'flock', [
+                '--exclusive',
+                '--nonblock',
+                '--no-fork',
+                options.lockPath,
+                process.execPath,
+                '-e',
+                LOCK_HELPER,
+            ], {
+                env: {
+                    ...process.env,
+                    CERALIVE_MODEM_CONTROL_LOCK_PATH: options.lockPath,
+                },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const closed = childClosed(child);
+            const started = await childStarted(child);
+            if (started.status === 'closed') {
+                if (started.code === 1) {
+                    const holder = await readHolder(options.lockPath);
+                    return {
+                        status: 'refused',
+                        reason: 'already-owned',
+                        ...(holder !== undefined && pidIsAlive(holder.pid) ? { holder } : {}),
+                    };
+                }
+                throw new FlockResourceOwnershipError(`helper exited ${started.code ?? 'by signal'}${started.stderr ? `: ${started.stderr}` : ''}`);
+            }
+            return {
+                status: 'acquired',
+                lease: createLease(child, closed, started.holder),
+            };
+        },
+    };
+}
+function createLease(child, closed, holder) {
+    let released = false;
+    return {
+        holder,
+        lost: closed.then(() => ({ reason: 'holder-exited' })),
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (child.exitCode === null && child.signalCode === null) {
+                child.stdin.end();
+            }
+            await closed;
+        },
+    };
+}
+function childClosed(child) {
+    return new Promise((resolve) => child.once('close', () => resolve()));
+}
+function childStarted(child) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(result);
+        };
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString('utf8');
+        });
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString('utf8');
+            const newline = stdout.indexOf('\n');
+            if (newline < 0)
+                return;
+            const holder = parseAcquiredLine(stdout.slice(0, newline));
+            if (holder !== undefined)
+                finish({ status: 'acquired', holder });
+        });
+        child.once('close', (code) => finish({ status: 'closed', code, stderr: stderr.trim() }));
+    });
+}
+function parseAcquiredLine(line) {
+    try {
+        const parsed = JSON.parse(line);
+        if (typeof parsed !== 'object' || parsed === null || !('holder' in parsed))
+            return undefined;
+        return parseHolder(parsed.holder);
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+async function readHolder(lockPath) {
+    try {
+        return parseHolder(JSON.parse(await readFile(lockPath, 'utf8')));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return undefined;
+        if (error instanceof SyntaxError)
+            return undefined;
+        throw error;
+    }
+}
+function parseHolder(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    if (!('pid' in value) || !('startedAtEpochMs' in value))
+        return undefined;
+    if (typeof value.pid !== 'number' || !Number.isSafeInteger(value.pid) || value.pid <= 0) {
+        return undefined;
+    }
+    if (typeof value.startedAtEpochMs !== 'number' || !Number.isFinite(value.startedAtEpochMs)) {
+        return undefined;
+    }
+    return { pid: value.pid, startedAtEpochMs: value.startedAtEpochMs };
+}
+function pidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ESRCH')
+            return false;
+        return true;
+    }
+}

package/dist/safety/index.d.ts

@@ -0,0 +1,2 @@
+export * from './composition-root.js';
+export * from './flock-resource-ownership.js';

package/dist/safety/index.js

@@ -0,0 +1,2 @@
+export * from './composition-root.js';
+export * from './flock-resource-ownership.js';

package/dist/sms/dbus-messaging.d.ts

@@ -0,0 +1,17 @@
+import { type DecodedProps } from '../backend/managed-objects.js';
+import type { SmsMessage, SmsObservationPort } from '../ports/sms.js';
+import type { DbusTransport } from '../transport/index.js';
+/** `org.freedesktop.ModemManager1.Sms` — one message object. */
+export declare const SMS_IFACE = "org.freedesktop.ModemManager1.Sms";
+/** Build one message from an SMS object's decoded `Sms` properties. */
+export declare function smsFromProps(path: string, props: DecodedProps | undefined): SmsMessage;
+export interface DbusSmsPortOptions {
+    readonly transport: DbusTransport;
+    /** The modem's ModemManager object path. */
+    readonly modemPath: string;
+    readonly destination?: string;
+    readonly cap?: number;
+    /** Called when a fold-time error must be surfaced without failing a read. */
+    readonly onError?: (error: unknown) => void;
+}
+export declare function createDbusSmsPort(options: DbusSmsPortOptions): SmsObservationPort;

package/dist/sms/dbus-messaging.js

@@ -0,0 +1,185 @@
+// The ModemManager Messaging adapter — LIST ONCE, then follow Added / Deleted.
+//
+// Three verbs, all reads: `Messaging.List` for the object paths,
+// `Properties.GetAll` per message, and a subscription to `Added` / `Deleted`.
+// There is no `Create`, no `Send`, no `Delete`, and none may be added — see
+// `../ports/sms.ts` for why that is permanent rather than staged, and
+// `readonly-gate.test.ts` for the lock.
+//
+// NEVER RE-LIST ON A TICK. MM tells us about every change, so a poll would cost
+// one method call per stored message per tick and still could not report an
+// arrival sooner than the tick it happened to land on. The ONLY re-list is on a
+// source RECONNECT, where the events that occurred while the bus was down were
+// never delivered and folding is therefore impossible; that re-list is published
+// as `resynced` so the consumer replaces its rows instead of merging (see
+// `inbox-store.ts`).
+//
+// A MESSAGE THAT VANISHES BETWEEN THE LIST AND ITS READ IS ORDINARY. The modem's
+// own storage rotates, so a failed per-message read SKIPS that message rather
+// than failing the whole inbox. A failed LIST is different — nothing was read at
+// all — and answers a typed refusal.
+import { MM_BUS_NAME, PROPERTIES_IFACE } from '../backend/constants.js';
+import { numberProp, stringProp } from '../backend/managed-objects.js';
+// The one definition of MM's Messaging interface name lives with the capability
+// probe that also keys on it; duplicating it here is how the two drift apart.
+import { MESSAGING_IFACE } from '../capability/detect.js';
+import { classifySmsFailure } from './mmcli-parse.js';
+import { normalizeSmsState, SMS_INBOX_CAP, selectReadablePaths, sortAndCapSms } from './normalize.js';
+/** `org.freedesktop.ModemManager1.Sms` — one message object. */
+export const SMS_IFACE = 'org.freedesktop.ModemManager1.Sms';
+/**
+ * `MMSmsState` (ModemManager `mm-enums.h`) as the port's own vocabulary. The
+ * index IS the enum value; an out-of-range value folds to `unknown` through
+ * {@link normalizeSmsState}, so a future MM state can never surface as a raw
+ * number an operator cannot act on.
+ */
+const SMS_STATE_BY_ORDINAL = [
+    'unknown',
+    'stored',
+    'receiving',
+    'received',
+    'sending',
+    'sent',
+];
+function stateFromOrdinal(ordinal) {
+    if (ordinal === undefined) {
+        return 'unknown';
+    }
+    return normalizeSmsState(SMS_STATE_BY_ORDINAL[ordinal]);
+}
+/** Build one message from an SMS object's decoded `Sms` properties. */
+export function smsFromProps(path, props) {
+    const from = stringProp(props, 'Number');
+    const timestamp = stringProp(props, 'Timestamp');
+    const index = path.slice(path.lastIndexOf('/') + 1);
+    return {
+        id: index,
+        ...(from !== undefined && from !== '' ? { from } : {}),
+        ...(timestamp !== undefined && timestamp !== '' ? { timestamp } : {}),
+        // A data-only (WAP/PDU) message carries no text at all; `''` says so.
+        text: stringProp(props, 'Text') ?? '',
+        state: stateFromOrdinal(numberProp(props, 'State')),
+    };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function createDbusSmsPort(options) {
+    const { transport, modemPath } = options;
+    const destination = options.destination ?? MM_BUS_NAME;
+    const cap = options.cap ?? SMS_INBOX_CAP;
+    const listeners = new Set();
+    const subscriptions = [];
+    let wiring;
+    let stopped = false;
+    const emit = (event) => {
+        for (const listener of listeners) {
+            try {
+                listener(event);
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
+        }
+    };
+    const readMessage = async (path) => {
+        try {
+            const reply = await transport.callMethod({
+                destination,
+                path,
+                interface: PROPERTIES_IFACE,
+                member: 'GetAll',
+                signature: 's',
+                args: [SMS_IFACE],
+            });
+            return smsFromProps(path, reply.body[0]);
+        }
+        catch {
+            // Vanished between the list and this read — ordinary storage rotation.
+            // Nothing is logged: the error text is the only place a body could hide.
+            return undefined;
+        }
+    };
+    const listInbox = async () => {
+        let paths;
+        try {
+            const reply = await transport.callMethod({
+                destination,
+                path: modemPath,
+                interface: MESSAGING_IFACE,
+                member: 'List',
+            });
+            paths = Array.isArray(reply.body[0]) ? reply.body[0] : [];
+        }
+        catch (error) {
+            return { ok: false, reason: classifySmsFailure(describe(error)) };
+        }
+        const candidates = selectReadablePaths(paths.filter((value) => typeof value === 'string'), cap);
+        const messages = [];
+        for (const path of candidates) {
+            const message = await readMessage(path);
+            if (message !== undefined) {
+                messages.push(message);
+            }
+        }
+        return { ok: true, messages: sortAndCapSms(messages, cap) };
+    };
+    const resync = async () => {
+        const result = await listInbox();
+        if (result.ok) {
+            emit({ kind: 'resynced', messages: result.messages });
+        }
+    };
+    const onAdded = async (body) => {
+        const path = body[0];
+        if (typeof path !== 'string') {
+            return;
+        }
+        const message = await readMessage(path);
+        if (message !== undefined) {
+            emit({ kind: 'added', message });
+        }
+    };
+    const wire = async () => {
+        const added = await transport.subscribeSignal({ interface: MESSAGING_IFACE, member: 'Added', path: modemPath }, (event) => {
+            void onAdded(event.body).catch((error) => options.onError?.(error));
+        });
+        const deleted = await transport.subscribeSignal({ interface: MESSAGING_IFACE, member: 'Deleted', path: modemPath }, (event) => {
+            const path = event.body[0];
+            if (typeof path === 'string') {
+                emit({ kind: 'deleted', id: path.slice(path.lastIndexOf('/') + 1) });
+            }
+        });
+        subscriptions.push(added, deleted);
+        transport.on('reconnected', reconnected);
+        // A subscription established AFTER the caller's own `list()` can have
+        // missed an arrival in between, so the wiring ends with one resync.
+        await resync();
+    };
+    const reconnected = () => {
+        void resync().catch((error) => options.onError?.(error));
+    };
+    return {
+        list: listInbox,
+        observe(listener) {
+            listeners.add(listener);
+            if (wiring === undefined && !stopped) {
+                wiring = wire().catch((error) => {
+                    options.onError?.(error);
+                });
+            }
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        async stop() {
+            stopped = true;
+            listeners.clear();
+            transport.off('reconnected', reconnected);
+            await wiring?.catch(() => undefined);
+            wiring = undefined;
+            const held = subscriptions.splice(0, subscriptions.length);
+            await Promise.all(held.map((subscription) => subscription.unsubscribe()));
+        },
+    };
+}

package/dist/sms/inbox-store.d.ts

@@ -0,0 +1,10 @@
+import type { SmsInboxEvent, SmsMessage } from '../ports/sms.js';
+export interface SmsInboxStore {
+    /** Apply one event. Answers whether the visible inbox actually changed. */
+    apply(event: SmsInboxEvent): boolean;
+    /** The current inbox, newest-first and capped. */
+    snapshot(): SmsMessage[];
+    /** Number of retained rows, before the cap is applied. */
+    size(): number;
+}
+export declare function createSmsInboxStore(cap?: number): SmsInboxStore;