@umituz/react-native-subscription 2.27.65 → 2.27.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.27.65",
+  "version": "2.27.67",
   "description": "Complete subscription management with RevenueCat, paywall UI, and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -55,7 +55,9 @@
     "@tanstack/query-async-storage-persister": "^5.66.7",
     "@tanstack/react-query": "^5.0.0",
     "@tanstack/react-query-persist-client": "^5.66.7",
+    "@types/jest": "^30.0.0",
     "@types/react": "~19.1.10",
+    "@types/react-native": "^0.72.8",
     "@typescript-eslint/eslint-plugin": "^8.50.1",
     "@typescript-eslint/parser": "^8.50.1",
     "@umituz/react-native-auth": "^3.6.14",

package/src/domains/credits/application/CreditLimitCalculator.ts

@@ -0,0 +1,17 @@
+import type { CreditsConfig } from "../../domain/entities/Credits";
+import { detectPackageType } from "../../utils/packageTypeDetector";
+import { getCreditAllocation } from "../../utils/creditMapper";
+
+export class CreditLimitCalculator {
+  static calculate(productId: string | undefined, config: CreditsConfig): number {
+    if (!productId) return config.creditLimit;
+
+    const explicitAmount = config.creditPackageAmounts?.[productId];
+    if (explicitAmount) return explicitAmount;
+
+    const packageType = detectPackageType(productId);
+    const dynamicLimit = getCreditAllocation(packageType, config.packageAllocations);
+    
+    return dynamicLimit ?? config.creditLimit;
+  }
+}

package/src/domains/credits/application/CreditsInitializer.ts

@@ -0,0 +1,85 @@
+import { Platform } from "react-native";
+import Constants from "expo-constants";
+import {
+  runTransaction,
+  serverTimestamp,
+  Timestamp,
+  type Firestore,
+  type Transaction,
+  type DocumentReference,
+} from "firebase/firestore";
+import type { CreditsConfig } from "../core/Credits";
+import type { UserCreditsDocumentRead } from "../core/UserCreditsDocument";
+import { resolveSubscriptionStatus } from "../../subscription/core/SubscriptionStatus";
+import { CreditLimitCalculator } from "./CreditLimitCalculator";
+import { PurchaseMetadataGenerator } from "./PurchaseMetadataGenerator";
+import { creditAllocationContext } from "./credit-strategies/CreditAllocationContext";
+import type { InitializeCreditsMetadata, InitializationResult } from "../../subscription/application/SubscriptionInitializerTypes";
+
+export async function initializeCreditsTransaction(
+    db: Firestore,
+    creditsRef: DocumentReference,
+    config: CreditsConfig,
+    purchaseId?: string,
+    metadata?: InitializeCreditsMetadata
+): Promise<InitializationResult> {
+    return runTransaction(db, async (transaction: Transaction) => {
+        const creditsDoc = await transaction.get(creditsRef);
+        const now = serverTimestamp();
+        const existingData = creditsDoc.exists() ? creditsDoc.data() as UserCreditsDocumentRead : null;
+
+        if (existingData && purchaseId && existingData.processedPurchases?.includes(purchaseId)) {
+            return { credits: existingData.credits, alreadyProcessed: true };
+        }
+
+        const creditLimit = CreditLimitCalculator.calculate(metadata?.productId, config);
+        const { purchaseType, purchaseHistory } = PurchaseMetadataGenerator.generate({
+          productId: metadata?.productId,
+          source: metadata?.source,
+          type: metadata?.type,
+          creditLimit,
+          platform: Platform.OS as "ios" | "android",
+          appVersion: Constants.expoConfig?.version,
+        }, existingData);
+
+        const isPremium = metadata?.isPremium ?? true;
+        const isExpired = metadata?.expirationDate ? new Date(metadata.expirationDate).getTime() < Date.now() : false;
+        const status = resolveSubscriptionStatus({ 
+          isPremium, willRenew: metadata?.willRenew, isExpired, periodType: metadata?.periodType 
+        });
+
+        // Resolve credits using Strategy Pattern
+        const isStatusSync = purchaseId?.startsWith("status_sync_") ?? false;
+        const isSubscriptionActive = isPremium && !isExpired;
+
+        const newCredits = creditAllocationContext.allocate({
+            status,
+            isStatusSync,
+            existingData,
+            creditLimit,
+            isSubscriptionActive
+        });
+
+        const creditsData: Record<string, any> = {
+            isPremium, status, credits: newCredits, creditLimit, 
+            lastUpdatedAt: now, 
+            processedPurchases: (purchaseId ? [...(existingData?.processedPurchases || []), purchaseId].slice(-10) : existingData?.processedPurchases) || [],
+            purchaseHistory: purchaseHistory.length ? purchaseHistory : undefined
+        };
+
+        const isNewPurchaseOrRenewal = purchaseId?.startsWith("purchase_") || purchaseId?.startsWith("renewal_");
+        if (isNewPurchaseOrRenewal) creditsData.lastPurchaseAt = now;
+        if (metadata?.expirationDate) creditsData.expirationDate = Timestamp.fromDate(new Date(metadata.expirationDate));
+        if (metadata?.willRenew !== undefined) creditsData.willRenew = metadata.willRenew;
+        if (metadata?.originalTransactionId) creditsData.originalTransactionId = metadata.originalTransactionId;
+        if (metadata?.productId) {
+            creditsData.productId = metadata.productId;
+            creditsData.platform = Platform.OS;
+        }
+
+        transaction.set(creditsRef, creditsData, { merge: true });
+        
+        const finalData = { ...(existingData || {}), ...creditsData } as UserCreditsDocumentRead;
+        return { credits: newCredits, finalData };
+    });
+}

