@ceralive/modem-control 1.0.0 → 1.2.0

package/dist/usb-mode/runtime-capability.js

@@ -0,0 +1,157 @@
+export const RUNTIME_COMPOSITION_VENDORS = ['fibocom', 'quectel', 'simcom', 'sierra'];
+/** Commands only: selecting a port, sending, deadlines, and retries belong to the provider. */
+export const RUNTIME_COMPOSITION_QUERY_REGISTRY = Object.freeze({
+    fibocom: Object.freeze({ current: 'AT+GTUSBMODE?', enumerate: 'AT+GTUSBMODE=?' }),
+    quectel: Object.freeze({ current: 'AT+QCFG="usbnet"', enumerate: 'AT+QCFG=?' }),
+    simcom: Object.freeze({ current: 'AT+CUSBPIDSWITCH?', enumerate: 'AT+CUSBPIDSWITCH=?' }),
+    sierra: Object.freeze({ current: 'AT!USBCOMP?', enumerate: 'AT!USBCOMP=?' }),
+});
+function decimalSetCommand(prefix) {
+    return (target) => typeof target === 'number' && Number.isSafeInteger(target) && target >= 0
+        ? `${prefix}${target}`
+        : undefined;
+}
+/** Exact reviewed SET forms. Callers still allowlist only the one enumerated target selected. */
+export const RUNTIME_COMPOSITION_SET_REGISTRY = Object.freeze({
+    fibocom: decimalSetCommand('AT+GTUSBMODE='),
+    quectel: decimalSetCommand('AT+QCFG="usbnet",'),
+    simcom: (target) => typeof target === 'string' && /^[0-9A-Fa-f]{4}$/.test(target)
+        ? `AT+CUSBPIDSWITCH=${target.toUpperCase()},1,1`
+        : undefined,
+    sierra: decimalSetCommand('AT!USBCOMP='),
+});
+const UNKNOWN_VENDOR = Object.freeze({
+    status: 'unknown',
+    current: null,
+    enumerated: [],
+    returnPathProven: false,
+    offerable: [],
+    reason: 'vendor-unsupported',
+});
+const MALFORMED_RESPONSE = Object.freeze({
+    status: 'unknown',
+    current: null,
+    enumerated: [],
+    returnPathProven: false,
+    offerable: [],
+    reason: 'malformed-response',
+});
+function parseDecimalDomain(domain) {
+    const values = [];
+    for (const member of domain.split(',')) {
+        const token = member.trim();
+        const range = /^(\d+)-(\d+)$/.exec(token);
+        if (range !== null) {
+            const start = Number(range[1]);
+            const end = Number(range[2]);
+            if (!Number.isSafeInteger(start) ||
+                !Number.isSafeInteger(end) ||
+                start > end ||
+                end - start > 255)
+                return undefined;
+            for (let value = start; value <= end; value += 1)
+                values.push(value);
+            continue;
+        }
+        if (!/^\d+$/.test(token))
+            return undefined;
+        const value = Number(token);
+        if (!Number.isSafeInteger(value))
+            return undefined;
+        values.push(value);
+    }
+    return values.length > 0 && new Set(values).size === values.length ? values : undefined;
+}
+function parseFibocom(input) {
+    const current = /^\s*\+GTUSBMODE:\s*(\d+)\s*$/m.exec(input.currentResponse);
+    const enumeration = /^\s*\+GTUSBMODE:\s*\(([^)]+)\)\s*$/m.exec(input.enumerationResponse);
+    if (current === null || enumeration === null)
+        return undefined;
+    const enumerated = parseDecimalDomain(enumeration[1] ?? '');
+    return enumerated === undefined ? undefined : { current: Number(current[1]), enumerated };
+}
+function parseQuectel(input) {
+    const current = /^\s*\+QCFG:\s*"usbnet"\s*,\s*(\d+)\s*$/m.exec(input.currentResponse);
+    const enumeration = /^\s*\+QCFG:\s*"usbnet"\s*,\s*\(([^)]+)\)\s*$/m.exec(input.enumerationResponse);
+    if (current === null || enumeration === null)
+        return undefined;
+    const enumerated = parseDecimalDomain(enumeration[1] ?? '');
+    return enumerated === undefined ? undefined : { current: Number(current[1]), enumerated };
+}
+function parseSimcom(input) {
+    const current = /^\s*\+CUSBPIDSWITCH:\s*([0-9A-Fa-f]{4})\s*$/m.exec(input.currentResponse);
+    const enumeration = /\+CUSBPIDSWITCH:\s*\(([^)]+)\)\s*,\s*\(0-1\)\s*,\s*\(0-1\)/m.exec(input.enumerationResponse);
+    if (current === null || enumeration === null)
+        return undefined;
+    const tokens = (enumeration[1] ?? '').split(',').map((token) => token.trim().toUpperCase());
+    if (tokens.length === 0 || tokens.some((token) => !/^[0-9A-F]{4}$/.test(token)))
+        return undefined;
+    if (new Set(tokens).size !== tokens.length)
+        return undefined;
+    return { current: (current[1] ?? '').toUpperCase(), enumerated: tokens };
+}
+function parseSierra(input) {
+    const current = /^\s*!USBCOMP:\s*(\d+)(?:\s*,.*)?$/m.exec(input.currentResponse);
+    if (current === null)
+        return undefined;
+    const enumerated = Array.from(input.enumerationResponse.matchAll(/^\s*(\d+)\s*:\s*.+$/gm), (match) => Number(match[1]));
+    if (enumerated.length === 0 || new Set(enumerated).size !== enumerated.length)
+        return undefined;
+    return { current: Number(current[1]), enumerated };
+}
+const PARSERS = {
+    fibocom: parseFibocom,
+    quectel: parseQuectel,
+    simcom: parseSimcom,
+    sierra: parseSierra,
+};
+export function isRuntimeCompositionVendor(vendor) {
+    return Object.hasOwn(RUNTIME_COMPOSITION_QUERY_REGISTRY, vendor);
+}
+export function buildRuntimeCompositionSetCommand(vendor, target) {
+    const normalized = vendor.trim().toLowerCase();
+    return isRuntimeCompositionVendor(normalized)
+        ? RUNTIME_COMPOSITION_SET_REGISTRY[normalized](target)
+        : undefined;
+}
+/** Parse only the vendor READ response used by the weaker post-switch proof tier. */
+export function readRuntimeCompositionCurrent(vendor, response) {
+    const normalized = vendor.trim().toLowerCase();
+    if (!isRuntimeCompositionVendor(normalized))
+        return undefined;
+    switch (normalized) {
+        case 'fibocom': {
+            const match = /^\s*\+GTUSBMODE:\s*(\d+)\s*$/m.exec(response);
+            return match === null ? undefined : Number(match[1]);
+        }
+        case 'quectel': {
+            const match = /^\s*\+QCFG:\s*"usbnet"\s*,\s*(\d+)\s*$/m.exec(response);
+            return match === null ? undefined : Number(match[1]);
+        }
+        case 'simcom': {
+            const match = /^\s*\+CUSBPIDSWITCH:\s*([0-9A-Fa-f]{4})\s*$/m.exec(response);
+            return match === null ? undefined : (match[1] ?? '').toUpperCase();
+        }
+        case 'sierra': {
+            const match = /^\s*!USBCOMP:\s*(\d+)(?:\s*,.*)?$/m.exec(response);
+            return match === null ? undefined : Number(match[1]);
+        }
+    }
+}
+/** Derive controls exclusively from the device's current and enumerated response text. */
+export function resolveRuntimeCompositionCapability(input) {
+    const vendor = input.vendor.trim().toLowerCase();
+    if (!isRuntimeCompositionVendor(vendor))
+        return UNKNOWN_VENDOR;
+    const parsed = PARSERS[vendor](input);
+    if (parsed === undefined)
+        return MALFORMED_RESPONSE;
+    const returnPathProven = parsed.enumerated.includes(parsed.current);
+    return {
+        status: 'available',
+        current: parsed.current,
+        enumerated: parsed.enumerated,
+        returnPathProven,
+        offerable: returnPathProven ? parsed.enumerated : [],
+    };
+}

