@umituz/react-native-subscription 2.14.98 → 2.14.100

package/src/domains/wallet/presentation/components/README.md

@@ -1,231 +1,41 @@
 # Wallet Presentation Components
 
+## Location
 UI components for wallet and credit display.
 
-## Overview
-
-This directory contains React Native components for displaying credits, transactions, and wallet information.
-
-## Components
-
-### CreditBalanceCard
-Card displaying current credit balance.
-
-```typescript
-interface CreditBalanceCardProps {
-  credits: number;
-  balance: number;
-  isLoading?: boolean;
-  onPress?: () => void;
-  onRefresh?: () => void;
-}
-```
-
-**Usage:**
-```typescript
-<CreditBalanceCard
-  credits={50}
-  balance={0.50}
-  onPress={() => navigation.navigate('CreditHistory')}
-  onRefresh={() => refetch()}
-/>
-```
-
-### TransactionItem
-Individual transaction display component.
-
-```typescript
-interface TransactionItemProps {
-  transaction: Transaction;
-  format?: 'full' | 'compact';
-}
-```
-
-**Usage:**
-```typescript
-<TransactionItem
-  transaction={{
-    id: 'tx_123',
-    amount: -5,
-    reason: 'AI Generation',
-    timestamp: new Date(),
-    type: 'deduction',
-  }}
-  format="full"
-/>
-```
-
-### CreditProgressBar
-Progress bar showing credit usage.
-
-```typescript
-interface CreditProgressBarProps {
-  current: number;
-  total: number;
-  showLabel?: boolean;
-  showPercentage?: boolean;
-  height?: number;
-}
-```
-
-**Usage:**
-```typescript
-<CreditProgressBar
-  current={50}
-  total={100}
-  showLabel={true}
-  showPercentage={true}
-  height={8}
-/>
-```
-
-### CreditPackageCard
-Display card for purchasable credit packages.
-
-```typescript
-interface CreditPackageCardProps {
-  package: {
-    id: string;
-    amount: number;
-    price: number;
-    bonus?: number;
-    currency: string;
-  };
-  onPress: () => void;
-  highlight?: boolean;
-}
-```
-
-**Usage:**
-```typescript
-<CreditPackageCard
-  package={{
-    id: 'premium_credits',
-    amount: 100,
-    price: 9.99,
-    bonus: 10,
-    currency: 'USD',
-  }}
-  onPress={() => purchaseCredits('premium_credits')}
-  highlight={true}
-/>
-```
-
-## Usage Patterns
-
-### Complete Credit Dashboard
-
-```typescript
-function CreditDashboard() {
-  const { credits, transactions, isLoading, refetch } = useCredits();
-
-  return (
-    <ScrollView>
-      <CreditBalanceCard
-        credits={credits}
-        balance={calculateBalance(credits)}
-        onRefresh={refetch}
-      />
-
-      <View style={styles.section}>
-        <Text style={styles.title}>Recent Transactions</Text>
-        {transactions.slice(0, 10).map(tx => (
-          <TransactionItem key={tx.id} transaction={tx} />
-        ))}
-      </View>
-
-      <Button onPress={() => navigation.navigate('CreditPackages')}>
-        Get More Credits
-      </Button>
-    </ScrollView>
-  );
-}
-```
-
-### Credit Warning Banner
-
-```typescript
-function LowCreditWarning() {
-  const { credits } = useCredits();
-  const warningThreshold = 20;
-
-  if (credits > warningThreshold) return null;
-
-  return (
-    <Banner type={credits === 0 ? 'error' : 'warning'}>
-      <Text>
-        {credits === 0
-          ? 'No credits remaining'
-          : `Only ${credits} credits left`
-        }
-      </Text>
-      <Button onPress={() => navigation.navigate('CreditPackages')}>
-        Get More
-      </Button>
-    </Banner>
-  );
-}
-```
-
-### Credit History List
-
-```typescript
-function TransactionHistory() {
-  const { transactions } = useCredits();
-
-  return (
-    <FlatList
-      data={transactions}
-      keyExtractor={(item) => item.id}
-      renderItem={({ item }) => (
-        <TransactionItem transaction={item} format="compact" />
-      )}
-      ListHeaderComponent={() => (
-        <Text style={styles.title}>Transaction History</Text>
-      )}
-      ListEmptyComponent={() => (
-        <EmptyState
-          icon="receipt"
-          title="No transactions yet"
-          message="Your credit transaction history will appear here"
-        />
-      )}
-    />
-  );
-}
-```
-
-## Styling
-
-Components use design system:
-
-```typescript
-import { useAppDesignTokens } from '@umituz/react-native-design-system';
-
-const tokens = useAppDesignTokens();
-
-const styles = StyleSheet.create({
-  card: {
-    backgroundColor: tokens.colors.surface,
-    borderRadius: tokens.radius.lg,
-    padding: tokens.spacing.lg,
-    marginBottom: tokens.spacing.md,
-  },
-});
-```
-
-## Best Practices
-
-1. **Visual Hierarchy**: Emphasize important information
-2. **Color Coding**: Use colors to indicate status (low/warning/good)
-3. **Loading States**: Show skeletons while loading
-4. **Empty States**: Provide helpful empty state messages
-5. **Refresh Capability**: Allow manual refresh
-6. **Transactional History**: Show clear transaction history
-7. **Purchase Links**: Easy access to purchase more credits
-
-## Related
-
+## Strategy
+This directory contains React Native components for displaying credits, transactions, and wallet information with clear visual hierarchy and status indicators.
+
+## Restrictions
+
+### REQUIRED
+- Must show loading states appropriately
+- Must provide empty state messages
+- Must allow manual refresh capability
+- Must display transaction history clearly
+
+### PROHIBITED
+- DO NOT hide credit balance from users
+- DO NOT show technical errors directly
+- DO NOT skip loading indicators
+- DO NOT obscure transaction details
+
+### CRITICAL SAFETY
+- Credit balance MUST always be visible
+- Status indicators MUST be color-coded appropriately
+- Transaction history MUST be complete and accurate
+- Purchase links MUST be easily accessible
+
+## AI Agent Guidelines
+1. Emphasize important information with visual hierarchy
+2. Use color coding to indicate status (low/warning/good)
+3. Show skeleton screens while loading data
+4. Provide helpful empty state messages
+5. Allow users to manually refresh credit data
+6. Display complete transaction history
+7. Make credit purchases easily accessible
+
+## Related Documentation
 - [Credit Row](../../../presentation/components/details/CreditRow.md)
 - [Credits Hook](../hooks/README.md)
 - [Wallet Domain](../../domain/README.md)

