feat(creator5): add native /printGcode start-job command

The Creator 5 performs material matching at print-start (POST /printGcode),
unlike the AD5X which maps materials at upload time. Add a Creator 5-native
start method that sends only the fields the firmware reads.

- startCreator5Job(Creator5JobParams): POSTs /printGcode with fileName,
  levelingBeforePrint, optional flowCalibration/timeLapseVideo, and 3-field
  Creator5MaterialMapping[] (toolId 0-based, slotId 1-based, materialName).
  Omits materialMappings for single-tool prints; no AD5X-only fields.
- Add Creator5JobParams / Creator5MaterialMapping types + exports.
- Replace the AD5X-bodied start aliases (released minutes ago, no consumers)
  with the native method; keep uploadFileWithMaterialMappings since C5 upload
  genuinely reuses the AD5X path.
- Document Creator 5 support and the library's by-concern organization
  (do-not-refactor-into-per-printer-clients) in CLAUDE.md.

Bump to 1.3.4.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: GhostTypes

CLAUDE.md

@@ -42,6 +42,18 @@ The API uses two communication layers that work together:
 
 Raw API responses (`FFPrinterDetail` in `src/models/ff-models.ts`) are transformed into the structured `FFMachineInfo` model by `MachineInfo.fromDetail()` (`src/models/MachineInfo.ts`). This handles status string-to-enum mapping, time formatting, temperature pairing, and boolean conversion from the printer's "open"/"close" string convention.
 
+### Model Detection (Pid-First)
+
+`MachineInfo.fromDetail()` derives `IsPro` / `IsAD5X` from the firmware-set integer `pid` field on `/detail` (35 = Adventurer 5M, 36 = 5M Pro, 38 = AD5X — see `KNOWN_HTTP_PIDS` in `MachineInfo.ts`). The raw value is also surfaced as `FFMachineInfo.Pid` for consumers that need to do their own model-class gating. When `pid` is absent (older firmware) the parser falls back to a name+capability heuristic, but new code should NOT substring-match `detail.name` — that field is user-mutable via the LCD or cloud account and changing it broke detection in pre-1.3.1 builds (see CHANGELOG entry for 1.3.1, ref `ff-5mp-hass#13`).
+
+### Why TCP Bootstrap Is Still Required for Modern Printers
+
+The HTTP `/detail` endpoint requires authentication (`serialNumber` + `checkCode` via `FNetCode`). During discovery and the first connection attempt — before a check code has been entered — there are no credentials, so `pid` cannot be read from `/detail`. The library bridges this with TCP:
+
+1. `PrinterDiscovery` (UDP) returns the USB-style PID in the broadcast packet and maps it to a `PrinterModel`. Consumers can pre-select a model class before pairing.
+2. After a check code is provided, `FiveMClient.initialize()` runs an authenticated `/detail` call alongside an unauthenticated TCP `M115` via `tcpClient.getPrinterInfo()`. M115 returns `TypeName` (firmware-controlled, e.g. `"FlashForge Adventurer 5M Pro"`) which is safe to substring-match; do NOT use M115's `Name` field for capability inference — like `detail.name` it is user-set.
+3. Once `verifyConnection()` finishes, `FFMachineInfo.Pid` / `IsPro` / `IsAD5X` are authoritative. All later capability gating should read those, not re-parse strings.
+
 ### Network Layer
 
 - `NetworkUtils` (`src/api/network/NetworkUtils.ts`) — Response validation helpers; checks `GenericResponse.code` for success.
@@ -56,6 +68,16 @@ Located in `src/tcpapi/replays/`, each parser has a `fromReplay(response)` metho
 
 The AD5X (Adventurer 5X) extends the 5M API with Intelligent Filament Station (IFS) support. Key types: `AD5XMaterialMapping`, `AD5XLocalJobParams`, `AD5XSingleColorJobParams`, `AD5XUploadParams`, `MatlStationInfo`, `SlotInfo` — all in `src/models/ff-models.ts`.
 
