sesame-kit 0.4.0

package/src/ir.js

@@ -0,0 +1,341 @@
+// SESAME Hub3 IR リモコン関連の高レベル操作。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/api/useRemoteCtrl.js
+//
+// 基本 op (sendIR / getIRCodes) は transport.js に置いたまま、
+// それ以外の op (remote/key の CRUD, mode 制御, 学習フロー, preset 検索) をここに集約。
+//
+// 命名規則 (vendor 由来の不一致):
+//   - sendIR: deviceId / irDeviceUUID    ← Hub3 / リモコン
+//   - getIRCodes/updateIRCode/deleteIRCode: hub3DeviceId / remoteId
+//   - updateRemoteAlias: deviceId / uuid  ← Hub3 / リモコン (Alias 系のみ uuid 名)
+//   - deleteIRRemote: hub3DeviceId / uuid
+// → biz3 のフィールド命名は op ごとに微妙に違うので、こちら側ヘルパーで吸収する。
+//
+// ⚠️ irType の特大トラップ (自己学習リモコンの type が 2 つある):
+//
+//   biz3 の公式 UI には「リモコン種別の選択メニュー」(ir-type-list 画面) があり、
+//   エアコン/テレビ/照明/扇風機/学習 から選ぶ。各項目に整数 id が振られている:
+//       エアコン=0xC000 テレビ=0x2000 照明=0xE000 扇風機=0x8000 学習=0xFEFF
+//
+//   プリセット (エアコン等) を選ぶと、その「メニュー id」がそのまま
+//   実デバイスの remote.type になり、sendIR にも乗る。つまり id = 実 type で一致する。
+//
+//   ところが「学習」だけは違う。メニュー id は 0xFEFF だが、学習を選んだ後に
+//   実際に作られるリモコンの remote.type は 0xFE00 になる (= 旧実装が実機で観測した 65024)。
+//   0xFEFF は「学習メニューを押した」という UI 上の印でしかなく、
+//   デバイスにも sendIR にも 0xFEFF は決して現れない。
+//
+//   → このコードで getRemoteList / matchRemote などに渡す type や、
+//     自己学習リモコンを表す値は **必ず実 type = 0xFE00 (65024)** を使う。
+//     UI メニュー id の 0xFEFF を実 type と勘違いすると、サーバ照合が一致せず
+//     リモコンが見つからない/動かない。一次資料: learn/index.js:142,
+//     useRemoteCtrl.js:228 (どちらも 0xFE00 を学習リモコンの type として扱う)。
+//     値の一覧と出所は crypto.js の IR_TYPE コメントにも記載。
+
+import { generateUUID } from "./crypto.js";
+import { ACTION_TYPES } from "../vendor/biz3/constants/messageConstants.js";
+import { assertSuccess } from "./util.js";
+
+const ACTION = ACTION_TYPES.BIZ3_IR_REMOTE; // "biz3IRRemote" (vendor 由来)
+const DEFAULT_TIMEOUT_MS = 10_000;
+const LEARN_DEFAULT_TIMEOUT_MS = 60_000;
+
+const MODE = Object.freeze({
+  CONTROL: 0,
+  REGISTER: 1,
+});
+
+const modeTopic = (deviceId) => `hub3/${deviceId}/ir/mode`;
+const dataTopic = (deviceId) => `hub3/${deviceId}/ir/learned/data`;
+
+// ---------- remote 一覧 / 検索 ----------
+
+/**
+ * 登録済みリモコン一覧を取得 (ページング)。
+ * @param {{type:number, companyID:string, page?:number, pageSize?:number}} p
+ *   type は **実 remote.type** (自己学習=0xFE00, UI メニューの 0xFEFF ではない / 上記トラップ参照)
+ */
+export async function getRemoteList(client, p) {
+  const frame = {
+    action: ACTION,
+    op: "getRemoteList",
+    type: p.type,
+    companyID: p.companyID,
+    pagination: { page: p.page ?? 1, pageSize: p.pageSize ?? 200 },
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "getRemoteList", { strict: true });
+  return resp.data || [];
+}
+
+/**
+ * プリセットリモコン (メーカー DB) 検索。最大 1000 件返却。
+ * @param {{type:number, companyID:string, searchTerm:string}} p
+ */
+export async function searchRemoteList(client, p) {
+  const frame = {
+    action: ACTION,
+    op: "searchRemoteList",
+    type: p.type,
+    companyID: p.companyID,
+    searchTerm: p.searchTerm,
+    pagination: { page: 1, pageSize: 1000 },
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "searchRemoteList", { strict: true });
+  return resp.data || [];
+}
+
+// ---------- remote CRUD ----------
+
+/**
+ * リモコンを追加 (Hub3 1 台あたり 3 個上限がサーバ側にある)。
+ * `remote` の形は biz3 がそのまま remoteDevice オブジェクトを渡しているので、
+ * 呼び出し側で {hub3DeviceId, type, name, irOperation, ...} を入れる。
+ */
+export async function addIRRemote(client, { remote, companyID }) {
+  const frame = { action: ACTION, op: "addIRRemote", remote, companyID };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "addIRRemote", { strict: true });
+  return resp.data || resp;
+}
+
+/** リモコン削除。 */
+export async function deleteIRRemote(client, { hub3DeviceId, uuid, companyID }) {
+  const frame = { action: ACTION, op: "deleteIRRemote", hub3DeviceId, uuid, companyID };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "deleteIRRemote", { strict: true });
+  return resp;
+}
+
+/** リモコンの alias を更新。注: 命名差で `deviceId`/`uuid`。 */
+export async function updateRemoteAlias(client, { hub3DeviceId, uuid, alias, companyID }) {
+  const frame = {
+    action: ACTION,
+    op: "updateRemoteAlias",
+    deviceId: hub3DeviceId, // 公式仕様: ここだけ deviceId
+    uuid,
+    alias,
+    companyID,
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "updateRemoteAlias", { strict: true });
+  return resp;
+}
+
+// ---------- key CRUD ----------
+
+/**
+ * IR キー (ボタン) を追加。学習フロー (learnIRKey) から呼ばれることが多い。
+ * `irCode` の形は biz3 がオブジェクトをそのまま乗せるので、
+ * 呼び出し側で {hub3DeviceId, remoteId, name, irData, irWaveLength, irType, ...} を入れる。
+ */
+export async function addIRCode(client, { irCode, companyID }) {
+  const frame = { action: ACTION, op: "addIRCode", irCode, companyID };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "addIRCode", { strict: true });
+  return resp.data || resp;
+}
+
+/** キー名変更。 */
+export async function updateIRCode(client, { hub3DeviceId, remoteId, keyUUID, name, companyID }) {
+  const frame = {
+    action: ACTION,
+    op: "updateIRCode",
+    hub3DeviceId,
+    remoteId,
+    keyUUID,
+    name,
+    companyID,
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "updateIRCode", { strict: true });
+  return resp;
+}
+
+/** キー削除。 */
+export async function deleteIRCode(client, { hub3DeviceId, remoteId, keyUUID, companyID }) {
+  const frame = {
+    action: ACTION,
+    op: "deleteIRCode",
+    hub3DeviceId,
+    remoteId,
+    keyUUID,
+    companyID,
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "deleteIRCode", { strict: true });
+  return resp;
+}
+
+// ---------- mode 制御 + subscribe ----------
+
+/** 現在の IR モード (CONTROL=0 / REGISTER=1) を取得。 */
+export async function getIRMode(client, { deviceId, companyID }) {
+  const frame = { action: ACTION, op: "getIRMode", deviceId, companyID };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "getIRMode", { strict: true });
+  return resp.data;
+}
+
+/** モード切替。学習するには REGISTER に入れる必要がある。 */
+export async function setIRMode(client, { deviceId, mode, companyID }) {
+  const frame = { action: ACTION, op: "setIRMode", deviceId, mode, companyID };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "setIRMode", { strict: true });
+  return resp;
+}
+
+/**
+ * IR データ (= 学習で取り込まれた赤外線波形) の購読を開始。
+ * 戻り値は `{ unsubscribe, onData }`。`onData(fn)` で `subscribeIRDataRsp` 受信ごとに fn が呼ばれる。
+ * 利用後は必ず `unsubscribe()` を呼ぶこと。
+ */
+export async function subscribeIRData(client, { deviceId, companyID }) {
+  const topic = dataTopic(deviceId);
+  const ackFrame = {
+    action: ACTION,
+    op: "subscribeIRData",
+    topic,
+    deviceId,
+    companyID,
+  };
+  const ack = await client.request(ackFrame, DEFAULT_TIMEOUT_MS);
+  if (!ack.success) throw new Error(`subscribeIRData failed: ${ack.message || JSON.stringify(ack)}`);
+
+  const listeners = new Set();
+  const unsub = client.subscribe(`${ACTION}:subscribeIRDataRsp`, (msg) => {
+    if (msg?.deviceId && msg.deviceId !== deviceId) return;
+    for (const fn of listeners) {
+      try { fn(msg); } catch { /* ignore */ }
+    }
+  });
+
+  return {
+    onData(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    unsubscribe() {
+      unsub();
+      listeners.clear();
+      // fire-and-forget で server に解除通知 (Review H-5: request にすると 10s block)
+      try {
+        client.send({ action: ACTION, op: "unsubscribeIRData", topic, deviceId, companyID });
+      } catch { /* ignore */ }
+    },
+  };
+}
+
+/** モード変化 (例: REGISTER から CONTROL に戻った瞬間) の購読。subscribeIRData と同形。 */
+export async function subscribeIRMode(client, { deviceId, companyID }) {
+  const topic = modeTopic(deviceId);
+  const ack = await client.request(
+    { action: ACTION, op: "subscribeIRMode", topic, deviceId, companyID },
+    DEFAULT_TIMEOUT_MS,
+  );
+  if (!ack.success) throw new Error(`subscribeIRMode failed: ${ack.message || JSON.stringify(ack)}`);
+  const listeners = new Set();
+  const unsub = client.subscribe(`${ACTION}:subscribeIRModeRsp`, (msg) => {
+    if (msg?.deviceId && msg.deviceId !== deviceId) return;
+    for (const fn of listeners) {
+      try { fn(msg); } catch { /* ignore */ }
+    }
+  });
+  return {
+    onData(fn) { listeners.add(fn); return () => listeners.delete(fn); },
+    unsubscribe() {
+      unsub();
+      listeners.clear();
+      try {
+        client.send({ action: ACTION, op: "unsubscribeIRMode", topic, deviceId, companyID });
+      } catch { /* ignore */ }
+    },
+  };
+}
+
+// ---------- match (学習波形から既知リモコンを照合) ----------
+
+/**
+ * 学習で取った irData を既知のメーカー DB と照合する。
+ * @param {{irData:string, irType:number, brandName?:string, companyID:string}} p
+ */
+export async function matchRemote(client, { irData, irType, brandName, companyID }) {
+  const frame = {
+    action: ACTION,
+    op: "matchRemote",
+    irData,
+    irWaveLength: irData.length / 2,
+    irType,
+    brandName: brandName || "",
+    companyID,
+  };
+  const resp = await client.request(frame, DEFAULT_TIMEOUT_MS);
+  assertSuccess(resp, "matchRemote", { strict: true });
+  // biz3 remote-match/index.js:158: 一致候補は response.data.matches (配列)
+  return resp.data?.matches || [];
+}
+
+// ---------- composite: 学習フロー ----------
+
+/**
+ * 物理リモコンのボタン 1 個を学習して、リモコンに新キーとして登録する。
+ *
+ *   1. setIRMode(REGISTER) — Hub3 を学習モードに
+ *   2. subscribeIRData — 波形イベント購読
+ *   3. (ユーザが物理リモコンを Hub3 に向けてボタンを押す)
+ *   4. subscribeIRDataRsp イベントで波形を受信
+ *   5. unsubscribeIRData + setIRMode(CONTROL)
+ *   6. addIRCode で名前付きキーとして保存
+ *
+ * @param {{
+ *   hub3DeviceId: string,
+ *   remoteId: string,            // 既存リモコンの irDeviceUUID
+ *   keyName: string,
+ *   irType: number,              // remote.type
+ *   companyID: string,
+ *   timeoutMs?: number,          // ボタン押下待ち timeout (default 60s)
+ *   onPrompt?: () => void,       // 学習モード突入後に呼ばれる (ユーザに「ボタン押して」と促す)
+ * }} p
+ * @returns {Promise<{keyUUID: string, captured: any, saved: any}>}
+ *   keyUUID はクライアント発番 (これを send の command に使う)
+ */
+export async function learnIRKey(client, p) {
+  const timeoutMs = p.timeoutMs ?? LEARN_DEFAULT_TIMEOUT_MS;
+
+  await setIRMode(client, { deviceId: p.hub3DeviceId, mode: MODE.REGISTER, companyID: p.companyID });
+  const sub = await subscribeIRData(client, { deviceId: p.hub3DeviceId, companyID: p.companyID });
+
+  // biz3 learn/index.js:217-228 に厳密に合わせる:
+  //   - 波形は subscribeIRDataRsp の `response.data.data` (msg.data.data)
+  //   - keyUUID は **クライアントが発番** (generateUUID)。サーバ発番ではない。
+  //   - addIRCode に渡す irCode = {keyUUID, name, uuid: remote.uuid, deviceId: hub3, data: 波形}
+  let waveform = null;
+  try {
+    if (p.onPrompt) try { p.onPrompt(); } catch { /* ignore */ }
+    waveform = await new Promise((resolve, reject) => {
+      const to = setTimeout(() => reject(new Error("learn timeout (no IR captured)")), timeoutMs);
+      sub.onData((msg) => {
+        clearTimeout(to);
+        resolve(msg?.data?.data); // biz3: response.data.data が生波形
+      });
+    });
+  } finally {
+    sub.unsubscribe();
+    try {
+      await setIRMode(client, { deviceId: p.hub3DeviceId, mode: MODE.CONTROL, companyID: p.companyID });
+    } catch { /* ignore */ }
+  }
+
+  const keyUUID = generateUUID();
+  const irCode = {
+    keyUUID,
+    name: p.keyName,
+    uuid: p.remoteId,        // biz3: remote.uuid (= リモコンの irDeviceUUID)
+    deviceId: p.hub3DeviceId, // biz3: hub3DeviceId
+    data: waveform,           // biz3: response.data.data
+  };
+  const saved = await addIRCode(client, { irCode, companyID: p.companyID });
+  return { keyUUID, captured: waveform, saved };
+}
+
+export { MODE };

package/src/itemcodes.js

@@ -0,0 +1,29 @@
+// 正準 SesameItemCode。クラウド経路 (biz3TriggerLocker / cmdSesame) も BLE 経路 (GATT) も、
+// 最後に送る「命令の正体」はこの同一の itemCode。違うのは梱包 (cloud=CMAC(time)+base64 を WS /
+// BLE=AES-CCM 暗号セグメントを GATT) だけ — 公式 SesameSDK の CHSesame5.lock() 等が内部で
+// 「BLE 可なら BLE、不可ならクラウド」を選びつつ同じ itemCode を送るのと同じ構造。
+//
+// かつてクラウド側 (crypto.js CMD) と BLE 側 (ble/protocol.js ITEM) で同じ番号を二重定義していたが、
+// それは設計の取り違え。ここを唯一のソースとし、両者は別名で参照する。
+//
+// 値の出典: Android SesameSDK SesameProtocols.kt:32-53 (SesameItemCode)。
+export const ITEM_CODES = Object.freeze({
+  NONE: 0,
+  REGISTRATION: 1,
+  LOGIN: 2,
+  USER: 3,
+  HISTORY: 4,
+  VERSION_TAG: 5,
+  TIME: 8,
+  AUTOLOCK: 11,        // payload = 2byte LE 秒数 (0=無効)。クラウド中継は ack のみで未反映 (実機検証済み) → BLE 専用扱い
+  INITIAL: 14,
+  MAGNET: 17,
+  HISTORY_DELETE: 18,
+  MECH_SETTING: 80,
+  MECH_STATUS: 81,     // 状態通知 (publish)
+  LOCK: 82,
+  UNLOCK: 83,
+  MOVE_TO: 84,
+  TOGGLE: 88,          // 現在状態で施錠/解錠を反転 (クラウドはサーバが判定、BLE は SDK 同様クライアントが lock/unlock を選ぶ)
+  CLICK: 89,           // SESAME Bot のクリック (biz3 web の呼称は BOT_CLICK)
+});

package/src/lock.js

@@ -0,0 +1,194 @@
+// SESAME ロック (WM2 / SESAME 4/5/Pro / SESAME 6 等) のクラウド経由制御。
+//
+// Ported from biz3 (CANDY-HOUSE/biz3, MIT):
+//   - vendor reference: references_web/src/api/useIotCtrl.js (sendCommandToWM2)
+//
+// 設計メモ:
+//   - `biz3TriggerLocker` リクエストには op フィールドが無い (`{action, cmd, sign, history, device_id}`)
+//   - 応答は同期 ack ではなく、async push `biz3TriggerLocker:pubDeviceStateChange` で届く
+//     → request/response ペアリングではなく subscribe して target deviceId のメッセージを待つ
+//   - cmd code: 82=LOCK / 83=UNLOCK / 88=TOGGLE (cloud only) / 89=CLICK (Bot)
+//   - sign は 256 秒粒度の時刻 CMAC。リプレイ耐性はサーバ側ウィンドウ任せ。
+//   - subUUID はログインユーザ自身の UUID (history 経由でサーバ側操作ログに残る)
+
+import { Buffer } from "node:buffer";
+import { cmacTime, uuidToHistoryBase64, CMD } from "./crypto.js";
+import { ACTION_TYPES } from "../vendor/biz3/constants/messageConstants.js";
+
+const TRIGGER_ACTION = ACTION_TYPES.BIZ3_TRIGGER_LOCKER; // "biz3TriggerLocker" (vendor 由来)
+// 同期 ack のキー: サーバは {action:"biz3TriggerLocker", code:200, data:{}, success:true} を
+// op 無しで返す → transport の dispatch キーは `biz3TriggerLocker:` (op 空)。
+const ACK_KEY = `${TRIGGER_ACTION}:`;
+// 状態 push (来る環境なら): {action:"biz3TriggerLocker", op:"pubDeviceStateChange", data:{deviceUUID,...}}
+const STATE_EVENT_KEY = `${TRIGGER_ACTION}:pubDeviceStateChange`;
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * 内部: biz3TriggerLocker フレームを送信し、サーバの **同期 ack** を待って解決する。
+ *
+ * 実機観測 (2026, /production): biz3TriggerLocker は送信に対し
+ *   `{action:"biz3TriggerLocker", code:200, data:{}, success:true}` を**即時 ack** で返す。
+ * 旧実装は `pubDeviceStateChange` push を待っていたが、このアカウント/デバイスでは push が
+ * 来ず timeout 誤判定していた (コマンド自体はサーバ受理済みなのに失敗扱い)。よって ack で解決し、
+ * pubDeviceStateChange は来た場合のみ補助的に解決トリガにする (デバイス差異への保険)。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{cmd:number, sign:string, history:string, deviceId:string, timeoutMs?:number}} f
+ * @returns {Promise<any>} ack (または state push) メッセージ
+ */
+function dispatchTrigger(client, { cmd, sign, history, deviceId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  // sign は時刻 CMAC で 256 秒粒度。未接続で queue に積まれ 256 秒超過すると署名期限切れ。
+  // lock は queue させず即 throw (Review H-3)。
+  if (client.getStatus && client.getStatus() !== "open") {
+    throw new Error("triggerLock: not connected — call connect() first (queueing not allowed for sign-based ops)");
+  }
+  const target = normalizeUuid(deviceId);
+
+  return new Promise((resolve, reject) => {
+    let done = false;
+    const cleanup = () => { clearTimeout(to); unsubAck(); unsubState(); };
+    const succeed = (msg) => { if (done) return; done = true; cleanup(); resolve(msg); };
+    const fail = (err) => { if (done) return; done = true; cleanup(); reject(err); };
+
+    const to = setTimeout(
+      () => fail(new Error(`triggerLock timeout (cmd=${cmd}, device=${target})`)),
+      timeoutMs,
+    );
+
+    // (主) 同期 ack。success:false は明示的失敗、それ以外 (code:200/success:true) は成功。
+    const unsubAck = client.subscribe(ACK_KEY, (msg) => {
+      if (msg && msg.success === false) {
+        fail(new Error(`triggerLock failed (cmd=${cmd}): code=${msg.code ?? "?"} ${msg.message || ""}`.trim()));
+        return;
+      }
+      succeed(msg);
+    });
+
+    // (副) 状態 push。data.deviceUUID 一致のときのみ解決 (来ない環境では無視される)。
+    const unsubState = client.subscribe(STATE_EVENT_KEY, (msg) => {
+      const incoming = normalizeUuid(msg?.data?.deviceUUID || msg.deviceUUID || msg.device_id);
+      if (incoming && incoming !== target) return;
+      succeed(msg);
+    });
+
+    client.send({ action: TRIGGER_ACTION, cmd, sign, history, device_id: deviceId });
+  });
+}
+
+/**
+ * lock 制御コマンドを送信し、サーバ ack を待って解決する。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{
+ *   deviceId: string,    // ロックの deviceUUID
+ *   secretKey: string,   // 32hex のロック共通鍵 (devices command で取得)
+ *   subUUID: string,     // ログインユーザの subUUID
+ *   cmd: number,         // CMD.LOCK | UNLOCK | TOGGLE | CLICK
+ *   timeoutMs?: number,
+ * }} params
+ * @returns {Promise<any>} biz3TriggerLocker ack メッセージ
+ */
+export async function triggerLock(client, params) {
+  if (!params.deviceId) throw new Error("deviceId required");
+  if (!params.secretKey) throw new Error("secretKey required");
+  if (!params.subUUID) throw new Error("subUUID required");
+  if (typeof params.cmd !== "number") throw new Error("cmd required (number)");
+
+  const sign = cmacTime(params.secretKey);
+  const history = uuidToHistoryBase64(params.subUUID);
+  return dispatchTrigger(client, {
+    cmd: params.cmd,
+    sign,
+    history,
+    deviceId: params.deviceId,
+    timeoutMs: params.timeoutMs,
+  });
+}
+
+/** ロックを施錠 (cmd=82)。 */
+export function lockLock(client, p) { return triggerLock(client, { ...p, cmd: CMD.LOCK }); }
+/** ロックを解錠 (cmd=83)。 */
+export function lockUnlock(client, p) { return triggerLock(client, { ...p, cmd: CMD.UNLOCK }); }
+/** ロックを反転 (cmd=88, cloud のみ)。現在状態に応じてサーバが LOCK/UNLOCK を判定。 */
+export function lockToggle(client, p) { return triggerLock(client, { ...p, cmd: CMD.TOGGLE }); }
+/** SESAME Bot のボタンクリック (cmd=89)。 */
+export function botClick(client, p) { return triggerLock(client, { ...p, cmd: CMD.CLICK }); }
+
+/**
+ * 任意の SESAME ItemCode をクラウド経由 (biz3TriggerLocker) で送る汎用レール。
+ *
+ * フレームは lock/unlock と同型 `{action, cmd, sign:cmacTime(secretKey), history:base64(payload), device_id}`
+ * (公式 SDK CHAPIClientBiz.cmdSesame と一致: msg=3byte時刻の CMAC を sign、payload を history に base64)。
+ * lock/unlock(82/83) と autolock(11) 等は同一 ItemCode 名前空間 (Android SesameSDK SesameProtocols.kt)。
+ *
+ * ⚠️ **lock/unlock/toggle/bot 以外は実機に反映されない (実機検証済み)**:
+ *   biz3TriggerLocker は lock/unlock/toggle/bot のみを実機へ中継する。それ以外の ItemCode は
+ *   サーバが `success:true` で **ack だけ返すが、ロック本体には適用されない** (autolock=11 で
+ *   2026 実機確認: ack は返るが autolock 設定は変化せず)。biz3 web/SDK にも設定系のクラウド送信
+ *   経路は無く (useIotCtrl.js の IoT cmd は ADD/REMOVE_SESAME・LED・RELAY 等のみで autolock は
+ *   "Unsupported"、公式アプリは BLE 直送)。よって本関数で lock/unlock 系以外を送っても
+ *   **`success:true` は「サーバ受領」止まりで実機反映の保証は無い**。lock/unlock/toggle/bot 用、
+ *   もしくは将来クラウド対応された ItemCode 用の汎用レールとして残す。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{
+ *   deviceId: string,                 // ロックの deviceUUID
+ *   secretKey: string,                // 32hex の共通鍵
+ *   cmd: number,                      // SesameItemCode 値 (CMD.AUTOLOCK 等)
+ *   payload?: Uint8Array|Buffer|number[], // BLE ペイロード (省略時は subUUID の history タグ)
+ *   subUUID?: string,                 // payload 省略時に history へ使う
+ *   timeoutMs?: number,
+ * }} params
+ * @returns {Promise<any>} biz3TriggerLocker ack メッセージ (success:false は reject)
+ */
+export async function triggerItemCommand(client, params) {
+  if (!params.deviceId) throw new Error("deviceId required");
+  if (!params.secretKey) throw new Error("secretKey required");
+  if (typeof params.cmd !== "number") throw new Error("cmd required (number)");
+
+  const sign = cmacTime(params.secretKey);
+  let history;
+  if (params.payload != null) {
+    history = Buffer.from(params.payload).toString("base64");
+  } else if (params.subUUID) {
+    history = uuidToHistoryBase64(params.subUUID);
+  } else {
+    throw new Error("payload または subUUID のいずれかが必要です");
+  }
+
+  return dispatchTrigger(client, {
+    cmd: params.cmd,
+    sign,
+    history,
+    deviceId: params.deviceId,
+    timeoutMs: params.timeoutMs,
+  });
+}
+
+/**
+ * オートロック (解錠 N 秒後に自動施錠) を設定する。autolock = ItemCode 11、payload = 2byte LE 秒数。
+ * `seconds=0` で無効化 (autolock_jp.md: 遅延時間 0 は自動施錠無効)。
+ *
+ * ⚠️ **クラウド経由では実機に反映されない (2026 実機検証済み)**。biz3TriggerLocker は cmd=11 に
+ *   `success:true` を返すが、ロック本体の autolock 設定は変化しない。autolock の正規経路は **BLE 直送のみ**
+ *   (公式アプリ準拠)。本関数はフレーム生成としては正しい (BLE トランスポートや将来のクラウド対応用) が、
+ *   現状の biz3 クラウドでは効果が無い。CLI からは公開していない ({@link triggerItemCommand} 参照)。
+ *
+ * @param {import("./transport.js").Hub3WsClient} client
+ * @param {{ deviceId: string, secretKey: string, seconds: number, timeoutMs?: number }} params
+ *   seconds: 0..65535 (0=無効)。SESAME 本体の選択肢は 0/5/10/.../秒。
+ * @returns {Promise<{ack: any, cmd: number, seconds: number}>}
+ */
+export async function setAutolock(client, { deviceId, secretKey, seconds, timeoutMs }) {
+  if (!Number.isInteger(seconds) || seconds < 0 || seconds > 0xffff) {
+    throw new Error("seconds must be an integer 0..65535 (0 = disable autolock)");
+  }
+  // 2byte リトルエンディアン (SDK: delay.toShort().toReverseBytes())。
+  const payload = Buffer.from([seconds & 0xff, (seconds >> 8) & 0xff]);
+  const ack = await triggerItemCommand(client, { deviceId, secretKey, cmd: CMD.AUTOLOCK, payload, timeoutMs });
+  return { ack, cmd: CMD.AUTOLOCK, seconds };
+}
+
+function normalizeUuid(s) {
+  return typeof s === "string" ? s.replace(/-/g, "").toLowerCase() : "";
+}