@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/ussd/refusal.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Every way a USSD verb can fail to do what the operator asked.
+ *
+ *   unsupported          — this modem exposes no USSD interface at all.
+ *   lte-only-unsupported — the modem is registered PS-only (LTE/5G with no CS
+ *                          domain) and the network refused. NOT a device fault.
+ *   carrier-rejected     — the network refused for some other reason.
+ *   not-registered       — there is no network to carry the session.
+ *   session-busy         — a session is already open (locally or network-side).
+ *   no-session           — respond/cancel with nothing open.
+ *   invalid-state        — the verb is wrong for the state the session is in.
+ *   timeout              — the bounded wait elapsed with no answer.
+ *   transport-failed     — the bus call itself failed; the modem never answered.
+ */
+export declare const USSD_REFUSAL_REASONS: readonly ["unsupported", "lte-only-unsupported", "carrier-rejected", "not-registered", "session-busy", "no-session", "invalid-state", "timeout", "transport-failed"];
+export type UssdRefusalReason = (typeof USSD_REFUSAL_REASONS)[number];
+/**
+ * What the modem is registered on, as far as anyone has looked.
+ *
+ * `csDomain` is the load-bearing field: `false` means the modem is attached with
+ * NO circuit-switched domain available (LTE/5G-SA without CSFB), which is the
+ * registration on which a plain USSD refusal is a carrier-policy statement rather
+ * than a device one. `undefined` means nobody read it, and is never treated as
+ * `false`.
+ */
+export interface UssdRegistrationFacts {
+    readonly registered: boolean;
+    /** Is a circuit-switched domain available on this registration? */
+    readonly csDomain?: boolean;
+    /** MM access technologies currently in use, lowercased (`lte`, `5gnr`, …). */
+    readonly accessTechnologies?: readonly string[];
+}
+/**
+ * True when the modem's registration positively cannot carry a circuit-switched
+ * service. Requires evidence in BOTH directions: something must say the CS domain
+ * is absent, and every technology in use must be a packet-only one. A modem that
+ * reported no technologies at all answers `false` — an empty list is a statement
+ * about the read.
+ */
+export declare function isPacketSwitchedOnly(facts: UssdRegistrationFacts): boolean;
+/**
+ * Classify a failed USSD call. Pure, total, never throws.
+ *
+ * Order is deliberate: the D-Bus error NAME is the strongest signal and is read
+ * first; the message text is consulted only for the names MM overloads; anything
+ * unrecognised stays `transport-failed`, which is the honest answer for a failure
+ * whose origin cannot be attributed to the network.
+ *
+ * The PS-only promotion runs LAST and applies to exactly the two reasons that are
+ * ambiguous between a device limit and a carrier policy — a `not-registered` or a
+ * bus failure is neither, and is left alone.
+ */
+export declare function classifyUssdFailure(error: unknown, registration?: UssdRegistrationFacts): UssdRefusalReason;

package/dist/ussd/refusal.js

