@use-stall/core 0.0.5 → 0.0.6

package/README.md

@@ -12,59 +12,76 @@ The Stall Core SDK provides an adapter-based architecture that allows you to:
 - **Implement CRUD + bulk operations** with a consistent API
 - **Handle errors gracefully** with try-catch wrapped operations
 - **Cache adapter modules** in IndexedDB with TTL-based invalidation
+- **Work offline-first** with automatic local data caching and intelligent sync queuing
+- **Sync intelligently** with dependency-aware batch processing and automatic ID management
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────┐
-│        Your Application             │
-└──────────────┬──────────────────────┘
-               │
-       ┌───────▼──────────────────┐
-       │  initializeStallCore()
-       │  Returns: CoreConfig
-       └───────┬──────────────────┘
-               │          
-    ┌──────────▼──────────┐
-    │   Service Layer     │
-    ├─────────────────────┤
-    │ - products          │
-    │ - orders            │
-    │ - customers         │
-    │ - variants          │
-    │ - inventory_levels  │
-    │ - promotions        │
-    │ - refunds           │
-    │ - payments          │
-    │ - tax_regions       │
-    │ - locations         │
-    │ - fulfillments      │
-    │ - ... and more      │
-    └──────────┬──────────┘
-               │
-    ┌──────────▼──────────────────┐
-    │  Adapter Module (Cached)    │
-    │  ┌───────────────────────┐  │
-    │  │ - Products module     │  │
-    │  │ - Orders module       │  │
-    │  │ - Customers module    │  │
-    │  │ - All modules         │  │
-    │  └───────────────────────┘  │
-    │                             │
-    │  Storage: IndexedDB + Dexie │
-    │  TTL: 4 hours (configurable)│
-    └──────────┬──────────────────┘
-               │
-    ┌──────────▼──────────────────┐
-    │   Connector Loader          │
-    │  (Dynamic Module Import)    │
-    └──────────┬──────────────────┘
-               │
-    ┌──────────▼──────────────────┐
-    │  Commerce Platform API      │
-    │  (WooCommerce, Shopify,     │
-    │  Medusa,Google Sheets etc.) │
-    └─────────────────────────────┘
+┌──────────────────────────────────────────┐
+│         Your Application                 │
+└────────────────┬─────────────────────────┘
+                 │
+         ┌───────▼──────────────────┐
+         │  initializeStallCore()   │
+         │  Returns: CoreConfig     │
+         └───────┬──────────────────┘
+                 │          
+    ┌────────────▼──────────────┐
+    │    Service Layer          │
+    ├──────────────────────────┤
+    │ - products, orders, etc. │
+    │ - All 16+ services       │
+    └────────────┬─────────────┘
+                 │
+    ┌────────────▼────────────────────────┐
+    │    Offline-First Processing         │
+    ├─────────────────────────────────────┤
+    │ Read Operations:                    │
+    │ 1. Fetch from Connector            │
+    │ 2. Cache in Local DB (Dexie)       │
+    │ 3. Return cached data              │
+    │                                     │
+    │ Write Operations:                   │
+    │ 1. Generate temporary offline ID   │
+    │ 2. Save locally immediately        │
+    │ 3. Queue for sync                  │
+    │ 4. Return local data instantly     │
+    │                                     │
+    │ Storage: IndexedDB + Dexie         │
+    │ Tables: products, orders, sync_queue,
+    │         sync_logs, customers, etc. │
+    └────────────┬────────────────────────┘
+                 │
+    ┌────────────▼──────────────────┐
+    │   Sync Queue & Smart Sync      │
+    ├───────────────────────────────┤
+    │ - Dependency-aware processing │
+    │ - 5-layer sync strategy       │
+    │ - Automatic ID replacement    │
+    │ - Batch sync operations       │
+    │ - Sync status logging         │
+    └────────────┬──────────────────┘
+                 │
+    ┌────────────▼──────────────────────┐
+    │  Adapter Module (Cached)          │
+    │  ┌─────────────────────────────┐  │
+    │  │ - Products, Orders modules  │  │
+    │  │ - All connector modules     │  │
+    │  └─────────────────────────────┘  │
+    │  Caching: TTL 4 hours (default)   │
+    └────────────┬──────────────────────┘
+                 │
+    ┌────────────▼──────────────────┐
+    │   Connector Loader            │
+    │  (Dynamic Module Import)      │
+    └────────────┬──────────────────┘
+                 │
+    ┌────────────▼───────────────────────┐
+    │  Commerce Platform API             │
+    │  (WooCommerce, Shopify, Medusa,   │
+    │   Shopware, Google Sheets, etc.)   │
+    └────────────────────────────────────┘
 ```
 
 ## Installation
@@ -264,6 +281,113 @@ const fulfillment = await fulfillments.retrieve({ sdk: stall, id: 'ful_123' });
 const newFulfillment = await fulfillments.create({ sdk: stall, data: { order_id: 'order_123' } });
 ```
 
