whiskops-sdk 0.1.0

package/README.md

@@ -0,0 +1,34 @@
+# @codemenschen/whiskops-sdk (Node.js)
+
+Client SDK for the Whisk device External API. Wraps bearer-token auth,
+idempotency-key generation for `turn`, retry with backoff on 429/5xx, and
+client-side spacing between `turn` calls.
+
+## Usage
+
+```js
+import { WhiskClient } from "./src/index.js";
+
+const client = new WhiskClient({ apiKey: process.env.WHISK_API_KEY });
+
+const status = await client.status();
+if (status.online) {
+  await client.turn({ speed: 80 });
+  await client.stop();
+}
+```
+
+## Notes
+
+- `turn()` validates `speed` is an integer 1-500 before making a request.
+- A 409 response (active Time/Turns session) is not retried — it is thrown
+  as a `WhiskApiError` since retrying would not resolve the conflict.
+- `baseUrl` defaults to `https://myremotedevice.com/api/v1/external` per the
+  published API docs; override it via the constructor if the real production
+  host differs.
+
+## Tests
+
+```
+npm test
+```

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "whiskops-sdk",
+  "version": "0.1.0",
+  "description": "Client SDK for the Whisk device External API (status, turn, stop) with built-in idempotency-key handling and retry/backoff.",
+  "type": "module",
+  "main": "src/index.js",
+  "files": ["src", "README.md"],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": ["whisk", "iot", "device-control", "sdk"],
+  "author": "Codemenschen GmbH",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,125 @@
+const DEFAULT_BASE_URL = "https://myremotedevice.com/api/v1/external";
+const MIN_SPEED = 1;
+const MAX_SPEED = 500;
+const MIN_TURN_INTERVAL_MS = 1000;
+
+export class WhiskApiError extends Error {
+  constructor(message, { status, body } = {}) {
+    super(message);
+    this.name = "WhiskApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Client for the Whisk device External API.
+ *
+ * Wraps authentication, idempotency-key generation for `turn`, and retry with
+ * exponential backoff on transient failures (429 / 5xx). A 409 from `turn`
+ * (an active Time/Turns session) is not retried — it is returned to the caller
+ * as an error since retrying blindly would not help.
+ */
+export class WhiskClient {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiKey - Bearer token (`twk_...`) for a single device.
+   * @param {string} [opts.baseUrl] - Override the External API base URL.
+   * @param {number} [opts.maxRetries] - Max retry attempts on 429/5xx (default 3).
+   * @param {number} [opts.minTurnIntervalMs] - Client-side spacing enforced between
+   *   `turn` calls, mirroring the documented "at least 1 second apart" limit.
+   */
+  constructor({ apiKey, baseUrl = DEFAULT_BASE_URL, maxRetries = 3, minTurnIntervalMs = MIN_TURN_INTERVAL_MS } = {}) {
+    if (!apiKey) throw new Error("WhiskClient requires apiKey");
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.maxRetries = maxRetries;
+    this.minTurnIntervalMs = minTurnIntervalMs;
+    this._lastTurnAt = 0;
+  }
+
+  async _request(path, { method = "GET", headers = {}, body } = {}) {
+    const url = `${this.baseUrl}${path}`;
+    const reqHeaders = {
+      Authorization: `Bearer ${this.apiKey}`,
+      ...headers,
+    };
+    if (body !== undefined) reqHeaders["Content-Type"] = "application/json";
+
+    let attempt = 0;
+    for (;;) {
+      const res = await fetch(url, {
+        method,
+        headers: reqHeaders,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+
+      if (res.status === 429 || res.status >= 500) {
+        if (attempt >= this.maxRetries) {
+          const text = await res.text().catch(() => "");
+          throw new WhiskApiError(`${method} ${path} failed after ${attempt + 1} attempts: ${res.status}`, {
+            status: res.status,
+            body: text,
+          });
+        }
+        const retryAfter = Number(res.headers.get("retry-after"));
+        const backoffMs = Number.isFinite(retryAfter) && retryAfter > 0
+          ? retryAfter * 1000
+          : 2 ** attempt * 500;
+        await sleep(backoffMs);
+        attempt += 1;
+        continue;
+      }
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new WhiskApiError(`${method} ${path} failed: ${res.status}`, { status: res.status, body: text });
+      }
+
+      if (res.status === 204) return null;
+      return res.json().catch(() => null);
+    }
+  }
+
+  /** Read current device status. Offline devices return `{ online: false }` successfully. */
+  status() {
+    return this._request("/device/status");
+  }
+
+  /**
+   * Start a single turn.
+   * @param {object} opts
+   * @param {number} opts.speed - Integer 1-500.
+   * @param {string} [opts.idempotencyKey] - Supply your own to control retries/dedup
+   *   explicitly; otherwise one is generated per call.
+   */
+  async turn({ speed, idempotencyKey } = {}) {
+    if (!Number.isInteger(speed) || speed < MIN_SPEED || speed > MAX_SPEED) {
+      throw new RangeError(`speed must be an integer between ${MIN_SPEED} and ${MAX_SPEED}`);
+    }
+
+    const sinceLast = Date.now() - this._lastTurnAt;
+    if (sinceLast < this.minTurnIntervalMs) {
+      await sleep(this.minTurnIntervalMs - sinceLast);
+    }
+    this._lastTurnAt = Date.now();
+
+    const key = idempotencyKey || crypto.randomUUID();
+    return this._request("/device/turn", {
+      method: "POST",
+      headers: { "Idempotency-Key": key },
+      body: { speed },
+    });
+  }
+
+  /** Stop the device. Also ends any active Time/Turns session. */
+  stop() {
+    return this._request("/device/stop", { method: "POST" });
+  }
+}
+
+export default WhiskClient;