zh-web-sdk 2.16.1 → 2.17.0

package/README.md

@@ -1,56 +1,249 @@
-# ZeroHash Platform SDK
+# ZeroHash Web SDK
 
-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.
+The ZeroHash Web SDK enables platforms to integrate ZeroHash financial services on web and mobile applications. Access various UI flows including Crypto Buy, Crypto Sell, Crypto Withdrawals, Fiat Deposits, Fiat Withdrawals, and Onboarding through a single SDK instance.
 
-### SDK Methods
+## Installation
+
+```bash
+npm install zh-web-sdk
+```
+
+or
+
+```bash
+yarn add zh-web-sdk
+```
+
+## Quick Start
+
+### React Example
+
+```typescript
+import React, { useMemo } from 'react';
+import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
+
+const App = () => {
+  // Create SDK instance once - not on every render
+  const sdk = useMemo(() => new ZeroHashSDK({
+    zeroHashAppsURL: "https://web-sdk.zerohash.com"
+  }), []);
+
+  const handleOpenCryptoBuy = () => {
+    sdk.openModal({
+      appIdentifier: AppIdentifier.CRYPTO_BUY,
+      jwt: "<JWT_TOKEN_HERE>"
+    });
+  };
+
+  return (
+    <button onClick={handleOpenCryptoBuy}>
+      Buy Crypto
+    </button>
+  );
+};
+
+export default App;
+```
+
+### Vanilla JavaScript Example
 
 ```javascript
-import { AppIdentifier } from 'zh-web-sdk'
+import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
+
+// Initialize SDK once
+const sdk = new ZeroHashSDK({
+  zeroHashAppsURL: "https://web-sdk.zerohash.com"
+});
+
+// Open a modal
+sdk.openModal({
+  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  jwt: "<JWT_TOKEN_HERE>"
+});
 
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING, jwt: jwt})
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING})
+// Close when done
+sdk.closeModal(AppIdentifier.CRYPTO_BUY);
+```
+
+## Environments
 
-sdk.closeModal(AppIdentifier.ONBOARDING)
+The SDK supports multiple environments:
 
-sdk.setJWT({ jwt: jwt, appIdentifier: AppIdentifier.ONBOARDING })
+- **Production**: `https://web-sdk.zerohash.com`
+- **Certification/Sandbox**: `https://web-sdk.cert.zerohash.com`
 
-sdk.isModalOpen(AppIdentifier.ONBOARDING)
+```typescript
+const sdk = new ZeroHashSDK({
+  zeroHashAppsURL: "https://web-sdk.cert.zerohash.com" // Use cert environment
+});
 ```
 
-See the `ZeroHashSDK` class in `index.d.ts` in `/dist`.
+## Available App Identifiers
+
+The SDK supports the following application flows:
+
+| AppIdentifier | Description |
+|--------------|-------------|
+| `ONBOARDING` | User onboarding and KYC |
+| `CRYPTO_BUY` | Purchase cryptocurrency |
+| `CRYPTO_SELL` | Sell cryptocurrency |
+| `CRYPTO_WITHDRAWALS` | Withdraw crypto to external wallets |
+| `FIAT_DEPOSITS` | Deposit fiat currency |
+| `FIAT_WITHDRAWALS` | Withdraw fiat currency |
+| `FUND` | Fund account operations |
+| `PROFILE` | User profile management |
+| `CRYPTO_ACCOUNT_LINK` | Link cryptocurrency accounts |
+| `CRYPTO_ACCOUNT_LINK_PAYOUTS` | Link crypto accounts for payouts |
+| `FIAT_ACCOUNT_LINK` | Link bank accounts |
+| `PAYOUTS` | Payout operations |
+| `PAY` | Payment operations |
 
-## Quick Setup
+## API Reference
+
+### Constructor
 
 ```typescript
-import React from 'react';
-import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
+new ZeroHashSDK(config: IInitializeParameters)
+```
 
