@telemetryos/root-sdk 1.0.0

package/README.md

@@ -0,0 +1,598 @@
+# TelemetryOS Root Applications SDK
+
+Welcome to the TelemetryOS Root Applications SDK! This document will guide you through building root 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.
+
+## Root Applications in TelemetryOS
+
+Root applications are advanced web applications that replace TelemetryOS's default Freeform Editor entirely. When you build a root application, you're creating a complete custom interface that runs directly on devices.
+
+**Important:** Most developers should use the standard SDK (`@telemetryos/sdk`) instead. Root applications are for specialized use cases that require complete control over the device experience.
+
+### Example Use Cases
+
+Root applications could be used for scenarios like:
+
+- **IPTV Set-Top Box Interface** - Custom UI for channel navigation, program guides, and proprietary video decoding with specialized hardware integration
+- **Industrial Control Dashboards** - Real-time monitoring and control interfaces for manufacturing equipment or building systems  
+- **Interactive Kiosk Systems** - Completely custom navigation flows for specific business processes (beyond standard digital signage)
+- **Point-of-Sale Terminals** - Custom checkout interfaces with payment processing and inventory integration
+- **Educational Interactive Displays** - Specialized learning interfaces with custom interaction patterns
+
+### How Root Applications Work
+
+Your root application runs as an iframe directly within TelemetryOS's infrastructure, completely replacing the Freeform Editor. You're responsible for building:
+
+- **Complete Device Interface** - The entire user experience that displays on physical devices
+- **Custom Administration Interface** - Configuration tools integrated into TelemetryOS's administration UI
+- **Administration Navigation** - Custom sidebar navigation items in the TelemetryOS administration UI for managing your specialized resources
+
+### Mount Points
+
+Root applications define specialized mount points in their `telemetry.config.json` file:
+
+- `rootRender` - The main interface that displays on physical devices. This replaces the Freeform Editor entirely.
+- `rootSettings` - The main configuration interface in TelemetryOS's [administration UI][admin-ui] where customers configure your root application.
+
+And specialized worker scripts:
+
+- `rootSettingsNavigation` - Registers custom navigation items in TelemetryOS's administration UI sidebar, allowing you to add specialized management interfaces (e.g., "Channel Management", "Hardware Settings", "Custom Reports").
+- `rootSettingsDeviceContentAssignment` - Configures custom options when customers assign your root application to devices.
+
+### Administration UI Integration
+
+Root applications can integrate deeply with TelemetryOS's administration interface by registering custom navigation items:
+
+```javascript
+// Register custom sidebar navigation for your root application
+import { rootSettingsNavigation } from '@telemetryos/root-sdk';
+
+await rootSettingsNavigation().register([
+  { label: 'Channel Management', path: '/admin/channels' },
+  { label: 'Hardware Configuration', path: '/admin/hardware' },
+  { label: 'Viewing Analytics', path: '/admin/analytics' }
+]);
+```
+
+This allows customers to manage your specialized resources alongside their standard TelemetryOS configuration.
+
+### Embedding Other Applications (Optional)
+
+Root applications can also discover and embed other TelemetryOS applications if needed:
+
+```javascript
+// Discover applications by mount point  
+const widgets = await applications().getAllByMountPoint('status-widget');
+
+// Create custom composition interface
+const iframe = document.createElement('iframe');
+iframe.src = await applications().getUrl('system-monitor', 'render');
+```
+
+## Getting Started
+
+To get started, add the SDK to your project:
+
+### Installation
+
+With npm:
+
+```bash
+npm install @telemetryos/root-sdk
+```
+
+Or include it directly in your HTML:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@telemetryos/root-sdk"></script>
+```
+
+### Basic Configuration
+
+Import and configure the SDK with your application name:
+
+```javascript
+import { configure } from '@telemetryos/root-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 device-specific calibration or state.
+- **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/root-sdk';
+
+// Global scope - shared across all instances of your app
+await store().global.set('systemConfig', { theme: 'dark', language: 'en' });
+
+// Local scope - specific to this app instance
+await store().local.set('currentChannel', 'HBO');
+
+// DeviceLocal scope - stays on this device only
+await store().deviceLocal.set('hardwareConfig', { audioLevel: 0.8 });
+
+// Shared scope - communicate with other applications
+await store().shared.set('system-status', 'currentMode', 'interactive');
+
+// Subscribe to changes for real-time updates
+const channelHandler = (newChannel) => {
+  console.log(`Channel updated to: ${newChannel}`);
+  switchToChannel(newChannel);
+};
+
+store().local.subscribe('currentChannel', channelHandler);
+
+// Clean up subscriptions when no longer needed
+store().local.unsubscribe('currentChannel', channelHandler);
+```
+
+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/root-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/root-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/root-sdk';
+
+// Get current account
+const account = await accounts().getCurrent();
+
+// Get current user
+const userResult = await users().getCurrent();
+const userId = userResult.user.id;
+```
+
+## 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 continuously for root applications. On devices, they start when your root application is assigned and run until it's replaced. In the administration UI, they start when the page loads for any enabled root applications. 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. Enable your root application in account settings
+5. Assign your root application to specific devices in the devices list view
+
+## 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/root-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/root-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/root-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/root-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/root-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/root-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/root-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/accounts.d.ts

