@teardown/react-native 2.0.2 → 2.0.9

package/docs/06-logging.mdx

@@ -1,345 +0,0 @@
-# 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

@@ -1,349 +0,0 @@
-# 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)