@tomorrowos/sdk 0.1.0

package/dist/store/types.js

@@ -0,0 +1,5 @@
+/**
+ * Persistent (or replaceable) data for pairing — scheme C.
+ * Live WebSocket handles stay in-memory on the TomorrowOS instance.
+ */
+export {};

package/dist/tomorrowos.d.ts

@@ -0,0 +1,62 @@
+import { EventEmitter } from "events";
+import http from "http";
+import type { TomorrowOSStore } from "./store/types.js";
+export interface TomorrowOSBrand {
+    name?: string;
+    cmsEndpoint?: string;
+    [key: string]: unknown;
+}
+export interface TomorrowOSOptions {
+    brand: TomorrowOSBrand;
+    /** Scheme C: inject Postgres/Redis-backed store. Defaults to MemoryStore. */
+    store?: TomorrowOSStore;
+}
+export interface ListenOptions {
+    port: number;
+    host?: string;
+    /**
+     * If set, GET requests serve files from this directory (e.g. CMS UI assets).
+     * `GET /` serves `staticIndex` (default `index.html`) under this root.
+     * WebSocket upgrades on `/` are unchanged.
+     */
+    staticRoot?: string;
+    /**
+     * Entry file under `staticRoot` for `GET /` (relative path only, no `..`).
+     * Default: `index.html`. Ignored when `staticRoot` is not set.
+     */
+    staticIndex?: string;
+}
+export declare class TomorrowOS extends EventEmitter {
+    readonly brand: TomorrowOSBrand;
+    private readonly store;
+    private readonly devices;
+    private httpServer;
+    private wss;
+    private staticRoot;
+    private staticIndexFile;
+    constructor(options: TomorrowOSOptions);
+    /** Verify a 6-digit pairing code (same as POST /pairing/verify). */
+    pairingVerify(code: string): Promise<{
+        deviceId: string;
+    }>;
+    pairing: {
+        verify: (code: string) => Promise<{
+            deviceId: string;
+        }>;
+    };
+    device(deviceId: string): {
+        sendCommand<T = unknown>(method: string, params?: Record<string, unknown>): Promise<{
+            status: string;
+            data?: T;
+            error?: string;
+            stack?: string;
+        }>;
+    };
+    private sendCommandToSocket;
+    listen(options: ListenOptions): http.Server;
+    private tryServeStatic;
+    private handleHttp;
+    private handleDeviceHttp;
+    private handleConnection;
+}
+//# sourceMappingURL=tomorrowos.d.ts.map

package/dist/tomorrowos.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tomorrowos.d.ts","sourceRoot":"","sources":["../src/tomorrowos.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,OAAO,IAAI,MAAM,MAAM,CAAC;AAKxB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,eAAe,CAAC;IACvB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAmDD,qBAAa,UAAW,SAAQ,YAAY;IAC1C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,GAAG,CAAgC;IAC3C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,eAAe,CAAgB;gBAE3B,OAAO,EAAE,iBAAiB;IAMtC,oEAAoE;IAC9D,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAiChE,OAAO;uBACU,MAAM;sBAlCgC,MAAM;;MAmC3D;IAEF,MAAM,CAAC,QAAQ,EAAE,MAAM;oBAGD,CAAC,oBACT,MAAM,WACN,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CAAC;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;;IAU5E,OAAO,CAAC,mBAAmB;IA6D3B,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC,MAAM;YAgD7B,cAAc;YAmCd,UAAU;YAyCV,gBAAgB;IAgE9B,OAAO,CAAC,gBAAgB;CA8EzB"}

package/dist/tomorrowos.js

