@camstack/types 1.2.576 → 1.2.577

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,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.577] - 2026-11-15
11
+
12
+ ### Changed
13
+
14
+ - Capability history declares which fields share a chart (group) and which series a device card trends (primary, priority)
15
+
10
16
  ## [1.2.576] - 2026-11-15
11
17
 
12
18
  ### Changed
@@ -68,11 +68,13 @@ export declare const airQualitySensorCapability: {
68
68
  readonly deadband: 5;
69
69
  };
70
70
  readonly pm25: {
71
+ readonly group: 'particulates';
71
72
  readonly kind: 'gauge';
72
73
  readonly unit: 'µg/m³';
73
74
  readonly deadband: 1;
74
75
  };
75
76
  readonly pm10: {
77
+ readonly group: 'particulates';
76
78
  readonly kind: 'gauge';
77
79
  readonly unit: 'µg/m³';
78
80
  readonly deadband: 1;
@@ -461,6 +461,15 @@ export interface CapabilityHistoryField {
461
461
  */
462
462
  readonly unitFrom?: string;
463
463
  readonly displayName?: string;
464
+ /**
465
+ * Fields of ONE cap that name the same group share a History chart; a field
466
+ * with no group gets a chart of its own. Only closely related GAUGES belong
467
+ * together (the five `powerW` of an energy system), so the members must share
468
+ * a unit dimension. A counter is always its own per-period bar chart and takes
469
+ * no group; neither does a state, nor a field of a keyed `items` array. Judged
470
+ * by `scripts/check-cap-history-declared.ts`.
471
+ */
472
+ readonly group?: string;
464
473
  /** Drop a change smaller than this (ABSOLUTE) — anti-jitter for noisy gauges. */
465
474
  readonly deadband?: number;
466
475
  /**
@@ -523,7 +532,20 @@ export declare function historyItemFieldPath(itemsPath: string, field: string):
523
532
  export type CapabilityHistory = 'none' | {
524
533
  readonly fields: Readonly<Record<string, CapabilityHistoryField>>;
525
534
  readonly items?: CapabilityHistoryItems;
535
+ /**
536
+ * The field a device card trends: a numeric `fields` key. Declared with
537
+ * {@link priority}; the card shows the primary of the ENABLED cap with the
538
+ * highest priority that has data on the device.
539
+ */
540
+ readonly primary?: string;
541
+ /** Higher wins between the caps of one device; required with `primary`. */
542
+ readonly priority?: number;
526
543
  };
544
+ /** A cap's declared card series: a numeric history field and its rank between caps. */
545
+ export interface CapabilityHistoryPrimary {
546
+ readonly field: string;
547
+ readonly priority: number;
548
+ }
527
549
  /** Capture floor (ms) applied to `gauge` / `counter` series when a field states none. */
528
550
  export declare const HISTORY_DEFAULT_MIN_INTERVAL_MS = 10000;
529
551
  /**
@@ -311,8 +311,11 @@ export declare const climateControlCapability: {
311
311
  * History (D850): recorded series. Celsius by contract; setpoints keep every change (`minIntervalMs: 0`).
312
312
  */
313
313
  readonly history: {
314
+ readonly primary: 'currentTemp';
315
+ readonly priority: 70;
314
316
  readonly fields: {
315
317
  readonly currentTemp: {
318
+ readonly group: 'temperature';
316
319
  readonly kind: 'gauge';
317
320
  readonly unit: '°C';
318
321
  readonly deadband: 0.1;
@@ -323,16 +326,19 @@ export declare const climateControlCapability: {
323
326
  readonly deadband: 0.5;
324
327
  };
325
328
  readonly target: {
329
+ readonly group: 'temperature';
326
330
  readonly kind: 'gauge';
327
331
  readonly unit: '°C';
328
332
  readonly minIntervalMs: 0;
329
333
  };
330
334
  readonly targetHigh: {
335
+ readonly group: 'target-range';
331
336
  readonly kind: 'gauge';
332
337
  readonly unit: '°C';
333
338
  readonly minIntervalMs: 0;
334
339
  };
335
340
  readonly targetLow: {
341
+ readonly group: 'target-range';
336
342
  readonly kind: 'gauge';
337
343
  readonly unit: '°C';
338
344
  readonly minIntervalMs: 0;
@@ -200,8 +200,11 @@ export declare const energySystemCapability: {
200
200
  * counters' difference over the day.
201
201
  */
202
202
  readonly history: {
203
+ readonly primary: 'house.powerW';
204
+ readonly priority: 50;
203
205
  readonly fields: {
204
206
  readonly 'solar.powerW': {
207
+ readonly group: 'power-flow';
205
208
  readonly kind: 'gauge';
206
209
  readonly unit: 'W';
207
210
  readonly deadband: 50;
@@ -213,6 +216,7 @@ export declare const energySystemCapability: {
213
216
  readonly displayName: 'Solar energy';
214
217
  };
215
218
  readonly 'grid.powerW': {
219
+ readonly group: 'power-flow';
216
220
  readonly kind: 'gauge';
217
221
  readonly unit: 'W';
218
222
  readonly deadband: 50;
@@ -229,6 +233,7 @@ export declare const energySystemCapability: {
229
233
  readonly displayName: 'Grid export';
230
234
  };
231
235
  readonly 'house.powerW': {
236
+ readonly group: 'power-flow';
232
237
  readonly kind: 'gauge';
233
238
  readonly unit: 'W';
234
239
  readonly deadband: 50;
@@ -240,6 +245,7 @@ export declare const energySystemCapability: {
240
245
  readonly displayName: 'House energy';
241
246
  };
242
247
  readonly 'heatPump.powerW': {
248
+ readonly group: 'power-flow';
243
249
  readonly kind: 'gauge';
244
250
  readonly unit: 'W';
245
251
  readonly deadband: 50;
@@ -263,6 +269,7 @@ export declare const energySystemCapability: {
263
269
  readonly displayName: 'Stored energy';
264
270
  };
265
271
  readonly 'storage.powerW': {
272
+ readonly group: 'power-flow';
266
273
  readonly kind: 'gauge';
267
274
  readonly unit: 'W';
268
275
  readonly deadband: 50;
@@ -442,12 +442,14 @@ export declare const heatPumpStatusCapability: {
442
442
  readonly history: {
443
443
  readonly fields: {
444
444
  readonly 'power.thermalW': {
445
+ readonly group: 'power';
445
446
  readonly kind: 'gauge';
446
447
  readonly unit: 'W';
447
448
  readonly deadband: 50;
448
449
  readonly displayName: 'Thermal power';
449
450
  };
450
451
  readonly 'power.electricalW': {
452
+ readonly group: 'power';
451
453
  readonly kind: 'gauge';
452
454
  readonly unit: 'W';
453
455
  readonly deadband: 50;
@@ -460,12 +462,14 @@ export declare const heatPumpStatusCapability: {
460
462
  readonly displayName: 'Compressor';
461
463
  };
462
464
  readonly 'temperatures.supply': {
465
+ readonly group: 'loop';
463
466
  readonly kind: 'gauge';
464
467
  readonly unit: '°C';
465
468
  readonly deadband: 0.5;
466
469
  readonly displayName: 'Supply';
467
470
  };
468
471
  readonly 'temperatures.return': {
472
+ readonly group: 'loop';
469
473
  readonly kind: 'gauge';
470
474
  readonly unit: '°C';
471
475
  readonly deadband: 0.5;
@@ -43,6 +43,8 @@ export declare const humiditySensorCapability: {
43
43
  * History (D850): recorded series.
44
44
  */
45
45
  readonly history: {
46
+ readonly primary: 'humidity';
47
+ readonly priority: 90;
46
48
  readonly fields: {
47
49
  readonly humidity: {
48
50
  readonly kind: 'gauge';
@@ -36,7 +36,7 @@ export { BrokerGetStateInputSchema, BrokerPublishInputSchema, BrokerRegistryStat
36
36
  export { cameraPipelineConfigCapability, type ICameraPipelineConfigProvider, } from './camera-pipeline-config.cap.js';
37
37
  export { cameraStreamsCapability, type ICameraStreamsProvider, type PickedCamStream, PickedCamStreamSchema, type PickStreamPreferences, PickStreamPreferencesSchema, type PickStreamRequirements, PickStreamRequirementsSchema, type StreamCodec, StreamCodecSchema, } from './camera-streams.cap.js';
38
38
  export { emitsCollectionSelector, extractNestedAddonId, isArrayOutputSchema, isCollectionArrayMethod, isObjectInput, isVoidInput, kebabToCamel, looseSchema, objectInputDeclaresAddonId, objectInputDeclaresRequiredDeviceId, procedureAuthKey, resolveMethodAuth, } from './cap-router-predicates.js';
39
- export type { CapabilityDefinition, CapabilityEventSchema, CapabilityMethodAuth, CapabilityMethodCaller, CapabilityMethodKind, CapabilityMethodOptions, CapabilityMethodSchema, CapabilityMountHint, CapabilityMountKind, CapabilityStatusItemArray, CapabilityStatusKind, CapabilityStatusSchema, CapCaller, DeviceConfigDerivedFormUi, DeviceConfigSpec, DeviceConfigUiSpec, DeviceConfigWidgetUi, DeviceSettingsContribution, InferDeviceProxyCap, InferEvents, InferName, InferNativeProvider, InferProvider, InferRuntimeState, CapabilityHistory, CapabilityHistoryField, CapabilityPowerHint, PowerHintField, PowerHintMethods, PowerHintMode, CapabilityHistoryItems, HistoryUnit, ProviderKind, RuntimeStateDurability, UiContribution, UiContributionKind, UiContributionRemote, } from './capability-definition.js';
39
+ export type { CapabilityDefinition, CapabilityEventSchema, CapabilityMethodAuth, CapabilityMethodCaller, CapabilityMethodKind, CapabilityMethodOptions, CapabilityMethodSchema, CapabilityMountHint, CapabilityMountKind, CapabilityStatusItemArray, CapabilityStatusKind, CapabilityStatusSchema, CapCaller, DeviceConfigDerivedFormUi, DeviceConfigSpec, DeviceConfigUiSpec, DeviceConfigWidgetUi, DeviceSettingsContribution, InferDeviceProxyCap, InferEvents, InferName, InferNativeProvider, InferProvider, InferRuntimeState, CapabilityHistory, CapabilityHistoryField, CapabilityPowerHint, PowerHintField, PowerHintMethods, PowerHintMode, CapabilityHistoryItems, CapabilityHistoryPrimary, HistoryUnit, ProviderKind, RuntimeStateDurability, UiContribution, UiContributionKind, UiContributionRemote, } from './capability-definition.js';
40
40
  export { DEFAULT_RUNTIME_STATE_DURABILITY, HISTORY_DEFAULT_MIN_INTERVAL_MS, HISTORY_UNIT_LABELS, historyItemFieldPath, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, event, expandCapMethods, isDeviceConfigCap, method, optionalMethod, PROVIDER_PIN_FIELD, resolveCapMount, } from './capability-definition.js';
41
41
  export { COMPOSER_RUNNER_ID, type ComposerApplyInput, ComposerApplyInputSchema, type ComposerApplyResult, ComposerApplyResultSchema, type ComposerBlock, ComposerBlockSchema, type ComposerBlockVerdict, ComposerBlockVerdictSchema, type ComposerUnreadableBlock, ComposerUnreadableBlockSchema, composerCapability, type IComposerProvider, type UnreleasedClaim, UnreleasedClaimSchema, } from './composer.cap.js';
42
42
  export { CORE_BLOCK_ADDON_PREFIX, CORE_BLOCKS_ADDON_ID, type CompositionBlockInput, CompositionBlockInputSchema, type CompositionBlockPatch, type CompositionCustomizationRead, CompositionCustomizationReadSchema, type CompositionGetRead, CompositionGetReadSchema, type CompositionListRead, CompositionListReadSchema, type CompositionStateRead, CompositionStateReadSchema, type CompositionView, CompositionViewSchema, type CoreBlock, type CoreBlockCompileInput, CoreBlockCompileInputSchema, type CoreBlockCompileResult, CoreBlockCompileResultSchema, type CoreBlockFiles, CoreBlockFilesSchema, type CoreBlockInput, CoreBlockInputFieldsSchema, CoreBlockInputSchema, type CoreBlockPlacement, CoreBlockPlacementSchema, CoreBlockSchema, type CoreBlockSource, type CoreBlockSourceKind, CoreBlockSourceSchema, type CoreBlockStatus, CoreBlockStatusSchema, coreBlockAddonId, coreBlockComposition, coreBlockIdFromAddonId, coreBlockSourceKind, coreBlocksCapability, DEFAULT_CORE_BLOCK_ENTRY, type ICoreBlocksProvider, normalizeCoreBlockWrite, resolveCoreBlockEntry, resolveCoreBlockFiles, } from './core-blocks.cap.js';
@@ -75,6 +75,8 @@ export declare const powerMeterCapability: {
75
75
  * History (D850): recorded series. Gauges are floored at 30 s; `energy` is the one monotonic meter (counter).
76
76
  */
77
77
  readonly history: {
78
+ readonly primary: 'power';
79
+ readonly priority: 80;
78
80
  readonly fields: {
79
81
  readonly power: {
80
82
  readonly kind: 'gauge';
@@ -497,18 +497,22 @@ export declare const streamParamsCapability: {
497
497
  readonly history: {
498
498
  readonly fields: {
499
499
  readonly 'main.bitrate': {
500
+ readonly group: 'bitrate';
500
501
  readonly kind: 'gauge';
501
502
  readonly unit: 'kbps';
502
503
  };
503
504
  readonly 'main.framerate': {
505
+ readonly group: 'framerate';
504
506
  readonly kind: 'gauge';
505
507
  readonly unit: 'fps';
506
508
  };
507
509
  readonly 'sub.bitrate': {
510
+ readonly group: 'bitrate';
508
511
  readonly kind: 'gauge';
509
512
  readonly unit: 'kbps';
510
513
  };
511
514
  readonly 'sub.framerate': {
515
+ readonly group: 'framerate';
512
516
  readonly kind: 'gauge';
513
517
  readonly unit: 'fps';
514
518
  };
@@ -47,6 +47,8 @@ export declare const temperatureSensorCapability: {
47
47
  * History (D850): recorded series.
48
48
  */
49
49
  readonly history: {
50
+ readonly primary: 'temperature';
51
+ readonly priority: 100;
50
52
  readonly fields: {
51
53
  readonly temperature: {
52
54
  readonly kind: 'gauge';
@@ -97,11 +97,13 @@ export declare const waterHeaterCapability: {
97
97
  readonly history: {
98
98
  readonly fields: {
99
99
  readonly currentTemp: {
100
+ readonly group: 'temperature';
100
101
  readonly kind: 'gauge';
101
102
  readonly unit: '°C';
102
103
  readonly deadband: 0.5;
103
104
  };
104
105
  readonly targetTemp: {
106
+ readonly group: 'temperature';
105
107
  readonly kind: 'gauge';
106
108
  readonly unit: '°C';
107
109
  readonly minIntervalMs: 0;
@@ -122,8 +122,11 @@ export declare const weatherStationCapability: {
122
122
  * levels, so `gauge`; `counter` is for a monotonic meter only.
123
123
  */
124
124
  readonly history: {
125
+ readonly primary: 'temperature';
126
+ readonly priority: 60;
125
127
  readonly fields: {
126
128
  readonly temperature: {
129
+ readonly group: 'temperature';
127
130
  readonly kind: 'gauge';
128
131
  readonly unit: '°C';
129
132
  readonly deadband: 0.1;
@@ -139,16 +142,19 @@ export declare const weatherStationCapability: {
139
142
  readonly deadband: 0.2;
140
143
  };
141
144
  readonly windSpeed: {
145
+ readonly group: 'wind-speed';
142
146
  readonly kind: 'gauge';
143
147
  readonly unit: 'm/s';
144
148
  readonly deadband: 0.2;
145
149
  };
146
150
  readonly windGust: {
151
+ readonly group: 'wind-speed';
147
152
  readonly kind: 'gauge';
148
153
  readonly unit: 'm/s';
149
154
  readonly deadband: 0.2;
150
155
  };
151
156
  readonly windBearing: {
157
+ readonly group: 'wind-bearing';
152
158
  readonly kind: 'gauge';
153
159
  readonly unit: '°';
154
160
  readonly deadband: 5;
@@ -179,11 +185,13 @@ export declare const weatherStationCapability: {
179
185
  readonly deadband: 5;
180
186
  };
181
187
  readonly dewPoint: {
188
+ readonly group: 'temperature';
182
189
  readonly kind: 'gauge';
183
190
  readonly unit: '°C';
184
191
  readonly deadband: 0.1;
185
192
  };
186
193
  readonly feelsLike: {
194
+ readonly group: 'temperature';
187
195
  readonly kind: 'gauge';
188
196
  readonly unit: '°C';
189
197
  readonly deadband: 0.1;
@@ -194,11 +202,13 @@ export declare const weatherStationCapability: {
194
202
  readonly deadband: 0.05;
195
203
  };
196
204
  readonly windGustMax: {
205
+ readonly group: 'wind-speed';
197
206
  readonly kind: 'gauge';
198
207
  readonly unit: 'm/s';
199
208
  readonly deadband: 0.2;
200
209
  };
201
210
  readonly windBearingAvg: {
211
+ readonly group: 'wind-bearing';
202
212
  readonly kind: 'gauge';
203
213
  readonly unit: '°';
204
214
  readonly deadband: 5;
@@ -1,4 +1,4 @@
1
- import type { CapabilityHistoryField, CapabilityHistoryItems } from '../capabilities/capability-definition.js';
1
+ import type { CapabilityHistoryField, CapabilityHistoryItems, CapabilityHistoryPrimary } from '../capabilities/capability-definition.js';
2
2
  /**
3
3
  * Cap history catalog, projected from every `*.cap.ts` `history` block.
4
4
  * 46 caps with series (124 series), 38 caps answered `'none'`.
@@ -11,6 +11,11 @@ export declare const HISTORY_CATALOG: Readonly<Record<string, Readonly<Record<st
11
11
  * the series key is `cap:<capName>.<path>[].<field>`.
12
12
  */
13
13
  export declare const HISTORY_ITEM_CATALOG: Readonly<Record<string, CapabilityHistoryItems>>;
14
+ /**
15
+ * The series a device card trends, per cap (`history.primary` + `history.priority`):
16
+ * 6 caps. The card shows the primary of the enabled cap with the highest priority.
17
+ */
18
+ export declare const HISTORY_PRIMARY: Readonly<Record<string, CapabilityHistoryPrimary>>;
14
19
  /** Caps that declared `history: 'none'`, sorted. */
15
20
  export declare const HISTORY_NONE_CAPS: readonly string[];
16
21
  /** The series specs of `capName`; empty for a `'none'` cap or an unknown one. */
@@ -0,0 +1,10 @@
1
+ /** The history series key of a cap's declared primary field; `null` when it declares none. */
2
+ export declare function primarySeriesKey(cap: string): string | null;
3
+ export interface PickPrimarySeriesInput {
4
+ /** The caps enabled on the device (its hero layout's bindings). A disabled cap is absent. */
5
+ readonly enabledCaps: readonly string[];
6
+ /** Whether the device has points for a series key. */
7
+ readonly hasData: (key: string) => boolean;
8
+ }
9
+ /** The card series of a device: the data-bearing primary of the highest-priority enabled cap. */
10
+ export declare function pickPrimarySeriesKey(input: PickPrimarySeriesInput): string | null;
package/dist/index.d.ts CHANGED
@@ -335,7 +335,9 @@ export { CAP_PROVIDER_KIND_MAP, getCapsByProviderKind, PROVIDER_KIND_CAP_NAMES,
335
335
  export type { RuntimeStatePolicy } from './generated/runtime-state-durability.js';
336
336
  export { isRestoredCap, RESTORED_CAP_NAMES, RUNTIME_STATE_POLICY, runtimeStatePolicyFor, } from './generated/runtime-state-durability.js';
337
337
  export { BucketAccumulator, bucketStartOf, type ClosedHistoryBucket, HISTORY_BUCKET_MS, MAX_REQUEUED_BUCKETS_PER_SERIES, } from './history/bucket-accumulator.js';
338
- export { HISTORY_CATALOG, HISTORY_ITEM_CATALOG, HISTORY_NONE_CAPS, historyFieldsFor, } from './generated/history-catalog.js';
338
+ export { pickPrimarySeriesKey, primarySeriesKey } from './history/primary-series.js';
339
+ export type { PickPrimarySeriesInput } from './history/primary-series.js';
340
+ export { HISTORY_CATALOG, HISTORY_ITEM_CATALOG, HISTORY_PRIMARY, HISTORY_NONE_CAPS, historyFieldsFor, } from './generated/history-catalog.js';
339
341
  export { CAP_CUSTOMIZE_CATALOG } from './generated/customize-catalog.js';
340
342
  export type { CustomizeCatalog, CustomizeCatalogField, CustomizeCatalogSource, CustomizeCatalogTarget, CustomizeCatalogTransform, } from './capabilities/customize-catalog.js';
341
343
  export { CAP_RUNTIME_FIELD_UNITS } from './generated/customize-catalog.js';