@smarthome.exchange/api 0.1.0 → 1.0.0

package/readme.md

@@ -2,7 +2,7 @@
 
 🔌 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`.
+This package wraps the hub's authenticated HTTP and Node WebSocket boundaries. Each client is bound to one home and returns the exact response shapes from `@smarthome.exchange/interfaces`.
 
 ## Issue Reporting and Security
 
@@ -21,6 +21,11 @@ import { SmarthomeExchangeApiClient } from '@smarthome.exchange/api';
 
 const client = new SmarthomeExchangeApiClient({
   hubUrl: 'http://localhost:8080',
+  homeId: 'home:primary',
+  authorizationHeaderProvider: async ({ abortSignal }) => {
+    const accessToken = await yourCredentialProvider.getAccessToken({ abortSignal });
+    return `Bearer ${accessToken}`;
+  },
 });
 
 const snapshotResponse = await client.getHomeSnapshot();
@@ -32,26 +37,51 @@ const deviceResponse = await client.listDevices({
 console.log(deviceResponse.devices.map((deviceArg) => deviceArg.name));
 ```
 
-## Socket Mode
+`yourCredentialProvider` is the application's configured credential service; the client does not perform sign-in or persist tokens. The asynchronous `authorizationHeaderProvider` is required. It runs once per HTTP request and before each explicitly started physical Node socket connection. It receives the immutable home, final transport endpoint, operation name, transport, and cancellation signal. A socket context uses `method: 'connect'` and `transport: 'websocket'`, with the owning attempt and preparation deadline. Return the complete Authorization header value. Provider failure, an empty value, or invalid HTTP header syntax rejects the call without sending an anonymous request.
+
+The constructor captures the home and provider from plain own data properties. Changing the original options or a filter while credentials are being obtained cannot change the prepared request. Every operation includes `context: { homeId }`; filter parameters cannot replace that context or supply trusted identity. Nested action inputs must contain finite, acyclic JSON data. Accessors, symbolic properties, and class instances are rejected without evaluating their getters, before credential preparation. Tool plans and calls cannot supply identity or grant fields. The home selects a resource. The server derives identity and checks home grants from the transport credentials.
+
+## Transport and Cancellation
+
+HTTP calls use published TypedRequest 9.1 and `${hubUrl}/typedrequest`. Credentials stay in HTTP headers outside RPC JSON. Header-bearing calls bypass the shared response cache, including when `useCache: true`, and reject redirects before credentials can be forwarded. Configure the final hub URL without embedded credentials, query parameters, or a fragment. HTTPS and server-managed browser CORS remain deployment responsibilities.
+
+Every method accepts optional request options:
 
 ```ts
-const client = new SmarthomeExchangeApiClient({ hubUrl: 'http://localhost:8080' });
+const abortController = new AbortController();
+const snapshot = await client.getHomeSnapshot({
+  abortSignal: abortController.signal,
+  timeoutMs: 5000,
+});
+const devices = await client.listDevices({ room: 'kitchen' }, {
+  abortSignal: abortController.signal,
+});
+```
 
-await client.start();
+Cancellation is checked before and after credential preparation and passed to TypedRequest. Cancellation settles the API request even when a credential provider ignores its signal; late provider results or failures are observed and cannot open a request. The provider still owns its own resources and must cooperate with the supplied signal to release them. The client cannot terminate foreign provider work or synchronous code. `timeoutMs` is TypedRequest's HTTP deadline, beginning after credential preparation and covering transport and response decoding. API operations set the owning transport’s `maxRetries` to zero: a server-requested retry raises `TypedRequestRetryLimitError` after the first attempt. HTTP abort and timeout do not establish whether an already admitted device action completed. Inspect its durable approval or audit outcome before another attempt.
 
+## Authenticated Node Socket Mode
+
+```ts
+await client.start();
 try {
-  const agents = await client.listAgents();
-  console.log(agents.statuses);
+  const { agents, statuses } = await client.listAgents();
+  console.log(agents.length, statuses.length);
 } 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`.
+Node `start()` consumes published TypedSocket 9 and obtains an Authorization header before the WebSocket upgrade, including its transport compatibility handshake. Credentials stay outside URLs and RPC frames; upgrade redirects are disabled. Socket calls carry the captured home context, and the hub must enforce current subject grants on every message. The package-major handshake establishes compatibility only.
 
