zh-web-sdk 1.0.2

package/dist/onboarding/OnboardingApp.d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+interface AppProps {
+    isOnboardingAppActive: boolean;
+    isOnboardingAppLoaded: boolean;
+    userOnboardingJWT: string;
+    zeroHashOnboardingURL: string;
+}
+declare const _default: import("react-redux").ConnectedComponent<({ isOnboardingAppActive, isOnboardingAppLoaded, userOnboardingJWT, zeroHashOnboardingURL }: AppProps) => import("react/jsx-runtime").JSX.Element, {
+    zeroHashOnboardingURL: string;
+    context?: React.Context<import("react-redux").ReactReduxContextValue<any, import("redux").AnyAction>> | undefined;
+    store?: import("redux").Store<any, import("redux").AnyAction> | undefined;
+}>;
+export default _default;

package/dist/onboarding/constants.d.ts

@@ -0,0 +1 @@
+export declare const MESSAGE_TYPE_SEND_JWT_TOKEN: string;

package/dist/redux/actions/index.d.ts

@@ -0,0 +1,8 @@
+export declare const openOnboardingModal: () => {
+    type: string;
+    isOnboardingAppActive: true;
+};
+export declare const closeOnboardingModal: () => {
+    type: string;
+    isOnboardingAppActive: false;
+};

package/dist/redux/reducers/app.d.ts

@@ -0,0 +1,13 @@
+export interface IState {
+    isOnboardingAppActive: boolean;
+    isOnboardingAppLoaded: boolean;
+    userOnboardingJWT: string;
+}
+export interface IAction {
+    type: string;
+    isOnboardingAppActive?: boolean;
+    isOnboardingAppLoaded?: boolean;
+    userOnboardingJWT?: string;
+}
+declare const appReducer: (state: IState | undefined, action: IAction) => IState;
+export default appReducer;

package/dist/redux/reducers/constants.d.ts

@@ -0,0 +1,3 @@
+export declare const ACTION_SET_ONBOARDING_MODAL_STATE = "SET_ONBOARDING_MODAL_STATE";
+export declare const ACTION_SET_USER_ONBOARDING_JWT = "SET_USER_ONBOARDING_JWT";
+export declare const ACTION_ONBOARDING_APP_LOADED = "ONBOARDING_APP_LOADED";

package/dist/redux/reducers/index.d.ts

@@ -0,0 +1,4 @@
+declare const rootReducer: import("redux").Reducer<import("redux").CombinedState<{
+    appState: import("./app").IState;
+}>, import("./app").IAction>;
+export default rootReducer;

package/dist/redux/store/index.d.ts

@@ -0,0 +1,4 @@
+declare const store: import("redux").Store<import("redux").EmptyObject & {
+    appState: import("../reducers/app").IState;
+}, import("../reducers/app").IAction>;
+export default store;

package/dist/styles.d.ts

