@teardown/react-native 2.0.23 → 2.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@teardown/react-native",
-	"version": "2.0.23",
+	"version": "2.0.24",
 	"private": false,
 	"publishConfig": {
 		"access": "public"

package/src/clients/force-update/force-update.client.test.ts

@@ -259,7 +259,7 @@ describe("ForceUpdateClient", () => {
 		});
 	});
 
-	describe("throttle and cooldown", () => {
+	describe("checkIntervalMs", () => {
 		test("skips version check when identify returns null", async () => {
 			const mockIdentity = createMockIdentityClient();
 			const mockLogging = createMockLoggingClient();
@@ -268,8 +268,7 @@ describe("ForceUpdateClient", () => {
 			mockIdentity.setNextIdentifyResult(null);
 
 			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
-				throttleMs: 0,
-				checkCooldownMs: 0,
+				checkIntervalMs: 0,
 			});
 			client.initialize();
 
@@ -287,14 +286,13 @@ describe("ForceUpdateClient", () => {
 			client.shutdown();
 		});
 
-		test("checkCooldownMs -1 disables version checking entirely", async () => {
+		test("checkIntervalMs -1 disables version checking entirely", async () => {
 			const mockIdentity = createMockIdentityClient();
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
 			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
-				throttleMs: 0,
-				checkCooldownMs: -1,
+				checkIntervalMs: -1,
 			});
 			client.initialize();
 
@@ -310,47 +308,46 @@ describe("ForceUpdateClient", () => {
 			client.shutdown();
 		});
 
-		test("throttle prevents rapid foreground checks", async () => {
+		test("interval prevents checks too soon after successful check", async () => {
 			const mockIdentity = createMockIdentityClient();
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
 			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
-				checkOnForeground: false,
-				throttleMs: 100,
-				checkCooldownMs: 0,
+				checkOnForeground: true,
+				checkIntervalMs: 100_000,
 			});
 			client.initialize();
 
 			const foregroundHandler = mockAppStateListeners[0];
 
-			// First foreground
+			// First foreground - should trigger check
 			await foregroundHandler("active");
 			await new Promise((r) => setTimeout(r, 10));
 
 			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
 
-			// Second foreground immediately (within throttle window)
+			// Second foreground immediately (within interval window)
 			await foregroundHandler("active");
 			await new Promise((r) => setTimeout(r, 10));
 
 			const callsAfterSecond = mockIdentity.getIdentifyCallCount();
 
-			// Only first call should have triggered identify (throttle blocks second)
+			// Only first call should have triggered identify (interval blocks second)
 			expect(callsAfterFirst).toBe(1);
 			expect(callsAfterSecond).toBe(1);
 
 			client.shutdown();
 		});
 
-		test("checkOnForeground: true always checks on foreground", async () => {
+		test("checkOnForeground: true respects interval", async () => {
 			const mockIdentity = createMockIdentityClient();
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
 			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
 				checkOnForeground: true,
-				throttleMs: 100_000,
+				checkIntervalMs: 100_000,
 			});
 			client.initialize();
 
@@ -362,28 +359,77 @@ describe("ForceUpdateClient", () => {
 
 			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
 
-			// Second foreground immediately (within throttle window)
+			// Second foreground immediately (within interval window)
 			await foregroundHandler("active");
 			await new Promise((r) => setTimeout(r, 10));
 
 			const callsAfterSecond = mockIdentity.getIdentifyCallCount();
 
-			// Both should trigger identify calls with checkOnForeground: true
+			// Only first should trigger - interval blocks second even with checkOnForeground: true
 			expect(callsAfterFirst).toBe(1);
-			expect(callsAfterSecond).toBe(2);
+			expect(callsAfterSecond).toBe(1);
 
 			client.shutdown();
 		});
 
-		test("cooldown prevents checks too soon after successful check", async () => {
+		test("checkOnForeground: false disables foreground checking entirely", async () => {
 			const mockIdentity = createMockIdentityClient();
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
 			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
 				checkOnForeground: false,
-				throttleMs: 0,
-				checkCooldownMs: 100_000,
+				checkIntervalMs: 0, // Would normally allow every check
+			});
+			client.initialize();
+
+			const foregroundHandler = mockAppStateListeners[0];
+
+			// Foreground should not trigger check when checkOnForeground is false
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			expect(mockIdentity.getIdentifyCallCount()).toBe(0);
+
+			client.shutdown();
+		});
+
+		test("checkIntervalMs 0 checks on every foreground", async () => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkOnForeground: true,
+				checkIntervalMs: 0,
+			});
+			client.initialize();
+
+			const foregroundHandler = mockAppStateListeners[0];
+
+			// First foreground
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			// Second foreground immediately
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			// Both should trigger since interval is 0
+			expect(mockIdentity.getIdentifyCallCount()).toBe(2);
+
+			client.shutdown();
+		});
+
+		test("values below 30s are clamped to 30s minimum", async () => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			// Set interval to 10ms (below 30s minimum)
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkOnForeground: true,
+				checkIntervalMs: 10,
 			});
 			client.initialize();
 
@@ -395,13 +441,13 @@ describe("ForceUpdateClient", () => {
 
 			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
 
-			// Second foreground immediately (within cooldown window)
+			// Second foreground immediately - should be blocked by 30s minimum
 			await foregroundHandler("active");
 			await new Promise((r) => setTimeout(r, 10));
 
 			const callsAfterSecond = mockIdentity.getIdentifyCallCount();
 
-			// Only first call should have triggered identify (cooldown blocks second)
+			// Only first call should have triggered (30s minimum enforced)
 			expect(callsAfterFirst).toBe(1);
 			expect(callsAfterSecond).toBe(1);
 

package/src/clients/force-update/force-update.client.ts

@@ -69,41 +69,30 @@ export interface VersionStatusChangeEvents {
 
 export type ForceUpdateClientOptions = {
 	/**
-	 * Minimum time (ms) between foreground transitions to prevent rapid-fire checks.
-	 * Measured from the last time the app came to foreground.
-	 * Prevents checking when user quickly switches apps back and forth.
-	 * Default: 30000 (30 seconds)
-	 *
-	 * Special values:
-	 * - -1: Disable throttling, check on every foreground (respects checkCooldownMs)
-	 *
-	 * Example: If throttleMs is 30s and user backgrounds then foregrounds the app
-	 * twice within 20s, only the first transition triggers a check.
-	 */
-	throttleMs?: number;
-	/**
-	 * Minimum time (ms) since the last successful version check before checking again.
-	 * Measured from when the last check completed successfully (not when it started).
-	 * Prevents unnecessary API calls after we already have fresh version data.
+	 * Minimum time (ms) between version checks.
 	 * Default: 300000 (5 minutes)
 	 *
+	 * Values below 30 seconds are clamped to 30 seconds to prevent excessive API calls.
+	 *
 	 * Special values:
-	 * - 0: Disable cooldown, check on every foreground (respects throttleMs)
-	 * - -1: Disable all automatic version checking
+	 * - 0: Check on every foreground (no interval)
+	 * - -1: Disable automatic version checking entirely
 	 *
-	 * Example: If checkCooldownMs is 5min and a check completes at 12:00pm,
+	 * Example: If checkIntervalMs is 5min and a check completes at 12:00pm,
 	 * no new checks occur until 12:05pm, even if user foregrounds the app multiple times.
 	 */
-	checkCooldownMs?: number;
-	/** Always check on foreground, ignoring throttle (default: true) */
+	checkIntervalMs?: number;
+	/** Check version when app comes to foreground, respecting checkIntervalMs (default: true) */
 	checkOnForeground?: boolean;
 	/** If true, check version even when not identified by using anonymous device identification (default: false) */
 	identifyAnonymousDevice?: boolean;
 };
 
+/** Hard minimum interval between checks to prevent excessive API calls */
+const MIN_CHECK_INTERVAL_MS = 30_000; // 30 seconds
+
 const DEFAULT_OPTIONS: Required<ForceUpdateClientOptions> = {
-	throttleMs: 30_000, // 30 seconds
-	checkCooldownMs: 300_000, // 5 minutes
+	checkIntervalMs: 300_000, // 5 minutes
 	checkOnForeground: true,
 	identifyAnonymousDevice: false,
 };
@@ -116,7 +105,6 @@ export class ForceUpdateClient {
 	private unsubscribe: (() => void) | null = null;
 	private appStateSubscription: NativeEventSubscription | null = null;
 	private lastCheckTime: number | null = null;
-	private lastForegroundTime: number | null = null;
 	private initialized = false;
 
 	private readonly logger: Logger;
@@ -132,7 +120,6 @@ export class ForceUpdateClient {
 		this.logger = logging.createLogger({ name: "ForceUpdateClient" });
 		this.storage = storage.createStorage("version");
 		this.options = { ...DEFAULT_OPTIONS, ...options };
-		// Don't initialize here - defer to initialize()
 	}
 
 	initialize(): void {
@@ -142,7 +129,6 @@ export class ForceUpdateClient {
 		}
 		this.initialized = true;
 
-		// Load from storage, subscribe to events, and sync with current identity state
 		this.versionStatus = this.getVersionStatusFromStorage();
 		this.logger.debug(`Initialized with version status: ${this.versionStatus.type}`);
 		this.subscribeToIdentity();
@@ -164,25 +150,30 @@ export class ForceUpdateClient {
 	}
 
 	private getVersionStatusFromStorage(): VersionStatus {
-		const stored = this.storage.getItem(VERSION_STATUS_STORAGE_KEY);
+		try {
+			const stored = this.storage.getItem(VERSION_STATUS_STORAGE_KEY);
 
-		if (stored == null) {
-			this.logger.debug("No stored version status, returning initializing");
-			return InitializingVersionStatusSchema.parse({ type: "initializing" });
-		}
+			if (stored == null) {
+				this.logger.debug("No stored version status, returning initializing");
+				return InitializingVersionStatusSchema.parse({ type: "initializing" });
+			}
 
-		const parsed = VersionStatusSchema.parse(JSON.parse(stored));
-		this.logger.debug(`Parsed version status from storage: ${parsed.type}`);
+			const parsed = VersionStatusSchema.parse(JSON.parse(stored));
+			this.logger.debug(`Parsed version status from storage: ${parsed.type}`);
+
+			// "checking" and "initializing" are transient states - if we restore them, reset to initializing
+			// This can happen if the app was killed during a version check
+			if (parsed.type === "checking" || parsed.type === "initializing") {
+				this.logger.debug(`Found stale '${parsed.type}' state in storage, resetting to initializing`);
+				this.storage.removeItem(VERSION_STATUS_STORAGE_KEY);
+				return InitializingVersionStatusSchema.parse({ type: "initializing" });
+			}
 
-		// "checking" and "initializing" are transient states - if we restore them, reset to initializing
-		// This can happen if the app was killed during a version check
-		if (parsed.type === "checking" || parsed.type === "initializing") {
-			this.logger.debug(`Found stale '${parsed.type}' state in storage, resetting to initializing`);
-			this.storage.removeItem(VERSION_STATUS_STORAGE_KEY);
+			return parsed;
+		} catch (error) {
+			this.logger.debugError("Error getting version status from storage", { error });
 			return InitializingVersionStatusSchema.parse({ type: "initializing" });
 		}
-
-		return parsed;
 	}
 
 	private saveVersionStatusToStorage(status: VersionStatus): void {
@@ -239,30 +230,22 @@ export class ForceUpdateClient {
 		if (nextState === "active") {
 			this.logger.debug("App state changed to active");
 
-			// If checkCooldownMs is -1, disable checking entirely
-			if (this.options.checkCooldownMs === -1) {
-				this.logger.debug("Version checking disabled (checkCooldownMs = -1)");
+			// If checkIntervalMs is -1, disable checking entirely
+			if (this.options.checkIntervalMs === -1) {
+				this.logger.debug("Version checking disabled (checkIntervalMs = -1)");
 				return;
 			}
 
 			const now = Date.now();
 
-			// If throttleMs is -1, disable throttling (always pass)
-			// Otherwise, check if enough time has passed since last foreground
-			const throttleOk =
-				this.options.throttleMs === -1 ||
-				!this.lastForegroundTime ||
-				now - this.lastForegroundTime >= this.options.throttleMs;
-
-			// If checkCooldownMs is 0, always allow check (no cooldown)
-			// Otherwise, check if enough time has passed since last successful check
-			const cooldownOk =
-				this.options.checkCooldownMs === 0 ||
-				!this.lastCheckTime ||
-				now - this.lastCheckTime >= this.options.checkCooldownMs;
-
-			if (this.options.checkOnForeground || (throttleOk && cooldownOk)) {
-				this.lastForegroundTime = now;
+			// Calculate effective interval (clamp to minimum unless 0 for "always check")
+			const effectiveInterval =
+				this.options.checkIntervalMs === 0 ? 0 : Math.max(this.options.checkIntervalMs, MIN_CHECK_INTERVAL_MS);
+
+			// Check if enough time has passed since last successful check
+			const canCheck = effectiveInterval === 0 || !this.lastCheckTime || now - this.lastCheckTime >= effectiveInterval;
+
+			if (this.options.checkOnForeground && canCheck) {
 				this.checkVersionOnForeground();
 			}
 		}

package/src/clients/identity/identity.client.test.ts

@@ -25,6 +25,8 @@ function createMockLoggingClient() {
 			warn: (message: string, ...args: unknown[]) => logs.push({ level: "warn", message, args }),
 			error: (message: string, ...args: unknown[]) => logs.push({ level: "error", message, args }),
 			debug: (message: string, ...args: unknown[]) => logs.push({ level: "debug", message, args }),
+			debugInfo: (message: string, ...args: unknown[]) => logs.push({ level: "debugInfo", message, args }),
+			debugError: (message: string, ...args: unknown[]) => logs.push({ level: "debugError", message, args }),
 		}),
 		getLogs: () => logs,
 		clearLogs: () => {
@@ -256,20 +258,26 @@ describe("IdentityClient", () => {
 			expect(client.getIdentifyState().type).toBe("unidentified");
 		});
 
-		test("throws error on invalid stored state (corrupt JSON)", () => {
+		test("gracefully handles invalid stored state (corrupt JSON)", () => {
 			const mockStorage = createMockStorageClient();
 			mockStorage.getStorage().set(IDENTIFY_STORAGE_KEY, "not-valid-json{{{");
 
 			const { client } = createTestClient({ storage: mockStorage });
-			expect(() => loadStateFromStorage(client)).toThrow();
+			loadStateFromStorage(client);
+
+			// Should gracefully fall back to unidentified state
+			expect(client.getIdentifyState().type).toBe("unidentified");
 		});
 
-		test("throws error on invalid stored state (schema mismatch)", () => {
+		test("gracefully handles invalid stored state (schema mismatch)", () => {
 			const mockStorage = createMockStorageClient();
 			mockStorage.getStorage().set(IDENTIFY_STORAGE_KEY, JSON.stringify({ type: "invalid_type" }));
 
 			const { client } = createTestClient({ storage: mockStorage });
-			expect(() => loadStateFromStorage(client)).toThrow();
+			loadStateFromStorage(client);
+
+			// Should gracefully fall back to unidentified state
+			expect(client.getIdentifyState().type).toBe("unidentified");
 		});
 
 		test("creates logger with correct name", () => {
@@ -627,10 +635,10 @@ describe("IdentityClient", () => {
 
 			// Should have debug logs about state transitions
 			// When already identified, identify() will transition: identified -> identifying -> identified
-			const debugLogs = mockLogging.getLogs().filter((l) => l.level === "debug");
+			const debugLogs = mockLogging.getLogs().filter((l) => l.level === "debug" || l.level === "debugInfo");
 			expect(debugLogs.length).toBeGreaterThan(0);
 			// Check that state transitions are logged
-			expect(debugLogs.some((l) => l.message.includes("Identify state:"))).toBe(true);
+			expect(debugLogs.some((l) => l.message.includes("Identify state"))).toBe(true);
 		});
 	});