@tomorrowos/sdk 0.9.67 → 0.9.69

package/README.md

@@ -6,9 +6,9 @@
 
 Build and own your digital signage CMS.
 
-An open-source SDK and player runtime for digital signage. One server-side API drives commercial signage panels — you write the CMS, we handle device sessions, pairing, and the wire protocol.
+An open-source SDK and player runtime for digital signage. One server-side API drives commercial signage panels �?you write the CMS, we handle device sessions, pairing, and the wire protocol.
 
-Apache 2.0. Build a proprietary CMS on top of it and sell it as your own — no royalty, no permission needed.
+Apache 2.0. Build a proprietary CMS on top of it and sell it as your own �?no royalty, no permission needed.
 
 ---
 
@@ -19,7 +19,7 @@ Apache 2.0. Build a proprietary CMS on top of it and sell it as your own — no
 | Node.js | **18** or newer (`engines.node` in this package) |
 | npm | 9 or newer (or a compatible client) |
 | OS | macOS, Linux, Windows (WSL2 recommended on Windows) |
-| Network | CMS host reachable from your screens — a public HTTPS address in production |
+| Network | CMS host reachable from your screens �?a public HTTPS address in production |
 
 Screens connect to your CMS over the network. For real panels, deploy to a public host (Railway, Render, Fly, Vercel Fluid, Replit, your own server), or use a tunnel while developing locally.
 
@@ -52,7 +52,7 @@ Guided setup is supported for **Replit** and **Vercel / v0** only. **Replit is r
 
 The SDK ships an elicitation protocol so the agent asks the right questions before it writes anything. Skipping it reliably produces a CMS that doesn't run.
 
-### Replit (recommended) — use Power agent mode
+### Replit (recommended) �?use Power agent mode
 
 Paste into Replit **Power**:
 
@@ -70,31 +70,15 @@ Follow NPM package @tomorrowos/sdk REPLIT_UPGRADE.md to upgrade my CMS with the
 
 That protocol diffs and merges against the current templates. It must never run `init --force` or delete `data/` or `public/uploads/`.
 
-### Vercel / v0 — use v0 Max
+### Vercel / v0 �?use v0 Max
 
 Paste into **v0 Max** (or Vercel Agent with Max capability):
 
 ```text
-Follow @tomorrowos/sdk (an NPM package) VERCEL_SETUP.md and set up my TomorrowOS CMS from scratch.
-
-Open VERCEL_QUESTIONS.md first.
-For Q1, Q2, Q3: paste each question block VERBATIM. Do not rephrase options.
-For Q3: DO NOT ask a branding choice. Open one form with ALL SEVEN optional inputs at once, then HARD STOP and WAIT for my submit or "skip". Never auto-continue with defaults without my reply. Never only Name + Primary colour. Logo = Upload above Logo URL.
-After Q1 database choice, YOU set TOMORROWOS_STORE and DATABASE_SSL. Do not ask me to fill those.
-After Q2 media storage choice, YOU set TOMORROWOS_MEDIA. Do not ask me to fill those.
-Run: npx @tomorrowos/sdk@latest init . --hosting v0 --force
-Keep cms-starter-v0 layout.
-Apply the NON-NEGOTIABLE VERCEL RUNTIME CONTRACT exactly:
-one TomorrowOS instance only
-never create a second TomorrowOS in api/ws.ts
-never use public/ as Vercel Output Directory
-Preview Next only under preview/
-Publish must be the Fluid Function
-after deploy verify: GET /status → JSON, GET / → Control Panel, WebSocket on / or /api → 101
-pair devices against the Production URL only
+Follow NPM package @tomorrowos/sdk VERCEL_SETUP.md and set up my TomorrowOS CMS.
 ```
 
