@camstack/types 1.2.25 → 1.2.27

package/dist/catalogs/device-state-vocabulary.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Which capability says what a device's STATE is, and how to read it.
+ *
+ * `deviceManager.loadRuntimeState` returns every cap's slice for a device,
+ * keyed by the kebab-case cap name:
+ *
+ *   { 'device-status': { online: true }, switch: { on: true, … } }
+ *
+ * "The state of this device" is not a thing the platform models — a switch has
+ * `on`, a contact has `entryOpen`, an alarm panel has `state`. So the mapping
+ * is a TABLE, declared here, rather than a guess made at read time. An
+ * unmapped cap yields no state, and no state never matches a gate: adding a cap
+ * cannot silently change what an existing rule does.
+ *
+ * ORDER MATTERS. A device usually carries several of these slices (a switch is
+ * also `device-status`), and the first match wins — so the list runs from most
+ * specific to least. `device-status` is deliberately absent: "online" is not a
+ * state a rule should gate on, and having it here would make every device match
+ * the first entry and mask its real one.
+ */
+/** How one capability's slice collapses to a single comparable string. */
+interface StateReader {
+    /** kebab-case cap name, as `loadRuntimeState` keys it. */
+    readonly cap: string;
+    /** Field inside that slice. */
+    readonly field: string;
+    /**
+     * Vocabulary a rule author writes. A boolean field becomes these two words,
+     * in this order — `[whenTrue, whenFalse]`. Absent for a field that is already
+     * a string (the alarm's `state`, the cover's `state`).
+     */
+    readonly booleanWords?: readonly [string, string];
+}
+/**
+ * Most specific first. Extending this list is how a new device kind becomes
+ * gateable; nothing else needs to change.
+ */
+export declare const DEVICE_STATE_READERS: readonly StateReader[];
+/**
+ * Collapse a device's full runtime state to the one string a rule compares
+ * against, or `undefined` when nothing in the table applies.
+ *
+ * `undefined` is the safe answer everywhere: the gate treats it as "does not
+ * match", so a device whose kind we cannot read simply never arms a rule.
+ */
+export declare function readDeviceStateFrom(runtimeState: Readonly<Record<string, unknown>>): string | undefined;
+/**
+ * The states a rule editor can offer for a device, given its runtime state.
+ * Same table, same order — so the picker can never offer a value the gate
+ * would not recognise.
+ */
+export declare function stateVocabularyFor(runtimeState: Readonly<Record<string, unknown>>, alarmStates?: readonly string[]): readonly string[];
+export {};

package/dist/generated/device-scoped-caps.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AUTO-GENERATED by scripts/generate-device-scoped-caps.ts — DO NOT EDIT.
+ *
+ * Every `scope: 'device'` capability name, as plain data — so a forked runner
+ * can answer "may a rule actuate this?" without importing the schema barrel
+ * (~144MB RSS per runner, D28).
+ *
+ * Coverage: 80 device-scoped capabilities.
+ */
+export declare const DEVICE_SCOPED_CAPS: ReadonlySet<string>;
+/**
+ * True when `capName` is a device capability.
+ *
+ * This is the ONLY boundary on what a notification rule may actuate. A rule can
+ * be authored by a non-admin and the runner executes with the addon's
+ * privileges, so an unbounded action would be an arbitrary RPC channel with a
+ * privilege escalation attached. Device scope excludes the system caps
+ * (`device-manager.removeDevice` and friends) by construction.
+ */
+export declare function isDeviceScopedCap(capName: string): boolean;

package/dist/index.d.ts

@@ -121,6 +121,8 @@ export { COCO_80_LABELS, COCO_TO_MACRO, MACRO_LABELS, } from './catalogs/coco-cl
 export { AUDIO_MACRO_LABELS, YAMNET_TO_MACRO, APPLE_SA_TO_MACRO, mapAudioLabelToMacro, getAudioMacroClassIds, } from './catalogs/audio-classmap.js';
 export { EVENT_TAXONOMY, TAXONOMY_COLORS, DEFAULT_EVENT_COLOR, getTaxonomyEntry, colorForKind, subKindsOf, type EventTaxonomyEntry, type EventTaxonomyCategory, type EventTaxonomyLevel, } from './catalogs/event-taxonomy.js';
 export { NcTaxonomyEntrySchema, NcTaxonomySchema, buildNcTaxonomy, NC_TAXONOMY, type NcTaxonomyEntry, type NcTaxonomy, } from './catalogs/nc-taxonomy.js';