+## Offline-First Caching
+
+### How It Works
+
+All service operations use a local-first, cloud-sync strategy:
+
+**Read Operations:**
+1. Service method calls connector adapter via `sdk.adapter()`
+2. Data is fetched from the commerce platform API
+3. Results are automatically cached in the local Dexie database
+4. Cached data is returned to your application
+5. Subsequent calls return local cached data instantly
+
+**Write Operations:**
+1. Data is saved immediately to the local database with a temporary offline ID
+2. Operation is queued for synchronization (added to sync_queue table)
+3. Local data is returned instantly for better user experience
+4. When connectivity returns, the sync engine processes the queue
+5. Temporary ID is replaced with the real connector ID
+6. Sync status is logged in the sync_logs table
+
+### Local Storage Structure
+
+The SDK uses the following Dexie tables for offline functionality:
+
+```typescript
+// Data tables (cached from connector)
+- products
+- orders
+- customers
+- variants
+- categories
+- collections
+- inventory_levels
+- promotions
+- refunds
+- payments
+- payment_providers
+- tax_regions
+- tax_rates
+- locations
+- fulfillments
+- order_notes
+
+// Offline-specific tables
+- sync_queue: Tracks pending create/update/delete operations
+- sync_logs: Records sync status and timestamps
+```
+
+### Offline ID Management
+
+When creating records locally, the SDK generates temporary offline IDs:
+
+```typescript
+// Temporary ID format
+stall_product_<uuid>_<timestamp>
+
+// Example
+const newProduct = await products.create({
+  sdk: stall,
+  data: { name: 'Offline Product', price: 29.99 }
+});
+
+// Returns immediately with temporary ID
+// Product ID: stall_product_a1b2c3d4_1699564800000
+
+// After sync completes, ID is replaced with real connector ID
+// Product ID: prod_12345 (from WooCommerce, Shopify, etc.)
+```
+
+### Sync Queue Structure
+
+Each queued operation tracks:
+
+```typescript
+interface SyncQueueItem {
+  id: string;                    // Unique queue item ID
+  action: 'create' | 'update' | 'delete';
+  table: string;                 // Which table (products, orders, etc.)
+  document_id: string;           // Local or connector ID
+  stall_offline_id: string;      // Persistent offline reference
+  data: any;                      // Operation payload
+  status: 'pending' | 'syncing' | 'synced' | 'failed';
+  error?: string;                // Error message if failed
+  created_at: string;            // When queued
+  synced_at?: string;            // When successfully synced
+}
+```
+
+### Sync Logs
+
+Each operation is logged for audit and debugging:
+
+```typescript
+interface SyncLog {
+  id: string;
+  batch_id: string;              // Groups related operations
+  action: string;
+  table: string;
+  document_id: string;
+  status: 'success' | 'failed' | 'pending';
+  message: string;
+  created_at: string;
+  completed_at?: string;
+}
+```
+
 ## Adapter Architecture
 
 ### How It Works
@@ -291,6 +415,18 @@ const products3 = await products.list({ sdk: stall, query: 'hats' });
 await stall.refreshAdapter(); // Clears cache, fetches fresh module
 ```
 
+### Dependency-Aware Sync
+
+The sync engine processes operations in dependency order to maintain data integrity:
+
+**Layer 1 (Foundation):** Categories, Collections, Tax Regions
+**Layer 2 (Products):** Products and their core properties
+**Layer 3 (Variants):** Product Variants and Inventory
+**Layer 4 (Orders):** Orders, Notes, and basic fulfillment
+**Layer 5 (Payments):** Payment Providers, Payments, Refunds, Fulfillments
+
+This ensures that referenced entities are created before dependent records.
+
 ## Error Handling
 
 All service methods are wrapped in try-catch blocks and propagate errors:
@@ -303,6 +439,118 @@ try {
 }
 ```
 
