@calimero-network/mero-js 1.1.0 → 2.0.0-beta.1

package/README.md

@@ -1,442 +1,464 @@
-# Mero.js - Pure JavaScript SDK for Calimero
+# Mero.js v2 — Pure JavaScript SDK for Calimero
 
-A lightweight, universal JavaScript SDK for Calimero that works in both browser and Node.js environments using Web Standards.
-
-> **🚨 Breaking Change (v1.0.0)**: This version removes all legacy Axios-based code. The package now uses only Web Standards (`fetch`, `AbortController`) with zero external dependencies.
+A lightweight, universal JavaScript SDK for interacting with Calimero nodes. Works in browsers, Node.js, React Native, and Tauri.
 
 ## Features
 
-- 🌐 **Web Standards First**: Built on `fetch`, `AbortController`, and other Web APIs
-- 🔄 **Universal**: Works in browsers, Node.js, and edge runtimes
-- 📦 **Zero Dependencies**: No external dependencies, uses native Web APIs
-- 🔧 **Dependency Injection**: Flexible and testable architecture
-- ⚡ **Modern**: ES2020+ with TypeScript support
-- 🛡️ **Type Safe**: Full TypeScript definitions
-- 🔄 **Smart Retry**: Distinguishes user aborts vs timeouts for intelligent retry logic
-- 🎯 **Advanced Cancellation**: Signal combination and proper timeout handling
-
-## Behavior
-
-### Error Model (Throwing)
+- 🌐 **Universal** — Browser, Node.js, React Native, Tauri
+- 📦 **Zero Dependencies** — Built on Web Standards (`fetch`, `AbortController`)
+- 🔐 **Smart Token Management** — Automatic refresh on 401, preemptive refresh before expiry
+- 💾 **Pluggable Storage** — Bring your own `TokenStorage` (localStorage, AsyncStorage, Keychain)
+- 🔄 **Real-time** — WebSocket and SSE clients for event subscriptions
+- ⚡ **JSON-RPC** — Execute queries and mutations on contexts
+- 🛡️ **Type Safe** — Full TypeScript definitions
+- ✅ **Tested** — 236 unit tests, E2E with Merobox
 
-The client **throws** `HTTPError` on any `!response.ok` status. Network/timeout/abort errors are re-thrown as-is:
+## Installation
 
