Add SDK 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,40 @@
+{
+  "name": "@smarthome.exchange/sdk",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Automation authoring SDK 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": {
+    "@smarthome.exchange/interfaces": "workspace:*"
+  },
+  "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/sdk
+
+TypeScript automation authoring SDK for smarthome.exchange.

test/test.node.ts

@@ -0,0 +1,14 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import { ShxAutomationContext } from '../ts/index.js';
+
+tap.test('registers and runs automation handlers', async () => {
+  const context = new ShxAutomationContext({ callerId: 'test' });
+  let ran = false;
+  context.on({ id: 'manual:test', kind: 'manual', expression: 'test' }, async () => {
+    ran = true;
+  });
+  await context.runTrigger({ triggerId: 'manual:test', kind: 'manual', payload: {} });
+  expect(ran).toBeTrue();
+});
+
+export default tap.start();

ts/classes.agentproxy.ts

@@ -0,0 +1,36 @@
+import * as plugins from './plugins.js';
+import type { ShxAutomationContext } from './classes.automationcontext.js';
+
+export class AgentProxy {
+  constructor(private context: ShxAutomationContext) {}
+
+  public async decide(optionsArg: {
+    agentId: string;
+    goal: string;
+    scopes: plugins.shxInterfaces.data.TToolScope[];
+    input?: Record<string, unknown>;
+    confidence?: number;
+  }) {
+    const callId = `call:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const plan: plugins.shxInterfaces.data.IToolPlan = {
+      id: `plan:${callId}`,
+      callerId: this.context.options.callerId,
+      title: `Ask ${optionsArg.agentId}`,
+      reason: optionsArg.goal,
+      confidence: optionsArg.confidence ?? 0.65,
+      calls: [
+        {
+          id: callId,
+          toolId: `agent:${optionsArg.agentId}:decide`,
+          callerId: this.context.options.callerId,
+          input: {
+            goal: optionsArg.goal,
+            scopes: optionsArg.scopes,
+            ...(optionsArg.input ?? {}),
+          },
+        },
+      ],
+    };
+    return this.context.executePlan(plan);
+  }
+}

ts/classes.automationcontext.ts

@@ -0,0 +1,76 @@
+import * as plugins from './plugins.js';
+import { AgentProxy } from './classes.agentproxy.js';
+import { DeviceProxy } from './classes.deviceproxy.js';
+
+export type TAutomationEvent = {
+  triggerId: string;
+  kind: plugins.shxInterfaces.data.TAutomationTriggerKind;
+  payload: Record<string, unknown>;
+};
+
+export type TAutomationHandler = (
+  eventArg: TAutomationEvent,
+  contextArg: ShxAutomationContext
+) => Promise<void> | void;
+
+export type TToolPlanExecutor = (
+  planArg: plugins.shxInterfaces.data.IToolPlan
+) => Promise<plugins.shxInterfaces.data.IToolPlanResult>;
+
+export interface IShxAutomationContextOptions {
+  callerId: string;
+  executePlan?: TToolPlanExecutor;
+}
+
+export interface IAutomationRegistration {
+  trigger: plugins.shxInterfaces.data.IAutomationTrigger;
+  handler: TAutomationHandler;
+}
+
+export class ShxAutomationContext {
+  public devices = new DeviceProxy(this);
+  public agents = new AgentProxy(this);
+  private registrations: IAutomationRegistration[] = [];
+
+  constructor(public options: IShxAutomationContextOptions) {}
+
+  public on(
+    triggerArg: plugins.shxInterfaces.data.IAutomationTrigger,
+    handlerArg: TAutomationHandler
+  ) {
+    this.registrations.push({
+      trigger: triggerArg,
+      handler: handlerArg,
+    });
+    return triggerArg;
+  }
+
+  public getRegistrations() {
+    return [...this.registrations];
+  }
+
+  public async runTrigger(eventArg: TAutomationEvent) {
+    const matchingRegistrations = this.registrations.filter((registrationArg) => {
+      return registrationArg.trigger.id === eventArg.triggerId || registrationArg.trigger.kind === eventArg.kind;
+    });
+    for (const registration of matchingRegistrations) {
+      await registration.handler(eventArg, this);
+    }
+  }
+
+  public async executePlan(planArg: plugins.shxInterfaces.data.IToolPlan) {
+    if (this.options.executePlan) {
+      return this.options.executePlan(planArg);
+    }
+    return {
+      planId: planArg.id,
+      results: planArg.calls.map((callArg: plugins.shxInterfaces.data.IToolCall) => ({
+        callId: callArg.id,
+        status: 'suggested' as const,
+        output: {
+          message: 'No hub executor attached. Plan was recorded as a suggestion.',
+        },
+      })),
+    };
+  }
+}

ts/classes.deviceproxy.ts

@@ -0,0 +1,47 @@
+import * as plugins from './plugins.js';
+import type { ShxAutomationContext } from './classes.automationcontext.js';
+
+export class DeviceProxy {
+  constructor(private context: ShxAutomationContext) {}
+
+  public async call(optionsArg: {
+    deviceId: string;
+    toolId: string;
+    title: string;
+    reason: string;
+    input?: Record<string, unknown>;
+    confidence?: number;
+  }) {
+    const callId = `call:${Date.now()}:${Math.random().toString(36).slice(2)}`;
+    const plan: plugins.shxInterfaces.data.IToolPlan = {
+      id: `plan:${callId}`,
+      callerId: this.context.options.callerId,
+      title: optionsArg.title,
+      reason: optionsArg.reason,
+      confidence: optionsArg.confidence ?? 0.5,
+      calls: [
+        {
+          id: callId,
+          toolId: optionsArg.toolId,
+          callerId: this.context.options.callerId,
+          input: {
+            deviceId: optionsArg.deviceId,
+            ...(optionsArg.input ?? {}),
+          },
+        },
+      ],
+    };
+    return this.context.executePlan(plan);
+  }
+
+  public async read(deviceIdArg: string) {
+    return this.call({
+      deviceId: deviceIdArg,
+      toolId: `device:${deviceIdArg}:read`,
+      title: `Read ${deviceIdArg}`,
+      reason: 'Automation requested current device state.',
+      input: {},
+      confidence: 1,
+    });
+  }
+}

ts/index.ts

@@ -0,0 +1,20 @@
+export * from './classes.automationcontext.js';
+export * from './classes.agentproxy.js';
+export * from './classes.deviceproxy.js';
+
+import type * as shxInterfaces from '@smarthome.exchange/interfaces';
+import { ShxAutomationContext, type TAutomationHandler } from './classes.automationcontext.js';
+import { AgentProxy } from './classes.agentproxy.js';
+import { DeviceProxy } from './classes.deviceproxy.js';
+
+export const defaultAutomationContext = new ShxAutomationContext({
+  callerId: 'automation:default',
+});
+
+export const on: (
+  triggerArg: shxInterfaces.data.IAutomationTrigger,
+  handlerArg: TAutomationHandler
+) => shxInterfaces.data.IAutomationTrigger = defaultAutomationContext.on.bind(defaultAutomationContext);
+
+export const devices: DeviceProxy = defaultAutomationContext.devices;
+export const agents: AgentProxy = defaultAutomationContext.agents;

ts/plugins.ts

@@ -0,0 +1,4 @@
+// Project scope
+import * as shxInterfaces from '@smarthome.exchange/interfaces';
+
+export { shxInterfaces };

tsconfig.json

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