@camstack/types 1.2.547 → 1.2.548

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.548] - 2026-11-11
11
+
12
+ ### Added
13
+
14
+ - Automations can gate on the time of day: a new 'time is' condition (a window such as 22:00 to 06:00, and/or chosen weekdays) that also starts a state-only automation when the window opens. A window bounded by a sun event is refused at save when the site has no location.
15
+ - Automations: a "Started by" condition tells which trigger row started the run, so one automation can run a different step per trigger
16
+ - Automations: a "device becomes" trigger hands the run the device, the value before the change and the new value (vars.deviceId, vars.from, vars.to)
17
+
10
18
  ## [1.2.547] - 2026-11-11
11
19
 
12
20
  ### Changed
@@ -12,6 +12,7 @@
12
12
  * ones a short-circuit never reached) with a stable path and a human reason, so
13
13
  * the editor can paint each block.
14
14
  */
15
+ import type { TimeSite } from '../time/time-spec.js';
15
16
  import { type HoldTracker } from './hold.js';
16
17
  import { type LegacyCondition } from './legacy-recipe.js';
17
18
  import { type AutomationWhen } from './when.js';
@@ -48,6 +49,15 @@ export interface StableIdDevice {
48
49
  export declare function stableIdMapOf(devices: readonly StableIdDevice[]): Map<string, number>;
49
50
  /** Every (device, cap) a `when` tree's STATE leaves read, deduplicated. */
50
51
  export declare function collectWhenMirrorSources(cond: AutomationWhen | undefined): MirrorSource[];
52
+ /** Does the tree hold a `time-is` leaf? */
53
+ export declare function hasTimeLeaves(when: AutomationWhen): boolean;
54
+ /**
55
+ * The soonest ANY `time-is` leaf changes sides (ms from `now`), over every
56
+ * leaf of the tree — a short-circuit that skipped a leaf in the last
57
+ * evaluation must not hide its boundary. Undefined: no time leaf, no site, or
58
+ * no boundary within reach.
59
+ */
60
+ export declare function nextTimeBoundaryInMs(when: AutomationWhen, now: number, site: TimeSite | undefined, rootPath?: string): number | undefined;
51
61
  /** Legacy name, for blocks generated before the single tree: an old condition tree. */
52
62
  export declare function collectMirrorSources(cond: LegacyCondition | undefined): MirrorSource[];
53
63
  export interface ConditionReader {
@@ -91,6 +101,8 @@ export interface ConditionEvaluation {
91
101
  readonly nodes: readonly AutomationConditionTraceNode[];
92
102
  /** The soonest a pending `for` completes (ms from now); absent when none is pending. */
93
103
  readonly holdDueInMs?: number;
104
+ /** The soonest a `time-is` leaf changes sides (ms from now); absent when the tree holds none or no site. */
105
+ readonly timeDueInMs?: number;
94
106
  }
95
107
  /** Options of one evaluation of a `when` tree. */
96
108
  export interface WhenEvaluationOptions {
@@ -100,6 +112,18 @@ export interface WhenEvaluationOptions {
100
112
  readonly holds?: HoldTracker;
101
113
  /** The root path (default `when`; the legacy wrapper keeps `conditions`). */
102
114
  readonly rootPath?: string;
115
+ /** The site the `time-is` leaves read their clock on; absent, such a leaf is unknown. */
116
+ readonly site?: TimeSite;
117
+ /**
118
+ * What started the run, for a `triggered-by` leaf. Absent, it is read off
119
+ * the tree itself: the id of the leaf at `firedPath`. A tree that is NOT the
120
+ * one the trigger sits in (a step guard) must be told, or say `'unknown'`.
121
+ */
122
+ readonly trigger?: RunTrigger | 'unknown';
123
+ }
124
+ /** What started a run: the id of the event leaf that fired, or null when none with an id did. */
125
+ export interface RunTrigger {
126
+ readonly leafId: string | null;
103
127
  }
104
128
  /** Evaluate a `when` tree: the fired event leaf is true, every other event leaf false. */
105
129
  export declare function evaluateWhenTree(when: AutomationWhen, reader: ConditionReader, now: number, options?: WhenEvaluationOptions): ConditionEvaluation;
@@ -123,9 +123,18 @@ export type BecomesRead = {
123
123
  } | {
124
124
  readonly ok: false;
125
125
  };
126
+ /** What a `device-becomes` trigger hands the run. */
127
+ export interface BecomesVars {
128
+ readonly deviceId: number;
129
+ /** The value before the change, `null` when it was not a scalar or not seen. */
130
+ readonly from: string | number | boolean | null;
131
+ readonly to: string | number | boolean | null;
132
+ }
126
133
  export type BecomesEffect = {
127
134
  readonly kind: 'fire';
128
135
  readonly value: unknown;
136
+ /** What the field held before it last changed; `undefined` when no change was seen. */
137
+ readonly from: unknown;
129
138
  readonly hold?: HoldTrace;
130
139
  } | {
131
140
  readonly kind: 'hold';
@@ -153,6 +162,8 @@ export declare class BecomesWatch {
153
162
  private readonly spec;
154
163
  private readonly deps;
155
164
  private previous;
165
+ /** The value the field left at its last change — a re-report does not move it. */
166
+ private from;
156
167
  private seeded;
157
168
  private readonly core;
158
169
  private handle;
@@ -10,8 +10,8 @@
10
10
  */
11
11
  export type { GenerateAutomationBlockInput } from './codegen.js';
12
12
  export { generateAutomationBlock } from './codegen.js';
13
- export type { ConditionEvaluation, ConditionReader, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, } from './condition-eval.js';
14
- export { collectMirrorSources, collectWhenMirrorSources, ConditionMirror, stableIdKey, stableIdMapOf, evaluateConditionTree, evaluateWhenTree, hasHoldLeaves, observeHoldLeaves, } from './condition-eval.js';
13
+ export type { ConditionEvaluation, ConditionReader, MirrorRefreshFetchers, RunTrigger, MirrorRefreshReport, MirrorSource, } from './condition-eval.js';
14
+ export { collectMirrorSources, collectWhenMirrorSources, ConditionMirror, stableIdKey, stableIdMapOf, evaluateConditionTree, evaluateWhenTree, hasHoldLeaves, hasTimeLeaves, nextTimeBoundaryInMs, observeHoldLeaves, } from './condition-eval.js';
15
15
  export type { BecomesDeps, BecomesEffect, BecomesOperator, BecomesSpec, HoldMode, HoldReading, HoldSpec, HoldTrace, LegacyHoldFields, } from './hold.js';
16
16
  export { BecomesOperatorSchema, BecomesWatch, describeHold, describeHoldMs, HoldCore, HoldSpecSchema, HoldTraceSchema, HoldTracker, holdOf, } from './hold.js';
17
17
  export type { DetectionDecision, DetectionTrigger, DetectionVars, TrackLifecycleInput, } from './detection-trigger.js';
@@ -26,8 +26,8 @@ export type { AutomationConditionTraceNode, AutomationRunOutcome, AutomationRunT
26
26
  export { AutomationConditionTraceNodeSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildStepArgsTrace, buildTriggerTrace, isSkippedTrace, MAX_TRACE_ARG_LENGTH, MAX_STEP_DEVICE_OUTCOMES, MAX_TRACE_ARGS, REDACTED_ARG, skipSignature, StepDeviceTraceSchema, TraceNodeOutcomeSchema, TraceValueSchema, } from './trace.js';
27
27
  export type { ActionStep, AutomationAction, AutomationCapStep, AutomationRecipe, AutomationRunMode, LegacyAutomationRecipe, NormalizedCapStep, } from './recipe.js';
28
28
  export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, AutomationRecipeSchema, AutomationRunModeSchema, CurrentAutomationRecipeSchema, convertLegacyRecipe, DEFAULT_TRACE_KEEP, LegacyAutomationRecipeSchema, MAX_TRACE_KEEP, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, normalizeCapStep, normalizeStepTargets, validateRecipeBounds, } from './recipe.js';
29
- export type { AutomationAll, AutomationAny, AutomationConditionOperator, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLeaf, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, StationaryLeaf, StationaryPresentLeaf, } from './when.js';
30
- export { AutomationConditionOperatorSchema, AutomationWhenSchema, countWhenLeaves, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, MAX_WHEN_DEPTH, MAX_WHEN_LEAVES, validateWhenTree, whenDepth, } from './when.js';
29
+ export type { AutomationAll, AutomationAny, AutomationConditionOperator, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLeaf, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, TimeIsLeaf, TriggeredByLeaf, IdentifiedEventLeaf, StationaryLeaf, StationaryPresentLeaf, } from './when.js';
30
+ export { AutomationConditionOperatorSchema, AutomationWhenSchema, countWhenLeaves, eventLeafIdAt, identifiedEventLeaves, hasTriggeredByLeaves, triggeredByIssue, EVENT_LEAF_ID_RE, TRIGGERED_BY_MAX_IDS, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, MAX_WHEN_DEPTH, MAX_WHEN_LEAVES, validateWhenTree, whenDepth, } from './when.js';
31
31
  export type { LegacyCondition, LegacyTrigger, } from './legacy-recipe.js';
32
32
  export { convertLegacyCondition, convertLegacyWhen, LegacyConditionSchema, LegacyTriggerSchema, } from './legacy-recipe.js';
33
33
  export type { DetectionLabelSource, DetectionSubject, IdentityLabel, PlateLabel, SubClassLabel, SubjectObservation, SubjectVerdict, } from './detection-subject.js';
@@ -42,3 +42,5 @@ export { prepareRecipeUnits } from './prepare-units.js';
42
42
  export type { PreparedRecipe } from './prepare-units.js';
43
43
  export type { AutomationLeafCatalog, AutomationLeafCatalogEntry, AutomationLeafCategory, AutomationLeafContext, AutomationLeafKind, AutomationLeafRole, } from './leaf-catalog.js';
44
44
  export { AUTOMATION_LEAF_CATALOG, AUTOMATION_LEAF_CATEGORIES, AUTOMATION_LEAF_KINDS, leafCatalogEntry, leafKindsFor, seedLeaf, } from './leaf-catalog.js';
45
+ export { recipeSiteIssues, stepGuardSiteIssues, whenSiteIssues } from './when-site.js';
46
+ export type { GuardedStepLike, WhenSiteIssue } from './when-site.js';
@@ -141,6 +141,11 @@ export declare const LeafActionStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
141
141
  }, z.core.$strip>], "kind">;
142
142
  /** How many steps one `else` list holds. */
143
143
  export declare const STEP_ELSE_MAX = 10;
144
+ /**
145
+ * A step of a STANDALONE list (an action, a scheduler point, a preset): the
146
+ * same two step kinds an automation runs, minus a guard that reads the
147
+ * automation's trigger, which such a list does not have.
148
+ */
144
149
  export declare const ActionStepSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
145
150
  kind: z.ZodLiteral<"wait">;
146
151
  seconds: z.ZodNumber;
@@ -5,7 +5,8 @@
5
5
  * read is UNKNOWN, and unknown runs neither side (D49: a failed read changes
6
6
  * nothing, and never decides a branch).
7
7
  */
8
- import { ConditionMirror, type MirrorRefreshFetchers } from './condition-eval.js';
8
+ import type { TimeSite } from '../time/time-spec.js';
9
+ import { ConditionMirror, type MirrorRefreshFetchers, type RunTrigger } from './condition-eval.js';
9
10
  import type { HoldTracker } from './hold.js';
10
11
  import type { AutomationWhen } from './when.js';
11
12
  export type StepConditionResult = 'true' | 'false' | 'unknown';
@@ -27,4 +28,8 @@ export interface StepConditionHistory {
27
28
  readonly rootPath: string;
28
29
  }
29
30
  /** Fill a mirror for the tree's leaves from `fetchers` and judge it NOW. */
30
- export declare function evaluateStepCondition(when: AutomationWhen, fetchers: MirrorRefreshFetchers, now?: () => number, history?: StepConditionHistory): Promise<StepConditionVerdict>;
31
+ export declare function evaluateStepCondition(when: AutomationWhen, fetchers: MirrorRefreshFetchers, now?: () => number, history?: StepConditionHistory,
32
+ /** The site a `time-is` leaf reads its clock on; absent, such a leaf is unknown. */
33
+ site?: TimeSite,
34
+ /** What started the run, for a `triggered-by` leaf; absent, such a leaf is unknown. */
35
+ trigger?: RunTrigger): Promise<StepConditionVerdict>;
@@ -78,6 +78,8 @@ export declare const AutomationConditionTraceNodeSchema: z.ZodObject<{
78
78
  schedule: "schedule";
79
79
  stationary: "stationary";
80
80
  "stationary-present": "stationary-present";
81
+ "time-is": "time-is";
82
+ "triggered-by": "triggered-by";
81
83
  }>;
82
84
  outcome: z.ZodEnum<{
83
85
  fail: "fail";
@@ -250,6 +252,8 @@ export declare const AutomationRunTraceSchema: z.ZodObject<{
250
252
  schedule: "schedule";
251
253
  stationary: "stationary";
252
254
  "stationary-present": "stationary-present";
255
+ "time-is": "time-is";
256
+ "triggered-by": "triggered-by";
253
257
  }>;
254
258
  outcome: z.ZodEnum<{
255
259
  fail: "fail";
@@ -434,6 +438,8 @@ export declare const AutomationStateDocSchema: z.ZodObject<{
434
438
  schedule: "schedule";
435
439
  stationary: "stationary";
436
440
  "stationary-present": "stationary-present";
441
+ "time-is": "time-is";
442
+ "triggered-by": "triggered-by";
437
443
  }>;
438
444
  outcome: z.ZodEnum<{
439
445
  fail: "fail";
@@ -1,8 +1,10 @@
1
1
  import type { AutomationWhen } from './when.js';
2
2
  export interface TriggerVariable {
3
3
  readonly name: string;
4
- /** English hint; the editor translates it by `name`. */
4
+ /** English hint; the editor translates it by `hintKey`, else by `name`. */
5
5
  readonly description: string;
6
+ /** Set when the same name means something else on another trigger kind. */
7
+ readonly hintKey?: string;
6
8
  }
7
9
  /** What one event row kind provides; kinds that provide none are absent. */
8
10
  export declare function triggerLeafVariables(kind: string): readonly TriggerVariable[];
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Save-time check of a `when` tree against the SITE: a `time-is` window
3
+ * bounded by a sun event needs the site location, and any window needs a known
4
+ * time zone. Refused before the save with a typed reason — at run time the
5
+ * same leaf can only read `unknown`, and a rule that never decides is a rule
6
+ * the operator believes is working. Pure: the site reading is handed in.
7
+ */
8
+ import { type SiteReading, type TimeSpecRefusal } from '../time/time-spec.js';
9
+ import type { AutomationRecipe } from './recipe.js';
10
+ import { type AutomationWhen } from './when.js';
11
+ export interface WhenSiteIssue {
12
+ /** `when.1.between.from` — the end of the window that cannot be placed. */
13
+ readonly path: string;
14
+ readonly reason: TimeSpecRefusal;
15
+ readonly message: string;
16
+ }
17
+ /** Every `time-is` window end of the tree this site cannot place. `rootPath` replaces the leading `when`. */
18
+ export declare function whenSiteIssues(when: AutomationWhen, reading: SiteReading, rootPath?: string): WhenSiteIssue[];
19
+ /** A step as far as its guard goes. */
20
+ export interface GuardedStepLike {
21
+ readonly kind: string;
22
+ readonly if?: AutomationWhen | undefined;
23
+ }
24
+ /** The same check over the guard (`if`) of every step of a list, reported under `<rootPath>.<i>.if`. */
25
+ export declare function stepGuardSiteIssues(steps: readonly GuardedStepLike[], reading: SiteReading, rootPath: string): WhenSiteIssue[];
26
+ /** The whole recipe: its `when` tree and every step guard. */
27
+ export declare function recipeSiteIssues(recipe: AutomationRecipe, reading: SiteReading): WhenSiteIssue[];
@@ -45,6 +45,12 @@ export declare const AutomationConditionOperatorSchema: z.ZodEnum<{
45
45
  ne: "ne";
46
46
  }>;
47
47
  export type AutomationConditionOperator = z.infer<typeof AutomationConditionOperatorSchema>;
48
+ /**
49
+ * The stable name of an event leaf. A path (`when.0.1`) moves when a row is
50
+ * reordered; the id does not, so a `triggered-by` leaf keeps pointing at the
51
+ * same row. Optional: a leaf nothing refers to needs none.
52
+ */
53
+ export declare const EVENT_LEAF_ID_RE: RegExp;
48
54
  /**
49
55
  * D8 compliance, and it is the reason a "becomes" leaf is not merely an event
50
56
  * subscription: it evaluates against the **state mirror**, which is reconciled,
@@ -52,6 +58,7 @@ export type AutomationConditionOperator = z.infer<typeof AutomationConditionOper
52
58
  * fire; it does not lose it.
53
59
  */
54
60
  declare const DeviceBecomesLeafSchema: z.ZodObject<{
61
+ id: z.ZodOptional<z.ZodString>;
55
62
  kind: z.ZodLiteral<"device-becomes">;
56
63
  deviceId: z.ZodNumber;
57
64
  cap: z.ZodString;
@@ -81,6 +88,7 @@ declare const DeviceBecomesLeafSchema: z.ZodObject<{
81
88
  debounceMs: z.ZodOptional<z.ZodNumber>;
82
89
  }, z.core.$strip>;
83
90
  declare const DeviceEventLeafSchema: z.ZodObject<{
91
+ id: z.ZodOptional<z.ZodString>;
84
92
  kind: z.ZodLiteral<"device-event">;
85
93
  category: z.ZodString;
86
94
  deviceId: z.ZodOptional<z.ZodNumber>;
@@ -92,6 +100,7 @@ declare const DeviceEventLeafSchema: z.ZodObject<{
92
100
  * a stored automation never stops firing, and is not written by new editors.
93
101
  */
94
102
  declare const ScheduleLeafSchema: z.ZodObject<{
103
+ id: z.ZodOptional<z.ZodString>;
95
104
  kind: z.ZodLiteral<"schedule">;
96
105
  at: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
97
106
  kind: z.ZodLiteral<"clock">;
@@ -122,13 +131,16 @@ declare const ScheduleLeafSchema: z.ZodObject<{
122
131
  cron: z.ZodOptional<z.ZodString>;
123
132
  }, z.core.$strip>;
124
133
  declare const ManualLeafSchema: z.ZodObject<{
134
+ id: z.ZodOptional<z.ZodString>;
125
135
  kind: z.ZodLiteral<"manual">;
126
136
  }, z.core.$strip>;
127
137
  declare const IntervalLeafSchema: z.ZodObject<{
138
+ id: z.ZodOptional<z.ZodString>;
128
139
  kind: z.ZodLiteral<"interval">;
129
140
  minutes: z.ZodNumber;
130
141
  }, z.core.$strip>;
131
142
  declare const DetectionLeafSchema: z.ZodObject<{
143
+ id: z.ZodOptional<z.ZodString>;
132
144
  kind: z.ZodLiteral<"detection">;
133
145
  subjects: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
134
146
  macro: z.ZodLiteral<"animal">;
@@ -167,6 +179,7 @@ declare const DetectionLeafSchema: z.ZodObject<{
167
179
  minScore: z.ZodOptional<z.ZodNumber>;
168
180
  }, z.core.$strip>;
169
181
  declare const StationaryLeafSchema: z.ZodObject<{
182
+ id: z.ZodOptional<z.ZodString>;
170
183
  kind: z.ZodLiteral<"stationary">;
171
184
  deviceIds: z.ZodArray<z.ZodNumber>;
172
185
  subjects: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -280,6 +293,73 @@ declare const StationaryPresentLeafSchema: z.ZodObject<{
280
293
  zones: z.ZodOptional<z.ZodArray<z.ZodString>>;
281
294
  minCount: z.ZodOptional<z.ZodNumber>;
282
295
  }, z.core.$strip>;
296
+ /**
297
+ * True while the site-local clock is inside a daily window and/or on one of
298
+ * the named days. `days` names the local day a window STARTS on, so
299
+ * 22:00-06:00 on weekdays is still inside at 01:00 Saturday. A one-date spec
300
+ * (`kind: 'date'`) is refused: only a clock time or a sun event makes a window
301
+ * that repeats every day.
302
+ */
303
+ declare const TimeIsLeafSchema: z.ZodObject<{
304
+ kind: z.ZodLiteral<"time-is">;
305
+ between: z.ZodOptional<z.ZodObject<{
306
+ from: z.ZodDiscriminatedUnion<[z.ZodObject<{
307
+ kind: z.ZodLiteral<"clock">;
308
+ hh: z.ZodNumber;
309
+ mm: z.ZodNumber;
310
+ }, z.core.$strip>, z.ZodObject<{
311
+ kind: z.ZodLiteral<"sun">;
312
+ event: z.ZodEnum<{
313
+ dawn: "dawn";
314
+ dusk: "dusk";
315
+ sunrise: "sunrise";
316
+ sunset: "sunset";
317
+ }>;
318
+ offsetMin: z.ZodNumber;
319
+ }, z.core.$strip>, z.ZodObject<{
320
+ kind: z.ZodLiteral<"date">;
321
+ local: z.ZodString;
322
+ }, z.core.$strip>], "kind">;
323
+ to: z.ZodDiscriminatedUnion<[z.ZodObject<{
324
+ kind: z.ZodLiteral<"clock">;
325
+ hh: z.ZodNumber;
326
+ mm: z.ZodNumber;
327
+ }, z.core.$strip>, z.ZodObject<{
328
+ kind: z.ZodLiteral<"sun">;
329
+ event: z.ZodEnum<{
330
+ dawn: "dawn";
331
+ dusk: "dusk";
332
+ sunrise: "sunrise";
333
+ sunset: "sunset";
334
+ }>;
335
+ offsetMin: z.ZodNumber;
336
+ }, z.core.$strip>, z.ZodObject<{
337
+ kind: z.ZodLiteral<"date">;
338
+ local: z.ZodString;
339
+ }, z.core.$strip>], "kind">;
340
+ }, z.core.$strip>>;
341
+ days: z.ZodOptional<z.ZodArray<z.ZodEnum<{
342
+ fri: "fri";
343
+ mon: "mon";
344
+ sat: "sat";
345
+ sun: "sun";
346
+ thu: "thu";
347
+ tue: "tue";
348
+ wed: "wed";
349
+ }>>>;
350
+ }, z.core.$strip>;
351
+ /** How many event leaves one `triggered-by` names. */
352
+ export declare const TRIGGERED_BY_MAX_IDS = 20;
353
+ /**
354
+ * True for the run that one of the named event leaves started. It reads the
355
+ * run, not a device: in the tree it is judged against the leaf that fired, in
356
+ * a step guard against the trigger the run carries. A run no event leaf
357
+ * started (a state-only tree becoming true) is false.
358
+ */
359
+ declare const TriggeredByLeafSchema: z.ZodObject<{
360
+ kind: z.ZodLiteral<"triggered-by">;
361
+ leafIds: z.ZodArray<z.ZodString>;
362
+ }, z.core.$strip>;
283
363
  /**
284
364
  * The escape hatch: the bounded expression engine over named device bindings.
285
365
  * Declared as a plain object so a discriminated union can read `kind`; the
@@ -313,7 +393,7 @@ declare const ExpressionLeafSchema: z.ZodObject<{
313
393
  }, z.core.$strip>>;
314
394
  }, z.core.$strip>;
315
395
  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>;
316
- export type AutomationStateLeaf = z.infer<typeof DeviceIsLeafSchema> | z.infer<typeof StationaryPresentLeafSchema> | z.infer<typeof ExpressionLeafSchema>;
396
+ export type AutomationStateLeaf = z.infer<typeof DeviceIsLeafSchema> | z.infer<typeof StationaryPresentLeafSchema> | z.infer<typeof ExpressionLeafSchema> | z.infer<typeof TimeIsLeafSchema> | z.infer<typeof TriggeredByLeafSchema>;
317
397
  export type AutomationLeaf = AutomationEventLeaf | AutomationStateLeaf;
318
398
  export type DeviceBecomesLeaf = Extract<AutomationEventLeaf, {
319
399
  kind: 'device-becomes';
@@ -333,6 +413,12 @@ export type StationaryPresentLeaf = Extract<AutomationStateLeaf, {
333
413
  export type ExpressionLeaf = Extract<AutomationStateLeaf, {
334
414
  kind: 'expression';
335
415
  }>;
416
+ export type TimeIsLeaf = Extract<AutomationStateLeaf, {
417
+ kind: 'time-is';
418
+ }>;
419
+ export type TriggeredByLeaf = Extract<AutomationStateLeaf, {
420
+ kind: 'triggered-by';
421
+ }>;
336
422
  export interface AutomationAll {
337
423
  readonly kind: 'all';
338
424
  readonly children: readonly AutomationWhen[];
@@ -356,6 +442,26 @@ export declare function countWhenLeaves(node: AutomationWhen): number;
356
442
  /** Every leaf with its path (`when`, `when.0`, `when.0.1`, `when.0` under a `not`). */
357
443
  export declare function forEachLeaf(node: AutomationWhen, visit: (leaf: AutomationLeaf, path: string) => void, path?: string): void;
358
444
  export declare function hasEventLeaves(node: AutomationWhen): boolean;
445
+ /** One event leaf that carries an id, with where it sits. */
446
+ export interface IdentifiedEventLeaf {
447
+ readonly id: string;
448
+ readonly path: string;
449
+ readonly leaf: AutomationEventLeaf;
450
+ }
451
+ /** The event leaves of the tree that carry an id, in tree order. */
452
+ export declare function identifiedEventLeaves(when: AutomationWhen): IdentifiedEventLeaf[];
453
+ /** The id of the event leaf at `path` (`when.0.1`); null when the leaf has none or the path names no event leaf. */
454
+ export declare function eventLeafIdAt(when: AutomationWhen, path: string): string | null;
455
+ /** Does the tree hold a `triggered-by` leaf? */
456
+ export declare function hasTriggeredByLeaves(when: AutomationWhen): boolean;
457
+ /** Why a `triggered-by` leaf is refused outside an automation: there is no trigger row to name. */
458
+ export declare const TRIGGERED_BY_NEEDS_AUTOMATION = "\"triggered by\" reads which trigger started an automation \u2014 an action or a scheduler has no trigger rows, so it could never be true here";
459
+ /**
460
+ * What is wrong with the `triggered-by` leaves of `tree`, given the ids the
461
+ * automation's event leaves carry: an id nothing carries can never be true.
462
+ * `where` names the tree in the message (`the rules`, `step 2`).
463
+ */
464
+ export declare function triggeredByIssue(tree: AutomationWhen, knownIds: ReadonlySet<string>, where: string): string | null;
359
465
  /**
360
466
  * Author-time bounds and sense check of a `when` tree. Returns `null` when it
361
467
  * is legal, else a message the editor shows verbatim.
@@ -316,6 +316,8 @@ export declare const actionsCapability: {
316
316
  schedule: "schedule";
317
317
  stationary: "stationary";
318
318
  "stationary-present": "stationary-present";
319
+ "time-is": "time-is";
320
+ "triggered-by": "triggered-by";
319
321
  }>;
320
322
  outcome: z.ZodEnum<{
321
323
  fail: "fail";
@@ -14167,6 +14167,8 @@ export declare const coreBlocksCapability: {
14167
14167
  schedule: "schedule";
14168
14168
  stationary: "stationary";
14169
14169
  "stationary-present": "stationary-present";
14170
+ "time-is": "time-is";
14171
+ "triggered-by": "triggered-by";
14170
14172
  }>;
14171
14173
  outcome: z.ZodEnum<{
14172
14174
  fail: "fail";
@@ -14352,6 +14354,8 @@ export declare const coreBlocksCapability: {
14352
14354
  schedule: "schedule";
14353
14355
  stationary: "stationary";
14354
14356
  "stationary-present": "stationary-present";
14357
+ "time-is": "time-is";
14358
+ "triggered-by": "triggered-by";
14355
14359
  }>;
14356
14360
  outcome: z.ZodEnum<{
14357
14361
  fail: "fail";
@@ -14533,6 +14537,8 @@ export declare const coreBlocksCapability: {
14533
14537
  schedule: "schedule";
14534
14538
  stationary: "stationary";
14535
14539
  "stationary-present": "stationary-present";
14540
+ "time-is": "time-is";
14541
+ "triggered-by": "triggered-by";
14536
14542
  }>;
14537
14543
  outcome: z.ZodEnum<{
14538
14544
  fail: "fail";
@@ -1537,6 +1537,8 @@ export declare const schedulersCapability: {
1537
1537
  schedule: "schedule";
1538
1538
  stationary: "stationary";
1539
1539
  "stationary-present": "stationary-present";
1540
+ "time-is": "time-is";
1541
+ "triggered-by": "triggered-by";
1540
1542
  }>;
1541
1543
  outcome: z.ZodEnum<{
1542
1544
  fail: "fail";
@@ -14589,6 +14589,16 @@ export type AppRouter = TrpcCoreRouter<{
14589
14589
  } | null;
14590
14590
  meta: object;
14591
14591
  }>;
14592
+ deviceAccess: import("@trpc/server").TRPCQueryProcedure<{
14593
+ input: {
14594
+ deviceId: number;
14595
+ };
14596
+ output: {
14597
+ view: boolean;
14598
+ command: boolean;
14599
+ };
14600
+ meta: object;
14601
+ }>;
14592
14602
  previewScope: import("@trpc/server").TRPCQueryProcedure<{
14593
14603
  input: {
14594
14604
  scopes: unknown[];
@@ -15668,6 +15678,16 @@ export type AppRouter = TrpcCoreRouter<{
15668
15678
  } | null;
15669
15679
  meta: object;
15670
15680
  }>;
15681
+ deviceAccess: import("@trpc/server").TRPCQueryProcedure<{
15682
+ input: {
15683
+ deviceId: number;
15684
+ };
15685
+ output: {
15686
+ view: boolean;
15687
+ command: boolean;
15688
+ };
15689
+ meta: object;
15690
+ }>;
15671
15691
  previewScope: import("@trpc/server").TRPCQueryProcedure<{
15672
15692
  input: {
15673
15693
  scopes: unknown[];
package/dist/index.d.ts CHANGED
@@ -191,8 +191,8 @@ export { APP_FLOW_DEFAULT_REDIRECT, APP_FLOW_REFUSAL_MESSAGES, APP_FLOW_STATE_PR
191
191
  export { SSO_STATE_COOKIE, SSO_STATE_COOKIE_MAX_AGE_SEC } from './auth/sso-state.js';
192
192
  export { buildDeviceEnrollmentLink, buildDeviceSignatureMessage, type CompleteEnrollmentInput, CompleteEnrollmentInputSchema, type CompleteEnrollmentOutput, CompleteEnrollmentOutputSchema, DEVICE_CERT_RENEW_WINDOW_DAYS, DEVICE_CERT_SIGNATURE, DEVICE_CERT_VALIDITY_DAYS, DEVICE_ENROLLMENT_TTL_MS, DEVICE_NONCE_TTL_MS, DEVICE_SAN_CREDENTIAL_PREFIX, DEVICE_SAN_USER_PREFIX, DEVICE_SIGNATURE_MESSAGE_VERSION, type DeviceCertificateLoginMethod, DeviceCertificateLoginMethodSchema, type DeviceChallenge, DeviceChallengeSchema, type DeviceCredential, DeviceCredentialSchema, type DeviceCredentialStatus, DeviceCredentialStatusSchema, type DevicePlatform, DevicePlatformSchema, type DeviceProofInput, DeviceProofInputSchema, type CompleteEnrollmentResult, CompleteEnrollmentResultSchema, DEFINITIVE_DEVICE_REFUSALS, DEVICE_DEFINITIVE_REFUSALS_BEFORE_DELETE, DEVICE_REFRESH_REFUSAL_PREFIX, deviceRefusalFromMessage, type DeviceChallengeResult, DeviceChallengeResultSchema, DeviceEnrollProofSchema, type DeviceRefusal, type DeviceRefusalReason, DeviceRefusalReasonSchema, DeviceRefusalSchema, type DeviceRevoker, type EnrollSelfInput, EnrollSelfInputSchema, formatDeviceRevoker, isDefinitiveDeviceRefusal, type RenewDeviceCertificateResult, RenewDeviceCertificateResultSchema, type RevokeOwnDeviceCertificateResult, RevokeOwnDeviceCertificateResultSchema, type DeviceSignaturePurpose, DeviceSignaturePurposeSchema, type RenewDeviceCertificateOutput, RenewDeviceCertificateOutputSchema, type StartEnrollmentOutput, StartEnrollmentOutputSchema, parseDeviceEnrollmentLink, } from './auth/device-certificate.js';
193
193
  export { advertisedHubOrigins, claimedRequestOrigins, normalizeOrigin, pickRequestOrigin, type RequestHeaders, requestMountPrefix, } from './auth/request-origin.js';
194
- export type { ActionStep, AutomationAction, AutomationAll, AutomationAny, AutomationCapStep, AutomationConditionOperator, AutomationConditionTraceNode, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLabelSource, DetectionLeaf, DetectionSubject, DeviceBecomesLeaf, BecomesDeps, BecomesEffect, BecomesOperator, BecomesSpec, DeviceIsLeaf, ExpressionLeaf, HoldMode, HoldReading, HoldSpec, HoldTrace, IdentityLabel, LegacyAutomationRecipe, NormalizedCapStep, StepDeviceTrace, LegacyCondition, LegacyTrigger, PlateLabel, StationaryLeaf, StationaryPresentLeaf, SubClassLabel, SubjectObservation, SubjectVerdict, AutomationRecipe, AutomationRunMode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, ConditionEvaluation, ConditionReader, DetectionDecision, DetectionTrigger, DetectionVars, GenerateAutomationBlockInput, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, StationaryChangedInput, StationaryDecision, StationaryTrigger, StationaryVars, TraceNodeOutcome, TraceValue, TrackLifecycleInput, TriggerVariable, } from './automation/index.js';
195
- export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationConditionOperatorSchema, AutomationConditionTraceNodeSchema, AutomationRecipeSchema, AutomationWhenSchema, CurrentAutomationRecipeSchema, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, LegacyAutomationRecipeSchema, LegacyConditionSchema, LegacyTriggerSchema, MAX_TRACE_ARG_LENGTH, MAX_STEP_DEVICE_OUTCOMES, MAX_TRACE_ARGS, MAX_WHEN_DEPTH, normalizeCapStep, normalizeStepTargets, StepDeviceTraceSchema, MAX_WHEN_LEAVES, REDACTED_ARG, StationarySubjectSchema, anySubjectMatches, buildStepArgsTrace, collectWhenMirrorSources, convertLegacyCondition, convertLegacyRecipe, convertLegacyWhen, countWhenLeaves, describeSubject, evaluateWhenTree, forEachLeaf, BecomesOperatorSchema, BecomesWatch, HoldCore, HoldSpecSchema, HoldTraceSchema, HoldTracker, describeHold, describeHoldMs, hasEventLeaves, hasHoldLeaves, holdOf, observeHoldLeaves, isEventLeaf, isLeaf, subClassesOf, subjectFromClassName, subjectMatches, validateWhenTree, whenDepth, AutomationRunModeSchema, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildTriggerTrace, collectMirrorSources, ConditionMirror, stableIdKey, stableIdMapOf, DEFAULT_TRACE_KEEP, DetectionTriggerFilter, detectionClassMatches, evaluateConditionTree, evaluateStationaryTrigger, generateAutomationBlock, isSkippedTrace, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, MAX_TRACE_KEEP, RunGate, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, triggerLeafVariables, triggerVariablesOf, validateRecipeBounds, } from './automation/index.js';
194
+ export type { ActionStep, AutomationAction, AutomationAll, AutomationAny, AutomationCapStep, AutomationConditionOperator, AutomationConditionTraceNode, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLabelSource, DetectionLeaf, DetectionSubject, DeviceBecomesLeaf, BecomesDeps, BecomesEffect, BecomesOperator, BecomesSpec, DeviceIsLeaf, ExpressionLeaf, TimeIsLeaf, TriggeredByLeaf, IdentifiedEventLeaf, WhenSiteIssue, HoldMode, HoldReading, HoldSpec, HoldTrace, IdentityLabel, LegacyAutomationRecipe, NormalizedCapStep, StepDeviceTrace, LegacyCondition, LegacyTrigger, PlateLabel, StationaryLeaf, StationaryPresentLeaf, SubClassLabel, SubjectObservation, SubjectVerdict, AutomationRecipe, AutomationRunMode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, ConditionEvaluation, ConditionReader, DetectionDecision, DetectionTrigger, DetectionVars, GenerateAutomationBlockInput, MirrorRefreshFetchers, RunTrigger, MirrorRefreshReport, MirrorSource, StationaryChangedInput, StationaryDecision, StationaryTrigger, StationaryVars, TraceNodeOutcome, TraceValue, TrackLifecycleInput, TriggerVariable, } from './automation/index.js';
195
+ export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationConditionOperatorSchema, AutomationConditionTraceNodeSchema, AutomationRecipeSchema, AutomationWhenSchema, CurrentAutomationRecipeSchema, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, LegacyAutomationRecipeSchema, LegacyConditionSchema, LegacyTriggerSchema, MAX_TRACE_ARG_LENGTH, MAX_STEP_DEVICE_OUTCOMES, MAX_TRACE_ARGS, MAX_WHEN_DEPTH, normalizeCapStep, normalizeStepTargets, StepDeviceTraceSchema, MAX_WHEN_LEAVES, REDACTED_ARG, StationarySubjectSchema, anySubjectMatches, buildStepArgsTrace, collectWhenMirrorSources, convertLegacyCondition, convertLegacyRecipe, convertLegacyWhen, countWhenLeaves, describeSubject, evaluateWhenTree, eventLeafIdAt, identifiedEventLeaves, hasTriggeredByLeaves, triggeredByIssue, EVENT_LEAF_ID_RE, TRIGGERED_BY_MAX_IDS, recipeSiteIssues, stepGuardSiteIssues, whenSiteIssues, forEachLeaf, BecomesOperatorSchema, BecomesWatch, HoldCore, HoldSpecSchema, HoldTraceSchema, HoldTracker, describeHold, describeHoldMs, hasEventLeaves, hasHoldLeaves, hasTimeLeaves, nextTimeBoundaryInMs, holdOf, observeHoldLeaves, isEventLeaf, isLeaf, subClassesOf, subjectFromClassName, subjectMatches, validateWhenTree, whenDepth, AutomationRunModeSchema, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildTriggerTrace, collectMirrorSources, ConditionMirror, stableIdKey, stableIdMapOf, DEFAULT_TRACE_KEEP, DetectionTriggerFilter, detectionClassMatches, evaluateConditionTree, evaluateStationaryTrigger, generateAutomationBlock, isSkippedTrace, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, MAX_TRACE_KEEP, RunGate, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, triggerLeafVariables, triggerVariablesOf, validateRecipeBounds, } from './automation/index.js';
196
196
  export { UnitWarningSchema, capUnitResolver, normalizeActionUnits, normalizeConditionUnits, normalizeRecipeUnits, prepareRecipeUnits, } from './automation/index.js';
197
197
  export type { PreparedRecipe, UnitResolver, UnitWarning, UnitsNormalized, } from './automation/index.js';
198
198
  export * from './automation/action.js';