@@ -0,0 +1,371 @@
+import { randomBytes, randomUUID } from "crypto";
+import { EventEmitter } from "events";
+import fs from "fs/promises";
+import http from "http";
+import path from "path";
+import { WebSocket, WebSocketServer } from "ws";
+import { MemoryStore } from "./store/memory-store.js";
+function createSixDigitCode() {
+    return Math.floor(100000 + Math.random() * 900000).toString();
+}
+async function readJsonBody(req) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(typeof chunk === "string" ? Buffer.from(chunk) : chunk);
+    }
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw.trim())
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error("Invalid JSON body");
+    }
+}
+function sendJson(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+function parseDevicePath(pathname) {
+    const base = /^\/device\/([^/]+)\/(.+)$/.exec(pathname);
+    if (!base)
+        return null;
+    const deviceId = decodeURIComponent(base[1]);
+    const action = base[2];
+    return { deviceId, action };
+}
+export class TomorrowOS extends EventEmitter {
+    brand;
+    store;
+    devices = new Map();
+    httpServer = null;
+    wss = null;
+    staticRoot = null;
+    staticIndexFile = "index.html";
+    constructor(options) {
+        super();
+        this.brand = options.brand;
+        this.store = options.store ?? new MemoryStore();
+    }
+    /** Verify a 6-digit pairing code (same as POST /pairing/verify). */
+    async pairingVerify(code) {
+        const record = await this.store.getPendingCode(code);
+        if (!record) {
+            const err = new Error("Invalid or expired code");
+            err.code = "PAIRING_INVALID";
+            throw err;
+        }
+        const pairingToken = randomBytes(32).toString("hex");
+        const pairedAt = new Date().toISOString();
+        await this.store.setPairedDevice(record.deviceId, {
+            pairingToken,
+            pairedAt
+        });
+        await this.store.deletePendingCode(code);
+        const ws = this.devices.get(record.deviceId);
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+                type: "pairing.verified",
+                method: "tomorrowos.pairing.verify",
+                deviceId: record.deviceId,
+                pairingToken
+            }));
+        }
+        this.emit("device.paired", { deviceId: record.deviceId });
+        return { deviceId: record.deviceId };
+    }
+    pairing = {
+        verify: (code) => this.pairingVerify(code)
+    };
+    device(deviceId) {
+        const self = this;
+        return {
+            async sendCommand(method, params = {}) {
+                const ws = self.devices.get(deviceId);
+                if (!ws || ws.readyState !== WebSocket.OPEN) {
+                    throw new Error("Device not connected");
+                }
+                return self.sendCommandToSocket(ws, deviceId, method, params);
+            }
+        };
+    }
+    sendCommandToSocket(ws, deviceId, method, params, timeoutMs = 60_000) {
+        const commandId = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                ws.removeListener("message", onMessage);
+                reject(new Error(`Command timeout: ${method}`));
+            }, timeoutMs);
+            const onMessage = (data) => {
+                let msg;
+                try {
+                    msg = JSON.parse(String(data));
+                }
+                catch {
+                    return;
+                }
+                if (msg.type === "command.result" &&
+                    msg.commandId === commandId &&
+                    msg.method === method) {
+                    clearTimeout(timer);
+                    ws.removeListener("message", onMessage);
+                    const status = String(msg.status ?? "unknown");
+                    if (status === "failed") {
+                        const error = new Error(String(msg.error ?? "Command failed"));
+                        this.emit("command.failed", {
+                            commandId,
+                            method,
+                            deviceId,
+                            error
+                        });
+                        resolve({
+                            status,
+                            error: String(msg.error),
+                            stack: msg.stack
+                        });
+                        return;
+                    }
+                    this.emit("command.verified", { commandId, method, deviceId });
+                    resolve({ status, data: msg.data });
+                }
+            };
+            ws.on("message", onMessage);
+            ws.send(JSON.stringify({
+                type: "command",
+                commandId,
+                method,
+                params
+            }));
+        });
+    }
+    listen(options) {
+        const { port, host = "0.0.0.0", staticRoot, staticIndex } = options;
+        this.staticRoot = staticRoot ?? null;
+        if (this.staticRoot) {
+            const idx = (staticIndex ?? "index.html").trim().replace(/^[\\/]+/, "") || "index.html";
+            if (idx.includes("..")) {
+                throw new Error("staticIndex must not contain '..'");
+            }
+            this.staticIndexFile = idx;
+        }
+        else {
+            this.staticIndexFile = "index.html";
+        }
+        const server = http.createServer((req, res) => {
+            void this.handleHttp(req, res);
+        });
+        const wss = new WebSocketServer({ noServer: true });
+        server.on("upgrade", (request, socket, head) => {
+            if (!request.url) {
+                socket.destroy();
+                return;
+            }
+            const { pathname } = new URL(request.url, `http://${request.headers.host}`);
+            if (pathname === "/" || pathname === "") {
+                wss.handleUpgrade(request, socket, head, (ws) => {
+                    wss.emit("connection", ws, request);
+                });
+            }
+            else {
+                socket.destroy();
+            }
+        });
+        wss.on("connection", (ws) => {
+            this.handleConnection(ws);
+        });
+        server.listen(port, host, () => {
+            // eslint-disable-next-line no-console
+            console.log(`[TomorrowOS] listening on http://${host}:${port}`);
+        });
+        this.httpServer = server;
+        this.wss = wss;
+        return server;
+    }
+    async tryServeStatic(pathname, res) {
+        if (!this.staticRoot)
+            return false;
+        const rel = pathname === "/" || pathname === "" ? this.staticIndexFile : pathname.slice(1);
+        if (!rel || rel.includes(".."))
+            return false;
+        const rootResolved = path.resolve(this.staticRoot);
+        const filePath = path.resolve(rootResolved, rel);
+        const relativeToRoot = path.relative(rootResolved, filePath);
+        if (relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+            return false;
+        }
+        try {
+            const buf = await fs.readFile(filePath);
+            const ext = path.extname(rel).toLowerCase();
+            const types = {
+                ".html": "text/html; charset=utf-8",
+                ".js": "application/javascript; charset=utf-8",
+                ".css": "text/css; charset=utf-8",
+                ".json": "application/json; charset=utf-8"
+            };
+            const ctype = types[ext] ?? "application/octet-stream";
+            res.writeHead(200, { "Content-Type": ctype });
+            res.end(buf);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async handleHttp(req, res) {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            const pathname = url.pathname;
+            if (req.method === "GET" && this.staticRoot) {
+                const served = await this.tryServeStatic(pathname, res);
+                if (served)
+                    return;
+            }
+            if (req.method === "POST" && pathname === "/pairing/verify") {
+                const body = (await readJsonBody(req));
+                const code = typeof body.code === "string" ? body.code : "";
+                try {
+                    const { deviceId } = await this.pairingVerify(code);
+                    sendJson(res, 200, { status: "success", deviceId });
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : "Verify failed";
+                    sendJson(res, 400, { status: "failed", error: msg });
+                }
+                return;
+            }
+            if (req.method === "POST") {
+                const parsed = parseDevicePath(pathname);
+                if (parsed) {
+                    await this.handleDeviceHttp(req, res, parsed);
+                    return;
+                }
+            }
+            sendJson(res, 404, { status: "failed", error: "Not found" });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : "Server error";
+            sendJson(res, 500, { status: "failed", error: msg });
+        }
+    }
+    async handleDeviceHttp(req, res, parsed) {
+        const { deviceId, action } = parsed;
+        const ws = this.devices.get(deviceId);
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+            sendJson(res, 404, { status: "failed", error: "Device not connected" });
+            return;
+        }
+        let method;
+        let params = {};
+        switch (action) {
+            case "get-info":
+                method = "device.info.get";
+                break;
+            case "get-capabilities":
+                method = "device.info.getCapabilities";
+                break;
+            case "reboot":
+                method = "device.power.reboot";
+                break;
+            case "content/set-policy": {
+                method = "device.content.setPolicy";
+                const body = (await readJsonBody(req));
+                if (!body.policy || typeof body.policy !== "object") {
+                    sendJson(res, 400, {
+                        status: "failed",
+                        error: "Invalid payload. Provide params.policy object."
+                    });
+                    return;
+                }
+                params = { policy: body.policy };
+                break;
+            }
+            case "content/clear":
+                method = "device.content.clear";
+                break;
+            default:
+                sendJson(res, 404, { status: "failed", error: "Unknown device action" });
+                return;
+        }
+        try {
+            const result = await this.sendCommandToSocket(ws, deviceId, method, params);
+            if (result.status === "failed") {
+                sendJson(res, 500, {
+                    status: result.status,
+                    error: result.error ?? "Command failed",
+                    stack: result.stack
+                });
+                return;
+            }
+            sendJson(res, 200, { status: result.status, data: result.data });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : "Command failed";
+            sendJson(res, 500, { status: "failed", error: msg });
+        }
+    }
+    handleConnection(ws) {
+        ws.on("message", (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(raw));
+            }
+            catch {
+                return;
+            }
+            const type = msg.type;
+            if (type === "device.hello") {
+                const deviceId = typeof msg.deviceId === "string" && msg.deviceId
+                    ? msg.deviceId
+                    : randomUUID();
+                const code = createSixDigitCode();
+                this.devices.set(deviceId, ws);
+                void this.store.setPendingCode(code, {
+                    deviceId,
+                    createdAt: Date.now()
+                });
+                ws.deviceId = deviceId;
+                ws.send(JSON.stringify({
+                    type: "pairing.code",
+                    method: "tomorrowos.pairing.createCode",
+                    code,
+                    deviceId
+                }));
+                this.emit("device.online", { deviceId });
+                return;
+            }
+            if (type === "device.resume") {
+                const deviceId = String(msg.deviceId ?? "");
+                const pairingToken = String(msg.pairingToken ?? "");
+                void (async () => {
+                    const record = await this.store.getPairedDevice(deviceId);
+                    if (!record || record.pairingToken !== pairingToken) {
+                        ws.send(JSON.stringify({
+                            type: "device.resume.failed",
+                            reason: "Invalid pairing token"
+                        }));
+                        return;
+                    }
+                    this.devices.set(deviceId, ws);
+                    ws.deviceId = deviceId;
+                    ws.send(JSON.stringify({
+                        type: "device.resumed",
+                        method: "tomorrowos.pairing.resume",
+                        deviceId
+                    }));
+                    this.emit("device.online", { deviceId });
+                })();
+            }
+        });
+        ws.on("close", () => {
+            const id = ws.deviceId;
+            if (id) {
+                this.devices.delete(id);
+                this.emit("device.offline", {
+                    deviceId: id,
+                    lastSeen: new Date().toISOString()
+                });
+            }
+        });
+    }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tomorrowos/sdk",
+  "version": "0.1.0",
+  "description": "TomorrowOS CMS server SDK — WebSocket transport, pairing, device commands, optional static CMS UI. Includes CLI (tomorrowos init / build) and starter templates.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "tomorrowos": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LLM_PROMPT.md",
+    "BUILD_GUARDRAILS.md",
+    "PLAYER_INSTALL.md",
+    "brand.schema.json",
+    "brand.example.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.41",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.5.0"
+  },
+  "license": "Apache-2.0"
+}

