@applicaster/zapp-react-native-utils 15.0.0-rc.94 → 15.0.0-rc.95

package/cloudEventsUtils/__tests__/index.test.ts

@@ -0,0 +1,529 @@
+// Mock dependencies are set up before requiring the module
+// The module is required dynamically in beforeEach to allow test-specific setup
+// and state is reset using resetCloudEventsSource() between tests
+jest.mock("uuid", () => ({
+  v4: jest.fn(() => "test-uuid-1234"),
+}));
+
+jest.mock("@applicaster/zapp-pipes-v2-client", () => ({
+  RequestBuilder: jest.fn().mockImplementation(() => ({
+    setUrl: jest.fn().mockReturnThis(),
+    setMethod: jest.fn().mockReturnThis(),
+    addBodyParams: jest.fn().mockReturnThis(),
+    call: jest.fn().mockResolvedValue({ success: true }),
+  })),
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage",
+  () => ({
+    sessionStorage: {
+      getItem: jest.fn(),
+    },
+  })
+);
+
+jest.mock("@applicaster/zapp-react-native-utils/appDataUtils", () => ({
+  getAppUrlScheme: jest.fn(),
+}));
+
+import { v4 as uuid } from "uuid";
+import { RequestBuilder } from "@applicaster/zapp-pipes-v2-client";
+import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
+import { getAppUrlScheme } from "@applicaster/zapp-react-native-utils/appDataUtils";
+import type { CloudEvent, CreateCloudEventParams } from "../index";
+
+describe("cloudEventsUtils", () => {
+  const mockGetAppUrlScheme = getAppUrlScheme as jest.MockedFunction<
+    typeof getAppUrlScheme
+  >;
+
+  const mockSessionStorageGetItem =
+    sessionStorage.getItem as jest.MockedFunction<
+      typeof sessionStorage.getItem
+    >;
+
+  const mockUuid = uuid as jest.MockedFunction<typeof uuid>;
+
+  let createCloudEvent: <T = any>(
+    params: CreateCloudEventParams<T>
+  ) => Promise<CloudEvent<T>>;
+
+  let sendCloudEvent: <T = any>(
+    cloudEvent: CloudEvent<T>,
+    url: string
+  ) => Promise<any>;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    // Setup default mocks
+    mockGetAppUrlScheme.mockReturnValue("myapp");
+
+    mockSessionStorageGetItem
+      .mockResolvedValueOnce("com.example.app") // bundleId
+      .mockResolvedValueOnce("1.0.0"); // appVersion
+
+    mockUuid.mockReturnValue("test-uuid-1234");
+
+    const utils = require("../");
+    createCloudEvent = utils.createCloudEvent;
+    sendCloudEvent = utils.sendCloudEvent;
+    utils.resetCloudEventsSource();
+
+    // Note: Source caching means tests will reuse the source from the first test
+    // Tests that need specific source values or error conditions should run in isolation
+  });
+
+  describe("createCloudEvent", () => {
+    it("should create a cloud event with all required fields", async () => {
+      const { createCloudEvent } = require("../index");
+
+      const event = await createCloudEvent({
+        type: "user.action",
+        subject: "button.click",
+        data: { buttonId: "submit" },
+      });
+
+      expect(event).toHaveProperty("specversion", "1.0");
+      expect(event).toHaveProperty("type", "user.action");
+      expect(event).toHaveProperty("subject", "button.click");
+      expect(event).toHaveProperty("datacontenttype", "application/json");
+      expect(event).toHaveProperty("source");
+      expect(event).toHaveProperty("time");
+      expect(event).toHaveProperty("id", "test-uuid-1234");
+      expect(event).toHaveProperty("data", { buttonId: "submit" });
+    });
+
+    it("should generate source from appUrlScheme, bundleId, and appVersion", async () => {
+      mockGetAppUrlScheme.mockReset();
+      mockGetAppUrlScheme.mockReturnValue("testapp");
+
+      mockSessionStorageGetItem.mockReset();
+
+      mockSessionStorageGetItem
+        .mockResolvedValueOnce("com.test.bundle")
+        .mockResolvedValueOnce("2.3.4");
+
+      const { createCloudEvent } = require("../index");
+
+      const event = await createCloudEvent({
+        type: "test.event",
+        subject: "test",
+        data: {},
+      });
+
+      expect(event.source).toBe("testapp://com.test.bundle/versions/2.3.4");
+    });
+
+    it("should generate unique ID using uuid", async () => {
+      mockUuid.mockReturnValueOnce("uuid-1").mockReturnValueOnce("uuid-2");
+
+      const { createCloudEvent } = require("../index");
+
+      const event1 = await createCloudEvent({
+        type: "event1",
+        subject: "subject1",
+        data: {},
+      });
+
+      const event2 = await createCloudEvent({
+        type: "event2",
+        subject: "subject2",
+        data: {},
+      });
+
+      expect(event1.id).toBe("uuid-1");
+      expect(event2.id).toBe("uuid-2");
+    });
+
+    it("should generate ISO timestamp for time field", async () => {
+      const event = await createCloudEvent({
+        type: "test.event",
+        subject: "test",
+        data: {},
+      });
+
+      // Verify ISO 8601 format
+      expect(event.time).toMatch(
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+      );
+
+      // Verify it's a valid date
+      expect(new Date(event.time).getTime()).toBeGreaterThan(0);
+    });
+
+    it("should include custom data in event", async () => {
+      const customData = {
+        userId: "user123",
+        action: "purchase",
+        amount: 99.99,
+        items: ["item1", "item2"],
+      };
+
+      const event = await createCloudEvent({
+        type: "commerce.purchase",
+        subject: "order.completed",
+        data: customData,
+      });
+
+      expect(event.data).toEqual(customData);
+    });
+
+    it("should throw error when appUrlScheme is missing", async () => {
+      jest.clearAllMocks();
+      mockSessionStorageGetItem.mockReset();
+      mockGetAppUrlScheme.mockReturnValue(null as any);
+
+      mockSessionStorageGetItem
+        .mockResolvedValueOnce("com.example.app")
+        .mockResolvedValueOnce("1.0.0");
+
+      mockUuid.mockReturnValue("test-uuid-1234");
+
+      const { createCloudEvent: freshCreate } = require("../index");
+
+      await expect(
+        freshCreate({
+          type: "test",
+          subject: "test",
+          data: {},
+        })
+      ).rejects.toThrow("Can not create client data addSource");
+    });
+
+    it("should throw error when bundleId is missing", async () => {
+      jest.clearAllMocks();
+      mockSessionStorageGetItem.mockReset();
+      mockGetAppUrlScheme.mockReturnValue("myapp");
+
+      mockSessionStorageGetItem
+        .mockResolvedValueOnce(null) // bundleId
+        .mockResolvedValueOnce("1.0.0");
+
+      mockUuid.mockReturnValue("test-uuid-1234");
+
+      const { createCloudEvent: freshCreate } = require("../index");
+
+      await expect(
+        freshCreate({
+          type: "test",
+          subject: "test",
+          data: {},
+        })
+      ).rejects.toThrow("Can not create client data addSource");
+    });
+
+    it("should throw error when appVersion is missing", async () => {
+      jest.clearAllMocks();
+      mockSessionStorageGetItem.mockReset();
+      mockGetAppUrlScheme.mockReturnValue("myapp");
+
+      mockSessionStorageGetItem
+        .mockResolvedValueOnce("com.example.app")
+        .mockResolvedValueOnce(null); // appVersion
+
+      mockUuid.mockReturnValue("test-uuid-1234");
+
+      const { createCloudEvent: freshCreate } = require("../index");
+
+      await expect(
+        freshCreate({
+          type: "test",
+          subject: "test",
+          data: {},
+        })
+      ).rejects.toThrow("Can not create client data addSource");
+    });
+
+    it("should cache source after first call", async () => {
+      jest.clearAllMocks();
+      mockGetAppUrlScheme.mockReturnValue("myapp");
+
+      mockSessionStorageGetItem.mockReset();
+
+      mockSessionStorageGetItem
+        .mockResolvedValueOnce("com.example.app")
+        .mockResolvedValueOnce("1.0.0");
+
+      mockUuid.mockReturnValueOnce("uuid-1").mockReturnValueOnce("uuid-2");
+
+      const freshUtils = require("../index");
+      freshUtils.resetCloudEventsSource();
+
+      const { createCloudEvent: freshCreate } = freshUtils;
+
+      const event1 = await freshCreate({
+        type: "event1",
+        subject: "subject1",
+        data: {},
+      });
+
+      const event2 = await freshCreate({
+        type: "event2",
+        subject: "subject2",
+        data: {},
+      });
+
+      expect(event1.source).toBe(event2.source);
+      expect(mockGetAppUrlScheme).toHaveBeenCalledTimes(1);
+      expect(mockSessionStorageGetItem).toHaveBeenCalledTimes(2);
+    });
+
+    it("should handle empty data object", async () => {
+      const event = await createCloudEvent({
+        type: "test.event",
+        subject: "test.subject",
+        data: {},
+      });
+
+      expect(event.data).toEqual({});
+    });
+
+    it("should handle null data", async () => {
+      const event = await createCloudEvent({
+        type: "test.event",
+        subject: "test.subject",
+        data: null,
+      });
+
+      expect(event.data).toBeNull();
+    });
+
+    it("should handle complex nested data", async () => {
+      const complexData = {
+        level1: {
+          level2: {
+            level3: {
+              value: "deep",
+            },
+          },
+        },
+        array: [1, 2, { nested: true }],
+      };
+
+      const event = await createCloudEvent({
+        type: "test.event",
+        subject: "test.subject",
+        data: complexData,
+      });
+
+      expect(event.data).toEqual(complexData);
+    });
+  });
+
+  describe("sendCloudEvent", () => {
+    let mockRequestBuilder: any;
+
+    beforeEach(() => {
+      mockRequestBuilder = {
+        setUrl: jest.fn().mockReturnThis(),
+        setMethod: jest.fn().mockReturnThis(),
+        addBodyParams: jest.fn().mockReturnThis(),
+        call: jest.fn().mockResolvedValue({ success: true, data: "response" }),
+      };
+
+      (
+        RequestBuilder as jest.MockedClass<typeof RequestBuilder>
+      ).mockImplementation(() => mockRequestBuilder);
+    });
+
+    it("should send cloud event to specified URL", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      const url = "https://api.example.com/events";
+
+      await sendCloudEvent(cloudEvent, url);
+
+      expect(mockRequestBuilder.setUrl).toHaveBeenCalledWith(url);
+      expect(mockRequestBuilder.setMethod).toHaveBeenCalledWith("POST");
+      expect(mockRequestBuilder.addBodyParams).toHaveBeenCalledWith(cloudEvent);
+      expect(mockRequestBuilder.call).toHaveBeenCalled();
+    });
+
+    it("should return response from API call", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      const expectedResponse = { success: true, eventId: "evt-123" };
+      mockRequestBuilder.call.mockResolvedValue(expectedResponse);
+
+      const result = await sendCloudEvent(
+        cloudEvent,
+        "https://api.example.com/events"
+      );
+
+      expect(result).toEqual(expectedResponse);
+    });
+
+    it("should throw error when URL is missing", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      await expect(sendCloudEvent(cloudEvent, "")).rejects.toThrow(
+        "Feed locator is missing"
+      );
+    });
+
+    it("should throw error when URL is null", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      await expect(sendCloudEvent(cloudEvent, null as any)).rejects.toThrow(
+        "Feed locator is missing"
+      );
+    });
+
+    it("should throw error when URL is undefined", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      await expect(
+        sendCloudEvent(cloudEvent, undefined as any)
+      ).rejects.toThrow("Feed locator is missing");
+    });
+
+    it("should handle API errors", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      mockRequestBuilder.call.mockRejectedValue(new Error("Network error"));
+
+      await expect(
+        sendCloudEvent(cloudEvent, "https://api.example.com/events")
+      ).rejects.toThrow("Network error");
+    });
+
+    it("should send event with all cloud event properties", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "user.created",
+        subject: "user/123",
+        source: "app://com.example/versions/1.0.0",
+        id: "uuid-123",
+        time: "2023-01-01T00:00:00.000Z",
+        datacontenttype: "application/json" as const,
+        data: {
+          userId: "123",
+          username: "testuser",
+        },
+      };
+
+      await sendCloudEvent(cloudEvent, "https://api.example.com/events");
+
+      expect(mockRequestBuilder.addBodyParams).toHaveBeenCalledWith(cloudEvent);
+    });
+
+    it("should handle different URL formats", async () => {
+      const cloudEvent: CloudEvent = {
+        specversion: "1.0" as const,
+        type: "test.event",
+        subject: "test",
+        source: "test://source",
+        id: "123",
+        time: new Date().toISOString(),
+        datacontenttype: "application/json" as const,
+        data: {},
+      };
+
+      const urls = [
+        "https://api.example.com/events",
+        "http://localhost:3000/events",
+        "https://api.example.com/v1/events?apiKey=123",
+      ];
+
+      for (const url of urls) {
+        mockRequestBuilder.setUrl.mockClear();
+        await sendCloudEvent(cloudEvent, url);
+        expect(mockRequestBuilder.setUrl).toHaveBeenCalledWith(url);
+      }
+    });
+  });
+
+  describe("integration", () => {
+    it("should create and send cloud event together", async () => {
+      const mockResponse = { success: true, eventId: "evt-123" };
+
+      const mockRequestBuilder = {
+        setUrl: jest.fn().mockReturnThis(),
+        setMethod: jest.fn().mockReturnThis(),
+        addBodyParams: jest.fn().mockReturnThis(),
+        call: jest.fn().mockResolvedValue(mockResponse),
+      };
+
+      (
+        RequestBuilder as jest.MockedClass<typeof RequestBuilder>
+      ).mockImplementation(() => mockRequestBuilder as any);
+
+      const event = await createCloudEvent({
+        type: "user.action",
+        subject: "button.click",
+        data: { buttonId: "submit" },
+      });
+
+      const response = await sendCloudEvent(
+        event,
+        "https://api.example.com/events"
+      );
+
+      expect(mockRequestBuilder.addBodyParams).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "user.action",
+          subject: "button.click",
+          data: { buttonId: "submit" },
+        })
+      );
+
+      expect(response).toEqual(mockResponse);
+    });
+  });
+});

