@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/useCredits.md

@@ -1,342 +1,103 @@
 # useCredits Hook
 
-Hook for accessing and managing credits balance.
+Hook for accessing and managing credits balance with real-time updates.
 
-## Import
+## Location
 
-```typescript
-import { useCredits } from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useCredits.ts`
 
-```typescript
-function useCredits(): {
-  credits: number;
-  balance: number;
-  transactions: Transaction[];
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-}
-```
+**Type**: Hook
 
-## Returns
+## Strategy
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `credits` | `number` | Current credit balance |
-| `balance` | `number` | Balance in currency (USD, etc.) |
-| `transactions` | `Transaction[]` | Transaction history |
-| `isLoading` | `boolean` | Loading state |
-| `error` | `Error \| null` | Error if any |
-| `refetch` | `() => Promise<void>` | Manually refetch data |
+### Data Fetching Flow
 
-## Basic Usage
+1. **Initial Load**
+   - Fetch credits from repository on mount
+   - Cache results in TanStack Query
+   - Handle loading/error states
 
-```typescript
-function CreditsDisplay() {
-  const { credits, isLoading } = useCredits();
+2. **Real-time Updates**
+   - Subscribe to credit changes via repository listener
+   - Auto-update on balance changes
+   - Invalidate query on external modifications
 
-  if (isLoading) return <ActivityIndicator />;
+3. **Cache Management**
+   - Use TanStack Query for caching
+   - Background refetch on window focus
+   - Manual refetch capability
 
-  return (
-    <View>
-      <Text>Your Credits: {credits}</Text>
-      <Text>Balance: ${balance.toFixed(2)}</Text>
-    </View>
-  );
-}
-```
+### Integration Points
 
-## Advanced Usage
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
+- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
+- **TanStack Query**: For cache management and background updates
+- **useFocusEffect**: For refresh on screen focus
 
-### With Refresh Control
+## Restrictions
 
-```typescript
-function CreditsWithRefresh() {
-  const { credits, refetch, isLoading } = useCredits();
+### REQUIRED
 
-  const [refreshing, setRefreshing] = useState(false);
+- **User Authentication**: User MUST be authenticated to access credits
+- **Error Handling**: MUST handle error state in UI
+- **Loading State**: MUST show loading indicator while fetching
 
-  const handleRefresh = async () => {
-    setRefreshing(true);
-    await refetch();
-    setRefreshing(false);
-  };
+### PROHIBITED
 
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
+- **NEVER** assume credits are available without checking loading state
+- **NEVER** use this hook for unauthenticated users
+- **DO NOT** mutate credits directly - use `useDeductCredit` instead
+- **DO NOT** call refetch excessively (causes unnecessary network calls)
 
-      <Button
-        onPress={handleRefresh}
-        disabled={refreshing || isLoading}
-        title={refreshing ? 'Refreshing...' : 'Refresh'}
-      />
-    </View>
-  );
-}
-```
+### CRITICAL SAFETY
 
-### With Auto-Refresh
+- **ALWAYS** check `isLoading` before displaying credits
+- **ALWAYS** handle `error` state to prevent crashes
+- **NEVER** use `credits` value for security decisions (validate on backend)
+- **MUST** implement error boundaries when displaying balance
 
-```typescript
-function AutoRefreshCredits() {
-  const { credits, refetch } = useCredits();
+## AI Agent Guidelines
 
-  // Refresh every 30 seconds
-  useEffect(() => {
-    const interval = setInterval(() => {
-      refetch();
-    }, 30000);
+### When Implementing Credit Displays
 
-    return () => clearInterval(interval);
-  }, [refetch]);
+1. **Always** handle loading state explicitly
+2. **Always** handle error state gracefully
+3. **Always** provide manual refresh option
+4. **Always** format balance safely (handle undefined/null)
+5. **Never** use credits for security decisions (server-side validation required)
 
-  // Refresh when app comes to foreground
-  useFocusEffect(
-    useCallback(() => {
-      refetch();
-    }, [refetch])
-  );
+### Integration Checklist
 
-  return <Text>Credits: {credits}</Text>;
-}
-```
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Handle loading state in UI
+- [ ] Handle error state in UI
+- [ ] Provide refresh mechanism
+- [ ] Format balance safely with default values
+- [ ] Implement error boundaries
+- [ ] Test with no credits (zero balance)
+- [ ] Test with loading states
+- [ ] Test with error states
+- [ ] Test refresh functionality
 
-### With Credit History
+### Common Patterns to Implement
 
