@switchbot/homebridge-switchbot 5.0.0-beta.7 → 5.0.0-beta.71

package/src/switchbotClient.ts

@@ -0,0 +1,266 @@
+import type { SwitchBotPluginConfig } from './settings'
+
+export interface ISwitchBotClient {
+  init(): Promise<void>
+  getDevice(id: string): Promise<any>
+  destroy(): Promise<void>
+}
+
+// Adapter that tries to use the node-switchbot v4 hybrid API when available.
+export class SwitchBotClient implements ISwitchBotClient {
+  private cfg: SwitchBotPluginConfig
+  private client: any | null = null
+  private baseUrl = 'https://api.switch-bot.com/v1.0'
+  // configurable network options
+  private requestTimeout = 5000
+  private maxRetries = 2
+  private baseBackoffMs = 100
+  private maxBackoffMs = 2000
+  private backoffFactor = 2
+  private jitter = true
+  // per-device write debounce (ms). 0 = disabled. Configurable via plugin options.
+  // Default enabled to coalesce rapid writes and prevent command floods.
+  private writeDebounceMs = 100
+  // structured logger (expects info/warn/error/debug); defaults to console
+  private logger: any
+  // per-device retry tracking
+  private perDeviceRetries: Map<string, number> = new Map()
+  private perDeviceMaxRetries = 3
+  // per-device cooldown after exceeding retries (ms)
+  private perDeviceCooldownMs = 60_000
+  private perDeviceCooldownUntil: Map<string, number> = new Map()
+
+  constructor(cfg: SwitchBotPluginConfig) {
+    this.cfg = cfg
+    this.logger = (cfg as any)?.logger ?? console
+    if (typeof (cfg as any)?.requestTimeout === 'number') this.requestTimeout = (cfg as any).requestTimeout
+    if (typeof (cfg as any)?.maxRetries === 'number') this.maxRetries = (cfg as any).maxRetries
+    if (typeof (cfg as any)?.perDeviceMaxRetries === 'number') this.perDeviceMaxRetries = (cfg as any).perDeviceMaxRetries
+    if (typeof (cfg as any)?.baseBackoffMs === 'number') this.baseBackoffMs = (cfg as any).baseBackoffMs
+    if (typeof (cfg as any)?.maxBackoffMs === 'number') this.maxBackoffMs = (cfg as any).maxBackoffMs
+    if (typeof (cfg as any)?.backoffFactor === 'number') this.backoffFactor = (cfg as any).backoffFactor
+    if (typeof (cfg as any)?.jitter === 'boolean') this.jitter = (cfg as any).jitter
+    if (typeof (cfg as any)?.perDeviceCooldownMs === 'number') this.perDeviceCooldownMs = (cfg as any).perDeviceCooldownMs
+    if (typeof (cfg as any)?.writeDebounceMs === 'number') this.writeDebounceMs = (cfg as any).writeDebounceMs
+  }
+
+  // pending writes coalescing: deviceId -> { timer, body, resolvers }
+  private pendingWrites: Map<string, { timer: any; body: any; resolvers: Array<{ resolve: (v:any)=>void; reject: (e:any)=>void }>; }> = new Map()
+
+  async init(): Promise<void> {
+    // Try to dynamically import the new node-switchbot package. If it exposes
+    // a hybrid client we will use it. Otherwise the consumer can implement
+    // OpenAPI fallback logic here.
+    try {
+      const mod = await import('node-switchbot')
+      // The new library may export a default or named client. Try common names.
+      const m: any = mod as any
+      this.client = m?.default ?? m?.SwitchBot ?? m
+      if (typeof this.client === 'function') {
+        // some builds export a constructor
+        this.client = new this.client({ token: this.cfg.openApiToken })
+      }
+    } catch (e) {
+      // If import fails, leave client null and rely on OpenAPI code paths later.
+      this.logger?.warn?.('node-switchbot import failed; falling back to OpenAPI when token available')
+      this.client = null
+    }
+  }
+
+  private async fetchWithTimeoutAndRetry(url: string, opts: any = {}, timeoutMs?: number, retries?: number, deviceId?: string) {
+    const to = typeof timeoutMs === 'number' ? timeoutMs : this.requestTimeout
+    const max = typeof retries === 'number' ? retries : this.maxRetries
+
+    // Check per-device cooldown
+    if (deviceId) {
+      const until = this.perDeviceCooldownUntil.get(deviceId) ?? 0
+      if (Date.now() < until) {
+        const ms = until - Date.now()
+        this.logger?.warn?.('device in cooldown, aborting fetch', { deviceId, cooldownMs: ms })
+        throw new Error(`device ${deviceId} in cooldown for ${ms}ms`)
+      }
+    }
+
+    let attempt = 0
+    while (true) {
+      attempt += 1
+      // AbortController-based timeout
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), to)
+      try {
+        this.logger?.debug?.('fetch', { url, attempt, deviceId })
+        const fetchOpts = Object.assign({}, opts)
+        try {
+          Object.defineProperty(fetchOpts, 'signal', { value: controller.signal, enumerable: false, configurable: true })
+        } catch (_e) {
+          // ignore environments where defineProperty may fail
+        }
+        const resp = await fetch(url, fetchOpts)
+        clearTimeout(timer)
+
+        // helper to safely read response body when available
+        const safeReadBody = async (r: any) => {
+          try {
+            if (!r) return ''
+            if (typeof r.text === 'function') return await r.text()
+            if (typeof r.json === 'function') {
+              const j = await r.json().catch(() => null)
+              return j ? JSON.stringify(j) : ''
+            }
+            return String(r)
+          } catch (_e) {
+            return ''
+          }
+        }
+
+        // Some tests/mocks provide response-like objects without numeric `status`.
+        // In those cases attempt to parse the body and return a Response-like
+        // object so callers (resp.json()) continue to work instead of forcing
+        // a retry path.
+        if (typeof (resp as any).status !== 'number') {
+          const bodyStr = await safeReadBody(resp)
+          try {
+            const parsed = bodyStr ? JSON.parse(bodyStr) : {}
+            if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+            return { ok: true, status: 200, json: async () => parsed }
+          } catch (_e) {
+            if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+            return { ok: true, status: 200, json: async () => ({ body: bodyStr }) }
+          }
+        }
+
+        // classify response
+        if (resp.ok) {
+          if (deviceId) this.perDeviceRetries.set(deviceId, 0)
+          return resp
+        }
+
+        // Do not retry on client errors (4xx), except 429 (rate limit)
+        if (resp.status >= 400 && resp.status < 500 && resp.status !== 429) {
+          const body = await safeReadBody(resp)
+          this.logger?.error?.('fetch non-retriable response', { url, status: resp.status, body })
+          const err = new Error(`HTTP ${resp.status}`)
+          ;(err as any).status = resp.status
+          throw err
+        }
+
+        // server error / rate limit: treat as retriable
+        const body = await safeReadBody(resp)
+        this.logger?.warn?.('fetch retriable response', { url, status: resp.status, body })
+        // throw to enter retry/catch logic below and apply backoff
+        throw new Error(`retriable response: ${resp.status || 'unknown'}`)
+      } catch (err: any) {
+        clearTimeout(timer)
+        const isAbort = err?.name === 'AbortError' || err?.message === 'The user aborted a request.' || err?.message === 'timeout'
+        const reason = isAbort ? 'timeout' : err?.message ?? String(err)
+        this.logger?.warn?.('fetch failed', { url, attempt, deviceId, reason })
+
+        // per-device retry guard
+        if (deviceId) {
+          const prev = this.perDeviceRetries.get(deviceId) ?? 0
+          const next = prev + 1
+          this.perDeviceRetries.set(deviceId, next)
+          if (next > this.perDeviceMaxRetries) {
+            this.logger?.error?.('per-device retry limit exceeded, entering cooldown', { deviceId, attempts: next })
+            this.perDeviceCooldownUntil.set(deviceId, Date.now() + this.perDeviceCooldownMs)
+            throw new Error(`per-device retry limit exceeded for ${deviceId}`)
+          }
+        }
+
+        if (attempt > max) throw err
+
+        // exponential backoff with optional jitter
+        let backoff = Math.min(this.baseBackoffMs * Math.pow(this.backoffFactor, attempt - 1), this.maxBackoffMs)
+        if (this.jitter) {
+          const jitterVal = Math.floor(Math.random() * backoff)
+          backoff = Math.floor(backoff / 2) + jitterVal
+        }
+        this.logger?.debug?.('backoff before retry', { url, attempt, backoff })
+        await new Promise((r) => setTimeout(r, backoff))
+      }
+    }
+  }
+
+  async getDevice(id: string): Promise<any> {
+    if (this.client && typeof this.client.getDevice === 'function') {
+      return this.client.getDevice(id)
+    }
+    // Fallback: call OpenAPI via HTTP using token if available.
+    if (this.cfg.openApiToken) {
+      const url = `${this.baseUrl}/devices/${id}`
+      const opts = { headers: { Authorization: this.cfg.openApiToken } }
+      const resp = await this.fetchWithTimeoutAndRetry(url, opts, undefined, undefined, id)
+      return resp.json()
+    }
+    throw new Error('No SwitchBot client available')
+  }
+
+  async setDeviceState(id: string, body: any): Promise<any> {
+    // If debounce is disabled do a direct write path
+    if (!this.writeDebounceMs || this.writeDebounceMs <= 0) {
+      return this._doSetDeviceState(id, body)
+    }
+
+    // Coalesce writes per-device within debounce window. Last write wins.
+    return new Promise((resolve, reject) => {
+      const existing = this.pendingWrites.get(id)
+      if (existing) {
+        existing.body = body
+        existing.resolvers.push({ resolve, reject })
+        // timer already scheduled
+        return
+      }
+
+      const resolvers: Array<{ resolve: (v:any)=>void; reject: (e:any)=>void }> = [{ resolve, reject }]
+      const timer = setTimeout(async () => {
+        const entry = this.pendingWrites.get(id)
+        if (!entry) return
+        this.pendingWrites.delete(id)
+        try {
+          const out = await this._doSetDeviceState(id, entry.body)
+          for (const r of entry.resolvers) r.resolve(out)
+        } catch (e) {
+          for (const r of entry.resolvers) r.reject(e)
+        }
+      }, this.writeDebounceMs)
+
+      this.pendingWrites.set(id, { timer, body, resolvers })
+    })
+  }
+
+  private async _doSetDeviceState(id: string, body: any): Promise<any> {
+    // Prefer client API
+    if (this.client && typeof this.client.setDeviceState === 'function') {
+      return this.client.setDeviceState(id, body)
+    }
+
+    // Try generic command methods
+    if (this.client && typeof this.client.sendCommand === 'function') {
+      return this.client.sendCommand(id, body)
+    }
+
+    // OpenAPI fallback
+    if (this.cfg.openApiToken) {
+      const url = `${this.baseUrl}/devices/${id}/commands`
+      const opts = {
+        method: 'POST',
+        headers: {
+          Authorization: this.cfg.openApiToken,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      }
+      const resp = await this.fetchWithTimeoutAndRetry(url, opts, undefined, undefined, id)
+      return resp.json()
+    }
+
+    throw new Error('No SwitchBot client available for setDeviceState')
+  }
+
+  async destroy(): Promise<void> {
+    if (this.client && typeof this.client.destroy === 'function') {
+      await this.client.destroy()
+    }
+    this.client = null
+  }
+}