@camstack/types 1.2.52 → 1.2.53

package/dist/index.js

@@ -585,6 +585,106 @@ function resolveAddonPlacement(decl) {
 	return resolveAddonExecution(decl).placement;
 }
 //#endregion
+//#region src/interfaces/adoption-job.ts
+/**
+* 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.
+*/
+var AdoptionJobStateSchema = zod.z.enum([
+	"running",
+	"done",
+	"failed",
+	"cancelled"
+]);
+/**
+* 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.
+*/
+var AdoptionOutcomeSchema = zod.z.enum([
+	"adopted",
+	"already-adopted",
+	"failed",
+	"cancelled"
+]);
+var AdoptionCandidateResultSchema = zod.z.object({
+	childNativeId: zod.z.string(),
+	outcome: AdoptionOutcomeSchema,
+	/** The materialised parent device id — null for `failed` / `cancelled`. */
+	parentDeviceId: zod.z.number().int().nonnegative().nullable(),
+	/** Accessory children created for this candidate. */
+	accessoryCount: zod.z.number().int().nonnegative(),
+	/** Failure message; null unless `outcome === 'failed'`. */
+	error: zod.z.string().nullable()
+});
+var AdoptionJobSchema = zod.z.object({
+	jobId: zod.z.string(),
+	/** The integration provider this job adopts through (the `addonId` pin). */
+	addonId: zod.z.string(),
+	integrationId: zod.z.string(),
+	state: AdoptionJobStateSchema,
+	/** Candidates the job was asked to adopt. Known up front, so never null. */
+	total: zod.z.number().int().nonnegative(),
+	/** Candidates that have reached a terminal bucket. */
+	processed: zod.z.number().int().nonnegative(),
+	adopted: zod.z.number().int().nonnegative(),
+	alreadyAdopted: zod.z.number().int().nonnegative(),
+	failed: zod.z.number().int().nonnegative(),
+	/** Accessory child devices created across every candidate — the real unit
+	*  of work, surfaced so a slow job is legible rather than mysterious. */
+	accessoriesCreated: zod.z.number().int().nonnegative(),
+	/** The candidate currently being adopted; null when idle or finished. */
+	currentChildNativeId: zod.z.string().nullable(),
+	/** One entry per candidate, in the order they were processed. */
+	results: zod.z.array(AdoptionCandidateResultSchema).readonly(),
+	startedAt: zod.z.number(),
+	finishedAt: zod.z.number().nullable(),
+	/** Set only when the job itself broke (not a per-candidate failure). */
+	error: zod.z.string().nullable()
+});
+//#endregion
 //#region src/interfaces/analysis-persistence.ts
 var DEFAULT_RETENTION = {
 	cleanupIntervalMs: 3600 * 1e3,
@@ -8706,6 +8806,31 @@ var deviceManagerCapability = {
 			auth: "admin"
 		}),
 		/**
+		* Start a background adoption and return its `jobId` immediately. The job
+		* adopts ONE candidate per provider call, so no single request can exceed
+		* the transport deadline, and it skips candidates that are already adopted
+		* — which makes re-submitting a batch after a timeout safe and silent
+		* rather than a wall of duplicate-stableId errors.
+		*/
+		adoptionStartJob: require_sleep.method(AdoptInputSchema.extend({ addonId: zod.z.string() }), zod.z.object({ jobId: zod.z.string() }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
+		* Adoption jobs for an integration, newest first. This is the answer to
+		* "which of my 25 landed?" — `results` carries one entry per candidate,
+		* every one of them in a named bucket.
+		*/
+		adoptionListJobs: require_sleep.method(zod.z.object({
+			addonId: zod.z.string(),
+			integrationId: zod.z.string().optional()
+		}), zod.z.array(AdoptionJobSchema).readonly(), { auth: "admin" }),
+		/** Cooperative cancel: the in-flight candidate finishes, the rest never start. */
+		adoptionCancelJob: require_sleep.method(zod.z.object({ jobId: zod.z.string() }), zod.z.object({ cancelled: zod.z.boolean() }), {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		/**
 		* Re-sync a device with its source via the device-adoption provider of the
 		* device's OWNING addon (resolved from `camDeviceId`). Unlike the singleton
 		* `device-adoption.resync`, this routes to the correct integration so a
@@ -20044,6 +20169,101 @@ onColorChanged: { data: zod.z.object({
 	runtimeState: ColorStatusSchema
 };
 //#endregion
+//#region src/capabilities/connection-test.cap.ts
+/**
+* `connection-test` — pre-creation validation of an integration's settings,
+* system-scoped collection (one provider per integration addon).
+*
+* ── Why this cap exists ─────────────────────────────────────────────────────
+*
+* Before it, `integrations.testConnection` had exactly two behaviours: a broker
+* branch (`settings.brokerId` → `broker.testConnection`) and a DEFAULT branch
+* that probed `settings.main_stream_url ?? settings.url` with ffprobe. Every
+* account-based integration — Dreo, Dreame, Tuya, Petkit, Wyze — fell into that
+* default and was told `{"success":false,"error":"No stream URL provided"}`.
+* That answer neither validated nor refused anything, so:
+*
+*   - the Test button had NEVER worked for an account integration, and
+*   - `integrations.create` had nothing to gate on, so an integration with a
+*     wrong password was created happily and failed later, silently, at
+*     reconcile time.
+*
+* The structural gap was that at CREATE time the integration does not exist
+* yet: there is no `integrationId`, no `brokerId`, no live client — and every
+* existing provider surface (`device-provider`, `device-adoption`) is keyed by
+* one of those. There was no way to ask "are these settings valid?" before the
+* row existed.
+*
+* ── The contract ────────────────────────────────────────────────────────────
+*
+* The provider knows how to validate its OWN settings. The framework does not
+* guess from the shape of the settings — a stream-URL probe is one provider's
+* implementation of this cap, not the universal fallback. A provider that does
+* not register this cap is a KNOWN "cannot validate", never a silent pass.
+*
+* `testSettings` takes the candidate settings blob exactly as the wizard's
+* config step collected it (the same blob that would be handed to
+* `integrations.create`), and MUST NOT persist anything, mint an integration,
+* or mutate live state. It opens a throwaway session, asks, and closes it.
+*
+* ── The three outcomes are NOT interchangeable ──────────────────────────────
+*
+* This is the whole point of the discriminated union: a `null` from a timeout
+* must never look like a `null` from a refusal.
+*
+*   - `validated`    — the remote ACCEPTED these credentials. Observed.
+*   - `rejected`     — the remote REFUSED these credentials. Observed.
+*                      This is the ONLY outcome that blocks creation.
+*   - `inconclusive` — the check could not complete (DNS, timeout, 5xx, an
+*                      unexpected shape). NOTHING was observed about the
+*                      credentials. Never rendered, or counted, as a failure.
+*
+* A provider that cannot tell a refusal from a transport fault must return
+* `inconclusive`. Guessing `rejected` would block creation on a flaky network;
+* guessing `validated` would wave a wrong password through.
+*/
+/** Ceiling on how long a pre-creation probe may hold the wizard. */
+var CONNECTION_TEST_TIMEOUT_MS = 2e4;
+var ConnectionTestOutcomeSchema = zod.z.discriminatedUnion("outcome", [
+	zod.z.object({
+		outcome: zod.z.literal("validated"),
+		/** Round-trip of the sign-in, when the provider measured it. */
+		latencyMs: zod.z.number().nonnegative().optional(),
+		/** Optional human detail worth showing next to the tick
+		*  ("3 devices visible on this account"). */
+		detail: zod.z.string().optional()
+	}).strict(),
+	zod.z.object({
+		outcome: zod.z.literal("rejected"),
+		error: zod.z.string()
+	}).strict(),
+	zod.z.object({
+		outcome: zod.z.literal("inconclusive"),
+		error: zod.z.string()
+	}).strict()
+]);
+var ConnectionTestInputSchema = zod.z.object({ 
+/** Candidate integration settings, exactly as the create form collected them. */
+settings: zod.z.record(zod.z.string(), zod.z.unknown()) });
+/**
+* What the provider's test actually DOES, so the UI can say it in words before
+* the operator presses the button ("Signs in to the Dreo cloud"). Purely
+* descriptive — it never changes routing.
+*/
+var ConnectionTestDescriptorSchema = zod.z.object({ label: zod.z.string() });
+var connectionTestCapability = {
+	name: "connection-test",
+	scope: "system",
+	mode: "collection",
+	methods: {
+		testSettings: require_sleep.method(ConnectionTestInputSchema, ConnectionTestOutcomeSchema, {
+			kind: "mutation",
+			auth: "admin"
+		}),
+		describeTest: require_sleep.method(zod.z.void(), ConnectionTestDescriptorSchema, { auth: "admin" })
+	}
+};
+//#endregion
 //#region src/capabilities/connectivity.cap.ts
 /**
 * Upstream-system connectivity sensor — distinct from `device-status`,
@@ -21528,15 +21748,57 @@ var AvailableIntegrationTypeSchema = zod.z.object({
 	*  flow can import (e.g. HA areas). Drives the adopt modal's "import
 	*  locations" checkbox. Provider-declared in the addon manifest. */
 	supportsLocationImport: zod.z.boolean(),
+	/**
+	* True when this integration DECLARES a pre-creation test (the
+	* `connection-test` cap, or a broker whose settings it stores). Drives the
+	* Test button: an integration that cannot be tested must say so up front
+	* rather than offering a button that always answers the same nonsense.
+	*/
+	canTest: zod.z.boolean(),
 	existingInstances: zod.z.array(zod.z.object({
 		id: zod.z.string(),
 		name: zod.z.string()
 	})),
 	canAdd: zod.z.boolean()
 });
+/**
+* Why a test could not be answered as a plain boolean.
+*
+* `success` alone collapsed four different situations into one red box, and the
+* one that mattered most — "nobody ever asked the remote anything" — looked
+* exactly like "the remote said no". The status is the discriminator:
+*
+*   - `validated`    — a provider-declared test ran and the remote ACCEPTED.
+*   - `rejected`     — a provider-declared test ran and the remote REFUSED.
+*                      The only status that blocks `integrations.create`.
+*   - `inconclusive` — a test IS declared but could not complete (timeout,
+*                      DNS, 5xx). Nothing was observed; not a failure.
+*   - `unsupported`  — this integration declares NO test. Nothing was
+*                      observed either; not a failure, and not a pass.
+*
+* `unsupported` and `inconclusive` both carry `success: false` so an older
+* client can never read them as a green tick, and both carry an `error` string
+* that SAYS the test did not run rather than inventing a failure.
+*/
+var TestConnectionStatusEnum = zod.z.enum([
+	"validated",
+	"rejected",
+	"inconclusive",
+	"unsupported"
+]);
 var TestConnectionResultSchema$1 = zod.z.object({
+	/** True ONLY for `validated`. Never true for a test that did not run. */
 	success: zod.z.boolean(),
-	error: zod.z.string().optional()
+	error: zod.z.string().optional(),
+	/** Optional for wire back-compat with clients built before the tri-state;
+	*  the server always sets it. */
+	status: TestConnectionStatusEnum.optional(),
+	/** Addon id whose declared test answered — `null` when none did. Lets the UI
+	*  attribute a result instead of blaming "the integration". */
+	testedBy: zod.z.string().nullable().optional(),
+	latencyMs: zod.z.number().nonnegative().optional(),
+	/** Human detail from a `validated` result ("3 devices on this account"). */
+	detail: zod.z.string().optional()
 });
 var CreateIntegrationInputSchema = zod.z.object({
 	addonId: zod.z.string(),
@@ -29851,6 +30113,7 @@ var CAPABILITY_NAMES = {
 	carbonMonoxide: "carbon-monoxide",
 	climateControl: "climate-control",
 	color: "color",
+	connectionTest: "connection-test",
 	connectivity: "connectivity",
 	consumables: "consumables",
 	contact: "contact",
@@ -30094,6 +30357,10 @@ var CAPABILITY_ROUTER_KEYS = [
 		key: "color",
 		name: "color"
 	},
+	{
+		key: "connectionTest",
+		name: "connection-test"
+	},
 	{
 		key: "connectivity",
 		name: "connectivity"
@@ -30600,6 +30867,7 @@ var ALL_CAPABILITY_DEFINITIONS = [
 	carbonMonoxideCapability,
 	climateControlCapability,
 	colorCapability,
+	connectionTestCapability,
 	connectivityCapability,
 	consumablesCapability,
 	contactCapability,
@@ -31494,6 +31762,18 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"connectionTest.describeTest": {
+		capName: "connection-test",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
+	"connectionTest.testSettings": {
+		capName: "connection-test",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"consumables.reset": {
 		capName: "consumables",
 		capScope: "device",
@@ -31884,6 +32164,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionCancelJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.adoptionListCandidateFilters": {
 		capName: "device-manager",
 		capScope: "system",
@@ -31896,6 +32182,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceManager.adoptionListJobs": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"deviceManager.adoptionRefresh": {
 		capName: "device-manager",
 		capScope: "system",
@@ -31914,6 +32206,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionStartJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.allocateDeviceId": {
 		capName: "device-manager",
 		capScope: "system",
@@ -36155,6 +36453,7 @@ var KNOWN_CAP_NAMES = [
 	"camera-streams",
 	"climate-control",
 	"color",
+	"connection-test",
 	"consumables",
 	"control",
 	"core-blocks",
@@ -36324,6 +36623,7 @@ var SYSTEM_CAP_NAMES = [
 	"auth-provider",
 	"backup",
 	"broker",
+	"connection-test",
 	"core-blocks",
 	"custom-model-registry",
 	"data-store-provider",
@@ -36595,6 +36895,10 @@ function createSystemProxy(api) {
 			getState: (input) => dispatch("broker", "getState", "query", input),
 			getStatus: (input) => dispatch("broker", "getStatus", "query", input)
 		},
+		connectionTest: {
+			testSettings: (input) => dispatch("connectionTest", "testSettings", "mutation", input),
+			describeTest: (input) => dispatch("connectionTest", "describeTest", "query", input)
+		},
 		coreBlocks: {
 			list: (input) => dispatch("coreBlocks", "list", "query", input),
 			get: (input) => dispatch("coreBlocks", "get", "query", input),
@@ -36664,6 +36968,9 @@ function createSystemProxy(api) {
 			adoptionRefresh: (input) => dispatch("deviceManager", "adoptionRefresh", "mutation", input),
 			adoptionAdopt: (input) => dispatch("deviceManager", "adoptionAdopt", "mutation", input),
 			adoptionRelease: (input) => dispatch("deviceManager", "adoptionRelease", "mutation", input),
+			adoptionStartJob: (input) => dispatch("deviceManager", "adoptionStartJob", "mutation", input),
+			adoptionListJobs: (input) => dispatch("deviceManager", "adoptionListJobs", "query", input),
+			adoptionCancelJob: (input) => dispatch("deviceManager", "adoptionCancelJob", "mutation", input),
 			adoptionResync: (input) => dispatch("deviceManager", "adoptionResync", "mutation", input),
 			discoveryProviders: (input) => dispatch("deviceManager", "discoveryProviders", "query", input),
 			discoverAllProviders: (input) => dispatch("deviceManager", "discoverAllProviders", "mutation", input),
@@ -39288,10 +39595,14 @@ exports.AddonPageDeclarationSchema = AddonPageDeclarationSchema;
 exports.AddonPageInfoSchema = AddonPageInfoSchema;
 exports.AdoptionAdoptInputSchema = AdoptInputSchema;
 exports.AdoptionAdoptResultSchema = AdoptResultSchema;
+exports.AdoptionCandidateResultSchema = AdoptionCandidateResultSchema;
 exports.AdoptionFilterSchema = AdoptionFilterSchema;
 exports.AdoptionGetCandidateInputSchema = GetCandidateInputSchema;
+exports.AdoptionJobSchema = AdoptionJobSchema;
+exports.AdoptionJobStateSchema = AdoptionJobStateSchema;
 exports.AdoptionListCandidatesInputSchema = ListCandidatesInputSchema;
 exports.AdoptionListCandidatesOutputSchema = ListCandidatesOutputSchema;
+exports.AdoptionOutcomeSchema = AdoptionOutcomeSchema;
 exports.AdoptionReleaseInputSchema = ReleaseInputSchema;
 exports.AdoptionStatusSchema = AdoptionStatusSchema;
 exports.AgentLoadSummarySchema = AgentLoadSummarySchema;
@@ -39380,6 +39691,7 @@ exports.CAP_NODE_PIN_CONTEXT_KEY = require_sleep.CAP_NODE_PIN_CONTEXT_KEY;
 exports.CAP_PROVIDER_KIND_MAP = CAP_PROVIDER_KIND_MAP;
 exports.COCO_80_LABELS = COCO_80_LABELS;
 exports.COCO_TO_MACRO = COCO_TO_MACRO;
+exports.CONNECTION_TEST_TIMEOUT_MS = CONNECTION_TEST_TIMEOUT_MS;
 exports.CORE_BLOCKS_ADDON_ID = CORE_BLOCKS_ADDON_ID;
 exports.CORE_BLOCK_ADDON_PREFIX = CORE_BLOCK_ADDON_PREFIX;
 exports.CamProfileSchema = require_sleep.CamProfileSchema;
@@ -39432,6 +39744,9 @@ exports.ColorStatusSchema = ColorStatusSchema;
 exports.ConfigEntrySchema = ConfigEntrySchema;
 exports.ConfigSectionWithValuesSchema = ConfigSectionWithValuesSchema;
 exports.ConfigTabDeclarationSchema = ConfigTabDeclarationSchema;
+exports.ConnectionTestDescriptorSchema = ConnectionTestDescriptorSchema;
+exports.ConnectionTestInputSchema = ConnectionTestInputSchema;
+exports.ConnectionTestOutcomeSchema = ConnectionTestOutcomeSchema;
 exports.ConnectivityStatusSchema = ConnectivityStatusSchema;
 exports.ConsumableItemSchema = ConsumableItemSchema;
 exports.ConsumablesStatusSchema = ConsumablesStatusSchema;
@@ -39997,6 +40312,7 @@ exports.TemperatureSensorStatusSchema = TemperatureSensorStatusSchema;
 exports.TerminalProfileInfoSchema = TerminalProfileInfoSchema;
 exports.TerminalSessionInfoSchema = TerminalSessionInfoSchema;
 exports.TestConnectionResultSchema = TestConnectionResultSchema$1;
+exports.TestConnectionStatusEnum = TestConnectionStatusEnum;
 exports.TestResultSchema = TestResultSchema;
 exports.TimelapseRuleInputSchema = TimelapseRuleInputSchema;
 exports.TimelapseRulePatchSchema = TimelapseRulePatchSchema;
@@ -40136,6 +40452,7 @@ exports.colorForKind = colorForKind;
 exports.compileExpression = compileExpression;
 exports.compileExpressionSafe = compileExpressionSafe;
 exports.conditionDepth = conditionDepth;
+exports.connectionTestCapability = connectionTestCapability;
 exports.connectivityCapability = connectivityCapability;
 exports.consumablesCapability = consumablesCapability;
 exports.contactCapability = contactCapability;