package/src/domains/credits/application/DeductCreditsCommand.ts

@@ -0,0 +1,52 @@
+import { runTransaction, serverTimestamp, type Firestore, type Transaction, type DocumentReference } from "firebase/firestore";
+import { getFirestore } from "@umituz/react-native-firebase";
+import type { DeductCreditsResult } from "../../../domain/entities/Credits";
+import { subscriptionEventBus, SUBSCRIPTION_EVENTS } from "../SubscriptionEventBus";
+
+export interface IDeductCreditsCommand {
+  execute(userId: string, cost: number): Promise<DeductCreditsResult>;
+}
+
+/**
+ * Command for deducting credits.
+ * Encapsulates the domain rules and transaction logic for credit usage.
+ */
+export class DeductCreditsCommand implements IDeductCreditsCommand {
+  constructor(
+    private getCreditsRef: (db: Firestore, userId: string) => DocumentReference
+  ) {}
+
+  async execute(userId: string, cost: number = 1): Promise<DeductCreditsResult> {
+    const db = getFirestore();
+    if (!db) return { success: false, error: { message: "No DB", code: "ERR" } };
+
+    try {
+      const remaining = await runTransaction(db, async (tx: Transaction) => {
+        const ref = this.getCreditsRef(db, userId);
+        const docSnap = await tx.get(ref);
+        
+        if (!docSnap.exists()) throw new Error("NO_CREDITS");
+        
+        const current = docSnap.data().credits as number;
+        if (current < cost) throw new Error("CREDITS_EXHAUSTED");
+        
+        const updated = current - cost;
+        tx.update(ref, { 
+            credits: updated, 
+            lastUpdatedAt: serverTimestamp() 
+        });
+        
+        return updated;
+      });
+
+      // Emit event via EventBus (Observer Pattern)
+      subscriptionEventBus.emit(SUBSCRIPTION_EVENTS.CREDITS_UPDATED, userId);
+
+      return { success: true, remainingCredits: remaining };
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      const code = message === "NO_CREDITS" || message === "CREDITS_EXHAUSTED" ? message : "DEDUCT_ERR";
+      return { success: false, error: { message, code } };
+    }
+  }
+}

package/src/domains/credits/application/PurchaseMetadataGenerator.ts

