@apocaliss92/nodelink-js 0.4.26 → 0.4.28

package/dist/index.d.ts

@@ -2978,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`.
@@ -4079,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;
@@ -4773,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;
@@ -4799,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`.
@@ -4959,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;
@@ -5076,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.
  *
@@ -5083,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;
 
 /**
@@ -5091,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.
  */
@@ -5770,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 {
@@ -5796,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-
@@ -6168,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.
  */
@@ -6556,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.
@@ -6570,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;
     /**
@@ -7093,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.
@@ -7109,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
@@ -7128,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
@@ -8745,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"`
@@ -10848,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
  */
@@ -11220,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;
 
 /**