@trillboards/ads-sdk 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to `@trillboards/ads-sdk` will be documented in this file.
+
+## [2.0.0] - 2026-02-14
+
+### Breaking Changes
+- Singleton pattern via `TrillboardsAds.create()` factory -- `init()` is now private
+- All events require typed listeners matching `EventMap`
+
+### Features
+- **Circuit breaker**: Automatic failure detection with configurable thresholds and half-open recovery
+- **Waterfall engine**: Three modes -- `programmatic_only`, `programmatic_then_direct`, `direct_only`
+- **Telemetry**: Real-time fill rate, no-fill, timeout, and error rate tracking
+- **React bindings**: `TrillboardsProvider`, `TrillboardsAdSlot`, `useTrillboardsAds`, `useAdEvents`
+- **React Native bindings**: `TrillboardsWebView` with ref handle, `useTrillboardsNative` hook
+- **Server bindings**: `PartnerClient` with `AudienceClient`, `AnalyticsClient`, `AuctionClient`, `CreativeClient`, `VastTagBuilder`, `TrackingBatch`
+- **NativeBridge**: 10 platform types -- Android, Android-alt, iOS, React Native, Flutter, CTV, Electron, Tauri, postMessage, custom
+- **IndexedDB caching**: Offline ad storage with automatic eviction
+- **IIFE build**: Direct `<script>` tag support via `trillboards-ads.iife.js`
+- **`createAuthenticatedFetch`**: Reusable authenticated HTTP client factory
+- **`once()` on EventEmitter**: One-shot event listener support
+
+### Fixes
+- Double-callback guard in impression tracking
+- React Strict Mode compatibility (proper cleanup in useEffect)
+- WebView XSS prevention in NativeBridge message handling
+- Memory leak in event listeners on destroy
+- `isOffline` state getting stuck after reconnection
+- BidCollector CPM normalization for multi-source auctions
+- Half-open circuit breaker state transition logic
+
+## [1.0.0] - 2026-01-15
+
+### Features
+- Initial release
+- Core ad player with VAST support
+- Basic impression tracking
+- IndexedDB offline caching

package/README.md

