IterableEmbeddedManager.ts

import { NativeEventEmitter } from 'react-native';

import { RNIterableAPI } from '../../api';
import { IterableAction } from '../../core/classes/IterableAction';
import { IterableActionContext } from '../../core/classes/IterableActionContext';
import { IterableApi } from '../../core/classes/IterableApi';
import { IterableConfig } from '../../core/classes/IterableConfig';
import { IterableLogger } from '../../core/classes/IterableLogger';
import { IterableActionSource } from '../../core/enums/IterableActionSource';
import { IterableEventName } from '../../core/enums/IterableEventName';
import { callUrlHandler } from '../../core/utils/callUrlHandler';
import { getActionPrefix } from '../../core/utils/getActionPrefix';
import type { IterableEmbeddedMessage } from '../types/IterableEmbeddedMessage';

const RNEventEmitter = new NativeEventEmitter(RNIterableAPI);

/**
 * Manages embedded messages from Iterable.
 *
 * Provides embedded message functionality including retrieving messages,
 * displaying messages, removing messages, and more.
 *
 * **Documentation**
 * - [Embedded Messaging Overview](https://support.iterable.com/hc/en-us/articles/23060529977364-Embedded-Messaging-Overview)
 * - [Android Embedded Messaging](https://support.iterable.com/hc/en-us/articles/23061877893652-Embedded-Messages-with-Iterable-s-Android-SDK)
 * - [iOS Embedded Messaging](https://support.iterable.com/hc/en-us/articles/23061840746900-Embedded-Messages-with-Iterable-s-iOS-SDK)
 */
export class IterableEmbeddedManager {
  /**
   * List of listeners for embedded messages updated events.
   */
  private _messagesUpdatedListeners: (() => void)[] = [];

  /**
   * List of listeners for embedded messaging disabled events.
   */
  private _embeddedMessagingDisabledListeners: (() => void)[] = [];

  /**
   * Whether the embedded manager is enabled.
   *
   * This is set through the `enableEmbeddedMessaging` flag in the
   * `IterableConfig` class.
   */
  private _isEnabled = false;

  /**
   * Gets whether the embedded manager is enabled.
   */
  get isEnabled(): boolean {
    return this._isEnabled;
  }

  /**
   * Sets whether the embedded manager is enabled.
   *
   * @internal This method is for internal SDK use only and should not be called
   * by SDK consumers, as it is meant to be called at initialization time.
   *
   * @param enabled - Whether the embedded manager is enabled.
   */
  setEnabled(enabled: boolean) {
    this._isEnabled = enabled;
  }

  /**
   * The config for the Iterable SDK.
   */
  private _config: IterableConfig = new IterableConfig();

  constructor(config: IterableConfig) {
    this._config = config;
    this._isEnabled = config.enableEmbeddedMessaging ?? false;
  }

  /**
   * Notifies all registered listeners that messages have been updated.
   *
   * @internal This method is for internal SDK use only.
   */
  notifyMessagesUpdated() {
    this._messagesUpdatedListeners.forEach((listener) => {
      listener();
    });
  }

  /**
   * Notifies all registered listeners that embedded messaging has been disabled.
   *
   * @internal This method is for internal SDK use only.
   */
  notifyEmbeddedMessagingDisabled() {
    this._embeddedMessagingDisabledListeners.forEach((listener) => {
      listener();
    });
  }

  /**
   * Syncs embedded local cache with the server.
   *
   * When your app first launches, and each time it comes to the foreground,
   * Iterable's Native SDKs automatically refresh a local, on-device cache of
   * embedded messages for the signed-in user. These are the messages the
   * signed-in user is eligible to see.
   *
   * At key points during your app's lifecycle, you may want to manually refresh
   * your app's local cache of embedded messages. For example, as users navigate
   * around, on pull-to-refresh, etc.
   *
   * However, do not poll for new embedded messages at a regular interval.
   *
   * @example
   * ```typescript
   * IterableEmbeddedManager.syncMessages();
   * ```
   */
  syncMessages() {
    return IterableApi.syncEmbeddedMessages();
  }

  /**
   * Retrieves a list of placement IDs for the embedded manager.
   *
   * [Placement Documentation](https://support.iterable.com/hc/en-us/articles/23060529977364-Embedded-Messaging-Overview#placements-and-prioritization)
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.getPlacementIds().then(placementIds => {
   *   console.log('Placement IDs:', placementIds);
   * });
   * ```
   */
  getPlacementIds() {
    return IterableApi.getEmbeddedPlacementIds();
  }

