@apocaliss92/scrypted-reolink-native 0.5.25 → 0.5.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apocaliss92/scrypted-reolink-native",
-  "version": "0.5.25",
+  "version": "0.5.27",
   "description": "Use any reolink camera with Scrypted, even older/unsupported models without HTTP protocol support",
   "author": "@apocaliss92",
   "license": "Apache",
@@ -44,7 +44,7 @@
     ]
   },
   "dependencies": {
-    "@apocaliss92/nodelink-js": "^0.4.31",
+    "@apocaliss92/nodelink-js": "^0.4.32",
     "@scrypted/common": "file:../../scrypted/common",
     "@scrypted/rtsp": "file:../../scrypted/plugins/rtsp",
     "@scrypted/sdk": "^0.3.118"

package/src/baichuan-base.ts

@@ -1,6 +1,5 @@
 import type {
   BaichuanClientOptions,
-  EmailPushEvent,
   ReolinkBaichuanApi,
   ReolinkSimpleEvent,
 } from "@apocaliss92/nodelink-js" with { "resolution-mode": "import" };
@@ -16,6 +15,13 @@ export interface BaichuanConnectionConfig {
   transport: BaichuanTransport;
   debugOptions?: any;
   udpDiscoveryMethod?: BaichuanClientOptions["udpDiscoveryMethod"];
+  /**
+   * When set, the api auto-bridges the global email-push bus into
+   * its own `simpleEventListeners` so SMTP motion lands on the same
+   * `onSimpleEvent` stream as native Baichuan push. Standalone
+   * (non-NVR-child, non-multifocal-lens) cameras only.
+   */
+  emailPushCameraId?: string;
 }
 
 export interface BaichuanConnectionCallbacks {
@@ -23,26 +29,6 @@ export interface BaichuanConnectionCallbacks {
   onClose?: () => void | Promise<void>;
   onSimpleEvent?: (ev: ReolinkSimpleEvent) => void;
   getEventSubscriptionEnabled?: () => boolean;
-  /**
-   * When provided, the base class binds the camera's api to the global
-   * email-push bus filtered on `cameraId === emailPushCameraId()`. The
-   * lib's `subscribeEmailPushEvents` converts each matching event into
-   * a `ReolinkSimpleEvent` and dispatches it through `onSimpleEvent`,
-   * so the camera's existing motion / AI handler lights up for SMTP-
-   * delivered events with no extra wiring. Standalone cameras only —
-   * leave undefined on NVR children where email-push isn't meaningful.
-   */
-  emailPushCameraId?: () => string;
-  /**
-   * Optional. When the email-push event carries an image attachment
-   * (typical for `attachmentType=picture` on motion), the camera
-   * receives the full event so it can republish the snapshot —
-   * usually by updating its `lastPicture` cache so subsequent
-   * `takePicture()` calls return the fresh thumbnail without waking
-   * the camera. Invoked AFTER the simple-event dispatch so any motion
-   * listener has already fired.
-   */
-  onEmailPushEvent?: (event: EmailPushEvent) => void;
 }
 
 /**
@@ -207,7 +193,6 @@ export abstract class BaseBaichuanClass extends ScryptedDeviceBase {
   private eventSubscriptionActive: boolean = false;
   private lastEventTime: number = 0;
   private currentWrappedEventHandler?: (ev: ReolinkSimpleEvent) => void;
-  private currentEmailPushOff?: () => void;
   private subscribeToEventsPromise?: Promise<void>;
   private pingInterval?: NodeJS.Timeout;
   private autoRenewInterval?: NodeJS.Timeout;
@@ -371,6 +356,9 @@ export abstract class BaseBaichuanClass extends ScryptedDeviceBase {
             logger,
             debugOptions: config.debugOptions,
             udpDiscoveryMethod: config.udpDiscoveryMethod,
+            ...(config.emailPushCameraId
+              ? { emailPushCameraId: config.emailPushCameraId }
+              : {}),
           },
           transport: config.transport,
         });
@@ -904,33 +892,11 @@ export abstract class BaseBaichuanClass extends ScryptedDeviceBase {
       // the library watchdog handles auto-recovery internally.
       await api.onSimpleEvent(this.currentWrappedEventHandler);
 
-      // Bridge the global email-push bus into this api's onSimpleEvent
-      // stream so the same wrapped handler above (and any other
-      // listener) sees SMTP-delivered motion exactly like a native push.
-      // Idempotent: if a previous off-handle is still around, release it.
-      if (callbacks.emailPushCameraId) {
-        if (this.currentEmailPushOff) {
-          try {
-            this.currentEmailPushOff();
-          } catch {}
-          this.currentEmailPushOff = undefined;
-        }
-        try {
-          this.currentEmailPushOff = api.subscribeEmailPushEvents({
-            cameraId: callbacks.emailPushCameraId(),
-            channel: 0,
-            ...(callbacks.onEmailPushEvent
-              ? { onEvent: callbacks.onEmailPushEvent }
-              : {}),
-          });
-          logger.debug("Bridged email-push bus to onSimpleEvent");
-        } catch (e) {
-          logger.warn(
-            "Failed to bridge email-push events",
-            e?.message || String(e),
-          );
-        }
-      }
+      // NOTE: the email-push bus subscription used to live here, but
+      // it's now owned by `ReolinkCamera.subscribeToEmailPushBus()`
+      // because the bus is global and must outlive the Baichuan api —
+      // battery cams routinely drop the api between motions, which
+      // would silently drop SMTP events with an api-scoped bridge.
 
       this.eventSubscriptionActive = true;
       this.lastEventTime = Date.now(); // Initialize on subscription
@@ -961,12 +927,6 @@ export abstract class BaseBaichuanClass extends ScryptedDeviceBase {
         // api.close() destroys the pool before the promise settles.
         await this.baichuanApi.offSimpleEvent(this.currentWrappedEventHandler);
         this.currentWrappedEventHandler = undefined;
-        if (this.currentEmailPushOff) {
-          try {
-            this.currentEmailPushOff();
-          } catch {}
-          this.currentEmailPushOff = undefined;
-        }
         logger.debug("Unsubscribed from Baichuan events");
       } catch (e) {
         logger.warn("Error unsubscribing from events", e?.message || String(e));

package/src/camera.ts

@@ -1,7 +1,6 @@
 import type {
   BatteryInfo,
   DeviceCapabilities,
-  EmailPushEvent,
   NativeVideoStreamVariant,
   PtzCommand,
   PtzPreset,
@@ -1558,6 +1557,14 @@ export class ReolinkCamera
     //   throw new Error("IP Address is required for TCP devices");
     // }
 
+    // Enable the lib-level email-push auto-bridge on the api so SMTP
+    // motion lands on `api.onSimpleEvent` together with native push.
+    // Skipped for NVR children / multifocal lens children — they
+    // share the parent's connection and the parent (camera/NVR) owns
+    // the mail path; running the bridge twice would dispatch the
+    // event to both ends and risk double-counting.
+    const eligibleForEmailPush = !this.isOnNvr && !this.multiFocalDevice;
+
     return {
       host: ipAddress,
       username,
@@ -1568,6 +1575,9 @@ export class ReolinkCamera
       udpDiscoveryMethod: discoveryMethod,
       // NOTE: idleDisconnect is NOT set here - the library handles it internally
       // based on the battery status detected during connection
+      ...(eligibleForEmailPush && this.nativeId
+        ? { emailPushCameraId: this.nativeId }
+        : {}),
     };
   }
 
@@ -1609,20 +1619,12 @@ export class ReolinkCamera
       onSimpleEvent: this.onSimpleEventBound,
       getEventSubscriptionEnabled: () =>
         this.isEventDispatchEnabled?.() ?? false,
-      // Bind this api to the global email-push bus so battery cameras
-      // delivering motion via SMTP land on the same `onSimpleEvent`
-      // stream as the native push. The Email Push Server device
-      // (singleton under the provider) maps `cam-<nativeId>@<domain>`
-      // RCPT addresses back to this `nativeId`.
-      emailPushCameraId: () => this.nativeId ?? "",
-      // When the e-mail carries the snapshot Reolink sends with
-      // `attachmentType=picture`, hand it to the camera's `lastPicture`
-      // cache. Downstream consumers (Snapshot mixin → MQTT image
-      // entity, Advanced Notifier, HA discovery) call `takePicture()`
-      // on the back of the motion event; for battery cams that returns
-      // the cached value, so dropping the fresh snapshot in here makes
-      // the trigger frame surface in MQTT/HA without waking the camera.
-      onEmailPushEvent: (event) => this.handleEmailPushSnapshot(event),
+      // Email-push events are wired in `init()` directly against the
+      // lib's global bus — NOT through the api here, because for
+      // battery cams the Baichuan api lifetime is much shorter than
+      // the camera lifetime (api closes when the cam sleeps), so an
+      // api-level subscription would be dead by the time the next
+      // motion email arrives. See `subscribeToEmailPushBus()`.
     };
   }
 
@@ -2121,6 +2123,17 @@ export class ReolinkCamera
       this.processEvents({ motion, objects }).catch((e) => {
         logger.warn("Error processing events", e?.message || String(e));
       });
+
+      // Battery cams cache `lastPicture` aggressively because waking
+      // the device for a snapshot is expensive. When motion fires the
+      // cam is, by definition, awake right now — proactively refresh
+      // the cache so the Snapshot mixin → MQTT image entity / HA
+      // discovery serves the trigger frame on the next `takePicture`
+      // call instead of the previous cached one. Wired cams don't
+      // need this (Snapshot mixin always gets fresh data anyway).
+      if (motion && this.isBattery && !this.multiFocalDevice) {
+        void this.refreshSnapshotOnMotion(ev.timestamp ?? Date.now());
+      }
     } catch (e) {
       logger.warn("Error in onSimpleEvent handler", e?.message || String(e));
     }
@@ -2744,34 +2757,37 @@ export class ReolinkCamera
   }
 
   /**
-   * Called from `baichuan-base.subscribeToEvents` when a per-camera
-   * email-push event lands on the bus. We don't use the e-mail's image
-   * attachment — Reolink firmwares vary on quality/encoding and we'd
-   * be reimplementing the snapshot pipeline. Instead we leverage the
-   * fact that the camera is *guaranteed awake* right now (it just
-   * pushed an e-mail) and call the live Baichuan snapshot API: it
-   * returns a fresh frame in milliseconds without forcing an extra
-   * wake-up cycle. The result is stashed in `lastPicture` so the
-   * Snapshot mixin → MQTT image entity (and any other consumer that
-   * calls `takePicture()` on the back of the motion event) serves the
-   * trigger frame instead of the previous cached one.
+   * Refresh the `lastPicture` cache by fetching a live snapshot via
+   * the Baichuan API. Used on motion events for battery cameras: the
+   * cam is guaranteed awake at that moment (just sent native push or
+   * SMTP), so the round-trip is cheap, and downstream consumers
+   * (Snapshot mixin → MQTT image entity, HA discovery) reading
+   * `takePicture()` on the back of the motion get the trigger frame
+   * instead of the previous cached one. Fire-and-forget; per-camera
+   * debounce so an event burst doesn't trigger overlapping fetches.
    */
-  private async handleEmailPushSnapshot(
-    event: EmailPushEvent,
-  ): Promise<void> {
+  private lastMotionSnapshotAtMs = 0;
+  private motionSnapshotInFlight = false;
+  private async refreshSnapshotOnMotion(timestampMs: number): Promise<void> {
+    if (this.motionSnapshotInFlight) return;
+    if (timestampMs - this.lastMotionSnapshotAtMs < 5_000) return;
+    this.motionSnapshotInFlight = true;
+    this.lastMotionSnapshotAtMs = timestampMs;
     const logger = this.getBaichuanLogger();
     try {
       const client = await this.ensureClient();
       const mo = await this.takePictureInternal(client);
-      this.lastPicture = { mo, atMs: event.receivedAtMs };
+      this.lastPicture = { mo, atMs: timestampMs };
       this.forceNewSnapshot = false;
       logger.log(
-        `E-mail Push snapshot fetched live (type=${event.inferredType}) — next takePicture will serve it`,
+        `Motion snapshot refreshed — next takePicture will serve the trigger frame`,
       );
     } catch (e) {
       logger.warn(
-        `E-mail Push: live snapshot fetch failed: ${e?.message || String(e)}`,
+        `Motion snapshot refresh failed: ${e?.message || String(e)}`,
       );
+    } finally {
+      this.motionSnapshotInFlight = false;
     }
   }
 
@@ -2933,6 +2949,8 @@ export class ReolinkCamera
     this.statusPollTimer && clearInterval(this.statusPollTimer);
     this.sleepCheckTimer && clearInterval(this.sleepCheckTimer);
     this.batteryUpdateTimer && clearInterval(this.batteryUpdateTimer);
+    // The lib's email-push auto-bridge is released by `api.close()`
+    // inside `resetBaichuanClient` — no separate teardown needed.
     this.resetBaichuanClient();
     this.plugin.camerasMap.delete(this.id);
   }
@@ -3601,6 +3619,13 @@ export class ReolinkCamera
     }
 
     this.startPeriodicTasks();
+
+    // NOTE: the email-push bus subscription used to live here, but
+    // the lib's api factory now auto-bridges SMTP motion into
+    // `api.onSimpleEvent` when `emailPushCameraId` is passed (see
+    // `getConnectionConfig()`), so there's nothing to wire up at the
+    // camera level — the next `ensureClient()` activates the bridge.
+
     await this.ensureClient();
 
     try {

package/src/connect.ts

@@ -14,6 +14,18 @@ export type BaichuanConnectInputs = {
   logger?: Console;
   debugOptions?: BaichuanClientOptions["debugOptions"];
   udpDiscoveryMethod?: BaichuanClientOptions["udpDiscoveryMethod"];
+  /**
+   * When set, the lib api auto-bridges the global email-push bus into
+   * its own `simpleEventListeners`, so SMTP motion lands on the same
+   * `onSimpleEvent` stream as native Baichuan push. Bridge survives
+   * TCP transient disconnects (it's a pure JS fan-out). For Reolink
+   * cameras this should be the camera's plugin-side nativeId — the
+   * `EmailPushServerDevice` resolves `cam-<nativeId>@<domain>` against
+   * the same string, so the round-trip is symmetric.
+   */
+  emailPushCameraId?: string;
+  /** Channel reported on the synthesised event. Default 0. */
+  emailPushChannel?: number;
 };
 
 export function normalizeUid(uid?: string): string | undefined {
@@ -38,6 +50,21 @@ export async function createBaichuanApi(props: {
     debugOptions: inputs.debugOptions ?? {},
   };
 
+  // The lib's auto-bridge fields belong on the second positional arg
+  // of `new ReolinkBaichuanApi(opts)` alongside `nativeOnly` etc.; we
+  // build a small `extras` bag and spread it at construction time
+  // below for both tcp + udp paths.
+  const extras: {
+    emailPushCameraId?: string;
+    emailPushChannel?: number;
+  } = {};
+  if (inputs.emailPushCameraId) {
+    extras.emailPushCameraId = inputs.emailPushCameraId;
+    if (inputs.emailPushChannel !== undefined) {
+      extras.emailPushChannel = inputs.emailPushChannel;
+    }
+  }
+
   const attachErrorHandler = (api: ReolinkBaichuanApi) => {
     // Critical: BaichuanClient emits 'error'. If nobody listens, Node treats it as an
     // uncaught exception. Ensure we always have a listener.
@@ -75,6 +102,7 @@ export async function createBaichuanApi(props: {
   if (transport === "tcp") {
     const api = new ReolinkBaichuanApi({
       ...base,
+      ...extras,
       transport: "tcp",
     });
     attachErrorHandler(api);
@@ -88,6 +116,7 @@ export async function createBaichuanApi(props: {
 
   const api = new ReolinkBaichuanApi({
     ...base,
+    ...extras,
     transport: "udp",
     uid,
     // NOTE: idleDisconnect is NOT set here - the library handles it internally