+### Creator 5 / Creator 5 Pro Support
+
+The Creator 5 series is "AD5X + per-tool temps". It shares the 4-slot material station and reuses the AD5X upload path, but **material matching happens at print-start** (`POST /printGcode`) rather than at upload time. Use `startCreator5Job(Creator5JobParams)` — its `materialMappings` are the 3-field `Creator5MaterialMapping` (`toolId` 0-based, `slotId` 1-based, `materialName`; no colors). Per-tool temps are in `FFMachineInfo.ToolTemps[]` (single-nozzle models report a 1-element array). Capability flags: `IsCreator5Pro`, `HasCamera`, `HasLidar`, `HasDoorSensor` (Pro only — plain C5 `doorStatus` is cosmetic). Filtration is force-enabled by model for the C5 Pro in `FiveMClient.sendProductCommand` because its `/product` under-reports the fan states.
+
+## Architecture Note — Organization Axis (future cleanup, NOT urgent)
+
+This library is intentionally organized **by concern** (`Control` / `JobControl` / `Info` / `Files` / `TempControl` / discovery / TCP), exposing a **single `FiveMClient` facade** — not by printer model the way FFUI splits into per-model backends (`AD5XBackend`, `Creator5Backend`, …). That asymmetry is **correct on purpose**: a transport library wins with one capability-based entry point; per-printer *client subclasses* would force a breaking API change and a migration across every consumer (FFUI, FFWebUI) to make the library *worse* to use. **Do not refactor this into per-printer clients.**
+
+The one real smell is that model-specific job logic is accumulating inline in `JobControl.ts` (AD5X + Creator 5). If/when it gets unwieldy, the **non-breaking** fix is to extract per-model job modules *behind the same facade* (e.g. `api/controls/jobs/ad5x.ts`, `api/controls/jobs/creator5.ts`, composed by `JobControl`) — same for `MachineInfo.fromDetail` if model branching grows there. This is optional polish with zero consumer breakage; defer it until it actually hurts, and never bundle it with feature work.
+
 ## Key Conventions
 
 - All public exports go through `src/index.ts`

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghosttypes/ff-api",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "FlashForge 3D Printer API for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/api/controls/JobControl.test.ts

@@ -475,4 +475,78 @@ describe('JobControl', () => {
       expect(result).toBe(false);
     });
   });
+
+  describe('startCreator5Job', () => {
+    beforeEach(() => {
+      // Creator 5 printer
+      (mockFiveMClient as { isCreator5: boolean }).isCreator5 = true;
+    });
+
+    it('POSTs the Creator 5-native /printGcode body with 3-field mappings', async () => {
+      mockedAxios.post.mockResolvedValue({ status: 200, data: { code: 0, message: 'Success' } });
+
+      const result = await jobControl.startCreator5Job({
+        fileName: 'multi.3mf',
+        levelingBeforePrint: true,
+        materialMappings: [
+          { toolId: 0, slotId: 1, materialName: 'PLA' },
+          { toolId: 1, slotId: 3, materialName: 'PETG' },
+        ],
+      });
+
+      expect(result).toBe(true);
+      expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+      const [url, body] = mockedAxios.post.mock.calls[0];
+      expect(url).toBe(`http://printer:8898${Endpoints.GCodePrint}`);
+      // Only Creator 5 fields — no AD5X-only useMatlStation/gcodeToolCnt/colors.
+      expect(body).toEqual({
+        serialNumber: 'SN123456',
+        checkCode: 'CC123456',
+        fileName: 'multi.3mf',
+        levelingBeforePrint: true,
+        materialMappings: [
+          { toolId: 0, slotId: 1, materialName: 'PLA' },
+          { toolId: 1, slotId: 3, materialName: 'PETG' },
+        ],
+      });
+      expect(body).not.toHaveProperty('useMatlStation');
+      expect(body).not.toHaveProperty('gcodeToolCnt');
+    });
+
+    it('omits materialMappings for a single-tool print', async () => {
+      mockedAxios.post.mockResolvedValue({ status: 200, data: { code: 0, message: 'Success' } });
+
+      const result = await jobControl.startCreator5Job({
+        fileName: 'single.gcode',
+        levelingBeforePrint: false,
+      });
+
+      expect(result).toBe(true);
+      const [, body] = mockedAxios.post.mock.calls[0];
+      expect(body).not.toHaveProperty('materialMappings');
+    });
+
+    it('rejects an invalid slotId (must be 1-4) without calling the printer', async () => {
+      const result = await jobControl.startCreator5Job({
+        fileName: 'bad.3mf',
+        levelingBeforePrint: true,
+        materialMappings: [{ toolId: 0, slotId: 0, materialName: 'PLA' }],
+      });
+
+      expect(result).toBe(false);
+      expect(mockedAxios.post).not.toHaveBeenCalled();
+    });
+
+    it('refuses to run on a non-material-station printer', async () => {
+      (mockFiveMClient as { isCreator5: boolean }).isCreator5 = false;
+
+      const result = await jobControl.startCreator5Job({
+        fileName: 'x.gcode',
+        levelingBeforePrint: true,
+      });
+
+      expect(result).toBe(false);
+      expect(mockedAxios.post).not.toHaveBeenCalled();
+    });
+  });
 });

