npm package: @onlyfrontend/remote-storage
Description: A localStorage-compatible library that syncs with OnlyFrontend backend
Author: OnlyFrontend
Latest version: 0.1.1

# OnlyFrontend Remote Storage

A TypeScript library that provides a localStorage-compatible interface to automatically sync data with a remote backend. Perfect for building frontend applications that need persistent state without managing complex backend infrastructure.

## Features

- **localStorage-compatible API** - Drop-in replacement for localStorage
- **Automatic sync** - Changes are automatically synced to the remote backend
- **Offline support** - Works offline and syncs when connection is restored
- **TypeScript support** - Full type safety and IntelliSense support
- **Zero backend setup** - Uses OnlyFrontend's managed backend service
- **Client-side encryption** - Built-in encryption using client-side generated userId to keep data private

## Installation

```bash
npm install @onlyfrontend/remote-storage
```

## Quick Start

```typescript
import { createRemoteStorage } from '@onlyfrontend/remote-storage';

// Create a remote storage instance
const remoteStorage = createRemoteStorage({
  apiKey: 'your-api-key'
});

// Create user (do this once)
const userId = await remoteStorage.createUser();

// Use it like localStorage!
remoteStorage.setItem('username', 'john_doe');
remoteStorage.setItem('preferences', JSON.stringify({
  theme: 'dark',
  language: 'en'
}));

console.log(remoteStorage.getItem('username')); // 'john_doe'
console.log(remoteStorage.length); // 2

// Data is automatically synced to the backend!
```

## API Reference

### Class: RemoteStorage

The main class that implements the Storage interface with remote synchronization.

#### Constructor

```typescript
new RemoteStorage(config: Partial<RemoteStorageConfig>)
```

- `config.baseUrl` - The base URL of your backend (optional, uses DEFAULT_BASE_URL if not provided)
- `config.apiKey` - (optional) API key for client
- `config.userId` - (optional) User ID for the current user

#### Authentication Methods

##### `createUser(): Promise<string>`

Create a new user for the current client. Requires API key to be set.

```typescript
const userId = await remoteStorage.createUser();
```

##### `initialize(apiKey: string, userId?: string): Promise<void>`

Initialize with API key and optionally a user ID. If user ID is provided, it will load remote state.

```typescript
await remoteStorage.initialize('your-api-key', 'user-id');
```

##### `setUserId(userId: string): void`

Set the current user ID.

```typescript
remoteStorage.setUserId('user-id');
```

#### Storage Methods (localStorage-compatible)

##### `setItem(key: string, value: string): void`

Store a key-value pair. Automatically syncs to remote.

```typescript
remoteStorage.setItem('theme', 'dark');
```

##### `getItem(key: string): string | null`

Retrieve a value by key.

```typescript
const theme = remoteStorage.getItem('theme'); // 'dark' or null
```

##### `removeItem(key: string): void`

Remove a key-value pair. Automatically syncs to remote.

```typescript
remoteStorage.removeItem('theme');
```

##### `clear(): void`

Remove all stored data. Automatically syncs to remote.

```typescript
remoteStorage.clear();
```

##### `key(index: number): string | null`

Get the key at the specified index.

```typescript
const firstKey = remoteStorage.key(0);
```

##### `length: number`

Get the number of stored items.

```typescript
console.log(remoteStorage.length); // 5
```

#### Sync Methods

##### `syncFromRemote(): Promise<void>`

Manually sync remote data to local cache. Requires API key and user ID to be set.

```typescript
await remoteStorage.syncFromRemote();
```

##### `syncToRemote(): Promise<void>`

Manually sync local data to the remote backend. Requires API key and user ID to be set.

```typescript
await remoteStorage.syncToRemote();
```

##### `save(): Promise<void>`

Alias for `syncToRemote()`.

```typescript
await remoteStorage.save();
```

##### `load(): Promise<void>`

Alias for `syncFromRemote()`.

```typescript
await remoteStorage.load();
```

#### Additional Methods

##### `getAll(): Record<string, string>`

Get all stored data as an object.

```typescript
const allData = remoteStorage.getAll();
// Returns: { key1: 'value1', key2: 'value2' }
```

##### `setMultiple(items: Record<string, string>): void`

Set multiple key-value pairs at once. Automatically syncs to remote if initialized.

```typescript
remoteStorage.setMultiple({
  'username': 'john',
  'email': 'john@example.com',
  'preferences': JSON.stringify({ theme: 'dark' })
});
```

## Usage Examples

### Basic Usage

```typescript
import { createRemoteStorage } from '@onlyfrontend/remote-storage';

const remoteStorage = createRemoteStorage({
  apiKey: 'your-api-key'
});

// One-time setup - create a user
const userId = await remoteStorage.createUser();

// Store credentials for future sessions
localStorage.setItem('app_user_id', userId);

// Use as localStorage
remoteStorage.setItem('user_settings', JSON.stringify({
  theme: 'dark',
  notifications: true
}));
```

### With Existing Credentials

```typescript
const remoteStorage = createRemoteStorage({
  apiKey: 'your-api-key'
});

// Initialize with stored credentials
await remoteStorage.initialize(
  localStorage.getItem('app_user_id')!
);

// Load existing data
await remoteStorage.load();

// Now use normally
const settings = remoteStorage.getItem('user_settings');
```

### User Preferences Class

```typescript
import { RemoteStorage } from '@onlyfrontend/remote-storage';

class UserPreferences {
  constructor(private storage: RemoteStorage) {}

  getTheme(): 'light' | 'dark' {
    return this.storage.getItem('theme') as 'light' | 'dark' || 'light';
  }

  setTheme(theme: 'light' | 'dark'): void {
    this.storage.setItem('theme', theme);
  }

  getLanguage(): string {
    return this.storage.getItem('language') || 'en';
  }

  setLanguage(language: string): void {
    this.storage.setItem('language', language);
  }
}

// Usage
const prefs = new UserPreferences(remoteStorage);
prefs.setTheme('dark');
console.log(prefs.getTheme()); // 'dark'
```

### Error Handling

```typescript
try {
  await remoteStorage.initialize('your-api-key');
  await remoteStorage.createUser();
} catch (error) {
  console.error('Failed to initialize:', error);
  // Fall back to localStorage
  const fallbackStorage = window.localStorage;
}
```

## Backend Integration

This library is designed to work with the OnlyFrontend backend service. The backend provides these endpoints:

- `POST /users` - Create a new user
- `POST /users/{user_id}` - Save user state
- `GET /users/{user_id}` - Load user state

### Authentication

The library automatically handles authentication using an API key:

- `X-API-Key` header with the API key

## TypeScript Support

The library is written in TypeScript and provides full type definitions:

```typescript
interface RemoteStorageConfig {
  baseUrl: string;
  apiKey?: string;
  userId?: string;
}

interface SaveStateRequest {
  state: Record<string, any>;
}

interface StateResponse {
  state: Record<string, any>;
  updated_at: string;
}
```

## Development

```bash
# Install dependencies
npm install

# Build the library
npm run build

# Watch for changes
npm run dev

# Run linting
npm run lint
```

## License

MIT License - see LICENSE file for details.