@camstack/types 1.2.550 → 1.2.552

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/dist/index.js CHANGED
@@ -539,8 +539,7 @@ function buildCapturingReply(envelope) {
539
539
  * path with no instance segment and a link with no instance both mean it, and
540
540
  * its id is the addon id. {@link oauthLinkServesInstance} is the one
541
541
  * comparison a per-instance route is meant to call, so nobody compares
542
- * `undefined` with an id. Nothing calls it yet: no route declares
543
- * `perInstance` (the Alexa per-instance route, T3, is the first consumer).
542
+ * `undefined` with an id. The Alexa export's routes are its first caller.
544
543
  */
545
544
  /** An instance id as it may appear in a path or a query: no separator, no escape, bounded. */
546
545
  var ADDON_INSTANCE_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
@@ -5741,12 +5740,12 @@ function toStreamSourceEntry(stream) {
5741
5740
  function isString(v) {
5742
5741
  return typeof v === "string";
5743
5742
  }
5744
- function isRecord$5(v) {
5743
+ function isRecord$6(v) {
5745
5744
  return typeof v === "object" && v !== null && !Array.isArray(v);
5746
5745
  }
5747
5746
  function parseStreamEntry(v) {
5748
5747
  if (isString(v) && v.trim()) return { url: v };
5749
- if (isRecord$5(v) && isString(v["url"]) && v["url"].trim()) return {
5748
+ if (isRecord$6(v) && isString(v["url"]) && v["url"].trim()) return {
5750
5749
  url: v["url"],
5751
5750
  label: isString(v["label"]) ? v["label"] : void 0
5752
5751
  };
@@ -6387,20 +6386,20 @@ var SURVIVING_TRIGGER_KEYS = [
6387
6386
  "objectClasses",
6388
6387
  "sensorDeviceIds"
6389
6388
  ];
6390
- function isRecord$4(value) {
6389
+ function isRecord$5(value) {
6391
6390
  return typeof value === "object" && value !== null && !Array.isArray(value);
6392
6391
  }
6393
6392
  function listensToLegacySignal(band) {
6394
- return isRecord$4(band) && isRecord$4(band.triggers) && band.triggers.deviceSignal === true;
6393
+ return isRecord$5(band) && isRecord$5(band.triggers) && band.triggers.deviceSignal === true;
6395
6394
  }
6396
6395
  function hasSurvivingTrigger(band) {
6397
6396
  const triggers = band.triggers;
6398
- if (!isRecord$4(triggers)) return false;
6397
+ if (!isRecord$5(triggers)) return false;
6399
6398
  return SURVIVING_TRIGGER_KEYS.some((key) => triggers[key] !== void 0);
6400
6399
  }
6401
6400
  function withoutLegacySignal(band) {
6402
6401
  const triggers = band.triggers;
6403
- if (!isRecord$4(triggers)) return band;
6402
+ if (!isRecord$5(triggers)) return band;
6404
6403
  const { deviceSignal: _retired, ...rest } = triggers;
6405
6404
  return {
6406
6405
  ...band,
@@ -6430,11 +6429,11 @@ function migrateLegacyDeviceSignalConfig(raw) {
6430
6429
  migrated: false,
6431
6430
  strippedOnly: false
6432
6431
  };
6433
- if (!isRecord$4(raw) || !Array.isArray(raw.bands)) return unchanged;
6432
+ if (!isRecord$5(raw) || !Array.isArray(raw.bands)) return unchanged;
6434
6433
  if (!raw.bands.some(listensToLegacySignal)) return unchanged;
6435
6434
  const kept = [];
6436
6435
  for (const band of raw.bands) {
6437
- if (!listensToLegacySignal(band) || !isRecord$4(band)) {
6436
+ if (!listensToLegacySignal(band) || !isRecord$5(band)) {
6438
6437
  kept.push(band);
6439
6438
  continue;
6440
6439
  }
@@ -32172,6 +32171,143 @@ function anySubjectMatches(subjects, observed) {
32172
32171
  };
32173
32172
  }
32174
32173
  //#endregion
32174
+ //#region src/capabilities/event-vocabulary.ts
32175
+ /**
32176
+ * The declared vocabulary of an `event-emitter` device (D1044): what the
32177
+ * device can fire, named for a person and typed for a rule.
32178
+ *
32179
+ * `id` is the native token, verbatim. `kind` is the meaning shared by every
32180
+ * integration, so "any long press" can be asked without knowing a vendor's
32181
+ * token. A device with several buttons declares one entry per button and
32182
+ * token: an entry is identified by its token AND its source.
32183
+ */
32184
+ /** The cross-integration meaning of an event. */
32185
+ var EVENT_VOCABULARY_KINDS = [
32186
+ "press",
32187
+ "long-press",
32188
+ "long-press-start",
32189
+ "release",
32190
+ "repeat",
32191
+ "double-press",
32192
+ "other"
32193
+ ];
32194
+ var EventVocabularyKindSchema = zod.z.enum(EVENT_VOCABULARY_KINDS);
32195
+ /** The part of the device an event comes from: a button, a channel. */
32196
+ var EventVocabularySourceSchema = zod.z.object({
32197
+ id: zod.z.string().min(1),
32198
+ label: zod.z.string().min(1)
32199
+ });
32200
+ /** One scalar field of an event's `data`, by dotted path. */
32201
+ var EventVocabularyFieldSchema = zod.z.object({
32202
+ path: zod.z.string().min(1),
32203
+ kind: zod.z.enum([
32204
+ "string",
32205
+ "number",
32206
+ "boolean",
32207
+ "enum"
32208
+ ]),
32209
+ enumValues: zod.z.array(zod.z.string()).optional(),
32210
+ label: zod.z.string().min(1).optional()
32211
+ });
32212
+ var EventVocabularyEntrySchema = zod.z.object({
32213
+ /** The native token, verbatim. */
32214
+ id: zod.z.string().min(1),
32215
+ source: EventVocabularySourceSchema.optional(),
32216
+ label: zod.z.string().min(1),
32217
+ description: zod.z.string().optional(),
32218
+ kind: EventVocabularyKindSchema.optional(),
32219
+ payload: zod.z.array(EventVocabularyFieldSchema).optional()
32220
+ });
32221
+ /**
32222
+ * The vocabulary of a source that declares tokens and nothing else: one
32223
+ * entry per token, labelled with the token itself.
32224
+ */
32225
+ function plainEventVocabulary(eventTypes) {
32226
+ return [...new Set(eventTypes)].filter((eventType) => eventType !== "").map((eventType) => ({
32227
+ id: eventType,
32228
+ label: eventType
32229
+ }));
32230
+ }
32231
+ /**
32232
+ * Tokens many integrations use for a button, by their normalised spelling
32233
+ * (lower case, words joined by `_`). Exact matches only: a token that
32234
+ * merely contains one of these words gets no kind.
32235
+ */
32236
+ var CONVENTIONAL_KINDS = {
32237
+ press: "press",
32238
+ pressed: "press",
32239
+ single: "press",
32240
+ single_press: "press",
32241
+ single_click: "press",
32242
+ short_press: "press",
32243
+ press_short: "press",
32244
+ click: "press",
32245
+ initial_press: "press",
32246
+ long_press: "long-press",
32247
+ press_long: "long-press",
32248
+ long_click: "long-press",
32249
+ hold: "long-press",
32250
+ long_press_start: "long-press-start",
32251
+ press_long_start: "long-press-start",
32252
+ release: "release",
32253
+ released: "release",
32254
+ long_release: "release",
32255
+ long_press_release: "release",
32256
+ press_long_release: "release",
32257
+ short_release: "release",
32258
+ repeat: "repeat",
32259
+ hold_repeat: "repeat",
32260
+ press_cont: "repeat",
32261
+ double_press: "double-press",
32262
+ double_click: "double-press",
32263
+ double: "double-press",
32264
+ multi_press_2: "double-press"
32265
+ };
32266
+ function normalisedToken(token) {
32267
+ return token.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
32268
+ }
32269
+ function readableToken(token) {
32270
+ const words = normalisedToken(token).replace(/_/g, " ");
32271
+ if (words === "") return token;
32272
+ return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
32273
+ }
32274
+ /**
32275
+ * The vocabulary of a source that declares tokens only, read by convention:
32276
+ * a readable label, and the shared kind when the token is one many
32277
+ * integrations use for a button. The token itself is kept verbatim.
32278
+ */
32279
+ function conventionalEventVocabulary(eventTypes) {
32280
+ return plainEventVocabulary(eventTypes).map((entry) => {
32281
+ const kind = CONVENTIONAL_KINDS[normalisedToken(entry.id)];
32282
+ const label = readableToken(entry.id);
32283
+ return kind === void 0 ? {
32284
+ id: entry.id,
32285
+ label
32286
+ } : {
32287
+ id: entry.id,
32288
+ label,
32289
+ kind
32290
+ };
32291
+ });
32292
+ }
32293
+ /** The native tokens of a vocabulary, each once, in declaration order. */
32294
+ function eventTypesOfVocabulary(vocabulary) {
32295
+ return [...new Set(vocabulary.map((entry) => entry.id))];
32296
+ }
32297
+ /**
32298
+ * The vocabulary to show and match against. A status with none declared
32299
+ * answers with its plain tokens, so an older provider is still usable.
32300
+ */
32301
+ function readEventVocabulary(status) {
32302
+ const declared = status.vocabulary;
32303
+ if (declared !== void 0 && declared.length > 0) return declared;
32304
+ return plainEventVocabulary(status.eventTypes);
32305
+ }
32306
+ /** The entry a fire belongs to: same token, same source (or both without one). */
32307
+ function findVocabularyEntry(vocabulary, eventType, sourceId) {
32308
+ return vocabulary.find((entry) => entry.id === eventType && entry.source?.id === sourceId);
32309
+ }
32310
+ //#endregion
32175
32311
  //#region src/time/solar.ts
32176
32312
  /**
32177
32313
  * Where the sun is, from a latitude and a longitude — the one solar
@@ -32922,6 +33058,33 @@ var ScheduleLeafSchema = zod.z.object({
32922
33058
  /** @deprecated legacy cron — new schedules use `at`. */
32923
33059
  cron: zod.z.string().min(1).max(120).optional()
32924
33060
  }).refine((leaf) => leaf.at === void 0 !== (leaf.cron === void 0), { message: "a schedule names exactly one of `at` (a time spec) and `cron` (legacy)" }).refine((leaf) => leaf.days === void 0 || leaf.at !== void 0, { message: "`days` goes with `at`; a cron expression carries its own days" });
33061
+ /**
33062
+ * One payload predicate of a `device-fired` row: the value at `path` inside
33063
+ * the fire's `data` (dotted) equals `equals`. Compared strictly, no coercion.
33064
+ */
33065
+ var DeviceFiredMatchSchema = zod.z.object({
33066
+ path: zod.z.string().min(1).max(120),
33067
+ equals: zod.z.union([
33068
+ zod.z.string(),
33069
+ zod.z.number(),
33070
+ zod.z.boolean()
33071
+ ])
33072
+ });
33073
+ /**
33074
+ * "fires": one device of the `event-emitter` capability reported an event
33075
+ * (D1045). Every list is an OR, the lists together an AND; an absent list does
33076
+ * not narrow. `eventIds` are the device's own tokens, `sourceIds` the parts of
33077
+ * the device (a button), `kinds` the shared press kinds of its vocabulary.
33078
+ */
33079
+ var DeviceFiredLeafSchema = zod.z.object({
33080
+ kind: zod.z.literal("device-fired"),
33081
+ ...eventLeafId,
33082
+ deviceId: zod.z.number().int().nonnegative(),
33083
+ eventIds: zod.z.array(zod.z.string().min(1)).min(1).max(64).optional(),
33084
+ sourceIds: zod.z.array(zod.z.string().min(1)).min(1).max(64).optional(),
33085
+ kinds: zod.z.array(EventVocabularyKindSchema).min(1).optional(),
33086
+ match: zod.z.array(DeviceFiredMatchSchema).min(1).max(8).optional()
33087
+ });
32925
33088
  var ManualLeafSchema = zod.z.object({
32926
33089
  kind: zod.z.literal("manual"),
32927
33090
  ...eventLeafId
@@ -33065,6 +33228,7 @@ var AutomationWhenSchema = zod.z.lazy(() => zod.z.discriminatedUnion("kind", [
33065
33228
  }),
33066
33229
  DeviceBecomesLeafSchema,
33067
33230
  DeviceEventLeafSchema,
33231
+ DeviceFiredLeafSchema,
33068
33232
  ScheduleLeafSchema,
33069
33233
  ManualLeafSchema,
33070
33234
  IntervalLeafSchema,
@@ -33079,6 +33243,7 @@ var AutomationWhenSchema = zod.z.lazy(() => zod.z.discriminatedUnion("kind", [
33079
33243
  var EVENT_KINDS = new Set([
33080
33244
  "device-becomes",
33081
33245
  "device-event",
33246
+ "device-fired",
33082
33247
  "schedule",
33083
33248
  "manual",
33084
33249
  "interval",
@@ -33177,6 +33342,7 @@ function hasEmptyContainer(node) {
33177
33342
  var LEAF_WORDS = {
33178
33343
  "device-becomes": "a device value that becomes",
33179
33344
  "device-event": "a device event",
33345
+ "device-fired": "a device firing an event",
33180
33346
  schedule: "a schedule",
33181
33347
  manual: "a manual run",
33182
33348
  interval: "an interval",
@@ -34645,6 +34811,16 @@ var BECOMES_DESCRIPTIONS = {
34645
34811
  from: "the value before the change, empty when it is not known",
34646
34812
  to: "the value it changed to"
34647
34813
  };
34814
+ /**
34815
+ * A fire's payload is offered too, as `data.<path>` (`{{vars.data.channel}}`):
34816
+ * those names depend on the device, so they are not in this list.
34817
+ */
34818
+ var FIRED_DESCRIPTIONS = {
34819
+ deviceId: "the device that fired",
34820
+ eventType: "the event, as the device names it",
34821
+ sourceId: "the part of the device that fired (a button), empty when it names none",
34822
+ eventKind: "the kind of press (press, long-press …), empty when the device declares none"
34823
+ };
34648
34824
  function describe$1(descriptions) {
34649
34825
  return Object.entries(descriptions).map(([name, description]) => ({
34650
34826
  name,
@@ -34653,6 +34829,10 @@ function describe$1(descriptions) {
34653
34829
  }
34654
34830
  var DETECTION_VARIABLES = describe$1(DETECTION_DESCRIPTIONS);
34655
34831
  var STATIONARY_VARIABLES = describe$1(STATIONARY_DESCRIPTIONS);
34832
+ var FIRED_VARIABLES = describe$1(FIRED_DESCRIPTIONS).map((v) => v.name === "deviceId" ? {
34833
+ ...v,
34834
+ hintKey: "firedDeviceId"
34835
+ } : v);
34656
34836
  var BECOMES_VARIABLES = describe$1(BECOMES_DESCRIPTIONS).map((v) => v.name === "deviceId" ? {
34657
34837
  ...v,
34658
34838
  hintKey: "becomesDeviceId"
@@ -34668,6 +34848,7 @@ function triggerLeafVariables(kind) {
34668
34848
  if (kind === "detection") return DETECTION_VARIABLES;
34669
34849
  if (kind === "stationary") return STATIONARY_VARIABLES;
34670
34850
  if (kind === "device-becomes") return BECOMES_VARIABLES;
34851
+ if (kind === "device-fired") return FIRED_VARIABLES;
34671
34852
  return [];
34672
34853
  }
34673
34854
  /**
@@ -34787,6 +34968,52 @@ function emitLeaf(trigger, path) {
34787
34968
  },
34788
34969
  ),
34789
34970
  )`;
34971
+ case "device-fired": return ` // event leaf ${path}: device fired — the bus event is the normal door; the
34972
+ // reconcile reads the device's event-emitter slice, so a fire whose event was
34973
+ // dropped is still seen while it is the LATEST one (D8, D1045). The first good
34974
+ // read only seeds: what fired before the start is not a trigger.
34975
+ {
34976
+ const watch = new DeviceFiredWatch(${j(trigger)})
34977
+ // The reconcile answers the same "nothing new" every tick: said once per reason.
34978
+ let lastQuiet = ''
34979
+ const land = (decision: ReturnType<DeviceFiredWatch['onEvent']>, door: 'event' | 'reconcile'): void => {
34980
+ if (decision.kind === 'ignore') {
34981
+ if (door === 'reconcile' && decision.why === lastQuiet) return
34982
+ if (door === 'reconcile') lastQuiet = decision.why
34983
+ ctx.logger.debug('device-fired trigger did not run — ' + decision.why, {
34984
+ tags: { deviceId: ${j(trigger.deviceId)} },
34985
+ leaf: ${at},
34986
+ door,
34987
+ })
34988
+ return
34989
+ }
34990
+ if (decision.kind === 'reject') {
34991
+ ctx.logger.debug('device-fired trigger rejected a fire', {
34992
+ tags: { deviceId: decision.vars.deviceId },
34993
+ reason: decision.reason,
34994
+ })
34995
+ }
34996
+ void run(
34997
+ { kind: 'device-fired', leaf: ${at}, at: Date.now(), ${varsPick("device-fired")}, ...decision.data },
34998
+ decision.reason,
34999
+ decision.kind === 'fire',
35000
+ )
35001
+ }
35002
+ disposers.push(
35003
+ ctx.eventBus.subscribe(
35004
+ { category: EventCategory.EventEmitted, deviceId: ${j(trigger.deviceId)} },
35005
+ (event) => land(watch.onEvent(event.data), 'event'),
35006
+ ),
35007
+ )
35008
+ const check = async (): Promise<void> => {
35009
+ const read = await readCapSlice(${j(trigger.deviceId)}, 'event-emitter')
35010
+ if (!read.ok) return // a failed read changes nothing: the next good one still seeds (D49)
35011
+ land(watch.onStatus(read.slice), 'reconcile')
35012
+ }
35013
+ void check()
35014
+ const reconcile = setInterval(() => { void check() }, RECONCILE_MS)
35015
+ disposers.push(() => clearInterval(reconcile))
35016
+ }`;
34790
35017
  case "device-becomes": {
34791
35018
  const hold = holdOf(trigger);
34792
35019
  return ` // event leaf ${path}: device state — the mirror is the authority, the
@@ -35140,6 +35367,7 @@ import {
35140
35367
  ConditionMirror,
35141
35368
  HoldTracker,
35142
35369
  DetectionTriggerFilter,
35370
+ DeviceFiredWatch,
35143
35371
  EventCategory,
35144
35372
  RunGate,
35145
35373
  buildTriggerTrace,
@@ -35482,24 +35710,15 @@ ${hasTime ? ` // a time-is leaf changes sides at a boundary with no device ev
35482
35710
  }
35483
35711
  }
35484
35712
 
35485
- /** Read one cap field off the state mirror. \`ok: false\` when the device,
35486
- * the cap or the field cannot be resolved — the caller decides what that
35487
- * means (the device-state trigger changes nothing), and it is logged at
35488
- * debug with the device. (Conditions read the ConditionMirror instead.) */
35489
- async function readField(
35713
+ /** One cap slice off the state mirror. \`ok: false\` when the read threw —
35714
+ * logged at debug with the device; the caller decides what that means. */
35715
+ async function readCapSlice(
35490
35716
  deviceId: number,
35491
35717
  cap: string,
35492
- fieldPath: string,
35493
- ): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false }> {
35718
+ ): Promise<{ readonly ok: true; readonly slice: unknown } | { readonly ok: false }> {
35494
35719
  try {
35495
35720
  const slice = await ctx.api.deviceState.getCapSlice.query({ deviceId, capName: cap })
35496
- let cursor: unknown = slice
35497
- for (const part of fieldPath.split('.')) {
35498
- if (cursor === null || typeof cursor !== 'object') return { ok: false }
35499
- cursor = Reflect.get(cursor, part)
35500
- }
35501
- if (cursor === undefined) return { ok: false }
35502
- return { ok: true, value: cursor }
35721
+ return { ok: true, slice }
35503
35722
  } catch (err: unknown) {
35504
35723
  ctx.logger.debug('device state read failed — the leaf keeps what it knew', {
35505
35724
  tags: { deviceId },
@@ -35510,6 +35729,26 @@ ${hasTime ? ` // a time-is leaf changes sides at a boundary with no device ev
35510
35729
  }
35511
35730
  }
35512
35731
 
35732
+ /** Read one cap field off the state mirror. \`ok: false\` when the device,
35733
+ * the cap or the field cannot be resolved — the caller decides what that
35734
+ * means (the device-state trigger changes nothing). (Conditions read the
35735
+ * ConditionMirror instead.) */
35736
+ async function readField(
35737
+ deviceId: number,
35738
+ cap: string,
35739
+ fieldPath: string,
35740
+ ): Promise<{ readonly ok: true; readonly value: unknown } | { readonly ok: false }> {
35741
+ const read = await readCapSlice(deviceId, cap)
35742
+ if (!read.ok) return { ok: false }
35743
+ let cursor: unknown = read.slice
35744
+ for (const part of fieldPath.split('.')) {
35745
+ if (cursor === null || typeof cursor !== 'object') return { ok: false }
35746
+ cursor = Reflect.get(cursor, part)
35747
+ }
35748
+ if (cursor === undefined) return { ok: false }
35749
+ return { ok: true, value: cursor }
35750
+ }
35751
+
35513
35752
  /** A trigger var keeps primitives only. */
35514
35753
  function toTraceScalar(value: unknown): string | number | boolean | null {
35515
35754
  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' ? value : null
@@ -36093,6 +36332,236 @@ function evaluateStationaryTrigger(trigger, event) {
36093
36332
  };
36094
36333
  }
36095
36334
  //#endregion
36335
+ //#region src/capabilities/event-emitter.cap.ts
36336
+ /**
36337
+ * Generic stateless event emitter. Installed on a `DeviceType.EventEmitter`
36338
+ * device. Carries the device's EXACT declared event vocabulary verbatim
36339
+ * (NO normalization). Two shapes:
36340
+ * - structured source (HA `event.*` entity) → `vocabulary` is the fixed
36341
+ * declared set (e.g. press_short, press_long, …).
36342
+ * - generic/legacy source (HA bus events, e.g. zha_event) → `vocabulary`
36343
+ * is [] (open) and `lastEvent.data` carries the complex payload.
36344
+ * `vocabulary` (D1044) names each event for a person and types it for a
36345
+ * rule; `eventTypes` is its list of native tokens, kept for older readers.
36346
+ * A fire names the part of the device it came from in `sourceId` when the
36347
+ * vocabulary declares sources (a remote's buttons).
36348
+ * `seq` is monotonic so two identical events still produce distinct slice writes.
36349
+ */
36350
+ var EventFireSchema = zod.z.object({
36351
+ deviceId: zod.z.number(),
36352
+ eventType: zod.z.string(),
36353
+ sourceId: zod.z.string().optional(),
36354
+ data: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
36355
+ timestamp: zod.z.number().meta(require_sleep.readingMeta("none")),
36356
+ seq: zod.z.number().meta(require_sleep.readingMeta("count"))
36357
+ });
36358
+ var EventEmitterStatusSchema = zod.z.object({
36359
+ eventTypes: zod.z.array(zod.z.string()),
36360
+ /**
36361
+ * Required of a provider by the type. A status written before the field
36362
+ * existed still parses, as an empty vocabulary: read it through
36363
+ * `readEventVocabulary`, which then answers with the plain tokens.
36364
+ */
36365
+ vocabulary: zod.z.array(EventVocabularyEntrySchema).default([]),
36366
+ lastEvent: EventFireSchema.nullable(),
36367
+ eventCountSinceStart: zod.z.number().meta(require_sleep.readingMeta("count"))
36368
+ });
36369
+ var eventEmitterCapability = {
36370
+ name: "event-emitter",
36371
+ scope: "device",
36372
+ deviceNative: true,
36373
+ mode: "singleton",
36374
+ deviceTypes: [require_composed_stable_id.DeviceType.EventEmitter],
36375
+ methods: {},
36376
+ events: { onEvent: { data: EventFireSchema } },
36377
+ status: {
36378
+ schema: EventEmitterStatusSchema,
36379
+ kind: "push"
36380
+ },
36381
+ runtimeState: EventEmitterStatusSchema,
36382
+ /**
36383
+ * Runtime-state durability: **session** — `eventCountSinceStart` names its own scope.
36384
+ *
36385
+ * See `RuntimeStateDurability`. Enforced by
36386
+ * `scripts/check-runtime-state-durability.ts`.
36387
+ */
36388
+ durability: "session",
36389
+ /**
36390
+ * History (D850): none — `eventCountSinceStart` resets with the addon; events live in ledgers.
36391
+ */
36392
+ history: "none"
36393
+ };
36394
+ //#endregion
36395
+ //#region src/automation/fired-trigger.ts
36396
+ /**
36397
+ * The `device-fired` trigger: does this fire of an `event-emitter` device start
36398
+ * a run (D1045).
36399
+ *
36400
+ * Two doors lead here, and a fire passes exactly one of them:
36401
+ * - the bus event (`EventCategory.EventEmitted`, payload `EventFire`) — the
36402
+ * normal path;
36403
+ * - the reconcile read of the device's `event-emitter` slice — events are
36404
+ * telemetry (D8), so a fire whose event was dropped is still seen as
36405
+ * `lastEvent`, when it is the latest one. Only the LATEST is recoverable.
36406
+ *
36407
+ * The watch remembers the newest fire it has handled. "Newer" is the fire's
36408
+ * timestamp, then its `seq`: `seq` restarts at 1 with the provider, so it
36409
+ * orders two fires of one provider run and nothing else.
36410
+ *
36411
+ * The first reading of the slice only SEEDS (a restart is not a press), and a
36412
+ * read that failed changes nothing (D49): the next good one still seeds.
36413
+ */
36414
+ /** How deep a payload is walked, and how many variables one fire may add. */
36415
+ var MAX_DATA_DEPTH = 3;
36416
+ var MAX_DATA_VARS = 32;
36417
+ function isScalar(value) {
36418
+ return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
36419
+ }
36420
+ function isRecord$4(value) {
36421
+ return value !== null && typeof value === "object" && !Array.isArray(value);
36422
+ }
36423
+ /** The scalars of a fire's payload as `data.<path>` variables; lists and nulls are left out. */
36424
+ function firedDataVars(data) {
36425
+ const out = {};
36426
+ const walk = (value, path, depth) => {
36427
+ if (Object.keys(out).length >= MAX_DATA_VARS) return;
36428
+ if (isScalar(value)) {
36429
+ out[path] = value;
36430
+ return;
36431
+ }
36432
+ if (!isRecord$4(value) || depth >= MAX_DATA_DEPTH) return;
36433
+ for (const [key, child] of Object.entries(value)) walk(child, `${path}.${key}`, depth + 1);
36434
+ };
36435
+ if (isRecord$4(data)) for (const [key, child] of Object.entries(data)) walk(child, `data.${key}`, 1);
36436
+ return out;
36437
+ }
36438
+ function readPath(data, path) {
36439
+ let cursor = data;
36440
+ for (const part of path.split(".")) {
36441
+ if (!isRecord$4(cursor)) return void 0;
36442
+ cursor = cursor[part];
36443
+ }
36444
+ return cursor;
36445
+ }
36446
+ function isNewer(fire, than) {
36447
+ if (than === null) return true;
36448
+ if (fire.timestamp !== than.timestamp) return fire.timestamp > than.timestamp;
36449
+ return fire.seq > than.seq;
36450
+ }
36451
+ /** Said in the trace when the reconcile, not the bus event, brought the fire. */
36452
+ var FIRED_RECOVERED_NOTE = "recovered by reconcile";
36453
+ var DeviceFiredWatch = class {
36454
+ leaf;
36455
+ /** The newest fire handled, by either door. */
36456
+ #last = null;
36457
+ /** A baseline exists: a slice was read, or a bus event arrived. */
36458
+ #seeded = false;
36459
+ /** The device's vocabulary as last read; `null` until a slice answered. */
36460
+ #vocabulary = null;
36461
+ constructor(leaf) {
36462
+ this.leaf = leaf;
36463
+ }
36464
+ /** A bus event (`event.data` of `EventCategory.EventEmitted`). */
36465
+ onEvent(data) {
36466
+ const parsed = EventFireSchema.safeParse(data);
36467
+ if (!parsed.success) return {
36468
+ kind: "ignore",
36469
+ why: "malformed event"
36470
+ };
36471
+ const fire = parsed.data;
36472
+ if (fire.deviceId !== this.leaf.deviceId) return {
36473
+ kind: "ignore",
36474
+ why: `device ${fire.deviceId} is not the trigger's device`
36475
+ };
36476
+ if (!isNewer(fire, this.#last)) return {
36477
+ kind: "ignore",
36478
+ why: "this fire was already handled"
36479
+ };
36480
+ this.#last = {
36481
+ timestamp: fire.timestamp,
36482
+ seq: fire.seq
36483
+ };
36484
+ this.#seeded = true;
36485
+ return this.#judge(fire, false);
36486
+ }
36487
+ /** A reading of the device's `event-emitter` slice (seed, then reconcile). */
36488
+ onStatus(status) {
36489
+ const parsed = EventEmitterStatusSchema.safeParse(status);
36490
+ if (!parsed.success) return {
36491
+ kind: "ignore",
36492
+ why: "the event-emitter status is unreadable"
36493
+ };
36494
+ this.#vocabulary = readEventVocabulary(parsed.data);
36495
+ const fire = parsed.data.lastEvent;
36496
+ const first = !this.#seeded;
36497
+ this.#seeded = true;
36498
+ if (fire === null) return {
36499
+ kind: "ignore",
36500
+ why: "the device has not fired"
36501
+ };
36502
+ if (!isNewer(fire, this.#last)) return {
36503
+ kind: "ignore",
36504
+ why: "this fire was already handled"
36505
+ };
36506
+ this.#last = {
36507
+ timestamp: fire.timestamp,
36508
+ seq: fire.seq
36509
+ };
36510
+ if (first) return {
36511
+ kind: "ignore",
36512
+ why: "seeded: what fired before the start is not a trigger"
36513
+ };
36514
+ if (fire.deviceId !== this.leaf.deviceId) return {
36515
+ kind: "ignore",
36516
+ why: `device ${fire.deviceId} is not the trigger's device`
36517
+ };
36518
+ return this.#judge(fire, true);
36519
+ }
36520
+ #kindOf(fire) {
36521
+ const vocabulary = this.#vocabulary ?? conventionalEventVocabulary([fire.eventType]);
36522
+ return (findVocabularyEntry(vocabulary, fire.eventType, fire.sourceId) ?? findVocabularyEntry(vocabulary, fire.eventType))?.kind;
36523
+ }
36524
+ #judge(fire, recovered) {
36525
+ const { eventIds, sourceIds, kinds, match } = this.leaf;
36526
+ if (eventIds !== void 0 && !eventIds.includes(fire.eventType)) return {
36527
+ kind: "ignore",
36528
+ why: `event ${fire.eventType} is not one of [${eventIds.join(", ")}]`
36529
+ };
36530
+ if (sourceIds !== void 0 && (fire.sourceId === void 0 || !sourceIds.includes(fire.sourceId))) return {
36531
+ kind: "ignore",
36532
+ why: `source ${fire.sourceId ?? "(none)"} is not one of [${sourceIds.join(", ")}]`
36533
+ };
36534
+ const kind = this.#kindOf(fire);
36535
+ if (kinds !== void 0 && (kind === void 0 || !kinds.includes(kind))) return {
36536
+ kind: "ignore",
36537
+ why: `kind ${kind ?? "(none)"} is not one of [${kinds.join(", ")}]`
36538
+ };
36539
+ const vars = {
36540
+ deviceId: fire.deviceId,
36541
+ eventType: fire.eventType,
36542
+ sourceId: fire.sourceId ?? "",
36543
+ eventKind: kind ?? ""
36544
+ };
36545
+ const data = firedDataVars(fire.data);
36546
+ for (const predicate of match ?? []) {
36547
+ const found = readPath(fire.data, predicate.path);
36548
+ if (found !== predicate.equals) return {
36549
+ kind: "reject",
36550
+ reason: `data.${predicate.path} is ${JSON.stringify(found) ?? "not set"}, the trigger wants ${JSON.stringify(predicate.equals)}`,
36551
+ vars,
36552
+ data
36553
+ };
36554
+ }
36555
+ const what = `${fire.eventType}${fire.sourceId === void 0 ? "" : ` from ${fire.sourceId}`}`;
36556
+ return {
36557
+ kind: "fire",
36558
+ reason: recovered ? `${what} — ${FIRED_RECOVERED_NOTE}` : what,
36559
+ vars,
36560
+ data
36561
+ };
36562
+ }
36563
+ };
36564
+ //#endregion
36096
36565
  //#region src/automation/run-gate.ts
36097
36566
  var MINUTE_MS$2 = 6e4;
36098
36567
  function minutes(ms) {
@@ -36624,6 +37093,7 @@ var AutomationConditionTraceNodeSchema = zod.z.object({
36624
37093
  "triggered-by",
36625
37094
  "device-becomes",
36626
37095
  "device-event",
37096
+ "device-fired",
36627
37097
  "schedule",
36628
37098
  "interval",
36629
37099
  "manual",
@@ -37580,7 +38050,8 @@ function isVarRef(value) {
37580
38050
  const keys = Object.keys(value);
37581
38051
  return keys.length === 1 && keys[0] === "$var" && typeof Reflect.get(value, "$var") === "string";
37582
38052
  }
37583
- var TEMPLATE_RE = /\{\{\s*vars\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
38053
+ /** `{{vars.name}}`, or a dotted name (`{{vars.data.channel}}`): the bag is flat, the dots are part of the key. */
38054
+ var TEMPLATE_RE = /\{\{\s*vars\.([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*\}\}/g;
37584
38055
  /**
37585
38056
  * Substitute a step's args from the run's variables. SUBSTITUTION only, never
37586
38057
  * evaluation:
@@ -37630,7 +38101,7 @@ function newSlotNonce() {
37630
38101
  return Math.random().toString(36).slice(2, 12);
37631
38102
  }
37632
38103
  function slotPattern(nonce) {
37633
- return new RegExp(`${VAR_SLOT_OPEN}${nonce}:([A-Za-z_][A-Za-z0-9_]*)${VAR_SLOT_CLOSE}`, "g");
38104
+ return new RegExp(`${VAR_SLOT_OPEN}${nonce}:([A-Za-z_][A-Za-z0-9_.]*)${VAR_SLOT_CLOSE}`, "g");
37634
38105
  }
37635
38106
  /** `text` with every `{{vars.x}}` slot (the only slot the run-time holds) replaced by `replacement`. */
37636
38107
  function holdVarSlots(text, replacement) {
@@ -38319,6 +38790,29 @@ var AUTOMATION_LEAF_CATALOG = {
38319
38790
  category: ""
38320
38791
  })
38321
38792
  },
38793
+ "device-fired": {
38794
+ kind: "device-fired",
38795
+ category: "devices",
38796
+ role: "event",
38797
+ allowedIn: EVENT_CONTEXTS,
38798
+ i18nKey: "automation.leafCatalog.device-fired",
38799
+ keywords: [
38800
+ "button",
38801
+ "press",
38802
+ "long",
38803
+ "remote",
38804
+ "switch",
38805
+ "key",
38806
+ "fires",
38807
+ "event",
38808
+ "click"
38809
+ ],
38810
+ needsDeviceValue: false,
38811
+ seed: () => ({
38812
+ kind: "device-fired",
38813
+ deviceId: 0
38814
+ })
38815
+ },
38322
38816
  schedule: {
38323
38817
  kind: "schedule",
38324
38818
  category: "time",
@@ -38506,6 +39000,7 @@ var AUTOMATION_LEAF_KINDS = [
38506
39000
  "detection",
38507
39001
  "stationary",
38508
39002
  "device-becomes",
39003
+ "device-fired",
38509
39004
  "device-event",
38510
39005
  "schedule",
38511
39006
  "interval",
@@ -57153,203 +57648,6 @@ var enumSensorCapability = {
57153
57648
  volatileStateFields: ["lastFetchedAt", "timestamp"]
57154
57649
  };
57155
57650
  //#endregion
57156
- //#region src/capabilities/event-vocabulary.ts
57157
- /**
57158
- * The declared vocabulary of an `event-emitter` device (D1044): what the
57159
- * device can fire, named for a person and typed for a rule.
57160
- *
57161
- * `id` is the native token, verbatim. `kind` is the meaning shared by every
57162
- * integration, so "any long press" can be asked without knowing a vendor's
57163
- * token. A device with several buttons declares one entry per button and
57164
- * token: an entry is identified by its token AND its source.
57165
- */
57166
- /** The cross-integration meaning of an event. */
57167
- var EVENT_VOCABULARY_KINDS = [
57168
- "press",
57169
- "long-press",
57170
- "long-press-start",
57171
- "release",
57172
- "repeat",
57173
- "double-press",
57174
- "other"
57175
- ];
57176
- var EventVocabularyKindSchema = zod.z.enum(EVENT_VOCABULARY_KINDS);
57177
- /** The part of the device an event comes from: a button, a channel. */
57178
- var EventVocabularySourceSchema = zod.z.object({
57179
- id: zod.z.string().min(1),
57180
- label: zod.z.string().min(1)
57181
- });
57182
- /** One scalar field of an event's `data`, by dotted path. */
57183
- var EventVocabularyFieldSchema = zod.z.object({
57184
- path: zod.z.string().min(1),
57185
- kind: zod.z.enum([
57186
- "string",
57187
- "number",
57188
- "boolean",
57189
- "enum"
57190
- ]),
57191
- enumValues: zod.z.array(zod.z.string()).optional(),
57192
- label: zod.z.string().min(1).optional()
57193
- });
57194
- var EventVocabularyEntrySchema = zod.z.object({
57195
- /** The native token, verbatim. */
57196
- id: zod.z.string().min(1),
57197
- source: EventVocabularySourceSchema.optional(),
57198
- label: zod.z.string().min(1),
57199
- description: zod.z.string().optional(),
57200
- kind: EventVocabularyKindSchema.optional(),
57201
- payload: zod.z.array(EventVocabularyFieldSchema).optional()
57202
- });
57203
- /**
57204
- * The vocabulary of a source that declares tokens and nothing else: one
57205
- * entry per token, labelled with the token itself.
57206
- */
57207
- function plainEventVocabulary(eventTypes) {
57208
- return [...new Set(eventTypes)].filter((eventType) => eventType !== "").map((eventType) => ({
57209
- id: eventType,
57210
- label: eventType
57211
- }));
57212
- }
57213
- /**
57214
- * Tokens many integrations use for a button, by their normalised spelling
57215
- * (lower case, words joined by `_`). Exact matches only: a token that
57216
- * merely contains one of these words gets no kind.
57217
- */
57218
- var CONVENTIONAL_KINDS = {
57219
- press: "press",
57220
- pressed: "press",
57221
- single: "press",
57222
- single_press: "press",
57223
- single_click: "press",
57224
- short_press: "press",
57225
- press_short: "press",
57226
- click: "press",
57227
- initial_press: "press",
57228
- long_press: "long-press",
57229
- press_long: "long-press",
57230
- long_click: "long-press",
57231
- hold: "long-press",
57232
- long_press_start: "long-press-start",
57233
- press_long_start: "long-press-start",
57234
- release: "release",
57235
- released: "release",
57236
- long_release: "release",
57237
- long_press_release: "release",
57238
- press_long_release: "release",
57239
- short_release: "release",
57240
- repeat: "repeat",
57241
- hold_repeat: "repeat",
57242
- press_cont: "repeat",
57243
- double_press: "double-press",
57244
- double_click: "double-press",
57245
- double: "double-press",
57246
- multi_press_2: "double-press"
57247
- };
57248
- function normalisedToken(token) {
57249
- return token.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
57250
- }
57251
- function readableToken(token) {
57252
- const words = normalisedToken(token).replace(/_/g, " ");
57253
- if (words === "") return token;
57254
- return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
57255
- }
57256
- /**
57257
- * The vocabulary of a source that declares tokens only, read by convention:
57258
- * a readable label, and the shared kind when the token is one many
57259
- * integrations use for a button. The token itself is kept verbatim.
57260
- */
57261
- function conventionalEventVocabulary(eventTypes) {
57262
- return plainEventVocabulary(eventTypes).map((entry) => {
57263
- const kind = CONVENTIONAL_KINDS[normalisedToken(entry.id)];
57264
- const label = readableToken(entry.id);
57265
- return kind === void 0 ? {
57266
- id: entry.id,
57267
- label
57268
- } : {
57269
- id: entry.id,
57270
- label,
57271
- kind
57272
- };
57273
- });
57274
- }
57275
- /** The native tokens of a vocabulary, each once, in declaration order. */
57276
- function eventTypesOfVocabulary(vocabulary) {
57277
- return [...new Set(vocabulary.map((entry) => entry.id))];
57278
- }
57279
- /**
57280
- * The vocabulary to show and match against. A status with none declared
57281
- * answers with its plain tokens, so an older provider is still usable.
57282
- */
57283
- function readEventVocabulary(status) {
57284
- const declared = status.vocabulary;
57285
- if (declared !== void 0 && declared.length > 0) return declared;
57286
- return plainEventVocabulary(status.eventTypes);
57287
- }
57288
- /** The entry a fire belongs to: same token, same source (or both without one). */
57289
- function findVocabularyEntry(vocabulary, eventType, sourceId) {
57290
- return vocabulary.find((entry) => entry.id === eventType && entry.source?.id === sourceId);
57291
- }
57292
- //#endregion
57293
- //#region src/capabilities/event-emitter.cap.ts
57294
- /**
57295
- * Generic stateless event emitter. Installed on a `DeviceType.EventEmitter`
57296
- * device. Carries the device's EXACT declared event vocabulary verbatim
57297
- * (NO normalization). Two shapes:
57298
- * - structured source (HA `event.*` entity) → `vocabulary` is the fixed
57299
- * declared set (e.g. press_short, press_long, …).
57300
- * - generic/legacy source (HA bus events, e.g. zha_event) → `vocabulary`
57301
- * is [] (open) and `lastEvent.data` carries the complex payload.
57302
- * `vocabulary` (D1044) names each event for a person and types it for a
57303
- * rule; `eventTypes` is its list of native tokens, kept for older readers.
57304
- * A fire names the part of the device it came from in `sourceId` when the
57305
- * vocabulary declares sources (a remote's buttons).
57306
- * `seq` is monotonic so two identical events still produce distinct slice writes.
57307
- */
57308
- var EventFireSchema = zod.z.object({
57309
- deviceId: zod.z.number(),
57310
- eventType: zod.z.string(),
57311
- sourceId: zod.z.string().optional(),
57312
- data: zod.z.record(zod.z.string(), zod.z.unknown()).nullable(),
57313
- timestamp: zod.z.number().meta(require_sleep.readingMeta("none")),
57314
- seq: zod.z.number().meta(require_sleep.readingMeta("count"))
57315
- });
57316
- var EventEmitterStatusSchema = zod.z.object({
57317
- eventTypes: zod.z.array(zod.z.string()),
57318
- /**
57319
- * Required of a provider by the type. A status written before the field
57320
- * existed still parses, as an empty vocabulary: read it through
57321
- * `readEventVocabulary`, which then answers with the plain tokens.
57322
- */
57323
- vocabulary: zod.z.array(EventVocabularyEntrySchema).default([]),
57324
- lastEvent: EventFireSchema.nullable(),
57325
- eventCountSinceStart: zod.z.number().meta(require_sleep.readingMeta("count"))
57326
- });
57327
- var eventEmitterCapability = {
57328
- name: "event-emitter",
57329
- scope: "device",
57330
- deviceNative: true,
57331
- mode: "singleton",
57332
- deviceTypes: [require_composed_stable_id.DeviceType.EventEmitter],
57333
- methods: {},
57334
- events: { onEvent: { data: EventFireSchema } },
57335
- status: {
57336
- schema: EventEmitterStatusSchema,
57337
- kind: "push"
57338
- },
57339
- runtimeState: EventEmitterStatusSchema,
57340
- /**
57341
- * Runtime-state durability: **session** — `eventCountSinceStart` names its own scope.
57342
- *
57343
- * See `RuntimeStateDurability`. Enforced by
57344
- * `scripts/check-runtime-state-durability.ts`.
57345
- */
57346
- durability: "session",
57347
- /**
57348
- * History (D850): none — `eventCountSinceStart` resets with the addon; events live in ledgers.
57349
- */
57350
- history: "none"
57351
- };
57352
- //#endregion
57353
57651
  //#region src/capabilities/face-gallery.cap.ts
57354
57652
  var IdentitySchema = zod.z.object({
57355
57653
  id: zod.z.string(),
@@ -95999,6 +96297,10 @@ function leafIssues(site, when, root) {
95999
96297
  }
96000
96298
  return;
96001
96299
  }
96300
+ if (leaf.kind === "device-fired") {
96301
+ if (deviceOf(site, leaf.deviceId) === void 0) issues.push(`${at}: no device has id ${leaf.deviceId}`);
96302
+ return;
96303
+ }
96002
96304
  if (leaf.kind === "device-event" && leaf.deviceId !== void 0) {
96003
96305
  if (deviceOf(site, leaf.deviceId) === void 0) issues.push(`${at}: no device has id ${leaf.deviceId}`);
96004
96306
  }
@@ -139182,6 +139484,8 @@ exports.DeviceExportInstancePinSchema = InstancePinSchema;
139182
139484
  exports.DeviceExportStatusSchema = DeviceExportStatusSchema;
139183
139485
  exports.DeviceExportUnexposeInputSchema = UnexposeInputSchema;
139184
139486
  exports.DeviceFeature = require_composed_stable_id.DeviceFeature;
139487
+ exports.DeviceFiredMatchSchema = DeviceFiredMatchSchema;
139488
+ exports.DeviceFiredWatch = DeviceFiredWatch;
139185
139489
  exports.DeviceHistoryKindSchema = DeviceHistoryKindSchema;
139186
139490
  exports.DeviceHistoryOrphanDeleteRefusalSchema = DeviceHistoryOrphanDeleteRefusalSchema;
139187
139491
  exports.DeviceHistoryOrphanReasonSchema = DeviceHistoryOrphanReasonSchema;
@@ -139400,6 +139704,7 @@ exports.FEEDER_EXAMPLE_ADDON_ID = FEEDER_EXAMPLE_ADDON_ID;
139400
139704
  exports.FEEDER_EXAMPLE_HA_DEVICE_ID = FEEDER_EXAMPLE_HA_DEVICE_ID;
139401
139705
  exports.FEW_SHOT_COUNT = FEW_SHOT_COUNT;
139402
139706
  exports.FFMPEG_PATH_ENV = require_implemented_methods.FFMPEG_PATH_ENV;
139707
+ exports.FIRED_RECOVERED_NOTE = FIRED_RECOVERED_NOTE;
139403
139708
  exports.FIRST_LEVEL_MACRO_CLASSES = FIRST_LEVEL_MACRO_CLASSES;
139404
139709
  exports.FORBIDDEN_MESSAGE_PREFIX = require_sleep.FORBIDDEN_MESSAGE_PREFIX;
139405
139710
  exports.FORWARD_INPUT_KEY = require_implemented_methods.FORWARD_INPUT_KEY;
@@ -141557,6 +141862,7 @@ exports.findMigrationsBlocked = require_sleep.findMigrationsBlocked;
141557
141862
  exports.findTimezone = findTimezone;
141558
141863
  exports.findVocabAction = require_sleep.findVocabAction;
141559
141864
  exports.findVocabularyEntry = findVocabularyEntry;
141865
+ exports.firedDataVars = firedDataVars;
141560
141866
  exports.flattenNestedRecords = flattenNestedRecords;
141561
141867
  exports.flattenPortsOver = flattenPortsOver;
141562
141868
  exports.flipperIrDraft = flipperIrDraft;