zixflow-reactnative 1.0.0

package/src/notification-inbox.ts

@@ -0,0 +1,154 @@
+import { type EventSubscription } from 'react-native';
+import { NativeLoggerListener } from './native-logger-listener';
+import type { Spec as CodegenSpec } from './specs/modules/NativeCustomerIOMessagingInApp';
+import NativeCustomerIOMessagingInApp from './specs/modules/NativeCustomerIOMessagingInApp';
+import type { InboxMessage, NotificationInboxChangeListener } from './types';
+import { callNativeModule, ensureNativeModule } from './utils/native-bridge';
+
+// Reference to the native CustomerIO In-App Messaging module
+const nativeModule = ensureNativeModule(NativeCustomerIOMessagingInApp);
+
+// Wrapper function that ensures SDK is initialized before calling native methods
+const withNativeModule = <R>(fn: (native: CodegenSpec) => R): R => {
+  return callNativeModule(nativeModule, fn);
+};
+
+/**
+ * Public API methods for NotificationInbox.
+ * Define the TypeScript API here with proper types (InboxMessage instead of UnsafeObject).
+ *
+ * @internal
+ */
+interface NotificationInboxPublicSpec {
+  getMessages(topic?: string): Promise<InboxMessage[]>;
+  subscribeToMessages(
+    listener: NotificationInboxChangeListener,
+    topic?: string
+  ): EventSubscription;
+  markMessageOpened(message: InboxMessage): void;
+  markMessageUnopened(message: InboxMessage): void;
+  markMessageDeleted(message: InboxMessage): void;
+  trackMessageClicked(message: InboxMessage, actionName?: string): void;
+}
+
+/**
+ * Native inbox methods from CodegenSpec that should be excluded from CustomerIOInAppMessaging.
+ * Includes both public methods (in NotificationInboxPublicSpec) and internal methods.
+ *
+ * @internal
+ */
+export type NotificationInboxSpec =
+  | keyof NotificationInboxPublicSpec
+  | 'subscribeToMessagesChanged'
+  | 'setupInboxListener';
+
+/**
+ * Helper function to parse raw inbox message from native layer
+ * @internal
+ */
+function parseInboxMessage(raw: any): InboxMessage {
+  return {
+    queueId: raw.queueId,
+    deliveryId: raw.deliveryId ?? undefined,
+    expiry: raw.expiry ?? undefined,
+    sentAt: raw.sentAt,
+    topics: raw.topics || [],
+    type: raw.type,
+    opened: raw.opened,
+    priority: raw.priority ?? undefined,
+    properties: raw.properties || {},
+  };
+}
+
+/**
+ * Manages inbox messages for the current user.
+ *
+ * @public
+ */
+export class NotificationInbox implements NotificationInboxPublicSpec {
+  /**
+   * Gets inbox messages.
+   */
+  async getMessages(topic?: string): Promise<InboxMessage[]> {
+    return withNativeModule(async (native) => {
+      const rawMessages = await native.getMessages(topic);
+      return rawMessages.map(parseInboxMessage);
+    });
+  }
+
+  /**
+   * Subscribes to inbox message changes.
+   * Optionally filter messages by topic.
+   */
+  subscribeToMessages(
+    listener: NotificationInboxChangeListener,
+    topic?: string
+  ): EventSubscription {
+    const emitter = (data: any) => {
+      let messages = (data.messages || []).map(parseInboxMessage);
+
+      // Filter by topic if specified (case-insensitive)
+      if (topic) {
+        const topicLower = topic.toLowerCase();
+        messages = messages.filter((msg: InboxMessage) =>
+          msg.topics.some((t) => t.toLowerCase() === topicLower)
+        );
+      }
+
+      listener.onMessagesChanged(messages);
+    };
+
+    return withNativeModule((native) => {
+      try {
+        // Set up the native inbox listener before subscribing to events
+        // This will automatically trigger onMessagesChanged with current messages
+        native.setupInboxListener();
+
+        // Register TurboModule event listener and return subscription
+        return native.subscribeToMessagesChanged(emitter);
+      } catch (error) {
+        NativeLoggerListener.warn(
+          'Failed to attach inbox change listener:',
+          error
+        );
+        // Return a no-op subscription to maintain backwards compatibility
+        return {
+          remove: () => {},
+          eventType: '',
+          key: 0,
+          subscriber: null as any,
+        } as EventSubscription;
+      }
+    });
+  }
+
+  /**
+   * Marks an inbox message as opened/read.
+   */
+  markMessageOpened(message: InboxMessage) {
+    withNativeModule((native) => native.markMessageOpened(message));
+  }
+
+  /**
+   * Marks an inbox message as unopened/unread.
+   */
+  markMessageUnopened(message: InboxMessage) {
+    withNativeModule((native) => native.markMessageUnopened(message));
+  }
+
+  /**
+   * Marks an inbox message as deleted.
+   */
+  markMessageDeleted(message: InboxMessage) {
+    withNativeModule((native) => native.markMessageDeleted(message));
+  }
+
+  /**
+   * Tracks a click event for an inbox message.
+   */
+  trackMessageClicked(message: InboxMessage, actionName?: string) {
+    withNativeModule((native) =>
+      native.trackMessageClicked(message, actionName)
+    );
+  }
+}

