@umituz/react-native-subscription 2.14.97 → 2.14.98

package/src/presentation/hooks/useCredits.md

@@ -0,0 +1,342 @@
+# useCredits Hook
+
+Hook for accessing and managing credits balance.
+
+## Import
+
+```typescript
+import { useCredits } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+function useCredits(): {
+  credits: number;
+  balance: number;
+  transactions: Transaction[];
+  isLoading: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+```
+
+## Returns
+
+| 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 |
+
+## Basic Usage
+
+```typescript
+function CreditsDisplay() {
+  const { credits, isLoading } = useCredits();
+
+  if (isLoading) return <ActivityIndicator />;
+
+  return (
+    <View>
+      <Text>Your Credits: {credits}</Text>
+      <Text>Balance: ${balance.toFixed(2)}</Text>
+    </View>
+  );
+}
+```
+
+## Advanced Usage
+
+### With Refresh Control
+
+```typescript
+function CreditsWithRefresh() {
+  const { credits, refetch, isLoading } = useCredits();
+
+  const [refreshing, setRefreshing] = useState(false);
+
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    await refetch();
+    setRefreshing(false);
+  };
+
+  return (
+    <View>
+      <Text>Credits: {credits}</Text>
+
+      <Button
+        onPress={handleRefresh}
+        disabled={refreshing || isLoading}
+        title={refreshing ? 'Refreshing...' : 'Refresh'}
+      />
+    </View>
+  );
+}
+```
+
+### With Auto-Refresh
+
+```typescript
+function AutoRefreshCredits() {
+  const { credits, refetch } = useCredits();
+
+  // Refresh every 30 seconds
+  useEffect(() => {
+    const interval = setInterval(() => {
+      refetch();
+    }, 30000);
+
+    return () => clearInterval(interval);
+  }, [refetch]);
+
+  // Refresh when app comes to foreground
+  useFocusEffect(
+    useCallback(() => {
+      refetch();
+    }, [refetch])
+  );
+
+  return <Text>Credits: {credits}</Text>;
+}
+```
+
+### With Credit History
+
+```typescript
+function CreditsWithHistory() {
+  const { credits, transactions, isLoading } = useCredits();
+
+  return (
+    <View>
+      <BalanceDisplay credits={credits} />
+
+      <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)

package/src/presentation/hooks/useCreditsGate.md

@@ -0,0 +1,346 @@
+# useCreditsGate Hook
+
+Hook for gating features behind credit requirements.
+
+## Import
+
+```typescript
+import { useCreditsGate } from '@umituz/react-native-subscription';
+```
+
+## Signature
+
+```typescript
+function useCreditsGate(config: {
+  creditCost: number;
+  featureId: string;
+}): {
+  hasCredits: boolean;
+  credits: number;
+  consumeCredit: () => Promise<CreditsResult>;
+  isLoading: boolean;
+  showPurchasePrompt: () => void;
+}
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `config.creditCost` | `number` | Yes | Number of credits required |
+| `config.featureId` | `string` | Yes | Unique identifier for the feature |
+
+## Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `hasCredits` | `boolean` | Whether user has enough credits |
+| `credits` | `number` | Current credit balance |
+| `consumeCredit` | `() => Promise<CreditsResult>` | Function to consume credits |
+| `isLoading` | `boolean` | Whether hook is loading |
+| `showPurchasePrompt` | `() => void` | Show purchase prompt UI |
+
+## Basic Usage
+
+```typescript
+function CreditFeature() {
+  const { hasCredits, credits, consumeCredit } = useCreditsGate({
+    creditCost: 5,
+    featureId: 'export_data',
+  });
+
+  const handleExport = async () => {
+    if (!hasCredits) {
+      Alert.alert('Insufficient Credits', `You need 5 credits, have ${credits}`);
+      return;
+    }
+
+    const result = await consumeCredit();
+
+    if (result.success) {
+      await exportData();
+      Alert.alert('Success', `Data exported! ${result.newBalance} credits remaining`);
+    } else {
+      Alert.alert('Error', result.error?.message || 'Failed to consume credits');
+    }
+  };
+
+  return (
+    <Button
+      onPress={handleExport}
+      title={`Export Data (5 credits)`}
+      disabled={!hasCredits}
+    />
+  );
+}
+```
+
+## Advanced Usage
+
+### With Purchase Prompt
+
+```typescript
+function AdvancedCreditFeature() {
+  const { hasCredits, credits, consumeCredit, showPurchasePrompt } =
+    useCreditsGate({
+      creditCost: 10,
+      featureId: 'ai_analysis',
+    });
+
+  const handleAnalyze = async () => {
+    if (!hasCredits) {
+      showPurchasePrompt();
+      return;
+    }
+
+    const result = await consumeCredit();
+
+    if (result.success) {
+      await performAIAnalysis();
+    }
+  };
+
+  return (
+    <View>
+      <Text>Credits: {credits}</Text>
+      <Text>Cost: 10 credits</Text>
+
+      <Button
+        onPress={handleAnalyze}
+        title={hasCredits ? 'Analyze (10 credits)' : 'Get More Credits'}
+        disabled={!hasCredits && credits < 10}
+      />
+    </View>
+  );
+}
+```
+
+### With Transaction Tracking
+
+```typescript
+function TrackedCreditFeature() {
+  const { consumeCredit, hasCredits } = useCreditsGate({
+    creditCost: 3,
+    featureId: 'filter_apply',
+  });
+
+  const handleApplyFilter = async () => {
+    const result = await consumeCredit();
+
+    if (result.success) {
+      // Track usage
+      analytics.track('credit_consumed', {
+        feature_id: 'filter_apply',
+        amount: 3,
+        transaction_id: result.transaction?.id,
+      });
+
+      // Apply filter
+      await applyFilter();
+    }
+  };
+
+  return <Button onPress={handleApplyFilter} title="Apply Filter (3 credits)" />;
+}
+```
+
+### With Loading State
+
+```typescript
+function CreditFeatureWithLoading() {
+  const { consumeCredit, isLoading, hasCredits } = useCreditsGate({
+    creditCost: 5,
+    featureId: 'premium_template',
+  });
+
+  const handleUse = async () => {
+    if (!hasCredits) return;
+
+    const result = await consumeCredit();
+
+    if (result.success) {
+      // Show loading while processing
+      await processFeature();
+    }
+  };
+
+  return (
+    <View>
+      <Button
+        onPress={handleUse}
+        disabled={isLoading || !hasCredits}
+        title={isLoading ? 'Processing...' : 'Use Feature (5 credits)'}
+      />
+    </View>
+  );
+}
+```
+
+## Examples
+
+### Credit-Based Action Button
+
+```typescript
+function CreditActionButton({ featureId, cost, action, label }) {
+  const { hasCredits, credits, consumeCredit } = useCreditsGate({
+    creditCost: cost,
+    featureId,
+  });
+
+  const handlePress = async () => {
+    if (!hasCredits) {
+      showInsufficientCreditsDialog(cost, credits);
+      return;
+    }
+
+    const result = await consumeCredit();
+    if (result.success) {
+      await action();
+    }
+  };
+
+  return (
+    <TouchableOpacity
+      onPress={handlePress}
+      disabled={!hasCredits}
+      style={hasCredits ? styles.buttonEnabled : styles.buttonDisabled}
+    >
+      <Text style={styles.buttonText}>{label}</Text>
+      <Text style={styles.costText}>{cost} credits</Text>
+    </TouchableOpacity>
+  );
+}
+```
+
+### Credit Balance Display
+
+```typescript
+function CreditBalanceDisplay() {
+  const { credits, isLoading } = useCreditsGate({
+    creditCost: 1,
+    featureId: 'any',
+  });
+
+  return (
+    <View style={styles.balanceContainer}>
+      <Text style={styles.balanceLabel}>Your Credits:</Text>
+
+      {isLoading ? (
+        <ActivityIndicator size="small" />
+      ) : (
+        <Text style={styles.balanceValue}>{credits}</Text>
+      )}
+    </View>
+  );
+}
+```
+
+### Multiple Credit Tiers
+
+```typescript
+function TieredFeatureAccess() {
+  const { credits: basicCredits, hasCredits: hasBasic } = useCreditsGate({
+    creditCost: 5,
+    featureId: 'basic_feature',
+  });
+
+  const { credits: proCredits, hasCredits: hasPro } = useCreditsGate({
+    creditCost: 20,
+    featureId: 'pro_feature',
+  });
+
+  return (
+    <View>
+      <Button
+        onPress={handleBasicFeature}
+        disabled={!hasBasic}
+        title={`Basic Feature (5 credits)`}
+      />
+
+      <Button
+        onPress={handleProFeature}
+        disabled={!hasPro}
+        title={`Pro Feature (20 credits)`}
+      />
+
+      <Text>Balance: {basicCredits} credits</Text>
+    </View>
+  );
+}
+```
+
+## Result Type
+
+```typescript
+interface CreditsResult {
+  success: boolean;
+  newBalance?: number;
+  transaction?: {
+    id: string;
+    amount: number;
+    reason: string;
+    timestamp: string;
+  };
+  error?: Error;
+}
+```
+
+## Error Handling
+
+```typescript
+function RobustCreditFeature() {
+  const { consumeCredit } = useCreditsGate({
+    creditCost: 10,
+    featureId: 'robust_feature',
+  });
+
+  const handleAction = async () => {
+    const result = await consumeCredit();
+
+    if (!result.success) {
+      if (result.error?.message.includes('Insufficient')) {
+        Alert.alert('Insufficient Credits', 'Please purchase more credits');
+      } else if (result.error?.message.includes('Network')) {
+        Alert.alert('Network Error', 'Please check your connection');
+      } else {
+        Alert.alert('Error', 'Failed to process. Please try again');
+      }
+
+      // Log error
+      analytics.track('credit_consumption_failed', {
+        feature_id: 'robust_feature',
+        error: result.error?.message,
+      });
+      return;
+    }
+
+    // Success
+    await executeFeature();
+  };
+
+  return <Button onPress={handleAction} title="Execute (10 credits)" />;
+}
+```
+
+## Best Practices
+
+1. **Always check `hasCredits`** before enabling actions
+2. **Show credit cost** in UI
+3. **Handle errors gracefully**
+4. **Provide purchase prompt** when credits are insufficient
+5. **Display current balance**
+6. **Track credit consumption** in analytics
+7. **Refetch balance** after consumption
+
+## Related Hooks
+
+- **useCredits** - For credit balance only
+- **useDeductCredit** - For manual credit deduction
+- **usePremiumWithCredits** - For premium OR credits access
+- **useCreditChecker** - For simple credit checks
+
+## See Also
+
+- [useCredits](./useCredits.md)
+- [useDeductCredit](./useDeductCredit.md)
+- [usePremiumWithCredits](./usePremiumWithCredits.md)