@@ -0,0 +1,158 @@
+# @trillboards/ads-sdk
+
+[![npm version](https://img.shields.io/npm/v/@trillboards/ads-sdk.svg)](https://www.npmjs.com/package/@trillboards/ads-sdk)
+[![license](https://img.shields.io/npm/l/@trillboards/ads-sdk.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+
+Programmatic infrastructure as a service for digital signage -- client, React, React Native, and server bindings.
+
+## Installation
+
+```bash
+npm install @trillboards/ads-sdk
+```
+
+## Quick Start
+
+### Browser (core)
+
+```typescript
+import { TrillboardsAds } from '@trillboards/ads-sdk';
+
+const sdk = await TrillboardsAds.create({ deviceId: 'your-device-id' });
+sdk.on('ad_started', (data) => console.log('Ad playing:', data.id));
+sdk.show();
+```
+
+### React
+
+```tsx
+import { TrillboardsProvider, TrillboardsAdSlot, useTrillboardsAds } from '@trillboards/ads-sdk/react';
+
+function App() {
+  return (
+    <TrillboardsProvider config={{ deviceId: 'your-device-id' }}>
+      <TrillboardsAdSlot style={{ width: '100%', height: '100%' }} />
+    </TrillboardsProvider>
+  );
+}
+```
+
+### React Native
+
+```tsx
+import { TrillboardsWebView, useTrillboardsNative } from '@trillboards/ads-sdk/react-native';
+
+function AdScreen() {
+  return <TrillboardsWebView config={{ deviceId: 'your-device-id' }} />;
+}
+```
+
+### Server (Node.js)
+
+```typescript
+import { PartnerClient } from '@trillboards/ads-sdk/server';
+
+const client = new PartnerClient({ apiKey: 'trb_partner_xxx' });
+const audience = await client.audience.getLive('screen-id');
+const analytics = await client.analytics.getScreenDaily('screen-id', {
+  startDate: '2026-02-01',
+  endDate: '2026-02-14',
+});
+```
+
+## Configuration
+
+The `TrillboardsConfig` interface accepts the following options:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `deviceId` | `string` | required | Device fingerprint |
+| `apiBase` | `string` | `https://api.trillboards.com/v1/partner` | API base URL |
+| `cdnBase` | `string` | `https://cdn.trillboards.com` | CDN base URL |
+| `waterfall` | `WaterfallMode` | `'programmatic_only'` | Ad source priority |
+| `autoStart` | `boolean` | `true` | Start playing on init |
+| `refreshInterval` | `number` | `120000` | Ad refresh interval (ms) |
+| `cacheSize` | `number` | `10` | Max cached ads |
+
+## Events
+
+The SDK emits typed events via the `EventMap` interface. Subscribe with `sdk.on(event, listener)` or `sdk.once(event, listener)`.
+
+| Event | Description |
+|-------|-------------|
+| `initialized` | SDK has completed initialization |
+| `ads_refreshed` | New ads fetched and ready |
+| `ad_started` | An ad has started playing |
+| `ad_ended` | An ad has finished playing |
+| `ad_error` | An error occurred during ad playback |
+| `programmatic_started` | A programmatic ad has started |
+| `programmatic_ended` | A programmatic ad has ended |
+| `impression_tracked` | An impression was successfully reported |
+| `state_changed` | The SDK state machine transitioned |
+| `offline` | Network connectivity lost |
+| `online` | Network connectivity restored |
+
+## Architecture
+
+The SDK is organized around four entry points, each targeting a different runtime:
+
+- **Core browser** (`@trillboards/ads-sdk`) -- Full ad player with VAST support, waterfall engine, and telemetry. Works in any browser environment.
+- **React** (`@trillboards/ads-sdk/react`) -- Context provider, ad slot component, and hooks (`useTrillboardsAds`, `useAdEvents`) for React 17+ applications.
+- **React Native** (`@trillboards/ads-sdk/react-native`) -- WebView-based player with native bridge communication and a `useTrillboardsNative` hook.
+- **Server** (`@trillboards/ads-sdk/server`) -- Node.js `PartnerClient` for audience data, analytics, auctions, creatives, VAST tag building, and batch tracking.
+
+### Key internals
+
+- **IIFE build**: A `trillboards-ads.iife.js` bundle is produced for direct `<script>` tag usage without a bundler.
+- **Waterfall engine**: Three modes control ad source priority -- `programmatic_only`, `programmatic_then_direct`, and `direct_only`.
+- **Circuit breaker**: Automatic failure detection with configurable thresholds and half-open recovery to avoid hammering failing endpoints.
+- **Telemetry**: Real-time tracking of fill rate, no-fill, timeout, and error rates reported back to the platform.
+- **IndexedDB caching**: Ads are cached offline in IndexedDB with automatic eviction based on `cacheSize`.
+- **NativeBridge**: Supports 10 platform types -- Android, Android-alt, iOS, React Native, Flutter, CTV, Electron, Tauri, postMessage, and custom.
+
+## Server Sub-Clients
+
+The `PartnerClient` exposes domain-specific sub-clients:
+
+| Sub-client | Description |
+|------------|-------------|
+| `client.audience` | Live audience data, predictions, lookalike screens |
+| `client.analytics` | Daily screen analytics, earnings data |
+| `client.auctions` | Programmatic auction results |
+| `client.creatives` | Creative review, moderation stats |
+| `client.createVastTagBuilder()` | Build VAST tags with targeting parameters |
+| `client.createTrackingBatch()` | Batch impression reporting |
+
+### Example: VAST tag builder
+
+```typescript
+const vastBuilder = client.createVastTagBuilder();
+const tag = await vastBuilder.buildTag({
+  deviceId: 'device-001',
+  width: 1920,
+  height: 1080,
+  orientation: 'landscape',
+});
+console.log('VAST URL:', tag.url);
+```
+
+### Example: Batch tracking
+
+```typescript
+const tracker = client.createTrackingBatch();
+const result = await tracker.report([
+  { adId: 'ad-1', impressionId: 'imp-1', deviceId: 'dev-1', duration: 15, completed: true, timestamp: new Date().toISOString() },
+  { adId: 'ad-2', impressionId: 'imp-2', deviceId: 'dev-1', duration: 30, completed: true, timestamp: new Date().toISOString() },
+]);
+console.log('Tracked:', result.tracked);
+```
+
+## Links
+
+- [Developer documentation](https://trillboards.com/developers/partner-sdk)
+- [API reference](https://api.trillboards.com/docs/partner)
+
+## License
+
+MIT