@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/backend/managed-objects.js

@@ -0,0 +1,82 @@
+// Walkers over a DECODED `GetManagedObjects` / `InterfacesAdded` tree.
+//
+// The transport decodes `a{oa{sa{sv}}}` into nested tuple arrays: a dict `a{sv}`
+// becomes `[key, variant][]` and a variant becomes `{ signature, value }`. These
+// accessors navigate that structure by object path and interface name. They live in
+// `src` (not the A2.3 test fake's `tree.ts`) because the observer that ships must not
+// import test-support — the published package would not contain it.
+import { MM_ROOT_PATH, OBJECT_MANAGER_IFACE } from './constants.js';
+/** Treat a `GetManagedObjects` reply body value as the decoded tree. */
+export function asManagedObjects(value) {
+    if (!Array.isArray(value)) {
+        throw new TypeError('managed-objects payload is not an array');
+    }
+    return value;
+}
+/** Call `ObjectManager.GetManagedObjects` on `destination` and decode the reply. */
+export async function fetchManagedObjects(transport, destination) {
+    const reply = await transport.callMethod({
+        destination,
+        path: MM_ROOT_PATH,
+        interface: OBJECT_MANAGER_IFACE,
+        member: 'GetManagedObjects',
+    });
+    return asManagedObjects(reply.body[0]);
+}
+/** Treat an `InterfacesAdded` body (`[path, interfaces]`) as one decoded object. */
+export function asAddedObject(path, interfaces) {
+    if (typeof path !== 'string' || !Array.isArray(interfaces)) {
+        throw new TypeError('InterfacesAdded body is not [objectPath, interfaces]');
+    }
+    return [path, interfaces];
+}
+/** Every object path in the tree, in wire order. */
+export function objectPaths(tree) {
+    return tree.map(([path]) => path);
+}
+/** The object at `path`, or `undefined`. */
+export function findObject(tree, path) {
+    return tree.find(([objectPath]) => objectPath === path);
+}
+/** The property entries of one interface on one object, or `undefined`. */
+export function findInterface(tree, path, iface) {
+    return findObject(tree, path)?.[1].find(([name]) => name === iface)?.[1];
+}
+/** Object paths that carry a given interface. */
+export function pathsWithInterface(tree, iface) {
+    return tree
+        .filter(([, interfaces]) => interfaces.some(([name]) => name === iface))
+        .map(([path]) => path);
+}
+/** Whether an object exposes a given interface. */
+export function hasInterface(tree, path, iface) {
+    return findInterface(tree, path, iface) !== undefined;
+}
+/** The inner value of a property (a variant's `.value`), or `undefined`. */
+export function propValue(props, name) {
+    return props?.find(([key]) => key === name)?.[1]?.value;
+}
+/** A string-typed property, or `undefined` if absent / not a string. */
+export function stringProp(props, name) {
+    const value = propValue(props, name);
+    return typeof value === 'string' ? value : undefined;
+}
+/** A number-typed property, or `undefined` if absent / not a number. */
+export function numberProp(props, name) {
+    const value = propValue(props, name);
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * A string-array (`as`) property, or `undefined` if absent / not an array. An
+ * EMPTY array answers `[]` — the device saying "none", a different fact from an
+ * absent property. Non-string members are dropped, never coerced.
+ */
+export function stringArrayProp(props, name) {
+    const value = propValue(props, name);
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
+}
+/** Resolve an object-path property (e.g. a modem's `Sim`) to that object's props. */
+export function followObjectPath(tree, props, propName, iface) {
+    const target = propValue(props, propName);
+    return typeof target === 'string' ? findInterface(tree, target, iface) : undefined;
+}

package/dist/backend/mapping.d.ts

@@ -0,0 +1,11 @@
+import { type CellularSnapshot } from '../domain/index.js';
+import { type DecodedManagedObjects } from './managed-objects.js';
+/** The dimensions of a mapped modem, WITHOUT a revision (the observer stamps that). */
+export type MappedModem = Omit<CellularSnapshot, 'revision'>;
+/** Map ONE modem object to its dimensions. The modem must expose `Modem`. */
+export declare function mapModem(tree: DecodedManagedObjects, modemPath: string): MappedModem;
+/** Every modem path in the tree (objects exposing the `Modem` interface), in order. */
+export declare function modemPaths(tree: DecodedManagedObjects): string[];
+/** A stable fingerprint of a mapped modem's meaningful dimensions (ignores revision
+ *  and source health), used to suppress redundant revision bumps on identical reads. */
+export declare function fingerprint(mapped: MappedModem): string;

package/dist/backend/mapping.js

@@ -0,0 +1,148 @@
+// Pure mapping: a decoded ModemManager object tree → a `CellularSnapshot`.
+//
+// A3.1 is lifecycle-only. This mapper is DELIBERATELY conservative: it captures
+// identity, presence, source health, radio power, and MM state — the facts the
+// observer needs to order and reconcile modems — but leaves the richer 3GPP
+// registration + access-technology set as `unknown`/empty. Faithful registration and
+// cell-info normalisation are A3.2 (identity ladder) and A3.3 (Signal.Setup / cell
+// info); mapping them here would either be a guess or trip the domain guards. The
+// snapshot this produces is always guard-valid by construction.
+import { imeiEquipmentId, subscriberNumber as makeSubscriberNumber, subscriptionId as makeSubscriptionId, runtimePath, } from '../domain/index.js';
+import { MODEM_IFACE, MODEM3GPP_IFACE, SIM_IFACE } from './constants.js';
+import { findInterface, followObjectPath, numberProp, pathsWithInterface, stringArrayProp, stringProp, } from './managed-objects.js';
+/** MMModemState (`Modem.State`, signed) → the domain `MmState`. */
+function mapMmState(state) {
+    switch (state) {
+        case -1:
+            return 'failed';
+        case 1:
+            return 'initializing';
+        case 2:
+            return 'locked';
+        case 3:
+            return 'disabled';
+        case 4:
+            return 'disabling';
+        case 5:
+            return 'enabling';
+        case 6:
+            return 'enabled';
+        case 7:
+            return 'searching';
+        case 8:
+            return 'registered';
+        case 9:
+            return 'disconnecting';
+        case 10:
+            return 'connecting';
+        case 11:
+            return 'connected';
+        default:
+            return 'unknown';
+    }
+}
+/** MMModemPowerState (`Modem.PowerState`) → the domain `RadioPower`. */
+function mapRadioPower(power) {
+    switch (power) {
+        case 1:
+            return 'off';
+        case 2:
+            return 'low';
+        case 3:
+            return 'on';
+        default:
+            return 'unknown';
+    }
+}
+/** Locked / failed modems keep the radio off; every other state we cannot see as
+ *  off (the guards forbid an active MM state with the radio off), so an unknown
+ *  power reading is treated as `on` when the modem is clearly on the air. */
+function reconcilePower(power, state) {
+    const onTheAir = state === 'enabled' ||
+        state === 'searching' ||
+        state === 'registered' ||
+        state === 'connecting' ||
+        state === 'connected' ||
+        state === 'disconnecting';
+    if (onTheAir && (power === 'unknown' || power === 'off')) {
+        return 'on';
+    }
+    return power;
+}
+/** Read a modem's subscription id (ICCID) from its active SIM object, if any. */
+function readSubscriptionId(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const sim = followObjectPath(tree, modem, 'Sim', SIM_IFACE);
+    const iccid = stringProp(sim, 'SimIdentifier');
+    return iccid !== undefined && iccid.length > 0 ? makeSubscriptionId(iccid) : undefined;
+}
+/**
+ * The SIM's own number(s) from `Modem.OwnNumbers`, or `undefined` when the
+ * carrier published none. Most SIMs carry no MSISDN at all, so an absent or
+ * empty property is the ordinary case and must read as "not reported" rather
+ * than as an empty list an operator could mistake for a failed read.
+ */
+function readOwnNumbers(modem) {
+    const raw = stringArrayProp(modem, 'OwnNumbers');
+    if (raw === undefined) {
+        return undefined;
+    }
+    const numbers = raw
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)
+        .map((value) => makeSubscriberNumber(value));
+    return numbers.length > 0 ? numbers : undefined;
+}
+/** Map ONE modem object to its dimensions. The modem must expose `Modem`. */
+export function mapModem(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const modem3gpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const equipment = stringProp(modem, 'EquipmentIdentifier') ?? stringProp(modem3gpp, 'Imei') ?? '';
+    const mmState = mapMmState(numberProp(modem, 'State'));
+    const radioPower = reconcilePower(mapRadioPower(numberProp(modem, 'PowerState')), mmState);
+    const sub = readSubscriptionId(tree, modemPath);
+    const ownNumbers = readOwnNumbers(modem);
+    return {
+        identity: {
+            equipmentId: imeiEquipmentId(equipment),
+            runtimePath: runtimePath(modemPath),
+            ...(sub !== undefined ? { subscriptionId: sub } : {}),
+            ...(ownNumbers !== undefined ? { ownNumbers } : {}),
+        },
+        presence: 'present',
+        sourceHealth: 'live',
+        simSlots: [],
+        radioPower,
+        mmState,
+        // Conservative: 3GPP registration + RAT set are A3.3's job (see file header).
+        registration: { status: 'unknown', activeRats: new Set() },
+        nmActivation: 'unavailable',
+        dataInterface: { present: false },
+        reconcileStatus: 'pending',
+        recoveryState: { stage: 'idle', attempts: 0 },
+    };
+}
+/** Every modem path in the tree (objects exposing the `Modem` interface), in order. */
+export function modemPaths(tree) {
+    return pathsWithInterface(tree, MODEM_IFACE);
+}
+/** A stable fingerprint of a mapped modem's meaningful dimensions (ignores revision
+ *  and source health), used to suppress redundant revision bumps on identical reads. */
+export function fingerprint(mapped) {
+    return JSON.stringify({
+        id: mapped.identity.equipmentId,
+        sub: mapped.identity.subscriptionId ?? null,
+        own: mapped.identity.ownNumbers ?? null,
+        path: mapped.identity.runtimePath,
+        presence: mapped.presence,
+        radioPower: mapped.radioPower,
+        mmState: mapped.mmState,
+        registration: {
+            status: mapped.registration.status,
+            rats: [...mapped.registration.activeRats].sort(),
+        },
+        nmActivation: mapped.nmActivation,
+        dataInterface: mapped.dataInterface,
+        reconcileStatus: mapped.reconcileStatus,
+    });
+}

