sesame-kit 0.4.0

package/docs/commands.md

@@ -0,0 +1,308 @@
+<!-- English | [日本語](./commands.ja.md) -->
+
+# Command Reference
+
+> 日本語: [commands.ja.md](./commands.ja.md)
+
+> Every CLI command. Each subcommand also accepts `sesame <cmd> --help`.
+> When calling from another language via `sesame serve`, `sesame rpc` (or `rpc.discover`) is the machine-readable source of truth.
+
+## Device operations (device as the subject)
+
+The subject is the **device**. `sesame <device> <action>` mirrors the SDK's `device.action()` ordering.
+`device` is a name (substring match allowed). Omit `action` for that device's interactive menu; omit `device` too for the interactive menu over all devices (= `session`).
+
+```bash
+sesame front unlock            # front.unlock()  (substring match: sesame 玄関 unlock)
+sesame front lock              # lock
+sesame front toggle            # invert from current state
+sesame front status            # status (locked / unlocked, position)
+sesame front autolock 30       # autolock (BLE only. 0 = off)
+sesame kitchen click           # SESAME Bot click (Bot2/Bot3)
+
+sesame front                   # interactive menu for front
+sesame                         # interactive menu for all devices (session)
+```
+
+action: `unlock` / `lock` / `toggle` / `click` / `status` / `autolock <seconds>` (**which operations apply depends on the type** — see below).
+
+### The route (transport) defaults to all-routes mode
+
+- The default is all-routes mode; the route is chosen automatically. Ops that the cloud can carry go over cloud, and only BLE-required ops such as `autolock` open a BLE connection (so you don't pay the BLE scan/connect cost every time).
+- Pin the route with `--ble-only` / `--cloud-only`. `--ble-only` takes a few seconds to connect. `--cloud-only` restricts some operations.
+- To hold a BLE connection open across a run of operations, use `sesame session` (the multi-device form of `sesame <device>`).
+
+```bash
+sesame front unlock            # all-routes mode (the tool picks the route)
+sesame front autolock 30       # BLE-required op → connects over BLE automatically
+sesame front lock --ble-only   # pinned to BLE (a few seconds to connect)
+sesame front lock --cloud-only # pinned to cloud
+```
+
+> For the design details (the unified cloud/BLE capability model), see [architecture.md](./architecture.md).
+
+Manage lock definitions with the `locks` group:
+
+```bash
+sesame locks ls                # list registered locks
+sesame locks set-default front
+sesame locks add               # add interactively (deviceUUID + secretKey)
+sesame locks add --name front --uuid <UUID> --secret <32hex> --model sesame_5_pro  # non-interactive / flag-based add
+sesame locks sync-from-devices # auto-import from the result of devices
+sesame locks rm front
+```
+
+A cloud operation returns only after the synchronous ack (`biz3TriggerLocker`, `success:true`) arrives (timeout 10s).
+
+> autolock cannot be set over the cloud (BLE only). Use `sesame autolock`. Background in [architecture.md](./architecture.md).
+
+---
+
+## Hub3 IR
+
+### Emit an existing key
+
+```bash
+sesame send 停止                         # emit on the default remote
+sesame send 停止 --remote ac
+sesame list                              # list the keys registered on a remote
+```
+
+### Advanced operations
+
+```bash
+# Learn: aim a physical remote at the Hub3 and press a button
+sesame ir learn ac 強風                  # learn the "強風" key onto remote=ac
+                                         # → Hub3 into REGISTER mode → capture waveform → back to CONTROL → addIRCode
+
+# Mode control
+sesame ir mode get [hub3]                # get the current mode (0=CONTROL / 1=REGISTER)
+sesame ir mode set 1 [hub3]              # force a switch to REGISTER (for debugging)
+
+# Key CRUD
+sesame ir key rename ac 強風 強運転        # rename a key (server + config)
+sesame ir key rm ac 試運転                # delete a key
+
+# Remote CRUD (server side)
+sesame ir remote-list ac              # registered remotes (by irType)
+sesame ir remote-rm ac                   # delete from server
+sesame ir remote-rename "リビング" ac      # change the server alias
+
+# Preset DB
+sesame ir search ac ダイキン           # manufacturer DB search (max 1000)
+sesame ir match ac <hex波形>           # match a learned waveform against known remotes
+```
+
+> To refer to a self-learned remote, use the real type `0xFE00` (65024) for `irType`. Passing the menu id `0xFEFF` makes the server match fail and the remote is not found. See [architecture.md](./architecture.md) for details.
+
+---
+
+## Device management
+
+```bash
+sesame device user-ls                    # list personal devices
+sesame device status <uuid>              # current state
+sesame device rename <uuid> "玄関 SESAME"  # rename
+sesame device rm <uuid>                  # remove from the company
+
+sesame history <uuid>                    # lock open/close history
+sesame history                           # all devices
+sesame battery <uuid>                    # battery history (light/heavy voltage + percentage)
+sesame firmware                          # list firmware currently being distributed
+```
+
+---
+
+## WebAPI proxy
+
+Set the REST API key (apiKeyId) issued in the biz3 dev console as `config.apiKeyId`, and you can proxy any REST WebAPI call over the WebSocket:
+
+```bash
+# with "apiKeyId": "..." in config.json:
+sesame webapi webapi_ssm_shadow_get --query '{"device_id":"..."}'
+sesame webapi webapi_history_get --query '{"device_id":"...","page":0,"lg":"ja","isBiz":true}'
+sesame webapi webapi_cmd_send --body '{"device_id":"...","cmd":83,"sign":"...","history":"..."}'
+```
+
+---
+
+## Scheduling (biz3Schedule)
+
+```bash
+sesame schedule ls                 # list registered schedules (lock/unlock/upgrade_firmware)
+sesame schedule cancel <id>        # cancel a schedule (omit id to pick interactively from the list)
+```
+
+> Since **biz3 web has no op to create a schedule**, the CLI offers only list / cancel.
+
+---
+
+## Access control (NFC cards / passcodes)
+
+The **server-DB sync** ops for SESAME Touch (Pro) NFC cards and keypad passcodes.
+Writing to the device firmware itself goes through a separate path (BLE); this layer handles only the DB-side sync — a two-layer structure.
+
+```bash
+sesame access cards ls --device <uuid> [--device <uuid2> ...]   # list cards
+sesame access cards clear --device <uuid>                       # delete all cards on the given device
+sesame access cards rm --json '[{"deviceID":"...","cardID":"..."}]'   # delete individually (no response)
+sesame access cards owner <cardID> [ownerSubUUID]               # assign an owner ('' to clear)
+sesame access passcodes ls --device <uuid>                      # list passcodes
+```
+
+> `rm` (delCards/delPasscodes) has no response handler in biz3 and is **fire-and-forget**. No completion response is returned.
+
+---
+
+## Company / org management (biz3 enterprise)
+
+Enterprise features for handling multiple companies, employees, roles, and device groups. `companyID` is filled in automatically from your login.
+
+```bash
+# Company
+sesame company ls                  # list the companies you belong to
+sesame company rename "新社名"      # rename the preferred company
+sesame company add "新会社"         # register a new company
+sesame company payment             # get billing settings
+
+# Org
+sesame org employee ls             # list employees
+sesame org employee search <kw>    # cross-CS user search
+sesame org role ls                 # list role tags
+sesame org group ls                # list employee groups
+sesame org device-group ls         # list device groups
+sesame org keys device <deviceUUID>   # enumerate employees holding a key for the device
+```
+
+### Guest sharing (key-sharing URL / QR)
+
+Generates the same `ssm://UI?t=sk&sk=…&l=…&n=…` URL that the SESAME app reads as a sharing QR.
+Only with `--level 2` (guest) is a single-use `guestKeyId` issued and embedded (same behavior as biz3).
+
+```bash
+sesame org keys share-url --device <uuid> --level 2 --name "来客用"   # guest sharing URL
+sesame org keys share-url --device <uuid> --level 1                  # manager key sharing
+sesame org keys share-url --device <uuid> --qr                       # show a QR in the terminal (requires qrcode-terminal)
+```
+
+> Building and parsing the sharing URL is a 1:1 port of biz3 `generateInviteGuestQRCodeByInfo` / `readQrcode`.
+> It is **independent of any image library**, so you can paste the output URL into any QR generator to share.
+> Many create/update ops take a struct via `--json '<…>'` (each subcommand's `--help` has examples).
+> Note that `org employee confirm <email>` signs out the current session on success, per the biz3 spec.
+
+---
+
+## Hub3 IoT control (biz3OperateIoT)
+
+Direct commands to the Hub3 itself (LED dimming, LTE relay, firmware update, Matter pairing, etc.).
+Pass `--device <hub3UUID> --secret <hex>`, or select from connected devices when interactive.
+
+```bash
+sesame iot led 80 --device <uuid> --secret <hex>   # LED dimming (0-100)
+sesame iot led --get --device <uuid> --secret <hex># get the current dimming level
+sesame iot relay on  --device <uuid> --secret <hex># LTE relay open/close
+sesame iot firmware-update --device <uuid> --secret <hex> --wait 60
+sesame iot matter-code --device <uuid> --secret <hex>   # Matter pairing code
+```
+
+---
+
+## Preset IR remotes (HXD command)
+
+Emit air conditioners and the like **from preset DB commands** rather than by "learning". Specify the Hub3 as `--device`:
+
+```bash
+sesame preset-ir air --device <hub3uuid> --code <n> --power --temp 26 --mode 1 --fan 2
+sesame preset-ir button --device <hub3uuid> --code <n> --button power --irtype 8192
+sesame preset-ir send --device <hub3uuid> --command <hex> --irtype 49152   # emit raw hex
+```
+
+> Preset command generation (biz3's HXDCommandProcessor) is not yet ported, so preset emit does not currently work.
+> Use a self-learned remote (`sesame ir learn`) instead ([known limitations](../README.md#known-limitations)).
+
+---
+
+## BLE direct control (without the cloud)
+
+Operate registered SESAME devices **directly** over the PC's Bluetooth. Since it does not go through the cloud (WS), it works offline, and **settings such as `autolock` that the cloud could not apply do take effect on the device**.
+
+BLE operation is not a dedicated command — just **add `--ble-only`** to a device-subject operation
+(`autolock` is BLE-required, so it goes over BLE automatically even without the flag):
+
+```bash
+sesame front status --ble-only   # current state (locked / unlocked, position)
+sesame front unlock --ble-only   # unlock (Lock / Bike)
+sesame front lock   --ble-only   # lock (Lock)
+sesame front toggle --ble-only   # invert based on current state (Lock)
+sesame kitchen click --ble-only  # SESAME Bot click (Bot2/Bot3)
+sesame front autolock 30         # autolock (BLE required. Actually takes effect)
+sesame front autolock 0          # disable
+```
+
+> **BLE errors are given meaning via `SesameResultCode`** — when a device returns a non-zero result, the library throws
+> `BleResultError` (`.resultCode` / `.resultName`). `resultName` matches the official SesameSDK's
+> `SesameResultCode` (`success`/`invalidFormat`/`notSupported`/`invalidSig`/`notFound`/`unknown`/
+> `busy`/`invalidParam`/`invalidAction`), so you can branch on it programmatically.
+> Note: this is the **device-layer (SesameOS3) taxonomy** and is available only over the BLE direct route
+> (the cloud route does not surface this code, so it does not appear in `sesame serve`'s `kind`).
+
+### Operations per device type (per the official SesameSDK)
+
+The operation set differs by device type. The SDK defines capabilities asymmetrically per type, and this CLI reproduces the same asymmetry by determining the type from the `model` in `config`. Unsupported operations are rejected by the command (e.g. `lock` on a Bot → "use click").
+
+| Type (model examples) | BLE operations | mechStatus |
+|---|---|---|
+| Lock `sesame_5`/`_pro`/`sesame_6`/`_pro`/`_us`/`miwa` | `lock` `unlock` `toggle` `autolock` `status` | locked/unlocked + position |
+| Bot `bot_2`/`bot_3` | `click` `status` | locked/unlocked (no position) |
+| Bike `bike_2`/`bike_3` | `unlock` `status` | locked/unlocked (no position) |
+| Touch/Face/Sensor/Remote, Hub3, WiFiModule2 | (no BLE lock operations) | — |
+| OS2 `sesame_2`/`_4`, `ssmbot_1`, `bike_1` | BLE not implemented (key derivation/crypto is a separate path). Operate over cloud | — |
+
+> "locked/unlocked" is only the **two values** based on the presence of `isInLockRange` in OS3. OS3 has no intermediate (moved) state
+> (only OS2 devices such as Sesame2 have moved). For the BLE implementation design, see [architecture.md](./architecture.md).
+
+Usable as a library too:
+
+```js
+import { SesameBle } from "sesame-kit";   // or: import { ble } from "sesame-kit"
+await SesameBle.use({ deviceUUID, secretKey }, async (lock) => {
+  await lock.unlock();
+  await lock.autolock(30);
+  console.log(lock.lastStatus);            // { state, batteryMv, position, ... }
+});
+```
+
+> The target is **SesameOS3** (SESAME 5 / 5 Pro / Touch, etc.). New pairing (registering an unregistered device) is a separate phase.
+
+---
+
+## Interactive session
+
+The interactive session (`sesame` / `sesame <device>` / `sesame session`) is an **app-like all-routes mode**.
+It lists **every device you can operate**: Locks/Bots/Bikes (BLE + cloud) and, if you are logged in, **Hub3** (cloud: IR send / relay / LED).
+It attaches BLE best-effort but **does not exit even when BLE is zero**: devices out of range or without permission are **operated over cloud** when you are logged in (devices with a BLE connection prefer BLE = lower latency + autolock available).
+
+```text
+$ sesame                      # all devices (alias: sesame session / watch)
+[ble] バックグラウンドで接続中... (クラウドで操作可能)
+─── SESAME セッション ── 矢印キーで選択 ───
+  front   [sesame_5·BLE]:   state=locked pos=-176
+  kitchen [bot_2·cloud]:    (BLE未接続)
+  hub3-居間 [hub3·hub3]:    (Hub3: IR / リレー / LED)
+
+? 操作するデバイス          ← ① pick a device
+? front の操作              ← ② pick an operation (varies by type)
+  ロック  : 🔓 解錠 / 🔒 施錠 / ↕ トグル / ⏱ オートロック / ℹ 状態
+  Bot     : 👆 クリック / ℹ 状態
+  Hub3    : 📡 IR 送信 (リモコン→キー選択) / 🔌 リレー ON/OFF / 💡 LED 調光
+```
+
+The trailing tag on each device, `·BLE` / `·cloud`, is the route. Because **`autolock` is BLE-required**, cloud devices are prompted to "move closer and retry". If only one connection exists, device selection is skipped.
+
+**Live updates**: the screen is a live dashboard built with **Ink (React for CLI)** and **re-renders in place** as BLE state changes or background connections complete (cloud→BLE promotion is real-time too). Startup shows the menu immediately over cloud and connects BLE in the background, so you don't wait the 8-second scan. Quit with `q` / Esc.
+
+**Prerequisites**:
+- Keys reuse the existing `config.locks` (deviceUUID/secretKey imported via `sesame locks sync-from-devices`). No new registration needed.
+- The BLE adapter `@abandonware/noble` is required. As an `optionalDependency`, `npm install` tries to **install it automatically**, and on unsupported environments the install itself still succeeds (only BLE is disabled). To install it manually, `npm i @abandonware/noble`.
+- **macOS requires Bluetooth permission for Terminal/iTerm** (System Settings → Privacy & Security → Bluetooth).
+- Be within BLE range (close proximity) of the lock.

package/docs/library.ja.md

@@ -0,0 +1,152 @@
+<!-- [English](./library.md) | 日本語 -->
+
+# ライブラリとして使う
+
+> English: [library.md](./library.md)
+
+`sesame` CLI と同じ機能を Node.js から直接呼べる。他言語から使うなら [`sesame serve`](../README.ja.md#言語非依存バックエンド-sesame-serve) を、Node 内で使うならこちら。
+
+## 一番楽な形: `use()` ヘルパ (auto connect/close)
+
+```js
+import { SesameHub3 } from "sesame-kit";
+
+await SesameHub3.use(async (hub) => {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");
+});
+// connect / close は自動。例外時も close される。
+```
+
+設定ディレクトリを変えたい:
+
+```js
+await SesameHub3.use({ configDir: "/tmp/cfg" }, async (hub) => {...});
+```
+
+config ファイル不要で in-memory token を使いたい (他プロジェクト埋込み等):
+
+```js
+await SesameHub3.use({
+  tokenStore: {
+    // load() が返す idToken は実際の Cognito 由来の JWT である必要があります:
+    //   - exp クレーム (UNIX秒) が「現在時刻 + 60秒」より先 でないと毎回 refresh が走る
+    //   - sub クレーム が UUID 形式。ロック操作の history (誰が操作したか) に使われるため必須。
+    // → 通常は `sesame login` で取得し FileTokenStore に保存された値をそのまま使う。
+    //   独自 store は「その値を別の場所から load/save する」だけで、idToken を自作しない。
+    load() { return { idToken, refreshToken, clientId: "6ialca0p8u0lsgvbmvsljfm305" }; },
+    save(t) { /* persist however */ },
+    clear() {}, loadPending() { return null; }, savePending() {}, clearPending() {},
+  },
+  config: { companyID: "ch_X", wsUrl: "wss://..." },  // companyID/wsUrl は省略可 (DEFAULT_CONFIG が補完)
+}, async (hub) => {
+  await hub.unlockDevice({ deviceUUID: "...", secretKey: "..." });
+});
+```
+
+## Config を介さない直接 API (name lookup なし)
+
+```js
+await SesameHub3.use(async (hub) => {
+  // ロック (config の locks 定義に頼らず deviceUUID + secretKey 直指定)
+  await hub.unlockDevice({ deviceUUID, secretKey });
+  await hub.lockDevice({ deviceUUID, secretKey });
+  await hub.toggleDevice({ deviceUUID, secretKey });
+  await hub.botClickDevice({ deviceUUID, secretKey });
+  await hub.triggerLockDevice({ deviceUUID, secretKey, cmd: 83 });   // 任意 cmd
+
+  // IR
+  await hub.sendIRDirect({
+    hub3DeviceId, irDeviceUUID, irType: 49152, command: keyUUID, operation: "learnEmit",
+  });
+  const keys = await hub.getIRCodesDirect({ hub3DeviceId, irDeviceUUID });
+});
+```
+
+## イベント購読 (state push)
+
+```js
+await SesameHub3.use(async (hub) => {
+  // 設定名でロック状態の push を購読
+  const off1 = hub.onLockStateChange("front", (msg) => {
+    console.log("front state:", msg.data?.state);
+  });
+
+  // UUID 直指定でも OK
+  const off2 = hub.onLockStateChangeDevice(deviceUUID, (msg) => { ... });
+
+  // IR 学習データを受信 (内部で setIRMode + subscribeIRData を発行、unsubscribe で元に戻す)
+  const offLearn = await hub.onIRLearned("livinghub3", (irData) => {
+    console.log("captured:", irData);
+  });
+
+  // デバイス state 一括購読 (subscribeDevicesUpdate)
+  const off3 = hub.onDeviceUpdate(
+    [{ deviceUUID, deviceModel: "sesame_5_pro" }],
+    (msg) => console.log(msg),
+  );
+
+  await new Promise((r) => setTimeout(r, 30_000));
+  off1(); off2(); off3();
+  await offLearn();
+});
+```
+
+## 名前ベースの古い API (config 必須)
+
+```js
+import { SesameHub3 } from "sesame-kit";
+
+const hub = await SesameHub3.fromConfig();
+await hub.connect();
+try {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");
+  await hub.learnIR("ac", "強風", { onPrompt: () => console.log("ボタン押して") });
+  const devs = await hub.listDevices();
+  const hist = await hub.getDeviceHistory([{ deviceUUID: devs[0].deviceUUID }]);
+} finally {
+  await hub.close();
+}
+```
+
+## 低レベル import (transport / op 関数 / crypto を直接)
+
+メインエントリ (`"sesame-kit"`) から取れるもの:
+
+```js
+import {
+  Hub3WsClient,          // WebSocket + reconnect/keepalive/queue/sleep 検知
+  sendIR, getIRCodes,    // IR 基本 op (named export)
+  triggerLock, lockLock, lockUnlock, lockToggle, botClick,  // lock 個別関数 (named export)
+  ir, devices, crypto, lock, auth,  // ← これらは namespace export (オブジェクト)
+  FileTokenStore, ConfigStore, configPaths,
+} from "sesame-kit";
+
+// namespace は メソッドをドット経由で呼ぶ:
+crypto.cmacTime("...");          // ✅ メインから取れるのは namespace の crypto
+auth.getValidIdToken(store);     // ✅ 同上
+// ⚠️ import { cmacTime } from "sesame-kit" は不可 (cmacTime は crypto namespace の中)
+```
+
+個別関数を named import したい場合はサブパス (`package.json` の exports map) から:
+
+```js
+import { cmacTime } from "sesame-kit/crypto";   // ✅ サブパスなら named でOK
+import { learnIRKey } from "sesame-kit/ir";
+import { lockLock } from "sesame-kit/lock";
+```
+
+## TypeScript
+
+`.d.ts` 型定義を同梱しています (`types/`、JSDoc から `tsc` で生成)。`moduleResolution: "node16" / "nodenext" / "bundler"` で
+パッケージ名 import (`from "sesame-kit"` / `"sesame-kit/crypto"` 等) すれば型が効きます:
+
+```ts
+import { SesameHub3 } from "sesame-kit";
+await SesameHub3.use(async (hub) => {
+  await hub.unlockDevice({ deviceUUID: "...", secretKey: "..." });  // 引数が型チェックされる
+});
+```
+
+型は `npm run build:types` で再生成できます (ソースの JSDoc を編集したら実行)。

package/docs/library.md

@@ -0,0 +1,152 @@
+<!-- English | [日本語](./library.ja.md) -->
+
+# Using sesame-kit as a library
+
+> 日本語: [library.ja.md](./library.ja.md)
+
+The same features as the `sesame` CLI can be called directly from Node.js. To use it from other languages, use [`sesame serve`](../README.md#language-agnostic-backend-sesame-serve); to use it inside Node, use this.
+
+## The simplest form: the `use()` helper (auto connect/close)
+
+```js
+import { SesameHub3 } from "sesame-kit";
+
+await SesameHub3.use(async (hub) => {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");
+});
+// connect / close are automatic, including close on exceptions.
+```
+
+To change the config directory:
+
+```js
+await SesameHub3.use({ configDir: "/tmp/cfg" }, async (hub) => {...});
+```
+
+To use an in-memory token without a config file (e.g. embedding in another project):
+
+```js
+await SesameHub3.use({
+  tokenStore: {
+    // The idToken returned by load() must be a real Cognito-issued JWT:
+    //   - the exp claim (UNIX seconds) must be later than "now + 60s", or a refresh runs every time.
+    //   - the sub claim must be in UUID format. It is used for lock-operation history (who operated it), so it is required.
+    // → Normally use the value obtained via `sesame login` and saved by FileTokenStore as-is.
+    //   A custom store only "loads/saves that value from/to a different place"; it does not fabricate the idToken.
+    load() { return { idToken, refreshToken, clientId: "6ialca0p8u0lsgvbmvsljfm305" }; },
+    save(t) { /* persist however */ },
+    clear() {}, loadPending() { return null; }, savePending() {}, clearPending() {},
+  },
+  config: { companyID: "ch_X", wsUrl: "wss://..." },  // companyID/wsUrl are optional (DEFAULT_CONFIG fills them in)
+}, async (hub) => {
+  await hub.unlockDevice({ deviceUUID: "...", secretKey: "..." });
+});
+```
+
+## Direct API without config (no name lookup)
+
+```js
+await SesameHub3.use(async (hub) => {
+  // Lock (pass deviceUUID + secretKey directly, without relying on the config locks definitions)
+  await hub.unlockDevice({ deviceUUID, secretKey });
+  await hub.lockDevice({ deviceUUID, secretKey });
+  await hub.toggleDevice({ deviceUUID, secretKey });
+  await hub.botClickDevice({ deviceUUID, secretKey });
+  await hub.triggerLockDevice({ deviceUUID, secretKey, cmd: 83 });   // arbitrary cmd
+
+  // IR
+  await hub.sendIRDirect({
+    hub3DeviceId, irDeviceUUID, irType: 49152, command: keyUUID, operation: "learnEmit",
+  });
+  const keys = await hub.getIRCodesDirect({ hub3DeviceId, irDeviceUUID });
+});
+```
+
+## Event subscription (state push)
+
+```js
+await SesameHub3.use(async (hub) => {
+  // Subscribe to lock-state push by config name
+  const off1 = hub.onLockStateChange("front", (msg) => {
+    console.log("front state:", msg.data?.state);
+  });
+
+  // Passing a UUID directly also works
+  const off2 = hub.onLockStateChangeDevice(deviceUUID, (msg) => { ... });
+
+  // Receive IR learning data (internally issues setIRMode + subscribeIRData, and reverts on unsubscribe)
+  const offLearn = await hub.onIRLearned("livinghub3", (irData) => {
+    console.log("captured:", irData);
+  });
+
+  // Bulk-subscribe to device state (subscribeDevicesUpdate)
+  const off3 = hub.onDeviceUpdate(
+    [{ deviceUUID, deviceModel: "sesame_5_pro" }],
+    (msg) => console.log(msg),
+  );
+
+  await new Promise((r) => setTimeout(r, 30_000));
+  off1(); off2(); off3();
+  await offLearn();
+});
+```
+
+## The older name-based API (config required)
+
+```js
+import { SesameHub3 } from "sesame-kit";
+
+const hub = await SesameHub3.fromConfig();
+await hub.connect();
+try {
+  await hub.unlock("front");
+  await hub.send("ac", "停止");
+  await hub.learnIR("ac", "強風", { onPrompt: () => console.log("press the button") });
+  const devs = await hub.listDevices();
+  const hist = await hub.getDeviceHistory([{ deviceUUID: devs[0].deviceUUID }]);
+} finally {
+  await hub.close();
+}
+```
+
+## Low-level imports (transport / op functions / crypto directly)
+
+Available from the main entry (`"sesame-kit"`):
+
+```js
+import {
+  Hub3WsClient,          // WebSocket + reconnect/keepalive/queue/sleep detection
+  sendIR, getIRCodes,    // IR base ops (named export)
+  triggerLock, lockLock, lockUnlock, lockToggle, botClick,  // individual lock functions (named export)
+  ir, devices, crypto, lock, auth,  // ← these are namespace exports (objects)
+  FileTokenStore, ConfigStore, configPaths,
+} from "sesame-kit";
+
+// Call namespace methods via dot:
+crypto.cmacTime("...");          // ✅ what you get from the main entry is the crypto namespace
+auth.getValidIdToken(store);     // ✅ same as above
+// ⚠️ import { cmacTime } from "sesame-kit" does not work (cmacTime is inside the crypto namespace)
+```
+
+To named-import individual functions, use the subpath (the `exports` map in `package.json`):
+
+```js
+import { cmacTime } from "sesame-kit/crypto";   // ✅ named works on a subpath
+import { learnIRKey } from "sesame-kit/ir";
+import { lockLock } from "sesame-kit/lock";
+```
+
+## TypeScript
+
+`.d.ts` type definitions are bundled (`types/`, generated from JSDoc with `tsc`). With `moduleResolution: "node16" / "nodenext" / "bundler"`,
+package-name imports (`from "sesame-kit"` / `"sesame-kit/crypto"` etc.) get types:
+
+```ts
+import { SesameHub3 } from "sesame-kit";
+await SesameHub3.use(async (hub) => {
+  await hub.unlockDevice({ deviceUUID: "...", secretKey: "..." });  // arguments are type-checked
+});
+```
+
+Types can be regenerated with `npm run build:types` (run it after editing the JSDoc in the source).

package/docs/migration.ja.md

@@ -0,0 +1,13 @@
+<!-- [English](./migration.md) | 日本語 -->
+
+# 旧版からのマイグレーション
+
+> English: [migration.md](./migration.md)
+
+旧 `sesame-hub3` (CLI=`hub3-ir`) からのアップグレード:
+
+- CLI 名は `sesame` に変更 (旧 `hub3-ir` は廃止)。シェルスクリプトを使っている場合は置換。
+- 設定ディレクトリ (`~/.config/sesame-hub3`) は変更なし、既存 config.json はそのまま使える。
+- `locks` キーは自動で追加される (空 `{}` から開始)。`sesame locks sync-from-devices` で `devices` コマンドの出力から取り込み可能。
+
+旧 `.env + .tokens.json + keys.json` からの移行は `sesame migrate` がそのまま使える。

package/docs/migration.md

@@ -0,0 +1,13 @@
+<!-- English | [日本語](./migration.ja.md) -->
+
+# Migrating from older versions
+
+> 日本語: [migration.ja.md](./migration.ja.md)
+
+Upgrading from the old `sesame-hub3` (CLI = `hub3-ir`):
+
+- The CLI is renamed to `sesame` (the old `hub3-ir` is removed). Replace it in any shell scripts.
+- The config directory (`~/.config/sesame-hub3`) is unchanged; an existing config.json works as-is.
+- The `locks` key is added automatically (starting from an empty `{}`). Import from the `devices` command output with `sesame locks sync-from-devices`.
+
+Migrating from an old `.env` + `.tokens.json` + `keys.json` works with `sesame migrate`.