@umituz/react-native-subscription 2.24.17 → 2.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.24.17",
+  "version": "2.25.1",
   "description": "Complete subscription management with RevenueCat, paywall UI, and credits system for React Native apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/domain/entities/Credits.ts

@@ -6,6 +6,7 @@
  */
 
 import type { SubscriptionPackageType } from "../../utils/packageTypeDetector";
+import type { SubscriptionStatusType, PeriodType } from "./SubscriptionStatus";
 
 export type CreditType = "text" | "image";
 
@@ -19,13 +20,11 @@ export type PurchaseSource =
 
 export type PurchaseType = "initial" | "renewal" | "upgrade" | "downgrade";
 
-export type SubscriptionStatus = "active" | "expired" | "canceled" | "free";
-
 /** Single Source of Truth for user subscription + credits data */
 export interface UserCredits {
   // Core subscription
   isPremium: boolean;
-  status: SubscriptionStatus;
+  status: SubscriptionStatusType;
 
   // Dates
   purchasedAt: Date | null;
@@ -38,6 +37,14 @@ export interface UserCredits {
   packageType?: "weekly" | "monthly" | "yearly" | "lifetime";
   originalTransactionId?: string;
 
+  // Trial fields
+  periodType?: PeriodType;
+  isTrialing?: boolean;
+  trialStartDate?: Date | null;
+  trialEndDate?: Date | null;
+  trialCredits?: number;
+  convertedFromTrial?: boolean;
+
   // Credits
   credits: number;
   creditLimit?: number;

package/src/domain/entities/SubscriptionStatus.ts

@@ -2,11 +2,22 @@ import { timezoneService } from "@umituz/react-native-design-system";
 
 export const SUBSCRIPTION_STATUS = {
   ACTIVE: 'active',
+  TRIAL: 'trial',
+  TRIAL_CANCELED: 'trial_canceled',
   EXPIRED: 'expired',
   CANCELED: 'canceled',
   NONE: 'none',
 } as const;
 
+/** RevenueCat period type constants */
+export const PERIOD_TYPE = {
+  NORMAL: 'NORMAL',
+  INTRO: 'INTRO',
+  TRIAL: 'TRIAL',
+} as const;
+
+export type PeriodType = (typeof PERIOD_TYPE)[keyof typeof PERIOD_TYPE];
+
 export type SubscriptionStatusType = (typeof SUBSCRIPTION_STATUS)[keyof typeof SUBSCRIPTION_STATUS];
 
 export interface SubscriptionStatus {
@@ -17,6 +28,10 @@ export interface SubscriptionStatus {
     customerId?: string | null;
     syncedAt?: string | null;
     status?: SubscriptionStatusType;
+    /** RevenueCat period type: NORMAL, INTRO, or TRIAL */
+    periodType?: PeriodType;
+    /** Whether user is currently in trial period */
+    isTrialing?: boolean;
 }
 
 export const createDefaultSubscriptionStatus = (): SubscriptionStatus => ({
@@ -26,7 +41,7 @@ export const createDefaultSubscriptionStatus = (): SubscriptionStatus => ({
     purchasedAt: null,
     customerId: null,
     syncedAt: null,
-    status: 'none',
+    status: SUBSCRIPTION_STATUS.NONE,
 });
 
 export const isSubscriptionValid = (status: SubscriptionStatus | null): boolean => {
@@ -41,3 +56,32 @@ export const calculateDaysRemaining = (expiresAt: string | null): number | null
     return timezoneService.getDaysUntil(new Date(expiresAt));
 };
 
+/** Subscription status resolver input */
+export interface StatusResolverInput {
+    isPremium: boolean;
+    willRenew?: boolean;
+    isExpired?: boolean;
+    periodType?: PeriodType;
+}
+
+/**
+ * Resolves subscription status from input parameters
+ * Single source of truth for status determination logic
+ */
+export const resolveSubscriptionStatus = (input: StatusResolverInput): SubscriptionStatusType => {
+    const { isPremium, willRenew, isExpired, periodType } = input;
+
+    if (!isPremium || isExpired) {
+        return isExpired ? SUBSCRIPTION_STATUS.EXPIRED : SUBSCRIPTION_STATUS.NONE;
+    }
+
+    const isTrial = periodType === PERIOD_TYPE.TRIAL;
+    const isCanceled = willRenew === false;
+
+    if (isTrial) {
+        return isCanceled ? SUBSCRIPTION_STATUS.TRIAL_CANCELED : SUBSCRIPTION_STATUS.TRIAL;
+    }
+
+    return isCanceled ? SUBSCRIPTION_STATUS.CANCELED : SUBSCRIPTION_STATUS.ACTIVE;
+};
+

package/src/index.ts

@@ -7,8 +7,14 @@ export * from "./domains/paywall";
 export * from "./domains/config";
 
 // Domain Layer
-export { createDefaultSubscriptionStatus, isSubscriptionValid } from "./domain/entities/SubscriptionStatus";
-export type { SubscriptionStatus, SubscriptionStatusType } from "./domain/entities/SubscriptionStatus";
+export {
+  SUBSCRIPTION_STATUS,
+  PERIOD_TYPE,
+  createDefaultSubscriptionStatus,
+  isSubscriptionValid,
+  resolveSubscriptionStatus,
+} from "./domain/entities/SubscriptionStatus";
+export type { SubscriptionStatus, SubscriptionStatusType, PeriodType, StatusResolverInput } from "./domain/entities/SubscriptionStatus";
 export type { SubscriptionConfig } from "./domain/value-objects/SubscriptionConfig";
 export type { ISubscriptionRepository } from "./application/ports/ISubscriptionRepository";
 
@@ -22,6 +28,16 @@ export {
   type FeedbackSubmitResult,
 } from "./infrastructure/services/FeedbackService";
 export { initializeSubscription, type SubscriptionInitConfig, type CreditPackageConfig } from "./infrastructure/services/SubscriptionInitializer";
+export {
+  getDeviceId,
+  checkTrialEligibility,
+  recordTrialStart,
+  recordTrialEnd,
+  recordTrialConversion,
+  TRIAL_CONFIG,
+  type DeviceTrialRecord,
+  type TrialEligibilityResult,
+} from "./infrastructure/services/TrialService";
 export { CreditsRepository, createCreditsRepository } from "./infrastructure/repositories/CreditsRepository";
 export { configureCreditsRepository, getCreditsRepository, getCreditsConfig, resetCreditsRepository, isCreditsRepositoryConfigured } from "./infrastructure/repositories/CreditsRepositoryProvider";
 export {

package/src/infrastructure/mappers/CreditsMapper.ts

@@ -1,13 +1,15 @@
-import type { UserCredits, SubscriptionStatus } from "../../domain/entities/Credits";
+import type { UserCredits } from "../../domain/entities/Credits";
+import { resolveSubscriptionStatus, type PeriodType, type SubscriptionStatusType } from "../../domain/entities/SubscriptionStatus";
 import type { UserCreditsDocumentRead } from "../models/UserCreditsDocument";
 
 /** Maps Firestore document to domain entity with expiration validation */
 export class CreditsMapper {
   static toEntity(doc: UserCreditsDocumentRead): UserCredits {
     const expirationDate = doc.expirationDate?.toDate?.() ?? null;
+    const periodType = doc.periodType as PeriodType | undefined;
 
     // Validate isPremium against expirationDate (real-time check)
-    const { isPremium, status } = CreditsMapper.validateSubscription(doc, expirationDate);
+    const { isPremium, status } = CreditsMapper.validateSubscription(doc, expirationDate, periodType);
 
     return {
       // Core subscription (validated)
@@ -25,6 +27,14 @@ export class CreditsMapper {
       packageType: doc.packageType,
       originalTransactionId: doc.originalTransactionId,
 
+      // Trial fields
+      periodType,
+      isTrialing: doc.isTrialing,
+      trialStartDate: doc.trialStartDate?.toDate?.() ?? null,
+      trialEndDate: doc.trialEndDate?.toDate?.() ?? null,
+      trialCredits: doc.trialCredits,
+      convertedFromTrial: doc.convertedFromTrial,
+
       // Credits
       credits: doc.credits,
       creditLimit: doc.creditLimit,
@@ -37,33 +47,27 @@ export class CreditsMapper {
     };
   }
 
-  /** Validate subscription status against expirationDate */
+  /** Validate subscription status against expirationDate and periodType */
   private static validateSubscription(
     doc: UserCreditsDocumentRead,
-    expirationDate: Date | null
-  ): { isPremium: boolean; status: SubscriptionStatus } {
-    const docIsPremium = doc.isPremium ?? false;
-
-    // No expiration date = lifetime or free
-    if (!expirationDate) {
-      return {
-        isPremium: docIsPremium,
-        status: docIsPremium ? "active" : "free",
-      };
-    }
-
-    // Check if subscription has expired
-    const isExpired = expirationDate < new Date();
+    expirationDate: Date | null,
+    periodType?: PeriodType
+  ): { isPremium: boolean; status: SubscriptionStatusType } {
+    const isPremium = doc.isPremium ?? false;
+    const willRenew = doc.willRenew ?? false;
+    const isExpired = expirationDate ? expirationDate < new Date() : false;
 
-    if (isExpired) {
-      // Subscription expired - override document's isPremium
-      return { isPremium: false, status: "expired" };
-    }
+    const status = resolveSubscriptionStatus({
+      isPremium,
+      willRenew,
+      isExpired,
+      periodType,
+    });
 
-    // Subscription still active
+    // Override isPremium if expired
     return {
-      isPremium: docIsPremium,
-      status: docIsPremium ? "active" : "free",
+      isPremium: isExpired ? false : isPremium,
+      status,
     };
   }
 }

package/src/infrastructure/models/UserCreditsDocument.ts

@@ -12,7 +12,10 @@ export type PurchaseSource =
 
 export type PurchaseType = "initial" | "renewal" | "upgrade" | "downgrade";
 
-export type SubscriptionDocStatus = "active" | "expired" | "canceled" | "free";
+export type SubscriptionDocStatus = "active" | "trial" | "trial_canceled" | "expired" | "canceled" | "free";
+
+/** RevenueCat period types */
+export type PeriodType = "NORMAL" | "INTRO" | "TRIAL";
 
 export interface PurchaseMetadata {
   productId: string;
@@ -43,6 +46,14 @@ export interface UserCreditsDocumentRead {
     packageType?: "weekly" | "monthly" | "yearly" | "lifetime";
     originalTransactionId?: string;
 
+    // Trial fields
+    periodType?: PeriodType;
+    isTrialing?: boolean;
+    trialStartDate?: FirestoreTimestamp;
+    trialEndDate?: FirestoreTimestamp;
+    trialCredits?: number;
+    convertedFromTrial?: boolean;
+
     // Credits
     credits: number;
     creditLimit?: number;

package/src/infrastructure/repositories/CreditsRepository.ts

@@ -20,6 +20,8 @@ export interface RevenueCatData {
   willRenew?: boolean;
   originalTransactionId?: string;
   isPremium?: boolean;
+  /** RevenueCat period type: NORMAL, INTRO, or TRIAL */
+  periodType?: "NORMAL" | "INTRO" | "TRIAL";
 }
 
 export class CreditsRepository extends BaseRepository {
@@ -84,6 +86,7 @@ export class CreditsRepository extends BaseRepository {
         willRenew: revenueCatData?.willRenew,
         originalTransactionId: revenueCatData?.originalTransactionId,
         isPremium: revenueCatData?.isPremium,
+        periodType: revenueCatData?.periodType,
       };
 
       const res = await initializeCreditsTransaction(

package/src/infrastructure/services/CreditsInitializer.ts

@@ -15,8 +15,9 @@ import type {
   PurchaseSource,
   PurchaseType,
   PurchaseMetadata,
-  SubscriptionDocStatus,
 } from "../models/UserCreditsDocument";
+import { SUBSCRIPTION_STATUS, resolveSubscriptionStatus, type PeriodType } from "../../domain/entities/SubscriptionStatus";
+import { TRIAL_CONFIG } from "./TrialService";
 import { detectPackageType } from "../../utils/packageTypeDetector";
 import { getCreditAllocation } from "../../utils/creditMapper";
 
@@ -34,6 +35,8 @@ export interface InitializeCreditsMetadata {
   willRenew?: boolean;
   originalTransactionId?: string;
   isPremium?: boolean;
+  /** RevenueCat period type: NORMAL, INTRO, or TRIAL */
+  periodType?: PeriodType;
 }
 
 export async function initializeCreditsTransaction(
@@ -122,18 +125,24 @@ export async function initializeCreditsTransaction(
           ? [...(existing?.purchaseHistory || []), purchaseMetadata].slice(-10)
           : existing?.purchaseHistory;
 
-        // Determine subscription status based on isPremium and willRenew
+        // Determine subscription status
         const isPremium = metadata?.isPremium ?? true;
         const willRenew = metadata?.willRenew;
+        const periodType = metadata?.periodType;
 
-        // Status logic: canceled if premium but willRenew=false, expired if not premium, active otherwise
-        let status: SubscriptionDocStatus;
-        if (!isPremium) {
-            status = "expired";
-        } else if (willRenew === false) {
-            status = "canceled";
-        } else {
-            status = "active";
+        const status = resolveSubscriptionStatus({
+            isPremium,
+            willRenew,
+            isExpired: !isPremium,
+            periodType,
+        });
+
+        // Determine credits based on status
+        // Trial: 5 credits, Trial canceled: 0 credits, Normal: plan-based credits
+        if (status === SUBSCRIPTION_STATUS.TRIAL) {
+            newCredits = TRIAL_CONFIG.CREDITS;
+        } else if (status === SUBSCRIPTION_STATUS.TRIAL_CANCELED) {
+            newCredits = 0;
         }
 
         // Build credits data (Single Source of Truth)
@@ -176,6 +185,28 @@ export async function initializeCreditsTransaction(
             creditsData.appVersion = appVersion;
         }
 
+        // Trial-specific fields
+        const isTrialing = status === SUBSCRIPTION_STATUS.TRIAL || status === SUBSCRIPTION_STATUS.TRIAL_CANCELED;
+
+        if (periodType) {
+            creditsData.periodType = periodType;
+        }
+        if (isTrialing) {
+            creditsData.isTrialing = status === SUBSCRIPTION_STATUS.TRIAL;
+            creditsData.trialCredits = TRIAL_CONFIG.CREDITS;
+            // Set trial dates if this is a new trial
+            if (!existing?.trialStartDate) {
+                creditsData.trialStartDate = now;
+            }
+            if (metadata?.expirationDate) {
+                creditsData.trialEndDate = Timestamp.fromDate(new Date(metadata.expirationDate));
+            }
+        } else if (existing?.isTrialing && isPremium) {
+            // User converted from trial to paid
+            creditsData.isTrialing = false;
+            creditsData.convertedFromTrial = true;
+        }
+
         // Purchase metadata
         if (metadata?.source) {
             creditsData.purchaseSource = metadata.source;

package/src/infrastructure/services/SubscriptionInitializer.ts

@@ -51,6 +51,7 @@ export const initializeSubscription = async (config: SubscriptionInitConfig): Pr
       willRenew: entitlement?.willRenew ?? false,
       originalTransactionId: entitlement?.originalPurchaseDate ?? undefined,
       isPremium: Object.keys(customerInfo.entitlements.active).length > 0,
+      periodType: entitlement?.periodType as "NORMAL" | "INTRO" | "TRIAL" | undefined,
     };
   };
 
@@ -110,16 +111,18 @@ export const initializeSubscription = async (config: SubscriptionInitConfig): Pr
     isPremium: boolean,
     productId?: string,
     expiresAt?: string,
-    willRenew?: boolean
+    willRenew?: boolean,
+    periodType?: "NORMAL" | "INTRO" | "TRIAL"
   ) => {
     if (__DEV__) {
-      console.log('[SubscriptionInitializer] onPremiumStatusChanged:', { userId, isPremium, productId, willRenew });
+      console.log('[SubscriptionInitializer] onPremiumStatusChanged:', { userId, isPremium, productId, willRenew, periodType });
     }
     try {
       const revenueCatData: RevenueCatData = {
         expirationDate: expiresAt ?? null,
         willRenew: willRenew ?? false,
         isPremium,
+        periodType,
       };
       await getCreditsRepository().initializeCredits(
         userId,

package/src/infrastructure/services/TrialService.ts

@@ -0,0 +1,241 @@
+/**
+ * Trial Service
+ * Handles device-based trial tracking to prevent abuse
+ * Uses persistent device ID that survives app reinstalls
+ */
+
+declare const __DEV__: boolean;
+
+import {
+  doc,
+  getDoc,
+  setDoc,
+  serverTimestamp,
+  arrayUnion,
+} from "firebase/firestore";
+import { getFirestore } from "@umituz/react-native-firebase";
+import { PersistentDeviceIdService } from "@umituz/react-native-design-system";
+
+const DEVICE_TRIALS_COLLECTION = "device_trials";
+
+/** Trial constants */
+export const TRIAL_CONFIG = {
+  DURATION_DAYS: 3,
+  CREDITS: 5,
+} as const;
+
+/** Device trial record in Firestore */
+export interface DeviceTrialRecord {
+  deviceId: string;
+  hasUsedTrial: boolean;
+  trialStartedAt?: Date;
+  trialEndedAt?: Date;
+  trialConvertedAt?: Date;
+  lastUserId?: string;
+  userIds: string[];
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Trial eligibility result */
+export interface TrialEligibilityResult {
+  eligible: boolean;
+  reason?: "already_used" | "device_not_found" | "error";
+  deviceId?: string;
+}
+
+/**
+ * Get persistent device ID
+ */
+export async function getDeviceId(): Promise<string> {
+  return PersistentDeviceIdService.getDeviceId();
+}
+
+/**
+ * Check if device is eligible for trial
+ */
+export async function checkTrialEligibility(
+  deviceId?: string
+): Promise<TrialEligibilityResult> {
+  try {
+    const effectiveDeviceId = deviceId || await getDeviceId();
+    const db = getFirestore();
+
+    if (!db) {
+      if (__DEV__) {
+        console.log("[TrialService] No Firestore instance");
+      }
+      return { eligible: true, deviceId: effectiveDeviceId };
+    }
+
+    const trialRef = doc(db, DEVICE_TRIALS_COLLECTION, effectiveDeviceId);
+    const trialDoc = await getDoc(trialRef);
+
+    if (!trialDoc.exists()) {
+      if (__DEV__) {
+        console.log("[TrialService] No trial record found, eligible");
+      }
+      return { eligible: true, deviceId: effectiveDeviceId };
+    }
+
+    const data = trialDoc.data();
+    const hasUsedTrial = data?.hasUsedTrial === true;
+
+    if (__DEV__) {
+      console.log("[TrialService] Trial record found:", {
+        deviceId: effectiveDeviceId.slice(0, 8),
+        hasUsedTrial,
+      });
+    }
+
+    if (hasUsedTrial) {
+      return {
+        eligible: false,
+        reason: "already_used",
+        deviceId: effectiveDeviceId,
+      };
+    }
+
+    return { eligible: true, deviceId: effectiveDeviceId };
+  } catch (error) {
+    if (__DEV__) {
+      console.error("[TrialService] Eligibility check error:", error);
+    }
+    return { eligible: true, reason: "error" };
+  }
+}
+
+/**
+ * Record trial start for a device
+ */
+export async function recordTrialStart(
+  userId: string,
+  deviceId?: string
+): Promise<boolean> {
+  try {
+    const effectiveDeviceId = deviceId || await getDeviceId();
+    const db = getFirestore();
+
+    if (!db) {
+      if (__DEV__) {
+        console.log("[TrialService] No Firestore instance");
+      }
+      return false;
+    }
+
+    const trialRef = doc(db, DEVICE_TRIALS_COLLECTION, effectiveDeviceId);
+
+    await setDoc(
+      trialRef,
+      {
+        deviceId: effectiveDeviceId,
+        hasUsedTrial: true,
+        trialStartedAt: serverTimestamp(),
+        lastUserId: userId,
+        userIds: arrayUnion(userId),
+        updatedAt: serverTimestamp(),
+      },
+      { merge: true }
+    );
+
+    // Also set createdAt if it's a new record
+    const existingDoc = await getDoc(trialRef);
+    if (!existingDoc.data()?.createdAt) {
+      await setDoc(
+        trialRef,
+        { createdAt: serverTimestamp() },
+        { merge: true }
+      );
+    }
+
+    if (__DEV__) {
+      console.log("[TrialService] Trial recorded:", {
+        deviceId: effectiveDeviceId.slice(0, 8),
+        userId: userId.slice(0, 8),
+      });
+    }
+
+    return true;
+  } catch (error) {
+    if (__DEV__) {
+      console.error("[TrialService] Record trial error:", error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Record trial end (cancelled or expired)
+ */
+export async function recordTrialEnd(
+  deviceId?: string
+): Promise<boolean> {
+  try {
+    const effectiveDeviceId = deviceId || await getDeviceId();
+    const db = getFirestore();
+
+    if (!db) {
+      return false;
+    }
+
+    const trialRef = doc(db, DEVICE_TRIALS_COLLECTION, effectiveDeviceId);
+
+    await setDoc(
+      trialRef,
+      {
+        trialEndedAt: serverTimestamp(),
+        updatedAt: serverTimestamp(),
+      },
+      { merge: true }
+    );
+
+    if (__DEV__) {
+      console.log("[TrialService] Trial end recorded");
+    }
+
+    return true;
+  } catch (error) {
+    if (__DEV__) {
+      console.error("[TrialService] Record trial end error:", error);
+    }
+    return false;
+  }
+}
+
+/**
+ * Record trial conversion to paid subscription
+ */
+export async function recordTrialConversion(
+  deviceId?: string
+): Promise<boolean> {
+  try {
+    const effectiveDeviceId = deviceId || await getDeviceId();
+    const db = getFirestore();
+
+    if (!db) {
+      return false;
+    }
+
+    const trialRef = doc(db, DEVICE_TRIALS_COLLECTION, effectiveDeviceId);
+
+    await setDoc(
+      trialRef,
+      {
+        trialConvertedAt: serverTimestamp(),
+        updatedAt: serverTimestamp(),
+      },
+      { merge: true }
+    );
+
+    if (__DEV__) {
+      console.log("[TrialService] Trial conversion recorded");
+    }
+
+    return true;
+  } catch (error) {
+    if (__DEV__) {
+      console.error("[TrialService] Record conversion error:", error);
+    }
+    return false;
+  }
+}

package/src/presentation/components/details/PremiumStatusBadge.tsx

@@ -16,6 +16,10 @@ export interface PremiumStatusBadgeProps {
   expiredLabel: string;
   noneLabel: string;
   canceledLabel: string;
+  /** Label for trial status (defaults to activeLabel if not provided) */
+  trialLabel?: string;
+  /** Label for trial_canceled status (defaults to canceledLabel if not provided) */
+  trialCanceledLabel?: string;
 }
 
 export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = ({
@@ -24,11 +28,15 @@ export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = ({
   expiredLabel,
   noneLabel,
   canceledLabel,
+  trialLabel,
+  trialCanceledLabel,
 }) => {
   const tokens = useAppDesignTokens();
 
   const labels: Record<SubscriptionStatusType, string> = {
     active: activeLabel,
+    trial: trialLabel ?? activeLabel,
+    trial_canceled: trialCanceledLabel ?? canceledLabel,
     expired: expiredLabel,
     none: noneLabel,
     canceled: canceledLabel,
@@ -37,6 +45,8 @@ export const PremiumStatusBadge: React.FC<PremiumStatusBadgeProps> = ({
   const backgroundColor = useMemo(() => {
     const colors: Record<SubscriptionStatusType, string> = {
       active: tokens.colors.success,
+      trial: tokens.colors.primary, // Blue/purple for trial
+      trial_canceled: tokens.colors.warning, // Orange for trial canceled
       expired: tokens.colors.error,
       none: tokens.colors.textTertiary,
       canceled: tokens.colors.warning,

package/src/presentation/hooks/index.ts

@@ -20,5 +20,6 @@ export * from "./useSubscriptionSettingsConfig";
 export * from "./useSubscriptionStatus";
 export * from "./useUserTier";
 export * from "./useUserTierWithRepository";
+export * from "./useTrialEligibility";
 export * from "./feedback/usePaywallFeedback";
 export * from "./feedback/useFeedbackSubmit";

package/src/presentation/hooks/useSubscriptionSettingsConfig.ts

@@ -65,10 +65,13 @@ export const useSubscriptionSettingsConfig = (
   // Days remaining
   const daysRemaining = useMemo(() => calculateDaysRemaining(expiresAtIso), [expiresAtIso]);
 
-  // Status type: prioritize Firestore status, then derive from willRenew + expiration
+  // Period type from Firestore
+  const periodType = credits?.periodType;
+
+  // Status type: prioritize Firestore status, then derive from willRenew + expiration + periodType
   const statusType: SubscriptionStatusType = credits?.status
     ? (credits.status as SubscriptionStatusType)
-    : getSubscriptionStatusType(isPremium, willRenew, expiresAtIso);
+    : getSubscriptionStatusType(isPremium, willRenew, expiresAtIso, periodType);
 
   const creditsArray = useCreditsArray(credits, dynamicCreditLimit, translations);
 

package/src/presentation/hooks/useSubscriptionSettingsConfig.utils.ts

@@ -5,6 +5,7 @@
 
 import { useMemo } from "react";
 import type { UserCredits } from "../../domain/entities/Credits";
+import { resolveSubscriptionStatus, type PeriodType, type SubscriptionStatusType } from "../../domain/entities/SubscriptionStatus";
 import type { SubscriptionSettingsTranslations } from "../types/SubscriptionSettingsTypes";
 
 export interface CreditsInfo {
@@ -37,36 +38,20 @@ export function useCreditsArray(
 }
 
 /**
- * Calculates subscription status type based on premium and renewal status
- * @param isPremium - Whether user has premium subscription
- * @param willRenew - Whether subscription will auto-renew (false = canceled)
- * @param expiresAt - Expiration date ISO string (null for lifetime)
+ * Calculates subscription status type based on premium, renewal status, and period type
  */
 export function getSubscriptionStatusType(
   isPremium: boolean,
   willRenew?: boolean,
-  expiresAt?: string | null
-): "active" | "canceled" | "expired" | "none" {
-  if (!isPremium) {
-    return "none";
-  }
-
-  // Lifetime subscription (no expiration) - always active
-  if (!expiresAt) {
-    return "active";
-  }
-
-  // Check if expired
-  const now = new Date();
-  const expDate = new Date(expiresAt);
-  if (expDate < now) {
-    return "expired";
-  }
-
-  // Premium with willRenew=false means subscription is canceled but still active until expiration
-  if (willRenew === false) {
-    return "canceled";
-  }
-
-  return "active";
+  expiresAt?: string | null,
+  periodType?: PeriodType
+): SubscriptionStatusType {
+  const isExpired = expiresAt ? new Date(expiresAt) < new Date() : false;
+
+  return resolveSubscriptionStatus({
+    isPremium,
+    willRenew,
+    isExpired,
+    periodType,
+  });
 }

package/src/presentation/hooks/useTrialEligibility.ts

@@ -0,0 +1,66 @@
+/**
+ * useTrialEligibility Hook
+ * Checks if device is eligible for free trial
+ * Uses persistent device ID to prevent trial abuse
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import {
+  checkTrialEligibility,
+  getDeviceId,
+} from "../../infrastructure/services/TrialService";
+
+export interface UseTrialEligibilityResult {
+  /** Whether device is eligible for trial */
+  isEligible: boolean;
+  /** Whether eligibility check is in progress */
+  isLoading: boolean;
+  /** Reason why not eligible (if applicable) */
+  reason?: "already_used" | "device_not_found" | "error";
+  /** Device ID used for checking */
+  deviceId: string | null;
+  /** Refresh eligibility status */
+  refresh: () => Promise<void>;
+}
+
+/**
+ * Hook to check trial eligibility based on device ID
+ * Device ID persists across app reinstalls via Keychain
+ */
+export function useTrialEligibility(): UseTrialEligibilityResult {
+  const [isEligible, setIsEligible] = useState(true);
+  const [isLoading, setIsLoading] = useState(true);
+  const [reason, setReason] = useState<"already_used" | "device_not_found" | "error">();
+  const [deviceId, setDeviceId] = useState<string | null>(null);
+
+  const checkEligibility = useCallback(async () => {
+    setIsLoading(true);
+
+    try {
+      const id = await getDeviceId();
+      setDeviceId(id);
+
+      const result = await checkTrialEligibility(id);
+      setIsEligible(result.eligible);
+      setReason(result.reason);
+    } catch {
+      // On error, allow trial (better UX)
+      setIsEligible(true);
+      setReason("error");
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    checkEligibility();
+  }, [checkEligibility]);
+
+  return {
+    isEligible,
+    isLoading,
+    reason,
+    deviceId,
+    refresh: checkEligibility,
+  };
+}

package/src/presentation/types/SubscriptionDetailTypes.ts

@@ -16,6 +16,10 @@ export interface SubscriptionDetailTranslations {
   statusExpired: string;
   statusFree: string;
   statusCanceled: string;
+  /** Trial status label (defaults to statusActive if not provided) */
+  statusTrial?: string;
+  /** Trial canceled status label (defaults to statusCanceled if not provided) */
+  statusTrialCanceled?: string;
   expiresLabel: string;
   purchasedLabel: string;
   lifetimeLabel: string;
@@ -100,6 +104,8 @@ export interface SubscriptionHeaderProps {
     | "statusExpired"
     | "statusFree"
     | "statusCanceled"
+    | "statusTrial"
+    | "statusTrialCanceled"
     | "expiresLabel"
     | "purchasedLabel"
     | "lifetimeLabel"

package/src/presentation/types/SubscriptionSettingsTypes.ts

@@ -42,6 +42,10 @@ export interface SubscriptionSettingsTranslations {
   statusFree: string;
   statusExpired: string;
   statusCanceled: string;
+  /** Trial status label (defaults to statusActive if not provided) */
+  statusTrial?: string;
+  /** Trial canceled status label (defaults to statusCanceled if not provided) */
+  statusTrialCanceled?: string;
   /** Detail screen translations */
   statusLabel: string;
   expiresLabel: string;

package/src/revenuecat/domain/value-objects/RevenueCatConfig.ts

@@ -20,7 +20,9 @@ export interface RevenueCatConfig {
     isPremium: boolean,
     productId?: string,
     expiresAt?: string,
-    willRenew?: boolean
+    willRenew?: boolean,
+    /** RevenueCat period type: NORMAL, INTRO, or TRIAL */
+    periodType?: "NORMAL" | "INTRO" | "TRIAL"
   ) => Promise<void> | void;
   /** Callback for purchase completion */
   onPurchaseCompleted?: (

package/src/revenuecat/infrastructure/utils/PremiumStatusSyncer.ts

@@ -28,10 +28,11 @@ export async function syncPremiumStatus(
                 true,
                 premiumEntitlement.productIdentifier,
                 premiumEntitlement.expirationDate ?? undefined,
-                premiumEntitlement.willRenew
+                premiumEntitlement.willRenew,
+                premiumEntitlement.periodType as "NORMAL" | "INTRO" | "TRIAL" | undefined
             );
         } else {
-            await config.onPremiumStatusChanged(userId, false, undefined, undefined, undefined);
+            await config.onPremiumStatusChanged(userId, false, undefined, undefined, undefined, undefined);
         }
     } catch {
         // Silent error handling