@teardown/react-native 2.0.29 → 2.0.32

package/src/clients/events/events.client.ts

@@ -0,0 +1,102 @@
+import type { AsyncResult } from "@teardown/types";
+import type { ApiClient } from "../api";
+import type { DeviceClient } from "../device/device.client";
+import type { Logger, LoggingClient } from "../logging";
+
+/**
+ * Event payload for tracking events
+ */
+export interface EventPayload {
+	/** Name of the event (e.g., "user_signed_out", "button_clicked") */
+	event_name: string;
+	/** Type of event */
+	event_type?: "action" | "screen_view" | "custom";
+	/** Additional properties to attach to the event */
+	properties?: Record<string, unknown>;
+	/** ISO timestamp. Defaults to current time if not provided */
+	timestamp?: string;
+}
+
+/**
+ * EventsClient - Universal client for sending events to the backend
+ *
+ * This client provides a centralized way to track events from anywhere in the SDK.
+ * It automatically handles device ID retrieval and API communication.
+ */
+export class EventsClient {
+	private readonly logger: Logger;
+
+	constructor(
+		logging: LoggingClient,
+		private readonly api: ApiClient,
+		private readonly device: DeviceClient
+	) {
+		this.logger = logging.createLogger({
+			name: "EventsClient",
+		});
+	}
+
+	/**
+	 * Track a single event
+	 * @param event - The event payload to track
+	 * @param sessionId - Optional session ID to associate with the event
+	 * @returns AsyncResult indicating success/failure
+	 */
+	async track(event: EventPayload, sessionId?: string): AsyncResult<void> {
+		return this.trackBatch([event], sessionId);
+	}
+
+	/**
+	 * Track multiple events in a single batch
+	 * @param events - Array of event payloads to track
+	 * @param sessionId - Optional session ID to associate with all events
+	 * @returns AsyncResult indicating success/failure
+	 */
+	async trackBatch(events: EventPayload[], sessionId?: string): AsyncResult<void> {
+		if (events.length === 0) {
+			return { success: true, data: undefined };
+		}
+
+		this.logger.debug(`Tracking ${events.length} event(s)`, {
+			eventNames: events.map((e) => e.event_name),
+		});
+
+		try {
+			const deviceId = await this.device.getDeviceId();
+
+			const response = await this.api.client("/v1/events", {
+				method: "POST",
+				headers: {
+					"td-api-key": this.api.apiKey,
+					"td-org-id": this.api.orgId,
+					"td-project-id": this.api.projectId,
+					"td-environment-slug": this.api.environmentSlug,
+					"td-device-id": deviceId,
+					...(sessionId ? { "td-session-id": sessionId } : {}),
+				},
+				body: {
+					events: events.map((event) => ({
+						event_name: event.event_name,
+						event_type: event.event_type ?? "custom",
+						properties: event.properties,
+						timestamp: event.timestamp ?? new Date().toISOString(),
+					})),
+				},
+			});
+
+			if (response.error != null) {
+				this.logger.warn("Failed to track events", { error: response.error });
+				return { success: false, error: "Failed to track events" };
+			}
+
+			this.logger.debug(`Successfully tracked ${events.length} event(s)`);
+			return { success: true, data: undefined };
+		} catch (error) {
+			this.logger.error("Error tracking events", { error });
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : "Unknown error",
+			};
+		}
+	}
+}

package/src/clients/events/index.ts

@@ -0,0 +1 @@
+export { type EventPayload, EventsClient } from "./events.client";

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

