@camstack/types 1.2.143 → 1.2.145

package/dist/capabilities/device-manager.cap.d.ts

@@ -1365,6 +1365,9 @@ export declare const deviceManagerCapability: {
                 uniqueId: z.ZodOptional<z.ZodString>;
                 raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$strip>>;
+            alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+            onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+            onboardedName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>, "mutation">;
         /** Adopt a discovered device via the device-provider capability. */
         readonly adoptDevice: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
@@ -1380,6 +1383,9 @@ export declare const deviceManagerCapability: {
                     uniqueId: z.ZodOptional<z.ZodString>;
                     raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 }, z.core.$strip>>;
+                alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+                onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+                onboardedName: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
             integrationId: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, z.ZodObject<{
@@ -1622,6 +1628,9 @@ export declare const deviceManagerCapability: {
                         uniqueId: z.ZodOptional<z.ZodString>;
                         raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                     }, z.core.$strip>>;
+                    alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+                    onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+                    onboardedName: z.ZodOptional<z.ZodString>;
                 }, z.core.$strip>>>;
                 error: z.ZodNullable<z.ZodString>;
             }, z.core.$strip>>>;
@@ -1643,6 +1652,9 @@ export declare const deviceManagerCapability: {
                     uniqueId: z.ZodOptional<z.ZodString>;
                     raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 }, z.core.$strip>>;
+                alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+                onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+                onboardedName: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>>>;
         }, z.core.$strip>, "mutation">;
         /** The device type a provider creates via manual add (Camera/Container/Hub),

package/dist/capabilities/device-provider.cap.d.ts

@@ -28,6 +28,9 @@ declare const DiscoveryCandidateSchema: z.ZodObject<{
         uniqueId: z.ZodOptional<z.ZodString>;
         raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, z.core.$strip>>;
+    alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+    onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+    onboardedName: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * Flat device summary returned by `createDevice` / `adoptDiscoveredDevice`.
@@ -132,6 +135,9 @@ export declare const deviceProviderCapability: {
                 uniqueId: z.ZodOptional<z.ZodString>;
                 raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, z.core.$strip>>;
+            alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+            onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+            onboardedName: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>, "mutation">;
         /**
          * Optional form schema (`ConfigUISchema`) for the EXTRA per-scan inputs a
@@ -161,6 +167,9 @@ export declare const deviceProviderCapability: {
                     uniqueId: z.ZodOptional<z.ZodString>;
                     raw: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 }, z.core.$strip>>;
+                alreadyOnboarded: z.ZodOptional<z.ZodBoolean>;
+                onboardedDeviceId: z.ZodOptional<z.ZodNumber>;
+                onboardedName: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodObject<{
             id: z.ZodNumber;

package/dist/device/base-device-provider.d.ts

@@ -17,6 +17,16 @@ export interface DiscoveryCandidate {
      *  knows the upstream identity ahead of adoption (HA: entity_id +
      *  unit + device_class from `GET /api/states`). */
     readonly sourceInfo?: SourceInfo;
