odelic 0.2.0 → 0.2.1

package/src/{protocol.js → protocol.ts}

@@ -4,9 +4,12 @@
  * Mirrors jp.co.odelic.smt.remote03.act.module.ControllerAct in "central" (Tiger) mode:
  *     03 <dst vaddr 4B> <channel> <own vaddr 4B> <msg id> <args...>
  */
-import { InputError } from './errors.js';
+import { InputError } from './errors.ts';
 
-export const BROADCAST = Buffer.from([0xff, 0xff, 0xff, 0xff]);
+/** A light address: 4 bytes, a number (little endian) or a hex string ("00000000", "00:00:00:00"). */
+export type VaddrLike = Uint8Array | number | string;
+
+export const BROADCAST: Buffer = Buffer.from([0xff, 0xff, 0xff, 0xff]);
 
 // channels
 export const CH_TO_LIGHT = 0x20;
@@ -21,30 +24,30 @@ export const MSG_CHANGE_COLOR = 0xe2; //  SM_CHANGE_COLOR (cycle colour preset)
 export const MSG_SCENE_SAVE = 0x40; //    SM_SCENE_IN
 export const MSG_SCENE_PLAY = 0x42; //    SM_SCENE_PLAY
 export const MSG_STATUS = 0x70; //        SM_STATUS
-export const MSG_STATUS_RESPONSES = [0x71, 0x35]; // STATUS_MAIN / STATE_RESPONSE_FD
+export const MSG_STATUS_RESPONSES: readonly number[] = [0x71, 0x35]; // STATUS_MAIN / STATE_RESPONSE_FD
 
 // special (x, y) pairs
-export const XY_ON = [55, 55];
-export const XY_OFF = [50, 50];
+export const XY_ON = [55, 55] as const;
+export const XY_OFF = [50, 50] as const;
 
 export const X_MAX = 20; // colour: 0 = warm (電球色) ... 20 = cool (昼光色)
 export const Y_MAX = 19; // brightness: 0 = brightest ... 19 = dimmest
 
-const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+const clamp = (v: number, lo: number, hi: number) => Math.max(lo, Math.min(hi, v));
 
 /** 0 (warmest) .. 100 (coolest) -> x 0..20 */
