@ecobridge.xyz/devicemanager 3.1.1 → 3.2.0

package/readme.md

@@ -10,8 +10,9 @@ A comprehensive, TypeScript-first device manager for discovering and communicati
 `@ecobridge.xyz/devicemanager` provides a unified, object-oriented API for discovering and modeling network devices, with live communication where protocol implementations are available. Whether you're building a document scanning workflow, managing printers, controlling smart home devices, or monitoring UPS systems — this library has you covered.
 
 **Supported Device Types:**
-- 🖨️ **Scanners** — eSCL (AirScan), SANE protocols
-- 📄 **Printers** — IPP discovery and print execution; JetDirect/raw port detection
+- 🖨️ **Scanners** — Brother native network scanning, eSCL (AirScan), and SANE
+- 📄 **Printers** — IPP/AirPrint discovery, capabilities, jobs, cancellation, and print execution; JetDirect/raw port detection
+- 📁 **SMB Shares** — Host local folders through smartsamba and emit settled document arrivals through RxJS
 - 🔊 **Speakers** — Sonos, AirPlay, Chromecast, and DLNA discovery with normalized feature/factory modeling
 - 🔋 **UPS Systems** — NUT, SNMP protocols
 - 📡 **SNMP Devices** — Community-based SNMP v1 and v2c sessions; v3 is not implemented
@@ -107,7 +108,7 @@ The library follows a clean, composable architecture:
                               ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                        Protocols                            │
