@camstack/types 1.2.451 → 1.2.453

package/dist/automation/when.d.ts

@@ -0,0 +1,295 @@
+/**
+ * The `when` tree — the ONE place an automation says when it runs.
+ *
+ * Containers are `all` / `any` / `not`. Leaves come in two kinds, told apart by
+ * what they ARE, not by which section of a form they sit in:
+ *
+ *  - **event leaves (instants)** — something HAPPENS: a device field *becomes*
+ *    a value, a device event, a schedule tick, an interval, a manual run, a
+ *    detection, a parked object appearing or leaving;
+ *  - **state leaves (durations)** — something IS true: a device field *is*
+ *    compared to a value, a parked object is present, an expression holds.
+ *
+ * Firing rule (ADR, "one tree"):
+ *  1. A tree with event leaves fires when ONE of them occurs AND the whole tree
+ *     is true at that instant. The event that occurred is true; every other
+ *     event leaf is false.
+ *  2. A tree of state leaves only fires when it goes false → true. The first
+ *     evaluation seeds the state, so it never fires because it was already true.
+ *  3. Two event leaves that can only be satisfied together are refused at
+ *     author time ({@link validateWhenTree}).
+ */
+import { z } from 'zod';
+/**
+ * Depth of the `when` tree, counting the root container as level 1. The old
+ * condition tree was bounded at 3 under a flat list of triggers; the trigger
+ * list is now the tree's top `any`, one level, so the bound is 3 + 1 and a
+ * converted recipe never exceeds it.
+ *
+ * `NOT` over a group is always rewritable by De Morgan, so the shapes that
+ * would need a fifth level have an equivalent at four.
+ */
+export declare const MAX_WHEN_DEPTH = 4;
+/** Leaves per automation. A UI that grows without a bound becomes a language. */
+export declare const MAX_WHEN_LEAVES = 32;
+/** How a state leaf compares a device field to a value. Derived from the
+ *  field's `kind` in `deviceManager.getWireableFields`, never hand-maintained. */
+export declare const AutomationConditionOperatorSchema: z.ZodEnum<{
+    contains: "contains";
+    eq: "eq";
+    gt: "gt";
+    gte: "gte";
+    in: "in";
+    lt: "lt";
+    lte: "lte";
+    ne: "ne";
+}>;
+export type AutomationConditionOperator = z.infer<typeof AutomationConditionOperatorSchema>;
+/**
+ * D8 compliance, and it is the reason a "becomes" leaf is not merely an event
+ * subscription: it evaluates against the **state mirror**, which is reconciled,
+ * and an event only WAKES the evaluation. A dropped event therefore DELAYS a
+ * fire; it does not lose it.
+ */
+declare const DeviceBecomesLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"device-becomes">;
+    deviceId: z.ZodNumber;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+    becomes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    edge: z.ZodOptional<z.ZodBoolean>;
+    forMs: z.ZodOptional<z.ZodNumber>;
+    debounceMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const DeviceEventLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"device-event">;
+    category: z.ZodString;
+    deviceId: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const ScheduleLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"schedule">;
+    cron: z.ZodString;
+}, z.core.$strip>;
+declare const ManualLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"manual">;
+}, z.core.$strip>;
+declare const IntervalLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"interval">;
+    minutes: z.ZodNumber;
+}, z.core.$strip>;
+declare const DetectionLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"detection">;
+    subjects: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        macro: z.ZodLiteral<"animal">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"person">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"identity">;
+            identityId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"vehicle">;
+        label: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"plate">;
+            text: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"package">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"other">;
+        className: z.ZodString;
+    }, z.core.$strip>], "macro">>;
+    deviceIds: z.ZodArray<z.ZodNumber>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+declare const StationaryLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"stationary">;
+    deviceIds: z.ZodArray<z.ZodNumber>;
+    subjects: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        macro: z.ZodLiteral<"animal">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"person">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"identity">;
+            identityId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"vehicle">;
+        label: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"plate">;
+            text: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"package">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"other">;
+        className: z.ZodString;
+    }, z.core.$strip>], "macro">>>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    phase: z.ZodEnum<{
+        appeared: "appeared";
+        departed: "departed";
+    }>;
+}, z.core.$strip>;
+/** "is": one device field compared to one value, NOW. */
+declare const DeviceIsLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"device-is">;
+    deviceId: z.ZodNumber;
+    cap: z.ZodString;
+    fieldPath: z.ZodString;
+    operator: z.ZodEnum<{
+        contains: "contains";
+        eq: "eq";
+        gt: "gt";
+        gte: "gte";
+        in: "in";
+        lt: "lt";
+        lte: "lte";
+        ne: "ne";
+    }>;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>, z.ZodObject<{
+        value: z.ZodNumber;
+        unit: z.ZodString;
+    }, z.core.$strip>]>;
+    unit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * True when the camera currently has a PARKED object matching `subjects` in at
+ * least one of `zones`. Reads the zone-analytics snapshot through the same
+ * mirror as every other state leaf, so a dropped event never decides it (D49).
+ */
+declare const StationaryPresentLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"stationary-present">;
+    deviceId: z.ZodNumber;
+    subjects: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        macro: z.ZodLiteral<"animal">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"person">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"identity">;
+            identityId: z.ZodString;
+            name: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"vehicle">;
+        label: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"plate">;
+            text: z.ZodString;
+        }, z.core.$strip>], "kind">>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"package">;
+        label: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodLiteral<"sub-class">;
+            className: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        macro: z.ZodLiteral<"other">;
+        className: z.ZodString;
+    }, z.core.$strip>], "macro">>>;
+    zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * The escape hatch: the bounded expression engine over named device bindings.
+ * Declared as a plain object so a discriminated union can read `kind`; the
+ * author-time validation is the SAME function `ExpressionSourceSchema` runs.
+ */
+declare const ExpressionLeafSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"expression">;
+    expr: z.ZodString;
+    bindings: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+        kind: z.ZodOptional<z.ZodLiteral<"field">>;
+        sourceKey: z.ZodString;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"literal">;
+        value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"global">;
+        sourceStableId: z.ZodString;
+        cap: z.ZodString;
+        fieldPath: z.ZodString;
+    }, z.core.$strip>]>>;
+}, z.core.$strip>;
+export type AutomationEventLeaf = z.infer<typeof DeviceBecomesLeafSchema> | z.infer<typeof DeviceEventLeafSchema> | z.infer<typeof ScheduleLeafSchema> | z.infer<typeof ManualLeafSchema> | z.infer<typeof IntervalLeafSchema> | z.infer<typeof DetectionLeafSchema> | z.infer<typeof StationaryLeafSchema>;
+export type AutomationStateLeaf = z.infer<typeof DeviceIsLeafSchema> | z.infer<typeof StationaryPresentLeafSchema> | z.infer<typeof ExpressionLeafSchema>;
+export type AutomationLeaf = AutomationEventLeaf | AutomationStateLeaf;
+export type DeviceBecomesLeaf = Extract<AutomationEventLeaf, {
+    kind: 'device-becomes';
+}>;
+export type DetectionLeaf = Extract<AutomationEventLeaf, {
+    kind: 'detection';
+}>;
+export type StationaryLeaf = Extract<AutomationEventLeaf, {
+    kind: 'stationary';
+}>;
+export type DeviceIsLeaf = Extract<AutomationStateLeaf, {
+    kind: 'device-is';
+}>;
+export type StationaryPresentLeaf = Extract<AutomationStateLeaf, {
+    kind: 'stationary-present';
+}>;
+export type ExpressionLeaf = Extract<AutomationStateLeaf, {
+    kind: 'expression';
+}>;
+export interface AutomationAll {
+    readonly kind: 'all';
+    readonly children: readonly AutomationWhen[];
+}
+export interface AutomationAny {
+    readonly kind: 'any';
+    readonly children: readonly AutomationWhen[];
+}
+export interface AutomationNot {
+    readonly kind: 'not';
+    readonly child: AutomationWhen;
+}
+export type AutomationWhen = AutomationAll | AutomationAny | AutomationNot | AutomationLeaf;
+export declare const AutomationWhenSchema: z.ZodType<AutomationWhen>;
+export declare function isEventLeaf(node: AutomationWhen): node is AutomationEventLeaf;
+export declare function isLeaf(node: AutomationWhen): node is AutomationLeaf;
+/** Depth of a tree, root container = 1. A bare leaf is depth 1. */
+export declare function whenDepth(node: AutomationWhen): number;
+/** Leaves only — containers do not count toward the leaf budget. */
+export declare function countWhenLeaves(node: AutomationWhen): number;
+/** Every leaf with its path (`when`, `when.0`, `when.0.1`, `when.0` under a `not`). */
+export declare function forEachLeaf(node: AutomationWhen, visit: (leaf: AutomationLeaf, path: string) => void, path?: string): void;
+export declare function hasEventLeaves(node: AutomationWhen): boolean;
+/**
+ * Author-time bounds and sense check of a `when` tree. Returns `null` when it
+ * is legal, else a message the editor shows verbatim.
+ */
+export declare function validateWhenTree(when: AutomationWhen): string | null;
+export {};

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