@@ -0,0 +1,154 @@
+// Why a USSD verb did not succeed — one typed vocabulary, and the classifier that
+// maps ModemManager's own failure surface onto it.
+//
+// The point of typing these is that every member names a DIFFERENT thing the
+// operator can do, and the one this module exists for is the honest reporting of
+// a carrier that will not carry USSD at all on the registration the modem has.
+//
+// THE LTE-ONLY CASE, stated plainly. USSD is a circuit-switched supplementary
+// service. A modem registered PS-only — LTE or 5G-SA with no CS domain and no
+// CSFB — can only carry it if the operator deploys USSI (USSD over IMS, 3GPP TS
+// 24.390); many do not, and the modem/network then answers a generic
+// unsupported/failed error that is indistinguishable, on its face, from "this
+// modem has no USSD interface". Reporting that as a device limitation would send
+// an operator hunting for a firmware fix for a network policy, so the classifier
+// takes the modem's REGISTRATION alongside the error and separates the two.
+//
+// Nothing here guesses: `lte-only-unsupported` is claimed ONLY when the
+// registration is positively known to be PS-only. An unknown registration keeps
+// the generic reason, because "we did not look" is not evidence.
+/**
+ * Every way a USSD verb can fail to do what the operator asked.
+ *
+ *   unsupported          — this modem exposes no USSD interface at all.
+ *   lte-only-unsupported — the modem is registered PS-only (LTE/5G with no CS
+ *                          domain) and the network refused. NOT a device fault.
+ *   carrier-rejected     — the network refused for some other reason.
+ *   not-registered       — there is no network to carry the session.
+ *   session-busy         — a session is already open (locally or network-side).
+ *   no-session           — respond/cancel with nothing open.
+ *   invalid-state        — the verb is wrong for the state the session is in.
+ *   timeout              — the bounded wait elapsed with no answer.
+ *   transport-failed     — the bus call itself failed; the modem never answered.
+ */
+export const USSD_REFUSAL_REASONS = [
+    'unsupported',
+    'lte-only-unsupported',
+    'carrier-rejected',
+    'not-registered',
+    'session-busy',
+    'no-session',
+    'invalid-state',
+    'timeout',
+    'transport-failed',
+];
+/** Access technologies that carry no circuit-switched domain of their own. */
+const PACKET_ONLY_RATS = new Set([
+    'lte',
+    '5gnr',
+    'lte-cat-m',
+    'lte-nb-iot',
+]);
+/**
+ * True when the modem's registration positively cannot carry a circuit-switched
+ * service. Requires evidence in BOTH directions: something must say the CS domain
+ * is absent, and every technology in use must be a packet-only one. A modem that
+ * reported no technologies at all answers `false` — an empty list is a statement
+ * about the read.
+ */
+export function isPacketSwitchedOnly(facts) {
+    if (!facts.registered) {
+        return false;
+    }
+    if (facts.csDomain !== false) {
+        return false;
+    }
+    const rats = facts.accessTechnologies;
+    if (rats === undefined || rats.length === 0) {
+        return false;
+    }
+    return rats.every((rat) => PACKET_ONLY_RATS.has(rat.toLowerCase()));
+}
+/**
+ * ModemManager D-Bus error names this classifier recognises, matched on the
+ * SUFFIX after the last dot so a future `...Error.Core.Unsupported` regrouping
+ * does not silently fall through to `transport-failed`.
+ */
+const ERROR_SUFFIX_REASONS = new Map([
+    ['Unsupported', 'unsupported'],
+    ['NotSupported', 'unsupported'],
+    ['InProgress', 'session-busy'],
+    ['NoNetwork', 'not-registered'],
+    ['NotRegistered', 'not-registered'],
+    ['Timeout', 'timeout'],
+    ['Aborted', 'carrier-rejected'],
+    ['Failed', 'carrier-rejected'],
+]);
+/**
+ * Message fragments that identify a refusal no error NAME distinguishes. MM
+ * folds several modem answers into `Core.Failed`, so the text is the only signal
+ * separating "the network said no" from "the bus call broke".
+ */
+const MESSAGE_REASONS = [
+    [/ussd.*(?:not supported|unsupported)/i, 'unsupported'],
+    [/(?:session|operation) (?:already )?(?:active|in progress)/i, 'session-busy'],
+    [/no (?:active )?ussd session/i, 'no-session'],
+    [/not registered|no network/i, 'not-registered'],
+    [/timed? ?out/i, 'timeout'],
+    [/rejected|refused|denied|network error/i, 'carrier-rejected'],
+];
+function errorName(error) {
+    if (typeof error !== 'object' || error === null) {
+        return undefined;
+    }
+    const name = error.dbusName;
+    if (typeof name === 'string' && name.includes('.')) {
+        return name;
+    }
+    const fallback = error.name;
+    return typeof fallback === 'string' && fallback.includes('.') ? fallback : undefined;
+}
+function errorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'object' && error !== null) {
+        const message = error.message;
+        if (typeof message === 'string') {
+            return message;
+        }
+    }
+    return String(error);
+}
+/**
+ * Classify a failed USSD call. Pure, total, never throws.
+ *
+ * Order is deliberate: the D-Bus error NAME is the strongest signal and is read
+ * first; the message text is consulted only for the names MM overloads; anything
+ * unrecognised stays `transport-failed`, which is the honest answer for a failure
+ * whose origin cannot be attributed to the network.
+ *
+ * The PS-only promotion runs LAST and applies to exactly the two reasons that are
+ * ambiguous between a device limit and a carrier policy — a `not-registered` or a
+ * bus failure is neither, and is left alone.
+ */
+export function classifyUssdFailure(error, registration = { registered: false }) {
+    const name = errorName(error);
+    const suffix = name?.slice(name.lastIndexOf('.') + 1);
+    const message = errorMessage(error);
+    let reason = suffix === undefined ? undefined : ERROR_SUFFIX_REASONS.get(suffix);
+    // `Core.Failed` is MM's catch-all, so its message is worth more than its name.
+    if (reason === undefined || reason === 'carrier-rejected') {
+        for (const [pattern, mapped] of MESSAGE_REASONS) {
+            if (pattern.test(message)) {
+                reason = mapped;
+                break;
+            }
+        }
+    }
+    if (reason === undefined) {
+        return 'transport-failed';
+    }
+    const ambiguous = reason === 'unsupported' || reason === 'carrier-rejected';
+    return ambiguous && isPacketSwitchedOnly(registration) ? 'lte-only-unsupported' : reason;
+}

