@mega-yfue/eufy-sdk 0.2.0-beta.11 → 0.2.0-beta.13

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

@@ -90,8 +90,33 @@ export type BatteryActions = Surface<typeof BATTERY_MEMBERS>;
  * The richer raw `APP_CMD_SET_POWER_SOURCE` blob is a separate param, surfaced as `powerSourceInfo`.
  */
 declare function decodePowerSource(raw: string | number | boolean): number | string;
-/** False for a mains camera that only reports 1101 as a sentinel — used to gate the physical reads. */
-declare const notMainsCamera: (ctx: AvailabilityContext) => boolean;
+/**
+ * The params whose subject IS the physical cell — so every member reading one must carry
+ * {@link notMainsCamera}.
+ *
+ * The ONE place that fact is declared. {@link cellGated} applies {@link notMainsCamera} from this list
+ * when the table is built, so a member never states the gate itself: adding a cell read is adding its
+ * param here, and there is no second place for it to be missing from. A per-member `available` was the
+ * alternative and is what the first two passes of this guard got wrong, in both directions — first by
+ * covering two of the seven, then by reading `unexposed` as covering a third.
+ *
+ * What is NOT here matters as much.
+ *
+ *  - `workingMode` and the three `record*` settings describe how hard the camera works, not what powers
+ *    it, and a mains camera genuinely has them. They are the reason the capability stays attached.
+ *  - `cameraInfo` (1103) is a number whose meaning is unevidenced. Gating it would assert it is a
+ *    battery fact, which is the kind of claim this guard exists to stop making.
+ *  - `powerSource` (1293) is the open one. Both values it names — `Battery` and `External Solar Panel` —
+ *    describe how a CELL is fed, so by this list's own rule it arguably belongs here. It is out because
+ *    every param above is one a live mains camera was observed to publish and 1293 was not among them,
+ *    and because it is `requires`-gated on its own param, so it appears only where the device reports
+ *    it. Gating it would also withhold a described WRITE rather than a read, which is a different class
+ *    of change. Unresolved rather than decided: see the note in the pull request.
+ *
+ * The two solar params ARE here: a panel exists to charge a cell, so a device without one has no solar
+ * harvest to report either.
+ */
+export declare const CELL_PARAMS: readonly number[];
 /**
  * Every `battery` feature, declared once — the property schema, the evidence-gated getters, the derived
  * setters, the intent routes and the descriptions all come out of this table. Order is schema order.
@@ -117,7 +142,6 @@ export declare const BATTERY_MEMBERS: {
         readonly unit: "%";
         readonly kind: "percent";
         readonly provenance: "verified";
-        readonly available: typeof notMainsCamera;
         readonly description: "Battery level 0-100 (verified: param 1101).";
     };
     /**
@@ -130,7 +154,6 @@ export declare const BATTERY_MEMBERS: {
         readonly type: "bool";
         readonly kind: "boolean";
         readonly provenance: "apk";
-        readonly available: typeof notMainsCamera;
         readonly coerce: (v: string | number | boolean) => boolean;
         readonly description: string;
     };
@@ -300,6 +323,11 @@ export declare const BATTERY_MEMBERS: {
      * Reported, so it stays in the schema and answers through `getProperty` — but given no typed getter:
      * the payload's fields have never been decoded, and a getter would hand back an opaque blob typed as
      * though it meant something.
+     *
+     * `unexposed` is NOT a substitute for the cell gate. It suppresses the fluent GETTER; `propertiesOf`
+     * filters `writeOnly` and `available` and deliberately not `unexposed`, because a schema entry
+     * reachable through `getProperty` is the whole point of the mark. So a cell param needs
+     * {@link CELL_PARAMS} either way, or a mains camera publishes "battery power history" and answers it.
      */
     readonly batteryPowerStats: {
         readonly param: 3100;

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

@@ -54,6 +54,15 @@ export declare function getCapabilityModule(cap: Capability): CapabilityModule |
  * @internal
  */
 export declare const CAPABILITY_MODULES: Record<Capability, CapabilityModule>;
+/**
+ * Every param these capabilities declare before any gate — the set a device's schema is a subset of.
+ *
+ * A param in here that a device's schema does NOT carry is one a gate withheld: the capability resolved,
+ * and its member decided the read does not describe this device — a cell reading on a mains model, a mode
+ * a family does not carry. Read-aliases count, since a member reads them under its own name.
+ * @internal
+ */
+export declare function claimedParams(caps: Capability[]): Set<number>;
 /**
  * Merge the property schemas of several capabilities into one flat, de-duplicated list.
  *

package/dist/model/device.d.ts

@@ -62,6 +62,11 @@ export declare class Device {
      * different wire ids across device families still resolves to one named value.
      */
     private specByParam;
+    /**
+     * Params a resolved capability declares that this device's schema does not carry — withheld by a
+     * member's gate, so not named from the param dictionary either. See {@link Device.applyParams}.
+     */
+    private withheld;
     /** Which param namespace this device's ids live in (clean DPs vs security P2P). */
     private namespace;
     /** The record's `device_name` as stated, before the {@link modelName} fallback is applied. */
@@ -201,6 +206,16 @@ export declare class Device {
      * Apply a raw param map (cloud record or P2P notification). Known params update their named
      * property; unrecognised params are retained as `unknown_<paramType>` so nothing is lost.
      *
+     * Naming precedence: this device's own `PropertySpec` (curated), then the param dictionary for its
+     * namespace, then the `unknown_<paramType>` passthrough. The dictionary def is consulted even where a
+     * spec exists, because `encoding` lives there.
+     *
+     * A param a resolved capability's gate WITHHELD takes the passthrough instead of its dictionary name.
+     * The gate decided the read does not describe this device, the dictionary names it what the member
+     * would have, and republishing it there hands a caller a reading indistinguishable from one the device
+     * really answered. A capability that never resolved withholds nothing: a param arriving before its
+     * capability is still the device's own, and keeps its dictionary name.
+     *
      * @param params param_type → raw value.
      * @param ts observation time (epoch ms); defaults to `Date.now()`.
      * @returns the list of property names whose value changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mega-yfue/eufy-sdk",
-  "version": "0.2.0-beta.11",
+  "version": "0.2.0-beta.13",
   "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",