Add interfaces package

.gitignore

@@ -0,0 +1,13 @@
+node_modules/
+dist/
+dist_*/
+dist_ts/
+coverage/
+.nyc_output/
+.nogit/
+.playwright-mcp/
+*.log
+.DS_Store
+.env
+.env.*
+!.env.example

package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@smarthome.exchange/interfaces",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Shared TypeScript interfaces and TypedRequest contracts for smarthome.exchange.",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
+  "type": "module",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "scripts": {
+    "test": "tstest test/ --verbose --logfile --timeout 60",
+    "build": "tsbuild tsfolders --allowimplicitany",
+    "buildDocs": "tsdoc"
+  },
+  "dependencies": {
+    "@api.global/typedrequest-interfaces": "^3.0.19",
+    "@tsclass/tsclass": "^9.5.1"
+  },
+  "devDependencies": {
+    "@git.zone/tsbuild": "^4.4.0",
+    "@git.zone/tsdoc": "^2.0.3",
+    "@git.zone/tsrun": "^2.0.3",
+    "@git.zone/tstest": "^3.6.3",
+    "@types/node": "^25.6.0"
+  },
+  "files": [
+    "ts/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    "readme.md",
+    "changelog.md",
+    "license"
+  ],
+  "browserslist": [
+    "last 1 chrome versions"
+  ],
+  "packageManager": "pnpm@10.28.2"
+}

readme.md

@@ -0,0 +1,3 @@
+# @smarthome.exchange/interfaces
+
+Shared data interfaces and TypedRequest contracts for smarthome.exchange packages.

test/test.node.ts

@@ -0,0 +1,9 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as shxInterfaces from '../ts/index.js';
+
+tap.test('exports data and request namespaces', async () => {
+  expect(shxInterfaces.data).toBeTruthy();
+  expect(shxInterfaces.request).toBeTruthy();
+});
+
+export default tap.start();

ts/data/agent.ts

@@ -0,0 +1,34 @@
+import type { TToolScope } from './tool.js';
+
+export type TAgentMode = 'auto' | 'ask' | 'suggest';
+
+export type TAgentGlyph = 'comfort' | 'sentinel' | 'watt' | 'dawn' | 'echo' | 'steward' | 'custom';
+
+export interface IAgentDefinition {
+  id: string;
+  name: string;
+  role: string;
+  glyph: TAgentGlyph;
+  color: string;
+  mode: TAgentMode;
+  model: string;
+  scopes: TToolScope[];
+  systemPrompt: string;
+  enabled: boolean;
+}
+
+export interface IAgentStatus {
+  agentId: string;
+  actionsToday: number;
+  latest?: string;
+  savings?: string;
+  runningToolIds: string[];
+}
+
+export interface IAgentReasoningEvent {
+  id: string;
+  agentId: string;
+  kind: 'observe' | 'think' | 'plan' | 'tool' | 'speak';
+  text: string;
+  createdAt: string;
+}

ts/data/audit.ts

@@ -0,0 +1,14 @@
+export type TAuditReceiptKind = 'tool' | 'approval' | 'automation' | 'agent' | 'system';
+
+export interface IAuditReceipt {
+  id: string;
+  kind: TAuditReceiptKind;
+  callerId: string;
+  toolId?: string;
+  approvalId?: string;
+  scope?: string;
+  inputSummary: string;
+  outputSummary: string;
+  reversible: boolean;
+  createdAt: string;
+}

ts/data/automation.ts

@@ -0,0 +1,28 @@
+import type { TToolScope } from './tool.js';
+
+export type TAutomationTriggerKind = 'time' | 'device' | 'presence' | 'calendar' | 'manual' | 'system';
+
+export interface IAutomationTrigger {
+  id: string;
+  kind: TAutomationTriggerKind;
+  expression: string;
+}
+
+export interface IAutomationDefinition {
+  id: string;
+  name: string;
+  sourcePath: string;
+  enabled: boolean;
+  triggers: IAutomationTrigger[];
+  requiredScopes: TToolScope[];
+}
+
+export interface IAutomationRun {
+  id: string;
+  automationId: string;
+  triggerId: string;
+  status: 'running' | 'completed' | 'failed';
+  startedAt: string;
+  finishedAt?: string;
+  errorMessage?: string;
+}

