@cshah18/sdk 4.8.0 → 4.9.0

package/README.md

@@ -236,40 +236,300 @@ The SDK automatically selects the appropriate API endpoint based on the `env` pa
 
 The backend URLs are managed internally by the SDK for security.
 
+## Performance Configuration
+
+The SDK supports optional performance tuning for different network conditions and use cases. Configure these settings when initializing the SDK:
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-merchant-key",
+  env: "production",
+  performance: {
+    requestTimeout: 30000, // Default: 30000ms (30 seconds)
+    maxRetries: 2, // Default: 2
+    animationSpeed: "normal", // Default: "normal" ("fast" | "normal" | "slow")
+  },
+});
+```
+
+### Configuration Options
+
+#### `requestTimeout` (number, default: 30000)
+
+Maximum time in milliseconds to wait for API requests before timing out.
+
+**Use Cases:**
+
+- **Slow Networks** (Mobile, poor connections): `60000` or `90000`
+- **Fast Networks** (Fiber, corporate): `10000` or `15000`
+- **Standard** (Default): `30000`
+
+**Example - Slow Network:**
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-key",
+  performance: {
+    requestTimeout: 60000, // Wait up to 60 seconds for API responses
+  },
+});
+```
+
+#### `maxRetries` (number, default: 2)
+
+Number of times to automatically retry failed API requests.
+
+**Use Cases:**
+
+- **Flaky Networks** (WiFi, variable connectivity): `3` or `4`
+- **Stable Networks** (Fiber, datacenter): `1` or `2`
+- **Offline-First Apps**: `0` (handle retries manually)
+
+**Example - Flaky Network:**
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-key",
+  performance: {
+    maxRetries: 4, // Retry up to 4 times on failure
+  },
+});
+```
+
+#### `animationSpeed` (string, default: "normal")
+
+Controls the speed of widget animations (open/close, transitions, etc).
+
+**Options:**
+
+- `"fast"` - Reduced animation duration for snappy interactions
+- `"normal"` (default) - Standard animation timing
+- `"slow"` - Extended animation duration for better visibility
+
+**Example - Fast Animations:**
+
+```typescript
+CoBuy.init({
+  merchantKey: "your-key",
+  theme: {
+    primaryColor: "#4f46e5",
+  },
+  performance: {
+    animationSpeed: "fast",
+  },
+});
+```
+
+### Complete Example
+
+```typescript
+CoBuy.init({
+  merchantKey: "pk_live_abc123xyz",
+  env: "production",
+  debug: true,
+  theme: {
+    primaryColor: "#4f46e5",
+    borderRadius: "8px",
+  },
+  performance: {
+    requestTimeout: 45000, // 45 seconds for slower connections
+    maxRetries: 3, // Retry 3 times on failure
+    animationSpeed: "normal", // Standard animation speed
+  },
+});
+```
+
+### Default Behavior
+
+If performance config is not provided, the SDK uses sensible defaults optimized for typical production environments:
+
+```typescript
+{
+  requestTimeout: 30000,
+  maxRetries: 2,
+  animationSpeed: "normal"
+}
+```
+
 ## Error Handling
 
-The SDK includes custom error classes:
+The SDK uses a **standardized error handling approach** for different operation types:
+
+### Error Patterns by Method Type
+
+**1. Initialization & Validation Methods** - Throw synchronous errors
+
+- `CoBuy.init()` - Throws errors for invalid configuration
+- `ConfigManager.setConfig()` - Throws errors for validation failure
+
+**2. Widget Rendering** - Returns Promise that may reject
+
+- `CoBuy.renderWidget()` - Returns `Promise<void>` that rejects on rendering errors
+- Can be handled with try/catch OR .catch()
+
+**3. API Methods** - Return ApiResponse<T> (no exceptions)
+
+- `apiClient.getProductReward()` - Returns `{success: true|false, data?, error?}`
+- Check `response.success` to determine outcome
+
+### Custom Error Classes
 
-### `CoBuyNotInitializedError`
+#### `CoBuyNotInitializedError`
 
-Thrown when attempting to use the SDK before calling `init()`.
+Thrown when attempting to use SDK features before calling `CoBuy.init()`.
 
 ```typescript
 try {
   CoBuy.renderWidget({
-    /* ... */
+    productId: "prod_123",
+    container: "#widget",
   });
 } catch (error) {
   if (error instanceof CoBuyNotInitializedError) {
-    console.error("SDK not initialized");
+    console.error("SDK must be initialized first");
+    CoBuy.init({ merchantKey: "your-key" });
   }
 }
 ```
 
-### `CoBuyInvalidConfigError`
+#### `CoBuyInvalidConfigError`
 
-Thrown when invalid configuration is provided to `init()`.
+Thrown when invalid configuration is provided to `CoBuy.init()`.
 
 ```typescript
 try {
-  CoBuy.init({ merchantKey: "" }); // Invalid
+  CoBuy.init({
+    authMode: "public",
+    // Missing required merchantKey
+  });
 } catch (error) {
   if (error instanceof CoBuyInvalidConfigError) {
-    console.error("Invalid configuration:", error.message);
+    console.error("Config validation failed:", error.message);
+    console.error("Error code:", error.code); // "INVALID_CONFIG"
   }
 }
 ```
 
+#### `CoBuyRenderError`
+
+Thrown when widget rendering fails (container not found, DOM issues, etc).
+
+```typescript
+try {
+  await CoBuy.renderWidget({
+    productId: "prod_123",
+    container: "#nonexistent-container",
+  });
+} catch (error) {
+  if (error instanceof CoBuyRenderError) {
+    console.error("Widget render failed:", error.message);
+    console.error("Container selector:", error.details?.selector);
+  }
+}
+```
+
+#### `CoBuyValidationError`
+
+Thrown when input validation fails (invalid product ID, invalid container selector, etc).
+
+```typescript
+try {
+  await CoBuy.renderWidget({
+    productId: "", // Invalid: empty string
+    container: "#widget",
+  });
+} catch (error) {
+  if (error instanceof CoBuyValidationError) {
+    console.error("Input validation failed:", error.message);
+    console.error("Details:", error.details); // { productId: '' }
+  }
+}
+```
+
+#### `CoBuyApiError`
+
+Thrown when API communication fails (network errors, CORS issues, API errors, etc).
+
+```typescript
+const apiClient = CoBuy.getApiClient();
+try {
+  const response = await apiClient.getProductReward("prod_123");
+  if (!response.success) {
+    // API returned error response - check error details
+    console.error("API Error:", response.error?.code);
+    if (response.error?.statusCode === 429) {
+      console.log("Rate limited - retry after delay");
+    }
+  }
+} catch (error) {
+  // This usually doesn't happen as ApiClient returns ApiResponse
+  // But some methods may throw CoBuyApiError
+  if (error instanceof CoBuyApiError) {
+    console.error("API Error:", error.message);
+    console.error("Code:", error.code);
+  }
+}
+```
+
+### Error Base Class
+
+All custom errors inherit from `CoBuyError` which provides consistent structure:
+
+```typescript
+class CoBuyError extends Error {
+  code: string; // Error code for programmatic handling
+  details?: unknown; // Additional error details
+}
+```
+
+### Handling Different Error Types
+
+```typescript
+import {
+  CoBuyError,
+  CoBuyNotInitializedError,
+  CoBuyInvalidConfigError,
+  CoBuyRenderError,
+  CoBuyValidationError,
+  CoBuyApiError,
+} from "@cobuy/sdk";
+
+// Universal error handler
+async function renderWithErrorHandling() {
+  try {
+    await CoBuy.renderWidget({
+      productId: "prod_123",
+      container: "#widget",
+    });
+  } catch (error) {
+    if (error instanceof CoBuyNotInitializedError) {
+      // Handle: SDK not initialized
+      console.error("Please call CoBuy.init() first");
+    } else if (error instanceof CoBuyInvalidConfigError) {
+      // Handle: Bad configuration
+      console.error("Check your init options:", error.message);
+    } else if (error instanceof CoBuyValidationError) {
+      // Handle: Invalid input
+      console.error("Input validation failed:", error.details);
+    } else if (error instanceof CoBuyRenderError) {
+      // Handle: Rendering failed
+      console.error("Failed to render widget:", error.message);
+    } else if (error instanceof CoBuyApiError) {
+      // Handle: API communication failed
+      console.error("API error:", error.code);
+    } else if (error instanceof CoBuyError) {
+      // Handle: Other CoBuy errors
+      console.error("SDK error:", error.code);
+    } else {
+      // Handle: Unexpected error
+      console.error("Unexpected error:", error);
+    }
+  }
+}
+```
+
+> 📖 **Comprehensive Error Reference**: See [ERROR_CODES.md](./docs/ERROR_CODES.md) for complete list of all error codes, handling strategies, and debugging guidance.
+
 ## Debugging
 
 Enable debug logging to monitor SDK operations:
@@ -287,6 +547,14 @@ When debug mode is enabled, the SDK logs:
 - Environment and API base URL
 - Widget rendering operations
 
+## Migration Guide
+
+For breaking changes and upgrade steps, see [MIGRATION_GUIDE.md](MIGRATION_GUIDE.md).
+
+## Versioning & Changelog
+
+This project follows Semantic Versioning and tracks changes in [CHANGELOG.md](CHANGELOG.md).
+
 ## Project Structure
 
 ```