package/dist/usb-mode/usb-devices-parse.d.ts

@@ -0,0 +1,36 @@
+/** One interface line of a `usb-devices` record. */
+export interface ParsedUsbInterface {
+    readonly interfaceClass: number;
+    readonly interfaceSubClass: number;
+    readonly interfaceProtocol: number;
+    /** The bound kernel driver, omitted when `usb-devices` reports `(none)`. */
+    readonly driver?: string;
+}
+/** One device block of a `usb-devices` capture. */
+export interface ParsedUsbDevice {
+    /** Lowercase hex `xxxx:xxxx`, exactly the catalog's `vidPid` discriminator shape. */
+    readonly vidPid: string;
+    /** The `D:` line's `Cls=` byte — the device-descriptor `bDeviceClass`. */
+    readonly bDeviceClass: number;
+    readonly manufacturer?: string;
+    readonly product?: string;
+    readonly interfaces: readonly ParsedUsbInterface[];
+}
+/**
+ * Parse `usb-devices` output into one record per device. Pure and total: malformed
+ * lines are skipped rather than guessed at, and a block with no `P:` line yields no
+ * record (it has no identity, so inventing one would be a lie).
+ */
+export declare function parseUsbDevices(text: string): ParsedUsbDevice[];
+/**
+ * Find the single device matching `vidPid` in a parsed capture. Returns `undefined`
+ * when there is NO match, and — deliberately — also when there is more than one: a
+ * duplicate VID:PID (this bench has two identical Huawei HiLink units) makes the
+ * selection ambiguous, and an ambiguous selection must refuse rather than pick the
+ * first. The caller turns that into a typed refusal.
+ */
+export declare function selectUniqueDevice(devices: readonly ParsedUsbDevice[], vidPid: string): {
+    readonly device: ParsedUsbDevice;
+} | {
+    readonly ambiguousMatches: number;
+};