-│  eSCL │ SANE │ IPP │ SNMP │ NUT │ UPnP/SOAP │ Home Assistant│
+│ Brother Scan │ eSCL │ SANE │ IPP │ SNMP │ NUT │ UPnP/SOAP  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -142,6 +143,7 @@ const printers = await manager.discoverPrinters('192.168.1.0/24');
 // General network scan (all device types)
 const devices = await manager.scanNetwork({
   ipRange: '192.168.1.0/24',
+  probeBrother: true,
   probeEscl: true,
   probeIpp: true,
   probeSane: true,
@@ -237,11 +239,38 @@ const result = await scanFeature.scan({
 
 // result.data is a Buffer containing the scanned image
 await fs.writeFile('scan.jpg', result.data);
+
+// ADF scans expose every returned document. `data` remains the first document
+// for backwards compatibility. Use `pages` to avoid dropping later sheets/sides.
+console.log(`Scanner returned ${result.pageCount} document(s)`);
+for (const [index, page] of (result.pages ?? []).entries()) {
+  await fs.writeFile(`scan-${index + 1}.jpg`, page.data);
+}
 ```
 
+If a scanner times out or cancels after transferring one or more documents,
+`EsclScanError.partialResult` contains those documents with `isComplete: false`.
+Callers can persist `partialResult.pages` before deciding whether to retry.
+Some scanner firmware accepts eSCL settings but returns a different format or
+resolution. Check `result.settingsWarnings` before treating the requested scan
+quality as confirmed.
+
+Brother devices discovered on TCP 54921 use the native scan transport before
+eSCL. It explicitly selects `AUTO` for ADF input, controls simplex/duplex, and
+rejects a lease when the device does not grant the requested resolution. The
+native transport currently returns color JPEG pages; unsupported output formats
+or color modes fail explicitly instead of being silently substituted.
+Duplex-capable scanners default to `adf-duplex`; callers can still request
+`adf` or `flatbed` explicitly. The transport preserves every returned side.
+Blank-page classification and removal belong in consuming applications, where
+document-specific review rules can be applied.
+
 #### 📄 PrintFeature
 
-`PrintFeature.print()` submits jobs through IPP. Network discovery can identify an open JetDirect/raw port at TCP 9100, but JetDirect print execution is not implemented.
+`PrintFeature.print()` submits jobs through IPP, the print transport used by
+AirPrint. It reads printer capabilities, submits jobs, reports job state, and
+supports cancellation. Network discovery can also identify an open
+JetDirect/raw port at TCP 9100, but JetDirect print execution is not implemented.
 
 ```typescript
 const printFeature = device.selectFeature<PrintFeature>('print');
@@ -249,6 +278,7 @@ await printFeature.connect();
 
 // Get printer capabilities
 const caps = await printFeature.getCapabilities();
+console.log(caps.airPrintSupported, caps.documentFormats, caps.resolutions);
 
 // Print a document
 const job = await printFeature.print(pdfBuffer, {
@@ -264,6 +294,60 @@ const job = await printFeature.print(pdfBuffer, {
 const jobInfo = await printFeature.getJobInfo(job.id);
 ```
 
+#### 📁 SMB Share Provider
+
+`DeviceManager.provideSmbShares()` hosts one or more local folders with
+`@push.rocks/smartsamba`. The provider waits until a new file has stopped
+changing before it emits `document:arrived`, which keeps consumers from opening
+a scan while the sending device is still writing it.
+
+```typescript
+import { DeviceManager } from '@ecobridge.xyz/devicemanager';
+
+const manager = new DeviceManager({ autoDiscovery: false });
+const provider = await manager.provideSmbShares({
+  host: '0.0.0.0',
+  port: 445,
+  users: [{
+    username: 'scanner',
+    password: process.env.SMB_SCANNER_PASSWORD!,
+  }],
+  shares: [{
+    name: 'scans',
+    path: '/srv/device-scans',
+    users: [{ username: 'scanner', access: 'readWrite' }],
+  }],
+  settleTimeMs: 1000,
+});
+
+const subscription = provider.documents$.subscribe((document) => {
+  console.log(`New document: ${document.shareName}/${document.relativePath}`);
+});
+
+// The same event is forwarded through the manager as smb:document:arrived.
+const managerSubscription = manager.events$.subscribe((event) => {
+  if (event.name === 'smb:document:arrived') {
+    console.log(event.args[0]);
+  }
+});
+
+// Later:
+subscription.unsubscribe();
+managerSubscription.unsubscribe();
+await manager.shutdown();
+```
+
+The provider recursively monitors every configured share. It also emits
+`document:changed`, `document:removed`, `started`, `stopped`, and
+`provider:error`. Existing files are treated as the startup baseline unless
+`emitExistingDocuments` is enabled.
+
+Binding SMB's standard TCP port 445 can require elevated privileges. Published
+smartsamba 0.3.1 packages support signed SMB 2.0.2 and 2.1 clients and include
+Linux amd64 and arm64 engines. Other platforms can provide a locally built engine
+through `SMARTSAMBA_RUST_BINARY`.
+Do not store SMB passwords in device metadata or log provider options.
+
 #### 🔊 PlaybackFeature & VolumeFeature
 
 `PlaybackFeature` and `VolumeFeature` provide normalized capability and state models. No external Sonos or Chromecast protocol client is bundled or wired into these features, so their methods update local feature state and emit events but do not provide live playback control for those devices.
@@ -522,9 +606,17 @@ The smart-home factories require a `protocolClient` that implements the correspo
 
 ### Event Handling
 
+`DeviceManager`, `UniversalDevice`, every `Feature`, and host-side providers
+remain Node `EventEmitter` instances and additionally expose `events$`. Each
+observable item contains the event `name`, its `args`, and `emittedAt`.
+
 ```typescript
 const manager = new DeviceManager();
 
+const subscription = manager.events$.subscribe((event) => {
+  console.log(event.name, event.args, event.emittedAt);
+});
+
 // Discovery events
 manager.on('device:found', ({ device, featureType }) => {
   console.log(`Found ${device.name} with ${featureType} capability`);
@@ -547,6 +639,8 @@ device.on('status:changed', ({ oldStatus, newStatus }) => {
 device.on('feature:connected', (featureType) => {
   console.log(`Feature ${featureType} connected`);
 });
+
+subscription.unsubscribe();
 ```
 
 ### Error Handling

package/test/test.brother.node.ts

@@ -0,0 +1,306 @@
+import * as net from 'node:net';
+
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import {
+  BrotherScanError,
+  BrotherScanProtocol,
+} from '../ts/protocols/protocol.brother.js';
+
+function makeJpeg(width: number, height: number, resolution: number): Buffer {
+  const padding = Buffer.alloc(80, 0x41);
+  return Buffer.concat([
+    Buffer.from([
+      0xff, 0xd8,
+      0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0x02, 0x01,
+      (resolution >> 8) & 0xff, resolution & 0xff,
+      (resolution >> 8) & 0xff, resolution & 0xff, 0x00, 0x00,
+      0xff, 0xfe, 0x00, 0x52,
+    ]),
+    padding,
+    Buffer.from([
+      0xff, 0xc0, 0x00, 0x0b, 0x08,
+      (height >> 8) & 0xff, height & 0xff,
+      (width >> 8) & 0xff, width & 0xff,
+      0x01, 0x01, 0x11, 0x00,
+      0xff, 0xd9,
+    ]),
+  ]);
+}
+
+function simpleFrame(payload: Buffer): Buffer {
+  const length = Buffer.alloc(2);
+  length.writeUInt16LE(payload.length);
+  return Buffer.concat([Buffer.from([0x40]), length, payload]);
+}
+
+function wrappedFrame(payload: Buffer, imageNumber: number = 1): Buffer {
+  const header = Buffer.alloc(12, 0);
+  header[0] = 0x40;
+  header.writeUInt16LE(7, 1);
+  header.writeUInt16LE(imageNumber, 3);
+  header.writeUInt16LE(payload.length, 10);
+  return Buffer.concat([header, payload]);
+}
+
+function endOfImage(imageNumber: number): Buffer {
+  const header = Buffer.alloc(10, 0);
+  header[0] = 0x82;
+  header.writeUInt16LE(7, 1);
+  header.writeUInt16LE(imageNumber, 3);
+  return header;
+}
+
+function readCommands(socket: net.Socket, onCommand: (command: Buffer) => void): void {
+  let input = Buffer.alloc(0);
+  socket.on('data', (data) => {
+    input = Buffer.concat([input, data]);
+    while (true) {
+      const end = input.indexOf(0x80);
+      if (end < 0) return;
+      const command = input.subarray(0, end + 1);
+      input = input.subarray(end + 1);
+      onCommand(command);
+    }
+  });
+}
+
+tap.test('Brother native scan supports variable-length ADF leases and drains every page', async () => {
+  const commands: string[] = [];
+  const firstPage = makeJpeg(5052, 8400, 600);
+  const secondPage = makeJpeg(5052, 8400, 600);
+  const secondPageWithoutEndMarker = secondPage.subarray(0, -2);
+  const server = net.createServer((socket) => {
+    socket.write('+OK 200\r\n');
+    readCommands(socket, (command) => {
+      const text = command.toString('latin1');
+      commands.push(text);
+      if (text.startsWith('\x1bS\n')) {
+        socket.write(Buffer.from([0x80]));
+      } else if (text.startsWith('\x1bI\n')) {
+        socket.write(Buffer.concat([
+          Buffer.from([0x1a, 0x00]),
+          Buffer.from('600,600,1,213,5052,0,0', 'ascii'),
+        ]));
+      } else if (text.includes('D=DUP')) {
+        socket.write(Buffer.concat([
+          wrappedFrame(firstPage.subarray(0, Math.floor(firstPage.length / 2)), 1),
+          wrappedFrame(secondPageWithoutEndMarker.subarray(0, Math.floor(secondPageWithoutEndMarker.length / 2)), 2),
+          wrappedFrame(firstPage.subarray(Math.floor(firstPage.length / 2)), 1),
+          endOfImage(1),
+          wrappedFrame(secondPageWithoutEndMarker.subarray(Math.floor(secondPageWithoutEndMarker.length / 2)), 2),
+          endOfImage(2),
+          Buffer.from([0x80]),
+        ]));
+      }
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, { timeout: 1000, scanTimeout: 1000 });
+
+  try {
+    await client.connect();
+    const result = await client.scan({
+      source: 'adf-duplex',
+      resolution: 600,
+      format: 'jpeg',
+      colorMode: 'color',
+      quality: 90,
+      area: { x: 0, y: 0, width: 215.9, height: 355.6 },
+    });
+
+    expect(result.pageCount).toEqual(2);
+    expect(result.pages?.[0]?.data.equals(firstPage)).toEqual(true);
+    expect(result.pages?.[1]?.data.equals(secondPage)).toEqual(true);
+    expect(result.width).toEqual(5052);
+    expect(result.height).toEqual(8400);
+    expect(result.resolution).toEqual(600);
+    expect(commands[0]).toEqual('\x1bS\nAUTO\n\x80');
+    expect(commands[1]).toContain('R=600,600');
+    expect(commands[2]).toContain('D=DUP');
+    expect(commands[2]).toContain('C=JPEG\nJ=MID');
+    expect(commands[2]).toContain('A=0,0,5052,8400');
+    expect(commands).toHaveLength(3);
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+tap.test('Brother native scan uses FB and bottom-right scan coordinates', async () => {
+  const commands: string[] = [];
+  const page = makeJpeg(1181, 1417, 300);
+  const server = net.createServer((socket) => {
+    socket.write('+OK 200\r\n');
+    readCommands(socket, (command) => {
+      const text = command.toString('latin1');
+      commands.push(text);
+      if (text.startsWith('\x1bS\n')) {
+        socket.write(Buffer.from([0x80]));
+      } else if (text.startsWith('\x1bI\n')) {
+        socket.write(Buffer.concat([
+          Buffer.from([0x1a, 0x00]),
+          Buffer.from('300,300,0,216,2551,356,4205', 'ascii'),
+        ]));
+      } else if (text.startsWith('\x1bX\n')) {
+        socket.write(Buffer.concat([wrappedFrame(page), endOfImage(1), Buffer.from([0x80])]));
+      }
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, {
+    timeout: 1000,
+    scanTimeout: 1000,
+  });
+
+  try {
+    await client.connect();
+    const result = await client.scan({
+      source: 'flatbed',
+      resolution: 300,
+      format: 'jpeg',
+      colorMode: 'color',
+      area: { x: 10, y: 20, width: 100, height: 120 },
+    });
+
+    expect(result.pageCount).toEqual(1);
+    expect(commands[0]).toEqual('\x1bS\nFB\n\x80');
+    expect(commands[2]).toContain('A=118,236,1299,1653');
+    expect(commands[2]).not.toContain('U=OFF');
+    expect(commands[2]).not.toContain('P=OFF');
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+tap.test('Brother legacy page boundaries request the next page', async () => {
+  const commands: string[] = [];
+  const firstPage = makeJpeg(2480, 3507, 300);
+  const secondPage = makeJpeg(2480, 3507, 300);
+  const server = net.createServer((socket) => {
+    socket.write('+OK 200\r\n');
+    readCommands(socket, (command) => {
+      const text = command.toString('latin1');
+      commands.push(text);
+      if (text.startsWith('\x1bS\n')) {
+        socket.write(Buffer.from([0x80]));
+      } else if (text.startsWith('\x1bI\n')) {
+        socket.write(Buffer.concat([
+          Buffer.from([0x1a, 0x00]),
+          Buffer.from('300,300,2,210,2480,297,3507', 'ascii'),
+        ]));
+      } else if (text.includes('C=JPEG')) {
+        socket.write(Buffer.concat([simpleFrame(firstPage), Buffer.from([0x81])]));
+      } else if (text === '\x1bX\n\x80') {
+        socket.write(Buffer.concat([simpleFrame(secondPage), Buffer.from([0x80])]));
+      }
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, {
+    timeout: 1000,
+    scanTimeout: 1000,
+  });
+
+  try {
+    await client.connect();
+    const result = await client.scan({
+      source: 'adf', resolution: 300, format: 'jpeg', colorMode: 'color',
+      area: { x: 0, y: 0, width: 210, height: 297 },
+    });
+    expect(result.pageCount).toEqual(2);
+    expect(commands[3]).toEqual('\x1bX\n\x80');
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+tap.test('Brother native scan rejects a silently downgraded resolution', async () => {
+  const server = net.createServer((socket) => {
+    socket.write('+OK 200\r\n');
+    readCommands(socket, (command) => {
+      const text = command.toString('latin1');
+      if (text.startsWith('\x1bS\n')) socket.write(Buffer.from([0x80]));
+      if (text.startsWith('\x1bI\n')) {
+        socket.write(Buffer.concat([
+          Buffer.from([0x1a, 0x00]),
+          Buffer.from('300,300,2,210,2480,297,3507', 'ascii'),
+        ]));
+      }
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, { timeout: 1000 });
+
+  try {
+    await client.connect();
+    let scanError: BrotherScanError | undefined;
+    try {
+      await client.scan({
+        source: 'adf', resolution: 600, format: 'jpeg', colorMode: 'color',
+        area: { x: 0, y: 0, width: 210, height: 297 },
+      });
+    } catch (error) {
+      if (error instanceof BrotherScanError) scanError = error;
+    }
+    expect(scanError?.code).toEqual('settings-rejected');
+    expect(scanError?.message).toContain('offered 300x300 dpi');
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+tap.test('Brother native scan retries a temporarily busy device', async () => {
+  let connections = 0;
+  const server = net.createServer((socket) => {
+    connections++;
+    if (connections < 3) socket.end('-NG 401\r\n');
+    else socket.write('+OK 200\r\n');
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, {
+    timeout: 1000,
+    busyRetryInterval: 5,
+    busyTimeout: 100,
+  });
+
+  try {
+    await client.connect();
+    expect(connections).toEqual(3);
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+tap.test('Brother native scan reports a persistently occupied device as busy', async () => {
+  const server = net.createServer((socket) => socket.end('-NG 401\r\n'));
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const address = server.address() as net.AddressInfo;
+  const client = new BrotherScanProtocol('127.0.0.1', address.port, {
+    timeout: 1000,
+    busyTimeout: 0,
+  });
+
+  try {
+    let connectError: BrotherScanError | undefined;
+    try {
+      await client.connect();
+    } catch (error) {
+      if (error instanceof BrotherScanError) connectError = error;
+    }
+    expect(connectError?.code).toEqual('busy');
+  } finally {
+    await client.disconnect();
+    await new Promise<void>((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+  }
+});
+
+export default tap.start();