@fastybird/smart-panel-backend 1.1.0-alpha.0 → 1.1.0-alpha.10

package/dist/modules/devices/services/property-command-window.service.d.ts

@@ -0,0 +1,71 @@
+import { PropertyValueState } from '../models/property-value-state.model';
+import { PropertyCommandValue } from '../utils/property-command-value.utils';
+export declare const PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = 1500;
+export type PropertyCommandWindowState = 'pending' | 'confirmed_grace';
+export interface PropertyCommandWindowTarget {
+    readonly deviceId: string;
+    readonly channelId: string;
+    readonly propertyId: string;
+}
+export interface PropertyCommandWindowHandle {
+    readonly canonicalPropertyId: string;
+    readonly generation: string;
+}
+export interface PropertyCommandReceipt {
+    readonly value: PropertyCommandValue;
+    readonly receivedAt: number;
+}
+export interface PropertyCommandPatchReceipt {
+    readonly baseline: PropertyValueState;
+    readonly optimisticState: PropertyValueState;
+}
+export interface PropertyCommandWindow {
+    readonly canonicalTarget: PropertyCommandWindowTarget;
+    readonly requestedTargets: readonly PropertyCommandWindowTarget[];
+    readonly generation: string;
+    readonly intentId: string | null;
+    readonly commandedValue: PropertyCommandValue;
+    readonly previousValue: PropertyCommandValue | null;
+    readonly lastReceipt: PropertyCommandReceipt | null;
+    readonly heldReceipt: PropertyCommandReceipt | null;
+    readonly recoveryReceipt: PropertyCommandReceipt | null;
+    readonly rollbackBaseline: PropertyValueState | null;
+    readonly patchReceipt: PropertyCommandPatchReceipt | null;
+    readonly openedAt: number;
+    readonly expiresAt: number;
+    readonly state: PropertyCommandWindowState;
+    readonly confirmedAt: number | null;
+    readonly confirmationExpiresAt: number | null;
+}
+export interface OpenPropertyCommandWindowInput {
+    readonly canonicalTarget: PropertyCommandWindowTarget;
+    readonly requestedTargets: readonly PropertyCommandWindowTarget[];
+    readonly intentId?: string;
+    readonly commandedValue: PropertyCommandValue;
+    readonly previousValue: PropertyCommandValue | null;
+    readonly ttlMs: number;
+}
+export declare class PropertyCommandWindowService {
+    private readonly windows;
+    private readonly recoveries;
+    open(input: OpenPropertyCommandWindowInput): PropertyCommandWindowHandle;
+    get(canonicalPropertyId: string): PropertyCommandWindow | null;
+    peekGeneration(canonicalPropertyId: string): string | undefined;
+    confirm(handle: PropertyCommandWindowHandle, receipt: PropertyCommandReceipt): PropertyCommandWindow | null;
+    attachPatchReceipt(handle: PropertyCommandWindowHandle, receipt: PropertyCommandPatchReceipt): boolean;
+    hold(handle: PropertyCommandWindowHandle, receipt: PropertyCommandReceipt): PropertyCommandWindow | null;
+    close(handle: PropertyCommandWindowHandle): boolean;
+    fail(handle: PropertyCommandWindowHandle): boolean;
+    sweep(): readonly PropertyCommandWindowHandle[];
+    expire(canonicalPropertyId: string): PropertyCommandWindowHandle | null;
+    getRecovery(handle: PropertyCommandWindowHandle): PropertyCommandWindow | null;
+    completeRecovery(handle: PropertyCommandWindowHandle): boolean;
+    cancelRecovery(canonicalPropertyId: string): void;
+    cancel(canonicalPropertyId: string): void;
+    clear(): void;
+    private getCurrent;
+    private isExpired;
+    private detach;
+    private pruneRecoveries;
+    private toSnapshot;
+}

package/dist/modules/devices/services/property-command-window.service.js