+    /** Set when the provider recognises this candidate as a device it ALREADY
+     *  owns. A scan usually cannot reproduce the identity a device was onboarded
+     *  under, so a stableId comparison never matches and an owned device looks
+     *  addable — re-adopting it overwrites its config with scan-derived values.
+     *  Absent means "not recognised", NOT "known to be new". */
+    readonly alreadyOnboarded?: boolean;
+    /** Numeric id of the device this candidate was matched to. Set with `alreadyOnboarded`. */
+    readonly onboardedDeviceId?: number;
+    /** Operator-facing name of the matched device, so the UI can say WHICH one it is. */
+    readonly onboardedName?: string;
 }
 export interface DeviceSummary {
     readonly id: number;
@@ -263,6 +273,22 @@ export declare abstract class BaseDeviceProvider<TConfig extends object = Record
      * failed — logged at ERROR with `tags.deviceId` and surfaced via
      * `getStatus().error`.
      */
+    /**
+     * Repair a row's PERSISTED config blob immediately before it is restored.
+     * Default: no-op — most providers have nothing to heal.
+     *
+     * This exists because a restored device self-hydrates from the DB: `create()`
+     * passes `{}` and `BaseDevice` parses the stored blob against the device
+     * schema. A blob that lost a REQUIRED field therefore fails restore forever,
+     * and no later pass revisits it — a hub-adopted Reolink camera whose blob had
+     * been emptied failed all four bounded attempts against fields
+     * (`host`, `password`) it inherits from its parent and never dials itself.
+     *
+     * Implementations get every saved row, so a child can read its parent's blob.
+     * A heal that throws is treated like any other restore failure: retried under
+     * the bound, then reported — never swallowed.
+     */
+    protected healSavedConfig(_saved: SavedDevice, _allSaved: readonly SavedDevice[]): Promise<void>;
     protected onRestoreDevices(savedDevices: readonly SavedDevice[]): Promise<DeviceRestoreReport | void>;
     /** Convert an IDevice to the flat DeviceSummary for the cap router. */
     protected toSummary(device: IDevice): DeviceSummary;

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

@@ -66,11 +66,34 @@ export interface ContainerChildRef {
      */
     readonly entityId?: string;
     readonly type: string;
+    /**
+     * The child's `DeviceRole`, when the provider stamped one. Ranked BEFORE
+     * `type` — see {@link CONTAINER_CHILD_ROLE_PRIORITY}. Absent is normal and
+     * simply defers to type priority.
+     */
+    readonly role?: string;
+    /** The child's operator-facing name, used only for the namesake tiebreak. */
+    readonly name?: string;
 }
+/**
+ * Roles that say what a container IS, most→least defining. Consulted BEFORE
+ * type priority, because `DeviceType` cannot tell them apart: Home Assistant
+ * maps a door contact, a battery level, a temperature reading and a "last seen"
+ * timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+ * `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+ * and a role-less `button` — the type list ranked `button` above `sensor` and
+ * the container stood for its "Identifica" button instead of the door contact
+ * it is named after.
+ *
+ * Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+ * temperature, humidity, signal, last-seen) is never what a container is, so
+ * they are deliberately absent and fall through to type priority.
+ */
+export declare const CONTAINER_CHILD_ROLE_PRIORITY: readonly string[];
 /**
  * The child a container stands for: the operator's pick when it still exists,
  * else the highest-priority type. `null` for a childless container — a caller
  * must decide what an empty container means for it, rather than being handed a
  * child that is not there.
  */
-export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined): ContainerChildRef | null;
+export declare function resolveContainerPrimaryChild(children: readonly ContainerChildRef[], overrideEntityId: string | null | undefined, containerName?: string): ContainerChildRef | null;

package/dist/index.js

