@teardown/react-native 1.2.39 → 2.0.1

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

@@ -0,0 +1,295 @@
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+import { EventEmitter } from "eventemitter3";
+import { ForceUpdateClient, IdentifyVersionStatusEnum } from "./force-update.client";
+
+// Must mock react-native BEFORE any imports that use it
+const mockAppStateListeners: ((state: string) => void)[] = [];
+mock.module("react-native", () => ({
+	AppState: {
+		addEventListener: (_event: string, handler: (state: string) => void) => {
+			mockAppStateListeners.push(handler);
+			return { remove: () => mockAppStateListeners.splice(mockAppStateListeners.indexOf(handler), 1) };
+		},
+	},
+}));
+
+type IdentifyState = import("../identity").IdentifyState;
+type IdentifyStateChangeEvents = import("../identity").IdentifyStateChangeEvents;
+type VersionStatus = import("./force-update.client").VersionStatus;
+
+function createMockIdentityClient() {
+	const emitter = new EventEmitter<IdentifyStateChangeEvents>();
+	let identifyCallCount = 0;
+	let nextIdentifyResult: { success: boolean; data?: { version_info: { status: IdentifyVersionStatusEnum } } } = {
+		success: true,
+		data: { version_info: { status: IdentifyVersionStatusEnum.UP_TO_DATE } },
+	};
+
+	return {
+		emitter,
+		onIdentifyStateChange: (listener: (state: IdentifyState) => void) => {
+			emitter.addListener("IDENTIFY_STATE_CHANGED", listener);
+			return () => emitter.removeListener("IDENTIFY_STATE_CHANGED", listener);
+		},
+		identify: async () => {
+			identifyCallCount++;
+			emitter.emit("IDENTIFY_STATE_CHANGED", { type: "identifying" });
+			emitter.emit("IDENTIFY_STATE_CHANGED", {
+				type: "identified",
+				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				version_info: { status: nextIdentifyResult.data?.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE, update: null },
+			});
+			return nextIdentifyResult;
+		},
+		getIdentifyCallCount: () => identifyCallCount,
+		setNextIdentifyResult: (result: typeof nextIdentifyResult) => {
+			nextIdentifyResult = result;
+		},
+	};
+}
+
+function createMockLoggingClient() {
+	return {
+		createLogger: () => ({
+			info: () => { },
+			warn: () => { },
+			error: () => { },
+			debug: () => { },
+		}),
+	};
+}
+
+function createMockStorageClient() {
+	const storage = new Map<string, string>();
+	return {
+		createStorage: () => ({
+			getItem: (key: string) => storage.get(key) ?? null,
+			setItem: (key: string, value: string) => storage.set(key, value),
+			removeItem: (key: string) => storage.delete(key),
+		}),
+	};
+}
+
+describe("ForceUpdateClient", () => {
+	beforeEach(() => {
+		mockAppStateListeners.length = 0;
+	});
+
+	describe("updateFromVersionStatus single emission", () => {
+		test("emits VERSION_STATUS_CHANGED exactly once per identify cycle", 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: 0 }
+			);
+
+			const statusChanges: VersionStatus[] = [];
+			client.onVersionStatusChange((status) => statusChanges.push(status));
+
+			// Trigger identify via state change
+			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", { type: "identifying" });
+			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
+				type: "identified",
+				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				version_info: { status: IdentifyVersionStatusEnum.UPDATE_AVAILABLE, update: null },
+			});
+
+			// Should have: checking (from identifying) + update_available (from identified)
+			expect(statusChanges).toHaveLength(2);
+			expect(statusChanges[0]).toEqual({ type: "checking" });
+			expect(statusChanges[1]).toEqual({ type: "update_available" });
+
+			client.shutdown();
+		});
+
+		test("foreground check triggers only one status update via subscription", async () => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			mockIdentity.setNextIdentifyResult({
+				success: true,
+				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 statusChanges: VersionStatus[] = [];
+			client.onVersionStatusChange((status) => statusChanges.push(status));
+
+			// Simulate app coming to foreground
+			const foregroundHandler = mockAppStateListeners[0];
+			expect(foregroundHandler).toBeDefined();
+
+			await foregroundHandler("active");
+
+			// Wait for async identify to complete
+			await new Promise((r) => setTimeout(r, 10));
+
+			// Should have: checking + update_required (NOT duplicated)
+			expect(statusChanges).toHaveLength(2);
+			expect(statusChanges[0]).toEqual({ type: "checking" });
+			expect(statusChanges[1]).toEqual({ type: "update_required" });
+
+			client.shutdown();
+		});
+	});
+
+	describe("cleanup on shutdown", () => {
+		test("removes all listeners on shutdown", () => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			const client = new ForceUpdateClient(
+				mockLogging as never,
+				mockStorage as never,
+				mockIdentity as never
+			);
+
+			const statusChanges: VersionStatus[] = [];
+			client.onVersionStatusChange((status) => statusChanges.push(status));
+
+			client.shutdown();
+
+			// After shutdown, emitting should not trigger listener
+			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
+				type: "identified",
+				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				version_info: { status: IdentifyVersionStatusEnum.UPDATE_AVAILABLE, update: null },
+			});
+
+			// No new status changes after shutdown
+			expect(statusChanges).toHaveLength(0);
+		});
+
+		test("removes AppState listener on shutdown", () => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			const client = new ForceUpdateClient(
+				mockLogging as never,
+				mockStorage as never,
+				mockIdentity as never
+			);
+
+			expect(mockAppStateListeners).toHaveLength(1);
+
+			client.shutdown();
+
+			expect(mockAppStateListeners).toHaveLength(0);
+		});
+	});
+
+	describe("throttle and cooldown", () => {
+		test("throttle prevents rapid foreground checks", 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 foregroundHandler = mockAppStateListeners[0];
+
+			// First foreground
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
+
+			// Second foreground immediately (within throttle window)
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			const callsAfterSecond = mockIdentity.getIdentifyCallCount();
+
+			// Should only have one identify call due to throttle
+			expect(callsAfterFirst).toBe(1);
+			expect(callsAfterSecond).toBe(1);
+
+			client.shutdown();
+		});
+
+		test("cooldown prevents redundant checks after recent success", 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 foregroundHandler = mockAppStateListeners[0];
+
+			// First foreground - should trigger check
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			const callsAfterFirst = mockIdentity.getIdentifyCallCount();
+
+			// Second foreground (within cooldown window)
+			await foregroundHandler("active");
+			await new Promise((r) => setTimeout(r, 10));
+
+			const callsAfterSecond = mockIdentity.getIdentifyCallCount();
+
+			// Only first call should have triggered identify (cooldown blocks second)
+			expect(callsAfterFirst).toBe(1);
+			expect(callsAfterSecond).toBe(1);
+
+			client.shutdown();
+		});
+	});
+
+	describe("version status mapping", () => {
+		test.each([
+			[IdentifyVersionStatusEnum.UP_TO_DATE, "up_to_date"],
+			[IdentifyVersionStatusEnum.UPDATE_AVAILABLE, "update_available"],
+			[IdentifyVersionStatusEnum.UPDATE_REQUIRED, "update_required"],
+			[IdentifyVersionStatusEnum.UPDATE_RECOMMENDED, "update_recommended"],
+			[IdentifyVersionStatusEnum.DISABLED, "disabled"],
+		])("maps %s to %s", (apiStatus, expectedType) => {
+			const mockIdentity = createMockIdentityClient();
+			const mockLogging = createMockLoggingClient();
+			const mockStorage = createMockStorageClient();
+
+			const client = new ForceUpdateClient(
+				mockLogging as never,
+				mockStorage as never,
+				mockIdentity as never
+			);
+
+			const statusChanges: VersionStatus[] = [];
+			client.onVersionStatusChange((status) => statusChanges.push(status));
+
+			mockIdentity.emitter.emit("IDENTIFY_STATE_CHANGED", {
+				type: "identified",
+				session: { session_id: "s1", device_id: "d1", persona_id: "p1", token: "t1" },
+				version_info: { status: apiStatus, update: null },
+			});
+
+			expect(statusChanges[statusChanges.length - 1]?.type).toBe(expectedType);
+
+			client.shutdown();
+		});
+	});
+});

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

