feat(creator5): add Creator 5 / 5 Pro detail, capabilities, and material-station support

Extend the modern client to support the Creator 5 series, which is
functionally "AD5X + per-tool temps". All additions are backwards-compatible
and null-safe so existing 5M/AD5X parsing is unaffected.

- FFPrinterDetail: add camera, lidar, model, nozzleTemps[], nozzleTargetTemps[].
- FFMachineInfo: add IsCreator5Pro, Model, HasCamera, HasLidar, HasDoorSensor,
  ToolTemps[] (single-nozzle models report a 1-element array).
- MachineInfo.fromDetail: build ToolTemps with single-extruder fallback; derive
  capabilities by presence (HasDoorSensor only on Creator 5 Pro, since plain C5
  has no real door sensor); Model resolves model -> PID name -> name.
- FiveMClient: optional Product fields; ProductCapabilities + deriveCapabilities
  (1 = available); force-enable filtration on Creator 5 Pro (its /product
  under-reports the fans despite having the hardware); cache tool temps + caps.
- JobControl: generalize the AD5X material-station guard to also accept Creator 5
  and add model-neutral aliases (uploadFileWithMaterialMappings,
  startMaterialMappingJob, startSingleColorMaterialStationJob).

Bump to 1.3.3.

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

Author: GhostTypes

package.json

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

src/FiveMClient.test.ts

@@ -131,4 +131,54 @@ describe('FiveMClient', () => {
     expect(httpGet).toHaveBeenCalledTimes(1);
     expect(destroy).toHaveBeenCalledTimes(1);
   });
+
+  describe('deriveCapabilities', () => {
+    it('maps 1=available control states to capability flags', () => {
+      const caps = FiveMClient.deriveCapabilities({
+        chamberTempCtrlState: 1,
+        externalFanCtrlState: 1,
+        internalFanCtrlState: 1,
+        lightCtrlState: 1,
+        nozzleTempCtrlState: 1,
+        platformTempCtrlState: 1,
+      });
+
+      expect(caps).toEqual({
+        hasLed: true,
+        hasFiltration: true,
+        hasChamberControl: true,
+        hasNozzleControl: true,
+        hasPlatformControl: true,
+      });
+    });
+
+    it('requires BOTH fans for filtration (Creator 5 Pro reports 0/0)', () => {
+      // Live C5 Pro /product: light + chamber + nozzle + platform available,
+      // but internal/external fans reported 0 -> filtration must be false here.
+      const caps = FiveMClient.deriveCapabilities({
+        chamberTempCtrlState: 1,
+        externalFanCtrlState: 0,
+        internalFanCtrlState: 0,
+        lightCtrlState: 1,
+        nozzleTempCtrlState: 1,
+        platformTempCtrlState: 1,
+      });
+
+      expect(caps.hasFiltration).toBe(false);
+      expect(caps.hasLed).toBe(true);
+      expect(caps.hasChamberControl).toBe(true);
+    });
+
+    it('treats missing control states as not-available', () => {
+      const caps = FiveMClient.deriveCapabilities({});
+
+      expect(caps).toEqual({
+        hasLed: false,
+        hasFiltration: false,
+        hasChamberControl: false,
+        hasNozzleControl: false,
+        hasPlatformControl: false,
+      });
+    });
+  });
 });

src/FiveMClient.ts

@@ -10,7 +10,7 @@ import { JobControl } from './api/controls/JobControl';
 import { TempControl } from './api/controls/TempControl';
 import { NetworkUtils } from './api/network/NetworkUtils';
 import { Endpoints } from './api/server/Endpoints';
-import type { FFMachineInfo } from './models/ff-models';
+import type { FFMachineInfo, Temperature } from './models/ff-models';
 import { MachineInfo } from './models/MachineInfo';
 import { FlashForgeClient } from './tcpapi/FlashForgeClient';
 
