@teardown/react-native 2.0.28 → 2.0.30

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.debugError("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`);
 		}
@@ -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 });
 

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",
@@ -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.debugInfo("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.debugInfo("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,6 +382,82 @@ 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"}`);
 		const previousState = this.identifyState;
@@ -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,6 +488,7 @@ export class IdentityClient {
 							application: deviceInfo.application,
 							hardware: deviceInfo.hardware,
 							update: null,
+							notifications: notificationsInfo,
 						},
 					},
 				});
@@ -260,48 +498,34 @@ export class IdentityClient {
 					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/exports/index.ts

@@ -1,6 +1,7 @@
 // Clients
 export * from "../clients/api";
 export * from "../clients/device/device.client";
+export * from "../clients/events";
 export * from "../clients/logging";
 export * from "../clients/notifications";
 export * from "../clients/storage";

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

@@ -19,6 +19,11 @@ export interface UseForceUpdateResult {
 	 * Whether the the current version is out of date and is forced to be updated.
 	 */
 	isUpdateRequired: boolean;
+	/**
+	 * Release notes for the update, if available.
+	 * Only present when there's an update (update_available, update_recommended, or update_required).
+	 */
+	releaseNotes: string | null;
 }
 
 export const useForceUpdate = (): UseForceUpdateResult => {
@@ -35,10 +40,19 @@ export const useForceUpdate = (): UseForceUpdateResult => {
 	const isUpdateRecommended = versionStatus.type === "update_recommended";
 	const isUpdateAvailable = isUpdateRequired || isUpdateRecommended || versionStatus.type === "update_available";
 
+	// Extract release notes from update status types
+	const releaseNotes =
+		versionStatus.type === "update_available" ||
+		versionStatus.type === "update_recommended" ||
+		versionStatus.type === "update_required"
+			? (versionStatus.releaseNotes ?? null)
+			: null;
+
 	return {
 		versionStatus,
 		isUpdateRequired,
 		isUpdateRecommended,
 		isUpdateAvailable,
+		releaseNotes,
 	};
 };