@camstack/types 1.2.140 → 1.2.141

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

@@ -9,7 +9,7 @@ import { DeviceType } from '../device/device-type.js';
  * threshold.
  */
 export declare const BatteryStatusSchema: z.ZodObject<{
-    percentage: z.ZodNumber;
+    percentage: z.ZodNullable<z.ZodNumber>;
     charging: z.ZodEnum<{
         none: "none";
         dc: "dc";
@@ -63,7 +63,7 @@ export declare const batteryCapability: {
             readonly data: z.ZodObject<{
                 deviceId: z.ZodNumber;
                 status: z.ZodObject<{
-                    percentage: z.ZodNumber;
+                    percentage: z.ZodNullable<z.ZodNumber>;
                     charging: z.ZodEnum<{
                         none: "none";
                         dc: "dc";
@@ -79,7 +79,7 @@ export declare const batteryCapability: {
     };
     readonly status: {
         readonly schema: z.ZodObject<{
-            percentage: z.ZodNumber;
+            percentage: z.ZodNullable<z.ZodNumber>;
             charging: z.ZodEnum<{
                 none: "none";
                 dc: "dc";
@@ -108,7 +108,7 @@ export declare const batteryCapability: {
      * the underlying driver.
      */
     readonly runtimeState: z.ZodObject<{
-        percentage: z.ZodNumber;
+        percentage: z.ZodNullable<z.ZodNumber>;
         charging: z.ZodEnum<{
             none: "none";
             dc: "dc";

package/dist/capabilities/pipeline-analytics.cap.d.ts

@@ -1106,6 +1106,7 @@ declare const RecentTracksQueryInput: z.ZodObject<{
         slim: "slim";
     }>>;
     includeStationary: z.ZodOptional<z.ZodBoolean>;
+    classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type RecentTracksQuery = z.infer<typeof RecentTracksQueryInput>;
 declare const RecentTracksPageSchema: z.ZodObject<{
@@ -1907,6 +1908,7 @@ export declare const pipelineAnalyticsCapability: {
                 slim: "slim";
             }>>;
             includeStationary: z.ZodOptional<z.ZodBoolean>;
+            classes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>, z.ZodObject<{
             tracks: z.ZodReadonly<z.ZodArray<z.ZodObject<{
                 retrainStatus: z.ZodOptional<z.ZodEnum<{

package/dist/device/container-primary-child.d.ts

@@ -14,6 +14,15 @@
  * Each carried the same list and a comment asking the others to stay in sync.
  * This is that list, in the one package all of them already depend on.
  *
+ * `ui-library` and the server's linked-devices expansion IMPORT it. Two
+ * consumers cannot, and keep a checked copy instead: the viewer resolves
+ * `@camstack/types` from its own `node_modules` (an installed release, where a
+ * newly added export simply is not there), and the Home Assistant provider
+ * expresses the same precedence over the `DeviceType` enum because it answers
+ * a different question from the same ordering. `scripts/check-container-
+ * priority-in-sync.ts` fails the build when either drifts — the comment that
+ * used to ask for this could not.
+ *
  * The rule has two halves and the ORDER matters: an operator's explicit pick
  * wins outright, and only in its absence does type priority decide. The pick is
  * keyed on the child's re-sync-stable `entityId`, not its numeric id, so it
@@ -34,8 +43,28 @@ export declare const CONTAINER_CHILD_PRIORITY: readonly string[];
 /** The slice of a child this resolution needs. */
 export interface ContainerChildRef {
     readonly id: number;
-    /** Re-sync-stable identity (`sourceInfo.id`, falling back to `stableId`). */
-    readonly entityId: string;
+    /**
+     * The CANONICAL key an operator's pick is matched on.
+     *
+     * `stableId` and not `sourceInfo.id`, because `sourceInfo` is rebuilt from
+     * the device's config blob and the projection that linked-devices must use
+     * (`slim`) does not read it — measured on the live hub, 677 of 925 container
+     * children have a `sourceInfo.id` that differs from their `stableId`, so a
+     * resolver keyed on it would have missed the operator's pick for three
+     * children in four and fallen back to priority WHILE LOOKING LIKE IT WORKED.
+     *
+     * `stableId` costs nothing to have: it is a NOT NULL column, and
+     * `(addonId, stableId)` is the very index the row store re-identifies a
+     * device by across a re-sync — which is exactly the durability the pick
+     * needs.
+     */
+    readonly stableId: string;
+    /**
+     * The integration's own entity id, when the caller has it. Accepted ONLY so
+     * a pick stored under the previous key still resolves; new picks are written
+     * as `stableId`. Absent is normal.
+     */
+    readonly entityId?: string;
     readonly type: string;
 }
 /**

package/dist/index.js

@@ -18783,7 +18783,20 @@ var RecentTracksQueryInput = zod.z.object({
 	projection: TrackProjectionSchema.optional(),
 	/** Include stationary-promoted rows (parked objects). Default false: the
 	*  feed lists passages; parking records live on the stationary registry. */
-	includeStationary: zod.z.boolean().optional()
+	includeStationary: zod.z.boolean().optional(),
+	/**
+	* Restrict to these track classes. ABSENT or EMPTY means no filter.
+	*
+	* The same filter `listTracks` takes, because the timeline's class chips must
+	* mean the same thing whether the scope is one camera or twelve. Until this
+	* existed the scoped feed downloaded a page and narrowed it on the phone
+	* while the single-camera path narrowed the read — one filter, two costs.
+	*
+	* A SUPERSET prefilter on `classes[]`, like its single-camera twin: rows
+	* whose class list is unreadable are kept, and the client's rule stays the
+	* exact one.
+	*/
+	classes: zod.z.array(zod.z.string()).optional()
 });
 var RecentTracksPageSchema = zod.z.object({
 	/** Merged page, ordered by (`lastSeen` DESC, `trackId` DESC). */
@@ -25123,8 +25136,22 @@ var automationControlCapability = {
 * threshold.
 */
 var BatteryStatusSchema = zod.z.object({
-	/** 0..100 inclusive. Firmware-reported. */
-	percentage: zod.z.number().min(0).max(100),
+	/**
+	* 0..100 inclusive, firmware-reported. **`null` means NOT YET KNOWN** — the
+	* provider has registered the capability but no reading has landed.
+	*
+	* It is nullable because it was not, and the only value a provider could
+	* seed with was `0`. A battery camera behind an NVR therefore announced
+	* itself at 0% on every start and corrected itself a moment later, which is
+	* indistinguishable from a real flat battery: it fires the low-battery alert
+	* every time the hub restarts. Unknown is not empty (D315), and on a battery
+	* reading the difference is an alarm.
+	*
+	* `vacuum-control` and `lawn-mower-control` already model it this way.
+	* Consumers must SKIP a null rather than coerce it — `battery-band` already
+	* declines to band a non-finite reading, which is the correct shape.
+	*/
+	percentage: zod.z.number().min(0).max(100).nullable(),
 	/**
 	* Charging source. `'dc'` covers wall/USB adapters; `'solar'` is
 	* Reolink-specific for the Solar Panel 2 accessory (will become
@@ -35273,6 +35300,15 @@ var RUNTIME_DEFAULTS = {
 * Each carried the same list and a comment asking the others to stay in sync.
 * This is that list, in the one package all of them already depend on.
 *
+* `ui-library` and the server's linked-devices expansion IMPORT it. Two
+* consumers cannot, and keep a checked copy instead: the viewer resolves
+* `@camstack/types` from its own `node_modules` (an installed release, where a
+* newly added export simply is not there), and the Home Assistant provider
+* expresses the same precedence over the `DeviceType` enum because it answers
+* a different question from the same ordering. `scripts/check-container-
+* priority-in-sync.ts` fails the build when either drifts — the comment that
+* used to ask for this could not.
+*
 * The rule has two halves and the ORDER matters: an operator's explicit pick
 * wins outright, and only in its absence does type priority decide. The pick is
 * keyed on the child's re-sync-stable `entityId`, not its numeric id, so it
@@ -35328,7 +35364,7 @@ function rank(type) {
 */
 function resolveContainerPrimaryChild(children, overrideEntityId) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
-		const picked = children.find((c) => c.entityId === overrideEntityId);
+		const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
 		if (picked !== void 0) return picked;
 	}
 	return [...children].toSorted((a, b) => rank(a.type) - rank(b.type))[0] ?? null;

package/dist/index.mjs

@@ -18782,7 +18782,20 @@ var RecentTracksQueryInput = z.object({
 	projection: TrackProjectionSchema.optional(),
 	/** Include stationary-promoted rows (parked objects). Default false: the
 	*  feed lists passages; parking records live on the stationary registry. */
-	includeStationary: z.boolean().optional()
+	includeStationary: z.boolean().optional(),
+	/**
+	* Restrict to these track classes. ABSENT or EMPTY means no filter.
+	*
+	* The same filter `listTracks` takes, because the timeline's class chips must
+	* mean the same thing whether the scope is one camera or twelve. Until this
+	* existed the scoped feed downloaded a page and narrowed it on the phone
+	* while the single-camera path narrowed the read — one filter, two costs.
+	*
+	* A SUPERSET prefilter on `classes[]`, like its single-camera twin: rows
+	* whose class list is unreadable are kept, and the client's rule stays the
+	* exact one.
+	*/
+	classes: z.array(z.string()).optional()
 });
 var RecentTracksPageSchema = z.object({
 	/** Merged page, ordered by (`lastSeen` DESC, `trackId` DESC). */
@@ -25122,8 +25135,22 @@ var automationControlCapability = {
 * threshold.
 */
 var BatteryStatusSchema = z.object({
-	/** 0..100 inclusive. Firmware-reported. */
-	percentage: z.number().min(0).max(100),
+	/**
+	* 0..100 inclusive, firmware-reported. **`null` means NOT YET KNOWN** — the
+	* provider has registered the capability but no reading has landed.
+	*
+	* It is nullable because it was not, and the only value a provider could
+	* seed with was `0`. A battery camera behind an NVR therefore announced
+	* itself at 0% on every start and corrected itself a moment later, which is
+	* indistinguishable from a real flat battery: it fires the low-battery alert
+	* every time the hub restarts. Unknown is not empty (D315), and on a battery
+	* reading the difference is an alarm.
+	*
+	* `vacuum-control` and `lawn-mower-control` already model it this way.
+	* Consumers must SKIP a null rather than coerce it — `battery-band` already
+	* declines to band a non-finite reading, which is the correct shape.
+	*/
+	percentage: z.number().min(0).max(100).nullable(),
 	/**
 	* Charging source. `'dc'` covers wall/USB adapters; `'solar'` is
 	* Reolink-specific for the Solar Panel 2 accessory (will become
@@ -35265,6 +35292,15 @@ var RUNTIME_DEFAULTS = {
 * Each carried the same list and a comment asking the others to stay in sync.
 * This is that list, in the one package all of them already depend on.
 *
+* `ui-library` and the server's linked-devices expansion IMPORT it. Two
+* consumers cannot, and keep a checked copy instead: the viewer resolves
+* `@camstack/types` from its own `node_modules` (an installed release, where a
+* newly added export simply is not there), and the Home Assistant provider
+* expresses the same precedence over the `DeviceType` enum because it answers
+* a different question from the same ordering. `scripts/check-container-
+* priority-in-sync.ts` fails the build when either drifts — the comment that
+* used to ask for this could not.
+*
 * The rule has two halves and the ORDER matters: an operator's explicit pick
 * wins outright, and only in its absence does type priority decide. The pick is
 * keyed on the child's re-sync-stable `entityId`, not its numeric id, so it
@@ -35320,7 +35356,7 @@ function rank(type) {
 */
 function resolveContainerPrimaryChild(children, overrideEntityId) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
-		const picked = children.find((c) => c.entityId === overrideEntityId);
+		const picked = children.find((c) => c.stableId === overrideEntityId) ?? children.find((c) => c.entityId !== void 0 && c.entityId === overrideEntityId);
 		if (picked !== void 0) return picked;
 	}
 	return [...children].toSorted((a, b) => rank(a.type) - rank(b.type))[0] ?? null;

package/dist/interfaces/event-bus.d.ts

@@ -1084,11 +1084,17 @@ export interface EventCatalog {
      * `capabilities/battery.cap`) to avoid a cycle between the cap
      * definitions and the event bus typing — they're kept in lock-step
      * by hand (see also `BatteryStatus` in `capabilities/battery.cap.ts`).
+     *
+     * "By hand" failed exactly as the repo's no-duplicate-shapes rule predicts:
+     * `percentage` became nullable in the cap and stayed `number` here, so this
+     * copy refused the very value the cap now defines. Kept in lock-step is a
+     * hope; the compiler noticing is the only reason it was caught.
      */
     'battery.onStatusChanged': {
         readonly deviceId: number;
         readonly status: {
-            readonly percentage: number;
+            /** `null` = NOT YET KNOWN. See `BatteryStatusSchema.percentage`. */
+            readonly percentage: number | null;
             readonly charging: 'dc' | 'solar' | 'none';
             readonly sleeping: boolean;
             readonly lastUpdated: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.140",
+  "version": "1.2.141",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",