-```typescript
-function CreditsWithHistory() {
-  const { credits, transactions, isLoading } = useCredits();
+1. **Balance Card**: Display credits with currency conversion
+2. **Transaction List**: Show recent credit activity
+3. **Low Credits Warning**: Alert when balance is low
+4. **Refresh Control**: Pull-to-refresh or button
+5. **Real-time Updates**: Use focus effect for auto-refresh
+6. **Purchase Prompt**: Link to credit packages when low
+7. **Skeletal Loading**: Show skeleton during initial load
+8. **Error Recovery**: Retry mechanism for failed fetches
 
-  return (
-    <View>
-      <BalanceDisplay credits={credits} />
+## Related Documentation
 
-      <Text style={styles.historyTitle}>Recent Transactions</Text>
-
-      {isLoading ? (
-        <ActivityIndicator />
-      ) : (
-        <FlatList
-          data={transactions}
-          keyExtractor={(item) => item.id}
-          renderItem={({ item }) => (
-            <TransactionItem
-              amount={item.amount}
-              reason={item.reason}
-              timestamp={item.timestamp}
-            />
-          )}
-        />
-      )}
-    </View>
-  );
-}
-```
-
-### With Balance Conversion
-
-```typescript
-function CreditsWithConversion() {
-  const { credits, balance } = useCredits();
-
-  const creditValue = 0.01; // 1 credit = $0.01
-
-  return (
-    <View>
-      <Text style={styles.credits}>{credits} Credits</Text>
-      <Text style={styles.balance}>
-        Worth approximately ${(balance || 0).toFixed(2)}
-      </Text>
-      <Text style={styles.info}>
-        (1 credit = ${(creditValue).toFixed(2)})
-      </Text>
-    </View>
-  );
-}
-```
-
-## Examples
-
-### Credits Balance Card
-
-```typescript
-function CreditsBalanceCard() {
-  const { credits, balance, isLoading } = useCredits();
-
-  if (isLoading) {
-    return <SkeletonLoader />;
-  }
-
-  return (
-    <Card style={styles.card}>
-      <Card.Header>
-        <Card.Title>Your Balance</Card.Title>
-      </Card.Header>
-
-      <Card.Body>
-        <View style={styles.balanceContainer}>
-          <Text style={styles.credits}>{credits}</Text>
-          <Text style={styles.label}>Credits</Text>
-        </View>
-
-        <View style={styles.balanceContainer}>
-          <Text style={styles.balance}>
-            ${(balance || 0).toFixed(2)}
-          </Text>
-          <Text style={styles.label}>Value</Text>
-        </View>
-      </Card.Body>
-
-      <Card.Footer>
-        <Button
-          onPress={() => navigation.navigate('CreditPackages')}
-          title="Get More Credits"
-          size="sm"
-        />
-      </Card.Footer>
-    </Card>
-  );
-}
-```
-
-### Credits Indicator
-
-```typescript
-function CreditsIndicator() {
-  const { credits } = useCredits();
-
-  return (
-    <TouchableOpacity
-      onPress={() => navigation.navigate('Wallet')}
-      style={styles.indicator}
-    >
-      <Icon name="coins" size={20} color="#FFD700" />
-      <Text style={styles.credits}>{credits}</Text>
-    </TouchableOpacity>
-  );
-}
-```
-
-### Low Credits Warning
-
-```typescript
-function LowCreditsWarning() {
-  const { credits } = useCredits();
-  const lowCreditThreshold = 10;
-
-  useEffect(() => {
-    if (credits <= lowCreditThreshold && credits > 0) {
-      notifications.show({
-        title: 'Low Credits',
-        body: `You have ${credits} credits remaining. Purchase more to continue using features.`,
-      });
-    }
-  }, [credits]);
-
-  if (credits <= lowCreditThreshold) {
-    return (
-      <Alert
-        severity={credits === 0 ? 'error' : 'warning'}
-        message={
-          credits === 0
-            ? 'No credits remaining. Purchase more to continue.'
-            : `Low credits: ${credits} remaining`
-        }
-        action={
-          <Button onPress={() => navigation.navigate('CreditPackages')}>
-            Get More
-          </Button>
-        }
-      />
-    );
-  }
-
-  return null;
-}
-```
-
-### Credits Usage Chart
-
-```typescript
-function CreditsUsageChart() {
-  const { transactions } = useCredits();
-
-  // Group transactions by date
-  const usageByDate = useMemo(() => {
-    const grouped = transactions.reduce((acc, tx) => {
-      const date = new Date(tx.timestamp).toDateString();
-      acc[date] = (acc[date] || 0) + Math.abs(tx.amount);
-      return acc;
-    }, {});
-
-    return Object.entries(grouped)
-      .map(([date, amount]) => ({ date, amount }))
-      .sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime())
-      .slice(-7); // Last 7 days
-  }, [transactions]);
-
-  return (
-    <View>
-      <Text>Credits Usage (Last 7 Days)</Text>
-
-      <LineChart
-        data={usageByDate}
-        xKey="date"
-        yKey="amount"
-        height={200}
-      />
-    </View>
-  );
-}
-```
-
-### Real-Time Balance Updates
-
-```typescript
-function RealtimeCreditsBalance() {
-  const { credits, refetch } = useCredits();
-
-  // Listen to credit updates
-  useEffect(() => {
-    const unsubscribe = creditsListener.on((newBalance) => {
-      console.log('Credits updated:', newBalance);
-      refetch();
-    });
-
-    return () => unsubscribe?.();
-  }, []);
-
-  return (
-    <View>
-      <Text>Credits: {credits}</Text>
-    </View>
-  );
-}
-```
-
-## Best Practices
-
-1. **Handle loading** - Show skeleton or spinner
-2. **Display balance** - Show both credits and value
-3. **Provide purchase option** - Link to credit packages
-4. **Show warnings** - Alert when credits are low
-5. **Track usage** - Display transaction history
-6. **Auto-refresh** - Keep balance up to date
-7. **Handle errors** - Show user-friendly messages
-
-## Related Hooks
-
-- **useCreditsGate** - For gating features with credits
-- **useDeductCredit** - For deducting credits
-- **useTransactionHistory** - For transaction list
-- **useWallet** - Wallet domain hook
-
-## See Also
-
-- [CreditsGate](./useCreditsGate.md)
-- [DeductCredit](./useDeductCredit.md)
-- [Wallet Domain](../../../domains/wallet/README.md)
+- **useDeductCredit**: Deduct credits from balance
+- **useCreditChecker**: Check credit availability before operations
+- **useInitializeCredits**: Initialize credits after purchase
+- **useCreditsGate**: Gate features behind credit requirements
+- **useFeatureGate**: Unified feature gating with credits
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
+- **Wallet Domain**: `src/domains/wallet/README.md`