package/dist/ussd/registration.d.ts

@@ -0,0 +1,20 @@
+import { type DecodedManagedObjects } from '../backend/managed-objects.js';
+import type { DbusTransport } from '../transport/index.js';
+import type { UssdRegistrationFacts } from './refusal.js';
+/** Decode `Modem.AccessTechnologies` into the technology names in use. */
+export declare function decodeAccessTechnologies(mask: number): readonly string[];
+/**
+ * Derive the registration facts from an already-fetched managed-objects tree.
+ *
+ * Pure, so the derivation is testable against a fixture tree without a bus — the
+ * `sim-unlock.ts` split between "read the tree" and "decide from the tree".
+ */
+export declare function registrationFactsFromTree(tree: DecodedManagedObjects, modemPath: string): UssdRegistrationFacts;
+/** The unread default — every field withheld, so nothing can be claimed from it. */
+export declare const UNKNOWN_REGISTRATION: UssdRegistrationFacts;
+/**
+ * Read the registration facts for one modem. Fail-soft: a tree we could not fetch
+ * yields {@link UNKNOWN_REGISTRATION}, which can only ever make the refusal LESS
+ * specific.
+ */
+export declare function readUssdRegistrationFacts(transport: DbusTransport, destination: string, modemPath: string): Promise<UssdRegistrationFacts>;

package/dist/ussd/registration.js

