@camstack/types 1.2.453 → 1.2.455

package/dist/device/cap-vocabulary/action-index.d.ts

@@ -0,0 +1,31 @@
+import type { LooseVocabAction, VocabEffectValue } from './types.js';
+/** A vocabulary action with the cap that offers it. */
+export interface IndexedVocabAction {
+    readonly cap: string;
+    readonly action: LooseVocabAction;
+}
+/** The state an action leads to, resolved against the args the step carries. */
+export interface ActionEffect {
+    readonly cap: string;
+    readonly field: string;
+    readonly value: VocabEffectValue;
+}
+/** Every vocabulary action id, with its cap. */
+export declare function allVocabActions(): readonly IndexedVocabAction[];
+/** The vocabulary action with this id, or `undefined`. */
+export declare function findVocabAction(actionId: string): IndexedVocabAction | undefined;
+/**
+ * The action id a stored `cap` + `method` (+ args) pair stands for, when
+ * exactly ONE vocabulary action matches it: same cap, same method, and every
+ * arg the action bakes in equals the stored one. Two matches (`cover.position`
+ * and … none today, but `switch.on` / `switch.off` share a method and differ
+ * by their baked arg) are told apart by the baked args; still ambiguous, or
+ * none, gives `undefined`.
+ */
+export declare function vocabActionIdFor(cap: string, method: string, args: Readonly<Record<string, unknown>> | undefined): string | undefined;
+/**
+ * The state `actionId` leads to with these args, or `null` when the action
+ * declares none (toggle, press, stop), is unknown, or the arg carrying the
+ * value is missing.
+ */
+export declare function actionEffect(actionId: string, args: Readonly<Record<string, unknown>> | undefined): ActionEffect | null;

package/dist/device/cap-vocabulary/index.d.ts

@@ -4,6 +4,8 @@
  */
 export type { ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, } from './resolve.js';
 export { actionsForDevice, renderVocabPhrase, triggersForDevice, } from './resolve.js';
+export type { ActionEffect, IndexedVocabAction } from './action-index.js';
+export { actionEffect, allVocabActions, findVocabAction, vocabActionIdFor, } from './action-index.js';
 export { VOCAB_TEMPLATES } from './templates.js';