-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 <></>;
+**Configuration Options:**
+
+```typescript
+{
+  zeroHashAppsURL: string;          // Required: Base URL for ZeroHash apps
+  rootQuerySelector?: string;        // Optional: Custom DOM element selector
+
+  // Optional: Set JWTs during initialization
+  cryptoBuyJWT?: string;
+  cryptoSellJWT?: string;
+  cryptoWithdrawalsJWT?: string;
+  fiatDepositsJWT?: string;
+  fiatWithdrawalsJWT?: string;
+  userOnboardingJWT?: string;
+  fundJWT?: string;
+  profileJWT?: string;
+  cryptoAccountLinkJWT?: string;
+  cryptoAccountLinkPayoutsJWT?: string;
+  fiatAccountLinkJWT?: string;
+  payoutsJWT?: string;
+  payJWT?: string;
 }
+```
 
-export default App;
+### Methods
+
+#### `openModal(params)`
+
+Opens a modal for the specified app.
+
+```typescript
+sdk.openModal({
+  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  jwt?: string,           // Optional: Set or update JWT
+  filters?: Filters,      // Optional: Filter options
+  navigate?: Page         // Optional: Navigation parameters
+});
+```
+
+#### `closeModal(appIdentifier)`
+
+Closes the modal for the specified app.
+
+```typescript
+sdk.closeModal(AppIdentifier.CRYPTO_BUY);
+```
+
+#### `setJWT(params)`
+
+Set or update the JWT for a specific app.
+
+```typescript
+sdk.setJWT({
+  jwt: "<JWT_TOKEN>",
+  appIdentifier: AppIdentifier.CRYPTO_BUY
+});
+```
+
+#### `isModalOpen(appIdentifier)`
+
+Check if a modal is currently open.
+
+```typescript
+const isOpen = sdk.isModalOpen(AppIdentifier.CRYPTO_BUY);
+```
+
+#### `setFilters(params)`
+
+Set filters for a specific app.
+
+```typescript
+sdk.setFilters({
+  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  filters: {
+    getAssets: {
+      stablecoin: true
+    }
+  }
+});
+```
+
+## JWT Authentication
+
+**⚠️ Security Note**: JWTs should be obtained from your backend server using the ZeroHash API with your API key. Never expose your API key or perform JWT exchanges on the client side.
+
+### Two approaches for providing JWTs:
+
+**1. During initialization:**
+```typescript
+const sdk = new ZeroHashSDK({
+  zeroHashAppsURL: "https://web-sdk.zerohash.com",
+  cryptoBuyJWT: jwt
+});
+```
+
+**2. When opening a modal:**
+```typescript
+sdk.openModal({
+  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  jwt: jwt
+});
+```
+
+**3. Update JWT later:**
+```typescript
+sdk.setJWT({
+  jwt: newJwt,
+  appIdentifier: AppIdentifier.CRYPTO_BUY
+});
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes type definitions. Import types as needed:
+
+```typescript
+import ZeroHashSDK, {
+  AppIdentifier,
+  IInitializeParameters,
+  IOpenModalParameters,
+  Filters
+} from 'zh-web-sdk';
 ```
 
 ## Versioning
 
 The ZeroHash SDK uses [Semantic Versioning 2.0.0](https://semver.org/). Version numbers follow the `MAJOR.MINOR.PATCH` format:
 
-- **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`).
+- **MAJOR** version increments for incompatible API changes (e.g., `1.0.0` to `2.0.0`)
+- **MINOR** version increments for backward-compatible new features (e.g., `1.0.0` to `1.1.0`)
+- **PATCH** version increments for backward-compatible bug fixes (e.g., `1.0.0` to `1.0.1`)
+
+## Documentation & Support
+
+- **Full Documentation**: [ZeroHash SDK Documentation](https://docs.zerohash.com/reference/sdk-overview)
+- **Changelog**: [ZeroHash Documentation Changelog](https://docs.zerohash.com/reference/changelog)
+- **Mobile Usage**: See the [SDK Overview](https://docs.zerohash.com/reference/sdk-overview) for mobile implementation details
 
-## Changelog
-[zerohash Documentation Changelog](https://docs.zerohash.com/reference/changelog)
+## License
 
-## 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).
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zh-web-sdk",
-  "version": "2.16.1",
+  "version": "2.17.0",
   "private": false,
   "description": "ZeroHash Web SDK",
   "homepage": "https://github.com/seedcx/zh-web-sdk",
@@ -8,6 +8,11 @@
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "keywords": [],
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "author": "support@zerohash.com",
   "license": "MIT",
   "scripts": {

package/.eslintrc.js

@@ -1,12 +0,0 @@
-module.exports = {
-  env: { browser: true, es2020: true },
-  extends: [
-    'eslint:recommended',
-    'plugin:@typescript-eslint/recommended',
-    'plugin:react-hooks/recommended',
-  ],
-  parser: '@typescript-eslint/parser',
-  parserOptions: { ecmaVersion: 'latest', sourceType: 'module' },
-  plugins: ['react-refresh'],
-  rules: {},
-}

package/.github/CHANGELOG_TEMPLATE.md

@@ -1,73 +0,0 @@
-# Changelog Entry Template
-
-Use this template when adding a new version to CHANGELOG.md
-
----
-
-## [X.Y.Z] - YYYY-MM-DD
-
-### Added
-- New feature that allows users to [describe user benefit] [#PR_NUMBER]
-- Another feature description focusing on customer value
-
-### Changed
-- Updated [feature/behavior] to [improvement description]
-- [Behavior change] now [new behavior] instead of [old behavior]
-
-### Deprecated
-- [Feature name] is deprecated and will be removed in version [X.Y.Z]
-- Migration path: Use [alternative approach] instead
-- See [documentation link] for details
-
-### Removed
-- Removed [feature name] (deprecated since version [X.Y.Z])
-- See [migration guide link] for alternatives
-
-### Fixed
-- Fixed issue where [problem description] [#PR_NUMBER]
-- Resolved [bug description] affecting [user impact]
-
-### Security
-- Updated [dependency name] to address [vulnerability type]
-- Fixed [security issue description]
-
----
-
-## Guidelines
-
-### Writing Tips
-
-1. **Focus on User Impact**
-   - ✅ Good: "Fixed SDK positioning to prevent scrolling issues"
-   - ❌ Avoid: "Refactored internal positioning logic"
-
-2. **Be Specific and Clear**
-   - ✅ Good: "Added bank account linking feature for direct deposits"
-   - ❌ Avoid: "Added new feature"
-
-
-### Breaking Changes
-
-For MAJOR version releases, clearly mark breaking changes:
-
-```markdown
-## [3.0.0] - 2026-XX-XX
-
-### Changed
-- ⚠️ **BREAKING**: Renamed `cryptoBuyJWT` parameter to `jwt` in SDK configuration
-
-**Migration Guide:**
-\`\`\`typescript
-// Before (v2.x)
-const sdk = new ZeroHashSDK({
-  cryptoBuyJWT: token
-})
-
-// After (v3.x)
-const sdk = new ZeroHashSDK({
-  jwt: token
-})
-\`\`\`
-
-See [Migration Guide v2 to v3](link) for full details.
-```

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -1,10 +0,0 @@
-## Description
-
-## Solution
-
-## Result
-
-## Checklist
-
-- [ ] CHANGELOG.md has been updated
-- [ ] Official docs have been updated

package/.github/backup/publish-tag.yaml

@@ -1,14 +0,0 @@
-name: "Reusable NPM Publish tag"
-
-on:
-  push:
-    tags:
-      - "v*"
-  workflow_dispatch:
-
-jobs:
-  from_reusable:
-    uses: seedcx/composite-actions/.github/workflows/rw-npm-publish-public-oidc.yml@main
-    secrets: inherit
-    with:
-      NODE_VERSION: "22.21.1"

package/.github/workflows/build.yaml

@@ -1,13 +0,0 @@
-name: "Reusable NPM Build"
-
-on:
-  pull_request:
-    branches: [ main, master ]
-
-jobs:
-  from_reusable:
-    uses: seedcx/composite-actions/.github/workflows/rw-npm-build.yml@main
-    secrets: inherit
-    with:
-      NODE_VERSION: "22.22.0"
-      NPM_VERSION: "9"

package/.github/workflows/pr.yaml

@@ -1,14 +0,0 @@
-name: "Pull Request"
-
-on:
-  pull_request:
-    branches: [main]
-
-jobs:
-  from_reusable:
-    uses: seedcx/composite-actions/.github/workflows/rw-node-pull-request.yml@main
-    secrets: inherit
-    with:
-      NODE_VERSION: "22.22.0"
-      TEST_PLATFORM: 'npm'
-      TEST_REPORTER: 'jest-junit'

package/.github/workflows/publish.yaml

@@ -1,13 +0,0 @@
-name: "Reusable NPM Publish"
-
-on:
-  push:
-    tags:
-      - "*"
-
-jobs:
-  from_reusable:
-    uses: seedcx/composite-actions/.github/workflows/rw-npm-publish-public.yml@main
-    secrets: inherit
-    with:
-      NODE_VERSION: "22.22.0"

package/.github/workflows/security.yml

@@ -1,15 +0,0 @@
-name: 'Security Workflow'
-
-on:
-  workflow_dispatch:
-  pull_request:
-    branches: [main]
-  schedule:
-    - cron: '0 16 * * 2'
-
-jobs:
-  security:
-    uses: seedcx/composite-actions/.github/workflows/rw-security.yml@main
-    with:
-      NODE_VERSION: 22.12.0
-    secrets: inherit

package/.github/workflows/tag.yaml

@@ -1,14 +0,0 @@
-name: 'Tag New Version'
-
-on:
-  push:
-    branches:
-      - main
-  workflow_dispatch:
-
-jobs:
-  from_reusable:
-    uses: seedcx/composite-actions/.github/workflows/rw-npm-tag.yml@main
-    secrets: inherit
-    with:
-      NODE_VERSION: "22.22.0"

package/RELEASING.md

@@ -1,39 +0,0 @@
-# Release Process
-
-This document describes the process for releasing new versions of the zerohash Web SDK.
-
-## Release Steps
-
-### 1. Update CHANGELOG.md
-
-Add a new version section at the top of `CHANGELOG.md`:
-
-```markdown
-## [X.Y.Z] - YYYY-MM-DD
-
-### Added
-- New feature description [#PR_NUMBER]
-
-### Fixed
-- Bug fix description [#PR_NUMBER]
-
-### Changed
-- Behavior change description
-```
-
-See `.github/CHANGELOG_TEMPLATE.md` for detailed guidelines.
-
-**Commit the changelog:**
-
-```bash
-git add CHANGELOG.md
-git commit -m "docs: update CHANGELOG for vX.Y.Z"
-git push origin main
-```
-
-### 2. Update ReadMe Changelog
-
-1. Go to ReadMe dashboard: https://dash.readme.com/
-2. Navigate to the Changelog section
-3. Create new changelog entry with content from `CHANGELOG.md`
-4. Publish the entry

package/jest.config.js

@@ -1,8 +0,0 @@
-module.exports = {
-  testEnvironment: "jsdom",
-  transform: {
-    "^.+.tsx?$": ["ts-jest",{}],
-  },
-  modulePathIgnorePatterns: ["<rootDir>/dist/", "<rootDir>/build/", "<rootDir>/node_modules/"],
-  setupFiles: ["<rootDir>/jest.setup.js"],
-};

package/jest.setup.js

@@ -1,24 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-/* eslint-disable @typescript-eslint/no-var-requires */
-/* eslint-disable no-undef */
-
-const { TextEncoder, TextDecoder } = require('util');
-
-Object.assign(global, { TextDecoder, TextEncoder })
-global.CSS = {
-  supports: (k, v) => true,
-}
-
-Object.defineProperty(window, 'matchMedia', {
-  writable: true,
-  value: jest.fn().mockImplementation(query => ({
-    matches: false,
-    media: query,
-    onchange: null,
-    addListener: jest.fn(), // Deprecated
-    removeListener: jest.fn(), // Deprecated
-    addEventListener: jest.fn(),
-    removeEventListener: jest.fn(),
-    dispatchEvent: jest.fn(),
-  })),
-});

package/scripts/build.js

@@ -1,34 +0,0 @@
-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

@@ -1,49 +0,0 @@
-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);
-    });