package/dist/backend/mm-backend.d.ts

@@ -0,0 +1,44 @@
+import type { DesiredRadio } from '../domain/index.js';
+import type { BandReadResult, InhibitLease, ModemManagerPort, ModemRef, NetworkScanResult, ObservationList, ObservationListener, Receipt, SimPukUnlockResult, SimUnlockResult, Unsubscribe } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import { type CellReading } from './cell-info.js';
+import { type ModemEnrichment } from './enrichment.js';
+import { ModemActor, type QuiesceHook } from './modem-actor.js';
+import { type SignalCadence } from './signal-setup.js';
+export interface MmDbusBackendOptions {
+    readonly transport: DbusTransport;
+    readonly destination?: string;
+    readonly actor?: ModemActor;
+    /** NM quiesce hook for disruptive mode/slot changes (A3.3 default: no-op). */
+    readonly quiesce?: QuiesceHook;
+    /** Signal.Setup reporting interval in seconds. */
+    readonly signalIntervalSeconds?: number;
+    readonly scanTimeoutMs?: number;
+    readonly now?: () => number;
+}
+/** The real D-Bus ModemManager backend: observation + mutations + Signal.Setup. */
+export declare class MmDbusBackend implements ModemManagerPort {
+    #private;
+    constructor(options: MmDbusBackendOptions);
+    start(): Promise<ObservationList>;
+    observe(listener: ObservationListener): Unsubscribe;
+    stop(): Promise<void>;
+    setRadioModes(modem: ModemRef, preference: DesiredRadio): Promise<Receipt>;
+    setModeCombination(modem: ModemRef, allowed: number, preferred: number): Promise<Receipt>;
+    setPrimarySimSlot(modem: ModemRef, slotIndex: number): Promise<Receipt>;
+    readBands(modem: ModemRef): Promise<BandReadResult>;
+    setCurrentBands(modem: ModemRef, bands: readonly string[]): Promise<Receipt>;
+    sendPin(modem: ModemRef, pin: string): Promise<SimUnlockResult>;
+    sendPuk(modem: ModemRef, puk: string, newPin: string): Promise<SimPukUnlockResult>;
+    scanNetworks(modem: ModemRef): Promise<NetworkScanResult>;
+    inhibit(uid: string): Promise<InhibitLease>;
+    uninhibit(lease: InhibitLease): Promise<void>;
+    /** Whether periodic signal reporting is configured for a modem (Signal.Setup). */
+    signalCadence(modem: ModemRef): SignalCadence;
+    /** Read the normalized visible-cell list for a modem via `Modem.GetCellInfo`. */
+    readCellInfo(modem: ModemRef): Promise<readonly CellReading[]>;
+    /** Assemble the full read-only enrichment (revision, eSIM, cadence, cell info). */
+    readEnrichment(modem: ModemRef): Promise<ModemEnrichment>;
+}
+/** Construct the real D-Bus ModemManager backend over an A2.4 transport. */
+export declare function createMmDbusBackend(options: MmDbusBackendOptions): MmDbusBackend;

