@mega-yfue/eufy-sdk 0.2.0-beta.1 → 0.2.0-beta.3

package/dist/model/capabilities/arming.d.ts

@@ -2,11 +2,15 @@ import { type Surface } from "./members.js";
 import type { CapabilityModule, CommandContext } from "./types.js";
 import type { Command } from "../../core/contracts.js";
 /**
- * The guard modes {@link ArmingActions} can SET — the three whose write was captured byte-exact against a
- * real station. `ArmingMode` is both the const value-object (`ArmingMode.home`) and the union type of its
+ * The guard modes `setMode` can SET — the four whose write is confirmed against a real station. Three are
+ * byte-exact captures and `custom1` is a live confirmation; `ARMING_MODE_WIRE` carries the per-value
+ * evidence. `ArmingMode` is both the const value-object (`ArmingMode.home`) and the union type of its
  * values, so callers pass the named constant: `setMode(ArmingMode.home)`.
  *
- * Deliberately NARROWER than the set a device may report. The other six modes are ones the app itself
+ * The domain of `setMode` (cmd 1224) alone. The alarm-delay write (cmd 1255) carries its own mode integer
+ * on a separate wire and takes {@link AlarmDelayMode}.
+ *
+ * Deliberately NARROWER than the set a device may report. The remaining five modes are ones the app itself
  * defines and the `mode` read still names them, but no capture shows one being SENT — and
  * on a fire-and-forget wire a wrong one looks exactly like success. Leaving them out of this union is the
  * compile-time half of the refusal; `mode`'s published argument and the generated rejection are the
@@ -17,10 +21,31 @@ export declare const ArmingMode: {
     readonly away: "away";
     /** Armed for occupancy — reduced/perimeter protection while home (wire value 1). */
     readonly home: "home";
+    /** Custom 1 — a user-defined posture configured in the app (wire value 3). */
+    readonly custom1: "custom1";
     /** Disarmed — no alarms; sensors still report state (wire value 63). */
     readonly disarmed: "disarmed";
 };
 export type ArmingMode = (typeof ArmingMode)[keyof typeof ArmingMode];
+/**
+ * The modes the alarm-delay write (cmd 1255) accepts a `mode_id` for — the three guard modes whose wire
+ * integer is byte-captured.
+ *
+ * A domain of its own, because the two mode integers ride different commands: `setMode` writes `mode_type`
+ * on cmd 1224, and cmd 1255 carries `mode_id`. Neither wire validates the integer, so each union IS its
+ * command's gate, and evidence for one is not evidence for the other. `custom1` is confirmed on 1224 only;
+ * 1255 has no capture carrying mode 3, and no known GET to read one back — the app's own replies
+ * `{count:0,data:null}` — so it is absent here. Narrower than {@link ArmingMode} by exactly that value.
+ */
+export declare const AlarmDelayMode: {
+    /** Armed — full protection, nobody home (wire value 0). */
+    readonly away: "away";
+    /** Armed for occupancy — reduced/perimeter protection while home (wire value 1). */
+    readonly home: "home";
+    /** Disarmed — no alarms; sensors still report state (wire value 63). */
+    readonly disarmed: "disarmed";
+};
+export type AlarmDelayMode = (typeof AlarmDelayMode)[keyof typeof AlarmDelayMode];
 /**
  * The P2P **feature-command ids** this arming capability drives. Capability-owned wire vocabulary
  * (transport forwards `cmd.param` opaquely; full id→name catalog in the generated
@@ -34,10 +59,11 @@ export declare const ARMING_CMD: {
      * mValue3:0, `payload:{mode_type:<int>, user_name:<string>}`.
      *
      * ⚠️ Only 3 of the 9 modes were exercised in that capture — `mode_type` 0 (away), 63 (disarmed), 1
-     * (home), all confirmed byte-exact, and those three are the whole of {@link ArmingMode}. Re-confirmed
-     * live 2026-08-05: each reported its own MODE_SWITCH push within ~5s of the write. The remaining six are
-     * named by the app but never observed leaving it, so this capability reads them and refuses to send
-     * them. See `ARMING_MODE_WIRE` for the per-value breakdown.
+     * (home), all confirmed byte-exact. Re-confirmed live 2026-08-05: each reported its own MODE_SWITCH push
+     * within ~5s of the write. `custom1` 3 joined {@link ArmingMode} on a live confirmation rather than a
+     * capture, making four settable in total. The remaining five are named by the app but never observed
+     * leaving it, so this capability reads them and refuses to send them. See `ARMING_MODE_WIRE` for the
+     * per-value breakdown.
      */
     readonly SET_ARMING: 1224;
     /**
@@ -139,9 +165,9 @@ export type ArmingActions = Surface<typeof ARMING_MEMBERS>;
 export declare const ARMING_MEMBERS: {
     /**
      * The one member whose write domain is NARROWER than its read: `enumValues` names all nine modes a
-     * station can report, and the argument's `values` publishes only the three whose wire was captured. That
-     * argument IS the domain the derived setter enforces and the refusal names, so an uncaptured mode is
-     * refused by naming the three that work — nine labels for the read and three for the write, off one
+     * station can report, and the argument's `values` publishes only the four whose write is confirmed. That
+     * argument IS the domain the derived setter enforces and the refusal names, so an unconfirmed mode is
+     * refused by naming the four that work — nine labels for the read and four for the write, off one
      * declaration.
      *
      * `armingCommand` may also throw synchronously (missing account identity) and `bindMembers` turns that
@@ -187,15 +213,17 @@ export declare const ARMING_MEMBERS: {
      * this mode — there is no known GET to fetch it automatically, and a wrong guess here can silently
      * misconfigure which sensors arm/trigger for real.
      *
-     * Takes {@link ArmingMode}, so a delay can only be configured for a mode whose `mode_id` integer is
-     * captured. The frame carries that same integer, so a schedule/custom mode would be the identical guess
-     * `setMode` refuses.
+     * Takes {@link AlarmDelayMode}, not {@link ArmingMode}: a delay is configurable only for a mode whose
+     * integer is captured on THIS command, and `custom1` is confirmed on cmd 1224 only. The frame carries
+     * that integer in `mode_id` with no runtime validation and no readback, so a mode outside this union
+     * would be the same unverified guess `setMode` refuses.
      */