+## Offline Handling
+
+The SDK handles offline scenarios gracefully by queuing operations locally and syncing when connectivity returns:
+
+### Write Operations While Offline
+
+```typescript
+// This operation succeeds even without connectivity
+const product = await products.create({
+  sdk: stall,
+  data: {
+    name: 'Offline Created Product',
+    price: 79.99
+  }
+});
+
+// Returns immediately with temporary offline ID
+console.log(product.id); // stall_product_xyz_1699564800000
+
+// Operation is queued and will sync automatically when online
+```
+
+### Monitoring Sync Queue
+
+Check for pending operations before taking critical actions:
+
+```typescript
+import { local_db } from '@use-stall/core/db/db';
+
+// Get all pending sync operations
+const pending = await local_db.sync_queue
+  .where('status')
+  .equals('pending')
+  .toArray();
+
+console.log(`Pending operations: ${pending.length}`);
+
+// Check for failed operations
+const failed = await local_db.sync_queue
+  .where('status')
+  .equals('failed')
+  .toArray();
+
+if (failed.length > 0) {
+  console.warn(`${failed.length} sync operations failed:`, failed);
+}
+
+// Check sync logs for history
+const recentLogs = await local_db.sync_logs
+  .orderBy('created_at')
+  .reverse()
+  .limit(10)
+  .toArray();
+
+console.log('Recent sync activity:', recentLogs);
+```
+
+### Handling Offline State in Your App
+
+```typescript
+// Detect if there are pending operations
+async function hasPendingSync() {
+  const pending = await local_db.sync_queue
+    .where('status')
+    .equals('pending')
+    .count();
+  
+  return pending > 0;
+}
+
+// Show indicator to user
+const hasSync = await hasPendingSync();
+if (hasSync) {
+  showSyncIndicator('Syncing changes...');
+}
+
+// Disable certain actions while syncing
+const isSyncing = await local_db.sync_queue
+  .where('status')
+  .equals('syncing')
+  .count();
+
+if (isSyncing > 0) {
+  disableCheckout(); // Don't checkout while syncing
+}
+```
+
+### Retrying Failed Operations
+
+```typescript
+// Get failed operations
+const failedOps = await local_db.sync_queue
+  .where('status')
+  .equals('failed')
+  .toArray();
+
+// Manually retry a failed operation
+for (const operation of failedOps) {
+  try {
+    // Update status to pending for retry
+    await local_db.sync_queue.update(operation.id, {
+      status: 'pending',
+      error: null
+    });
+    
+    console.log(`Queued retry for ${operation.action} on ${operation.table}`);
+  } catch (error) {
+    console.error('Failed to queue retry:', error);
+  }
+}
+```
+
 ## Type Safety
 
 All services use TypeScript types from `@use-stall/types`:
@@ -398,6 +646,55 @@ const items = await products.bulk_create({
 
 5. **Type your data**: Use TypeScript types for safety
 
+6. **Embrace offline-first**: Write operations return instantly with local data and sync automatically
+
+```typescript
+// Create returns immediately with temporary ID
+const product = await products.create({
+  sdk: stall,
+  data: { name: 'New Product', price: 49.99 }
+});
+
+// Use the product immediately in your UI
+// It will sync in the background when connectivity returns
+console.log(product.id); // stall_product_abc123_1699564800000
+```
+
+7. **Monitor sync status**: Check pending operations before critical actions
+
+```typescript
+// Get pending sync operations (implementation depends on your sync service)
+const pending = await local_db.sync_queue
+  .where('status')
+  .equals('pending')
+  .toArray();
+
+if (pending.length > 0) {
+  console.log(`${pending.length} operations pending sync`);
+}
+```
+
+8. **Batch related operations**: Group dependent operations for better sync efficiency
+
+```typescript
+// Create product, then variants together
+const product = await products.create({
+  sdk: stall,
+  data: { name: 'New Product' }
+});
+
+const variants = await variants.bulk_create({
+  sdk: stall,
+  data: [
+    { product_id: product.id, size: 'S' },
+    { product_id: product.id, size: 'M' },
+    { product_id: product.id, size: 'L' },
+  ]
+});
+
+// Sync engine will create product first, then variants
+```
+
 ```typescript
 import type { UnifiedProductType } from '@use-stall/types';