@@ -0,0 +1,18 @@
+import { Client } from './index.js';
+type CurrentAccount = {
+    id: string;
+};
+export declare class Accounts {
+    _client: Client;
+    constructor(client: Client);
+    /**
+     * Retrieves information about the account associated with the current session.
+     *
+     * This method allows an application to get details about the TelemetryOS account
+     * in which it is currently running.
+     *
+     * @returns A promise that resolves to the current account object
+     */
+    getCurrent(): Promise<CurrentAccount>;
+}
+export {};

package/dist/applications.d.ts

@@ -0,0 +1,55 @@
+import { Client } from './client.js';
+export type MountPoint = {
+    [key: string]: any;
+    path: string;
+};
+export type Application = {
+    name: string;
+    mountPoints: Record<string, MountPoint>;
+};
+export type GetUrlResult = {
+    url: string;
+};
+export declare class Applications {
+    _client: Client;
+    constructor(client: Client);
+    /**
+     * Retrieves all applications with a specific mount point within the current account.
+     *
+     * This method allows applications that host other applications to discover compatible
+     * applications that can be embedded. For example, a dashboard application might search
+     * for all applications that have a 'dashboard-widget' mount point.
+     *
+     * The results are scoped to the current account, so only applications associated with
+     * the same account will be returned.
+     *
+     * @param mountPoint The mount point identifier to search for
+     * @returns A promise that resolves to an array of applications having the specified mount point
+     */
+    getAllByMountPoint(mountPoint: string): Promise<Application[]>;
+    /**
+     * Retrieves an application by its name.
+     *
+     * This method allows finding a specific application when you know its name. It's useful
+     * when you need to check if a particular application is available or get its details
+     * before attempting to embed it.
+     *
+     * @param name The name of the application to query for
+     * @returns A promise that resolves to the application object if found, or null if not found
+     */
+    getByName(name: string): Promise<Application | null>;
+    /**
+     * Generates a URL for embedding an application with the specified name and mount point.
+     *
+     * This method returns a URL that can be used in an iframe src attribute to embed
+     * the application. The URL includes necessary parameters for the application to
+     * understand its context and communicate with the platform.
+     *
+     * Only applications that are associated with the current account can be retrieved.
+     *
+     * @param name The name of the application to get the URL for
+     * @param mountPoint The mount point to use when embedding the application
+     * @returns A promise that resolves to the URL string for embedding the application
+     */
+    getUrl(name: string, mountPoint: string): Promise<string>;
+}

package/dist/bridge-message-formatter.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import { bridgeMessageValidator } from './bridge-message-validator.js';
+export type Message = z.infer<typeof bridgeMessageValidator>;
+export declare function formatBridgeMessage(data: Message): {
+    name: string;
+    data?: any;
+};

package/dist/bridge-message-validator.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+export declare const bridgeMessageValidator: z.ZodObject<{
+    name: z.ZodString;
+    data: z.ZodAny;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    data?: any;
+}, {
+    name: string;
+    data?: any;
+}>;

package/dist/bridge.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-JDXm3DEz.cjs");const a=e.z.object({telemetrySdkVersion:e.z.string(),applicationName:e.z.string(),name:e.z.string(),data:e.z.any(),responseName:e.z.string().optional(),subscriptionName:e.z.string().optional(),unsubscribeName:e.z.string().optional()});class r{bind(){this._windowMessageHandler=n=>{var s;if(n.source===window)return;const i=a.safeParse(n.data);if(!i.success)return;const t=i.data;(s=this.onMessage)===null||s===void 0||s.call(this,t)},window.addEventListener("message",this._windowMessageHandler)}unbind(){this._windowMessageHandler&&window.removeEventListener("message",this._windowMessageHandler)}send(n){for(let s=0;s<window.frames.length;s+=1)window.frames[s].postMessage(n,"*")}}exports.Bridge=r;