@teardown/react-native 2.0.0 → 2.0.1

package/docs/06-logging.mdx

@@ -0,0 +1,345 @@
+# Logging
+
+Structured logging system with configurable log levels.
+
+## Overview
+
+The LoggingClient provides:
+- Configurable log levels
+- Named loggers for each client
+- Console binding preservation
+- Debug mode support
+
+## Log Levels
+
+```typescript
+type LogLevel = 
+  | "none"      // No logging
+  | "error"     // Only errors
+  | "warn"      // Errors and warnings
+  | "info"      // Errors, warnings, and info
+  | "verbose"   // Everything including debug
+```
+
+### Level Priority
+
+```
+none < error < warn < info < verbose
+```
+
+When you set a level, all lower-priority levels are also shown:
+- `error`: Shows only errors
+- `warn`: Shows errors + warnings
+- `info`: Shows errors + warnings + info
+- `verbose`: Shows everything (errors + warnings + info + debug)
+
+## Setting Log Level
+
+### On Initialization
+
+```typescript
+const teardown = new TeardownCore({
+  // ... other options
+});
+
+// Set log level after initialization
+teardown.setLogLevel('verbose');
+```
+
+### During Runtime
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function DebugPanel() {
+  const { core } = useTeardown();
+  
+  const enableDebugMode = () => {
+    core.setLogLevel('verbose');
+  };
+  
+  const disableLogging = () => {
+    core.setLogLevel('none');
+  };
+  
+  return (
+    <View>
+      <Button title="Enable Debug" onPress={enableDebugMode} />
+      <Button title="Disable Logs" onPress={disableLogging} />
+    </View>
+  );
+}
+```
+
+## Log Output Format
+
+All logs are prefixed with the client name:
+
+```
+[Teardown:TeardownCore] Shutting down TeardownCore
+[Teardown:IdentityClient] Identify state: unidentified -> identifying
+[Teardown:IdentityClient] Identify state: identifying -> identified
+[Teardown:ForceUpdateClient] Version status changing: initializing -> checking
+[Teardown:ForceUpdateClient] Checking version status on foreground
+[Teardown:DeviceClient] Getting device ID
+[Teardown:StorageClient] Creating storage for teardown:v1:identity
+```
+
+## Logger Methods
+
+Each client has a logger with these methods:
+
+```typescript
+logger.info(message, ...args)    // Info level
+logger.warn(message, ...args)    // Warning level
+logger.error(message, ...args)   // Error level
+logger.debug(message, ...args)   // Debug level (verbose)
+logger.trace(message, ...args)   // Stack trace (verbose)
+```
+
+## Internal Logging
+
+The SDK logs these events:
+
+### TeardownCore
+
+```typescript
+[Teardown:TeardownCore] Error initializing TeardownCore { error }
+[Teardown:TeardownCore] Shutting down TeardownCore
+```
+
+### IdentityClient
+
+```typescript
+[Teardown:IdentityClient] Identify state: unidentified -> identifying
+[Teardown:IdentityClient] Identify state: identifying -> identified
+[Teardown:IdentityClient] 422 Error identifying user { ... }
+```
+
+### ForceUpdateClient
+
+```typescript
+[Teardown:ForceUpdateClient] Version status changing: initializing -> up_to_date
+[Teardown:ForceUpdateClient] Checking version status on foreground
+[Teardown:ForceUpdateClient] Skipping version check - not identified
+```
+
+### DeviceClient
+
+```typescript
+[Teardown:DeviceClient] Getting device ID
+```
+
+### StorageClient
+
+```typescript
+[Teardown:StorageClient] Creating storage for teardown:v1:identity
+[Teardown:StorageClient] Storage already exists for teardown:v1:identity
+[Teardown:StorageClient] Returning existing storage for teardown:v1:identity
+[Teardown:StorageClient] Clearing storage for teardown:v1:identity
+```
+
+## Console Binding
+
+The logger preserves console call sites for better debugging:
+
+```typescript
+// Bound console methods preserve original call site
+private boundConsole = {
+  log: console.log.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+  warn: console.warn.bind(console),
+  trace: console.trace.bind(console),
+};
+```
+
+This means clicking log messages in DevTools takes you to the original SDK code, not the logger wrapper.
+
+## Creating Custom Loggers
+
+While not typically needed, you can create custom loggers:
+
+```typescript
+import { LoggingClient } from '@teardown/react-native';
+
+const logging = new LoggingClient({ logLevel: 'info' });
+const logger = logging.createLogger({ name: 'MyFeature' });
+
+logger.info('Feature initialized');
+logger.error('Something went wrong');
+```
+
+## Conditional Logging
+
+The SDK checks log level before logging:
+
+```typescript
+// Only logs if current level >= info
+if (this.loggingClient.shouldLog('info')) {
+  logger.info('Message');
+}
+```
+
+This prevents unnecessary string concatenation and formatting in production.
+
+## Best Practices
+
+### 1. Use 'none' in Production
+
+```typescript
+// ✅ Good - no logs in production
+const logLevel = __DEV__ ? 'verbose' : 'none';
+teardown.setLogLevel(logLevel);
+```
+
+### 2. Use 'verbose' for Debugging
+
+```typescript
+// ✅ Good - detailed logs during development
+if (__DEV__) {
+  teardown.setLogLevel('verbose');
+}
+```
+
+### 3. Enable Logging for Support
+
+```typescript
+// ✅ Good - user can enable logs for support
+function Settings() {
+  const { core } = useTeardown();
+  const [debugMode, setDebugMode] = useState(false);
+  
+  const toggleDebug = () => {
+    const newMode = !debugMode;
+    setDebugMode(newMode);
+    core.setLogLevel(newMode ? 'verbose' : 'none');
+  };
+  
+  return <Switch value={debugMode} onValueChange={toggleDebug} />;
+}
+```
+
+### 4. Don't Rely on Logs for Logic
+
+```typescript
+// ❌ Bad - logs may be disabled
+logger.info('User identified');
+// ... rely on this log
+
+// ✅ Good - use state/events
+const result = await identify();
+if (result.success) {
+  // ... use result, not logs
+}
+```
+
+## Log Level Examples
+
+### Development
+
+```typescript
+// See everything
+teardown.setLogLevel('verbose');
+
+// Output:
+// [Teardown:IdentityClient] Getting device ID
+// [Teardown:IdentityClient] Identify state: unidentified -> identifying
+// [Teardown:StorageClient] Creating storage for teardown:v1:identity
+// etc.
+```
+
+### Debugging Issues
+
+```typescript
+// See important events
+teardown.setLogLevel('info');
+
+// Output:
+// [Teardown:IdentityClient] Identify state: unidentified -> identifying
+// [Teardown:ForceUpdateClient] Version status changing: initializing -> up_to_date
+```
+
+### Production
+
+```typescript
+// See only errors
+teardown.setLogLevel('error');
+
+// Output:
+// [Teardown:TeardownCore] Error initializing TeardownCore { error }
+// [Teardown:IdentityClient] 422 Error identifying user { ... }
+```
+
+### Disabled
+
+```typescript
+// No logs
+teardown.setLogLevel('none');
+
+// Output:
+// (nothing)
+```
+
+## Environment-Based Configuration
+
+```typescript
+const LOG_LEVEL: LogLevel = 
+  process.env.NODE_ENV === 'development' ? 'verbose' :
+  process.env.NODE_ENV === 'staging' ? 'info' :
+  'error';
+
+teardown.setLogLevel(LOG_LEVEL);
+```
+
+## Debugging Tips
+
+### 1. Enable Verbose Logging
+
+```typescript
+teardown.setLogLevel('verbose');
+```
+
+### 2. Filter by Client
+
+Search DevTools console for specific client:
+```
+[Teardown:IdentityClient]
+```
+
+### 3. Track State Transitions
+
+Look for state change logs:
+```
+Identify state: unidentified -> identifying
+Version status changing: checking -> up_to_date
+```
+
+### 4. Check Error Details
+
+Errors include full context:
+```typescript
+logger.error('Error initializing', { error, context });
+```
+
+## Performance
+
+Logging is optimized for production:
+
+```typescript
+// ✅ Good - check happens before string operations
+if (this.shouldLog('verbose')) {
+  logger.debug(`Expensive operation: ${JSON.stringify(bigObject)}`);
+}
+
+// ❌ Bad - string created even if logging disabled
+logger.debug(`Expensive operation: ${JSON.stringify(bigObject)}`);
+```
+
+The SDK uses the first pattern internally.
+
+## Next Steps
+
+- [API Reference](./07-api-reference.mdx)
+- [Hooks Reference](./08-hooks-reference.mdx)
+- [Advanced Usage](./09-advanced.mdx)

package/docs/06-storage.mdx

@@ -0,0 +1,349 @@
+# Storage
+
+Persistent, namespaced storage with platform adapters.
+
+## Overview
+
+The StorageClient provides:
+- Namespaced key-value storage
+- Platform-agnostic interface
+- Multiple storage adapters
+- Automatic cleanup
+
+## Storage Adapters
+
+### MMKV Adapter (Recommended)
+
+Fast, encrypted storage using react-native-mmkv:
+
+```typescript
+import { TeardownCore } from '@teardown/react-native';
+import { createMMKVStorageFactory } from '@teardown/react-native/mmkv';
+
+const teardown = new TeardownCore({
+  // ... other options
+  storageFactory: createMMKVStorageFactory(),
+});
+```
+
+Install dependency:
+```bash
+bun add react-native-mmkv
+```
+
+Benefits:
+- ⚡ Extremely fast (synchronous)
+- 🔒 Encrypted by default
+- 📦 Small bundle size
+- 💾 Persistent across app restarts
+
+### Custom Storage Adapter
+
+Create your own storage adapter:
+
+```typescript
+import type { SupportedStorage } from '@teardown/react-native';
+
+function createCustomStorageFactory() {
+  return (storageKey: string): SupportedStorage => {
+    // Your storage implementation
+    return {
+      preload: () => {
+        // Load data into memory if needed
+      },
+      getItem: (key: string) => {
+        // Return value or null
+        return localStorage.getItem(`${storageKey}:${key}`);
+      },
+      setItem: (key: string, value: string) => {
+        // Store value
+        localStorage.setItem(`${storageKey}:${key}`, value);
+      },
+      removeItem: (key: string) => {
+        // Remove value
+        localStorage.removeItem(`${storageKey}:${key}`);
+      },
+      clear: () => {
+        // Clear all keys for this namespace
+      },
+      keys: () => {
+        // Return all keys
+        return Object.keys(localStorage);
+      },
+    };
+  };
+}
+```
+
+## Storage Interface
+
+```typescript
+type SupportedStorage = {
+  preload: () => void;
+  getItem: (key: string) => string | null;
+  setItem: (key: string, value: string) => void;
+  removeItem: (key: string) => void;
+  clear: () => void;
+  keys: () => string[];
+}
+```
+
+## Namespacing
+
+Storage is automatically namespaced to prevent key collisions:
+
+```typescript
+// Internal storage keys are prefixed
+teardown:v1:identity:IDENTIFY_STATE
+teardown:v1:device:deviceId
+teardown:v1:version:VERSION_STATUS
+```
+
+This prevents conflicts with:
+- Your app's storage
+- Other libraries
+- Multiple Teardown instances
+
+## How It Works
+
+### 1. Storage Factory
+
+The storage factory creates namespaced storage instances:
+
+```typescript
+// You provide the factory
+storageFactory: createMMKVStorageFactory()
+
+// SDK calls it for each client
+const identityStorage = storage.createStorage('identity');
+const deviceStorage = storage.createStorage('device');
+```
+
+### 2. Client Storage
+
+Each client gets its own namespaced storage:
+
+```typescript
+class IdentityClient {
+  constructor(storage: StorageClient) {
+    // Creates "teardown:v1:identity" namespace
+    this.storage = storage.createStorage('identity');
+  }
+  
+  saveSession(session: Session) {
+    // Actually saves to "teardown:v1:identity:IDENTIFY_STATE"
+    this.storage.setItem('IDENTIFY_STATE', JSON.stringify(session));
+  }
+}
+```
+
+### 3. Automatic Persistence
+
+The SDK automatically persists critical state:
+
+- Identity state (session data)
+- Version status
+- Device ID
+
+## Internal Storage Keys
+
+The SDK uses these storage keys internally:
+
+| Client | Key | Data |
+|--------|-----|------|
+| Identity | `IDENTIFY_STATE` | User session and identity state |
+| Device | `deviceId` | Generated device UUID |
+| ForceUpdate | `VERSION_STATUS` | Current version status |
+
+## Creating Storage Instances
+
+You typically don't create storage instances directly - clients do it internally:
+
+```typescript
+// Internal SDK code
+class MyClient {
+  constructor(storage: StorageClient) {
+    this.storage = storage.createStorage('my-namespace');
+  }
+}
+```
+
+If you need custom storage:
+
+```typescript
+import { useTeardown } from '@teardown/react-native';
+
+function MyComponent() {
+  const { core } = useTeardown();
+  
+  // Access internal storage (not recommended)
+  // Better to use your own storage solution for app data
+}
+```
+
+## Data Format
+
+All data is stored as JSON strings:
+
+```typescript
+// Stored
+storage.setItem('key', JSON.stringify({ foo: 'bar' }));
+
+// Retrieved
+const data = JSON.parse(storage.getItem('key'));
+```
+
+## Cleanup
+
+Storage is automatically cleaned up on SDK shutdown:
+
+```typescript
+// Happens automatically when TeardownProvider unmounts
+core.shutdown();
+```
+
+This clears all namespaced storage instances.
+
+## Best Practices
+
+### 1. Use MMKV for Production
+
+```typescript
+// ✅ Recommended - fast and encrypted
+storageFactory: createMMKVStorageFactory()
+
+// ⚠️ Avoid in production - slow and unencrypted
+storageFactory: createAsyncStorageFactory()
+```
+
+### 2. Don't Access Internal Storage Directly
+
+```typescript
+// ❌ Bad - bypasses SDK abstractions
+MMKV.set('teardown:v1:identity:IDENTIFY_STATE', '...');
+
+// ✅ Good - use SDK methods
+await core.identity.identify({...});
+```
+
+### 3. Use Your Own Storage for App Data
+
+```typescript
+// ❌ Bad - mixing SDK and app data
+core.storage.setItem('user-preferences', '...');
+
+// ✅ Good - separate storage for app
+import { MMKV } from 'react-native-mmkv';
+const appStorage = new MMKV({ id: 'app-storage' });
+appStorage.set('user-preferences', '...');
+```
+
+### 4. Handle Storage Errors
+
+```typescript
+// Storage operations can throw
+try {
+  const value = storage.getItem('key');
+} catch (error) {
+  console.error('Storage error:', error);
+  // Handle error (fallback, retry, etc.)
+}
+```
+
+## Migrations
+
+If you need to migrate storage data:
+
+```typescript
+function migrateStorage() {
+  const oldKey = 'old-app:session';
+  const newKey = 'teardown:v1:identity:IDENTIFY_STATE';
+  
+  const oldData = localStorage.getItem(oldKey);
+  if (oldData) {
+    // Transform data if needed
+    const newData = transformData(oldData);
+    localStorage.setItem(newKey, newData);
+    localStorage.removeItem(oldKey);
+  }
+}
+
+// Run before initializing Teardown
+migrateStorage();
+const teardown = new TeardownCore({...});
+```
+
+## Storage Size
+
+The SDK stores minimal data:
+
+- Identity state: ~500 bytes
+- Device ID: ~36 bytes (UUID)
+- Version status: ~50 bytes
+
+Total: Less than 1KB for all SDK data.
+
+## Encryption
+
+### MMKV
+
+MMKV encrypts data by default:
+
+```typescript
+// Already encrypted
+storageFactory: createMMKVStorageFactory()
+```
+
+### Custom Encryption
+
+For custom adapters, implement encryption:
+
+```typescript
+import CryptoJS from 'crypto-js';
+
+function createEncryptedStorage(encryptionKey: string) {
+  return (namespace: string) => ({
+    getItem: (key: string) => {
+      const encrypted = localStorage.getItem(`${namespace}:${key}`);
+      if (!encrypted) return null;
+      return CryptoJS.AES.decrypt(encrypted, encryptionKey).toString();
+    },
+    setItem: (key: string, value: string) => {
+      const encrypted = CryptoJS.AES.encrypt(value, encryptionKey).toString();
+      localStorage.setItem(`${namespace}:${key}`, encrypted);
+    },
+    // ... other methods
+  });
+}
+```
+
+## Testing
+
+Mock storage for testing:
+
+```typescript
+function createMockStorageFactory() {
+  const store = new Map<string, string>();
+  
+  return (namespace: string) => ({
+    preload: () => {},
+    getItem: (key: string) => store.get(`${namespace}:${key}`) ?? null,
+    setItem: (key: string, value: string) => store.set(`${namespace}:${key}`, value),
+    removeItem: (key: string) => store.delete(`${namespace}:${key}`),
+    clear: () => store.clear(),
+    keys: () => Array.from(store.keys()),
+  });
+}
+
+// Use in tests
+const teardown = new TeardownCore({
+  storageFactory: createMockStorageFactory(),
+  // ...
+});
+```
+
+## Next Steps
+
+- [Logging](./06-logging.mdx)
+- [API Reference](./07-api-reference.mdx)
+- [Advanced Usage](./09-advanced.mdx)