@camstack/types 1.2.52 → 1.2.54

package/dist/capabilities/connection-test.cap.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+/**
+ * `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. */
+export declare const CONNECTION_TEST_TIMEOUT_MS = 20000;
+export declare const ConnectionTestOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    outcome: z.ZodLiteral<"validated">;
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"rejected">;
+    error: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    outcome: z.ZodLiteral<"inconclusive">;
+    error: z.ZodString;
+}, z.core.$strict>], "outcome">;
+export type ConnectionTestOutcome = z.infer<typeof ConnectionTestOutcomeSchema>;
+export declare const ConnectionTestInputSchema: z.ZodObject<{
+    settings: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * 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.
+ */
+export declare const ConnectionTestDescriptorSchema: z.ZodObject<{
+    label: z.ZodString;
+}, z.core.$strip>;
+export declare const connectionTestCapability: {
+    readonly name: "connection-test";
+    readonly scope: "system";
+    readonly mode: "collection";
+    readonly methods: {
+        readonly testSettings: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            settings: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
+            outcome: z.ZodLiteral<"validated">;
+            latencyMs: z.ZodOptional<z.ZodNumber>;
+            detail: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"rejected">;
+            error: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            outcome: z.ZodLiteral<"inconclusive">;
+            error: z.ZodString;
+        }, z.core.$strict>], "outcome">, "mutation">;
+        readonly describeTest: import("./capability-definition.js").CapabilityMethodSchema<z.ZodVoid, z.ZodObject<{
+            label: z.ZodString;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+    };
+};
+export type IConnectionTestProvider = InferProvider<typeof connectionTestCapability>;

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

@@ -1159,6 +1159,73 @@ export declare const deviceManagerCapability: {
             camDeviceId: z.ZodNumber;
             addonId: z.ZodString;
         }, z.core.$strip>, z.ZodVoid, "mutation">;