src/api/controls/JobControl.ts

@@ -14,6 +14,8 @@ import type {
   AD5XMaterialMapping,
   AD5XSingleColorJobParams,
   AD5XUploadParams,
+  Creator5JobParams,
+  Creator5MaterialMapping,
 } from '../../models/ff-models';
 import { NetworkUtils } from '../network/NetworkUtils';
 import { Endpoints } from '../server/Endpoints';
@@ -498,39 +500,119 @@ export class JobControl {
     }
   }
 
-  // --- Model-neutral material-station aliases ---
-  // The Creator 5 series shares the AD5X material-mapping print flow, so these
-  // delegate to the AD5X implementations. Prefer these names in model-agnostic
-  // code (e.g. a Creator5 backend) so call sites aren't misleadingly "AD5X".
+  // --- Creator 5 / Creator 5 Pro ---
+  // The Creator 5 uploads files the same way as the AD5X (the extra IFS headers
+  // are simply ignored by its firmware), but it performs material matching at
+  // print-start via POST /printGcode rather than at upload time. So upload reuses
+  // the AD5X path, while starting a job uses the Creator 5-native body below.
 
   /**
-   * Uploads a file with material-station mappings (AD5X / Creator 5 series).
-   * @param params Upload parameters including material mappings.
+   * Uploads a file to a Creator 5 / Creator 5 Pro. Reuses the AD5X upload path;
+   * the Creator 5 firmware ignores the IFS-specific headers. To run a multi-tool
+   * print, upload with `startPrint = false`, then call {@link startCreator5Job}
+   * with material mappings.
+   * @param params Upload parameters (material mappings are ignored by the C5 firmware).
    * @returns Promise resolving to true on success.
    */
   public async uploadFileWithMaterialMappings(params: AD5XUploadParams): Promise<boolean> {
     return this.uploadFileAD5X(params);
   }
 
   /**
-   * Starts a multi-color local job using material-station mappings (AD5X / Creator 5 series).
-   * @param params Job parameters including material mappings.
-   * @returns Promise resolving to true on success.
+   * Starts a local print on a Creator 5 / Creator 5 Pro via `POST /printGcode`.
+   *
+   * This is the Creator 5's print-start material-matching command (distinct from
+   * the AD5X, which maps materials at upload time). The file must already be on the
+   * printer. Provide `materialMappings` for a multi-tool print, or omit them for a
+   * single-tool print. Sends only the fields the Creator 5 firmware reads.
+   *
+   * @param params File name, leveling flag, and optional flags / material mappings.
+   * @returns Promise resolving to true if the printer accepts the print command.
+   * @throws Error if there's a network issue sending the command.
    */
