@ceralive/modem-control 0.2.0 → 1.1.0

package/dist/fcc/policy-store.js

@@ -0,0 +1,146 @@
+// Durable persistence for the operator's FCC-auto-unlock POLICY.
+//
+// WHY THE FILE IS THE RECORD AND THE SYMLINK IS NOT. ModemManager's opt-in
+// mechanism is a symlink in `/etc/ModemManager/fcc-unlock.d/<vid>:<pid>`. `/etc` is
+// on the rootfs, and the rootfs is exactly what a RAUC A/B slot swap REPLACES
+// (`image-building-pipeline/docs/partition-contract.md`), so that symlink survives a
+// reboot and does NOT survive an OTA. `/data` is the only update-surviving store, so
+// the durable record lives there and the symlink is a derived artifact re-created
+// from it on every boot by `ceralive-fcc-reconcile`.
+//
+// The two hard guarantees are the SAME ones `backend/usage/policy-store.ts` makes,
+// and deliberately implemented the same way so the pair can be read side by side:
+//   - MODE 0600 via temp → chmod → atomic rename, regardless of umask.
+//   - FAIL-SAFE ON CORRUPTION: an unparseable/incompatible file logs METADATA ONLY
+//     (byte length + a classification reason, never the content) and is treated as
+//     EMPTY. Note the divergence from the usage store, and it is load-bearing: the
+//     usage store REWRITES a fresh file, while this one leaves the damaged bytes on
+//     disk for an operator to look at and simply refuses to act on them. Enabling a
+//     regulatory-unlock procedure is not something to infer from a file we could not
+//     read, and silently replacing the evidence would make the next person's
+//     diagnosis impossible.
+//
+// A policy row carries ONLY a `<vid>:<pid>` MODEL identifier and a boolean. There is
+// no per-unit identity here by construction — no serial, no ICCID, no ID_PATH —
+// because ModemManager's mechanism is model-wide and a per-unit key would be a
+// promise the dispatcher cannot keep.
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { isFccUnlockKey } from './coverage.js';
+/** The current on-disk schema version. Bump when the persisted shape changes. */
+export const FCC_UNLOCK_SCHEMA_VERSION = 1;
+/** The pinned location of the policy of record. `/data` survives a slot swap. */
+export const FCC_UNLOCK_POLICY_PATH = '/data/ceralive/fcc-unlock-policy.json';
+function defaultLogger(event) {
+    console.warn(`[fcc-unlock-policy] ${event.kind}: bytes=${event.bytes} reason=${event.reason}`);
+}
+function emptyState(nowMs) {
+    return { schemaVersion: FCC_UNLOCK_SCHEMA_VERSION, savedAtMs: nowMs, unlock: {} };
+}
+/** A schema violation naming only the offending FIELD (never file content). */
+class FccPolicySchemaError extends Error {
+    constructor(field) {
+        super(`schema-mismatch: ${field}`);
+    }
+}
+/**
+ * Parse + validate the document. Throws `FccPolicySchemaError` (metadata-only).
+ *
+ * WHOLE-DOCUMENT rejection, never per-key skipping: a half-applied policy is a
+ * policy nobody wrote, and the shell reconciler makes the same all-or-nothing
+ * judgement, so the two halves agree on what a damaged file means.
+ */
+function validate(raw) {
+    if (typeof raw !== 'object' || raw === null) {
+        throw new FccPolicySchemaError('document');
+    }
+    const doc = raw;
+    if (doc.schemaVersion !== FCC_UNLOCK_SCHEMA_VERSION) {
+        throw new FccPolicySchemaError('schemaVersion');
+    }
+    if (typeof doc.savedAtMs !== 'number' || !Number.isFinite(doc.savedAtMs)) {
+        throw new FccPolicySchemaError('savedAtMs');
+    }
+    if (typeof doc.unlock !== 'object' || doc.unlock === null || Array.isArray(doc.unlock)) {
+        throw new FccPolicySchemaError('unlock');
+    }
+    const unlock = {};
+    for (const [key, value] of Object.entries(doc.unlock)) {
+        if (!isFccUnlockKey(key)) {
+            throw new FccPolicySchemaError('unlock.key');
+        }
+        if (typeof value !== 'boolean') {
+            throw new FccPolicySchemaError('unlock.value');
+        }
+        unlock[key] = value;
+    }
+    return {
+        schemaVersion: FCC_UNLOCK_SCHEMA_VERSION,
+        savedAtMs: doc.savedAtMs,
+        unlock,
+    };
+}
+/** Classify a load failure into a metadata-only reason string (no raw content). */
+function classifyFailure(error) {
+    if (error instanceof FccPolicySchemaError) {
+        return error.message;
+    }
+    if (error instanceof SyntaxError) {
+        const offset = /position (\d+)/.exec(error.message)?.[1];
+        return offset !== undefined ? `invalid-json at offset ${offset}` : 'invalid-json';
+    }
+    return 'unreadable';
+}
+/** The `<vid>:<pid>` models the policy positively enables. Sorted, for stability. */
+export function enabledFccUnlockKeys(state) {
+    return Object.entries(state.unlock)
+        .filter(([, enabled]) => enabled)
+        .map(([key]) => key)
+        .sort();
+}
+/** One model's answer. An unmentioned model is NOT enabled — absence is not consent. */
+export function isFccUnlockEnabled(state, key) {
+    return state.unlock[key] === true;
+}
+export function createFccUnlockPolicyFileStore(options = {}) {
+    const logger = options.logger ?? defaultLogger;
+    const path = options.path ?? FCC_UNLOCK_POLICY_PATH;
+    async function writeAtomic(state) {
+        await mkdir(dirname(path), { recursive: true });
+        const tmp = `${path}.tmp`;
+        // The trailing newline is for the shell reconciler's benefit, not decoration:
+        // it reads the file with `tr -d`, and a newline-terminated document is what a
+        // human `cat`ing it on a board expects to see.
+        await writeFile(tmp, `${JSON.stringify(state)}\n`);
+        // chmod AFTER the write (not an open flag) so mode is 0600 regardless of umask.
+        await chmod(tmp, 0o600);
+        await rename(tmp, path);
+    }
+    return {
+        async load(nowMs) {
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch {
+                // Absent (or unreadable) → EMPTY, which activates nothing. This is the
+                // state on every device that never opted in, and it is the safe default.
+                return emptyState(nowMs);
+            }
+            try {
+                return validate(JSON.parse(text));
+            }
+            catch (error) {
+                logger({
+                    kind: 'corrupt-policy',
+                    bytes: Buffer.byteLength(text, 'utf8'),
+                    reason: classifyFailure(error),
+                });
+                // Deliberately NOT rewritten — see the header. Refuse to act, keep the
+                // evidence, and let the next write replace it wholesale.
+                return emptyState(nowMs);
+            }
+        },
+        save: writeAtomic,
+    };
+}

