react-native-moengage-personalize 1.0.0

package/src/internal/utils/PayloadBuilder.ts

@@ -0,0 +1,91 @@
+import ExperienceCampaign from "../../model/ExperienceCampaign";
+import { ExperienceStatus } from "../../model/ExperienceStatus";
+import { MoEngageLogger } from "react-native-moengage";
+import { MODULE_TAG } from "../Constants";
+
+const TAG = `${MODULE_TAG}PayloadBuilder`;
+
+function getAccountMetaPayload(appId: string) {
+    return { appId: appId };
+}
+
+function serializeCampaign(campaign: ExperienceCampaign) {
+    if (campaign.payload == null) {
+        MoEngageLogger.warn(`${TAG} serializeCampaign() : campaign.payload is null/undefined for "${campaign.experienceKey}"`);
+    }
+    if (campaign.experienceContext == null) {
+        MoEngageLogger.warn(`${TAG} serializeCampaign() : campaign.experienceContext is null/undefined for "${campaign.experienceKey}"`);
+    }
+    return {
+        experienceKey: campaign.experienceKey,
+        payload: campaign.payload,
+        experienceContext: campaign.experienceContext,
+        source: campaign.source
+    };
+}
+
+export function buildFetchExperiencesMetaPayload(appId: string, statuses: ExperienceStatus[]): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            status: statuses
+        }
+    };
+    return JSON.stringify(payload);
+}
+
+export function buildFetchExperiencesPayload(appId: string, experienceKeys: string[], attributes: Record<string, string>): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            experienceKeys: experienceKeys,
+            attributes: attributes
+        }
+    };
+    return JSON.stringify(payload);
+}
+
+export function buildExperiencesShownPayload(appId: string, campaigns: ExperienceCampaign[]): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            experiences: campaigns.map(serializeCampaign)
+        }
+    };
+    return JSON.stringify(payload);
+}
+
+export function buildExperienceClickedPayload(appId: string, campaign: ExperienceCampaign): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            experience: serializeCampaign(campaign)
+        }
+    };
+    return JSON.stringify(payload);
+}
+
+export function buildOfferingsShownPayload(appId: string, offeringPayloads: Record<string, any>[]): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            offeringPayloads: offeringPayloads
+        }
+    };
+    return JSON.stringify(payload);
+}
+
+export function buildOfferingClickedPayload(
+    appId: string,
+    campaign: ExperienceCampaign,
+    offeringPayload: Record<string, any>
+): string {
+    let payload = {
+        accountMeta: getAccountMetaPayload(appId),
+        data: {
+            experience: serializeCampaign(campaign),
+            offeringPayload: offeringPayload
+        }
+    };
+    return JSON.stringify(payload);
+}

package/src/internal/utils/PayloadParser.ts