+export { DEVICE_SCOPED_CAPS, isDeviceScopedCap } from './generated/device-scoped-caps.js';
+export { DEVICE_STATE_READERS, readDeviceStateFrom, stateVocabularyFor, } from './catalogs/device-state-vocabulary.js';
 export type { CameraMotionConfig, CameraNativeDetectionConfig, CameraDetectionCapabilities, } from './types/camera-detection.js';
 export { type DeviceTypeInfo, DEVICE_TYPE_INFO } from './types/device-type.js';
 export type { DeviceBinding, DeviceBindingEntry } from './device/device-binding.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_sleep = require("./sleep-BvSjpsfC.js");
+const require_sleep = require("./sleep-6oDIDtYV.js");
 const require_event_category = require("./event-category-BE4PDZ_3.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
@@ -2973,6 +2973,78 @@ function buildNcTaxonomy() {
 /** The frozen NC taxonomy, derived once from the taxonomy dictionary. */
 var NC_TAXONOMY = Object.freeze(buildNcTaxonomy());
 //#endregion
+//#region src/catalogs/device-state-vocabulary.ts
+/**
+* Most specific first. Extending this list is how a new device kind becomes
+* gateable; nothing else needs to change.
+*/
+var DEVICE_STATE_READERS = [
+	{
+		cap: "alarm-panel",
+		field: "state"
+	},
+	{
+		cap: "cover",
+		field: "state"
+	},
+	{
+		cap: "presence",
+		field: "state"
+	},
+	{
+		cap: "lock",
+		field: "locked",
+		booleanWords: ["locked", "unlocked"]
+	},
+	{
+		cap: "contact",
+		field: "entryOpen",
+		booleanWords: ["open", "closed"]
+	},
+	{
+		cap: "switch",
+		field: "on",
+		booleanWords: ["on", "off"]
+	},
+	{
+		cap: "binary",
+		field: "on",
+		booleanWords: ["on", "off"]
+	}
+];
+/**
+* Collapse a device's full runtime state to the one string a rule compares
+* against, or `undefined` when nothing in the table applies.
+*
+* `undefined` is the safe answer everywhere: the gate treats it as "does not
+* match", so a device whose kind we cannot read simply never arms a rule.
+*/
+function readDeviceStateFrom(runtimeState) {
+	for (const reader of DEVICE_STATE_READERS) {
+		const slice = runtimeState[reader.cap];
+		if (slice === null || typeof slice !== "object") continue;
+		const value = slice[reader.field];
+		if (typeof value === "string" && value.length > 0) return value;
+		if (typeof value === "boolean" && reader.booleanWords !== void 0) return value ? reader.booleanWords[0] : reader.booleanWords[1];
+	}
+}
+/**
+* The states a rule editor can offer for a device, given its runtime state.
+* Same table, same order — so the picker can never offer a value the gate
+* would not recognise.
+*/
+function stateVocabularyFor(runtimeState, alarmStates = []) {
+	for (const reader of DEVICE_STATE_READERS) {
+		const slice = runtimeState[reader.cap];
+		if (slice === null || typeof slice !== "object") continue;
+		if (reader.booleanWords !== void 0) return [...reader.booleanWords];
+		if (reader.cap === "alarm-panel") return [...alarmStates];
+		const current = slice[reader.field];
+		return typeof current === "string" ? [current] : [];
+	}
+	return [];
+}
+//#endregion
 //#region src/types/device-type.ts
 var DEVICE_TYPE_INFO = { ["camera"]: {
 	type: "camera",
@@ -4784,7 +4856,87 @@ var NcZoneConditionSchema = zod.z.object({
 * The P1 condition set — a flat AND of groups; absent group = pass;
 * membership lists are OR within the list (spec §2.3).
 */
+/**
+* What a rule may actuate.
+*
+* **No hand-maintained allowlist** (operator decision, and the right one — a
+* written list of methods is a third parallel map to keep aligned, and this
+* repo has paid for those). The boundary instead comes from a property the
+* capabilities already carry: an action may target only a **device-scoped**
+* capability method.
+*
+* That is not decoration. A rule can be authored by a NON-ADMIN — personal
+* rules are a supported flow — and the executor runs with the addon's
+* privileges, so an unbounded action is an arbitrary RPC channel with a
+* privilege escalation attached. Restricting to device scope excludes the
+* system caps (`device-manager.removeDevice` and friends) by construction,
+* costs nothing to maintain, and cannot rot: a cap that stops being
+* device-scoped stops being actuatable in the same change.
+*
+* The executor enforces it; {@link NcRuleActionSchema} carries the intent.
+*/
+/**
+* One step of a sequence.
+*
+* `wait` is a first-class step rather than a property of the next action: it is
+* what makes a sequence a SEQUENCE and not a list — "unlock, wait 5s, open"
+* cannot be expressed otherwise.
+*/
+var NcRuleActionSchema = zod.z.discriminatedUnion("kind", [zod.z.object({
+	kind: zod.z.literal("wait"),
+	seconds: zod.z.number().min(0).max(300)
+}), zod.z.object({
+	kind: zod.z.literal("cap"),
+	deviceId: zod.z.number().int(),
+	/** Capability name, e.g. `alarm-panel`. */
+	cap: zod.z.string().min(1),
+	/** Method on it. The executor refuses a non-device-scoped cap. */
+	method: zod.z.string().min(1),
+	/** Method arguments, minus `deviceId` (the executor injects it). */
+	args: zod.z.record(zod.z.string(), zod.z.unknown()).optional()
+})]);
+/**
+* A named, ordered run of steps with its own throttle.
+*
+* `minDelaySec` exists because a noisy rule otherwise hammers a physical
+* actuator — the rule's own cooldown governs NOTIFICATIONS, which is a
+* different budget from "how often may this gate actually open".
+*/
+var NcRuleActionSequenceSchema = zod.z.object({
+	name: zod.z.string().min(1).max(120),
+	enabled: zod.z.boolean(),
+	minDelaySec: zod.z.number().int().min(0).max(86400).optional(),
+	actions: zod.z.array(NcRuleActionSchema).min(1)
+});
+/**
+* Sequences a rule runs, by hook point.
+*
+* ONLY `onTrigger` is here, deliberately. The reference also has activation /
+* deactivation / reset / post-generation hooks, and they are wanted — but this
+* repo's expensive failure mode is declaring a surface nothing produces, so a
+* hook appears here in the same change that produces its edge, never before.
+*/
+var NcRuleActionsSchema = zod.z.object({ 
+/** Runs when the rule MATCHES. */
+onTrigger: zod.z.array(NcRuleActionSequenceSchema).optional() });
+/**
+* "This rule applies only while `deviceId` is in one of `states`."
+*
+* The states are the DEVICE's own vocabulary — `AlarmState` for a panel,
+* `on`/`off` for a switch — not a normalised set, because normalising would
+* make the condition lie about devices whose states have no equivalent.
+*
+* An unreadable state does NOT match: see the engine's fail-closed gate. A
+* condition that fired on "I could not read it" would be worse than no gate.
+*/
+var NcDeviceStateConditionSchema = zod.z.object({
+	deviceId: zod.z.number().int(),
+	/** Any of these matches. */
+	states: zod.z.array(zod.z.string().min(1)).min(1)
+});
 var NcConditionsSchema = zod.z.object({
+	/** Gate on ANOTHER device's current state (the alarm armed, a switch on). */
+	deviceState: NcDeviceStateConditionSchema.optional(),
 	/** Device scope — absent = all devices. */
 	devices: zod.z.array(zod.z.number()).optional(),
 	/** Detector class names (any overlap with the record's class set). */
@@ -5078,7 +5230,16 @@ var NcRuleInputSchema = zod.z.object({
 	* read as `false` by {@link canSetGlobal} in the engine. Admins are not bound
 	* by this flag — see the scope rules on that function.
 	*/
-	snoozeAllowGlobal: zod.z.boolean().optional()
+	snoozeAllowGlobal: zod.z.boolean().optional(),
+	/**
+	* Devices this rule ACTUATES — arm the alarm, open a gate, turn on a light.
+	*
+	* This is what makes the rule set the alarm's trigger set without the alarm
+	* being a special case: arming is
+	* `{ cap: 'alarm-panel', method: 'arm', args: { mode: 'away' } }`, the same
+	* shape as every other actuation.
+	*/
+	actions: NcRuleActionsSchema.optional()
 });
 /**
 * Partial patch for `updateRule` — any subset of the input fields, plus the
@@ -5149,7 +5310,8 @@ var NcConditionDescriptorSchema = zod.z.object({
 		"packagePhase",
 		"crossingSelect",
 		"polygonDraw",
-		"occupancy"
+		"occupancy",
+		"deviceState"
 	]),
 	operator: zod.z.enum([
 		"in",
@@ -5408,6 +5570,21 @@ var NC_CONDITION_CATALOG = [
 		phase: "P1",
 		description: "pipeline / onboard / sensor; a record with no stamped source counts as pipeline."
 	},
+	{
+		id: "deviceState",
+		group: "scope",
+		label: "Device state",
+		valueType: "deviceState",
+		operator: "in",
+		appliesTo: [
+			"immediate",
+			"track-end",
+			"device-event",
+			"package-event"
+		],
+		phase: "P2",
+		description: "Only fire while another device is in one of the chosen states — the alarm armed, a switch on, a contact closed. A state that cannot be read does NOT fire."
+	},
 	{
 		id: "sensorKinds",
 		group: "device",
@@ -34284,7 +34461,9 @@ exports.DEFAULT_SCRUB_THUMBNAIL_PRESET = DEFAULT_SCRUB_THUMBNAIL_PRESET;
 exports.DEVICE_BACKEND_TO_FORMAT = DEVICE_BACKEND_TO_FORMAT;
 exports.DEVICE_CAP_NAMES = DEVICE_CAP_NAMES;
 exports.DEVICE_PROFILES = DEVICE_PROFILES;
+exports.DEVICE_SCOPED_CAPS = require_sleep.DEVICE_SCOPED_CAPS;
 exports.DEVICE_SETTINGS_CONTRIBUTION_METHODS = require_sleep.DEVICE_SETTINGS_CONTRIBUTION_METHODS;
+exports.DEVICE_STATE_READERS = DEVICE_STATE_READERS;
 exports.DEVICE_STATUS_METHOD = require_sleep.DEVICE_STATUS_METHOD;
 exports.DEVICE_TYPE_CONTROL_KIND = DEVICE_TYPE_CONTROL_KIND;
 exports.DEVICE_TYPE_INFO = DEVICE_TYPE_INFO;
@@ -34496,6 +34675,7 @@ exports.NcConditionDescriptorSchema = NcConditionDescriptorSchema;
 exports.NcConditionsSchema = NcConditionsSchema;
 exports.NcCrossingSchema = NcCrossingSchema;
 exports.NcDeliverySchema = NcDeliverySchema;
+exports.NcDeviceStateConditionSchema = NcDeviceStateConditionSchema;
 exports.NcHistoryEntrySchema = NcHistoryEntrySchema;
 exports.NcHistoryFilterSchema = NcHistoryFilterSchema;
 exports.NcHistoryRecordKindSchema = NcHistoryRecordKindSchema;
@@ -34505,6 +34685,9 @@ exports.NcMediaFrameSchema = NcMediaFrameSchema;
 exports.NcMediaPolicySchema = NcMediaPolicySchema;
 exports.NcOccupancyConditionSchema = NcOccupancyConditionSchema;
 exports.NcPlateMatcherSchema = NcPlateMatcherSchema;
+exports.NcRuleActionSchema = NcRuleActionSchema;
+exports.NcRuleActionSequenceSchema = NcRuleActionSequenceSchema;
+exports.NcRuleActionsSchema = NcRuleActionsSchema;
 exports.NcRuleInputSchema = NcRuleInputSchema;
 exports.NcRulePatchSchema = NcRulePatchSchema;
 exports.NcRuleSchema = NcRuleSchema;
@@ -34921,6 +35104,7 @@ exports.isBaseConditionKey = isBaseConditionKey;
 exports.isCollectionArrayMethod = isCollectionArrayMethod;
 exports.isDeployableToAgent = isDeployableToAgent;
 exports.isDeviceConfigCap = require_sleep.isDeviceConfigCap;
+exports.isDeviceScopedCap = require_sleep.isDeviceScopedCap;
 exports.isEvent = require_sleep.isEvent;
 exports.isNode = isNode;
 exports.isObjectInput = isObjectInput;
@@ -35001,6 +35185,7 @@ exports.procedureAuthKey = procedureAuthKey;
 exports.ptzAutotrackCapability = ptzAutotrackCapability;
 exports.ptzCapability = ptzCapability;
 exports.pythonScriptForBackend = pythonScriptForBackend;
+exports.readDeviceStateFrom = readDeviceStateFrom;
 exports.readNodePin = require_sleep.readNodePin;
 exports.readinessKey = require_sleep.readinessKey;
 exports.rebootCapability = rebootCapability;
@@ -35040,6 +35225,7 @@ exports.smtpProviderCapability = smtpProviderCapability;
 exports.snapshotCapability = snapshotCapability;
 exports.ssoBridgeCapability = ssoBridgeCapability;
 exports.startReachabilityPoll = startReachabilityPoll;
+exports.stateVocabularyFor = stateVocabularyFor;
 exports.storageCapability = storageCapability;
 exports.storageEvictableCapability = storageEvictableCapability;
 exports.storageProviderCapability = storageProviderCapability;