package/dist/fcc/policy-write.d.ts

@@ -0,0 +1,32 @@
+import type { FccUnlockPolicyStore, PersistedFccUnlockPolicy } from './policy-store.js';
+export interface SetFccUnlockPolicyDeps {
+    readonly store: FccUnlockPolicyStore;
+    /** Injectable clock (defaults to `Date.now`). */
+    readonly now?: () => number;
+}
+export interface SetFccUnlockPolicyRequest {
+    readonly vid: string;
+    readonly pid: string;
+    readonly enabled: boolean;
+}
+export type SetFccUnlockPolicyRejection = 'invalid-vid-pid' | 'not-covered';
+export type SetFccUnlockPolicyResult = {
+    readonly status: 'applied';
+    /** The dispatcher key this write is about, normalized. */
+    readonly key: string;
+    readonly enabled: boolean;
+    /** The whole document now on disk, so a caller need not re-read it. */
+    readonly policy: PersistedFccUnlockPolicy;
+    /**
+     * True when the persisted value CHANGED. A caller uses this to decide
+     * whether the modem needs a re-probe: ModemManager runs the dispatcher
+     * during initialization only, so a genuine change needs
+     * `mmcli -m <id> --disable && --enable` (or a replug) to take effect on an
+     * already-enumerated modem — and an unchanged write must not cost one.
+     */
+    readonly changed: boolean;
+} | {
+    readonly status: 'rejected';
+    readonly reason: SetFccUnlockPolicyRejection;
+};
+export declare function setFccUnlockPolicy(request: SetFccUnlockPolicyRequest, deps: SetFccUnlockPolicyDeps): Promise<SetFccUnlockPolicyResult>;

