mcp-3d-printer-server 1.2.9 → 1.2.11

package/dist/printers/klipper.js

@@ -1,48 +1,95 @@
-import { PrinterImplementation } from "../types.js";
 import fs from "fs";
 import FormData from "form-data";
-export class KlipperImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation } from "./generic-base.js";
+function encodePath(filename) {
+    return filename.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+}
+export class KlipperImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "Klipper/Moonraker";
+    }
+    authHeaders(apiKey) {
+        return apiKey ? { headers: { "X-Api-Key": apiKey } } : {};
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/printer/info`;
-        const response = await this.apiClient.get(url);
+        const response = await this.apiClient.get(url, this.authHeaders(apiKey));
         return response.data;
     }
     async getFiles(host, port, apiKey) {
         const url = `http://${host}:${port}/server/files/list`;
-        const response = await this.apiClient.get(url);
+        const response = await this.apiClient.get(url, this.authHeaders(apiKey));
         return response.data;
     }
     async getFile(host, port, apiKey, filename) {
         const url = `http://${host}:${port}/server/files/metadata?filename=${encodeURIComponent(filename)}`;
-        const response = await this.apiClient.get(url);
+        const response = await this.apiClient.get(url, this.authHeaders(apiKey));
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    /**
+     * Moonraker object query: webhooks.state must be "ready" (not startup,
+     * shutdown or error) and print_stats.state standby/complete/cancelled.
+     * complete/cancelled can leave a part on the bed, so they need a human.
+     */
+    async readPrinterState(host, port, apiKey) {
+        let data;
+        try {
+            data = (await this.apiClient.get(`http://${host}:${port}/printer/objects/query?webhooks&print_stats`, this.authHeaders(apiKey))).data;
+        }
+        catch (error) {
+            throw new Error(`Cannot read Klipper/Moonraker printer state; nothing was sent: ${error.message}`);
+        }
+        const status = data?.result?.status;
+        const klippy = status?.webhooks?.state;
+        const job = status?.print_stats?.state;
+        if (typeof klippy !== "string" || typeof job !== "string") {
+            throw new Error("Moonraker did not report webhooks.state and print_stats.state; cannot verify the printer is idle.");
+        }
+        const state = `klippy ${klippy}, print ${job}`;
+        if (klippy !== "ready") {
+            return { state, ready: false, reason: status?.webhooks?.state_message ? String(status.webhooks.state_message) : "Klipper is not ready" };
+        }
+        if (!["standby", "complete", "cancelled"].includes(job)) {
+            return { state, ready: false, reason: `print_stats.state is ${job}` };
+        }
+        return {
+            state,
+            ready: true,
+            finishedJob: job === "standby" ? undefined : JSON.stringify([job, status?.print_stats?.filename ?? null]),
+        };
+    }
+    async downloadRemoteFile(host, port, apiKey, filename, destination) {
+        await this.downloadToFile(`http://${host}:${port}/server/files/gcodes/${encodePath(filename)}`, apiKey ? { "X-Api-Key": apiKey } : {}, destination);
+    }
+    /** Current Moonraker returns {result:{item}}; older releases returned result "success". */
+    uploadSucceeded(data) {
+        return data?.result === "success" || !!data?.result?.item || !!data?.item;
+    }
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
         const url = `http://${host}:${port}/server/files/upload`;
         const formData = new FormData();
         formData.append("file", fs.createReadStream(filePath));
         formData.append("filename", filename);
         const response = await this.apiClient.post(url, formData, {
             headers: {
-                ...formData.getHeaders()
+                ...formData.getHeaders(),
+                ...(apiKey ? { "X-Api-Key": apiKey } : {})
             }
         });
-        if (print && response.data.result === "success") {
-            await this.startJob(host, port, apiKey, filename);
-        }
         return response.data;
     }