package/dist/backend/mm-backend.js

@@ -0,0 +1,154 @@
+// MmDbusBackend — the real D-Bus `ModemManagerPort`, composed from the A3 parts.
+//
+// It fulfils the whole port: the read side delegates to A3.1's epoch-scoped observer;
+// the mutations run through `MmMutations` (each serialized on the shared per-modem
+// `ModemActor`, keyed on A3.2's STABLE key so serialization survives replug); the
+// Signal.Setup lifecycle is driven off the observer's `onEpochRefresh` hook; and the
+// read-only enrichment (firmware revision, eSIM, signal cadence, normalized cell info)
+// is assembled on demand. One transport is shared by all of them.
+//
+// The `onEpochRefresh` hook is the single integration seam: on every current-epoch
+// authoritative snapshot it (1) rebuilds the live path → stable-key map (so a mutation
+// keys the actor by the durable identity, not the transient path) and (2) re-drives
+// Signal.Setup for that epoch — applying to new modems, re-applying to survivors after
+// an owner change, and never firing for a superseded epoch.
+import { epochMillis } from '../domain/index.js';
+import { normalizeCellInfo } from './cell-info.js';
+import { MM_BUS_NAME, MODEM_IFACE } from './constants.js';
+import { buildEnrichment } from './enrichment.js';
+import { modemIdentityFactsFromTree, resolveModemIdentities } from './identity-ladder.js';
+import { fetchManagedObjects, pathsWithInterface } from './managed-objects.js';
+import { MmMutations } from './mm-mutations.js';
+import { ModemActor } from './modem-actor.js';
+import { createMmDbusObserver } from './observer.js';
+import { SignalSetupManager } from './signal-setup.js';
+/** The real D-Bus ModemManager backend: observation + mutations + Signal.Setup. */
+export class MmDbusBackend {
+    #transport;
+    #destination;
+    #now;
+    #observer;
+    #mutations;
+    #signalSetup;
+    // Live modem path → durable stable key; rebuilt on every epoch snapshot.
+    #stableKeyByPath = new Map();
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#destination = options.destination ?? MM_BUS_NAME;
+        this.#now = options.now ?? Date.now;
+        const actor = options.actor ?? new ModemActor(options.quiesce);
+        this.#signalSetup = new SignalSetupManager({
+            transport: this.#transport,
+            destination: this.#destination,
+            ...(options.signalIntervalSeconds !== undefined
+                ? { intervalSeconds: options.signalIntervalSeconds }
+                : {}),
+        });
+        this.#observer = createMmDbusObserver({
+            transport: this.#transport,
+            destination: this.#destination,
+            onEpochRefresh: (event) => this.#onEpochRefresh(event),
+        });
+        this.#mutations = new MmMutations({
+            transport: this.#transport,
+            actor,
+            destination: this.#destination,
+            resolveStableKey: (modem) => this.#stableKeyByPath.get(modem) ?? modem,
+            ...(options.scanTimeoutMs !== undefined ? { scanTimeoutMs: options.scanTimeoutMs } : {}),
+            now: this.#now,
+        });
+    }
+    // ── observation (delegated to the A3.1 observer) ────────────────────────────────
+    start() {
+        return this.#observer.start();
+    }
+    observe(listener) {
+        return this.#observer.observe(listener);
+    }
+    stop() {
+        return this.#observer.stop();
+    }
+    // ── mutations (serialized per modem through the shared actor) ────────────────────
+    setRadioModes(modem, preference) {
+        return this.#mutations.setRadioModes(modem, preference);
+    }
+    setModeCombination(modem, allowed, preferred) {
+        return this.#mutations.setModeCombination(modem, allowed, preferred);
+    }
+    setPrimarySimSlot(modem, slotIndex) {
+        return this.#mutations.setPrimarySimSlot(modem, slotIndex);
+    }
+    readBands(modem) {
+        return this.#mutations.readBands(modem);
+    }
+    setCurrentBands(modem, bands) {
+        return this.#mutations.setCurrentBands(modem, bands);
+    }
+    sendPin(modem, pin) {
+        return this.#mutations.sendPin(modem, pin);
+    }
+    sendPuk(modem, puk, newPin) {
+        return this.#mutations.sendPuk(modem, puk, newPin);
+    }
+    scanNetworks(modem) {
+        return this.#mutations.scanNetworks(modem);
+    }
+    inhibit(uid) {
+        return this.#mutations.inhibit(uid);
+    }
+    uninhibit(lease) {
+        return this.#mutations.uninhibit(lease);
+    }
+    // ── enrichment (additive, read-only, never gating) ──────────────────────────────
+    /** Whether periodic signal reporting is configured for a modem (Signal.Setup). */
+    signalCadence(modem) {
+        return this.#signalSetup.cadenceFor(modem);
+    }
+    /** Read the normalized visible-cell list for a modem via `Modem.GetCellInfo`. */
+    async readCellInfo(modem) {
+        const provenance = { source: modem, observedAt: epochMillis(this.#now()) };
+        try {
+            const reply = await this.#transport.callMethod({
+                destination: this.#destination,
+                path: modem,
+                interface: MODEM_IFACE,
+                member: 'GetCellInfo',
+            });
+            const cells = Array.isArray(reply.body[0])
+                ? reply.body[0]
+                : [];
+            return normalizeCellInfo(cells, provenance);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Assemble the full read-only enrichment (revision, eSIM, cadence, cell info). */
+    async readEnrichment(modem) {
+        const [tree, cellInfo] = await Promise.all([
+            fetchManagedObjects(this.#transport, this.#destination),
+            this.readCellInfo(modem),
+        ]);
+        return buildEnrichment(tree, modem, this.#signalSetup.cadenceFor(modem), cellInfo);
+    }
+    #onEpochRefresh(event) {
+        this.#refreshStableKeys(event);
+        this.#signalSetup.applyForEpoch(event.epoch, event.tree);
+    }
+    #refreshStableKeys(event) {
+        const paths = pathsWithInterface(event.tree, MODEM_IFACE);
+        const facts = paths.map((path) => modemIdentityFactsFromTree(event.tree, path));
+        const resolved = resolveModemIdentities(facts);
+        this.#stableKeyByPath.clear();
+        paths.forEach((path, index) => {
+            const entry = resolved[index];
+            if (entry !== undefined) {
+                this.#stableKeyByPath.set(path, entry.stableKey);
+            }
+        });
+    }
+}
+/** Construct the real D-Bus ModemManager backend over an A2.4 transport. */
+export function createMmDbusBackend(options) {
+    return new MmDbusBackend(options);
+}

package/dist/backend/mm-location.d.ts

@@ -0,0 +1,21 @@
+import type { FixRead, GnssSource, LocationStatusResult, LocationToggleResult, ModemLocationPort, ModemRef } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import type { ModemActor } from './modem-actor.js';
+/** Decode an MMModemLocationSource bitmask into source names. */
+export declare function decodeLocationSources(mask: number): ReadonlySet<string>;
+export declare function encodeLocationSources(sources: Iterable<string>): number;
+export interface MmLocationDeps {
+    readonly transport: DbusTransport;
+    readonly actor: ModemActor;
+    readonly destination?: string;
+    readonly resolveStableKey: (modem: ModemRef) => string;
+    readonly now?: () => number;
+}
+export declare class MmLocation implements ModemLocationPort {
+    #private;
+    constructor(deps: MmLocationDeps);
+    getLocationStatus(modem: ModemRef): Promise<LocationStatusResult>;
+    enableGnss(modem: ModemRef, sources: readonly GnssSource[]): Promise<LocationToggleResult>;
+    disableGnss(modem: ModemRef): Promise<LocationToggleResult>;
+    readFix(modem: ModemRef): Promise<FixRead>;
+}