@camstack/types 1.2.412 → 1.2.414

package/dist/capabilities/advanced-parameters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Derive advanced Customize parameters from runtime Zod (D939).
+ */
+import { z } from 'zod';
+import type { CapabilityCustomizeSpec } from './customize-spec.js';
+export declare const ADVANCED_SHORT_STRING_MAX = 80;
+export type AdvancedParameterKind = 'boolean' | 'number' | 'string' | 'enum';
+export interface DerivedAdvancedParameter {
+    readonly path: string;
+    readonly kind: AdvancedParameterKind;
+    readonly label: string;
+    readonly unit?: string;
+    readonly enumValues?: readonly string[];
+}
+export declare function collectCustomizeOwnedPaths(spec: CapabilityCustomizeSpec): ReadonlySet<string>;
+export declare function collectEventTimestampPaths(spec: CapabilityCustomizeSpec): ReadonlySet<string>;
+export declare function deriveAdvancedParameters(runtimeSchema: z.ZodObject<z.core.$ZodLooseShape>, ownedPaths: ReadonlySet<string>, eventTimestampPaths: ReadonlySet<string>): readonly DerivedAdvancedParameter[];

package/dist/capabilities/ambient-light-sensor.cap.d.ts

@@ -57,5 +57,10 @@ export declare const ambientLightSensorCapability: {
     /** Clock fields: written, but excluded from the compare that decides
      *  whether persisting is worth a SQLite commit. */
     readonly volatileStateFields: readonly ["lastFetchedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type IAmbientLightSensorProvider = InferProvider<typeof ambientLightSensorCapability>;

package/dist/capabilities/battery.cap.d.ts

@@ -162,6 +162,7 @@ export declare const batteryCapability: {
     };
     readonly customize: {
         readonly version: 1;
+        readonly advanced: 'derive';
         readonly targets: readonly [{
             readonly id: 'percentage';
             readonly cardinality: 'scalar';

package/dist/capabilities/binary.cap.d.ts

@@ -55,5 +55,10 @@ export declare const binaryCapability: {
     /** Clock fields: written, but excluded from the compare that decides
      *  whether persisting is worth a SQLite commit. */
     readonly volatileStateFields: readonly ["lastChangedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type IBinaryProvider = InferProvider<typeof binaryCapability>;

package/dist/capabilities/composer.cap.d.ts

@@ -249,6 +249,7 @@ export declare const ComposerBlockVerdictSchema: z.ZodObject<{
     status: z.ZodEnum<{
         degraded: "degraded";
         failed: "failed";
+        incomplete: "incomplete";
         running: "running";
         starting: "starting";
         stopped: "stopped";
@@ -262,6 +263,7 @@ export declare const ComposerApplyResultSchema: z.ZodObject<{
         status: z.ZodEnum<{
             degraded: "degraded";
             failed: "failed";
+            incomplete: "incomplete";
             running: "running";
             starting: "starting";
             stopped: "stopped";
@@ -404,6 +406,7 @@ export declare const composerCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -427,6 +430,7 @@ export declare const composerCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";

package/dist/capabilities/core-blocks.cap.d.ts

@@ -66,6 +66,7 @@ export type CoreBlockPlacement = z.infer<typeof CoreBlockPlacementSchema>;
 export declare const CoreBlockStatusSchema: z.ZodEnum<{
     degraded: "degraded";
     failed: "failed";
+    incomplete: "incomplete";
     running: "running";
     starting: "starting";
     stopped: "stopped";
@@ -400,6 +401,7 @@ export declare const CoreBlockSchema: z.ZodObject<{
     status: z.ZodEnum<{
         degraded: "degraded";
         failed: "failed";
+        incomplete: "incomplete";
         running: "running";
         starting: "starting";
         stopped: "stopped";
@@ -558,6 +560,7 @@ export declare const CompositionStateReadSchema: z.ZodDiscriminatedUnion<[z.ZodO
         status: z.ZodEnum<{
             degraded: "degraded";
             failed: "failed";
+            incomplete: "incomplete";
             running: "running";
             starting: "starting";
             stopped: "stopped";
@@ -603,6 +606,7 @@ export declare const CompositionViewSchema: z.ZodObject<{
         status: z.ZodEnum<{
             degraded: "degraded";
             failed: "failed";
+            incomplete: "incomplete";
             running: "running";
             starting: "starting";
             stopped: "stopped";
@@ -757,6 +761,7 @@ export declare const CompositionViewSchema: z.ZodObject<{
             status: z.ZodEnum<{
                 degraded: "degraded";
                 failed: "failed";
+                incomplete: "incomplete";
                 running: "running";
                 starting: "starting";
                 stopped: "stopped";
@@ -804,6 +809,7 @@ export declare const CompositionListReadSchema: z.ZodDiscriminatedUnion<[z.ZodOb
             status: z.ZodEnum<{
                 degraded: "degraded";
                 failed: "failed";
+                incomplete: "incomplete";
                 running: "running";
                 starting: "starting";
                 stopped: "stopped";
@@ -958,6 +964,7 @@ export declare const CompositionListReadSchema: z.ZodDiscriminatedUnion<[z.ZodOb
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1009,6 +1016,7 @@ export declare const CompositionGetReadSchema: z.ZodDiscriminatedUnion<[z.ZodObj
             status: z.ZodEnum<{
                 degraded: "degraded";
                 failed: "failed";
+                incomplete: "incomplete";
                 running: "running";
                 starting: "starting";
                 stopped: "stopped";
@@ -1163,6 +1171,7 @@ export declare const CompositionGetReadSchema: z.ZodDiscriminatedUnion<[z.ZodObj
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1215,6 +1224,7 @@ export declare const CompositionCustomizationReadSchema: z.ZodDiscriminatedUnion
             status: z.ZodEnum<{
                 degraded: "degraded";
                 failed: "failed";
+                incomplete: "incomplete";
                 running: "running";
                 starting: "starting";
                 stopped: "stopped";
@@ -1369,6 +1379,7 @@ export declare const CompositionCustomizationReadSchema: z.ZodDiscriminatedUnion
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1441,6 +1452,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1607,6 +1619,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1787,6 +1800,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -1965,6 +1979,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -2139,6 +2154,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -2318,6 +2334,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -2687,6 +2704,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -2960,6 +2978,7 @@ export declare const coreBlocksCapability: {
                 status: z.ZodEnum<{
                     degraded: "degraded";
                     failed: "failed";
+                    incomplete: "incomplete";
                     running: "running";
                     starting: "starting";
                     stopped: "stopped";
@@ -3131,6 +3150,7 @@ export declare const coreBlocksCapability: {
                     status: z.ZodEnum<{
                         degraded: "degraded";
                         failed: "failed";
+                        incomplete: "incomplete";
                         running: "running";
                         starting: "starting";
                         stopped: "stopped";
@@ -3285,6 +3305,7 @@ export declare const coreBlocksCapability: {
                         status: z.ZodEnum<{
                             degraded: "degraded";
                             failed: "failed";
+                            incomplete: "incomplete";
                             running: "running";
                             starting: "starting";
                             stopped: "stopped";
@@ -3335,6 +3356,7 @@ export declare const coreBlocksCapability: {
                     status: z.ZodEnum<{
                         degraded: "degraded";
                         failed: "failed";
+                        incomplete: "incomplete";
                         running: "running";
                         starting: "starting";
                         stopped: "stopped";
@@ -3489,6 +3511,7 @@ export declare const coreBlocksCapability: {
                         status: z.ZodEnum<{
                             degraded: "degraded";
                             failed: "failed";
+                            incomplete: "incomplete";
                             running: "running";
                             starting: "starting";
                             stopped: "stopped";
@@ -3546,6 +3569,7 @@ export declare const coreBlocksCapability: {
                     status: z.ZodEnum<{
                         degraded: "degraded";
                         failed: "failed";
+                        incomplete: "incomplete";
                         running: "running";
                         starting: "starting";
                         stopped: "stopped";
@@ -3700,6 +3724,7 @@ export declare const coreBlocksCapability: {
                         status: z.ZodEnum<{
                             degraded: "degraded";
                             failed: "failed";
+                            incomplete: "incomplete";
                             running: "running";
                             starting: "starting";
                             stopped: "stopped";

package/dist/capabilities/customize-catalog.d.ts

@@ -65,8 +65,16 @@ export interface CustomizeCatalogTarget {
     readonly sourceReport: CustomizeSourceReport;
     readonly advancedExpression: boolean;
 }
+export interface CustomizeCatalogAdvancedParameter {
+    readonly path: string;
+    readonly kind: CustomizeCatalogValueKind;
+    readonly label: string;
+    readonly unit?: string;
+    readonly enumValues?: readonly string[];
+}
 export interface CustomizeCatalogEntry {
     readonly version: 1;
     readonly targets: readonly CustomizeCatalogTarget[];
+    readonly advancedParameters: readonly CustomizeCatalogAdvancedParameter[];
 }
 export type CustomizeCatalog = Readonly<Record<string, CustomizeCatalogEntry>>;

package/dist/capabilities/customize-spec.d.ts

@@ -13,6 +13,8 @@ export type CustomizeApplyMode = 'add' | 'replace' | 'add-or-replace';
 export interface CapabilityCustomizeSpec {
     readonly version: 1;
     readonly targets: readonly CapabilityCustomizeTarget[];
+    /** Opt-in advanced parameters: derive from runtime schema or an explicit path list (D939). */
+    readonly advanced?: 'derive' | readonly string[];
 }
 export type CapabilityCustomizeTarget = ScalarCustomizeTarget | KeyedArrayCustomizeTarget | EventCustomizeTarget;
 export interface CustomizeVocabularyRef {

package/dist/capabilities/humidity-sensor.cap.d.ts

@@ -60,5 +60,10 @@ export declare const humiditySensorCapability: {
     /** Clock fields: written, but excluded from the compare that decides
      *  whether persisting is worth a SQLite commit. */
     readonly volatileStateFields: readonly ["lastFetchedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type IHumiditySensorProvider = InferProvider<typeof humiditySensorCapability>;

package/dist/capabilities/power-meter.cap.d.ts

@@ -113,5 +113,10 @@ export declare const powerMeterCapability: {
     /** Clock fields: written, but excluded from the compare that decides
      *  whether persisting is worth a SQLite commit. */
     readonly volatileStateFields: readonly ["lastFetchedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type IPowerMeterProvider = InferProvider<typeof powerMeterCapability>;

package/dist/capabilities/running-state.cap.d.ts

@@ -74,6 +74,7 @@ export declare const runningStateCapability: {
     readonly volatileStateFields: readonly ["lastFetchedAt"];
     readonly customize: {
         readonly version: 1;
+        readonly advanced: 'derive';
         readonly targets: readonly [{
             readonly id: 'running';
             readonly cardinality: 'scalar';

package/dist/capabilities/switch.cap.d.ts

@@ -82,5 +82,10 @@ export declare const switchCapability: {
             };
         }];
     };
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type ISwitchProvider = InferProvider<typeof switchCapability>;

package/dist/capabilities/temperature-sensor.cap.d.ts

@@ -68,5 +68,10 @@ export declare const temperatureSensorCapability: {
     /** Clock fields: written, but excluded from the compare that decides
      *  whether persisting is worth a SQLite commit. */
     readonly volatileStateFields: readonly ["lastFetchedAt"];
+    readonly customize: {
+        readonly version: 1;
+        readonly advanced: 'derive';
+        readonly targets: readonly [];
+    };
 };
 export type ITemperatureSensorProvider = InferProvider<typeof temperatureSensorCapability>;

package/dist/composition/cards/__fixtures__/stored-compositions.d.ts

@@ -0,0 +1,3 @@
+import { type Composition } from '../../composition.js';
+export declare const VERANDA_COMPOSITION: Composition;
+export declare const DOORBELL_615_COMPOSITION: Composition;

package/dist/composition/cards/card-types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Card editor model for a stored composition (D939).
+ */
+import type { Composition, CompositionExpressionSource, CompositionFieldRead, CompositionFieldsFeature, CompositionPassthroughFeature } from '../composition.js';
+import type { KeyedArrayRead } from '../customize/keyed-array-decode.js';
+import type { PulseDecoded } from '../customize/event-decode.js';
+import type { ScalarDecoded } from '../customize/scalar-decode.js';
+export type FieldAggregateKind = 'avg-round-1' | 'max';
+export interface FromFieldEntry {
+    readonly kind: 'from';
+    readonly sources: readonly CompositionFieldRead[];
+    readonly aggregate: FieldAggregateKind | null;
+}
+export interface CompanionFieldEntry {
+    readonly kind: 'companion';
+    readonly companion: 'now';
+}
+export interface FormulaFieldEntry {
+    readonly kind: 'formula';
+    readonly expr: string;
+    readonly bindings: CompositionExpressionSource['bindings'];
+}
+/** Publish this field converted from its declared unit to `to` (D939). */
+export interface ConvertUnitFieldEntry {
+    readonly kind: 'convert-unit';
+    readonly bindingName: string;
+    readonly from: string;
+    readonly to: string;
+    readonly source: CompositionFieldRead;
+}
+export type CompositionCardFieldEntry = FromFieldEntry | CompanionFieldEntry | FormulaFieldEntry | ConvertUnitFieldEntry;
+export interface CompositionFieldsCard {
+    readonly cardKind: 'fields';
+    readonly cap: string;
+    readonly enabled: boolean | undefined;
+    readonly entries: Readonly<Record<string, CompositionCardFieldEntry>>;
+    readonly items: CompositionFieldsFeature['items'];
+}
+export interface CompositionPulseCard {
+    readonly cardKind: 'pulse';
+    readonly cap: string;
+    readonly targetId: string;
+    readonly decoded: PulseDecoded;
+}
+export interface CompositionScalarCard {
+    readonly cardKind: 'scalar';
+    readonly cap: string;
+    readonly targetId: string;
+    readonly decoded: ScalarDecoded;
+}
+export interface CompositionKeyedArrayCard {
+    readonly cardKind: 'keyedArray';
+    readonly cap: string;
+    readonly targetId: string;
+    readonly decoded: KeyedArrayRead;
+}
+export type CompositionCard = CompositionFieldsCard | CompositionPulseCard | CompositionScalarCard | CompositionKeyedArrayCard;
+export interface CompositionPassthroughSlot {
+    readonly featureIndex: number;
+    readonly feature: CompositionPassthroughFeature;
+}
+export interface CompositionCardSlot {
+    readonly featureIndex: number;
+    readonly card: CompositionCard;
+}
+export interface CompositionCardEditorModel {
+    readonly original: Composition;
+    readonly passthroughFeatures: readonly CompositionPassthroughSlot[];
+    readonly cards: readonly CompositionCardSlot[];
+    /** Field paths edited on a `fields` card, keyed by cap. */
+    readonly editedFieldPaths: Readonly<Record<string, readonly string[]>>;
+    /** Whole-card overrides (pulse / scalar / keyed) marked edited. */
+    readonly editedCards: Readonly<Record<string, true>>;
+}
+export interface DecodedCompositionCards {
+    readonly model: CompositionCardEditorModel;
+}

package/dist/composition/cards/classify-field.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Classify one composition field into a card entry.
+ */
+import type { CompositionFieldRead, CompositionFieldSource } from '../composition.js';
+import type { CompositionCardFieldEntry } from './card-types.js';
+declare function sameRead(a: CompositionFieldRead, b: CompositionFieldRead): boolean;
+export declare function classifyFieldSource(source: CompositionFieldSource): CompositionCardFieldEntry;
+export declare function fieldEntryToSource(entry: CompositionCardFieldEntry, original: CompositionFieldSource | undefined): CompositionFieldSource;
+export { sameRead };

package/dist/composition/cards/convert-unit.d.ts

@@ -0,0 +1 @@
+export declare function convertUnitTargets(from: string): readonly string[];

package/dist/composition/cards/decode.d.ts

@@ -0,0 +1,3 @@
+import type { Composition } from '../composition.js';
+import type { DecodedCompositionCards } from './card-types.js';
+export declare function decodeCompositionToCards(composition: Composition): DecodedCompositionCards;

package/dist/composition/cards/edit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Immutable edits on the card editor model (D939).
+ */
+import type { CompositionCardEditorModel } from './card-types.js';
+export declare function markFieldEdited(model: CompositionCardEditorModel, cap: string, fieldPath: string): CompositionCardEditorModel;
+export declare function setFormulaExpr(model: CompositionCardEditorModel, cap: string, fieldPath: string, expr: string): CompositionCardEditorModel;

package/dist/composition/cards/encode.d.ts

@@ -0,0 +1,3 @@
+import type { Composition } from '../composition.js';
+import type { CompositionCardEditorModel } from './card-types.js';
+export declare function encodeCardsToComposition(model: CompositionCardEditorModel): Composition;

package/dist/composition/cards/fill-status.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Whether a composition still needs required value fields (D939).
+ */
+import type { CompositionProblem } from '../composition-report.js';
+export type CompositionFillStatus = 'complete' | 'incomplete';
+export declare function isUnfilledRequiredProblem(problem: CompositionProblem): boolean;
+export declare function compositionFillStatus(problems: readonly CompositionProblem[]): CompositionFillStatus;
+/** True when the only problems are unfilled required fields — save may proceed. */
+export declare function problemsBlockSave(problems: readonly CompositionProblem[]): boolean;

package/dist/composition/cards/formula-problem.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Surface composer validation for a formula entry (D939).
+ */
+import type { CompositionExpressionSource } from '../composition.js';
+export declare function formulaProblem(expr: string, bindings: CompositionExpressionSource['bindings']): string | null;

package/dist/composition/cards/index.d.ts

@@ -0,0 +1,9 @@
+export * from './card-types.js';
+export * from './classify-field.js';
+export * from './convert-unit.js';
+export * from './decode.js';
+export * from './encode.js';
+export * from './edit.js';
+export * from './formula-problem.js';
+export * from './role-cap.js';
+export * from './fill-status.js';

package/dist/composition/cards/role-cap.d.ts

@@ -0,0 +1 @@
+export declare function primaryCapForRole(role: string | null): string | null;

package/dist/composition/composition-report.d.ts

@@ -308,6 +308,7 @@ export type CompositionValidation = z.infer<typeof CompositionValidationSchema>;
 export declare const CompositionRunStatusSchema: z.ZodEnum<{
     degraded: "degraded";
     failed: "failed";
+    incomplete: "incomplete";
     running: "running";
     starting: "starting";
     stopped: "stopped";
@@ -342,6 +343,7 @@ export declare const CompositionBlockStateSchema: z.ZodObject<{
     status: z.ZodEnum<{
         degraded: "degraded";
         failed: "failed";
+        incomplete: "incomplete";
         running: "running";
         starting: "starting";
         stopped: "stopped";

package/dist/composition/index.d.ts

@@ -14,3 +14,4 @@ export * from './expression-kinds.js';
 export * from './presets/numeric-transforms.js';
 export * from './state-fields.js';
 export * from './validate-composition.js';
+export * from './cards/index.js';

package/dist/composition/presets/numeric-transforms.d.ts

@@ -16,4 +16,6 @@ export interface ConvertPresetInput {
     /** Cap top-level `unit` field replaced with `to`; null when the cap has none. */
     readonly unitField: string | null;
 }
+/** `unit` when converting that cap's primary numeric field; otherwise none. */
+export declare function unitCompanionField(cap: string, fieldPath: string): string | null;
 export declare function convertPresetFeature(input: ConvertPresetInput): CompositionFieldsFeature | null;