@mega-yfue/eufy-sdk 0.4.0-beta.16 → 0.4.0-beta.18

package/dist/client/eufy-mega.d.ts

@@ -20,8 +20,8 @@ import { type P2PSession } from "../transport/p2p/p2p-session.js";
 import { type CleanRecordPage } from "../model/clean-records.js";
 import { type AvailabilityObservation, type EufyDevice } from "../core/types.js";
 import { Device, type DeviceInspection } from "../model/index.js";
-import type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, DeviceState, RealtimeReadiness, WaitForRealtimeOptions } from "./types.js";
-export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, WaitForRealtimeOptions, } from "./types.js";
+import type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, DeviceState, RealtimeReadiness, StationFace, StationFacesOptions, WaitForRealtimeOptions } from "./types.js";
+export type { EufyMegaOptions, EufyMegaEvent, EufyMegaEventMap, AnyDeviceEvent, DeviceState, RealtimePlaneReadiness, RealtimeReadiness, StationFace, StationFacesOptions, WaitForRealtimeOptions, } from "./types.js";
 export interface EufyMega {
     on<E extends EufyMegaEvent>(event: E, listener: (...args: EufyMegaEventMap[E]) => void): this;
     once<E extends EufyMegaEvent>(event: E, listener: (...args: EufyMegaEventMap[E]) => void): this;
@@ -764,6 +764,22 @@ export declare class EufyMega extends EventEmitter {
      * every event the station's own session already delivers.
      */
     getP2pSessions(): Map<string, P2PSession>;
+    /**
+     * The people enrolled on a station, read from its own `person_basic_info` table over P2P.
+     *
+     * The cloud roster (`api.getFaces()`) answers empty for an account that keeps its faces on the
+     * station, because they were never uploaded — the station holds them.
+     *
+     * Resolves with the rows the station returned. Rejects on a station that cannot be reached, on a
+     * record stating no `admin_user_id`, and on the reply not arriving whole in time. Assembling that
+     * reply is `P2PSession.readDatabase`'s; this resolves which station and which account id.
+     *
+     * `stranger<n>` names are the station's own placeholders for a face nobody has named, and are
+     * returned as they arrive; a caller that wants only named people filters them.
+     */
+    getStationFaces(stationSn: string, opts?: StationFacesOptions): Promise<StationFace[]>;
+    /** The station's own `admin_user_id`, which its database refuses the query without. */
+    private adminUserIdOf;
     /**
      * The liveness facts for one device — see {@link DeviceState}. Facts, not an `online` verdict: "how
      * long is too long" is a threshold that belongs to the caller, and it differs per device class.

package/dist/client/types.d.ts

@@ -221,6 +221,31 @@ export interface DeviceState {
      */
     lastSeenMs?: number;
 }
+/**
+ * One person enrolled on a station, as its `person_basic_info` table states them.
+ *
+ * The station's own table, not the cloud's: an account that keeps its faces on the station never
+ * uploaded them, so the cloud roster answers empty for it while this answers the household.
+ *
+ * `person_id` is the id an `IDENTITY_PERSON_DETECTION` push carries, which is what makes a detection
+ * nameable. Every field is optional because the row is the station's to shape — an absent one is a
+ * column that row did not carry, never a default — and unrecognised columns are kept verbatim, so a
+ * station that states more than this is not truncated by it. Keys are the table's own, uncased.
+ */
+export interface StationFace {
+    person_id?: number;
+    /** The name this person was enrolled under. `stranger<n>` is the station's own placeholder. */
+    name?: string;
+    relation?: number | string;
+    group_id?: number | string;
+    [column: string]: unknown;
+}
+/** How long to wait for a station's database reply, and how to give up early. */
+export interface StationFacesOptions {
+    /** Default 15s. A full table is a handful of frames; a station that will not answer says nothing. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
 /**
  * A single semantic event tagged with its name — the payload of the catch-all `"event"` listener.
  * A discriminated union over {@link DeviceEventMap}, so switching on `e.eventName` narrows `e` to that

package/dist/index.js

@@ -3955,7 +3955,6 @@ var MOTION_CMD = {
    * payload key AND pass mChannel 0 explicitly; the two are separate choices, not linked.)
    *
    * ⚠️ Replay + readback confirmed on a HomeBase-attached T8425 (1719 `0`→`1`→`0`), NOT byte-captured.
-   * Provenance is `apk`, not `verified`: a divergent-but-also-accepted frame can't be ruled out.
    */
   HUMAN_ONLY_AT_NIGHT: 1719,
   /**
@@ -3969,7 +3968,7 @@ var MOTION_CMD = {
    * form, so a feature that is on reads as off.
    * Decoded by {@link decodeRadarWdSwitch} to match the app.
    *
-   * ⚠️ Replay + readback confirmed on a T8214 (2706 `0`→`1`→`0`), NOT byte-captured. Provenance `apk`.
+   * ⚠️ Replay + readback confirmed on a T8214 (2706 `0`→`1`→`0`), NOT byte-captured.
    */
   LOITERING_DETECTION: 2706,
   /**
@@ -4293,7 +4292,7 @@ var MOTION_MEMBERS = {
     param: MOTION_CMD.HUMAN_ONLY_AT_NIGHT,
     type: "bool",
     kind: "boolean",
-    provenance: "apk",
+    provenance: "verified",
     description: "Restrict AI classification to night-time only (1719). \u26A0\uFE0F Replay + readback confirmed on a HomeBase-attached T8425, not byte-captured.",
     requires: [MOTION_CMD.HUMAN_ONLY_AT_NIGHT],
     write: (v, ctx) => {
@@ -4309,7 +4308,7 @@ var MOTION_MEMBERS = {
     param: MOTION_CMD.LOITERING_DETECTION,
     type: "bool",
     kind: "boolean",
-    provenance: "apk",
+    provenance: "verified",
     coerce: (raw) => decodeRadarWdSwitch(raw) ?? false,
     description: "Loitering detection \u2014 alert on lingering rather than passing (2706). Observed on the T8214 doorbell only; the read is object-OR-scalar, matching the app's own decode.",
     requires: [MOTION_CMD.LOITERING_DETECTION],
@@ -6889,9 +6888,9 @@ function parseQuickResponses(voiceList) {
 var DOORBELL_MEMBERS = {
   /**
    * The HOMEBASE as the doorbell's chime — the hub plays the ring, not the wired chime box
-   * `mechanicalChimeSwitch` drives. `provenance` is "verified" on our own decrypt of the app's frame,
-   * not merely the param id observed live: direct-binary `[ch][value][acct]`, 1=on/0=off, the same shape
-   * as its 1703 sibling — captured, not inferred from the shared param range.
+   * `mechanicalChimeSwitch` drives. `provenance` is "verified" on our own decrypt of the app's frame:
+   * direct-binary `[ch][value][acct]`, 1=on/0=off, the same shape as its 1703 sibling — captured, not
+   * inferred from the shared param range.
    */
   chimeSwitch: {
     param: DOORBELL_CMD.CHIME_SWITCH,
@@ -6902,9 +6901,8 @@ var DOORBELL_MEMBERS = {
     write: (v, ctx) => setScalar(DOORBELL_CMD.CHIME_SWITCH, asBool(v) ? 1 : 0, ctx, "direct-binary")
   },
   /**
-   * `provenance` is "verified" not "mega": the actual write wire is confirmed (
-   * our own P2P decrypt), not merely the param id observed on a live device. Direct-binary
-   * `[ch][value][acct]`, 1=on/0=off — verified live on a T8214 (ON then OFF).
+   * `provenance` is "verified" on our own P2P decrypt of the write wire: direct-binary
+   * `[ch][value][acct]`, 1=on/0=off, verified live on a T8214 (ON then OFF).
    */
   mechanicalChimeSwitch: {
     param: DOORBELL_CMD.MECHANICAL_CHIME_SWITCH,
@@ -6935,7 +6933,7 @@ var DOORBELL_MEMBERS = {
     type: "number",
     unit: "%",
     kind: "percent",
-    provenance: "mega",
+    provenance: "verified",
     writtenElsewhere: true,
     description: "Ringtone volume (1708; confirmed on T8214, observed value 80). The WRITE is `audio`'s setRingtoneVolume \u2014 that capability owns every volume wire."
   },
@@ -7040,7 +7038,7 @@ var DOORBELL_MEMBERS = {
     param: 1710,
     type: "string",
     kind: "text",
-    provenance: "mega",
+    provenance: "verified",
     description: "Notification config JSON {notification_motion_onoff,notification_ring_onoff,notification_style} (1710; confirmed on T8214)."
   },
   /**
@@ -15266,6 +15264,49 @@ function paramReport(payload) {
   return Object.keys(out).length ? out : void 0;
 }
 var traceSequence = 0;
+var DB_TABLE_TIMEOUT_MS = 15e3;
+function firstTableRows(text2) {
+  const decoded = Buffer.from(text2, "latin1").toString("utf8");
+  for (let start = decoded.indexOf("{"); start >= 0; start = decoded.indexOf("{", start + 1)) {
+    const end = closingBrace(decoded, start);
+    if (end < 0)
+      return void 0;
+    let parsed;
+    try {
+      parsed = JSON.parse(decoded.slice(start, end + 1));
+    } catch {
+      continue;
+    }
+    const data = parsed?.data;
+    if (Array.isArray(data))
+      return data;
+  }
+  return void 0;
+}
+function closingBrace(text2, start) {
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text2.length; i++) {
+    const c = text2[i];
+    if (inString) {
+      if (escaped)
+        escaped = false;
+      else if (c === "\\")
+        escaped = true;
+      else if (c === '"')
+        inString = false;
+      continue;
+    }
+    if (c === '"')
+      inString = true;
+    else if (c === "{")
+      depth++;
+    else if (c === "}" && --depth === 0)
+      return i;
+  }
+  return -1;
+}
 var P2PSession = class _P2PSession extends EventEmitter2 {
   cfg;
   socket;
@@ -16495,8 +16536,14 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
    * The HomeBase streams back `CMD_DATABASE` (1306) frames `{cmd:10000,count,data:[…]}`,
    * level-1-encrypted — decoded and emitted as `dbChunk` (decrypted text) per frame.
    * Tables: `familiar_faces`, `person_basic_info`, `event_person_list`, `history_record_info`.
+   *
+   * Throws while a {@link readDatabase} is accumulating: every table answers `{data:[…]}` and the
+   * frames tie no chunk to its request, so a second query's reply would be assembled into the first
+   * one's buffer and answered as its rows.
    */
   queryDatabase(table, opts = {}) {
+    if (this.dbReadInFlight)
+      throw new Error(`queryDatabase: ${this.cfg.stationSn} is already reading a table`);
     if (!this.connectAddress)
       throw new Error("not connected");
     const channel = opts.channel ?? STATION_CHANNEL3;
@@ -16559,6 +16606,49 @@ var P2PSession = class _P2PSession extends EventEmitter2 {
       query: this.fullTableQuery()
     });
   }
+  /**
+   * Query one on-station table and answer its rows, once the reply is whole.
+   *
+   * The request half of {@link queryDatabase} with its reply assembled: `CMD_DATABASE` arrives as
+   * several frames whose decrypted text is a fragment of one document, so the fragments are
+   * accumulated here and scanned after each one. Answers that document's `data` rows. Rejects when
+   * `signal` aborts, and when `timeoutMs` (default {@link DB_TABLE_TIMEOUT_MS}) elapses with no
+   * complete reply.
+   *
+   * One read at a time per session: while one is accumulating, every {@link queryDatabase} on the
+   * session throws, so a second reply cannot land in this buffer.
+   */
+  async readDatabase(table, opts = {}) {
+    if (opts.signal?.aborted)
+      throw new Error("readDatabase: aborted");
+    this.queryDatabase(table, { accountId: opts.accountId, query: this.fullTableQuery() });
+    this.dbReadInFlight = true;
+    try {
+      return await new Promise((resolve, reject) => {
+        let text2 = "";
+        const onChunk = (chunk) => {
+          text2 += chunk.text;
+          const rows = firstTableRows(text2);
+          if (rows)
+            settle(() => resolve(rows));
+        };
+        const timer = setTimeout(() => settle(() => reject(new Error(`readDatabase: ${this.cfg.stationSn} sent no complete ${table}`))), opts.timeoutMs ?? DB_TABLE_TIMEOUT_MS);
+        const onAbort = () => settle(() => reject(new Error("readDatabase: aborted")));
+        const settle = (finish) => {
+          clearTimeout(timer);
+          this.off("dbChunk", onChunk);
+          opts.signal?.removeEventListener("abort", onAbort);
+          finish();
+        };
+        this.on("dbChunk", onChunk);
+        opts.signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    } finally {
+      this.dbReadInFlight = false;
+    }
+  }
+  /** Whether a {@link readDatabase} is accumulating; see {@link queryDatabase} for what it bars. */
+  dbReadInFlight = false;
   /**
    * Request the **face feature rows** over P2P (`face_feature_info`, inner `cmd 10000`). Each row
    * carries `{person_id, face_name, face_id, face_picture_content, face_feature_file_path}` — where
@@ -25380,6 +25470,11 @@ function recordString(raw, key) {
   const v = typeof nested === "string" && nested ? nested : raw[key];
   return typeof v === "string" && v ? v : void 0;
 }
+function adminUserIdFrom(raw) {
+  const member = (raw ?? {}).member;
+  const id = member?.admin_user_id;
+  return typeof id === "string" && id ? id : void 0;
+}
 function tuyaDevIdFrom(raw) {
   for (const field of ["tuya_uuid", "tuya_virtual_id", "tuya_device_id", "virtualId"]) {
     const v = recordString(raw, field);
@@ -25537,13 +25632,7 @@ var EufyMega = class extends EventEmitter9 {
       onError: (e) => this.reportError(e),
       // The `a2` account id an `eufy_life` DP frame embeds — the owning member's `admin_user_id`,
       // falling back to the logged-in account's user id (the confirmed script path does the same).
-      resolveAccountId: (dev) => {
-        const member = (dev.raw ?? {}).member;
-        const adminId = member?.admin_user_id;
-        if (typeof adminId === "string" && adminId)
-          return adminId;
-        return this.mega.auth?.userId ?? "";
-      },
+      resolveAccountId: (dev) => adminUserIdFrom(dev.raw) ?? this.mega.auth?.userId ?? "",
       // Fetch + parse a gallery effect from the HTTP catalogue into the serializable spec. The catalogue
       // lives in the http layer (transport/http/light-catalog); the mqtt router owns the frame bytes.
       resolvePreset: (presetId) => resolveLightEffect(this.mega, presetId),
@@ -26990,6 +27079,37 @@ var EufyMega = class extends EventEmitter9 {
   getP2pSessions() {
     return this.p2p.getSessions();
   }
+  /**
+   * The people enrolled on a station, read from its own `person_basic_info` table over P2P.
+   *
+   * The cloud roster (`api.getFaces()`) answers empty for an account that keeps its faces on the
+   * station, because they were never uploaded — the station holds them.
+   *
+   * Resolves with the rows the station returned. Rejects on a station that cannot be reached, on a
+   * record stating no `admin_user_id`, and on the reply not arriving whole in time. Assembling that
+   * reply is `P2PSession.readDatabase`'s; this resolves which station and which account id.
+   *
+   * `stranger<n>` names are the station's own placeholders for a face nobody has named, and are
+   * returned as they arrive; a caller that wants only named people filters them.
+   */
+  async getStationFaces(stationSn, opts = {}) {
+    if (!this.registry.list().length)
+      await this.getDevices();
+    const station = this.p2p.stationKeyOf(stationSn);
+    const accountId = this.adminUserIdOf(station);
+    if (!accountId)
+      throw new Error(`getStationFaces: no admin_user_id on record for ${station}`);
+    await this.p2p.ensureStation(station, opts.signal);
+    const session = this.p2p.getSessions().get(station);
+    if (!session)
+      throw new Error(`getStationFaces: no P2P session for ${station}`);
+    const rows = await session.readDatabase("person_basic_info", { accountId, ...opts });
+    return rows.filter((row) => typeof row === "object" && row !== null);
+  }
+  /** The station's own `admin_user_id`, which its database refuses the query without. */
+  adminUserIdOf(stationSn) {
+    return adminUserIdFrom(this.registry.list().find((d) => d.sn === stationSn)?.raw);
+  }
   /**
    * The liveness facts for one device — see {@link DeviceState}. Facts, not an `online` verdict: "how
    * long is too long" is a threshold that belongs to the caller, and it differs per device class.