feat: add camera stream detection fallback

Author: GhostTypes

CHANGELOG.md

@@ -7,9 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-03-21
+
 ### Added
 
-- `FlashForgeA4Client` — dedicated Adventurer 4 Lite / Pro TCP client aligned with the documented M601 and M115 behavior
+- `Endpoints.CAMERA_STREAM_PORT` - exported constant for the known FlashForge OEM MJPEG stream port
+- `FiveMClient.detectCameraStream()` - probes `http://<printer-ip>:8080/?action=stream` and falls back from `HEAD` to `GET` when firmware does not report `cameraStreamUrl`
+- Vitest coverage for camera stream probing success, `HEAD` timeout fallback, and no-camera behavior
+- `FlashForgeA4Client` - dedicated Adventurer 4 Lite / Pro TCP client aligned with the documented M601 and M115 behavior
 - `A4BuildVolume`, `A4FileEntry`, `A4PrinterInfo`, and `A4PrinterVariant` types for typed Adventurer 4 responses
 
 ### Changed
@@ -21,7 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `FiveMClient.cameraStreamUrl` — caches the OEM camera stream URL reported by the printer in machine-info responses, cleared on dispose
+- `FiveMClient.cameraStreamUrl` — caches the OEM camera stream URL reported by the printer in machine-info responses, cleared on dispose
 
 ### Changed
 
@@ -31,17 +36,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `FlashForgeA3Client` — full Adventurer 3 TCP client aligned with the documented G-code protocol, exported from the package root
-- `A3GCodeController` — A3-specific G-code command controller with a dedicated instruction set
+- `FlashForgeA3Client` — full Adventurer 3 TCP client aligned with the documented G-code protocol, exported from the package root
+- `A3GCodeController` — A3-specific G-code command controller with a dedicated instruction set
 - `A3BuildVolume`, `A3FileEntry`, `A3PrinterInfo`, `A3Thumbnail` types for typed Adventurer 3 responses
 - `GCodeClientCapabilities` interface for capability-based client selection across printer generations
 - `PrinterModel`, `DiscoveryProtocol`, `PrinterStatus` enums providing fully-typed discovery results
 - `DiscoveredPrinter` and `DiscoveryOptions` TypeScript interfaces replacing loosely-typed discovery objects
-- `DiscoveryErrors` — custom error class hierarchy for structured discovery error handling
+- `DiscoveryErrors` — custom error class hierarchy for structured discovery error handling
 - PID-based legacy model fallback in `PrinterDiscovery`: known USB product IDs (`0x0008` Adventurer 3, `0x001e` Adventurer 4 Pro) are used as a secondary hint when name heuristics are inconclusive
-- `FlashForgeTcpClient.uploadFile()` — M28 / raw-binary / M29 file upload flow for legacy printers, with automatic filename normalization
-- `FiveMClientConnectionOptions` — optional HTTP port and TCP port overrides for `FiveMClient` construction
-- `FlashForgeTcpClientOptions` — optional TCP port override for `FlashForgeTcpClient` construction
+- `FlashForgeTcpClient.uploadFile()` — M28 / raw-binary / M29 file upload flow for legacy printers, with automatic filename normalization
+- `FiveMClientConnectionOptions` — optional HTTP port and TCP port overrides for `FiveMClient` construction
+- `FlashForgeTcpClientOptions` — optional TCP port override for `FlashForgeTcpClient` construction
 - Vitest test suite with unit coverage for discovery, client lifecycle, and response parsers
 - Biome linter and formatter configuration
 
