@syncvault/sdk 1.1.0 → 1.2.0

package/README.md

@@ -210,3 +210,81 @@ await fetch(`https://api.syncvault.dev/api/entitlements/${userId}`, {
 ```
 
 Never expose the secret token in client-side code.
+
+## Offline Sync
+
+The SDK supports offline-first sync with local caching and automatic retry.
+
+### Basic Usage
+
+```javascript
+import { SyncVault, createOfflineClient } from '@syncvault/sdk';
+
+const baseClient = new SyncVault({ appToken: 'your_token' });
+const vault = createOfflineClient(baseClient, {
+  retryInterval: 30000,  // Retry every 30 seconds
+  maxRetries: 10,        // Max retries per operation
+  autoSync: true         // Auto-sync when online
+});
+
+// Initialize (loads cache from storage)
+await vault.init();
+
+// Authenticate
+await vault.auth('username', 'password');
+
+// Put - queues if offline, syncs when online
+await vault.put('data.json', { hello: 'world' });
+
+// Get - returns cached data if offline
+const data = await vault.get('data.json');
+
+// Check pending operations
+if (vault.hasPendingChanges()) {
+  console.log('Pending:', vault.pendingCount());
+}
+```
+
+### Callbacks
+
+```javascript
+vault.onSyncSuccess = (op) => {
+  console.log('Synced:', op.path);
+};
+
+vault.onSyncError = (op, error) => {
+  console.log('Failed:', op.path, error);
+};
+```
+
+### Manual Sync Control
+
+```javascript
+// Manually trigger sync
+await vault.syncPending();
+
+// Stop auto-sync
+vault.stopAutoSync();
+
+// Clear cache/queue
+await vault.getStore().clearCache();
+await vault.getStore().clearQueue();
+```
+
+### Custom Storage (React Native, etc.)
+
+```javascript
+const customStorage = {
+  async get(key) {
+    return AsyncStorage.getItem(key).then(JSON.parse);
+  },
+  async set(key, value) {
+    await AsyncStorage.setItem(key, JSON.stringify(value));
+  },
+  async remove(key) {
+    await AsyncStorage.removeItem(key);
+  }
+};
+
+const vault = createOfflineClient(baseClient, { storage: customStorage });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncvault/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "SyncVault SDK - Zero-knowledge encrypted sync for Node.js and browsers",
   "type": "module",
   "main": "src/index.js",

package/src/index.d.ts

@@ -72,3 +72,90 @@ export declare class SyncVault {
 
 export declare function encrypt(data: unknown, password: string): Promise<string>;
 export declare function decrypt<T = unknown>(encryptedBase64: string, password: string): Promise<T>;
+
+// Offline sync types
+export interface PendingOperation {
+  id: string;
+  type: 'put' | 'delete';
+  path: string;
+  data?: string;
+  createdAt: number;
+  retries: number;
+}
+
+export interface CacheEntry {
+  path: string;
+  data: string;
+  updatedAt: number;
+}
+
+export interface OfflineStorage {
+  get(key: string): Promise<unknown | null>;
+  set(key: string, value: unknown): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+export interface OfflineOptions {
+  storage?: OfflineStorage;
+  retryInterval?: number;
+  maxRetries?: number;
+  autoSync?: boolean;
+}
+
+export declare class OfflineStore {
+  constructor(storage?: OfflineStorage | null);
+  load(): Promise<void>;
+  persist(): Promise<void>;
+  getCached(path: string): CacheEntry | null;
+  setCache(path: string, data: string): Promise<void>;
+  removeCache(path: string): Promise<void>;
+  queueOperation(op: Partial<PendingOperation>): Promise<void>;
+  getPendingOperations(): PendingOperation[];
+  removeOperation(id: string): Promise<void>;
+  incrementRetry(id: string): Promise<void>;
+  hasPendingOperations(): boolean;
+  clearQueue(): Promise<void>;
+  clearCache(): Promise<void>;
+}
+
+export declare class OfflineSyncVault {
+  constructor(baseClient: SyncVault, options?: OfflineOptions);
+  
+  onSyncSuccess: ((op: PendingOperation) => void) | null;
+  onSyncError: ((op: PendingOperation, error: Error) => void) | null;
+  
+  init(): Promise<void>;
+  
+  // Auth (proxied to base client)
+  auth(username: string, password: string): Promise<User>;
+  register(username: string, password: string): Promise<User>;
+  setAuth(token: string, password: string): void;
+  getAuthUrl(state?: string): string;
+  exchangeCode(code: string, password: string): Promise<User>;
+  isAuthenticated(): boolean;
+  logout(): void;
+  
+  // Data operations with offline support
+  put<T = unknown>(path: string, data: T): Promise<PutResponse | { queued: boolean; path: string }>;
+  get<T = unknown>(path: string): Promise<T>;
+  delete(path: string): Promise<DeleteResponse | { queued: boolean; path: string }>;
+  list(): Promise<FileInfo[]>;
+  
+  // Metadata/entitlements (no offline caching)
+  getMetadata<T extends Metadata = Metadata>(): Promise<T>;
+  setMetadata<T extends Metadata = Metadata>(metadata: T): Promise<T>;
+  updateMetadata<T extends Metadata = Metadata>(metadata: Partial<T>): Promise<T>;
+  getEntitlements<T extends Entitlements = Entitlements>(): Promise<T>;
+  getQuota(): Promise<QuotaInfo>;
+  getUser(): Promise<User>;
+  
+  // Sync control
+  startAutoSync(): void;
+  stopAutoSync(): void;
+  syncPending(): Promise<void>;
+  hasPendingChanges(): boolean;
+  pendingCount(): number;
+  getStore(): OfflineStore;
+}
+
+export declare function createOfflineClient(baseClient: SyncVault, options?: OfflineOptions): OfflineSyncVault;

package/src/index.js

@@ -280,3 +280,4 @@ export class SyncVault {
 }
 
 export { encrypt, decrypt } from './crypto.js';
+export { OfflineSyncVault, OfflineStore, createOfflineClient } from './offline.js';

package/src/offline.js

@@ -0,0 +1,434 @@
+import { encrypt, decrypt } from './crypto.js';
+
+const DEFAULT_STORE_NAME = 'syncvault-offline';
+const CACHE_KEY = 'cache';
+const QUEUE_KEY = 'queue';
+
+/**
+ * Storage adapter interface
+ */
+class MemoryStorage {
+  constructor() {
+    this.data = new Map();
+  }
+  
+  async get(key) {
+    return this.data.get(key) || null;
+  }
+  
+  async set(key, value) {
+    this.data.set(key, value);
+  }
+  
+  async remove(key) {
+    this.data.delete(key);
+  }
+}
+
+/**
+ * LocalStorage adapter (browser)
+ */
+class LocalStorageAdapter {
+  constructor(prefix = DEFAULT_STORE_NAME) {
+    this.prefix = prefix;
+  }
+  
+  async get(key) {
+    const item = localStorage.getItem(`${this.prefix}:${key}`);
+    return item ? JSON.parse(item) : null;
+  }
+  
+  async set(key, value) {
+    localStorage.setItem(`${this.prefix}:${key}`, JSON.stringify(value));
+  }
+  
+  async remove(key) {
+    localStorage.removeItem(`${this.prefix}:${key}`);
+  }
+}
+
+/**
+ * Offline store for caching and queue management
+ */
+export class OfflineStore {
+  constructor(storage = null) {
+    this.storage = storage || this._detectStorage();
+    this.cache = {};
+    this.queue = [];
+    this.loaded = false;
+  }
+  
+  _detectStorage() {
+    if (typeof localStorage !== 'undefined') {
+      return new LocalStorageAdapter();
+    }
+    return new MemoryStorage();
+  }
+  
+  async load() {
+    if (this.loaded) return;
+    
+    const cache = await this.storage.get(CACHE_KEY);
+    const queue = await this.storage.get(QUEUE_KEY);
+    
+    this.cache = cache || {};
+    this.queue = queue || [];
+    this.loaded = true;
+  }
+  
+  async persist() {
+    await this.storage.set(CACHE_KEY, this.cache);
+    await this.storage.set(QUEUE_KEY, this.queue);
+  }
+  
+  getCached(path) {
+    return this.cache[path] || null;
+  }
+  
+  async setCache(path, data) {
+    this.cache[path] = {
+      path,
+      data,
+      updatedAt: Date.now()
+    };
+    await this.persist();
+  }
+  
+  async removeCache(path) {
+    delete this.cache[path];
+    await this.persist();
+  }
+  
+  async queueOperation(op) {
+    op.id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    op.createdAt = Date.now();
+    op.retries = 0;
+    this.queue.push(op);
+    await this.persist();
+  }
+  
+  getPendingOperations() {
+    return [...this.queue];
+  }
+  
+  async removeOperation(id) {
+    this.queue = this.queue.filter(op => op.id !== id);
+    await this.persist();
+  }
+  
+  async incrementRetry(id) {
+    const op = this.queue.find(op => op.id === id);
+    if (op) {
+      op.retries++;
+      await this.persist();
+    }
+  }
+  
+  hasPendingOperations() {
+    return this.queue.length > 0;
+  }
+  
+  async clearQueue() {
+    this.queue = [];
+    await this.persist();
+  }
+  
+  async clearCache() {
+    this.cache = {};
+    await this.persist();
+  }
+}
+
+/**
+ * Check if error is network-related
+ */
+function isNetworkError(error) {
+  if (!error) return false;
+  const msg = error.message?.toLowerCase() || '';
+  return (
+    error.name === 'TypeError' ||
+    msg.includes('network') ||
+    msg.includes('failed to fetch') ||
+    msg.includes('load failed') ||
+    msg.includes('offline') ||
+    msg.includes('timeout') ||
+    msg.includes('econnrefused') ||
+    msg.includes('enotfound')
+  );
+}
+
+/**
+ * Offline-capable SyncVault client
+ */
+export class OfflineSyncVault {
+  constructor(baseClient, options = {}) {
+    this.client = baseClient;
+    this.store = new OfflineStore(options.storage);
+    this.retryInterval = options.retryInterval || 30000;
+    this.maxRetries = options.maxRetries || 10;
+    this.autoSync = options.autoSync !== false;
+    
+    this.onSyncSuccess = null;
+    this.onSyncError = null;
+    
+    this._syncTimer = null;
+    this._initialized = false;
+  }
+  
+  async init() {
+    if (this._initialized) return;
+    await this.store.load();
+    this._initialized = true;
+    
+    if (this.autoSync) {
+      this.startAutoSync();
+    }
+  }
+  
+  /**
+   * Proxy auth methods to base client
+   */
+  async auth(username, password) {
+    await this.init();
+    return this.client.auth(username, password);
+  }
+  
+  async register(username, password) {
+    await this.init();
+    return this.client.register(username, password);
+  }
+  
+  setAuth(token, password) {
+    this.client.setAuth(token, password);
+  }
+  
+  getAuthUrl(state) {
+    return this.client.getAuthUrl(state);
+  }
+  
+  async exchangeCode(code, password) {
+    return this.client.exchangeCode(code, password);
+  }
+  
+  isAuthenticated() {
+    return this.client.isAuthenticated();
+  }
+  
+  logout() {
+    this.client.logout();
+  }
+  
+  /**
+   * Put with offline support
+   */
+  async put(path, data) {
+    await this.init();
+    
+    const encrypted = await encrypt(data, this.client.password);
+    
+    try {
+      const result = await this.client.put(path, data);
+      await this.store.setCache(path, encrypted);
+      return result;
+    } catch (error) {
+      if (isNetworkError(error)) {
+        await this.store.setCache(path, encrypted);
+        await this.store.queueOperation({
+          type: 'put',
+          path,
+          data: encrypted
+        });
+        return { queued: true, path };
+      }
+      throw error;
+    }
+  }
+  
+  /**
+   * Get with offline fallback
+   */
+  async get(path) {
+    await this.init();
+    
+    try {
+      const result = await this.client.get(path);
+      // Update cache with fresh data
+      const encrypted = await encrypt(result, this.client.password);
+      await this.store.setCache(path, encrypted);
+      return result;
+    } catch (error) {
+      if (isNetworkError(error)) {
+        const cached = this.store.getCached(path);
+        if (cached) {
+          return decrypt(cached.data, this.client.password);
+        }
+        throw new Error('Offline and no cached data available');
+      }
+      throw error;
+    }
+  }
+  
+  /**
+   * Delete with offline support
+   */
+  async delete(path) {
+    await this.init();
+    
+    try {
+      const result = await this.client.delete(path);
+      await this.store.removeCache(path);
+      return result;
+    } catch (error) {
+      if (isNetworkError(error)) {
+        await this.store.removeCache(path);
+        await this.store.queueOperation({
+          type: 'delete',
+          path
+        });
+        return { queued: true, path };
+      }
+      throw error;
+    }
+  }
+  
+  /**
+   * List files (no offline caching for list)
+   */
+  async list() {
+    return this.client.list();
+  }
+  
+  /**
+   * Proxy metadata/entitlements (no offline for these)
+   */
+  async getMetadata() {
+    return this.client.getMetadata();
+  }
+  
+  async setMetadata(metadata) {
+    return this.client.setMetadata(metadata);
+  }
+  
+  async updateMetadata(metadata) {
+    return this.client.updateMetadata(metadata);
+  }
+  
+  async getEntitlements() {
+    return this.client.getEntitlements();
+  }
+  
+  async getQuota() {
+    return this.client.getQuota();
+  }
+  
+  async getUser() {
+    return this.client.getUser();
+  }
+  
+  /**
+   * Start automatic sync of pending operations
+   */
+  startAutoSync() {
+    if (this._syncTimer) return;
+    
+    this._syncTimer = setInterval(() => {
+      this.syncPending();
+    }, this.retryInterval);
+    
+    // Also listen for online event in browser
+    if (typeof window !== 'undefined') {
+      window.addEventListener('online', () => this.syncPending());
+    }
+  }
+  
+  /**
+   * Stop automatic sync
+   */
+  stopAutoSync() {
+    if (this._syncTimer) {
+      clearInterval(this._syncTimer);
+      this._syncTimer = null;
+    }
+  }
+  
+  /**
+   * Manually sync pending operations
+   */
+  async syncPending() {
+    const ops = this.store.getPendingOperations();
+    
+    for (const op of ops) {
+      if (op.retries >= this.maxRetries) {
+        await this.store.removeOperation(op.id);
+        if (this.onSyncError) {
+          this.onSyncError(op, new Error('Max retries exceeded'));
+        }
+        continue;
+      }
+      
+      try {
+        if (op.type === 'put') {
+          await this._syncPut(op);
+        } else if (op.type === 'delete') {
+          await this._syncDelete(op);
+        }
+        
+        await this.store.removeOperation(op.id);
+        if (this.onSyncSuccess) {
+          this.onSyncSuccess(op);
+        }
+      } catch (error) {
+        if (isNetworkError(error)) {
+          await this.store.incrementRetry(op.id);
+        } else {
+          await this.store.removeOperation(op.id);
+          if (this.onSyncError) {
+            this.onSyncError(op, error);
+          }
+        }
+      }
+    }
+  }
+  
+  async _syncPut(op) {
+    await this.client._request('/api/sync/put', {
+      method: 'POST',
+      body: JSON.stringify({ path: op.path, data: op.data })
+    });
+  }
+  
+  async _syncDelete(op) {
+    await this.client._request('/api/sync/delete', {
+      method: 'POST',
+      body: JSON.stringify({ path: op.path })
+    });
+  }
+  
+  /**
+   * Check if there are pending changes
+   */
+  hasPendingChanges() {
+    return this.store.hasPendingOperations();
+  }
+  
+  /**
+   * Get number of pending operations
+   */
+  pendingCount() {
+    return this.store.getPendingOperations().length;
+  }
+  
+  /**
+   * Get the offline store for direct access
+   */
+  getStore() {
+    return this.store;
+  }
+}
+
+/**
+ * Create an offline-capable client
+ */
+export function createOfflineClient(baseClient, options = {}) {
+  return new OfflineSyncVault(baseClient, options);
+}