@camstack/addon-provider-homematic 1.2.11 → 1.2.12

package/dist/addon.js

@@ -8,7 +8,7 @@ let http = require("http");
 let crypto$1 = require("crypto");
 let fs_promises = require("fs/promises");
 let path = require("path");
-//#region ../types/dist/event-category-41fKf-q9.mjs
+//#region ../types/dist/event-category-Cv9dO26A.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -24,6 +24,13 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* A newer addon or server-root package version was found by the
+	* authoritative registry check. Emitted once per
+	* `(target, packageName, currentVersion, latestVersion)` transition; repeated
+	* polling of the same result is deduplicated by the checker.
+	*/
+	EventCategory["UpdateAvailable"] = "update.available";
+	/**
 	* Readiness transition for a capability provider. Every producer emits
 	* this event on `onInitialize` completion, `onDestroy`, and
 	* `$node.reconnect`; every consumer that needs to gate on a cross-process
@@ -7123,6 +7130,104 @@ object({
 	})
 });
 /**
+* 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 = _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 = _enum([
+	"adopted",
+	"already-adopted",
+	"failed",
+	"cancelled"
+]);
+var AdoptionCandidateResultSchema = object({
+	childNativeId: string(),
+	outcome: AdoptionOutcomeSchema,
+	/** The materialised parent device id — null for `failed` / `cancelled`. */
+	parentDeviceId: number().int().nonnegative().nullable(),
+	/** Accessory children created for this candidate. */
+	accessoryCount: number().int().nonnegative(),
+	/** Failure message; null unless `outcome === 'failed'`. */
+	error: string().nullable()
+});
+var AdoptionJobSchema = object({
+	jobId: string(),
+	/** The integration provider this job adopts through (the `addonId` pin). */
+	addonId: string(),
+	integrationId: string(),
+	state: AdoptionJobStateSchema,
+	/** Candidates the job was asked to adopt. Known up front, so never null. */
+	total: number().int().nonnegative(),
+	/** Candidates that have reached a terminal bucket. */
+	processed: number().int().nonnegative(),
+	adopted: number().int().nonnegative(),
+	alreadyAdopted: number().int().nonnegative(),
+	failed: 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: number().int().nonnegative(),
+	/** The candidate currently being adopted; null when idle or finished. */
+	currentChildNativeId: string().nullable(),
+	/** One entry per candidate, in the order they were processed. */
+	results: array(AdoptionCandidateResultSchema).readonly(),
+	startedAt: number(),
+	finishedAt: number().nullable(),
+	/** Set only when the job itself broke (not a per-candidate failure). */
+	error: string().nullable()
+});
+/**
 * Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
 * pipeline functions an operator thinks in terms of.
 *
@@ -12105,6 +12210,15 @@ method(object({
 }), method(ReleaseInputSchema.extend({ addonId: string() }), _void(), {
 	kind: "mutation",
 	auth: "admin"
+}), method(AdoptInputSchema.extend({ addonId: string() }), object({ jobId: string() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	addonId: string(),
+	integrationId: string().optional()
+}), array(AdoptionJobSchema).readonly(), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(ResyncInputSchema, ResyncResultSchema, {
 	kind: "mutation",
 	auth: "admin"
@@ -14020,8 +14134,35 @@ var NcDeliverySchema = _enum([
 	"immediate",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
+/**
+* Stable Notification Center vocabulary over infrastructure/liveness events.
+* Bus categories are normalized into these intent-level kinds so rules do not
+* depend on a provider's raw event name or payload shape.
+*/
+var NcSystemEventKindSchema = _enum([
+	"camera-online",
+	"camera-offline",
+	"stream-online",
+	"stream-offline",
+	"node-online",
+	"node-offline",
+	"addon-update-available",
+	"server-update-available"
+]);
+/**
+* One coherent system-event condition. `kinds` is the required opt-in safety
+* gate; the remaining lists are optional narrowing filters relevant to the
+* selected kinds.
+*/
+var NcSystemEventConditionSchema = object({
+	kinds: array(NcSystemEventKindSchema).min(1),
+	deviceIds: array(number().int()).min(1).optional(),
+	nodeIds: array(string().min(1)).min(1).optional(),
+	packageNames: array(string().min(1)).min(1).optional()
+});
 /** Weekly schedule — OR of windows; absence on the rule = always active. */
 var NcScheduleSchema = object({
 	windows: array(object({
@@ -14326,6 +14467,8 @@ var NcConditionsSchema = object({
 		"picked-up",
 		"both"
 	]).optional(),
+	/** Infrastructure/liveness/update event matcher (`system-event` delivery). */
+	systemEvent: NcSystemEventConditionSchema.optional(),
 	/**
 	* PERSONAL-RULE custom zones (viewer-drawn). Inline normalized polygons
 	* (MaskShape vocabulary). A record passes when its bbox overlaps ANY
@@ -14545,7 +14688,8 @@ var NcTestResultSchema = object({
 		"object-event",
 		"track",
 		"device-event",
-		"package-event"
+		"package-event",
+		"system-event"
 	]),
 	deviceId: number(),
 	timestamp: number(),
@@ -14567,7 +14711,8 @@ var NcConditionDescriptorSchema = object({
 		"schedule",
 		"device",
 		"package",
-		"occupancy"
+		"occupancy",
+		"system"
 	]),
 	label: string(),
 	/** Editor widget the UI renders — never hardcode per-condition forms. */
@@ -14585,7 +14730,8 @@ var NcConditionDescriptorSchema = object({
 		"crossingSelect",
 		"polygonDraw",
 		"occupancy",
-		"deviceState"
+		"deviceState",
+		"systemEvent"
 	]),
 	operator: _enum([
 		"in",
@@ -14644,7 +14790,8 @@ var NcHistoryRecordKindSchema = _enum([
 	"object-event",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
 /** Subject summary frozen on the row at fire time (survives rule/record edits). */
 var NcHistorySubjectSchema = object({
@@ -14652,7 +14799,14 @@ var NcHistorySubjectSchema = object({
 	label: string().optional(),
 	confidence: number().optional(),
 	zones: array(string()),
-	timestamp: number()
+	timestamp: number(),
+	systemEvent: object({
+		kind: NcSystemEventKindSchema,
+		subject: string(),
+		title: string(),
+		body: string(),
+		data: record(string(), unknown())
+	}).optional()
 });
 /**
 * One delivery-history row. This is a read-only VIEW over the durable
@@ -15012,6 +15166,76 @@ object({
 * Each provider returns a static descriptor; the core enumerates them
 * to validate the `integration=` query param and resolve the consent
 * label + the scopes baked into the issued token.
+*
+* ## Declaring one
+*
+* An OAuth client is integration-specific knowledge — who the client is, what
+* it may ask for, where it may be sent — so it is declared by the ADDON that
+* owns the integration, never by the kernel and never as a branch inside
+* `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+* steps, no others:
+*
+* 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+*    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+*    a descriptor is owed — see "the boot window" below.
+* 2. Return a provider from `onInitialize()`:
+*
+*    ```ts
+*    const provider: IOauthIntegrationProvider = {
+*      getDescriptor: async () => ({
+*        integrationId: 'my-thing',      // the `integration=` query param
+*        displayName: 'My Thing',
+*        requestedScopes: [ … ],         // see below
+*        allowedRedirectPrefixes: ['https://callback.example/'],
+*      }),
+*    }
+*    return [{ capability: oauthIntegrationCapability, provider }]
+*    ```
+*
+*    The descriptor must be **static** — it is read on the authorize path, so
+*    never put an await on network or disk behind it, and never register it
+*    behind one either (a provider is registered only once `onInitialize`
+*    RETURNS, so anything awaited before the return delays linking).
+* 3. Nothing else. There is no allow-list to join, no id to register with the
+*    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+*    `/api/oauth2/integrations` are built from this collection alone.
+*
+* **Scopes. `requestedScopes` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* Prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family; a category scope grants every future member
+* of that category too. `category:system [create]` has been rejected once and
+* should stay rejected: it hands `addons.installPackage` to an integration.
+*
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
+*
+* **The boot window.** An addon registers its provider after its runner forks
+* and initialises, so between hub start and that moment this collection is
+* incomplete and an `integrationId` can be legitimately absent. The core does
+* not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+* it compares the manifest declarers against the registered providers and
+* answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+* addon ids) instead of `400 unknown integration`, and reports
+* `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+* while the list is incomplete rather than conclude the hub cannot do OAuth.
 */
 var OauthIntegrationDescriptorSchema = object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */
@@ -15042,7 +15266,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 method(_void(), OauthIntegrationDescriptorSchema);
 /**
@@ -18179,11 +18426,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -20164,6 +20429,37 @@ onColorChanged: { data: object({
 	*/
 	runtimeState: ColorStatusSchema
 };
+var ConnectionTestOutcomeSchema = discriminatedUnion("outcome", [
+	object({
+		outcome: literal("validated"),
+		/** Round-trip of the sign-in, when the provider measured it. */
+		latencyMs: number().nonnegative().optional(),
+		/** Optional human detail worth showing next to the tick
+		*  ("3 devices visible on this account"). */
+		detail: string().optional()
+	}).strict(),
+	object({
+		outcome: literal("rejected"),
+		error: string()
+	}).strict(),
+	object({
+		outcome: literal("inconclusive"),
+		error: string()
+	}).strict()
+]);
+var ConnectionTestInputSchema = object({ 
+/** Candidate integration settings, exactly as the create form collected them. */
+settings: record(string(), 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 = object({ label: string() });
+method(ConnectionTestInputSchema, ConnectionTestOutcomeSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(_void(), ConnectionTestDescriptorSchema, { auth: "admin" });
 /**
 * Upstream-system connectivity sensor — distinct from `device-status`,
 * which is the kernel-managed online/offline flag for the device's
@@ -21525,15 +21821,57 @@ var AvailableIntegrationTypeSchema = object({
 	*  flow can import (e.g. HA areas). Drives the adopt modal's "import
 	*  locations" checkbox. Provider-declared in the addon manifest. */
 	supportsLocationImport: 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: boolean(),
 	existingInstances: array(object({
 		id: string(),
 		name: string()
 	})),
 	canAdd: 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 = _enum([
+	"validated",
+	"rejected",
+	"inconclusive",
+	"unsupported"
+]);
 var TestConnectionResultSchema$1 = object({
+	/** True ONLY for `validated`. Never true for a test that did not run. */
 	success: boolean(),
-	error: string().optional()
+	error: 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: string().nullable().optional(),
+	latencyMs: number().nonnegative().optional(),
+	/** Human detail from a `validated` result ("3 devices on this account"). */
+	detail: string().optional()
 });
 var CreateIntegrationInputSchema = object({
 	addonId: string(),
@@ -25302,7 +25640,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"
@@ -27756,6 +28099,18 @@ 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",
@@ -28146,6 +28501,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionCancelJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.adoptionListCandidateFilters": {
 		capName: "device-manager",
 		capScope: "system",
@@ -28158,6 +28519,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceManager.adoptionListJobs": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"deviceManager.adoptionRefresh": {
 		capName: "device-manager",
 		capScope: "system",
@@ -28176,6 +28543,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionStartJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.allocateDeviceId": {
 		capName: "device-manager",
 		capScope: "system",

package/dist/addon.mjs

@@ -9,7 +9,7 @@ import { join } from "path";
 var __commonJSMin = (cb, mod) => () => (mod || (cb((mod = { exports: {} }).exports, mod), cb = null), mod.exports);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
-//#region ../types/dist/event-category-41fKf-q9.mjs
+//#region ../types/dist/event-category-Cv9dO26A.mjs
 var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	EventCategory["SystemBoot"] = "system.boot";
 	EventCategory["SystemAddonsReady"] = "system.addons-ready";
@@ -25,6 +25,13 @@ var EventCategory = /* @__PURE__ */ function(EventCategory) {
 	*/
 	EventCategory["SystemRestartCompleted"] = "system.restart-completed";
 	/**
+	* A newer addon or server-root package version was found by the
+	* authoritative registry check. Emitted once per
+	* `(target, packageName, currentVersion, latestVersion)` transition; repeated
+	* polling of the same result is deduplicated by the checker.
+	*/
+	EventCategory["UpdateAvailable"] = "update.available";
+	/**
 	* Readiness transition for a capability provider. Every producer emits
 	* this event on `onInitialize` completion, `onDestroy`, and
 	* `$node.reconnect`; every consumer that needs to gate on a cross-process
@@ -7124,6 +7131,104 @@ object({
 	})
 });
 /**
+* 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 = _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 = _enum([
+	"adopted",
+	"already-adopted",
+	"failed",
+	"cancelled"
+]);
+var AdoptionCandidateResultSchema = object({
+	childNativeId: string(),
+	outcome: AdoptionOutcomeSchema,
+	/** The materialised parent device id — null for `failed` / `cancelled`. */
+	parentDeviceId: number().int().nonnegative().nullable(),
+	/** Accessory children created for this candidate. */
+	accessoryCount: number().int().nonnegative(),
+	/** Failure message; null unless `outcome === 'failed'`. */
+	error: string().nullable()
+});
+var AdoptionJobSchema = object({
+	jobId: string(),
+	/** The integration provider this job adopts through (the `addonId` pin). */
+	addonId: string(),
+	integrationId: string(),
+	state: AdoptionJobStateSchema,
+	/** Candidates the job was asked to adopt. Known up front, so never null. */
+	total: number().int().nonnegative(),
+	/** Candidates that have reached a terminal bucket. */
+	processed: number().int().nonnegative(),
+	adopted: number().int().nonnegative(),
+	alreadyAdopted: number().int().nonnegative(),
+	failed: 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: number().int().nonnegative(),
+	/** The candidate currently being adopted; null when idle or finished. */
+	currentChildNativeId: string().nullable(),
+	/** One entry per candidate, in the order they were processed. */
+	results: array(AdoptionCandidateResultSchema).readonly(),
+	startedAt: number(),
+	finishedAt: number().nullable(),
+	/** Set only when the job itself broke (not a per-candidate failure). */
+	error: string().nullable()
+});
+/**
 * Per-camera FUNCTION SWITCHES — the one coherent on/off surface over the
 * pipeline functions an operator thinks in terms of.
 *
@@ -12106,6 +12211,15 @@ method(object({
 }), method(ReleaseInputSchema.extend({ addonId: string() }), _void(), {
 	kind: "mutation",
 	auth: "admin"
+}), method(AdoptInputSchema.extend({ addonId: string() }), object({ jobId: string() }), {
+	kind: "mutation",
+	auth: "admin"
+}), method(object({
+	addonId: string(),
+	integrationId: string().optional()
+}), array(AdoptionJobSchema).readonly(), { auth: "admin" }), method(object({ jobId: string() }), object({ cancelled: boolean() }), {
+	kind: "mutation",
+	auth: "admin"
 }), method(ResyncInputSchema, ResyncResultSchema, {
 	kind: "mutation",
 	auth: "admin"
@@ -14021,8 +14135,35 @@ var NcDeliverySchema = _enum([
 	"immediate",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
+/**
+* Stable Notification Center vocabulary over infrastructure/liveness events.
+* Bus categories are normalized into these intent-level kinds so rules do not
+* depend on a provider's raw event name or payload shape.
+*/
+var NcSystemEventKindSchema = _enum([
+	"camera-online",
+	"camera-offline",
+	"stream-online",
+	"stream-offline",
+	"node-online",
+	"node-offline",
+	"addon-update-available",
+	"server-update-available"
+]);
+/**
+* One coherent system-event condition. `kinds` is the required opt-in safety
+* gate; the remaining lists are optional narrowing filters relevant to the
+* selected kinds.
+*/
+var NcSystemEventConditionSchema = object({
+	kinds: array(NcSystemEventKindSchema).min(1),
+	deviceIds: array(number().int()).min(1).optional(),
+	nodeIds: array(string().min(1)).min(1).optional(),
+	packageNames: array(string().min(1)).min(1).optional()
+});
 /** Weekly schedule — OR of windows; absence on the rule = always active. */
 var NcScheduleSchema = object({
 	windows: array(object({
@@ -14327,6 +14468,8 @@ var NcConditionsSchema = object({
 		"picked-up",
 		"both"
 	]).optional(),
+	/** Infrastructure/liveness/update event matcher (`system-event` delivery). */
+	systemEvent: NcSystemEventConditionSchema.optional(),
 	/**
 	* PERSONAL-RULE custom zones (viewer-drawn). Inline normalized polygons
 	* (MaskShape vocabulary). A record passes when its bbox overlaps ANY
@@ -14546,7 +14689,8 @@ var NcTestResultSchema = object({
 		"object-event",
 		"track",
 		"device-event",
-		"package-event"
+		"package-event",
+		"system-event"
 	]),
 	deviceId: number(),
 	timestamp: number(),
@@ -14568,7 +14712,8 @@ var NcConditionDescriptorSchema = object({
 		"schedule",
 		"device",
 		"package",
-		"occupancy"
+		"occupancy",
+		"system"
 	]),
 	label: string(),
 	/** Editor widget the UI renders — never hardcode per-condition forms. */
@@ -14586,7 +14731,8 @@ var NcConditionDescriptorSchema = object({
 		"crossingSelect",
 		"polygonDraw",
 		"occupancy",
-		"deviceState"
+		"deviceState",
+		"systemEvent"
 	]),
 	operator: _enum([
 		"in",
@@ -14645,7 +14791,8 @@ var NcHistoryRecordKindSchema = _enum([
 	"object-event",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
 /** Subject summary frozen on the row at fire time (survives rule/record edits). */
 var NcHistorySubjectSchema = object({
@@ -14653,7 +14800,14 @@ var NcHistorySubjectSchema = object({
 	label: string().optional(),
 	confidence: number().optional(),
 	zones: array(string()),
-	timestamp: number()
+	timestamp: number(),
+	systemEvent: object({
+		kind: NcSystemEventKindSchema,
+		subject: string(),
+		title: string(),
+		body: string(),
+		data: record(string(), unknown())
+	}).optional()
 });
 /**
 * One delivery-history row. This is a read-only VIEW over the durable
@@ -15013,6 +15167,76 @@ object({
 * Each provider returns a static descriptor; the core enumerates them
 * to validate the `integration=` query param and resolve the consent
 * label + the scopes baked into the issued token.
+*
+* ## Declaring one
+*
+* An OAuth client is integration-specific knowledge — who the client is, what
+* it may ask for, where it may be sent — so it is declared by the ADDON that
+* owns the integration, never by the kernel and never as a branch inside
+* `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+* steps, no others:
+*
+* 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+*    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+*    a descriptor is owed — see "the boot window" below.
+* 2. Return a provider from `onInitialize()`:
+*
+*    ```ts
+*    const provider: IOauthIntegrationProvider = {
+*      getDescriptor: async () => ({
+*        integrationId: 'my-thing',      // the `integration=` query param
+*        displayName: 'My Thing',
+*        requestedScopes: [ … ],         // see below
+*        allowedRedirectPrefixes: ['https://callback.example/'],
+*      }),
+*    }
+*    return [{ capability: oauthIntegrationCapability, provider }]
+*    ```
+*
+*    The descriptor must be **static** — it is read on the authorize path, so
+*    never put an await on network or disk behind it, and never register it
+*    behind one either (a provider is registered only once `onInitialize`
+*    RETURNS, so anything awaited before the return delays linking).
+* 3. Nothing else. There is no allow-list to join, no id to register with the
+*    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+*    `/api/oauth2/integrations` are built from this collection alone.
+*
+* **Scopes. `requestedScopes` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* Prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family; a category scope grants every future member
+* of that category too. `category:system [create]` has been rejected once and
+* should stay rejected: it hands `addons.installPackage` to an integration.
+*
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
+*
+* **The boot window.** An addon registers its provider after its runner forks
+* and initialises, so between hub start and that moment this collection is
+* incomplete and an `integrationId` can be legitimately absent. The core does
+* not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+* it compares the manifest declarers against the registered providers and
+* answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+* addon ids) instead of `400 unknown integration`, and reports
+* `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+* while the list is incomplete rather than conclude the hub cannot do OAuth.
 */
 var OauthIntegrationDescriptorSchema = object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */
@@ -15043,7 +15267,30 @@ var OauthIntegrationDescriptorSchema = object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: string().optional()
+	hubUrl: string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: union([number().int().positive(), literal("never")]).optional()
 });
 method(_void(), OauthIntegrationDescriptorSchema);
 /**
@@ -18180,11 +18427,29 @@ var SsoBridgeClaimsSchema = object({
 	codeChallenge: string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: string().optional()
+	sessionId: string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: union([number().int().positive(), literal("never")]).optional()
 });
 method(object({
 	claims: SsoBridgeClaimsSchema,
-	ttlSec: number().int().positive().optional()
+	/**
+	* Seconds, or `'never'` for a token minted with NO `exp` claim.
+	*
+	* `'never'` is a literal rather than `undefined`/`0` because omitting
+	* this field already means "the 5-minute SSO hand-off default", and
+	* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+	* went through the numeric path would fail at mint time and break
+	* linking rather than produce an eternal token.
+	*/
+	ttlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ token: string() })), method(object({ token: string() }), SsoBridgeClaimsSchema.nullable());
 var ProviderListEntrySchema = discriminatedUnion("shouldSaveDiskSpace", [object({
 	providerId: string().min(1),
@@ -20165,6 +20430,37 @@ onColorChanged: { data: object({
 	*/
 	runtimeState: ColorStatusSchema
 };
+var ConnectionTestOutcomeSchema = discriminatedUnion("outcome", [
+	object({
+		outcome: literal("validated"),
+		/** Round-trip of the sign-in, when the provider measured it. */
+		latencyMs: number().nonnegative().optional(),
+		/** Optional human detail worth showing next to the tick
+		*  ("3 devices visible on this account"). */
+		detail: string().optional()
+	}).strict(),
+	object({
+		outcome: literal("rejected"),
+		error: string()
+	}).strict(),
+	object({
+		outcome: literal("inconclusive"),
+		error: string()
+	}).strict()
+]);
+var ConnectionTestInputSchema = object({ 
+/** Candidate integration settings, exactly as the create form collected them. */
+settings: record(string(), 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 = object({ label: string() });
+method(ConnectionTestInputSchema, ConnectionTestOutcomeSchema, {
+	kind: "mutation",
+	auth: "admin"
+}), method(_void(), ConnectionTestDescriptorSchema, { auth: "admin" });
 /**
 * Upstream-system connectivity sensor — distinct from `device-status`,
 * which is the kernel-managed online/offline flag for the device's
@@ -21526,15 +21822,57 @@ var AvailableIntegrationTypeSchema = object({
 	*  flow can import (e.g. HA areas). Drives the adopt modal's "import
 	*  locations" checkbox. Provider-declared in the addon manifest. */
 	supportsLocationImport: 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: boolean(),
 	existingInstances: array(object({
 		id: string(),
 		name: string()
 	})),
 	canAdd: 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 = _enum([
+	"validated",
+	"rejected",
+	"inconclusive",
+	"unsupported"
+]);
 var TestConnectionResultSchema$1 = object({
+	/** True ONLY for `validated`. Never true for a test that did not run. */
 	success: boolean(),
-	error: string().optional()
+	error: 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: string().nullable().optional(),
+	latencyMs: number().nonnegative().optional(),
+	/** Human detail from a `validated` result ("3 devices on this account"). */
+	detail: string().optional()
 });
 var CreateIntegrationInputSchema = object({
 	addonId: string(),
@@ -25303,7 +25641,12 @@ method(_void(), array(UserSummarySchema), { auth: "admin" }), method(CreateUserI
 	hubUrl: string(),
 	/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 	*  that carries one can ONLY be exchanged with the matching verifier. */
-	codeChallenge: string().optional()
+	codeChallenge: string().optional(),
+	/** The integration's declared refresh lifetime — seconds, or `'never'`.
+	*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+	*  code so the link carries its own lifetime; omit for the 30-day
+	*  default. */
+	refreshTtlSec: union([number().int().positive(), literal("never")]).optional()
 }), object({ code: string() }), {
 	kind: "mutation",
 	access: "create"
@@ -27757,6 +28100,18 @@ 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",
@@ -28147,6 +28502,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionCancelJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.adoptionListCandidateFilters": {
 		capName: "device-manager",
 		capScope: "system",
@@ -28159,6 +28520,12 @@ Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"deviceManager.adoptionListJobs": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"deviceManager.adoptionRefresh": {
 		capName: "device-manager",
 		capScope: "system",
@@ -28177,6 +28544,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"deviceManager.adoptionStartJob": {
+		capName: "device-manager",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"deviceManager.allocateDeviceId": {
 		capName: "device-manager",
 		capScope: "system",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/addon-provider-homematic",
-  "version": "1.2.11",
+  "version": "1.2.12",
   "description": "Homematic / HomematicIP (CCU3 / RaspberryMatic) device-provider addon for CamStack — wraps the nodehomematic library",
   "keywords": [
     "camstack",