@camstack/types 1.2.548 → 1.2.550

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.
Files changed (90) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/dist/addon/addon-instance.d.ts +24 -0
  3. package/dist/addon/build-addon-route-provider.d.ts +2 -0
  4. package/dist/addon.js +5 -5
  5. package/dist/addon.mjs +5 -5
  6. package/dist/automation/index.d.ts +4 -3
  7. package/dist/automation/recipe.d.ts +12105 -604
  8. package/dist/automation/scheduler.d.ts +7 -0
  9. package/dist/automation/step-runner.d.ts +70 -0
  10. package/dist/automation/trace.d.ts +252 -145
  11. package/dist/automation/wait-until.d.ts +32 -0
  12. package/dist/automation/when-site.d.ts +1 -1
  13. package/dist/capabilities/accessories.cap.d.ts +1 -1
  14. package/dist/capabilities/actions.cap.d.ts +1 -178
  15. package/dist/capabilities/addon-routes.cap.d.ts +3 -0
  16. package/dist/capabilities/battery.cap.d.ts +2 -2
  17. package/dist/capabilities/capability-definition.d.ts +47 -1
  18. package/dist/capabilities/climate-control.cap.d.ts +8 -1
  19. package/dist/capabilities/core-blocks.cap.d.ts +119 -8723
  20. package/dist/capabilities/customize-catalog.d.ts +3 -1
  21. package/dist/capabilities/customize-spec.d.ts +26 -2
  22. package/dist/capabilities/device-manager.cap.d.ts +6 -0
  23. package/dist/capabilities/event-emitter.cap.d.ts +99 -3
  24. package/dist/capabilities/event-vocabulary.d.ts +99 -0
  25. package/dist/capabilities/fan-control.cap.d.ts +248 -0
  26. package/dist/capabilities/fan-presets.cap.d.ts +172 -536
  27. package/dist/capabilities/group-active.cap.d.ts +1 -1
  28. package/dist/capabilities/group-commands.cap.d.ts +1 -1
  29. package/dist/capabilities/group-status.cap.d.ts +1 -1
  30. package/dist/capabilities/heating-valve.cap.d.ts +1 -1
  31. package/dist/capabilities/hero-layout.cap.d.ts +2 -0
  32. package/dist/capabilities/humidifier.cap.d.ts +5 -0
  33. package/dist/capabilities/humidity-sensor.cap.d.ts +1 -1
  34. package/dist/capabilities/index.d.ts +5 -4
  35. package/dist/capabilities/media-player.cap.d.ts +7 -0
  36. package/dist/capabilities/oauth-integration.cap.d.ts +8 -0
  37. package/dist/capabilities/pet-fountain.cap.d.ts +5 -0
  38. package/dist/capabilities/power-meter.cap.d.ts +5 -5
  39. package/dist/capabilities/power-source.cap.d.ts +5 -0
  40. package/dist/capabilities/running-state.cap.d.ts +2 -2
  41. package/dist/capabilities/schedulers.cap.d.ts +1 -178
  42. package/dist/capabilities/sso-bridge.cap.d.ts +3 -0
  43. package/dist/capabilities/switch.cap.d.ts +1 -1
  44. package/dist/capabilities/temperature-sensor.cap.d.ts +1 -1
  45. package/dist/capabilities/timed-run.cap.d.ts +19 -5
  46. package/dist/capabilities/user-management.cap.d.ts +4 -0
  47. package/dist/capabilities/water-heater.cap.d.ts +7 -0
  48. package/dist/client.js +7 -11
  49. package/dist/client.mjs +7 -11
  50. package/dist/{composed-stable-id-DrGLxjVF.js → composed-stable-id-CDNLq7Y8.js} +27 -10
  51. package/dist/{composed-stable-id-DFNyOFzz.mjs → composed-stable-id-CPp3votu.mjs} +27 -10
  52. package/dist/composition/composition-report.d.ts +6 -0
  53. package/dist/composition/evaluate-field.d.ts +7 -0
  54. package/dist/composition/field-kinds.d.ts +12 -1
  55. package/dist/composition/helpers/index.d.ts +1 -1
  56. package/dist/composition/helpers/source-pick.d.ts +0 -5
  57. package/dist/composition/power-source-link.d.ts +15 -0
  58. package/dist/composition/state-fields.d.ts +2 -0
  59. package/dist/composition/validate-composition.d.ts +15 -1
  60. package/dist/device/base-device-provider.d.ts +13 -0
  61. package/dist/device/device-control-resolution.d.ts +1 -33
  62. package/dist/device/device-kind.d.ts +36 -0
  63. package/dist/device/device-management.d.ts +3 -0
  64. package/dist/device/device-type.d.ts +27 -10
  65. package/dist/device/hero/hero-fragment.d.ts +2 -0
  66. package/dist/device/hero/hero-layout.d.ts +1 -3
  67. package/dist/device/hero/hero-look.d.ts +18 -12
  68. package/dist/device/hero/hero-scene.d.ts +9 -3
  69. package/dist/device/index.d.ts +2 -1
  70. package/dist/device/power-switch.d.ts +82 -0
  71. package/dist/device/schema-fields.d.ts +10 -1
  72. package/dist/generated/addon-api.d.ts +7 -0
  73. package/dist/generated/addon-cap-facts.d.ts +1 -1
  74. package/dist/generated/cap-input-defaults.d.ts +1 -1
  75. package/dist/generated/collection-array-methods.d.ts +1 -1
  76. package/dist/generated/customize-catalog.d.ts +257 -8
  77. package/dist/generated/method-access-map.d.ts +1 -1
  78. package/dist/generated/method-device-selectors.d.ts +1 -1
  79. package/dist/{implemented-methods-M5aguGon.mjs → implemented-methods-5YMDeE3f.mjs} +1 -1
  80. package/dist/{implemented-methods-8AU92riC.js → implemented-methods-Cj65uy2F.js} +1 -1
  81. package/dist/index.d.ts +11 -6
  82. package/dist/index.js +2386 -494
  83. package/dist/index.mjs +2312 -488
  84. package/dist/interfaces/addon-routes.d.ts +13 -0
  85. package/dist/interfaces/config-ui.d.ts +15 -24
  86. package/dist/node.js +2 -2
  87. package/dist/node.mjs +2 -2
  88. package/dist/{sleep-D_NpiLFP.mjs → sleep-D0roI_CZ.mjs} +50 -1
  89. package/dist/{sleep-vzHEmsrO.js → sleep-dcR4vBFG.js} +50 -1
  90. package/package.json +1 -1
