@camstack/types 1.2.586 → 1.2.588
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 +33 -0
- package/dist/addon.d.ts +2 -0
- package/dist/addon.js +21 -5
- package/dist/addon.mjs +18 -6
- package/dist/capabilities/camera-grid-layout.cap.d.ts +3 -5
- package/dist/capabilities/cap-method-absent.d.ts +19 -0
- package/dist/capabilities/device-manager.cap.d.ts +464 -0
- package/dist/capabilities/hero-layout.cap.d.ts +2 -2
- package/dist/capabilities/index.d.ts +9 -5
- package/dist/capabilities/network-link.cap.d.ts +10 -0
- package/dist/capabilities/power-source.cap.d.ts +20 -0
- package/dist/capabilities/recording-export.cap.d.ts +1 -0
- package/dist/capabilities/siren-duration.d.ts +45 -7
- package/dist/capabilities/siren.cap.d.ts +45 -2
- package/dist/capabilities/switch-settable.d.ts +15 -0
- package/dist/capabilities/switch.cap.d.ts +71 -0
- package/dist/capabilities/terminal-session.cap.d.ts +3 -60
- package/dist/capabilities/videoclips.cap.d.ts +3 -0
- package/dist/capabilities/workload.cap.d.ts +655 -0
- package/dist/client.js +59 -5
- package/dist/client.mjs +59 -5
- package/dist/{composed-stable-id-RvQIEpqg.mjs → composed-stable-id-BBL71oUQ.mjs} +20 -0
- package/dist/{composed-stable-id-C3NfRTj8.js → composed-stable-id-CVbyajE5.js} +20 -0
- package/dist/composition/engine-hosted-blocks.d.ts +131 -0
- package/dist/composition/helpers/index.d.ts +1 -1
- package/dist/composition/helpers/spec.d.ts +56 -2
- package/dist/composition/index.d.ts +1 -0
- package/dist/device/base-device.d.ts +29 -0
- package/dist/device/cap-vocabulary/declaration.d.ts +12 -1
- package/dist/device/cap-vocabulary/index.d.ts +4 -4
- package/dist/device/cap-vocabulary/resolve.d.ts +47 -1
- package/dist/device/cap-vocabulary/types.d.ts +26 -1
- package/dist/device/declare-identifiers.d.ts +58 -0
- package/dist/device/device-control-resolution.d.ts +1 -1
- package/dist/device/device-icon.d.ts +7 -0
- package/dist/device/device-identifiers.d.ts +190 -0
- package/dist/device/device-identity-candidates.d.ts +124 -0
- package/dist/device/device-management.d.ts +10 -0
- package/dist/device/device-type.d.ts +22 -2
- package/dist/device/hero/build-hero-model.d.ts +15 -0
- package/dist/device/hero/hero-fragment.d.ts +11 -0
- package/dist/device/hero/hero-layout.d.ts +1 -0
- package/dist/device/hero/hero-look.d.ts +12 -0
- package/dist/device/hero/hero-model.d.ts +4 -4
- package/dist/device/hero/hero-scene.d.ts +7 -0
- package/dist/device/index.d.ts +7 -1
- package/dist/enums/event-category.d.ts +8 -0
- package/dist/enums.js +1 -1
- package/dist/enums.mjs +1 -1
- package/dist/{event-category-d9kiqCqC.js → event-category-CE_VCE2G.js} +8 -0
- package/dist/{event-category-Dhcd0TRH.mjs → event-category-Hwx_JSCU.mjs} +8 -0
- package/dist/generated/addon-api.d.ts +99 -14
- package/dist/generated/addon-cap-facts.d.ts +1 -1
- package/dist/generated/cap-status-types.d.ts +3 -1
- package/dist/generated/cap-vocabulary.d.ts +1 -1
- package/dist/generated/capability-router-map.d.ts +5 -2
- package/dist/generated/collection-array-methods.d.ts +1 -1
- package/dist/generated/customize-catalog.d.ts +1 -1
- package/dist/generated/device-local-state.d.ts +3 -0
- package/dist/generated/device-proxy.d.ts +4 -1
- package/dist/generated/device-scoped-caps.d.ts +1 -1
- package/dist/generated/history-catalog.d.ts +2 -2
- package/dist/generated/method-access-map.d.ts +1 -1
- package/dist/generated/method-device-selectors.d.ts +2 -2
- package/dist/generated/runtime-state-durability.d.ts +1 -1
- package/dist/generated/system-proxy.d.ts +2 -2
- package/dist/{implemented-methods-C7ScGvEz.js → implemented-methods-ChtdIofW.js} +128 -1
- package/dist/{implemented-methods-C5FMXLGP.mjs → implemented-methods-u7ddjc-_.mjs} +57 -2
- package/dist/index.d.ts +9 -3
- package/dist/index.js +2069 -429
- package/dist/index.mjs +2008 -428
- package/dist/node.js +2 -2
- package/dist/node.mjs +2 -2
- package/dist/{sleep-DwRtgB2i.js → sleep-CsZJsb8n.js} +692 -35
- package/dist/{sleep-Ch7Q7UtE.mjs → sleep-D6Pih0Qt.mjs} +669 -36
- package/package.json +1 -1
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
import { z } from 'zod';
|
|
6
6
|
import { STATISTIC_STATS } from './history-math.js';
|
|
7
7
|
import { type ResetPeriod, type RollingWindow, type StatisticWindow } from './history-window.js';
|
|
8
|
-
import { CompositionSourceRefSchema } from '../source-ref.js';
|
|
8
|
+
import { type CompositionSourceRef, CompositionSourceRefSchema } from '../source-ref.js';
|
|
9
9
|
/** A group may name more members than an expression call (the 16-arg cap). */
|
|
10
10
|
export declare const MAX_HELPER_MEMBERS: number;
|
|
11
11
|
export declare const GROUP_TEMPLATE_IDS: readonly ['temperature', 'humidity', 'pressure', 'illuminance', 'power', 'energy', 'battery', 'numeric', 'motion', 'contact', 'leak', 'smoke', 'occupancy', 'binary', 'switch', 'light', 'fan', 'cover', 'valve', 'lock', 'media-player', 'climate'];
|
|
@@ -98,10 +98,64 @@ export type DerivativeHelperSpec = {
|
|
|
98
98
|
readonly source: HelperMember;
|
|
99
99
|
};
|
|
100
100
|
export declare const DerivativeHelperSpecSchema: z.ZodType<DerivativeHelperSpec>;
|
|
101
|
-
|
|
101
|
+
/** The stream profiles a camera grid can publish. */
|
|
102
|
+
export declare const GRID_PROFILES: readonly ['high', 'mid', 'low'];
|
|
103
|
+
export type GridProfile = (typeof GRID_PROFILES)[number];
|
|
104
|
+
export declare const MAX_GRID_CELLS: number;
|
|
105
|
+
export type GridRect = {
|
|
106
|
+
readonly x: number;
|
|
107
|
+
readonly y: number;
|
|
108
|
+
readonly width: number;
|
|
109
|
+
readonly height: number;
|
|
110
|
+
};
|
|
111
|
+
/** A rectangle in normalized [0,1] coordinates of whatever contains it. */
|
|
112
|
+
export declare const GridRectSchema: z.ZodType<GridRect>;
|
|
113
|
+
/**
|
|
114
|
+
* One grid cell: a source camera (by its addon-facing identity, never a
|
|
115
|
+
* numeric id), the part of its picture taken, and where it lands on the canvas.
|
|
116
|
+
*/
|
|
117
|
+
export type GridCellSpec = {
|
|
118
|
+
readonly source: CompositionSourceRef;
|
|
119
|
+
readonly region: GridRect;
|
|
120
|
+
readonly cell: GridRect;
|
|
121
|
+
};
|
|
122
|
+
export declare const GridCellSpecSchema: z.ZodType<GridCellSpec>;
|
|
123
|
+
/**
|
|
124
|
+
* A camera grid (planning#580). The composer declares its camera
|
|
125
|
+
* (`composed-<blockId>`); the camera-grid engine serves the camera caps on it.
|
|
126
|
+
* No canvas size: it is derived from the cells and the sources.
|
|
127
|
+
*/
|
|
128
|
+
export type GridHelperSpec = {
|
|
129
|
+
readonly kind: 'grid';
|
|
130
|
+
readonly fps: number;
|
|
131
|
+
readonly publishedProfiles: readonly GridProfile[];
|
|
132
|
+
readonly cells: readonly GridCellSpec[];
|
|
133
|
+
};
|
|
134
|
+
export declare const GridHelperSpecSchema: z.ZodType<GridHelperSpec>;
|
|
135
|
+
/** A new grid: no cells yet, 10 fps, publishing the mid and low profiles. */
|
|
136
|
+
export declare const DEFAULT_GRID_FPS: number;
|
|
137
|
+
export declare const DEFAULT_GRID_PROFILES: readonly GridProfile[];
|
|
138
|
+
export declare function newGridHelperSpec(): GridHelperSpec;
|
|
139
|
+
/**
|
|
140
|
+
* A Terminal camera (planning#580): the camera of one Terminal, created on the
|
|
141
|
+
* Terminal page. The composer declares the camera; addon-terminal serves it.
|
|
142
|
+
*/
|
|
143
|
+
export type TerminalHelperSpec = {
|
|
144
|
+
readonly kind: 'terminal';
|
|
145
|
+
readonly terminalId: string;
|
|
146
|
+
};
|
|
147
|
+
export declare const TerminalHelperSpecSchema: z.ZodType<TerminalHelperSpec>;
|
|
148
|
+
export type HelperSpec = GroupHelperSpec | StatisticHelperSpec | IntegralHelperSpec | ThresholdHelperSpec | ArithmeticHelperSpec | ExpressionHelperSpec | DerivativeHelperSpec | GridHelperSpec | TerminalHelperSpec;
|
|
102
149
|
export declare const HelperSpecSchema: z.ZodType<HelperSpec>;
|
|
103
150
|
/** The kinds the composer runs from device history, on a schedule. */
|
|
104
151
|
export type HistoryHelperSpec = StatisticHelperSpec | IntegralHelperSpec | DerivativeHelperSpec;
|
|
105
152
|
export declare function isHistoryHelper(spec: HelperSpec): spec is HistoryHelperSpec;
|
|
106
153
|
/** Every member a helper reads. A group has many; the others have one. */
|
|
107
154
|
export declare function helperMembers(spec: HelperSpec): readonly HelperMember[];
|
|
155
|
+
/** The kinds whose camera an engine serves on the composer's row (planning#580). */
|
|
156
|
+
export declare const ENGINE_HOSTED_HELPER_KINDS: readonly ['grid', 'terminal'];
|
|
157
|
+
export type EngineHostedHelperKind = (typeof ENGINE_HOSTED_HELPER_KINDS)[number];
|
|
158
|
+
export type EngineHostedHelperSpec = GridHelperSpec | TerminalHelperSpec;
|
|
159
|
+
export declare function isEngineHostedHelper(spec: HelperSpec): spec is EngineHostedHelperSpec;
|
|
160
|
+
/** The devices a helper depends on without reading a field of them: a grid's cell sources. */
|
|
161
|
+
export declare function helperDeviceRefs(spec: HelperSpec): readonly CompositionSourceRef[];
|
|
@@ -6,6 +6,7 @@ export * from './composable-caps.js';
|
|
|
6
6
|
export * from './helpers/index.js';
|
|
7
7
|
export * from './actuator-running.js';
|
|
8
8
|
export * from './composition.js';
|
|
9
|
+
export * from './engine-hosted-blocks.js';
|
|
9
10
|
export * from './composition-events.js';
|
|
10
11
|
export * from './composition-graph.js';
|
|
11
12
|
export * from './composition-items.js';
|
|
@@ -8,12 +8,21 @@ import type { ConfigUISchemaWithValues } from '../interfaces/config-ui.js';
|
|
|
8
8
|
import type { CapabilityDefinition, InferRuntimeState } from '../capabilities/capability-definition.js';
|
|
9
9
|
import { type DeviceLocalState } from '../generated/device-local-state.js';
|
|
10
10
|
import { type SourceInfo } from './source-info.js';
|
|
11
|
+
import { type DeclareIdentifiersOptions, type DeclareIdentifiersResult } from './declare-identifiers.js';
|
|
12
|
+
import type { RawDeviceIdentifiers } from './device-identifiers.js';
|
|
11
13
|
import { type ErrorStatus } from '../capabilities/error.cap.js';
|
|
12
14
|
import type { CustomActionSpec } from '../capabilities/custom-actions.js';
|
|
15
|
+
/**
|
|
16
|
+
* Who writes a device's base slices (`device-status`, `feature-probe`): the
|
|
17
|
+
* device itself, or another process (planning#580).
|
|
18
|
+
*/
|
|
19
|
+
export type DeviceStatusOwnership = 'own' | 'external';
|
|
13
20
|
export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseShape> = z.ZodObject<z.ZodRawShape>> implements IDevice {
|
|
14
21
|
readonly id: number;
|
|
15
22
|
readonly stableId: string;
|
|
16
23
|
readonly type: DeviceType;
|
|
24
|
+
/** True when another process owns the base slices (`options.deviceStatus: 'external'`). */
|
|
25
|
+
private readonly statusIsExternal;
|
|
17
26
|
readonly name: string;
|
|
18
27
|
readonly parentDeviceId: number | null;
|
|
19
28
|
readonly role?: DeviceRole;
|
|
@@ -102,6 +111,14 @@ export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseS
|
|
|
102
111
|
type: DeviceType;
|
|
103
112
|
/** Optional semantic role within parent — see `DeviceRole`. */
|
|
104
113
|
role?: DeviceRole;
|
|
114
|
+
/**
|
|
115
|
+
* `external`: another process serves this row's base slices,
|
|
116
|
+
* `device-status` and `feature-probe` (an engine hosting caps on a row
|
|
117
|
+
* it does not own, planning#580). This device then registers neither
|
|
118
|
+
* native, seeds nothing, and `markOnline` / the default `onProbe` are
|
|
119
|
+
* no-ops — one writer per slice.
|
|
120
|
+
*/
|
|
121
|
+
deviceStatus?: DeviceStatusOwnership;
|
|
105
122
|
});
|
|
106
123
|
private readonly deviceActions;
|
|
107
124
|
/** Declare a device custom action + its typed handler. Idempotent per name. */
|
|
@@ -154,6 +171,18 @@ export declare abstract class BaseDevice<T extends z.ZodObject<z.core.$ZodLooseS
|
|
|
154
171
|
* via the `DeviceSourceInfoChanged` event without polling.
|
|
155
172
|
*/
|
|
156
173
|
protected updateSourceInfo(patch: Partial<SourceInfo>): Promise<void>;
|
|
174
|
+
/**
|
|
175
|
+
* Declare this device's identifiers (D1059): MAC(s), serial, vendor uid,
|
|
176
|
+
* machine uuid, hostname, IP — what a later step matches across integrations.
|
|
177
|
+
* Normalises `raw` (`normaliseIdentifiers`), logs every refused value, and
|
|
178
|
+
* writes the result through `device-manager.setIdentifiers`, which accepts it
|
|
179
|
+
* only from the provider that owns this device. Each kind it carries replaces
|
|
180
|
+
* the stored one and each kind it lacks is removed — except the kinds listed in
|
|
181
|
+
* `options.unread` (reads that FAILED), which keep their stored value. Pass
|
|
182
|
+
* everything read in one call; a call where every kind is unread writes
|
|
183
|
+
* nothing. Best-effort: never throws.
|
|
184
|
+
*/
|
|
185
|
+
protected declareIdentifiers(raw: RawDeviceIdentifiers, options?: DeclareIdentifiersOptions): Promise<DeclareIdentifiersResult>;
|
|
157
186
|
/**
|
|
158
187
|
* Re-publish the device's current `features` array to the persisted
|
|
159
188
|
* meta blob. Drivers call this after a probe finishes when the live
|
|
@@ -24,7 +24,7 @@
|
|
|
24
24
|
* every one of those names against the cap definition, and
|
|
25
25
|
* `check-cap-vocabulary` checks values against the Zod schemas.
|
|
26
26
|
*/
|
|
27
|
-
import type { L10n, LooseVocabEffect, LooseVocabOffer, LooseVocabOverrides, LooseVocabStateTrigger, VocabEffectValue, VocabEventTrigger, VocabIcon } from './types.js';
|
|
27
|
+
import type { LooseVocabActionGate, L10n, LooseVocabEffect, LooseVocabOffer, LooseVocabOverrides, LooseVocabStateTrigger, VocabEffectValue, VocabEventTrigger, VocabIcon } from './types.js';
|
|
28
28
|
/** The operator-supplied keys of a method input (`deviceId` is the target). */
|
|
29
29
|
export type MethodActionArgs<TInput> = TInput extends object ? Omit<TInput, 'deviceId'> : Record<never, never>;
|
|
30
30
|
/** An open arg of a method action, keyed by the method's own input. */
|
|
@@ -43,6 +43,14 @@ export type MethodActionEffect<TKey extends string = string> = {
|
|
|
43
43
|
readonly field: string;
|
|
44
44
|
readonly fromArg: TKey;
|
|
45
45
|
};
|
|
46
|
+
/**
|
|
47
|
+
* When a device is offered an action: a read method of the same cap, and the
|
|
48
|
+
* boolean field of its answer that must not be `false`. Only an ANSWERED
|
|
49
|
+
* `false` withdraws the action (D315) — a provider without the method, a read
|
|
50
|
+
* that failed or is still pending keeps it offered. `switch.on` reads
|
|
51
|
+
* `getOptions().supportsSetState`: a switch that only reports offers no on/off.
|
|
52
|
+
*/
|
|
53
|
+
export type MethodActionGate = LooseVocabActionGate;
|
|
46
54
|
/**
|
|
47
55
|
* One operator-facing action declared on the method it calls. `TInput` is the
|
|
48
56
|
* method's Zod input; the action's `method` is the key the method is declared
|
|
@@ -62,6 +70,8 @@ export interface MethodActionDecl<TInput = Readonly<Record<string, unknown>>> {
|
|
|
62
70
|
readonly openArgs?: readonly MethodActionOpenArg<keyof MethodActionArgs<TInput> & string>[];
|
|
63
71
|
/** The state this action leads to, when it is one. */
|
|
64
72
|
readonly effect?: MethodActionEffect<keyof MethodActionArgs<TInput> & string>;
|
|
73
|
+
/** When the device is offered it at all — absent = always ({@link MethodActionGate}). */
|
|
74
|
+
readonly offeredWhen?: MethodActionGate;
|
|
65
75
|
}
|
|
66
76
|
/** A method action as codegen reads it off a method schema, string-keyed. */
|
|
67
77
|
export interface LooseMethodActionDecl {
|
|
@@ -72,6 +82,7 @@ export interface LooseMethodActionDecl {
|
|
|
72
82
|
readonly args?: Readonly<Record<string, unknown>>;
|
|
73
83
|
readonly openArgs?: readonly MethodActionOpenArg[];
|
|
74
84
|
readonly effect?: LooseVocabEffect;
|
|
85
|
+
readonly offeredWhen?: MethodActionGate;
|
|
75
86
|
}
|
|
76
87
|
/** What a declared cap event is to an automation: a trigger, or an excuse. */
|
|
77
88
|
export type EventVocabularyDecl = {
|
|
@@ -2,14 +2,14 @@
|
|
|
2
2
|
* The cap vocabulary (D920) — what every capability lets an operator DO to a
|
|
3
3
|
* device and WATCH it for, in one cap-keyed map generated from the caps (D1050).
|
|
4
4
|
*/
|
|
5
|
-
export type { ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, } from './resolve.js';
|
|
6
|
-
export { actionsForDevice, deviceOffersActions, renderVocabPhrase, triggersForDevice, } from './resolve.js';
|
|
5
|
+
export type { ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ActionGateAnswer, ActionGateAnswerOf, DynamicOfferAnswer, DynamicOfferAnswerOf, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, } from './resolve.js';
|
|
6
|
+
export { actionGateAnswerFrom, actionOfferedWith, actionsForDevice, deviceOffersActions, offeredActionsWith, renderVocabPhrase, triggersForDevice, } from './resolve.js';
|
|
7
7
|
export type { ActionEffect, IndexedVocabAction, VocabActionRefusal, VocabCall, } from './action-index.js';
|
|
8
8
|
export { actionEffect, allVocabActions, assertDeviceOffers, findVocabAction, VocabActionError, vocabActionIdFor, vocabCall, } from './action-index.js';
|
|
9
9
|
export type { CommandEffect } from './command-catalog.js';
|
|
10
10
|
export { auditedFields, commandEffect, isCommand } from './command-catalog.js';
|
|
11
11
|
export { VOCAB_TEMPLATES } from './templates.js';
|
|
12
|
-
export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapStatusField, CapVocabularyEntry, CapVocabularyMap, DeviceCapVocabulary, DeviceVocabCapName, DynamicOffer, EnumOffer, EnumStateValue, L10n, LooseCapVocabularyEntry, LooseDynamicOffer, LooseVocabAction, LooseVocabEffect, LooseVocabOffer, LooseVocabOpenArg, LooseVocabStateTrigger, NumberOffer, SystemCapVocabulary, SystemVocabCapName, TextOffer, VocabAction, VocabCapName, VocabChoice, VocabEffectFor, VocabEffectValue, VocabEventTrigger, VocabIcon, VocabLocale, VocabOffer, VocabOpenArg, VocabStateTrigger, } from './types.js';
|
|
12
|
+
export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapNestedNumericPath, CapStatusField, CapVocabularyEntry, CapVocabularyMap, DeviceCapVocabulary, DeviceVocabCapName, DynamicOffer, EnumOffer, EnumStateValue, L10n, LooseCapVocabularyEntry, LooseDynamicOffer, LooseVocabAction, LooseVocabActionGate, LooseVocabEffect, LooseVocabOffer, LooseVocabOpenArg, LooseVocabStateTrigger, NumberOffer, SystemCapVocabulary, SystemVocabCapName, TextOffer, VocabAction, VocabCapName, VocabChoice, VocabEffectFor, VocabEffectValue, VocabEventTrigger, VocabIcon, VocabLocale, VocabOffer, VocabOpenArg, VocabStateTrigger, } from './types.js';
|
|
13
13
|
export { CAP_VOCABULARY, CAP_VOCABULARY_BY_NAME } from './vocabulary.js';
|
|
14
|
-
export type { CapVocabularyDecl, DeviceCapVocabularyDecl, EventVocabularyDecl, LooseMethodActionDecl, MethodActionArgs, MethodActionDecl, MethodActionEffect, MethodActionOpenArg, SystemCapVocabularyDecl, } from './declaration.js';
|
|
14
|
+
export type { CapVocabularyDecl, DeviceCapVocabularyDecl, EventVocabularyDecl, LooseMethodActionDecl, MethodActionArgs, MethodActionDecl, MethodActionEffect, MethodActionGate, MethodActionOpenArg, SystemCapVocabularyDecl, } from './declaration.js';
|
|
15
15
|
export { NOT_A_DEVICE } from './system-reasons.js';
|
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
import type { CapabilityMethodAccess } from '../../capabilities/capability-definition.js';
|
|
12
12
|
import type { EventCategory } from '../../enums/event-category.js';
|
|
13
13
|
import type { DeviceBinding, DeviceBindingEntry } from '../device-binding.js';
|
|
14
|
-
import type { L10n, LooseDynamicOffer, LooseVocabOpenArg, VocabIcon, VocabLocale } from './types.js';
|
|
14
|
+
import type { L10n, LooseDynamicOffer, LooseVocabActionGate, LooseVocabOpenArg, VocabIcon, VocabLocale } from './types.js';
|
|
15
15
|
/** A device's caps, however the caller holds them. */
|
|
16
16
|
export type VocabBindingsInput = DeviceBinding | readonly DeviceBindingEntry[] | readonly string[];
|
|
17
17
|
/** One action a device can be made to do — the wire is `{ cap, method, args }`. */
|
|
@@ -28,6 +28,8 @@ export interface ResolvedVocabAction {
|
|
|
28
28
|
readonly openArgs: readonly LooseVocabOpenArg[];
|
|
29
29
|
/** The method's access tier (METHOD_ACCESS_MAP). */
|
|
30
30
|
readonly access: CapabilityMethodAccess;
|
|
31
|
+
/** The read that decides whether a device is offered it at all; null = always. */
|
|
32
|
+
readonly offeredWhen: LooseVocabActionGate | null;
|
|
31
33
|
}
|
|
32
34
|
interface ResolvedTriggerBase {
|
|
33
35
|
readonly id: string;
|
|
@@ -98,6 +100,50 @@ export declare function actionsForDevice(bindings: VocabBindingsInput, deviceTyp
|
|
|
98
100
|
* device search and the command picker share.
|
|
99
101
|
*/
|
|
100
102
|
export declare function deviceOffersActions(bindings: VocabBindingsInput, actionIds: readonly string[], mode?: 'any' | 'all', deviceType?: string): boolean;
|
|
103
|
+
/**
|
|
104
|
+
* What a device answered for the list a `dynamic` offer reads. `failed` and
|
|
105
|
+
* `pending` are unknown, never "none" (D315); only `answered` carries a count.
|
|
106
|
+
*/
|
|
107
|
+
export type DynamicOfferAnswer = {
|
|
108
|
+
readonly kind: 'pending';
|
|
109
|
+
} | {
|
|
110
|
+
readonly kind: 'failed';
|
|
111
|
+
} | {
|
|
112
|
+
readonly kind: 'answered';
|
|
113
|
+
readonly choiceCount: number;
|
|
114
|
+
};
|
|
115
|
+
/** The answer for one dynamic offer of an action of `cap` on the device at hand. */
|
|
116
|
+
export type DynamicOfferAnswerOf = (cap: string, offer: LooseDynamicOffer) => DynamicOfferAnswer;
|
|
117
|
+
/**
|
|
118
|
+
* What a device answered for the read an action's `offeredWhen` names.
|
|
119
|
+
* `failed` and `pending` are unknown, never "closed" (D315).
|
|
120
|
+
*/
|
|
121
|
+
export type ActionGateAnswer = {
|
|
122
|
+
readonly kind: 'pending';
|
|
123
|
+
} | {
|
|
124
|
+
readonly kind: 'failed';
|
|
125
|
+
} | {
|
|
126
|
+
readonly kind: 'answered';
|
|
127
|
+
readonly open: boolean;
|
|
128
|
+
};
|
|
129
|
+
/** The answer for one action gate of `cap` on the device at hand. */
|
|
130
|
+
export type ActionGateAnswerOf = (cap: string, gate: LooseVocabActionGate) => ActionGateAnswer;
|
|
131
|
+
/**
|
|
132
|
+
* A gate's answer from what its read returned: closed only when the answer is
|
|
133
|
+
* an object whose `field` is `false`. A shape that is not an object is not an
|
|
134
|
+
* answer — it reads as `failed` and keeps the action offered.
|
|
135
|
+
*/
|
|
136
|
+
export declare function actionGateAnswerFrom(raw: unknown, gate: LooseVocabActionGate): ActionGateAnswer;
|
|
137
|
+
/**
|
|
138
|
+
* Whether one device is offered an action, given what it answered: withdrawn
|
|
139
|
+
* when its `offeredWhen` read ANSWERED `false` (a switch that only reports has
|
|
140
|
+
* no on/off), or when a dynamic list its arguments read ANSWERED empty (a
|
|
141
|
+
* siren that counts no plays has nothing to sound N times). A read that failed
|
|
142
|
+
* or is pending keeps it offered.
|
|
143
|
+
*/
|
|
144
|
+
export declare function actionOfferedWith(action: Pick<ResolvedVocabAction, 'cap' | 'openArgs' | 'offeredWhen'>, answerOf: DynamicOfferAnswerOf, gateOf?: ActionGateAnswerOf): boolean;
|
|
145
|
+
/** One device's actions, minus those {@link actionOfferedWith} withdraws. */
|
|
146
|
+
export declare function offeredActionsWith<A extends Pick<ResolvedVocabAction, 'cap' | 'openArgs' | 'offeredWhen'>>(actions: readonly A[], answerOf: DynamicOfferAnswerOf, gateOf?: ActionGateAnswerOf): readonly A[];
|
|
101
147
|
/**
|
|
102
148
|
* The triggers a device can be watched for — its state fields, then the bus
|
|
103
149
|
* events it emits — phrased for its type and role.
|
|
@@ -69,6 +69,19 @@ type StatusOf<C extends VocabCapName> = CapDef<C> extends {
|
|
|
69
69
|
} ? z.output<R> : never;
|
|
70
70
|
/** A top-level status field of cap `C`. */
|
|
71
71
|
export type CapStatusField<C extends VocabCapName> = [StatusOf<C>] extends [never] ? never : keyof StatusOf<C> & string;
|
|
72
|
+
/** The keys of `T` whose value is a number (nullable / optional allowed). */
|
|
73
|
+
type NumericKeysOf<T> = {
|
|
74
|
+
[K in keyof T & string]-?: NonNullable<T[K]> extends number ? K : never;
|
|
75
|
+
}[keyof T & string];
|
|
76
|
+
/**
|
|
77
|
+
* A number one object below the top of cap `C`'s status, by its dotted path
|
|
78
|
+
* (`resources.cpuPercent`). The rule runtime reads dotted paths (`readField`,
|
|
79
|
+
* the condition mirror) and the unit resolver finds their quantity, so a
|
|
80
|
+
* reading grouped under an object is a threshold trigger like a top-level one.
|
|
81
|
+
*/
|
|
82
|
+
export type CapNestedNumericPath<C extends VocabCapName> = [StatusOf<C>] extends [never] ? never : {
|
|
83
|
+
[K in keyof StatusOf<C> & string]-?: NonNullable<StatusOf<C>[K]> extends readonly unknown[] ? never : NonNullable<StatusOf<C>[K]> extends object ? `${K}.${NumericKeysOf<NonNullable<StatusOf<C>[K]>>}` : never;
|
|
84
|
+
}[keyof StatusOf<C> & string];
|
|
72
85
|
/** An event name declared by cap `C`. */
|
|
73
86
|
export type CapEventName<C extends VocabCapName> = CapDef<C> extends {
|
|
74
87
|
readonly events: infer E;
|
|
@@ -203,6 +216,11 @@ export interface VocabActionFor<C extends VocabCapName, M extends CapMethodName<
|
|
|
203
216
|
readonly openArgs?: readonly VocabOpenArg<C, ActionArgKey<C, M>>[];
|
|
204
217
|
/** The state this action leads to, when it is one (see {@link VocabEffectFor}). */
|
|
205
218
|
readonly effect?: VocabEffectFor<C, M>;
|
|
219
|
+
/** When a device is offered it at all: a read of this cap answering `false` at `field` withdraws it. */
|
|
220
|
+
readonly offeredWhen?: {
|
|
221
|
+
readonly method: CapMethodName<C>;
|
|
222
|
+
readonly field: string;
|
|
223
|
+
};
|
|
206
224
|
}
|
|
207
225
|
/** Any action of cap `C`, discriminated by `method`. */
|
|
208
226
|
export type VocabAction<C extends VocabCapName> = {
|
|
@@ -221,7 +239,8 @@ export interface BooleanStateTrigger<C extends VocabCapName> {
|
|
|
221
239
|
/** A number: rises above / falls below / changes by, with a unit. */
|
|
222
240
|
export interface NumericStateTrigger<C extends VocabCapName> {
|
|
223
241
|
readonly kind: 'numeric';
|
|
224
|
-
|
|
242
|
+
/** A top-level field, or a number nested one object down ({@link CapNestedNumericPath}). */
|
|
243
|
+
readonly field: CapStatusField<C> | CapNestedNumericPath<C>;
|
|
225
244
|
/** The quantity WITH its article, as it reads in a sentence ("the temperature" / "la temperatura"). */
|
|
226
245
|
readonly quantity: L10n;
|
|
227
246
|
readonly label: L10n;
|
|
@@ -397,6 +416,12 @@ export interface LooseVocabAction {
|
|
|
397
416
|
readonly args?: Readonly<Record<string, unknown>>;
|
|
398
417
|
readonly openArgs?: readonly LooseVocabOpenArg[];
|
|
399
418
|
readonly effect?: LooseVocabEffect;
|
|
419
|
+
readonly offeredWhen?: LooseVocabActionGate;
|
|
420
|
+
}
|
|
421
|
+
/** When a device is offered an action, string-keyed (`MethodActionGate`). */
|
|
422
|
+
export interface LooseVocabActionGate {
|
|
423
|
+
readonly method: string;
|
|
424
|
+
readonly field: string;
|
|
400
425
|
}
|
|
401
426
|
/** A boolean state trigger, string-keyed. */
|
|
402
427
|
export interface LooseBooleanStateTrigger {
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The provider side of `device-manager.setIdentifiers` (D1059): normalise what a
|
|
3
|
+
* driver read, log what was refused, send the declaration. `BaseDevice.
|
|
4
|
+
* declareIdentifiers` calls it for a device; a provider module that holds only a
|
|
5
|
+
* device id (a metadata populator) calls it directly with `ctx.api`.
|
|
6
|
+
*
|
|
7
|
+
* Best-effort like every other device-meta write from a driver: a failure is
|
|
8
|
+
* logged with `tags: { deviceId }` and answered as an outcome, never thrown, so a
|
|
9
|
+
* device boot never fails on it.
|
|
10
|
+
*/
|
|
11
|
+
import type { IScopedLogger } from '../interfaces/logging.js';
|
|
12
|
+
import { type DeviceIdentifierKey, type DeviceIdentifiers, type NormaliseIdentifiersOptions, type RawDeviceIdentifiers } from './device-identifiers.js';
|
|
13
|
+
/** The input `device-manager.setIdentifiers` takes. */
|
|
14
|
+
export interface SetIdentifiersInput {
|
|
15
|
+
readonly deviceId: number;
|
|
16
|
+
readonly identifiers: DeviceIdentifiers | null;
|
|
17
|
+
/** Kinds whose read FAILED this time: the stored value is kept. */
|
|
18
|
+
readonly unread?: readonly DeviceIdentifierKey[];
|
|
19
|
+
}
|
|
20
|
+
/** The slice of the generated `ctx.api.deviceManager.setIdentifiers` this helper uses. */
|
|
21
|
+
export interface IdentifiersWriter {
|
|
22
|
+
mutate(input: SetIdentifiersInput): Promise<unknown>;
|
|
23
|
+
}
|
|
24
|
+
export interface DeclareIdentifiersDeps {
|
|
25
|
+
readonly deviceId: number;
|
|
26
|
+
readonly logger: IScopedLogger;
|
|
27
|
+
/** `ctx.api.deviceManager?.setIdentifiers`; absent when the device-manager is not reachable. */
|
|
28
|
+
readonly writer: IdentifiersWriter | undefined;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* - `declared` — written (or already equal to what is stored);
|
|
32
|
+
* - `nothing-to-declare` — every kind is `unread`; NOTHING is written, so a probe
|
|
33
|
+
* that read nothing never erases an earlier declaration. A declaration that
|
|
34
|
+
* carries no value but READ some kinds is still sent: those kinds were read and
|
|
35
|
+
* found absent, and are removed;
|
|
36
|
+
* - `unavailable` — no device-manager to write to;
|
|
37
|
+
* - `failed` — the write was refused or threw (logged).
|
|
38
|
+
*/
|
|
39
|
+
export type DeclareIdentifiersOutcome = 'declared' | 'nothing-to-declare' | 'unavailable' | 'failed';
|
|
40
|
+
export interface DeclareIdentifiersResult {
|
|
41
|
+
readonly outcome: DeclareIdentifiersOutcome;
|
|
42
|
+
readonly identifiers: DeviceIdentifiers;
|
|
43
|
+
}
|
|
44
|
+
export interface DeclareIdentifiersOptions extends NormaliseIdentifiersOptions {
|
|
45
|
+
/**
|
|
46
|
+
* Kinds the provider TRIED to read and could not (a probe threw, a session has
|
|
47
|
+
* not answered yet). Their stored values are kept; every other kind is replaced
|
|
48
|
+
* by this declaration, and a kind absent from it is removed. Never list a kind
|
|
49
|
+
* that was read and found absent — that is what removes a stale value.
|
|
50
|
+
*/
|
|
51
|
+
readonly unread?: readonly DeviceIdentifierKey[];
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Normalise `raw` and declare it: every kind it carries replaces the stored one,
|
|
55
|
+
* every kind it lacks is removed, except the kinds in `options.unread` (a failed
|
|
56
|
+
* read keeps what was stored) — pass everything the provider read in one call.
|
|
57
|
+
*/
|
|
58
|
+
export declare function declareDeviceIdentifiers(deps: DeclareIdentifiersDeps, raw: RawDeviceIdentifiers, options?: DeclareIdentifiersOptions): Promise<DeclareIdentifiersResult>;
|
|
@@ -5,7 +5,7 @@ import { DeviceType } from './device-type.js';
|
|
|
5
5
|
* kind can back several device types (`'switch'` ← Switch + Siren, `'sensor'`
|
|
6
6
|
* ← Sensor + Presence, `'dummy'` ← every placeholder/non-controllable type).
|
|
7
7
|
*/
|
|
8
|
-
export type DeviceControlKind = 'cover' | 'valve' | 'humidifier' | 'water-heater' | 'switch' | 'light' | 'fan' | 'sensor' | 'thermostat' | 'climate' | 'button' | 'update' | 'lock' | 'media-player' | 'alarm' | 'control' | 'weather' | 'vacuum' | 'lawn-mower' | 'image' | 'pet-feeder' | 'pet-fountain' | 'heater' | 'dishwasher' | 'appliance' | 'script' | 'automation' | 'energy-system' | 'dummy';
|
|
8
|
+
export type DeviceControlKind = 'cover' | 'valve' | 'humidifier' | 'water-heater' | 'switch' | 'light' | 'fan' | 'sensor' | 'thermostat' | 'climate' | 'button' | 'update' | 'lock' | 'media-player' | 'alarm' | 'control' | 'weather' | 'vacuum' | 'lawn-mower' | 'image' | 'pet-feeder' | 'pet-fountain' | 'heater' | 'dishwasher' | 'appliance' | 'script' | 'automation' | 'energy-system' | 'workload' | 'dummy';
|
|
9
9
|
/**
|
|
10
10
|
* Exhaustive `DeviceType` → `DeviceControlKind` map. Omitting a new enum member
|
|
11
11
|
* fails the build here (the single place the type→kind decision is encoded).
|
|
@@ -24,6 +24,7 @@ export declare const DEVICE_TYPE_ICON: {
|
|
|
24
24
|
readonly climate: 'thermometer';
|
|
25
25
|
readonly "heat-pump": 'flame';
|
|
26
26
|
readonly "energy-system": 'solar-panel';
|
|
27
|
+
readonly workload: 'server';
|
|
27
28
|
readonly button: 'circle-dot';
|
|
28
29
|
readonly "event-emitter": 'zap';
|
|
29
30
|
readonly update: 'refresh-cw';
|
|
@@ -78,6 +79,7 @@ export declare const DEVICE_ROLE_ICON: {
|
|
|
78
79
|
readonly "switch-heater": 'flame';
|
|
79
80
|
readonly "switch-fan": 'fan';
|
|
80
81
|
readonly "switch-light": 'lightbulb';
|
|
82
|
+
readonly "poe-port": 'ethernet-port';
|
|
81
83
|
readonly "climate-ac": 'air-vent';
|
|
82
84
|
readonly "climate-thermostat": 'thermometer';
|
|
83
85
|
readonly "climate-floor": 'waves';
|
|
@@ -123,6 +125,11 @@ export declare const DEVICE_ROLE_ICON: {
|
|
|
123
125
|
readonly "email-notifier": 'mail';
|
|
124
126
|
readonly "generic-notifier": 'bell';
|
|
125
127
|
readonly "ir-transmitter": 'radio-tower';
|
|
128
|
+
readonly vm: 'monitor';
|
|
129
|
+
readonly "app-container": 'container';
|
|
130
|
+
readonly lxc: 'box';
|
|
131
|
+
readonly app: 'app-window';
|
|
132
|
+
readonly host: 'server';
|
|
126
133
|
};
|
|
127
134
|
/** Every icon a device can be drawn with — a subset of the catalog the glyph tables must cover. */
|
|
128
135
|
export type DeviceIconKey = (typeof DEVICE_TYPE_ICON)[DeviceType] | (typeof DEVICE_ROLE_ICON)[DeviceRole];
|
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Provider-declared device identifiers (D1059, planning#590).
|
|
3
|
+
*
|
|
4
|
+
* What a device IS, as its owning provider read it from the hardware: the keys a
|
|
5
|
+
* later step matches across integrations to tell that two devices are the same
|
|
6
|
+
* physical object. Separate from `DeviceMetadata` on purpose — metadata is a
|
|
7
|
+
* free-form blob the operator can edit, identifiers are typed, normalised and
|
|
8
|
+
* written ONLY by the provider that owns the device (`device-manager.
|
|
9
|
+
* setIdentifiers`, owner-checked on the transport's caller stamp).
|
|
10
|
+
*
|
|
11
|
+
* | Key | Stored form | Strength |
|
|
12
|
+
* | -------------- | ----------------------------------- | -------- |
|
|
13
|
+
* | `mac` | `aa:bb:cc:dd:ee:ff`, several | strong |
|
|
14
|
+
* | `serial` | `<manufacturer>:<serial>` | strong |
|
|
15
|
+
* | `machine-uuid` | SMBIOS / VM / container uuid | strong |
|
|
16
|
+
* | `vendor-uid` | `<vendor>:<id>` | strong |
|
|
17
|
+
* | `hostname` | lower-case, no domain | weak |
|
|
18
|
+
* | `ip` | IPv4 / IPv6 | weak |
|
|
19
|
+
*
|
|
20
|
+
* Strength is a property of the KEY, derived by {@link identifierStrength} —
|
|
21
|
+
* never stored, so it cannot drift from the table above. A weak key never links
|
|
22
|
+
* two devices on its own.
|
|
23
|
+
*
|
|
24
|
+
* The schema refuses a value that is not in its stored form, so whatever is
|
|
25
|
+
* persisted is already normalised. Build a declaration with
|
|
26
|
+
* {@link normaliseIdentifiers}, which turns the raw values a driver read into
|
|
27
|
+
* that form and names every value it refused.
|
|
28
|
+
*/
|
|
29
|
+
import { z } from 'zod';
|
|
30
|
+
export declare const DEVICE_IDENTIFIER_KEYS: readonly ['mac', 'serial', 'machine-uuid', 'vendor-uid', 'hostname', 'ip'];
|
|
31
|
+
export declare const DeviceIdentifierKeySchema: z.ZodEnum<{
|
|
32
|
+
hostname: "hostname";
|
|
33
|
+
ip: "ip";
|
|
34
|
+
mac: "mac";
|
|
35
|
+
"machine-uuid": "machine-uuid";
|
|
36
|
+
serial: "serial";
|
|
37
|
+
"vendor-uid": "vendor-uid";
|
|
38
|
+
}>;
|
|
39
|
+
export type DeviceIdentifierKey = z.infer<typeof DeviceIdentifierKeySchema>;
|
|
40
|
+
/** `read` — the provider read it from the device; `derived` — computed from something else it read. */
|
|
41
|
+
export declare const DeviceIdentifierOriginSchema: z.ZodEnum<{
|
|
42
|
+
derived: "derived";
|
|
43
|
+
read: "read";
|
|
44
|
+
}>;
|
|
45
|
+
export type DeviceIdentifierOrigin = z.infer<typeof DeviceIdentifierOriginSchema>;
|
|
46
|
+
export type DeviceIdentifierStrength = 'strong' | 'weak';
|
|
47
|
+
export declare const DeviceIdentifierEntrySchema: z.ZodObject<{
|
|
48
|
+
value: z.ZodString;
|
|
49
|
+
origin: z.ZodEnum<{
|
|
50
|
+
derived: "derived";
|
|
51
|
+
read: "read";
|
|
52
|
+
}>;
|
|
53
|
+
readAt: z.ZodNumber;
|
|
54
|
+
}, z.core.$strict>;
|
|
55
|
+
export type DeviceIdentifierEntry = z.infer<typeof DeviceIdentifierEntrySchema>;
|
|
56
|
+
/** The typed declaration. Every key optional; `mac` the only one that holds several. */
|
|
57
|
+
export declare const DeviceIdentifiersSchema: z.ZodObject<{
|
|
58
|
+
mac: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
|
|
59
|
+
value: z.ZodString;
|
|
60
|
+
origin: z.ZodEnum<{
|
|
61
|
+
derived: "derived";
|
|
62
|
+
read: "read";
|
|
63
|
+
}>;
|
|
64
|
+
readAt: z.ZodNumber;
|
|
65
|
+
}, z.core.$strict>>>>;
|
|
66
|
+
serial: z.ZodOptional<z.ZodObject<{
|
|
67
|
+
value: z.ZodString;
|
|
68
|
+
origin: z.ZodEnum<{
|
|
69
|
+
derived: "derived";
|
|
70
|
+
read: "read";
|
|
71
|
+
}>;
|
|
72
|
+
readAt: z.ZodNumber;
|
|
73
|
+
}, z.core.$strict>>;
|
|
74
|
+
'machine-uuid': z.ZodOptional<z.ZodObject<{
|
|
75
|
+
value: z.ZodString;
|
|
76
|
+
origin: z.ZodEnum<{
|
|
77
|
+
derived: "derived";
|
|
78
|
+
read: "read";
|
|
79
|
+
}>;
|
|
80
|
+
readAt: z.ZodNumber;
|
|
81
|
+
}, z.core.$strict>>;
|
|
82
|
+
'vendor-uid': z.ZodOptional<z.ZodObject<{
|
|
83
|
+
value: z.ZodString;
|
|
84
|
+
origin: z.ZodEnum<{
|
|
85
|
+
derived: "derived";
|
|
86
|
+
read: "read";
|
|
87
|
+
}>;
|
|
88
|
+
readAt: z.ZodNumber;
|
|
89
|
+
}, z.core.$strict>>;
|
|
90
|
+
hostname: z.ZodOptional<z.ZodObject<{
|
|
91
|
+
value: z.ZodString;
|
|
92
|
+
origin: z.ZodEnum<{
|
|
93
|
+
derived: "derived";
|
|
94
|
+
read: "read";
|
|
95
|
+
}>;
|
|
96
|
+
readAt: z.ZodNumber;
|
|
97
|
+
}, z.core.$strict>>;
|
|
98
|
+
ip: z.ZodOptional<z.ZodObject<{
|
|
99
|
+
value: z.ZodUnion<readonly [z.ZodIPv4, z.ZodIPv6]>;
|
|
100
|
+
origin: z.ZodEnum<{
|
|
101
|
+
derived: "derived";
|
|
102
|
+
read: "read";
|
|
103
|
+
}>;
|
|
104
|
+
readAt: z.ZodNumber;
|
|
105
|
+
}, z.core.$strict>>;
|
|
106
|
+
}, z.core.$strict>;
|
|
107
|
+
export type DeviceIdentifiers = z.infer<typeof DeviceIdentifiersSchema>;
|
|
108
|
+
/** How much a match on this key says about two devices being the same object. */
|
|
109
|
+
export declare function identifierStrength(key: DeviceIdentifierKey): DeviceIdentifierStrength;
|
|
110
|
+
/** True when the declaration carries no key at all. */
|
|
111
|
+
export declare function isEmptyIdentifiers(identifiers: DeviceIdentifiers): boolean;
|
|
112
|
+
/** A `<manufacturer>:<serial>` pair as the driver read it. */
|
|
113
|
+
export interface RawSerialIdentifier {
|
|
114
|
+
readonly manufacturer: string;
|
|
115
|
+
readonly serial: string;
|
|
116
|
+
}
|
|
117
|
+
/** A `<vendor>:<id>` pair as the driver read it. */
|
|
118
|
+
export interface RawVendorUidIdentifier {
|
|
119
|
+
readonly vendor: string;
|
|
120
|
+
readonly id: string;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* The values a driver read, in whatever spelling the device used. Absent,
|
|
124
|
+
* `null` and blank are all "not known".
|
|
125
|
+
*/
|
|
126
|
+
export interface RawDeviceIdentifiers {
|
|
127
|
+
readonly mac?: string | readonly string[] | null;
|
|
128
|
+
readonly serial?: RawSerialIdentifier | null;
|
|
129
|
+
readonly machineUuid?: string | null;
|
|
130
|
+
readonly vendorUid?: RawVendorUidIdentifier | null;
|
|
131
|
+
readonly hostname?: string | null;
|
|
132
|
+
readonly ip?: string | null;
|
|
133
|
+
/** A connection host as the operator typed it (an address OR a name): it lands
|
|
134
|
+
* on `ip` or `hostname`, whichever it is. Ignored for a key given explicitly. */
|
|
135
|
+
readonly host?: string | null;
|
|
136
|
+
}
|
|
137
|
+
export interface NormaliseIdentifiersOptions {
|
|
138
|
+
/** Epoch ms of the read. Default: now. */
|
|
139
|
+
readonly readAt?: number;
|
|
140
|
+
/** Origin for every key. Default `read`. */
|
|
141
|
+
readonly origin?: DeviceIdentifierOrigin;
|
|
142
|
+
/** Per-key origin, over {@link origin}. */
|
|
143
|
+
readonly originByKey?: Readonly<Partial<Record<DeviceIdentifierKey, DeviceIdentifierOrigin>>>;
|
|
144
|
+
}
|
|
145
|
+
/** One value {@link normaliseIdentifiers} refused, and why — the caller logs it. */
|
|
146
|
+
export interface RejectedIdentifier {
|
|
147
|
+
readonly key: DeviceIdentifierKey;
|
|
148
|
+
readonly value: string;
|
|
149
|
+
readonly reason: string;
|
|
150
|
+
}
|
|
151
|
+
export interface NormalisedIdentifiers {
|
|
152
|
+
readonly identifiers: DeviceIdentifiers;
|
|
153
|
+
readonly rejected: readonly RejectedIdentifier[];
|
|
154
|
+
}
|
|
155
|
+
export interface AcceptedValue {
|
|
156
|
+
readonly ok: true;
|
|
157
|
+
readonly value: string;
|
|
158
|
+
}
|
|
159
|
+
export type NormaliseResult = AcceptedValue | RejectedReason;
|
|
160
|
+
export interface RejectedReason {
|
|
161
|
+
readonly ok: false;
|
|
162
|
+
readonly reason: string;
|
|
163
|
+
}
|
|
164
|
+
/** `AA-BB-CC-DD-EE-FF`, `aabb.ccdd.eeff`, `AABBCCDDEEFF` → `aa:bb:cc:dd:ee:ff`. */
|
|
165
|
+
export declare function normaliseMac(raw: string): NormaliseResult;
|
|
166
|
+
/**
|
|
167
|
+
* Turn what a driver read into a valid {@link DeviceIdentifiers}: MACs lower-case
|
|
168
|
+
* with colons and de-duplicated, a hostname without its domain, an IP validated,
|
|
169
|
+
* a serial prefixed by its manufacturer, a vendor uid by its vendor. A value that
|
|
170
|
+
* cannot be normalised is left out and listed in `rejected` — the caller logs it
|
|
171
|
+
* (with `tags: { deviceId }`), it is never dropped in silence.
|
|
172
|
+
*/
|
|
173
|
+
export declare function normaliseIdentifiers(raw: RawDeviceIdentifiers, options?: NormaliseIdentifiersOptions): NormalisedIdentifiers;
|
|
174
|
+
/**
|
|
175
|
+
* The declaration to store when the owning provider declares `next` over
|
|
176
|
+
* `stored` (D1059).
|
|
177
|
+
*
|
|
178
|
+
* - A kind in `unread` — the provider TRIED to read it and the read failed —
|
|
179
|
+
* keeps its stored entry: a failed read changes nothing (D49).
|
|
180
|
+
* - Every other kind is what `next` says: a kind absent from `next` was read and
|
|
181
|
+
* found absent, so it is removed.
|
|
182
|
+
* - An entry whose value and origin are unchanged keeps its stored `readAt`:
|
|
183
|
+
* `readAt` is when that value was FIRST read, so a provider re-declaring on every
|
|
184
|
+
* boot writes nothing and emits nothing.
|
|
185
|
+
*
|
|
186
|
+
* Returns `null` when nothing is left.
|
|
187
|
+
*/
|
|
188
|
+
export declare function mergeIdentifiers(stored: DeviceIdentifiers | null | undefined, next: DeviceIdentifiers | null, unread?: readonly DeviceIdentifierKey[]): DeviceIdentifiers | null;
|
|
189
|
+
/** True when two declarations hold the same entries, `readAt` included (key order ignored). */
|
|
190
|
+
export declare function sameIdentifiers(a: DeviceIdentifiers | null | undefined, b: DeviceIdentifiers | null | undefined): boolean;
|