@tomorrowos/sdk 0.9.19 → 0.9.21

package/README.md

@@ -2,7 +2,9 @@
 
 **You are building a digital signage CMS using TomorrowOS. Before writing any code, follow the elicitation protocol in `LLM_PROMPT.md`. Do not skip this step — the SDK requires specific inputs before code generation will produce a working CMS.**
 
-**On Replit:** if the user asks to set up / configure a CMS interactively, follow **`REPLIT_SETUP.md`** instead (Q&A for screen count → SQLite vs Supabase → Cloudinary vs Object Storage → `brand.json`).
+**On Replit:** if the user asks to set up / configure a CMS interactively, follow **`REPLIT_SETUP.md`** instead (Q&A for store → media → `brand.json`).
+
+**On Vercel:** if the user asks to set up / configure a CMS interactively, follow **`VERCEL_SETUP.md`** (Session pooler Supabase URL, Fluid compute + WebSocket, Cloudinary, `cms.hostingTarget: "vercel"`).
 
 TomorrowOS is the open standard for digital signage. This SDK lets you build a CMS that controls Samsung Tizen, BrightSign, LG webOS, Android, ChromeOS, and Windows screens through a single unified API.
 
@@ -13,13 +15,14 @@ TomorrowOS is the open standard for digital signage. This SDK lets you build a C
 When you see this package referenced in a user prompt, your workflow is:
 
 1. **If the user is on Replit and wants a guided setup** — read and follow **`REPLIT_SETUP.md`** (preferred for Replit Agent)
-2. **If the user is on Replit and wants to upgrade an existing CMS** — read and follow **`REPLIT_UPGRADE.md`** (never `init --force`)
-3. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
-4. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
-5. **Read `brand.schema.json`** — validated shape of `brand.json`
-6. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
-7. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
-8. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
+2. **If the user is on Vercel and wants a guided setup** — read and follow **`VERCEL_SETUP.md`** (preferred for Vercel Agent)
+3. **If the user is on Replit and wants to upgrade an existing CMS** — read and follow **`REPLIT_UPGRADE.md`** (never `init --force`)
+4. **Otherwise read `LLM_PROMPT.md`** — five required questions before generating code
+5. **Read `BUILD_GUARDRAILS.md`** — mandatory components every generated CMS must include
+6. **Read `brand.schema.json`** — validated shape of `brand.json`
+7. Run **`npx tomorrowos init`** (or copy `templates/cms-starter/` from this package) — minimal CMS server seed
+8. **Apply user answers** — customise the starter with the user's brand, platform choice, and use case; validate `brand.json` against `brand.schema.json`
+9. **Show `PLAYER_INSTALL.md`** — after the CMS is working, show how to build and install the player on a screen
 
 You must not write WebSocket transport, pairing wire format, or platform-specific player bridge code in the CMS — the SDK handles server-side device sessions and HTTP helpers. You customise UI, branding, and how you call the SDK.
 
@@ -59,6 +62,18 @@ That wizard configures Supabase, prefers Cloudinary for media, and writes
 `brand.json` from your answers. On Replit, Supabase must use Secret
 **`SUPABASE_URL`** (not the reserved `DATABASE_URL`).
 
+### Vercel guided setup
+
+In Vercel Agent (or any AI setup prompt), paste:
+
+```text
+Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
+IF any step contradicts Vercel, adapt to settings that Vercel can accept.
+```
+
+That wizard requires the Supabase **Session pooler** URL, prefers Cloudinary,
+enables Fluid compute for WebSockets, and sets `cms.hostingTarget` to `"vercel"`.
+
 ### Replit upgrade (existing CMS)
 
 In Replit Agent, paste:
@@ -153,6 +168,7 @@ See `PLAYER_INSTALL.md` for installation notes.
 |------|---------|
 | `LLM_PROMPT.md` | Five-question elicitation for LLMs |
 | `REPLIT_SETUP.md` | Replit Agent guided CMS setup |
+| `VERCEL_SETUP.md` | Vercel Agent guided CMS setup |
 | `REPLIT_UPGRADE.md` | Replit Agent upgrade to latest SDK (no init) |
 | `BUILD_GUARDRAILS.md` | Mandatory CMS components |
 | `PLAYER_INSTALL.md` | Player build / install / pairing |

package/VERCEL_SETUP.md