-    async startJob(host, port, apiKey, filename) {
+    async rawStartJob(host, port, apiKey, filename) {
         const url = `http://${host}:${port}/printer/print/start`;
-        const response = await this.apiClient.post(url, { filename });
+        const response = await this.apiClient.post(url, { filename }, this.authHeaders(apiKey));
         return response.data;
     }
-    async cancelJob(host, port, apiKey) {
+    async rawCancelJob(host, port, apiKey) {
         const url = `http://${host}:${port}/printer/print/cancel`;
-        const response = await this.apiClient.post(url, null);
+        const response = await this.apiClient.post(url, null, this.authHeaders(apiKey));
         return response.data;
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         const url = `http://${host}:${port}/printer/gcode/script`;
         let gcode;
         if (component === "bed") {
@@ -56,7 +103,7 @@ export class KlipperImplementation extends PrinterImplementation {
         }
         const response = await this.apiClient.post(url, {
             script: gcode
-        });
+        }, this.authHeaders(apiKey));
         return response.data;
     }
 }

package/dist/printers/octoprint.d.ts

@@ -1,10 +1,22 @@
-import { PrinterImplementation } from "../types.js";
-export declare class OctoPrintImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState, type HeaterComponent } from "./generic-base.js";
+export declare class OctoPrintImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "OctoPrint";
+    protected readonly uploadStartsPrint = true;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /**
+     * GET /api/printer state.flags (OctoPrint REST API). A 409 means the printer
+     * is not operational. Informational flags such as sdReady never block.
+     */
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    /** OctoPrint reports effectivePrint=false when print=true had no effect. */
+    protected uploadStartedPrint(data: any): boolean;
+    protected downloadRemoteFile(host: string, port: string, apiKey: string, filename: string, destination: string): Promise<void>;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    /** OctoPrint tool targets are keyed tool{n} (POST /api/printer/tool, command "target"). */
+    protected heaterComponent(component: string): HeaterComponent | undefined;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }

package/dist/printers/octoprint.js

@@ -1,7 +1,18 @@
-import { PrinterImplementation } from "../types.js";
 import fs from "fs";
 import FormData from "form-data";
-export class OctoPrintImplementation extends PrinterImplementation {
+import { isAxiosError } from "axios";
+import { GenericPrinterImplementation } from "./generic-base.js";
+const BLOCKING_FLAGS = ["printing", "paused", "pausing", "cancelling", "resuming", "finishing", "error", "closedOrError"];
+function encodePath(filename) {
+    return filename.replace(/^\/+/, "").split("/").map(encodeURIComponent).join("/");
+}
+export class OctoPrintImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "OctoPrint";
+        // POST /api/files/local with print=true uploads and starts the same bytes.
+        this.uploadStartsPrint = true;
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/api/printer`;
         const response = await this.apiClient.get(url, {
@@ -29,7 +40,40 @@ export class OctoPrintImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    /**
+     * GET /api/printer state.flags (OctoPrint REST API). A 409 means the printer
+     * is not operational. Informational flags such as sdReady never block.
+     */
+    async readPrinterState(host, port, apiKey) {
+        let data;
+        try {
+            data = (await this.apiClient.get(`http://${host}:${port}/api/printer`, { headers: { "X-Api-Key": apiKey } })).data;
+        }
+        catch (error) {
+            if (isAxiosError(error) && error.response?.status === 409) {
+                return { state: "Offline", ready: false, reason: "OctoPrint reports the printer is not operational" };
+            }
+            throw new Error(`Cannot read OctoPrint printer state; nothing was sent: ${error.message}`);
+        }
+        const flags = data?.state?.flags;
+        if (!flags || typeof flags !== "object") {
+            throw new Error("OctoPrint returned no printer state flags; cannot verify the printer is idle.");
+        }
+        const blocking = BLOCKING_FLAGS.filter((flag) => flags[flag] === true);
+        if (flags.operational !== true)
+            blocking.unshift("not operational");
+        if (flags.ready === false && !blocking.length)
+            blocking.push("not ready");
+        return { state: String(data?.state?.text ?? "unknown"), ready: blocking.length === 0, reason: blocking.join(", ") || undefined };
+    }
+    /** OctoPrint reports effectivePrint=false when print=true had no effect. */
+    uploadStartedPrint(data) {
+        return data?.effectivePrint !== false;
+    }
+    async downloadRemoteFile(host, port, apiKey, filename, destination) {
+        await this.downloadToFile(`http://${host}:${port}/downloads/files/local/${encodePath(filename)}`, { "X-Api-Key": apiKey }, destination);
+    }
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
         const url = `http://${host}:${port}/api/files/local`;
         const formData = new FormData();
         formData.append("file", fs.createReadStream(filePath));
