@teardown/react-native 2.0.23 → 2.0.27

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

@@ -1,4 +1,4 @@
-import { describe, expect, mock, test, beforeEach } from "bun:test";
+import { describe, expect, mock, test } from "bun:test";
 
 // Mock react-native before any imports that use it
 mock.module("react-native", () => ({
@@ -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", () => {
@@ -485,7 +493,7 @@ describe("IdentityClient", () => {
 
 			const stored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
 			expect(stored).toBeDefined();
-			const parsed = JSON.parse(stored!);
+			const parsed = JSON.parse(stored ?? "{}");
 			expect(parsed.type).toBe("identified");
 			expect(parsed.session.session_id).toBe("session-123");
 			expect(parsed.version_info.status).toBe(IdentifyVersionStatusEnum.UP_TO_DATE);
@@ -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);
 		});
 	});
 
@@ -747,7 +755,7 @@ describe("IdentityClient", () => {
 			await client.identify();
 
 			// Update mock to return new session
-			mockApi.client = async (endpoint: string, config: ApiCallRecord["config"]) => ({
+			mockApi.client = async (_endpoint: string, _config: ApiCallRecord["config"]) => ({
 				error: null,
 				data: {
 					data: {
@@ -792,7 +800,7 @@ describe("IdentityClient", () => {
 			// After reset, storage should contain unidentified state
 			const stored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
 			expect(stored).toBeDefined();
-			expect(JSON.parse(stored!).type).toBe("unidentified");
+			expect(JSON.parse(stored ?? "{}").type).toBe("unidentified");
 		});
 
 		test("emits unidentified state on reset", async () => {
@@ -1041,14 +1049,14 @@ describe("IdentityClient", () => {
 			// Check storage while API call is pending
 			await new Promise((resolve) => setTimeout(resolve, 10));
 			const intermediateStored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
-			expect(JSON.parse(intermediateStored!).type).toBe("identifying");
+			expect(JSON.parse(intermediateStored ?? "{}").type).toBe("identifying");
 
 			// Complete API call
-			resolveApi!(null);
+			resolveApi?.(null);
 			await identifyPromise;
 
 			const finalStored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
-			expect(JSON.parse(finalStored!).type).toBe("identified");
+			expect(JSON.parse(finalStored ?? "{}").type).toBe("identified");
 		});
 
 		test("storage survives client recreation", async () => {
@@ -1132,7 +1140,7 @@ describe("IdentityClient", () => {
 
 			// Verify it can be stored and retrieved
 			const stored = mockStorage.getStorage().get(IDENTIFY_STORAGE_KEY);
-			const parsed = JSON.parse(stored!);
+			const parsed = JSON.parse(stored ?? "{}");
 			expect(parsed.session.session_id).toBe("session-with-émojis-🚀-and-üñíçödé");
 		});
 	});

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

@@ -23,7 +23,7 @@ export interface IdentityUser {
 		status: IdentifyVersionStatusEnum;
 		update: null;
 	};
-};
+}
 
 export const UnidentifiedSessionStateSchema = z.object({
 	type: z.literal("unidentified"),

package/src/clients/identity/index.ts

@@ -1 +1 @@
-export * from "./identity.client";
+export * from "./identity.client";

package/src/clients/logging/index.ts

@@ -1 +1 @@
-export * from "./logging.client";
+export * from "./logging.client";

package/src/clients/notifications/adapters/expo-notifications.adapter.ts

@@ -0,0 +1,105 @@
+import * as Notifications from "expo-notifications";
+import { NotificationPlatformEnum } from "../../device/device.client";
+import {
+	type DataMessage,
+	NotificationAdapter,
+	type PermissionStatus,
+	type PushNotification,
+	type Unsubscribe,
+} from "./notifications.adapter-interface";
+
+/**
+ * Notification adapter for expo-notifications library.
+ * Uses Expo push tokens for routing through Expo's notification service.
+ *
+ * @example
+ * ```typescript
+ * import { NotificationsClient } from "@teardown/react-native";
+ * import { ExpoNotificationsAdapter } from "@teardown/react-native/expo-notifications";
+ *
+ * const notifications = new NotificationsClient(logging, storage, {
+ *   adapter: new ExpoNotificationsAdapter()
+ * });
+ * ```
+ */
+export class ExpoNotificationsAdapter extends NotificationAdapter {
+	get platform(): NotificationPlatformEnum {
+		return NotificationPlatformEnum.EXPO;
+	}
+
+	async getToken(): Promise<string | null> {
+		try {
+			const { status } = await Notifications.getPermissionsAsync();
+			if (status !== "granted") {
+				return null;
+			}
+
+			const tokenData = await Notifications.getExpoPushTokenAsync();
+			return tokenData.data;
+		} catch {
+			return null;
+		}
+	}
+
+	async requestPermissions(): Promise<PermissionStatus> {
+		const { status, canAskAgain } = await Notifications.requestPermissionsAsync();
+
+		return {
+			granted: status === "granted",
+			canAskAgain: canAskAgain ?? true,
+		};
+	}
+
+	onTokenRefresh(listener: (token: string) => void): Unsubscribe {
+		const subscription = Notifications.addPushTokenListener((event) => {
+			// Expo push token listener returns ExpoPushToken object
+			if (event.data) {
+				listener(event.data);
+			}
+		});
+
+		return () => subscription.remove();
+	}
+
+	onNotificationReceived(listener: (notification: PushNotification) => void): Unsubscribe {
+		const subscription = Notifications.addNotificationReceivedListener((notification) => {
+			const content = notification.request.content;
+			listener({
+				title: content.title ?? undefined,
+				body: content.body ?? undefined,
+				data: content.data ?? undefined,
+			});
+		});
+
+		return () => subscription.remove();
+	}
+
+	onNotificationOpened(listener: (notification: PushNotification) => void): Unsubscribe {
+		const subscription = Notifications.addNotificationResponseReceivedListener((response) => {
+			const content = response.notification.request.content;
+			listener({
+				title: content.title ?? undefined,
+				body: content.body ?? undefined,
+				data: content.data ?? undefined,
+			});
+		});
+
+		return () => subscription.remove();
+	}
+
+	onDataMessage(listener: (message: DataMessage) => void): Unsubscribe {
+		// In Expo, data-only messages come through the same listener as regular notifications
+		// but without title/body. We filter for messages that have data but no display content.
+		const subscription = Notifications.addNotificationReceivedListener((notification) => {
+			const content = notification.request.content;
+			// Data-only message: has data but no title or body
+			if (content.data && !content.title && !content.body) {
+				listener({
+					data: content.data,
+				});
+			}
+		});
+
+		return () => subscription.remove();
+	}
+}

package/src/clients/notifications/adapters/firebase-messaging.adapter.ts

@@ -0,0 +1,87 @@
+import messaging, { type FirebaseMessagingTypes } from "@react-native-firebase/messaging";
+import { NotificationPlatformEnum } from "../../device/device.client";
+import {
+	type DataMessage,
+	NotificationAdapter,
+	type PermissionStatus,
+	type PushNotification,
+	type Unsubscribe,
+} from "./notifications.adapter-interface";
+
+/**
+ * Notification adapter for @react-native-firebase/messaging library.
+ * Uses FCM (Firebase Cloud Messaging) tokens for push notifications.
+ *
+ * @example
+ * ```typescript
+ * import { NotificationsClient } from "@teardown/react-native";
+ * import { FirebaseMessagingAdapter } from "@teardown/react-native/firebase-messaging";
+ *
+ * const notifications = new NotificationsClient(logging, storage, {
+ *   adapter: new FirebaseMessagingAdapter()
+ * });
+ * ```
+ */
+export class FirebaseMessagingAdapter extends NotificationAdapter {
+	get platform(): NotificationPlatformEnum {
+		return NotificationPlatformEnum.FCM;
+	}
+
+	async getToken(): Promise<string | null> {
+		try {
+			const token = await messaging().getToken();
+			return token;
+		} catch {
+			return null;
+		}
+	}
+
+	async requestPermissions(): Promise<PermissionStatus> {
+		const authStatus = await messaging().requestPermission();
+
+		const granted =
+			authStatus === messaging.AuthorizationStatus.AUTHORIZED ||
+			authStatus === messaging.AuthorizationStatus.PROVISIONAL;
+
+		// Firebase doesn't expose canAskAgain, assume true if not denied
+		const canAskAgain = authStatus !== messaging.AuthorizationStatus.DENIED;
+
+		return { granted, canAskAgain };
+	}
+
+	onTokenRefresh(listener: (token: string) => void): Unsubscribe {
+		return messaging().onTokenRefresh(listener);
+	}
+
+	onNotificationReceived(listener: (notification: PushNotification) => void): Unsubscribe {
+		return messaging().onMessage((remoteMessage: FirebaseMessagingTypes.RemoteMessage) => {
+			listener({
+				title: remoteMessage.notification?.title,
+				body: remoteMessage.notification?.body,
+				data: remoteMessage.data,
+			});
+		});
+	}
+
+	onNotificationOpened(listener: (notification: PushNotification) => void): Unsubscribe {
+		return messaging().onNotificationOpenedApp((remoteMessage: FirebaseMessagingTypes.RemoteMessage) => {
+			listener({
+				title: remoteMessage.notification?.title,
+				body: remoteMessage.notification?.body,
+				data: remoteMessage.data,
+			});
+		});
+	}
+
+	onDataMessage(listener: (message: DataMessage) => void): Unsubscribe {
+		// Firebase data-only messages come through onMessage but without notification payload
+		return messaging().onMessage((remoteMessage: FirebaseMessagingTypes.RemoteMessage) => {
+			// Data-only message: has data but no notification
+			if (remoteMessage.data && !remoteMessage.notification) {
+				listener({
+					data: remoteMessage.data,
+				});
+			}
+		});
+	}
+}

package/src/clients/notifications/adapters/notifications.adapter-interface.ts

@@ -0,0 +1,112 @@
+import type { NotificationPlatformEnum } from "../../device/device.client";
+
+/**
+ * Permission status returned from notification permission requests.
+ */
+export interface PermissionStatus {
+	/** Whether notifications permission is granted */
+	granted: boolean;
+	/** Whether the user can be prompted again (iOS specific) */
+	canAskAgain: boolean;
+}
+
+/**
+ * Normalized push notification payload across all adapters.
+ */
+export interface PushNotification {
+	/** Notification title */
+	title?: string;
+	/** Notification body text */
+	body?: string;
+	/** Custom data payload */
+	data?: Record<string, unknown>;
+}
+
+/**
+ * Data-only message payload (silent/background push).
+ * These messages contain only data without notification display.
+ */
+export interface DataMessage {
+	/** Custom data payload */
+	data: Record<string, unknown>;
+}
+
+/**
+ * Function to unsubscribe from event listeners.
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * Abstract adapter interface for push notification providers.
+ *
+ * Implement this interface to add support for different push notification
+ * libraries (expo-notifications, firebase messaging, react-native-notifications).
+ *
+ * @example
+ * ```typescript
+ * class MyNotificationAdapter extends NotificationAdapter {
+ *   get platform() { return NotificationPlatformEnum.FCM; }
+ *   async getToken() { ... }
+ *   // ... implement other methods
+ * }
+ * ```
+ */
+export abstract class NotificationAdapter {
+	/**
+	 * The notification platform this adapter supports.
+	 * Used to identify token type when sending to backend.
+	 */
+	abstract get platform(): NotificationPlatformEnum;
+
+	/**
+	 * Get the current push notification token.
+	 * Returns null if permissions not granted or token unavailable.
+	 */
+	abstract getToken(): Promise<string | null>;
+
+	/**
+	 * Request push notification permissions from the user.
+	 * On iOS, shows the permission dialog. On Android 13+, requests POST_NOTIFICATIONS.
+	 */
+	abstract requestPermissions(): Promise<PermissionStatus>;
+
+	/**
+	 * Subscribe to token refresh events.
+	 * Called when the push token changes (e.g., after app reinstall or token rotation).
+	 *
+	 * @param listener - Callback invoked with new token
+	 * @returns Unsubscribe function to remove the listener
+	 */
+	abstract onTokenRefresh(listener: (token: string) => void): Unsubscribe;
+
+	/**
+	 * Subscribe to foreground notification events.
+	 * Called when a notification is received while the app is in the foreground.
+	 *
+	 * @param listener - Callback invoked with notification payload
+	 * @returns Unsubscribe function to remove the listener
+	 */
+	abstract onNotificationReceived(listener: (notification: PushNotification) => void): Unsubscribe;
+
+	/**
+	 * Subscribe to notification opened events.
+	 * Called when the user taps on a notification to open the app.
+	 *
+	 * @param listener - Callback invoked with notification payload
+	 * @returns Unsubscribe function to remove the listener
+	 */
+	abstract onNotificationOpened(listener: (notification: PushNotification) => void): Unsubscribe;
+
+	/**
+	 * Subscribe to data-only message events (silent/background push).
+	 * Called when a data-only message is received without notification display.
+	 * These are typically used for background data sync or silent updates.
+	 *
+	 * Note: On iOS, requires "Remote notifications" background mode enabled.
+	 * On Android, these are handled automatically via FCM data messages.
+	 *
+	 * @param listener - Callback invoked with data payload
+	 * @returns Unsubscribe function to remove the listener
+	 */
+	abstract onDataMessage(listener: (message: DataMessage) => void): Unsubscribe;
+}

package/src/clients/notifications/adapters/wix-notifications.adapter.ts

@@ -0,0 +1,183 @@
+import { Platform } from "react-native";
+import { type Notification, Notifications, type Registered } from "react-native-notifications";
+import { NotificationPlatformEnum } from "../../device/device.client";
+import {
+	type DataMessage,
+	NotificationAdapter,
+	type PermissionStatus,
+	type PushNotification,
+	type Unsubscribe,
+} from "./notifications.adapter-interface";
+
+/**
+ * Notification adapter for react-native-notifications (Wix) library.
+ * Uses native FCM/APNS tokens for push notifications.
+ *
+ * Note: This library uses event-based token delivery, which is normalized
+ * to a Promise-based API by this adapter.
+ *
+ * @example
+ * ```typescript
+ * import { NotificationsClient } from "@teardown/react-native";
+ * import { WixNotificationsAdapter } from "@teardown/react-native/wix-notifications";
+ *
+ * const notifications = new NotificationsClient(logging, storage, {
+ *   adapter: new WixNotificationsAdapter()
+ * });
+ * ```
+ */
+export class WixNotificationsAdapter extends NotificationAdapter {
+	private tokenPromise: Promise<string> | null = null;
+	private tokenResolver: ((token: string) => void) | null = null;
+	private currentToken: string | null = null;
+	private tokenListeners: Set<(token: string) => void> = new Set();
+
+	constructor() {
+		super();
+		this.setupTokenListener();
+	}
+
+	get platform(): NotificationPlatformEnum {
+		return Platform.OS === "ios" ? NotificationPlatformEnum.APNS : NotificationPlatformEnum.FCM;
+	}
+
+	async getToken(): Promise<string | null> {
+		if (this.currentToken) {
+			return this.currentToken;
+		}
+
+		// Create a promise that will resolve when we receive the token
+		if (!this.tokenPromise) {
+			this.tokenPromise = new Promise<string>((resolve) => {
+				this.tokenResolver = resolve;
+			});
+
+			// Trigger registration to get token
+			Notifications.registerRemoteNotifications();
+		}
+
+		try {
+			// Wait for token with timeout
+			const token = await Promise.race([
+				this.tokenPromise,
+				new Promise<null>((_, reject) => setTimeout(() => reject(new Error("Token timeout")), 10000)),
+			]);
+			return token;
+		} catch {
+			return null;
+		}
+	}
+
+	async requestPermissions(): Promise<PermissionStatus> {
+		return new Promise((resolve) => {
+			// Set up one-time listener for registration result
+			const registeredHandler = () => {
+				resolve({ granted: true, canAskAgain: true });
+			};
+
+			const deniedHandler = () => {
+				resolve({ granted: false, canAskAgain: false });
+			};
+
+			// Subscribe to registration events
+			Notifications.events().registerRemoteNotificationsRegistered(registeredHandler);
+			Notifications.events().registerRemoteNotificationsRegistrationDenied(deniedHandler);
+
+			// Trigger registration
+			Notifications.registerRemoteNotifications();
+
+			// Timeout fallback
+			setTimeout(() => {
+				resolve({ granted: false, canAskAgain: true });
+			}, 10000);
+		});
+	}
+
+	onTokenRefresh(listener: (token: string) => void): Unsubscribe {
+		this.tokenListeners.add(listener);
+
+		// If we already have a token, call listener immediately
+		if (this.currentToken) {
+			listener(this.currentToken);
+		}
+
+		return () => {
+			this.tokenListeners.delete(listener);
+		};
+	}
+
+	onNotificationReceived(listener: (notification: PushNotification) => void): Unsubscribe {
+		const subscription = Notifications.events().registerNotificationReceivedForeground(
+			(
+				notification: Notification,
+				completion: (response: { alert: boolean; sound: boolean; badge: boolean }) => void
+			) => {
+				const payload = notification.payload;
+				listener({
+					title: payload.title,
+					body: payload.body,
+					data: payload,
+				});
+				completion({ alert: true, sound: true, badge: true });
+			}
+		);
+
+		return () => subscription.remove();
+	}
+
+	onNotificationOpened(listener: (notification: PushNotification) => void): Unsubscribe {
+		const subscription = Notifications.events().registerNotificationOpened(
+			(notification: Notification, completion: () => void) => {
+				const payload = notification.payload;
+				listener({
+					title: payload.title,
+					body: payload.body,
+					data: payload,
+				});
+				completion();
+			}
+		);
+
+		return () => subscription.remove();
+	}
+
+	onDataMessage(listener: (message: DataMessage) => void): Unsubscribe {
+		// Wix library handles data-only messages through the same foreground listener
+		// but without title/body in the payload
+		const subscription = Notifications.events().registerNotificationReceivedForeground(
+			(
+				notification: Notification,
+				completion: (response: { alert: boolean; sound: boolean; badge: boolean }) => void
+			) => {
+				const payload = notification.payload;
+				// Data-only message: has payload but no title or body
+				if (payload && !payload.title && !payload.body) {
+					listener({
+						data: payload,
+					});
+				}
+				completion({ alert: false, sound: false, badge: false });
+			}
+		);
+
+		return () => subscription.remove();
+	}
+
+	private setupTokenListener(): void {
+		Notifications.events().registerRemoteNotificationsRegistered((event: Registered) => {
+			this.currentToken = event.deviceToken;
+
+			// Resolve any pending getToken promise
+			if (this.tokenResolver) {
+				this.tokenResolver(event.deviceToken);
+				this.tokenResolver = null;
+				this.tokenPromise = null;
+			}
+
+			// Notify all listeners
+			for (const listener of this.tokenListeners) {
+				listener(event.deviceToken);
+			}
+		});
+	}
+}

package/src/clients/notifications/index.ts

@@ -0,0 +1,2 @@
+export * from "./adapters/notifications.adapter-interface";
+export * from "./notifications.client";