package/src/postInstall.js

@@ -0,0 +1,10 @@
+/*
+  This code block attempts to set expoVersion in package.json.
+  If it fails, the assumption is that Expo plugin is not installed,
+  therefore we are running on bare React Native project.
+  If it succeeds, we use Expo as the user agent instead of React Native.
+*/
+try {
+  const ph = require('customerio-expo-plugin/postinstall');
+  ph.runPostInstall();
+} catch {}

package/src/specs/components/InlineMessageNativeComponent.ts

@@ -0,0 +1,59 @@
+// React Native docs now recommend Codegen types should be imported from the react-native package
+// But it breaks on Expo and older React Native versions, so we import from react-native/Libraries/Types/CodegenTypes
+// for compatibility with all versions until we can fully migrate to the new import style without breaking older versions
+// https://reactnative.dev/docs/strict-typescript-api#codegen-types-should-now-be-imported-from-the-react-native-package
+
+import type { HostComponent, ViewProps } from 'react-native';
+/* eslint-disable @react-native/no-deep-imports */
+import type {
+  DirectEventHandler,
+  Double,
+} from 'react-native/Libraries/Types/CodegenTypes';
+import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNativeComponent';
+
+/** Event data for inline message size changes. */
+export interface SizeChangeEvent {
+  width: Double;
+  height: Double;
+  duration?: Double;
+}
+
+/** States representing the loading and display status of inline messages. */
+export enum InlineMessageState {
+  LoadingStarted = 'LoadingStarted',
+  LoadingFinished = 'LoadingFinished',
+  NoMessageToDisplay = 'NoMessageToDisplay',
+}
+
+/** Event data for inline message state changes. */
+export interface StateChangeEvent {
+  state: string;
+}
+
+/** Event data for inline message action clicks. */
+export interface ActionClickEvent {
+  /** Message data structure - defined inline for codegen compatibility (cannot import types) */
+  message: {
+    messageId: string;
+    deliveryId?: string;
+    elementId?: string;
+  };
+  actionValue: string;
+  actionName: string;
+}
+
+/** Props for the native inline message component. */
+export interface NativeProps extends ViewProps {
+  /** Required element ID for retrieving inline message content. */
+  elementId: string;
+  onSizeChange: DirectEventHandler<SizeChangeEvent>;
+  onStateChange?: DirectEventHandler<StateChangeEvent>;
+  onActionClick?: DirectEventHandler<ActionClickEvent>;
+}
+
+// React Native Codegen automatically generates the native component bridge based on the NativeProps interface
+// This creates the low-level native component that handles communication between JS and native code
+// Used by native iOS/Android components - the public view is InlineInAppMessageView in components directory
+export default codegenNativeComponent<NativeProps>(
+  'InlineMessageNative'
+) as HostComponent<NativeProps>;