@@ -0,0 +1,224 @@
+import { EventEmitter } from "eventemitter3";
+import { AppState, type AppStateStatus, type NativeEventSubscription } from "react-native";
+import { z } from "zod";
+import type { IdentityClient } from "../identity";
+import type { Logger, LoggingClient } from "../logging";
+import type { StorageClient, SupportedStorage } from "../storage";
+
+// TODO: sort out why importing these enuims from schemas is not working - @teardown/schemas
+export enum IdentifyVersionStatusEnum {
+	/**
+	 * A new version is available
+	 */
+	UPDATE_AVAILABLE = "UPDATE_AVAILABLE",
+	/**
+	 * An update is recommended
+	 */
+	UPDATE_RECOMMENDED = "UPDATE_RECOMMENDED",
+	/**
+	 * An update is required
+	 */
+	UPDATE_REQUIRED = "UPDATE_REQUIRED",
+	/**
+	 * The current version is valid & up to date
+	 */
+	UP_TO_DATE = "UP_TO_DATE",
+	/**
+	 * The version or build has been disabled
+	 */
+	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") });
+export const UpdateAvailableVersionStatusSchema = z.object({ type: z.literal("update_available") });
+export const UpdateRecommendedVersionStatusSchema = z.object({ type: z.literal("update_recommended") });
+export const UpdateRequiredVersionStatusSchema = z.object({ type: z.literal("update_required") });
+export const DisabledVersionStatusSchema = z.object({ type: z.literal("disabled") });
+/**
+ * The version status schema.
+ * - "initializing" - The version status is initializing.
+ * - "checking" - The version status is being checked.
+ * - "up_to_date" - The version is up to date.
+ * - "update_available" - The version is available for update.
+ * - "update_required" - The version is required for update.
+ */
+export const VersionStatusSchema = z.discriminatedUnion("type", [
+	InitializingVersionStatusSchema,
+	CheckingVersionStatusSchema,
+	UpToDateVersionStatusSchema,
+	UpdateAvailableVersionStatusSchema,
+	UpdateRecommendedVersionStatusSchema,
+	UpdateRequiredVersionStatusSchema,
+	DisabledVersionStatusSchema,
+]);
+
+export type InitializingVersionStatus = z.infer<typeof InitializingVersionStatusSchema>;
+export type CheckingVersionStatus = z.infer<typeof CheckingVersionStatusSchema>;
+export type UpToDateVersionStatus = z.infer<typeof UpToDateVersionStatusSchema>;
+export type UpdateAvailableVersionStatus = z.infer<typeof UpdateAvailableVersionStatusSchema>;
+export type UpdateRecommendedVersionStatus = z.infer<typeof UpdateRecommendedVersionStatusSchema>;
+export type UpdateRequiredVersionStatus = z.infer<typeof UpdateRequiredVersionStatusSchema>;
+export type DisabledVersionStatus = z.infer<typeof DisabledVersionStatusSchema>;
+export type VersionStatus = z.infer<typeof VersionStatusSchema>;
+
+export type VersionStatusChangeEvents = {
+	VERSION_STATUS_CHANGED: (status: VersionStatus) => void;
+};
+
+export type ForceUpdateClientOptions = {
+	/** Min ms between foreground checks (default: 30000) */
+	throttleMs?: number;
+	/** Min ms since last successful check before re-checking (default: 300000 = 5min) */
+	checkCooldownMs?: number;
+};
+
+const DEFAULT_OPTIONS: Required<ForceUpdateClientOptions> = {
+	throttleMs: 30_000, // 30 seconds
+	checkCooldownMs: 300_000, // 5 minutes
+};
+
+export const VERSION_STATUS_STORAGE_KEY = "VERSION_STATUS";
+
+export class ForceUpdateClient {
+	private emitter = new EventEmitter<VersionStatusChangeEvents>();
+	private versionStatus: VersionStatus;
+	private unsubscribe: (() => void) | null = null;
+	private appStateSubscription: NativeEventSubscription | null = null;
+	private lastCheckTime: number | null = null;
+	private lastForegroundTime: number | null = null;
+
+	private readonly logger: Logger;
+	private readonly storage: SupportedStorage;
+	private readonly options: Required<ForceUpdateClientOptions>;
+
+	constructor(
+		logging: LoggingClient,
+		storage: StorageClient,
+		private readonly identity: IdentityClient,
+		options: ForceUpdateClientOptions = {}
+	) {
+		this.logger = logging.createLogger({ name: "ForceUpdateClient" });
+		this.storage = storage.createStorage("version");
+		this.options = { ...DEFAULT_OPTIONS, ...options };
+		this.versionStatus = this.getVersionStatusFromStorage();
+		this.subscribeToIdentity();
+		this.subscribeToAppState();
+	}
+
+	private getVersionStatusFromStorage(): VersionStatus {
+		const stored = this.storage.getItem(VERSION_STATUS_STORAGE_KEY);
+		if (stored == null) {
+			return InitializingVersionStatusSchema.parse({ type: "initializing" });
+		}
+
+		return VersionStatusSchema.parse(JSON.parse(stored));
+	}
+
+	private saveVersionStatusToStorage(status: VersionStatus): void {
+		this.storage.setItem(VERSION_STATUS_STORAGE_KEY, JSON.stringify(status));
+	}
+
+	private subscribeToIdentity() {
+		this.unsubscribe = this.identity.onIdentifyStateChange((state) => {
+			if (state.type === "identifying") {
+				this.setVersionStatus({ type: "checking" });
+			} else if (state.type === "identified") {
+				this.updateFromVersionStatus(state.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE);
+			}
+		});
+	}
+
+	private updateFromVersionStatus(status?: IdentifyVersionStatusEnum) {
+		if (!status) {
+			this.setVersionStatus({ type: "up_to_date" });
+			return;
+		}
+
+		switch (status) {
+			case "UPDATE_AVAILABLE":
+				this.setVersionStatus({ type: "update_available" });
+				break;
+			case "UPDATE_RECOMMENDED":
+				this.setVersionStatus({ type: "update_recommended" });
+				break;
+			case "UPDATE_REQUIRED":
+				this.setVersionStatus({ type: "update_required" });
+				break;
+			case "UP_TO_DATE":
+				this.setVersionStatus({ type: "up_to_date" });
+				break;
+			case "DISABLED":
+				this.setVersionStatus({ type: "disabled" });
+				break;
+			default:
+				this.setVersionStatus({ type: "up_to_date" });
+		}
+	}
+
+	private subscribeToAppState() {
+		this.appStateSubscription = AppState.addEventListener("change", this.handleAppStateChange);
+	}
+
+	private handleAppStateChange = (nextState: AppStateStatus) => {
+		if (nextState === "active") {
+			const now = Date.now();
+			const throttleOk = !this.lastForegroundTime || now - this.lastForegroundTime >= this.options.throttleMs;
+			const cooldownOk = !this.lastCheckTime || now - this.lastCheckTime >= this.options.checkCooldownMs;
+
+			this.lastForegroundTime = now;
+
+			if (throttleOk && cooldownOk) {
+				this.checkVersionOnForeground();
+			}
+		}
+	};
+
+	private async checkVersionOnForeground() {
+		this.logger.info("Checking version status on foreground");
+		const result = await this.identity.identify();
+
+		if (!result) {
+			this.logger.info("Skipping version check - not identified");
+			return;
+		}
+
+		if (result.success) {
+			this.lastCheckTime = Date.now();
+			// Version status is handled by subscribeToIdentity() listener
+		}
+	}
+
+	public onVersionStatusChange(listener: (status: VersionStatus) => void) {
+		this.emitter.addListener("VERSION_STATUS_CHANGED", listener);
+		return () => {
+			this.emitter.removeListener("VERSION_STATUS_CHANGED", listener);
+		};
+	}
+
+	public getVersionStatus(): VersionStatus {
+		return this.versionStatus;
+	}
+
+	private setVersionStatus(newStatus: VersionStatus) {
+		this.logger.info(`Version status changing: ${this.versionStatus.type} -> ${newStatus.type}`);
+		this.versionStatus = newStatus;
+		this.saveVersionStatusToStorage(newStatus);
+		this.emitter.emit("VERSION_STATUS_CHANGED", newStatus);
+	}
+
+	public shutdown() {
+		if (this.unsubscribe) {
+			this.unsubscribe();
+			this.unsubscribe = null;
+		}
+		if (this.appStateSubscription) {
+			this.appStateSubscription.remove();
+			this.appStateSubscription = null;
+		}
+		this.emitter.removeAllListeners("VERSION_STATUS_CHANGED");
+	}
+
+}

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

@@ -0,0 +1 @@
+export * from "./force-update.client";