package/dist/fcc/policy-write.js

@@ -0,0 +1,37 @@
+// `setFccUnlockPolicy` — the WRITE half of the FCC auto-unlock surface.
+//
+// TYPED RESULTS, NEVER A THROW ON BAD INPUT. Following the `PowerHook` and
+// `setUsagePolicy` precedents, a malformed key or an uncovered model is a `rejected`
+// result carrying a named reason rather than an exception — this is called from an
+// RPC boundary, where a throw becomes an opaque 500.
+//
+// THE COVERAGE CHECK IS PART OF THE WRITE, not a UI nicety. Persisting `true` for a
+// model ModemManager ships no procedure for would leave the operator staring at an
+// enabled toggle that provably cannot do anything: the reconciler would find no
+// `<vid>:<pid>` in the available tier and skip it forever, silently. Refusing at the
+// write is the only place that fact can be reported to the person who asked for it.
+//
+// Disabling is deliberately NOT coverage-checked. A `false` must always be
+// persistable — including for a model whose coverage answer has since changed, or
+// which a previous release wrote — because a fail-closed opt-OUT is not a thing.
+import { normalizeVidPid, resolveFccUnlockCoverage } from './coverage.js';
+export async function setFccUnlockPolicy(request, deps) {
+    const key = normalizeVidPid(request.vid, request.pid);
+    if (key === undefined) {
+        return { status: 'rejected', reason: 'invalid-vid-pid' };
+    }
+    if (request.enabled && resolveFccUnlockCoverage(request.vid, request.pid) !== 'present') {
+        return { status: 'rejected', reason: 'not-covered' };
+    }
+    const now = deps.now ?? Date.now;
+    const nowMs = now();
+    const current = await deps.store.load(nowMs);
+    const changed = (current.unlock[key] === true) !== request.enabled;
+    const next = {
+        schemaVersion: current.schemaVersion,
+        savedAtMs: nowMs,
+        unlock: { ...current.unlock, [key]: request.enabled },
+    };
+    await deps.store.save(next);
+    return { status: 'applied', key, enabled: request.enabled, policy: next, changed };
+}

package/dist/hardware/hilink-protocol.d.ts

@@ -0,0 +1,39 @@
+export declare function parseHilinkXmlValue(body: string, tag: string): string | undefined;
+export type HilinkSessionDocument = {
+    readonly cookie: string;
+    readonly token: string;
+};
+export declare function parseHilinkSession(body: string): HilinkSessionDocument | undefined;
+export type HilinkUserState = {
+    readonly state: string;
+    readonly passwordType: 3 | 4;
+};
+export declare function parseHilinkUserState(body: string): HilinkUserState | undefined;
+export type HilinkProtocolUnknownReason = 'unsupported' | 'not-reported' | 'malformed' | 'auth-expired' | 'unreachable';
+export type HilinkDataCapability = {
+    readonly state: 'reported';
+    readonly enabled: boolean;
+} | {
+    readonly state: 'unavailable';
+    readonly reason: HilinkProtocolUnknownReason | 'refused';
+    readonly code?: string;
+};
+export declare function parseHilinkDataCapability(body: string): HilinkDataCapability;
+export type HilinkNetModeCapability = {
+    readonly state: 'reported';
+    readonly modes: readonly {
+        readonly id: string;
+        readonly name?: string;
+    }[];
+    readonly current?: string;
+} | {
+    readonly state: 'unavailable';
+    readonly reason: HilinkProtocolUnknownReason | 'refused';
+    readonly code?: string;
+};
+export declare function parseHilinkCapabilities(input: {
+    readonly netModeList: string;
+    readonly netMode?: string;
+}): {
+    readonly net_mode: HilinkNetModeCapability;
+};

