@evervault/react-native 2.6.0 → 2.6.2

package/src/ThreeDSecure/types.ts

@@ -0,0 +1,80 @@
+import { ThreeDSecureEvent } from "./event";
+
+export interface ThreeDSecureCallbacks {
+  /**
+   * The error event will be fired if the component fails to load.
+   */
+  onError?(error: Error): void;
+
+  /**
+   * The 'requestChallenge' event will be fired if the 3DS authentication process requires a challenge.
+   * If you'd like to fail the authentication, you should call `preventDefault` on the passed event.
+   */
+  onRequestChallenge?(event: ThreeDSecureEvent): void;
+
+  /**
+   * The 'failure' event will be fired if the 3DS authentication process fails. You should use this event to handle the failure and inform the user and prompt them to try again.
+   * If the user cancels the 3DS authentication process this event will be fired.
+   */
+  onFailure?(error: Error): void;
+
+  /**
+   * The 'success' event will be fired once the 3DS authentication process has been completed successfully.
+   * You should use this event to trigger your backend to finalize the payment.
+   * Your backend can use the [Retrieve 3DS Session](https://docs.evervault.com/api-reference#retrieveThreeDSSession) endpoint to retrieve the cryptogram for the session and complete the payment.
+   */
+  onSuccess?(): void;
+}
+
+export interface ThreeDSecureOptions extends ThreeDSecureCallbacks {
+  /**
+   * If set to `true` (or a function that returns `true`), the authentication will fail if a challenge is required.
+   */
+  failOnChallenge?: boolean | (() => Promise<boolean>);
+}
+
+export interface ThreeDSecureInitialState {
+  session: ThreeDSecureSession | null;
+  isVisible: boolean;
+}
+
+export interface ThreeDSecureSession {
+  cancel(): Promise<void>;
+  get(): Promise<ThreeDSecureSessionResponse>;
+  sessionId: string;
+}
+
+export type SessionStatus = "action-required" | "failure" | "success";
+
+export interface ThreeDSecureSessionResponse {
+  nextAction: {
+    creq?: string;
+    type: string;
+    url?: string;
+  };
+  status: SessionStatus;
+}
+
+export interface ThreeDSecureSessionsParams {
+  appId: string;
+  options?: ThreeDSecureOptions;
+  intervalRef: React.MutableRefObject<NodeJS.Timeout | null>;
+  sessionId: string;
+  setIsVisible: (show: boolean) => void;
+}
+
+export interface ThreeDSecureState extends ThreeDSecureInitialState {
+  /**
+   * The `cancel()` function is used to cancel the ongoing 3DS authentication process.
+   * This can be particularly useful for canceling a session when a custom cancel button is triggered.
+   */
+  cancel(): Promise<void>;
+
+  /**
+   * The `start()` function is used to kick off the 3DS authentication process.
+   *
+   * @param sessionId The 3DS session ID. A 3DS session can be created using the [Evervault API](https://docs.evervault.com/api-reference#createThreeDSSession).
+   * @param options The options to be used for the 3DS authentication process.
+   */
+  start(sessionId: string, options?: ThreeDSecureOptions): void;
+}

package/src/ThreeDSecure/useThreeDSecure.test.tsx