package/dist/usb-mode/usb-devices-parse.js

@@ -0,0 +1,157 @@
+// Parsing `usb-devices` text — the ONLY per-interface descriptor source inside a
+// certification bundle.
+//
+// A base certification bundle (`certify <slot>` with no `--transition`) carries no
+// structured descriptors at all: it holds `lsusb -v` and `usb-devices` as raw text plus
+// the slot's udev property map. Authoring a classifier fixture or a catalog entry from
+// such a bundle therefore requires reading the descriptors back out of that text, and
+// `usb-devices` is the right half to read — it is line-oriented, one fixed-width record
+// per device, and it names each interface's BOUND KERNEL DRIVER, which `lsusb -v` does
+// not. The driver is not optional detail here: `classifyDevice` decides `mm-managed` vs
+// `router-mode` partly on `qmi_wwan` / `cdc_ether` / `option` bindings.
+//
+// The parser is pure and total: unparseable lines are SKIPPED, never guessed at, and a
+// device that yields no interfaces still yields a record (callers decide whether an
+// interface-less device is usable — this file never makes that judgement).
+//
+// Record shape (`usb-devices`, one blank-line-separated block per device):
+//   T:  Bus=04 Lev=03 Prnt=03 Port=03 Cnt=01 Dev#=  7 Spd=480 MxCh= 0
+//   D:  Ver= 2.00 Cls=00(>ifc ) Sub=00 Prot=00 MxPS=64 #Cfgs=  1
+//   P:  Vendor=2c7c ProdID=0801 Rev=05.04
+//   S:  Manufacturer=Quectel
+//   S:  Product=RM530N-GL
+//   I:  If#= 4 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=ff Prot=ff Driver=qmi_wwan
+/** Read `Key=value` from a `usb-devices` line; `undefined` when the key is absent. */
+function field(line, key) {
+    // Values are whitespace-delimited and may be preceded by padding spaces (`Dev#=  7`).
+    // `Cls=ff(vend.)` carries a trailing gloss, stripped by the hex/number parsers below.
+    const match = new RegExp(`${key}=\\s*(\\S+)`).exec(line);
+    return match?.[1];
+}
+/** Parse a hex byte field, tolerating `usb-devices`' `ff(vend.)` gloss suffix. */
+function hexByte(line, key) {
+    const raw = field(line, key);
+    if (raw === undefined) {
+        return undefined;
+    }
+    const digits = /^[0-9a-fA-F]{1,2}/.exec(raw)?.[0];
+    if (digits === undefined) {
+        return undefined;
+    }
+    const value = Number.parseInt(digits, 16);
+    return Number.isNaN(value) ? undefined : value;
+}
+/** Parse an `S:  Manufacturer=…` style line into its `[key, value]` pair. */
+function stringField(line) {
+    const eq = line.indexOf('=');
+    if (eq < 0) {
+        return undefined;
+    }
+    const key = line.slice(3, eq).trim();
+    const value = line.slice(eq + 1).trim();
+    return key === '' || value === '' ? undefined : [key, value];
+}
+function emptyAccumulator() {
+    return { interfaces: [] };
+}
+function finish(acc, out) {
+    // A record with no `P:` line is not a device — never synthesise an identity for it.
+    if (acc.vidPid === undefined) {
+        return;
+    }
+    out.push({
+        vidPid: acc.vidPid,
+        bDeviceClass: acc.bDeviceClass ?? 0,
+        interfaces: acc.interfaces,
+        ...(acc.manufacturer !== undefined ? { manufacturer: acc.manufacturer } : {}),
+        ...(acc.product !== undefined ? { product: acc.product } : {}),
+    });
+}
+function applyProductLine(line, acc) {
+    const vendor = field(line, 'Vendor');
+    const product = field(line, 'ProdID');
+    if (vendor !== undefined && product !== undefined) {
+        acc.vidPid = `${vendor.toLowerCase()}:${product.toLowerCase()}`;
+    }
+}
+function applyStringLine(line, acc) {
+    const pair = stringField(line);
+    if (pair === undefined) {
+        return;
+    }
+    const [key, value] = pair;
+    if (key === 'Manufacturer') {
+        acc.manufacturer = value;
+    }
+    else if (key === 'Product') {
+        acc.product = value;
+    }
+}
+function applyInterfaceLine(line, acc) {
+    const interfaceClass = hexByte(line, 'Cls');
+    const interfaceSubClass = hexByte(line, 'Sub');
+    const interfaceProtocol = hexByte(line, 'Prot');
+    if (interfaceClass === undefined ||
+        interfaceSubClass === undefined ||
+        interfaceProtocol === undefined) {
+        return;
+    }
+    const driver = field(line, 'Driver');
+    acc.interfaces.push({
+        interfaceClass,
+        interfaceSubClass,
+        interfaceProtocol,
+        ...(driver !== undefined && driver !== '(none)' ? { driver } : {}),
+    });
+}
+/**
+ * Parse `usb-devices` output into one record per device. Pure and total: malformed
+ * lines are skipped rather than guessed at, and a block with no `P:` line yields no
+ * record (it has no identity, so inventing one would be a lie).
+ */
+export function parseUsbDevices(text) {
+    const out = [];
+    let acc = emptyAccumulator();
+    for (const line of text.split('\n')) {
+        // A `T:` line opens a new device record; `usb-devices` also blank-line-separates
+        // them, but the topology line is the reliable delimiter (blank lines are optional
+        // in some kernels' output).
+        if (line.startsWith('T:')) {
+            finish(acc, out);
+            acc = emptyAccumulator();
+            continue;
+        }
+        if (line.startsWith('D:')) {
+            const deviceClass = hexByte(line, 'Cls');
+            if (deviceClass !== undefined) {
+                acc.bDeviceClass = deviceClass;
+            }
+        }
+        else if (line.startsWith('P:')) {
+            applyProductLine(line, acc);
+        }
+        else if (line.startsWith('S:')) {
+            applyStringLine(line, acc);
+        }
+        else if (line.startsWith('I:')) {
+            applyInterfaceLine(line, acc);
+        }
+    }
+    finish(acc, out);
+    return out;
+}
+/**
+ * Find the single device matching `vidPid` in a parsed capture. Returns `undefined`
+ * when there is NO match, and — deliberately — also when there is more than one: a
+ * duplicate VID:PID (this bench has two identical Huawei HiLink units) makes the
+ * selection ambiguous, and an ambiguous selection must refuse rather than pick the
+ * first. The caller turns that into a typed refusal.
+ */
+export function selectUniqueDevice(devices, vidPid) {
+    const matches = devices.filter((d) => d.vidPid === vidPid);
+    const only = matches[0];
+    if (matches.length === 1 && only !== undefined) {
+        return { device: only };
+    }
+    return { ambiguousMatches: matches.length };
+}