package/src/domains/wallet/presentation/hooks/README.md

@@ -1,255 +1,41 @@
 # Wallet Presentation Hooks
 
+## Location
 React hooks for wallet and credit functionality.
 
-## Overview
-
-This directory contains React hooks specifically for credit management and wallet operations.
-
-## Hooks
-
-### useCredits
-Access and manage credit balance.
-
-```typescript
-function useCredits(params: {
-  userId: string | undefined;
-  enabled?: boolean;
-}): {
-  credits: number;
-  balance: number;
-  transactions: Transaction[];
-  isLoading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
-}
-```
-
-**Usage:**
-```typescript
-function CreditBalance() {
-  const { credits, isLoading } = useCredits({ userId: user?.uid });
-
-  if (isLoading) return <LoadingSpinner />;
-
-  return (
-    <View>
-      <Text>Balance: {credits} credits</Text>
-    </View>
-  );
-}
-```
-
-### useDeductCredit
-Deduct credits with optimistic updates.
-
-```typescript
-function useDeductCredit(params: {
-  userId: string | undefined;
-  onCreditsExhausted?: () => void;
-}): {
-  deductCredit: (cost?: number) => Promise<boolean>;
-  deductCredits: (cost: number) => Promise<boolean>;
-  isDeducting: boolean;
-}
-```
-
-**Usage:**
-```typescript
-function AIGeneration() {
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-    onCreditsExhausted: () => showPaywall(),
-  });
-
-  const handleGenerate = async () => {
-    const success = await deductCredit(5);
-    if (success) {
-      await callAIGenerationAPI();
-    }
-  };
-}
-```
-
-### useInitializeCredits
-Initialize credits after purchase.
-
-```typescript
-function useInitializeCredits(params: {
-  userId: string | undefined;
-}): {
-  initializeCredits: (options?: {
-    purchaseId?: string;
-    productId?: string;
-  }) => Promise<boolean>;
-  isInitializing: boolean;
-}
-```
-
-**Usage:**
-```typescript
-function PurchaseCompletion() {
-  const { initializeCredits } = useInitializeCredits({
-    userId: user?.uid,
-  });
-
-  const handlePurchaseComplete = async (transaction: Purchase) => {
-    const success = await initializeCredits({
-      purchaseId: transaction.transactionId,
-      productId: transaction.productId,
-    });
-
-    if (success) {
-      Alert.alert('Success', 'Credits added!');
-    }
-  };
-}
-```
-
-### useCreditChecker
-Check credit availability before operations.
-
-```typescript
-function useCreditChecker(params?: {
-  onCreditDeducted?: (userId: string, cost: number) => void;
-}): {
-  checkCreditsAvailable: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<CreditCheckResult>;
-  deductCreditsAfterSuccess: (
-    userId: string | undefined,
-    cost?: number
-  ) => Promise<void>;
-}
-```
-
-**Usage:**
-```typescript
-function PreCheckFeature() {
-  const { checkCreditsAvailable } = useCreditChecker();
-
-  const handleCheck = async () => {
-    const result = await checkCreditsAvailable(user?.uid, 10);
-
-    if (!result.canProceed) {
-      Alert.alert(
-        'Insufficient Credits',
-        `You need ${result.required} credits but have ${result.currentBalance}`
-      );
-      return;
-    }
-
-    await executeFeature();
-  };
-}
-```
-
-## Usage Patterns
-
-### Two-Step Credit Process
-
-```typescript
-function TwoStepCreditProcess() {
-  const { checkCreditsAvailable } = useCreditChecker();
-  const { deductCreditsAfterSuccess } = useCreditChecker();
-
-  const handleOperation = async () => {
-    // Step 1: Check credits
-    const check = await checkCreditsAvailable(user?.uid, 10);
-
-    if (!check.canProceed) {
-      showPaywall({ required: 10 });
-      return;
-    }
-
-    try {
-      // Step 2: Perform operation
-      await performOperation();
-
-      // Step 3: Deduct credits after success
-      await deductCreditsAfterSuccess(user?.uid, 10);
-
-      Alert.alert('Success', 'Operation completed');
-    } catch (error) {
-      Alert.alert('Error', 'Operation failed');
-    }
-  };
-}
-```
-
-### With Loading and Error States
-
-```typescript
-function CreditOperation() {
-  const { credits, isLoading, error } = useCredits({ userId: user?.uid });
-  const { deductCredit } = useDeductCredit({
-    userId: user?.uid,
-  });
-
-  const handleDeduct = async () => {
-    if (isLoading) return;
-
-    const success = await deductCredit(5);
-
-    if (success) {
-      await executeFeature();
-    } else {
-      Alert.alert('Failed', 'Could not deduct credits');
-    }
-  };
-
-  return (
-    <View>
-      {error && <ErrorBanner message={error.message} />}
-      {isLoading ? (
-        <LoadingSpinner />
-      ) : (
-        <>
-          <Text>Credits: {credits}</Text>
-          <Button onPress={handleDeduct} disabled={isLoading}>
-            Use 5 Credits
-          </Button>
-        </>
-      )}
-    </View>
-  );
-}
-```
-
-### With Auto-Initialization
-
-```typescript
-function AutoInitialize() {
-  const { isPremium } = usePremium();
-  const { credits } = useCredits({ userId: user?.uid });
-  const { initializeCredits, isInitializing } = useInitializeCredits({
-    userId: user?.uid,
-  });
-
-  useEffect(() => {
-    // Auto-initialize if premium but no credits
-    if (isPremium && !credits && !isInitializing) {
-      initializeCredits();
-    }
-  }, [isPremium, credits]);
-
-  return <YourComponent />;
-}
-```
-
-## Best Practices
-
-1. **Check Balance First**: Always check before deducting
-2. **Handle Loading**: Show loading states appropriately
-3. **Error Recovery**: Handle deduction failures gracefully
-4. **Optimistic Updates**: Use optimistic updates for better UX
-5. **Track Usage**: Log all credit operations
-6. **Auto-Init**: Initialize credits after premium purchase
-7. **Test Scenarios**: Test zero credits, max credits, failures
-
-## Related
-
+## Strategy
+This directory contains React hooks specifically for credit management and wallet operations with optimistic updates and proper error handling.
+
+## Restrictions
+
+### REQUIRED
+- Must check balance before deducting
+- Must handle loading states appropriately
+- Must handle deduction failures gracefully
+- Must log all credit operations
+
+### PROHIBITED
+- DO NOT deduct credits without balance check
+- DO NOT skip error handling
+- DO NOT ignore loading states
+- DO NOT perform operations without tracking
+
+### CRITICAL SAFETY
+- Balance checks MUST precede all deductions
+- Deduction failures MUST be handled gracefully
+- Optimistic updates MUST support rollback
+- All operations MUST be logged
+
+## AI Agent Guidelines
+1. Always check credit balance before deducting
+2. Show appropriate loading states during operations
+3. Handle deduction failures with graceful recovery
+4. Use optimistic updates for better user experience
+5. Log all credit operations for debugging
+6. Initialize credits automatically after premium purchase
+7. Test edge cases: zero credits, max credits, failures
+
+## Related Documentation
 - [useCredits Hook Documentation](../../../presentation/hooks/useCredits.md)
 - [useDeductCredit Hook Documentation](../../../presentation/hooks/useDeductCredit.md)
 - [Credits Entity](../../domain/entities/README.md)