@@ -66,17 +71,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `FiveMClient` — modern HTTP/JSON API client for Adventurer 5M and Adventurer 5M Pro
-- `FlashForgeClient` / `FlashForgeTcpClient` — legacy TCP G-code client base
-- `FlashForgePrinterDiscovery` — UDP multicast and broadcast discovery covering all FlashForge models
-- `Control`, `Files`, `Info`, `JobControl`, `TempControl` — modern API action classes for printer control
-- `Filament` — filament data accessor for modern printers
-- `GCodeController` — G-code command controller for legacy TCP printers
-- `GCodes`, `Commands`, `Endpoints` — G-code and HTTP API constant tables
-- `EndstopStatus`, `LocationInfo`, `PrintStatus`, `TempInfo`, `ThumbnailInfo` — TCP response parsers and models
-- `MachineInfo` — unified machine state model with AD5X material station support
-- `FNetCode`, `NetworkUtils` — network response code constants and HTTP utility helpers
-- `FFMachineInfo`, `FFPrinterDetail`, `MatlStationInfo`, `SlotInfo` — typed models for printer detail responses
+- `FiveMClient` — modern HTTP/JSON API client for Adventurer 5M and Adventurer 5M Pro
+- `FlashForgeClient` / `FlashForgeTcpClient` — legacy TCP G-code client base
+- `FlashForgePrinterDiscovery` — UDP multicast and broadcast discovery covering all FlashForge models
+- `Control`, `Files`, `Info`, `JobControl`, `TempControl` — modern API action classes for printer control
+- `Filament` — filament data accessor for modern printers
+- `GCodeController` — G-code command controller for legacy TCP printers
+- `GCodes`, `Commands`, `Endpoints` — G-code and HTTP API constant tables
+- `EndstopStatus`, `LocationInfo`, `PrintStatus`, `TempInfo`, `ThumbnailInfo` — TCP response parsers and models
+- `MachineInfo` — unified machine state model with AD5X material station support
+- `FNetCode`, `NetworkUtils` — network response code constants and HTTP utility helpers
+- `FFMachineInfo`, `FFPrinterDetail`, `MatlStationInfo`, `SlotInfo` — typed models for printer detail responses
 - AD5X material station support: `AD5XLocalJobParams`, `AD5XSingleColorJobParams`, `AD5XUploadParams`, `AD5XMaterialMapping`
 - `Product` enum for modern printer model identification
 - LED control for legacy TCP clients
@@ -85,14 +90,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- Homing command (`G28`) incorrectly triggering a short timeout — extended to 15 s
+- Homing command (`G28`) incorrectly triggering a short timeout — extended to 15 s
 - M661 local file list response parsing rewritten to handle varied firmware delimiter patterns
 - `Commands` / `Endpoints` constant lookup inconsistencies on initial port
 - `FlashForgeTcpClient` shutdown race condition
 - AD5X job info parsing returning incomplete data
 - `NetworkUtils.isOk` usage corrected across response handlers
 
-[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-ts/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-ts/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/GhostTypes/ff-5mp-api-ts/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/GhostTypes/ff-5mp-api-ts/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/GhostTypes/ff-5mp-api-ts/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/GhostTypes/ff-5mp-api-ts/releases/tag/v1.0.0

package.json

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

src/FiveMClient.test.ts

@@ -11,6 +11,10 @@ const { flashForgeClientConstructor, axiosCreate } = vi.hoisted(() => ({
   axiosCreate: vi.fn(),
 }));
 
+const httpPost = vi.fn();
+const httpHead = vi.fn();
+const httpGet = vi.fn();
+
 vi.mock('./tcpapi/FlashForgeClient', () => ({
   FlashForgeClient: flashForgeClientConstructor,
 }));
@@ -32,7 +36,9 @@ describe('FiveMClient', () => {
       };
     });
     axiosCreate.mockReturnValue({
-      post: vi.fn(),
+      post: httpPost,
+      head: httpHead,
+      get: httpGet,
     });
   });
 
@@ -71,4 +77,58 @@ describe('FiveMClient', () => {
     expect(client.cacheDetails(machineInfo)).toBe(true);
     expect(client.cameraStreamUrl).toBe('http://192.168.1.10:8080/?action=stream');
   });
+
+  it('detects the OEM camera stream from a successful HEAD probe', async () => {
+    const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1');
+
+    httpHead.mockResolvedValue({
+      status: 200,
+      headers: {
+        'content-type': 'multipart/x-mixed-replace; boundary=frame',
+      },
+    });
+
+    await expect(client.detectCameraStream()).resolves.toBe('http://192.168.1.10:8080/?action=stream');
+    expect(httpHead).toHaveBeenCalledTimes(1);
+    expect(httpGet).not.toHaveBeenCalled();
+  });
+
+  it('falls back to GET when HEAD does not detect a stream', async () => {
+    const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1');
+    const destroy = vi.fn();
+
+    httpHead.mockResolvedValue({
+      status: 405,
+      headers: {},
+    });
+    httpGet.mockResolvedValue({
+      status: 200,
+      headers: {},
+      data: { destroy },
+    });
+
+    await expect(client.detectCameraStream()).resolves.toBe('http://192.168.1.10:8080/?action=stream');
+    expect(httpHead).toHaveBeenCalledTimes(1);
+    expect(httpGet).toHaveBeenCalledTimes(1);
+    expect(destroy).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns an empty string when neither probe method finds a camera stream', async () => {
+    const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1');
+    const destroy = vi.fn();
+
+    httpHead.mockRejectedValue(new Error('timeout'));
+    httpGet.mockResolvedValue({
+      status: 404,
+      headers: {
+        'content-type': 'text/html',
+      },
+      data: { destroy },
+    });
+
+    await expect(client.detectCameraStream()).resolves.toBe('');
+    expect(httpHead).toHaveBeenCalledTimes(1);
+    expect(httpGet).toHaveBeenCalledTimes(1);
+    expect(destroy).toHaveBeenCalledTimes(1);
+  });
 });

