@smarthome.exchange/api 0.1.0

package/changelog.md

@@ -0,0 +1,22 @@
+# Changelog
+
+## 2026-08-10 - 0.1.0
+
+### Features
+
+- add stoppable home-snapshot polling (client)
+  - Poll `getHomeSnapshot` with configurable cadence and first-run behavior.
+  - Report poll errors without terminating the watcher, wait for in-flight transport work during shutdown, and never wait on user handlers that may stop their own watcher.
+  - Reject fractional, sub-millisecond, and timer-overflow polling intervals.
+
+### Changes
+
+- Migrate HTTP requests to TypedRequest 7 and socket requests to TypedSocket 7.
+- Type request helper method arguments from each request contract's literal `method`.
+- Remove the unused `useSocket` client option.
+- Expose required `live` or `stale` availability with every home snapshot response.
+- Document that v0.1 approval submission records decisions and receipts without resuming or executing tool calls.
+
+### Tests
+
+- Cover snapshot availability through the direct HTTP TypedRequest path with a loopback server while retaining polling coverage.

package/dist_ts/00_commitinfo_data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export declare const commitinfo: {
+    name: string;
+    version: string;
+    description: string;
+};

package/dist_ts/00_commitinfo_data.js

@@ -0,0 +1,9 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+    name: '@smarthome.exchange/api',
+    version: '0.1.0',
+    description: 'Typed API client for smarthome.exchange hubs.'
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx5QkFBeUI7SUFDL0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLCtDQUErQztDQUM3RCxDQUFBIn0=

package/dist_ts/classes.smarthomeexchangeapiclient.d.ts

@@ -0,0 +1,46 @@
+import * as plugins from './plugins.js';
+export interface IShxApiClientOptions {
+    hubUrl?: string;
+}
+export interface IHomeSnapshotWatchOptions {
+    intervalMs?: number;
+    immediate?: boolean;
+    onError?: (errorArg: unknown) => void | Promise<void>;
+}
+export type THomeSnapshotWatchCallback = (snapshotResponseArg: plugins.shxInterfaces.request.IReq_GetHomeSnapshot['response']) => void | Promise<void>;
+export type THomeSnapshotWatchStop = () => Promise<void>;
+export declare class SmarthomeExchangeApiClient {
+    private hubUrl;
+    typedrouter: plugins.typedrequest.TypedRouter<plugins.typedRequestInterfaces.ITypedRequest>;
+    typedsocketClient?: plugins.typedsocket.TypedSocket;
+    constructor(optionsArg?: IShxApiClientOptions);
+    private get httpEndpoint();
+    private createWsRequest;
+    private createHttpRequest;
+    private fire;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    listDevices(requestArg?: plugins.shxInterfaces.request.IReq_ListDevices['request']): Promise<{
+        devices: plugins.shxInterfaces.data.IDeviceDefinition[];
+    }>;
+    listAgents(): Promise<{
+        agents: plugins.shxInterfaces.data.IAgentDefinition[];
+        statuses: plugins.shxInterfaces.data.IAgentStatus[];
+    }>;
+    listTools(requestArg?: plugins.shxInterfaces.request.IReq_ListTools['request']): Promise<{
+        tools: plugins.shxInterfaces.data.IToolDefinition[];
+    }>;
+    getHomeSnapshot(): Promise<{
+        availability: plugins.shxInterfaces.data.THomeSnapshotAvailability;
+        snapshot: plugins.shxInterfaces.data.IHomeSnapshot;
+    }>;
+    watchHomeSnapshot(callbackArg: THomeSnapshotWatchCallback, optionsArg?: IHomeSnapshotWatchOptions): THomeSnapshotWatchStop;
+    executeToolPlan(planArg: plugins.shxInterfaces.data.IToolPlan): Promise<plugins.shxInterfaces.data.IToolPlanResult>;
+    listApprovals(requestArg?: plugins.shxInterfaces.request.IReq_ListApprovals['request']): Promise<{
+        approvals: plugins.shxInterfaces.data.IApprovalRequest[];
+    }>;
+    submitApproval(requestArg: plugins.shxInterfaces.request.IReq_SubmitApproval['request']): Promise<{
+        approval: plugins.shxInterfaces.data.IApprovalRequest;
+        receipt: plugins.shxInterfaces.data.IAuditReceipt;
+    }>;
+}

