@umituz/react-native-subscription 1.7.0 → 1.8.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "1.7.0",
-  "description": "Subscription management and paywall UI for React Native apps",
+  "version": "1.8.0",
+  "description": "Subscription management, paywall UI and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "scripts": {
@@ -13,6 +13,7 @@
     "subscription",
     "premium",
     "paywall",
+    "credits",
     "in-app-purchase",
     "iap",
     "revenuecat",
@@ -30,15 +31,21 @@
     "react-native": ">=0.74.0",
     "react-native-purchases": ">=8.0.0",
     "react-native-safe-area-context": ">=4.0.0",
+    "@tanstack/react-query": ">=5.0.0",
+    "@umituz/react-native-firestore": "*",
     "@umituz/react-native-design-system-atoms": "*",
     "@umituz/react-native-design-system-theme": "*",
-    "@umituz/react-native-legal": "*"
+    "@umituz/react-native-legal": "*",
+    "firebase": ">=10.0.0"
   },
   "devDependencies": {
     "@types/react": "~19.1.0",
     "typescript": "~5.9.2",
     "react-native": "~0.76.0",
-    "@umituz/react-native-design-system-theme": "latest"
+    "@umituz/react-native-design-system-theme": "latest",
+    "@umituz/react-native-firestore": "latest",
+    "@tanstack/react-query": "^5.0.0",
+    "firebase": "^11.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/domain/entities/Credits.ts

@@ -0,0 +1,45 @@
+/**
+ * Credits Domain Entities
+ *
+ * Generic credit system types for subscription-based apps.
+ * Designed to be used across hundreds of apps with configurable limits.
+ */
+
+export type CreditType = "text" | "image";
+
+export interface UserCredits {
+  textCredits: number;
+  imageCredits: number;
+  purchasedAt: Date;
+  lastUpdatedAt: Date;
+}
+
+export interface CreditsConfig {
+  collectionName: string;
+  textCreditLimit: number;
+  imageCreditLimit: number;
+}
+
+export interface CreditsResult<T = UserCredits> {
+  success: boolean;
+  data?: T;
+  error?: {
+    message: string;
+    code: string;
+  };
+}
+
+export interface DeductCreditsResult {
+  success: boolean;
+  remainingCredits?: number;
+  error?: {
+    message: string;
+    code: string;
+  };
+}
+
+export const DEFAULT_CREDITS_CONFIG: CreditsConfig = {
+  collectionName: "user_credits",
+  textCreditLimit: 1000,
+  imageCreditLimit: 100,
+};

package/src/index.ts

@@ -164,3 +164,70 @@ export {
   validateIsPremium,
   validateFetcher,
 } from "./utils/validation";
+
+// =============================================================================
+// CREDITS SYSTEM - Domain Entities
+// =============================================================================
+
+export type {
+  CreditType,
+  UserCredits,
+  CreditsConfig,
+  CreditsResult,
+  DeductCreditsResult,
+} from "./domain/entities/Credits";
+
+export { DEFAULT_CREDITS_CONFIG } from "./domain/entities/Credits";
+
+// =============================================================================
+// CREDITS SYSTEM - Repository
+// =============================================================================
+
+export {
+  CreditsRepository,
+  createCreditsRepository,
+} from "./infrastructure/repositories/CreditsRepository";
+
+// =============================================================================
+// CREDITS SYSTEM - Context & Provider
+// =============================================================================
+
+export {
+  CreditsContext,
+  useCreditsContext,
+  useCreditsConfig,
+  useCreditsRepository,
+  type CreditsContextValue,
+} from "./presentation/context/CreditsContext";
+
+export {
+  CreditsProvider,
+  type CreditsProviderProps,
+} from "./presentation/providers/CreditsProvider";
+
+// =============================================================================
+// CREDITS SYSTEM - Hooks
+// =============================================================================
+
+export {
+  useCredits,
+  useHasCredits,
+  creditsQueryKeys,
+  type UseCreditsParams,
+  type UseCreditsResult,
+} from "./presentation/hooks/useCredits";
+
+export {
+  useDeductCredit,
+  useInitializeCredits,
+  type UseDeductCreditParams,
+  type UseDeductCreditResult,
+  type UseInitializeCreditsParams,
+  type UseInitializeCreditsResult,
+} from "./presentation/hooks/useDeductCredit";
+
+export {
+  usePremiumWithCredits,
+  type UsePremiumWithCreditsParams,
+  type UsePremiumWithCreditsResult,
+} from "./presentation/hooks/usePremiumWithCredits";

package/src/infrastructure/repositories/CreditsRepository.ts

@@ -0,0 +1,247 @@
+/**
+ * Credits Repository
+ *
+ * Firestore operations for user credits management.
+ * Extends BaseRepository from @umituz/react-native-firestore.
+ *
+ * Generic and reusable - accepts config from main app.
+ */
+
+import {
+  doc,
+  getDoc,
+  runTransaction,
+  serverTimestamp,
+} from "firebase/firestore";
+import { BaseRepository, getFirestore } from "@umituz/react-native-firestore";
+import type {
+  CreditType,
+  UserCredits,
+  CreditsConfig,
+  CreditsResult,
+  DeductCreditsResult,
+} from "../../domain/entities/Credits";
+
+interface FirestoreTimestamp {
+  toDate: () => Date;
+}
+
+interface UserCreditsDocument {
+  textCredits: number;
+  imageCredits: number;
+  purchasedAt: FirestoreTimestamp;
+  lastUpdatedAt: FirestoreTimestamp;
+  lastPurchaseAt?: FirestoreTimestamp;
+  processedPurchases?: string[];
+}
+
+export class CreditsRepository extends BaseRepository {
+  private config: CreditsConfig;
+
+  constructor(config: CreditsConfig) {
+    super();
+    this.config = config;
+  }
+
+  async getCredits(userId: string): Promise<CreditsResult> {
+    const db = this.getDb();
+    if (!db) {
+      return {
+        success: false,
+        error: { message: "Database not available", code: "DB_NOT_AVAILABLE" },
+      };
+    }
+
+    try {
+      const creditsRef = doc(db, this.config.collectionName, userId);
+      const snapshot = await getDoc(creditsRef);
+
+      if (!snapshot.exists()) {
+        return { success: true, data: undefined };
+      }
+
+      const data = snapshot.data() as UserCreditsDocument;
+      return {
+        success: true,
+        data: {
+          textCredits: data.textCredits,
+          imageCredits: data.imageCredits,
+          purchasedAt: data.purchasedAt?.toDate?.() || new Date(),
+          lastUpdatedAt: data.lastUpdatedAt?.toDate?.() || new Date(),
+        },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: {
+          message:
+            error instanceof Error ? error.message : "Failed to get credits",
+          code: "FETCH_FAILED",
+        },
+      };
+    }
+  }
+
+  async initializeCredits(
+    userId: string,
+    purchaseId?: string
+  ): Promise<CreditsResult> {
+    const db = getFirestore();
+    if (!db) {
+      return {
+        success: false,
+        error: { message: "Database not available", code: "INIT_FAILED" },
+      };
+    }
+
+    try {
+      const creditsRef = doc(db, this.config.collectionName, userId);
+
+      const result = await runTransaction(db, async (transaction) => {
+        const creditsDoc = await transaction.get(creditsRef);
+        const now = serverTimestamp();
+
+        let newTextCredits = this.config.textCreditLimit;
+        let newImageCredits = this.config.imageCreditLimit;
+        let purchasedAt = now;
+        let processedPurchases: string[] = [];
+
+        if (creditsDoc.exists()) {
+          const existing = creditsDoc.data() as UserCreditsDocument;
+          processedPurchases = existing.processedPurchases || [];
+
+          if (purchaseId && processedPurchases.includes(purchaseId)) {
+            return {
+              textCredits: existing.textCredits,
+              imageCredits: existing.imageCredits,
+              alreadyProcessed: true,
+            };
+          }
+
+          newTextCredits =
+            (existing.textCredits || 0) + this.config.textCreditLimit;
+          newImageCredits =
+            (existing.imageCredits || 0) + this.config.imageCreditLimit;
+          purchasedAt = existing.purchasedAt || now;
+        }
+
+        if (purchaseId) {
+          processedPurchases = [...processedPurchases, purchaseId].slice(-10);
+        }
+
+        transaction.set(creditsRef, {
+          textCredits: newTextCredits,
+          imageCredits: newImageCredits,
+          purchasedAt,
+          lastUpdatedAt: now,
+          lastPurchaseAt: now,
+          processedPurchases,
+        });
+
+        return { textCredits: newTextCredits, imageCredits: newImageCredits };
+      });
+
+      return {
+        success: true,
+        data: {
+          textCredits: result.textCredits,
+          imageCredits: result.imageCredits,
+          purchasedAt: new Date(),
+          lastUpdatedAt: new Date(),
+        },
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: {
+          message:
+            error instanceof Error
+              ? error.message
+              : "Failed to initialize credits",
+          code: "INIT_FAILED",
+        },
+      };
+    }
+  }
+
+  async deductCredit(
+    userId: string,
+    creditType: CreditType
+  ): Promise<DeductCreditsResult> {
+    const db = getFirestore();
+    if (!db) {
+      return {
+        success: false,
+        error: { message: "Database not available", code: "DEDUCT_FAILED" },
+      };
+    }
+
+    try {
+      const creditsRef = doc(db, this.config.collectionName, userId);
+      const fieldName = creditType === "text" ? "textCredits" : "imageCredits";
+
+      const newCredits = await runTransaction(db, async (transaction) => {
+        const creditsDoc = await transaction.get(creditsRef);
+
+        if (!creditsDoc.exists()) {
+          throw new Error("NO_CREDITS");
+        }
+
+        const currentCredits = creditsDoc.data()[fieldName] as number;
+
+        if (currentCredits <= 0) {
+          throw new Error("CREDITS_EXHAUSTED");
+        }
+
+        const updatedCredits = currentCredits - 1;
+        transaction.update(creditsRef, {
+          [fieldName]: updatedCredits,
+          lastUpdatedAt: serverTimestamp(),
+        });
+
+        return updatedCredits;
+      });
+
+      return { success: true, remainingCredits: newCredits };
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+
+      if (errorMessage === "NO_CREDITS") {
+        return {
+          success: false,
+          error: { message: "No credits found", code: "NO_CREDITS" },
+        };
+      }
+
+      if (errorMessage === "CREDITS_EXHAUSTED") {
+        return {
+          success: false,
+          error: { message: "Credits exhausted", code: "CREDITS_EXHAUSTED" },
+        };
+      }
+
+      return {
+        success: false,
+        error: { message: errorMessage, code: "DEDUCT_FAILED" },
+      };
+    }
+  }
+
+  async hasCredits(userId: string, creditType: CreditType): Promise<boolean> {
+    const result = await this.getCredits(userId);
+    if (!result.success || !result.data) {
+      return false;
+    }
+
+    const credits =
+      creditType === "text" ? result.data.textCredits : result.data.imageCredits;
+    return credits > 0;
+  }
+}
+
+export const createCreditsRepository = (
+  config: CreditsConfig
+): CreditsRepository => {
+  return new CreditsRepository(config);
+};

package/src/presentation/context/CreditsContext.ts

@@ -0,0 +1,42 @@
+/**
+ * Credits Context
+ *
+ * React context for credits configuration.
+ * Allows main app to provide credit limits and collection name.
+ */
+
+import { createContext, useContext } from "react";
+import type { CreditsConfig } from "../../domain/entities/Credits";
+import { DEFAULT_CREDITS_CONFIG } from "../../domain/entities/Credits";
+import type { CreditsRepository } from "../../infrastructure/repositories/CreditsRepository";
+
+export interface CreditsContextValue {
+  config: CreditsConfig;
+  repository: CreditsRepository | null;
+}
+
+export const CreditsContext = createContext<CreditsContextValue>({
+  config: DEFAULT_CREDITS_CONFIG,
+  repository: null,
+});
+
+export const useCreditsContext = (): CreditsContextValue => {
+  const context = useContext(CreditsContext);
+  if (!context.repository) {
+    throw new Error("CreditsProvider must be used to provide credits config");
+  }
+  return context;
+};
+
+export const useCreditsConfig = (): CreditsConfig => {
+  const { config } = useContext(CreditsContext);
+  return config;
+};
+
+export const useCreditsRepository = (): CreditsRepository => {
+  const { repository } = useContext(CreditsContext);
+  if (!repository) {
+    throw new Error("CreditsProvider must be used to provide repository");
+  }
+  return repository;
+};

package/src/presentation/hooks/useCredits.ts

@@ -0,0 +1,97 @@
+/**
+ * useCredits Hook
+ *
+ * TanStack Query hook for fetching user credits.
+ * Generic and reusable - uses config from CreditsProvider.
+ */
+
+import { useQuery } from "@tanstack/react-query";
+import type { UserCredits, CreditType } from "../../domain/entities/Credits";
+import {
+  useCreditsRepository,
+  useCreditsConfig,
+} from "../context/CreditsContext";
+
+const CACHE_CONFIG = {
+  staleTime: 30 * 1000,
+  gcTime: 5 * 60 * 1000,
+};
+
+export const creditsQueryKeys = {
+  all: ["credits"] as const,
+  user: (userId: string) => ["credits", userId] as const,
+};
+
+export interface UseCreditsParams {
+  userId: string | undefined;
+  enabled?: boolean;
+}
+
+export interface UseCreditsResult {
+  credits: UserCredits | null;
+  isLoading: boolean;
+  error: Error | null;
+  hasTextCredits: boolean;
+  hasImageCredits: boolean;
+  textCreditsPercent: number;
+  imageCreditsPercent: number;
+  refetch: () => void;
+}
+
+export const useCredits = ({
+  userId,
+  enabled = true,
+}: UseCreditsParams): UseCreditsResult => {
+  const repository = useCreditsRepository();
+  const config = useCreditsConfig();
+
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: creditsQueryKeys.user(userId ?? ""),
+    queryFn: async () => {
+      if (!userId) return null;
+      const result = await repository.getCredits(userId);
+      if (!result.success) {
+        throw new Error(result.error?.message || "Failed to fetch credits");
+      }
+      return result.data || null;
+    },
+    enabled: enabled && !!userId,
+    staleTime: CACHE_CONFIG.staleTime,
+    gcTime: CACHE_CONFIG.gcTime,
+  });
+
+  const credits = data ?? null;
+  const hasTextCredits = (credits?.textCredits ?? 0) > 0;
+  const hasImageCredits = (credits?.imageCredits ?? 0) > 0;
+
+  const textCreditsPercent = credits
+    ? Math.round((credits.textCredits / config.textCreditLimit) * 100)
+    : 0;
+
+  const imageCreditsPercent = credits
+    ? Math.round((credits.imageCredits / config.imageCreditLimit) * 100)
+    : 0;
+
+  return {
+    credits,
+    isLoading,
+    error: error as Error | null,
+    hasTextCredits,
+    hasImageCredits,
+    textCreditsPercent,
+    imageCreditsPercent,
+    refetch,
+  };
+};
+
+export const useHasCredits = (
+  userId: string | undefined,
+  creditType: CreditType
+): boolean => {
+  const { credits } = useCredits({ userId });
+  if (!credits) return false;
+
+  return creditType === "text"
+    ? credits.textCredits > 0
+    : credits.imageCredits > 0;
+};

