This package is the contract layer. It defines the durable shapes for homes, devices, rooms, agents, automations, tools, approvals, audit receipts, dashboards, and typed hub requests. It contains no runtime business logic, which makes it safe to import from hubs, CLIs, browser apps, automation files, tests, and integration packages.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit 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/ account to submit Pull Requests directly.

Install

pnpm add @smarthome.exchange/interfaces

Import Pattern

import type { data, request } from '@smarthome.exchange/interfaces';

const device: data.IDeviceDefinition = {
  id: 'light.living.floor',
  name: 'Living Floor Lamp',
  protocol: 'hue',
  online: true,
  features: [
    {
      id: 'power',
      capability: 'light',
      name: 'Power',
      readable: true,
      writable: true,
    },
  ],
  state: [
    {
      featureId: 'power',
      value: true,
      updatedAt: new Date().toISOString(),
    },
  ],
};

type SnapshotResponse = request.IReq_GetHomeSnapshot['response'];

Public Surface

The package exports two namespaces from the root entry point:

Namespace	What it contains
`data`	Durable domain objects such as `IDeviceDefinition`, `IAgentDefinition`, `IToolPlan`, `IApprovalRequest`, and `IHomeSnapshot`.
`request`	TypedRequest contracts such as `IReq_ListDevices`, `IReq_ExecuteToolPlan`, and `IReq_SubmitApproval`.

Data Contracts

Core groups include:

Home state: IHomeDefinition, IHomeMember, IHomeSnapshot.
Devices and rooms: IDeviceDefinition, IDeviceFeature, IDeviceState, IRoomDefinition.
Agents: IAgentDefinition, IAgentStatus, IAgentReasoningEvent.
Tools and approvals: IToolDefinition, IToolCall, IToolPlan, IToolPlanResult, IApprovalRequest.
Automations: IAutomationDefinition, IAutomationTrigger, IAutomationRun.
Dashboards and audit: IDashboardDefinition, IDashboardWidget, IAuditReceipt.

Device protocols are explicit string unions such as matter, zigbee, thread, mqtt, homeassistant, hue, http, tcp, udp, cloud, and virtual. Native integrations that communicate directly over TCP, such as selected Onkyo eISCP or Denon receivers, use protocol: 'tcp'; their metadata can identify the vendor wire protocol. This transport value does not imply peer authentication or encryption. Device capabilities include vacuum alongside light, switch, sensor, energy, climate, cover, lock, fan, camera, media, and other normalized classes. Tool scopes are equally explicit, including device.read, device.write, light.write, climate.write, approval.write, and *.read.

TToolExecutionResult is discriminated by status. An executed result may include output, queuedForApproval always includes approvalId, suggested carries no fabricated execution fields, and failed and indeterminate always include errorMessage. indeterminate means a dispatched effect timed out or was aborted without proof of physical cancellation; callers must reconcile authoritative state before retrying.

IReq_GetHomeSnapshot requires availability beside the snapshot. live identifies a successfully served live hub response and stale identifies a response carrying stale snapshot data. Availability is response-envelope metadata: a standalone IHomeSnapshot is not automatically live.

Every hub request requires context: { homeId }. This selects the home; it provides no authority. Credentials belong to the HTTP or WebSocket transport. The hub derives ITrustedIdentity from verified transport state and applies the matching IHomeAccessGrant. callerId on plans and calls remains attribution metadata and must never substitute for the verified subjectId. The *.read scope is limited to read scopes; it does not grant writes or approval decisions.

Tool definitions carry a revision. An approval captures an immutable IApprovalAction with its home, verified requester's subjectId and required subjectKind (user, agent, or service), plan, complete call input, required scopes, and tool revision. The ID and kind together identify the original requester: identical IDs with different kinds must retain their distinct authorization policies. The hub must validate and include both fields in the canonical digest and use the stored kind when authorizing the queued dispatch. A missing kind cannot be inferred from the ID, caller metadata, approver, or current request identity; an action without it cannot be dispatched.

Its actionDigest uses the sha256: prefix followed by 64 lowercase hexadecimal digits. The hub owns JSON validation, snapshotting, canonical serialization, digest calculation, revision checks, and authorization; these TypeScript contracts provide no runtime enforcement. Consumers upgrading from 1.x must capture subjectKind from the verified identity when producing approval actions and explicitly handle existing actions that lack it before allowing dispatch.

submitApproval requires expectedActionDigest so a decision identifies the exact reviewed action. The approval records the verified decision actor in decision.subjectId. An approved action may claim one dispatch attempt, and approval.execution reports notStarted, dispatching, executed, failed, or indeterminate. Each terminal state carries its matching tool result and claim identifiers. indeterminate requires reconciliation after uncertain dispatch or recovery; the contract does not promise that a physical device effect happens exactly once.

Audit receipts carry homeId and the verified subjectId, with optional action digest and execution identifiers for correlation. They are durable data shapes; append-only storage and recovery remain hub responsibilities.

TypedRequest Contracts

The request namespace defines the hub API boundary:

Method	Contract	Purpose
`getHomeSnapshot`	`IReq_GetHomeSnapshot`	Return availability and the complete home snapshot.
`listDevices`	`IReq_ListDevices`	List devices, optionally filtered by room and/or capability.
`listAgents`	`IReq_ListAgents`	List agents and runtime statuses.
`listTools`	`IReq_ListTools`	List available tools, optionally by owner.
`executeToolPlan`	`IReq_ExecuteToolPlan`	Execute, queue, or suggest a typed tool plan.
`listApprovals`	`IReq_ListApprovals`	Query approval requests by status.
`submitApproval`	`IReq_SubmitApproval`	Decide the reviewed action digest and report its execution continuation and audit receipt.

Every request interface carries a literal method, a typed request containing the required home context, and a typed response, so API clients and hub handlers stay in lockstep with TypedRequest 7.

Scripts

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 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.

readme.md

@smarthome.exchange/interfaces