-Agents must paste questions from [`VERCEL_QUESTIONS.md`](./VERCEL_QUESTIONS.md) verbatim. Q1/Q2 are choice questions; **Q3 is a form only** — open **all seven** optional inputs at once, then **wait** for submit or `"skip"` (never auto-skip because fields are optional; never a branding choice first; never only Name + Primary colour). Logo = Upload above Logo URL. WebSockets require Fluid compute. The agent sets `cms.hostingTarget` to `"vercel"`.
+Agents must paste questions from [`VERCEL_QUESTIONS.md`](./VERCEL_QUESTIONS.md) verbatim.
 
 Upgrading an existing Vercel / v0 CMS instead:
 
@@ -115,7 +99,7 @@ Supported hosts: **Replit** and **Vercel / v0**. Prefer **Replit Power agent mod
 4. Scaffold with the correct template (**always `@latest`**):
    - Replit / self-host style: `npx @tomorrowos/sdk@latest init .` (default `cms-starter`)
    - Vercel / v0: `npx @tomorrowos/sdk@latest init . --hosting v0 --force` (`cms-starter-v0`)
-5. Apply the user’s answers — brand and use case. Validate `brand.json`. On Vercel, apply the **NON-NEGOTIABLE VERCEL RUNTIME CONTRACT** from `VERCEL_SETUP.md`.
+5. Apply the user’s answers �?brand and use case. Validate `brand.json`. On Vercel, apply the **NON-NEGOTIABLE VERCEL RUNTIME CONTRACT** from `VERCEL_SETUP.md`.
 6. Point the user at `PLAYER_INSTALL.md` and the Control Panel **Download Players** UI once the CMS is running.
 
 Do not write WebSocket transport, pairing wire format, or platform-specific player bridge code. The SDK handles server-side device sessions and HTTP helpers. Customise the UI, the branding, and how you call the SDK.
@@ -155,7 +139,7 @@ npm run dev
 | **Railway** | Simple Node deploy; good default for self-built CMS |
 | **Render** | Web Service with persistent process |
 | **Fly.io** | Global edge VMs; hold WebSockets cleanly |