@@ -32,9 +32,18 @@ export enum IdentifyVersionStatusEnum {
 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 UpdateAvailableVersionStatusSchema = z.object({
+	type: z.literal("update_available"),
+	releaseNotes: z.string().nullable().optional(),
+});
+export const UpdateRecommendedVersionStatusSchema = z.object({
+	type: z.literal("update_recommended"),
+	releaseNotes: z.string().nullable().optional(),
+});
+export const UpdateRequiredVersionStatusSchema = z.object({
+	type: z.literal("update_required"),
+	releaseNotes: z.string().nullable().optional(),
+});
 export const DisabledVersionStatusSchema = z.object({ type: z.literal("disabled") });
 /**
  * The version status schema.
@@ -143,7 +152,7 @@ export class ForceUpdateClient {
 			this.logger.debug(
 				`Identity already identified, syncing version status from: ${currentState.version_info.status}`
 			);
-			this.updateFromVersionStatus(currentState.version_info.status);
+			this.updateFromVersionInfo(currentState.version_info);
 		} else {
 			this.logger.debug(`Identity not yet identified (${currentState.type}), waiting for identify event`);
 		}
@@ -171,7 +180,7 @@ export class ForceUpdateClient {
 
 			return parsed;
 		} catch (error) {
-			this.logger.debugError("Error getting version status from storage", { error });
+			this.logger.error("Error getting version status from storage", { error });
 			return InitializingVersionStatusSchema.parse({ type: "initializing" });
 		}
 	}
@@ -189,13 +198,19 @@ export class ForceUpdateClient {
 					break;
 				case "identified":
 					this.logger.debug(`Identified with version_info.status: ${state.version_info.status}`);
-					this.updateFromVersionStatus(state.version_info.status ?? IdentifyVersionStatusEnum.UP_TO_DATE);
+					this.updateFromVersionInfo(state.version_info);
 					break;
 			}
 		});
 	}
 
-	private updateFromVersionStatus(status?: IdentifyVersionStatusEnum) {
+	private updateFromVersionInfo(versionInfo: {
+		status: IdentifyVersionStatusEnum;
+		update: { release_notes: string | null } | null;
+	}) {
+		const status = versionInfo.status;
+		const releaseNotes = versionInfo.update?.release_notes ?? null;
+
 		if (!status) {
 			this.setVersionStatus({ type: "up_to_date" });
 			return;
@@ -203,13 +218,15 @@ export class ForceUpdateClient {
 
 		switch (status) {
 			case "UPDATE_AVAILABLE":
-				this.setVersionStatus({ type: "update_available" });
+				this.setVersionStatus(releaseNotes ? { type: "update_available", releaseNotes } : { type: "update_available" });
 				break;
 			case "UPDATE_RECOMMENDED":
-				this.setVersionStatus({ type: "update_recommended" });
+				this.setVersionStatus(
+					releaseNotes ? { type: "update_recommended", releaseNotes } : { type: "update_recommended" }
+				);
 				break;
 			case "UPDATE_REQUIRED":
-				this.setVersionStatus({ type: "update_required" });
+				this.setVersionStatus(releaseNotes ? { type: "update_required", releaseNotes } : { type: "update_required" });
 				break;
 			case "UP_TO_DATE":
 				this.setVersionStatus({ type: "up_to_date" });

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

@@ -127,6 +127,7 @@ function createMockApiClient(
 		apiKey: "test-api-key",
 		orgId: "test-org-id",
 		projectId: "test-project-id",
+		environmentSlug: "production",
 		client: async (endpoint: string, config: ApiCallRecord["config"]) => {
 			calls.push({ endpoint, config });
 
@@ -635,7 +636,7 @@ 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" || l.level === "debugInfo");
+			const debugLogs = mockLogging.getLogs().filter((l) => l.level === "debug" || l.level === "info");
 			expect(debugLogs.length).toBeGreaterThan(0);
 			// Check that state transitions are logged
 			expect(debugLogs.some((l) => l.message.includes("Identify state"))).toBe(true);

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

@@ -2,9 +2,11 @@ import type { AsyncResult } from "@teardown/types";
 import { EventEmitter } from "eventemitter3";
 import { z } from "zod";
 import type { ApiClient } from "../api";
-import type { DeviceClient } from "../device/device.client";
+import type { DeviceClient, NotificationPlatformEnum } from "../device/device.client";
+import type { EventsClient } from "../events";
 import { IdentifyVersionStatusEnum } from "../force-update";
 import type { Logger, LoggingClient } from "../logging";
+import type { NotificationsClient } from "../notifications/notifications.client";
 import type { StorageClient, SupportedStorage } from "../storage";
 import type { UtilsClient } from "../utils";
 
@@ -14,6 +16,26 @@ export interface Persona {
 	email?: string | undefined;
 }
 
+export interface SignOutOptions {
+	/**
+	 * Additional properties to include in the sign out event
+	 */
+	properties?: Record<string, unknown>;
+	/**
+	 * Whether to wait for the event to be sent before clearing state.
+	 * Default: true (fire-and-forget if false)
+	 */
+	waitForEvent?: boolean;
+}
+
+export interface UpdateInfo {
+	version: string;
+	build: string;
+	update_id: string;
+	effective_date: Date;
+	release_notes: string | null;
+}
+
 export interface IdentityUser {
 	session_id: string;
 	device_id: string;
@@ -21,7 +43,7 @@ export interface IdentityUser {
 	token: string;
 	version_info: {
 		status: IdentifyVersionStatusEnum;
-		update: null;
+		update: UpdateInfo | null;
 	};
 }
 
@@ -49,13 +71,50 @@ export const VersionStatusResponseSchema = z.object({
 	latest_version: z.string().optional(),
 });
 
+export const UpdateInfoSchema = z.object({
+	version: z.string(),
+	build: z.string(),
+	update_id: z.string(),
+	effective_date: z.coerce.date(),
+	release_notes: z.string().nullable(),
+});
+
+/** Type guard to check if update has nested structure */
+function isNestedUpdate(update: unknown): update is { status: string; update: UpdateInfo } {
+	return typeof update === "object" && update !== null && "status" in update && "update" in update;
+}
+
+// Accept either the nested schema from API or the flat UpdateInfo schema
+export const VersionInfoResponseSchema = z.object({
+	status: z.enum(IdentifyVersionStatusEnum),
+	update: z.union([
+		z.object({
+			status: z.enum(IdentifyVersionStatusEnum),
+			update: UpdateInfoSchema,
+		}),
+		UpdateInfoSchema,
+		z.null(),
+	]),
+});
+
 export const IdentifiedSessionStateSchema = z.object({
 	type: z.literal("identified"),
 	session: SessionSchema,
-	version_info: z.object({
-		status: z.enum(IdentifyVersionStatusEnum),
-		update: z.null(),
-	}),
+	version_info: z
+		.object({
+			status: z.enum(IdentifyVersionStatusEnum),
+			update: UpdateInfoSchema.nullable(),
+		})
+		.transform((data) => {
+			// Flatten nested structure if present
+			if (isNestedUpdate(data.update)) {
+				return {
+					status: data.status,
+					update: data.update.update,
+				};
+			}
+			return data;
+		}),
 });
 
 export const IdentifyStateSchema = z.discriminatedUnion("type", [
@@ -89,7 +148,9 @@ export class IdentityClient {
 		utils: UtilsClient,
 		storage: StorageClient,
 		private readonly api: ApiClient,
-		private readonly device: DeviceClient
+		private readonly device: DeviceClient,
+		private readonly events: EventsClient,
+		private readonly notificationsClient?: NotificationsClient
 	) {
 		this.logger = logging.createLogger({
 			name: "IdentityClient",
@@ -113,7 +174,7 @@ export class IdentityClient {
 			this.logger.debug(`Initialized with state: ${this.identifyState.type}`);
 		} catch (error) {
 			// Silently fail on errors - we'll re-identify on app boot if needed
-			this.logger.debugError("Error initializing IdentityClient", { error });
+			this.logger.error("Error initializing IdentityClient", { error });
 			this.identifyState = { type: "unidentified" };
 		}
 
@@ -126,17 +187,17 @@ export class IdentityClient {
 			const stored = this.storage.getItem(IDENTIFY_STORAGE_KEY);
 
 			if (stored == null) {
-				this.logger.debugInfo("No stored identity state, returning unidentified");
+				this.logger.info("No stored identity state, returning unidentified");
 				return UnidentifiedSessionStateSchema.parse({ type: "unidentified" });
 			}
 
 			const parsed = IdentifyStateSchema.parse(JSON.parse(stored));
-			this.logger.debugInfo(`Parsed identity state from storage: ${parsed.type}`);
+			this.logger.info(`Parsed identity state from storage: ${parsed.type}`);
 
 			// "identifying" is a transient state - if we restore it, treat as unidentified
 			// This can happen if the app was killed during an identify call
 			if (parsed.type === "identifying") {
-				this.logger.debugInfo("Found stale 'identifying' state in storage, resetting to unidentified");
+				this.logger.info("Found stale 'identifying' state in storage, resetting to unidentified");
 				// Clear the stale state from storage immediately
 				this.storage.removeItem(IDENTIFY_STORAGE_KEY);
 				return UnidentifiedSessionStateSchema.parse({ type: "unidentified" });
@@ -144,7 +205,7 @@ export class IdentityClient {
 
 			return parsed;
 		} catch (error) {
-			this.logger.debugError("Error getting identify state from storage", { error });
+			this.logger.error("Error getting identify state from storage", { error });
 			return { type: "unidentified" };
 		}
 	}
@@ -155,11 +216,11 @@ export class IdentityClient {
 
 	private setIdentifyState(newState: IdentifyState): void {
 		if (this.identifyState.type === newState.type) {
-			this.logger.debugInfo(`Identify state already set: ${this.identifyState.type}`);
+			this.logger.info(`Identify state already set: ${this.identifyState.type}`);
 			return;
 		}
 
-		this.logger.debugInfo(`Identify state: ${this.identifyState.type} -> ${newState.type}`);
+		this.logger.info(`Identify state: ${this.identifyState.type} -> ${newState.type}`);
 		this.identifyState = newState;
 		this.saveIdentifyStateToStorage(newState);
 		this.emitter.emit("IDENTIFY_STATE_CHANGED", newState);
@@ -187,11 +248,109 @@ export class IdentityClient {
 		this.emitter.removeAllListeners("IDENTIFY_STATE_CHANGED");
 	}
 
-	public reset() {
+	/**
+	 * Reset identity state to unidentified.
+	 * Clears stored state and emits state change.
+	 */
+	public reset(): void {
+		this.setIdentifyState({ type: "unidentified" });
+	}
+
+	/**
+	 * Internal method to clear identity state.
+	 * Used by signOut() and signOutAll().
+	 */
+	private clearIdentityState(): void {
 		this.storage.removeItem(IDENTIFY_STORAGE_KEY);
 		this.setIdentifyState({ type: "unidentified" });
 	}
 
+	/**
+	 * Sign out the current user.
+	 * Sends a sign_out event to the backend and clears session/user identity.
+	 * The deviceId is preserved - the same device will be recognized on next identify.
+	 *
+	 * @param options - Optional configuration for the sign out
+	 * @returns AsyncResult indicating success/failure of the event send
+	 */
+	async signOut(options?: SignOutOptions): AsyncResult<void> {
+		this.logger.info("Signing out user");
+
+		const session = this.getSessionState();
+		const waitForEvent = options?.waitForEvent ?? true;
+
+		// Send event FIRST while session/device data still exists
+		const eventPromise = this.events.track(
+			{
+				event_name: "user_signed_out",
+				event_type: "action",
+				properties: {
+					sign_out_type: "sign_out",
+					session_id: session?.session_id,
+					user_id: session?.user_id,
+					...options?.properties,
+				},
+			},
+			session?.session_id
+		);
+
+		if (waitForEvent) {
+			const result = await eventPromise;
+			// Clear state regardless of event send result
+			this.clearIdentityState();
+			return result;
+		}
+
+		// Fire-and-forget mode - don't await but still clear state
+		void eventPromise;
+		this.clearIdentityState();
+		return { success: true, data: undefined };
+	}
+
+	/**
+	 * Sign out and reset all state including deviceId.
+	 * Sends a sign_out_all event to the backend and clears all SDK state.
+	 * The device will appear as a fresh install on next identify.
+	 *
+	 * @param options - Optional configuration for the sign out
+	 * @returns AsyncResult indicating success/failure of the event send
+	 */
+	async signOutAll(options?: SignOutOptions): AsyncResult<void> {
+		this.logger.info("Signing out all - full reset");
+
+		const session = this.getSessionState();
+		const waitForEvent = options?.waitForEvent ?? true;
+
+		// Send event FIRST while session/device data still exists
+		const eventPromise = this.events.track(
+			{
+				event_name: "user_signed_out",
+				event_type: "action",
+				properties: {
+					sign_out_type: "sign_out_all",
+					session_id: session?.session_id,
+					user_id: session?.user_id,
+					...options?.properties,
+				},
+			},
+			session?.session_id
+		);
+
+		if (waitForEvent) {
+			const result = await eventPromise;
+			// Clear all state regardless of event send result
+			this.clearIdentityState();
+			this.device.reset();
+			return result;
+		}
+
+		// Fire-and-forget mode - don't await but still clear state
+		void eventPromise;
+		this.clearIdentityState();
+		this.device.reset();
+		return { success: true, data: undefined };
+	}
+
 	/**
 	 * Re-identify the current persona to refresh session data.
 	 * Only works if already identified.
@@ -223,8 +382,84 @@ export class IdentityClient {
 		}
 	}
 
+	/**
+	 * Extract error message from API validation error response (422)
+	 */
+	private extractValidationErrorMessage(errorValue: unknown): string {
+		if (typeof errorValue === "string") return errorValue;
+		if (typeof errorValue === "object" && errorValue !== null) {
+			const obj = errorValue as { summary?: string; message?: string };
+			if (obj.summary) return obj.summary;
+			if (obj.message) return obj.message;
+		}
+		return "Unknown error";
+	}
+
+	/**
+	 * Extract error message from API error response (non-422)
+	 */
+	private extractErrorMessage(errorValue: unknown): string {
+		if (typeof errorValue === "string") return errorValue;
+		if (typeof errorValue === "object" && errorValue !== null) {
+			const obj = errorValue as { code?: string; message?: string };
+			if (obj.message) return obj.message;
+		}
+		return "Unknown error";
+	}
+
+	/**
+	 * Get push notification info if notifications client is configured
+	 */
+	private async getNotificationsInfo(): Promise<
+		| {
+				push: {
+					enabled: boolean;
+					granted: boolean;
+					token: string | null;
+					platform: NotificationPlatformEnum;
+				};
+		  }
+		| undefined
+	> {
+		if (!this.notificationsClient) return undefined;
+
+		this.logger.debug("Getting push notification token...");
+		const token = await this.notificationsClient.getToken();
+		this.logger.debug(`Push token retrieved: ${token ? "yes" : "no"}, platform: ${this.notificationsClient.platform}`);
+
+		return {
+			push: {
+				enabled: true,
+				granted: token !== null,
+				token,
+				platform: this.notificationsClient.platform,
+			},
+		};
+	}
+
+	/**
+	 * Flatten nested version_info structure from API response
+	 */
+	private flattenVersionInfo(rawVersionInfo: { status: string; update: unknown }): {
+		status: IdentifyVersionStatusEnum;
+		update: UpdateInfo | null;
+	} {
+		let flattenedUpdate: UpdateInfo | null = null;
+
+		if (rawVersionInfo.update) {
+			flattenedUpdate = isNestedUpdate(rawVersionInfo.update)
+				? rawVersionInfo.update.update
+				: (rawVersionInfo.update as UpdateInfo);
+		}
+
+		return {
+			status: rawVersionInfo.status as IdentifyVersionStatusEnum,
+			update: flattenedUpdate,
+		};
+	}
+
 	async identify(user?: Persona): AsyncResult<IdentityUser> {
-		this.logger.debugInfo(`Identifying user with persona: ${user?.name ?? "none"}`);
+		this.logger.info(`Identifying user with persona: ${user?.name ?? "none"}`);
 		const previousState = this.identifyState;
 		this.setIdentifyState({ type: "identifying" });
 
@@ -233,6 +468,8 @@ export class IdentityClient {
 				this.logger.debug("Getting device ID...");
 				const deviceId = await this.device.getDeviceId();
 				const deviceInfo = await this.device.getDeviceInfo();
+				const notificationsInfo = await this.getNotificationsInfo();
+
 				this.logger.debug("Calling identify API...");
 				const response = await this.api.client("/v1/identify", {
 					method: "POST",
@@ -240,7 +477,7 @@ export class IdentityClient {
 						"td-api-key": this.api.apiKey,
 						"td-org-id": this.api.orgId,
 						"td-project-id": this.api.projectId,
-						"td-environment-slug": "production",
+						"td-environment-slug": this.api.environmentSlug,
 						"td-device-id": deviceId,
 					},
 					body: {
@@ -251,57 +488,44 @@ export class IdentityClient {
 							application: deviceInfo.application,
 							hardware: deviceInfo.hardware,
 							update: null,
+							notifications: notificationsInfo,
 						},
 					},
 				});
 
-				this.logger.debugInfo(`Identify API response received`);
+				this.logger.info(`Identify API response received`);
 				if (response.error != null) {
 					this.logger.warn("Identify API error", response.error.status, response.error.value);
 					this.setIdentifyState(previousState);
 
-					if (response.error.status === 422) {
-						this.logger.warn("422 Error identifying user", response.error.value);
-						return {
-							success: false,
-							error: response.error.value.message ?? "Unknown error",
-						};
-					}
-
-					const value = response.error.value;
-					return {
-						success: false,
-						error: value?.error?.message ?? "Unknown error",
-					};
+					const errorMessage =
+						response.error.status === 422
+							? this.extractValidationErrorMessage(response.error.value)
+							: this.extractErrorMessage(response.error.value);
+
+					return { success: false, error: errorMessage };
 				}
 
+				const parsedSession = SessionSchema.parse(response.data.data);
+				const flattenedVersionInfo = this.flattenVersionInfo(response.data.data.version_info);
+
+				const identityUser: IdentityUser = {
+					...parsedSession,
+					version_info: flattenedVersionInfo,
+				};
+
 				this.setIdentifyState({
 					type: "identified",
-					session: response.data.data,
-					version_info: {
-						status: response.data.data.version_info.status,
-						update: null,
-					},
+					session: parsedSession,
+					version_info: flattenedVersionInfo,
 				});
 
-				return {
-					success: true,
-					data: {
-						...response.data.data,
-						version_info: {
-							status: response.data.data.version_info.status,
-							update: null,
-						},
-					},
-				};
+				return { success: true, data: identityUser };
 			},
 			(error) => {
 				this.logger.error("Error identifying user", error);
 				this.setIdentifyState(previousState);
-				return {
-					success: false,
-					error: error.message,
-				};
+				return { success: false, error: error.message };
 			}
 		);
 	}

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

@@ -57,10 +57,6 @@ export class Logger {
 		warn: console.warn.bind(console),
 		trace: console.trace.bind(console),
 		debug: console.debug.bind(console),
-		debugError: console.debug.bind(console, "Error: "),
-		debugWarn: console.debug.bind(console, "Warning: "),
-		debugInfo: console.debug.bind(console, "Info: "),
-		debugVerbose: console.debug.bind(console, "Verbose: "),
 	};
 
 	constructor(private readonly options: LoggerOptions) {}
@@ -93,24 +89,4 @@ export class Logger {
 		if (!this.options.loggingClient.shouldLog("verbose")) return;
 		this.boundConsole.debug(`${this.prefix} ${message}`, ...args);
 	}
-
-	debugError(message: string, ...args: unknown[]) {
-		if (!this.options.loggingClient.shouldLog("verbose")) return;
-		this.boundConsole.debugError(`${this.prefix} ${message}`, ...args);
-	}
-
-	debugWarn(message: string, ...args: unknown[]) {
-		if (!this.options.loggingClient.shouldLog("verbose")) return;
-		this.boundConsole.debugWarn(`${this.prefix} ${message}`, ...args);
-	}
-
-	debugInfo(message: string, ...args: unknown[]) {
-		if (!this.options.loggingClient.shouldLog("verbose")) return;
-		this.boundConsole.debugInfo(`${this.prefix} ${message}`, ...args);
-	}
-
-	debugVerbose(message: string, ...args: unknown[]) {
-		if (!this.options.loggingClient.shouldLog("verbose")) return;
-		this.boundConsole.debugVerbose(`${this.prefix} ${message}`, ...args);
-	}
 }