@@ -0,0 +1,244 @@
+import { PropsWithChildren } from "react";
+import { EvervaultProvider } from "../EvervaultProvider";
+import { act, renderHook } from "@testing-library/react-native";
+import { useThreeDSecure } from "./useThreeDSecure";
+import { ThreeDSecureEvent } from "./event";
+
+function wrapper({ children }: PropsWithChildren) {
+  return (
+    <EvervaultProvider teamId="team_123" appId="app_123">
+      {children}
+    </EvervaultProvider>
+  );
+}
+
+const callbacks = {
+  onSuccess: vi.fn(),
+  onError: vi.fn(),
+  onFailure: vi.fn(),
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+it("returns the correct state", () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  expect(result.current).toEqual({
+    start: expect.any(Function),
+    cancel: expect.any(Function),
+    session: null,
+    isVisible: false,
+  });
+});
+
+it("starts a session when action is required", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  await act(() => result.current.start("session_123", callbacks));
+
+  expect(result.current.session).toEqual({
+    sessionId: "session_123",
+    cancel: expect.any(Function),
+    get: expect.any(Function),
+  });
+  expect(result.current.isVisible).toBe(true);
+});
+
+it("fails the session when failOnChallenge is true and a challenge is required", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  const onRequestChallenge = vi.fn();
+
+  await act(() =>
+    result.current.start("session_123", {
+      ...callbacks,
+      onRequestChallenge,
+      failOnChallenge: true,
+    })
+  );
+
+  expect(callbacks.onFailure).toHaveBeenCalled();
+  expect(onRequestChallenge).not.toHaveBeenCalled();
+});
+
+it("fails the session when failOnChallenge is a function that returns true and a challenge is required", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  const onRequestChallenge = vi.fn();
+
+  await act(() =>
+    result.current.start("session_123", {
+      ...callbacks,
+      onRequestChallenge,
+      failOnChallenge: () => Promise.resolve(true),
+    })
+  );
+
+  expect(callbacks.onFailure).toHaveBeenCalled();
+  expect(onRequestChallenge).not.toHaveBeenCalled();
+});
+
+it("fails the session when failOnChallenge resolves true at hook level and a challenge is required", async () => {
+  const { result } = renderHook(
+    () =>
+      useThreeDSecure({
+        failOnChallenge: () => Promise.resolve(true),
+      }),
+    {
+      wrapper,
+    }
+  );
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  const onRequestChallenge = vi.fn();
+  await act(() =>
+    result.current.start("session_123", {
+      ...callbacks,
+      onRequestChallenge,
+    })
+  );
+
+  expect(onRequestChallenge).not.toHaveBeenCalled();
+  expect(callbacks.onFailure).toHaveBeenCalled();
+});
+
+it("fails the session when onRequestChallenge is called and defaultPrevented is true", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  let onRequestChallenge = vi.fn((event: ThreeDSecureEvent) =>
+    event.preventDefault()
+  );
+  await act(() =>
+    result.current.start("session_123", {
+      ...callbacks,
+      onRequestChallenge,
+    })
+  );
+  expect(onRequestChallenge).toHaveBeenCalled();
+  expect(callbacks.onFailure).toHaveBeenCalled();
+
+  let onFailure = vi.fn();
+  onRequestChallenge = vi.fn();
+  await act(() =>
+    result.current.start("session_123", {
+      onFailure,
+      onRequestChallenge,
+    })
+  );
+  expect(onRequestChallenge).toHaveBeenCalled();
+  expect(onFailure).not.toHaveBeenCalled();
+});
+
+it("calls the success callback when the session is successful", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "success" }),
+  } as any);
+
+  await act(() => result.current.start("session_123", callbacks));
+
+  expect(callbacks.onSuccess).toHaveBeenCalled();
+});
+
+it("calls the failure callback when the session fails on start", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "failure" }),
+  } as any);
+
+  await act(() => result.current.start("session_123", callbacks));
+
+  expect(callbacks.onFailure).toHaveBeenCalled();
+});
+
+it("calls the error callback when the fetch fails on start", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockRejectedValue(new Error("Session failed"));
+
+  await act(() => result.current.start("session_123", callbacks));
+
+  expect(callbacks.onError).toHaveBeenCalled();
+});
+
+it("silently fails if the session is not found", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  const consoleWarnSpy = vi.spyOn(console, "warn");
+
+  await act(() => result.current.cancel());
+
+  expect(result.current.session).toBeNull();
+  expect(result.current.isVisible).toBe(false);
+  expect(consoleWarnSpy).toHaveBeenCalledWith("No 3DS session to cancel");
+});
+
+it("cancels the session when the user cancels", async () => {
+  const { result } = renderHook(() => useThreeDSecure(), {
+    wrapper,
+  });
+
+  vi.spyOn(global, "fetch").mockResolvedValue({
+    json: () => Promise.resolve({ status: "action-required" }),
+  } as any);
+
+  await act(() => result.current.start("session_123", callbacks));
+
+  expect(result.current.session).toEqual({
+    sessionId: "session_123",
+    cancel: expect.any(Function),
+    get: expect.any(Function),
+  });
+  expect(result.current.isVisible).toBe(true);
+
+  await act(() => result.current.session?.cancel());
+
+  expect(result.current.session).toEqual({
+    sessionId: "session_123",
+    cancel: expect.any(Function),
+    get: expect.any(Function),
+  });
+  expect(result.current.isVisible).toBe(false);
+  expect(callbacks.onFailure).toHaveBeenCalled();
+});

package/src/ThreeDSecure/useThreeDSecure.ts