package/dist/ussd/calls.d.ts

@@ -0,0 +1,32 @@
+import type { DbusTransport } from '../transport/index.js';
+import type { UssdRepliedState } from './session.js';
+/** `MMModem3gppUssdSessionState`. */
+export declare const USSD_STATE_UNKNOWN = 0;
+export declare const USSD_STATE_IDLE = 1;
+export declare const USSD_STATE_ACTIVE = 2;
+export declare const USSD_STATE_USER_RESPONSE = 3;
+/**
+ * Decode MM's post-call session state. `UNKNOWN` folds onto `released` with the
+ * rest: an unreadable state must close the session rather than leave the operator
+ * looking at a dialogue nothing can advance.
+ */
+export declare function decodeRepliedState(state: number): UssdRepliedState;
+export interface UssdCallTarget {
+    readonly transport: DbusTransport;
+    readonly destination: string;
+    readonly modem: string;
+    readonly timeoutMs: number;
+}
+export declare function callInitiate(target: UssdCallTarget, ussdCommand: string): Promise<string>;
+export declare function callRespond(target: UssdCallTarget, ussdResponse: string): Promise<string>;
+export declare function callCancel(target: UssdCallTarget): Promise<void>;
+/**
+ * Read the post-call session state.
+ *
+ * A targeted `Properties.Get` rather than a `GetManagedObjects` sweep: this runs
+ * after every network round-trip, and the whole-tree read is the most expensive
+ * call in the package. `unknown` on anything unreadable — the caller treats that
+ * as "the network released the session", which is the conservative direction (it
+ * closes a session rather than leaving one the operator cannot see).
+ */
+export declare function readUssdState(target: UssdCallTarget): Promise<number>;