@@ -0,0 +1,117 @@
+import ExperienceCampaign from "../../model/ExperienceCampaign";
+import ExperienceCampaignFailure from "../../model/ExperienceCampaignFailure";
+import ExperienceCampaignMeta from "../../model/ExperienceCampaignMeta";
+import ExperienceCampaignsMetadata from "../../model/ExperienceCampaignsMetadata";
+import ExperienceCampaignsResult from "../../model/ExperienceCampaignsResult";
+import { DataSource } from "../../model/DataSource";
+import { ExperienceStatus } from "../../model/ExperienceStatus";
+import { ExperienceFailureReason, KNOWN_FAILURE_REASONS } from "../../model/ExperienceFailureReason";
+import { MoEngageLogger } from "react-native-moengage";
+import {
+    MODULE_TAG,
+    keyData,
+    keyStatus,
+    keyExperiences,
+    keyExperienceKey,
+    keyExperienceName,
+    keyPayload,
+    keyExperienceContext,
+    keySource,
+    keyFailures,
+    keyReason,
+    keyExperienceKeys
+} from "../Constants";
+
+const TAG = `${MODULE_TAG}PayloadParser`;
+
+function parseDataSource(value: string): DataSource {
+    if (value === DataSource.CACHE) return DataSource.CACHE;
+    if (value === DataSource.NETWORK) return DataSource.NETWORK;
+    MoEngageLogger.warn(`${TAG} parseDataSource() : Unknown DataSource "${value}", defaulting to NETWORK`);
+    return DataSource.NETWORK;
+}
+
+function parseExperienceStatus(value: string): ExperienceStatus {
+    switch (value.toLowerCase()) {
+        case ExperienceStatus.ACTIVE: return ExperienceStatus.ACTIVE;
+        case ExperienceStatus.PAUSED: return ExperienceStatus.PAUSED;
+        case ExperienceStatus.SCHEDULED: return ExperienceStatus.SCHEDULED;
+        default:
+            MoEngageLogger.warn(`${TAG} parseExperienceStatus() : Unknown ExperienceStatus "${value}", defaulting to ACTIVE`);
+            return ExperienceStatus.ACTIVE;
+    }
+}
+
+function parseFailureReason(value: string): ExperienceFailureReason {
+    if (KNOWN_FAILURE_REASONS.has(value as ExperienceFailureReason)) {
+        return value as ExperienceFailureReason;
+    }
+    MoEngageLogger.warn(`${TAG} parseFailureReason() : Unknown ExperienceFailureReason "${value}", defaulting to PERSONALIZATION_FAILED`);
+    return "PERSONALIZATION_FAILED";
+}
+
+export function parseExperiencesMetadata(payload: string): ExperienceCampaignsMetadata {
+    MoEngageLogger.verbose(`${TAG} parseExperiencesMetadata() : ${payload}`);
+    const json = JSON.parse(payload);
+    const data = json[keyData];
+    if (data == null || typeof data !== "object") {
+        MoEngageLogger.warn(`${TAG} parseExperiencesMetadata() : missing or invalid 'data' key, returning empty result`);
+        return new ExperienceCampaignsMetadata(DataSource.NETWORK, []);
+    }
+
+    const source = parseDataSource(data[keySource]);
+    const experiences: ExperienceCampaignMeta[] = [];
+
+    const experiencesArray = data[keyExperiences];
+    if (Array.isArray(experiencesArray)) {
+        for (const exp of experiencesArray) {
+            if (exp == null || typeof exp !== "object") continue;
+            experiences.push(new ExperienceCampaignMeta(
+                exp[keyExperienceKey] ?? "",
+                exp[keyExperienceName] ?? "",
+                parseExperienceStatus(exp[keyStatus])
+            ));
+        }
+    }
+
+    return new ExperienceCampaignsMetadata(source, experiences);
+}
+
+export function parseExperiencesResult(payload: string): ExperienceCampaignsResult {
+    MoEngageLogger.verbose(`${TAG} parseExperiencesResult() : ${payload}`);
+    const json = JSON.parse(payload);
+    const data = json[keyData];
+    if (data == null || typeof data !== "object") {
+        MoEngageLogger.warn(`${TAG} parseExperiencesResult() : missing or invalid 'data' key, returning empty result`);
+        return new ExperienceCampaignsResult([], []);
+    }
+
+    const experiences: ExperienceCampaign[] = [];
+    const failures: ExperienceCampaignFailure[] = [];
+
+    const experiencesArray = data[keyExperiences];
+    if (Array.isArray(experiencesArray)) {
+        for (const exp of experiencesArray) {
+            if (exp == null || typeof exp !== "object") continue;
+            experiences.push(new ExperienceCampaign(
+                exp[keyExperienceKey] ?? "",
+                exp[keyPayload] ?? {},
+                exp[keyExperienceContext] ?? {},
+                parseDataSource(exp[keySource])
+            ));
+        }
+    }
+
+    const failuresArray = data[keyFailures];
+    if (Array.isArray(failuresArray)) {
+        for (const fail of failuresArray) {
+            if (fail == null || typeof fail !== "object") continue;
+            failures.push(new ExperienceCampaignFailure(
+                parseFailureReason(fail[keyReason]),
+                fail[keyExperienceKeys] ?? []
+            ));
+        }
+    }
+
+    return new ExperienceCampaignsResult(experiences, failures);
+}

package/src/model/DataSource.ts

@@ -0,0 +1,12 @@
+/**
+ * Source from which an experience campaign or its metadata was retrieved.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export enum DataSource {
+  /** Returned from local cache. */
+  CACHE = "CACHE",
+  /** Fetched from the MoEngage backend. */
+  NETWORK = "NETWORK",
+}

package/src/model/ExperienceCampaign.ts

@@ -0,0 +1,47 @@
+import { DataSource } from "./DataSource";
+
+/**
+ * Holds the data for a single experience campaign returned by the personalization
+ * service.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export default class ExperienceCampaign {
+
+  /**
+   * Unique identifier for the experience.
+   * @since 1.0.0
+   */
+  experienceKey: string;
+
+  /**
+   * The JSON payload for the experience campaign.
+   * @since 1.0.0
+   */
+  payload: Record<string, any>;
+
+  /**
+   * Metadata describing the experience campaign (campaign id, audience, locale, etc.).
+   * @since 1.0.0
+   */
+  experienceContext: Record<string, string>;
+
+  /**
+   * Source from which the campaign was retrieved (cache or network).
+   * @since 1.0.0
+   */
+  source: DataSource;
+
+  constructor(
+    experienceKey: string,
+    payload: Record<string, any>,
+    experienceContext: Record<string, string>,
+    source: DataSource
+  ) {
+    this.experienceKey = experienceKey;
+    this.payload = payload;
+    this.experienceContext = experienceContext;
+    this.source = source;
+  }
+}

package/src/model/ExperienceCampaignFailure.ts

@@ -0,0 +1,28 @@
+import { ExperienceFailureReason } from "./ExperienceFailureReason";
+
+/**
+ * Represents a categorized failure for one or more experience campaigns within
+ * a fetch result.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export default class ExperienceCampaignFailure {
+
+  /**
+   * Reason this group of experience campaigns failed.
+   * @since 1.0.0
+   */
+  reason: ExperienceFailureReason;
+
+  /**
+   * List of experience keys that failed for this reason.
+   * @since 1.0.0
+   */
+  experienceKeys: string[];
+
+  constructor(reason: ExperienceFailureReason, experienceKeys: string[]) {
+    this.reason = reason;
+    this.experienceKeys = experienceKeys;
+  }
+}