@@ -0,0 +1,64 @@
+import { useCallback, useMemo, useState } from "react";
+import { useRef } from "react";
+import { startSession, threeDSecureSession } from "./session";
+import {
+  ThreeDSecureOptions,
+  ThreeDSecureSession,
+  ThreeDSecureState,
+} from "./types";
+import { useEvervault } from "../useEvervault";
+
+export interface UseThreeDSecureOptions {
+  failOnChallenge?: boolean | (() => Promise<boolean>);
+}
+
+export function useThreeDSecure(
+  options?: UseThreeDSecureOptions
+): ThreeDSecureState {
+  const { appId } = useEvervault();
+  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+  const [session, setSession] = useState<ThreeDSecureSession | null>(null);
+  const [isVisible, setIsVisible] = useState(false);
+
+  const failOnChallenge = options?.failOnChallenge ?? false;
+
+  const start = useCallback<ThreeDSecureState["start"]>(
+    (sessionId, options) => {
+      const startOptions: ThreeDSecureOptions = {
+        ...options,
+        failOnChallenge: options?.failOnChallenge ?? failOnChallenge,
+      };
+
+      const session = threeDSecureSession({
+        sessionId,
+        appId,
+        options: startOptions,
+        intervalRef,
+        setIsVisible,
+      });
+
+      setSession(session);
+
+      startSession(session, startOptions, intervalRef, setIsVisible);
+    },
+    [appId, failOnChallenge]
+  );
+
+  const cancel = useCallback<ThreeDSecureState["cancel"]>(async () => {
+    if (session) {
+      await session.cancel();
+    } else {
+      console.warn("No 3DS session to cancel");
+    }
+  }, [session]);
+
+  return useMemo(
+    () => ({
+      start,
+      cancel,
+      session,
+      isVisible,
+    }),
+    [start, cancel, session, isVisible]
+  );
+}

package/src/__mocks__/NativeEvervault.ts

@@ -0,0 +1,13 @@
+import type { Spec } from "../specs/NativeEvervault";
+
+export const encryptedValue =
+  "ev:W98t:uu98aas09udya863ty9372y7y23h97rg6gfs678987";
+
+export const NativeEvervault: Spec = {
+  initialize: vi.fn(),
+  encryptString: vi.fn(() => Promise.resolve(encryptedValue)),
+  encryptNumber: vi.fn(() => Promise.resolve(encryptedValue)),
+  encryptBoolean: vi.fn(() => Promise.resolve(encryptedValue)),
+  encryptObject: vi.fn(),
+  encryptArray: vi.fn(),
+};

package/src/__mocks__/react-native-webview.tsx

@@ -0,0 +1,6 @@
+import { View } from "react-native";
+import type { WebViewProps } from "react-native-webview";
+
+export function WebView(props: WebViewProps) {
+  return <View testID="webview" {...props} />;
+}

package/src/context.ts

@@ -0,0 +1,14 @@
+import { createContext } from "react";
+import type { Encrypted } from "./sdk";
+
+export type EncryptFn = <T>(data: T) => Promise<Encrypted<T>>;
+
+export interface EvervaultContextValue {
+  teamId: string;
+  appId: string;
+  encrypt: EncryptFn;
+}
+
+export const EvervaultContext = createContext<EvervaultContextValue | null>(
+  null
+);

package/src/index.ts

@@ -0,0 +1,21 @@
+import { sdk } from "./sdk";
+
+export const verifyInstallation = sdk.verify;
+
+export type { Encrypted } from "./sdk";
+
+export {
+  EvervaultProvider,
+  type EvervaultProviderProps,
+} from "./EvervaultProvider";
+
+export type { EncryptFn } from "./context";
+export { useEvervault } from "./useEvervault";
+
+export type {
+  EvervaultInput,
+  BaseEvervaultInputProps as EvervaultInputProps,
+} from "./Input";
+
+export * from "./Card";
+export * from "./ThreeDSecure";

package/src/sdk.test.ts