@@ -0,0 +1,101 @@
+// Reading the registration facts the USSD refusal classifier needs.
+//
+// ModemManager publishes NO "is a circuit-switched domain available" property, so
+// the fact has to be DERIVED — and the derivation is worth stating, because it is
+// the difference between telling an operator their modem cannot do USSD and
+// telling them their carrier will not carry it on this registration:
+//
+//   * `Modem.AccessTechnologies` is a bitmask. When every bit in use is a
+//     packet-only radio (LTE, 5G-NR, LTE-M, NB-IoT) the modem is not camped on a
+//     circuit-switched radio at all.
+//   * `Modem3gpp.RegistrationState` still overrides that, because CS FALLBACK is
+//     exactly the case where an LTE-camped modem CAN reach the CS domain. MM has
+//     two states that say so outright — `HOME_CSFB_NOT_PREFERRED` (9) and
+//     `ROAMING_CSFB_NOT_PREFERRED` (10) — and a modem in either of them is
+//     reported CS-capable regardless of its radio.
+//
+// Both reads are best-effort and NEVER throw: a fact nobody could read is left
+// `undefined`, which the classifier treats as "we did not look" rather than as a
+// negative. That asymmetry is the whole safety property — an unread registration
+// can only ever produce the generic refusal, never the more specific claim.
+import { MODEM_IFACE, MODEM3GPP_IFACE } from '../backend/constants.js';
+import { fetchManagedObjects, findInterface, numberProp, } from '../backend/managed-objects.js';
+/** `MMModemAccessTechnology` bits this module names. */
+const ACCESS_TECHNOLOGY_BITS = [
+    [1 << 1, 'gsm'],
+    [1 << 2, 'gsm-compact'],
+    [1 << 3, 'gprs'],
+    [1 << 4, 'edge'],
+    [1 << 5, 'umts'],
+    [1 << 6, 'hsdpa'],
+    [1 << 7, 'hsupa'],
+    [1 << 8, 'hspa'],
+    [1 << 9, 'hspa-plus'],
+    [1 << 10, '1xrtt'],
+    [1 << 11, 'evdo0'],
+    [1 << 12, 'evdoa'],
+    [1 << 13, 'evdob'],
+    [1 << 14, 'lte'],
+    [1 << 15, '5gnr'],
+    [1 << 16, 'lte-cat-m'],
+    [1 << 17, 'lte-nb-iot'],
+];
+/** `MMModem3gppRegistrationState` values that mean the modem is on a network. */
+const REGISTERED_STATES = new Set([1, 5, 6, 7, 9, 10]);
+/** …and the two that positively advertise a circuit-switched fallback. */
+const CSFB_STATES = new Set([9, 10]);
+/** Decode `Modem.AccessTechnologies` into the technology names in use. */
+export function decodeAccessTechnologies(mask) {
+    const names = [];
+    for (const [bit, name] of ACCESS_TECHNOLOGY_BITS) {
+        if ((mask & bit) !== 0) {
+            names.push(name);
+        }
+    }
+    return names;
+}
+/**
+ * Derive the registration facts from an already-fetched managed-objects tree.
+ *
+ * Pure, so the derivation is testable against a fixture tree without a bus — the
+ * `sim-unlock.ts` split between "read the tree" and "decide from the tree".
+ */
+export function registrationFactsFromTree(tree, modemPath) {
+    const modem = findInterface(tree, modemPath, MODEM_IFACE);
+    const threeGpp = findInterface(tree, modemPath, MODEM3GPP_IFACE);
+    const registrationState = numberProp(threeGpp, 'RegistrationState');
+    const accessMask = numberProp(modem, 'AccessTechnologies');
+    const registered = registrationState !== undefined && REGISTERED_STATES.has(registrationState);
+    const technologies = accessMask === undefined ? undefined : decodeAccessTechnologies(accessMask);
+    // A CSFB registration is CS-capable outright. Otherwise the domain is only
+    // declared ABSENT when the radios in use were actually read and are all
+    // packet-only; an unread mask leaves the field undefined on purpose.
+    let csDomain;
+    if (registrationState !== undefined && CSFB_STATES.has(registrationState)) {
+        csDomain = true;
+    }
+    else if (technologies !== undefined && technologies.length > 0) {
+        csDomain = technologies.some((rat) => rat !== 'lte' && rat !== '5gnr' && rat !== 'lte-cat-m' && rat !== 'lte-nb-iot');
+    }
+    return {
+        registered,
+        ...(csDomain === undefined ? {} : { csDomain }),
+        ...(technologies === undefined ? {} : { accessTechnologies: technologies }),
+    };
+}
+/** The unread default — every field withheld, so nothing can be claimed from it. */
+export const UNKNOWN_REGISTRATION = { registered: false };
+/**
+ * Read the registration facts for one modem. Fail-soft: a tree we could not fetch
+ * yields {@link UNKNOWN_REGISTRATION}, which can only ever make the refusal LESS
+ * specific.
+ */
+export async function readUssdRegistrationFacts(transport, destination, modemPath) {
+    try {
+        const tree = await fetchManagedObjects(transport, destination);
+        return registrationFactsFromTree(tree, modemPath);
+    }
+    catch {
+        return UNKNOWN_REGISTRATION;
+    }
+}

package/dist/ussd/session.d.ts