package/dist/ussd/calls.js

@@ -0,0 +1,96 @@
+// The four D-Bus calls the USSD adapter makes, and nothing else.
+//
+// Split from the adapter so the session machinery above can be read without the
+// marshalling below, and so a call's shape (interface, member, signature) is
+// stated once in one place.
+//
+// CARRIER TEXT DISCIPLINE: `Initiate` and `Respond` both take and return operator
+// text, and neither the command nor the reply may ever reach a log line. Nothing
+// in this file logs, and every error raised here is re-thrown untouched so the
+// classifier — not a string built around the payload — decides what the caller is
+// told.
+import { MODEM3GPP_USSD_IFACE, PROPERTIES_IFACE } from '../backend/constants.js';
+/** `MMModem3gppUssdSessionState`. */
+export const USSD_STATE_UNKNOWN = 0;
+export const USSD_STATE_IDLE = 1;
+export const USSD_STATE_ACTIVE = 2;
+export const USSD_STATE_USER_RESPONSE = 3;
+/**
+ * Decode MM's post-call session state. `UNKNOWN` folds onto `released` with the
+ * rest: an unreadable state must close the session rather than leave the operator
+ * looking at a dialogue nothing can advance.
+ */
+export function decodeRepliedState(state) {
+    if (state === USSD_STATE_USER_RESPONSE) {
+        return 'awaiting-reply';
+    }
+    return state === USSD_STATE_ACTIVE ? 'active' : 'released';
+}
+function firstString(body) {
+    const value = body[0];
+    return typeof value === 'string' ? value : '';
+}
+export async function callInitiate(target, ussdCommand) {
+    const reply = await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Initiate',
+        signature: 's',
+        args: [ussdCommand],
+        timeoutMs: target.timeoutMs,
+    });
+    return firstString(reply.body);
+}
+export async function callRespond(target, ussdResponse) {
+    const reply = await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Respond',
+        signature: 's',
+        args: [ussdResponse],
+        timeoutMs: target.timeoutMs,
+    });
+    return firstString(reply.body);
+}
+export async function callCancel(target) {
+    await target.transport.callMethod({
+        destination: target.destination,
+        path: target.modem,
+        interface: MODEM3GPP_USSD_IFACE,
+        member: 'Cancel',
+        timeoutMs: target.timeoutMs,
+    });
+}
+/**
+ * Read the post-call session state.
+ *
+ * A targeted `Properties.Get` rather than a `GetManagedObjects` sweep: this runs
+ * after every network round-trip, and the whole-tree read is the most expensive
+ * call in the package. `unknown` on anything unreadable — the caller treats that
+ * as "the network released the session", which is the conservative direction (it
+ * closes a session rather than leaving one the operator cannot see).
+ */
+export async function readUssdState(target) {
+    try {
+        const reply = await target.transport.callMethod({
+            destination: target.destination,
+            path: target.modem,
+            interface: PROPERTIES_IFACE,
+            member: 'Get',
+            signature: 'ss',
+            args: [MODEM3GPP_USSD_IFACE, 'State'],
+            timeoutMs: target.timeoutMs,
+        });
+        const wrapped = reply.body[0];
+        if (typeof wrapped === 'number') {
+            return wrapped;
+        }
+        const inner = wrapped?.value;
+        return typeof inner === 'number' ? inner : USSD_STATE_UNKNOWN;
+    }
+    catch {
+        return USSD_STATE_UNKNOWN;
+    }
+}