@@ -0,0 +1,122 @@
+import { NativeEvervault } from "./__mocks__/NativeEvervault";
+import { sdk } from "./sdk";
+
+describe("sdk", () => {
+  describe("verify", () => {
+    it("should return true", () => {
+      expect(sdk.verify()).toBe(true);
+    });
+  });
+
+  describe("initialize", () => {
+    it("throws an error if teamId is not provided", () => {
+      expect(() => sdk.initialize("", "appId")).toThrow("Team ID is required.");
+    });
+
+    it("throws an error if appId is not provided", () => {
+      expect(() => sdk.initialize("teamId", "")).toThrow("App ID is required.");
+    });
+
+    it("initializes the sdk", () => {
+      sdk.initialize("teamId", "appId");
+      expect(NativeEvervault.initialize).toHaveBeenCalledWith(
+        "teamId",
+        "appId"
+      );
+    });
+  });
+
+  describe("encrypt", () => {
+    it("encrypts an undefined value", async () => {
+      const result = await sdk.encrypt("instanceId", undefined);
+      expect(result).toBe(undefined);
+      expect(NativeEvervault.encryptString).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptNumber).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptBoolean).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptObject).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptArray).not.toHaveBeenCalled();
+    });
+
+    it("encrypts a null value", async () => {
+      const result = await sdk.encrypt("instanceId", null);
+      expect(result).toBe(null);
+      expect(NativeEvervault.encryptString).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptNumber).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptBoolean).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptObject).not.toHaveBeenCalled();
+      expect(NativeEvervault.encryptArray).not.toHaveBeenCalled();
+    });
+
+    it("encrypts a string", async () => {
+      await sdk.encrypt("instanceId", "hello");
+      expect(NativeEvervault.encryptString).toHaveBeenCalledWith(
+        "instanceId",
+        "hello"
+      );
+      assertType<Promise<string>>(sdk.encrypt("instanceId", "hello"));
+    });
+
+    it("encrypts a number", async () => {
+      await sdk.encrypt("instanceId", 123);
+      expect(NativeEvervault.encryptNumber).toHaveBeenCalledWith(
+        "instanceId",
+        123
+      );
+      assertType<Promise<string>>(sdk.encrypt("instanceId", 123));
+    });
+
+    it("encrypts a boolean", async () => {
+      await sdk.encrypt("instanceId", true);
+      expect(NativeEvervault.encryptBoolean).toHaveBeenCalledWith(
+        "instanceId",
+        true
+      );
+      assertType<Promise<string>>(sdk.encrypt("instanceId", true));
+    });
+
+    it("encrypts an object", async () => {
+      await sdk.encrypt("instanceId", { a: 1, b: 2 });
+      expect(NativeEvervault.encryptObject).toHaveBeenCalledWith("instanceId", {
+        a: 1,
+        b: 2,
+      });
+      assertType<Promise<{ a: string; b: string }>>(
+        sdk.encrypt("instanceId", { a: 1, b: 2 })
+      );
+    });
+
+    it("encrypts a deep object", async () => {
+      await sdk.encrypt("instanceId", { a: 1, b: { c: 2, d: 3 } });
+      expect(NativeEvervault.encryptObject).toHaveBeenCalledWith("instanceId", {
+        a: 1,
+        b: { c: 2, d: 3 },
+      });
+      assertType<Promise<{ a: string; b: { c: string; d: string } }>>(
+        sdk.encrypt("instanceId", { a: 1, b: { c: 2, d: 3 } })
+      );
+    });
+
+    it("encrypts an array", async () => {
+      await sdk.encrypt("instanceId", [1, 2, 3]);
+      expect(NativeEvervault.encryptArray).toHaveBeenCalledWith(
+        "instanceId",
+        [1, 2, 3]
+      );
+      assertType<Promise<Array<string>>>(sdk.encrypt("instanceId", [1, 2, 3]));
+    });
+
+    it("throws an error if the data is not supported", async () => {
+      const fn = () => {};
+      await expect(() => sdk.encrypt("instanceId", fn)).rejects.toThrow(
+        "Unsupported data type."
+      );
+      assertType<() => Promise<never>>(() => sdk.encrypt("instanceId", fn));
+
+      const symbol = Symbol("test");
+      await expect(() => sdk.encrypt("instanceId", symbol)).rejects.toThrow(
+        "Unsupported data type."
+      );
+      assertType<() => Promise<never>>(() => sdk.encrypt("instanceId", symbol));
+    });
+  });
+});

package/src/sdk.ts

@@ -0,0 +1,71 @@
+import {
+  NativeEvervault,
+  Spec as NativeEvervaultSpec,
+} from "./specs/NativeEvervault";
+
+export type Encrypted<T> = T extends undefined
+  ? undefined
+  : T extends null
+  ? null
+  : T extends string | number | boolean
+  ? string
+  : T extends Function
+  ? never
+  : T extends object
+  ? {
+      [K in keyof T]: Encrypted<T[K]>;
+    }
+  : T extends Array<infer U>
+  ? Array<Encrypted<U>>
+  : never;
+
+function getModule(): NativeEvervaultSpec {
+  if (!NativeEvervault) {
+    throw new Error("NativeEvervault is not available.");
+  }
+
+  return NativeEvervault;
+}
+
+export const sdk = {
+  verify() {
+    getModule();
+    return true;
+  },
+
+  initialize(teamId: string, appId: string): string {
+    const evervault = getModule();
+
+    if (!teamId) {
+      throw new Error("Team ID is required.");
+    }
+
+    if (!appId) {
+      throw new Error("App ID is required.");
+    }
+
+    return evervault.initialize(teamId, appId);
+  },
+
+  async encrypt<T>(instanceId: string, data: T): Promise<Encrypted<T>> {
+    const evervault = getModule();
+
+    if (data === undefined) {
+      return undefined as any;
+    } else if (data === null) {
+      return null as any;
+    } else if (typeof data === "string") {
+      return (await evervault.encryptString(instanceId, data)) as any;
+    } else if (typeof data === "number") {
+      return (await evervault.encryptNumber(instanceId, data)) as any;
+    } else if (typeof data === "boolean") {
+      return (await evervault.encryptBoolean(instanceId, data)) as any;
+    } else if (Array.isArray(data)) {
+      return (await evervault.encryptArray(instanceId, data)) as any;
+    } else if (typeof data === "object") {
+      return (await evervault.encryptObject(instanceId, data)) as any;
+    }
+
+    throw new Error("Unsupported data type.");
+  },
+};