@@ -0,0 +1,204 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PropertyCommandWindowService = exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const property_value_state_model_1 = require("../models/property-value-state.model");
+exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS = 1_500;
+let PropertyCommandWindowService = class PropertyCommandWindowService {
+    constructor() {
+        this.windows = new Map();
+        this.recoveries = new Map();
+    }
+    open(input) {
+        const now = Date.now();
+        const canonicalPropertyId = input.canonicalTarget.propertyId;
+        const current = this.getCurrent(canonicalPropertyId, now);
+        const ttlMs = Number.isFinite(input.ttlMs) && input.ttlMs > 0 ? input.ttlMs : 3_000;
+        const generation = (0, node_crypto_1.randomUUID)();
+        const previousValue = current?.commandedValue ?? input.previousValue;
+        this.recoveries.delete(canonicalPropertyId);
+        this.windows.set(canonicalPropertyId, {
+            canonicalTarget: freezeTarget(input.canonicalTarget),
+            requestedTargets: input.requestedTargets.map(freezeTarget),
+            generation,
+            intentId: input.intentId ?? null,
+            commandedValue: input.commandedValue,
+            previousValue,
+            lastReceipt: null,
+            heldReceipt: null,
+            recoveryReceipt: null,
+            rollbackBaseline: current?.rollbackBaseline ?? current?.patchReceipt?.baseline ?? null,
+            patchReceipt: null,
+            openedAt: now,
+            expiresAt: now + ttlMs,
+            state: 'pending',
+            confirmedAt: null,
+            confirmationExpiresAt: null,
+        });
+        return Object.freeze({ canonicalPropertyId, generation });
+    }
+    get(canonicalPropertyId) {
+        return this.toSnapshot(this.getCurrent(canonicalPropertyId, Date.now()));
+    }
+    peekGeneration(canonicalPropertyId) {
+        const current = this.windows.get(canonicalPropertyId);
+        return current !== undefined && current.expiresAt > Date.now() ? current.generation : undefined;
+    }
+    confirm(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation) {
+            return null;
+        }
+        if (current.state === 'pending') {
+            current.state = 'confirmed_grace';
+            current.confirmedAt = receipt.receivedAt;
+            current.confirmationExpiresAt = receipt.receivedAt + exports.PROPERTY_COMMAND_CONFIRMATION_GRACE_MS;
+            current.lastReceipt = freezeReceipt(receipt);
+            current.heldReceipt = null;
+            current.rollbackBaseline = null;
+            current.patchReceipt = null;
+        }
+        return this.toSnapshot(current);
+    }
+    attachPatchReceipt(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return false;
+        }
+        const baseline = current.rollbackBaseline ?? receipt.baseline;
+        current.rollbackBaseline = freezeValueState(baseline);
+        current.patchReceipt = freezePatchReceipt({
+            baseline,
+            optimisticState: receipt.optimisticState,
+        });
+        return true;
+    }
+    hold(handle, receipt) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return null;
+        }
+        current.heldReceipt = freezeReceipt(receipt);
+        return this.toSnapshot(current);
+    }
+    close(handle) {
+        const current = this.windows.get(handle.canonicalPropertyId);
+        if (current !== undefined && current.generation === handle.generation) {
+            this.windows.delete(handle.canonicalPropertyId);
+            return true;
+        }
+        return false;
+    }
+    fail(handle) {
+        const current = this.getCurrent(handle.canonicalPropertyId, Date.now());
+        if (current === undefined || current.generation !== handle.generation || current.state !== 'pending') {
+            return false;
+        }
+        this.detach(handle.canonicalPropertyId, current);
+        return true;
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [canonicalPropertyId, window] of this.windows) {
+            if (!this.isExpired(window, now)) {
+                continue;
+            }
+            this.detach(canonicalPropertyId, window);
+        }
+        this.pruneRecoveries(now);
+        return Object.freeze([...this.recoveries.entries()].map(([canonicalPropertyId, recovery]) => Object.freeze({ canonicalPropertyId, generation: recovery.window.generation })));
+    }
+    expire(canonicalPropertyId) {
+        const current = this.windows.get(canonicalPropertyId);
+        if (current === undefined || !this.isExpired(current, Date.now())) {
+            return null;
+        }
+        this.detach(canonicalPropertyId, current);
+        return Object.freeze({ canonicalPropertyId, generation: current.generation });
+    }
+    getRecovery(handle) {
+        this.pruneRecoveries(Date.now());
+        const recovery = this.recoveries.get(handle.canonicalPropertyId);
+        return recovery?.window.generation === handle.generation ? this.toSnapshot(recovery.window) : null;
+    }
+    completeRecovery(handle) {
+        const recovery = this.recoveries.get(handle.canonicalPropertyId);
+        if (recovery === undefined || recovery.window.generation !== handle.generation) {
+            return false;
+        }
+        this.recoveries.delete(handle.canonicalPropertyId);
+        return true;
+    }
+    cancelRecovery(canonicalPropertyId) {
+        this.recoveries.delete(canonicalPropertyId);
+    }
+    cancel(canonicalPropertyId) {
+        this.windows.delete(canonicalPropertyId);
+        this.recoveries.delete(canonicalPropertyId);
+    }
+    clear() {
+        this.windows.clear();
+        this.recoveries.clear();
+    }
+    getCurrent(canonicalPropertyId, now) {
+        const current = this.windows.get(canonicalPropertyId);
+        if (current !== undefined && this.isExpired(current, now)) {
+            this.detach(canonicalPropertyId, current);
+            return undefined;
+        }
+        return current;
+    }
+    isExpired(window, now) {
+        return now >= (window.confirmationExpiresAt ?? window.expiresAt);
+    }
+    detach(canonicalPropertyId, window, now = Date.now()) {
+        this.windows.delete(canonicalPropertyId);
+        if (window.state === 'pending' && (window.heldReceipt !== null || window.patchReceipt !== null)) {
+            this.recoveries.set(canonicalPropertyId, {
+                window,
+                deadlineAt: now + (window.expiresAt - window.openedAt),
+            });
+        }
+    }
+    pruneRecoveries(now) {
+        for (const [canonicalPropertyId, recovery] of this.recoveries) {
+            if (now >= recovery.deadlineAt) {
+                this.recoveries.delete(canonicalPropertyId);
+            }
+        }
+    }
+    toSnapshot(window) {
+        if (window === undefined) {
+            return null;
+        }
+        return Object.freeze({
+            ...window,
+            canonicalTarget: freezeTarget(window.canonicalTarget),
+            requestedTargets: Object.freeze(window.requestedTargets.map(freezeTarget)),
+            lastReceipt: window.lastReceipt === null ? null : freezeReceipt(window.lastReceipt),
+            heldReceipt: window.heldReceipt === null ? null : freezeReceipt(window.heldReceipt),
+            recoveryReceipt: window.recoveryReceipt === null ? null : freezeReceipt(window.recoveryReceipt),
+            rollbackBaseline: window.rollbackBaseline === null ? null : freezeValueState(window.rollbackBaseline),
+            patchReceipt: window.patchReceipt === null ? null : freezePatchReceipt(window.patchReceipt),
+        });
+    }
+};
+exports.PropertyCommandWindowService = PropertyCommandWindowService;
+exports.PropertyCommandWindowService = PropertyCommandWindowService = __decorate([
+    (0, common_1.Injectable)()
+], PropertyCommandWindowService);
+const freezeTarget = (target) => Object.freeze({ ...target });
+const freezeReceipt = (receipt) => Object.freeze({ ...receipt });
+const freezePatchReceipt = (receipt) => Object.freeze({
+    baseline: freezeValueState(receipt.baseline),
+    optimisticState: freezeValueState(receipt.optimisticState),
+});
+const freezeValueState = (state) => Object.freeze(new property_value_state_model_1.PropertyValueState(state.value, state.lastUpdated, state.trend));
+//# sourceMappingURL=property-command-window.service.js.map