@@ -0,0 +1,59 @@
+import { Timestamp } from "firebase/firestore";
+import type { 
+  PurchaseType, 
+  PurchaseMetadata,
+  UserCreditsDocumentRead,
+  PurchaseSource
+} from "../models/UserCreditsDocument";
+import { detectPackageType } from "../../utils/packageTypeDetector";
+
+export interface MetadataGeneratorConfig {
+  productId?: string;
+  source?: PurchaseSource;
+  type?: PurchaseType;
+  creditLimit: number;
+  platform: "ios" | "android";
+  appVersion?: string;
+}
+
+export class PurchaseMetadataGenerator {
+  static generate(
+    config: MetadataGeneratorConfig,
+    existingData: UserCreditsDocumentRead | null
+  ): { purchaseType: PurchaseType; purchaseHistory: PurchaseMetadata[] } {
+    const { productId, source, type, creditLimit, platform, appVersion } = config;
+    
+    if (!productId || !source) {
+      return { 
+        purchaseType: type ?? "initial", 
+        purchaseHistory: existingData?.purchaseHistory || [] 
+      };
+    }
+
+    const packageType = detectPackageType(productId);
+    let purchaseType: PurchaseType = type ?? "initial";
+
+    if (existingData?.packageType && packageType !== "unknown") {
+      const oldLimit = existingData.creditLimit || 0;
+      if (creditLimit > oldLimit) purchaseType = "upgrade";
+      else if (creditLimit < oldLimit) purchaseType = "downgrade";
+      // This check is a bit fragile if purchaseId is not passed here, 
+      // but we use the explicit 'type' if provided.
+    }
+
+    const newMetadata: PurchaseMetadata = {
+      productId,
+      packageType,
+      creditLimit,
+      source,
+      type: purchaseType,
+      platform,
+      appVersion,
+      timestamp: Timestamp.fromDate(new Date()) as any,
+    };
+
+    const purchaseHistory = [...(existingData?.purchaseHistory || []), newMetadata].slice(-10);
+
+    return { purchaseType, purchaseHistory };
+  }
+}

package/src/domains/credits/application/credit-strategies/CreditAllocationContext.ts

@@ -0,0 +1,35 @@
+import type { ICreditStrategy, CreditAllocationParams } from "./ICreditStrategy";
+import { SyncCreditStrategy } from "./SyncCreditStrategy";
+import { TrialCreditStrategy } from "./TrialCreditStrategy";
+import { StandardPurchaseCreditStrategy } from "./StandardPurchaseCreditStrategy";
+
+/**
+ * Strategy Context to coordinate credit allocation logic using the Strategy Pattern.
+ */
+export class CreditAllocationContext {
+    private strategies: ICreditStrategy[] = [
+        new SyncCreditStrategy(),
+        new TrialCreditStrategy(),
+        new StandardPurchaseCreditStrategy(), // Fallback strategy
+    ];
+
+    /**
+     * Finds the first applicable strategy and executes its logic.
+     */
+    allocate(params: CreditAllocationParams): number {
+        const strategy = this.strategies.find(s => s.canHandle(params));
+        
+        if (!strategy) {
+            // Should theoretically never happen due to StandardPurchaseCreditStrategy fallback
+            return params.creditLimit;
+        }
+
+        if (__DEV__) {
+            console.log(`[CreditAllocationContext] Using strategy: ${strategy.constructor.name}`);
+        }
+
+        return strategy.execute(params);
+    }
+}
+
+export const creditAllocationContext = new CreditAllocationContext();

package/src/domains/credits/application/credit-strategies/ICreditStrategy.ts