-export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapStatusField, CapVocabularyEntry, CapVocabularyMap, CapVocabularySlice, DeviceCapVocabulary, DeviceVocabCapName, DynamicOffer, EnumOffer, EnumStateValue, L10n, LooseCapVocabularyEntry, LooseDynamicOffer, LooseVocabAction, LooseVocabOffer, LooseVocabOpenArg, LooseVocabStateTrigger, NumberOffer, SystemCapVocabulary, SystemVocabCapName, TextOffer, VocabAction, VocabCapName, VocabChoice, VocabEventTrigger, VocabIcon, VocabLocale, VocabOffer, VocabOpenArg, VocabStateTrigger, } from './types.js';
+export type { ActionArgKey, ActionArgs, BooleanOffer, CapEventName, CapMethodName, CapStatusField, CapVocabularyEntry, CapVocabularyMap, CapVocabularySlice, 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';
 export { CAP_VOCABULARY, CAP_VOCABULARY_BY_NAME } from './vocabulary.js';

package/dist/device/cap-vocabulary/types.d.ts

@@ -148,6 +148,22 @@ export interface VocabOpenArg<C extends VocabCapName, K extends string> {
     /** The method accepts the call without it. */
     readonly optional?: boolean;
 }
+/** A value a status field can hold, as an action's effect states it. */
+export type VocabEffectValue = string | number | boolean;
+/**
+ * The state an action LEADS TO (D983): the cap status field and either a
+ * literal value (`cover.open` → `state = 'open'`) or the arg that carries it
+ * (`brightness.set` → `level = <level arg>`). Only an action with an effect
+ * can be HELD by a scheduler. Absent where the outcome is not a state
+ * (toggle, press, stop).
+ */
+export type VocabEffectFor<C extends VocabCapName, M extends CapMethodName<C>> = {
+    readonly field: CapStatusField<C>;
+    readonly value: VocabEffectValue;
+} | {
+    readonly field: CapStatusField<C>;
+    readonly fromArg: ActionArgKey<C, M>;
+};
 /** One operator-facing action: a cap method call with a phrase. */
 export interface VocabActionFor<C extends VocabCapName, M extends CapMethodName<C>> {
     /** Stable id — persisted by pickers as a select value (`switch.on`). */
@@ -165,6 +181,8 @@ export interface VocabActionFor<C extends VocabCapName, M extends CapMethodName<
     readonly args?: Partial<ActionArgs<C, M>>;
     /** Args the operator fills. */
     readonly openArgs?: readonly VocabOpenArg<C, ActionArgKey<C, M>>[];
+    /** The state this action leads to, when it is one (see {@link VocabEffectFor}). */
+    readonly effect?: VocabEffectFor<C, M>;
 }
 /** Any action of cap `C`, discriminated by `method`. */
 export type VocabAction<C extends VocabCapName> = {
@@ -343,6 +361,14 @@ export interface LooseVocabOpenArg {
     readonly offer: LooseVocabOffer;
     readonly optional?: boolean;
 }
+/** An effect as a consumer reads it, with no cap-specific key type. */
+export type LooseVocabEffect = {
+    readonly field: string;
+    readonly value: VocabEffectValue;
+} | {
+    readonly field: string;
+    readonly fromArg: string;
+};
 /** An action as a consumer reads it. */
 export interface LooseVocabAction {
     readonly id: string;
@@ -352,6 +378,7 @@ export interface LooseVocabAction {
     readonly icon: VocabIcon;
     readonly args?: Readonly<Record<string, unknown>>;
     readonly openArgs?: readonly LooseVocabOpenArg[];
+    readonly effect?: LooseVocabEffect;
 }
 /** A boolean state trigger, string-keyed. */
 export interface LooseBooleanStateTrigger {

package/dist/index.d.ts

@@ -163,11 +163,13 @@ export { APP_FLOW_DEFAULT_REDIRECT, APP_FLOW_REFUSAL_MESSAGES, APP_FLOW_STATE_PR
 export { SSO_STATE_COOKIE, SSO_STATE_COOKIE_MAX_AGE_SEC } from './auth/sso-state.js';
 export { buildDeviceEnrollmentLink, buildDeviceSignatureMessage, type CompleteEnrollmentInput, CompleteEnrollmentInputSchema, type CompleteEnrollmentOutput, CompleteEnrollmentOutputSchema, DEVICE_CERT_RENEW_WINDOW_DAYS, DEVICE_CERT_SIGNATURE, DEVICE_CERT_VALIDITY_DAYS, DEVICE_ENROLLMENT_TTL_MS, DEVICE_NONCE_TTL_MS, DEVICE_SAN_CREDENTIAL_PREFIX, DEVICE_SAN_USER_PREFIX, DEVICE_SIGNATURE_MESSAGE_VERSION, type DeviceCertificateLoginMethod, DeviceCertificateLoginMethodSchema, type DeviceChallenge, DeviceChallengeSchema, type DeviceCredential, DeviceCredentialSchema, type DeviceCredentialStatus, DeviceCredentialStatusSchema, type DevicePlatform, DevicePlatformSchema, type DeviceProofInput, DeviceProofInputSchema, type CompleteEnrollmentResult, CompleteEnrollmentResultSchema, DEFINITIVE_DEVICE_REFUSALS, DEVICE_DEFINITIVE_REFUSALS_BEFORE_DELETE, DEVICE_REFRESH_REFUSAL_PREFIX, deviceRefusalFromMessage, type DeviceChallengeResult, DeviceChallengeResultSchema, DeviceEnrollProofSchema, type DeviceRefusal, type DeviceRefusalReason, DeviceRefusalReasonSchema, DeviceRefusalSchema, type DeviceRevoker, type EnrollSelfInput, EnrollSelfInputSchema, formatDeviceRevoker, isDefinitiveDeviceRefusal, type RenewDeviceCertificateResult, RenewDeviceCertificateResultSchema, type RevokeOwnDeviceCertificateResult, RevokeOwnDeviceCertificateResultSchema, type DeviceSignaturePurpose, DeviceSignaturePurposeSchema, type RenewDeviceCertificateOutput, RenewDeviceCertificateOutputSchema, type StartEnrollmentOutput, StartEnrollmentOutputSchema, parseDeviceEnrollmentLink, } from './auth/device-certificate.js';
 export { advertisedHubOrigins, claimedRequestOrigins, normalizeOrigin, pickRequestOrigin, type RequestHeaders, requestMountPrefix, } from './auth/request-origin.js';
-export type { ActionStep, AutomationAction, AutomationAll, AutomationAny, AutomationCapStep, AutomationConditionOperator, AutomationConditionTraceNode, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLabelSource, DetectionLeaf, DetectionSubject, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, IdentityLabel, LegacyAutomationRecipe, LegacyCondition, LegacyTrigger, PlateLabel, StationaryLeaf, StationaryPresentLeaf, SubClassLabel, SubjectObservation, SubjectVerdict, AutomationRecipe, AutomationRunMode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, ConditionEvaluation, ConditionReader, DetectionDecision, DetectionTrigger, DetectionVars, GenerateAutomationBlockInput, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, StationaryChangedInput, StationaryDecision, StationaryTrigger, StationaryVars, TraceNodeOutcome, TraceValue, TrackLifecycleInput, } from './automation/index.js';
-export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationConditionOperatorSchema, AutomationConditionTraceNodeSchema, AutomationRecipeSchema, AutomationWhenSchema, CurrentAutomationRecipeSchema, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, LegacyAutomationRecipeSchema, LegacyConditionSchema, LegacyTriggerSchema, MAX_TRACE_ARG_LENGTH, MAX_TRACE_ARGS, MAX_WHEN_DEPTH, MAX_WHEN_LEAVES, REDACTED_ARG, StationarySubjectSchema, anySubjectMatches, buildStepArgsTrace, collectWhenMirrorSources, convertLegacyCondition, convertLegacyRecipe, convertLegacyWhen, countWhenLeaves, describeSubject, evaluateWhenTree, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, subClassesOf, subjectFromClassName, subjectMatches, validateWhenTree, whenDepth, AutomationRunModeSchema, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildTriggerTrace, collectMirrorSources, ConditionMirror, DEFAULT_TRACE_KEEP, DetectionTriggerFilter, detectionClassMatches, evaluateConditionTree, evaluateStationaryTrigger, generateAutomationBlock, isSkippedTrace, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, MAX_TRACE_KEEP, RunGate, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, validateRecipeBounds, } from './automation/index.js';
+export type { ActionStep, AutomationAction, AutomationAll, AutomationAny, AutomationCapStep, AutomationConditionOperator, AutomationConditionTraceNode, AutomationEventLeaf, AutomationLeaf, AutomationNot, AutomationStateLeaf, AutomationWhen, DetectionLabelSource, DetectionLeaf, DetectionSubject, DeviceBecomesLeaf, DeviceIsLeaf, ExpressionLeaf, IdentityLabel, LegacyAutomationRecipe, NormalizedCapStep, StepDeviceTrace, LegacyCondition, LegacyTrigger, PlateLabel, StationaryLeaf, StationaryPresentLeaf, SubClassLabel, SubjectObservation, SubjectVerdict, AutomationRecipe, AutomationRunMode, AutomationRunOutcome, AutomationRunTrace, AutomationRunVerdict, AutomationStateDoc, AutomationStepTrace, AutomationTriggerTrace, ConditionEvaluation, ConditionReader, DetectionDecision, DetectionTrigger, DetectionVars, GenerateAutomationBlockInput, MirrorRefreshFetchers, MirrorRefreshReport, MirrorSource, StationaryChangedInput, StationaryDecision, StationaryTrigger, StationaryVars, TraceNodeOutcome, TraceValue, TrackLifecycleInput, } from './automation/index.js';
+export { ActionStepSchema, AutomationActionSchema, AutomationCapStepSchema, AutomationWaitStepSchema, EMPTY_AUTOMATION_STATE, mergeSkipTraces, AutomationConditionOperatorSchema, AutomationConditionTraceNodeSchema, AutomationRecipeSchema, AutomationWhenSchema, CurrentAutomationRecipeSchema, DETECTION_LABEL_SOURCES, DetectionSubjectSchema, LegacyAutomationRecipeSchema, LegacyConditionSchema, LegacyTriggerSchema, MAX_TRACE_ARG_LENGTH, MAX_STEP_DEVICE_OUTCOMES, MAX_TRACE_ARGS, MAX_WHEN_DEPTH, normalizeCapStep, normalizeStepTargets, StepDeviceTraceSchema, MAX_WHEN_LEAVES, REDACTED_ARG, StationarySubjectSchema, anySubjectMatches, buildStepArgsTrace, collectWhenMirrorSources, convertLegacyCondition, convertLegacyRecipe, convertLegacyWhen, countWhenLeaves, describeSubject, evaluateWhenTree, forEachLeaf, hasEventLeaves, isEventLeaf, isLeaf, subClassesOf, subjectFromClassName, subjectMatches, validateWhenTree, whenDepth, AutomationRunModeSchema, AutomationRunOutcomeSchema, AutomationRunTraceSchema, AutomationRunVerdictSchema, AutomationStateDocSchema, AutomationStepTraceSchema, AutomationTriggerTraceSchema, appendTrace, buildTriggerTrace, collectMirrorSources, ConditionMirror, DEFAULT_TRACE_KEEP, DetectionTriggerFilter, detectionClassMatches, evaluateConditionTree, evaluateStationaryTrigger, generateAutomationBlock, isSkippedTrace, MAX_CONDITION_DEPTH, MAX_CONDITION_LEAVES, MAX_TRACE_KEEP, RunGate, skipSignature, TraceNodeOutcomeSchema, TraceValueSchema, validateRecipeBounds, } from './automation/index.js';
 export { UnitWarningSchema, capUnitResolver, normalizeActionUnits, normalizeConditionUnits, normalizeRecipeUnits, prepareRecipeUnits, } from './automation/index.js';
 export type { PreparedRecipe, UnitResolver, UnitWarning, UnitsNormalized, } from './automation/index.js';
 export * from './automation/action.js';
+export * from './automation/action-target.js';
+export * from './automation/nc-action-target.js';
 export * from './automation/step-runner.js';
 export * from './automation/export-entities.js';
 export * from './cap-call-context.js';
@@ -220,8 +222,8 @@ export type { AccessoryControlInput, AccessoryControlKind, AccessoryControlPick,
 export { DEVICE_TYPE_CONTROL_KIND, hasMotionTrigger, isNode, MOTION_TRIGGER_FEATURE, pickAccessoryControl, resolveDeviceControlKind, resolveMutate, SENSOR_FEATURES, SENSOR_MAP, } from './device/device-control-resolution.js';
 export type { DeviceDoAction, DeviceDoOpenArg } from './device/device-do-actions.js';
 export { actionsForBoundCaps, actionsForDevice, actionsForDevices, actionsForDeviceType, allDoActions, DEVICE_DO_ACTIONS, DEVICE_TYPE_DO_CAPS, deviceDoFamily, doActionSelectValue, isDoActionActuatable, isDoPickerDeviceType, matchDoAction, sameDoFamily, } from './device/device-do-actions.js';
-export type { CapVocabularyEntry, CapVocabularyMap, L10n as VocabL10n, LooseCapVocabularyEntry, LooseVocabOffer, LooseVocabOpenArg, ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, VocabCapName, VocabLocale, } from './device/cap-vocabulary/index.js';
-export { actionsForDevice as vocabularyActionsForDevice, CAP_VOCABULARY, CAP_VOCABULARY_BY_NAME, renderVocabPhrase, triggersForDevice as vocabularyTriggersForDevice, VOCAB_TEMPLATES, } from './device/cap-vocabulary/index.js';
+export type { CapVocabularyEntry, CapVocabularyMap, L10n as VocabL10n, ActionEffect, IndexedVocabAction, LooseCapVocabularyEntry, LooseVocabEffect, LooseVocabOffer, LooseVocabOpenArg, ResolvedBooleanTrigger, ResolvedEnumTrigger, ResolvedEnumValue, ResolvedEventTrigger, ResolvedNumericTrigger, ResolvedValueTrigger, ResolvedVocabAction, ResolvedVocabTrigger, VocabBindingsInput, VocabCapName, VocabLocale, } from './device/cap-vocabulary/index.js';
+export { actionEffect, actionsForDevice as vocabularyActionsForDevice, allVocabActions, CAP_VOCABULARY, CAP_VOCABULARY_BY_NAME, findVocabAction, renderVocabPhrase, triggersForDevice as vocabularyTriggersForDevice, VOCAB_TEMPLATES, vocabActionIdFor, } from './device/cap-vocabulary/index.js';
 export type { ChildLayout, ChildLayoutEntry, CreateDeviceSpec, DeviceCapDisplayOverride, DeviceDiscovery, DeviceDisplayOverride, DeviceManualCreation, DeviceMeta, DiscoveredDevice, InitialDeviceMeta, RoleDisplayDefault, SavedDevice, } from './device/device-management.js';
 export type { DeviceProfile, DeviceProfileDefaults, DeviceProfileMatch, PipelinePhaseMode, } from './device/device-profile.js';
 export { BATTERY_DEVICE_PROFILE, DEVICE_PROFILES, deviceMatchesProfile, resolveDeviceProfile, } from './device/device-profile.js';
@@ -388,3 +390,4 @@ export type { ServerNameInfo } from './system/server-name.js';
 export { resolveServerName, SERVER_NAME_MAX_LENGTH, SERVER_NAME_SETTING_KEY, ServerNameInfoSchema, ServerNameSchema, shortHostname, } from './system/server-name.js';
 export { armRemovalReconcile, reconcileRemovedDevices, REMOVAL_RECONCILE_INTERVAL_MS, type RemovalReconcileOptions, type RemovalReconcileOutcome, type TombstoneSource, } from './device/device-removal-reconcile.js';
 export * from './ir/index.js';
+export * from './time/index.js';