@telemetryos/sdk 1.0.0

package/README.md

@@ -0,0 +1,588 @@
+# TelemetryOS Applications SDK
+
+Welcome to the TelemetryOS Applications SDK! This document will guide you through building applications for TelemetryOS.
+
+## What is TelemetryOS?
+
+TelemetryOS is a platform for running web applications on devices connected to displays, such as TVs and touch screen kiosks. It can manage thousands of devices per account, enabling organizations to create, manage, and deploy dynamic content and interactive applications across their physical locations.
+
+Key features of the platform include:
+
+- Run single-page applications on display devices.
+- Support containers that run alongside applications.
+- Run worker scripts that operate continuously in the background.
+- Compose content with our Freeform Editor for visual layouts.
+- Support content playlists and scheduling.
+- Manage devices at scale.
+
+## Standard Applications in TelemetryOS
+
+Standard applications are web applications that run within TelemetryOS's Freeform Editor. The Freeform Editor is our default visual content composition tool that allows users to create layouts by positioning applications alongside media, text, and other visual elements.
+
+Your standard application will be embedded as an iframe within the Freeform Editor and can be positioned, resized, and scheduled as part of content playlists that display on physical devices like digital signage and kiosks.
+
+### Mount Points
+
+Standard applications define mount points in their `telemetry.config.json` file:
+
+- `settings` - The configuration interface that appears in the Freeform Editor's sidebar when your application is selected. This runs in the [administration UI][admin-ui] where customers configure your app.
+- `render` - The actual content that displays on devices and in the Freeform Editor's canvas. This is what end users see.
+
+And optionally a worker script:
+
+- `background` - A worker that runs continuously in the background, even when your application is not currently visible in the playlist rotation.
+
+### Integration with Freeform Editor
+
+Since your application runs within the Freeform Editor, you get additional capabilities:
+
+- **Control playlist navigation** - Move between playlist pages or modify page timing
+- **Trigger content overrides** - Display emergency alerts or priority content that interrupts the normal playlist flow  
+- **Communicate with other applications** - Discover and embed other applications within your own interface
+
+## Getting Started
+
+To get started, add the SDK to your project:
+
+### Installation
+
+With npm:
+
+```bash
+npm install @telemetryos/sdk
+```
+
+Or include it directly in your HTML:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@telemetryos/sdk"></script>
+```
+
+### Basic Configuration
+
+Import and configure the SDK with your application name:
+
+```javascript
+import { configure } from '@telemetryos/sdk';
+
+// Initialize the SDK - call this early in your application lifecycle
+// The application name must match the name in your telemetry.config.json
+configure('myAppName')
+```
+
+Or using the global object if you included the script directly:
+
+```javascript
+telemetry.configure('myAppName')
+```
+
+The SDK automatically extracts the application ID from URL parameters, which is essential for proper functioning of the store's local and deviceLocal scopes.
+
+## Core SDK Features
+
+### Storage API
+
+The SDK provides a powerful storage system with multiple scopes:
+
+- **Global** - Shared across all instances of your application within an account. Use for app-wide settings like branding or global configuration.
+- **Local** - Specific to this application instance (uses applicationId). Perfect for settings ↔ render communication since both mount points share the same instance.
+- **DeviceLocal** - Stored only on the current device, never synced across devices. Survives device restarts. Ideal for kiosk interactions or device-specific calibration.
+- **Shared** - Inter-application communication using namespace strings. Applications can coordinate by agreeing on namespace and key conventions.
+
+The `applicationId` is automatically provided when your application is embedded, ensuring that multiple instances of your app maintain separate configurations.
+
+Example usage:
+
+```javascript
+import { store } from '@telemetryos/sdk';
+
+// Global scope - shared across all instances of your app
+await store().global.set('companyBranding', { logo: 'url', colors: {...} });
+
+// Local scope - specific to this app instance
+await store().local.set('city', 'New York');
+
+// DeviceLocal scope - stays on this device only
+await store().deviceLocal.set('calibrationData', { brightness: 0.8 });
+
+// Shared scope - communicate with other applications
+await store().shared.set('weather-data', 'temperature', '72°F');
+
+// Subscribe to changes for real-time updates
+const cityHandler = (newCity) => {
+  console.log(`City updated to: ${newCity}`);
+  updateWeatherDisplay(newCity);
+};
+
+store().local.subscribe('city', cityHandler);
+
+// Clean up subscriptions when no longer needed
+store().local.unsubscribe('city', cityHandler);
+```
+
+Store subscriptions are essential for real-time applications. When a setting is changed (e.g., in the settings mount point), the render mount point will receive immediate updates through store subscriptions.
+
+### Application Discovery
+
+Applications can discover and embed other applications:
+
+```javascript
+import { applications } from '@telemetryos/sdk';
+
+// Find all applications with a specific mount point
+const widgets = await applications().getAllByMountPoint('dashboard-widget');
+
+// Get URL for embedding an application
+const url = await applications().getUrl('weather-app', 'render');
+
+// Use this URL in an iframe to embed the application
+const iframe = document.createElement('iframe');
+iframe.src = url;
+document.body.appendChild(iframe);
+```
+
+### Media Access
+
+Access media content uploaded to TelemetryOS:
+
+```javascript
+import { media } from '@telemetryos/sdk';
+
+// Get media folders by tag
+const folders = await media().getFoldersByTag('marketing');
+
+// Get content from a folder
+const content = await media().getMediaContentByFolderId(folderId);
+
+// Access the media file URLs
+const mediaItem = await media().getMediaContentById(mediaId);
+
+// Use this URL to display/play the media
+const publicUrl = mediaItem.publicUrls[0];
+```
+
+### Account and User Information
+
+Access information about the current account and user:
+
+```javascript
+import { accounts, users } from '@telemetryos/sdk';
+
+// Get current account
+const account = await accounts().getCurrent();
+
+// Get current user
+const userResult = await users().getCurrent();
+const userId = userResult.user.id;
+```
+
+### Playlist Control
+
+Control the Freeform Editor's playlist state, allowing your application to navigate through playlist pages and modify timing:
+
+```javascript
+import { playlist } from '@telemetryos/sdk';
+
+// Move to the next page in the playlist
+await playlist().nextPage();
+
+// Move to the previous page in the playlist  
+await playlist().previousPage();
+
+// Set the duration for the current page (in seconds)
+await playlist().setDuration(30);
+```
+
+### Content Overrides
+
+Manage content overrides within the Freeform Editor to temporarily display specific content:
+
+```javascript
+import { overrides } from '@telemetryos/sdk';
+
+// Set an override to display specific content
+await overrides().setOverride('emergency-alert');
+
+// Clear an existing override
+await overrides().clearOverride('emergency-alert');
+```
+
+## Communication Patterns
+
+The SDK uses a request-response pattern for most operations. All requests have a 30-second timeout by default to prevent hanging promises:
+
+```javascript
+try {
+  const result = await someAsyncSdkOperation();
+  // Handle successful result
+} catch (error) {
+  // Handle timeout or other errors
+  console.error('Operation failed:', error.message);
+}
+```
+
+## Offline Support
+
+Your applications automatically work offline without any additional code. TelemetryOS handles caching for you:
+
+- **Applications are cached locally** on devices for offline operation
+- **Store system works offline** - all data reads and writes continue normally, syncing when back online
+- **External API calls are cached** - HTTP requests to external services work offline using cached responses
+- **No configuration needed** - offline support is completely automatic
+
+This means users can interact with your application even when devices lose internet connectivity.
+
+## Advanced Features
+
+### Worker Scripts
+
+Worker scripts run in the background even when your application isn't currently visible in the playlist rotation. For standard applications, they start automatically when a playlist containing your application is loaded (on devices) or opened for editing (in the administration UI). Define them in your `telemetry.config.json`:
+
+```json
+{
+  "name": "my-application",
+  "version": "1.0.0",
+  "workers": [
+    {
+      "script": "./workers/background-sync.js"
+    }
+  ]
+}
+```
+
+Worker scripts can access the SDK by importing and configuring it just like the main application. They're ideal for:
+
+- Periodic data synchronization.
+- Processing background tasks.
+- Maintaining real-time connections.
+- Updating shared state even when the main app is not in view.
+
+### Containers
+
+Containers allow you to run more complex backend services alongside your application. They run in a local Docker instance, with traffic to specific hostnames automatically tunneled to the appropriate container.
+
+Define containers in your `telemetry.config.json`:
+
+```json
+{
+  "name": "my-application",
+  "version": "1.0.0",
+  "containers": [
+    {
+      "name": "my-backend",
+      "image": "mybackend:latest",
+      "port": 3000
+    }
+  ]
+}
+```
+
+Access the container from your application (containers only run on devices):
+
+```javascript
+// Container name becomes hostname - requests to my-backend are routed to your container
+fetch('https://my-backend/api/data')
+  .then(response => response.json())
+  .then(data => console.log(data));
+
+// Your app should handle cases where containers aren't available (e.g., in administration UI)
+```
+
+## `telemetry.config.json` Configuration
+
+Your application must include a `telemetry.config.json` file at the root level:
+
+```json
+{
+  "name": "my-application",
+  "version": "1.0.0",
+  "displayName": "My Application",
+  "description": "A TelemetryOS application that does amazing things",
+  "mountPoints": {
+    "render": {
+      "path": "/render"
+    },
+    "settings": {
+      "path": "/settings"
+    }
+  },
+  "workers": [
+    {
+      "name": "background",
+      "script": "./workers/background.js"
+    }
+  ],
+  "containers": []
+}
+```
+
+This configuration:
+
+1. Defines your application name and metadata
+2. Specifies mount points for different application contexts
+3. Configures background workers
+4. Sets up containers if needed
+
+## Best Practices
+
+1. **Store Usage**
+   - Use the appropriate store scope for your data
+   - Always subscribe to changes for real-time updates rather than polling
+   - Consider data persistence requirements when choosing a scope
+
+2. **Application Structure**
+   - Clearly separate your settings UI from your render UI using mount points
+   - Handle settings changes gracefully in the render view
+   - Consider using a state management library with the SDK for complex applications
+
+3. **Performance**
+   - Optimize your application for performance on TelemetryOS
+   - Use worker scripts for background tasks and to maintain state during playlist transitions
+   - Implement efficient rendering patterns to minimize resource usage
+
+4. **Error Handling**
+   - Implement robust error handling for all SDK operations
+   - Account for timeout scenarios (30-second default)
+   - Provide fallback content when network operations fail
+
+5. **Responsive Design**
+   - Design your application to adapt to different screen sizes and orientations
+   - Test your application on different device types
+   - Consider touch interaction for kiosk deployments
+
+## Development Workflow
+
+1. Develop and test your application locally
+2. Package your application with its config file
+3. Upload to TelemetryOS
+4. Add your application to a playlist
+5. Assign your playlist to one or more devices
+
+## Implementation Patterns and Examples
+
+This section provides structured examples of common implementation patterns to help you build effective TelemetryOS applications.
+
+### SDK Architecture Overview
+
+- **Core Communication**: The SDK uses the `postMessage` API for communication with TelemetryOS.
+- **Message Flow**: Messages flow between applications and TelemetryOS via the parent window.
+- **Resource APIs**: Domain-specific APIs (store, media, applications, etc.) are built on top of the core messaging APIs.
+- **Configuration Flow**: Applications must call `configure()` before using any SDK features.
+
+### Common Implementation Patterns
+
+#### 1. Fetching and Displaying Media
+
+```javascript
+import { media } from '@telemetryos/sdk';
+
+async function displayMedia(mediaId) {
+  const mediaItem = await media().getMediaContentById(mediaId);
+  const mediaElement = document.createElement('img');
+  mediaElement.src = mediaItem.publicUrls[0];
+  document.body.appendChild(mediaElement);
+}
+```
+
+#### 2. Settings Communication Between Mount Points
+
+```javascript
+import { store } from '@telemetryos/sdk';
+
+// In settings mount point
+async function saveSettings(city) {
+  await store().local.set('city', city);
+}
+
+// In render mount point
+function setupSettingsListener() {
+  store().local.subscribe('city', (city) => {
+    updateWeatherDisplay(city);
+  });
+  
+  // Initial load
+  store().local.get('city').then(city => {
+    if (city) updateWeatherDisplay(city);
+  });
+}
+```
+
+#### 3. Embedding Another Application
+
+```javascript
+import { applications } from '@telemetryos/sdk';
+
+async function embedWeatherWidget(containerId) {
+  const url = await applications().getUrl('weather-app', 'render');
+  const container = document.getElementById(containerId);
+  
+  const iframe = document.createElement('iframe');
+  iframe.src = url;
+  iframe.style.border = 'none';
+  iframe.style.width = '100%';
+  iframe.style.height = '100%';
+  
+  container.appendChild(iframe);
+}
+```
+
+#### 4. Implementing a Background Worker
+
+```javascript
+// In worker.js - defined in telemetry.config.json
+import { configure, store } from '@telemetryos/sdk';
+
+configure('myApp');
+
+// Run periodic synchronization
+async function syncData() {
+  try {
+    const data = await fetchExternalData();
+    await store().global.set('latestData', data);
+  } catch (error) {
+    console.error('Sync failed:', error);
+  }
+  
+  // Schedule next sync
+  setTimeout(syncData, 60000);
+}
+
+// Start sync process
+syncData();
+```
+
+#### 5. Robust Error Handling
+
+Always implement proper error handling for SDK operations:
+
+```javascript
+try {
+  const result = await media().getFoldersByTag('marketing');
+  displayFolders(result);
+} catch (error) {
+  // Check for timeout errors
+  if (error.message.includes('timed out')) {
+    showTimeoutMessage();
+  } else {
+    showGenericError();
+  }
+  
+  // Provide fallback content or retry strategy
+  displayCachedContent();
+}
+```
+
+### Complete Application Examples
+
+#### Weather Application
+
+```javascript
+// In settings.js (settings mount point)
+import { configure, store } from '@telemetryos/sdk';
+
+configure('weather-app');
+
+document.getElementById('cityForm').addEventListener('submit', async (e) => {
+  e.preventDefault();
+  const city = document.getElementById('cityInput').value;
+  await store().local.set('city', city);
+  showSuccessMessage('City saved successfully');
+});
+
+// Initial load of current value
+store().local.get('city').then(city => {
+  if (city) {
+    document.getElementById('cityInput').value = city;
+  }
+});
+```
+
+```javascript
+// In render.js (render mount point)
+import { configure, store } from '@telemetryos/sdk';
+
+configure('weather-app');
+
+// Subscribe to city changes
+store().local.subscribe('city', (city) => {
+  if (city) {
+    fetchAndDisplayWeather(city);
+  } else {
+    showConfigurationMessage();
+  }
+});
+
+// Initial load
+store().local.get('city').then(city => {
+  if (city) {
+    fetchAndDisplayWeather(city);
+  } else {
+    showConfigurationMessage();
+  }
+});
+
+async function fetchAndDisplayWeather(city) {
+  try {
+    const weather = await fetchWeatherData(city);
+    renderWeatherUI(weather);
+  } catch (error) {
+    showErrorMessage('Could not load weather data');
+  }
+}
+```
+
+#### Dashboard Container Application
+
+```javascript
+import { configure, applications } from '@telemetryos/sdk';
+
+configure('dashboard-app');
+
+async function initializeDashboard() {
+  try {
+    // Discover all dashboard widget applications
+    const widgets = await applications().getAllByMountPoint('dashboard-widget');
+    
+    if (widgets.length === 0) {
+      showNoWidgetsMessage();
+      return;
+    }
+    
+    const container = document.getElementById('widgetsContainer');
+    
+    // Create a grid layout for widgets
+    for (const widget of widgets) {
+      const widgetElement = document.createElement('div');
+      widgetElement.className = 'widget-container';
+      
+      // Get embeddable URL for this widget
+      const url = await applications().getUrl(widget.name, 'dashboard-widget');
+      
+      // Create and configure iframe
+      const iframe = document.createElement('iframe');
+      iframe.src = url;
+      iframe.title = widget.name;
+      iframe.frameBorder = '0';
+      iframe.style.width = '100%';
+      iframe.style.height = '100%';
+      
+      widgetElement.appendChild(iframe);
+      container.appendChild(widgetElement);
+    }
+  } catch (error) {
+    console.error('Failed to initialize dashboard:', error);
+    showErrorMessage();
+  }
+}
+
+// Initialize dashboard when DOM is ready
+document.addEventListener('DOMContentLoaded', initializeDashboard);
+```
+
+## Support and Resources
+
+For more information or support, please visit our documentation or contact our support team.
+
+Happy building!
+
+[admin-ui]: https://app.telemetryos.ai

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+import { Client as RootClient } from '@telemetryos/root-sdk';
+import { Overrides } from './overrides.js';
+import { Playlist } from './playlist.js';
+export declare class Client extends RootClient {
+    get playlist(): Playlist;
+    get overrides(): Overrides;
+}