@@ -144,6 +144,7 @@ export declare const actionsCapability: {
                 endedAt: z.ZodNumber;
                 trigger: z.ZodObject<{
                     kind: z.ZodString;
+                    path: z.ZodOptional<z.ZodString>;
                     outcome: z.ZodEnum<{
                         fail: "fail";
                         pass: "pass";
@@ -157,8 +158,16 @@ export declare const actionsCapability: {
                         all: "all";
                         any: "any";
                         condition: "condition";
+                        detection: "detection";
+                        "device-becomes": "device-becomes";
+                        "device-event": "device-event";
+                        "device-is": "device-is";
                         expression: "expression";
+                        interval: "interval";
+                        manual: "manual";
                         not: "not";
+                        schedule: "schedule";
+                        stationary: "stationary";
                         "stationary-present": "stationary-present";
                     }>;
                     outcome: z.ZodEnum<{
@@ -207,6 +216,7 @@ export declare const actionsCapability: {
                     deviceId: z.ZodOptional<z.ZodNumber>;
                     startedAt: z.ZodOptional<z.ZodNumber>;
                     endedAt: z.ZodOptional<z.ZodNumber>;
+                    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>]>>>;
                     outcome: z.ZodEnum<{
                         error: "error";
                         "not-run": "not-run";

package/dist/capabilities/addon-settings.cap.d.ts

@@ -167,6 +167,24 @@ export declare const addonSettingsCapability: {
                 fields: z.ZodArray<z.ZodAny>;
             }, z.core.$strip>>;
         }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        readonly getDeclaredSettingsKeys: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            addonId: z.ZodString;
+            nodeId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodNullable<z.ZodObject<{
+            keys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>, import("./capability-definition.js").CapabilityMethodKind>;
+        readonly unsetStoredSettingsKeys: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
+            addonId: z.ZodString;
+            nodeId: z.ZodOptional<z.ZodString>;
+            keys: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            removed: z.ZodArray<z.ZodString>;
+            refused: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                reason: z.ZodString;
+            }, z.core.$strip>>;
+            secretsCleared: z.ZodNumber;
+        }, z.core.$strip>, "mutation">;
         readonly getDeviceSettings: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
             addonId: z.ZodString;
             deviceId: z.ZodNumber;