package/src/model/ExperienceCampaignMeta.ts

@@ -0,0 +1,34 @@
+import { ExperienceStatus } from "./ExperienceStatus";
+
+/**
+ * Lightweight metadata for an experience campaign returned by `fetchExperiencesMeta`.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export default class ExperienceCampaignMeta {
+
+  /**
+   * Unique identifier for the experience.
+   * @since 1.0.0
+   */
+  experienceKey: string;
+
+  /**
+   * Human-readable name of the experience campaign.
+   * @since 1.0.0
+   */
+  experienceName: string;
+
+  /**
+   * Current status of the experience campaign.
+   * @since 1.0.0
+   */
+  status: ExperienceStatus;
+
+  constructor(experienceKey: string, experienceName: string, status: ExperienceStatus) {
+    this.experienceKey = experienceKey;
+    this.experienceName = experienceName;
+    this.status = status;
+  }
+}

package/src/model/ExperienceCampaignsMetadata.ts

@@ -0,0 +1,29 @@
+import { DataSource } from "./DataSource";
+import ExperienceCampaignMeta from "./ExperienceCampaignMeta";
+
+/**
+ * Container for the result of `fetchExperiencesMeta` — the source of the data
+ * and the list of experience metadata entries.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export default class ExperienceCampaignsMetadata {
+
+  /**
+   * Source from which the metadata was retrieved (cache or network).
+   * @since 1.0.0
+   */
+  source: DataSource;
+
+  /**
+   * List of experience metadata entries.
+   * @since 1.0.0
+   */
+  experiences: ExperienceCampaignMeta[];
+
+  constructor(source: DataSource, experiences: ExperienceCampaignMeta[]) {
+    this.source = source;
+    this.experiences = experiences;
+  }
+}

package/src/model/ExperienceCampaignsResult.ts

@@ -0,0 +1,30 @@
+import ExperienceCampaign from "./ExperienceCampaign";
+import ExperienceCampaignFailure from "./ExperienceCampaignFailure";
+
+/**
+ * Container for the result of `fetchExperiences` — the successfully fetched
+ * campaigns plus any failures grouped by reason.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export default class ExperienceCampaignsResult {
+
+  /**
+   * Successfully fetched experience campaigns.
+   * @since 1.0.0
+   */
+  experiences: ExperienceCampaign[];
+
+  /**
+   * Failures grouped by reason — each entry lists the experience keys that
+   * failed for that reason.
+   * @since 1.0.0
+   */
+  failures: ExperienceCampaignFailure[];
+
+  constructor(experiences: ExperienceCampaign[], failures: ExperienceCampaignFailure[]) {
+    this.experiences = experiences;
+    this.failures = failures;
+  }
+}

package/src/model/ExperienceFailureReason.ts

@@ -0,0 +1,36 @@
+/**
+ * Server-side failure reasons for an experience campaign fetch. Mirrors the
+ * `ExperienceFailureReason` enum in the contract proto.
+ *
+ * SDK-level errors (network errors, SDK not initialized, etc.) surface via
+ * `Promise.reject` from the fetch APIs and are not part of this union.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export type ExperienceFailureReason =
+    | "USER_IN_CAMPAIGN_CONTROL_GROUP"
+    | "USER_IN_GLOBAL_CONTROL_GROUP"
+    | "USER_NOT_IN_SEGMENT"
+    | "INVALID_EXPERIENCE_KEY"
+    | "MAX_LIMIT_BREACHED"
+    | "EXPERIENCE_NOT_ACTIVE"
+    | "EXPERIENCE_EXPIRED"
+    | "PERSONALIZATION_FAILED";
+
+/**
+ * Set of all known failure reasons. Used by the parser to validate incoming
+ * values and fall back to `PERSONALIZATION_FAILED` for unknown values.
+ *
+ * @since 1.0.0
+ */
+export const KNOWN_FAILURE_REASONS: ReadonlySet<ExperienceFailureReason> = new Set([
+    "USER_IN_CAMPAIGN_CONTROL_GROUP",
+    "USER_IN_GLOBAL_CONTROL_GROUP",
+    "USER_NOT_IN_SEGMENT",
+    "INVALID_EXPERIENCE_KEY",
+    "MAX_LIMIT_BREACHED",
+    "EXPERIENCE_NOT_ACTIVE",
+    "EXPERIENCE_EXPIRED",
+    "PERSONALIZATION_FAILED",
+]);

package/src/model/ExperienceStatus.ts

@@ -0,0 +1,14 @@
+/**
+ * Lifecycle status of an experience campaign on the MoEngage dashboard.
+ *
+ * @author MoEngage
+ * @since 1.0.0
+ */
+export enum ExperienceStatus {
+  /** Currently running. */
+  ACTIVE = "active",
+  /** Manually paused on the dashboard. */
+  PAUSED = "paused",
+  /** Scheduled to start in the future. */
+  SCHEDULED = "scheduled",
+}