package/src/presentation/hooks/useCredits.md.bak

@@ -0,0 +1,231 @@
+# useCredits Hook
+
+Hook for accessing and managing credits balance with real-time updates.
+
+## Location
+
+**Import Path**: `@umituz/react-native-subscription`
+
+**File**: `src/presentation/hooks/useCredits.ts`
+
+**Type**: Hook
+
+## Strategy
+
+### Data Fetching Flow
+
+1. **Initial Load**
+   - Fetch credits from repository on mount
+   - Cache results in TanStack Query
+   - Handle loading/error states
+
+2. **Real-time Updates**
+   - Subscribe to credit changes via repository listener
+   - Auto-update on balance changes
+   - Invalidate query on external modifications
+
+3. **Cache Management**
+   - Use TanStack Query for caching
+   - Background refetch on window focus
+   - Manual refetch capability
+
+### Integration Points
+
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/CreditsRepository.ts`
+- **Credits Entity**: `src/domains/wallet/domain/entities/UserCredits.ts`
+- **TanStack Query**: For cache management and background updates
+- **useFocusEffect**: For refresh on screen focus
+
+## Restrictions
+
+### REQUIRED
+
+- **User Authentication**: User MUST be authenticated to access credits
+- **Error Handling**: MUST handle error state in UI
+- **Loading State**: MUST show loading indicator while fetching
+
+### PROHIBITED
+
+- **NEVER** assume credits are available without checking loading state
+- **NEVER** use this hook for unauthenticated users
+- **DO NOT** mutate credits directly - use `useDeductCredit` instead
+- **DO NOT** call refetch excessively (causes unnecessary network calls)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** check `isLoading` before displaying credits
+- **ALWAYS** handle `error` state to prevent crashes
+- **NEVER** use `credits` value for security decisions (validate on backend)
+- **MUST** implement error boundaries when displaying balance
+
+## Rules
+
+### Basic Usage
+
+```typescript
+// CORRECT - Handle all states
+function CreditsDisplay() {
+  const { credits, isLoading, error } = useCredits();
+
+  if (isLoading) return <ActivityIndicator />;
+  if (error) return <ErrorDisplay error={error} />;
+
+  return <Text>Credits: {credits}</Text>;
+}
+
+// INCORRECT - No loading check
+function CreditsDisplay() {
+  const { credits } = useCredits();
+  return <Text>Credits: {credits}</Text>; // May show undefined
+}
+
+// INCORRECT - No error handling
+function CreditsDisplay() {
+  const { credits, isLoading, error } = useCredits();
+
+  if (isLoading) return <ActivityIndicator />;
+  return <Text>Credits: {credits}</Text>; // Crashes if error
+}
+```
+
+### Manual Refresh
+
+```typescript
+// CORRECT - Manual refetch with loading state
+function CreditsWithRefresh() {
+  const { credits, refetch, isLoading } = useCredits();
+
+  const handleRefresh = async () => {
+    await refetch();
+  };
+
+  return (
+    <Button onPress={handleRefresh} disabled={isLoading}>
+      Refresh
+    </Button>
+  );
+}
+
+// INCORRECT - Ignore loading state during refresh
+const handleRefresh = () => {
+  refetch(); // No loading indication
+};
+```
+
+### Transaction History
+
+```typescript
+// CORRECT - Display transactions with safety checks
+function CreditsWithHistory() {
+  const { credits, transactions, isLoading } = useCredits();
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <View>
+      <Text>Credits: {credits}</Text>
+      <FlatList
+        data={transactions || []}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <TransactionItem {...item} />}
+      />
+    </View>
+  );
+}
+
+// INCORRECT - Assume transactions exist
+<FlatList
+  data={transactions} // Crashes if undefined
+  keyExtractor={(item) => item.id}
+  renderItem={({ item }) => <TransactionItem {...item} />}
+/>
+```
+
+### Auto-Refresh Patterns
+
+```typescript
+// CORRECT - Refresh on focus with effect cleanup
+function AutoRefreshCredits() {
+  const { credits, refetch } = useCredits();
+
+  useFocusEffect(
+    useCallback(() => {
+      refetch();
+    }, [refetch])
+  );
+
+  return <Text>Credits: {credits}</Text>;
+}
+
+// INCORRECT - Missing dependency
+useFocusEffect(
+  useCallback(() => {
+    refetch();
+  }, []) // Missing refetch dependency
+);
+```
+
+### Balance Display
+
+```typescript
+// CORRECT - Safe balance display with formatting
+function BalanceDisplay() {
+  const { credits, balance, isLoading } = useCredits();
+
+  if (isLoading) return <Skeleton />;
+
+  return (
+    <View>
+      <Text>{credits} Credits</Text>
+      <Text>Value: ${(balance || 0).toFixed(2)}</Text>
+    </View>
+  );
+}
+
+// INCORRECT - Unsafe balance access
+<Text>Value: ${balance.toFixed(2)}</Text> // Crashes if undefined
+```
+
+## AI Agent Guidelines
+
+### When Implementing Credit Displays
+
+1. **Always** handle loading state explicitly
+2. **Always** handle error state gracefully
+3. **Always** provide manual refresh option
+4. **Always** format balance safely (handle undefined/null)
+5. **Never** use credits for security decisions (server-side validation required)
+
+### Integration Checklist
+
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Handle loading state in UI
+- [ ] Handle error state in UI
+- [ ] Provide refresh mechanism
+- [ ] Format balance safely with default values
+- [ ] Implement error boundaries
+- [ ] Test with no credits (zero balance)
+- [ ] Test with loading states
+- [ ] Test with error states
+- [ ] Test refresh functionality
+
+### Common Patterns to Implement
+
+1. **Balance Card**: Display credits with currency conversion
+2. **Transaction List**: Show recent credit activity
+3. **Low Credits Warning**: Alert when balance is low
+4. **Refresh Control**: Pull-to-refresh or button
+5. **Real-time Updates**: Use focus effect for auto-refresh
+6. **Purchase Prompt**: Link to credit packages when low
+7. **Skeletal Loading**: Show skeleton during initial load
+8. **Error Recovery**: Retry mechanism for failed fetches
+
+## Related Documentation
+
+- **useDeductCredit**: Deduct credits from balance
+- **useCreditChecker**: Check credit availability before operations
+- **useInitializeCredits**: Initialize credits after purchase
+- **useCreditsGate**: Gate features behind credit requirements
+- **useFeatureGate**: Unified feature gating with credits
+- **Credits Repository**: `src/domains/wallet/infrastructure/repositories/README.md`
+- **Wallet Domain**: `src/domains/wallet/README.md`