package/templates/cms-starter/assets/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="160" height="40" viewBox="0 0 160 40" role="img" aria-label="Logo placeholder">
+  <rect width="160" height="40" rx="6" fill="#FF8A3D"/>
+  <text x="80" y="26" text-anchor="middle" fill="#ffffff" font-family="system-ui,sans-serif" font-size="14" font-weight="600">Your logo</text>
+</svg>

package/templates/cms-starter/brand.json

@@ -0,0 +1,24 @@
+{
+  "name": "My Venue",
+  "tagline": "Digital signage",
+  "targetPlatforms": ["tizen"],
+  "primaryColor": "#FF8A3D",
+  "secondaryColor": "#F5F3EF",
+  "backgroundColor": "#FAFAF9",
+  "textColor": "#0A0908",
+  "logoPath": "./assets/logo.svg",
+  "fontFamily": "Inter",
+  "cmsEndpoint": "ws://localhost:3000",
+  "cms": {
+    "useCase": "other",
+    "hostingTarget": "self-hosted",
+    "expectedScreens": 5,
+    "features": {
+      "bulkCommands": false,
+      "proofOfPlay": false,
+      "contentScheduling": true,
+      "userManagement": false
+    }
+  },
+  "protocolVersion": "1.0"
+}

package/templates/cms-starter/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "my-tomorrowos-cms",
+  "version": "0.1.0",
+  "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts",
+    "build-player": "tomorrowos build --platform tizen"
+  },
+  "dependencies": {
+    "@tomorrowos/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}

package/templates/cms-starter/server.ts

@@ -0,0 +1,47 @@
+/**
+ * TomorrowOS CMS server — minimal starter.
+ * Add routes, database, or serve a React build via listen({ staticRoot }).
+ */
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { TomorrowOS } from "@tomorrowos/sdk";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const brand = JSON.parse(readFileSync(join(__dirname, "brand.json"), "utf8"));
+
+const tomorrowos = new TomorrowOS({ brand });
+
+tomorrowos.listen({
+  port: Number(process.env.PORT) || 3000,
+  host: "0.0.0.0"
+});
+
+tomorrowos.on("device.paired", (event) => {
+  console.log(`[TomorrowOS] device paired: ${event.deviceId}`);
+});
+
+tomorrowos.on("device.online", (event) => {
+  console.log(`[TomorrowOS] device online: ${event.deviceId}`);
+});
+
+tomorrowos.on("device.offline", (event) => {
+  console.log(
+    `[TomorrowOS] device offline: ${event.deviceId} (lastSeen: ${event.lastSeen})`
+  );
+});
+
+tomorrowos.on("command.verified", (event) => {
+  console.log(
+    `[TomorrowOS] command verified: ${event.commandId} (${event.method})`
+  );
+});
+
+tomorrowos.on("command.failed", (event) => {
+  console.error(
+    `[TomorrowOS] command failed: ${event.commandId} (${event.method}) — ${event.error.message}`
+  );
+});
+
+export default tomorrowos;

package/templates/cms-starter/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "noEmit": true
+  },
+  "include": ["server.ts"]
+}