@apocaliss92/nodelink-js 0.1.20 → 0.2.2

package/dist/index.d.ts

@@ -454,6 +454,13 @@ export declare class BaichuanClient extends EventEmitter<{
      *   and may leave device-side sessions in a bad state.
      */
     private static readonly coverPreviewQueueTail;
+    /**
+     * Global CoverPreview backoff – increases on 400 rejection, resets on success.
+     * Prevents flooding the camera when it's overwhelmed.
+     */
+    private static readonly coverPreviewBackoffMs;
+    private static readonly COVER_PREVIEW_INITIAL_BACKOFF_MS;
+    private static readonly COVER_PREVIEW_MAX_BACKOFF_MS;
     private readonly opts;
     private readonly debugCfg;
     private readonly logger;
@@ -804,6 +811,10 @@ export declare class BaichuanClient extends EventEmitter<{
      * Send CoverPreview command (cmd_id=298) to get an I-frame from a past recording.
      * Similar to sendBinarySnapshot109 but handles the stream header + frame format
      * instead of JPEG.
+     *
+     * Retry is minimal (2 attempts) – the global backoff in `withSerializedCoverPreview`
+     * throttles subsequent requests when the camera is overwhelmed.
+     * PCAP analysis shows the camera routinely rejects the first request with 400.
      */
     sendBinaryCoverPreview(params: {
         cmdId: number;
@@ -818,10 +829,6 @@ export declare class BaichuanClient extends EventEmitter<{
         streamType?: number;
         encryption?: EncryptionProtocol;
         timeoutMs?: number;
-        /** Maximum retry attempts on 400 rejection (default: 5). PCAP analysis shows camera often rejects first few requests. */
-        maxRetries?: number;
-        /** Delay between retries in ms (default: 1000). */
-        retryDelayMs?: number;
     }): Promise<Buffer>;
     /**
      * Internal: single attempt for sendBinaryCoverPreview
@@ -1830,6 +1837,10 @@ export declare const BC_CMD_ID_COVER_STANDALONE_461 = 461;
 
 export declare const BC_CMD_ID_COVER_STANDALONE_462 = 462;
 
+export declare const BC_CMD_ID_DING_DONG_CTRL = 483;
+
+export declare const BC_CMD_ID_DING_DONG_OPT = 485;
+
 export declare const BC_CMD_ID_FILE_INFO_LIST_CLOSE = 16;
 
 export declare const BC_CMD_ID_FILE_INFO_LIST_DL_VIDEO = 8;
@@ -1876,6 +1887,12 @@ export declare const BC_CMD_ID_GET_DAY_NIGHT_THRESHOLD = 296;
 
 export declare const BC_CMD_ID_GET_DAY_RECORDS = 142;
 
+export declare const BC_CMD_ID_GET_DING_DONG_CFG = 486;
+
+export declare const BC_CMD_ID_GET_DING_DONG_LIST = 484;
+
+export declare const BC_CMD_ID_GET_DING_DONG_SILENT = 609;
+
 export declare const BC_CMD_ID_GET_EMAIL_TASK = 217;
 
 export declare const BC_CMD_ID_GET_FTP_TASK = 70;
@@ -1955,12 +1972,18 @@ export declare const BC_CMD_ID_PUSH_SLEEP_STATUS = 623;
 
 export declare const BC_CMD_ID_PUSH_VIDEO_INPUT = 78;
 
+export declare const BC_CMD_ID_QUICK_REPLY_PLAY = 349;
+
 export declare const BC_CMD_ID_SET_AI_ALARM = 343;
 
 export declare const BC_CMD_ID_SET_AI_CFG = 300;
 
 export declare const BC_CMD_ID_SET_AUDIO_TASK = 231;
 
+export declare const BC_CMD_ID_SET_DING_DONG_CFG = 487;
+
+export declare const BC_CMD_ID_SET_DING_DONG_SILENT = 610;
+
 export declare const BC_CMD_ID_SET_MOTION_ALARM = 47;
 
 export declare const BC_CMD_ID_SET_PIR_INFO = 213;
@@ -2862,6 +2885,39 @@ export declare interface ChannelStreamMetadata {
     rawXml?: string;
 }
 
+/** Per-event alarm config entry inside a chime's GetDingDongCfg response. */
+export declare interface ChimeAlarmCfg {
+    /** Whether this event type triggers the chime: 0 = off, 1 = on */
+    valid: number;
+    /** Ringtone / music ID */
+    musicId: number;
+}
+
+/** Per-chime config from GetDingDongCfg. */
+export declare interface ChimeCfg {
+    /** Chime ring ID */
+    id: number;
+    /** Map of event type string → alarm config */
+    type: Record<string, ChimeAlarmCfg>;
+}
+
+/** A paired wireless chime device as returned by GetDingDongList. */
+export declare interface ChimeDevice {
+    id: number;
+    name: string;
+    /** 0 = offline, 1 = online */
+    netState: number;
+}
+
+/** Wireless chime parameters returned by DingDongOpt (option 2 / getParam). */
+export declare interface ChimeParams {
+    name?: string;
+    /** Volume level (0-4 typical) */
+    volLevel?: number;
+    /** LED state: 0 = off, 1 = on */
+    ledState?: number;
+}
+
 export declare function collectCgiDiagnostics(params: {
     cgi: ReolinkCgiApi;
     channel?: number;
@@ -3417,6 +3473,8 @@ export declare interface DeviceCapabilities {
     isDoorbell: boolean;
     /** True when device supports autotracking (smartTrack in AiCfg). */
     hasAutotracking: boolean;
+    /** True when device is a doorbell (can potentially support wireless chime) or has dingDong abilities explicitly detected. */
+    hasWirelessChime: boolean;
 }
 
 export declare type DeviceCapabilitiesCacheEntry = {
@@ -3449,6 +3507,12 @@ export declare interface DeviceCapabilitiesDebugInfo {
     supportPirSch?: number;
     /** Selected SupportItem chnID */
     supportItemChnID?: number;
+    /** Wireless chime IDs from GetDingDongList (cmd 484) */
+    dingDongListIds?: number[];
+    /** Wireless chime IDs from GetDingDongCfg (cmd 486) */
+    dingDongCfgIds?: number[];
+    /** Error message if chime discovery failed */
+    wirelessChimeError?: string;
 }
 
 export declare interface DeviceCapabilitiesResult {
@@ -3873,6 +3937,8 @@ export declare interface GetRecordingVideoStats {
     hasAudio: boolean;
 }
 
+export declare function getSupportItemForChannel(support: SupportInfo | undefined, channel: number): SupportItem | undefined;
+
 /**
  * Extract client info from HTTP request headers.
  */
@@ -3963,6 +4029,16 @@ export declare class H265RtpDepacketizer {
     push(payload: Buffer): Buffer[];
 }
 
+/** Hardwired (wired-in) chime state from GetDingDongCtrl / SetDingDongCtrl. */
+export declare interface HardwiredChimeState {
+    /** Chime type string (e.g. "dingdong", "single", "dual") */
+    type: string;
+    /** Whether the chime is enabled */
+    enabled: boolean;
+    /** Duration / timing value */
+    time: number;
+}
+
 /**
  * H.265/HEVC Format Converter
  * Converts H.265 data from length-prefixed (HVCC) to Annex-B (start codes).
@@ -4691,6 +4767,11 @@ export declare class ReolinkBaichuanApi {
     private readonly host;
     private readonly username;
     private readonly password;
+    /**
+     * Set to `true` after `close()` is called.
+     * Once closed, the API instance should not be reused.
+     */
+    private _closed;
     /**
      * Socket pool with tag-based allocation strategy.
      * Tags determine which sockets are shared vs dedicated:
@@ -4715,6 +4796,46 @@ export declare class ReolinkBaichuanApi {
      * This getter maintains backward compatibility with existing code that uses `this.client`.
      */
     get client(): BaichuanClient;
+    /**
+     * `true` after `close()` has been called. A closed API should not be reused;
+     * the consumer should create a new instance.
+     */
+    get isClosed(): boolean;
+    /**
+     * `true` when the API is usable: not closed, general socket exists, socket
+     * is connected and the client is logged in.
+     *
+     * This is the recommended way for consumers to check whether the API is
+     * still valid before issuing commands, instead of directly accessing
+     * `api.client.isSocketConnected()` / `api.client.loggedIn` (which throws
+     * if the socket pool was already destroyed).
+     */
+    get isReady(): boolean;
+    /** Promise tracking an in-flight reconnection from `ensureConnected()`. */
+    private _ensureConnectedPromise;
+    /**
+     * Ensure the "general" socket is connected and logged in.
+     * If the socket is disconnected or the pool entry was destroyed, a new
+     * 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}.
+     *
+     * @throws If `close()` was called — the API is permanently closed and a new
+     *         instance must be created.
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Internal: destroy the current general socket (if any), create a new one,
+     * login, and re-attach all listeners.
+     */
+    private reconnectGeneralSocket;
+    /**
+     * Attach event, push, channelInfo, and guard listeners to the current
+     * "general" client.  Called from the constructor and from
+     * {@link reconnectGeneralSocket}.
+     */
+    private setupGeneralClientListeners;
     /**
      * Cached camera UID. May be initially undefined if not provided in the constructor.
      * Will be lazily populated on demand when needed (e.g. for recordings).
@@ -5353,11 +5474,19 @@ export declare class ReolinkBaichuanApi {
      * Minimal per-channel inventory for NVR-connected devices.
      *
      * Intended to be fast: avoids AI/abilities and returns only the common identity + battery hints.
+     *
+     * @param options.source - Data source for the channel list (default: `"cgi"`):
+     *   - `"cgi"`: Uses HTTP `GetChannelstatus` — returns the channel list immediately,
+     *     no dependency on async push messages. Recommended for first-call discovery.
+     *   - `"baichuan"`: Uses the cmd_id 145 push cache populated when the NVR sends channel
+     *     info after login + event subscription. This push is *asynchronous*: if it has not
+     *     arrived yet, the result will have zero channels. Callers must retry (nvr.ts does this
+     *     with a 1-second loop). Note: explicitly requesting cmd_id 145 is not supported.
      */
     getNvrChannelsSummary(options?: {
         channels?: number[];
         timeoutMs?: number;
-        source?: "baichuan" | "cgi";
+        source?: "cgi" | "baichuan";
     }): Promise<NvrChannelsSummaryCacheEntry>;
     /**
      * Group NVR/HUB channels by physical device (best-effort).
@@ -6406,16 +6535,6 @@ export declare class ReolinkBaichuanApi {
      * Clear the device capabilities cache for a specific channel or all channels.
      */
     clearCapabilitiesCache(channel?: number): void;
-    /**
-     * Pick the best SupportItem for a channel.
-     * Prefers items without a name (capability items) over named items (googleHome, amazonAlexa).
-     */
-    private pickBestSupportItem;
-    /**
-     * Parse device capabilities from SupportInfo.
-     * Uses SupportInfo as the single source of truth with AbilityInfo as fallback.
-     */
-    private parseCapabilitiesFromSupport;
     /**
      * Parse support features from SupportInfo.
      */
@@ -7299,6 +7418,119 @@ export declare class ReolinkBaichuanApi {
      * ```
      */
     standaloneGetSnapshot(): Promise<Buffer>;
+    /**
+     * Get the list of paired wireless chime devices.
+     * cmd_id: 484 (GetDingDongList)
+     *
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Array of paired chime devices
+     */
+    getDingDongList(channel?: number): Promise<ChimeDevice[]>;
+    /**
+     * Get parameters (name, volume, LED state) for a specific wireless chime.
+     * cmd_id: 485 (DingDongOpt, option getParam)
+     *
+     * @param chimeId - The chime device ID
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Chime parameters
+     */
+    getDingDongParams(chimeId: number, channel?: number): Promise<ChimeParams>;
+    /**
+     * Set parameters (name, volume, LED state) for a specific wireless chime.
+     * cmd_id: 485 (DingDongOpt, option setParam)
+     *
+     * @param chimeId - The chime device ID
+     * @param params - Parameters to set (volLevel, ledState, name)
+     * @param channel - Channel number (0-based, default 0)
+     */
+    setDingDongParams(chimeId: number, params: {
+        volLevel?: number;
+        ledState?: number;
+        name?: string;
+    }, channel?: number): Promise<void>;
+    /**
+     * Trigger a wireless chime to ring with a specific ringtone.
+     * cmd_id: 485 (DingDongOpt, option ringWithMusic)
+     *
+     * @param chimeId - The chime device ID
+     * @param musicId - The ringtone/music ID to play
+     * @param channel - Channel number (0-based, default 0)
+     */
+    ringDingDong(chimeId: number, musicId: number, channel?: number): Promise<void>;
+    /**
+     * Get the per-event alarm configuration for paired wireless chimes.
+     * cmd_id: 486 (GetDingDongCfg)
+     *
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Array of chime configurations (one per paired chime)
+     */
+    getDingDongCfg(channel?: number): Promise<ChimeCfg[]>;
+    /**
+     * Set the per-event alarm configuration for a specific wireless chime.
+     * cmd_id: 487 (SetDingDongCfg)
+     *
+     * @param chimeId - The chime ring/device ID
+     * @param eventType - Event type string (e.g. "doorbell", "package", "people")
+     * @param state - 0 = disabled, 1 = enabled
+     * @param musicId - Ringtone ID to use for this event type
+     * @param channel - Channel number (0-based, default 0)
+     */
+    setDingDongCfg(chimeId: number, eventType: string, state: 0 | 1, musicId: number, channel?: number): Promise<void>;
+    /** Cache of last known hardwired chime state per channel, used to avoid re-fetching on every set. */
+    private _hardwiredChimeCache;
+    /**
+     * Get the hardwired (wired-in) chime state.
+     * cmd_id: 483 (GetDingDongCtrl)
+     *
+     * Note: calling this may briefly trigger the physical chime to rattle.
+     *
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Hardwired chime state (type, enabled, time)
+     */
+    getHardwiredChime(channel?: number): Promise<HardwiredChimeState>;
+    /**
+     * Set the hardwired (wired-in) chime state.
+     * cmd_id: 483 (SetDingDongCtrl)
+     *
+     * Uses the cached state from a previous getHardwiredChime call to fill in
+     * missing type/time fields, avoiding a double round-trip on every set.
+     * Falls back to fetching if no cache is available.
+     *
+     * @param params - Chime configuration (type, enabled, time)
+     * @param channel - Channel number (0-based, default 0)
+     */
+    setHardwiredChime(params: {
+        type?: string | undefined;
+        enabled: boolean;
+        time?: number;
+    }, channel?: number): Promise<HardwiredChimeState>;
+    /**
+     * Play an audio file on the doorbell / chime device.
+     * cmd_id: 349 (QuickReplyPlay)
+     *
+     * @param fileId - The audio file ID to play
+     * @param channel - Channel number (0-based, default 0)
+     */
+    quickReplyPlay(fileId: number, channel?: number): Promise<void>;
+    /**
+     * Get the silent mode state of a paired wireless chime.
+     * cmd_id: 609 (GetDingDongSilent)
+     *
+     * @param chimeId - The wireless chime device ID (from getDingDongList)
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Wireless chime silent state (time=0 means active/not silenced)
+     */
+    getDingDongSilent(chimeId: number, channel?: number): Promise<WirelessChimeSilentState>;
+    /**
+     * Set the silent mode of a paired wireless chime.
+     * cmd_id: 610 (SetDingDongSilent)
+     *
+     * @param chimeId - The wireless chime device ID (from getDingDongList)
+     * @param time - Silence duration in seconds. 0 = not silenced (chime active), >0 = silenced for this many seconds.
+     * @param channel - Channel number (0-based, default 0)
+     * @returns Updated wireless chime silent state
+     */
+    setDingDongSilent(chimeId: number, time: number, channel?: number): Promise<WirelessChimeSilentState>;
 }
 
 export declare type ReolinkBaichuanChannelIdentity = {
@@ -8779,6 +9011,19 @@ export declare interface WhiteLedState {
     brightness?: number;
 }
 
+/** Wireless chime silent mode state from GetDingDongSilent / SetDingDongSilent. */
+export declare interface WirelessChimeSilentState {
+    /** The wireless chime device ID */
+    id: number;
+    /**
+     * Silent mode duration in seconds.
+     * 0 = not silenced (chime active), >0 = silenced for this many seconds.
+     */
+    time: number;
+    /** Whether the chime is currently active (not silenced). Derived: time === 0 */
+    active: boolean;
+}
+
 export declare function xmlEscape(text: string | undefined | null): string;
 
 declare type XmlJsonObject = {

package/dist/index.js

@@ -29,6 +29,7 @@ import {
   flattenAbilitiesForChannel,
   getConstructedVideoStreamOptions,
   getGlobalLogger,
+  getSupportItemForChannel,
   getVideoStream,
   isDualLenseModel,
   isNvrHubModel,
@@ -37,7 +38,7 @@ import {
   normalizeUid,
   parseSupportXml,
   setGlobalLogger
-} from "./chunk-EHWVA3SG.js";
+} from "./chunk-MN7GUZT7.js";
 import {
   AesStreamDecryptor,
   BC_AES_IV,
@@ -61,6 +62,8 @@ import {
   BC_CMD_ID_COVER_STANDALONE_460,
   BC_CMD_ID_COVER_STANDALONE_461,
   BC_CMD_ID_COVER_STANDALONE_462,
+  BC_CMD_ID_DING_DONG_CTRL,
+  BC_CMD_ID_DING_DONG_OPT,
   BC_CMD_ID_FILE_INFO_LIST_CLOSE,
   BC_CMD_ID_FILE_INFO_LIST_DL_VIDEO,
   BC_CMD_ID_FILE_INFO_LIST_DOWNLOAD,
@@ -84,6 +87,9 @@ import {
   BC_CMD_ID_GET_BATTERY_INFO_LIST,
   BC_CMD_ID_GET_DAY_NIGHT_THRESHOLD,
   BC_CMD_ID_GET_DAY_RECORDS,
+  BC_CMD_ID_GET_DING_DONG_CFG,
+  BC_CMD_ID_GET_DING_DONG_LIST,
+  BC_CMD_ID_GET_DING_DONG_SILENT,
   BC_CMD_ID_GET_EMAIL_TASK,
   BC_CMD_ID_GET_FTP_TASK,
   BC_CMD_ID_GET_HDD_INFO_LIST,
@@ -120,9 +126,12 @@ import {
   BC_CMD_ID_PUSH_SERIAL,
   BC_CMD_ID_PUSH_SLEEP_STATUS,
   BC_CMD_ID_PUSH_VIDEO_INPUT,
+  BC_CMD_ID_QUICK_REPLY_PLAY,
   BC_CMD_ID_SET_AI_ALARM,
   BC_CMD_ID_SET_AI_CFG,
   BC_CMD_ID_SET_AUDIO_TASK,
+  BC_CMD_ID_SET_DING_DONG_CFG,
+  BC_CMD_ID_SET_DING_DONG_SILENT,
   BC_CMD_ID_SET_MOTION_ALARM,
   BC_CMD_ID_SET_PIR_INFO,
   BC_CMD_ID_SET_WHITE_LED_STATE,
@@ -206,7 +215,7 @@ import {
   testChannelStreams,
   xmlEscape,
   zipDirectory
-} from "./chunk-YPU7RAEY.js";
+} from "./chunk-NLTB7GTA.js";
 
 // src/reolink/baichuan/HlsSessionManager.ts
 var withTimeout = async (p, ms, label) => {
@@ -558,8 +567,12 @@ function detectIosClient(userAgent) {
   return {
     isIos,
     isIosInstalledApp,
-    // iOS InstalledApp needs HLS for video playback
-    needsHls: isIos && isIosInstalledApp
+    // ALL iOS clients need HLS for reliable video clip playback.
+    // iOS AVFoundation requires Content-Length + Range support for regular MP4,
+    // but generating the full MP4 upfront takes too long (camera download + transcode).
+    // HLS delivers segments progressively (~3-5s to first frame vs 25+ seconds).
+    // Safari, AVPlayer, and InstalledApp all support HLS natively.
+    needsHls: isIos
   };
 }
 function buildHlsRedirectUrl(originalUrl) {
@@ -7075,6 +7088,8 @@ export {
   BC_CMD_ID_COVER_STANDALONE_460,
   BC_CMD_ID_COVER_STANDALONE_461,
   BC_CMD_ID_COVER_STANDALONE_462,
+  BC_CMD_ID_DING_DONG_CTRL,
+  BC_CMD_ID_DING_DONG_OPT,
   BC_CMD_ID_FILE_INFO_LIST_CLOSE,
   BC_CMD_ID_FILE_INFO_LIST_DL_VIDEO,
   BC_CMD_ID_FILE_INFO_LIST_DOWNLOAD,
@@ -7098,6 +7113,9 @@ export {
   BC_CMD_ID_GET_BATTERY_INFO_LIST,
   BC_CMD_ID_GET_DAY_NIGHT_THRESHOLD,
   BC_CMD_ID_GET_DAY_RECORDS,
+  BC_CMD_ID_GET_DING_DONG_CFG,
+  BC_CMD_ID_GET_DING_DONG_LIST,
+  BC_CMD_ID_GET_DING_DONG_SILENT,
   BC_CMD_ID_GET_EMAIL_TASK,
   BC_CMD_ID_GET_FTP_TASK,
   BC_CMD_ID_GET_HDD_INFO_LIST,
@@ -7134,9 +7152,12 @@ export {
   BC_CMD_ID_PUSH_SERIAL,
   BC_CMD_ID_PUSH_SLEEP_STATUS,
   BC_CMD_ID_PUSH_VIDEO_INPUT,
+  BC_CMD_ID_QUICK_REPLY_PLAY,
   BC_CMD_ID_SET_AI_ALARM,
   BC_CMD_ID_SET_AI_CFG,
   BC_CMD_ID_SET_AUDIO_TASK,
+  BC_CMD_ID_SET_DING_DONG_CFG,
+  BC_CMD_ID_SET_DING_DONG_SILENT,
   BC_CMD_ID_SET_MOTION_ALARM,
   BC_CMD_ID_SET_PIR_INFO,
   BC_CMD_ID_SET_WHITE_LED_STATE,
@@ -7253,6 +7274,7 @@ export {
   getGlobalLogger,
   getH265NalType,
   getMjpegContentType,
+  getSupportItemForChannel,
   getVideoStream,
   getVideoclipClientInfo,
   getXmlText,