@syncvault/sdk 1.0.0 → 1.2.0

package/README.md

@@ -105,33 +105,59 @@ List all files for this app.
 #### `vault.delete(path)`
 Delete a file.
 
-### Metadata Methods
+### Metadata Methods (Preferences)
 
-App metadata is unencrypted data stored server-side. Use it for app-specific logic like subscription status, feature flags, or user preferences that don't need encryption.
+Metadata is unencrypted data for app preferences like theme, timezone, language. Use it for settings that don't need encryption and are needed for app logic.
 
 #### `vault.getMetadata()`
-Get app metadata for the current user.
+Get preferences for the current user.
 
 #### `vault.setMetadata(metadata)`
-Set app metadata (replaces all existing metadata).
+Set preferences (replaces all existing).
 
 #### `vault.updateMetadata(metadata)`
-Update app metadata (merges with existing metadata).
+Update preferences (merges with existing).
 
 ```javascript
-// Example: Store subscription status
+// Example: Store user preferences
 await vault.setMetadata({
-  subscriptionActive: true,
-  subscriptionExpiresAt: '2026-12-31',
-  plan: 'premium'
+  theme: 'dark',
+  timezone: 'UTC',
+  language: 'en'
 });
 
-// Read metadata
-const meta = await vault.getMetadata();
-console.log(meta.subscriptionActive); // true
+// Read preferences
+const prefs = await vault.getMetadata();
+console.log(prefs.theme); // 'dark'
 
 // Update specific fields
-await vault.updateMetadata({ lastLogin: new Date().toISOString() });
+await vault.updateMetadata({ language: 'es' });
+```
+
+### Entitlements Methods
+
+Entitlements are read-only data set by the developer's backend. Use them for subscription status, feature flags, etc. Users can read but not modify entitlements.
+
+#### `vault.getEntitlements()`
+Get entitlements for the current user.
+
+```javascript
+// Read entitlements (set by developer backend)
+const entitlements = await vault.getEntitlements();
+console.log(entitlements.plan); // 'premium'
+console.log(entitlements.features); // ['advanced', 'export']
+```
+
+### Quota Methods
+
+#### `vault.getQuota()`
+Get user's storage quota information.
+
+```javascript
+const quota = await vault.getQuota();
+console.log(quota.quotaBytes);   // 10485760 (10MB) or null if unlimited
+console.log(quota.usedBytes);    // 1048576 (1MB)
+console.log(quota.unlimited);    // false
 ```
 
 ### State Methods
@@ -158,4 +184,107 @@ Users see these permissions during OAuth authorization.
 
 All data is encrypted client-side using AES-256-GCM with a key derived from the user's password using PBKDF2 (100,000 iterations). The server never sees unencrypted data.
 
-Note: Metadata is NOT encrypted - use it only for non-sensitive app logic.
+Note: Metadata (preferences) and entitlements are NOT encrypted - use them only for non-sensitive settings and subscription status.
+
+## Setting Entitlements (Developer Backend)
+
+Entitlements can only be set from your backend using both the app token and secret token:
+
+```javascript
+// On your backend (e.g., after payment webhook)
+await fetch(`https://api.syncvault.dev/api/entitlements/${userId}`, {
+  method: 'PUT',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-App-Token': process.env.SYNCVAULT_APP_TOKEN,
+    'X-Secret-Token': process.env.SYNCVAULT_SECRET_TOKEN
+  },
+  body: JSON.stringify({
+    entitlements: {
+      plan: 'premium',
+      features: ['advanced', 'export'],
+      expiresAt: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toISOString()
+    }
+  })
+});
+```
+
+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.0.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

@@ -27,6 +27,14 @@ export interface DeleteResponse {
 
 export type Metadata = Record<string, unknown>;
 
+export type Entitlements = Record<string, unknown>;
+
+export interface QuotaInfo {
+  quotaBytes: number | null;
+  usedBytes: number;
+  unlimited: boolean;
+}
+
 export declare class SyncVault {
   constructor(options: SyncVaultOptions);
   
@@ -45,11 +53,17 @@ export declare class SyncVault {
   list(): Promise<FileInfo[]>;
   delete(path: string): Promise<DeleteResponse>;
   
-  // Metadata operations (unencrypted server-side data)
+  // Metadata operations (unencrypted, for app preferences like theme, timezone)
   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>;
   
+  // Entitlements (read-only, set by developer's backend for subscriptions, feature flags)
+  getEntitlements<T extends Entitlements = Entitlements>(): Promise<T>;
+  
+  // Quota info
+  getQuota(): Promise<QuotaInfo>;
+  
   // State
   isAuthenticated(): boolean;
   logout(): void;
@@ -58,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

@@ -2,6 +2,15 @@ import { encrypt, decrypt, prepareAuthPassword } from './crypto.js';
 
 const DEFAULT_SERVER = 'https://api.syncvault.dev';
 
+export class SyncVaultError extends Error {
+  constructor(message, statusCode, data) {
+    super(message);
+    this.name = 'SyncVaultError';
+    this.statusCode = statusCode;
+    this.data = data;
+  }
+}
+
 export class SyncVault {
   constructor(options = {}) {
     if (!options.appToken) {
@@ -186,6 +195,26 @@ export class SyncVault {
     return response.metadata;
   }
 
+  /**
+   * Get entitlements for current user (read-only, set by developer's backend)
+   * Entitlements are used for subscription status, feature flags, etc.
+   */
+  async getEntitlements() {
+    this._checkAuth();
+
+    const response = await this._request('/api/sync/entitlements');
+    return response.entitlements;
+  }
+
+  /**
+   * Get user storage quota info for the current app
+   */
+  async getQuota() {
+    this._checkAuth();
+
+    return this._request('/api/sync/quota');
+  }
+
   /**
    * Check if user is authenticated
    */
@@ -239,7 +268,11 @@ export class SyncVault {
     const data = await response.json();
 
     if (!response.ok) {
-      throw new Error(data.error || 'Request failed');
+      throw new SyncVaultError(
+        data.error || 'Request failed',
+        response.status,
+        data
+      );
     }
 
     return data;
@@ -247,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);
+}