@teardown/react-native 2.0.22 → 2.0.24

package/package.json

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

package/src/clients/api/api.client.ts

@@ -37,7 +37,6 @@ export type ApiClientOptions = {
 	 * @returns The options for the request.
 	 */
 	onRequest?: (endpoint: IngestApi.Endpoints, options: IngestApi.RequestOptions) => Promise<IngestApi.RequestOptions>;
-
 	/**
 	 * The URL of the ingest API.
 	 * @default https://ingest.teardown.dev

package/src/clients/device/device.client.ts

@@ -31,9 +31,9 @@ export enum DevicePlatformEnum {
 	OTHER = "OTHER",
 }
 
-export type DeviceClientOptions = {
+export interface DeviceClientOptions {
 	adapter: DeviceInfoAdapter;
-};
+}
 export class DeviceClient {
 	private logger: Logger;
 	private storage: SupportedStorage;

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

@@ -1,4 +1,4 @@
-import { describe, test, expect, beforeEach, mock } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 import { EventEmitter } from "eventemitter3";
 import { ForceUpdateClient, IdentifyVersionStatusEnum, VERSION_STATUS_STORAGE_KEY } from "./force-update.client";
 
@@ -21,10 +21,11 @@ function createMockIdentityClient(initialState?: IdentifyState) {
 	const emitter = new EventEmitter<IdentifyStateChangeEvents>();
 	let identifyCallCount = 0;
 	let currentState: IdentifyState = initialState ?? { type: "unidentified" };
-	let nextIdentifyResult: { success: boolean; data?: { version_info: { status: IdentifyVersionStatusEnum } } } | null = {
-		success: true,
-		data: { version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE } },
-	};
+	let nextIdentifyResult: { success: boolean; data?: { version_info: { status: IdentifyVersionStatusEnum } } } | null =
+		{
+			success: true,
+			data: { version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE } },
+		};
 
 	return {
 		emitter,
@@ -43,7 +44,10 @@ function createMockIdentityClient(initialState?: IdentifyState) {
 			currentState = {
 				type: "identified",
 				session: { session_id: "s1", device_id: "d1", user_id: "p1", token: "t1" },
-				version_info: { status: nextIdentifyResult.data?.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE, update: null },
+				version_info: {
+					status: nextIdentifyResult.data?.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE,
+					update: null,
+				},
 			};
 			emitter.emit("IDENTIFY_STATE_CHANGED", currentState);
 			return nextIdentifyResult;
@@ -58,10 +62,10 @@ function createMockIdentityClient(initialState?: IdentifyState) {
 function createMockLoggingClient() {
 	return {
 		createLogger: () => ({
-			info: () => { },
-			warn: () => { },
-			error: () => { },
-			debug: () => { },
+			info: () => {},
+			warn: () => {},
+			error: () => {},
+			debug: () => {},
 		}),
 	};
 }
@@ -93,11 +97,7 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should immediately have update_required status from initialization
@@ -111,11 +111,7 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should stay in initializing since not yet identified
@@ -135,11 +131,7 @@ describe("ForceUpdateClient", () => {
 
 			const statusChanges: VersionStatus[] = [];
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Subscribe after construction to verify initial status was set
@@ -166,18 +158,15 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never,
-				{ throttleMs: 0, checkCooldownMs: 0 }
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkOnForeground: true,
+			});
 			client.initialize();
 
 			const statusChanges: VersionStatus[] = [];
 			client.onVersionStatusChange((status) => statusChanges.push(status));
 
-			// Trigger identify via state change
+			// Trigger identify via identify state change
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", { type: "identifying" });
 			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
 				type: "identified",
@@ -203,12 +192,9 @@ describe("ForceUpdateClient", () => {
 				data: { version_info: { status: IdentifyVersionStatusEnum.UPDATE_REQUIRED } },
 			});
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never,
-				{ throttleMs: 0, checkCooldownMs: 0 }
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkOnForeground: true,
+			});
 			client.initialize();
 
 			const statusChanges: VersionStatus[] = [];
@@ -238,11 +224,7 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			const statusChanges: VersionStatus[] = [];
@@ -266,11 +248,7 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			expect(mockAppStateListeners).toHaveLength(1);
@@ -281,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();
@@ -289,12 +267,9 @@ describe("ForceUpdateClient", () => {
 
 			mockIdentity.setNextIdentifyResult(null);
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never,
-				{ throttleMs: 0, checkCooldownMs: 0 }
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkIntervalMs: 0,
+			});
 			client.initialize();
 
 			const statusChanges: VersionStatus[] = [];
@@ -311,17 +286,14 @@ 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 }
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkIntervalMs: -1,
+			});
 			client.initialize();
 
 			const foregroundHandler = mockAppStateListeners[0];
@@ -336,17 +308,47 @@ 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,
-				{ throttleMs: 1000, checkCooldownMs: 0 }
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never, {
+				checkOnForeground: true,
+				checkIntervalMs: 100_000,
+			});
+			client.initialize();
+
+			const foregroundHandler = mockAppStateListeners[0];
+
+			// First foreground - should trigger check
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
+
+			// 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 (interval blocks second)
+			expect(callsAfterFirst).toBe(1);
+			expect(callsAfterSecond).toBe(1);
+
+			client.shutdown();
+		});
+
+		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,
+				checkIntervalMs: 100_000,
+			});
 			client.initialize();
 
 			const foregroundHandler = mockAppStateListeners[0];
@@ -357,30 +359,78 @@ 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();
 
-			// Should only have one identify call due to throttle
+			// Only first should trigger - interval blocks second even with checkOnForeground: true
 			expect(callsAfterFirst).toBe(1);
 			expect(callsAfterSecond).toBe(1);
 
 			client.shutdown();
 		});
 
-		test("cooldown prevents redundant checks after recent success", 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,
+				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,
-				{ throttleMs: 0, checkCooldownMs: 5000 }
-			);
+			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();
 
 			const foregroundHandler = mockAppStateListeners[0];
@@ -391,13 +441,13 @@ describe("ForceUpdateClient", () => {
 
 			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
 
-			// Second foreground (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);
 
@@ -414,11 +464,7 @@ describe("ForceUpdateClient", () => {
 			// Pre-populate storage with stale "checking" state
 			mockStorage.getStorage().set(VERSION_STATUS_STORAGE_KEY, JSON.stringify({ type: "checking" }));
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should reset to initializing, not stay in checking
@@ -435,11 +481,7 @@ describe("ForceUpdateClient", () => {
 			// Pre-populate storage with stale "initializing" state
 			mockStorage.getStorage().set(VERSION_STATUS_STORAGE_KEY, JSON.stringify({ type: "initializing" }));
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should reset to initializing (which it already is, but storage should be cleared)
@@ -456,11 +498,7 @@ describe("ForceUpdateClient", () => {
 			// Pre-populate storage with valid state
 			mockStorage.getStorage().set(VERSION_STATUS_STORAGE_KEY, JSON.stringify({ type: "up_to_date" }));
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should keep up_to_date from storage
@@ -477,11 +515,7 @@ describe("ForceUpdateClient", () => {
 			// Pre-populate storage with valid state
 			mockStorage.getStorage().set(VERSION_STATUS_STORAGE_KEY, JSON.stringify({ type: "update_required" }));
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			// Should keep update_required from storage
@@ -503,11 +537,7 @@ describe("ForceUpdateClient", () => {
 			const mockLogging = createMockLoggingClient();
 			const mockStorage = createMockStorageClient();
 
-			const client = new ForceUpdateClient(
-				mockLogging as never,
-				mockStorage as never,
-				mockIdentity as never
-			);
+			const client = new ForceUpdateClient(mockLogging as never, mockStorage as never, mockIdentity as never);
 			client.initialize();
 
 			const statusChanges: VersionStatus[] = [];

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

@@ -29,7 +29,6 @@ export enum IdentifyVersionStatusEnum {
 	DISABLED = "DISABLED",
 }
 
-
 export const InitializingVersionStatusSchema = z.object({ type: z.literal("initializing") });
 export const CheckingVersionStatusSchema = z.object({ type: z.literal("checking") });
 export const UpToDateVersionStatusSchema = z.object({ type: z.literal("up_to_date") });
@@ -64,43 +63,38 @@ export type UpdateRequiredVersionStatus = z.infer<typeof UpdateRequiredVersionSt
 export type DisabledVersionStatus = z.infer<typeof DisabledVersionStatusSchema>;
 export type VersionStatus = z.infer<typeof VersionStatusSchema>;
 
-export type VersionStatusChangeEvents = {
+export interface VersionStatusChangeEvents {
 	VERSION_STATUS_CHANGED: (status: VersionStatus) => void;
-};
+}
 
 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
-	 * 
-	 * Example: If checkCooldownMs is 5min and a check completes at 12:00pm,
+	 * - 0: Check on every foreground (no interval)
+	 * - -1: Disable automatic version checking entirely
+	 *
+	 * 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;
+	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,
 };
 
 export const VERSION_STATUS_STORAGE_KEY = "version_status";
@@ -111,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;
@@ -127,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 {
@@ -137,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();
@@ -149,7 +140,9 @@ export class ForceUpdateClient {
 		const currentState = this.identity.getIdentifyState();
 		this.logger.debug(`Current identity state during init: ${currentState.type}`);
 		if (currentState.type === "identified") {
-			this.logger.debug(`Identity already identified, syncing version status from: ${currentState.version_info.status}`);
+			this.logger.debug(
+				`Identity already identified, syncing version status from: ${currentState.version_info.status}`
+			);
 			this.updateFromVersionStatus(currentState.version_info.status);
 		} else {
 			this.logger.debug(`Identity not yet identified (${currentState.type}), waiting for identify event`);
@@ -157,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 {
@@ -232,29 +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;
+			// 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);
 
-			this.lastForegroundTime = now;
+			// Check if enough time has passed since last successful check
+			const canCheck = effectiveInterval === 0 || !this.lastCheckTime || now - this.lastCheckTime >= effectiveInterval;
 
-			if (throttleOk && cooldownOk) {
+			if (this.options.checkOnForeground && canCheck) {
 				this.checkVersionOnForeground();
 			}
 		}
@@ -304,5 +295,4 @@ export class ForceUpdateClient {
 		}
 		this.emitter.removeAllListeners("VERSION_STATUS_CHANGED");
 	}
-
 }

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

@@ -3,7 +3,7 @@ import { describe, expect, mock, test, beforeEach } from "bun:test";
 // Mock react-native before any imports that use it
 mock.module("react-native", () => ({
 	AppState: {
-		addEventListener: () => ({ remove: () => { } }),
+		addEventListener: () => ({ remove: () => {} }),
 	},
 }));
 
@@ -25,9 +25,13 @@ 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: () => { logs.length = 0; },
+		clearLogs: () => {
+			logs.length = 0;
+		},
 	};
 }
 
@@ -48,19 +52,23 @@ function createMockUtilsClient() {
 	let uuidCounter = 0;
 	return {
 		generateRandomUUID: async () => `mock-uuid-${++uuidCounter}`,
-		resetCounter: () => { uuidCounter = 0; },
+		resetCounter: () => {
+			uuidCounter = 0;
+		},
 	};
 }
 
-function createMockDeviceClient(overrides: Partial<{
-	deviceId: string;
-	timestamp: string;
-	application: { name: string; version: string; build: string; bundle_id: string };
-	hardware: { brand: string; model: string; device_type: string };
-	os: { name: string; version: string };
-	notifications: { push_token: string | null; platform: string | null };
-	update: null;
-}> = {}) {
+function createMockDeviceClient(
+	overrides: Partial<{
+		deviceId: string;
+		timestamp: string;
+		application: { name: string; version: string; build: string; bundle_id: string };
+		hardware: { brand: string; model: string; device_type: string };
+		os: { name: string; version: string };
+		notifications: { push_token: string | null; platform: string | null };
+		update: null;
+	}> = {}
+) {
 	const defaultDeviceInfo = {
 		timestamp: new Date().toISOString(),
 		application: { name: "TestApp", version: "1.0.0", build: "100", bundle_id: "com.test.app" },
@@ -88,17 +96,19 @@ type ApiCallRecord = {
 	};
 };
 
-function createMockApiClient(options: {
-	success?: boolean;
-	versionStatus?: (typeof IdentifyVersionStatusEnum)[keyof typeof IdentifyVersionStatusEnum];
-	errorStatus?: number;
-	errorMessage?: string;
-	sessionId?: string;
-	deviceId?: string;
-	user_id?: string;
-	token?: string;
-	throwError?: Error;
-} = {}) {
+function createMockApiClient(
+	options: {
+		success?: boolean;
+		versionStatus?: (typeof IdentifyVersionStatusEnum)[keyof typeof IdentifyVersionStatusEnum];
+		errorStatus?: number;
+		errorMessage?: string;
+		sessionId?: string;
+		deviceId?: string;
+		user_id?: string;
+		token?: string;
+		throwError?: Error;
+	} = {}
+) {
 	const {
 		success = true,
 		versionStatus = IdentifyVersionStatusEnum.UP_TO_DATE,
@@ -152,18 +162,22 @@ function createMockApiClient(options: {
 		},
 		getCalls: () => calls,
 		getLastCall: () => calls[calls.length - 1],
-		clearCalls: () => { calls.length = 0; },
+		clearCalls: () => {
+			calls.length = 0;
+		},
 	};
 }
 
 // Helper to create a standard client instance
-function createTestClient(overrides: {
-	logging?: ReturnType<typeof createMockLoggingClient>;
-	storage?: ReturnType<typeof createMockStorageClient>;
-	utils?: ReturnType<typeof createMockUtilsClient>;
-	api?: ReturnType<typeof createMockApiClient>;
-	device?: ReturnType<typeof createMockDeviceClient>;
-} = {}) {
+function createTestClient(
+	overrides: {
+		logging?: ReturnType<typeof createMockLoggingClient>;
+		storage?: ReturnType<typeof createMockStorageClient>;
+		utils?: ReturnType<typeof createMockUtilsClient>;
+		api?: ReturnType<typeof createMockApiClient>;
+		device?: ReturnType<typeof createMockDeviceClient>;
+	} = {}
+) {
 	const mockLogging = overrides.logging ?? createMockLoggingClient();
 	const mockStorage = overrides.storage ?? createMockStorageClient();
 	const mockUtils = overrides.utils ?? createMockUtilsClient();
@@ -244,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", () => {
@@ -550,7 +570,17 @@ describe("IdentityClient", () => {
 			await client.identify();
 
 			const lastCall = mockApi.getLastCall();
-			const device = (lastCall.config.body as { device?: { timestamp: string; application: { name: string; version: string; build: string; bundle_id: string }; os: { name: string; version: string }; hardware: { brand: string; model: string; device_type: string }; update: null } }).device;
+			const device = (
+				lastCall.config.body as {
+					device?: {
+						timestamp: string;
+						application: { name: string; version: string; build: string; bundle_id: string };
+						os: { name: string; version: string };
+						hardware: { brand: string; model: string; device_type: string };
+						update: null;
+					};
+				}
+			).device;
 
 			expect(device?.timestamp).toBe("2024-01-15T10:30:00.000Z");
 			expect(device?.application.name).toBe("MyApp");
@@ -603,12 +633,12 @@ describe("IdentityClient", () => {
 			// Second identify
 			await client.identify();
 
-			// Should have debug log about state already being 'identifying' (first setIdentifyState call)
-			// Then transitions to identified
-			const debugLogs = mockLogging.getLogs().filter((l) => l.level === "debug");
-			// The "identifying" to "identifying" won't happen since we start from "identified"
-			// But we can check that state changes are logged properly
-			expect(mockLogging.getLogs().some(l => l.level === "debug")).toBe(true);
+			// 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" || 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);
 		});
 	});
 
@@ -992,7 +1022,9 @@ describe("IdentityClient", () => {
 
 			// Make API slow so we can check intermediate state
 			let resolveApi: (value: unknown) => void;
-			const apiPromise = new Promise((resolve) => { resolveApi = resolve; });
+			const apiPromise = new Promise((resolve) => {
+				resolveApi = resolve;
+			});
 
 			mockApi.client = async () => {
 				await apiPromise;
@@ -1015,7 +1047,7 @@ describe("IdentityClient", () => {
 			const identifyPromise = client.identify();
 
 			// Check storage while API call is pending
-			await new Promise(resolve => setTimeout(resolve, 10));
+			await new Promise((resolve) => setTimeout(resolve, 10));
 			const intermediateStored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
 			expect(JSON.parse(intermediateStored!).type).toBe("identifying");
 
@@ -1048,14 +1080,10 @@ describe("IdentityClient", () => {
 		test("handles rapid successive identify calls", async () => {
 			const { client } = createTestClient();
 
-			const results = await Promise.all([
-				client.identify(),
-				client.identify(),
-				client.identify(),
-			]);
+			const results = await Promise.all([client.identify(), client.identify(), client.identify()]);
 
 			// All should succeed
-			results.forEach(result => {
+			results.forEach((result) => {
 				expect(result.success).toBe(true);
 			});
 
@@ -1116,4 +1144,4 @@ describe("IdentityClient", () => {
 			expect(parsed.session.session_id).toBe("session-with-émojis-🚀-and-üñíçödé");
 		});
 	});
-});
+});

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

@@ -8,13 +8,13 @@ import type { Logger, LoggingClient } from "../logging";
 import type { StorageClient, SupportedStorage } from "../storage";
 import type { UtilsClient } from "../utils";
 
-export type Persona = {
+export interface Persona {
 	name?: string | undefined;
 	user_id?: string | undefined;
 	email?: string | undefined;
-};
+}
 
-export type IdentityUser = {
+export interface IdentityUser {
 	session_id: string;
 	device_id: string;
 	user_id: string;
@@ -69,9 +69,9 @@ export type UnidentifiedSessionState = z.infer<typeof UnidentifiedSessionStateSc
 export type IdentifyingSessionState = z.infer<typeof IdentifyingSessionStateSchema>;
 export type IdentifiedSessionState = z.infer<typeof IdentifiedSessionStateSchema>;
 
-export type IdentifyStateChangeEvents = {
+export interface IdentifyStateChangeEvents {
 	IDENTIFY_STATE_CHANGED: (state: IdentifyState) => void;
-};
+}
 
 export const IDENTIFY_STORAGE_KEY = "IDENTIFY_STATE";
 

package/src/clients/logging/logging.client.ts

@@ -8,9 +8,9 @@ const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
 	verbose: 4,
 };
 
-export type LoggingClientOptions = {
+export interface LoggingClientOptions {
 	logLevel?: LogLevel;
-};
+}
 
 export class LoggingClient {
 	private logLevel: LogLevel;
@@ -42,12 +42,12 @@ export class LoggingClient {
 /**
  * Configuration options for logger creation
  */
-export type LoggerOptions = {
+export interface LoggerOptions {
 	/** Logger name used in log prefixes */
 	name: string;
 	/** Reference to parent LoggingClient for log level checks */
 	loggingClient: LoggingClient;
-};
+}
 
 export class Logger {
 	/** Bound console methods to preserve call site */

package/src/contexts/teardown.context.ts

@@ -2,9 +2,9 @@ import { createContext, useContext } from "react";
 
 import type { TeardownCore } from "../teardown.core";
 
-export type TeardownContextType = {
+export interface TeardownContextType {
 	core: TeardownCore;
-};
+}
 
 export const TeardownContext = createContext<TeardownContextType | null>(null);
 

package/src/hooks/use-force-update.ts

@@ -2,7 +2,7 @@ import { useEffect, useState } from "react";
 import type { VersionStatus } from "../clients/force-update";
 import { useTeardown } from "../contexts/teardown.context";
 
-export type UseForceUpdateResult = {
+export interface UseForceUpdateResult {
   /**
    * The current version status.
    */
@@ -19,7 +19,7 @@ export type UseForceUpdateResult = {
    * Whether the the current version is out of date and is forced to be updated. 
    */
   isUpdateRequired: boolean;
-};
+}
 
 export const useForceUpdate = (): UseForceUpdateResult => {
   const { core } = useTeardown();

package/src/hooks/use-session.ts

@@ -2,28 +2,26 @@ import { useEffect, useState } from "react";
 import type { Session } from "../clients/identity/identity.client";
 import { useTeardown } from "../contexts/teardown.context";
 
-export type UseSessionResult = Session | null
+export type UseSessionResult = Session | null;
 
 export const useSession = (): UseSessionResult => {
-  const { core } = useTeardown();
+	const { core } = useTeardown();
 
-  const [session, setSession] = useState<Session | null>(
-    core.identity.getSessionState()
-  );
+	const [session, setSession] = useState<Session | null>(core.identity.getSessionState());
 
-  useEffect(() => {
-    const unsubscribe = core.identity.onIdentifyStateChange((state) => {
-      switch (state.type) {
-        case "identified":
-          setSession(state.session);
-          break;
-        case "unidentified":
-          setSession(null);
-          break;
-      }
-    });
-    return unsubscribe;
-  }, [core.identity]);
+	useEffect(() => {
+		const unsubscribe = core.identity.onIdentifyStateChange((state) => {
+			switch (state.type) {
+				case "identified":
+					setSession(state.session);
+					break;
+				case "unidentified":
+					setSession(null);
+					break;
+			}
+		});
+		return unsubscribe;
+	}, [core.identity]);
 
-  return session;
-};
+	return session;
+};