-    readonly setAlarmDelayConfig: import("./members.js").MethodMember<(mode: ArmingMode, config: AlarmDelayConfig) => Promise<void>>;
+    readonly setAlarmDelayConfig: import("./members.js").MethodMember<(mode: AlarmDelayMode, config: AlarmDelayConfig) => Promise<void>>;
 };
 /**
  * `arming` — guard/arming mode. `armingMode` (see {@link ARMING_CMD.SET_ARMING}) has a verified
- * read/write MECHANISM, but only 3 of its 8 {@link ArmingMode} values (away/home/disarmed) are
- * wire-captured — see `ARMING_MODE_WIRE` for which 5 are still unverified third-party integers.
+ * read/write MECHANISM, but only 4 of the 9 modes it reports (away/home/custom1/disarmed, the
+ * {@link ArmingMode} union) are confirmed as writes — see `ARMING_MODE_WIRE` for which 5 are still
+ * unverified third-party integers, and which of the 4 is live-confirmed rather than byte-captured.
  */
 export declare const ARMING: CapabilityModule;

package/dist/model/capabilities/index.d.ts

@@ -385,7 +385,7 @@ export interface DeviceActionMap {
     lock: LockActions;
     /** Siren: reads `active`, `volume`, `alarmDuration`, `doNotDisturb`; writes `setVolume`, `setAlarmDuration`, `test`, `stop` (config setters present when the param is reported). No direct "sound the alarm" wire — a real alarm is driven by the `arming` system; `test` is the on-demand trigger. */
     siren: SirenActions;
-    /** Guard mode: `setMode(ArmingMode)` + `setAlarmDelayConfig(mode, config)`. Of the 8 `ArmingMode` values only `away`/`home`/`disarmed` are confirmed on-device. */
+    /** Guard mode: `setMode(ArmingMode)` + `setAlarmDelayConfig(mode, config)`. Of the 9 modes a station reports, only `away`/`home`/`custom1`/`disarmed` are confirmed as writes (`ArmingMode`); the alarm-delay write takes the narrower byte-captured `AlarmDelayMode`. */
     arming: ArmingActions;
     /** Doorbell: `playQuickResponse(voiceId)` (the canned voice replies). */
     doorbell: DoorbellActions;
@@ -555,7 +555,7 @@ export type { VacuumActivity, VacuumCleanType, CarpetStrategy, CleanExtent } fro
 export { VACUUM_ACTIVITIES, VACUUM_CLEAN_TYPES, CARPET_STRATEGIES, CLEAN_EXTENTS, MOP_LEVELS } from "./vacuum-clean.js";
 export { SuctionLevel, suctionLevelName, type SuctionLevelValue } from "./suction.js";
 export type { PtzPresetActions, ZoomRegion, PtzPreset, PtzPresetImage } from "./ptz.js";
-export { ArmingMode } from "./arming.js";
+export { AlarmDelayMode, ArmingMode } from "./arming.js";
 export type { AlarmDelayConfig, AlarmDelayCountdown, AlarmDelayDeviceAction, AlarmDelaySeconds } from "./arming.js";
 export { PtzDirection } from "./ptz.js";
 export { AiDetectType, encodeAiDetectType, decodeAiDetectType, type AiDetectFlags } from "./motion.js";

package/dist/transport/p2p/command-router.d.ts

@@ -18,6 +18,23 @@ import type { FfmpegLevel } from "../ffmpeg.js";
 import { SharedLiveSource } from "./shared-live-source.js";
 import { type PowerTier, type SessionManagerOpts } from "./session-manager.js";
 import { FragmentRecording } from "./fragment-recording.js";
+/**
+ * What a caller's own deadline on a station call has to clear, in milliseconds.
+ *
+ * A caller that bounds one of these calls itself races these waits, and a bound below them reports the
+ * caller's own expiry in place of the reason this SDK was about to give — the two are indistinguishable to
+ * whoever reads the outcome, and they call for different next steps. Published so that bound can be derived
+ * rather than copied: a literal in a caller's source is a second source of truth that goes stale silently
+ * when these change.
+ *
+ * `connect` applies to every call on a station, because nothing can be addressed to one before its session is
+ * up. `level2Grace` applies twice where the key is required: the negotiation is re-prompted once.
+ */
+export declare const P2P_STATION_WAITS: {
+    readonly connect: 20000;
+    readonly level2Grace: 25000;
+    readonly level2Settle: 8000;
+};
 /**
  * Options accepted when warming a {@link SharedLiveSource} for a device (all optional).
  *
@@ -90,6 +107,12 @@ export declare class P2PCommandRouter {
     constructor(deps: P2PRouterDeps);
     /** Forward one P2P failure once even when both the session listener and startup waiter observe it. */
     private reportError;
+    /**
+     * Emit a live trace under a station session's handle, for work this router does ON that session before
+     * the session itself records anything — reaching the station, and resolving what a device is on it. Same
+     * handle as everything the session goes on to trace, which is what groups one attempt.
+     */
+    private traceOnStation;
     /**
      * Whether this transport stack drives `dev`'s `ff09-*` commands — true when the device has its own
      * usable P2P endpoint (a non-empty `p2p_did`). The command sink asks each stack this to route a

package/dist/transport/p2p/index.d.ts

@@ -10,4 +10,5 @@ export * from "./envelope.js";
 export * from "./write-commands.js";
 export * from "./lan-ip.js";
 export { LIVE_TRACE_MESSAGE, type LiveTrace } from "./live-trace.js";
+export { P2P_STATION_WAITS } from "./command-router.js";
 export * as p2pCodec from "./codec.js";

package/dist/transport/p2p/live-trace.d.ts

@@ -63,12 +63,37 @@ export type LiveTrace =
     phase: "sequence-restart";
     dataType: number;
 }
+/**
+ * Work on a station is holding for its session to connect, with the milliseconds it will wait.
+ *
+ * The earliest phase there is: nothing else on a station can be attempted until its session is up, and a
+ * caller whose own deadline expires inside this wait has this record and no other. Emitted only where a wait
+ * actually happens, so its absence states that the session was already connected.
+ */
+ | {
+    phase: "session-connect-wait";
+    waitMs: number;
+}
+/** The session connected, after this long. */
+ | {
+    phase: "session-connected";
+    waitedMs: number;
+}
+/**
+ * The session did not connect within its wait, so nothing on this station can be attempted.
+ *
+ * The one outcome that is otherwise indistinguishable from a station that answered and then refused: both
+ * leave a caller with no media and no phase naming a station.
+ */
+ | {
+    phase: "session-unreachable";
+    waitedMs: number;
+}
 /**
  * A live start is holding for the station's level-2 key, with the milliseconds it will wait.
  *
- * The first of three phases that account for the wait before any media command is sent. A start that looks
- * slow is either waiting here, waiting for the station to serve the channel it was asked for, or being
- * re-issued — and only these separate them.
+ * A start that looks slow is either waiting here, waiting for its session to connect, waiting for the station
+ * to serve the channel it was asked for, or being re-issued — and only these phases separate them.
  */
  | {
     phase: "level2-wait";
@@ -79,10 +104,63 @@ export type LiveTrace =
     phase: "level2-ready";
     cipherId: number;
 }
-/** The level-2 key did not arrive in its grace, so the start proceeds at level 1 or not at all. */
+/**
+ * The station's key is not coming, why, and the cipher where a station named one.
+ *
+ * Every ending of a level-2 wait carries one of these reasons, so a start refused for want of a key is
+ * accounted for however it ended. `grace-elapsed` is a wait that ran out and states how long was waited;
+ * the rest are answered without waiting, because the negotiation is one-shot per connection and a
+ * concluded one is final. `no-cipher-key` and `derivation-failed` are about this account's cipher
+ * material, `not-negotiating` and `session-closed` about the station or its connection — and only a
+ * reason reached under a negotiation has a cipher to name.
+ *
+ * A `grace-elapsed` start proceeds at level 1 where it has such a form, and not at all where it does not.
+ */
+ | {
+    phase: "level2-unavailable";
+    reason: "no-cipher-key" | "derivation-failed" | "not-negotiating" | "session-closed" | "grace-elapsed";
+    cipherId?: number;
+    waitedMs?: number;
+}
+/**
+ * A station's cipher was answered with material for a DIFFERENT cipher, which was used in its place.
+ *
+ * The one lookup outcome no other phase accounts for: material for the cipher the station named is followed
+ * by `level2-ready` or by `level2-unavailable` with `derivation-failed`, an answer holding none by
+ * `no-cipher-key`, and a lookup that threw is reported as an error. Substituted material derives to
+ * nothing and otherwise reads as a station fault. `cipherId` is the cipher the station asked for,
+ * `answeredCipherId` the one whose material was used.
+ */
+ | {
+    phase: "cipher-fallback";
+    cipherId: number;
+    answeredCipherId: number;
+}
+/**
+ * The station answered its gateway-info prompt, so a key derivation has begun under the cipher it named.
+ *
+ * What separates a station that never answered the prompt from one that answered and produced no usable key:
+ * without it, `level2-unavailable` with `not-negotiating` covers both, and they are a station or network
+ * problem and an account cipher-material problem respectively.
+ */
  | {
-    phase: "level2-absent";
-    waitedMs: number;
+    phase: "level2-negotiating";
+    cipherId: number;
+}
+/**
+ * A station was resolved for a call, stating what the caller's device is on it and whose station it is.
+ *
+ * Emitted before anything is sent, so it is the only account of the intended topology on a call that fails
+ * during resolution: an attached camera's media start has no unencrypted form, so whether a device was taken
+ * as attached decides what its failure means. `stationAdmin` states whether the signed-in account is the
+ * station's administrator, which is what a key the account cannot resolve turns on; `unstated` is a device
+ * record that names no administrator, which is not the same as naming another.
+ */
+ | {
+    phase: "station-resolved";
+    topology: "attached" | "own";
+    channel: number;
+    stationAdmin: "self" | "other" | "unstated";
 }
 /** A shared source began warming, with the interval it re-issues on and the deadline it fails at. */
  | {

package/dist/transport/p2p/p2p-session.d.ts

@@ -208,6 +208,10 @@ export declare class P2PSession extends EventEmitter {
      * cameras from that second group streamed normally at level-1 — including one of the same firmware as an
      * own-session camera that delivered no video at all for a reason of its own. An expired grace therefore
      * separates nothing on this path, and a start failure on such a session is not evidence about it.
+     *
+     * Every `false` answer carries a `level2-unavailable` trace naming its reason, wherever the wait ended: a
+     * `terminal` outcome is the one already stated where the negotiation concluded, since that is where the
+     * cipher and the cause are known, and re-stating it here would double every settled negotiation.
      */
     awaitLevel2Key(graceMs: number, graceFrom?: "call" | "session"): Promise<boolean>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "description": "One typed TypeScript client for the Anker eufy v6 cloud — capability-driven devices, realtime events over P2P/MQTT/push, and live media",
   "license": "Apache-2.0",
   "author": "mega-yfue",