@umituz/react-native-subscription 2.24.17 → 2.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umituz/react-native-subscription",
-  "version": "2.24.17",
+  "version": "2.25.0",
   "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

@@ -19,7 +19,10 @@ export type PurchaseSource =
 
 export type PurchaseType = "initial" | "renewal" | "upgrade" | "downgrade";
 
-export type SubscriptionStatus = "active" | "expired" | "canceled" | "free";
+export type SubscriptionStatus = "active" | "trial" | "trial_canceled" | "expired" | "canceled" | "free";
+
+/** RevenueCat period types */
+export type PeriodType = "NORMAL" | "INTRO" | "TRIAL";
 
 /** Single Source of Truth for user subscription + credits data */
 export interface UserCredits {
@@ -38,6 +41,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,16 @@ 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 types */
+export type PeriodType = "NORMAL" | "INTRO" | "TRIAL";
+
 export type SubscriptionStatusType = (typeof SUBSCRIPTION_STATUS)[keyof typeof SUBSCRIPTION_STATUS];
 
 export interface SubscriptionStatus {
@@ -17,6 +22,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 => ({

package/src/index.ts

@@ -8,7 +8,7 @@ export * from "./domains/config";
 
 // Domain Layer
 export { createDefaultSubscriptionStatus, isSubscriptionValid } from "./domain/entities/SubscriptionStatus";
-export type { SubscriptionStatus, SubscriptionStatusType } from "./domain/entities/SubscriptionStatus";
+export type { SubscriptionStatus, SubscriptionStatusType, PeriodType } from "./domain/entities/SubscriptionStatus";
 export type { SubscriptionConfig } from "./domain/value-objects/SubscriptionConfig";
 export type { ISubscriptionRepository } from "./application/ports/ISubscriptionRepository";
 
@@ -22,6 +22,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,14 @@
-import type { UserCredits, SubscriptionStatus } from "../../domain/entities/Credits";
+import type { UserCredits, SubscriptionStatus, PeriodType } from "../../domain/entities/Credits";
 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 +26,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,12 +46,14 @@ export class CreditsMapper {
     };
   }
 
-  /** Validate subscription status against expirationDate */
+  /** Validate subscription status against expirationDate and periodType */
   private static validateSubscription(
     doc: UserCreditsDocumentRead,
-    expirationDate: Date | null
+    expirationDate: Date | null,
+    periodType?: PeriodType
   ): { isPremium: boolean; status: SubscriptionStatus } {
     const docIsPremium = doc.isPremium ?? false;
+    const willRenew = doc.willRenew ?? false;
 
     // No expiration date = lifetime or free
     if (!expirationDate) {
@@ -60,6 +71,19 @@ export class CreditsMapper {
       return { isPremium: false, status: "expired" };
     }
 
+    // Handle trial period
+    if (periodType === "TRIAL") {
+      return {
+        isPremium: docIsPremium,
+        status: willRenew === false ? "trial_canceled" : "trial",
+      };
+    }
+
+    // Handle canceled subscription (will not renew but still active)
+    if (docIsPremium && willRenew === false) {
+      return { isPremium: true, status: "canceled" };
+    }
+
     // Subscription still active
     return {
       isPremium: docIsPremium,

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

@@ -16,7 +16,9 @@ import type {
   PurchaseType,
   PurchaseMetadata,
   SubscriptionDocStatus,
+  PeriodType,
 } from "../models/UserCreditsDocument";
+import { TRIAL_CONFIG } from "./TrialService";
 import { detectPackageType } from "../../utils/packageTypeDetector";
 import { getCreditAllocation } from "../../utils/creditMapper";
 
@@ -34,6 +36,8 @@ export interface InitializeCreditsMetadata {
   willRenew?: boolean;
   originalTransactionId?: string;
   isPremium?: boolean;
+  /** RevenueCat period type: NORMAL, INTRO, or TRIAL */
+  periodType?: PeriodType;
 }
 
 export async function initializeCreditsTransaction(
@@ -122,20 +126,37 @@ export async function initializeCreditsTransaction(
           ? [...(existing?.purchaseHistory || []), purchaseMetadata].slice(-10)
           : existing?.purchaseHistory;
 
-        // Determine subscription status based on isPremium and willRenew
+        // Determine subscription status based on isPremium, willRenew, and periodType
         const isPremium = metadata?.isPremium ?? true;
         const willRenew = metadata?.willRenew;
-
-        // Status logic: canceled if premium but willRenew=false, expired if not premium, active otherwise
+        const periodType = metadata?.periodType;
+        const isTrialing = periodType === "TRIAL";
+
+        // Status logic:
+        // - trial: periodType is TRIAL and premium
+        // - trial_canceled: periodType is TRIAL and premium but willRenew=false
+        // - canceled: premium but willRenew=false (non-trial)
+        // - expired: not premium
+        // - active: premium and will renew (non-trial)
         let status: SubscriptionDocStatus;
         if (!isPremium) {
             status = "expired";
+        } else if (isTrialing) {
+            status = willRenew === false ? "trial_canceled" : "trial";
         } else if (willRenew === false) {
             status = "canceled";
         } else {
             status = "active";
         }
 
+        // Determine credits based on status
+        // Trial: 5 credits, Trial canceled: 0 credits, Normal: plan-based credits
+        if (status === "trial") {
+            newCredits = TRIAL_CONFIG.CREDITS;
+        } else if (status === "trial_canceled") {
+            newCredits = 0;
+        }
+
         // Build credits data (Single Source of Truth)
         const creditsData: Record<string, unknown> = {
             // Core subscription
@@ -176,6 +197,26 @@ export async function initializeCreditsTransaction(
             creditsData.appVersion = appVersion;
         }
 
+        // Trial-specific fields
+        if (periodType) {
+            creditsData.periodType = periodType;
+        }
+        if (isTrialing) {
+            creditsData.isTrialing = true;
+            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 && !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

@@ -37,16 +37,18 @@ export function useCreditsArray(
 }
 
 /**
- * Calculates subscription status type based on premium and renewal status
+ * Calculates subscription status type based on premium, renewal status, and period type
  * @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)
+ * @param periodType - RevenueCat period type: NORMAL, INTRO, or TRIAL
  */
 export function getSubscriptionStatusType(
   isPremium: boolean,
   willRenew?: boolean,
-  expiresAt?: string | null
-): "active" | "canceled" | "expired" | "none" {
+  expiresAt?: string | null,
+  periodType?: "NORMAL" | "INTRO" | "TRIAL"
+): "active" | "trial" | "trial_canceled" | "canceled" | "expired" | "none" {
   if (!isPremium) {
     return "none";
   }
@@ -63,6 +65,11 @@ export function getSubscriptionStatusType(
     return "expired";
   }
 
+  // Trial period handling
+  if (periodType === "TRIAL") {
+    return willRenew === false ? "trial_canceled" : "trial";
+  }
+
   // Premium with willRenew=false means subscription is canceled but still active until expiration
   if (willRenew === false) {
     return "canceled";

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