@@ -0,0 +1,18 @@
+import type { SubscriptionStatusType } from "../../domain/entities/SubscriptionStatus";
+import type { UserCreditsDocumentRead } from "../models/UserCreditsDocument";
+
+export interface CreditStrategyParams {
+    status: SubscriptionStatusType;
+    isStatusSync: boolean;
+    existingData: UserCreditsDocumentRead | null;
+    creditLimit: number;
+    isSubscriptionActive: boolean;
+}
+
+export interface ICreditStrategy {
+    canHandle(params: CreditAllocationParams): boolean;
+    execute(params: CreditAllocationParams): number;
+}
+
+// Renaming the input for clarity
+export type CreditAllocationParams = CreditStrategyParams;

package/src/domains/credits/application/credit-strategies/StandardPurchaseCreditStrategy.ts

@@ -0,0 +1,16 @@
+import { ICreditStrategy, type CreditAllocationParams } from "./ICreditStrategy";
+
+/**
+ * Default strategy for new purchases, renewals, or upgrades.
+ * Resets credits to the calculated credit limit.
+ */
+export class StandardPurchaseCreditStrategy implements ICreditStrategy {
+    canHandle(_params: CreditAllocationParams): boolean {
+        // This is a catch-all strategy
+        return true;
+    }
+
+    execute(params: CreditAllocationParams): number {
+        return params.creditLimit;
+    }
+}

package/src/domains/credits/application/credit-strategies/SyncCreditStrategy.ts

@@ -0,0 +1,15 @@
+import { ICreditStrategy, type CreditAllocationParams } from "./ICreditStrategy";
+
+/**
+ * Strategy for existing premium users during a simple status synchronization.
+ * Preserves their current credits to avoid accidental resets.
+ */
+export class SyncCreditStrategy implements ICreditStrategy {
+    canHandle(params: CreditAllocationParams): boolean {
+        return params.isStatusSync && params.existingData?.isPremium === true && params.isSubscriptionActive;
+    }
+
+    execute(params: CreditAllocationParams): number {
+        return params.existingData?.credits ?? params.creditLimit;
+    }
+}

package/src/domains/credits/application/credit-strategies/TrialCreditStrategy.ts

@@ -0,0 +1,18 @@
+import { ICreditStrategy, type CreditAllocationParams } from "./ICreditStrategy";
+import { SUBSCRIPTION_STATUS } from "../../../domain/entities/SubscriptionStatus";
+import { TRIAL_CONFIG } from "../TrialService";
+
+/**
+ * Strategy for Trial and Trial Canceled users.
+ * Allocates credits based on trial configuration.
+ */
+export class TrialCreditStrategy implements ICreditStrategy {
+    canHandle(params: CreditAllocationParams): boolean {
+        return params.status === SUBSCRIPTION_STATUS.TRIAL || 
+               params.status === SUBSCRIPTION_STATUS.TRIAL_CANCELED;
+    }
+
+    execute(_params: CreditAllocationParams): number {
+        return TRIAL_CONFIG.CREDITS;
+    }
+}

package/src/{infrastructure/mappers → domains/credits/core}/CreditsMapper.ts