ts/data/dashboard.ts

@@ -0,0 +1,27 @@
+export type TDashboardWidgetKind =
+  | 'agentRoster'
+  | 'approvalQueue'
+  | 'deviceGrid'
+  | 'floorPlan'
+  | 'timeline'
+  | 'activityStream'
+  | 'energyChart'
+  | 'custom';
+
+export interface IDashboardWidget {
+  id: string;
+  kind: TDashboardWidgetKind;
+  title: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  config: Record<string, unknown>;
+}
+
+export interface IDashboardDefinition {
+  id: string;
+  homeId: string;
+  name: string;
+  widgets: IDashboardWidget[];
+}

ts/data/device.ts

@@ -0,0 +1,64 @@
+export type TDeviceProtocol =
+  | 'matter'
+  | 'zigbee'
+  | 'zwave'
+  | 'thread'
+  | 'mqtt'
+  | 'homekit'
+  | 'esphome'
+  | 'homeassistant'
+  | 'hue'
+  | 'http'
+  | 'cloud'
+  | 'virtual'
+  | 'unknown';
+
+export type TDeviceCapability =
+  | 'switch'
+  | 'sensor'
+  | 'light'
+  | 'cover'
+  | 'lock'
+  | 'fan'
+  | 'climate'
+  | 'camera'
+  | 'media'
+  | 'energy'
+  | 'notification';
+
+export type TDeviceStateValue = string | number | boolean | null | Record<string, unknown>;
+
+export interface IDeviceFeature {
+  id: string;
+  capability: TDeviceCapability;
+  name: string;
+  readable: boolean;
+  writable: boolean;
+  unit?: string;
+}
+
+export interface IDeviceState {
+  featureId: string;
+  value: TDeviceStateValue;
+  updatedAt: string;
+}
+
+export interface IDeviceDefinition {
+  id: string;
+  integrationDomain?: string;
+  name: string;
+  room?: string;
+  protocol: TDeviceProtocol;
+  manufacturer?: string;
+  model?: string;
+  online: boolean;
+  features: IDeviceFeature[];
+  state: IDeviceState[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface IRoomDefinition {
+  id: string;
+  name: string;
+  floor?: string;
+}

ts/data/home.ts

@@ -0,0 +1,34 @@
+import type { IAgentDefinition, IAgentStatus } from './agent.js';
+import type { IAuditReceipt } from './audit.js';
+import type { IDashboardDefinition } from './dashboard.js';
+import type { IDeviceDefinition, IRoomDefinition } from './device.js';
+import type { IApprovalRequest } from './tool.js';
+
+export interface IHomeMember {
+  id: string;
+  name: string;
+  initials: string;
+  present: boolean;
+  locationLabel?: string;
+  eta?: string;
+}
+
+export interface IHomeDefinition {
+  id: string;
+  name: string;
+  address?: string;
+  timezone: string;
+  members: IHomeMember[];
+  rooms: IRoomDefinition[];
+}
+
+export interface IHomeSnapshot {
+  home: IHomeDefinition;
+  devices: IDeviceDefinition[];
+  agents: IAgentDefinition[];
+  agentStatuses: IAgentStatus[];
+  approvals: IApprovalRequest[];
+  dashboards: IDashboardDefinition[];
+  receipts: IAuditReceipt[];
+  createdAt: string;
+}

ts/data/index.ts

@@ -0,0 +1,7 @@
+export * from './agent.js';
+export * from './audit.js';
+export * from './automation.js';
+export * from './dashboard.js';
+export * from './device.js';
+export * from './home.js';
+export * from './tool.js';

ts/data/tool.ts

@@ -0,0 +1,74 @@
+import type { TAgentMode } from './agent.js';
+
+export type TToolScope =
+  | '*.read'
+  | 'device.read'
+  | 'device.write'
+  | 'light.read'
+  | 'light.write'
+  | 'climate.read'
+  | 'climate.write'
+  | 'energy.read'
+  | 'energy.write'
+  | 'lock.read'
+  | 'lock.write'
+  | 'camera.read'
+  | 'alarm.write'
+  | 'agent.invoke'
+  | 'automation.write'
+  | 'approval.write';
+
+export type TToolJsonSchema = Record<string, unknown>;
+
+export interface IToolDefinition {
+  id: string;
+  ownerId: string;
+  name: string;
+  description: string;
+  inputSchema: TToolJsonSchema;
+  requiredScopes: TToolScope[];
+  mode: TAgentMode;
+}
+
+export interface IToolCall {
+  id: string;
+  toolId: string;
+  callerId: string;
+  input: Record<string, unknown>;
+}
+
+export interface IToolPlan {
+  id: string;
+  callerId: string;
+  title: string;
+  reason: string;
+  confidence: number;
+  calls: IToolCall[];
+}
+
+export interface IToolExecutionResult {
+  callId: string;
+  status: 'executed' | 'queuedForApproval' | 'suggested' | 'failed';
+  output?: Record<string, unknown>;
+  approvalId?: string;
+  errorMessage?: string;
+}
+
+export interface IToolPlanResult {
+  planId: string;
+  results: IToolExecutionResult[];
+}
+
+export interface IApprovalRequest {
+  id: string;
+  planId: string;
+  callId: string;
+  agentId: string;
+  title: string;
+  reason: string;
+  confidence: number;
+  requestedScopes: TToolScope[];
+  status: 'pending' | 'approved' | 'rejected' | 'expired';
+  createdAt: string;
+  decidedAt?: string;
+}

ts/index.ts

@@ -0,0 +1,4 @@
+import * as data from './data/index.js';
+import * as request from './request/index.js';
+
+export { data, request };

ts/plugins.ts

@@ -0,0 +1,9 @@
+// @api.global scope
+import * as typedRequestInterfaces from '@api.global/typedrequest-interfaces';
+
+export { typedRequestInterfaces };
+
+// @tsclass scope
+import * as tsclass from '@tsclass/tsclass';
+
+export { tsclass };

ts/request/agent.ts

@@ -0,0 +1,15 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListAgents
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListAgents
+  > {
+  method: 'listAgents';
+  request: {};
+  response: {
+    agents: data.IAgentDefinition[];
+    statuses: data.IAgentStatus[];
+  };
+}

ts/request/approval.ts

@@ -0,0 +1,32 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListApprovals
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListApprovals
+  > {
+  method: 'listApprovals';
+  request: {
+    status?: data.IApprovalRequest['status'];
+  };
+  response: {
+    approvals: data.IApprovalRequest[];
+  };
+}
+
+export interface IReq_SubmitApproval
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_SubmitApproval
+  > {
+  method: 'submitApproval';
+  request: {
+    approvalId: string;
+    decision: 'approved' | 'rejected';
+  };
+  response: {
+    approval: data.IApprovalRequest;
+    receipt: data.IAuditReceipt;
+  };
+}

ts/request/device.ts

@@ -0,0 +1,17 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListDevices
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListDevices
+  > {
+  method: 'listDevices';
+  request: {
+    room?: string;
+    capability?: data.TDeviceCapability;
+  };
+  response: {
+    devices: data.IDeviceDefinition[];
+  };
+}

ts/request/home.ts

@@ -0,0 +1,14 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_GetHomeSnapshot
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_GetHomeSnapshot
+  > {
+  method: 'getHomeSnapshot';
+  request: {};
+  response: {
+    snapshot: data.IHomeSnapshot;
+  };
+}

ts/request/index.ts

@@ -0,0 +1,5 @@
+export * from './agent.js';
+export * from './approval.js';
+export * from './device.js';
+export * from './home.js';
+export * from './tool.js';

ts/request/tool.ts

@@ -0,0 +1,28 @@
+import * as plugins from '../plugins.js';
+import * as data from '../data/index.js';
+
+export interface IReq_ListTools
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ListTools
+  > {
+  method: 'listTools';
+  request: {
+    ownerId?: string;
+  };
+  response: {
+    tools: data.IToolDefinition[];
+  };
+}
+
+export interface IReq_ExecuteToolPlan
+  extends plugins.typedRequestInterfaces.implementsTR<
+    plugins.typedRequestInterfaces.ITypedRequest,
+    IReq_ExecuteToolPlan
+  > {
+  method: 'executeToolPlan';
+  request: {
+    plan: data.IToolPlan;
+  };
+  response: data.IToolPlanResult;
+}

tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  },
+  "exclude": [
+    "dist_*/**/*.d.ts"
+  ]
+}