package/dist/modules/devices/services/property-command-window.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"property-command-window.service.js","sourceRoot":"","sources":["../../../../src/modules/devices/services/property-command-window.service.ts"],"names":[],"mappings":"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"}

package/dist/modules/devices/services/property-command.service.d.ts

@@ -2,15 +2,27 @@ import { IntentContext } from '../../intents/models/intent.model';
 import { IntentsService } from '../../intents/services/intents.service';
 import { ClientUserDto } from '../../websocket/dto/client-user.dto';
 import { UpdateChannelPropertyDto } from '../dto/update-channel-property.dto';
-import { ChannelPropertyEntity, DeviceEntity } from '../entities/devices.entity';
+import { ChannelEntity, ChannelPropertyEntity, DeviceEntity } from '../entities/devices.entity';
+import { PropertyValueState } from '../models/property-value-state.model';
 import { PropertyCommandValue } from '../utils/property-command-value.utils';
 import { ChannelsPropertiesService } from './channels.properties.service';
 import { ChannelsService } from './channels.service';
+import { CommandLatencyTraceCollectorService } from './command-latency-trace-collector.service';
 import { DevicesService } from './devices.service';
 import { PlatformRegistryService } from './platform.registry.service';
+import { PropertyCommandDispatchService } from './property-command-dispatch.service';
+import { PropertyCommandWindowHandle, PropertyCommandWindowService } from './property-command-window.service';
 export interface PropertyCommandExecutionOptions {
     requestId?: string;
     context?: IntentContext;
+    apiReceipt?: ApiPropertyCommandReceipt;
+}
+export interface ApiPropertyCommandReceipt {
+    readonly handle: PropertyCommandWindowHandle;
+    readonly canonicalPropertyId: string;
+    readonly baseline: PropertyValueState | null;
+    readonly optimisticEligible: boolean;
+    readonly ttlMs: number;
 }
 export interface DevicePropertyCommandResult {
     device: string;
@@ -23,14 +35,21 @@ export interface SinglePropertyCommandResult extends DevicePropertyCommandResult
     property?: string;
     value?: PropertyCommandValue;
 }
