@trillboards/connect 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 1.0.0 (2026-02-19)
+
+Initial public release.
+
+### Features
+
+- **Device registration** — Automatic device fingerprinting (FNV-1a hash), registration via Partner API, and heartbeat loop with exponential backoff
+- **Ad auction** — Fetch ads by fingerprint, VAST XML parsing with media file/tracking extraction, and impression tracking via image beacons
+- **Ad rotation** — Configurable ad rotation manager with automatic cycling, video/image rendering, and completion callbacks
+- **Offline support** — IndexedDB-backed ad caching and impression queue with automatic sync on reconnect
+- **Branding** — Default CSS injection for ad containers with white-label custom CSS loading support
+- **Analytics** — Client-side event buffering with batch sending, `sendBeacon` on page unload, and visibility change tracking
+- **Socket.io integration** — Real-time commands (refresh ads, update config, force reload, content updates) via optional Socket.io connection
+- **Event system** — Full lifecycle events: `ready`, `device_registered`, `ad_start`, `ad_complete`, `impression`, `sync_complete`, `error`, and more

package/README.md

@@ -0,0 +1,122 @@
+# @trillboards/connect
+
+Zero-friction partner onboarding SDK for digital signage ad monetization. One `init()` call handles device registration, ad fetching, rendering, offline caching, and analytics.
+
+## Installation
+
+```bash
+npm install @trillboards/connect
+```
+
+Or via CDN:
+
+```html
+<script src="https://unpkg.com/@trillboards/connect/dist/trillboards-connect.global.js"></script>
+```
+
+## Quick Start
+
+```js
+const TrillboardsConnect = require('@trillboards/connect');
+// or: import TrillboardsConnect from '@trillboards/connect';
+
+const trillboards = TrillboardsConnect.init({
+  apiKey: 'trb_partner_xxx',
+  deviceId: 'my-screen-001',
+  containerId: 'ad-container',
+  options: {
+    heartbeatInterval: 60000,
+    adInterval: 60,
+    muted: true,
+    offlineCache: true,
+    analytics: true,
+  },
+});
+
+trillboards.on('ready', (data) => {
+  console.log('SDK ready:', data.fingerprint);
+});
+
+trillboards.on('ad_start', (data) => {
+  console.log('Ad started:', data.ad.id);
+});
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiKey` | `string` | *required* | Partner API key (`trb_partner_xxx`) |
+| `deviceId` | `string` | *required* | Unique device identifier |
+| `containerId` | `string \| HTMLElement` | `null` | DOM container for ad rendering |
+| `options.heartbeatInterval` | `number` | `60000` | Heartbeat interval in ms |
+| `options.adInterval` | `number` | `60` | Ad rotation interval in seconds |
+| `options.muted` | `boolean` | `true` | Start video ads muted |
+| `options.offlineCache` | `boolean` | `true` | Enable IndexedDB offline caching |
+| `options.analytics` | `boolean` | `true` | Enable analytics event buffering |
+| `options.deviceType` | `string` | `'digital_signage'` | Device type for registration |
+| `options.deviceName` | `string` | `'SDK Device: <deviceId>'` | Friendly device name |
+| `options.display` | `object` | auto-detected | Display specs `{ width, height }` |
+| `options.location` | `object` | `{}` | Location `{ lat, lng, address, venue_type }` |
+| `options.metadata` | `object` | `{}` | Custom metadata sent with registration |
+| `options.objectFit` | `string` | `'cover'` | CSS `object-fit` for ad rendering |
+
+## Events
+
+| Event | Data | Description |
+|-------|------|-------------|
+| `ready` | `{ deviceId, fingerprint, screenId, embedUrl }` | SDK fully initialized |
+| `device_registered` | `{ fingerprint, screen_id, embed_url }` | Device registered with API |
+| `device_status` | `{ from, to, deviceId }` | Device status changed |
+| `ad_start` | `{ ad, type, timestamp }` | Ad started rendering |
+| `ad_complete` | `{ ad, type, duration, completed }` | Ad finished rendering |
+| `ad_error` | `{ ad, type, error }` | Ad rendering error |
+| `impression` | `{ ad, result, totalImpressions }` | Impression tracked |
+| `heartbeat` | `{ beat, status, timestamp }` | Heartbeat sent |
+| `heartbeat_error` | `{ error, consecutiveFailures, willRetry }` | Heartbeat failed |
+| `sync_complete` | `{ total, synced, failed }` | Offline impressions synced |
+| `connectivity_change` | `{ online }` | Online/offline status changed |
+| `analytics_flush` | `{ flushed, errors }` | Analytics buffer flushed |
+| `socket_connected` | `{ socketId }` | Socket.io connected |
+| `socket_disconnected` | `{ reason }` | Socket.io disconnected |
+| `config_updated` | `{ config, source }` | Config updated via socket |
+| `error` | `{ phase, error, fatal? }` | General error |
+
+## API
+
+### `TrillboardsConnect.init(config)`
+
+Initialize the SDK. Returns a `ConnectInstance` that begins initialization asynchronously.
+
+### `TrillboardsConnect.create(config)`
+
+Create an uninitialized instance for advanced use cases. Call `instance.initialize()` manually.
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `on(event, callback)` | Register an event listener |
+| `off(event, callback)` | Remove an event listener |
+| `nextAd()` | Skip to the next ad |
+| `pause()` | Pause ad rotation |
+| `resume()` | Resume ad rotation |
+| `getState()` | Get complete SDK state |
+| `queueOfflineImpression(data)` | Queue an impression for offline sync |
+| `syncOffline()` | Force sync offline impressions |
+| `cacheAdsOffline(ads)` | Cache ads for offline playback |
+| `destroy()` | Clean up all resources |
+
+### Sub-Modules
+
+For advanced usage, sub-modules are exposed directly:
+
+- `TrillboardsConnect.device` — Registration, fingerprinting, heartbeat
+- `TrillboardsConnect.auction` — Ad fetching, rendering, VAST parsing
+- `TrillboardsConnect.offline` — IndexedDB caching and impression queue
+- `TrillboardsConnect.branding` — CSS injection and white-labeling
+- `TrillboardsConnect.analytics` — Event buffering and batch sending
+
+## License
+
+MIT