@@ -0,0 +1,15 @@
+import { CSSProperties } from "react";
+export declare const screenSizes: {
+    id: string;
+    size: number;
+}[];
+export declare const minWidthMatcher: () => string;
+export declare const containerStyle: CSSProperties;
+export declare const containerMediaStyles: {
+    [id: string]: CSSProperties;
+};
+export declare const appWrapperStyle: CSSProperties;
+export declare const appWrapperHiddenStyle: CSSProperties;
+export declare const modalStyle: CSSProperties;
+export declare const iframeWrapperStyle: CSSProperties;
+export declare const iframeStyle: CSSProperties;

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+declare global {
+    interface Window {
+        zerohash: any;
+    }
+}
+/**
+ * IInitializeParameters describes the parameters
+ * required for initializing the platform SDK
+ */
+export interface IInitializeParameters {
+    /**
+     * zeroHashOnboardingURL should be set to the URL of
+     * the webapp for onboarding users onto the ZeroHash
+     * platform.
+     */
+    zeroHashOnboardingURL: string;
+    /**
+     * rootQuerySelector is a query selector string that
+     * allows creating the ZeroHash UI subtree under a
+     * custom element.
+     *
+     * The default #zh-root query selector will be used
+     * instead otherwise. #zh-root will be a <div> appended
+     * as a child of the body in no specified order.
+     */
+    rootQuerySelector?: string;
+    /**
+     * userOnboardingJWT is the JWT that you received from
+     * the ZeroHash HTTP API that pertains to the customer
+     * to be onboarded.
+     *
+     * This is optional in the constructor and can be
+     * deferred to setUserOnboardingJWT() at a later time
+     * but must be provided before opening the onboarding
+     * UI in order for the onboarding UI to be loaded.
+     */
+    userOnboardingJWT?: string;
+}
+/**
+ * ISetUserOnboardingJWTParameters describes the
+ * parameters required for setting the user onboarding
+ * JWT.
+ */
+export interface ISetUserOnboardingJWTParameters {
+    /**
+     * userOnboardingJWT is the JWT that you received from
+     * the ZeroHash HTTP API that pertains to the customer
+     * to be onboarded.
+     */
+    userOnboardingJWT: string;
+}
+export interface IOpenOnboardingModalParameters {
+    /**
+     * userOnboardingJWT is the JWT that you received from
+     * the ZeroHash HTTP API that pertains to the customer
+     * to be onboarded.
+     */
+    userOnboardingJWT?: string;
+}
+/**
+ * IncomingMessageType are enums of message types that
+ * are registered that the host can handle.
+ */
+export declare enum IncomingMessageType {
+    /**
+     * OnboardingAppLoaded is received when the onboarding
+     * app has initialized.
+     */
+    OnboardingAppLoaded = "ONBOARDING_APP_LOADED",
+    /**
+     * OnboardingCloseButtonClicked is received when the close button
+     * has been clicked in the onboarding app
+     */
+    OnboardingCloseButtonClicked = "ONBOARDING_CLOSE_BUTTON_CLICKED"
+}
+/**
+ * IncomingMessage defines the structure of an incoming
+ * message
+ */
+export interface IncomingMessage {
+    /**
+     * type is the type of message that is used for routing
+     * the request to the appropriate handler
+     */
+    type: IncomingMessageType;
+    /**
+     * payload is any freeform value that pertains to the
+     * request
+     */
+    payload: unknown;
+}
+export type IncomingMessageHandler = (payload: unknown) => void;
+/**
+ * IZeroHashSDK is the interface that you may use to interact with the ZeroHash SDK.
+ */
+export interface IZeroHashSDK {
+    setUserOnboardingJWT(params: ISetUserOnboardingJWTParameters): void;
+    isOnboardingModalOpen(): boolean;
+    openOnboardingModal(params: IOpenOnboardingModalParameters): void;
+    closeOnboardingModal(): void;
+}

package/dist/utils/strings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * randomString generates a random string of specified
+ * @param length
+ * @param characters - charset to be used.
+ */
+export declare const randomString: (length: number, characters?: string) => string;

package/dist/utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * generateRootID attempts to create a dynamic ID to be
+ * used with a HTML element that is relatively unique
+ * and will not cause namespace conflicts.
+ *
+ * E.g. 'zerohash-49vt8y'
+ */
+export declare const generateRootID: () => string;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "zh-web-sdk",
+  "version": "1.0.2",
+  "private": false,
+  "description": "ZeroHash Web SDK",
+  "homepage": "https://github.com/seedcx/zh-web-sdk",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [],
+  "author": "support@zerohash.com",
+  "license": "MIT",
+  "scripts": {
+    "prepublish": "npm run build",
+    "ts-types": "tsc --emitDeclarationOnly --outDir dist",
+    "build": "rimraf dist && node ./scripts/build.js && npm run ts-types",
+    "build:zip": "npm run build && npm run zip",
+    "zip": "rimraf build/* && node scripts/zip.js",
+    "lint": "eslint src --ext ts,tsx --report-unused-disable-directives --max-warnings 0",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^6.4.0",
+    "archiver": "^5.3.1",
+    "esbuild": "0.18.3",
+    "eslint": "^8.47.0",
+    "eslint-config-prettier": "6.15.0",
+    "eslint-config-standard": "^17.1.0",
+    "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-n": "^16.0.1",
+    "eslint-plugin-prettier": "3.4.1",
+    "eslint-plugin-promise": "^6.1.1",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "eslint-plugin-react-refresh": "^0.3.4",
+    "rimraf": "^5.0.1",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "@types/react": "^18.2.12",
+    "@types/react-dom": "^18.2.5",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "react-redux": "^8.1.1",
+    "redux": "^4.2.1"
+  }
+}