@@ -328,7 +596,7 @@ npm install
 
 ### Scripts
 
-```bash
+````bash
 # Build the SDK
 npm run build
 
@@ -363,8 +631,9 @@ npm run version:prerelease
 
 # After bumping, push manually if desired
 git push && git push --tags
-```
-```
+````
+
+````
 
 ### Code Quality
 
@@ -407,7 +676,7 @@ const options: CoBuyInitOptions = {
 };
 
 CoBuy.init(options);
-```
+````
 
 ## Configuration Examples
 
@@ -461,6 +730,175 @@ CoBuy.renderWidget({
 });
 ```
 
+## Implementation Status
+
+### ✅ Complete & Stable
+
+- **Core Widget Rendering**: Fully implemented with loading states, error handling, and retry logic
+- **Product Reward Display**: Real-time reward data fetching with TTL-based caching
+- **Group Management**: Automatic group creation and joining with progress tracking
+- **Lobby Modal**: Full-featured group coordination UI with sharing, offline redemption, and real-time updates
+- **Authentication**: Support for both public (merchant key) and token-based auth modes
+- **Theme Customization**: Comprehensive theming with colors, animations, and typography
+- **Accessibility (WCAG AA)**:
+  - Keyboard navigation and focus management
+  - Screen reader support with ARIA labels and live regions
+  - Semantic HTML and proper heading hierarchy
+  - Color contrast compliance
+- **Input Validation**: Comprehensive validation for colors, product IDs, and auth credentials
+- **Request Optimization**:
+  - Response caching with 60s TTL for product rewards
+  - Request deduplication for concurrent identical calls
+  - Automatic timeout cleanup to prevent memory leaks
+  - Debounced group data refreshes
+- **Error Handling**: Custom error classes with descriptive messages
+- **TypeScript Support**: Full type definitions with strict mode enabled
+- **Browser Compatibility**: ES2017+ support (Chrome 51+, Firefox 54+, Safari 10+)
+
+### 🟡 Partial Implementation
+
+- **Offline Redemption**: QR code generation and manual code entry supported; SMS/email delivery backend integration pending
+
+---
+
+## Known Limitations
+
+### Technical Limitations
+
+1. **Bundle Size**: ~7.5 KB minified/gzipped (unavoidable due to full modal UI + real-time features)
+2. **Single Instance Per Container**: Only one widget can render per DOM container; multiple products require multiple containers
+3. **Modal Stacking**: Only one modal (lobby or group list) can be open simultaneously
+4. **Network Timeout Guarantees**: Hard timeout of 30 seconds on all API calls; no built-in retry for transient 5xx errors
+5. **CSS Scoping**: Widget uses CSS custom properties; global CSS may override if specificity is higher
+
+### Browser/Platform Limitations
+
+1. **No IE11 Support**: SDK targets ES2017+ only
+2. **WebSocket Required**: Real-time features require WebSocket support (unavailable in some corporate networks)
+3. **Third-Party Cookies**: Social sharing (WhatsApp, Facebook) requires third-party cookie support
+4. **Offline Mode**: Limited; QR code works offline, but group sync requires network connectivity
+
+### API/Data Limitations
+
+1. **Reward Expiry**: Expired rewards show as inactive; no pre-expiry notifications (planned for v2.0)
+2. **Group Capacity**: Max 999 participants per group (theoretical limit); recommend splitting larger promotions
+3. **Concurrency**: Widget serializes renders to prevent race conditions; may add concurrent render support in v2.0
+4. **Rate Limiting**: No built-in request rate limiting client-side (server enforces)
+
+---
+
+## Performance Improvements
+
+- Lazy-load modal components (reduce initial bundle by ~2 KB)
+- Implement virtual scrolling for activity feeds (currently loads all items)
+- Add service worker for offline caching of static assets
+
+## Migration Guide
+
+### From Older SDK Versions (v0.x → v1.0)
+
+#### Breaking Changes
+
+1. **API Client Access**
+
+   **v0.x:**
+
+   ```typescript
+   const client = window.CoBuy.apiClient;
+   ```
+
+   **v1.0:**
+
+   ```typescript
+   const client = window.CoBuy.getApiClient();
+   ```
+
+2. **Event Callback Names**
+
+   **v0.x:**
+
+   ```typescript
+   CoBuy.renderWidget({
+     onGroupJoined: (groupId) => {},
+     onCheckoutInitiated: (data) => {},
+   });
+   ```
+
+   **v1.0:**
+
+   ```typescript
+   CoBuy.renderWidget({
+     onCheckout: (data) => {}, // Consolidated
+   });
+   ```
+
+3. **Error Handling**
+
+   **v0.x:**
+
+   ```typescript
+   try {
+     CoBuy.renderWidget({
+       /*...*/
+     });
+   } catch (error) {
+     if (error.code === "INVALID_CONFIG") {
+     }
+   }
+   ```
+
+   **v1.0:**
+
+   ```typescript
+   try {
+     CoBuy.renderWidget({
+       /*...*/
+     });
+   } catch (error) {
+     if (error instanceof CoBuyInvalidConfigError) {
+     }
+   }
+   ```
+
+#### Migration Steps
+
+1. **Update initialization:**
+
+   ```typescript
+   // v0.x
+   CoBuy.initialize({ apiKey: "pk_..." });
+
+   // v1.0
+   CoBuy.init({ merchantKey: "pk_..." });
+   ```
+
+2. **Update theme property names:**
+
+   ```typescript
+   // v0.x
+   theme: {
+     buttonColor: "#...",
+     darkBg: false,
+   }
+
+   // v1.0
+   theme: {
+     primaryColor: "#...",
+     // Dark mode coming in v2.0
+   }
+   ```
+
+3. **Update error handling:**
+   - Import error classes: `import { CoBuyInvalidConfigError } from "@cobuy/sdk"`
+   - Check `error instanceof ErrorClass` instead of error codes
+
+#### Deprecations
+
+These will be removed in v2.0:
+
+- ❌ `CoBuy.getRawApiClient()` — Use `CoBuy.getApiClient()` instead
+- ❌ `options.onGroupJoined` callback — Use `onCheckout` instead
+
 ## License
 
 MIT
@@ -471,5 +909,5 @@ For issues, feature requests, or questions, please contact support@cobuy.app or
 
 ---
 
-**Version**: 1.0.0  
-**Last Updated**: December 2025
+**Version**: 1.0.0
+**Last Updated**: February 2026