package/dist/hardware/hilink-protocol.js

@@ -0,0 +1,58 @@
+export function parseHilinkXmlValue(body, tag) {
+    const match = body.match(new RegExp(`<${tag}>([^<]*)</${tag}>`, 'i'));
+    return match?.[1]?.trim();
+}
+export function parseHilinkSession(body) {
+    const cookie = parseHilinkXmlValue(body, 'SesInfo');
+    const token = parseHilinkXmlValue(body, 'TokInfo');
+    return cookie === undefined || cookie === '' || token === undefined || token === ''
+        ? undefined
+        : { cookie, token };
+}
+export function parseHilinkUserState(body) {
+    const state = parseHilinkXmlValue(body, 'State');
+    const rawPasswordType = parseHilinkXmlValue(body, 'password_type');
+    if (state === undefined || (rawPasswordType !== '3' && rawPasswordType !== '4'))
+        return undefined;
+    return { state, passwordType: rawPasswordType === '3' ? 3 : 4 };
+}
+export function parseHilinkDataCapability(body) {
+    const code = parseHilinkXmlValue(body, 'code');
+    if (code === '125002')
+        return { state: 'unavailable', reason: 'auth-expired' };
+    if (code !== undefined)
+        return { state: 'unavailable', reason: 'refused', code };
+    const value = parseHilinkXmlValue(body, 'dataswitch');
+    if (value === undefined)
+        return { state: 'unavailable', reason: body === '' ? 'unreachable' : 'malformed' };
+    if (value !== '0' && value !== '1')
+        return { state: 'unavailable', reason: 'malformed' };
+    return { state: 'reported', enabled: value === '1' };
+}
+export function parseHilinkCapabilities(input) {
+    const code = parseHilinkXmlValue(input.netModeList, 'code');
+    if (code === '125002')
+        return { net_mode: { state: 'unavailable', reason: 'auth-expired' } };
+    if (code !== undefined)
+        return { net_mode: { state: 'unavailable', reason: 'refused', code } };
+    if (input.netModeList.trim() === '')
+        return { net_mode: { state: 'unavailable', reason: 'unreachable' } };
+    // `malformed` is a statement about the BODY — something that is not this API
+    // answered. A `<response>` carrying no mode list IS this API, saying nothing,
+    // which is `not-reported` below.
+    if (!/<response>/i.test(input.netModeList))
+        return { net_mode: { state: 'unavailable', reason: 'malformed' } };
+    const modes = [...input.netModeList.matchAll(/<NetworkMode>([\s\S]*?)<\/NetworkMode>/gi)].flatMap((match) => {
+        const id = parseHilinkXmlValue(match[1] ?? '', 'Index');
+        if (id === undefined || id === '')
+            return [];
+        const name = parseHilinkXmlValue(match[1] ?? '', 'Name');
+        return name === undefined || name === '' ? [{ id }] : [{ id, name }];
+    });
+    if (modes.length === 0)
+        return { net_mode: { state: 'unavailable', reason: 'not-reported' } };
+    const current = parseHilinkXmlValue(input.netMode ?? '', 'NetworkMode');
+    return current === undefined || current === ''
+        ? { net_mode: { state: 'reported', modes } }
+        : { net_mode: { state: 'reported', modes, current } };
+}