package/scripts/build.js

@@ -0,0 +1,34 @@
+const esbuild = require("esbuild");
+const {name, version} = require("../package.json");
+
+const build = async () => {
+    console.log(`Building ${name}@${version}`);
+
+    const outputDir = "./dist/";
+    const minFileName = `${outputDir}zerohash_sdk.min.js`;
+    const bundleFileName = `${outputDir}zerohash_sdk.js`;
+
+    // Build minified dist
+    await esbuild
+        .build({
+            entryPoints: ['src/index.tsx'],
+            outdir: 'dist',
+            bundle: true,
+            sourcemap: true,
+            minify: true,
+            splitting: false,
+            format: 'esm',
+            target: ['esnext']
+        })
+        .catch(err => {
+            console.error('Error: build failed - unable to build minified dist');
+            throw err;
+        });
+}
+
+build()
+    .then(() => console.log("successfully built"))
+    .catch(err => {
+        console.error(err);
+        process.exit(1);
+    });

package/scripts/zip.js

@@ -0,0 +1,49 @@
+const fs = require("fs");
+const archiver = require("archiver");
+const {name, version} = require("../package.json");
+
+const zip = async () => {
+    const zipFile = `./build/zh_web_sdk_v${version}.zip`;
+    console.log(`Zipping to ${zipFile}`);
+
+    // create the directory forcibly
+    fs.mkdirSync("./build", {recursive: true});
+
+    // zip output as a package
+    const output = fs.createWriteStream(zipFile);
+    const archive = archiver('zip', {
+        zlib: { level: 9 }
+    });
+    output.on('close', () => {
+        console.log(archive.pointer() + ' total bytes');
+        console.log('archiver has been finalized and the output file descriptor has closed.');
+    });
+    output.on('end', () => {
+        console.log('Data has been drained');
+    });
+    archive.on('warning', (err) => {
+        if (err.code === "ENOENT") {
+            console.warn("ENOENT: ", err);
+        } else {
+            console.error(err);
+            throw err;
+        }
+    });
+    archive.on('error', (err) => {
+        console.error(err);
+        throw err;
+    });
+    archive.pipe(output);
+    archive.file("README.md");
+    archive.file("package.json");
+    archive.file("package-lock.json");
+    archive.directory("./dist/");
+    await archive.finalize();
+}
+
+zip()
+    .then(() => console.log("successfully zipped"))
+    .catch(err => {
+        console.error(err);
+        process.exit(1);
+    });

package/src/constants.ts

@@ -0,0 +1,2 @@
+export const DEFAULT_ZH_ONBOARDING_URL = "https://onboarding.zerohash.com/";
+export const DEFAULT_ROOT_ID_PREFIX = "zerohash"

package/src/index.tsx