package/dist/ussd/index.d.ts

@@ -0,0 +1,5 @@
+export { callCancel, callInitiate, callRespond, decodeRepliedState, readUssdState, USSD_STATE_ACTIVE, USSD_STATE_IDLE, USSD_STATE_UNKNOWN, USSD_STATE_USER_RESPONSE, type UssdCallTarget, } from './calls.js';
+export { MmUssd, type MmUssdDeps, type UssdScheduler, type UssdTimerHandle, type UssdVerbResult, } from './mm-ussd.js';
+export { classifyUssdFailure, isPacketSwitchedOnly, USSD_REFUSAL_REASONS, type UssdRefusalReason, type UssdRegistrationFacts, } from './refusal.js';
+export { decodeAccessTechnologies, readUssdRegistrationFacts, registrationFactsFromTree, UNKNOWN_REGISTRATION, } from './registration.js';
+export { IDLE_SESSION, isUssdSessionOpen, reduceUssdSession, USSD_SESSION_OUTCOMES, USSD_SESSION_STATES, type UssdRepliedState, type UssdSessionEvent, type UssdSessionOutcome, type UssdSessionSnapshot, type UssdSessionState, type UssdTransition, } from './session.js';

package/dist/ussd/index.js

@@ -0,0 +1,12 @@
+// The gated USSD capability module — session state machine, refusal taxonomy, and
+// the ModemManager `Modem3gpp.Ussd` adapter.
+//
+// GATED: nothing here runs unless the operator has enabled the `ussd` capability
+// module and the modem positively advertises the interface (`../capability`).
+// LEASE-ONLY: a USSD session cannot re-register the radio, so it takes the
+// per-modem mutation lease and is NOT journaled.
+export { callCancel, callInitiate, callRespond, decodeRepliedState, readUssdState, USSD_STATE_ACTIVE, USSD_STATE_IDLE, USSD_STATE_UNKNOWN, USSD_STATE_USER_RESPONSE, } from './calls.js';
+export { MmUssd, } from './mm-ussd.js';
+export { classifyUssdFailure, isPacketSwitchedOnly, USSD_REFUSAL_REASONS, } from './refusal.js';
+export { decodeAccessTechnologies, readUssdRegistrationFacts, registrationFactsFromTree, UNKNOWN_REGISTRATION, } from './registration.js';
+export { IDLE_SESSION, isUssdSessionOpen, reduceUssdSession, USSD_SESSION_OUTCOMES, USSD_SESSION_STATES, } from './session.js';

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

@@ -0,0 +1,37 @@
+import type { ModemActor } from '../backend/modem-actor.js';
+import type { ModemRef } from '../ports/index.js';
+import type { DbusTransport } from '../transport/index.js';
+import { type UssdRefusalReason } from './refusal.js';
+import { type UssdSessionSnapshot } from './session.js';
+export interface UssdTimerHandle {
+    cancel(): void;
+}
+export type UssdScheduler = (delayMs: number, run: () => void) => UssdTimerHandle;
+export interface UssdVerbResult {
+    readonly ok: boolean;
+    readonly snapshot: UssdSessionSnapshot;
+    /** Carrier text. Redacted by key everywhere it is serialized. */
+    readonly ussdReply?: string;
+    readonly refusal?: UssdRefusalReason;
+}
+export interface MmUssdDeps {
+    readonly transport: DbusTransport;
+    readonly actor: ModemActor;
+    readonly destination?: string;
+    readonly resolveStableKey: (modem: ModemRef) => string;
+    readonly callTimeoutMs?: number;
+    readonly sessionIdleTimeoutMs?: number;
+    readonly scheduler?: UssdScheduler;
+    /** Notified on every stored-state change, so a UI can follow a session. */
+    readonly onSessionChange?: (stableKey: string, snapshot: UssdSessionSnapshot) => void;
+}
+export declare class MmUssd {
+    #private;
+    constructor(deps: MmUssdDeps);
+    snapshot(modem: ModemRef): UssdSessionSnapshot;
+    initiate(modem: ModemRef, ussdCommand: string): Promise<UssdVerbResult>;
+    respond(modem: ModemRef, ussdResponse: string): Promise<UssdVerbResult>;
+    cancel(modem: ModemRef): Promise<UssdVerbResult>;
+    /** Drop every timer. A live session on the modem is NOT cancelled by this. */
+    stop(): void;
+}