Storage Methods

Complete reference for the TelemetryOS Storage Methods.

Overview

The Storage Methods provide persistent data storage with four different scopes:

• application - Shared across all instances of your application
• instance - Specific to the current application instance
• device - Only on the current physical device
• shared(namespace) - Inter-application communication

Importing

import { store } from '@telemetryos/sdk';

Storage Scopes

application

Purpose: Data shared across all instances of your application within an account.

Use Cases:

• Company branding (logos, colors)
• Global API endpoints
• Application-wide feature flags
• Shared resources

Availability: Admin portal and devices

Example:

// Save company branding
await store().application.set('branding', {
  logo: 'https://example.com/logo.png',
  primaryColor: '#007bff'
});

// Load in any instance
const branding = await store().application.get('branding');

instance

Purpose: Data specific to the current application instance.

Use Cases:

• Instance-specific settings
• Configuration values
• Settings ↔ Render communication

Availability: Admin portal and devices

Key Concept: Settings and render mount points share the same instance ID, enabling real-time communication.

Example:

// Settings view - save configuration
await store().instance.set('city', 'New York');

// Render view - subscribe to changes
store().instance.subscribe('city', (newCity) => {
  updateWeatherDisplay(newCity);
});

device

Purpose: Data stored only on the current physical device.

Use Cases:

• Device-specific calibration
• Local cache
• Kiosk session data
• Touch screen settings

Availability: Devices only (NOT available in admin portal)

Important: Device scope cannot be used in settings mount points.

Example:

// Only works on physical devices
await store().device.set('calibration', {
  brightness: 0.8,
  touchOffset: { x: 5, y: 3 }
});

shared(namespace)

Purpose: Data shared between different applications through a common namespace.

Use Cases:

• Inter-application communication
• Shared data sources
• Application coordination

Availability: Admin portal and devices

Important: Applications must agree on namespace and key conventions.

Example:

// Weather app publishes data
await store().shared('weather-data').set('temperature', '72°F');

// Energy app subscribes to weather data
store().shared('weather-data').subscribe('temperature', (temp) => {
  adjustHVACDisplay(temp);
});

Methods

All storage scopes provide the same methods:

set()

Save a value to storage.

Signature:

async set(key: string, value: any): Promise<boolean>

Parameters:

• key - Storage key (string)
• value - Value to store (must be JSON-serializable)

Returns: Promise<boolean> - true if successful

Example:

await store().instance.set('city', 'New York');

get()

Retrieve a value from storage.

Signature:

async get<T>(key: string): Promise<T | undefined>

Parameters:

• key - Storage key (string)

Returns: Promise<T | undefined> - Stored value or undefined if key doesn't exist

Example:

const city = await store().instance.get<string>('city');

subscribe()

Subscribe to changes for a specific key.

Signature:

async subscribe(key: string, handler: MessageHandler<any>): Promise<boolean>

Parameters:

• key - Storage key to watch
• handler - Callback function (value: T) => void

Returns: Promise<boolean> - true if subscription successful

Example:

await store().instance.subscribe('city', (newCity) => {
  updateDisplay(newCity);
});

unsubscribe()

Remove subscription for a specific key.

Signature:

async unsubscribe(key: string, handler?: MessageHandler<any>): Promise<boolean>

Parameters:

• key - Storage key to stop watching
• handler - (Optional) Specific handler to remove

Returns: Promise<boolean> - true if unsubscription successful

Example:

await store().instance.unsubscribe('city', handler);

delete()

Remove a value from storage.

Signature:

async delete(key: string): Promise<boolean>

Parameters:

• key - Storage key to delete

Returns: Promise<boolean> - true if successful

Example:

await store().instance.delete('temporaryData');

Storage Scope Comparison

Next Steps

• Code Examples - See complete storage patterns
• Mount Points - Understand where storage works
• Client Methods - Low-level messaging methods