+        /**
+         * 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.
+         */
+        readonly adoptionStartJob: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            integrationId: z.ZodString;
+            childNativeIds: z.ZodArray<z.ZodString>;
+            filter: z.ZodOptional<z.ZodString>;
+            importLocations: z.ZodOptional<z.ZodBoolean>;
+            perCandidate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                name: z.ZodOptional<z.ZodString>;
+                hiddenChildIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strip>>>;
+            addonId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            jobId: z.ZodString;
+        }, z.core.$strip>, "mutation">;
+        /**
+         * 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.
+         */
+        readonly adoptionListJobs: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            addonId: z.ZodString;
+            integrationId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodReadonly<z.ZodArray<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>>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** Cooperative cancel: the in-flight candidate finishes, the rest never start. */
+        readonly adoptionCancelJob: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            jobId: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            cancelled: z.ZodBoolean;
+        }, z.core.$strip>, "mutation">;
         /**
          * Re-sync a device with its source via the device-adoption provider of the
          * device's OWNING addon (resolved from `camDeviceId`). Unlike the singleton

package/dist/capabilities/index.d.ts

@@ -127,6 +127,7 @@ export { type CameraCredentials, CameraCredentialsSchema, type CameraCredentials
 export { type CarbonMonoxideStatus, CarbonMonoxideStatusSchema, carbonMonoxideCapability, type ICarbonMonoxideProvider, } from './carbon-monoxide.cap.js';
 export { type ClimateControlStatus, ClimateControlStatusSchema, climateControlCapability, type HvacMode, HvacModeSchema, type IClimateControlProvider, } from './climate-control.cap.js';
 export { type ColorHsvTriplet, type ColorInput, type ColorRgbTriplet, type ColorStatus, ColorStatusSchema, colorCapability, type IColorProvider, } from './color.cap.js';
+export { CONNECTION_TEST_TIMEOUT_MS, ConnectionTestDescriptorSchema, ConnectionTestInputSchema, type ConnectionTestOutcome, ConnectionTestOutcomeSchema, connectionTestCapability, type IConnectionTestProvider, } from './connection-test.cap.js';
 export { type ConnectivityStatus, ConnectivityStatusSchema, connectivityCapability, type IConnectivityProvider, } from './connectivity.cap.js';
 export { type ConsumableItem, ConsumableItemSchema, type ConsumablesStatus, ConsumablesStatusSchema, consumablesCapability, type IConsumablesProvider, } from './consumables.cap.js';
 export { type ContactStatus, ContactStatusSchema, contactCapability, type IContactProvider, } from './contact.cap.js';
@@ -149,7 +150,7 @@ export { type HumidifierStatus, HumidifierStatusSchema, humidifierCapability, ty
 export { type HumiditySensorStatus, HumiditySensorStatusSchema, humiditySensorCapability, type IHumiditySensorProvider, } from './humidity-sensor.cap.js';
 export { type IImageProvider, type ImageStatus, ImageStatusSchema, imageCapability, } from './image.cap.js';
 export { type BacklightMode, BacklightModeSchema, type ExposureMode, ExposureModeSchema, type IImageSettingsProvider, type ImageRotate, ImageRotateSchema, type ImageSettingsOptions, ImageSettingsOptionsSchema, type ImageSettingsPatch, ImageSettingsPatchSchema, type ImageSettingsStatus, ImageSettingsStatusSchema, imageSettingsCapability, type WhiteBalanceMode, WhiteBalanceModeSchema, } from './image-settings.cap.js';
-export { AvailableIntegrationTypeSchema, CreateIntegrationInputSchema, DeleteIntegrationResultSchema, type IIntegrationsProvider, IntegrationLiteSchema, IntegrationWithStateSchema, integrationsCapability, TestConnectionResultSchema, UpdateIntegrationInputSchema, } from './integrations.cap.js';
+export { AvailableIntegrationTypeSchema, CreateIntegrationInputSchema, DeleteIntegrationResultSchema, type IIntegrationsProvider, IntegrationLiteSchema, type IntegrationTestConnectionResult, type IntegrationTestConnectionStatus, IntegrationWithStateSchema, integrationsCapability, TestConnectionResultSchema, TestConnectionStatusEnum, UpdateIntegrationInputSchema, } from './integrations.cap.js';
 export { type IIntercomProvider, type IntercomAbility, IntercomAbilitySchema, type IntercomStatus, IntercomStatusSchema, intercomCapability, } from './intercom.cap.js';
 export { type DeviceCodeSeverity, DeviceCodeSeveritySchema, type ILawnMowerControlProvider, type LawnMowerActivity, LawnMowerActivitySchema, type LawnMowerControlStatus, LawnMowerControlStatusSchema, lawnMowerControlCapability, } from './lawn-mower-control.cap.js';
 export { type ConnectionEndpoint, type ILocalNetworkProvider, type LocalInterface, localNetworkCapability, } from './local-network.cap.js';
@@ -233,6 +234,7 @@ import type { cameraStreamsCapability } from './camera-streams.cap.js';
 import type { carbonMonoxideCapability } from './carbon-monoxide.cap.js';
 import type { climateControlCapability } from './climate-control.cap.js';
 import type { colorCapability } from './color.cap.js';
+import type { connectionTestCapability } from './connection-test.cap.js';
 import type { connectivityCapability } from './connectivity.cap.js';
 import type { consumablesCapability } from './consumables.cap.js';
 import type { contactCapability } from './contact.cap.js';
@@ -349,6 +351,6 @@ import type { webrtcSessionCapability } from './webrtc-session.cap.js';
 import type { zoneAnalyticsCapability } from './zone-analytics.cap.js';
 import type { zoneRulesCapability } from './zone-rules.cap.js';
 import type { zonesCapability } from './zones.cap.js';
-type AnyCapability = typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof logDestinationCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof consumablesCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof eventsCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingExportCapability | typeof deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability;
+type AnyCapability = typeof addonSettingsCapability | typeof alertsCapability | typeof storageCapability | typeof storageProviderCapability | typeof storageEvictableCapability | typeof filesystemBrowseCapability | typeof backupCapability | typeof terminalSessionCapability | typeof settingsStoreCapability | typeof dataStoreProviderCapability | typeof logDestinationCapability | typeof adminUiCapability | typeof viewerUiCapability | typeof ssoBridgeCapability | typeof userPasskeysCapability | typeof smtpProviderCapability | typeof mqttBrokerCapability | typeof brokerCapability | typeof deviceAdoptionCapability | typeof deviceExportCapability | typeof addonPagesCapability | typeof addonPagesSourceCapability | typeof addonWidgetsCapability | typeof addonWidgetsSourceCapability | typeof customModelRegistryCapability | typeof modelDistributorCapability | typeof modelConvertCapability | typeof addonRoutesCapability | typeof streamBrokerCapability | typeof decoderCapability | typeof webrtcSessionCapability | typeof cameraStreamsCapability | typeof motionDetectionCapability | typeof pipelineExecutorCapability | typeof detectionPipelineCapability | typeof cameraPipelineConfigCapability | typeof pipelineRunnerCapability | typeof pipelineOrchestratorCapability | typeof audioAnalyzerCapability | typeof audioAnalysisCapability | typeof audioCodecCapability | typeof embeddingEncoderCapability | typeof vectorStoreCapability | typeof deviceProviderCapability | typeof deviceManagerCapability | typeof deviceStateCapability | typeof authProviderCapability | typeof loginMethodCapability | typeof networkAccessCapability | typeof turnProviderCapability | typeof snapshotCapability | typeof llmCapability | typeof llmRuntimeCapability | typeof notificationOutputCapability | typeof coreBlocksCapability | typeof notificationRulesCapability | typeof pipelineAnalyticsCapability | typeof metricsProviderCapability | typeof ptzCapability | typeof ptzAutotrackCapability | typeof consumablesCapability | typeof connectionTestCapability | typeof rebootCapability | typeof deviceDiscoveryCapability | typeof brightnessCapability | typeof colorCapability | typeof climateControlCapability | typeof coverCapability | typeof valveCapability | typeof humidifierCapability | typeof waterHeaterCapability | typeof weatherCapability | typeof imageCapability | typeof lockControlCapability | typeof vacuumControlCapability | typeof petFeederCapability | typeof lawnMowerControlCapability | typeof fanControlCapability | typeof controlCapability | typeof notifierCapability | typeof mediaPlayerCapability | typeof alarmPanelCapability | typeof presenceCapability | typeof scriptRunnerCapability | typeof automationControlCapability | typeof motionTriggerCapability | typeof eventsCapability | typeof zonesCapability | typeof zoneRulesCapability | typeof zoneAnalyticsCapability | typeof audioMetricsCapability | typeof motionCapability | typeof contactCapability | typeof floodCapability | typeof smokeCapability | typeof carbonMonoxideCapability | typeof gasCapability | typeof tamperCapability | typeof vibrationCapability | typeof connectivityCapability | typeof binaryCapability | typeof temperatureSensorCapability | typeof humiditySensorCapability | typeof ambientLightSensorCapability | typeof pressureSensorCapability | typeof powerMeterCapability | typeof airQualitySensorCapability | typeof numericSensorCapability | typeof enumSensorCapability | typeof recordingCapability | typeof recordingExportCapability | typeof deviceOpsCapability | typeof platformProbeCapability | typeof localNetworkCapability | typeof meshNetworkCapability | typeof userManagementCapability | typeof systemCapability | typeof networkQualityCapability | typeof toastCapability | typeof nodesCapability | typeof serverManagementCapability | typeof integrationsCapability | typeof addonsCapability | typeof oauthIntegrationCapability | typeof streamParamsCapability | typeof streamCatalogCapability | typeof motionZonesCapability | typeof sceneMonitorCapability | typeof privacyMaskCapability | typeof dayNightCapability | typeof imageSettingsCapability | typeof osdCapability | typeof osdManagerCapability | typeof accessoriesCapability | typeof batteryCapability | typeof buttonCapability | typeof cameraCredentialsCapability | typeof deviceStatusCapability | typeof doorbellCapability | typeof eventEmitterCapability | typeof faceGalleryCapability | typeof featureProbeCapability | typeof intercomCapability | typeof nativeObjectDetectionCapability | typeof plateGalleryCapability | typeof switchCapability | typeof updateCapability | typeof videoclipsCapability;
 export type CapabilityName = AnyCapability['name'];
 export type ITypedReadinessRegistry = IReadinessRegistry<CapabilityName>;

package/dist/capabilities/integrations.cap.d.ts

@@ -54,15 +54,50 @@ declare const AvailableIntegrationTypeSchema: z.ZodObject<{
     }>;
     brokerKind: z.ZodNullable<z.ZodString>;
     supportsLocationImport: z.ZodBoolean;
+    canTest: z.ZodBoolean;
     existingInstances: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         name: z.ZodString;
     }, z.core.$strip>>;
     canAdd: z.ZodBoolean;
 }, z.core.$strip>;
+/**
+ * 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.
+ */
+declare const TestConnectionStatusEnum: z.ZodEnum<{
+    validated: "validated";
+    rejected: "rejected";
+    inconclusive: "inconclusive";
+    unsupported: "unsupported";
+}>;
 declare const TestConnectionResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
     error: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        validated: "validated";