@@ -0,0 +1,427 @@
+# Vercel Setup Protocol for TomorrowOS CMS
+
+> **This file is a contract for Vercel Agent / AI coding assistants setting up TomorrowOS on Vercel.**  
+> Follow it literally. Ask questions in order. Do not invent secrets. Prefer configuring **Vercel Environment Variables**, `.env` (non-secrets only), `brand.json`, and `server.ts` store wiring over inventing a custom CMS.
+>
+> **On Vercel, this file is the setup questionnaire** (not `REPLIT_SETUP.md`, not `LLM_PROMPT.md`).
+>
+> Protocol id: `vercel-setup/1.0` — pairs with `@tomorrowos/sdk` packages that ship `templates/cms-starter` and this file.
+
+## User trigger (copy-paste)
+
+When a human pastes a prompt like this, **read this file and start Question 1 immediately**:
+
+```text
+Follow @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
+Ask only the questions listed in VERCEL_SETUP.md, in order. Do not use LLM_PROMPT.md or REPLIT_SETUP.md.
+If any step contradicts Vercel, adapt to settings Vercel can accept (document the adaptation).
+After all setup questions are answered (including Cloudinary Env Vars if you chose Cloudinary), configure and deploy — minimal verification only (Control Panel at /). Prefer Supabase Session pooler URL. Do not treat sandbox ENETUNREACH / IPv6 :5432 errors as a hard setup failure when the pooler URL is configured for production.
+Question 3 only updates brand.json. Do not skip steps.
+```
+
+Alternate triggers:
+
+- “Set up TomorrowOS on Vercel using VERCEL_SETUP.md”
+- “Configure my TomorrowOS CMS (Vercel wizard)”
+
+When any of these fire, **ignore `REPLIT_SETUP.md` and `LLM_PROMPT.md`** for the Q&A phase (you may skim Replit docs only for shared SDK semantics).
+
+---
+
+## IRON RULE: long-lived Node + WebSocket (not classic static / short Functions)
+
+> **This is the #1 deployability rule on Vercel. Non-negotiable.**
+
+TomorrowOS CMS is **one Node process** that serves:
+
+- Browser Control Panel at `GET /` (`public/` via `staticRoot`)
+- Device **WebSocket** on the same origin (`https` → players use `wss`)
+
+| Required | Forbidden |
+|----------|-----------|
+| Single **Node HTTP server** entry (`tsx server.ts` / exported `http.Server` from `listen()`) | Next.js / Remix / static-only site as the CMS |
+| **Fluid compute** enabled (needed for WebSockets on Vercel) | Classic short-lived serverless with no WebSocket / no Fluid |
+| Durable store = **Supabase Postgres** (pooler URL) | **SQLite / `data/*.db` as production store** on Vercel (ephemeral filesystem) |
+| Media = **Cloudinary** (recommended) or other durable HTTPS URLs | Relying on local `public/uploads` alone for production fleets |
+| Env vars in **Vercel Project → Settings → Environment Variables** | Committing passwords / Cloudinary secrets / `.env` with secrets |
+| `cms.hostingTarget`: `"vercel"` in `brand.json` | Creating `.replit` / Replit artifact files |
+
+**Do not** scaffold a leftover Next.js app “and put TomorrowOS beside it.” Remove Next scaffolds so TomorrowOS `server.ts` is the sole app.
+
+---
+
+## Questionnaire scope (STRICT)
+
+Ask **only** these questions, in **this exact order**:
+
+| Step | Section | When |
+|------|---------|------|
+| 1 | **Question 1** — Supabase **Session pooler** connection string | Always |
+| 2 | **Question 2** — Media storage (+ Cloudinary Env Vars if chosen) | Always (after Q1) |
+| 3 | **Question 3** — Brand / TomorrowOS look (`brand.json` only) | Always last |
+
+**That is the complete list.** Do **not** ask how many screens / devices. There is **no** “Question 2b” — Cloudinary credentials stay **inside Question 2**.
+
+If the user says “just set it up, don’t ask questions,” respond:
+
+> I need a few quick answers from VERCEL_SETUP.md (Supabase Session pooler URL, media storage — plus Cloudinary credentials if you choose Cloudinary — and branding). It takes about a minute and ensures the CMS works on Vercel.
+
+Then ask **Question 1**.
+
+---
+
+## Hard rules
+
+1. **Ask only VERCEL_SETUP.md questions 1–3.** Never use `LLM_PROMPT.md` or `REPLIT_SETUP.md` as the questionnaire.
+2. **One question at a time** (exception: after Cloudinary choice, immediately collect the three Cloudinary env vars in the same Question 2).
+3. **Do not invent** Cloudinary credentials, Supabase URLs, or brand colours.
+4. **Prefer `SUPABASE_URL`** for Supabase (same as Replit). `DATABASE_URL` may be used as fallback on Vercel, but document one canonical name — prefer **`SUPABASE_URL`**.
+5. **Always prefer the Supabase Session pooler URL** (port **6543**, host like `*.pooler.supabase.com`). Direct `db.*.supabase.co:5432` URLs commonly fail on Vercel/sandbox with **`ENETUNREACH`** (often IPv6).
+6. **Prefer `npx @tomorrowos/sdk init`** (or `templates/cms-starter`) as the seed. Do not rebuild pairing / WebSocket / playlist APIs.
+7. **Never commit secrets.** Use Vercel Environment Variables (+ optional non-secret flags in committed `.env.example`).
+8. **Skip Replit-only files:** do **not** create `.replit`, `.replit-artifact`, or Replit `deploymentTarget`.
+9. **SQLite is not a production store on Vercel.** Configure Supabase for pairing/playlists. Keep `sqlitePath` only as a local-dev fallback in `createTomorrowOSStore`.
+10. **Enable Fluid compute** for WebSockets. Confirm Project settings after scaffold.
+11. **Export the HTTP server** Vercel can capture: `const server = tomorrowos.listen(...); export default server;` (or equivalent). Do not export only the `TomorrowOS` class instance unless the platform documents another capture path.
+12. After Q&A: **configure → install → run/deploy → minimal verify** (Control Panel at `/`). Do not run a long test suite.
+
+**Question order:** Q1 → Q2 → Q3 → execution checklist.
+
+---
+
+## Runtime & Vercel deploy rules (mandatory)
+
+### Runtime
+
+- Serve with **`tsx server.ts`** (or compiled Node that still calls `TomorrowOS.listen` with `staticRoot`).
+- Keep **`@tomorrowos/sdk`** and put **`tsx` in `dependencies`** (not only `devDependencies`) if production runs via `tsx`.
+- Node **20+**.
+- **Do not** replace the SDK with a hand-rolled server that drops WebSocket upgrades.
+
+### Expected `package.json` scripts
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts"
+  }
+}
+```
+
+**Forbidden as the Deploy entrypoint:** `next start`, static export only, or any command that does not start `TomorrowOS.listen(...)`.
+
+### Minimal dependencies
+
+```json
+{
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@tomorrowos/sdk": "latest",
+    "dotenv": "^17.2.3",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "dev": "tsx watch server.ts",
+    "start": "tsx server.ts"
+  }
+}
+```
+
+Use the latest published `@tomorrowos/sdk` when scaffolding (do not invent versions).
+
+### `server.ts` pattern (Vercel-adapted)
+
+```ts
+import "dotenv/config";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { createTomorrowOSStore, TomorrowOS } from "@tomorrowos/sdk";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const brand = JSON.parse(readFileSync(join(__dirname, "brand.json"), "utf8"));
+
+const store = createTomorrowOSStore({
+  // Prefer SUPABASE_URL. On Vercel use the Session pooler connection string.
+  databaseUrl: process.env.SUPABASE_URL || process.env.DATABASE_URL,
+  sqlitePath: join(__dirname, "data", "tomorrowos.db") // local/dev fallback only
+});
+
+const tomorrowos = new TomorrowOS({ brand, store });
+
+const server = tomorrowos.listen({
+  port: Number(process.env.PORT) || 3000,
+  host: "0.0.0.0",
+  staticRoot: join(__dirname, "public")
+});
+
+// Vercel / Node server capture: export the HTTP server, not only TomorrowOS.
+export default server;
+```
+
+Load env with `dotenv` for local/`vercel dev`. On production Deploy, Vercel injects Environment Variables natively.
+
+### `vercel.json` (recommended minimum)
+
+Adapt to the project’s current Vercel Node-server / Fluid conventions. At minimum ensure:
+
+```json
+{
+  "fluid": true
+}
+```
+
+Also:
+
+1. Project → **Fluid compute** enabled (required for WebSockets).
+2. Framework Preset: **Other** (or Node) — **not** Next.js unless wrapping is intentional and still exposes TomorrowOS `listen()`.
+3. Install / Start commands must end in running the CMS server (e.g. `npm run start` or Vercel’s detected `server.ts` entry).
+4. Do **not** enable “Output Directory” static-only hosting for this CMS.
+
+If Vercel’s UI and this file disagree on bundling, **prefer whatever keeps a single long-lived Node HTTP server with WebSocket upgrade on `/`**. Document the adaptation in the final summary.
+
+### WebSocket / multi-instance note
+
+- Device sockets are pinned to **one** function/instance. TomorrowOS device maps are **in-memory**.
+- For large fleets on multi-instance Vercel, prefer **one stable instance / region**, or accept that reconnects may land on another instance until the product adds shared presence (out of scope for this setup).
+- Always use **Supabase** so pairings/playlists survive cold starts and deploys.
+
+### What not to create
+
+- ❌ `.replit`, `.replit-artifact`
+- ❌ Next.js `app/` / `pages/` CMS
+- ❌ Separate “API project” without the Control Panel
+- ❌ Committing `SUPABASE_URL` passwords or Cloudinary secrets
+
+---
+
+## Question 1 — Supabase Session pooler (always)
+
+> Always configure Supabase for Vercel. Do **not** ask screen counts.
+
+**Ask exactly:**
+
+> Paste your Supabase Postgres **Session pooler** connection string. I will store it as the Vercel Environment Variable **`SUPABASE_URL`**.
+>
+> In Supabase: **Project Settings → Database → Connection string → Connection pooling** (Session mode).  
+> Preferred shape:  
+> `postgresql://postgres.[PROJECT]:[PASSWORD]@aws-0-[REGION].pooler.supabase.com:6543/postgres`
+>
+> **Do not** use the direct host `db.*.supabase.co:5432` for Vercel — sandbox/serverless often fails with `ENETUNREACH` (commonly on IPv6).
+>
+> Confirm SSL is required (usually **yes** for Supabase).
+
+**You must then:**
+
+1. Set Vercel Env Vars (Production + Preview + Development as appropriate):
+   - `SUPABASE_URL=<pooler string>`
+   - `TOMORROWOS_STORE=supabase`
+   - `DATABASE_SSL=true` (unless user explicitly disables SSL)
+2. Wire `server.ts` as in **Runtime & Vercel deploy rules**.
+3. Optional committed `.env.example` with **placeholders only** (no real password).
+4. **Do not** commit the real connection string.
+5. **Configuration over probing:** if local/`vercel dev` still shows `ENETUNREACH` / IPv6 errors, verify the string is the **pooler** (`pooler.supabase.com` + `:6543`). Treat remaining sandbox DNS issues as non-fatal when Production deploy Env Vars are correct — but **do** fix an obvious direct `:5432` URL before finishing.
+
+If the user refuses Supabase, warn that Vercel cannot use durable SQLite for fleets, then only continue with SQLite after explicit confirmation (local/demo only).
+
+**Later in Question 3:** set `cms.hostingTarget` to **`"vercel"`**.
+
+---
+
+## Question 2 — Media storage
+
+### Step A — Ask storage choice
+
+**Ask exactly:**
+
+> How should playlist media (images/videos) be stored?
+>
+> **Recommended on Vercel: Cloudinary** — durable public HTTPS URLs (`https://res.cloudinary.com/...`). Local `public/uploads` is ephemeral on serverless/filesystem deploys and is a poor fleet default.
+>
+> Alternatives:
+> - **Local disk only** — `public/uploads` (OK for quick local tests; **not** for production Vercel fleets).
+>
+> Do you want me to set up **Cloudinary**? (yes / no)
+
+### Step B — If YES / Cloudinary (same Question 2)
+
+Immediately collect and store as **Vercel Environment Variables**:
+
+- `CLOUDINARY_CLOUD_NAME`
+- `CLOUDINARY_API_KEY`
+- `CLOUDINARY_API_SECRET`
+- Optional: `CLOUDINARY_FOLDER` (e.g. `tomorrowos`)
+
+Do **not** invent placeholders. Do **not** proceed to Question 3 until the three required vars exist. Do **not** run a formal Cloudinary upload test unless the user asks.
+
+The SDK auto-detects these env vars.
+
+### If NO — local uploads
+
+1. `mkdir -p public/uploads`
+2. Warn clearly: files may vanish on redeploy; players need stable HTTPS URLs — Cloudinary is strongly preferred for Vercel.
+
+---
+
+## Question 3 — Brand (`brand.json` only)
+
+> Updates **only** `brand.json`. Does **not** change Vercel project settings, Env Vars, or `server.ts` store wiring beyond what Q1–Q2 already required.
+
+**Ask exactly:**
+
+> Let’s brand your TomorrowOS experience. Please provide:
+>
+> 1. **Product / venue name**
+> 2. **Tagline** (optional)
+> 3. **Primary colour** (hex, e.g. `#FF8A3D`)
+> 4. **Background colour** (hex, optional — default `#FAFAF9`)
+> 5. **Text colour** (hex, optional — default `#0A0908`)
+> 6. **Secondary / accent colour** (hex, optional)
+> 7. **Logo** — upload SVG/PNG into the project, or a URL I can fetch into `./assets/`
+
+Then write `brand.json` (validate mentally against `brand.schema.json`). Minimum:
+
+```json
+{
+  "name": "<user name>",
+  "tagline": "<user tagline or Digital signage>",
+  "targetPlatforms": ["tizen"],
+  "primaryColor": "#FF8A3D",
+  "secondaryColor": "#F5F3EF",
+  "backgroundColor": "#FAFAF9",
+  "textColor": "#0A0908",
+  "logoPath": "./assets/logo.svg",
+  "fontFamily": "Inter",
+  "cms": {
+    "useCase": "other",
+    "hostingTarget": "vercel",
+    "expectedScreens": 5,
+    "features": {
+      "bulkCommands": false,
+      "proofOfPlay": false,
+      "contentScheduling": true,
+      "userManagement": false
+    }
+  },
+  "protocolVersion": "1.0"
+}
+```
+
+Always set **`cms.hostingTarget`: `"vercel"`** without asking. Default `expectedScreens` to `5` unless the user already volunteered a number. Set `cmsEndpoint` only if they already know the public `https://…vercel.app` URL; otherwise tell them to pair TVs with the deployed HTTPS origin (player maps `https://` → `wss://`).
+
+---
+
+## After all answers — execution checklist
+
+### A. Seed the project
+
+```bash
+npx @tomorrowos/sdk@latest init .
+# If not empty and user confirms starter overwrite:
+# npx @tomorrowos/sdk@latest init . --force
+```
+
+Then:
+
+1. Remove leftover Next.js / other frameworks so TomorrowOS is sole app.
+2. Apply Vercel-adapted `server.ts` (**export `listen()` HTTP server**).
+3. Add/adjust `vercel.json` with **`fluid: true`** (or enable Fluid in the dashboard).
+4. Do **not** add `.replit*`.
+
+### B. Environment Variables (Vercel dashboard + local)
+
+| Name | Required | Notes |
+|------|----------|--------|
+| `SUPABASE_URL` | Yes (production) | **Session pooler** `:6543` |
+| `TOMORROWOS_STORE` | Yes | `supabase` |
+| `DATABASE_SSL` | Yes (typical) | `true` |
+| `CLOUDINARY_*` | If Q2 = Cloudinary | Three keys |
+| `PORT` | Optional | Vercel injects as needed |
+
+Mirror non-secrets in `.env` for local `npm run dev` if helpful; never commit secrets.
+
+### C. Install and run
+
+```bash
+npm install
+npm run start
+# or: vercel dev
+```
+
+Confirm logs: `[TomorrowOS] listening on http://0.0.0.0:…`  
+Confirm browser: Control Panel at `/`.
+
+### D. Deploy
+
+```bash
+vercel --prod
+# or git push → Vercel Git integration
+```
+
+Tell the user:
+
+- **Control Panel:** `https://YOUR-PROJECT.vercel.app`
+- **TV CMS endpoint:** same HTTPS origin (players use `wss://`)
+
+### E. Minimal verification only
+
+**Do:**
+
+1. Control Panel HTML at `/`
+2. Server status: Media OK when Cloudinary configured
+3. Database: if ERROR shows **`ENETUNREACH` … IPv6 … `:5432`**, switch `SUPABASE_URL` to **pooler `:6543`** and redeploy — call this out explicitly to the user
+4. Fluid compute on
+
+**Do not block** on long WebSocket/device pairing tests unless the user asks.
+
+---
+
+## Failure recovery cheat sheet
+
+| Symptom | Likely cause | Fix |
+|---------|--------------|-----|
+| `ENETUNREACH` / IPv6 / `:5432` | Direct Supabase DB URL | Use **Session pooler** `*.pooler.supabase.com:6543` |
+| Control Panel OK, devices never stay paired after restart | SQLite / ephemeral disk | Must use Supabase |
+| Uploads break / broken thumbs in prod | Local `public/uploads` | Cloudinary |
+| WebSocket fails / devices drop immediately | Fluid off / static-only / Next wrapper | Enable Fluid; sole Node `listen()` server |
+| Agent created Next.js + TomorrowOS | Wrong scaffold | Remove Next; keep cms-starter |
+| Secrets in git | Mistake | Rotate keys; move to Vercel Env Vars |
+| Replit files present | Copied wrong protocol | Delete `.replit*`; use this file |
+
+---
+
+## How this differs from `REPLIT_SETUP.md`
+
+| Topic | Replit | Vercel |
+|-------|--------|--------|
+| Secrets | Replit Secrets | Vercel Environment Variables |
+| Deploy config | `.replit`, artifact `kind=web` | `vercel.json` + Fluid; **no** `.replit` |
+| `hostingTarget` | `"here"` | `"vercel"` |
+| Supabase URL | Prefer pooler; Preview DNS may fail | **Require pooler**; direct `:5432` often `ENETUNREACH` |
+| SQLite | Demo OK on persistent Repl disk | **Not** production on Vercel |
+| Object Storage option | Replit Object Storage | N/A — prefer Cloudinary |
+| WebSocket | Long-lived Node (Autoscale) | Fluid compute + Node server export |
+
+---
+
+## Final summary template (Agent → human)
+
+After setup, report:
+
+1. **Live URL** (Production)
+2. **Env Vars set** (names only — never values)
+3. **Store:** Supabase pooler / SSL flags
+4. **Media:** Cloudinary or local (with warning)
+5. **Brand:** name + `hostingTarget: vercel`
+6. **Adaptations from Replit protocol:** list (e.g. skipped `.replit`, exported HTTP server, Fluid, pooler URL)
+7. **Open action:** if Database still ERROR, paste the pooler instruction again
+
+Protocol complete when the Control Panel renders at `/` on the deployed (or local) server and Q1–Q3 configuration is saved — even if a sandbox DB probe still flakes **after** the pooler URL is correctly set for Production.

