@apocaliss92/nodelink-js 0.4.24 → 0.4.28

package/dist/index.d.ts

@@ -1075,6 +1075,19 @@ export declare class BaichuanEventEmitter {
     isSubscribed(): boolean;
 }
 
+/**
+ * Floodlight status push (cmd_id 291 / MSG_ID_FLOODLIGHT_STATUS_LIST).
+ * Emitted by the camera whenever the floodlight transitions on/off
+ * (including the auto-off after the FloodlightManual duration expires).
+ * `<status>0|1</status>` carries the actual current ON/OFF — this is the
+ * only reliable source for the current manual state, since cmd 289 only
+ * returns the FloodlightTask config.
+ */
+export declare type BaichuanFloodlightStatusPush = {
+    /** True when the floodlight is currently emitting light. */
+    status: boolean;
+};
+
 export declare type BaichuanFrame = {
     header: BaichuanHeader;
     /** Raw body bytes, exactly `bodyLen` bytes (extension+payload, if any). */
@@ -1747,6 +1760,22 @@ export declare type BaichuanSettingsPushCacheEntry = {
     dingdongList?: BaichuanCachedPush<BaichuanDingdongListPush>;
     sleepStatus?: BaichuanCachedPush<BaichuanSleepStatusPush>;
     coordinatePointList?: BaichuanCachedPush<BaichuanCoordinatePointListPush>;
+    floodlightStatus?: BaichuanCachedPush<BaichuanFloodlightStatusPush>;
+    sirenStatus?: BaichuanCachedPush<BaichuanSirenStatusPush>;
+};
+
+/**
+ * Siren status push (cmd_id 547 / MSG_ID_AUDIO_ALARM).
+ * Emitted when the siren starts or stops playing. The Reolink firmware
+ * stops the siren automatically after its built-in playback duration,
+ * so polling cmd 547 by itself can race the auto-off; the push catches
+ * the actual transitions.
+ */
+export declare type BaichuanSirenStatusPush = {
+    /** True when the siren is currently audible. */
+    status: boolean;
+    /** Whether the camera reports the siren as actively playing (some firmwares emit only this). */
+    playing?: boolean;
 };
 
 export declare type BaichuanSleepState = {
@@ -2949,6 +2978,8 @@ export declare function buildStartZoomFocusXml(channelId: number, movePos: numbe
  */
 export declare function buildWhiteLedStateXml(channelId: number, state: number): string;
 
+declare type CameraResolver = (recipient: string) => string | undefined;
+
 /**
  * Capture all relevant API responses from a single device (or NVR channel)
  * and write them as JSON/XML fixtures into `outDir`.
@@ -4050,6 +4081,27 @@ export declare function createDiagnosticsBundle(params: {
     diagnosticsPath: string;
 }>;
 
+export declare function createEmailPushServer(params: CreateEmailPushServerParams): EmailPushServerInstance;
+
+export declare interface CreateEmailPushServerParams {
+    config: EmailPushServerConfig;
+    /**
+     * Resolver mapping the `cam-<id>` localpart (the part before `@domain`)
+     * to the consumer's internal camera identifier. Return `undefined` to
+     * reject the recipient at RCPT TO.
+     */
+    cameraResolver: (localCameraId: string) => string | undefined;
+    /** Optional logger; defaults to no-op. */
+    logger?: EmailPushLogger;
+    /**
+     * Optional TLS loader override. Default uses `loadEmailPushTls` which
+     * reads `cert.pem` + `key.pem` from `config.tlsDir`. Consumers (e.g.
+     * Scrypted) can pass their own loader to source the material from a
+     * different store.
+     */
+    loadTls?: (dir: string, warn: (m: string) => void) => Promise<EmailPushTlsOptions | undefined>;
+}
+
 export declare function createLogger(options?: {
     base?: LoggerLike;
     level?: LogLevel;
@@ -4744,6 +4796,115 @@ export declare interface EmailConfig {
 /** Patch payload accepted by SetEmail. All fields optional — only supplied ones are written. */
 export declare type EmailConfigPatch = Partial<Omit<EmailConfig, "senderMaxLen" | "pwdMaxLen" | "emailAttachAbility">>;
 
+export declare interface EmailPushEvent {
+    cameraId: string;
+    /** Original recipient address that matched this camera. */
+    recipient: string;
+    inferredType: EmailPushInferredType;
+    /** Reception timestamp on the manager (ms since epoch). */
+    receivedAtMs: number;
+    subject: string;
+    from: string;
+    /** Raw body text excerpt (max 500 chars). */
+    bodyExcerpt: string;
+}
+
+/**
+ * Email push event bus.
+ *
+ * Stateless in-memory dispatcher. Lives in the library so any consumer
+ * (the manager app, the Scrypted plugin, integration tests) can subscribe
+ * and emit through the same surface without dragging in the
+ * `smtp-server` / `mailparser` native deps.
+ *
+ * The bus is intentionally:
+ * - **Process-local** — every consumer has its own bus instance (the
+ *   module-level state below). No cross-process or cross-import sharing.
+ * - **Bounded** — keeps the last `MAX_GLOBAL_EVENTS` (default 300) for
+ *   the "recent emails" panel, and a single-event reference per camera
+ *   for the verifyDelivery race short-circuit. Footprint is O(cameras)
+ *   plus O(MAX_GLOBAL_EVENTS).
+ * - **Attachment-free** — only metadata (subject, from, body excerpt,
+ *   classified type) is retained; the actual JPEG/MP4 payloads from the
+ *   camera are never persisted by the bus.
+ */
+/** Trigger classification produced by parsing the camera's email body. */
+export declare type EmailPushInferredType = "motion" | "people" | "vehicle" | "animal" | "face" | "package" | "doorbell" | "other";
+
+export declare interface EmailPushLogger {
+    debug?: (msg: string) => void;
+    info?: (msg: string) => void;
+    warn?: (msg: string) => void;
+    error?: (msg: string) => void;
+}
+
+export declare interface EmailPushServerConfig {
+    /** SMTP listen port. */
+    port: number;
+    /** Bind host (`0.0.0.0` to accept on LAN). */
+    bindHost: string;
+    /** Virtual mail domain — used to extract the camera id from RCPT TO. */
+    domain: string;
+    /** Require AUTH PLAIN / AUTH LOGIN. */
+    requireAuth: boolean;
+    /** Expected AUTH username (stored bare, e.g. `nodelink-abcd`). */
+    authUsername: string;
+    /** Expected AUTH password. */
+    authPassword: string;
+    /** Enable STARTTLS using cert+key under `tlsDir`. */
+    tls: boolean;
+    /** Directory holding cert.pem + key.pem when `tls: true`. */
+    tlsDir?: string;
+    /** Maximum accepted message size in bytes. */
+    maxMessageBytes: number;
+}
+
+export declare interface EmailPushServerInstance {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    restart(): Promise<void>;
+    getStatus(): EmailPushServerStatus;
+    /**
+     * Replace the current config; the next `start` / `restart` picks it up.
+     * Hot updates of config without restart are not supported on purpose —
+     * SMTP server bind options need a fresh `listen()`.
+     */
+    updateConfig(next: EmailPushServerConfig): void;
+}
+
+export declare interface EmailPushServerStatus {
+    enabled: boolean;
+    running: boolean;
+    port: number;
+    bindHost: string;
+    domain: string;
+    requireAuth: boolean;
+    tls: boolean;
+    /** Cumulative messages accepted since start. */
+    messagesAccepted: number;
+    /** Cumulative messages rejected (unknown recipient, parse fail, etc.). */
+    messagesRejected: number;
+    startedAtMs: number | undefined;
+    lastErrorMessage: string | undefined;
+}
+
+/**
+ * Optional STARTTLS support for the email-push SMTP server.
+ *
+ * The library does NOT auto-generate a self-signed cert: doing so portably
+ * across Node versions requires a heavy dependency (`selfsigned` /
+ * `node-forge`), and Reolink cameras typically accept self-signed certs
+ * only when the user has consciously opted into TLS.
+ *
+ * Consumers point `loadEmailPushTls` at a directory containing `cert.pem`
+ * and `key.pem`. When either is missing the function returns `undefined`
+ * and logs through the provided logger (or `console.warn` by default).
+ */
+export declare interface EmailPushTlsOptions {
+    cert: Buffer;
+    key: Buffer;
+}
+
 /** Email schedule configuration (cmdId=216/217). */
 export declare interface EmailTaskConfig {
     channelId: number;
@@ -4770,6 +4931,9 @@ export declare interface EmailTaskScheduleItem {
 /** Whether the alert body carries the standard human-readable text. */
 export declare type EmailTextType = "withText" | "noText";
 
+/** Internal: SMTP server uses this to dispatch an event into the bus. */
+export declare function emitEmailPushEvent(event: EmailPushEvent): void;
+
 /**
  * Encoding configuration (getEnc response).
  * cmdId=56 (GetEnc) — payload is wrapped in `Compression`, not `Enc`.
@@ -4930,6 +5094,8 @@ export declare interface EncStreamPatch {
  */
 export declare function ensureXmlHeader(xml: string): string;
 
+declare type EventHandler = (event: EmailPushEvent) => void;
+
 export declare interface Events {
     channel?: number;
     ai?: AIState;
@@ -5047,6 +5213,9 @@ export declare interface FtpTaskConfig {
  */
 export declare function fullCoverageScope(columns: number, rows: number, width?: number, height?: number): MotionZoneScope;
 
+/** Build the recipient address assigned to a given camera. */
+export declare function getCameraEmailAddress(cameraId: string, domain: string): string;
+
 /**
  * Get constructed video stream options for all available profiles.
  *
@@ -5054,6 +5223,8 @@ export declare function fullCoverageScope(columns: number, rows: number, width?:
  */
 export declare function getConstructedVideoStreamOptions(channel: number, api: ReolinkBaichuanApi, rtspHost: string, rtspPort?: number, rtspUsername?: string, rtspPassword?: string): Promise<ResponseMediaStreamOptions[]>;
 
+export declare function getEmailPushCameraResolver(): CameraResolver;
+
 export declare function getGlobalLogger(): Logger_2;
 
 /**
@@ -5062,8 +5233,23 @@ export declare function getGlobalLogger(): Logger_2;
  */
 export declare function getH265NalType(nalPayload: Buffer): number | null;
 
+/**
+ * Read the most recent event observed for a camera. Returns `undefined`
+ * when no email-push event has been received since the consumer started.
+ */
+export declare function getLastEmailPushEvent(cameraId: string): EmailPushEvent | undefined;
+
 export declare function getMjpegContentType(boundary: string): string;
 
+/**
+ * Return a snapshot of the most recent email-push events across all
+ * cameras (most recent first). Capped at `MAX_GLOBAL_EVENTS` (300).
+ *
+ * `limit` is clamped to the buffer cap so callers can ask for a smaller
+ * page without juggling the storage limit.
+ */
+export declare function getRecentEmailPushEvents(limit?: number): EmailPushEvent[];
+
 /**
  * Result of getRecordingVideo() - a fully muxed MP4 with stats.
  */
@@ -5741,6 +5927,19 @@ export declare type LastSleepProbe = {
     status: SleepStatus;
 };
 
+/**
+ * Read the user-provided cert/key pair. Returns `undefined` (and logs a
+ * warning) when either file is missing.
+ */
+export declare function loadEmailPushTls(params: LoadTlsParams): Promise<EmailPushTlsOptions | undefined>;
+
+export declare interface LoadTlsParams {
+    /** Directory holding `cert.pem` + `key.pem`. */
+    dir: string;
+    /** Optional logger; defaults to console-based warn. */
+    warn?: (msg: string) => void;
+}
+
 export declare type Logger = Logger_2;
 
 declare interface Logger_2 {
@@ -5767,6 +5966,15 @@ export declare type LoginResponseValue = {
 
 export declare type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
 
+/**
+ * Map the email-push classifier output onto the lib's broader
+ * ReolinkSimpleEvent type union. Shared by `ReolinkBaichuanApi
+ * .subscribeEmailPushEvents` (the per-camera bridge) and any consumer
+ * that wants the same mapping at the global bus level (e.g. the
+ * manager-app's events-manager) so both code paths stay in sync.
+ */
+export declare function mapEmailPushInferredType(inferred: EmailPushInferredType): "motion" | "doorbell" | "people" | "vehicle" | "animal" | "face" | "package";
+
 /**
  * Privacy mask configuration (`getMask`). The `Shelter` block always
  * contains `enable` + `maxNum` + `shelterList`; tracked-shelter sub-
@@ -6139,6 +6347,12 @@ export declare type NvrChannelsSummaryCacheEntry = {
     devices: ReolinkBaichuanDeviceSummary[];
 };
 
+/**
+ * Register a handler invoked for every accepted email-push event. Returns
+ * an `off` function.
+ */
+export declare function onEmailPushEvent(handler: EventHandler): () => void;
+
 /**
  * Online user list response.
  */
@@ -6527,7 +6741,7 @@ export declare class ReolinkBaichuanApi {
      * general socket is created, logged in, and all event/push/guard listeners
      * are re-attached automatically.
      *
-     * This is a **no-op** when the API is already {@link isReady}.
+     * This is a **no-op** when the API is already ready (see `isReadyState()`).
      *
      * @throws If `close()` was called — the API is permanently closed and a new
      *         instance must be created.
@@ -6541,7 +6755,7 @@ export declare class ReolinkBaichuanApi {
     /**
      * Attach event, push, channelInfo, and guard listeners to the current
      * "general" client.  Called from the constructor and from
-     * {@link reconnectGeneralSocket}.
+     * `reconnectGeneralSocket()`.
      */
     private setupGeneralClientListeners;
     /**
@@ -7064,6 +7278,27 @@ export declare class ReolinkBaichuanApi {
      * Called on every socket close event.
      */
     private maybeRebootOnEconnresetStorm;
+    /**
+     * Bind this API instance to the global email-push bus so that incoming
+     * SMTP-delivered motion / AI events for the matching camera surface on
+     * this instance's standard `onSimpleEvent` channel. The consumer keeps
+     * a single subscription (`onSimpleEvent`) and gets both the native
+     * Baichuan push and the email-push transport on the same stream.
+     *
+     * - `cameraId` shorthand: match events with `event.cameraId === cameraId`.
+     * - `match`: arbitrary predicate (e.g. when the consumer uses a
+     *   nickname-based mapping or wants to handle multiple recipients).
+     *
+     * Returns an `off()` handle. Safe to call repeatedly — each call
+     * registers its own listener.
+     */
+    subscribeEmailPushEvents(params: {
+        cameraId: string;
+        channel?: number;
+    } | {
+        match: (event: EmailPushEvent) => boolean;
+        channel?: number;
+    }): () => void;
     /**
      * Subscribe to minimal high-level events.
      * The API manages Baichuan subscribe/unsubscribe automatically.
@@ -7080,7 +7315,7 @@ export declare class ReolinkBaichuanApi {
      * Subscribe to per-frame detection events sourced from the BcMedia
      * `additionalHeader` block on active video streams.
      *
-     * Mirrors {@link onSimpleEvent} but is fed by the streaming side-channel:
+     * Mirrors `onSimpleEvent()` but is fed by the streaming side-channel:
      * one event fires for every I-frame / P-frame that carries an overlay block.
      * Coordinates are reported in normalized [0, 1] fractions of the source
      * frame, so the same box renders correctly on mainStream, subStream, and
@@ -7099,7 +7334,7 @@ export declare class ReolinkBaichuanApi {
      * Subscribe to AI object detections (people / vehicle / animal / face boxes
      * with class label and confidence) without managing a video stream yourself.
      *
-     * Mirrors {@link onSimpleEvent} end-to-end: on the first listener for a given
+     * Mirrors `onSimpleEvent()` end-to-end: on the first listener for a given
      * `(channel, profile)` tuple the API ensures the corresponding video stream
      * is running (the pool socket may already be shared with a regular consumer),
      * forwards every box-bearing `additionalHeader` to your callback, and tears
@@ -8716,7 +8951,7 @@ export declare class ReolinkBaichuanApi {
      * Field meaning per stream:
      *  - `audio`           — 0/1 toggle
      *  - `width`/`height`  — resolution in pixels. Must be one of the
-     *                        resolutions returned by {@link getStreamInfoList}.
+     *                        resolutions returned by `getStreamInfoList()`.
      *  - `bitRate`         — kbps. Must match the table from `getStreamInfoList`.
      *  - `frameRate`       — fps. Must match the table from `getStreamInfoList`.
      *  - `videoEncType`    — `"h264"` or `"h265"`
@@ -9033,6 +9268,25 @@ export declare class ReolinkBaichuanApi {
     getDingdongListFromPushCache(channel?: number): BaichuanCachedPush<BaichuanDingdongListPush> | undefined;
     getSleepStatusFromPushCache(channel?: number): BaichuanCachedPush<BaichuanSleepStatusPush> | undefined;
     getCoordinatePointListFromPushCache(channel?: number): BaichuanCachedPush<BaichuanCoordinatePointListPush> | undefined;
+    /**
+     * Last cmd_id 291 (FloodlightStatusList) push observed for the channel.
+     * The camera emits this whenever the floodlight transitions on/off,
+     * including the auto-off after the FloodlightManual duration. This is
+     * the only reliable source for the current manual state because cmd 289
+     * only returns the FloodlightTask config.
+     *
+     * Returns undefined when no push has been received yet.
+     */
+    getCachedFloodlightStatus(channel?: number): BaichuanCachedPush<BaichuanFloodlightStatusPush> | undefined;
+    /**
+     * Last cmd_id 547 (SirenStatusList) push observed for the channel.
+     * Captures the actual on/off transitions including the firmware's
+     * built-in auto-off after the siren playback duration expires —
+     * polling cmd 547 alone can race that auto-off.
+     *
+     * Returns undefined when no push has been received yet.
+     */
+    getCachedSirenStatus(channel?: number): BaichuanCachedPush<BaichuanSirenStatusPush> | undefined;
     private isNvrLikeDevice;
     private sendPcapDerivedSettingsGetXml;
     /**
@@ -10800,6 +11054,9 @@ export declare interface ReplayHttpServerOptions {
     isNvr?: boolean;
 }
 
+/** Test hook: drop all subscribers, recent events, and reset the resolver. */
+export declare function _resetEmailPushBusForTests(): void;
+
 /**
  * ResponseMediaStreamOptions - Stream profile metadata
  */
@@ -11172,6 +11429,13 @@ export declare function sampleStreams(opts: StreamSamplingOptions): Promise<void
  */
 export declare function sanitizeFixtureData(value: unknown): unknown;
 
+/**
+ * Set the callback that maps a recipient address (e.g.
+ * `cam-abc@nodelink.local`) to a known cameraId. Returning `undefined`
+ * rejects the recipient at RCPT TO.
+ */
+export declare function setEmailPushCameraResolver(resolver: CameraResolver): void;
+
 export declare function setGlobalLogger(logger: LoggerLike | Logger_2 | undefined): void;
 
 /**