-## Version 7 Transport
+While started, methods use that authenticated socket and its bound subject; the header provider is not reevaluated for individual socket messages. To rotate credentials or change subjects, stop and explicitly start a new connection. Automatic reconnects are disabled, so denied upgrade admission settles immediately without repeatedly presenting stale credentials. Calls before startup and after successful stop use authenticated HTTP. An in-flight socket request that fails or is stopped is never resent over HTTP. In socket mode, `timeoutMs` configures both the TypedRequest deadline and TypedSocket’s per-call timeout, with the owning maximum of `300000` milliseconds; omitting it retains the socket’s `30000`-millisecond default. Larger HTTP deadlines are unavailable in socket mode.
+
+Browser and Deno WebSocket APIs cannot supply Authorization upgrade headers. Their `start()` fails with the owning `TypedSocketConnectionPreparationError`, code `callback-rejected`, whose `cause` is a `TypedSocketConnectionPreparationError` with code `unsupported-headers`. The capability check runs before obtaining credentials or opening a socket. Use the authenticated HTTP methods and snapshot polling in those runtimes. The hub has no published application cookie-ticket issuer/consumer contract; this client creates no ticket endpoint and sends no authentication RPC. Native Fetch CORS and credential policy remain server/application responsibilities.
+
+TypedSocket requires TLS for remote Node sockets; insecure `ws:` is permitted only on loopback. Configure an HTTPS hub URL for remote socket use. Credential preparation has the owning ten-second default/maximum deadline; set constructor `socketConnectionPreparationTimeoutMs` to a positive integer no greater than `10000` to reduce it. Its signal aborts on timeout, cancellation, disconnect, and stop. A noncooperative provider cannot hold socket stop open or open a connection with a late credential result.
+
+Concurrent identical `start()`/`stop()` calls coalesce. Mixed lifecycle calls run in order, with at most 64 active and queued operations. `stop()` supersedes earlier queued starts and cancels an in-flight startup using TypedSocket's exported public startup-aborted error. A late-created socket remains owned until its exact cleanup succeeds. A cleanup failure retains that socket for a later `stop()` and blocks new startup; failed startup is retryable through a later explicit `start()`.
 
-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
 
@@ -68,13 +98,35 @@ The client has migrated both transport paths to the version 7 stack: HTTP calls
 
 ## 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.
+Approval decisions bind to the exact action digest returned by `listApprovals()`:
+
+```ts
+const { approvals } = await client.listApprovals({ status: 'pending' });
+const approval = approvals[0];
+if (approval) {
+  const result = await client.submitApproval({
+    approvalId: approval.id,
+    expectedActionDigest: approval.actionDigest,
+    decision: 'approved',
+  });
+  console.log(result.approval.execution.status);
+}
+```
+
+The hub decides whether the authenticated subject may approve the snapshotted action. The shared contract distinguishes decision state from `approval.execution`; an approved decision alone is not proof of a physical effect. An interrupted dispatch may be `indeterminate`. The API client does not automatically resubmit approval decisions or device calls.
 
 ## 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`.
+`watchHomeSnapshot(callback, options?)` owns polling through `getHomeSnapshot()`. The cancellable watcher contract requires `@smarthome.exchange/api` 1.0.0 or newer. It captures and validates plain options once: `abortSignal` terminates the watcher lifetime, `timeoutMs` sets each request deadline, `intervalMs` defaults to `5000` and must be an integer from `1` through `2147483647`, and `immediate: false` defers its first poll. Accessors and unsupported properties are rejected before credential preparation.
+
+Every poll has an owned cancellation signal passed to the credential provider and transport. The async stop function clears the timer, aborts the active request, and drains API-owned request work. External lifetime cancellation is terminal, and a pre-aborted watcher starts no timer or request. No canceled or stopped poll publishes a later callback/error or schedules another poll. A normal request deadline is reported to `onError`; polling continues unless the watcher is stopped. HTTP deadlines begin after credential preparation, as for direct requests; providers must bound their own credential work.
+
+User callbacks and `onError` handlers may await their own stop function. Stop never waits for active user handlers, so user code cannot hold external close open; a handler already running may finish later. Likewise, cancellation settles credential preparation without waiting for a provider that ignores its signal, but provider-owned resources require the provider's cooperative cleanup. An ignored provider's late result never dispatches a request. Watcher stop does not stop the client's independently owned socket; stop the client separately when its socket is also application-owned.
+
+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. Polling does not add a server push contract. Explicit refreshes use the existing `getHomeSnapshot({ abortSignal, timeoutMs })` request options.
 
 ```ts
+const watchLifetime = new AbortController();
 const stopWatching = client.watchHomeSnapshot(
   async ({ availability, snapshot }) => {
     console.log(availability, snapshot.home.name, snapshot.devices.length);
@@ -82,6 +134,8 @@ const stopWatching = client.watchHomeSnapshot(
   {
     intervalMs: 5000,
     immediate: true,
+    abortSignal: watchLifetime.signal,
+    timeoutMs: 5000,
     onError: async (errorArg) => {
       console.error('Snapshot refresh failed:', errorArg);
     },
@@ -89,6 +143,7 @@ const stopWatching = client.watchHomeSnapshot(
 );
 
 // Later, when the UI or process is shutting down:
+watchLifetime.abort();
 await stopWatching();
 ```
 
@@ -124,6 +179,8 @@ for (const callResult of result.results) {
 
 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.
 
+The plan and call `callerId` fields remain part of the authoring contract. They do not grant authority: the server resolves the subject from HTTP authentication. Reuse stable plan and call identifiers when inspecting an uncertain operation; do not generate fresh identifiers to retry a possibly dispatched effect.
+
 ## Scripts
 
 ```bash

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@smarthome.exchange/api',
-  version: '0.1.0',
+  version: '1.0.0',
   description: 'Typed API client for smarthome.exchange hubs.'
 }