package/src/specs/modules/NativeCustomerIO.ts

@@ -0,0 +1,55 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Native module specification for CustomerIO React Native SDK
+ *
+ * This module defines the TurboModule interface for CustomerIO SDK native bridge.
+ * Types use basic primitives for React Native Codegen compatibility, while the public
+ * API layer provides more specific TypeScript types for better developer experience.
+ *
+ * The separation allows:
+ * - Native bridge compatibility with Codegen constraints
+ * - Type-safe public API with proper TypeScript definitions
+ * - Alignment between codegen spec and public contract
+ *
+ * @see https://github.com/facebook/react-native/issues/38769 for Codegen limitations
+ */
+
+/**
+ * Generic object type for native bridge parameter passing.
+ *
+ * Used for all complex data structures passed to native methods to ensure
+ * React Native Codegen compatibility. The public API layer converts these
+ * to proper TypeScript types (CustomAttributes, CioConfig, etc.) for
+ * better type safety and developer experience.
+ *
+ * @internal - Not exported to avoid conflicts with public API types
+ */
+type NativeBridgeObject = UnsafeObject;
+
+// =============================================================================
+// TURBO MODULE SPEC – Defines native bridge interface
+// =============================================================================
+
+/**
+ * TurboModule specification for CustomerIO SDK native bridge methods.
+ * Uses generic Object types for React Native Codegen compatibility.
+ */
+export interface Spec extends TurboModule {
+  initialize(
+    config: NativeBridgeObject,
+    args: NativeBridgeObject
+  ): Promise<void>;
+  identify(params?: NativeBridgeObject): void;
+  clearIdentify(): void;
+  track(name: string, properties?: NativeBridgeObject): void;
+  screen(title: string, properties?: NativeBridgeObject): void;
+  setProfileAttributes(attributes: NativeBridgeObject): void;
+  setDeviceAttributes(attributes: NativeBridgeObject): void;
+  registerDeviceToken(token: string): void;
+  trackMetric(deliveryID: string, deviceToken: string, event: string): void;
+  deleteDeviceToken(): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('NativeCustomerIO');

package/src/specs/modules/NativeCustomerIOLocation.ts

@@ -0,0 +1,15 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+
+/**
+ * Native module specification for CustomerIO Location React Native SDK
+ *
+ * @see NativeCustomerIO.ts for detailed documentation on TurboModule patterns,
+ * Codegen compatibility, and type safety approach.
+ */
+
+export interface Spec extends TurboModule {
+  setLastKnownLocation(latitude: number, longitude: number): void;
+  requestLocationUpdate(): void;
+}
+
+export default TurboModuleRegistry.get<Spec>('NativeCustomerIOLocation');

package/src/specs/modules/NativeCustomerIOLogging.ts

@@ -0,0 +1,24 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+import type {
+  EventEmitter,
+  UnsafeObject,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Native module specification for CustomerIO Logging React Native SDK
+ *
+ * This module defines the TurboModule interface for CustomerIO logging bridge.
+ * Used internally for printing logs to React Native environment instead of native.
+ *
+ * @see NativeCustomerIO.ts for detailed documentation on TurboModule patterns,
+ * Codegen compatibility, and type safety approach.
+ */
+
+/** TurboModule interface for CustomerIO logging native operations */
+export interface Spec extends TurboModule {
+  readonly onCioLogEvent: EventEmitter<UnsafeObject>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>(
+  'NativeCustomerIOLogging'
+);

package/src/specs/modules/NativeCustomerIOMessagingInApp.ts

@@ -0,0 +1,30 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+import type {
+  EventEmitter,
+  UnsafeObject,
+} from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Native module specification for CustomerIO In-App Messaging React Native SDK
+ *
+ * @see NativeCustomerIO.ts for detailed documentation on TurboModule patterns,
+ * Codegen compatibility, and type safety approach.
+ */
+
+/** TurboModule interface for CustomerIO In-App Messaging native operations */
+export interface Spec extends TurboModule {
+  dismissMessage(): void;
+  readonly onInAppEventReceived: EventEmitter<UnsafeObject>;
+  // Notification Inbox related methods
+  setupInboxListener(): void;
+  readonly subscribeToMessagesChanged: EventEmitter<UnsafeObject>;
+  getMessages(topic?: string): Promise<UnsafeObject[]>;
+  markMessageOpened(message: UnsafeObject): void;
+  markMessageUnopened(message: UnsafeObject): void;
+  markMessageDeleted(message: UnsafeObject): void;
+  trackMessageClicked(message: UnsafeObject, actionName?: string): void;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>(
+  'NativeCustomerIOMessagingInApp'
+);

package/src/specs/modules/NativeCustomerIOMessagingPush.ts

@@ -0,0 +1,27 @@
+import { TurboModuleRegistry, type TurboModule } from 'react-native';
+import type { UnsafeObject } from 'react-native/Libraries/Types/CodegenTypes';
+
+/**
+ * Native module specification for CustomerIO Push Messaging React Native SDK
+ *
+ * @see NativeCustomerIO.ts for detailed documentation on TurboModule patterns,
+ * Codegen compatibility, and type safety approach.
+ */
+
+type NativeBridgeObject = UnsafeObject;
+
+export interface Spec extends TurboModule {
+  onMessageReceived(
+    message: NativeBridgeObject,
+    handleNotificationTrigger: boolean
+  ): Promise<boolean>;
+  trackNotificationResponseReceived(payload: NativeBridgeObject): void;
+  trackNotificationReceived(payload: NativeBridgeObject): void;
+  getRegisteredDeviceToken(): Promise<string>;
+  showPromptForPushNotifications(options: NativeBridgeObject): Promise<string>;
+  getPushPermissionStatus(): Promise<string>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>(
+  'NativeCustomerIOMessagingPush'
+);

package/src/types/data-pipelines.ts

@@ -0,0 +1,150 @@
+import type { PushClickBehaviorAndroid } from './push';
+
+/**
+ * Key-value pairs for custom user attributes and event properties.
+ *
+ * Provides a type-safe interface for passing custom data to CustomerIO.
+ * While the native bridge uses generic Object types for Codegen compatibility,
+ * this type gives developers better TypeScript intellisense and validation.
+ *
+ * @example
+ * ```typescript
+ * const attributes: CustomAttributes = {
+ *   age: 25,
+ *   email: 'user@example.com',
+ *   preferences: { theme: 'dark' }
+ * };
+ * ```
+ *
+ * @public
+ */
+export type CustomAttributes = Record<string, any>;
+
+/**
+ * Parameters for identifying a user in CustomerIO.
+ *
+ * @param userId - Unique identifier for the user (email, username, etc.)
+ * @param traits - Additional user attributes and properties
+ *
+ * @public
+ */
+export interface IdentifyParams {
+  userId?: string;
+  traits?: CustomAttributes;
+}
+
+/**
+ * Configuration options for initializing the CustomerIO SDK.
+ *
+ * @param cdpApiKey - Customer Data Platform API key from CustomerIO dashboard
+ * @param migrationSiteId - Legacy site ID for migrating from tracking API
+ * @param region - Data center region (US or EU)
+ * @param logLevel - SDK logging verbosity level
+ * @param apiHost - Override the CDP API host. Use to route SDK traffic through a first-party proxy.
+ * @param cdnHost - Override the CDN host. Use to route SDK traffic through a first-party proxy.
+ * @param flushAt - Number of events to batch before sending
+ * @param flushInterval - Time interval (seconds) to flush events
+ * @param screenViewUse - How to handle screen view tracking
+ * @param trackApplicationLifecycleEvents - Auto-track app lifecycle events
+ * @param autoTrackDeviceAttributes - Auto-track device information
+ * @param inApp - In-app messaging configuration
+ * @param push - Push notification configuration
+ *
+ * @public
+ */
+export type CioConfig = {
+  cdpApiKey: string;
+  migrationSiteId?: string;
+  region?: CioRegion;
+  logLevel?: CioLogLevel;
+  apiHost?: string;
+  cdnHost?: string;
+  flushAt?: number;
+  flushInterval?: number;
+  screenViewUse?: ScreenView;
+  trackApplicationLifecycleEvents?: boolean;
+  autoTrackDeviceAttributes?: boolean;
+  inApp?: {
+    siteId: string;
+  };
+  push?: {
+    android?: {
+      pushClickBehavior?: PushClickBehaviorAndroid;
+    };
+  };
+  location?: {
+    /** Location tracking mode. Defaults to 'manual' if location config is provided. */
+    trackingMode?: CioLocationTrackingMode;
+  };
+};
+
+/**
+ * Log levels for CustomerIO SDK debugging and monitoring.
+ *
+ * Controls the verbosity of SDK logging output for debugging purposes.
+ *
+ * @public
+ */
+export enum CioLogLevel {
+  /** No logging output */
+  None = 'none',
+  /** Only error messages */
+  Error = 'error',
+  /** Error and informational messages */
+  Info = 'info',
+  /** All messages including debug information */
+  Debug = 'debug',
+}
+
+/**
+ * Data center regions for CustomerIO API endpoints.
+ *
+ * @public
+ */
+export enum CioRegion {
+  US = 'US',
+  EU = 'EU',
+}
+
+/**
+ * Screen view tracking behavior configuration.
+ *
+ * Defines how the SDK should handle automatic screen view events
+ * for analytics and in-app message targeting.
+ *
+ * @public
+ */
+export enum ScreenView {
+  /** Send screen events to destinations and display in-app messages */
+  All = 'all',
+  /** Only display in-app messages, don't send to destinations */
+  InApp = 'inApp',
+}
+
+/**
+ * Location tracking mode for the CustomerIO Location module.
+ *
+ * @public
+ */
+export enum CioLocationTrackingMode {
+  /** Location tracking is disabled. All location operations no-op. */
+  Off = 'OFF',
+  /** Host app controls when location is captured (default when location config is provided). */
+  Manual = 'MANUAL',
+  /** SDK auto-captures location once per app launch when the app becomes active. */
+  OnAppStart = 'ON_APP_START',
+}
+
+/**
+ * Enum to specify the type of metric for tracking
+ *
+ * @public
+ */
+export enum MetricEvent {
+  /** Push notification was delivered to the device */
+  Delivered = 'delivered',
+  /** Push notification was opened by the user */
+  Opened = 'opened',
+  /** Push notification resulted in a conversion */
+  Converted = 'converted',
+}

package/src/types/in-app.ts

@@ -0,0 +1,69 @@
+/**
+ * In-app message data structure for event callbacks.
+ *
+ * Contains metadata about displayed in-app messages that can be used
+ * for tracking user interactions and message performance analytics.
+ *
+ * @public
+ */
+export interface InAppMessage {
+  /** Unique identifier for the message template */
+  messageId: string;
+  /** Unique identifier for this specific message delivery */
+  deliveryId?: string;
+  /** Element ID for inline message UI component that was interacted with */
+  elementId?: string;
+}
+
+/**
+ * Enum to represent the type of event triggered by in-app event callback.
+ *
+ * @public
+ */
+export enum InAppMessageEventType {
+  errorWithMessage = 'errorWithMessage',
+  messageActionTaken = 'messageActionTaken',
+  messageDismissed = 'messageDismissed',
+  messageShown = 'messageShown',
+}
+
+/**
+ * Represents an inbox message for a user.
+ *
+ * Inbox messages are persistent messages that can be displayed in a message center or inbox UI.
+ * They support read/unread states, expiration, and custom properties.
+ *
+ * @public
+ */
+export interface InboxMessage {
+  /** Internal queue identifier (for SDK use) */
+  queueId: string;
+  /** Unique identifier for this message delivery */
+  deliveryId?: string;
+  /** Expiration date for the message. Messages may be hidden after this date. */
+  expiry?: number;
+  /** Date when the message was sent (Unix timestamp in milliseconds) */
+  sentAt: number;
+  /** List of topic identifiers associated with this message */
+  topics: string[];
+  /** Message type identifier */
+  type: string;
+  /** Whether the user has opened/read this message */
+  opened: boolean;
+  /** Priority for message ordering. Lower values = higher priority (e.g., 1 is higher priority than 100) */
+  priority?: number;
+  /** Custom key-value properties associated with this message */
+  properties: Record<string, any>;
+}
+
+/**
+ * Listener for notification inbox message changes.
+ *
+ * Receives real-time notifications when inbox messages are added, updated, or removed.
+ * Callbacks are invoked on the main thread for safe UI updates.
+ *
+ * @public
+ */
+export type NotificationInboxChangeListener = {
+  onMessagesChanged: (messages: InboxMessage[]) => void;
+};

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export * from './data-pipelines';
+export * from './in-app';
+export * from './push';

package/src/types/internal.ts

@@ -0,0 +1,20 @@
+/**
+ * Internal-only types used within the Customer.io React Native SDK implementation.
+ *
+ * Not intended for public use.
+ */
+
+/**
+ * Arguments passed to native SDK for package identification.
+ *
+ * Provides metadata about the host environment and SDK version to native
+ * CustomerIO SDK for debugging and analytics.
+ *
+ * @internal
+ */
+export type NativeSDKArgs = {
+  /** The package manager or framework hosting the SDK (ReactNative, Expo) */
+  packageSource: string;
+  /** Version of the SDK package being used */
+  packageVersion: string;
+};

package/src/types/push.ts

@@ -0,0 +1,50 @@
+/**
+ * Android-specific behavior when a push notification is clicked.
+ *
+ * Controls how the Android system handles activity lifecycle
+ * when users tap on push notifications.
+ *
+ * @public
+ */
+export enum PushClickBehaviorAndroid {
+  /** Clear the activity task stack and start fresh */
+  ResetTaskStack = 'RESET_TASK_STACK',
+  /** Prevent the current activity from restarting */
+  ActivityPreventRestart = 'ACTIVITY_PREVENT_RESTART',
+  /** Use default behavior without special flags */
+  ActivityNoFlags = 'ACTIVITY_NO_FLAGS',
+}
+
+/**
+ * Push notification permission request options.
+ *
+ * Configure which types of notifications to request permission for
+ * on different platforms.
+ *
+ * @public
+ */
+export type CioPushPermissionOptions = {
+  ios?: {
+    /** Request permission to show badge numbers on app icon */
+    badge: boolean;
+    /** Request permission to play notification sounds */
+    sound: boolean;
+  };
+};
+
+/**
+ * Current push notification permission status.
+ *
+ * Indicates whether the user has granted, denied, or not yet
+ * responded to push notification permission requests.
+ *
+ * @public
+ */
+export enum CioPushPermissionStatus {
+  /** User has granted push notification permissions */
+  Granted = 'GRANTED',
+  /** User has denied push notification permissions */
+  Denied = 'DENIED',
+  /** User may not yet have been asked for permissions and permission status is unknown */
+  NotDetermined = 'NOTDETERMINED',
+}