@camstack/types 1.2.259 → 1.2.261

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

@@ -0,0 +1,370 @@
+/**
+ * `device-extension` — ONE place to see and author what a device is extended
+ * with by OTHER devices (D648).
+ *
+ * **A contract, not a store.** Every slot (`linked-devices`,
+ * `doorbell-source`, later `consumables-graft`) is declared by the cap that
+ * owns the function (`extensionSlots` in its `*.cap.ts`, D4) and SERVED by the
+ * addon that already owns its store, over that store and its existing write
+ * path. This cap persists nothing and has no config method (guarded by
+ * `scripts/check-extension-slots.ts`): D62 applied to the whole feature, and
+ * D3 — no shadow registry.
+ *
+ * **Shape.** A device-scoped wrapper COLLECTION, the D554 shape `videoclips`
+ * uses: `resolveCapMount` gives it the `device-scoped` mount and
+ * `requireDeviceCollection` dispatches it. Its providers are the slot owners
+ * (device-manager, virtual-doorbell, …), and a device's sources are its
+ * bindings (step 0 of `getBindings`, derived, persisted nowhere).
+ *
+ *  - `listSources` — one row per provider, the D554 source-listing convention
+ *    that lets a scalar call be routed by the prefix of its `slotRef`.
+ *  - `listSlots` — fan-out, concatenated. A provider that throws becomes ONE
+ *    `unreachable` row naming it, never an absence (D554.4, D315): "no
+ *    extensions" is claimed only from an answer.
+ *  - `listCandidates` / `setSlot` — scalar, routed by `slotRef`
+ *    (`<source>:<slotId>`). An unclaimed ref is refused by name (D554.5).
+ *
+ * The slot's value travels as the generated discriminated union
+ * (`ExtensionSlotValue`, keyed on `slot`), so a value under the wrong slot is
+ * a schema error before it reaches any owner.
+ */
+import { z } from 'zod';
+import { type InferProvider } from './capability-definition.js';
+/** Separator between the source and the slot id in a `slotRef`. It is the
+ *  D554 routing separator: the dispatcher matches `<source>:` prefixes. */
+export declare const EXTENSION_SLOT_REF_SEPARATOR = ":";
+/** The contract method whose failure BECOMES a row, like `listSources`'s. */
+export declare const EXTENSION_SLOT_LISTING_METHOD = "listSlots";
+export declare const ExtensionSourceAvailabilitySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"ok">;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unreachable">;
+    reason: z.ZodString;
+}, z.core.$strip>], "state">;
+export type ExtensionSourceAvailability = z.infer<typeof ExtensionSourceAvailabilitySchema>;
+/** One provider of slots — the D554 source-listing row. */
+export declare const ExtensionSourceSchema: z.ZodObject<{
+    source: z.ZodString;
+    label: z.ZodString;
+    addonId: z.ZodOptional<z.ZodString>;
+    availability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        state: z.ZodLiteral<"ok">;
+    }, z.core.$strip>, z.ZodObject<{
+        state: z.ZodLiteral<"unreachable">;
+        reason: z.ZodString;
+    }, z.core.$strip>], "state">;
+}, z.core.$strip>;
+export type ExtensionSource = z.infer<typeof ExtensionSourceSchema>;
+/**
+ * How one picked source stands. `missing` — no such device (deleted, or an id
+ * that never existed); `foreign` — a device the slot's owner cannot read from
+ * (slice 2's cross-owner graft source); `unavailable` — it exists but is not a
+ * valid source now (a container, which is never a pick). A source in any of
+ * these states is SHOWN, never silently dropped or re-pointed.
+ */
+export declare const ExtensionSourceHealthSchema: z.ZodEnum<{
+    ok: "ok";
+    missing: "missing";
+    foreign: "foreign";
+    unavailable: "unavailable";
+}>;
+export type ExtensionSourceHealth = z.infer<typeof ExtensionSourceHealthSchema>;
+export declare const ExtensionSlotSourceSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    name: z.ZodNullable<z.ZodString>;
+    health: z.ZodEnum<{
+        ok: "ok";
+        missing: "missing";
+        foreign: "foreign";
+        unavailable: "unavailable";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ExtensionSlotSource = z.infer<typeof ExtensionSlotSourceSchema>;
+/**
+ * A DIFFERENT authority that gates whether the slot's sources do anything —
+ * reported read-only, named, never written through this contract (D62). The
+ * virtual doorbell's sources ring only while the wrapper is bound to the
+ * camera, and that binding belongs to `deviceManager.setWrapperActive`.
+ * `unknown` means the gate could not be read; it is not "inactive" (D315).
+ */
+export declare const ExtensionSlotActivationSchema: z.ZodObject<{
+    state: z.ZodEnum<{
+        unknown: "unknown";
+        active: "active";
+        inactive: "inactive";
+    }>;
+    authority: z.ZodString;
+    detail: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ExtensionSlotActivation = z.infer<typeof ExtensionSlotActivationSchema>;
+/** One slot of one device, as its owner reads it from its own store. */
+export declare const ExtensionSlotStateSchema: z.ZodObject<{
+    state: z.ZodLiteral<"ok">;
+    slotRef: z.ZodString;
+    slot: z.ZodEnum<{
+        "linked-devices": "linked-devices";
+        "doorbell-source": "doorbell-source";
+    }>;
+    authority: z.ZodString;
+    enabled: z.ZodNullable<z.ZodBoolean>;
+    projects: z.ZodNullable<z.ZodString>;
+    activation: z.ZodNullable<z.ZodObject<{
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            active: "active";
+            inactive: "inactive";
+        }>;
+        authority: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"doorbell-source">;
+    }, z.core.$strip>, z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"linked-devices">;
+    }, z.core.$strip>], "slot">;
+    sources: z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        name: z.ZodNullable<z.ZodString>;
+        health: z.ZodEnum<{
+            ok: "ok";
+            missing: "missing";
+            foreign: "foreign";
+            unavailable: "unavailable";
+        }>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExtensionSlotState = z.infer<typeof ExtensionSlotStateSchema>;
+/**
+ * A provider that could not answer `listSlots` at all. It could not name its
+ * own slots, so the row names the ADDON and carries the refusal verbatim.
+ * Written by the dispatcher, never by a provider.
+ */
+export declare const ExtensionSlotUnreachableSchema: z.ZodObject<{
+    state: z.ZodLiteral<"unreachable">;
+    addonId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type ExtensionSlotUnreachable = z.infer<typeof ExtensionSlotUnreachableSchema>;
+export declare const ExtensionSlotRowSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"ok">;
+    slotRef: z.ZodString;
+    slot: z.ZodEnum<{
+        "linked-devices": "linked-devices";
+        "doorbell-source": "doorbell-source";
+    }>;
+    authority: z.ZodString;
+    enabled: z.ZodNullable<z.ZodBoolean>;
+    projects: z.ZodNullable<z.ZodString>;
+    activation: z.ZodNullable<z.ZodObject<{
+        state: z.ZodEnum<{
+            unknown: "unknown";
+            active: "active";
+            inactive: "inactive";
+        }>;
+        authority: z.ZodString;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"doorbell-source">;
+    }, z.core.$strip>, z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"linked-devices">;
+    }, z.core.$strip>], "slot">;
+    sources: z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        name: z.ZodNullable<z.ZodString>;
+        health: z.ZodEnum<{
+            ok: "ok";
+            missing: "missing";
+            foreign: "foreign";
+            unavailable: "unavailable";
+        }>;
+        detail: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    state: z.ZodLiteral<"unreachable">;
+    addonId: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>], "state">;
+export type ExtensionSlotRow = z.infer<typeof ExtensionSlotRowSchema>;
+/** The row the dispatcher writes for a provider whose `listSlots` threw. */
+export declare function unreachableExtensionSlotRow(addonId: string, reason: string): ExtensionSlotUnreachable;
+/** One device the slot's editor may offer as a source. */
+export declare const ExtensionCandidateSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    name: z.ZodString;
+    type: z.ZodString;
+    location: z.ZodNullable<z.ZodString>;
+    parentName: z.ZodNullable<z.ZodString>;
+    suggested: z.ZodBoolean;
+    reason: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ExtensionCandidate = z.infer<typeof ExtensionCandidateSchema>;
+export declare const ExtensionCandidatesSchema: z.ZodObject<{
+    candidates: z.ZodArray<z.ZodObject<{
+        deviceId: z.ZodNumber;
+        name: z.ZodString;
+        type: z.ZodString;
+        location: z.ZodNullable<z.ZodString>;
+        parentName: z.ZodNullable<z.ZodString>;
+        suggested: z.ZodBoolean;
+        reason: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ExtensionCandidates = z.infer<typeof ExtensionCandidatesSchema>;
+/**
+ * What a write did. `none` — applied in place. `host` / `parent` — the owner
+ * reloaded the host (or, for an accessory child, its parent) because the
+ * write changed what the host REGISTERS (a graft switched on or off, slice 2).
+ */
+export declare const ExtensionSetResultSchema: z.ZodObject<{
+    applied: z.ZodLiteral<true>;
+    reload: z.ZodEnum<{
+        none: "none";
+        host: "host";
+        parent: "parent";
+    }>;
+}, z.core.$strip>;
+export type ExtensionSetResult = z.infer<typeof ExtensionSetResultSchema>;
+export declare const ExtensionSlotRefInputSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    slotRef: z.ZodString;
+}, z.core.$strip>;
+export type ExtensionSlotRefInput = z.infer<typeof ExtensionSlotRefInputSchema>;
+export declare const ExtensionSetSlotInputSchema: z.ZodObject<{
+    deviceId: z.ZodNumber;
+    slotRef: z.ZodString;
+    value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"doorbell-source">;
+    }, z.core.$strip>, z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+        slot: z.ZodLiteral<"linked-devices">;
+    }, z.core.$strip>], "slot">;
+}, z.core.$strip>;
+export type ExtensionSetSlotInput = z.infer<typeof ExtensionSetSlotInputSchema>;
+export declare const deviceExtensionCapability: {
+    readonly name: "device-extension";
+    readonly scope: "device";
+    readonly mode: "collection";
+    readonly kind: "wrapper";
+    readonly defaultActive: true;
+    readonly deviceTypes: readonly import("../index.js").DeviceType[];
+    readonly deviceConfig: {
+        readonly ui: {
+            readonly kind: "widget";
+            readonly widgetId: "host/extensions-panel";
+            readonly tab: "general";
+            readonly label: "Extensions";
+            readonly order: 72;
+        };
+    };
+    readonly methods: {
+        /** One row per slot owner — the D554 source listing `slotRef` routes by. */
+        readonly listSources: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+            source: z.ZodString;
+            label: z.ZodString;
+            addonId: z.ZodOptional<z.ZodString>;
+            availability: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                state: z.ZodLiteral<"ok">;
+            }, z.core.$strip>, z.ZodObject<{
+                state: z.ZodLiteral<"unreachable">;
+                reason: z.ZodString;
+            }, z.core.$strip>], "state">;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Every slot this device is offered, read by each owner from its own
+         * store. A provider that throws is ONE `unreachable` row (D554.4).
+         */
+        readonly listSlots: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+        }, z.core.$strip>, z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"ok">;
+            slotRef: z.ZodString;
+            slot: z.ZodEnum<{
+                "linked-devices": "linked-devices";
+                "doorbell-source": "doorbell-source";
+            }>;
+            authority: z.ZodString;
+            enabled: z.ZodNullable<z.ZodBoolean>;
+            projects: z.ZodNullable<z.ZodString>;
+            activation: z.ZodNullable<z.ZodObject<{
+                state: z.ZodEnum<{
+                    unknown: "unknown";
+                    active: "active";
+                    inactive: "inactive";
+                }>;
+                authority: z.ZodString;
+                detail: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                deviceIds: z.ZodArray<z.ZodNumber>;
+                slot: z.ZodLiteral<"doorbell-source">;
+            }, z.core.$strip>, z.ZodObject<{
+                deviceIds: z.ZodArray<z.ZodNumber>;
+                slot: z.ZodLiteral<"linked-devices">;
+            }, z.core.$strip>], "slot">;
+            sources: z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                name: z.ZodNullable<z.ZodString>;
+                health: z.ZodEnum<{
+                    ok: "ok";
+                    missing: "missing";
+                    foreign: "foreign";
+                    unavailable: "unavailable";
+                }>;
+                detail: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            state: z.ZodLiteral<"unreachable">;
+            addonId: z.ZodString;
+            reason: z.ZodString;
+        }, z.core.$strip>], "state">>, import("./capability-definition.js").CapabilityMethodKind>;
+        /** The devices the slot's editor may offer, suggestions pre-marked (D356). */
+        readonly listCandidates: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            slotRef: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            candidates: z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodNumber;
+                name: z.ZodString;
+                type: z.ZodString;
+                location: z.ZodNullable<z.ZodString>;
+                parentName: z.ZodNullable<z.ZodString>;
+                suggested: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, import("./capability-definition.js").CapabilityMethodKind>;
+        /**
+         * Write one slot through its owner's EXISTING write path. The owner
+         * validates (a container is never a linked device, a camera is never its
+         * own source) and refuses by name before persisting.
+         */
+        readonly setSlot: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            deviceId: z.ZodNumber;
+            slotRef: z.ZodString;
+            value: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                deviceIds: z.ZodArray<z.ZodNumber>;
+                slot: z.ZodLiteral<"doorbell-source">;
+            }, z.core.$strip>, z.ZodObject<{
+                deviceIds: z.ZodArray<z.ZodNumber>;
+                slot: z.ZodLiteral<"linked-devices">;
+            }, z.core.$strip>], "slot">;
+        }, z.core.$strip>, z.ZodObject<{
+            applied: z.ZodLiteral<true>;
+            reload: z.ZodEnum<{
+                none: "none";
+                host: "host";
+                parent: "parent";
+            }>;
+        }, z.core.$strip>, "mutation">;
+    };
+};
+export type IDeviceExtensionProvider = InferProvider<typeof deviceExtensionCapability>;

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

