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

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

@@ -15266,6 +15266,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 +16538,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 +16608,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 +25472,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 +25634,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 +27081,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.