@@ -3,7 +3,7 @@
3
3
  * server read this projection, not the cap module.
4
4
  */
5
5
  import type { DeviceType } from '../device/device-type.js';
6
- import type { CameraSensorCustomizeMode, CustomizeApplyAuthority, CustomizeApplyMode, CustomizeCardinality, CustomizeCompanion, CustomizeEventEdge, CustomizeOverridable, CustomizeOverrideRule, CustomizeSourceReport, CustomizeValueKind, ThresholdDeviceTypeDefaults } from './customize-spec.js';
6
+ import type { CameraSensorCustomizeMode, CustomizeApplyAuthority, CustomizeApplyMode, CustomizeCardinality, CustomizeCompanion, CustomizeEventEdge, CustomizeOverridable, CustomizeOverrideRule, CustomizeSourceReport, CustomizeTargetSection, CustomizeValueKind, ThresholdDeviceTypeDefaults } from './customize-spec.js';
7
7
  export type CustomizeCatalogValueKind = 'boolean' | 'number' | 'string' | 'enum';
8
8
  export type CustomizeCatalogTransform = {
9
9
  readonly kind: 'identity';
@@ -95,6 +95,8 @@ export interface CustomizeCatalogTarget {
95
95
  readonly companions?: readonly CustomizeCompanion[];
96
96
  readonly sourceReport: CustomizeSourceReport;
97
97
  readonly advancedExpression: boolean;
98
+ /** The Customize section the cap files this target under (D1034). */
99
+ readonly section?: CustomizeTargetSection;
98
100
  }
99
101
  export interface CustomizeCatalogEntry {
100
102
  readonly version: 1;
@@ -22,6 +22,13 @@ export type CustomizeEventShape = (typeof CUSTOMIZE_EVENT_SHAPES)[number];
22
22
  export declare const CUSTOMIZE_APPLY_AUTHORITY_KINDS: readonly ['composition-claim', 'camera-sensors'];
23
23
  export type CustomizeApplyAuthorityKind = (typeof CUSTOMIZE_APPLY_AUTHORITY_KINDS)[number];
24
24
  export type CustomizeValueKind = 'boolean' | 'number' | 'string' | 'enum';
25
+ /**
26
+ * A named group a cap may file its targets under in the Customize table
27
+ * (D1034). Admin-ui keys a section title off this list; a target without one
28
+ * lands in the section its cardinality implies.
29
+ */
30
+ export declare const CUSTOMIZE_TARGET_SECTIONS: readonly ['oscillation-axes'];
31
+ export type CustomizeTargetSection = (typeof CUSTOMIZE_TARGET_SECTIONS)[number];
25
32
  /**
26
33
  * `add`: an extension is offered only when the device lacks the capability (D944).
27
34
  * `replace`: the extension replaces a NATIVE field, and only a field the cap
@@ -30,7 +37,11 @@ export type CustomizeValueKind = 'boolean' | 'number' | 'string' | 'enum';
30
37
  export type CustomizeApplyMode = 'add' | 'replace';
31
38
  /** A native field a named extension of the same cap may replace. The only door to `apply: 'replace'`. */
32
39
  export interface CustomizeOverridable {
33
- /** Top-level state field of the cap's runtime slice. */
40
+ /**
41
+ * State field of the cap's runtime slice: top-level, or a dotted leaf
42
+ * (`oscillationAxes.horizontal.angle`, D1034) — the claim then owns that
43
+ * leaf only and the hub sets it into the native object.
44
+ */
34
45
  readonly path: string;
35
46
  /** The id of the scalar target allowed to replace it. */
36
47
  readonly by: string;
@@ -63,6 +74,8 @@ export interface CustomizeTargetBase {
63
74
  readonly apply: CustomizeApplyMode;
64
75
  readonly sourceReport: CustomizeSourceReport;
65
76
  readonly advancedExpression?: boolean;
77
+ /** The Customize section the target is listed under (D1034). */
78
+ readonly section?: CustomizeTargetSection;
66
79
  }
67
80
  export type CustomizeSourceSpec = SwitchSourceSpec | BinarySourceSpec | NumericSourceSpec | EnumSourceSpec | FieldSourceSpec;
68
81
  export interface SwitchSourceSpec {
@@ -156,7 +169,7 @@ export interface CustomizeSourceReport {
156
169
  readonly nativeValue?: string;
157
170
  readonly assignedValue?: string;
158
171
  }
159
- export type CustomizeCompanion = CustomizeConstantCompanion | CustomizeClockCompanion | CustomizeTransitionTimeCompanion;
172
+ export type CustomizeCompanion = CustomizeConstantCompanion | CustomizeClockCompanion | CustomizeTransitionTimeCompanion | CustomizeSourceFieldCompanion;
160
173
  export interface CustomizeConstantCompanion {
161
174
  readonly kind: 'constant';
162
175
  readonly path: string;
@@ -174,6 +187,17 @@ export interface CustomizeClockCompanion {
174
187
  readonly path: string;
175
188
  readonly when: 'add' | 'always';
176
189
  }
190
+ /**
191
+ * Another field of the SAME linked source, written beside the assigned value
192
+ * (D1034): a fan axis takes its limits from the `min`/`max`/`step` of the
193
+ * control linked to its angle. Rides with the field on an add and a replace.
194
+ */
195
+ export interface CustomizeSourceFieldCompanion {
196
+ readonly kind: 'source-field';
197
+ readonly path: string;
198
+ /** The field of the linked source device's cap. */
199
+ readonly field: string;
200
+ }
177
201
  export interface CustomizeTransitionTimeCompanion {
178
202
  readonly kind: 'transition-time';
179
203
  readonly path: string;
@@ -859,7 +859,13 @@ export declare const deviceManagerCapability: {
859
859
  enum: "enum";
860
860
  number: "number";
861
861
  string: "string";
862
+ union: "union";
862
863
  }>;
864
+ unionMembers: z.ZodOptional<z.ZodArray<z.ZodEnum<{
865
+ boolean: "boolean";
866
+ number: "number";
867
+ string: "string";
868
+ }>>>;
863
869
  enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
864
870
  item: z.ZodOptional<z.ZodBoolean>;
865
871
  quantity: z.ZodOptional<z.ZodType<"angle" | "apparent-power" | "area" | "bitrate" | "colour-temperature" | "concentration-mass" | "concentration-ppb" | "concentration-volume" | "count" | "current" | "device" | "duration" | "duration-ms" | "energy" | "humidity" | "illuminance" | "index" | "information" | "irradiance" | "length" | "mass" | "none" | "percentage" | "power" | "precipitation" | "precipitation-rate" | "pressure" | "rate" | "ratio" | "signal-level" | "sound-level" | "speed" | "temperature" | "voltage" | "volume", unknown, z.core.$ZodTypeInternals<"angle" | "apparent-power" | "area" | "bitrate" | "colour-temperature" | "concentration-mass" | "concentration-ppb" | "concentration-volume" | "count" | "current" | "device" | "duration" | "duration-ms" | "energy" | "humidity" | "illuminance" | "index" | "information" | "irradiance" | "length" | "mass" | "none" | "percentage" | "power" | "precipitation" | "precipitation-rate" | "pressure" | "rate" | "ratio" | "signal-level" | "sound-level" | "speed" | "temperature" | "voltage" | "volume", unknown>>>;
@@ -5,15 +5,20 @@ import { DeviceType } from '../device/device-type.js';
5
5
  * Generic stateless event emitter. Installed on a `DeviceType.EventEmitter`
6
6
  * device. Carries the device's EXACT declared event vocabulary verbatim
7
7
  * (NO normalization). Two shapes:
8
- * - structured source (HA `event.*` entity) → `eventTypes` is the fixed
9
- * declared vocabulary (e.g. ['press_short','press_long',...]).
10
- * - generic/legacy source (HA bus events, e.g. zha_event) → `eventTypes`
8
+ * - structured source (HA `event.*` entity) → `vocabulary` is the fixed
9
+ * declared set (e.g. press_short, press_long, …).
10
+ * - generic/legacy source (HA bus events, e.g. zha_event) → `vocabulary`
11
11
  * is [] (open) and `lastEvent.data` carries the complex payload.
12
+ * `vocabulary` (D1044) names each event for a person and types it for a
13
+ * rule; `eventTypes` is its list of native tokens, kept for older readers.
14
+ * A fire names the part of the device it came from in `sourceId` when the
15
+ * vocabulary declares sources (a remote's buttons).
12
16
  * `seq` is monotonic so two identical events still produce distinct slice writes.
13
17
  */
14
18
  export declare const EventFireSchema: z.ZodObject<{
15
19
  deviceId: z.ZodNumber;
16
20
  eventType: z.ZodString;
21
+ sourceId: z.ZodOptional<z.ZodString>;
17
22
  data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
18
23
  timestamp: z.ZodNumber;
19
24
  seq: z.ZodNumber;
@@ -21,9 +26,39 @@ export declare const EventFireSchema: z.ZodObject<{
21
26
  export type EventFire = z.infer<typeof EventFireSchema>;
22
27
  export declare const EventEmitterStatusSchema: z.ZodObject<{
23
28
  eventTypes: z.ZodArray<z.ZodString>;
29
+ vocabulary: z.ZodDefault<z.ZodArray<z.ZodObject<{
30
+ id: z.ZodString;
31
+ source: z.ZodOptional<z.ZodObject<{
32
+ id: z.ZodString;
33
+ label: z.ZodString;
34
+ }, z.core.$strip>>;
35
+ label: z.ZodString;
36
+ description: z.ZodOptional<z.ZodString>;
37
+ kind: z.ZodOptional<z.ZodEnum<{
38
+ "double-press": "double-press";
39
+ "long-press": "long-press";
40
+ "long-press-start": "long-press-start";
41
+ other: "other";
42
+ press: "press";
43
+ release: "release";
44
+ repeat: "repeat";
45
+ }>>;
46
+ payload: z.ZodOptional<z.ZodArray<z.ZodObject<{
47
+ path: z.ZodString;
48
+ kind: z.ZodEnum<{
49
+ boolean: "boolean";
50
+ enum: "enum";
51
+ number: "number";
52
+ string: "string";
53
+ }>;
54
+ enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
55
+ label: z.ZodOptional<z.ZodString>;
56
+ }, z.core.$strip>>>;
57
+ }, z.core.$strip>>>;
24
58
  lastEvent: z.ZodNullable<z.ZodObject<{
25
59
  deviceId: z.ZodNumber;
26
60
  eventType: z.ZodString;
61
+ sourceId: z.ZodOptional<z.ZodString>;
27
62
  data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
28
63
  timestamp: z.ZodNumber;
29
64
  seq: z.ZodNumber;
@@ -43,6 +78,7 @@ export declare const eventEmitterCapability: {
43
78
  readonly data: z.ZodObject<{
44
79
  deviceId: z.ZodNumber;
45
80
  eventType: z.ZodString;
81
+ sourceId: z.ZodOptional<z.ZodString>;
46
82
  data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
47
83
  timestamp: z.ZodNumber;
48
84
  seq: z.ZodNumber;
@@ -52,9 +88,39 @@ export declare const eventEmitterCapability: {
52
88
  readonly status: {
53
89
  readonly schema: z.ZodObject<{
54
90
  eventTypes: z.ZodArray<z.ZodString>;
91
+ vocabulary: z.ZodDefault<z.ZodArray<z.ZodObject<{
92
+ id: z.ZodString;
93
+ source: z.ZodOptional<z.ZodObject<{
94
+ id: z.ZodString;
95
+ label: z.ZodString;
96
+ }, z.core.$strip>>;
97
+ label: z.ZodString;
98
+ description: z.ZodOptional<z.ZodString>;
99
+ kind: z.ZodOptional<z.ZodEnum<{
100
+ "double-press": "double-press";
101
+ "long-press": "long-press";
102
+ "long-press-start": "long-press-start";
103
+ other: "other";
104
+ press: "press";
105
+ release: "release";
106
+ repeat: "repeat";
107
+ }>>;
108
+ payload: z.ZodOptional<z.ZodArray<z.ZodObject<{
109
+ path: z.ZodString;
110
+ kind: z.ZodEnum<{
111
+ boolean: "boolean";
112
+ enum: "enum";
113
+ number: "number";
114
+ string: "string";
115
+ }>;
116
+ enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
117
+ label: z.ZodOptional<z.ZodString>;
118
+ }, z.core.$strip>>>;
119
+ }, z.core.$strip>>>;
55
120
  lastEvent: z.ZodNullable<z.ZodObject<{
56
121
  deviceId: z.ZodNumber;
57
122
  eventType: z.ZodString;
123
+ sourceId: z.ZodOptional<z.ZodString>;
58
124
  data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
59
125
  timestamp: z.ZodNumber;
60
126
  seq: z.ZodNumber;
@@ -65,9 +131,39 @@ export declare const eventEmitterCapability: {
65
131
  };
66
132
  readonly runtimeState: z.ZodObject<{
67
133
  eventTypes: z.ZodArray<z.ZodString>;
134
+ vocabulary: z.ZodDefault<z.ZodArray<z.ZodObject<{
135
+ id: z.ZodString;
136
+ source: z.ZodOptional<z.ZodObject<{
137
+ id: z.ZodString;
138
+ label: z.ZodString;
139
+ }, z.core.$strip>>;
140
+ label: z.ZodString;
141
+ description: z.ZodOptional<z.ZodString>;
142
+ kind: z.ZodOptional<z.ZodEnum<{
143
+ "double-press": "double-press";
144
+ "long-press": "long-press";
145
+ "long-press-start": "long-press-start";
146
+ other: "other";
147
+ press: "press";
148
+ release: "release";
149
+ repeat: "repeat";
150
+ }>>;
151
+ payload: z.ZodOptional<z.ZodArray<z.ZodObject<{
152
+ path: z.ZodString;
153
+ kind: z.ZodEnum<{
154
+ boolean: "boolean";
155
+ enum: "enum";
156
+ number: "number";
157
+ string: "string";
158
+ }>;
159
+ enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
160
+ label: z.ZodOptional<z.ZodString>;
161
+ }, z.core.$strip>>>;
162
+ }, z.core.$strip>>>;
68
163
  lastEvent: z.ZodNullable<z.ZodObject<{
69
164
  deviceId: z.ZodNumber;
70
165
  eventType: z.ZodString;
166
+ sourceId: z.ZodOptional<z.ZodString>;
71
167
  data: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
72
168
  timestamp: z.ZodNumber;
73
169
  seq: z.ZodNumber;
@@ -0,0 +1,99 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * The declared vocabulary of an `event-emitter` device (D1044): what the
4
+ * device can fire, named for a person and typed for a rule.
5
+ *
6
+ * `id` is the native token, verbatim. `kind` is the meaning shared by every
7
+ * integration, so "any long press" can be asked without knowing a vendor's
8
+ * token. A device with several buttons declares one entry per button and
9
+ * token: an entry is identified by its token AND its source.
10
+ */
11
+ /** The cross-integration meaning of an event. */
12
+ export declare const EVENT_VOCABULARY_KINDS: readonly ['press', 'long-press', 'long-press-start', 'release', 'repeat', 'double-press', 'other'];
13
+ export declare const EventVocabularyKindSchema: z.ZodEnum<{
14
+ "double-press": "double-press";
15
+ "long-press": "long-press";
16
+ "long-press-start": "long-press-start";
17
+ other: "other";
18
+ press: "press";
19
+ release: "release";
20
+ repeat: "repeat";
21
+ }>;
22
+ export type EventVocabularyKind = z.infer<typeof EventVocabularyKindSchema>;
23
+ /** The part of the device an event comes from: a button, a channel. */
24
+ export declare const EventVocabularySourceSchema: z.ZodObject<{
25
+ id: z.ZodString;
26
+ label: z.ZodString;
27
+ }, z.core.$strip>;
28
+ export type EventVocabularySource = z.infer<typeof EventVocabularySourceSchema>;
29
+ /** One scalar field of an event's `data`, by dotted path. */
30
+ export declare const EventVocabularyFieldSchema: z.ZodObject<{
31
+ path: z.ZodString;
32
+ kind: z.ZodEnum<{
33
+ boolean: "boolean";
34
+ enum: "enum";
35
+ number: "number";
36
+ string: "string";
37
+ }>;
38
+ enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
39
+ label: z.ZodOptional<z.ZodString>;
40
+ }, z.core.$strip>;
41
+ export type EventVocabularyField = z.infer<typeof EventVocabularyFieldSchema>;
42
+ export declare const EventVocabularyEntrySchema: z.ZodObject<{
43
+ id: z.ZodString;
44
+ source: z.ZodOptional<z.ZodObject<{
45
+ id: z.ZodString;
46
+ label: z.ZodString;
47
+ }, z.core.$strip>>;
48
+ label: z.ZodString;
49
+ description: z.ZodOptional<z.ZodString>;
50
+ kind: z.ZodOptional<z.ZodEnum<{
51
+ "double-press": "double-press";
52
+ "long-press": "long-press";
53
+ "long-press-start": "long-press-start";
54
+ other: "other";
55
+ press: "press";
56
+ release: "release";
57
+ repeat: "repeat";
58
+ }>>;
59
+ payload: z.ZodOptional<z.ZodArray<z.ZodObject<{
60
+ path: z.ZodString;
61
+ kind: z.ZodEnum<{
62
+ boolean: "boolean";
63
+ enum: "enum";
64
+ number: "number";
65
+ string: "string";
66
+ }>;
67
+ enumValues: z.ZodOptional<z.ZodArray<z.ZodString>>;
68
+ label: z.ZodOptional<z.ZodString>;
69
+ }, z.core.$strip>>>;
70
+ }, z.core.$strip>;
71
+ export type EventVocabularyEntry = z.infer<typeof EventVocabularyEntrySchema>;
72
+ /**
73
+ * A status as a reader may meet it. `vocabulary` is absent on a status
74
+ * written by a provider older than the field.
75
+ */
76
+ export interface EventVocabularyCarrier {
77
+ readonly eventTypes: readonly string[];
78
+ readonly vocabulary?: readonly EventVocabularyEntry[];
79
+ }
80
+ /**
81
+ * The vocabulary of a source that declares tokens and nothing else: one
82
+ * entry per token, labelled with the token itself.
83
+ */
84
+ export declare function plainEventVocabulary(eventTypes: readonly string[]): EventVocabularyEntry[];
85
+ /**
86
+ * The vocabulary of a source that declares tokens only, read by convention:
87
+ * a readable label, and the shared kind when the token is one many
88
+ * integrations use for a button. The token itself is kept verbatim.
89
+ */
90
+ export declare function conventionalEventVocabulary(eventTypes: readonly string[]): EventVocabularyEntry[];
91
+ /** The native tokens of a vocabulary, each once, in declaration order. */
92
+ export declare function eventTypesOfVocabulary(vocabulary: readonly EventVocabularyEntry[]): string[];
93
+ /**
94
+ * The vocabulary to show and match against. A status with none declared
95
+ * answers with its plain tokens, so an older provider is still usable.
96
+ */
97
+ export declare function readEventVocabulary(status: EventVocabularyCarrier): readonly EventVocabularyEntry[];
98
+ /** The entry a fire belongs to: same token, same source (or both without one). */
99
+ export declare function findVocabularyEntry(vocabulary: readonly EventVocabularyEntry[], eventType: string, sourceId?: string): EventVocabularyEntry | undefined;
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { type InferProvider } from './capability-definition.js';
3
+ import type { ScalarCustomizeTarget } from './customize-spec.js';
3
4
  import { DeviceType } from '../device/device-type.js';
4
5
  /**
5
6
  * Fan-control cap. Models HA `fan.*` entity-specific surfaces:
@@ -18,12 +19,140 @@ import { DeviceType } from '../device/device-type.js';
18
19
  * - `FanPreset` — preset selector
19
20
  * - `FanDirection` — direction toggle (ceiling fans)
20
21
  * - `FanOscillating` — oscillation toggle
22
+ *
23
+ * Per-axis oscillation (`oscillationAxes`, `setOscillationAxis`, D1034): an air
24
+ * circulator sweeps horizontally and vertically, each axis with its own
25
+ * switch, fixed angle, sweep bounds and limits. A provider may report them
26
+ * natively; otherwise the OPERATOR links sibling devices to each field in
27
+ * Customize (a `replace` over the fields listed in `overridable` — nothing is
28
+ * linked or inferred by itself), and a write to a linked field is forwarded to
29
+ * its source. `oscillating` stays the single summary flag: when axes exist it
30
+ * means "any axis oscillates" (`anyAxisOscillating`).
21
31
  */
22
32
  export declare const FanDirectionSchema: z.ZodEnum<{
23
33
  forward: "forward";
24
34
  reverse: "reverse";
25
35
  }>;
26
36
  export type FanDirection = z.infer<typeof FanDirectionSchema>;
37
+ export declare const FAN_OSCILLATION_AXES: readonly ['horizontal', 'vertical'];
38
+ export declare const FanOscillationAxisNameSchema: z.ZodEnum<{
39
+ horizontal: "horizontal";
40
+ vertical: "vertical";
41
+ }>;
42
+ export type FanOscillationAxisName = z.infer<typeof FanOscillationAxisNameSchema>;
43
+ /** The fields of one axis a caller may set. */
44
+ export declare const FAN_OSCILLATION_AXIS_SETTABLE: readonly ['oscillating', 'angle', 'sweepFrom', 'sweepTo'];
45
+ export declare const FanOscillationAxisFieldSchema: z.ZodEnum<{
46
+ angle: "angle";
47
+ oscillating: "oscillating";
48
+ sweepFrom: "sweepFrom";
49
+ sweepTo: "sweepTo";
50
+ }>;
51
+ export type FanOscillationAxisField = z.infer<typeof FanOscillationAxisFieldSchema>;
52
+ /** The limits of one axis, read from the source that serves its angle. */
53
+ export declare const FAN_OSCILLATION_AXIS_LIMITS: readonly ['min', 'max', 'step'];
54
+ export type FanOscillationAxisLimit = (typeof FAN_OSCILLATION_AXIS_LIMITS)[number];
55
+ /**
56
+ * One oscillation axis. Every reading the device has not reported is `null`,
57
+ * never `0` (D393): `0°` is a real position. Each leaf defaults to `null`, so
58
+ * a slice that names only the leaves it knows (a Customize link of one field)
59
+ * is still a whole axis.
60
+ */
61
+ export declare const FanOscillationAxisSchema: z.ZodObject<{
62
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
63
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
64
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
65
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
66
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
67
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
68
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
69
+ }, z.core.$strip>;
70
+ export type FanOscillationAxis = z.infer<typeof FanOscillationAxisSchema>;
71
+ /** Both axes; an axis the device does not have is `null`. */
72
+ export declare const FanOscillationAxesSchema: z.ZodObject<{
73
+ horizontal: z.ZodDefault<z.ZodNullable<z.ZodObject<{
74
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
75
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
76
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
77
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
78
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
79
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
80
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
81
+ }, z.core.$strip>>>;
82
+ vertical: z.ZodDefault<z.ZodNullable<z.ZodObject<{
83
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
84
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
85
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
86
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
87
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
88
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
89
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
90
+ }, z.core.$strip>>>;
91
+ }, z.core.$strip>;
92
+ export type FanOscillationAxes = z.infer<typeof FanOscillationAxesSchema>;
93
+ export declare const FAN_OSCILLATION_AXIS_REFUSALS: readonly [
94
+ /** No field to set was given. */
95
+ 'nothing-to-set',
96
+ /** The field is neither linked in Customize nor served by the native provider. */
97
+ 'axis-not-linked',
98
+ /** An angle lies outside the axis limits. */
99
+ 'out-of-range',
100
+ /** The linked source device no longer exists. */
101
+ 'source-gone',
102
+ /** The linked source could not be resolved (the device index did not answer). */
103
+ 'source-unknown',
104
+ /** The linked source (or the native provider) rejected the call. */
105
+ 'source-call-failed'];
106
+ export declare const FanOscillationAxisRefusalSchema: z.ZodEnum<{
107
+ "axis-not-linked": "axis-not-linked";
108
+ "nothing-to-set": "nothing-to-set";
109
+ "out-of-range": "out-of-range";
110
+ "source-call-failed": "source-call-failed";
111
+ "source-gone": "source-gone";
112
+ "source-unknown": "source-unknown";
113
+ }>;
114
+ export type FanOscillationAxisRefusal = z.infer<typeof FanOscillationAxisRefusalSchema>;
115
+ export declare const FanOscillationAxisResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
116
+ status: z.ZodLiteral<"applied">;
117
+ }, z.core.$strip>, z.ZodObject<{
118
+ status: z.ZodLiteral<"refused">;
119
+ reason: z.ZodEnum<{
120
+ "axis-not-linked": "axis-not-linked";
121
+ "nothing-to-set": "nothing-to-set";
122
+ "out-of-range": "out-of-range";
123
+ "source-call-failed": "source-call-failed";
124
+ "source-gone": "source-gone";
125
+ "source-unknown": "source-unknown";
126
+ }>;
127
+ field: z.ZodOptional<z.ZodEnum<{
128
+ angle: "angle";
129
+ oscillating: "oscillating";
130
+ sweepFrom: "sweepFrom";
131
+ sweepTo: "sweepTo";
132
+ }>>;
133
+ detail: z.ZodString;
134
+ applied: z.ZodArray<z.ZodEnum<{
135
+ angle: "angle";
136
+ oscillating: "oscillating";
137
+ sweepFrom: "sweepFrom";
138
+ sweepTo: "sweepTo";
139
+ }>>;
140
+ }, z.core.$strip>], "status">;
141
+ export type FanOscillationAxisResult = z.infer<typeof FanOscillationAxisResultSchema>;
142
+ export declare const SetOscillationAxisInputSchema: z.ZodObject<{
143
+ deviceId: z.ZodNumber;
144
+ axis: z.ZodEnum<{
145
+ horizontal: "horizontal";
146
+ vertical: "vertical";
147
+ }>;
148
+ oscillating: z.ZodOptional<z.ZodBoolean>;
149
+ angle: z.ZodOptional<z.ZodNumber>;
150
+ sweepFrom: z.ZodOptional<z.ZodNumber>;
151
+ sweepTo: z.ZodOptional<z.ZodNumber>;
152
+ }, z.core.$strip>;
153
+ export type SetOscillationAxisInput = z.infer<typeof SetOscillationAxisInputSchema>;
154
+ /** The state path of one axis field: `oscillationAxes.<axis>.<field>`. */
155
+ export declare function fanAxisPath(axis: FanOscillationAxisName, field: FanOscillationAxisField | FanOscillationAxisLimit): string;
27
156
  export declare const FanControlStatusSchema: z.ZodObject<{
28
157
  speed: z.ZodNullable<z.ZodNumber>;
29
158
  percentageStep: z.ZodOptional<z.ZodNumber>;
@@ -34,9 +163,34 @@ export declare const FanControlStatusSchema: z.ZodObject<{
34
163
  reverse: "reverse";
35
164
  }>>;
36
165
  oscillating: z.ZodNullable<z.ZodBoolean>;
166
+ oscillationAxes: z.ZodOptional<z.ZodObject<{
167
+ horizontal: z.ZodDefault<z.ZodNullable<z.ZodObject<{
168
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
169
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
170
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
171
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
172
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
173
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
174
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
175
+ }, z.core.$strip>>>;
176
+ vertical: z.ZodDefault<z.ZodNullable<z.ZodObject<{
177
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
178
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
179
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
180
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
181
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
182
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
183
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
184
+ }, z.core.$strip>>>;
185
+ }, z.core.$strip>>;
37
186
  lastChangedAt: z.ZodNumber;
38
187
  }, z.core.$strip>;
39
188
  export type FanControlStatus = z.infer<typeof FanControlStatusSchema>;
189
+ /**
190
+ * The summary flag: with axes, "any axis oscillates"; without an axis that
191
+ * reports, the device's own `oscillating`.
192
+ */
193
+ export declare function anyAxisOscillating(status: Pick<FanControlStatus, 'oscillating' | 'oscillationAxes'>): boolean | null;
40
194
  export declare const fanControlCapability: {
41
195
  readonly name: 'fan-control';
42
196
  readonly scope: 'device';
@@ -71,6 +225,52 @@ export declare const fanControlCapability: {
71
225
  }, z.core.$strip>, z.ZodVoid, "mutation"> & {
72
226
  readonly providerOptional: true;
73
227
  };
228
+ /**
229
+ * Sets one oscillation axis: its switch, fixed angle and/or sweep bounds.
230
+ * Fields left out are untouched. A field linked in Customize is forwarded
231
+ * to its linked source (D1034); otherwise the native provider serves it;
232
+ * neither → `axis-not-linked`. Ranges are checked against the axis limits
233
+ * before anything is written; writes run in order and stop at the first
234
+ * failure, which the result names.
235
+ */
236
+ readonly setOscillationAxis: import("./capability-definition.js").CapabilityMethodSchema<z.ZodObject<{
237
+ deviceId: z.ZodNumber;
238
+ axis: z.ZodEnum<{
239
+ horizontal: "horizontal";
240
+ vertical: "vertical";
241
+ }>;
242
+ oscillating: z.ZodOptional<z.ZodBoolean>;
243
+ angle: z.ZodOptional<z.ZodNumber>;
244
+ sweepFrom: z.ZodOptional<z.ZodNumber>;
245
+ sweepTo: z.ZodOptional<z.ZodNumber>;
246
+ }, z.core.$strip>, z.ZodDiscriminatedUnion<[z.ZodObject<{
247
+ status: z.ZodLiteral<"applied">;
248
+ }, z.core.$strip>, z.ZodObject<{
249
+ status: z.ZodLiteral<"refused">;
250
+ reason: z.ZodEnum<{
251
+ "axis-not-linked": "axis-not-linked";
252
+ "nothing-to-set": "nothing-to-set";
253
+ "out-of-range": "out-of-range";
254
+ "source-call-failed": "source-call-failed";
255
+ "source-gone": "source-gone";
256
+ "source-unknown": "source-unknown";
257
+ }>;
258
+ field: z.ZodOptional<z.ZodEnum<{
259
+ angle: "angle";
260
+ oscillating: "oscillating";
261
+ sweepFrom: "sweepFrom";
262
+ sweepTo: "sweepTo";
263
+ }>>;
264
+ detail: z.ZodString;
265
+ applied: z.ZodArray<z.ZodEnum<{
266
+ angle: "angle";
267
+ oscillating: "oscillating";
268
+ sweepFrom: "sweepFrom";
269
+ sweepTo: "sweepTo";
270
+ }>>;
271
+ }, z.core.$strip>], "status">, "mutation"> & {
272
+ readonly providerOptional: true;
273
+ };
74
274
  };
75
275
  readonly status: {
76
276
  readonly schema: z.ZodObject<{
@@ -83,6 +283,26 @@ export declare const fanControlCapability: {
83
283
  reverse: "reverse";
84
284
  }>>;
85
285
  oscillating: z.ZodNullable<z.ZodBoolean>;
286
+ oscillationAxes: z.ZodOptional<z.ZodObject<{
287
+ horizontal: z.ZodDefault<z.ZodNullable<z.ZodObject<{
288
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
289
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
290
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
291
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
292
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
293
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
294
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
295
+ }, z.core.$strip>>>;
296
+ vertical: z.ZodDefault<z.ZodNullable<z.ZodObject<{
297
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
298
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
299
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
300
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
301
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
302
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
303
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
304
+ }, z.core.$strip>>>;
305
+ }, z.core.$strip>>;
86
306
  lastChangedAt: z.ZodNumber;
87
307
  }, z.core.$strip>;
88
308
  readonly kind: 'push';
@@ -101,8 +321,36 @@ export declare const fanControlCapability: {
101
321
  reverse: "reverse";
102
322
  }>>;
103
323
  oscillating: z.ZodNullable<z.ZodBoolean>;
324
+ oscillationAxes: z.ZodOptional<z.ZodObject<{
325
+ horizontal: z.ZodDefault<z.ZodNullable<z.ZodObject<{
326
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
327
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
328
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
329
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
330
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
331
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
332
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
333
+ }, z.core.$strip>>>;
334
+ vertical: z.ZodDefault<z.ZodNullable<z.ZodObject<{
335
+ oscillating: z.ZodDefault<z.ZodNullable<z.ZodBoolean>>;
336
+ angle: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
337
+ sweepFrom: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
338
+ sweepTo: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
339
+ min: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
340
+ max: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
341
+ step: z.ZodDefault<z.ZodNullable<z.ZodNumber>>;
342
+ }, z.core.$strip>>>;
343
+ }, z.core.$strip>>;
104
344
  lastChangedAt: z.ZodNumber;
105
345
  }, z.core.$strip>;
346
+ readonly customize: {
347
+ readonly version: 1;
348
+ readonly overridable: {
349
+ path: string;
350
+ by: string;
351
+ }[];
352
+ readonly targets: readonly ScalarCustomizeTarget[];
353
+ };
106
354
  /**
107
355
  * Runtime-state durability: **session** — as `brightness`.
108
356
  *