-| **Replit** | Fastest AI-assisted path — see [Build with an AI tool](#1-build-with-an-ai-tool) |
+| **Replit** | Fastest AI-assisted path �?see [Build with an AI tool](#1-build-with-an-ai-tool) |
 | **Vercel Fluid** | Use `--hosting v0` and follow [`VERCEL_SETUP.md`](./VERCEL_SETUP.md) |
 
 Avoid classic short-lived serverless without WebSocket support.
@@ -166,7 +150,7 @@ You now have a CMS serving:
 - `GET /brand.json` for player branding
 - a WebSocket device channel
 - media upload helpers (`/media/upload`, and Cloudinary direct upload when configured)
-- `GET /players/brightsign.zip` — BrightSign package with `config.js` `cmsEndpoint` set to this CMS origin
+- `GET /players/brightsign.zip` �?BrightSign package with `config.js` `cmsEndpoint` set to this CMS origin
 - a minimal admin panel (static UI under `staticRoot`)
 
 Deploy it to a public HTTPS address before pairing a production screen. While developing locally, a tunnel is the fastest way to get one.
@@ -204,10 +188,10 @@ What you keep from your app: your auth, your users, your tenancy model, your UI.
 
 Points to plan for:
 
-- **Multi-tenancy.** Devices belong to whatever tenant model you already have. The SDK does not impose one — map device IDs to your own tenant records.
+- **Multi-tenancy.** Devices belong to whatever tenant model you already have. The SDK does not impose one �?map device IDs to your own tenant records.
 - **Auth.** Pairing is a device-side flow. Your admin routes stay behind your existing auth.
 - **Store.** Use `createTomorrowOSStore` / `TOMORROWOS_STORE` for SQLite, Postgres, or Supabase, or pass a custom `TomorrowOSStore`.
-- **WebSockets.** Your host must hold long-lived connections. Most serverless platforms terminate idle sockets — check before you commit (Vercel needs Fluid compute).
+- **WebSockets.** Your host must hold long-lived connections. Most serverless platforms terminate idle sockets �?check before you commit (Vercel needs Fluid compute).
 
 **Next:** [Connect a screen](#connect-a-screen).
 
@@ -216,19 +200,19 @@ Points to plan for:
 ## Architecture
 
 ```
-  ┌─────────────────┐         WebSocket         ┌─────────────────┐
-  │  Your CMS       │ ◄────────────────────────►│  TomorrowOS     │
-  │  (your server)  │                           │  Player on      │
-  │                 │                           │  screen         │
-  │  imports        │                           │                 │
-  │  @tomorrowos    │                           │  unified API    │
-  │  /sdk           │                           │  across panels  │
-  └─────────────────┘                           └─────────────────┘
+  ┌─────────────────�?        WebSocket         ┌─────────────────�?
+  �? Your CMS       �?◄────────────────────────►│  TomorrowOS     �?
+  �? (your server)  �?                          �? Player on      �?
+  �?                �?                          �? screen         �?
+  �? imports        �?                          �?                �?
+  �? @tomorrowos    �?                          �? unified API    �?
+  �? /sdk           �?                          �? across panels  �?
+  └─────────────────�?                          └─────────────────�?
 ```
 
 You own the CMS: the UI, the branding, the business logic, the data. The SDK owns the device session, the pairing handshake, and the wire protocol.
 
-You should not need to write WebSocket transport, pairing wire format, or platform-specific player bridge code. If you find yourself doing that, open an issue — it means the SDK has a gap.
+You should not need to write WebSocket transport, pairing wire format, or platform-specific player bridge code. If you find yourself doing that, open an issue �?it means the SDK has a gap.
 
 ---
 
@@ -238,7 +222,7 @@ Your CMS is running. This is what happens next, in order.
 
 1. **Deploy the CMS to a public HTTPS address** (or tunnel for local tests). Screens must reach it from their network.
 2. **Get a player package** for your platform (see below and [`PLAYER_INSTALL.md`](./PLAYER_INSTALL.md)).  
-   Note: `npx tomorrowos build --platform …` is still a **placeholder** in this package — packaging lives in the player repos / prebuilt downloads, not in the CLI yet.
+   Note: `npx tomorrowos build --platform …` is still a **placeholder** in this package �?packaging lives in the player repos / prebuilt downloads, not in the CLI yet.
 3. **Install the player on the panel.**
 4. **Pair.** The player shows a 6-character code. Enter it in the Control Panel. The device appears in your device list.
 5. **Publish content.** Assign playlists / push a content policy. The screen updates without reloading the app.
@@ -247,9 +231,9 @@ Your CMS is running. This is what happens next, in order.
 
 Supported target: **Tizen 6.5+** commercial displays (see Control Panel captions and [`PLAYER_INSTALL.md`](./PLAYER_INSTALL.md)).
 
-**Fastest path for many setups — URL Launcher / prebuilt package**
+**Fastest path for many setups �?URL Launcher / prebuilt package**
 
-- From a running Control Panel, use **Download Players → Samsung**, or fetch the published Tizen package from TomorrowOS distribution (`https://tmr.sh/app/tizen/…`).
+- From a running Control Panel, use **Download Players �?Samsung**, or fetch the published Tizen package from TomorrowOS distribution (`https://tmr.sh/app/tizen/…`).
 - Or host / sideload a `.wgt` as described in [`PLAYER_INSTALL.md`](./PLAYER_INSTALL.md).
 
 On the panel, enter the CMS HTTPS URL (or the player package URL your install path requires). The player shows a pairing code.
@@ -262,7 +246,7 @@ Supported target: **Series 5 / 6** (as labeled in the Control Panel). Older seri
 
 **Recommended download path**
 
-1. Open your live CMS Control Panel → **Download Players → BrightSign**.
+1. Open your live CMS Control Panel �?**Download Players �?BrightSign**.
 2. That hits `GET /players/brightsign.zip` on *this* CMS.
 3. The SDK fetches the mother zip and rewrites `config.js` so:
 
@@ -281,7 +265,7 @@ Override the mother zip URL with `TOMORROWOS_BRIGHTSIGN_ZIP_URL` if you host you
 
 Android, LG webOS, and Windows are on the roadmap. They are not validated for production in this SDK release.
 
-If you are building for one of those platforms later: build your CMS against the same server API now. Server-side code does not need to change when a new player package lands — only the installable player does.
+If you are building for one of those platforms later: build your CMS against the same server API now. Server-side code does not need to change when a new player package lands �?only the installable player does.
 
 ---
 
@@ -289,12 +273,12 @@ If you are building for one of those platforms later: build your CMS against the
 
 | Platform | Status | Install |
 |---|---|---|
-| Samsung Tizen 6.5+ | V1 supported | Control Panel download / `.wgt` / URL Launcher — see `PLAYER_INSTALL.md` |
-| BrightSign Series 5, 6 | V1 supported | Control Panel `GET /players/brightsign.zip` → microSD autorun |
+| Samsung Tizen 6.5+ | V1 supported | Control Panel download / `.wgt` / URL Launcher �?see `PLAYER_INSTALL.md` |
+| BrightSign Series 5, 6 | V1 supported | Control Panel `GET /players/brightsign.zip` �?microSD autorun |
 | BrightSign older series | Validate on hardware | Same autorun zip flow |
-| Android | Roadmap | — |
-| LG webOS | Roadmap | — |
-| Windows | Roadmap | — |
+| Android | Roadmap | �?|
+| LG webOS | Roadmap | �?|
+| Windows | Roadmap | �?|
 
 Treat a platform as production-ready only after you have validated it on your panels.
 
@@ -315,7 +299,7 @@ DATABASE_SSL=true
 
 Supported store drivers: `sqlite`, `postgres`, `supabase`, `memory`.
 
-Use `memory` for throwaway demos only — nothing survives a restart.
+Use `memory` for throwaway demos only �?nothing survives a restart.
 
 ### Migrating between stores
 
@@ -327,13 +311,14 @@ npx tomorrowos migrate \
   --to-database-url "$DATABASE_URL"
 ```
 
-Works in either direction across `sqlite`, `postgres`, and `supabase`. It moves database records only — copy `public/uploads` or object-storage / Cloudinary media separately.
+Works in either direction across `sqlite`, `postgres`, and `supabase`. It moves database records only �?copy `public/uploads` or object-storage / Cloudinary media separately.
 
 ### Media
 
-- **Local disk:** small files may use `POST /media/upload`. Larger files use **chunked upload** (`/media/upload-init` → `/media/upload-chunk` → `/media/upload-complete`).
+- **Local disk:** small files may use `POST /media/upload`. Larger files use **chunked upload** (`/media/upload-init` �?`/media/upload-chunk` �?`/media/upload-complete`).
 - **Replit Object Storage:** set `TOMORROWOS_MEDIA=replit-object-storage` (auto-preferred on Replit when Cloudinary is unset). Uses `@replit/object-storage`; URLs stay `/uploads/...` and are served from the bucket after Republish. Same upload HTTP routes as local.
-- **Cloudinary:** set `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET` (optional `CLOUDINARY_FOLDER`). The Control Panel uses **browser → Cloudinary** direct upload (`/media/upload-sign` + `/media/register`) when Cloudinary is configured.
+- **Cloudinary:** set `CLOUDINARY_CLOUD_NAME`, `CLOUDINARY_API_KEY`, `CLOUDINARY_API_SECRET` (optional `CLOUDINARY_FOLDER`). The Control Panel uses **browser �?Cloudinary** direct upload (`/media/upload-sign` + `/media/register`) when Cloudinary is configured.
+- **Vercel Blob:** set `BLOB_READ_WRITE_TOKEN` and `TOMORROWOS_MEDIA=vercel-blob` (token alone also auto-enables Blob when Cloudinary is unset). SDK uploads via `@vercel/blob` `put()`; asset URLs are absolute `https://*.public.blob.vercel-storage.com/...`.
 
 Cloudinary account plans still enforce their own max file sizes (for example Free plan video caps).
 
@@ -366,7 +351,7 @@ POST /device/{deviceId}/content/set-policy
 
 Each playlist may include optional `schedule`, evaluated in **device local time**. The run window is **one continuous period**:
 
-**from** `startDate` + `start` **→ until** `endDate` + `end` (until is exclusive).
+**from** `startDate` + `start` **�?until** `endDate` + `end` (until is exclusive).
 
 | Field | Format | Notes |
 |---|---|---|
@@ -386,16 +371,16 @@ The player must reach your CMS. Confirm a public HTTPS (or reachable tunnel) URL
 Common causes: media the player cannot decode (codec / profile / unexpected tracks), or HTML video surface alpha / HTML widget timing in `autorun.brs`. Re-encode to a supported profile and confirm `config.js` points at the correct CMS. Check player logs on the device.
 
 **Paired, but the screen is black (other).**  
-Fetch `GET /brand.json` from the panel’s network. A live WebSocket with a black screen usually means no playable policy item — check published playlists, absolute media URLs, and fallback.
+Fetch `GET /brand.json` from the panel’s network. A live WebSocket with a black screen usually means no playable policy item �?check published playlists, absolute media URLs, and fallback.
 
 **Media 404s on the screen but loads in your browser.**  
 Policy URLs must be absolute and reachable from the screen. Relative paths or hosts only visible on your laptop will fail on the panel.
 
 **Upload fails with HTTP 413 on Replit (or similar hosts).**  
-Use `@tomorrowos/sdk` Control Panel / templates: non-Cloudinary uploads over ~2MB go through **chunked** `/media/upload-chunk`. On Replit, set `TOMORROWOS_MEDIA=replit-object-storage` (or rely on auto-detect) so files land in App Storage. With Cloudinary configured, the panel uses browser direct upload instead.
+Use `@tomorrowos/sdk` Control Panel / templates: non-Cloudinary uploads over ~2MB go through **chunked** `/media/upload-chunk`. On Replit, set `TOMORROWOS_MEDIA=replit-object-storage` (or rely on auto-detect) so files land in App Storage. On Vercel Blob, set `TOMORROWOS_MEDIA=vercel-blob` + `BLOB_READ_WRITE_TOKEN` so proxy/chunked complete stores absolute Blob URLs. With Cloudinary configured, the panel uses browser direct upload instead.
 
 **BrightSign zip has empty `cmsEndpoint`.**  
-You downloaded the mother zip from a static CDN instead of **this** CMS’s `/players/brightsign.zip`. Use Control Panel → Download Players → BrightSign on the deployed CMS.
+You downloaded the mother zip from a static CDN instead of **this** CMS’s `/players/brightsign.zip`. Use Control Panel �?Download Players �?BrightSign on the deployed CMS.
 
 **WebSocket disconnects on a serverless host.**  
 Most serverless platforms terminate idle connections. Vercel requires Fluid compute. Prefer a long-lived Node host (Railway, Render, Fly, Replit) if your platform cannot hold sockets.
@@ -410,7 +395,7 @@ You are probably on `TOMORROWOS_STORE=memory`. Switch to `sqlite` or Postgres/Su
 - **Package docs:** the Markdown files listed below ship inside `@tomorrowos/sdk`
 - **npm:** [https://www.npmjs.com/package/@tomorrowos/sdk](https://www.npmjs.com/package/@tomorrowos/sdk)
 
-If something in this README doesn't match what the package actually does, treat that as a bug and report it — documentation drift matters as much as a code defect.
+If something in this README doesn't match what the package actually does, treat that as a bug and report it �?documentation drift matters as much as a code defect.
 
 ---