@aubron/ankerts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,766 @@
+type Region = "us" | "eu";
+interface AnkerAccount {
+    user_id: string;
+    auth_token: string;
+    email: string;
+    region: Region;
+    country?: string;
+}
+interface AnkerPrinter {
+    id: string;
+    sn: string;
+    name: string;
+    model: string;
+    /** PPPP device id (`p2p_did`), e.g. `USPRAKM-000994-YYLLG`. */
+    duid: string;
+    /** LAN IP — populated by discovery, not login. Empty until discovered. */
+    ip_addr: string;
+    wifi_mac: string;
+    /** Per-printer MQTT AES key, hex-encoded (`secret_key` from the cloud). */
+    mqtt_key: string;
+    /** PPPP device secret key (`dsk_key`). */
+    p2p_key: string;
+    api_hosts: string[];
+    p2p_hosts: string[];
+    /** MQTT broker host (region-derived if absent). */
+    mqtt_host?: string;
+}
+interface AnkerConfig {
+    account: AnkerAccount | null;
+    printers: AnkerPrinter[];
+    /** DUID of the default-selected printer (`printer select`). */
+    selected?: string;
+}
+/** Region → cloud MQTT broker host. */
+declare const MQTT_HOSTS: Record<Region, string>;
+/** Region → cloud HTTPS app-API host. */
+declare const API_HOSTS: Record<Region, string>;
+declare const REDACTED = "<redacted>";
+/** MQTT username/password are derived from the account (reference `model.py`). */
+declare const mqttUsername: (acct: AnkerAccount) => string;
+declare const mqttPassword: (acct: AnkerAccount) => string;
+/** Resolve the per-printer MQTT broker host (explicit, else region default). */
+declare function mqttHostFor(acct: AnkerAccount, printer: AnkerPrinter): string;
+/** OS-appropriate config directory for the `ankerts` app. */
+declare function configDir(): string;
+/** A JSON-file-backed configuration store. */
+declare class ConfigStore {
+    readonly path: string;
+    constructor(path?: string);
+    exists(): boolean;
+    load(): AnkerConfig;
+    save(config: AnkerConfig): void;
+    /** Mutate-and-persist helper. */
+    update(fn: (config: AnkerConfig) => void): AnkerConfig;
+}
+/** Return a copy of the config with secrets masked (unless `reveal`). */
+declare function redactConfig(config: AnkerConfig, reveal?: boolean): AnkerConfig;
+/**
+ * Resolve a printer reference (DUID, serial, name, or numeric index) against the
+ * configured list. Returns the printer or null.
+ */
+declare function findPrinter(config: AnkerConfig, ref: string | number): AnkerPrinter | null;
+
+/**
+ * Gcode request/response handling (brief §6).
+ *
+ * IMPORTANT — corrected against real M5 hardware (see the project memory). The
+ * brief assumed a gcode reply arrives across multiple `0x0413` frames to be
+ * reassembled. It does not: each send yields exactly ONE reply whose `resData`
+ * is a point-in-time snapshot of the firmware's ~512-byte serial ring buffer,
+ * and the snapshot is RACY. Short replies (M105) come back whole; replies that
+ * exceed the window are capped at 512 bytes; and a reply caught mid-write
+ * truncates early with a `+ringbuf:<a>,512,<b>` marker (the buffer reporting its
+ * own state) — this is the real `echo:Ad` bug.
+ *
+ * So we still concatenate whatever chunks the transport collected, strip ANSI,
+ * and parse — but the key honesty fix is `truncated`: rather than silently
+ * handing back a partial line (as the reference did), we DETECT truncation and
+ * flag it, so a caller never mistakes `echo:Ad` for a complete reply.
+ *
+ * This module is pure: the transport collects the reply and decides completion;
+ * these functions turn the collected chunks into a result, keeping the parser
+ * fully unit-testable against the observed captures.
+ */
+interface GcodeResult {
+    /** Echoed input command. */
+    command: string;
+    /** FULL reassembled text, ANSI-free, all frames concatenated in order. */
+    raw: string;
+    /** `raw` split on newlines, trimmed, with empty lines removed. */
+    lines: string[];
+    /** A terminal `ok` line was seen. */
+    ok: boolean;
+    /** False iff an `echo:Unknown command` line was seen. */
+    recognized: boolean;
+    /** Parsed `echo:Key=Value` / `Key:Value` pairs, e.g. `{ "Advance K": "0.00" }`. */
+    fields: Record<string, string>;
+    /** Parsed Marlin report lines keyed by code, e.g. `{ "M900": "K0.00" }`. */
+    reports: Record<string, string>;
+    /** Wall-clock time spent collecting the response. */
+    durationMs: number;
+    /** Completion signal never arrived within the timeout. */
+    timedOut: boolean;
+    /**
+     * The reply is incomplete: it hit the firmware's ~512-byte snapshot window, or
+     * carries a `+ringbuf:` marker showing the serial buffer was mid-write. When
+     * true, `raw`/`fields`/`reports` may be partial — do not trust them as the
+     * full command output. (The reference silently returned these as if complete.)
+     */
+    truncated: boolean;
+    /** How many reply chunks were collected (diagnostic; usually 1 — see header). */
+    frames: number;
+}
+declare function stripAnsi(text: string): string;
+/** Concatenate reply chunks in arrival order; strip ANSI; normalize newlines. */
+declare function reassembleRaw(chunks: readonly string[]): string;
+/** Split reassembled text into trimmed, non-empty lines. */
+declare function splitLines(raw: string): string[];
+/**
+ * Does the reassembled text END with a terminal `ok`? Marlin terminates a
+ * command's output with an `ok` line (sometimes carrying data, e.g. M105's
+ * `ok T:...`). The check is on the LAST non-empty line, not any line: the M5
+ * firmware emits a leading `ok` (and a double-`ok`) BEFORE the real output (e.g.
+ * `ok\n\nok\n\n+ringbuf:...\necho:Advance K=0.00\nok`), so matching any `ok`
+ * would stop reassembly early and truncate the reply — the `echo:Ad` bug. Used
+ * by the transport's completion detection.
+ */
+declare function gcodeHasTerminalOk(raw: string): boolean;
+/**
+ * Parse the collected reply chunks for one command into a complete GcodeResult.
+ *
+ * @param command  the gcode that was sent (echoed back)
+ * @param chunks   `resData` strings from each reply frame, in arrival order
+ * @param meta     timing/diagnostic info supplied by the transport
+ */
+declare function parseGcodeResult(command: string, chunks: readonly string[], meta: {
+    durationMs: number;
+    timedOut: boolean;
+}): GcodeResult;
+
+/**
+ * Printer status/telemetry normalization (brief §5 + §4A).
+ *
+ * Notices stream continuously over MQTT `.../notice`. They carry raw firmware
+ * units — temperatures in 1/100 °C, progress in 1/100 % — which we normalize so
+ * callers never touch raw values. Crucially, for third-party-sliced gcode the
+ * firmware's headline ETA is garbage (§4A); we detect that and mark the ETA
+ * unreliable rather than surfacing a bogus 20,000-hour estimate.
+ */
+type JobState = "idle" | "printing" | "paused" | "complete" | "failed" | "cancelled";
+interface PrinterStatus {
+    nozzle: {
+        current: number;
+        target: number;
+    };
+    bed: {
+        current: number;
+        target: number;
+    };
+    job?: {
+        name: string;
+        state: JobState;
+        progressPct: number;
+        layer: number;
+        totalLayers: number;
+        etaSeconds?: number;
+        etaReliable?: boolean;
+        filamentUsed?: number;
+        filamentUnit?: string;
+        speedMmS?: number;
+        speedFactorPct?: number;
+    };
+    raw: Record<string, unknown>;
+}
+/** A raw notice payload: at minimum a `commandType`, plus arbitrary fields. */
+type RawNotice = Record<string, unknown> & {
+    commandType?: number;
+};
+/**
+ * Decide whether a `print_schedule` notice's ETA is trustworthy. Native
+ * AnkerMake/eufyMake gcode carries the proprietary time metadata the firmware
+ * needs; third-party slicers (OrcaSlicer/PrusaSlicer) do not, so the firmware
+ * emits an inconsistent `time` vs `totalTime` and an absurd remaining time.
+ */
+declare function isEtaReliable(schedule: RawNotice): boolean;
+/**
+ * Fold a set of notice payloads into a normalized {@link PrinterStatus}.
+ * The latest notice of each type wins. `etaReliableOverride` lets a caller that
+ * already knows the file is third-party force the ETA to be marked unreliable.
+ */
+declare function normalizeStatus(notices: readonly RawNotice[], opts?: {
+    etaReliableOverride?: boolean;
+}): PrinterStatus;
+
+/**
+ * HTTPS cloud API transport (brief §5, §8) — ported from the reference
+ * `libflagship/httpapi.py` and the `anselor` `config login` flow.
+ *
+ * Handles email/password login (ECDH-encrypted password), profile + printer
+ * list retrieval, and PPPP key fetch — assembling a full {@link AnkerConfig}.
+ * Region-coded endpoints; the login captcha branch surfaces as a structured
+ * {@link AuthError} (never a hang).
+ */
+
+type Json = Record<string, unknown>;
+declare function guessRegion(countryCode: string): Region;
+interface LoginResult {
+    auth_token: string;
+    user_id: string;
+    email: string;
+    region: Region;
+    ab_code?: string;
+}
+interface LoginOptions {
+    email: string;
+    password: string;
+    /** 2-letter country code selecting the API region. */
+    country: string;
+    captchaId?: string;
+    captchaAnswer?: string;
+}
+/** Low-level cloud HTTPS client for a single region. */
+declare class AnkerHttpApi {
+    readonly region: Region;
+    private readonly authToken?;
+    constructor(region: Region, authToken?: string | undefined);
+    private base;
+    private request;
+    /** Translate a non-zero API response into a structured error (captcha-aware). */
+    private apiError;
+    login(opts: LoginOptions): Promise<LoginResult>;
+    profile(): Promise<{
+        user_id: string;
+        email: string;
+        country: string;
+    }>;
+    queryFdmList(): Promise<Json[]>;
+    getDskKeys(stationSns: string[]): Promise<Record<string, string>>;
+}
+/**
+ * Full login → config bootstrap (reference `fetch_config_by_login` +
+ * `load_config_from_api`). Logs in, then pulls profile, printer list, and PPPP
+ * keys, returning a ready-to-store {@link AnkerConfig}.
+ */
+declare function loginAndBuildConfig(opts: LoginOptions): Promise<AnkerConfig>;
+
+declare const PPPP_LAN_PORT = 32108;
+declare enum PpppState {
+    Idle = 1,
+    Connecting = 2,
+    Connected = 3,
+    Disconnected = 4
+}
+interface LanPrinter {
+    duid: string;
+    ip: string;
+}
+interface UploadProgress {
+    sent: number;
+    total: number;
+    pct: number;
+}
+interface PpppClientOptions {
+    duid: string;
+    host: string;
+    port?: number;
+    log?: (msg: string) => void;
+}
+/**
+ * One-shot LAN discovery: broadcast a `LAN_SEARCH` and collect `PUNCH_PKT`
+ * replies (each yields a DUID + source IP). Retried by the caller — UDP
+ * broadcast is flaky (the §4 lesson).
+ */
+declare function discoverLan(opts?: {
+    timeoutMs?: number;
+    bindAddr?: string;
+    log?: (m: string) => void;
+}): Promise<LanPrinter[]>;
+declare class AnkerPpppClient {
+    private sock?;
+    private addr;
+    private readonly duid;
+    private readonly chans;
+    private pollTimer?;
+    private readonly log;
+    state: PpppState;
+    private connectResolve?;
+    private connectReject?;
+    constructor(opts: PpppClientOptions);
+    private get host();
+    private send;
+    /** Connect over the LAN via the punch/ready handshake. */
+    connect(timeoutMs?: number): Promise<void>;
+    private failConnect;
+    private pollChannels;
+    private process;
+    stop(): void;
+    /** Send one channel-1 AABB request and await the printer's reply byte. */
+    private aabbRequest;
+    /**
+     * Upload a gcode file and (by default) start the print. Mirrors the reference
+     * web service: XZYH(P2P_SEND_FILE) → AABB BEGIN (metadata) → AABB DATA chunks
+     * → AABB END (starts printing).
+     */
+    uploadFile(filename: string, data: Buffer, opts?: {
+        userName?: string;
+        userId?: string;
+        machineId?: string;
+        start?: boolean;
+        onProgress?: (p: UploadProgress) => void;
+    }): Promise<{
+        name: string;
+        size: number;
+        md5: string;
+        started: boolean;
+    }>;
+}
+
+/**
+ * Waitable conditions over server-authoritative printer state (brief §6A).
+ *
+ * Every wait is re-derivable from a fresh status snapshot, which is what makes
+ * waits re-attachable: an agent that crashed or timed out mid-wait can re-issue
+ * the same wait and it resolves against current state — no dependence on a live
+ * subscription. This module is the pure predicate layer; `AnkerClient.waitFor`
+ * supplies the polling/event loop.
+ */
+
+type WaitCondition = {
+    kind: "connected";
+} | {
+    kind: "lan";
+} | {
+    kind: "nozzle";
+    atLeast: number;
+} | {
+    kind: "bed";
+    atLeast: number;
+} | {
+    kind: "temp-stable";
+} | {
+    kind: "printing";
+} | {
+    kind: "idle";
+} | {
+    kind: "progress";
+    atLeast: number;
+} | {
+    kind: "layer";
+    atLeast: number;
+} | {
+    kind: "complete";
+} | {
+    kind: "failed";
+} | {
+    kind: "cancelled";
+} | {
+    kind: "runout";
+};
+/**
+ * Parse a CLI condition string such as `nozzle>=210`, `progress>=50`, or
+ * `complete` into a {@link WaitCondition}.
+ */
+declare function parseWaitCondition(input: string): WaitCondition;
+/** Render a condition back to its canonical string form. */
+declare function describeWaitCondition(cond: WaitCondition): string;
+/**
+ * Evaluate a status-derived condition against a snapshot. Transport-only
+ * conditions (`connected`, `lan`) return `null` — the caller resolves those from
+ * transport state, not status.
+ */
+declare function conditionHolds(cond: WaitCondition, status: PrinterStatus): boolean | null;
+
+type PrinterEvent = RawNotice;
+type Unsubscribe = () => void;
+type Logger = (msg: string) => void;
+interface AnkerClientOptions {
+    store?: ConfigStore;
+    log?: Logger;
+    printer?: string | number;
+    /** Disable TLS verification on transports (testing only). */
+    insecure?: boolean;
+}
+interface GcodeOptions {
+    timeoutMs?: number;
+    quietMs?: number;
+    wait?: boolean;
+    /** Append M400 semantics so the call returns on true motion completion. */
+    waitMotion?: boolean;
+}
+interface WaitOptions {
+    source?: "events" | "poll" | "hybrid";
+    pollMs?: number;
+    timeoutMs?: number;
+    onTick?: (status: PrinterStatus) => void;
+}
+interface MachineSettings {
+    /**
+     * The M503 result. NOTE: M503's output usually exceeds the firmware's
+     * ~512-byte reply window, so this can be partial — check `result.truncated`
+     * before treating `reports` as the complete settings set.
+     */
+    result: GcodeResult;
+    reports: Record<string, string>;
+    linearAdvanceK?: number;
+    hotendPid?: {
+        p: number;
+        i: number;
+        d: number;
+    };
+    steps?: string;
+    probeZOffset?: number;
+}
+interface JobResult {
+    name: string;
+    size: number;
+    md5: string;
+    started: boolean;
+    transport: "lan";
+    duid: string;
+    ip: string;
+}
+interface LanDiscoverOptions {
+    retries?: number;
+    timeoutMs?: number;
+    store?: boolean;
+}
+/** Per-command default gcode timeouts by latency class (§6A). */
+declare function defaultTimeoutFor(command: string): number;
+declare class AnkerClient {
+    private config;
+    private readonly store?;
+    private readonly log;
+    private readonly insecure;
+    private printerRef?;
+    private mqtt?;
+    constructor(config: AnkerConfig, opts?: AnkerClientOptions);
+    static login(opts: LoginOptions & {
+        save?: boolean;
+    }): Promise<AnkerClient>;
+    static fromStoredConfig(path?: string, opts?: AnkerClientOptions): AnkerClient;
+    getConfig(): AnkerConfig;
+    listPrinters(): AnkerPrinter[];
+    selectPrinter(ref: string | number): AnkerPrinter;
+    /** The currently selected printer (explicit ref → stored default → first). */
+    currentPrinter(): AnkerPrinter;
+    private notFound;
+    private account;
+    private ensureMqtt;
+    /** Close any open transports. */
+    close(): Promise<void>;
+    getStatus(): Promise<PrinterStatus>;
+    subscribeEvents(handler: (e: PrinterEvent) => void): Promise<Unsubscribe>;
+    gcode(command: string, opts?: GcodeOptions): Promise<GcodeResult>;
+    /** Run many commands, yielding each result as it completes (NDJSON-friendly). */
+    gcodeBatch(commands: string[], opts?: GcodeOptions): AsyncIterable<GcodeResult>;
+    snapshotState(): Promise<MachineSettings>;
+    restoreState(): Promise<GcodeResult>;
+    cancelJob(): Promise<void>;
+    pauseJob(): Promise<void>;
+    resumeJob(): Promise<void>;
+    discoverLan(opts?: LanDiscoverOptions): Promise<{
+        duid: string;
+        ip: string;
+    }[]>;
+    private persistDiscoveredIps;
+    /**
+     * Upload a gcode file over the LAN and (by default) start the print. Auto-runs
+     * discovery if the printer's IP is unknown; if it's still unreachable, throws
+     * {@link TransportUnavailableError} (exit 6) naming the transport and the fix.
+     */
+    uploadAndPrint(file: string | Buffer, opts?: {
+        start?: boolean;
+        transport?: "lan" | "auto";
+        /**
+         * Auto-fix the LCD ETA/filament display by transcoding a third-party
+         * slicer's embedded estimate into the Anker `;TIME:` header. ON by default
+         * (it auto-detects: a no-op on natively-sliced files, which already carry
+         * `;TIME:`). Operates on a copy — never mutates the file. Set `false` to
+         * upload the file byte-for-byte untouched.
+         */
+        fixMetadata?: boolean;
+        filename?: string;
+        onProgress?: (p: UploadProgress) => void;
+    }): Promise<JobResult>;
+    /**
+     * Block until `cond` holds, resolving the current status. Re-attachable: it
+     * re-derives state from fresh snapshots, so a re-issued wait still resolves.
+     * Rejects with a retriable {@link TimeoutError} (exit 5) on timeout.
+     */
+    waitFor(cond: WaitCondition, opts?: WaitOptions): Promise<PrinterStatus>;
+}
+
+/**
+ * Typed errors (brief §3, §7). Every error the SDK throws carries a structured,
+ * machine-parseable shape — code, transport, retriability, an actionable hint,
+ * and the echoed input — and maps to a documented CLI exit code. The SDK never
+ * writes to stderr or exits; it throws these and lets the CLI format + map them.
+ */
+type Transport = "mqtt" | "pppp" | "https";
+/** The structured body emitted as the JSON error and on stderr. */
+interface AnkerErrorBody {
+    code: string;
+    message: string;
+    transport?: Transport;
+    retriable: boolean;
+    hint?: string;
+    input?: Record<string, unknown>;
+}
+interface AnkerErrorOptions {
+    code: string;
+    message: string;
+    transport?: Transport;
+    retriable?: boolean;
+    hint?: string;
+    input?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * Base class for all SDK errors. `exitCode` is the documented CLI contract:
+ *
+ * ```
+ * 1  generic / unexpected      4  printer not found / not selected
+ * 2  usage error               5  connectivity / timeout (RETRIABLE)
+ * 3  auth error                6  transport unavailable for this op
+ *                              7  printer-side error (gcode rejected, job refused)
+ * ```
+ */
+declare class AnkerError extends Error {
+    readonly exitCode: number;
+    readonly code: string;
+    readonly transport?: Transport;
+    readonly retriable: boolean;
+    readonly hint?: string;
+    input?: Record<string, unknown>;
+    constructor(opts: AnkerErrorOptions);
+    /** Attach/merge the failing input (the CLI echoes this back). */
+    withInput(input: Record<string, unknown>): this;
+    /** The structured body for JSON output and stderr. */
+    body(): AnkerErrorBody;
+    toJSON(): {
+        error: AnkerErrorBody;
+    };
+}
+/** Exit 2 — bad/missing arguments. Thrown mostly at the CLI boundary. */
+declare class UsageError extends AnkerError {
+    readonly exitCode = 2;
+    constructor(opts: Omit<AnkerErrorOptions, "code"> & {
+        code?: string;
+    });
+}
+/** Exit 3 — login required/expired/captcha. */
+declare class AuthError extends AnkerError {
+    readonly exitCode = 3;
+    constructor(opts: Omit<AnkerErrorOptions, "code"> & {
+        code?: string;
+    });
+}
+/** Exit 4 — printer not found on the account / none selected. */
+declare class PrinterNotFoundError extends AnkerError {
+    readonly exitCode = 4;
+    constructor(opts: Omit<AnkerErrorOptions, "code"> & {
+        code?: string;
+    });
+}
+/** Exit 5 — connectivity/timeout. Always retriable (transient). */
+declare class TimeoutError extends AnkerError {
+    readonly exitCode = 5;
+    constructor(opts: Omit<AnkerErrorOptions, "code" | "retriable"> & {
+        code?: string;
+    });
+}
+/** Exit 6 — the chosen op needs a transport the printer isn't reachable on. */
+declare class TransportUnavailableError extends AnkerError {
+    readonly exitCode = 6;
+    constructor(opts: Omit<AnkerErrorOptions, "code"> & {
+        code?: string;
+    });
+}
+/** Exit 7 — the printer rejected the request (gcode/job refused). */
+declare class PrinterRejectedError extends AnkerError {
+    readonly exitCode = 7;
+    constructor(opts: Omit<AnkerErrorOptions, "code"> & {
+        code?: string;
+    });
+}
+/** Map any thrown value to an {@link AnkerError} (wrapping unknowns as exit 1). */
+declare function toAnkerError(err: unknown): AnkerError;
+
+/**
+ * State-mutating gcode detection (brief §4, lesson #5).
+ *
+ * Many gcode commands change persistent or volatile machine state. The reference
+ * silently let us set Linear Advance K in RAM, contaminating the next print. The
+ * SDK flags these so the CLI can warn — noting that the change is volatile, that
+ * `M500` persists it to EEPROM, and that `M501` reloads EEPROM to revert.
+ */
+interface GcodeInspection {
+    /** The leading G/M code, uppercased (e.g. `M900`), or null if unparseable. */
+    code: string | null;
+    /** True if the command writes machine state (volatile or persistent). */
+    mutatesState: boolean;
+    /** True if the effect lives in volatile RAM until power-cycle or `M501`. */
+    volatile: boolean;
+    /** True if the command persists settings to EEPROM (`M500`). */
+    persists: boolean;
+    /** Human-readable note about side effects (empty when none). */
+    note: string;
+}
+/** Extract the leading gcode word (e.g. `M900` from `M900 K0.5 ; comment`). */
+declare function gcodeCode(command: string): string | null;
+/** Inspect a gcode command for state-mutation side effects. */
+declare function inspectGcode(command: string): GcodeInspection;
+
+/**
+ * Gcode metadata transcoder (brief §4A, optional `print --fix-metadata`).
+ *
+ * Third-party slicers (OrcaSlicer/PrusaSlicer) print correctly on the M5, but
+ * the firmware's headline ETA/filament display reads from Anker-proprietary
+ * header comments those slicers don't emit. AnkerMake Studio is Cura-based and
+ * writes a `;TIME:<seconds>s` header; OrcaSlicer writes a human-readable
+ * `; estimated printing time (normal mode) = 1h 39m 52s` instead.
+ *
+ * This is a TRANSCODER, not a calculator: the slicer already embedded its own
+ * estimate; we only rewrite it into the keys/units Anker firmware reads. Motion,
+ * temps, and `M73` progress are left untouched (they already work cross-slicer).
+ * We never mutate the user's file — callers transcode a copy in the upload path.
+ */
+interface TranscodeResult {
+    /** The (possibly) rewritten gcode. */
+    content: string;
+    /** True if any Anker header line was injected. */
+    changed: boolean;
+    /** What was transcoded (for logging/reporting). */
+    injected: {
+        timeSeconds?: number;
+        filamentMm?: number;
+        filamentGrams?: number;
+    };
+}
+/** Parse a duration like `1d 2h 39m 52s` / `1h 39m 52s` / `99m` into seconds. */
+declare function parseDurationToSeconds(text: string): number | undefined;
+/** Heuristic slicer detection from header comments. */
+declare function detectSlicer(gcode: string): "ankermake" | "orca" | "prusa" | "unknown";
+/** True when the firmware would already read a correct headline ETA. */
+declare function hasAnkerTimeHeader(gcode: string): boolean;
+/**
+ * Transcode a third-party slicer's embedded estimates into Anker/Cura header
+ * comments. No-op (returns the input unchanged) when the file already carries a
+ * `;TIME:` header — i.e. it was sliced natively.
+ */
+declare function transcodeMetadata(gcode: string): TranscodeResult;
+
+/**
+ * MQTT `commandType` enum and notice identifiers, extracted from the reference
+ * `libflagship/mqtt.py` and the live captures documented in the brief (§5).
+ *
+ * The firmware speaks numeric command types; we name the ones that matter and
+ * leave the rest reachable through the raw `send`/numeric value.
+ */
+/** MQTT command/notice types (`commandType` field). Values are decimal. */
+declare enum MqttCommandType {
+    EVENT_NOTIFY = 1000,// 1000
+    PRINT_SCHEDULE = 1001,// 1001
+    FIRMWARE_VERSION = 1002,// 1002
+    NOZZLE_TEMP = 1003,// 1003 — 1/100 °C
+    HOTBED_TEMP = 1004,// 1004 — 1/100 °C
+    FAN_SPEED = 1005,// 1005
+    PRINT_SPEED = 1006,// 1006
+    AUTO_LEVELING = 1007,// 1007
+    PRINT_CONTROL = 1008,// 1008
+    FILE_LIST_REQUEST = 1009,// 1009
+    APP_QUERY_STATUS = 1027,// 1027
+    ONLINE_NOTIFY = 1028,// 1028
+    RECOVER_FACTORY = 1029,// 1029
+    BREAK_POINT = 1039,// 1039
+    MODEL_LAYER = 1052,// 1052
+    GCODE_COMMAND = 1043
+}
+/** Notice `commandType` values seen streaming on `.../notice` (decimal §5). */
+declare enum NoticeType {
+    EVENT_NOTIFY = 1000,
+    PRINT_SCHEDULE = 1001,
+    NOZZLE_TEMP = 1003,
+    HOTBED_TEMP = 1004,
+    PRINT_SPEED = 1006,
+    MODEL_LAYER = 1052
+}
+/**
+ * `PRINT_CONTROL` (0x03f0) `value` for job control. Reverse-engineered live
+ * against an M5 (2026-06-07): each value was sent and confirmed by watching the
+ * printer's authoritative job state and heater targets.
+ */
+declare enum PrintControl {
+    PAUSE = 2,// → state 2 (paused), progress freezes
+    RESUME = 3,// → state 1 (printing)
+    STOP = 4
+}
+
+interface MqttClientOptions {
+    sn: string;
+    /** Per-printer AES key (decoded from the hex `mqtt_key`). */
+    key: Buffer;
+    host: string;
+    port?: number;
+    username: string;
+    password: string;
+    guid?: string;
+    /** Override the pinned CA (advanced). */
+    ca?: string;
+    /** Disable TLS verification (testing only). */
+    insecure?: boolean;
+    /** Diagnostic sink (defaults to no-op; the CLI routes this to stderr). */
+    log?: (msg: string) => void;
+}
+interface GcodeWaitOptions {
+    /** Hard ceiling before giving up (latency-class aware; default 10s). */
+    timeoutMs?: number;
+    /** Quiet period with no new frame that signals completion (default 600ms). */
+    quietMs?: number;
+    /** When false, fire-and-forget: publish and return without collecting. */
+    wait?: boolean;
+}
+type NoticeHandler = (notice: RawNotice) => void;
+declare class AnkerMqttClient {
+    private readonly opts;
+    private client?;
+    private readonly guid;
+    private readonly log;
+    private readonly noticeHandlers;
+    private readonly replyHandlers;
+    private readonly latestNotices;
+    private gcodeLock;
+    constructor(opts: MqttClientOptions);
+    get connected(): boolean;
+    connect(timeoutMs?: number): Promise<void>;
+    disconnect(): Promise<void>;
+    private onMessage;
+    private publish;
+    /** Subscribe to streaming notices. Returns an unsubscribe function. */
+    onNotice(handler: NoticeHandler): () => void;
+    /** Publish a raw command payload (escape hatch for un-modeled commands). */
+    command(payload: Record<string, unknown>): void;
+    /** Publish a raw query payload. */
+    query(payload: Record<string, unknown>): void;
+    /**
+     * Send a single gcode command and return the parsed response (§6). The result
+     * carries `truncated` when the firmware's snapshot was partial. Serialized:
+     * only one gcode is in flight at a time.
+     */
+    gcode(command: string, opts?: GcodeWaitOptions): Promise<GcodeResult>;
+    private gcodeOnce;
+    /**
+     * Snapshot current printer status by normalizing the latest notice of each
+     * type. Optionally nudges the printer with an APP_QUERY_STATUS query and waits
+     * briefly for fresh telemetry.
+     */
+    getStatus(opts?: {
+        refresh?: boolean;
+        waitMs?: number;
+    }): Promise<PrinterStatus>;
+    /** Throw a structured timeout error (used by waiters). */
+    static timeout(message: string, hint?: string): never;
+}
+
+export { API_HOSTS, type AnkerAccount, AnkerClient, type AnkerClientOptions, type AnkerConfig, AnkerError, type AnkerErrorBody, AnkerHttpApi, AnkerMqttClient, AnkerPpppClient, type AnkerPrinter, AuthError, ConfigStore, type GcodeInspection, type GcodeOptions, type GcodeResult, type JobResult, type JobState, type LanDiscoverOptions, type LanPrinter, type Logger, type LoginOptions, type LoginResult, MQTT_HOSTS, type MachineSettings, type MqttClientOptions, MqttCommandType, NoticeType, PPPP_LAN_PORT, PpppState, PrintControl, type PrinterEvent, PrinterNotFoundError, PrinterRejectedError, type PrinterStatus, REDACTED, type RawNotice, type Region, TimeoutError, type TranscodeResult, type Transport, TransportUnavailableError, type Unsubscribe, type UploadProgress, UsageError, type WaitCondition, type WaitOptions, conditionHolds, configDir, defaultTimeoutFor, describeWaitCondition, detectSlicer, discoverLan, findPrinter, gcodeCode, gcodeHasTerminalOk, guessRegion, hasAnkerTimeHeader, inspectGcode, isEtaReliable, loginAndBuildConfig, mqttHostFor, mqttPassword, mqttUsername, normalizeStatus, parseDurationToSeconds, parseGcodeResult, parseWaitCondition, reassembleRaw, redactConfig, splitLines, stripAnsi, toAnkerError, transcodeMetadata };