# EnterSense TypeScript SDK

An ESM client for the stateless v1 intent API, with bundled TypeScript declarations and no runtime dependencies. It supports Node.js 22+ and browser environments with native fetch/AbortController. Install the versioned `.tgz` downloaded from the website or build this directory; registry publication is separate.

```sh
npm install ./entersense-sdk-0.1.1.tgz
```

```ts
import { EnterSenseClient } from "@entersense/sdk";

const client = new EnterSenseClient({ baseUrl: "https://YOUR-API-HOST" });
client.registerHandler("navigation.open", ({ target }) => {
  // Your router decides what navigation means. No built-in navigation occurs.
  console.log("Requested route:", target);
});
const request = {
  input: { sense: "voice" as const, transcript: "open home" },
  rules: [
    {
      id: "home",
      match: "open home",
      action: { type: "navigation.open" as const, target: "/" },
    },
  ],
};
const resolution = await client.resolve(request); // Returns intents, executes nothing.
const executed = await client.resolveAndDispatch(request); // Explicitly invokes registered handlers.
```

`capabilities()`, `actions()`, `templates()`, `validate(request)`, and `resolve(request)` call the matching `/api/v1/` endpoint. `templates()` returns requests you can edit. `registerHandler(type, fn)` receives a typed action and its intent; it returns an unregister callback. `dispatch(resolution)` is also explicit. All required handlers are checked before dispatch begins. Handler failure stops later handlers and is never retried; completed application effects are not rolled back.

## Configuration and cancellation

```ts
const controller = new AbortController();
const client = new EnterSenseClient({
  baseUrl: "https://YOUR-API-HOST",
  timeoutMs: 5000,
  fetch: globalThis.fetch, // Optional injectable transport, also useful for tests.
});
const pending = client.resolve(request, { signal: controller.signal });
controller.abort();
```

The base URL is required and can contain an application proxy prefix. Credentials, query strings and fragments are rejected. Default timeout is 10000 ms. Requests and response-body reading obey the deadline; abort cancels client waiting and native fetch. Cancellation cannot undo a request the server already received. Neither POST retries nor redirects are implicit.

Typed errors distinguish API rejection (`status`, server `code`), request timeout, abort, transport/invalid response, missing handler and handler failure. No request-body or secret logging occurs.

## Response validation

Catalog entries and template requests are validated before being returned. Invalid action payloads are rejected before registered handlers execute, including external navigation, invalid identifiers, unknown action fields and oversized UTF-8 payloads. Optional `confidence` and `minConfidence` accept both omission and JSON `null`, matching the generated API and templates. Applications still own authorization and the safety of handler side effects.

## Actions and product boundaries

Configure `enabled` and `minConfidence` on rules, and explicit `confidence` on inputs. Confidence comes from your adapter, never server inference. Motion input is a normalized gesture such as `swipe_left`; voice input is an explicit transcript. The SDK does not acquire microphone/camera data or perform recognition.

The six declarative types are `navigation.open`, `text.insert`, `media.play`, `media.pause`, `scene.focus`, and `workflow.trigger`. Workflow parameters are bounded string maps; destinations/resources remain application-owned. SDK handlers do not imply a shell or server HTTP relay. Voice production/motion beta are founder-reported product stages; they do not prove hardware, model accuracy or an integration. Other senses currently produce HTTP 422 `sense_unavailable`.

## Development

```sh
cd sdk/typescript
npm ci
npm run typecheck
npm test
npm run build
npm pack
```

Version `0.1.1`; exports compiled ESM and generated `.d.ts` declarations from `dist/`. Typed request/action contracts, explicit handler dispatch and transport adapters remain separate. Offline injected-transport tests and optional real endpoint contract tests establish different evidence. [SOURCES.md](SOURCES.md) records official guidance and checked versions.

## License

License terms have not yet been published. Public downloads do not grant an open-source license; the source repository remains private.