@@ -0,0 +1,84 @@
+import type { UssdRefusalReason } from './refusal.js';
+/**
+ * Session states.
+ *
+ * Three of them (`idle`, `active`, `awaiting-reply`) mirror MM's own
+ * `MMModem3gppUssdSessionState`; the rest are LOCAL in-flight states, because MM
+ * has no state for "we dispatched a call and the reply has not landed". Without
+ * them a second `initiate` racing the first would be judged against `idle` and
+ * allowed through, which is exactly the double-open the network answers busy.
+ */
+export declare const USSD_SESSION_STATES: readonly ["idle", "initiating", "active", "awaiting-reply", "responding", "cancelling", "closed"];
+export type UssdSessionState = (typeof USSD_SESSION_STATES)[number];
+/** How a session that reached `closed` got there. */
+export declare const USSD_SESSION_OUTCOMES: readonly ["completed", "cancelled", "timed-out", "failed"];
+export type UssdSessionOutcome = (typeof USSD_SESSION_OUTCOMES)[number];
+/** MM's post-call session state, decoded. */
+export type UssdRepliedState = 'awaiting-reply' | 'active' | 'released';
+export type UssdSessionEvent = 
+/** The operator asked to open a session. */
+{
+    readonly kind: 'initiate';
+}
+/** The operator answered a network prompt. */
+ | {
+    readonly kind: 'respond';
+}
+/** The operator asked to close the session. */
+ | {
+    readonly kind: 'cancel';
+}
+/**
+ * The network answered an `Initiate`/`Respond`. `sessionState` is MM's own
+ * post-call `Modem3gpp.Ussd.State`, decoded: the network either wants an
+ * answer, is holding the session open with nothing pending, or released it.
+ */
+ | {
+    readonly kind: 'replied';
+    readonly sessionState: UssdRepliedState;
+}
+/** A `Cancel` was confirmed by the modem. */
+ | {
+    readonly kind: 'cancelled';
+}
+/** The network released the session without our asking (notification path). */
+ | {
+    readonly kind: 'network-released';
+}
+/** The bounded wait elapsed with no answer. */
+ | {
+    readonly kind: 'timeout';
+}
+/** The call failed. The reason is carried onto the terminal state verbatim. */
+ | {
+    readonly kind: 'failed';
+    readonly reason: UssdRefusalReason;
+};
+export interface UssdSessionSnapshot {
+    readonly state: UssdSessionState;
+    /** Present only at `closed`. */
+    readonly outcome?: UssdSessionOutcome;
+    /** Present only at `closed` with outcome `failed`. */
+    readonly refusal?: UssdRefusalReason;
+}
+export type UssdTransition = {
+    readonly ok: true;
+    readonly snapshot: UssdSessionSnapshot;
+}
+/** The verb is not legal in this state, and the machine did NOT move. */
+ | {
+    readonly ok: false;
+    readonly refusal: UssdRefusalReason;
+};
+export declare const IDLE_SESSION: UssdSessionSnapshot;
+/**
+ * Apply one event. TOTAL: every (state, event) pair has an answer, and an answer
+ * is either a new snapshot or a typed refusal that leaves the machine untouched.
+ *
+ * A `closed` machine accepts NOTHING — not even another `cancel`. Re-opening a
+ * terminal session would hide the fact that the previous one ended, and the
+ * cost of a fresh machine is one object.
+ */
+export declare function reduceUssdSession(snapshot: UssdSessionSnapshot, event: UssdSessionEvent): UssdTransition;
+/** True while the session still holds a network dialogue open. */
+export declare function isUssdSessionOpen(snapshot: UssdSessionSnapshot): boolean;

package/dist/ussd/session.js