package/cloudEventsUtils/index.ts

@@ -3,6 +3,41 @@ import { RequestBuilder } from "@applicaster/zapp-pipes-v2-client";
 import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
 import { getAppUrlScheme } from "@applicaster/zapp-react-native-utils/appDataUtils";
 
+/**
+ * CloudEvents v1.0 compliant event object
+ * @see https://github.com/cloudevents/spec/blob/v1.0/spec.md
+ */
+export interface CloudEvent<T = any> {
+  /** CloudEvents specification version (always "1.0") */
+  specversion: "1.0";
+  /** Type of event (e.g., "user.action", "commerce.purchase") */
+  type: string;
+  /** Identifier for the entity that produced the event */
+  source: string;
+  /** Unique identifier for the event */
+  id: string;
+  /** Subject of the event in the context of the event producer */
+  subject: string;
+  /** Timestamp of when the event occurred (ISO 8601 format) */
+  time: string;
+  /** Content type of the data attribute (always "application/json") */
+  datacontenttype: "application/json";
+  /** Event payload */
+  data: T;
+}
+
+/**
+ * Parameters required to create a cloud event
+ */
+export interface CreateCloudEventParams<T = any> {
+  /** Type of event (e.g., "user.action", "commerce.purchase") */
+  type: string;
+  /** Subject of the event in the context of the event producer */
+  subject: string;
+  /** Event payload */
+  data: T;
+}
+
 let source: string | null = null;
 
 const addSource = async () => {
@@ -26,7 +61,36 @@ const addSource = async () => {
   return source;
 };
 
-export const createCloudEvent = async ({ type, subject, data }) => {
+/**
+ * Resets the cached CloudEvents source.
+ *
+ * @internal
+ * @testonly This function is intended for test use only and will only work in test environments.
+ *
+ * @remarks
+ * This function clears the cached source value, forcing the next call to `createCloudEvent`
+ * to regenerate the source from app metadata. It only operates when NODE_ENV is set to "test"
+ * to prevent accidental misuse in production code.
+ *
+ * @example
+ * ```typescript
+ * // In Jest tests
+ * beforeEach(() => {
+ *   resetCloudEventsSource();
+ * });
+ * ```
+ */
+export const resetCloudEventsSource = (): void => {
+  if (process.env.NODE_ENV === "test") {
+    source = null;
+  }
+};
+
+export const createCloudEvent = async <T = any>({
+  type,
+  subject,
+  data,
+}: CreateCloudEventParams<T>): Promise<CloudEvent<T>> => {
   return {
     specversion: "1.0",
     type,