package/dist/hardware/index.d.ts

@@ -0,0 +1,3 @@
+export * from '../band/index.js';
+export * from '../usb-mode/index.js';
+export * from './router-parsers.js';

package/dist/hardware/index.js

@@ -0,0 +1,15 @@
+// `@ceralive/modem-control/hardware` — the per-SKU hardware model.
+//
+// This subpath is the narrow entry for everything keyed on the PHYSICAL unit rather
+// than on a live D-Bus object: which USB composition a SKU may be switched into and
+// which transitions were certified for it (`../usb-mode`), and the MMModemBand
+// vocabulary plus the per-SKU band-lock certification catalog (`../band`).
+//
+// Both halves are evidence-gated catalogs plus their pure lookups — no transport, no
+// mutation verb. The D-Bus verbs that ACT on these facts stay where they live
+// (`../backend/mm-mutations.ts`, declared on `ModemManagerPort`); a consumer that only
+// needs to know what a SKU is capable of should not have to import a bus client to
+// find out. That asymmetry is the reason this entry exists.
+export * from '../band/index.js';
+export * from '../usb-mode/index.js';
+export * from './router-parsers.js';

package/dist/hardware/router-parsers.d.ts

@@ -0,0 +1,89 @@
+export * from './hilink-protocol.js';
+export type SimPresence = 'present' | 'absent' | 'unknown';
+export type SimPresenceFacts = {
+    readonly sim?: string;
+    readonly simSlots?: readonly string[];
+    readonly failedReason?: string;
+};
+/** The mmcli spelling of `MM_MODEM_STATE_FAILED_REASON_SIM_MISSING` — the ONLY proof of absence. */
+export declare const SIM_MISSING_FAILED_REASON = "sim-missing";
+/** The fields a presence decision may be drawn from, in the order they are inspected. */
+export declare const SIM_PRESENCE_FIELDS: readonly ["sim", "simSlots", "failedReason"];
+export type SimPresenceField = (typeof SIM_PRESENCE_FIELDS)[number];
+/**
+ * WHICH FACT decided a SIM presence — the whole point of this type.
+ *
+ * `absent` is reachable through exactly ONE member (`state-failed-reason`), so a
+ * consumer can prove that no code path inferred "there is no SIM" from a blank or
+ * missing field. A modem that exports `Sim: '/'` and says nothing else is
+ * `no-evidence`/`unknown`: an empty object path is ModemManager's answer for "no SIM
+ * object is bound right now", which a modem also reports while it is still
+ * initializing, while its SIM is locked out, and while a slot switch is in flight.
+ *
+ * `vendor-code-unclaimed` is the router half. HiLink, goform and HIMI each report
+ * their own presence code with vendor semantics no migrated decoder covers, so the
+ * code is NAMED here and its value stays verbatim in the diagnostics block, rather
+ * than being guessed into a presence.
+ */
+export type SimPresenceEvidence = {
+    readonly kind: 'sim-object-path';
+    readonly field: 'sim';
+    readonly value: string;
+} | {
+    readonly kind: 'sim-slot-object-path';
+    readonly field: 'simSlots';
+    readonly value: string;
+} | {
+    readonly kind: 'state-failed-reason';
+    readonly field: 'failedReason';
+    readonly value: typeof SIM_MISSING_FAILED_REASON;
+} | {
+    readonly kind: 'no-evidence';
+    readonly inspected: readonly SimPresenceField[];
+} | {
+    readonly kind: 'vendor-code-unclaimed';
+    readonly field: string;
+};
+export type SimPresenceReading = {
+    readonly presence: SimPresence;
+    readonly evidence: SimPresenceEvidence;
+};
+/** The presence decision together with the fact that produced it. */
+export declare function readSimPresence(facts: SimPresenceFacts): SimPresenceReading;
+export declare function deriveSimPresence(facts: SimPresenceFacts): SimPresence;
+export type RouterSignalUnknownReason = 'unsupported' | 'not-reported' | 'malformed' | 'auth-expired' | 'unreachable';
+export type RouterSignalMetric = {
+    readonly state: 'known';
+    readonly value: number;
+} | {
+    readonly state: 'unknown';
+    readonly reason: RouterSignalUnknownReason;
+};
+export type RouterSignalModel = {
+    readonly provenance: 'hilink-admin-api' | 'zte-goform' | 'ufi-himiapi';
+    readonly freshness: 'live' | 'unknown';
+    readonly bars: RouterSignalMetric;
+    readonly max_bars: RouterSignalMetric;
+    readonly dbm: RouterSignalMetric;
+    readonly rsrp: RouterSignalMetric;
+    readonly rsrq: RouterSignalMetric;
+    readonly snr: RouterSignalMetric;
+    readonly sinr: RouterSignalMetric;
+};
+export declare function parseHilinkSignal(input: {
+    readonly status: string;
+    readonly signal: string;
+}): RouterSignalModel;
+export declare function parseZteSignal(body: string): RouterSignalModel;
+export declare function parseUfiSignal(input: {
+    readonly sysinfo: string;
+    readonly overview: string;
+    readonly status: string;
+}): RouterSignalModel;
+export type RouterDetails = Readonly<Record<string, string>>;
+export declare function parseZteDetails(body: string): RouterDetails | undefined;
+export declare function parseUfiDetails(input: {
+    readonly overview?: string;
+    readonly sysinfo?: string;
+    readonly produceInfo?: string;
+}): RouterDetails | undefined;