@@ -1,7 +1,7 @@
-import type { UserCredits } from "../../domain/entities/Credits";
-import { resolveSubscriptionStatus } from "../../domain/entities/SubscriptionStatus";
-import type { PeriodType, SubscriptionStatusType } from "../../domain/entities/SubscriptionConstants";
-import type { UserCreditsDocumentRead } from "../models/UserCreditsDocument";
+import type { UserCredits } from "./Credits";
+import { resolveSubscriptionStatus } from "../../subscription/core/SubscriptionStatus";
+import type { PeriodType, SubscriptionStatusType } from "../../subscription/core/SubscriptionConstants";
+import type { UserCreditsDocumentRead } from "./UserCreditsDocument";
 
 /** Maps Firestore document to domain entity with expiration validation */
 export class CreditsMapper {

package/src/domains/credits/infrastructure/CreditsRepository.ts

@@ -0,0 +1,102 @@
+/**
+ * Credits Repository
+ * Optimized to use Design Patterns: Command, Observer, and Strategy.
+ */
+
+import { doc, getDoc, serverTimestamp, updateDoc, type Firestore } from "firebase/firestore";
+import { BaseRepository, getFirestore } from "@umituz/react-native-firebase";
+import type { CreditsConfig, CreditsResult, DeductCreditsResult } from "../core/Credits";
+import type { UserCreditsDocumentRead, PurchaseSource } from "../core/UserCreditsDocument";
+import { initializeCreditsTransaction } from "../application/CreditsInitializer";
+import { CreditsMapper } from "../core/CreditsMapper";
+import type { RevenueCatData } from "../../subscription/core/RevenueCatData";
+import { DeductCreditsCommand } from "../application/DeductCreditsCommand";
+import { CreditLimitCalculator } from "../application/CreditLimitCalculator";
+
+export class CreditsRepository extends BaseRepository {
+  private deductCommand: DeductCreditsCommand;
+
+  constructor(private config: CreditsConfig) { 
+    super(); 
+    this.deductCommand = new DeductCreditsCommand((db, uid) => this.getRef(db, uid));
+  }
+
+  private getRef(db: Firestore, userId: string) {
+    return this.config.useUserSubcollection
+      ? doc(db, "users", userId, "credits", "balance")
+      : doc(db, this.config.collectionName, userId);
+  }
+
+  async getCredits(userId: string): Promise<CreditsResult> {
+    const db = getFirestore();
+    if (!db) return { success: false, error: { message: "No DB", code: "DB_ERR" } };
+    try {
+      const snap = await getDoc(this.getRef(db, userId));
+      if (!snap.exists()) return { success: true, data: undefined };
+      
+      const entity = CreditsMapper.toEntity(snap.data() as UserCreditsDocumentRead);
+      return { success: true, data: entity };
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      return { success: false, error: { message, code: "FETCH_ERR" } };
+    }
+  }
+
+  async initializeCredits(
+    userId: string, purchaseId?: string, productId?: string,
+    source?: PurchaseSource, revenueCatData?: RevenueCatData
+  ): Promise<CreditsResult> {
+    const db = getFirestore();
+    if (!db) return { success: false, error: { message: "No DB", code: "INIT_ERR" } };
+    try {
+      // Use CreditLimitCalculator (Refactoring Logic)
+      const creditLimit = CreditLimitCalculator.calculate(productId, this.config);
+      const cfg = { ...this.config, creditLimit };
+
+      const result = await initializeCreditsTransaction(db, this.getRef(db, userId), cfg, purchaseId, {
+        productId, source,
+        expirationDate: revenueCatData?.expirationDate,
+        willRenew: revenueCatData?.willRenew,
+        originalTransactionId: revenueCatData?.originalTransactionId,
+        isPremium: revenueCatData?.isPremium,
+        periodType: revenueCatData?.periodType,
+      });
+      
+      return {
+        success: true,
+        data: result.finalData ? CreditsMapper.toEntity(result.finalData) : undefined,
+      };
+    } catch (e: unknown) {
+      const message = e instanceof Error ? e.message : String(e);
+      return { success: false, error: { message, code: "INIT_ERR" } };
+    }
+  }
+
+  /**
+   * Delegates to DeductCreditsCommand (Command Pattern)
+   */
+  async deductCredit(userId: string, cost: number = 1): Promise<DeductCreditsResult> {
+    return this.deductCommand.execute(userId, cost);
+  }
+
+  async hasCredits(userId: string, cost: number = 1): Promise<boolean> {
+    const res = await this.getCredits(userId);
+    return !!(res.success && res.data && res.data.credits >= cost);
+  }
+
+  async syncExpiredStatus(userId: string): Promise<void> {
+    const db = getFirestore();
+    if (!db) return;
+    try {
+      await updateDoc(this.getRef(db, userId), { 
+        isPremium: false, 
+        status: "expired", 
+        lastUpdatedAt: serverTimestamp() 
+      });
+    } catch (e) {
+      if (__DEV__) console.error("[CreditsRepository] Sync expired failed:", e);
+    }
+  }
+}
+
+export const createCreditsRepository = (c: CreditsConfig) => new CreditsRepository(c);

package/src/{presentation/hooks → domains/credits/presentation}/useCredits.ts

@@ -5,15 +5,16 @@
  * Uses status-based state management for reliable loading detection.
  */
 
-import { useQuery } from "@umituz/react-native-design-system";
-import { useCallback, useMemo } from "react";
+import { useQuery, useQueryClient } from "@umituz/react-native-design-system";
+import { useCallback, useMemo, useEffect } from "react";
 import { useAuthStore, selectUserId } from "@umituz/react-native-auth";
-import type { UserCredits } from "../../domain/entities/Credits";
+import { subscriptionEventBus, SUBSCRIPTION_EVENTS } from "../../../shared/infrastructure/SubscriptionEventBus";
+import type { UserCredits } from "../core/Credits";
 import {
   getCreditsRepository,
   getCreditsConfig,
   isCreditsRepositoryConfigured,
-} from "../../infrastructure/repositories/CreditsRepositoryProvider";
+} from "../infrastructure/CreditsRepositoryProvider";
 
 export const creditsQueryKeys = {
   all: ["credits"] as const,
@@ -90,6 +91,22 @@ export const useCredits = (): UseCreditsResult => {
     refetchOnReconnect: true,
   });
 
