# Storage Methods

Complete reference for the TelemetryOS Storage Methods with four storage scopes for data persistence and real-time synchronization.

# 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

```typescript
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:**

```typescript
// 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:**

```typescript
// 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:**

```typescript
// 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:**

```typescript
// 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:**

```typescript
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:**

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

### get()

Retrieve a value from storage.

**Signature:**

```typescript
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:**

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

### subscribe()

Subscribe to changes for a specific key.

**Signature:**

```typescript
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:**

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

### unsubscribe()

Remove subscription for a specific key.

**Signature:**

```typescript
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:**

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

### delete()

Remove a value from storage.

**Signature:**

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

**Parameters:**

* `key` - Storage key to delete

**Returns:** `Promise<boolean>` - `true` if successful

**Example:**

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

## Storage Scope Comparison

| Feature | application | instance | device | shared(ns) |
|---------|-------------|----------|--------|------------|
| Visibility | All instances | Single instance | Single device | All apps in namespace |
| Settings Access | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
| Device Access | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| Sync | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
| Offline | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |

## Next Steps

* **[Code Examples](../Development/code-examples.md)** - See complete storage patterns
* **[Mount Points](../Development/mount-points.md)** - Understand where storage works
* **[Client Methods](./client-methods.md)** - Low-level messaging methods