src/FiveMClient.ts

@@ -166,6 +166,27 @@ export class FiveMClient {
     await this.tcpClient.dispose();
   }
 
+  /**
+   * Probes the printer's known OEM camera endpoint.
+   * Falls back to a short GET when HEAD is unsupported so MJPEG servers
+   * that reject HEAD requests are still detected.
+   * @param timeoutMs Timeout for each probe attempt in milliseconds.
+   * @returns The working camera stream URL, or an empty string if not detected.
+   */
+  public async detectCameraStream(timeoutMs: number = 3000): Promise<string> {
+    const probeUrl = `http://${this.ipAddress}:${Endpoints.CAMERA_STREAM_PORT}/?action=stream`;
+
+    if (await this.probeCameraStreamWithHead(probeUrl, timeoutMs)) {
+      return probeUrl;
+    }
+
+    if (await this.probeCameraStreamWithGet(probeUrl, timeoutMs)) {
+      return probeUrl;
+    }
+
+    return '';
+  }
+
   /**
    * Caches machine details from the provided FFMachineInfo object.
    * @param info The FFMachineInfo object containing printer details.
@@ -200,6 +221,55 @@ export class FiveMClient {
     return `http://${this.ipAddress}:${this.PORT}${endpoint}`;
   }
 
+  private async probeCameraStreamWithHead(probeUrl: string, timeoutMs: number): Promise<boolean> {
+    try {
+      const response = await this.httpClient.head(probeUrl, {
+        timeout: timeoutMs,
+        validateStatus: () => true,
+      });
+      return this.isValidCameraProbeResponse(response.status, response.headers);
+    } catch {
+      return false;
+    }
+  }
+
+  private async probeCameraStreamWithGet(probeUrl: string, timeoutMs: number): Promise<boolean> {
+    let responseData: { destroy?: () => void } | undefined;
+
+    try {
+      const response = await this.httpClient.get(probeUrl, {
+        timeout: timeoutMs,
+        responseType: 'stream',
+        validateStatus: () => true,
+      });
+      responseData =
+        response.data && typeof response.data === 'object' ? (response.data as { destroy?: () => void }) : undefined;
+      return this.isValidCameraProbeResponse(response.status, response.headers);
+    } catch {
+      return false;
+    } finally {
+      responseData?.destroy?.();
+    }
+  }
+
+  private isValidCameraProbeResponse(
+    status: number,
+    headers: Record<string, string | string[] | undefined>
+  ): boolean {
+    if (status !== 200) {
+      return false;
+    }
+
+    const rawContentType = headers['content-type'];
+    const contentType = (
+      Array.isArray(rawContentType) ? rawContentType.join(',') : rawContentType || ''
+    ).toLowerCase();
+
+    return (
+      contentType === '' || contentType.includes('multipart') || contentType.includes('video/x-mjpeg')
+    );
+  }
+
   /**
    * Verifies the connection to the printer by retrieving machine details and TCP information.
    * @returns A Promise that resolves to true if the connection is verified, false otherwise.

src/api/server/Endpoints.ts

@@ -11,6 +11,8 @@
  * for various API requests.
  */
 export class Endpoints {
+  /** Known OEM camera stream port exposed by FlashForge firmware. */
+  static readonly CAMERA_STREAM_PORT = 8080;
   /** Endpoint for sending control commands to the printer (e.g., light control, job control, temperature control). */
   static readonly Control = '/control';
   /** Endpoint for retrieving detailed information and status about the printer. */