package/src/presentation/hooks/useDeductCredit.ts

@@ -0,0 +1,146 @@
+/**
+ * useDeductCredit Hook
+ *
+ * TanStack Query mutation hook for deducting credits.
+ * Generic and reusable - uses config from CreditsProvider.
+ */
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { CreditType, UserCredits } from "../../domain/entities/Credits";
+import { useCreditsRepository } from "../context/CreditsContext";
+import { creditsQueryKeys } from "./useCredits";
+
+export interface UseDeductCreditParams {
+  userId: string | undefined;
+  onCreditsExhausted?: () => void;
+}
+
+export interface UseDeductCreditResult {
+  deductCredit: (creditType: CreditType) => Promise<boolean>;
+  isDeducting: boolean;
+}
+
+export const useDeductCredit = ({
+  userId,
+  onCreditsExhausted,
+}: UseDeductCreditParams): UseDeductCreditResult => {
+  const repository = useCreditsRepository();
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: async (creditType: CreditType) => {
+      if (!userId) {
+        throw new Error("User not authenticated");
+      }
+      return repository.deductCredit(userId, creditType);
+    },
+    onMutate: async (creditType: CreditType) => {
+      if (!userId) return;
+
+      await queryClient.cancelQueries({
+        queryKey: creditsQueryKeys.user(userId),
+      });
+
+      const previousCredits = queryClient.getQueryData<UserCredits>(
+        creditsQueryKeys.user(userId)
+      );
+
+      queryClient.setQueryData<UserCredits | null>(
+        creditsQueryKeys.user(userId),
+        (old) => {
+          if (!old) return old;
+          const fieldName =
+            creditType === "text" ? "textCredits" : "imageCredits";
+          return {
+            ...old,
+            [fieldName]: Math.max(0, old[fieldName] - 1),
+            lastUpdatedAt: new Date(),
+          };
+        }
+      );
+
+      return { previousCredits };
+    },
+    onError: (_err, _creditType, context) => {
+      if (userId && context?.previousCredits) {
+        queryClient.setQueryData(
+          creditsQueryKeys.user(userId),
+          context.previousCredits
+        );
+      }
+    },
+    onSettled: () => {
+      if (userId) {
+        queryClient.invalidateQueries({
+          queryKey: creditsQueryKeys.user(userId),
+        });
+      }
+    },
+  });
+
+  const deductCredit = async (creditType: CreditType): Promise<boolean> => {
+    try {
+      const result = await mutation.mutateAsync(creditType);
+
+      if (!result.success) {
+        if (result.error?.code === "CREDITS_EXHAUSTED") {
+          onCreditsExhausted?.();
+        }
+        return false;
+      }
+
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  return {
+    deductCredit,
+    isDeducting: mutation.isPending,
+  };
+};
+
+export interface UseInitializeCreditsParams {
+  userId: string | undefined;
+}
+
+export interface UseInitializeCreditsResult {
+  initializeCredits: (purchaseId?: string) => Promise<boolean>;
+  isInitializing: boolean;
+}
+
+export const useInitializeCredits = ({
+  userId,
+}: UseInitializeCreditsParams): UseInitializeCreditsResult => {
+  const repository = useCreditsRepository();
+  const queryClient = useQueryClient();
+
+  const mutation = useMutation({
+    mutationFn: async (purchaseId?: string) => {
+      if (!userId) {
+        throw new Error("User not authenticated");
+      }
+      return repository.initializeCredits(userId, purchaseId);
+    },
+    onSuccess: (result) => {
+      if (userId && result.success && result.data) {
+        queryClient.setQueryData(creditsQueryKeys.user(userId), result.data);
+      }
+    },
+  });
+
+  const initializeCredits = async (purchaseId?: string): Promise<boolean> => {
+    try {
+      const result = await mutation.mutateAsync(purchaseId);
+      return result.success;
+    } catch {
+      return false;
+    }
+  };
+
+  return {
+    initializeCredits,
+    isInitializing: mutation.isPending,
+  };
+};

package/src/presentation/hooks/usePremiumWithCredits.ts

@@ -0,0 +1,48 @@
+/**
+ * usePremiumWithCredits Hook
+ *
+ * Combined hook for premium subscription with credits system.
+ * Ensures premium users always have credits initialized.
+ */
+
+import { useEffect, useCallback } from "react";
+import { useCredits, type UseCreditsResult } from "./useCredits";
+import { useInitializeCredits } from "./useDeductCredit";
+
+export interface UsePremiumWithCreditsParams {
+  userId: string | undefined;
+  isPremium: boolean;
+}
+
+export interface UsePremiumWithCreditsResult extends UseCreditsResult {
+  ensureCreditsInitialized: () => Promise<void>;
+}
+
+export const usePremiumWithCredits = ({
+  userId,
+  isPremium,
+}: UsePremiumWithCreditsParams): UsePremiumWithCreditsResult => {
+  const creditsResult = useCredits({ userId });
+  const { initializeCredits, isInitializing } = useInitializeCredits({
+    userId,
+  });
+
+  const ensureCreditsInitialized = useCallback(async () => {
+    if (!userId || !isPremium) return;
+    if (creditsResult.credits) return;
+    if (isInitializing) return;
+
+    await initializeCredits();
+  }, [userId, isPremium, creditsResult.credits, isInitializing, initializeCredits]);
+
+  useEffect(() => {
+    if (isPremium && userId && !creditsResult.credits && !creditsResult.isLoading) {
+      ensureCreditsInitialized();
+    }
+  }, [isPremium, userId, creditsResult.credits, creditsResult.isLoading, ensureCreditsInitialized]);
+
+  return {
+    ...creditsResult,
+    ensureCreditsInitialized,
+  };
+};

package/src/presentation/providers/CreditsProvider.tsx

@@ -0,0 +1,38 @@
+/**
+ * Credits Provider
+ *
+ * React provider for credits configuration.
+ * Main app uses this to configure credit limits.
+ */
+
+import React, { useMemo } from "react";
+import type { CreditsConfig } from "../../domain/entities/Credits";
+import { DEFAULT_CREDITS_CONFIG } from "../../domain/entities/Credits";
+import {
+  CreditsContext,
+  type CreditsContextValue,
+} from "../context/CreditsContext";
+import { createCreditsRepository } from "../../infrastructure/repositories/CreditsRepository";
+
+export interface CreditsProviderProps {
+  children: React.ReactNode;
+  config?: Partial<CreditsConfig>;
+}
+
+export const CreditsProvider: React.FC<CreditsProviderProps> = ({
+  children,
+  config,
+}) => {
+  const value = useMemo<CreditsContextValue>(() => {
+    const mergedConfig: CreditsConfig = {
+      ...DEFAULT_CREDITS_CONFIG,
+      ...config,
+    };
+    const repository = createCreditsRepository(mergedConfig);
+    return { config: mergedConfig, repository };
+  }, [config]);
+
+  return (
+    <CreditsContext.Provider value={value}>{children}</CreditsContext.Provider>
+  );
+};