@@ -125,6 +125,33 @@ export declare const LinkedDeviceSchema: z.ZodObject<{
     producesTrackedEvents: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type LinkedDevice = z.infer<typeof LinkedDeviceSchema>;
+/**
+ * The `linked-devices` extension slot's editable value (D648): the operator's
+ * pick list, exactly what `_linkedDeviceIds` persists. Tree children are NOT
+ * in it — they are always linked and are not a pick.
+ */
+export declare const LinkedDevicesSlotValueSchema: z.ZodObject<{
+    deviceIds: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export type LinkedDevicesSlotValue = z.infer<typeof LinkedDevicesSlotValueSchema>;
+/**
+ * The `linked-devices` slot — a camera's companion devices, owned by the
+ * device manager over `_linkedDeviceIds` (D648, D356). Any device may be a
+ * source except a container (its children are picked in its place) and the
+ * camera itself.
+ */
+export declare const LINKED_DEVICES_SLOT: {
+    readonly id: "linked-devices";
+    readonly label: "Linked devices";
+    readonly description: string;
+    readonly shape: "association";
+    readonly hostDeviceTypes: readonly [DeviceType.Camera];
+    readonly sourceCaps: "any";
+    readonly cardinality: "many";
+    readonly value: z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>;
+};
 /** One camera's resolved linked set, tagged with the camera it belongs to.
  *  The batch answer needs the tag; the single-device answer already has it
  *  from the input, which is why `getLinkedDevices` keeps the untagged shape. */
@@ -309,6 +336,18 @@ export declare const deviceManagerCapability: {
     readonly name: "device-manager";
     readonly scope: "system";
     readonly mode: "singleton";
+    readonly extensionSlots: readonly [{
+        readonly id: "linked-devices";
+        readonly label: "Linked devices";
+        readonly description: string;
+        readonly shape: "association";
+        readonly hostDeviceTypes: readonly [DeviceType.Camera];
+        readonly sourceCaps: "any";
+        readonly cardinality: "many";
+        readonly value: z.ZodObject<{
+            deviceIds: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+    }];
     readonly exposesDeviceSettings: true;
     readonly methods: {
         /** Reserve (or re-resolve) a progressive numeric id for `(addonId, stableId)`.
@@ -1134,11 +1173,12 @@ export declare const deviceManagerCapability: {
         /**
          * Resolve the devices LINKED to a camera — the single policy authority
          * both consumers call (viewer devices panel + pipeline-analytics event
-         * kinds/ingest). Device-tree children are ALWAYS included; mode 'auto'
-         * (default) adds every device sharing the camera's non-null `location`,
-         * mode 'manual' adds the persisted manual list instead. Excludes the
-         * camera itself; deduped. Configuration is standard per-device settings
-         * (see the module docblock) — there are no bespoke link mutations.
+         * kinds/ingest). Device-tree children are ALWAYS included, plus the
+         * operator's persisted pick list (`mode` is always `manual` since D356:
+         * same-location devices are suggested by the picker, never linked on
+         * their own). Excludes the camera itself; deduped. The list is written by
+         * the settings section or the `linked-devices` extension slot, both over
+         * `_linkedDeviceIds` (see the module docblock).
          */
         readonly getLinkedDevices: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             deviceId: z.ZodNumber;

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

@@ -34,6 +34,35 @@ export declare const DoorbellPressEventSchema: z.ZodObject<{
     timestamp: z.ZodNumber;
 }, z.core.$strip>;
 export type DoorbellPressEvent = z.infer<typeof DoorbellPressEventSchema>;
+/**
+ * The `doorbell-source` extension slot's editable value (D648): the camera's
+ * virtual-doorbell trigger devices, exactly what the wrapper's
+ * `doorbellSources` persists (as `{ deviceId }` records).
+ */
+export declare const DoorbellSourceSlotValueSchema: z.ZodObject<{
+    deviceIds: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>;
+export type DoorbellSourceSlotValue = z.infer<typeof DoorbellSourceSlotValueSchema>;
+/**
+ * The `doorbell-source` slot — which devices ring this camera's VIRTUAL
+ * doorbell, owned by the `virtual-doorbell` wrapper over its
+ * `doorbellSources` store (D648). A source rings when one of its
+ * `SOURCE_CAPS` rises. Whether the wrapper is bound to the camera at all is a
+ * different authority (`deviceManager.setWrapperActive`, D62) — the slot
+ * reports it, it never writes it.
+ */
+export declare const DOORBELL_SOURCE_SLOT: {
+    readonly id: "doorbell-source";
+    readonly label: "Doorbell trigger devices";
+    readonly description: string;
+    readonly shape: "association";
+    readonly hostDeviceTypes: readonly [DeviceType.Camera];
+    readonly sourceCaps: readonly string[];
+    readonly cardinality: "many";
+    readonly value: z.ZodObject<{
+        deviceIds: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>;
+};
 export declare const doorbellCapability: {
     readonly name: "doorbell";
     readonly scope: "device";
@@ -43,6 +72,18 @@ export declare const doorbellCapability: {
     readonly defaultActive: false;
     readonly deviceTypes: readonly [DeviceType.Button, DeviceType.Camera];
     readonly exposesDeviceSettings: true;
+    readonly extensionSlots: readonly [{
+        readonly id: "doorbell-source";
+        readonly label: "Doorbell trigger devices";
+        readonly description: string;
+        readonly shape: "association";
+        readonly hostDeviceTypes: readonly [DeviceType.Camera];
+        readonly sourceCaps: readonly string[];
+        readonly cardinality: "many";
+        readonly value: z.ZodObject<{
+            deviceIds: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>;
+    }];
     readonly methods: {};
     readonly events: {
         /**