@@ -0,0 +1,163 @@
+// The USSD session state machine — pure, total, and the only place a session's
+// legality is decided.
+//
+// USSD is a SESSION protocol, not a request/response one: `Initiate` opens a
+// dialogue the network may keep open pending a `Respond`, and a session that is
+// neither responded to nor cancelled stays open on the NETWORK side, consuming a
+// scarce per-subscriber slot and blocking the next `Initiate` with a busy error.
+// So "which verb is legal right now" is a real question with a real wrong answer,
+// and answering it inside the D-Bus adapter would make it untestable without a
+// bus. It lives here instead, as data.
+//
+// Everything the machine can be told is an EVENT and every answer is a
+// TRANSITION — an illegal verb is REFUSED with a typed reason, never thrown and
+// never silently ignored. A refusal at an RPC boundary must name what the caller
+// can do about it; a throw becomes an opaque failure and a silent no-op becomes a
+// UI that spins forever.
+//
+// The machine carries NO carrier text. The reply an operator sees is threaded by
+// the adapter and redacted at every log boundary (`../redact`); keeping it out of
+// the state entirely means a state snapshot can never leak one.
+/**
+ * Session states.
+ *
+ * Three of them (`idle`, `active`, `awaiting-reply`) mirror MM's own
+ * `MMModem3gppUssdSessionState`; the rest are LOCAL in-flight states, because MM
+ * has no state for "we dispatched a call and the reply has not landed". Without
+ * them a second `initiate` racing the first would be judged against `idle` and
+ * allowed through, which is exactly the double-open the network answers busy.
+ */
+export const USSD_SESSION_STATES = [
+    /** No session. MM `IDLE`. */
+    'idle',
+    /** `Initiate` dispatched, reply outstanding. Local. */
+    'initiating',
+    /** Network answered and the session is open with nothing pending. MM `ACTIVE`. */
+    'active',
+    /** Network asked a question; a `Respond` is required. MM `USER_RESPONSE`. */
+    'awaiting-reply',
+    /** `Respond` dispatched, reply outstanding. Local. */
+    'responding',
+    /** `Cancel` dispatched, confirmation outstanding. Local. */
+    'cancelling',
+    /** Terminal for this session object. A new session starts from a new machine. */
+    'closed',
+];
+/** How a session that reached `closed` got there. */
+export const USSD_SESSION_OUTCOMES = [
+    /** The network completed the dialogue and released the session. */
+    'completed',
+    /** The operator cancelled it. */
+    'cancelled',
+    /** No answer within the bound; the machine closed it locally. */
+    'timed-out',
+    /** The network or the modem refused. `refusal` names which. */
+    'failed',
+];
+export const IDLE_SESSION = { state: 'idle' };
+/** States in which an operator verb may be dispatched at all. */
+const ACCEPTS_INITIATE = new Set(['idle']);
+const ACCEPTS_RESPOND = new Set([
+    'awaiting-reply',
+]);
+const ACCEPTS_CANCEL = new Set([
+    'initiating',
+    'active',
+    'awaiting-reply',
+    'responding',
+]);
+/** States with a call in flight — the only ones a network answer may land on. */
+const IN_FLIGHT = new Set([
+    'initiating',
+    'responding',
+]);
+function open(state) {
+    return { ok: true, snapshot: { state } };
+}
+function close(outcome, refusal) {
+    return {
+        ok: true,
+        snapshot: { state: 'closed', outcome, ...(refusal === undefined ? {} : { refusal }) },
+    };
+}
+function refuse(refusal) {
+    return { ok: false, refusal };
+}
+/**
+ * Apply one event. TOTAL: every (state, event) pair has an answer, and an answer
+ * is either a new snapshot or a typed refusal that leaves the machine untouched.
+ *
+ * A `closed` machine accepts NOTHING — not even another `cancel`. Re-opening a
+ * terminal session would hide the fact that the previous one ended, and the
+ * cost of a fresh machine is one object.
+ */
+export function reduceUssdSession(snapshot, event) {
+    const state = snapshot.state;
+    if (state === 'closed') {
+        return refuse('no-session');
+    }
+    // Every event except `initiate` describes something happening TO a session,
+    // and an idle machine has none for them to happen to.
+    const sessionOpen = state !== 'idle';
+    switch (event.kind) {
+        case 'initiate':
+            // A session already in flight or open is the busy case the network
+            // itself would answer — refused locally so no second dialogue is opened.
+            return ACCEPTS_INITIATE.has(state) ? open('initiating') : refuse('session-busy');
+        case 'respond':
+            // Responding to a session that never asked a question is not a busy
+            // device; it is the wrong verb, and `invalid-state` says so.
+            return ACCEPTS_RESPOND.has(state) ? open('responding') : refuse('invalid-state');
+        case 'cancel':
+            // The two refusals are different operator facts: nothing to close, vs a
+            // cancel that is already in flight.
+            if (ACCEPTS_CANCEL.has(state)) {
+                return open('cancelling');
+            }
+            return refuse(sessionOpen ? 'invalid-state' : 'no-session');
+        case 'replied':
+            // A network answer that lands on a state with no call in flight is
+            // evidence of a lost reply or a duplicate; it is refused rather than
+            // used to resurrect a session the machine already moved past.
+            if (!IN_FLIGHT.has(state)) {
+                return refuse('invalid-state');
+            }
+            // The three-way answer is the dialogue-vs-one-shot distinction, and
+            // collapsing `active` into `released` is what would leave a session MM
+            // still considers open dangling on the network side.
+            if (event.sessionState === 'released') {
+                return close('completed');
+            }
+            return open(event.sessionState);
+        case 'cancelled':
+            // Only a machine that asked to cancel may be closed by one, so a stray
+            // confirmation cannot tear down a live dialogue.
+            return state === 'cancelling' ? close('cancelled') : refuse('invalid-state');
+        case 'network-released':
+            // The network is authoritative about its own session, so this lands
+            // from anywhere the session is still open — including mid-call, where
+            // it is the honest end of a dialogue whose reply will not come. During
+            // a cancel it is reported as `cancelled`: the operator asked for the
+            // session to end and it ended.
+            if (!sessionOpen) {
+                return refuse('no-session');
+            }
+            return close(state === 'cancelling' ? 'cancelled' : 'completed');
+        case 'timeout':
+            // The bound closes rather than reverting: after an unanswered call the
+            // network's own view is unknown, and pretending we are back at `idle`
+            // would let the next `initiate` walk into a busy error with no
+            // explanation.
+            return sessionOpen ? close('timed-out') : refuse('no-session');
+        case 'failed':
+            return sessionOpen ? close('failed', event.reason) : refuse('no-session');
+        default: {
+            const unreachable = event;
+            return unreachable;
+        }
+    }
+}
+/** True while the session still holds a network dialogue open. */
+export function isUssdSessionOpen(snapshot) {
+    return snapshot.state !== 'idle' && snapshot.state !== 'closed';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ceralive/modem-control",
-	"version": "0.2.0",
+	"version": "1.1.0",
 	"type": "module",
 	"description": "Cellular modem control for CeraLive — ModemManager D-Bus backend, NetworkManager adapter, desired-state reconciler, USB composition-mode model, data-usage sampler.",
 	"license": "AGPL-3.0",
@@ -13,14 +13,48 @@
 		"registry": "https://registry.npmjs.org/",
 		"access": "public"
 	},