@@ -45,7 +89,7 @@ export class OctoPrintImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async startJob(host, port, apiKey, filename) {
+    async rawStartJob(host, port, apiKey, filename) {
         const url = `http://${host}:${port}/api/files/local/${filename}`;
         const response = await this.apiClient.post(url, {
             command: "select",
@@ -58,7 +102,7 @@ export class OctoPrintImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async cancelJob(host, port, apiKey) {
+    async rawCancelJob(host, port, apiKey) {
         const url = `http://${host}:${port}/api/job`;
         const response = await this.apiClient.post(url, {
             command: "cancel"
@@ -70,7 +114,19 @@ export class OctoPrintImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
+    /** OctoPrint tool targets are keyed tool{n} (POST /api/printer/tool, command "target"). */
+    heaterComponent(component) {
+        const normalized = component.trim().toLowerCase();
+        if (normalized === "bed")
+            return { heater: "bed", raw: "bed" };
+        if (["extruder", "nozzle", "tool"].includes(normalized))
+            return { heater: "nozzle", raw: "tool0" };
+        const indexed = normalized.match(/^(?:extruder|tool)(\d+)$/);
+        if (indexed)
+            return { heater: "nozzle", raw: `tool${Number(indexed[1])}` };
+        return undefined;
+    }
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         let url = `http://${host}:${port}/api/printer/tool`;
         const data = {};
         if (component === "bed") {
@@ -78,10 +134,9 @@ export class OctoPrintImplementation extends PrinterImplementation {
             data.target = temperature;
             url = `http://${host}:${port}/api/printer/bed`;
         }
-        else if (component.startsWith("extruder")) {
+        else if (/^tool\d+$/.test(component)) {
             data.command = "target";
-            data.targets = {};
-            data.targets[component] = temperature;
+            data.targets = { [component]: temperature };
         }
         else {
             throw new Error(`Unsupported component: ${component}`);

package/dist/printers/printer-factory.d.ts

@@ -1,8 +1,17 @@
 import { PrinterImplementation } from "../types.js";
+import type { ConfirmHardware } from "../safety/confirmation.js";
+import type { PrintSafetyOptions } from "../safety/expected-peaks.js";
+/** Every adapter accepts trailing safety options on its print and heating mutations. */
+export type GuardedPrinterImplementation = PrinterImplementation & {
+    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean, options?: PrintSafetyOptions): Promise<any>;
+    startJob(host: string, port: string, apiKey: string, filename: string, options?: PrintSafetyOptions): Promise<any>;
+    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: unknown, options?: PrintSafetyOptions): Promise<any>;
+};
 export declare class PrinterFactory {
     private implementations;
     private apiClient;
-    constructor();
-    getImplementation(type: string): PrinterImplementation;
+    /** confirm is the human (MCP elicitation) confirmation used before prints and positive heating. */
+    constructor(confirm?: ConfirmHardware);
+    getImplementation(type: string): GuardedPrinterImplementation;
     disconnectAll(): Promise<void>;
 }

package/dist/printers/printer-factory.js

@@ -7,16 +7,17 @@ import { PrusaImplementation } from "./prusa.js";
 import { CrealityImplementation } from "./creality.js";
 import axios from "axios";
 export class PrinterFactory {
-    constructor() {
+    /** confirm is the human (MCP elicitation) confirmation used before prints and positive heating. */
+    constructor(confirm) {
         this.implementations = new Map();
         this.apiClient = axios.create({ timeout: 10000 });
-        this.implementations.set("octoprint", new OctoPrintImplementation(this.apiClient));
-        this.implementations.set("klipper", new KlipperImplementation(this.apiClient));
-        this.implementations.set("duet", new DuetImplementation(this.apiClient));
-        this.implementations.set("repetier", new RepetierImplementation(this.apiClient));
-        this.implementations.set("bambu", new BambuImplementation(this.apiClient));
-        this.implementations.set("prusa", new PrusaImplementation(this.apiClient));
-        this.implementations.set("creality", new CrealityImplementation(this.apiClient));
+        this.implementations.set("octoprint", new OctoPrintImplementation(this.apiClient, confirm));
+        this.implementations.set("klipper", new KlipperImplementation(this.apiClient, confirm));
+        this.implementations.set("duet", new DuetImplementation(this.apiClient, confirm));
+        this.implementations.set("repetier", new RepetierImplementation(this.apiClient, confirm));
+        this.implementations.set("bambu", new BambuImplementation(this.apiClient, confirm));
+        this.implementations.set("prusa", new PrusaImplementation(this.apiClient, confirm));
+        this.implementations.set("creality", new CrealityImplementation(this.apiClient, confirm));
     }
     getImplementation(type) {
         const implementation = this.implementations.get(type.toLowerCase());

package/dist/printers/prusa.d.ts

@@ -1,5 +1,6 @@
-import { PrinterImplementation } from "../types.js";
-export declare class PrusaImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState, type HeaterComponent } from "./generic-base.js";
+export declare class PrusaImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "Prusa";
     private buildAuthHeaders;
     private buildBaseUrl;
     private defaultProtocolFor;
@@ -11,8 +12,15 @@ export declare class PrusaImplementation extends PrinterImplementation {
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /**
+     * PrusaLink /api/v1/status printer.state, falling back to the legacy
+     * OctoPrint-compatible /api/printer flags. FINISHED and STOPPED are idle but
+     * may leave a part on the bed, so they require a human confirmation.
+     */
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected heaterComponent(component: string): HeaterComponent | undefined;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }

package/dist/printers/prusa.js

@@ -1,8 +1,14 @@
 import { isAxiosError } from "axios";
-import { PrinterImplementation } from "../types.js";
+import { GenericPrinterImplementation } from "./generic-base.js";
 import fs from "fs";
 import FormData from "form-data";
-export class PrusaImplementation extends PrinterImplementation {
+const PRUSALINK_READY_STATES = new Set(["IDLE", "READY", "FINISHED", "STOPPED"]);
+const OCTOPRINT_BLOCKING_FLAGS = ["printing", "paused", "pausing", "cancelling", "resuming", "finishing", "error", "closedOrError"];
+export class PrusaImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "Prusa";
+    }
     buildAuthHeaders(apiKey) {
         return {
             Accept: "application/json",
@@ -114,7 +120,41 @@ export class PrusaImplementation extends PrinterImplementation {
         ]);
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    /**
+     * PrusaLink /api/v1/status printer.state, falling back to the legacy
+     * OctoPrint-compatible /api/printer flags. FINISHED and STOPPED are idle but
+     * may leave a part on the bed, so they require a human confirmation.
+     */
+    async readPrinterState(host, port, apiKey) {
+        let response;
+        try {
+            response = await this.getWithFallback(host, port, apiKey, ["/api/v1/status", "/api/printer"]);
+        }
+        catch (error) {
+            throw new Error(`Cannot read Prusa printer state; nothing was sent: ${error.message}`);
+        }
+        const data = response.data;
+        const v1State = data?.printer?.state;
+        if (typeof v1State === "string" && v1State) {
+            const state = v1State.toUpperCase();
+            const ready = PRUSALINK_READY_STATES.has(state);
+            return {
+                state,
+                ready,
+                reason: ready ? undefined : `printer.state is ${state}`,
+                finishedJob: ready && (state === "FINISHED" || state === "STOPPED") ? JSON.stringify([state, data?.job?.id ?? null]) : undefined,
+            };
+        }
+        const flags = data?.state?.flags;
+        if (flags && typeof flags === "object") {
+            const blocking = OCTOPRINT_BLOCKING_FLAGS.filter((flag) => flags[flag] === true);
+            if (flags.operational !== true)
+                blocking.unshift("not operational");
+            return { state: String(data?.state?.text ?? "unknown"), ready: blocking.length === 0, reason: blocking.join(", ") || undefined };
+        }
+        throw new Error("Prusa did not report printer.state or state flags; cannot verify the printer is idle.");
+    }
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
         const formData = new FormData();
         formData.append("file", fs.createReadStream(filePath));
         formData.append("filename", filename);
@@ -126,12 +166,10 @@ export class PrusaImplementation extends PrinterImplementation {
                 ...formData.getHeaders(),
             },
         });
-        if (print) {
-            await this.startJob(host, port, apiKey, filename);
-        }
+        // Printing is started by the shared gate only after a fresh state recheck.
         return response.data;
     }
-    async startJob(host, port, apiKey, filename) {
+    async rawStartJob(host, port, apiKey, filename) {
         const response = await this.postWithFallback(host, port, apiKey, [
             {
                 route: "/api/v1/job",
@@ -164,7 +202,7 @@ export class PrusaImplementation extends PrinterImplementation {
         ]);
         return response.data;
     }
-    async cancelJob(host, port, apiKey) {
+    async rawCancelJob(host, port, apiKey) {
         const response = await this.postWithFallback(host, port, apiKey, [
             {
                 route: "/api/v1/job",
@@ -181,7 +219,16 @@ export class PrusaImplementation extends PrinterImplementation {
         ]);
         return response.data;
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
+    heaterComponent(component) {
+        const normalized = component.trim().toLowerCase();
+        if (normalized === "bed")
+            return { heater: "bed", raw: "bed" };
+        if (normalized.startsWith("extruder") || normalized === "nozzle" || normalized === "tool0" || normalized === "tool") {
+            return { heater: "nozzle", raw: "nozzle" };
+        }
+        return undefined;
+    }
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         const normalized = component.toLowerCase();
         if (normalized === "bed") {
             const response = await this.postWithFallback(host, port, apiKey, [

package/dist/printers/repetier.d.ts

@@ -1,10 +1,22 @@
-import { PrinterImplementation } from "../types.js";
-export declare class RepetierImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation, type GenericPrinterState } from "./generic-base.js";
+/**
+ * Note: Repetier-Server documents printer commands at /printer/api/<slug>;
+ * this adapter's slug-less routes are unverified. Remote starts are refused
+ * because Repetier documents no complete file download for inspection.
+ */
+export declare class RepetierImplementation extends GenericPrinterImplementation {
+    protected readonly printerLabel = "Repetier";
+    protected readonly uploadStartsPrint = true;
     getStatus(host: string, port: string, apiKey: string): Promise<any>;
     getFiles(host: string, port: string, apiKey: string): Promise<any>;
     getFile(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    uploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
-    startJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
-    cancelJob(host: string, port: string, apiKey: string): Promise<any>;
-    setTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
+    /**
+     * listPrinter returns one entry per printer (online 0/1, active, job "none").
+     * Without a configured slug, more than one printer is ambiguous.
+     */
+    protected readPrinterState(host: string, port: string, apiKey: string): Promise<GenericPrinterState>;
+    protected rawUploadFile(host: string, port: string, apiKey: string, filePath: string, filename: string, print: boolean): Promise<any>;
+    protected rawStartJob(host: string, port: string, apiKey: string, filename: string): Promise<any>;
+    protected rawCancelJob(host: string, port: string, apiKey: string): Promise<any>;
+    protected rawSetTemperature(host: string, port: string, apiKey: string, component: string, temperature: number): Promise<any>;
 }

package/dist/printers/repetier.js

@@ -1,7 +1,18 @@
-import { PrinterImplementation } from "../types.js";
 import fs from "fs";
 import FormData from "form-data";
-export class RepetierImplementation extends PrinterImplementation {
+import { GenericPrinterImplementation } from "./generic-base.js";
+/**
+ * Note: Repetier-Server documents printer commands at /printer/api/<slug>;
+ * this adapter's slug-less routes are unverified. Remote starts are refused
+ * because Repetier documents no complete file download for inspection.
+ */
+export class RepetierImplementation extends GenericPrinterImplementation {
+    constructor() {
+        super(...arguments);
+        this.printerLabel = "Repetier";
+        // The upload form's print=1 flag uploads and starts the same bytes.
+        this.uploadStartsPrint = true;
+    }
     async getStatus(host, port, apiKey) {
         const url = `http://${host}:${port}/printer/api/?a=getPrinterInfo&apikey=${apiKey}`;
         const response = await this.apiClient.get(url);
@@ -17,7 +28,38 @@ export class RepetierImplementation extends PrinterImplementation {
         const response = await this.apiClient.get(url);
         return response.data;
     }
-    async uploadFile(host, port, apiKey, filePath, filename, print) {
+    /**
+     * listPrinter returns one entry per printer (online 0/1, active, job "none").
+     * Without a configured slug, more than one printer is ambiguous.
+     */
+    async readPrinterState(host, port, apiKey) {
+        let data;
+        try {
+            data = (await this.apiClient.get(`http://${host}:${port}/printer/api/?a=listPrinter&apikey=${encodeURIComponent(apiKey)}`)).data;
+        }
+        catch (error) {
+            throw new Error(`Cannot read Repetier printer state; nothing was sent: ${error.message}`);
+        }
+        const printers = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : undefined;
+        if (!printers)
+            throw new Error("Repetier did not return a printer list; cannot verify the printer is idle.");
+        if (printers.length !== 1) {
+            throw new Error(`Repetier reports ${printers.length} printers; this adapter cannot tell which one would receive the job.`);
+        }
+        const [printer] = printers;
+        const online = printer?.online === 1 || printer?.online === true;
+        const job = typeof printer?.job === "string" ? printer.job : undefined;
+        if (job === undefined)
+            throw new Error("Repetier did not report the printer's job state; cannot verify it is idle.");
+        const reasons = [
+            ...(online ? [] : ["offline"]),
+            ...(printer?.active === false ? ["inactive"] : []),
+            ...(job !== "none" && job !== "" ? [`job ${job} is active`] : []),
+            ...(printer?.paused === true ? ["paused"] : []),
+        ];
+        return { state: `${online ? "online" : "offline"}, job ${job || "none"}`, ready: reasons.length === 0, reason: reasons.join(", ") || undefined };
+    }
+    async rawUploadFile(host, port, apiKey, filePath, filename, print) {
         const url = `http://${host}:${port}/printer/api/`;
         const formData = new FormData();
         formData.append("a", "upload");
@@ -32,17 +74,17 @@ export class RepetierImplementation extends PrinterImplementation {
         });
         return response.data;
     }
-    async startJob(host, port, apiKey, filename) {
+    async rawStartJob(host, port, apiKey, filename) {
         const url = `http://${host}:${port}/printer/api/?a=startJob&apikey=${apiKey}&filename=${encodeURIComponent(filename)}`;
         const response = await this.apiClient.get(url);
         return response.data;
     }
-    async cancelJob(host, port, apiKey) {
+    async rawCancelJob(host, port, apiKey) {
         const url = `http://${host}:${port}/printer/api/?a=stopJob&apikey=${apiKey}`;
         const response = await this.apiClient.get(url);
         return response.data;
     }
-    async setTemperature(host, port, apiKey, component, temperature) {
+    async rawSetTemperature(host, port, apiKey, component, temperature) {
         let url;
         if (component === "bed") {
             url = `http://${host}:${port}/printer/api/?a=setBedTemp&apikey=${apiKey}&temp=${temperature}`;

package/dist/safety/archive.d.ts

@@ -0,0 +1,11 @@
+import JSZip from 'jszip';
+export declare const MAX_PRINT_FILE_BYTES: number;
+/** Read no more than the fixed print-artifact limit, even if the file grows. */
+export declare function readBoundedPrintFile(filePath: string): Promise<Buffer>;
+/** Bounded native inflation prevents false size fields from making JSZip allocate
+ * unbounded output. Populate JSZip only with the verified, uniquely named bytes. */
+export declare function loadSafe3mfArchive(bytes: Buffer): Promise<JSZip>;
+export declare function readSafe3mfArchive(filePath: string): Promise<{
+    bytes: Buffer;
+    zip: JSZip;
+}>;