  /**
   * Retrieves a list of embedded messages the user is eligible to see.
   *
   * @param placementIds - The placement IDs to retrieve messages for.
   * @returns A Promise that resolves to an array of embedded messages.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.getMessages([1, 2, 3]).then(messages => {
   *   console.log('Messages:', messages);
   * });
   * ```
   */
  getMessages(
    placementIds: number[] | null
  ): Promise<IterableEmbeddedMessage[]> {
    return IterableApi.getEmbeddedMessages(placementIds);
  }

  /**
   * Starts a session.
   *
   * A session is a period of time when a user is on a screen or page that can
   * display embedded messages.
   *
   * When a user comes to a screen or page in your app where embedded messages
   * are displayed (in one or more placements), a session should be started.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.startSession();
   * ```
   */
  startSession() {
    return IterableApi.startEmbeddedSession();
  }

  /**
   * Ends a session.
   *
   * When a user leaves a screen in your app where embedded messages are
   * displayed, the session should be ended.  This causes the SDK to send
   * session an impression data back to the server.
   *
   * A session is tracked when it is ended, so you should be able to find
   * tracking data after this method is called.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.endSession();
   * ```
   */
  endSession() {
    return IterableApi.endEmbeddedSession();
  }
  /**
   * Starts an embedded impression.
   *
   * An impression represents the on-screen appearances of a given embedded message,
   * in context of a session.
   *
   * Each impression tracks:
   * - The total number of times a message appears during a session.
   * - The total amount of time that message was visible, across all its
   *   appearances in the session.
   *
   * Be sure to start and pause impressions when your app goes to and from the
   * background, too.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.startImpression(messageId, placementId);
   * ```
   */
  startImpression(messageId: string, placementId: number) {
    return IterableApi.startEmbeddedImpression(messageId, placementId);
  }

  /**
   * Pauses an embedded impression.
   *
   * An impression represents the on-screen appearances of a given embedded message,
   * in context of a session.
   *
   * And impression should be paused when the message is no longer visible,
   * including when your app goes to the background.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.pauseImpression(messageId);
   * ```
   */
  pauseImpression(messageId: string) {
    return IterableApi.pauseEmbeddedImpression(messageId);
  }

  /**
   * Tracks a click on an embedded message.
   *
   * This is called internally when `Iterable.embeddedManager.handleClick` is
   * called.  However, if you want to implement your own click handling, you can
   * use this method to track the click you implement.
   *
   * @param message - The embedded message.
   * @param buttonId - The button ID.
   * @param clickedUrl - The clicked URL.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.trackClick(message, buttonId, clickedUrl);
   * ```
   */
  trackClick(
    message: IterableEmbeddedMessage,
    buttonId: string | null,
    clickedUrl: string | null
  ) {
    return IterableApi.trackEmbeddedClick(message, buttonId, clickedUrl);
  }

  /**
   * Handles a click on an embedded message.
   *
   * This will fire the correct handlers set in the config, and will track the
   * click.  It should be use on either a button click or a click on the message itself.
   *
   * @param message - The embedded message.
   * @param buttonId - The button ID.
   * @param clickedUrl - The clicked URL.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.handleClick(message, buttonId, clickedUrl);
   * ```
   */
  handleClick(
    message: IterableEmbeddedMessage,
    buttonId: string | null,
    action?: IterableAction | null
  ) {
    const { data, type: actionType } = action ?? {};
    const clickedUrl = data && data?.length > 0 ? data : actionType;

    IterableLogger.log(
      'Iterable.embeddedManager.handleClick',
      message,
      buttonId,
      clickedUrl
    );

    if (!clickedUrl) {
      IterableLogger.log(
        'Iterable.embeddedManager.handleClick:',
        'A url or action is required to handle an embedded click',
        clickedUrl
      );
      return;
    }

    const actionPrefix = getActionPrefix(clickedUrl);
    const source = IterableActionSource.embedded;

    this.trackClick(message, buttonId, clickedUrl);

    if (actionPrefix) {
      const actionName = clickedUrl?.replace(actionPrefix, '');
      const actionDetails = new IterableAction(actionName, '', '');
      const context = new IterableActionContext(actionDetails, source);
      if (this._config.customActionHandler) {
        this._config.customActionHandler(actionDetails, context);
      }
    } else {
      const actionDetails = new IterableAction('openUrl', clickedUrl, '');
      const context = new IterableActionContext(actionDetails, source);
      callUrlHandler(this._config, clickedUrl, context);
    }
  }