-  public async startMaterialMappingJob(params: AD5XLocalJobParams): Promise<boolean> {
-    return this.startAD5XMultiColorJob(params);
+  public async startCreator5Job(params: Creator5JobParams): Promise<boolean> {
+    if (!this.validateMaterialStationPrinter()) {
+      return false;
+    }
+
+    if (!params.fileName || params.fileName.trim() === '') {
+      console.error('Creator 5 Job error: fileName cannot be empty');
+      return false;
+    }
+
+    const hasMappings = !!params.materialMappings && params.materialMappings.length > 0;
+    if (hasMappings && !this.validateCreator5MaterialMappings(params.materialMappings ?? [])) {
+      return false;
+    }
+
+    // Only the fields the /printGcode handler actually reads. fileName and
+    // levelingBeforePrint are required; the rest are optional.
+    const payload: Record<string, unknown> = {
+      serialNumber: this.client.serialNumber,
+      checkCode: this.client.checkCode,
+      fileName: params.fileName,
+      levelingBeforePrint: params.levelingBeforePrint,
+    };
+    if (params.flowCalibration !== undefined) payload.flowCalibration = params.flowCalibration;
+    if (params.timeLapseVideo !== undefined) payload.timeLapseVideo = params.timeLapseVideo;
+    if (hasMappings) payload.materialMappings = params.materialMappings;
+
+    try {
+      const response = await axios.post(this.client.getEndpoint(Endpoints.GCodePrint), payload, {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+      });
+
+      if (response.status !== 200) return false;
+
+      const result = response.data as GenericResponse;
+      return NetworkUtils.isOk(result);
+    } catch (error) {
+      console.error(`Creator 5 Job error: ${(error as Error).message}`);
+      throw error;
+    }
   }
 
   /**
-   * Starts a single-color local job on a material-station printer without using the
-   * station (AD5X / Creator 5 series).
-   * @param params Job parameters.
-   * @returns Promise resolving to true on success.
+   * Validates Creator 5 material mappings: toolId 0-3, slotId 1-4, non-empty
+   * materialName. (No color fields, unlike AD5X.)
+   * @param materialMappings Array of Creator 5 mappings to validate.
+   * @returns True if all mappings are valid, false otherwise.
+   * @private
    */
-  public async startSingleColorMaterialStationJob(
-    params: AD5XSingleColorJobParams
-  ): Promise<boolean> {
-    return this.startAD5XSingleColorJob(params);
+  private validateCreator5MaterialMappings(materialMappings: Creator5MaterialMapping[]): boolean {
+    if (materialMappings.length > 4) {
+      console.error('Creator 5 material mappings error: Maximum 4 material mappings allowed');
+      return false;
+    }
+
+    for (let i = 0; i < materialMappings.length; i++) {
+      const mapping = materialMappings[i];
+
+      if (mapping.toolId < 0 || mapping.toolId > 3) {
+        console.error(
+          `Creator 5 material mappings error: toolId must be between 0-3, got ${mapping.toolId} at index ${i}`
+        );
+        return false;
+      }
+
+      if (mapping.slotId < 1 || mapping.slotId > 4) {
+        console.error(
+          `Creator 5 material mappings error: slotId must be between 1-4, got ${mapping.slotId} at index ${i}`
+        );
+        return false;
+      }
+
+      if (!mapping.materialName || mapping.materialName.trim() === '') {
+        console.error(
+          `Creator 5 material mappings error: materialName cannot be empty at index ${i}`
+        );
+        return false;
+      }
+    }
+
+    return true;
   }
 
   /**

src/index.ts

@@ -43,6 +43,8 @@ export {
   AD5XMaterialMapping,
   AD5XSingleColorJobParams,
   AD5XUploadParams,
+  Creator5JobParams,
+  Creator5MaterialMapping,
   FFGcodeFileEntry,
   FFGcodeToolData,
   FFMachineInfo,

src/models/ff-models.ts

@@ -458,6 +458,42 @@ export interface AD5XSingleColorJobParams {
   levelingBeforePrint: boolean;
 }
 
+/**
+ * Material mapping for a Creator 5 / Creator 5 Pro multi-tool print.
+ *
+ * Unlike {@link AD5XMaterialMapping}, the Creator 5 performs material matching at
+ * print-start (`POST /printGcode`) and its mapping carries only three fields — no
+ * tool/slot colors. The firmware stores `toolId + 1` internally.
+ */
+export interface Creator5MaterialMapping {
+  /** Gcode tool / extruder index, 0-based (T0–T3). */
+  toolId: number;
+  /** Physical material-station slot to source from, 1-based (1–4). */
+  slotId: number;
+  /** Material name (e.g. "PLA"). */
+  materialName: string;
+}
+
+/**
+ * Parameters for starting a local print on a Creator 5 / Creator 5 Pro via
+ * `POST /printGcode`. The file must already be on the printer (upload first).
+ *
+ * For a single-tool print, omit `materialMappings`. For a multi-tool print, map
+ * each gcode tool to a slot + material.
+ */
+export interface Creator5JobParams {
+  /** Name of the file already stored on the printer. */
+  fileName: string;
+  /** Whether to bed-level before printing (required by the firmware). */
+  levelingBeforePrint: boolean;
+  /** Optional: enable flow calibration. */
+  flowCalibration?: boolean;
+  /** Optional: record a time-lapse video. */
+  timeLapseVideo?: boolean;
+  /** Optional per-tool material mappings (1–4). Omit for a single-tool print. */
+  materialMappings?: Creator5MaterialMapping[];
+}
+
 /**
  * Parameters for uploading a file to AD5X printer with material station support.
  * Extends basic upload functionality with AD5X-specific features like material mappings,