package/dist_ts/classes.smarthomeexchangeapiclient.js

@@ -0,0 +1,133 @@
+import * as plugins from './plugins.js';
+export class SmarthomeExchangeApiClient {
+    hubUrl;
+    typedrouter = new plugins.typedrequest.TypedRouter();
+    typedsocketClient;
+    constructor(optionsArg = {}) {
+        this.hubUrl = (optionsArg.hubUrl || 'http://localhost:8080').replace(/\/$/, '');
+    }
+    get httpEndpoint() {
+        return `${this.hubUrl}/typedrequest`;
+    }
+    createWsRequest(operationArg) {
+        return this.typedsocketClient?.createTypedRequest(operationArg);
+    }
+    createHttpRequest(operationArg) {
+        return new plugins.typedrequest.TypedRequest(this.httpEndpoint, operationArg);
+    }
+    async fire(operationArg, payloadArg) {
+        const wsRequest = this.createWsRequest(operationArg);
+        if (wsRequest) {
+            return wsRequest.fire(payloadArg);
+        }
+        return this.createHttpRequest(operationArg).fire(payloadArg);
+    }
+    async start() {
+        this.typedsocketClient = await plugins.typedsocket.TypedSocket.createClient(this.typedrouter, this.hubUrl);
+    }
+    async stop() {
+        await this.typedsocketClient?.stop();
+        this.typedsocketClient = undefined;
+    }
+    async listDevices(requestArg = {}) {
+        return this.fire('listDevices', requestArg);
+    }
+    async listAgents() {
+        return this.fire('listAgents', {});
+    }
+    async listTools(requestArg = {}) {
+        return this.fire('listTools', requestArg);
+    }
+    async getHomeSnapshot() {
+        return this.fire('getHomeSnapshot', {});
+    }
+    watchHomeSnapshot(callbackArg, optionsArg = {}) {
+        const intervalMs = optionsArg.intervalMs ?? 5000;
+        if (!Number.isInteger(intervalMs) || intervalMs < 1 || intervalMs > 2_147_483_647) {
+            throw new Error('watchHomeSnapshot intervalMs must be an integer from 1 through 2147483647.');
+        }
+        let stopped = false;
+        let timeout;
+        let activePoll;
+        let userHandlerActive = false;
+        const clearScheduledPoll = () => {
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = undefined;
+            }
+        };
+        const scheduleNextPoll = () => {
+            if (stopped) {
+                return;
+            }
+            timeout = setTimeout(() => {
+                timeout = undefined;
+                activePoll = runPoll();
+            }, intervalMs);
+        };
+        const handlePollError = async (errorArg) => {
+            if (stopped) {
+                return;
+            }
+            if (optionsArg.onError) {
+                userHandlerActive = true;
+                try {
+                    await optionsArg.onError(errorArg);
+                }
+                catch (errorHandlerError) {
+                    console.error('watchHomeSnapshot error handler failed:', errorHandlerError);
+                }
+                finally {
+                    userHandlerActive = false;
+                }
+                return;
+            }
+            console.error('watchHomeSnapshot poll failed:', errorArg);
+        };
+        const runPoll = async () => {
+            try {
+                const snapshotResponse = await this.getHomeSnapshot();
+                if (!stopped) {
+                    userHandlerActive = true;
+                    try {
+                        await callbackArg(snapshotResponse);
+                    }
+                    finally {
+                        userHandlerActive = false;
+                    }
+                }
+            }
+            catch (error) {
+                await handlePollError(error);
+            }
+            finally {
+                activePoll = undefined;
+                scheduleNextPoll();
+            }
+        };
+        if (optionsArg.immediate === false) {
+            scheduleNextPoll();
+        }
+        else {
+            activePoll = runPoll();
+        }
+        return async () => {
+            stopped = true;
+            clearScheduledPoll();
+            const pollToWait = userHandlerActive ? undefined : activePoll;
+            await pollToWait;
+        };
+    }
+    async executeToolPlan(planArg) {
+        return this.fire('executeToolPlan', {
+            plan: planArg,
+        });
+    }
+    async listApprovals(requestArg = {}) {
+        return this.fire('listApprovals', requestArg);
+    }
+    async submitApproval(requestArg) {
+        return this.fire('submitApproval', requestArg);
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5zbWFydGhvbWVleGNoYW5nZWFwaWNsaWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2NsYXNzZXMuc21hcnRob21lZXhjaGFuZ2VhcGljbGllbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFrQnhDLE1BQU0sT0FBTywwQkFBMEI7SUFDN0IsTUFBTSxDQUFTO0lBQ2hCLFdBQVcsR0FBRyxJQUFJLE9BQU8sQ0FBQyxZQUFZLENBQUMsV0FBVyxFQUFFLENBQUM7SUFDckQsaUJBQWlCLENBQW1DO0lBRTNELFlBQVksYUFBbUMsRUFBRTtRQUMvQyxJQUFJLENBQUMsTUFBTSxHQUFHLENBQUMsVUFBVSxDQUFDLE1BQU0sSUFBSSx1QkFBdUIsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxLQUFLLEVBQUUsRUFBRSxDQUFDLENBQUM7SUFDbEYsQ0FBQztJQUVELElBQVksWUFBWTtRQUN0QixPQUFPLEdBQUcsSUFBSSxDQUFDLE1BQU0sZUFBZSxDQUFDO0lBQ3ZDLENBQUM7SUFFTyxlQUFlLENBQ3JCLFlBQXlCO1FBRXpCLE9BQU8sSUFBSSxDQUFDLGlCQUFpQixFQUFFLGtCQUFrQixDQUFJLFlBQVksQ0FBQyxDQUFDO0lBQ3JFLENBQUM7SUFFTyxpQkFBaUIsQ0FDdkIsWUFBeUI7UUFFekIsT0FBTyxJQUFJLE9BQU8sQ0FBQyxZQUFZLENBQUMsWUFBWSxDQUFJLElBQUksQ0FBQyxZQUFZLEVBQUUsWUFBWSxDQUFDLENBQUM7SUFDbkYsQ0FBQztJQUVPLEtBQUssQ0FBQyxJQUFJLENBQ2hCLFlBQXlCLEVBQ3pCLFVBQXdCO1FBRXhCLE1BQU0sU0FBUyxHQUFHLElBQUksQ0FBQyxlQUFlLENBQUksWUFBWSxDQUFDLENBQUM7UUFDeEQsSUFBSSxTQUFTLEVBQUUsQ0FBQztZQUNkLE9BQU8sU0FBUyxDQUFDLElBQUksQ0FBQyxVQUFVLENBQUMsQ0FBQztRQUNwQyxDQUFD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

package/dist_ts/index.d.ts

@@ -0,0 +1 @@
+export * from './classes.smarthomeexchangeapiclient.js';

package/dist_ts/index.js

@@ -0,0 +1,2 @@
+export * from './classes.smarthomeexchangeapiclient.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLHlDQUF5QyxDQUFDIn0=

package/dist_ts/plugins.d.ts

@@ -0,0 +1,8 @@
+import * as shxInterfaces from '@smarthome.exchange/interfaces';
+export { shxInterfaces };
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedRequestInterfaces from '@api.global/typedrequest-interfaces';
+import * as typedsocket from '@api.global/typedsocket';
+export { typedrequest, typedRequestInterfaces, typedsocket };
+import * as smartpromise from '@push.rocks/smartpromise';
+export { smartpromise };

package/dist_ts/plugins.js

@@ -0,0 +1,12 @@
+// Project scope
+import * as shxInterfaces from '@smarthome.exchange/interfaces';
+export { shxInterfaces };
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedRequestInterfaces from '@api.global/typedrequest-interfaces';
+import * as typedsocket from '@api.global/typedsocket';
+export { typedrequest, typedRequestInterfaces, typedsocket };
+// @push.rocks scope
+import * as smartpromise from '@push.rocks/smartpromise';
+export { smartpromise };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsZ0JBQWdCO0FBQ2hCLE9BQU8sS0FBSyxhQUFhLE1BQU0sZ0NBQWdDLENBQUM7QUFFaEUsT0FBTyxFQUFFLGFBQWEsRUFBRSxDQUFDO0FBRXpCLG9CQUFvQjtBQUNwQixPQUFPLEtBQUssWUFBWSxNQUFNLDBCQUEwQixDQUFDO0FBQ3pELE9BQU8sS0FBSyxzQkFBc0IsTUFBTSxxQ0FBcUMsQ0FBQztBQUM5RSxPQUFPLEtBQUssV0FBVyxNQUFNLHlCQUF5QixDQUFDO0FBRXZELE9BQU8sRUFBRSxZQUFZLEVBQUUsc0JBQXNCLEVBQUUsV0FBVyxFQUFFLENBQUM7QUFFN0Qsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFFekQsT0FBTyxFQUFFLFlBQVksRUFBRSxDQUFDIn0=

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@smarthome.exchange/api",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Typed API client for smarthome.exchange hubs.",
+  "exports": {
+    ".": "./dist_ts/index.js"
+  },
+  "type": "module",
+  "author": "Task Venture Capital GmbH",
+  "license": "MIT",
+  "dependencies": {
+    "@api.global/typedrequest": "^7.0.2",
+    "@api.global/typedrequest-interfaces": "^7.0.0",
+    "@api.global/typedsocket": "^7.1.0",
+    "@push.rocks/smartpromise": "^4.2.4",
+    "@smarthome.exchange/interfaces": "0.1.0"
+  },
+  "devDependencies": {
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsdoc": "^2.1.1",
+    "@git.zone/tsrun": "^2.0.6",
+    "@git.zone/tstest": "^4.0.0",
+    "@types/node": "^26.2.0"
+  },
+  "files": [
+    "ts/**/*",
+    "dist/**/*",
+    "dist_*/**/*",
+    "dist_ts/**/*",
+    "readme.md",
+    "changelog.md",
+    "license.md"
+  ],
+  "browserslist": [
+    "last 1 chrome versions"
+  ],
+  "scripts": {
+    "test": "tstest test/ --verbose --logfile --timeout 60",
+    "build": "tsbuild tsfolders --allowimplicitany",
+    "buildDocs": "tsdoc"
+  }
+}

