@camstack/types 1.2.52 → 1.2.54

package/dist/interfaces/adoption-job.d.ts

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+/**
+ * Adoption job — the background form of `device-adoption.adopt`.
+ *
+ * ## Why this exists
+ *
+ * `adopt({childNativeIds: [...]})` materialises one CamStack device per
+ * candidate PLUS every accessory child, and the whole array shares ONE UDS
+ * request deadline (60s). Measured on the live hub against Home Assistant:
+ * each device the kernel creates costs ~450 ms — `devices.create` pre-seeds
+ * meta with up to eleven SEQUENTIAL round trips (`setName`, `setType`,
+ * `setRole`, … `persistConfig`) before the class is constructed — and an
+ * accessory child costs the same as its parent. So the real unit of work is
+ * the CHILD, not the candidate:
+ *
+ * - 25 candidates averaging 6 children  → ~150 devices → **>60s, times out**
+ * - ONE candidate with 217 children     → ~217 devices → **>60s, times out**
+ *
+ * That second line is why this is a job and not a smaller batch. No chunking,
+ * no bounded concurrency over candidates and no per-call tuning can fix a
+ * shape where **N=1 already exceeds the deadline** — the count that blows the
+ * budget is the source system's accessory fan-out, which the operator does not
+ * choose and cannot see. A design that only works below some N is the same bug
+ * deferred.
+ *
+ * ## What the timeout did NOT do
+ *
+ * It did not stop the work. The UDS deadline ends the CALLER's wait; the
+ * provider's loop runs to completion. Measured: a 25-candidate adopt that
+ * "failed" at 60s had adopted 17 by 87s and all 25 by ~130s. The operator saw
+ * an error and had no way to learn that. Every field below exists so that
+ * question has an answer.
+ *
+ * ## Idempotency
+ *
+ * Jobs are in-RAM; a restart forgets them. That is safe here because adoption
+ * is keyed by a stable id (`ha:<broker>:dev:<nativeId>` and equivalents), so
+ * re-running a job re-adopts nothing: an already-adopted candidate is SKIPPED
+ * by the engine before any provider call and lands in `alreadyAdopted`. It is
+ * never a duplicate device, and never an error the operator has to interpret.
+ */
+export declare const AdoptionJobStateSchema: z.ZodEnum<{
+    done: "done";
+    failed: "failed";
+    running: "running";
+    cancelled: "cancelled";
+}>;
+export type AdoptionJobState = z.infer<typeof AdoptionJobStateSchema>;
+/**
+ * Per-candidate result. Every candidate the job was asked to adopt ends in
+ * exactly one of these buckets — there is no silent drop, and the operator can
+ * always answer "which of my 25 landed?".
+ *
+ * - `adopted` — created now by this job.
+ * - `already-adopted` — a device for this candidate existed before the job
+ *   reached it (a re-run, or a retry after a timeout). Not an error.
+ * - `failed` — the provider threw; `error` carries the message.
+ * - `cancelled` — the operator cancelled before this candidate was reached.
+ */
+export declare const AdoptionOutcomeSchema: z.ZodEnum<{
+    failed: "failed";
+    cancelled: "cancelled";
+    adopted: "adopted";
+    "already-adopted": "already-adopted";
+}>;
+export type AdoptionOutcome = z.infer<typeof AdoptionOutcomeSchema>;
+export declare const AdoptionCandidateResultSchema: z.ZodObject<{
+    childNativeId: z.ZodString;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        cancelled: "cancelled";
+        adopted: "adopted";
+        "already-adopted": "already-adopted";
+    }>;
+    parentDeviceId: z.ZodNullable<z.ZodNumber>;
+    accessoryCount: z.ZodNumber;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AdoptionCandidateResult = z.infer<typeof AdoptionCandidateResultSchema>;
+export declare const AdoptionJobSchema: z.ZodObject<{
+    jobId: z.ZodString;
+    addonId: z.ZodString;
+    integrationId: z.ZodString;
+    state: z.ZodEnum<{
+        done: "done";
+        failed: "failed";
+        running: "running";
+        cancelled: "cancelled";
+    }>;
+    total: z.ZodNumber;
+    processed: z.ZodNumber;
+    adopted: z.ZodNumber;
+    alreadyAdopted: z.ZodNumber;
+    failed: z.ZodNumber;
+    accessoriesCreated: z.ZodNumber;
+    currentChildNativeId: z.ZodNullable<z.ZodString>;
+    results: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        childNativeId: z.ZodString;
+        outcome: z.ZodEnum<{
+            failed: "failed";
+            cancelled: "cancelled";
+            adopted: "adopted";
+            "already-adopted": "already-adopted";
+        }>;
+        parentDeviceId: z.ZodNullable<z.ZodNumber>;
+        accessoryCount: z.ZodNumber;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>>;
+    startedAt: z.ZodNumber;
+    finishedAt: z.ZodNullable<z.ZodNumber>;
+    error: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type AdoptionJob = z.infer<typeof AdoptionJobSchema>;

package/package.json

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