@teardown/react-native 2.0.4 → 2.0.10

package/docs/07-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)