zh-web-sdk 2.5.0 → 2.5.2

package/README.md

@@ -1,310 +1,53 @@
 # ZeroHash Platform SDK
 
-This SDK exposes functionality that allows platforms to integrate with ZeroHash on the web.
-You should be able to access different UI flows, such as Onboarding and Crypto Withdrawals
-using a single instance of `ZeroHashSDK`.
+This SDK (Software development Kit) exposes functionality that allows platforms to integrate with ZeroHash on the web and mobile. You should be able to access different UI flows, such as Crypto Buy, Crypto Sell, Crypto Withdrawals, Fiat Deposits, Fiat Withdrawals and Onboarding using a single instance of ZeroHashSDK.
 
-## Migrating from 1.x.x to 2.x.x
-On SDK v2 we added some new methods that will replace the ones marked with deprecated
-on future releases, if you update our SDK to v2 but don't do the below changes,
-your App should still work fine as we ensured everything is backwards compatible, but 
-we recommend that when updating to v2 you follow the steps below to ensure your App
-is kept up to date with our SDK.
-### Instantiating the SDK
-- `zeroHashOnboardingURL` was renamed to `zeroHashAppsURL`. Please replace `zeroHashOnboardingURL` with `zeroHashAppsURL`.
 ### SDK Methods
+
 ```javascript
 import { AppIdentifier } from 'zh-web-sdk'
 
-// openOnboardingModal replacement
-sdk.openOnboardingModal({userOnboardingJWT: jwt}) // Deprecated method
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING, jwt: jwt}) // New method
-sdk.openOnboardingModal({}) // Deprecated method
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING}) // New method
+sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING, jwt: jwt})
+sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING})
 
-// closeOnboardingModal replacement
-sdk.closeOnboardingModal() // Deprecated method
-sdk.closeModal(AppIdentifier.ONBOARDING) // New method
+sdk.closeModal(AppIdentifier.ONBOARDING)
 
-// setUserOnboardingJWT replacement
-sdk.setUserOnboardingJWT({ userOnboardingJWT: jwt }) // Deprecated method
-sdk.setJWT({ jwt: jwt, appIdentifier: AppIdentifier.ONBOARDING }) // New method
+sdk.setJWT({ jwt: jwt, appIdentifier: AppIdentifier.ONBOARDING })
 
-// isOnboardingModalOpen replacement
-sdk.isOnboardingModalOpen() // Deprecated method
-sdk.isModalOpen(AppIdentifier.ONBOARDING) // New method
+sdk.isModalOpen(AppIdentifier.ONBOARDING)
 ```
 
-## Quick setup
+See the `ZeroHashSDK` class in `index.d.ts` in `/dist`.
 
-```javascript
+## Quick Setup
+
+```typescript
+import React from 'react';
 import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
 
-// Initialize SDK
-const sdk = new ZeroHashSDK({
-    zeroHashAppsURL: "https://web-sdk.zerohash.com",
-    userOnboardingJWT: onboardingJWT // This can also be set later, when opening the Modal using the `openModal` method.
-});
+const App = () => {
+  const sdk = new ZeroHashSDK({
+    // For cert use "https://web-sdk.cert.zerohash.com"
+    zeroHashAppsURL: "https://web-sdk.zerohash.com", 
+    // JWT can be set later, when opening the Modal using `openModal` method
+    cryptoBuyJWT: "<JWT_TOKEN_HERE>" 
+  });
+
+  sdk.openModal({appIdentifier: AppIdentifier.CRYPTO_BUY})
+  return <></>;
+}
 
