@applicaster/zapp-react-native-utils 15.1.6-alpha.3988508055 → 16.0.0-alpha.1020865559

package/arrayUtils/index.ts

@@ -3,17 +3,16 @@ import * as R from "ramda";
 import { invariant } from "@applicaster/zapp-react-native-utils/errorUtils";
 
 /**
- * shifts an array by the given offset. a negative offset will take items
- * from the end of the array and add them at the beginning, while a positive offset
- * will take an item at the beginning and shift it to the end
- * shiftArray(-1, [1,2,3,4]) => [4, 1, 2, 3]
- * shiftArray(1, [1,2,3,4]) => [2, 3, 4, 1]
- * an offset of 0 leaves the array unchanged
- * this function returns a new array and doesn't mutate the original one
- * curried function which can be invoked like offset => array => result
- * @param {Number} offset offset to shift the array
- * @param {Array<T>} array array to shift
- * @returns {Array<T>}
+ * Shifts an array by the given offset and returns a new array (does not mutate).
+ * A positive offset moves items from the head to the tail;
+ * a negative offset moves items from the tail to the head.
+ * An offset of `0` leaves the order unchanged.
+ *
+ * Curried (Ramda): `shiftArray(offset)(array)` or `shiftArray(offset, array)`.
+ *
+ * @example
+ * shiftArray(-1, [1, 2, 3, 4]) // => [4, 1, 2, 3]
+ * shiftArray(1, [1, 2, 3, 4])  // => [2, 3, 4, 1]
  */
 export const shiftArray = R.curry(
   <T extends unknown>(offset: number, array: T[]): T[] => {
@@ -25,10 +24,9 @@ export const shiftArray = R.curry(
 );
 
 /**
- * Tries to remove an item from an array, and returns the array if the item is not found
- * @param {any} item to remove
- * @param {Array<any>} list to remove the item from
- * @returns {Array<any>}
+ * Removes the first item equal to `item` from `list` (Ramda `equals` / deep equality).
+ * If the item is not found, returns the same list reference; otherwise returns a new
+ * array without that element.
  */
 export function removeItemFromList<T extends unknown>(item: T, list: T[]): T[] {
   return R.compose(
@@ -37,6 +35,12 @@ export function removeItemFromList<T extends unknown>(item: T, list: T[]): T[] {
   )(list);
 }
 
+/**
+ * Maps each value to a promise and resolves them all in parallel via `Promise.all`.
+ * The mapper receives `(value, index)`.
+ *
+ * Curried (Ramda): `mapPromises(fn)(values)` or `mapPromises(fn, values)`.
+ */
 export const mapPromises = R.curry(
   <T extends unknown, S extends unknown>(
     fn: (value: T, index?: number) => Promise<S>,
@@ -44,6 +48,10 @@ export const mapPromises = R.curry(
   ): Promise<S[]> => Promise.all(R.addIndex(R.map)(R.nAry(2, fn), values))
 );
 
+/**
+ * Awaits `previousPromise`, then runs `fn(currentValue, previousValue, index)`.
+ * Used internally by `reducePromises` as a Ramda-indexed reducer step.
+ */
 const waitForPromiseAndRun = R.curryN(
   3,
   async <T extends unknown, S extends unknown>(
@@ -58,6 +66,14 @@ const waitForPromiseAndRun = R.curryN(
   }
 );
 
+/**
+ * Reduces a list by applying an async function sequentially.
+ * Each step awaits the previous result, then calls `fn(current, previous, index)`.
+ * An empty list resolves to `initialValue` without calling `fn`.
+ *
+ * Curried (Ramda): `reducePromises(fn)(initialValue)(values)` or
+ * `reducePromises(fn, initialValue, values)`.
+ */
 export const reducePromises = R.curry(
   <T extends unknown, S extends unknown>(
     fn: (current: T, previous: S, index?: number) => Promise<S>,
@@ -71,18 +87,32 @@ export const reducePromises = R.curry(
     )
 );
 
+/**
+ * Returns a function that maps a list with `mapperFn`, then splits the result
+ * into chunks of size `chunks` (`R.splitEvery`).
+ *
+ * Curried (Ramda): `mapAndSplit(mapperFn, chunks)(values)`.
+ */
 export const mapAndSplit = R.curry(
   <T extends unknown, S extends unknown>(
-    mapperFn: (T) => S,
+    mapperFn: (value: T) => S,
     chunks: number
-  ): S[][] => R.compose(R.splitEvery(chunks), R.map(mapperFn))
+  ): ((values: T[]) => S[][]) =>
+    (values: T[]) =>
+      R.splitEvery(chunks, R.map(mapperFn, values))
 );
 
+/** Returns `true` when `index` is at or past the last position (`length - 1`). */
 export const isLast = (index: number, length: number): boolean =>
   index >= length - 1;
 
+/** Returns `true` when `index` is `0` or negative. */
 export const isFirst = (index: number): boolean => index <= 0;
 
+/**
+ * Returns `true` when `index` is a valid zero-based index for a list of the
+ * given `length`. Returns `false` for empty/negative lengths or negative indexes.
+ */
 export const isIndexInRange = (index: number, length: number): boolean => {
   if (length <= 0) return false;
   if (index < 0) return false;
@@ -90,24 +120,29 @@ export const isIndexInRange = (index: number, length: number): boolean => {
   return index + 1 <= length;
 };
 
+/** Builds `[0, 1, ..., size - 1]`. Negative or zero `size` yields `[]`. */
 export const makeListOfIndexes = (size: number): number[] =>
   Array.from({ length: size }, (_, index) => index);
 
+/** Builds an array of the given `size` filled with `value`. */
 export const makeListOf = <T>(value: T, size: number): T[] => {
   return Array(size).fill(value);
 };
 
-/** Checks if a value is a non-empty array */
+/** Checks if a value is a non-empty array. */
 export function isFilledArray(value: unknown): boolean {
   return Array.isArray(value) && value.length > 0;
 }
 
-/** Checks if a value is a empty array */
+/** Checks if a value is an empty array. */
 export function isEmptyArray(value: unknown): boolean {
   return Array.isArray(value) && value.length === 0;
 }
 
-// get random item from the list
+/**
+ * Returns a random item from a non-empty array.
+ * Throws (in development via `invariant`) if the input is not an array or is empty.
+ */
 export const sample = (xs: unknown[]): unknown => {
   invariant(Array.isArray(xs), `input value is not an array: ${xs}`);
   invariant(isFilledArray(xs), `input array is empty: ${xs}`);
@@ -117,7 +152,9 @@ export const sample = (xs: unknown[]): unknown => {
   return xs[index];
 };
 
+/** Returns `true` when `xs` is non-empty and every value is truthy. */
 export const allTruthy = (xs: boolean[]) =>
   isFilledArray(xs) && xs.every(Boolean);
 
+/** Returns `true` when at least one value in `xs` is truthy. */
 export const anyTruthy = (xs: boolean[]) => xs.some(Boolean);

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);
+    });
+  });
+});