  /**
   * Adds a listener for when embedded messages are updated.
   *
   * This event fires when the embedded message cache is synced and messages
   * have changed (new messages added, existing messages removed, etc.).
   *
   * The listener is added to an internal list and will be called when the
   * native SDK detects that messages have been updated.
   *
   * @param callback - Function to call when messages are updated.
   *
   * @example
   * ```typescript
   * const callback = () => {
   *   // Refresh your UI with updated messages
   *   Iterable.embeddedManager.getMessages([1, 2, 3]).then(messages => {
   *     // Update UI with new messages
   *   });
   * };
   * Iterable.embeddedManager.addMessagesUpdatedListener(callback);
   *
   * // Later, remove the listener
   * Iterable.embeddedManager.removeMessagesUpdatedListener(callback);
   * ```
   */
  addMessagesUpdatedListener(callback: () => void) {
    // Add to internal list
    this._messagesUpdatedListeners.push(callback);
  }

  /**
   * Adds a listener for when embedded messaging is disabled.
   *
   * This event fires when embedded messaging is disabled, typically due to
   * subscription being inactive or invalid API key during sync.
   *
   * The listener is added to an internal list and will be called when the
   * native SDK detects that embedded messaging has been disabled.
   *
   * @param callback - Function to call when embedded messaging is disabled.
   *
   * @example
   * ```typescript
   * const callback = () => {
   *   // Handle embedded messaging being disabled
   *   console.log('Embedded messaging has been disabled');
   *   // Hide embedded message UI, etc.
   * };
   * Iterable.embeddedManager.addEmbeddedMessagingDisabledListener(callback);
   *
   * // Later, remove the listener
   * Iterable.embeddedManager.removeEmbeddedMessagingDisabledListener(callback);
   * ```
   */
  addEmbeddedMessagingDisabledListener(callback: () => void) {
    // Add to internal list
    this._embeddedMessagingDisabledListeners.push(callback);
  }

  /**
   * Removes a specific listener for when embedded messages are updated.
   *
   * @param callback - The callback function that was previously registered.
   *
   * @example
   * ```typescript
   * const listener = () => {
   *   console.log('Messages updated');
   * };
   * Iterable.embeddedManager.addMessagesUpdatedListener(listener);
   * // Later, remove the specific listener
   * Iterable.embeddedManager.removeMessagesUpdatedListener(listener);
   * ```
   */
  removeMessagesUpdatedListener(callback: () => void) {
    const index = this._messagesUpdatedListeners.indexOf(callback);
    if (index > -1) {
      this._messagesUpdatedListeners.splice(index, 1);
    }
  }

  /**
   * Removes a specific listener for when embedded messaging is disabled.
   *
   * @param callback - The callback function that was previously registered.
   *
   * @example
   * ```typescript
   * const listener = () => {
   *   console.log('Embedded messaging disabled');
   * };
   * Iterable.embeddedManager.addEmbeddedMessagingDisabledListener(listener);
   * // Later, remove the specific listener
   * Iterable.embeddedManager.removeEmbeddedMessagingDisabledListener(listener);
   * ```
   */
  removeEmbeddedMessagingDisabledListener(callback: () => void) {
    const index = this._embeddedMessagingDisabledListeners.indexOf(callback);
    if (index > -1) {
      this._embeddedMessagingDisabledListeners.splice(index, 1);
    }
  }

  /**
   * Removes all listeners for embedded message events.
   *
   * This removes all listeners for both `receivedIterableEmbeddedMessagesChanged`
   * and `receivedIterableEmbeddedMessagingDisabled` events, including the
   * internal lists of listeners.
   *
   * @example
   * ```typescript
   * Iterable.embeddedManager.removeAllListeners();
   * ```
   */
  removeAllListeners() {
    RNEventEmitter.removeAllListeners(
      IterableEventName.receivedIterableEmbeddedMessagesChanged
    );
    RNEventEmitter.removeAllListeners(
      IterableEventName.receivedIterableEmbeddedMessagingDisabled
    );
    // Clear internal listener lists
    this._messagesUpdatedListeners = [];
    this._embeddedMessagingDisabledListeners = [];
  }
}