@tomorrowos/sdk

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).

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.

For LLMs generating code with this package

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. Otherwise read LLM_PROMPT.md — five required questions before generating code
3. Read BUILD_GUARDRAILS.md — mandatory components every generated CMS must include
4. Read brand.schema.json — validated shape of brand.json
5. Run npx tomorrowos init (or copy templates/cms-starter/ from this package) — minimal CMS server seed
6. Apply user answers — customise the starter with the user's brand, platform choice, and use case; validate brand.json against brand.schema.json
7. 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.

For human developers

Install:

npm install @tomorrowos/sdk

Scaffold a new CMS project:

npx tomorrowos init
cd my-tomorrowos-cms
npm install
npm run dev

tomorrowos init creates data/tomorrowos.db with the TomorrowOS SQLite schema. The starter server uses that SQLite database by default, so pairings, playlists, and device assignments survive normal server restarts.

Replit guided setup

In Replit Agent, paste:

Follow @tomorrowos/sdk REPLIT_SETUP.md and set up my TomorrowOS CMS.
Ask me the questions in order. Do not skip steps.

That wizard chooses SQLite (≤5 screens) or Supabase (>5), prefers Cloudinary for media, and writes brand.json from your answers. On Replit, Supabase must use Secret SUPABASE_URL (not the reserved DATABASE_URL).

To switch to Supabase/Postgres manually, edit .env / Secrets:

TOMORROWOS_STORE=supabase
SUPABASE_URL=postgresql://...
DATABASE_SSL=true
# DATABASE_URL=...   # optional fallback outside Replit

For throwaway demos/tests, set TOMORROWOS_STORE=memory. The generated starter includes its own README.md beside server.ts with database selection, migration, and custom TomorrowOSStore examples.

Migrate database records between supported stores:

npx tomorrowos migrate \
  --from sqlite \
  --from-sqlite ./data/tomorrowos.db \
  --to supabase \
  --to-database-url "$DATABASE_URL"

The migrate command supports sqlite, postgres, and supabase in either direction. It migrates TomorrowOS database records only; copy public/uploads or object-storage media separately.

Build a player (placeholder in current SDK — see PLAYER_INSTALL.md for platform tooling):

npx tomorrowos build --platform tizen

Quick architecture

  ┌─────────────────┐         WebSocket         ┌─────────────────┐
  │  Your CMS       │ ◄────────────────────────►│  TomorrowOS     │
  │  (your server)  │                           │  Player on      │
  │                 │                           │  screen         │
  │  imports        │                           │                 │
  │  @tomorrowos    │                           │  unified API    │
  │  /sdk           │                           │  across OSes    │
  └─────────────────┘                           └─────────────────┘

TomorrowOS has no required cloud service. Your CMS talks to your screens over your network.

Player branding: GET /brand.json returns the brand object passed to new TomorrowOS({ brand }) (same host/port as listen). TomorrowOS players can fetch it to apply backgroundColor, logos, etc., without a separate static file server.

Content policy (device.content.setPolicy): POST /device/{deviceId}/content/set-policy with { "policy": { "playlists": [...], "fallback": { "type": "brand" } } }. Each playlist may include optional schedule (device local time):

| Field | Format | Notes | |-------|--------|--------| | startDate / endDate | YYYY-MM-DD | Inclusive calendar range; omit either for open-ended | | daysOfWeek | [0–6] | 0 = Sunday … 6 = Saturday | | start / end | HH:MM | Daily window; supports overnight (e.g. 22:00–06:00) |

All provided constraints must match for the playlist to play. See templates/cms-starter/policy.example.json.

Supported platforms (roadmap)

| Platform | Status | Player format | |-------------------|------------|---------------| | Samsung Tizen | V1 target | .wgt | | BrightSign | V1 target | autorun zip | | Others | See docs | varies |

See PLAYER_INSTALL.md for installation notes.

Documentation in this package

| File | Purpose | |------|---------| | LLM_PROMPT.md | Five-question elicitation for LLMs | | BUILD_GUARDRAILS.md | Mandatory CMS components | | PLAYER_INSTALL.md | Player build / install / pairing | | brand.schema.json | JSON Schema for brand.json | | brand.example.json | Full example brand.json | | templates/cms-starter/ | Minimal Node + TypeScript server seed | | templates/cms-starter/policy.example.json | Example setPolicy payload with date schedule | | templates/style-tokens/ | CSS tokens and UI pattern notes |

License

Apache 2.0.

Protocol version

Wire protocol 1.0 (see TomorrowOS specification).