package/readme.md

@@ -0,0 +1,154 @@
+# @smarthome.exchange/api
+
+🔌 Typed API client for connecting tools, CLIs, automations, and apps to a smarthome.exchange hub.
+
+This package wraps the hub's TypedRequest boundary in a programmer-friendly client. It speaks HTTP by default, switches to TypedSocket after `start()`, and returns the exact response shapes from `@smarthome.exchange/interfaces`.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Install
+
+```bash
+pnpm add @smarthome.exchange/api
+```
+
+## Basic Usage
+
+```ts
+import { SmarthomeExchangeApiClient } from '@smarthome.exchange/api';
+
+const client = new SmarthomeExchangeApiClient({
+  hubUrl: 'http://localhost:8080',
+});
+
+const snapshotResponse = await client.getHomeSnapshot();
+console.log(snapshotResponse.availability, snapshotResponse.snapshot.home.name);
+
+const deviceResponse = await client.listDevices({
+  capability: 'light',
+});
+console.log(deviceResponse.devices.map((deviceArg) => deviceArg.name));
+```
+
+## Socket Mode
+
+```ts
+const client = new SmarthomeExchangeApiClient({ hubUrl: 'http://localhost:8080' });
+
+await client.start();
+
+try {
+  const agents = await client.listAgents();
+  console.log(agents.statuses);
+} finally {
+  await client.stop();
+}
+```
+
+Calling `start()` creates a TypedSocket 7 client and resolves after its package-major compatibility handshake. That handshake establishes transport compatibility only; application authentication and authorization remain server responsibilities. Calls made before `start()` or after `stop()` use HTTP requests against `${hubUrl}/typedrequest`.
+
+## Version 7 Transport
+
+The client has migrated both transport paths to the version 7 stack: HTTP calls use TypedRequest 7 envelopes and socket calls use TypedSocket 7 with its exact package-major handshake. Request helper method arguments are derived from each shared contract's literal `method`, keeping every client method aligned with `@smarthome.exchange/interfaces`. The socket handshake authorizes transport compatibility only; application authentication and authorization remain server responsibilities.
+
+## Client Methods
+
+| Method | Typed operation | Returns |
+| --- | --- | --- |
+| `listDevices({ room?, capability? })` | `listDevices` | `{ devices }` |
+| `listAgents()` | `listAgents` | `{ agents, statuses }` |
+| `listTools(filter?)` | `listTools` | `{ tools }` |
+| `getHomeSnapshot()` | `getHomeSnapshot` | `{ availability, snapshot }` |
+| `watchHomeSnapshot(callback, options?)` | local polling helper | Async stop function |
+| `executeToolPlan(plan)` | `executeToolPlan` | `IToolPlanResult` |
+| `listApprovals(filter?)` | `listApprovals` | `{ approvals }` |
+| `submitApproval(request)` | `submitApproval` | Updated approval result |
+
+## Approval Decisions
+
+In v0.1, `submitApproval()` is decision-record-only. It records `approved` or `rejected` on the approval and returns the updated record plus its audit receipt. It never resumes or executes the related tool call, and an approved decision must not be interpreted as an execution result.
+
+## Snapshot Watching
+
+`watchHomeSnapshot(callback, options?)` is a client-local polling helper around `getHomeSnapshot()`. It does not add a server push contract. The callback receives the same `{ availability, snapshot }` response returned by `getHomeSnapshot()`. `availability` is `live` for a successfully served live hub response and `stale` when the response carries stale snapshot data. A raw `IHomeSnapshot` without this response envelope is not automatically live. The async stop function clears the polling timer and waits for active transport work unless a user callback or `onError` handler is already running. It never waits on active user handlers, so they may await their own stop function without a circular wait and external shutdown cannot be held open by user code. A handler already in progress may finish after stopping resolves, but no later poll is scheduled. `intervalMs` defaults to `5000` and must be an integer from `1` through `2147483647`.
+
+```ts
+const stopWatching = client.watchHomeSnapshot(
+  async ({ availability, snapshot }) => {
+    console.log(availability, snapshot.home.name, snapshot.devices.length);
+  },
+  {
+    intervalMs: 5000,
+    immediate: true,
+    onError: async (errorArg) => {
+      console.error('Snapshot refresh failed:', errorArg);
+    },
+  },
+);
+
+// Later, when the UI or process is shutting down:
+await stopWatching();
+```
+
+## Tool Plan Example
+
+```ts
+const result = await client.executeToolPlan({
+  id: 'plan:dim-living-room',
+  callerId: 'app:console',
+  title: 'Dim living room lights',
+  reason: 'The user requested a 35% living-room brightness level.',
+  confidence: 1,
+  calls: [{
+    id: 'call:living-room-dim',
+    toolId: 'device:homeassistant:light.living_room:brightness:write',
+    callerId: 'app:console',
+    input: { value: 35 },
+  }],
+});
+
+for (const callResult of result.results) {
+  if (callResult.status === 'failed') {
+    throw new Error(callResult.errorMessage);
+  }
+  if (callResult.status === 'indeterminate') {
+    console.error('Device outcome requires reconciliation:', callResult.errorMessage);
+  }
+  if (callResult.status === 'queuedForApproval') {
+    console.log('Approval required:', callResult.approvalId);
+  }
+}
+```
+
+Use a tool identifier returned by `listTools()` for a currently normalized integration-owned entity. Do not construct identifiers from seeded demo device IDs: a device without a live integration owner cannot dispatch a physical write and fails closed. Inspect every per-call result because a successful `executeToolPlan()` request may still contain `failed`, `indeterminate`, `suggested`, or `queuedForApproval` outcomes.
+
+## Scripts
+
+```bash
+pnpm test
+pnpm build
+pnpm buildDocs
+```
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license.md) file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH\
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@smarthome.exchange/api',
+  version: '0.1.0',
+  description: 'Typed API client for smarthome.exchange hubs.'
+}