+  const queryClient = useQueryClient();
+
+  // Observer Pattern: Listen for credit updates
+  useEffect(() => {
+    if (!userId) return;
+    
+    const unsubscribe = subscriptionEventBus.on(SUBSCRIPTION_EVENTS.CREDITS_UPDATED, (updatedUserId) => {
+      if (updatedUserId === userId) {
+        if (__DEV__) console.log("[useCredits] Event received: CREDITS_UPDATED, refetching...");
+        queryClient.invalidateQueries({ queryKey: creditsQueryKeys.user(userId) });
+      }
+    });
+
+    return unsubscribe;
+  }, [userId, queryClient]);
+
   const credits = data ?? null;
 
   const derivedValues = useMemo(() => {

package/src/domains/subscription/application/SubscriptionAuthListener.ts

@@ -0,0 +1,26 @@
+import type { FirebaseAuthLike } from "./SubscriptionInitializerTypes";
+
+/**
+ * Gets the current user ID from Firebase auth.
+ */
+export const getCurrentUserId = (getAuth: () => FirebaseAuthLike | null): string | undefined => {
+  const auth = getAuth();
+  if (!auth) return undefined;
+  return auth.currentUser?.uid;
+};
+
+/**
+ * Sets up auth state listener that will re-initialize subscription
+ * when user auth state changes (login/logout).
+ */
+export const setupAuthStateListener = (
+  getAuth: () => FirebaseAuthLike | null,
+  onUserChange: (userId: string | undefined) => void
+): (() => void) | null => {
+  const auth = getAuth();
+  if (!auth) return null;
+
+  return auth.onAuthStateChanged((user) => {
+    onUserChange(user?.uid);
+  });
+};

package/src/domains/subscription/application/SubscriptionInitializer.ts

@@ -0,0 +1,77 @@
+/**
+ * Subscription Initializer
+ *
+ * Uses RevenueCat best practices:
+ * - Non-blocking initialization (fire and forget)
+ * - Relies on CustomerInfoUpdateListener for state updates
+ */
+
+import { Platform } from "react-native";
+import { configureCreditsRepository } from "../../credits/infrastructure/CreditsRepositoryProvider";
+import { SubscriptionManager } from "../infrastructure/managers/SubscriptionManager";
+import { configureAuthProvider } from "../presentation/useAuthAwarePurchase";
+import { SubscriptionSyncService } from "./SubscriptionSyncService";
+import { getCurrentUserId, setupAuthStateListener } from "./SubscriptionAuthListener";
+import type { SubscriptionInitConfig } from "./SubscriptionInitializerTypes";
+
+export type { FirebaseAuthLike, CreditPackageConfig, SubscriptionInitConfig } from "./SubscriptionInitializerTypes";
+
+export const initializeSubscription = async (config: SubscriptionInitConfig): Promise<void> => {
+  const {
+    apiKey, apiKeyIos, apiKeyAndroid, entitlementId, credits,
+    getAnonymousUserId, getFirebaseAuth, showAuthModal,
+    onCreditsUpdated, creditPackages,
+  } = config;
+
+  const key = Platform.OS === 'ios' ? (apiKeyIos || apiKey || '') : (apiKeyAndroid || apiKey || '');
+  if (!key) throw new Error('API key required');
+
+  // 1. Configure Repository
+  configureCreditsRepository({ ...credits, creditPackageAmounts: creditPackages?.amounts });
+
+  // 2. Setup Sync Service
+  const syncService = new SubscriptionSyncService(entitlementId);
+
+  // 3. Configure Subscription Manager
+  SubscriptionManager.configure({
+    config: {
+      apiKey: key,
+      entitlementIdentifier: entitlementId,
+      consumableProductIdentifiers: [creditPackages?.identifierPattern || 'credit'],
+      onPurchaseCompleted: (u: string, p: string, c: any, s: any) => syncService.handlePurchase(u, p, c, s),
+      onRenewalDetected: (u: string, p: string, expires: string, c: any) => syncService.handleRenewal(u, p, expires, c),
+      onPremiumStatusChanged: (u: string, isP: boolean, pId: any, exp: any, willR: any, pt: any) => syncService.handlePremiumStatusChanged(u, isP, pId, exp, willR, pt),
+      onCreditsUpdated,
+    },
+    apiKey: key,
+    getAnonymousUserId,
+  });
+
+  // 4. Configure Auth aware actions
+  configureAuthProvider({
+    isAuthenticated: () => {
+      const u = getFirebaseAuth()?.currentUser;
+      return !!(u && !u.isAnonymous);
+    },
+    showAuthModal,
+  });
+
+  const initializeInBackground = async (userId?: string) => {
+    try {
+      await SubscriptionManager.initialize(userId);
+      if (__DEV__) console.log('[SubscriptionInitializer] Background init complete');
+    } catch (error) {
+      if (__DEV__) console.log('[SubscriptionInitializer] Background init failed (non-critical):', error);
+    }
+  };
+
+  // 5. Start Background Init
+  const initialUserId = getCurrentUserId(getFirebaseAuth);
+  initializeInBackground(initialUserId);
+
+  // 6. Listen for Auth Changes
+  setupAuthStateListener(getFirebaseAuth, (newUserId) => {
+    if (__DEV__) console.log('[SubscriptionInitializer] Auth changed, re-init:', newUserId);
+    initializeInBackground(newUserId);
+  });
+};

package/src/{infrastructure/services → domains/subscription/application}/SubscriptionInitializerTypes.ts

@@ -2,7 +2,10 @@
  * Subscription Initializer Types
  */
 
-import type { CreditsConfig } from "../../domain/entities/Credits";
+import type { CreditsConfig } from "../../credits/core/Credits";
+import type { UserCreditsDocumentRead } from "../../credits/core/UserCreditsDocument";
+import type { PurchaseSource, PurchaseType } from "../core/SubscriptionConstants";
+import type { PeriodType } from "../core/SubscriptionStatus";
 
 export interface FirebaseAuthLike {
   currentUser: { uid: string; isAnonymous: boolean } | null;
@@ -28,3 +31,20 @@ export interface SubscriptionInitConfig {
   timeoutMs?: number;
   authStateTimeoutMs?: number;
 }
+
+export interface InitializeCreditsMetadata {
+  productId?: string;
+  source?: PurchaseSource;
+  type?: PurchaseType;
+  expirationDate?: string | null;
+  willRenew?: boolean;
+  originalTransactionId?: string;
+  isPremium?: boolean;
+  periodType?: PeriodType;
+}
+
+export interface InitializationResult {
+    credits: number;
+    alreadyProcessed?: boolean;
+    finalData?: UserCreditsDocumentRead;
+}