@camstack/types 1.2.143 → 1.2.144

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/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`.
@@ -36904,6 +36923,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 +36947,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`.
@@ -36896,6 +36915,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 +36939,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.144",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",