@awarevue/api-types 2.0.22 → 2.0.24

package/dist/api/agent-protocol/protocol.js

@@ -0,0 +1,382 @@
+import { sDeviceDiscoveryDto } from '../../objects/device/device-import';
+import { z } from 'zod';
+import { sCreateAccessRuleRequest, sCreatePersonRequest, sCreateScheduleRequest, sCreateZoneRequest, } from '../rest';
+import { sAgentDeviceInfo } from '../../primitives';
+import { sProviderSpecs, sAccessControlCapabilityReport, sAccessObjectKind, } from '../../objects/agent-metadata';
+// PROTOCOL ENVELOPE
+export const sMessageHeader = z.object({
+    version: z.number().describe('Protocol version'),
+    id: z.string().nonempty('ID is required').describe('Unique message ID'),
+    from: z
+        .string()
+        .nonempty('Agent name required')
+        .describe("Sender ID (Agent ID or 'server')"),
+    on: z.number().describe('Timestamp in milliseconds since epoch'),
+});
+export const sMessageWithPayload = (sPayload) => sMessageHeader.and(sPayload).describe('Message with payload');
+export const sResponsePayload = (kind, sPayload) => 
+// success branch
+z.object({ requestId: z.string().nonempty(), kind }).and(sPayload);
+export const sAgentErrorCode = z.enum(['NOT_SUPPORTED', 'TIMEOUT']);
+export const sErrorPayload = sResponsePayload(z.literal('error-rs'), z.object({
+    error: z.string().nonempty().describe('Error message if request failed'),
+    code: sAgentErrorCode.optional().describe('Optional error code'),
+}));
+// REGISTER
+export const sRegisterRq = z.object({
+    kind: z.literal('register'),
+    providers: z
+        .record(sProviderSpecs)
+        .describe('Map of providers and their specs, ones that the agent can handle'),
+    accessControlProviders: z.record(sAccessControlCapabilityReport).optional(),
+});
+export const sRegisterRs = sResponsePayload(z.literal('register-rs'), z.object({}));
+// UNREGISTER
+export const sUnregister = z
+    .object({
+    kind: z.literal('unregister'),
+    provider: z.string().nonempty(),
+})
+    .describe('Request to unregister a provider');
+// VALIDATE PROVIDER CONFIG
+export const sValidateProviderConfigRq = z.object({
+    kind: z.literal('validate-config'),
+    provider: z.string().nonempty(),
+    config: z.record(z.unknown()),
+});
+export const sConfigurationIssue = z
+    .object({
+    paths: z.array(z.string()),
+    message: z.string(),
+})
+    .describe('A configuration issue that can be reported by agents');
+export const sValidateProviderConfigRs = sResponsePayload(z.literal('validate-config-rs'), z.object({
+    issues: z.array(sConfigurationIssue),
+})).describe('Validation result for provider configuration');
+// START SERVICE
+export const sStartServiceRq = z
+    .object({
+    kind: z.literal('start'),
+    provider: z.string().nonempty(),
+    config: z.record(z.unknown()),
+    lastEventForeignRef: z
+        .string()
+        .nullable()
+        .describe('Last event foreign reference that the agent should start from'),
+    lastEventTimestamp: z
+        .number()
+        .nullable()
+        .describe('Last event timestamp that the agent should start from'),
+})
+    .describe('Request to start a service for a provider');
+export const sStartServiceRs = sResponsePayload(z.literal('start-rs'), z.object({})).describe('Response for starting a service for a provider');
+// STOP SERVICE
+export const sStopServiceRq = z
+    .object({
+    kind: z.literal('stop'),
+    provider: z.string().nonempty(),
+})
+    .describe('Request to stop a service for a provider');
+export const sStopServiceRs = sResponsePayload(z.literal('stop-rs'), z.object({})).describe('Response for starting a service for a provider');
+// RUN COMMAND
+export const sRunCommandRq = z
+    .object({
+    kind: z.literal('command'),
+    device: sAgentDeviceInfo,
+    command: z.string().nonempty(),
+    batchId: z
+        .string()
+        .optional()
+        .describe('Batch ID for the command of the command was part of a macro'),
+    params: z.record(z.unknown()).optional(),
+})
+    .describe('Request to run a device command');
+export const sRunCommandRs = sResponsePayload(z.literal('command-rs'), z.object({})).describe('Response for running a device command');
+// QUERIES
+export const sQueryRq = z.object({
+    kind: z.literal('query'),
+    query: z.string().nonempty(),
+    device: sAgentDeviceInfo,
+    args: z.unknown().describe('Query arguments, depends on the query type'),
+});
+export const sQueryRs = sResponsePayload(z.literal('query-rs'), z.object({
+    result: z.unknown().describe('Query result, depends on the query type'),
+})).describe('Response for a query');
+// FILE PUSH INSTRUCTIONS
+export const sPushFile = z
+    .object({
+    kind: z.literal('push-file'),
+    query: z.string().nonempty(),
+    device: sAgentDeviceInfo,
+    args: z.unknown().describe('Query arguments, depends on the query type'),
+    url: z.string().nonempty().describe('URL to pull the file from'),
+})
+    .describe('Instruction to push a file from an agent to file relay');
+// PUSH DEVICE STATE UPDATE
+export const sPushStateUpdateRq = z
+    .object({
+    kind: z.literal('state'),
+    foreignRef: z.string().nonempty(),
+    provider: z.string().nonempty(),
+    mergeProps: z.record(z.unknown()),
+    removeProps: z.array(z.string().nonempty()),
+})
+    .describe('Request to push a device state update');
+export const sPushStateUpdateRs = sResponsePayload(z.literal('state-rs'), z.object({})).describe('Response for pushing a device state update');
+// PUSH DEVICE EVENT
+export const sPushEventRq = z
+    .object({
+    kind: z.literal('event'),
+    foreignRef: z.string().nonempty(),
+    provider: z.string().nonempty(),
+    eventTimestamp: z
+        .number()
+        .describe('Event timestamp in milliseconds since epoch, as reported by origin'),
+    eventForeignRef: z.string().nonempty(),
+    event: z.unknown().describe('Event data'),
+})
+    .describe('Request to push a device event');
+export const sPushEventRs = sResponsePayload(z.literal('event-rs'), z.object({})).describe('Response for pushing a device event');
+// REQUEST AVAILABLE DEVICES (DISCOVERY)
+export const sGetAvailableDevicesRq = z
+    .object({
+    kind: z.literal('get-available-devices'),
+    provider: z.string().nonempty(),
+})
+    .describe('Request to get available devices from a provider via an agent');
+export const sGetAvailableDevicesRs = sResponsePayload(z.literal('get-available-devices-rs'), sDeviceDiscoveryDto).describe('Response for getting available devices from a provider via an agent');
+// ACCESS SYNC SECTION
+// ————————————————————————————————————————————————————
+// Merge (insert vs update) variants, all listed explicitly
+// ————————————————————————————————————————————————————
+export const sObjectMerge = z
+    .union([
+    // accessRule insert
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('accessRule'),
+        original: z.null(),
+        props: sCreateAccessRuleRequest,
+    }),
+    // accessRule update
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('accessRule'),
+        original: sCreateAccessRuleRequest,
+        props: sCreateAccessRuleRequest.partial(),
+    }),
+    // schedule insert
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('schedule'),
+        original: z.null(),
+        props: sCreateScheduleRequest,
+    }),
+    // schedule update
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('schedule'),
+        original: sCreateScheduleRequest,
+        props: sCreateScheduleRequest.partial(),
+    }),
+    // person insert
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('person'),
+        original: z.null(),
+        props: sCreatePersonRequest,
+    }),
+    // person update
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('person'),
+        original: sCreatePersonRequest,
+        props: sCreatePersonRequest.partial(),
+    }),
+    // zone insert
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('zone'),
+        original: z.null(),
+        props: sCreateZoneRequest,
+    }),
+    // zone update
+    z.object({
+        kind: z.literal('merge'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('zone'),
+        original: sCreateZoneRequest,
+        props: sCreateZoneRequest.partial(),
+    }),
+])
+    .describe('Object merge request');
+// ————————————————————————————————————————————————————
+// Delete variants, also fully expanded
+// ————————————————————————————————————————————————————
+export const sObjectDelete = z
+    .union([
+    z.object({
+        kind: z.literal('delete'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('accessRule'),
+        original: sCreateAccessRuleRequest,
+    }),
+    z.object({
+        kind: z.literal('delete'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('schedule'),
+        original: sCreateScheduleRequest,
+    }),
+    z.object({
+        kind: z.literal('delete'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('person'),
+        original: sCreatePersonRequest,
+    }),
+    z.object({
+        kind: z.literal('delete'),
+        objectId: z.string().nonempty().describe('Object ID as in backend'),
+        objectKind: z.literal('zone'),
+        original: sCreateZoneRequest,
+    }),
+])
+    .describe('Object delete request');
+export const sAccessMutation = z
+    .union([sObjectMerge, sObjectDelete])
+    .describe('Access object change description');
+export const sDeviceMap = z
+    .record(z.record(z.unknown()))
+    .describe('Map of devices (readers) and their stashed provider metadata');
+export const sRefMap = z
+    .record(z.record(z.array(z.string().nonempty())))
+    .describe('Map of foreign references to object IDs');
+// A. VALIDATE ACCESS CHANGES
+export const sValidateChangeRq = z
+    .object({
+    kind: z.literal('validate-change'),
+    provider: z.string().nonempty(),
+    devices: sDeviceMap,
+    refMap: sRefMap,
+    mutations: z.array(sAccessMutation),
+})
+    .describe('Request to validate access changes');
+export const sChangeIssueCode = z.enum([
+    'BAD_REFERENCE',
+    'NOT_FOUND',
+    'NOT_UNIQUE',
+    'INVALID',
+    'NOT_SUPPORTED',
+]);
+export const sChangeIssue = z
+    .object({
+    objectId: z.string().optional().describe('Object ID as in backend'),
+    objectKind: sAccessObjectKind.optional(),
+    code: sChangeIssueCode
+        .optional()
+        .describe('Issue code that describes the issue to UI agent(s) or bots'),
+    path: z
+        .string()
+        .optional()
+        .describe('Path - inside object referenced by ObjectID, points to a field or a related object'),
+    index: z
+        .number()
+        .optional()
+        .describe('Index ofa value in field pointed at by path'),
+    message: z
+        .string()
+        .optional()
+        .describe('Message that describes the issue to user or the details of what went wrong'),
+})
+    .describe('Access change issue description');
+export const sValidateChangeRs = sResponsePayload(z.literal('validate-change-rs'), z.object({
+    issues: z.array(sChangeIssue),
+})).describe('Response for validating access changes');
+// B. APPLY ACCESS CHANGES
+export const sApplyChange = z
+    .object({
+    kind: z.literal('apply-change'),
+    provider: z.string().nonempty(),
+    devices: sDeviceMap,
+    refMap: sRefMap,
+    mutations: z.array(sAccessMutation),
+})
+    .describe('Request to apply access changes');
+export const sApplyChangeRs = sResponsePayload(z.literal('apply-change-rs'), z.object({
+    requestId: z.string().nonempty(),
+    //error: z.string().optional().describe('Error message if request failed'),
+    refs: sRefMap,
+})).describe('Response for applying access changes');
+export const sApplyChangeProgress = z
+    .object({
+    kind: z.literal('apply-change-progress'),
+    requestId: z.string().nonempty(),
+    mutationIndex: z
+        .number()
+        .describe('Index of the finished mutation in the batch'),
+    // total: z.number().describe('Progress of the access changes'),
+    // completed: z.number().describe('Progress of the access changes'),
+})
+    .describe('Progress of the access changes');
+// C. ABORT CHANGES
+export const sAbortChange = z
+    .object({
+    kind: z.literal('abort-change'),
+    provider: z.string().nonempty(),
+    policyVersion: z.number().describe('Version of the access changes'),
+})
+    .describe('Request to abort access changes');
+const fromAgentSchemaByKind = {
+    register: sRegisterRq,
+    unregister: sUnregister,
+    'validate-config-rs': sValidateProviderConfigRs,
+    'start-rs': sStartServiceRs,
+    'stop-rs': sStopServiceRs,
+    'command-rs': sRunCommandRs,
+    'query-rs': sQueryRs,
+    state: sPushStateUpdateRq,
+    event: sPushEventRq,
+    'get-available-devices-rs': sGetAvailableDevicesRs,
+    'validate-change-rs': sValidateChangeRs,
+    'apply-change-rs': sApplyChangeRs,
+    'apply-change-progress': sApplyChangeProgress,
+    'error-rs': sErrorPayload,
+};
+export const getAgentMessageIssues = (message) => {
+    const result = sMessageHeader.safeParse(message);
+    if (!result.success) {
+        return result.error.errors.map((e) => `${e.path.map((p) => p.toString()).join('.')} - ${e.message}`);
+    }
+    const { kind } = message;
+    const schema = fromAgentSchemaByKind[kind];
+    if (!schema) {
+        return [`Unknown message kind: ${kind}`];
+    }
+    const result2 = schema.safeParse(message);
+    if (!result2.success) {
+        return result2.error.errors.map((e) => `${e.path.map((p) => p.toString()).join('.')} - ${e.message}`);
+    }
+    return [];
+};
+export const isMessageFromAgent = (message) => {
+    if (typeof message !== 'object' || message === null) {
+        return false;
+    }
+    const headerResult = sMessageHeader.safeParse(message);
+    if (!headerResult.success) {
+        return false;
+    }
+    const { kind } = message;
+    const schema = fromAgentSchemaByKind[kind];
+    if (!schema) {
+        return false;
+    }
+    const result = schema.safeParse(message);
+    return result.success;
+};

package/dist/api/commands/alarm.js

@@ -0,0 +1,59 @@
+import { sDeviceEvent, sDeviceId, sDuration } from '../../primitives';
+import { z } from 'zod';
+// COMMANDS
+export const sArmCommand = z.object({
+    command: z.literal('alarm.arm'),
+    params: z.object({
+        deviceId: sDeviceId,
+    }),
+});
+export const sDisarmCommand = z.object({
+    command: z.literal('alarm.disarm'),
+    params: z.object({
+        deviceId: sDeviceId,
+        duration: sDuration.optional().describe('Duration in milliseconds'),
+    }),
+});
+export const sBypassCommand = z.object({
+    command: z.literal('alarm.bypass'),
+    params: z.object({
+        deviceId: sDeviceId,
+    }),
+});
+export const sUnbypassCommand = z.object({
+    command: z.literal('alarm.unbypass'),
+    params: z.object({
+        deviceId: sDeviceId,
+    }),
+});
+export const sArmAllCommand = z.object({
+    command: z.literal('alarm.arm-all'),
+    params: z.object({}),
+});
+export const sDisarmAllCommand = z.object({
+    command: z.literal('alarm.disarm-all'),
+    params: z.object({
+        duration: sDuration.optional().describe('Duration in milliseconds'),
+    }),
+});
+export const sAcknowledgeCommand = z.object({
+    command: z.literal('alarm.acknowledge'),
+    params: z.object({}),
+});
+export const sSetTriggerCommand = z.object({
+    command: z.literal('alarm.set-trigger'),
+    params: z.object({
+        event: sDeviceEvent,
+        onlyIfArmed: z.boolean().describe('Set only if the device is armed'),
+    }),
+});
+export const alarmCommandSchemas = {
+    'alarm.arm': sArmCommand,
+    'alarm.disarm': sDisarmCommand,
+    'alarm.arm-all': sArmAllCommand,
+    'alarm.disarm-all': sDisarmAllCommand,
+    'alarm.acknowledge': sAcknowledgeCommand,
+    'alarm.set-trigger': sSetTriggerCommand,
+    'alarm.bypass': sBypassCommand,
+    'alarm.unbypass': sUnbypassCommand,
+};