@@ -0,0 +1,197 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import {
+    IInitializeParameters,
+    IncomingMessage,
+    IncomingMessageHandler,
+    IncomingMessageType, IOpenOnboardingModalParameters,
+    ISetUserOnboardingJWTParameters, IZeroHashSDK
+} from './types';
+import {generateRootID} from "./utils";
+import {DEFAULT_ZH_ONBOARDING_URL} from "./constants";
+import OnboardingApp from "./onboarding/OnboardingApp";
+import {Provider} from "react-redux";
+import store from "./redux/store";
+import {
+    ACTION_ONBOARDING_APP_LOADED,
+    ACTION_SET_USER_ONBOARDING_JWT
+} from "./redux/reducers/constants";
+import {closeOnboardingModal, openOnboardingModal} from "./redux/actions";
+
+let _zeroHashOnboardingURL: string = DEFAULT_ZH_ONBOARDING_URL;
+let _zeroHashOnboardingOrigin: string = "";
+
+/**
+ * onboardingMessageHandlers are the message handlers that
+ * handle incoming messages from the onboarding app iframe.
+ * @private - not meant to be invoked publicly
+ */
+const onboardingMessageHandlers: { [messageType in IncomingMessageType]: IncomingMessageHandler } = {
+    [IncomingMessageType.OnboardingAppLoaded]: () => {
+        store.dispatch({
+            type: ACTION_ONBOARDING_APP_LOADED,
+            isOnboardingAppLoaded: true,
+        });
+    },
+    [IncomingMessageType.OnboardingCloseButtonClicked]: () => {
+        closeOnboardingModal();
+    }
+}
+
+/**
+ * messageRouter routes the message to the appropriate message handler based on the host
+ * @private - not meant to be invoked publicly
+ */
+const messageRouter = (event: MessageEvent): void => {
+    if (event.origin === _zeroHashOnboardingOrigin) {
+        const incomingMessage: IncomingMessage = event.data;
+        if (incomingMessage && incomingMessage.type && onboardingMessageHandlers[incomingMessage.type]) {
+            try {
+                onboardingMessageHandlers[incomingMessage.type](incomingMessage.payload);
+            } catch (e) {
+                console.error(e);
+                // TODO: emit event that informs the platform of failure event, to inform ZH of bug
+            }
+        }
+    }
+}
+
+export class ZeroHashSDK implements IZeroHashSDK {
+    private rootQuerySelector: string = "";
+    private onboardingInitialized: boolean = false;
+
+    /**
+     * Sets up the ZeroHash SDK and appends the ZeroHash DOM elements onto the page.
+     *
+     * For more information, see {@code IInitializeParameters}
+     */
+    constructor(
+        {
+            zeroHashOnboardingURL = DEFAULT_ZH_ONBOARDING_URL,
+            rootQuerySelector,
+            userOnboardingJWT
+        }: IInitializeParameters
+    ) {
+        _zeroHashOnboardingURL = zeroHashOnboardingURL
+        const onboardingURL = new URL(_zeroHashOnboardingURL);
+        _zeroHashOnboardingOrigin = onboardingURL.origin;
+        if (rootQuerySelector) {
+            this.rootQuerySelector = rootQuerySelector as string
+        }
+
+        // register message handler
+        window.addEventListener(
+            "message",
+            messageRouter,
+            false
+        )
+
+        if (userOnboardingJWT) {
+            this.setUserOnboardingJWT({
+                userOnboardingJWT,
+            });
+        }
+    }
+
+    /**
+     * setUserOnboardingJWT sets the JWT to be whatever value is provided.
+     * The JWT should be the UserJWT provided by ZeroHash via the platform
+     * API proxied through your servers. As ZeroHash cannot authenticate
+     * your users' requests, it is paramount that the user be authenticated
+     * and validated on your servers, and exchanged for the JWT using your
+     * API key. DO NOT have the JWT exchange logic be on your front-end.
+     *
+     * As a precaution, we may restrict traffic to the JWT exchange API to
+     * whitelisted IPs that come from your server.
+     */
+    setUserOnboardingJWT(params: ISetUserOnboardingJWTParameters): void {
+        store.dispatch({
+            type: ACTION_SET_USER_ONBOARDING_JWT,
+            userOnboardingJWT: params.userOnboardingJWT,
+        });
+    }
+
+    /**
+     * isOnboardingModalOpen returns true if the onboarding modal is open,
+     * false otherwise
+     */
+    isOnboardingModalOpen(): boolean {
+        return store.getState().appState.isOnboardingAppActive
+    }
+
+    /**
+     * openOnboardingModal opens the onboarding modal
+     */
+    openOnboardingModal(params: IOpenOnboardingModalParameters): void {
+        if (params.userOnboardingJWT) {
+            this.setUserOnboardingJWT({
+                userOnboardingJWT: params.userOnboardingJWT,
+            });
+        }
+        openOnboardingModal();
+        if (this.onboardingInitialized) {
+            // if it was previously initialized already,
+            // simply open the modal, do not re-inject.
+            return
+        }
+
+        let root: HTMLElement | null = null;
+        if (this.rootQuerySelector) {
+            root = document.querySelector(this.rootQuerySelector);
+        }
+
+        if (!root) {
+            // Create the default ZeroHash div, e.g. <div id="zerohash-49vt8y"/>
+            root = document.createElement("div");
+            const rootID = generateRootID();
+            root.id = rootID;
+            root.style.position = "absolute";
+            root.style.top = "0";
+            root.style.left = "0";
+            this.rootQuerySelector = `#${rootID}`;
+
+            // Append the ZeroHash div as a child of <body>
+            const destinationBox = document.querySelector("body") as HTMLBodyElement;
+            destinationBox.appendChild(root);
+        }
+
+        if (root) {
+            // Create a shadow wrapper around ZeroHash app for encapsulation
+            const shadowRoot = root.attachShadow({mode: 'closed'});
+
+            // Render the React modal
+            ReactDOM
+                .createRoot(shadowRoot)
+                .render(
+                    <Provider store={store}>
+                        <OnboardingApp
+                            zeroHashOnboardingURL={_zeroHashOnboardingURL}
+                        />
+                    </Provider>
+                )
+
+            // set as initialized
+            this.onboardingInitialized = true;
+        } else {
+            const errMsg = "failed to append ZeroHash root to the page: root not found";
+            console.error(errMsg);
+            throw new Error(errMsg)
+        }
+    }
+
+    /**
+     * closeOnboardingModalModal hides the onboarding modal
+     */
+    closeOnboardingModal(): void {
+        closeOnboardingModal();
+    }
+}
+
+if (window) {
+    // if the window object exists, the ZeroHash SDK
+    // constructor will be appended to it for easier
+    // access.
+    window.zerohash = ZeroHashSDK;
+}
+
+export default ZeroHashSDK;