@@ -58,10 +58,23 @@ export class FiveMClient {
   public isPro: boolean = false;
   public isAD5X: boolean = false;
   public isCreator5: boolean = false;
+  public isCreator5Pro: boolean = false;
+  /** Immutable factory model name (e.g. "Creator 5 Pro"); not user-editable. */
+  public model: string = '';
   public firmwareVersion: string = '';
   public firmVer: string = '';
   public cameraStreamUrl: string = '';
 
+  // Hardware capability flags (presence-derived, see MachineInfo.fromDetail).
+  /** Whether the printer has a built-in camera. */
+  public hasCamera: boolean = false;
+  /** Whether the printer has a lidar/first-layer scanner. */
+  public hasLidar: boolean = false;
+  /** Whether the printer has a real door sensor (only then is door status meaningful). */
+  public hasDoorSensor: boolean = false;
+  /** Current/target temperatures for every tool/nozzle (1 entry for single-nozzle models). */
+  public toolTemps: Temperature[] = [];
+
   public ipAddress: string;
   public macAddress: string = '';
 
@@ -78,6 +91,14 @@ export class FiveMClient {
   public filtrationControl: boolean = false;
   /** Raw product info containing all control states */
   public productInfo: Product | null = null;
+  /** Capabilities derived from the /product control states (1 = available). */
+  public capabilities: ProductCapabilities = {
+    hasLed: false,
+    hasFiltration: false,
+    hasChamberControl: false,
+    hasNozzleControl: false,
+    hasPlatformControl: false,
+  };
 
   /**
    * Creates an instance of FiveMClient.
@@ -201,6 +222,12 @@ export class FiveMClient {
     this.isPro = info.IsPro; // Use the value from MachineInfo
     this.isAD5X = info.IsAD5X; // Cache the AD5X status
     this.isCreator5 = info.IsCreator5; // Cache the Creator 5 status
+    this.isCreator5Pro = info.IsCreator5Pro; // Cache the Creator 5 Pro status
+    this.model = info.Model || '';
+    this.hasCamera = info.HasCamera;
+    this.hasLidar = info.HasLidar;
+    this.hasDoorSensor = info.HasDoorSensor;
+    this.toolTemps = info.ToolTemps || [];
     this.firmwareVersion = info.FirmwareVersion || '';
     this.firmVer = info.FirmwareVersion ? info.FirmwareVersion.split('-')[0] : '';
     this.cameraStreamUrl = info.CameraStreamUrl || '';
@@ -318,6 +345,31 @@ export class FiveMClient {
     }
   }
 
+  /**
+   * Derives capability flags from a /product response. Polarity is
+   * `1 = available, 0 = not available`; any missing field is treated as 0.
+   *
+   * NOTE: `hasFiltration` requires BOTH internal and external fan controls to be
+   * available, matching the 5M Pro charcoal-filtration behavior. This is a pure
+   * read of what /product advertises. The Creator 5 Pro under-reports it (both
+   * fans 0 despite having the hardware), so its filtration is force-enabled by
+   * model in `sendProductCommand` rather than here.
+   *
+   * @param product Raw (possibly sparse) product control-state object.
+   * @returns Derived {@link ProductCapabilities}.
+   */
+  public static deriveCapabilities(product: Partial<Product>): ProductCapabilities {
+    const avail = (v: number | undefined): boolean => v === 1;
+    return {
+      hasLed: avail(product.lightCtrlState),
+      hasFiltration:
+        avail(product.internalFanCtrlState) && avail(product.externalFanCtrlState),
+      hasChamberControl: avail(product.chamberTempCtrlState),
+      hasNozzleControl: avail(product.nozzleTempCtrlState),
+      hasPlatformControl: avail(product.platformTempCtrlState),
+    };
+  }
+
   /**
    * Sends a product command to the printer to retrieve control states.
    * This method sets the `httpClientBusy` flag while the request is in progress.
@@ -341,13 +393,20 @@ export class FiveMClient {
       try {
         const productResponse = response.data as ProductResponse;
         if (productResponse && NetworkUtils.isOk(productResponse)) {
-          // Parse & set control states
-          const product = productResponse.product;
+          // Parse & set control states. /product polarity is 1 = available,
+          // 0 = not available. Fields may be absent on some models, so default
+          // missing values to 0 (treat as not-available) rather than assume.
+          const product = productResponse.product ?? {};
           this.productInfo = product; // Store raw product data
-          this.ledControl = product.lightCtrlState !== 0;
-          this.filtrationControl = !(
-            product.internalFanCtrlState === 0 || product.externalFanCtrlState === 0
-          );
+          this.capabilities = FiveMClient.deriveCapabilities(product);
+          // Creator 5 Pro has 5M-Pro-style filtration/aux fan per FlashForge
+          // specs, but its /product under-reports it (both fan states 0), so
+          // enable by model. The 5M Pro advertises it correctly and needs no
+          // override. isCreator5Pro is already set here (verifyConnection ->
+          // cacheDetails runs before initControl -> sendProductCommand).
+          if (this.isCreator5Pro) this.capabilities.hasFiltration = true;
+          this.ledControl = this.capabilities.hasLed;
+          this.filtrationControl = this.capabilities.hasFiltration;
           //console.log("LedControl: " + this.ledControl);
           //console.log("FiltrationControl: " + this.filtrationControl);
           return true;
@@ -388,16 +447,33 @@ interface ProductResponse extends GenericResponse {
  * while other numbers (typically 1) mean on/available or a specific mode.
  */
 export interface Product {
-  /** State of the chamber temperature control. */
-  chamberTempCtrlState: number;
-  /** State of the external fan control. */
-  externalFanCtrlState: number;
-  /** State of the internal fan control. */
-  internalFanCtrlState: number;
-  /** State of the light control. */
-  lightCtrlState: number;
-  /** State of the nozzle temperature control. */
-  nozzleTempCtrlState: number;
-  /** State of the platform (bed) temperature control. */
-  platformTempCtrlState: number;
+  /** State of the chamber temperature control (1 = available). */
+  chamberTempCtrlState?: number;
+  /** State of the external fan control (1 = available). */
+  externalFanCtrlState?: number;
+  /** State of the internal fan control (1 = available). */
+  internalFanCtrlState?: number;
+  /** State of the light control (1 = available). */
+  lightCtrlState?: number;
+  /** State of the nozzle temperature control (1 = available). */
+  nozzleTempCtrlState?: number;
+  /** State of the platform (bed) temperature control (1 = available). */
+  platformTempCtrlState?: number;
+}
+
+/**
+ * Capability flags derived from a printer's /product control states.
+ * Each is true only when the corresponding control is reported as available.
+ */
+export interface ProductCapabilities {
+  /** LED light control is available. */
+  hasLed: boolean;
+  /** Air-filtration control (both internal and external fans) is available. */
+  hasFiltration: boolean;
+  /** Chamber temperature control is available. */
+  hasChamberControl: boolean;
+  /** Nozzle temperature control is available. */
+  hasNozzleControl: boolean;
+  /** Platform (bed) temperature control is available. */
+  hasPlatformControl: boolean;
 }

src/api/controls/JobControl.ts

@@ -227,7 +227,7 @@ export class JobControl {
    */
   public async uploadFileAD5X(params: AD5XUploadParams): Promise<boolean> {
     // Validate that this is an AD5X printer
-    if (!this.validateAD5XPrinter()) {
+    if (!this.validateMaterialStationPrinter()) {
       return false;
     }
 
@@ -400,7 +400,7 @@ export class JobControl {
    */
   public async startAD5XMultiColorJob(params: AD5XLocalJobParams): Promise<boolean> {
     // Validate that this is an AD5X printer
-    if (!this.validateAD5XPrinter()) {
+    if (!this.validateMaterialStationPrinter()) {
       return false;
     }
 
@@ -457,7 +457,7 @@ export class JobControl {
    */
   public async startAD5XSingleColorJob(params: AD5XSingleColorJobParams): Promise<boolean> {
     // Validate that this is an AD5X printer
-    if (!this.validateAD5XPrinter()) {
+    if (!this.validateMaterialStationPrinter()) {
       return false;
     }
 
@@ -498,14 +498,53 @@ 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".
+
+  /**
+   * Uploads a file with material-station mappings (AD5X / Creator 5 series).
+   * @param params Upload parameters including material mappings.
+   * @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.
+   */
+  public async startMaterialMappingJob(params: AD5XLocalJobParams): Promise<boolean> {
+    return this.startAD5XMultiColorJob(params);
+  }
+
+  /**
+   * 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.
+   */
+  public async startSingleColorMaterialStationJob(
+    params: AD5XSingleColorJobParams
+  ): Promise<boolean> {
+    return this.startAD5XSingleColorJob(params);
+  }
+
   /**
-   * Validates that the current printer is an AD5X model.
-   * @returns True if the printer is AD5X, false otherwise
+   * Validates that the current printer has a material station and therefore
+   * supports material-mapping uploads/jobs. Covers AD5X and the Creator 5 series,
+   * which share the same material-mapping print flow (Creator 5 = "AD5X + more").
+   * @returns True if the printer supports material mappings, false otherwise
    * @private
    */
-  private validateAD5XPrinter(): boolean {
-    if (!this.client.isAD5X) {
-      console.error('AD5X Job error: This method can only be used with AD5X printers');
+  private validateMaterialStationPrinter(): boolean {
+    if (!this.client.isAD5X && !this.client.isCreator5) {
+      console.error(
+        'Material-station job error: this method requires an AD5X or Creator 5 series printer'
+      );
       return false;
     }
     return true;

src/index.ts

@@ -31,7 +31,12 @@ export {
 // Server constants
 export { Commands } from './api/server/Commands';
 export { Endpoints } from './api/server/Endpoints';
-export { FiveMClient, type FiveMClientConnectionOptions, Product } from './FiveMClient';
+export {
+  FiveMClient,
+  type FiveMClientConnectionOptions,
+  Product,
+  type ProductCapabilities,
+} from './FiveMClient';
 // Models
 export {
   AD5XLocalJobParams,