package/dist/tomorrowos.d.ts

@@ -136,6 +136,15 @@ export declare class TomorrowOS extends EventEmitter {
         onOffTimer: DeviceOnOffTimer;
         pushed: boolean;
     }>;
+    /**
+     * Clear the daily on/off timer. The player keeps its current mute / power-save
+     * state until a new timer is set.
+     */
+    clearDeviceOnOffTimer(deviceId: string): Promise<{
+        deviceId: string;
+        onOffTimer: null;
+        pushed: boolean;
+    }>;
     private pushOnOffTimerToDevice;
     setDeviceName(deviceId: string, deviceName: string): Promise<{
         deviceId: string;

package/dist/tomorrowos.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tomorrowos.d.ts","sourceRoot":"","sources":["../src/tomorrowos.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tomorrowos.d.ts","sourceRoot":"","sources":["../src/tomorrowos.ts"],"names":[],"mappings":"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"}

package/dist/tomorrowos.js

@@ -441,15 +441,33 @@ export class TomorrowOS extends EventEmitter {
         const pushed = await this.pushOnOffTimerToDevice(id);
         return { deviceId: id, onOffTimer, pushed };
     }
+    /**
+     * Clear the daily on/off timer. The player keeps its current mute / power-save
+     * state until a new timer is set.
+     */
+    async clearDeviceOnOffTimer(deviceId) {
+        const id = String(deviceId || "").trim();
+        if (!id) {
+            throw new Error("deviceId is required");
+        }
+        const existing = await this.store.getPairedDevice(id);
+        if (!existing) {
+            throw new Error("Device is not paired");
+        }
+        const { onOffTimer: _removed, ...rest } = existing;
+        await this.store.setPairedDevice(id, rest);
+        const pushed = await this.pushOnOffTimerToDevice(id);
+        return { deviceId: id, onOffTimer: null, pushed };
+    }
     async pushOnOffTimerToDevice(deviceId) {
         const existing = await this.store.getPairedDevice(deviceId);
-        if (!existing?.onOffTimer)
+        if (!existing)
             return false;
         const ws = this.devices.get(deviceId);
         if (!ws || ws.readyState !== WebSocket.OPEN)
             return false;
         try {
-            const result = await this.sendCommandToSocket(ws, deviceId, "device.display.setOnOffTimer", { onOffTimer: existing.onOffTimer }, 15_000);
+            const result = await this.sendCommandToSocket(ws, deviceId, "device.display.setOnOffTimer", { onOffTimer: existing.onOffTimer ?? null }, 15_000);
             return result.status === "success" || result.status === "accepted";
         }
         catch (err) {
@@ -1178,8 +1196,14 @@ export class TomorrowOS extends EventEmitter {
                 const deviceId = decodeURIComponent(deviceOnOffTimer[1]);
                 const body = (await readJsonBody(req));
                 try {
-                    const result = await this.setDeviceOnOffTimer(deviceId, body.onOffTimer ?? body);
-                    sendJson(res, 200, { status: "success", ...result });
+                    if (body.clear === true || body.onOffTimer === null) {
+                        const result = await this.clearDeviceOnOffTimer(deviceId);
+                        sendJson(res, 200, { status: "success", ...result });
+                    }
+                    else {
+                        const result = await this.setDeviceOnOffTimer(deviceId, body.onOffTimer ?? body);
+                        sendJson(res, 200, { status: "success", ...result });
+                    }
                 }
                 catch (e) {
                     const msg = e instanceof Error ? e.message : "On/off timer failed";
@@ -1187,6 +1211,18 @@ export class TomorrowOS extends EventEmitter {
                 }
                 return;
             }
+            if (req.method === "DELETE" && deviceOnOffTimer) {
+                const deviceId = decodeURIComponent(deviceOnOffTimer[1]);
+                try {
+                    const result = await this.clearDeviceOnOffTimer(deviceId);
+                    sendJson(res, 200, { status: "success", ...result });
+                }
+                catch (e) {
+                    const msg = e instanceof Error ? e.message : "On/off timer clear failed";
+                    sendJson(res, 400, { status: "failed", error: msg });
+                }
+                return;
+            }
             if (req.method === "GET" && pathname === "/playlists") {
                 const playlists = await this.playlists.listPlaylists();
                 sendJson(res, 200, { status: "success", playlists });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tomorrowos/sdk",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "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",
@@ -20,6 +20,7 @@
     "README.md",
     "LLM_PROMPT.md",
     "REPLIT_SETUP.md",
+    "VERCEL_SETUP.md",
     "REPLIT_UPGRADE.md",
     "BUILD_GUARDRAILS.md",
     "PLAYER_INSTALL.md",

package/templates/cms-starter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-cms",
-  "version": "0.9.19",
+  "version": "0.9.21",
   "description": "CMS server on @tomorrowos/sdk. Add your UI (React, static files, etc.) alongside this server.",
   "private": true,
   "type": "module",
@@ -13,7 +13,7 @@
     "build-player": "tomorrowos build --platform tizen"
   },
   "dependencies": {
-    "@tomorrowos/sdk": "^0.9.19",
+    "@tomorrowos/sdk": "^0.9.21",
     "dotenv": "^17.2.3",
     "tsx": "^4.19.0"
   },

package/templates/cms-starter/public/index.html

@@ -187,6 +187,7 @@
         <h2>On / off timer</h2>
         <p class="hint" id="onOffTimerModalHint">
           Daily on/off times follow the device clock. Off blacks the screen; the player stays powered and connected to the CMS.
+          Removing the timer stops the schedule and leaves the screen in its current on or off state until you set a timer again.
         </p>
         <div class="on-off-timer-grid">
           <label class="field-label">
@@ -200,6 +201,7 @@
         </div>
         <div class="modal-actions">
           <button type="button" id="onOffTimerSaveBtn" class="primary">Save</button>
+          <button type="button" id="onOffTimerRemoveBtn" class="danger hidden">Remove timer</button>
           <button type="button" data-close-on-off-timer-modal="1">Cancel</button>
         </div>
       </div>

package/templates/cms-starter/public/methods.js

@@ -1084,6 +1084,67 @@ function appendDeviceMetaRow(meta, label, value) {
   meta.appendChild(row);
 }
 
+function hasConfiguredOnOffTimer(timer) {
+  return !!(
+    timer &&
+    typeof timer.turnOnAt === "string" &&
+    typeof timer.turnOffAt === "string" &&
+    timer.turnOnAt &&
+    timer.turnOffAt
+  );
+}
+
+function appendHardwareTimerStatusRow(meta, device) {
+  const timer = device.onOffTimer || null;
+  const configured = hasConfiguredOnOffTimer(timer);
+
+  const row = document.createElement("div");
+  row.className = "device-meta-row device-meta-row--timer-status";
+
+  const dt = document.createElement("dt");
+  dt.textContent = "Hardware timer status";
+
+  const dd = document.createElement("dd");
+  const statusWrap = document.createElement("span");
+  statusWrap.className = "hardware-timer-status";
+  statusWrap.tabIndex = 0;
+
+  const statusValue = document.createElement("span");
+  statusValue.className = configured
+    ? "hardware-timer-status__value hardware-timer-status__value--on"
+    : "hardware-timer-status__value hardware-timer-status__value--off";
+  statusValue.textContent = configured ? "On" : "Off";
+
+  const popup = document.createElement("span");
+  popup.className = "hardware-timer-status__popup";
+  popup.setAttribute("role", "tooltip");
+  if (configured) {
+    const onLine = document.createElement("div");
+    const onLabel = document.createElement("strong");
+    onLabel.textContent = "Turn on";
+    onLine.appendChild(onLabel);
+    onLine.appendChild(document.createTextNode(` ${timer.turnOnAt}`));
+
+    const offLine = document.createElement("div");
+    const offLabel = document.createElement("strong");
+    offLabel.textContent = "Turn off";
+    offLine.appendChild(offLabel);
+    offLine.appendChild(document.createTextNode(` ${timer.turnOffAt}`));
+
+    popup.appendChild(onLine);
+    popup.appendChild(offLine);
+  } else {
+    popup.textContent = "No timer configured";
+  }
+
+  statusWrap.appendChild(statusValue);
+  statusWrap.appendChild(popup);
+  dd.appendChild(statusWrap);
+  row.appendChild(dt);
+  row.appendChild(dd);
+  meta.appendChild(row);
+}
+
 function createDeviceScreenshotThumb(device) {
   const slot = document.createElement("div");
   slot.className = "device-screenshot-slot";
@@ -1250,6 +1311,7 @@ function renderDeviceCards() {
     for (const [label, value] of secondaryRows) {
       appendDeviceMetaRow(metaSecondary, label, value);
     }
+    appendHardwareTimerStatusRow(metaSecondary, device);
 
     metaBlock.appendChild(metaTop);
     metaBlock.appendChild(metaSecondary);
@@ -1833,11 +1895,17 @@ function openOnOffTimerModal(deviceId) {
   const modal = document.getElementById("onOffTimerModal");
   const onEl = document.getElementById("onOffTimerTurnOnAt");
   const offEl = document.getElementById("onOffTimerTurnOffAt");
+  const removeBtn = document.getElementById("onOffTimerRemoveBtn");
   if (!modal || !onEl || !offEl) return;
 
   const timer = device.onOffTimer || {};
+  const configured = hasConfiguredOnOffTimer(device.onOffTimer);
   onEl.value = normalizeTimeInputValue(timer.turnOnAt, "06:00");
   offEl.value = normalizeTimeInputValue(timer.turnOffAt, "18:00");
+  if (removeBtn) {
+    removeBtn.classList.toggle("hidden", !configured);
+    removeBtn.disabled = false;
+  }
   modal.classList.remove("hidden");
 }
 
@@ -1854,6 +1922,7 @@ async function saveOnOffTimerModal() {
   const onEl = document.getElementById("onOffTimerTurnOnAt");
   const offEl = document.getElementById("onOffTimerTurnOffAt");
   const saveBtn = document.getElementById("onOffTimerSaveBtn");
+  const removeBtn = document.getElementById("onOffTimerRemoveBtn");
   if (!onEl || !offEl) return;
 
   const onOffTimer = {
@@ -1867,6 +1936,7 @@ async function saveOnOffTimerModal() {
   }
 
   if (saveBtn) saveBtn.disabled = true;
+  if (removeBtn) removeBtn.disabled = true;
   try {
     const res = await fetch(`/device/${encodeURIComponent(deviceId)}/on-off-timer`, {
       method: "POST",
@@ -1885,6 +1955,43 @@ async function saveOnOffTimerModal() {
     alert(err?.message || "Could not save on/off timer");
   } finally {
     if (saveBtn) saveBtn.disabled = false;
+    if (removeBtn) removeBtn.disabled = false;
+  }
+}
+
+async function removeOnOffTimerModal() {
+  const deviceId = onOffTimerModalDeviceId;
+  if (!deviceId) return;
+
+  if (
+    !confirm(
+      "Remove the on/off timer? The screen will stay in its current on or off state until you set a timer again."
+    )
+  ) {
+    return;
+  }
+
+  const saveBtn = document.getElementById("onOffTimerSaveBtn");
+  const removeBtn = document.getElementById("onOffTimerRemoveBtn");
+  if (saveBtn) saveBtn.disabled = true;
+  if (removeBtn) removeBtn.disabled = true;
+  try {
+    const res = await fetch(`/device/${encodeURIComponent(deviceId)}/on-off-timer`, {
+      method: "DELETE"
+    });
+    const data = await res.json();
+    if (!res.ok || data.status === "failed") {
+      alert(data.error || "Could not remove on/off timer");
+      return;
+    }
+    showResult({ deviceId, onOffTimer: null, pushed: data.pushed });
+    closeOnOffTimerModal();
+    await fetchDevices();
+  } catch (err) {
+    alert(err?.message || "Could not remove on/off timer");
+  } finally {
+    if (saveBtn) saveBtn.disabled = false;
+    if (removeBtn) removeBtn.disabled = false;
   }
 }
 
@@ -2213,6 +2320,9 @@ document.addEventListener("DOMContentLoaded", () => {
   document
     .getElementById("onOffTimerSaveBtn")
     ?.addEventListener("click", () => void saveOnOffTimerModal());
+  document
+    .getElementById("onOffTimerRemoveBtn")
+    ?.addEventListener("click", () => void removeOnOffTimerModal());
   document.querySelectorAll("[data-close-download-failed-modal]").forEach((el) => {
     el.addEventListener("click", closeDownloadFailedModal);
   });

package/templates/cms-starter/public/panel.css

@@ -283,6 +283,7 @@ body {
   border-radius: 8px;
   padding: 0.85rem 0.95rem;
   background: #fafaf9;
+  overflow: visible;
 }
 
 .device-card-header {
@@ -439,6 +440,73 @@ body {
   display: block;
 }
 
+.device-meta-row--timer-status {
+  position: relative;
+}
+
+.hardware-timer-status {
+  position: relative;
+  display: inline-block;
+  cursor: default;
+  outline: none;
+}
+
+.hardware-timer-status__value--on {
+  color: #027a48;
+  font-weight: 600;
+}
+
+.hardware-timer-status__value--off {
+  color: #667085;
+  font-weight: 600;
+}
+
+.hardware-timer-status__popup {
+  position: absolute;
+  left: 0;
+  bottom: calc(100% + 0.45rem);
+  z-index: 20;
+  min-width: 9.5rem;
+  padding: 0.55rem 0.7rem;
+  border: 1px solid #e4e1dc;
+  border-radius: 6px;
+  background: #fff;
+  box-shadow: 0 6px 18px rgba(0, 0, 0, 0.12);
+  color: #333;
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.45;
+  white-space: nowrap;
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(4px);
+  transition: opacity 0.12s ease, transform 0.12s ease, visibility 0.12s;
+}
+
+.hardware-timer-status__popup::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 0.85rem;
+  border: 6px solid transparent;
+  border-top-color: #fff;
+  filter: drop-shadow(0 1px 0 #e4e1dc);
+}
+
+.hardware-timer-status__popup strong {
+  font-weight: 600;
+  color: #555;
+  margin-right: 0.35rem;
+}
+
+.hardware-timer-status:hover .hardware-timer-status__popup,
+.hardware-timer-status:focus-within .hardware-timer-status__popup {
+  opacity: 1;
+  visibility: visible;
+  transform: translateY(0);
+}
+
 .device-card-actions {
   display: flex;
   flex-wrap: wrap;