@umituz/react-native-subscription 2.14.99 → 2.14.101

package/src/presentation/hooks/useSubscriptionGate.md

@@ -2,167 +2,83 @@
 
 Subscription-only feature gating with simple, focused API.
 
-## Import
-
-```typescript
-import { useSubscriptionGate } from '@umituz/react-native-subscription';
-```
-
-## Signature
-
-```typescript
-function useSubscriptionGate(params: {
-  hasSubscription: boolean;
-  onSubscriptionRequired: () => void;
-}): {
-  hasSubscription: boolean;
-  requireSubscription: (action: () => void | Promise<void>) => boolean;
-}
-```
-
-## Parameters
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `hasSubscription` | `boolean` | **Required** | Whether user has active subscription |
-| `onSubscriptionRequired` | `() => void` | **Required** | Callback when subscription is required |
-
-## Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `hasSubscription` | `boolean` | User has active subscription |
-| `requireSubscription` | `(action) => boolean` | Gate action behind subscription |
-
-## Basic Usage
-
-```typescript
-function PremiumFeature() {
-  const { isPremium } = usePremium();
-
-  const { requireSubscription, hasSubscription } = useSubscriptionGate({
-    hasSubscription: isPremium,
-    onSubscriptionRequired: () => {
-      showPaywall();
-    },
-  });
-
-  const handlePremiumAction = () => {
-    const allowed = requireSubscription(() => {
-      executePremiumFeature();
-    });
-
-    if (!allowed) {
-      console.log('User was shown paywall');
-    }
-  };
-
-  return (
-    <Button
-      onPress={handlePremiumAction}
-      title={hasSubscription ? 'Access' : 'Upgrade to Premium'}
-    />
-  );
-}
-```
-
-## Advanced Usage
-
-### With Conditional Rendering
-
-```typescript
-function ConditionalPremiumFeature() {
-  const { isPremium } = usePremium();
-
-  const { requireSubscription, hasSubscription } = useSubscriptionGate({
-    hasSubscription: isPremium,
-    onSubscriptionRequired: () => {
-      navigation.navigate('Paywall');
-    },
-  });
-
-  if (!hasSubscription) {
-    return (
-      <View>
-        <PremiumLockedIcon />
-        <Text>This feature requires Premium</Text>
-        <Button
-          onPress={() => requireSubscription(() => {})}
-          title="Upgrade Now"
-        />
-      </View>
-    );
-  }
-
-  return (
-    <View>
-      <Text>Premium Content</Text>
-      <PremiumFeatureComponent />
-    </View>
-  );
-}
-```
-
-### With Async Actions
-
-```typescript
-function AsyncPremiumFeature() {
-  const { isPremium } = usePremium();
-
-  const { requireSubscription } = useSubscriptionGate({
-    hasSubscription: isPremium,
-    onSubscriptionRequired: () => {
-      showPaywall({
-        feature: 'Advanced Analytics',
-        onSubscribe: () => {
-          // Action will execute after subscription
-        },
-      });
-    },
-  });
-
-  const handleExportData = () => {
-    requireSubscription(async () => {
-      await exportLargeDataset();
-      Alert.alert('Success', 'Data exported successfully');
-    });
-  };
-
-  return <Button onPress={handleExportData} title="Export Data" />;
-}
-```
-
-## Best Practices
-
-1. **Simple checks** - Keep gating logic straightforward
-2. **Clear messaging** - Tell users what they're missing
-3. **Smooth upgrades** - Make subscription path obvious
-4. **Track access** - Monitor gate triggers for optimization
-5. **Value first** - Show benefits before locking
-6. **Graceful fallbacks** - Show preview or limited version
-7. **Context-aware** - Customize paywall based on feature
-
-## Development Logging
-
-In development mode, the hook logs useful information:
-
-```typescript
-// User not premium
-[useSubscriptionGate] No subscription, showing paywall
-
-// User has subscription
-[useSubscriptionGate] Has subscription, proceeding
-```
-
-## Related Hooks
-
-- **useAuthGate** - Add authentication requirements
-- **useCreditsGate** - Credits-based gating
-- **useFeatureGate** - Combined auth + subscription + credits
-- **usePremiumGate** - Premium feature gating with auth option
-
-## See Also
-
-- [Subscription Gating](../../../docs/SUBSCRIPTION_GATING.md)
-- [Paywall Triggers](../screens/README.md#triggers)
-- [usePremium](./usePremium.md)
+## Location
+
+**Import Path**: `@umituz/react-native-subscription`
+
+**File**: `src/presentation/hooks/useSubscriptionGate.ts`
+
+**Type**: Hook
+
+## Strategy
+
+### Subscription Gating Flow
+
+1. **Subscription Check**: Verify if user has active subscription
+2. **Gate Function**: Provide requireSubscription function for gating
+3. **Action Wrapping**: Wrap actions behind subscription check
+4. **Callback Trigger**: Execute callback when subscription is required
+5. **Boolean Access**: Provide simple hasSubscription boolean for conditional rendering
+
+### Integration Points
+
+- **usePremium**: For subscription status check
+- **Paywall Domain**: For subscription upgrade flow
+- **Feature Gates**: For unified feature access control
+
+## Restrictions
+
+### REQUIRED
+
+- **Subscription Status**: MUST provide hasSubscription parameter
+- **Callback**: MUST implement onSubscriptionRequired callback
+- **Return Check**: SHOULD check return value from requireSubscription
+
+### PROHIBITED
+
+- **NEVER** show protected content without checking hasSubscription
+- **NEVER** use for security decisions without server validation
+- **DO NOT** assume subscription status (always verify)
+
+### CRITICAL SAFETY
+
+- **ALWAYS** verify hasSubscription before allowing access
+- **NEVER** trust client-side state for security
+- **MUST** implement proper upgrade flow
+- **ALWAYS** handle both subscribed and non-subscribed states
+
+## AI Agent Guidelines
+
+### When Implementing Subscription Gates
+
+1. **Always** check hasSubscription before showing protected content
+2. **Always** provide clear upgrade path in callback
+3. **Always** use requireSubscription for action gating
+4. **Never** bypass subscription checks
+5. **Always** test with both subscribed and non-subscribed users
+
+### Integration Checklist
+
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide hasSubscription from usePremium
+- [ ] Implement onSubscriptionRequired callback
+- [ ] Use requireSubscription for action gating
+- [ ] Check hasSubscription for conditional rendering
+- [ ] Test with subscribed user
+- [ ] Test with non-subscribed user
+- [ ] Verify upgrade flow triggers correctly
+
+### Common Patterns
+
+1. **Action Gating**: Use requireSubscription to wrap actions
+2. **Conditional Rendering**: Check hasSubscription for UI
+3. **Button States**: Disable buttons when not subscribed
+4. **Upgrade Prompts**: Show in callback when not subscribed
+
+## Related Documentation
+
+- **usePremium**: Subscription status check
+- **usePremiumGate**: Premium feature gating
+- **useAuthGate**: Auth + subscription gating
+- **useFeatureGate**: Unified feature gating
+- **Paywall Domain**: `src/domains/paywall/README.md`

package/src/presentation/hooks/useSubscriptionSettingsConfig.md

@@ -2,373 +2,93 @@
 
 Returns ready-to-use configuration for subscription settings screens.
 
-## Import
+## Location
 
-```typescript
-import {
-  useSubscriptionSettingsConfig,
-  type SubscriptionSettingsConfig
-} from '@umituz/react-native-subscription';
-```
+**Import Path**: `@umituz/react-native-subscription`
 
-## Signature
+**File**: `src/presentation/hooks/useSubscriptionSettingsConfig.ts`
 
-```typescript
-function useSubscriptionSettingsConfig(
-  params: UseSubscriptionSettingsConfigParams
-): SubscriptionSettingsConfig
+**Type**: Hook
 
-interface UseSubscriptionSettingsConfigParams {
-  userId: string | undefined;
-  translations: SubscriptionSettingsTranslations;
-  creditLimit?: number;
-  upgradePrompt?: UpgradePromptConfig;
-}
+## Strategy
 
-interface SubscriptionSettingsConfig {
-  enabled: boolean;
-  settingsItem: SettingsItemConfig;
-  sectionConfig: SectionConfig;
-}
-```
+### Settings Configuration Generation
 
-## Parameters
+1. **Data Aggregation**: Combine subscription, credits, and tier information
+2. **Status Determination**: Calculate status type (active/expired/free/canceled)
+3. **Date Formatting**: Format expiration and purchase dates
+4. **Credit Items**: Generate credit item list with optional limit
+5. **Translation Support**: Apply provided translations to all strings
+6. **Upgrade Prompt**: Optional upgrade prompt configuration
 
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `userId` | `string \| undefined` | **Required** | User ID |
-| `translations` | `SubscriptionSettingsTranslations` | **Required** | Localized strings |
-| `creditLimit` | `number` | `undefined` | Max credits to display |
-| `upgradePrompt` | `UpgradePromptConfig` | `undefined` | Upgrade prompt configuration |
+### Integration Points
 
-## Translations
+- **useSubscriptionStatus**: For subscription status details
+- **useCredits**: For credits information
+- **useUserTier**: For tier determination
+- **Settings UI**: For settings screen integration
+- **Translation System**: For localization support
 
-```typescript
-interface SubscriptionSettingsTranslations {
-  title: string;                    // e.g., "Subscription"
-  description: string;              // e.g., "Manage your subscription"
-  statusLabel: string;              // e.g., "Status"
-  statusActive: string;             // e.g., "Active"
-  statusExpired: string;            // e.g., "Expired"
-  statusFree: string;               // e.g., "Free"
-  statusCanceled: string;           // e.g., "Canceled"
-  expiresLabel: string;            // e.g., "Expires on"
-  purchasedLabel: string;          // e.g., "Purchased on"
-  lifetimeLabel: string;           // e.g., "Lifetime"
-  creditsTitle: string;            // e.g., "Credits"
-  remainingLabel: string;          // e.g., "remaining"
-  manageButton: string;            // e.g., "Manage Subscription"
-  upgradeButton: string;           // e.g., "Upgrade to Premium"
-}
-```
+## Restrictions
 
-## Basic Usage
+### REQUIRED
 
-```typescript
-function SubscriptionSettings() {
-  const { user } = useAuth();
+- **User ID**: MUST provide valid userId parameter
+- **Translations**: MUST provide all translation strings
+- **Null Handling**: MUST handle null dates and values
+- **Enabled Check**: MUST check config.enabled before use
 
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: {
-      title: 'Subscription',
-      description: 'Manage your subscription',
-      statusLabel: 'Status',
-      statusActive: 'Active',
-      statusExpired: 'Expired',
-      statusFree: 'Free',
-      statusCanceled: 'Canceled',
-      expiresLabel: 'Expires on',
-      purchasedLabel: 'Purchased on',
-      lifetimeLabel: 'Lifetime',
-      creditsTitle: 'Credits',
-      remainingLabel: 'remaining',
-      manageButton: 'Manage Subscription',
-      upgradeButton: 'Upgrade to Premium',
-    },
-  });
+### PROHIBITED
 
-  if (!config.enabled) return null;
+- **NEVER** use without providing all translations
+- **NEVER** assume config is enabled (check enabled flag)
+- **DO NOT** hardcode translation strings
+- **DO NOT** use without userId
 
-  return (
-    <SettingsSection>
-      <SettingsItem
-        title={config.settingsItem.title}
-        description={config.settingsItem.description}
-        onPress={config.settingsItem.onPress}
-        icon={config.settingsItem.icon}
-      />
-    </SettingsSection>
-  );
-}
-```
+### CRITICAL SAFETY
 
-## Advanced Usage
+- **ALWAYS** check config.enabled before rendering
+- **MUST** provide complete translation objects
+- **ALWAYS** handle null dates gracefully
+- **NEVER** trust client-side config for security
 
-### With Custom Translations
+## AI Agent Guidelines
 
-```typescript
-function LocalizedSettings() {
-  const { t } = useTranslation();
-  const { user } = useAuth();
+### When Implementing Settings Config
 
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: {
-      title: t('subscription.title'),
-      description: t('subscription.description'),
-      statusLabel: t('subscription.status_label'),
-      statusActive: t('subscription.status_active'),
-      statusExpired: t('subscription.status_expired'),
-      statusFree: t('subscription.status_free'),
-      statusCanceled: t('subscription.status_canceled'),
-      expiresLabel: t('subscription.expires_label'),
-      purchasedLabel: t('subscription.purchased_label'),
-      lifetimeLabel: t('subscription.lifetime_label'),
-      creditsTitle: t('subscription.credits_title'),
-      remainingLabel: t('subscription.remaining_label'),
-      manageButton: t('subscription.manage_button'),
-      upgradeButton: t('subscription.upgrade_button'),
-    },
-  });
+1. **Always** provide complete translations
+2. **Always** check config.enabled
+3. **Always** handle null dates
+4. **Always** format dates appropriately
+5. **Never** use for security decisions without server validation
 
-  return <SubscriptionConfigView config={config} />;
-}
-```
+### Integration Checklist
 
-### With Credit Limit
+- [ ] Import from correct path: `@umituz/react-native-subscription`
+- [ ] Provide valid userId
+- [ ] Provide complete translations
+- [ ] Check config.enabled
+- [ ] Handle null dates
+- [ ] Format dates appropriately
+- [ ] Apply credit limit if needed
+- [ ] Configure upgrade prompt if needed
+- [ ] Test with active subscription
+- [ ] Test with expired subscription
+- [ ] Test with free user
+- [ ] Test with lifetime subscription
 
-```typescript
-function SettingsWithCreditLimit() {
-  const { user } = useAuth();
+### Common Patterns
 
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: englishTranslations,
-    creditLimit: 10, // Only show up to 10 credit items
-  });
+1. **Settings List Item**: Quick access item in settings
+2. **Detailed Section**: Comprehensive subscription section
+3. **Localized Settings**: Use with translation libraries
+4. **Credit Limit**: Limit displayed credit items
+5. **Upgrade Prompt**: Show upgrade prompt for free users
 
-  return (
-    <ScrollView>
-      <SubscriptionSection config={config} />
-    </ScrollView>
-  );
-}
-```
+## Related Documentation
 
-### With Upgrade Prompt
-
-```typescript
-function SettingsWithUpgradePrompt() {
-  const { user } = useAuth();
-
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: englishTranslations,
-    upgradePrompt: {
-      showPrompt: true,
-      highlightBenefits: [
-        'Unlimited access',
-        'Priority support',
-        'Ad-free experience',
-      ],
-      discountOffer: 'Save 50% with annual plan',
-    },
-  });
-
-  return (
-    <View>
-      <SubscriptionSection config={config} />
-      {!config.sectionConfig.isPremium && config.sectionConfig.upgradePrompt && (
-        <UpgradePromptCard prompt={config.sectionConfig.upgradePrompt} />
-      )}
-    </View>
-  );
-}
-```
-
-### Complete Subscription Settings Screen
-
-```typescript
-function SubscriptionSettingsScreen() {
-  const { user } = useAuth();
-
-  const config = useSubscriptionSettingsConfig({
-    userId: user?.uid,
-    translations: {
-      title: 'Subscription',
-      description: 'Manage your subscription',
-      statusLabel: 'Status',
-      statusActive: 'Active',
-      statusExpired: 'Expired',
-      statusFree: 'Free',
-      statusCanceled: 'Canceled',
-      expiresLabel: 'Expires on',
-      purchasedLabel: 'Purchased on',
-      lifetimeLabel: 'Lifetime',
-      creditsTitle: 'Credits',
-      remainingLabel: 'remaining',
-      manageButton: 'Manage Subscription',
-      upgradeButton: 'Upgrade to Premium',
-    },
-    creditLimit: 8,
-    upgradePrompt: {
-      showPrompt: true,
-      highlightBenefits: [
-        'Unlimited access to all features',
-        'Priority customer support',
-        'Ad-free experience',
-      ],
-    },
-  });
-
-  if (!config.enabled) return null;
-
-  const { settingsItem, sectionConfig } = config;
-
-  return (
-    <ScrollView style={styles.container}>
-      {/* Settings List Item */}
-      <SettingsList>
-        <SettingsListItem
-          title={settingsItem.title}
-          description={settingsItem.description}
-          icon={settingsItem.icon}
-          onPress={settingsItem.onPress}
-          badge={settingsItem.statusLabel}
-        />
-      </SettingsList>
-
-      {/* Detailed Section */}
-      <Card style={styles.card}>
-        <Card.Title>{sectionConfig.translations.title}</Card.Title>
-
-        <View style={styles.section}>
-          <DetailRow
-            label={sectionConfig.translations.statusLabel}
-            value={sectionConfig.statusType === 'active'
-              ? sectionConfig.translations.statusActive
-              : sectionConfig.statusType === 'expired'
-              ? sectionConfig.translations.statusExpired
-              : sectionConfig.translations.statusFree}
-          />
-
-          {sectionConfig.expirationDate && (
-            <DetailRow
-              label={sectionConfig.translations.expiresLabel}
-              value={sectionConfig.expirationDate}
-            />
-          )}
-
-          {sectionConfig.purchaseDate && (
-            <DetailRow
-              label={sectionConfig.translations.purchasedLabel}
-              value={sectionConfig.purchaseDate}
-            />
-          )}
-
-          {sectionConfig.isLifetime && (
-            <DetailRow
-              label=""
-              value={sectionConfig.translations.lifetimeLabel}
-            />
-          )}
-        </View>
-
-        {/* Credits Section */}
-        {sectionConfig.credits.length > 0 && (
-          <View style={styles.section}>
-            <Text style={styles.creditsTitle}>
-              {sectionConfig.translations.creditsTitle}
-            </Text>
-            {sectionConfig.credits.map((credit, index) => (
-              <View key={index} style={styles.creditItem}>
-                <Icon name="coin" size={16} />
-                <Text>{credit.amount}</Text>
-                <Text>{sectionConfig.translations.remainingLabel}</Text>
-              </View>
-            ))}
-          </View>
-        )}
-
-        {/* Actions */}
-        <View style={styles.actions}>
-          {sectionConfig.onUpgrade && !sectionConfig.isPremium && (
-            <Button
-              onPress={sectionConfig.onUpgrade}
-              title={sectionConfig.translations.upgradeButton}
-            />
-          )}
-
-          {sectionConfig.isPremium && (
-            <Button
-              onPress={() => Linking.openURL('https://apps.apple.com/account/subscriptions')}
-              title={sectionConfig.translations.manageButton}
-              variant="outline"
-            />
-          )}
-        </View>
-      </Card>
-    </ScrollView>
-  );
-}
-```
-
-## Configuration Object
-
-### settingsItem
-
-Quick access item for settings list:
-
-```typescript
-interface SettingsItemConfig {
-  title: string;           // "Subscription"
-  description: string;     // "Manage your subscription"
-  isPremium: boolean;      // Premium status
-  statusLabel: string;     // "Active" or "Free"
-  icon: string;           // "diamond"
-  onPress: () => void;    // Open paywall
-}
-```
-
-### sectionConfig
-
-Detailed section configuration:
-
-```typescript
-interface SectionConfig {
-  statusType: 'active' | 'expired' | 'free' | 'canceled';
-  isPremium: boolean;
-  expirationDate: string | null;      // "January 15, 2024"
-  purchaseDate: string | null;        // "January 15, 2023"
-  isLifetime: boolean;
-  daysRemaining: number | null;       // 30
-  willRenew: boolean;
-  credits: CreditItem[];
-  translations: SubscriptionSettingsTranslations;
-  onUpgrade: () => void;
-  upgradePrompt?: UpgradePromptConfig;
-}
-```
-
-## Best Practices
-
-1. **Provide all translations** - Ensure all strings are localized
-2. **Handle null values** - Dates may be null for lifetime subs
-3. **Use credit limit** - Limit credit items for better UX
-4. **Customize upgrade prompt** - Tailor to your app's benefits
-5. **Test all states** - Active, expired, free, lifetime
-6. **Handle navigation** - Implement onPress handlers
-7. **Format dates** - Use locale-appropriate formatting
-
-## Related Hooks
-
-- **useSubscriptionStatus** - For subscription status details
-- **useCredits** - For credits information
-- **useSubscriptionDetails** - For package and pricing info
-
-## See Also
-
-- [Settings Screen](../screens/README.md#settings)
-- [Subscription Utilities](../utils/subscriptionDateUtils.md)
-- [Config Types](../types/SubscriptionSettingsTypes.md)
+- **useSubscriptionStatus**: For subscription status details
+- **useCredits**: For credits information
+- **useSubscriptionDetails**: For package and pricing info
+- **Settings Screen**: `src/presentation/screens/README.md`
+- **Subscription Utilities**: `src/utils/subscriptionDateUtils.md`