-```typescript
-try {
-  const data = await httpClient.get('/api/data');
-  // Success - data is the parsed response
-} catch (error) {
-  if (error instanceof HTTPError) {
-    console.log(`HTTP ${error.status}: ${error.statusText}`);
-    console.log('URL:', error.url);
-    console.log('Headers:', error.headers);
-    console.log('Body:', error.bodyText); // Up to 64KB
-  } else if (error.name === 'TimeoutError') {
-    // Request timed out
-  } else if (error.name === 'AbortError') {
-    // Request was cancelled
-  }
-}
+```bash
+npm install @calimero-network/mero-js
+# or
+pnpm add @calimero-network/mero-js
 ```
 
-### Parsing Defaults & Override
-
-Each method accepts optional `{ parse?: 'json'|'text'|'blob'|'arrayBuffer'|'response' }`:
-
-**Default parsing rules:**
-
-- `Content-Type: application/json` → parse as JSON
-- `Content-Type: text/*` → parse as text
-- Other types → parse as `arrayBuffer`
-
-**Override:**
+## Quick Start
 
 ```typescript
-// Get raw Response object
-const response = await httpClient.get('/api/data', { parse: 'response' });
-```
-
-### Retry Policy (`withRetry`)
-
-The `withRetry` helper retries on:
+import { MeroJs } from '@calimero-network/mero-js';
 
-- `HTTPError` with status `429` or `>= 500`
-- `TimeoutError` (internal timeouts)
-- `TypeError` (network failures)
+const mero = new MeroJs({
+  baseUrl: 'http://localhost:2428',
+  credentials: {
+    username: 'admin',
+    password: 'your-password',
+  },
+});
 
-**Never retries:**
+// Authenticate
+await mero.authenticate();
 
-- `AbortError` (user/caller aborts)
+// Use the Admin API
+const apps = await mero.admin.applications.listApplications();
+const contexts = await mero.admin.contexts.listContexts();
 
-```typescript
-import { withRetry } from '@calimero-network/mero-js';
-
-const data = await withRetry(
-  (attempt) => httpClient.get('/api/data'),
-  { attempts: 3 }, // Default: 3 attempts
+// Execute JSON-RPC calls
+const result = await mero.rpc.query(
+  'context-id',
+  'get',
+  { key: 'myKey' },
+  'ed25519:executor-public-key'
 );
 ```
 
-### Signal Composition
+## Token Persistence
+
+By default, tokens are stored in-memory. Provide a `TokenStorage` to persist across sessions:
 
-The client combines caller signals with internal timeouts:
+### Browser (localStorage)
 
 ```typescript
-const userSignal = new AbortController().signal;
-const data = await httpClient.get('/api/data', {
-  signal: userSignal,
-  timeoutMs: 5000,
+const mero = new MeroJs({
+  baseUrl: 'http://localhost:2428',
+  credentials: { username: 'admin', password: 'password' },
+  tokenStorage: {
+    async get() {
+      const data = localStorage.getItem('mero-token');
+      return data ? JSON.parse(data) : null;
+    },
+    async set(token) {
+      localStorage.setItem('mero-token', JSON.stringify(token));
+    },
+    async clear() {
+      localStorage.removeItem('mero-token');
+    },
+  },
 });
-```
-
-### Header Precedence & Authorization
 
-- **Caller headers win**: Request-level headers override client defaults
-- **Authorization rules**: Only set `Authorization: Bearer ${token}` if caller didn't provide any `authorization` header (case-insensitive)
+// Load stored tokens on startup
+await mero.init();
 
-### FormData Handling
+if (!mero.isAuthenticated()) {
+  await mero.authenticate();
+}
+```
 
-For `FormData` bodies, the client does **not** set `content-type` (lets browser/undici add the boundary):
+### React Native (AsyncStorage)
 
 ```typescript
-const formData = new FormData();
-formData.append('file', file);
-await httpClient.post('/api/upload', formData);
-// No content-type header is set by the client
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+const mero = new MeroJs({
+  baseUrl: 'http://localhost:2428',
+  credentials: { username: 'admin', password: 'password' },
+  tokenStorage: {
+    async get() {
+      const data = await AsyncStorage.getItem('mero-token');
+      return data ? JSON.parse(data) : null;
+    },
+    async set(token) {
+      await AsyncStorage.setItem('mero-token', JSON.stringify(token));
+    },
+    async clear() {
+      await AsyncStorage.removeItem('mero-token');
+    },
+  },
+});
 ```
 
-### Credentials
-
-No implicit `same-origin` default. Credentials are only set if explicitly provided:
+### Tauri (Secure Store)
 
 ```typescript
-const client = createBrowserHttpClient({
-  baseUrl: 'https://api.example.com',
-  credentials: 'include', // Only if you want to include credentials
+import { Store } from '@tauri-apps/plugin-store';
+
+const store = new Store('.tokens.dat');
+
+const mero = new MeroJs({
+  baseUrl: 'http://localhost:2428',
+  requestCredentials: 'omit', // Required for Tauri
+  tokenStorage: {
+    async get() {
+      return await store.get('mero-token');
+    },
+    async set(token) {
+      await store.set('mero-token', token);
+      await store.save();
+    },
+    async clear() {
+      await store.delete('mero-token');
+      await store.save();
+    },
+  },
 });
 ```
 
-## Installation
+## Token Refresh
 
-```bash
-npm install @calimero-network/mero-js
+The SDK automatically handles token refresh in two ways:
+
+1. **Preemptive** — Refreshes 5 minutes before expiry
+2. **Reactive** — On 401 with `x-auth-error: token_expired`, automatically refreshes and retries
+
+```
+┌─────────────────────────────────────────────────┐
+│                Token Lifecycle                  │
+├─────────────────────────────────────────────────┤
+│  authenticate() ──> Token stored                │
+│                     │                           │
+│  API Request ───────┼──> Token valid? ──yes──>  │
+│                     │         │                 │
+│                     │        no (within 5min)   │
+│                     │         │                 │
+│                     │         ▼                 │
+│                     │    Refresh token          │
+│                     │         │                 │
+│  401 + expired ─────┼─────────┘                 │
+│                     │                           │
+│  clearToken() ──────┼──> Token cleared          │
+└─────────────────────────────────────────────────┘
 ```
 
-## Quick Start
+## API Reference
 
-### Browser Usage
+### MeroJs Class
 
 ```typescript
-import { createBrowserHttpClient } from '@calimero-network/mero-js';
+interface MeroJsConfig {
+  baseUrl: string;              // Node URL
+  authBaseUrl?: string;         // Auth service URL (if separate)
+  credentials?: { username: string; password: string };
+  timeoutMs?: number;           // Default: 10000
+  requestCredentials?: RequestCredentials;
+  tokenStorage?: TokenStorage;  // For persistence
+}
 
-const httpClient = createBrowserHttpClient({
-  baseUrl: 'https://api.calimero.network',
-  getAuthToken: async () => localStorage.getItem('access_token'),
-  onTokenRefresh: async (newToken) =>
-    localStorage.setItem('access_token', newToken),
-});
+const mero = new MeroJs(config);
 
-// Make requests
-try {
-  const data = await httpClient.get<{ message: string }>('/api/hello');
-  console.log(data.message);
-} catch (error) {
-  console.error('Request failed:', error);
-}
+// Lifecycle
+await mero.init();              // Load tokens from storage
+await mero.authenticate();      // Get new tokens
+await mero.clearToken();        // Clear tokens
+mero.isAuthenticated();         // Check auth status
+mero.getTokenData();            // Get current tokens
+
+// API Clients
+mero.auth                       // Auth API
+mero.admin                      // Admin API
+mero.rpc                        // JSON-RPC client
+
+// Real-time
+mero.createWebSocket();         // WebSocket client
+mero.createSse();               // SSE client
 ```
 
-### Node.js Usage
+### Admin API
 
 ```typescript
-import { createNodeHttpClient } from '@calimero-network/mero-js';
-// For Node.js < 18, install undici: npm install undici
-import { fetch as undiciFetch } from 'undici';
-
-const httpClient = createNodeHttpClient({
-  baseUrl: 'https://api.calimero.network',
-  fetch: undiciFetch, // Required for Node.js < 18
-  getAuthToken: async () => process.env.ACCESS_TOKEN,
-});
-
-const data = await httpClient.get<{ message: string }>('/api/hello');
-console.log(data.message);
+// Applications
+await mero.admin.applications.listApplications();
+await mero.admin.applications.getApplication(appId);
+await mero.admin.applications.installApplication({ url, metadata });
+await mero.admin.applications.uninstallApplication(appId);
+
+// Contexts
+await mero.admin.contexts.listContexts();
+await mero.admin.contexts.createContext({ applicationId, contextSeed });
+await mero.admin.contexts.getContext(contextId);
+await mero.admin.contexts.deleteContext(contextId);
+await mero.admin.contexts.joinContext({ contextId, invitationPayload });
+
+// Blobs
+await mero.admin.blobs.listBlobs();
+await mero.admin.blobs.uploadBlob(data);
+await mero.admin.blobs.getBlob(blobId);
+await mero.admin.blobs.deleteBlob(blobId);
+
+// Identity
+await mero.admin.identity.generateContextIdentity();
+
+// Network
+await mero.admin.network.getPeersCount();
+
+// Public (no auth required)
+await mero.admin.public.health();
+await mero.admin.public.isAuthed();
 ```
 
-### Universal Usage
+### Auth API
 
 ```typescript
-import { createUniversalHttpClient } from '@calimero-network/mero-js';
-
-const httpClient = createUniversalHttpClient({
-  baseUrl: 'https://api.calimero.network',
-  getAuthToken: async () => {
-    return typeof window !== 'undefined'
-      ? localStorage.getItem('access_token')
-      : process.env.ACCESS_TOKEN;
-  },
-});
+// Health & Info
+await mero.auth.getHealth();
+await mero.auth.getIdentity();
+await mero.auth.getProviders();
+
+// Tokens
+await mero.auth.getToken(request);
+await mero.auth.refreshToken({ refresh_token });
+await mero.auth.validateToken({ token });
+
+// Keys
+await mero.auth.listRootKeys();
+await mero.auth.createRootKey(request);
+await mero.auth.deleteRootKey(publicKey);
+await mero.auth.listClientKeys();
+await mero.auth.generateClientKey(request);
+await mero.auth.deleteClientKey(publicKey);
 ```
 
-## API Reference
+### JSON-RPC
 
-### Factory Functions
+```typescript
+// Query (read-only)
+const result = await mero.rpc.query(
+  'context-id',
+  'get',
+  { key: 'myKey' },
+  'ed25519:executor-public-key'
+);
 
-#### `createBrowserHttpClient(options)`
+// Mutate (write)
+const result = await mero.rpc.mutate(
+  'context-id',
+  'set',
+  { key: 'myKey', value: 'myValue' },
+  'ed25519:executor-public-key'
+);
 
-Creates an HTTP client optimized for browser environments.
+// Generic execute
+const result = await mero.rpc.execute({
+  contextId: 'context-id',
+  method: 'myMethod',
+  args: { foo: 'bar' },
+  executorPublicKey: 'ed25519:...',
+});
+```
 
-#### `createNodeHttpClient(options)`
+### WebSocket (Real-time Events)
 
-Creates an HTTP client for Node.js environments.
+```typescript
+const ws = mero.createWebSocket();
 
-#### `createUniversalHttpClient(options)`
+await ws.connect();
 
-Creates an HTTP client that works in both browser and Node.js.
+ws.onEvent((event) => {
+  console.log('Event:', event);
+});
 
-### Options
+ws.onError((error) => {
+  console.error('Error:', error);
+});
 
-```typescript
-interface HttpClientOptions {
-  baseUrl: string; // Base URL for all requests
-  fetch?: typeof fetch; // Custom fetch implementation (Node.js)
-  getAuthToken?: () => Promise<string | undefined>; // Token getter
-  onTokenRefresh?: (token: string) => Promise<void>; // Token refresh callback
-  defaultHeaders?: Record<string, string>; // Default headers
-  timeoutMs?: number; // Request timeout (default: 30000)
-  credentials?: RequestCredentials; // CORS credentials (default: 'same-origin' for browser)
-  defaultAbortSignal?: AbortSignal; // Default abort signal for all requests
-}
+await ws.subscribe(['context-id-1', 'context-id-2']);
+
+// Later...
+await ws.unsubscribe(['context-id-1']);
+ws.disconnect();
 ```
 
-### HTTP Methods
+### SSE (Server-Sent Events)
 
 ```typescript
-// GET request
-const response = await httpClient.get<T>('/api/endpoint', init?);
+const sse = mero.createSse();
 
-// POST request
-const response = await httpClient.post<T>('/api/endpoint', body?, init?);
+const sessionId = await sse.connect();
 
-// PUT request
-const response = await httpClient.put<T>('/api/endpoint', body?, init?);
-
-// DELETE request
-const response = await httpClient.delete<T>('/api/endpoint', init?);
+sse.onEvent((event) => {
+  console.log('Event:', event);
+});
 
-// PATCH request
-const response = await httpClient.patch<T>('/api/endpoint', body?, init?);
+await sse.subscribe(['context-id-1']);
 
-// HEAD request
-const response = await httpClient.head<T>('/api/endpoint', init?);
+// Get session info
+const session = await sse.getSession();
 
-// Generic request
-const response = await httpClient.request<T>('/api/endpoint', init?);
+// Later...
+sse.disconnect();
 ```
 
-### Request Options
+## Deep Imports
+
+For tree-shaking or direct access:
 
 ```typescript
-interface RequestOptions extends RequestInit {
-  parse?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'response';
-  timeoutMs?: number;
-}
+// Main SDK
+import { MeroJs } from '@calimero-network/mero-js';
+
+// HTTP Client only
+import { createBrowserHttpClient } from '@calimero-network/mero-js/http-client';
+
+// Specific API clients
+import { AdminApiClient } from '@calimero-network/mero-js/api/admin';
+import { AuthApiClient } from '@calimero-network/mero-js/api/auth';
+import { RpcClient } from '@calimero-network/mero-js/api/rpc';
+import { WebSocketClient } from '@calimero-network/mero-js/api/ws';
+import { SseClient } from '@calimero-network/mero-js/api/sse';
 ```
 
-### Response Format
+## HTTP Client (Low-Level)
 
-All methods return the parsed data directly or throw errors:
+For custom use cases, use the HTTP client directly:
 
 ```typescript
-// Success - returns parsed data
-const data: T = await httpClient.get<T>('/api/data');
+import { createBrowserHttpClient, HTTPError } from '@calimero-network/mero-js';
+
+const http = createBrowserHttpClient({
+  baseUrl: 'https://api.example.com',
+  getAuthToken: async () => myTokenStore.getToken(),
+  refreshToken: async () => {
+    const newToken = await myRefreshLogic();
+    return newToken;
+  },
+  onTokenRefresh: async (token) => {
+    await myTokenStore.setToken(token);
+  },
+  timeoutMs: 10000,
+});
 
-// Error - throws HTTPError or other errors
 try {
-  const data = await httpClient.get('/api/data');
+  const data = await http.get<MyType>('/api/endpoint');
 } catch (error) {
   if (error instanceof HTTPError) {
-    console.log(`HTTP ${error.status}: ${error.statusText}`);
-    console.log('URL:', error.url);
-    console.log('Headers:', error.headers);
-    console.log('Body:', error.bodyText);
+    console.log(`HTTP ${error.status}: ${error.bodyText}`);
   }
 }
 ```
 
-## Advanced Usage
-
-### Custom Transport
+## Error Handling
 
 ```typescript
-import { createHttpClient, Transport } from '@calimero-network/mero-js';
-
-const transport: Transport = {
-  fetch: customFetch,
-  baseUrl: 'https://api.example.com',
-  getAuthToken: async () => 'your-token',
-  timeoutMs: 5000,
-};
-
-const httpClient = createHttpClient(transport);
-```
+import { HTTPError, ApiResponseError } from '@calimero-network/mero-js';
 
-### Error Handling
-
-```typescript
 try {
-  const data = await httpClient.get('/api/data');
-  // Success - data is the parsed response
-  console.log(data);
+  await mero.admin.contexts.getContext('invalid-id');
 } catch (error) {
   if (error instanceof HTTPError) {
-    // HTTP error (4xx, 5xx)
-    console.error(`HTTP ${error.status}: ${error.statusText}`);
-    console.error('URL:', error.url);
-    console.error('Body:', error.bodyText);
-  } else if (error.name === 'TimeoutError') {
-    // Request timed out
-    console.error('Request timed out');
+    // HTTP-level error (4xx, 5xx)
+    console.log(`HTTP ${error.status}: ${error.statusText}`);
+    console.log('Body:', error.bodyText);
+  } else if (error instanceof ApiResponseError) {
+    // API-level error (in response body)
+    console.log(`API Error: ${error.message}`);
+    console.log('Type:', error.type);
+    console.log('Code:', error.code);
   } else if (error.name === 'AbortError') {
     // Request was cancelled
-    console.error('Request was cancelled');
-  } else {
-    // Network or other errors
-    console.error('Request failed:', error);
+  } else if (error.name === 'TimeoutError') {
+    // Request timed out
   }
 }
 ```
 
-### Custom Headers
-
-```typescript
-const data = await httpClient.post('/api/data', body, {
-  headers: {
-    'Content-Type': 'application/json',
-    'X-Custom-Header': 'value',
-  },
-});
-```
-
-### Request Cancellation
-
-```typescript
-const abortController = new AbortController();
-
-// Cancel request after 5 seconds
-setTimeout(() => abortController.abort(), 5000);
-
-const data = await httpClient.get('/api/slow-endpoint', {
-  signal: abortController.signal,
-});
-```
-
-### FormData Support
-
-```typescript
-const formData = new FormData();
-formData.append('file', fileInput.files[0]);
-formData.append('name', 'John Doe');
-
-const data = await httpClient.post('/api/upload', formData);
-// Content-Type is set by the browser/undici with proper boundary
-```
-
-### Response Parsing
-
-```typescript
-// Explicit parsing
-const jsonData = await httpClient.get('/api/data', { parse: 'json' });
-const textData = await httpClient.get('/api/text', { parse: 'text' });
-const blobData = await httpClient.get('/api/file', { parse: 'blob' });
-
-// Auto-detection based on Content-Type (default)
-const autoData = await httpClient.get('/api/data');
-```
+## Testing
 
-### Retry with Exponential Backoff
+```bash
+# Unit tests (236 tests)
+pnpm test
 
-```typescript
-import { withRetry } from '@calimero-network/mero-js';
+# E2E tests with Merobox
+pnpm test:e2e
 
-const data = await withRetry(
-  (attempt) => httpClient.get('/api/unreliable-endpoint'),
-  { attempts: 3 }, // Default: 3 attempts
-);
+# Full test suite
+pnpm test:all
 ```
 
-### Signal Combination
-
-```typescript
-import { combineSignals, createTimeoutSignal } from '@calimero-network/mero-js';
+## Development
 
-// Combine multiple abort signals
-const userSignal = new AbortController().signal;
-const timeoutSignal = createTimeoutSignal(5000);
-const combinedSignal = combineSignals([userSignal, timeoutSignal]);
+```bash
+# Install dependencies
+pnpm install
 
-const data = await httpClient.get('/api/endpoint', {
-  signal: combinedSignal,
-});
-```
+# Build (with strict mode)
+pnpm build
 
-### CORS and Credentials
+# Lint
+pnpm lint
 
-```typescript
-const httpClient = createBrowserHttpClient({
-  baseUrl: 'https://api.example.com',
-  credentials: 'include', // Include cookies in CORS requests
-});
+# Type check
+pnpm typecheck
 
-// For APIs that require credentials
-const data = await httpClient.get('/api/protected', {
-  credentials: 'include',
-});
+# Generate MSW handlers from OpenAPI
+pnpm generate:msw
 ```
 
-## Migration from Axios
-
-If you're migrating from an Axios-based client:
+## Bundle Sizes
 
-1. **Replace imports**: Use the factory functions instead of direct class instantiation
-2. **Update method signatures**: Methods now use `RequestInit` instead of custom options
-3. **Handle responses**: Methods now return parsed data directly or throw errors (no more `ResponseData<T>`)
-4. **Token management**: Use the `getAuthToken` and `onTokenRefresh` callbacks
+| Format | Size | Gzipped |
+|--------|------|---------|
+| ESM | ~57kb | ~15kb |
+| CJS | ~59kb | ~16kb |
+| Browser (minified) | ~29kb | ~9kb |
 
 ## Browser Support
 
-- Modern browsers with `fetch` support (Chrome 42+, Firefox 39+, Safari 10.1+)
-- Node.js 18+ (native fetch) or Node.js 16+ with `undici`
-
-## Bundle Sizes
-
-- **ESM**: ~9.4kb (gzipped: ~3.2kb)
-- **CJS**: ~10.5kb (gzipped: ~3.6kb)
+- Modern browsers with `fetch` (Chrome 42+, Firefox 39+, Safari 10.1+)
+- Node.js 18+ (native fetch) or 16+ with `undici`
+- React Native with `fetch` polyfill
+- Tauri (set `requestCredentials: 'omit'`)
 
-## Examples
+## Migration from v1.x
 
-See the `examples/` directory for complete usage examples:
+### Breaking Changes
 
-- `browser-example.ts` - Browser-specific usage (designed for browser environments)
-- `node-example.ts` - Node.js-specific usage (designed for Node.js environments)
-- `universal-example.ts` - Universal usage (works in both browser and Node.js)
+1. **`clearToken()` is now async**
+   ```typescript
+   // Before
+   mero.clearToken();
+   
+   // After
+   await mero.clearToken();
+   ```
 
-**Note**: Run `npm run build` before running the examples, as they import from the built library.
+2. **HTTP client wiring** — Token refresh callbacks are now wired automatically
 
-## Development
+### New Features
 
-```bash
-# Install dependencies
-pnpm install
-
-# Build
-pnpm build
-
-# Test
-pnpm test
-
-# Lint
-pnpm lint
-```
+- `TokenStorage` interface for persistence
+- `init()` method to load stored tokens
+- Automatic 401 token refresh with retry
+- WebSocket and SSE clients
+- JSON-RPC client
+- Lazy-loaded Admin API sub-clients
+- Enhanced `unwrap()` with RPC error detection
 
 ## License