package/src/onboarding/OnboardingApp.tsx

@@ -0,0 +1,128 @@
+import React, {useEffect, useRef, useState} from "react";
+import {
+    appWrapperStyle,
+    containerMediaStyles,
+    containerStyle,
+    iframeStyle,
+    iframeWrapperStyle,
+    minWidthMatcher,
+    modalStyle,
+    screenSizes,
+    appWrapperHiddenStyle
+} from "../styles";
+import {connect} from "react-redux";
+import {MESSAGE_TYPE_SEND_JWT_TOKEN} from "./constants";
+import {closeOnboardingModal} from "../redux/actions";
+
+interface AppProps {
+    isOnboardingAppActive: boolean
+    isOnboardingAppLoaded: boolean
+    userOnboardingJWT: string
+    zeroHashOnboardingURL: string
+}
+
+const appLoadTime = Date.now();
+
+// eslint-disable-next-line react-refresh/only-export-components
+const OnboardingApp = (
+    {
+        isOnboardingAppActive,
+        isOnboardingAppLoaded,
+        userOnboardingJWT,
+        zeroHashOnboardingURL
+    }: AppProps
+) => {
+    const [container, setContainerStyle] = useState(containerStyle);
+
+    /**
+     * setContainer sets the CSS styles based on the current matching media queries
+     */
+    const setContainer = () => {
+        const sizeId = minWidthMatcher();
+        const containerMediaStyle = containerMediaStyles[sizeId]
+        setContainerStyle({
+            ...containerStyle,
+            ...containerMediaStyle,
+        });
+    }
+
+    const iRef: React.MutableRefObject<HTMLIFrameElement | null> = useRef<HTMLIFrameElement | null>(null);
+    useEffect(() => {
+        // Send JWT to iframe when all 3 props are ready
+        if (zeroHashOnboardingURL && isOnboardingAppLoaded && userOnboardingJWT && iRef.current?.contentWindow) {
+            iRef.current.contentWindow.postMessage({
+                type: MESSAGE_TYPE_SEND_JWT_TOKEN,
+                userOnboardingJWT: userOnboardingJWT,
+            }, zeroHashOnboardingURL);
+        }
+    }, [isOnboardingAppLoaded, userOnboardingJWT, zeroHashOnboardingURL])
+
+    useEffect(() => {
+        // set the styles when the screen size changes
+        setContainer();
+        if (window) {
+            screenSizes.forEach(({size}) => {
+                window
+                    .matchMedia(`(min-width: ${size}px)`)
+                    .addEventListener('change', setContainer)
+            })
+            return () => screenSizes.forEach(({size}) => {
+                window
+                    .matchMedia(`(min-width: ${size}px)`)
+                    .removeEventListener('change', setContainer)
+            })
+        }
+    }, []);
+
+    const iframeURL = new URL(zeroHashOnboardingURL);
+    iframeURL.searchParams.set(
+        'name',
+        appLoadTime.toString(),
+    )
+    if (window) {
+        iframeURL.searchParams.set(
+            'origin',
+            window.location.origin,
+        );
+    }
+
+    return <div
+        style={isOnboardingAppActive ? appWrapperStyle : appWrapperHiddenStyle}
+        onClick={closeOnboardingModal}
+    >
+        <div
+            style={{
+                ...modalStyle,
+                ...container,
+            }}
+        >
+            <div
+                style={{
+                    ...iframeWrapperStyle,
+                }}
+            >
+                <iframe
+                    ref={iRef}
+                    title="Zerohash Onboarding"
+                    src={iframeURL.toString()}
+                    style={iframeStyle}
+                />
+            </div>
+        </div>
+    </div>;
+}
+
+const mapStateToProps = (state: {
+    appState: {
+        isOnboardingAppActive: boolean,
+        isOnboardingAppLoaded: boolean,
+        userOnboardingJWT: string,
+    };
+}) => ({
+    isOnboardingAppActive: state.appState.isOnboardingAppActive,
+    isOnboardingAppLoaded: state.appState.isOnboardingAppLoaded,
+    userOnboardingJWT: state.appState.userOnboardingJWT,
+});
+
+// eslint-disable-next-line react-refresh/only-export-components
+export default connect(mapStateToProps)(OnboardingApp);

package/src/onboarding/constants.ts

@@ -0,0 +1,2 @@
+const ONBOARDING_MESSAGE_TYPE_PREFIX = "ONBOARDING_"
+export const MESSAGE_TYPE_SEND_JWT_TOKEN = ONBOARDING_MESSAGE_TYPE_PREFIX + "SEND_JWT_TOKEN"

package/src/redux/actions/index.ts

@@ -0,0 +1,12 @@
+import store from "../store";
+import {ACTION_SET_ONBOARDING_MODAL_STATE} from "../reducers/constants";
+
+export const openOnboardingModal = () => store.dispatch({
+    type: ACTION_SET_ONBOARDING_MODAL_STATE,
+    isOnboardingAppActive: true,
+});
+
+export const closeOnboardingModal = () => store.dispatch({
+    type: ACTION_SET_ONBOARDING_MODAL_STATE,
+    isOnboardingAppActive: false,
+});