package/dist/hardware/router-parsers.js

@@ -0,0 +1,234 @@
+import { z } from 'zod';
+import { parseHilinkXmlValue } from './hilink-protocol.js';
+export * from './hilink-protocol.js';
+const SIM_OBJECT_PATH = /^\/org\/freedesktop\/ModemManager1\/SIM\/\d+$/;
+/** The mmcli spelling of `MM_MODEM_STATE_FAILED_REASON_SIM_MISSING` — the ONLY proof of absence. */
+export const SIM_MISSING_FAILED_REASON = 'sim-missing';
+/** The fields a presence decision may be drawn from, in the order they are inspected. */
+export const SIM_PRESENCE_FIELDS = ['sim', 'simSlots', 'failedReason'];
+/** The presence decision together with the fact that produced it. */
+export function readSimPresence(facts) {
+    const sim = facts.sim?.trim() ?? '';
+    if (SIM_OBJECT_PATH.test(sim)) {
+        return { presence: 'present', evidence: { kind: 'sim-object-path', field: 'sim', value: sim } };
+    }
+    const slot = facts.simSlots
+        ?.map((each) => each.trim())
+        .find((each) => SIM_OBJECT_PATH.test(each));
+    if (slot !== undefined) {
+        return {
+            presence: 'present',
+            evidence: { kind: 'sim-slot-object-path', field: 'simSlots', value: slot },
+        };
+    }
+    if (facts.failedReason === SIM_MISSING_FAILED_REASON) {
+        return {
+            presence: 'absent',
+            evidence: {
+                kind: 'state-failed-reason',
+                field: 'failedReason',
+                value: SIM_MISSING_FAILED_REASON,
+            },
+        };
+    }
+    return { presence: 'unknown', evidence: { kind: 'no-evidence', inspected: SIM_PRESENCE_FIELDS } };
+}
+export function deriveSimPresence(facts) {
+    return readSimPresence(facts).presence;
+}
+const unknown = (reason) => ({
+    state: 'unknown',
+    reason,
+});
+const known = (value) => ({ state: 'known', value });
+function numericMetric(value) {
+    if (value === undefined || String(value).trim() === '')
+        return unknown('not-reported');
+    const parsed = Number.parseFloat(String(value));
+    return Number.isFinite(parsed) ? known(parsed) : unknown('malformed');
+}
+const flatRecordSchema = z.record(z.string(), z.union([z.string(), z.number()]));
+const ufiBodySchema = z.object({
+    reply: z.string(),
+    params: flatRecordSchema.optional(),
+});
+function parseFlatRecord(body) {
+    const parsed = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(flatRecordSchema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+function parseUfiBody(body) {
+    const parsed = z
+        .string()
+        .transform((value, context) => {
+        try {
+            return JSON.parse(value);
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            context.addIssue({ code: 'custom', message: 'invalid JSON' });
+            return z.NEVER;
+        }
+    })
+        .pipe(ufiBodySchema)
+        .safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+export function parseHilinkSignal(input) {
+    const authStatus = parseHilinkXmlValue(input.status, 'code') === '125002';
+    const authSignal = parseHilinkXmlValue(input.signal, 'code') === '125002';
+    const statusReason = authStatus ? 'auth-expired' : 'not-reported';
+    const signalReason = authSignal ? 'auth-expired' : 'not-reported';
+    const metric = (tag) => authSignal ? unknown(signalReason) : numericMetric(parseHilinkXmlValue(input.signal, tag));
+    return {
+        provenance: 'hilink-admin-api',
+        freshness: authStatus && authSignal ? 'unknown' : 'live',
+        bars: authStatus
+            ? unknown(statusReason)
+            : numericMetric(parseHilinkXmlValue(input.status, 'SignalIcon')),
+        max_bars: authStatus
+            ? unknown(statusReason)
+            : numericMetric(parseHilinkXmlValue(input.status, 'maxsignal')),
+        dbm: metric('rssi'),
+        rsrp: metric('rsrp'),
+        rsrq: metric('rsrq'),
+        snr: unknown('unsupported'),
+        sinr: metric('sinr'),
+    };
+}
+export function parseZteSignal(body) {
+    const record = parseFlatRecord(body);
+    const malformed = record === undefined;
+    const metric = (key) => malformed ? unknown('malformed') : numericMetric(record[key]);
+    const bars = metric('signalbar');
+    return {
+        provenance: 'zte-goform',
+        freshness: malformed ? 'unknown' : 'live',
+        bars,
+        max_bars: bars.state === 'known' ? known(5) : unknown('not-reported'),
+        dbm: metric('rssi'),
+        rsrp: metric('lte_rsrp'),
+        rsrq: metric('lte_rsrq'),
+        snr: metric('lte_snr'),
+        sinr: unknown('unsupported'),
+    };
+}
+export function parseUfiSignal(input) {
+    const bodies = [input.sysinfo, input.overview, input.status].map(parseUfiBody);
+    const authExpired = bodies.every((body) => body?.reply === 'SessionOut');
+    const answered = bodies.some((body) => body?.reply === 'ok');
+    const value = bodies[0]?.params?.SIGNAL ?? bodies[1]?.params?.SIGNAL ?? bodies[2]?.params?.signalStrength;
+    const dbm = authExpired
+        ? unknown('auth-expired')
+        : answered
+            ? numericMetric(value)
+            : unknown('malformed');
+    return {
+        provenance: 'ufi-himiapi',
+        freshness: answered ? 'live' : 'unknown',
+        bars: unknown('unsupported'),
+        max_bars: unknown('unsupported'),
+        dbm,
+        rsrp: unknown('unsupported'),
+        rsrq: unknown('unsupported'),
+        snr: unknown('unsupported'),
+        sinr: unknown('unsupported'),
+    };
+}
+/**
+ * The vendor's own "unset" placeholders. A UFI answers `-` for a WAN address, an
+ * IMSI and an ICCID it does not have, and the ZTE builds answer `--` / `N/A` for
+ * an unpopulated counter — publishing any of those as a reading puts a value on
+ * screen that reads like a real one.
+ */
+const PLACEHOLDERS = new Set(['-', '--', 'n/a', 'N/A']);
+function stated(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized === '' || PLACEHOLDERS.has(normalized) ? undefined : normalized;
+}
+function compact(entries) {
+    const result = {};
+    for (const [key, value] of entries)
+        if (value !== undefined)
+            result[key] = value;
+    return Object.keys(result).length === 0 ? undefined : result;
+}
+export function parseZteDetails(body) {
+    const value = parseFlatRecord(body);
+    if (value === undefined)
+        return undefined;
+    return compact([
+        ['network_type', stated(value.network_type)],
+        [
+            'provider',
+            stated(value.network_provider_fullname) ??
+                stated(value.network_provider) ??
+                stated(value.provider),
+        ],
+        ['cell_id', stated(value.cell_id)],
+        ['roaming', stated(value.simcard_roam)],
+        ['mcc', stated(value.rmcc)],
+        ['mnc', stated(value.rmnc)],
+        ['pci', stated(value.lte_pci)],
+        // `band` and `network_band` are two DIFFERENT readings and must not be
+        // folded onto one key: `lte_band` is the serving cell's band, while
+        // `wan_active_band` is the band the WAN leg is active on, and the two
+        // disagree the moment carrier aggregation is up. Publishing either under
+        // the other's name reports a band the device never claimed for that leg.
+        ['band', stated(value.lte_band) ?? stated(value.band)],
+        ['network_band', stated(value.wan_active_band)],
+        ['carrier_aggregation', stated(value.wan_lte_ca)],
+        ['pcell_arfcn', stated(value.lte_ca_pcell_arfcn)],
+        ['pcell_band', stated(value.lte_ca_pcell_band)],
+        ['pcell_bandwidth', stated(value.lte_ca_pcell_bandwidth)],
+        ['scell_arfcn', stated(value.lte_ca_scell_arfcn)],
+        ['scell_band', stated(value.lte_ca_scell_band)],
+        ['scell_bandwidth', stated(value.lte_ca_scell_bandwidth)],
+        ['monthly_tx_bytes', stated(value.monthly_tx_bytes)],
+        ['monthly_rx_bytes', stated(value.monthly_rx_bytes)],
+        ['monthly_time', stated(value.monthly_time)],
+        ['monthly_period', stated(value.date_month)],
+        // Named `session_*` rather than `realtime_*`: these are cumulative counters
+        // and a throughput, and the vendor's own prefix reads as "live rate" for
+        // all five.
+        ['session_tx_bytes', stated(value.realtime_tx_bytes)],
+        ['session_rx_bytes', stated(value.realtime_rx_bytes)],
+        ['session_tx_rate', stated(value.realtime_tx_thrpt)],
+        ['session_rx_rate', stated(value.realtime_rx_thrpt)],
+        ['session_time', stated(value.realtime_time)],
+    ]);
+}
+export function parseUfiDetails(input) {
+    const overview = parseUfiBody(input.overview ?? '')?.params;
+    const sysinfo = parseUfiBody(input.sysinfo ?? '')?.params;
+    const product = parseUfiBody(input.produceInfo ?? '')?.params;
+    return compact([
+        ['product', stated(product?.productname) ?? stated(product?.ProductName)],
+        ['ssid', stated(overview?.SSID)],
+        ['wan_ip', stated(overview?.WANIP)],
+        ['imsi', stated(overview?.IMSI)],
+        ['iccid', stated(overview?.ICCID)],
+        ['web_version', stated(overview?.WEBVER)],
+        ['cell_id', stated(sysinfo?.cellid)],
+        ['station_id', stated(sysinfo?.bsid)],
+        ['cpu_temp', stated(sysinfo?.cputemp)],
+        ['wifi_clients', stated(sysinfo?.wifinum)],
+        ['eth_clients', stated(sysinfo?.ethnum)],
+    ]);
+}