-// Set the JWT retrieved for a particular App (each App requires a specific JWT,
-// i.e. you should not use your Onboarding JWT for Crypto Witdhrawals)
-// before the user can proceed with the flow.
-sdk.openModal({
-  appIdentifier: AppIdentifier.ONBOARDING,
-  jwt: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9." +
-    "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ." +
-    "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
-});
+export default App;
 ```
 
-## API
-
-See the `ZeroHashSDK` class in `index.d.ts` in `/dist`.
-
-If you are browsing this repository, you can find the implementation in `index.tsx`.
-
 ## Versioning
 
-The pipeline automatically updates the version in package.json after merge to main. It uses conventional commits to determine the type of bump to use:
-
-- `BREAKING CHANGE` is a major release (`1.0.0` to `2.0.0`)
-- `feat` is a minor release (`1.0.0` to `1.1.0`)
-- default is a patch release (`1.0.0` to `1.0.1`)
+The ZeroHash SDK uses [Semantic Versioning 2.0.0](https://semver.org/). Version numbers follow the `MAJOR.MINOR.PATCH` format:
 
-## Mobile usage
-In order to use our SDK on Mobile Apps you should follow the guide below. You won't need to install or have `zh-web-sdk` as a dependency in your project to use it for Mobile Apps. We use a proxy server that calls the SDK internally in order to make it work for Mobile Applications. This proxy service is referred to as `sdk-mobile` and the URLs are:
+- **MAJOR** version increments when we make incompatible API changes (e.g., `1.0.0` to `2.0.0`).
+- **MINOR** version increments when we add new functionality in a backward-compatible manner (e.g., `1.0.0` to `1.1.0`).
+- **PATCH** version increments when we make backward-compatible bug fixes (e.g., `1.0.0` to `1.0.1`).
 
-- Cert: https://sdk-mobile.cert.zerohash.com/v1
-- Prod: https://sdk-mobile.zerohash.com/v1
-
-These are the URLs your `WebView` should use on your Mobile App.
-
-### React native guide
-
-#### Events
-We forward events that come from the UI to the Native App using the `postMessage` API. You can handle these events using `onMessage` from the `WebView` component. Currently these are the events we have, for the respective Apps:
-- **Onboarding:** 
-  - `ONBOARDING_APP_LOADED` Sent when the App is loaded in the first time
-  - `ONBOARDING_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `ONBOARDING_PENDING_APPROVAL` Sent when flow is on pending approval state (e.g. document validation)
-  - `ONBOARDING_COMPLETED` Sent when user finished flow successfully with participant approved and webview can be closed
-  - `ONBOARDING_FAILED` Send when something went wrong in the flow (errored state)
-- **Crypto Withdrawals:**
-  - `CRYPTO_WITHDRAWALS_APP_LOADED` Sent when the App is loaded in the first time
-  - `CRYPTO_WITHDRAWALS_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `CRYPTO_WITHDRAWALS_COMPLETED` Sent when user finished flow successfully 
-  - `CRYPTO_WITHDRAWALS_FAILED` Send when something went wrong in the flow (errored state)
-- **Fiat Deposits:**
-  - `FIAT_DEPOSITS_APP_LOADED` Sent when the App is loaded in the first time
-  - `FIAT_DEPOSITS_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `FIAT_DEPOSITS_COMPLETED` Sent when user finished flow successfully
-  - `FIAT_DEPOSITS_FAILED` Send when something went wrong in the flow (errored state)
-- **Fiat Withdrawals:**
-  - `FIAT_WITHDRAWALS_APP_LOADED` Sent when the App is loaded in the first time
-  - `FIAT_WITHDRAWALS_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `FIAT_WITHDRAWALS_COMPLETED` Sent when user finished flow successfully
-  - `FIAT_WITHDRAWALS_FAILED` Send when something went wrong in the flow (errored state)
-- **Crypto Buy:**
-  - `CRYPTO_BUY_APP_LOADED` Sent when the App is loaded in the first time
-  - `CRYPTO_BUY_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `CRYPTO_BUY_COMPLETED` Sent when user finished flow successfully
-  - `CRYPTO_BUY_FAILED` Send when something went wrong in the flow (errored state)
-- **Crypto Sell:**
-  - `CRYPTO_SELL_APP_LOADED` Sent when the App is loaded in the first time
-  - `CRYPTO_SELL_CLOSE_BUTTON_CLICKED` Sent when the user clicks the Close button on the top-right corner
-  - `CRYPTO_SELL_COMPLETED` Sent when user finished flow successfully
-  - `CRYPTO_SELL_FAILED` Send when something went wrong in the flow (errored state)
-
-#### Messages
-To control the `WebView` you can also send messages *down*, using the `postMessage` API. Currently the accepted messages are for the respective Apps are:
-- **Onboarding**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "onboarding"} }`: It will open the onboarding modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "onboarding"}}`: It will close the onboarding modal
-- **Crypto Withdrawals**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "crypto-withdrawals"} }`: It will open the Crypto Withdrawals modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "crypto-withdrawals"}}`: It will close the Crypto Withdrawals modal
-- **Fiat Deposits**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "fiat-deposits"} }`: It will open the Fiat Deposits modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "fiat-deposits"}}`: It will close the Fiat Deposits modal
-- **Fiat Withdrawals**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "fiat-withdrawals"} }`: It will open the Fiat withdrawals modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "fiat-withdrawals"}}`: It will close the Fiat withdrawals modal
-- **Crypto Buy**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "crypto-buy"} }`: It will open the Crypto buy modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "crypto-buy"}}`: It will close the Crypto buy modal
-- **Crypto Sell**
-  - `{type: "OPEN_MODAL", payload:{jwt: "<JWT_HERE>", appIdentifier: "crypto-sell"} }`: It will open the Crypto sell modal with the JWT provided
-  - `{type: "CLOSE_MODAL", payload:{appIdentifier: "crypto-sell"}}`: It will close the Crypto sell modal
-
-#### Notes
-A postMessage call is required to open the modal when the webview is loaded (type: OPEN_MODAL). This requirement was added in version `https://{SDK_SERVER_URL}/v1` and is not present in `https://{SDK_SERVER_URL}/`, which opens the onboarding app automatically. The latter will be deprecated and will not be available for use in the future.
-
-To safely trigger the "OPEN_MODAL" event in the version 1, listen for an event sent by sdk-mobile indicating that the app is ready to receive events. This event generate by sdk-mobile is called **SDK_MOBILE_READY**.
- 
-The example below shows how you can implement the mentioned methods in a `react-native` project
-
-```jsx
-const sdkMobileServer = 'https://sdk-mobile.cert.zerohash.com/v1'
-const zeroHashAppsURL = 'https://web-sdk.zerohash.com/'
-const App = () => {
-  const webViewRef = useRef<WebView>(null)
-  const [isWebViewOpen, setIsWebViewOpen] = React.useState(false)
-  const currentAppIdentifier = 'onboarding'
-  const mockJWT =
-    'eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ6ZXJvaGFzaC5jb20iLCJzdWIiOiJ0ZXN0U3ViamVjdCIsImF1ZCI6WyJ6ZXJvaGFzaC5jb20iXSwiZXhwIjoxNjk1OTc2OTMzLCJpYXQiOjE2OTMzODQ5MzMsInBheWxvYWQiOnsiZW1haWwiOiJteS1lbWFpbEB0ZXN0LmNvbSIsInBhcnRpY2lwYW50X2NvZGUiOiJwYXJ0aWNpcGFudC1jb2RlIiwicGxhdGZvcm1fbmFtZSI6InBsYXRmb3JtLW5hbWUiLCJwbGF0Zm9ybV9jb2RlIjoicGxhdGZvcm0tY29kZSIsInBsYXRmb3JtX2FncmVlbWVudF9saW5rIjoicGxhdGZvcm0tYWdyZWVtZW50LWxpbmsifX0.r549t4J_iQ8wP5pnD2uTdRaRm4nHLO722lDmhbGoIc0E_cKVyVYnxZTO1DnXJ6NUJ6a3DvnkGv78iQHqvnFTmg'
-  const apps = {
-    fiatDeposits: { identifier: 'fiat-deposits', jwt: mockJWT },
-    cryptoBuy: { identifier: 'crypto-buy', jwt: mockJWT },
-    cryptoSell: { identifier: 'crypto-sell', jwt: mockJWT },
-    cryptoWithdrawals: { identifier: 'crypto-withdrawals', jwt: mockJWT },
-    fiatWithdrawals: { identifier: 'fiat-withdrawals', jwt: mockJWT },
-    userOnboarding: { identifier: 'onboarding', jwt: mockJWT },
-  }
-  /**
-   * Receive messages from sdk-mobile. Currently we expose the following event types:
-   * "ONBOARDING_APP_LOADED", "ONBOARDING_CLOSE_BUTTON_CLICKED",
-   * "CRYPTO_WITHDRAWALS_APP_LOADED", "CRYPTO_WITHDRAWALS_CLOSE_BUTTON_CLICKED",
-   * "FIAT_DEPOSITS_APP_LOADED", "FIAT_DEPOSITS_CLOSE_BUTTON_CLICKED",
-   * "FIAT_WITHDRAWALS_APP_LOADED", "FIAT_WITHDRAWALS_CLOSE_BUTTON_CLICKED",
-   * "CRYPTO_BUY_APP_LOADED", "CRYPTO_BUY_CLOSE_BUTTON_CLICKED",
-   * "CRYPTO_SELL_APP_LOADED", "CRYPTO_SELL_CLOSE_BUTTON_CLICKED",
-   * you should be able to take action based on these events.
-   */
-  const handleMessage = (event: WebViewMessageEvent) => {
-    const closeModalEvents = [
-      'ONBOARDING_CLOSE_BUTTON_CLICKED',
-      'CRYPTO_WITHDRAWALS_CLOSE_BUTTON_CLICKED',
-      'FIAT_DEPOSITS_CLOSE_BUTTON_CLICKED',
-      'FIAT_WITHDRAWALS_CLOSE_BUTTON_CLICKED',
-      'CRYPTO_BUY_CLOSE_BUTTON_CLICKED',
-      'CRYPTO_SELL_CLOSE_BUTTON_CLICKED',
-    ]
-    try {
-      const parsedMessage = JSON.parse(event.nativeEvent.data)
-      console.log('Received message:', parsedMessage)
-      if (closeModalEvents.includes(parsedMessage.type)) {
-        setIsWebViewOpen(false)
-      }
-      if (parsedMessage.type === 'SDK_MOBILE_READY') {
-        console.log('SDK is ready, opening modal...')
-        openModal()
-      }
-    } catch (e) {
-      alert(
-        `could not parse message: ${JSON.stringify(event.nativeEvent.data)}`,
-      )
-    }
-  }
-  /**
-   * You can also send messages to sdk-mobile, currently we accept the following messages:
-   * "OPEN_MODAL" and "CLOSE_MODAL"
-   * Note that the "true;" after the postMessage is required
-   * and recommended by the official react-native-webview docs
-   * https://github.com/react-native-webview/react-native-webview/blob/master/docs/Guide.md#the-injectedjavascript-prop
-   */
-  const makeEventType = (
-    eventAppIdentifier: string,
-    eventType: string,
-    useJWT = false,
-  ) => {
-    if (
-      !Object.entries(apps).some(
-        ([_, { identifier }]) => identifier === eventAppIdentifier,
-      )
-    ) {
-      throw new Error('Invalid app identifier')
-    }
-    if (useJWT) {
-      // You can send events with JWTs. See the example below
-      // { "type": "OPEN_MODAL", "payload": { "appIdentifier": "onboarding", "jwt": "some-jwt-token"}}
-      // { "type": "CLOSE_MODAL", "payload": { "appIdentifier": "onboarding", "jwt": "some-jwt-token"}}
-      return `{ "type": "${eventType}", "payload": { "appIdentifier": "${eventAppIdentifier}", "jwt": "${apps[eventAppIdentifier].jwt}"}}`
-    }
-    // Send events without JWTs if you already set in the URL with query parameters and don't want to send it again
-    // { "type": "OPEN_MODAL", "payload": { "appIdentifier": "onboarding"}}
-    // { "type": "CLOSE_MODAL", "payload": { "appIdentifier": "onboarding"}}
-    return `{ "type": "${eventType}", "payload": { "appIdentifier": "${eventAppIdentifier}"}}`
-  }
-  const openModal = () => {
-    setIsWebViewOpen(true)
-    webViewRef.current?.injectJavaScript(
-      `window.postMessage(${makeEventType(currentAppIdentifier, 'OPEN_MODAL')});true;`,
-    )
-  }
-  const closeModal = () => {
-    webViewRef.current?.injectJavaScript(
-      `window.postMessage(${makeEventType(currentAppIdentifier, 'CLOSE_MODAL')});true;`,
-    )
-  }
-  /**
-   * Generate the URL with the query parameters required and the JWTs for the apps
-   */
-  const generateURL = () => {
-    const jwtParams = Object.entries(apps)
-      .filter(([_, { jwt }]) => jwt)
-      .map(([key, { jwt }]) => `${key}JWT=${encodeURIComponent(jwt)}`)
-      .join('&')
-
-    return `${sdkMobileServer}?zeroHashAppsURL=${encodeURIComponent(zeroHashAppsURL)}&${jwtParams}`
-  }
-  return (
-    <SafeAreaProvider style={{ flex: 1 }}>
-      <SafeAreaView
-        style={{
-          flex: 1,
-          padding: 0,
-        }}
-      >
-        {!isWebViewOpen && (
-          <View
-            style={{
-              flex: 1,
-              alignContent: 'center',
-              flexDirection: 'row',
-              justifyContent: 'center',
-              alignItems: 'center',
-            }}
-          >
-            <TouchableOpacity
-              style={{
-                backgroundColor: '#00f197',
-                padding: 10,
-                margin: 10,
-                borderRadius: 5,
-                alignItems: 'center',
-                justifyContent: 'center',
-              }}
-              onPress={() => setIsWebViewOpen(true)}
-            >
-              <Text>Open modal</Text>
-            </TouchableOpacity>
-            <TouchableOpacity
-              style={{
-                backgroundColor: '#00f197',
-                padding: 10,
-                margin: 10,
-                borderRadius: 5,
-                alignItems: 'center',
-                justifyContent: 'center',
-              }}
-              onPress={() => closeModal()}
-            >
-              <Text>Close modal</Text>
-            </TouchableOpacity>
-          </View>
-        )}
-        <View style={{ display: isWebViewOpen ? 'flex' : 'none', flex: 1 }}>
-          {isWebViewOpen && (
-            <WebView
-              ref={webViewRef}
-              onMessage={handleMessage}
-              source={{ uri: generateURL() }}
-            />
-          )}
-        </View>
-      </SafeAreaView>
-    </SafeAreaProvider>
-  )
-}
-export default App
-```
+## Mobile Usage
+For more details on how to use it on mobile apps, please refer to our full documentation: 
+[ZeroHash SDK Documentation](https://docs.zerohash.com/reference/sdk-overview).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zh-web-sdk",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "private": false,
   "description": "ZeroHash Web SDK",
   "homepage": "https://github.com/seedcx/zh-web-sdk",