@@ -10061,7 +10061,26 @@ var DiscoveryCandidateSchema = zod.z.object({
 	* identity ahead of adoption. Rendering metadata (unit, precision)
 	* flows live through the cap STATUS SLICE after adoption.
 	*/
-	sourceInfo: SourceInfoSchema.optional()
+	sourceInfo: SourceInfoSchema.optional(),
+	/**
+	* Set when this candidate is a device the provider ALREADY owns.
+	*
+	* A scan cannot generally produce the identity a device was onboarded under
+	* (Reolink keys on `mac-<mac>`, learned at adopt time), so a stableId
+	* comparison never matches and an owned device looks addable. Re-adopting one
+	* overwrites its config with scan-derived values — that is how a Home Hub's
+	* Baichuan port was overwritten with its ONVIF port, taking the hub and its
+	* three child cameras offline for four hours.
+	*
+	* A provider that can recognise its own devices says so here. Absent means
+	* "not recognised", which is not the same as "known to be new" — a provider
+	* that cannot tell simply never sets it.
+	*/
+	alreadyOnboarded: zod.z.boolean().optional(),
+	/** Numeric id of the device this candidate was matched to. Set with `alreadyOnboarded`. */
+	onboardedDeviceId: zod.z.number().optional(),
+	/** Operator-facing name of the matched device, so the UI can say WHICH one it is. */
+	onboardedName: zod.z.string().optional()
 });
 /**
 * Flat device summary returned by `createDevice` / `adoptDiscoveredDevice`.
@@ -35532,6 +35551,39 @@ var CONTAINER_CHILD_PRIORITY = [
 	"image",
 	"sensor"
 ];
+/**
+* Roles that say what a container IS, most→least defining. Consulted BEFORE
+* type priority, because `DeviceType` cannot tell them apart: Home Assistant
+* maps a door contact, a battery level, a temperature reading and a "last seen"
+* timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+* `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+* and a role-less `button` — the type list ranked `button` above `sensor` and
+* the container stood for its "Identifica" button instead of the door contact
+* it is named after.
+*
+* Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+* temperature, humidity, signal, last-seen) is never what a container is, so
+* they are deliberately absent and fall through to type priority.
+*/
+var CONTAINER_CHILD_ROLE_PRIORITY = [
+	"contact-sensor",
+	"motion-sensor",
+	"occupancy-sensor",
+	"smoke-sensor",
+	"co-sensor",
+	"gas-sensor",
+	"leak-sensor",
+	"vibration-sensor",
+	"tamper-sensor",
+	"sound-sensor",
+	"binary-sensor",
+	"binary-helper"
+];
+function roleRank(role) {
+	if (role === void 0) return CONTAINER_CHILD_ROLE_PRIORITY.length;
+	const i = CONTAINER_CHILD_ROLE_PRIORITY.indexOf(role);
+	return i === -1 ? CONTAINER_CHILD_ROLE_PRIORITY.length : i;
+}
 function rank(type) {
 	const i = CONTAINER_CHILD_PRIORITY.indexOf(type);
 	return i === -1 ? CONTAINER_CHILD_PRIORITY.length : i;
@@ -35542,12 +35594,13 @@ function rank(type) {
 * must decide what an empty container means for it, rather than being handed a
 * child that is not there.
 */
-function resolveContainerPrimaryChild(children, overrideEntityId) {
+function resolveContainerPrimaryChild(children, overrideEntityId, containerName) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
 		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;
+	const namesake = (c) => containerName !== void 0 && containerName.length > 0 && c.name !== void 0 && c.name.toLowerCase() === containerName.toLowerCase() ? 0 : 1;
+	return [...children].toSorted((a, b) => roleRank(a.role) - roleRank(b.role) || namesake(a) - namesake(b) || rank(a.type) - rank(b.type))[0] ?? null;
 }
 //#endregion
 //#region src/device/accessory.ts
@@ -36904,6 +36957,22 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 	* failed — logged at ERROR with `tags.deviceId` and surfaced via
 	* `getStatus().error`.
 	*/
+	/**
+	* Repair a row's PERSISTED config blob immediately before it is restored.
+	* Default: no-op — most providers have nothing to heal.
+	*
+	* This exists because a restored device self-hydrates from the DB: `create()`
+	* passes `{}` and `BaseDevice` parses the stored blob against the device
+	* schema. A blob that lost a REQUIRED field therefore fails restore forever,
+	* and no later pass revisits it — a hub-adopted Reolink camera whose blob had
+	* been emptied failed all four bounded attempts against fields
+	* (`host`, `password`) it inherits from its parent and never dials itself.
+	*
+	* Implementations get every saved row, so a child can read its parent's blob.
+	* A heal that throws is treated like any other restore failure: retried under
+	* the bound, then reported — never swallowed.
+	*/
+	async healSavedConfig(_saved, _allSaved) {}
 	async onRestoreDevices(savedDevices) {
 		const restored = /* @__PURE__ */ new Set();
 		const failures = [];
@@ -36912,6 +36981,7 @@ var BaseDeviceProvider = class extends require_sleep.BaseAddon {
 			const Class = this.deviceClasses[saved.type];
 			if (!Class) throw new Error(`no device class registered for type "${saved.type}"`);
 			if (saved.parentDeviceId !== null && !restored.has(saved.parentDeviceId)) throw new Error(`parent device ${saved.parentDeviceId} not restored`);
+			await this.healSavedConfig(saved, savedDevices);
 			await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
 			restored.add(saved.id);
 		};

package/dist/index.mjs

@@ -10060,7 +10060,26 @@ var DiscoveryCandidateSchema = z.object({
 	* identity ahead of adoption. Rendering metadata (unit, precision)
 	* flows live through the cap STATUS SLICE after adoption.
 	*/
-	sourceInfo: SourceInfoSchema.optional()
+	sourceInfo: SourceInfoSchema.optional(),
+	/**
+	* Set when this candidate is a device the provider ALREADY owns.
+	*
+	* A scan cannot generally produce the identity a device was onboarded under
+	* (Reolink keys on `mac-<mac>`, learned at adopt time), so a stableId
+	* comparison never matches and an owned device looks addable. Re-adopting one
+	* overwrites its config with scan-derived values — that is how a Home Hub's
+	* Baichuan port was overwritten with its ONVIF port, taking the hub and its
+	* three child cameras offline for four hours.
+	*
+	* A provider that can recognise its own devices says so here. Absent means
+	* "not recognised", which is not the same as "known to be new" — a provider
+	* that cannot tell simply never sets it.
+	*/
+	alreadyOnboarded: z.boolean().optional(),
+	/** Numeric id of the device this candidate was matched to. Set with `alreadyOnboarded`. */
+	onboardedDeviceId: z.number().optional(),
+	/** Operator-facing name of the matched device, so the UI can say WHICH one it is. */
+	onboardedName: z.string().optional()
 });
 /**
 * Flat device summary returned by `createDevice` / `adoptDiscoveredDevice`.
@@ -35524,6 +35543,39 @@ var CONTAINER_CHILD_PRIORITY = [
 	"image",
 	"sensor"
 ];
+/**
+* Roles that say what a container IS, most→least defining. Consulted BEFORE
+* type priority, because `DeviceType` cannot tell them apart: Home Assistant
+* maps a door contact, a battery level, a temperature reading and a "last seen"
+* timestamp all to `DeviceType.Sensor`. Measured on container 4127 — children
+* `battery-sensor`, `temperature-sensor`, `datetime-sensor`, `contact-sensor`
+* and a role-less `button` — the type list ranked `button` above `sensor` and
+* the container stood for its "Identifica" button instead of the door contact
+* it is named after.
+*
+* Only STATE-DEFINING roles belong here. A diagnostic reading (battery,
+* temperature, humidity, signal, last-seen) is never what a container is, so
+* they are deliberately absent and fall through to type priority.
+*/
+var CONTAINER_CHILD_ROLE_PRIORITY = [
+	"contact-sensor",
+	"motion-sensor",
+	"occupancy-sensor",
+	"smoke-sensor",
+	"co-sensor",
+	"gas-sensor",
+	"leak-sensor",
+	"vibration-sensor",
+	"tamper-sensor",
+	"sound-sensor",
+	"binary-sensor",
+	"binary-helper"
+];
+function roleRank(role) {
+	if (role === void 0) return CONTAINER_CHILD_ROLE_PRIORITY.length;
+	const i = CONTAINER_CHILD_ROLE_PRIORITY.indexOf(role);
+	return i === -1 ? CONTAINER_CHILD_ROLE_PRIORITY.length : i;
+}
 function rank(type) {
 	const i = CONTAINER_CHILD_PRIORITY.indexOf(type);
 	return i === -1 ? CONTAINER_CHILD_PRIORITY.length : i;
@@ -35534,12 +35586,13 @@ function rank(type) {
 * must decide what an empty container means for it, rather than being handed a
 * child that is not there.
 */
-function resolveContainerPrimaryChild(children, overrideEntityId) {
+function resolveContainerPrimaryChild(children, overrideEntityId, containerName) {
 	if (overrideEntityId !== void 0 && overrideEntityId !== null) {
 		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;
+	const namesake = (c) => containerName !== void 0 && containerName.length > 0 && c.name !== void 0 && c.name.toLowerCase() === containerName.toLowerCase() ? 0 : 1;
+	return [...children].toSorted((a, b) => roleRank(a.role) - roleRank(b.role) || namesake(a) - namesake(b) || rank(a.type) - rank(b.type))[0] ?? null;
 }
 //#endregion
 //#region src/device/accessory.ts
@@ -36896,6 +36949,22 @@ var BaseDeviceProvider = class extends BaseAddon {
 	* failed — logged at ERROR with `tags.deviceId` and surfaced via
 	* `getStatus().error`.
 	*/
+	/**
+	* Repair a row's PERSISTED config blob immediately before it is restored.
+	* Default: no-op — most providers have nothing to heal.
+	*
+	* This exists because a restored device self-hydrates from the DB: `create()`
+	* passes `{}` and `BaseDevice` parses the stored blob against the device
+	* schema. A blob that lost a REQUIRED field therefore fails restore forever,
+	* and no later pass revisits it — a hub-adopted Reolink camera whose blob had
+	* been emptied failed all four bounded attempts against fields
+	* (`host`, `password`) it inherits from its parent and never dials itself.
+	*
+	* Implementations get every saved row, so a child can read its parent's blob.
+	* A heal that throws is treated like any other restore failure: retried under
+	* the bound, then reported — never swallowed.
+	*/
+	async healSavedConfig(_saved, _allSaved) {}
 	async onRestoreDevices(savedDevices) {
 		const restored = /* @__PURE__ */ new Set();
 		const failures = [];
@@ -36904,6 +36973,7 @@ var BaseDeviceProvider = class extends BaseAddon {
 			const Class = this.deviceClasses[saved.type];
 			if (!Class) throw new Error(`no device class registered for type "${saved.type}"`);
 			if (saved.parentDeviceId !== null && !restored.has(saved.parentDeviceId)) throw new Error(`parent device ${saved.parentDeviceId} not restored`);
+			await this.healSavedConfig(saved, savedDevices);
 			await this.ctx.kernel.devices.create(saved.stableId, Class, {}, saved.parentDeviceId);
 			restored.add(saved.id);
 		};

package/package.json

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