package/ts/classes.smarthomeexchangeapiclient.ts

@@ -0,0 +1,180 @@
+import * as plugins from './plugins.js';
+
+export interface IShxApiClientOptions {
+  hubUrl?: string;
+}
+
+export interface IHomeSnapshotWatchOptions {
+  intervalMs?: number;
+  immediate?: boolean;
+  onError?: (errorArg: unknown) => void | Promise<void>;
+}
+
+export type THomeSnapshotWatchCallback = (
+  snapshotResponseArg: plugins.shxInterfaces.request.IReq_GetHomeSnapshot['response']
+) => void | Promise<void>;
+
+export type THomeSnapshotWatchStop = () => Promise<void>;
+
+export class SmarthomeExchangeApiClient {
+  private hubUrl: string;
+  public typedrouter = new plugins.typedrequest.TypedRouter();
+  public typedsocketClient?: plugins.typedsocket.TypedSocket;
+
+  constructor(optionsArg: IShxApiClientOptions = {}) {
+    this.hubUrl = (optionsArg.hubUrl || 'http://localhost:8080').replace(/\/$/, '');
+  }
+
+  private get httpEndpoint() {
+    return `${this.hubUrl}/typedrequest`;
+  }
+
+  private createWsRequest<T extends plugins.typedRequestInterfaces.ITypedRequest>(
+    operationArg: T['method']
+  ) {
+    return this.typedsocketClient?.createTypedRequest<T>(operationArg);
+  }
+
+  private createHttpRequest<T extends plugins.typedRequestInterfaces.ITypedRequest>(
+    operationArg: T['method']
+  ) {
+    return new plugins.typedrequest.TypedRequest<T>(this.httpEndpoint, operationArg);
+  }
+
+  private async fire<T extends plugins.typedRequestInterfaces.ITypedRequest>(
+    operationArg: T['method'],
+    payloadArg: T['request']
+  ): Promise<T['response']> {
+    const wsRequest = this.createWsRequest<T>(operationArg);
+    if (wsRequest) {
+      return wsRequest.fire(payloadArg);
+    }
+    return this.createHttpRequest<T>(operationArg).fire(payloadArg);
+  }
+
+  public async start() {
+    this.typedsocketClient = await plugins.typedsocket.TypedSocket.createClient(
+      this.typedrouter,
+      this.hubUrl
+    );
+  }
+
+  public async stop() {
+    await this.typedsocketClient?.stop();
+    this.typedsocketClient = undefined;
+  }
+
+  public async listDevices(requestArg: plugins.shxInterfaces.request.IReq_ListDevices['request'] = {}) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListDevices>('listDevices', requestArg);
+  }
+
+  public async listAgents() {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListAgents>('listAgents', {});
+  }
+
+  public async listTools(requestArg: plugins.shxInterfaces.request.IReq_ListTools['request'] = {}) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListTools>('listTools', requestArg);
+  }
+
+  public async getHomeSnapshot() {
+    return this.fire<plugins.shxInterfaces.request.IReq_GetHomeSnapshot>('getHomeSnapshot', {});
+  }
+
+  public watchHomeSnapshot(
+    callbackArg: THomeSnapshotWatchCallback,
+    optionsArg: IHomeSnapshotWatchOptions = {}
+  ): THomeSnapshotWatchStop {
+    const intervalMs = optionsArg.intervalMs ?? 5000;
+    if (!Number.isInteger(intervalMs) || intervalMs < 1 || intervalMs > 2_147_483_647) {
+      throw new Error(
+        'watchHomeSnapshot intervalMs must be an integer from 1 through 2147483647.'
+      );
+    }
+
+    let stopped = false;
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let activePoll: Promise<void> | undefined;
+    let userHandlerActive = false;
+
+    const clearScheduledPoll = () => {
+      if (timeout) {
+        clearTimeout(timeout);
+        timeout = undefined;
+      }
+    };
+
+    const scheduleNextPoll = () => {
+      if (stopped) {
+        return;
+      }
+      timeout = setTimeout(() => {
+        timeout = undefined;
+        activePoll = runPoll();
+      }, intervalMs);
+    };
+
+    const handlePollError = async (errorArg: unknown) => {
+      if (stopped) {
+        return;
+      }
+      if (optionsArg.onError) {
+        userHandlerActive = true;
+        try {
+          await optionsArg.onError(errorArg);
+        } catch (errorHandlerError) {
+          console.error('watchHomeSnapshot error handler failed:', errorHandlerError);
+        } finally {
+          userHandlerActive = false;
+        }
+        return;
+      }
+      console.error('watchHomeSnapshot poll failed:', errorArg);
+    };
+
+    const runPoll = async () => {
+      try {
+        const snapshotResponse = await this.getHomeSnapshot();
+        if (!stopped) {
+          userHandlerActive = true;
+          try {
+            await callbackArg(snapshotResponse);
+          } finally {
+            userHandlerActive = false;
+          }
+        }
+      } catch (error) {
+        await handlePollError(error);
+      } finally {
+        activePoll = undefined;
+        scheduleNextPoll();
+      }
+    };
+
+    if (optionsArg.immediate === false) {
+      scheduleNextPoll();
+    } else {
+      activePoll = runPoll();
+    }
+
+    return async () => {
+      stopped = true;
+      clearScheduledPoll();
+      const pollToWait = userHandlerActive ? undefined : activePoll;
+      await pollToWait;
+    };
+  }
+
+  public async executeToolPlan(planArg: plugins.shxInterfaces.data.IToolPlan) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ExecuteToolPlan>('executeToolPlan', {
+      plan: planArg,
+    });
+  }
+
+  public async listApprovals(requestArg: plugins.shxInterfaces.request.IReq_ListApprovals['request'] = {}) {
+    return this.fire<plugins.shxInterfaces.request.IReq_ListApprovals>('listApprovals', requestArg);
+  }
+
+  public async submitApproval(requestArg: plugins.shxInterfaces.request.IReq_SubmitApproval['request']) {
+    return this.fire<plugins.shxInterfaces.request.IReq_SubmitApproval>('submitApproval', requestArg);
+  }
+}

package/ts/index.ts

@@ -0,0 +1 @@
+export * from './classes.smarthomeexchangeapiclient.js';

package/ts/plugins.ts

@@ -0,0 +1,16 @@
+// Project scope
+import * as shxInterfaces from '@smarthome.exchange/interfaces';
+
+export { shxInterfaces };
+
+// @api.global scope
+import * as typedrequest from '@api.global/typedrequest';
+import * as typedRequestInterfaces from '@api.global/typedrequest-interfaces';
+import * as typedsocket from '@api.global/typedsocket';
+
+export { typedrequest, typedRequestInterfaces, typedsocket };
+
+// @push.rocks scope
+import * as smartpromise from '@push.rocks/smartpromise';
+
+export { smartpromise };