+export interface PropertyBatchCommandResult {
+    success: boolean;
+    results: SinglePropertyCommandResult[];
+}
 export declare class PropertyCommandService {
     private readonly devicesService;
     private readonly channelsService;
     private readonly channelsPropertiesService;
     private readonly platformRegistryService;
     private readonly intentsService;
+    private readonly propertyCommandDispatchService;
+    private readonly propertyCommandWindowService;
+    private readonly commandLatencyTraceCollector;
     private readonly logger;
-    constructor(devicesService: DevicesService, channelsService: ChannelsService, channelsPropertiesService: ChannelsPropertiesService, platformRegistryService: PlatformRegistryService, intentsService: IntentsService);
+    constructor(devicesService: DevicesService, channelsService: ChannelsService, channelsPropertiesService: ChannelsPropertiesService, platformRegistryService: PlatformRegistryService, intentsService: IntentsService, propertyCommandDispatchService: PropertyCommandDispatchService, propertyCommandWindowService: PropertyCommandWindowService, commandLatencyTraceCollector?: CommandLatencyTraceCollectorService);
     handleInternal(user: ClientUserDto, payload?: object): Promise<{
         success: boolean;
         results: Array<{
@@ -40,9 +59,15 @@ export declare class PropertyCommandService {
         }> | string;
     }>;
     executePropertyCommandById(propertyId: string, rawValue: unknown, options?: PropertyCommandExecutionOptions): Promise<SinglePropertyCommandResult>;
+    executePropertyCommands(commands: Array<{
+        propertyId: string;
+        value: unknown;
+    }>, options?: PropertyCommandExecutionOptions): Promise<PropertyBatchCommandResult>;
     private executeCommands;
     private resolveCommandIntentTtlMs;
     private processDeviceCommands;
-    processApiPropertyCommand(deviceId: string, channelId: string, propertyId: string, value: string | number | boolean): Promise<void>;
+    processApiPropertyCommand(deviceId: string, channelId: string, propertyId: string, value: string | number | boolean, receipt?: ApiPropertyCommandReceipt): Promise<void>;
+    prepareApiPropertyCommand(device: DeviceEntity | string, channel: ChannelEntity, property: ChannelPropertyEntity, value: string | number | boolean): Promise<ApiPropertyCommandReceipt | null>;
+    failApiPropertyCommandReceipt(receipt: ApiPropertyCommandReceipt): void;
     usesAuthoritativePropertyReadback(device: DeviceEntity | string, property: ChannelPropertyEntity, update?: UpdateChannelPropertyDto): Promise<boolean>;
 }

package/dist/modules/devices/services/property-command.service.js

@@ -8,6 +8,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PropertyCommandService = void 0;
 const class_validator_1 = require("class-validator");
@@ -24,15 +27,21 @@ const property_command_dto_1 = require("../dto/property-command.dto");
 const property_command_value_utils_1 = require("../utils/property-command-value.utils");
 const channels_properties_service_1 = require("./channels.properties.service");
 const channels_service_1 = require("./channels.service");
+const command_latency_trace_collector_service_1 = require("./command-latency-trace-collector.service");
 const devices_service_1 = require("./devices.service");
 const platform_registry_service_1 = require("./platform.registry.service");
+const property_command_dispatch_service_1 = require("./property-command-dispatch.service");
+const property_command_window_service_1 = require("./property-command-window.service");
 let PropertyCommandService = class PropertyCommandService {
-    constructor(devicesService, channelsService, channelsPropertiesService, platformRegistryService, intentsService) {
+    constructor(devicesService, channelsService, channelsPropertiesService, platformRegistryService, intentsService, propertyCommandDispatchService, propertyCommandWindowService, commandLatencyTraceCollector = new command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService()) {
         this.devicesService = devicesService;
         this.channelsService = channelsService;
         this.channelsPropertiesService = channelsPropertiesService;
         this.platformRegistryService = platformRegistryService;
         this.intentsService = intentsService;
+        this.propertyCommandDispatchService = propertyCommandDispatchService;
+        this.propertyCommandWindowService = propertyCommandWindowService;
+        this.commandLatencyTraceCollector = commandLatencyTraceCollector;
         this.logger = (0, extension_logger_service_1.createExtensionLogger)(devices_constants_1.DEVICES_MODULE_NAME, 'PropertyCommandService');
     }
     async handleInternal(user, payload) {
@@ -129,6 +138,121 @@ let PropertyCommandService = class PropertyCommandService {
             reason: result?.reason ?? (typeof execution.results === 'string' ? execution.results : undefined),
         };
     }
+    async executePropertyCommands(commands, options = {}) {
+        if (commands.length === 0) {
+            return { success: true, results: [] };
+        }
+        const resolved = [];
+        let targetDeviceId = null;
+        for (const cmd of commands) {
+            const property = await this.channelsPropertiesService.findOne(cmd.propertyId);
+            if (!property) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: '',
+                        success: false,
+                        property: c.propertyId,
+                        reason: c.propertyId === cmd.propertyId ? 'Property not found' : 'Batch aborted due to invalid property',
+                    })),
+                };
+            }
+            const propertyChannel = property.channel;
+            const channel = typeof propertyChannel === 'string' ? await this.channelsService.findOne(propertyChannel) : propertyChannel;
+            if (!channel) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: '',
+                        success: false,
+                        property: c.propertyId,
+                        reason: c.propertyId === cmd.propertyId ? 'Channel not found' : 'Batch aborted due to invalid channel',
+                    })),
+                };
+            }
+            const channelDevice = channel.device;
+            const device = typeof channelDevice === 'string' ? await this.devicesService.findOne(channelDevice) : channelDevice;
+            if (!device) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: '',
+                        success: false,
+                        property: c.propertyId,
+                        reason: c.propertyId === cmd.propertyId ? 'Device not found' : 'Batch aborted due to invalid device',
+                    })),
+                };
+            }
+            if (targetDeviceId === null) {
+                targetDeviceId = device.id;
+            }
+            else if (targetDeviceId !== device.id) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: device.id,
+                        success: false,
+                        property: c.propertyId,
+                        reason: `Single-device batch execution violation: properties belong to multiple devices (${targetDeviceId} vs ${device.id})`,
+                    })),
+                };
+            }
+            if (!property.permissions.some((permission) => [devices_constants_1.PermissionType.READ_WRITE, devices_constants_1.PermissionType.WRITE_ONLY].includes(permission))) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: device.id,
+                        success: false,
+                        property: c.propertyId,
+                        reason: c.propertyId === cmd.propertyId ? 'Property is not writable' : 'Batch aborted: property not writable',
+                    })),
+                };
+            }
+            const validation = (0, property_command_value_utils_1.validatePropertyCommandValue)(property, cmd.value);
+            if (!validation.valid || validation.value === undefined) {
+                return {
+                    success: false,
+                    results: commands.map((c) => ({
+                        device: device.id,
+                        success: false,
+                        property: c.propertyId,
+                        reason: c.propertyId === cmd.propertyId
+                            ? (validation.reason ?? 'Invalid property value')
+                            : 'Batch aborted: invalid value',
+                    })),
+                };
+            }
+            resolved.push({
+                propertyId: cmd.propertyId,
+                property,
+                channel,
+                device,
+                value: validation.value,
+            });
+        }
+        const propertyCommandDtos = resolved.map((r) => ({
+            device: r.device.id,
+            channel: r.channel.id,
+            property: r.property.id,
+            value: r.value,
+        }));
+        const execution = await this.executeCommands(propertyCommandDtos, options);
+        const deviceResult = Array.isArray(execution.results) ? execution.results[0] : undefined;
+        const executionSuccess = execution.success && (deviceResult?.success ?? false);
+        const results = resolved.map((r) => ({
+            device: r.device.id,
+            deviceName: r.device.name,
+            channel: r.channel.id,
+            property: r.property.id,
+            value: r.value,
+            success: executionSuccess,
+            reason: deviceResult?.reason ?? (typeof execution.results === 'string' ? execution.results : undefined),
+        }));
+        return {
+            success: executionSuccess,
+            results,
+        };
+    }
     async executeCommands(commands, options) {
         const targets = commands.map((command) => ({
             deviceId: command.device,
@@ -146,19 +270,29 @@ let PropertyCommandService = class PropertyCommandService {
             }
             groupedProperties[prop.device].push(prop);
         });
+        const ttlMs = options.apiReceipt?.ttlMs ?? (await this.resolveCommandIntentTtlMs(groupedProperties));
         const intent = this.intentsService.createIntent({
             requestId: options.requestId,
             type: intents_constants_1.IntentType.DEVICE_SET_PROPERTY,
             context: options.context,
             targets,
             value: valueMap,
-            ttlMs: await this.resolveCommandIntentTtlMs(groupedProperties),
+            ttlMs,
         });
         this.logger.log(`Created intent ${intent.id} for ${targets.length} target(s)${options.requestId ? ` requestId=${options.requestId}` : ''}`);
+        this.commandLatencyTraceCollector.observeCommand({
+            requestId: options.requestId,
+            intentId: intent.id,
+            properties: commands,
+        });
         const results = [];
         try {
             for (const deviceId of Object.keys(groupedProperties)) {
-                const result = await this.processDeviceCommands(deviceId, groupedProperties[deviceId]);
+                const result = await this.processDeviceCommands(deviceId, groupedProperties[deviceId], {
+                    intentId: intent.id,
+                    ttlMs,
+                    windowHandles: options.apiReceipt === undefined ? undefined : [options.apiReceipt.handle],
+                });
                 results.push(result);
             }
             const intentResults = [];
@@ -206,7 +340,7 @@ let PropertyCommandService = class PropertyCommandService {
         }
         return this.platformRegistryService.getCommandTtlMs(executions, intents_constants_1.DEFAULT_TTL_DEVICE_COMMAND);
     }
-    async processDeviceCommands(deviceId, commands) {
+    async processDeviceCommands(deviceId, commands, dispatchOptions) {
         const device = await this.devicesService.findOne(deviceId);
         if (!device) {
             this.logger.warn(`Device not found id=${deviceId}`);
@@ -246,22 +380,45 @@ let PropertyCommandService = class PropertyCommandService {
             propertyUpdates.push({ device, channel, property, value: validation.value });
         }
         this.logger.log(`Processing batch of ${propertyUpdates.length} commands for deviceId=${device.id}`);
-        const success = await platform.processBatch(propertyUpdates);
-        if (!success) {
+        const dispatch = await this.propertyCommandDispatchService.dispatchBatch(propertyUpdates, dispatchOptions);
+        if (!dispatch.success) {
             this.logger.error(`Batch command execution failed for deviceId=${device.id}`);
-            return { device: deviceId, success: false, reason: 'Execution failed' };
+            return { device: deviceId, success: false, reason: dispatch.reason ?? 'Execution failed' };
         }
         this.logger.log(`Successfully executed batch command for deviceId=${device.id}`);
         return { device: deviceId, success: true };
     }
-    async processApiPropertyCommand(deviceId, channelId, propertyId, value) {
-        const execution = await this.executeCommands([{ device: deviceId, channel: channelId, property: propertyId, value }], { context: { origin: 'api' } });
+    async processApiPropertyCommand(deviceId, channelId, propertyId, value, receipt) {
+        const execution = await this.executeCommands([{ device: deviceId, channel: channelId, property: propertyId, value }], { context: { origin: 'api' }, apiReceipt: receipt });
         const result = Array.isArray(execution.results) ? execution.results[0] : undefined;
         if (!execution.success) {
+            if (receipt !== undefined) {
+                this.propertyCommandWindowService.fail(receipt.handle);
+            }
             const reason = result?.reason ?? (typeof execution.results === 'string' ? execution.results : 'Execution failed');
             this.logger.warn(`[API Command] Failed for deviceId=${deviceId}: ${reason}`);
         }
     }
+    async prepareApiPropertyCommand(device, channel, property, value) {
+        try {
+            const resolvedDevice = typeof device === 'string' ? await this.devicesService.findOne(device) : device;
+            if (resolvedDevice === null) {
+                return null;
+            }
+            const ttlMs = await this.resolveCommandIntentTtlMs({
+                [resolvedDevice.id]: [{ device: resolvedDevice.id, channel: channel.id, property: property.id, value }],
+            });
+            const prepared = await this.propertyCommandDispatchService.prepareApiCommand({ device: resolvedDevice, channel, property, value }, ttlMs);
+            return prepared === null ? null : { ...prepared, ttlMs };
+        }
+        catch (error) {
+            this.logger.warn(`[API Command] Could not prepare optimistic receipt for propertyId=${property.id}: ${error instanceof Error ? error.message : String(error)}`);
+            return null;
+        }
+    }
+    failApiPropertyCommandReceipt(receipt) {
+        this.propertyCommandWindowService.fail(receipt.handle);
+    }
     async usesAuthoritativePropertyReadback(device, property, update) {
         const resolvedDevice = typeof device === 'string' ? await this.devicesService.findOne(device) : device;
         const effectiveProperty = update
@@ -274,10 +431,14 @@ let PropertyCommandService = class PropertyCommandService {
 exports.PropertyCommandService = PropertyCommandService;
 exports.PropertyCommandService = PropertyCommandService = __decorate([
     (0, common_1.Injectable)(),
+    __param(7, (0, common_1.Optional)()),
     __metadata("design:paramtypes", [devices_service_1.DevicesService,
         channels_service_1.ChannelsService,
         channels_properties_service_1.ChannelsPropertiesService,
         platform_registry_service_1.PlatformRegistryService,
-        intents_service_1.IntentsService])
+        intents_service_1.IntentsService,
+        property_command_dispatch_service_1.PropertyCommandDispatchService,
+        property_command_window_service_1.PropertyCommandWindowService,
+        command_latency_trace_collector_service_1.CommandLatencyTraceCollectorService])
 ], PropertyCommandService);
 //# sourceMappingURL=property-command.service.js.map