+        rejected: "rejected";
+        inconclusive: "inconclusive";
+        unsupported: "unsupported";
+    }>>;
+    testedBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    latencyMs: z.ZodOptional<z.ZodNumber>;
+    detail: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 declare const CreateIntegrationInputSchema: z.ZodObject<{
     addonId: z.ZodString;
@@ -184,6 +219,7 @@ export declare const integrationsCapability: {
             }>;
             brokerKind: z.ZodNullable<z.ZodString>;
             supportsLocationImport: z.ZodBoolean;
+            canTest: z.ZodBoolean;
             existingInstances: z.ZodArray<z.ZodObject<{
                 id: z.ZodString;
                 name: z.ZodString;
@@ -196,6 +232,15 @@ export declare const integrationsCapability: {
         }, z.core.$strip>, z.ZodObject<{
             success: z.ZodBoolean;
             error: z.ZodOptional<z.ZodString>;
+            status: z.ZodOptional<z.ZodEnum<{
+                validated: "validated";
+                rejected: "rejected";
+                inconclusive: "inconclusive";
+                unsupported: "unsupported";
+            }>>;
+            testedBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            latencyMs: z.ZodOptional<z.ZodNumber>;
+            detail: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>, "mutation">;
     };
     /** BIG PLAN 2: declarative mount hint — read by `@camstack/system` `buildCapRouters`. */
@@ -204,4 +249,6 @@ export declare const integrationsCapability: {
     };
 };
 export type IIntegrationsProvider = InferProvider<typeof integrationsCapability>;
-export { IntegrationWithStateSchema, IntegrationLiteSchema, AvailableIntegrationTypeSchema, TestConnectionResultSchema, CreateIntegrationInputSchema, UpdateIntegrationInputSchema, DeleteIntegrationResultSchema, };
+export type IntegrationTestConnectionStatus = z.infer<typeof TestConnectionStatusEnum>;
+export type IntegrationTestConnectionResult = z.infer<typeof TestConnectionResultSchema>;
+export { AvailableIntegrationTypeSchema, CreateIntegrationInputSchema, DeleteIntegrationResultSchema, IntegrationLiteSchema, IntegrationWithStateSchema, TestConnectionResultSchema, TestConnectionStatusEnum, UpdateIntegrationInputSchema, };

package/dist/capabilities/oauth-integration.cap.d.ts

@@ -6,6 +6,65 @@ import { type InferProvider } from './capability-definition.js';
  * 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` is baked into every token this integration is
+ * ever issued and the operator consents to it once. Derive it from the tRPC
+ * paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
+ * 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.
+ *
+ * What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
+ * the addon and are not scope-checked. Alexa's descriptor is narrower than
+ * Home Assistant's for exactly that reason — its Lambda posts directives and
+ * the addon does the work, while the Home Assistant component calls tRPC
+ * directly with the token. So `requestedScopes` describes the blast radius of
+ * the GRANT, not the reach of the integration; do not widen one to describe the
+ * other.
+ *
+ * **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.
  */
 declare const OauthIntegrationDescriptorSchema: z.ZodObject<{
     integrationId: z.ZodString;

package/dist/generated/addon-api.d.ts

@@ -26,6 +26,7 @@ import type { cameraCredentialsCapability } from '../capabilities/camera-credent
 import type { cameraStreamsCapability } from '../capabilities/camera-streams.cap.js';
 import type { climateControlCapability } from '../capabilities/climate-control.cap.js';
 import type { colorCapability } from '../capabilities/color.cap.js';
+import type { connectionTestCapability } from '../capabilities/connection-test.cap.js';
 import type { consumablesCapability } from '../capabilities/consumables.cap.js';
 import type { controlCapability } from '../capabilities/control.cap.js';
 import type { coreBlocksCapability } from '../capabilities/core-blocks.cap.js';
@@ -1323,6 +1324,28 @@ export type AppRouter = TrpcCoreRouter<{
             meta: object;
         }>;
     }>>;
+    connectionTest: TRPCBuiltRouter<{
+        ctx: TrpcContext;
+        meta: object;
+        errorShape: AugmentedErrorShape;
+        transformer: true;
+    }, TRPCDecorateCreateRouterOptions<{
+        testSettings: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof connectionTestCapability.methods.testSettings.input>;
+            output: z.infer<typeof connectionTestCapability.methods.testSettings.output>;
+            meta: object;
+        }>;
+        describeTest: TRPCQueryProcedure<{
+            input: {
+                nodeId?: string | undefined;
+                addonId?: string | undefined;
+            } | undefined;
+            output: z.infer<typeof connectionTestCapability.methods.describeTest.output>;
+            meta: object;
+        }>;
+    }>>;
     connectivity: TRPCBuiltRouter<{
         ctx: TrpcContext;
         meta: object;
@@ -2419,6 +2442,27 @@ export type AppRouter = TrpcCoreRouter<{
             output: z.infer<typeof deviceManagerCapability.methods.adoptionRelease.output>;
             meta: object;
         }>;
+        adoptionStartJob: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.adoptionStartJob.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.adoptionStartJob.output>;
+            meta: object;
+        }>;
+        adoptionListJobs: TRPCQueryProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.adoptionListJobs.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.adoptionListJobs.output>;
+            meta: object;
+        }>;
+        adoptionCancelJob: TRPCMutationProcedure<{
+            input: {
+                [x: string]: unknown;
+            } & z.input<typeof deviceManagerCapability.methods.adoptionCancelJob.input>;
+            output: z.infer<typeof deviceManagerCapability.methods.adoptionCancelJob.output>;
+            meta: object;
+        }>;
         adoptionResync: TRPCMutationProcedure<{
             input: {
                 [x: string]: unknown;

package/dist/generated/capability-router-map.d.ts

@@ -29,6 +29,7 @@ export { cameraStreamsCapability } from '../capabilities/camera-streams.cap.js';
 export { carbonMonoxideCapability } from '../capabilities/carbon-monoxide.cap.js';
 export { climateControlCapability } from '../capabilities/climate-control.cap.js';
 export { colorCapability } from '../capabilities/color.cap.js';
+export { connectionTestCapability } from '../capabilities/connection-test.cap.js';
 export { connectivityCapability } from '../capabilities/connectivity.cap.js';
 export { consumablesCapability } from '../capabilities/consumables.cap.js';
 export { contactCapability } from '../capabilities/contact.cap.js';
@@ -177,6 +178,7 @@ export declare const CAPABILITY_NAMES: {
     readonly carbonMonoxide: "carbon-monoxide";
     readonly climateControl: "climate-control";
     readonly color: "color";
+    readonly connectionTest: "connection-test";
     readonly connectivity: "connectivity";
     readonly consumables: "consumables";
     readonly contact: "contact";
@@ -338,6 +340,7 @@ export interface CapabilityRouterMap<TRouter = unknown> {
     readonly carbonMonoxide: TRouter;
     readonly climateControl: TRouter;
     readonly color: TRouter;
+    readonly connectionTest: TRouter;
     readonly connectivity: TRouter;
     readonly consumables: TRouter;
     readonly contact: TRouter;
@@ -459,8 +462,8 @@ export interface CapabilityRouterMap<TRouter = unknown> {
 export declare const SINGLETON_CAPABILITY_NAMES: readonly ["accessories", "addon-pages", "addon-settings", "addon-widgets", "addons", "admin-ui", "air-quality-sensor", "alarm-panel", "alerts", "ambient-light-sensor", "audio-analysis", "audio-analyzer", "audio-codec", "audio-metrics", "automation-control", "backup", "battery", "binary", "brightness", "button", "camera-credentials", "camera-pipeline-config", "camera-streams", "carbon-monoxide", "climate-control", "color", "connectivity", "consumables", "contact", "control", "core-blocks", "cover", "day-night", "decoder", "detection-pipeline", "device-adoption", "device-discovery", "device-manager", "device-ops", "device-state", "device-status", "doorbell", "enum-sensor", "event-emitter", "events", "face-gallery", "fan-control", "feature-probe", "filesystem-browse", "flood", "gas", "humidifier", "humidity-sensor", "image", "image-settings", "integrations", "intercom", "lawn-mower-control", "llm-runtime", "local-network", "lock-control", "media-player", "metrics-provider", "model-convert", "model-distributor", "motion", "motion-detection", "motion-trigger", "motion-zones", "native-object-detection", "network-quality", "nodes", "notification-rules", "notifier", "numeric-sensor", "osd", "osd-manager", "pet-feeder", "pipeline-analytics", "pipeline-executor", "pipeline-orchestrator", "pipeline-runner", "plate-gallery", "platform-probe", "power-meter", "presence", "pressure-sensor", "privacy-mask", "ptz", "ptz-autotrack", "reboot", "recording", "recordingExport", "scene-monitor", "script-runner", "server-management", "settings-store", "smoke", "snapshot", "sso-bridge", "storage", "stream-broker", "stream-catalog", "stream-params", "switch", "system", "tamper", "temperature-sensor", "terminal-session", "toast", "update", "user-management", "vacuum-control", "valve", "vector-store", "vibration", "videoclips", "viewer-ui", "water-heater", "weather", "webrtc-session", "zone-analytics", "zone-rules", "zones"];
 /** Union of singleton capability names (literal string union). */
 export type SingletonCapabilityName = typeof SINGLETON_CAPABILITY_NAMES[number];
-/** Capability names whose mode is `collection` (23 caps). */
-export declare const COLLECTION_CAPABILITY_NAMES: readonly ["addon-pages-source", "addon-routes", "addon-widgets-source", "auth-provider", "broker", "custom-model-registry", "data-store-provider", "device-export", "device-provider", "embedding-encoder", "llm", "log-destination", "login-method", "mesh-network", "mqtt-broker", "network-access", "notification-output", "oauth-integration", "smtp-provider", "storage-evictable", "storage-provider", "turn-provider", "user-passkeys"];
+/** Capability names whose mode is `collection` (24 caps). */
+export declare const COLLECTION_CAPABILITY_NAMES: readonly ["addon-pages-source", "addon-routes", "addon-widgets-source", "auth-provider", "broker", "connection-test", "custom-model-registry", "data-store-provider", "device-export", "device-provider", "embedding-encoder", "llm", "log-destination", "login-method", "mesh-network", "mqtt-broker", "network-access", "notification-output", "oauth-integration", "smtp-provider", "storage-evictable", "storage-provider", "turn-provider", "user-passkeys"];
 /** Union of collection capability names (literal string union). */
 export type CollectionCapabilityName = typeof COLLECTION_CAPABILITY_NAMES[number];
 /** Capability mode lookup at runtime — mirrors the `.cap.ts` definitions. */

package/dist/generated/method-access-map.d.ts

@@ -6,7 +6,7 @@
  * scope+access check inside `protectedProcedure` (see
  * `server/backend/src/api/trpc/trpc.middleware.ts`).
  *
- * Coverage: 901 method paths across 121 capabilities.
+ * Coverage: 906 method paths across 122 capabilities.
  */
 import type { CapabilityMethodAccess } from '../capabilities/capability-definition.js';
 export interface MethodAccessRecord {

package/dist/generated/system-proxy.d.ts

@@ -9,6 +9,7 @@ import type { audioAnalyzerCapability } from '../capabilities/audio-analyzer.cap
 import type { audioCodecCapability } from '../capabilities/audio-codec.cap.js';
 import type { backupCapability } from '../capabilities/backup.cap.js';
 import type { brokerCapability } from '../capabilities/broker.cap.js';
+import type { connectionTestCapability } from '../capabilities/connection-test.cap.js';
 import type { coreBlocksCapability } from '../capabilities/core-blocks.cap.js';
 import type { decoderCapability } from '../capabilities/decoder.cap.js';
 import type { deviceAdoptionCapability } from '../capabilities/device-adoption.cap.js';
@@ -61,11 +62,12 @@ export interface SystemProxy {
     readonly audioCodec: Pick<InferProvider<typeof audioCodecCapability>, 'listSupportedCodecs' | 'canHandle' | 'createDecodeSession' | 'createEncodeSession' | 'closeSession' | 'pushEncodedFrame' | 'pullPcm' | 'pushPcm' | 'pullEncoded' | 'flushEncode' | 'listActiveSessions'>;
     readonly backup: Pick<InferProvider<typeof backupCapability>, 'listDestinations' | 'trigger' | 'list' | 'listLocations' | 'getEntries' | 'restore' | 'delete' | 'listArchives' | 'upsertDestinationPolicy' | 'previewSchedule' | 'listSchedules' | 'upsertSchedule' | 'deleteSchedule'>;
     readonly broker: Pick<InferProvider<typeof brokerCapability>, 'list' | 'get' | 'listProviders' | 'add' | 'remove' | 'testConnection' | 'getSettings' | 'setSettings' | 'getBrokerConfig' | 'getSettingsSchema' | 'testSettings' | 'publish' | 'subscribe' | 'unsubscribe' | 'getState' | 'getStatus'>;
+    readonly connectionTest: Pick<InferProvider<typeof connectionTestCapability>, 'testSettings' | 'describeTest'>;
     readonly coreBlocks: Pick<InferProvider<typeof coreBlocksCapability>, 'list' | 'get' | 'create' | 'update' | 'delete' | 'setEnabled' | 'restart' | 'compile' | 'getTypeDefs'>;
     readonly decoder: Pick<InferProvider<typeof decoderCapability>, 'supportsCodec' | 'getInfo' | 'createSession' | 'destroySession' | 'pushPacket' | 'openStream' | 'pullFrames' | 'pullHandles' | 'getFrame' | 'getShmStats' | 'updateConfig' | 'getStats' | 'listActiveSessions' | 'reprobeHwaccel'>;
     readonly deviceAdoption: Pick<InferProvider<typeof deviceAdoptionCapability>, 'listCandidateFilters' | 'listCandidates' | 'getCandidate' | 'refresh' | 'adopt' | 'release' | 'resync'>;
     readonly deviceExport: Pick<InferProvider<typeof deviceExportCapability>, 'getStatus' | 'listSupportedDeviceKinds' | 'listExposedDevices' | 'exposeDevice' | 'unexposeDevice'>;
-    readonly deviceManager: Pick<InferProvider<typeof deviceManagerCapability>, 'allocateDeviceId' | 'registerDevice' | 'removeDevice' | 'persistConfig' | 'getRoleDisplayDefaults' | 'setRoleDisplayDefaults' | 'listLocations' | 'addLocation' | 'removeLocation' | 'listPersistedByAddon' | 'listAll' | 'getChildren' | 'removeByIntegration' | 'listWrappersForCap' | 'listBindableCapsForDeviceType' | 'discoverDevices' | 'adoptDevice' | 'getCreationSchema' | 'createDevice' | 'testCreationField' | 'adoptionListCandidateFilters' | 'adoptionListCandidates' | 'adoptionRefresh' | 'adoptionAdopt' | 'adoptionRelease' | 'adoptionResync' | 'discoveryProviders' | 'discoverAllProviders' | 'discoverProvider' | 'providerCreationType' | 'providerDiscoveryParamsSchema' | 'getDeviceStatusAggregateBatch'>;
+    readonly deviceManager: Pick<InferProvider<typeof deviceManagerCapability>, 'allocateDeviceId' | 'registerDevice' | 'removeDevice' | 'persistConfig' | 'getRoleDisplayDefaults' | 'setRoleDisplayDefaults' | 'listLocations' | 'addLocation' | 'removeLocation' | 'listPersistedByAddon' | 'listAll' | 'getChildren' | 'removeByIntegration' | 'listWrappersForCap' | 'listBindableCapsForDeviceType' | 'discoverDevices' | 'adoptDevice' | 'getCreationSchema' | 'createDevice' | 'testCreationField' | 'adoptionListCandidateFilters' | 'adoptionListCandidates' | 'adoptionRefresh' | 'adoptionAdopt' | 'adoptionRelease' | 'adoptionStartJob' | 'adoptionListJobs' | 'adoptionCancelJob' | 'adoptionResync' | 'discoveryProviders' | 'discoverAllProviders' | 'discoverProvider' | 'providerCreationType' | 'providerDiscoveryParamsSchema' | 'getDeviceStatusAggregateBatch'>;
     readonly deviceProvider: Pick<InferProvider<typeof deviceProviderCapability>, 'start' | 'stop' | 'getStatus' | 'getDevices' | 'supportsDiscovery' | 'discoverDevices' | 'getDiscoveryParamsSchema' | 'getManualCreationType' | 'adoptDiscoveredDevice' | 'supportsManualCreation' | 'getChildCreationSchema' | 'createDevice' | 'testCreationField'>;
     readonly deviceState: Pick<InferProvider<typeof deviceStateCapability>, 'getAllSnapshots'>;
     readonly faceGallery: Pick<InferProvider<typeof faceGalleryCapability>, 'listIdentities' | 'createIdentity' | 'renameIdentity' | 'deleteIdentity' | 'listIdentitySamples' | 'removeSample' | 'listRecentFaces' | 'getFaceMedia' | 'assignFace' | 'unassignFace' | 'deleteFace' | 'assignFaces' | 'unassignFaces' | 'suggestFaceClusters'>;

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export { DEFAULT_ADDON_PLACEMENT, isAgentOnlyPlacement, isDeployableToAgent, res
 export type * from './interfaces/addon-data-plane.js';
 export { DATAPLANE_SECRET_HEADER } from './interfaces/addon-data-plane.js';
 export type * from './interfaces/addon-routes.js';
+export * from './interfaces/adoption-job.js';
 export type * from './interfaces/agent.js';
 export type * from './interfaces/agent-protocol.js';
 export * from './interfaces/agent-protocol.js';