-export function colorToX(color) {
+export function colorToX(color: number): number {
   return clamp(Math.round((color * X_MAX) / 100), 0, X_MAX);
 }
 
 /** 1..100 % -> y 19..0 (same rule as the app: (100 - b) / 5, clamped) */
-export function brightnessToY(brightness) {
+export function brightnessToY(brightness: number): number {
   return clamp(Math.floor((100 - brightness) / 5), 0, Y_MAX);
 }
 
-/** 4-byte vaddr from a Buffer/Uint8Array, a number (little endian) or a hex string ("00000000", "00:00:00:00"). */
-export function vaddr(v) {
-  let b;
+/** 4-byte vaddr from a Buffer/Uint8Array, a number (little endian) or a hex string. */
+export function vaddr(v: VaddrLike): Buffer {
+  let b: Buffer;
   if (v instanceof Uint8Array) {
     b = Buffer.from(v);
   } else if (typeof v === 'number') {
@@ -61,9 +64,9 @@ export function vaddr(v) {
 }
 
 /** Concatenate Buffers and byte arrays; like Python's bytes(), array values must be integers 0..255. */
-function bytes(...parts) {
+function bytes(...parts: (Uint8Array | readonly number[])[]): Buffer {
   return Buffer.concat(parts.map((p) => {
-    if (Buffer.isBuffer(p)) return p;
+    if (p instanceof Uint8Array) return p;
     for (const v of p) {
       if (!Number.isInteger(v) || v < 0 || v > 255) throw new InputError(`byte value out of range: ${v}`);
     }
@@ -71,61 +74,84 @@ function bytes(...parts) {
   }));
 }
 
-export function dataEvent(dst, channel, payload) {
+export function dataEvent(dst: Uint8Array, channel: number, payload: Uint8Array): Buffer {
   return bytes([0x03], dst, [channel], payload);
 }
 
 /** ControllerAct.setlight: on/off/colour/brightness for one light or all (broadcast). */
-export function light(own, dst, x, y, index = 0) {
+export function light(own: Uint8Array, dst: Buffer, x: number, y: number, index = 0): Buffer {
   const ch = dst.equals(BROADCAST) ? CH_TO_LIGHT_BROADCAST : CH_TO_LIGHT;
   return dataEvent(dst, ch, bytes(own, [MSG_LIGHT, index, x, y, 0, 0, 0, 0]));
 }
 
 /** ControllerAct.sendgroup_new */
-export function groupLight(own, groupId, x, y) {
+export function groupLight(own: Uint8Array, groupId: number, x: number, y: number): Buffer {
   return dataEvent(BROADCAST, CH_TO_LIGHT, bytes(own, [MSG_LIGHT_GROUP, x, y, 0, 0, 0, 0, 0, 0, groupId]));
 }
 
-export function changeColor(own, dst) {
+export function changeColor(own: Uint8Array, dst: Uint8Array): Buffer {
   return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_CHANGE_COLOR]));
 }
 
-export function scene(own, index, save, dst = BROADCAST) {
+export function scene(own: Uint8Array, index: number, save: boolean, dst: Uint8Array = BROADCAST): Buffer {
   const msg = save ? MSG_SCENE_SAVE : MSG_SCENE_PLAY;
   return dataEvent(dst, CH_TO_LIGHT, bytes(own, [msg, 0, 0, 0, 0, 0, 0, index]));
 }
 
-export function statusRequest(own, dst) {
+export function statusRequest(own: Uint8Array, dst: Uint8Array): Buffer {
   return dataEvent(dst, CH_TO_LIGHT, bytes(own, [MSG_STATUS]));
 }
 
-export function pingAll(own) {
+export function pingAll(own: Uint8Array): Buffer {
   return dataEvent(BROADCAST, CH_PING, own);
 }
 
+/** A light that answered a mesh ping. */
 export class Device {
-  constructor({ vaddr, mac, product, version }) {
+  readonly vaddr: Buffer;
+  readonly mac: string;
+  readonly product: number;
+  readonly version: string;
+
+  constructor({ vaddr, mac, product, version }: { vaddr: Buffer; mac: string; product: number; version: string }) {
     this.vaddr = vaddr;
     this.mac = mac;
     this.product = product;
     this.version = version;
   }
 
-  toString() {
+  toString(): string {
     return `vaddr=${this.vaddr.toString('hex')} mac=${this.mac} product=${this.product} ver=${this.version}`;
   }
 }
 
 /** MeshCommon.GetPingResponse; `p` is a decrypted type-3 packet with channel 0xFF. */
-export function parsePingResponse(p) {
+export function parsePingResponse(p: Buffer): Device | null {
   if (p.length < 20 || p[0] !== 0x03 || p[5] !== CH_PING_RESPONSE) return null;
   const mac = [...p.subarray(6, 12)].reverse().map((b) => b.toString(16).toUpperCase().padStart(2, '0')).join(':');
   const product = p[16] | (p[17] << 8);
   return new Device({ vaddr: Buffer.from(p.subarray(12, 16)), mac, product, version: `${product}.${p[18]}.${p[19]}` });
 }
 
+export interface LightStateJSON {
+  vaddr: string;
+  on: boolean;
+  /** 0 = warm .. 100 = cool, null if unknown */
+  color: number | null;
+  /** 1..100 %, 0 when off, null if unknown */
+  brightness: number | null;
+  x: number;
+  y: number;
+}
+
+/** State reported by one light. */
 export class LightState {
-  constructor({ vaddr, on, x, y }) {
+  readonly vaddr: Buffer;
+  readonly on: boolean;
+  readonly x: number;
+  readonly y: number;
+
+  constructor({ vaddr, on, x, y }: { vaddr: Buffer; on: boolean; x: number; y: number }) {
     this.vaddr = vaddr;
     this.on = on;
     this.x = x;
@@ -133,23 +159,23 @@ export class LightState {
   }
 
   /** 0 = warm .. 100 = cool, null if unknown (light reports a plain "on"). */
-  get color() {
+  get color(): number | null {
     return !this.on || this.x > X_MAX ? null : this.x * 5;
   }
 
   /** 1..100 %, 0 when off, null if unknown. */
-  get brightness() {
+  get brightness(): number | null {
     if (!this.on) return 0;
     return this.y > Y_MAX ? null : 100 - this.y * 5;
   }
 
-  toJSON() {
+  toJSON(): LightStateJSON {
     return { vaddr: this.vaddr.toString('hex'), on: this.on, color: this.color, brightness: this.brightness, x: this.x, y: this.y };
   }
 }
 
 /** Status reply (MeshBlePresenter.syncState): `03 <dst4> <ch> <src4> 71 <x> <y> ...` */
-export function parseStatus(p) {
+export function parseStatus(p: Buffer): LightState | null {
   if (p.length < 13 || p[0] !== 0x03 || !MSG_STATUS_RESPONSES.includes(p[10])) return null;
   const x = p[11];
   const y = p[12];
@@ -157,7 +183,7 @@ export function parseStatus(p) {
 }
 
 /** The app shows "ID:<HomeID><4-char password>", e.g. "ID:12345678" -> { homeid: 1234, password: "5678" }. */
-export function parseAppId(appId) {
+export function parseAppId(appId: string): { homeid: number; password: string } {
   let s = String(appId).trim();
   if (s.toUpperCase().startsWith('ID:')) s = s.slice(3);
   if (s.length < 5) throw new InputError(`ID looks too short: ${JSON.stringify(String(appId))}`);
@@ -170,7 +196,7 @@ export function parseAppId(appId) {
  * HomeID advertised by a mesh node (manufacturer id 0xFFFF, c0/c1 ff 01|02 <homeid LE>).
  * `manufacturerData` is the raw AD field as noble reports it, i.e. starting with the 2-byte company id.
  */
-export function advHomeid(manufacturerData) {
+export function advHomeid(manufacturerData: Buffer | null | undefined): number | null {
   const m = manufacturerData;
   if (!m || m.length < 9 || m[0] !== 0xff || m[1] !== 0xff) return null;
   const v = m.subarray(2);

package/src/{server.js → server.ts}

@@ -15,29 +15,42 @@
  */
 import { createHash, timingSafeEqual } from 'node:crypto';
 import http from 'node:http';
+import type { IncomingMessage, Server, ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
 
-import { InputError } from './errors.js';
-import { log } from './log.js';
-import { toInt } from './controller.js';
+import { InputError } from './errors.ts';
+import { log } from './log.ts';
+import { toInt } from './controller.ts';
+import type { Controller } from './controller.ts';
 
-export const LOOPBACK = ['127.0.0.1', 'localhost', '::1'];
+export const LOOPBACK: readonly string[] = ['127.0.0.1', 'localhost', '::1'];
 const MAX_BODY = 65536;
 
+/** The part of Controller the HTTP API uses. */
+export type HttpController = Pick<Controller,
+  'info' | 'lights' | 'status' | 'on' | 'off' | 'setLight' | 'nightLight' | 'group' | 'scene'>;
+
+type Params = Record<string, unknown>;
+
 export class HttpError extends Error {
-  constructor(status, message) {
+  readonly status: number;
+
+  constructor(status: number, message: string) {
     super(message);
     this.name = 'HttpError';
     this.status = status;
   }
 }
 
-function need(method, expected) {
+function need(method: string, expected: string): void {
   if (method !== expected) throw new HttpError(405, `use ${expected}`);
 }
 
+const num = (v: unknown, def: number) => (v ?? def) as number | string;
+
 /** Route one request to the controller. Returns the JSON-able result. */
-export async function dispatch(ctl, method, path, params) {
-  let parts;
+export async function dispatch(ctl: HttpController, method: string, path: string, params: Params): Promise<unknown> {
+  let parts: string[];
   try {
     parts = path.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean).map(decodeURIComponent);
   } catch {
@@ -60,11 +73,11 @@ export async function dispatch(ctl, method, path, params) {
     const act = parts[2];
     if (act === 'on') return ctl.on(target);
     if (act === 'off') return ctl.off(target);
-    if (act === 'light') return ctl.setLight(target, params.color ?? 50, params.brightness ?? 100);
-    if (act === 'night') return ctl.nightLight(target, params.level ?? 0);
+    if (act === 'light') return ctl.setLight(target, num(params.color, 50), num(params.brightness, 100));
+    if (act === 'night') return ctl.nightLight(target, num(params.level, 0));
   } else if (head === 'groups' && parts.length === 3) {
     need(method, 'POST');
-    return ctl.group(toInt(parts[1], 'group id'), parts[2], params.color ?? 50, params.brightness ?? 100);
+    return ctl.group(toInt(parts[1], 'group id'), parts[2], num(params.color, 50), num(params.brightness, 100));
   } else if (head === 'scenes' && parts.length === 3 && (parts[2] === 'play' || parts[2] === 'save')) {
     need(method, 'POST');
     return ctl.scene(toInt(parts[1], 'scene index'), parts[2] === 'save');
@@ -72,16 +85,16 @@ export async function dispatch(ctl, method, path, params) {
   throw new HttpError(404, 'not found');
 }
 
-function readBody(req) {
+function readBody(req: IncomingMessage): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const declared = Number(req.headers['content-length'] || 0);
     if (declared > MAX_BODY) {
       reject(new HttpError(413, 'body too large'));
       return;
     }
-    const chunks = [];
+    const chunks: Buffer[] = [];
     let size = 0;
-    req.on('data', (c) => {
+    req.on('data', (c: Buffer) => {
       size += c.length;
       if (size > MAX_BODY) {
         reject(new HttpError(413, 'body too large'));
@@ -95,19 +108,19 @@ function readBody(req) {
   });
 }
 
-const digest = (s) => createHash('sha256').update(String(s)).digest();
+const digest = (s: unknown) => createHash('sha256').update(String(s)).digest();
 
 /** A `(req, res)` handler for node:http. */
-export function makeHandler(ctl, token = null) {
-  return async (req, res) => {
+export function makeHandler(ctl: HttpController, token: string | null = null) {
+  return async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
     let status = 200;
-    let payload;
+    let payload: unknown;
     try {
-      const url = new URL(req.url, 'http://localhost');
-      const params = Object.fromEntries(url.searchParams);
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const params: Params = Object.fromEntries(url.searchParams);
       const body = await readBody(req);
       if (body.length) {
-        let data;
+        let data: unknown;
         try {
           data = JSON.parse(body.toString('utf8'));
         } catch {
@@ -116,22 +129,23 @@ export function makeHandler(ctl, token = null) {
         if (data && typeof data === 'object' && !Array.isArray(data)) Object.assign(params, data);
       }
       if (token) {
-        const auth = req.headers.authorization || '';
+        const auth = req.headers.authorization ?? '';
         const given = auth.toLowerCase().startsWith('bearer ') ? auth.slice(7) : (params.token ?? '');
         if (!timingSafeEqual(digest(given), digest(token))) throw new HttpError(401, 'bad or missing token');
       }
       delete params.token;
-      payload = await dispatch(ctl, req.method.toUpperCase(), url.pathname, params);
+      payload = await dispatch(ctl, (req.method ?? 'GET').toUpperCase(), url.pathname, params);
     } catch (e) {
-      if (e instanceof HttpError) {
-        status = e.status;
-      } else if (e instanceof InputError) {
+      const err = e as Error;
+      if (err instanceof HttpError) {
+        status = err.status;
+      } else if (err instanceof InputError) {
         status = 400;
       } else { // BLE / login failures
         status = 502;
-        log.error('request failed:', e);
+        log.error('request failed:', err);
       }
-      payload = { ok: false, error: e instanceof HttpError || e instanceof InputError ? e.message : `${e.name}: ${e.message}` };
+      payload = { ok: false, error: err instanceof HttpError || err instanceof InputError ? err.message : `${err.name}: ${err.message}` };
     }
     const data = Buffer.from(JSON.stringify(payload ?? null), 'utf8');
     if (res.headersSent || res.destroyed) return;
@@ -144,33 +158,38 @@ export function makeHandler(ctl, token = null) {
   };
 }
 
-/**
- * Start the HTTP API. Resolves to the listening http.Server; closing the server also closes the controller.
- * @param {import('./controller.js').Controller} ctl
- * @param {{host?: string, port?: number, token?: string|null}} [opts]
- */
-export async function serve(ctl, { host = '127.0.0.1', port = 8765, token = null } = {}) {
+export interface ServeOptions {
+  host?: string;
+  port?: number;
+  /** bearer token; required when listening on a non-loopback address */
+  token?: string | null;
+}
+
+/** Start the HTTP API. Resolves to the listening server; closing the server also closes the controller. */
+export async function serve(ctl: Controller, { host = '127.0.0.1', port = 8765, token = null }: ServeOptions = {}): Promise<Server> {
   if (!LOOPBACK.includes(host) && !token) {
     throw new InputError(`refusing to listen on ${host} without a token (use --token or ODELIC_HTTP_TOKEN)`);
   }
   const server = http.createServer(makeHandler(ctl, token));
   server.headersTimeout = 10_000;
   server.requestTimeout = 10_000 + 60_000; // BLE operations (scan + login) can take a while
-  await new Promise((resolve, reject) => {
+  await new Promise<void>((resolve, reject) => {
     server.once('error', reject);
     server.listen(port, host, () => {
       server.removeListener('error', reject);
       resolve();
     });
   });
-  server.on('close', () => ctl.close().catch(() => {}));
-  const addr = server.address();
+  server.on('close', () => {
+    ctl.close().catch(() => {});
+  });
+  const addr = server.address() as AddressInfo;
   log.warning(`HTTP API on http://${host}:${addr.port} (${ctl.keepConnected
     ? 'keeping the BLE link open' : `idle disconnect after ${ctl.idleTimeout}s`})`);
   if (ctl.keepConnected) {
     ctl.connect()
       .then(() => log.warning(`connected via ${ctl.mesh.nodeName}`))
-      .catch((e) => log.warning(`initial connect failed: ${e.message}`)); // the next request retries
+      .catch((e: Error) => log.warning(`initial connect failed: ${e.message}`)); // the next request retries
   }
   return server;
 }

package/src/version.ts

@@ -0,0 +1 @@
+export const VERSION = '0.2.1';