+	"sideEffects": false,
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
-		".": "./src/index.ts",
-		"./transport": "./src/transport/index.ts"
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./transport": {
+			"types": "./dist/transport/index.d.ts",
+			"import": "./dist/transport/index.js"
+		},
+		"./domain": {
+			"types": "./dist/domain/index.d.ts",
+			"import": "./dist/domain/index.js"
+		},
+		"./providers": {
+			"types": "./dist/providers/index.d.ts",
+			"import": "./dist/providers/index.js"
+		},
+		"./capabilities": {
+			"types": "./dist/capability/index.d.ts",
+			"import": "./dist/capability/index.js"
+		},
+		"./hardware": {
+			"types": "./dist/hardware/index.d.ts",
+			"import": "./dist/hardware/index.js"
+		},
+		"./testing": {
+			"types": "./dist/testing/index.d.ts",
+			"import": "./dist/testing/index.js"
+		},
+		"./package.json": "./package.json"
 	},
 	"files": [
-		"src"
+		"dist"
 	],
 	"scripts": {
+		"build": "bun run scripts/build.ts",
+		"prepack": "bun run build",
+		"verify:consumers": "bun run scripts/verify-consumers.ts",
+		"verify:tarball": "bun run scripts/assert-tarball-shape.ts",
 		"test": "bun test",
 		"typecheck": "tsc --noEmit"
 	},