zh-web-sdk 2.16.1 → 3.0.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+## [3.0.0] - 2026-05-21
+
+Major version bump signaling the rollout of the next-generation SDK rendering path. The integrator-facing API is unchanged for cert/prod consumers; the only public-type change is the narrowing of `env` (see Changed).
+
+### Changed
+- **Breaking (TypeScript surface):** Narrowed the public `Environment` type from `'dev' | 'cert' | 'prod'` to `'cert' | 'prod'`. The `'dev'` value targeted Zero Hash internal CDNs and was never intended for integrator use; it has been moved to a separate `InternalEnvironment` type used by our QA tooling. Integrators on cert or prod do not need to make any changes.
+
+### Added
+- Opt-in next-generation rendering for ZeroHash apps, delivering improved performance and UX across Crypto Buy/Sell, Onboarding, Fiat Deposits/Withdrawals, Crypto Withdrawals, Fund, Pay, Payouts, Profile, and Account Link flows [#97]
+  - Rolled out gradually and controlled server-side — no integration changes required
+  - Flows not yet migrated continue to render in the existing iframe
+- SDK version is now attached to embedded-app logs to make support investigations faster [#97]
+- New `theme` option on the SDK constructor (`'light' | 'dark' | 'auto'`, defaults to `'light'`) and `sdk.setTheme({ theme })` method to control the appearance of next-generation flows; legacy iframe and Connect Auth (Fund) appearance is unchanged [#97]
+- New `env` option on the SDK constructor (`'cert' | 'prod'`) for explicit environment selection. When set, it takes precedence over hostname inference from `zeroHashAppsURL` and is the recommended way to target a specific deployment going forward [#97]
+
+### Fixed
+- Expanded the URL-based environment-inference allowlist to cover the full set of Zero Hash hostnames used by integrators (cert/dev, US/EU, `0hash.com`/`zerohash.com`/`zerohash.eu`/`sandbox.connect.xyz`/`gating.0hash.com`). Previously, only `web-sdk.cert.0hash.com`, `web-sdk.sandbox.connect.xyz`, and `web-sdk.dev.0hash.com` were recognized — every other Zero Hash host silently fell back to `prod`, causing cert sessions to load the production CDN. Integrators on hosts outside this list should still pass the new `env` option explicitly [#97]
+- Removed the wrong-theme flash when opening a next-generation flow with `theme: 'dark'` or `'auto'`. The wrapper modal no longer paints a white background before the inner SDK renders, and it now becomes visible as soon as the SDK component reports it has loaded instead of waiting on a multi-second fallback. Light-mode and legacy iframe flows are unchanged [#97]
+- Fixed Fund's Connect Auth flow targeting the wrong Connect API on non-prod hosts. The Auth env was previously inferred via a substring check against `zeroHashAppsURL` and silently fell back to `production` for dev hosts (e.g. `web-sdk.dev.0hash.com`) and partner-hosted URLs, causing the Fund modal to call `api.connect.xyz` instead of `api.sandbox.connect.xyz`. The Auth env is now resolved from the same source as the new-SDK components — explicit `env` from the SDK constructor when provided, otherwise the hostname allowlist [#97]
+
+### Security
+- Hardened the Connect Auth issuer check to use a strict hostname allowlist, replacing the previous substring match [#97]
+
 ## [2.16.0] - 2026-02-20
 
 ### Added

package/README.md

@@ -1,56 +1,261 @@
-# 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 Fund, Onboarding, Crypto Buy, Crypto Sell, Crypto Withdrawals, Fiat Deposits, and Fiat Withdrawals 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",
+    env: "prod",
+    theme: "light"
+  }), []);
+
+  const handleOpenFund = () => {
+    sdk.openModal({
+      appIdentifier: AppIdentifier.FUND,
+      jwt: "<JWT_TOKEN_HERE>"
+    });
+  };
+
+  return (
+    <button onClick={handleOpenFund}>
+      Fund Account
+    </button>
+  );
+};
+
+export default App;
+```
+
+### Vanilla JavaScript Example
 
 ```javascript
-import { AppIdentifier } from 'zh-web-sdk'
+import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
 
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING, jwt: jwt})
-sdk.openModal({appIdentifier: AppIdentifier.ONBOARDING})
+// Initialize SDK once
+const sdk = new ZeroHashSDK({
+  zeroHashAppsURL: "https://web-sdk.zerohash.com",
+  env: "prod",
+  theme: "light"
+});
 
-sdk.closeModal(AppIdentifier.ONBOARDING)
+// Open a modal
+sdk.openModal({
+  appIdentifier: AppIdentifier.FUND,
+  jwt: "<JWT_TOKEN_HERE>"
+});
+
+// Close when done
+sdk.closeModal(AppIdentifier.FUND);
+```
 
-sdk.setJWT({ jwt: jwt, appIdentifier: AppIdentifier.ONBOARDING })
+## Environments
 
-sdk.isModalOpen(AppIdentifier.ONBOARDING)
+Pass `env` to select the deployment the SDK should target. Accepted values are `'cert'` and `'prod'`. When set, `env` is the source of truth for environment resolution and overrides hostname-based inference from `zeroHashAppsURL`.
+
+```typescript
+const sdk = new ZeroHashSDK({
+  zeroHashAppsURL: "https://web-sdk.cert.zerohash.com",
+  env: "cert"
+});
 ```
 
-See the `ZeroHashSDK` class in `index.d.ts` in `/dist`.
+Default URLs per environment:
+
+- **Production**: `https://web-sdk.zerohash.com`
+- **Certification/Sandbox**: `https://web-sdk.cert.zerohash.com`
+
+If `env` is omitted, the SDK falls back to inferring the environment from the hostname of `zeroHashAppsURL`. Hosts outside the recognized Zero Hash list resolve to `'prod'` — pass `env` explicitly when integrating from a partner-hosted domain.
+
+## Available App Identifiers
 
-## Quick Setup
+The SDK supports the following application flows:
+
+| AppIdentifier | Description |
+|--------------|-------------|
+| `FUND` | Fund account operations |
+| `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 |
+| `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 |
+
+## 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
+  env?: 'cert' | 'prod';             // Optional: Explicit environment selection
+  theme?: 'light' | 'dark' | 'auto'; // Optional: Appearance for next-gen flows (defaults to 'light')
+  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.FUND,
+  jwt?: string,           // Optional: Set or update JWT
+  filters?: Filters,      // Optional: Filter options
+  navigate?: Page         // Optional: Navigation parameters
+});
 ```
 
-## Versioning
+#### `closeModal(appIdentifier)`
+
+Closes the modal for the specified app.
+
+```typescript
+sdk.closeModal(AppIdentifier.FUND);
+```
+
+#### `setJWT(params)`
+
+Set or update the JWT for a specific app.
+
+```typescript
+sdk.setJWT({
+  jwt: "<JWT_TOKEN>",
+  appIdentifier: AppIdentifier.FUND
+});
+```
+
+#### `isModalOpen(appIdentifier)`
+
+Check if a modal is currently open.
+
+```typescript
+const isOpen = sdk.isModalOpen(AppIdentifier.FUND);
+```
+
+#### `setFilters(params)`
+
+Set filters for a specific app.
+
+```typescript
+sdk.setFilters({
+  appIdentifier: AppIdentifier.FUND,
+  filters: {
+    getAssets: {
+      stablecoin: true
+    }
+  }
+});
+```
+
+#### `setTheme(params)`
+
+Update the theme forwarded to the next-generation `@zerohash-sdk/*-react` flows and Connect Auth (Fund). Has no effect on the legacy iframe.
+
+```typescript
+sdk.setTheme({ theme: "dark" }); // 'light' | 'dark' | 'auto'
+```
+
+## 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",
+  env: "prod",
+  fundJWT: jwt
+});
+```
+
+**2. When opening a modal:**
+```typescript
+sdk.openModal({
+  appIdentifier: AppIdentifier.FUND,
+  jwt: jwt
+});
+```
+
+**3. Update JWT later:**
+```typescript
+sdk.setJWT({
+  jwt: newJwt,
+  appIdentifier: AppIdentifier.FUND
+});
+```
+
+## 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';
+```
 
-The ZeroHash SDK uses [Semantic Versioning 2.0.0](https://semver.org/). Version numbers follow the `MAJOR.MINOR.PATCH` format:
+## Documentation & Support
 
-- **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`).
+- **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/dist/__mocks__/@zerohash-sdk/sdk-react-mock.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/explicit-env.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/message-router-origins.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/sdk-version-attribution.test.d.ts

@@ -0,0 +1 @@
+import "../index";

package/dist/__tests__/styles.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/api/convert-token.d.ts

@@ -1,6 +1,18 @@
+export interface FundWithdrawalDetails {
+    quoted_asset?: string;
+    withdrawal_request_amount?: string | number;
+    external_account_id?: string;
+}
 export interface JWTPayload {
     auth_embedded?: boolean;
     reference_id?: string;
+    payload?: {
+        use_new_sdk?: boolean;
+        withdrawal_details?: FundWithdrawalDetails;
+        [key: string]: unknown;
+    };
     [key: string]: unknown;
 }
 export declare function decodeJWT(token: string): JWTPayload | null;
+export declare const ALLOWED_CONNECT_ISSUER_HOSTNAMES: readonly string[];
+export declare function isConnectIssuer(iss: unknown): boolean;

package/dist/iframe-container/AppContainer.d.ts

@@ -1,4 +1,4 @@
-import { AppIdentifier, AuthSettings, Filters, Page } from "../types";
+import { AppIdentifier, AuthSettings, Environment, InternalEnvironment, Filters, Page, Theme } from "../types";
 interface AppContainerProps {
     isAppActive?: boolean;
     isAppLoaded?: boolean;
@@ -9,10 +9,18 @@ interface AppContainerProps {
     navigate?: Page;
     useAuth?: boolean;
     authSettings?: AuthSettings;
+    useNewSdk?: boolean;
+    theme?: Theme;
+    /**
+     * Explicit environment forwarded by `ZeroHashSDK`. When provided, it is
+     * preferred over hostname inference from `zeroHashAppURL`.
+     */
+    env?: Environment | InternalEnvironment;
 }
-declare const _default: import("react-redux").ConnectedComponent<({ isAppActive, isAppLoaded, jwt, zeroHashAppURL, appIdentifier, navigate, useAuth, authSettings, }: AppContainerProps) => import("react/jsx-runtime").JSX.Element, {
-    zeroHashAppURL: string;
+declare const _default: import("react-redux").ConnectedComponent<({ isAppActive, isAppLoaded, jwt, zeroHashAppURL, appIdentifier, navigate, useAuth, authSettings, useNewSdk, theme, env: explicitEnv, }: AppContainerProps) => import("react/jsx-runtime").JSX.Element, {
     appIdentifier: AppIdentifier;
+    zeroHashAppURL: string;
+    env?: (Environment | InternalEnvironment) | undefined;
     isAppActive?: boolean | undefined;
     isAppLoaded?: boolean | undefined;
     jwt?: string | undefined;
@@ -20,6 +28,8 @@ declare const _default: import("react-redux").ConnectedComponent<({ isAppActive,
     navigate?: Page | undefined;
     useAuth?: boolean | undefined;
     authSettings?: AuthSettings | undefined;
+    useNewSdk?: boolean | undefined;
+    theme?: Theme | undefined;
     context?: import("react-redux/es/components/Context").ReactReduxContextInstance | undefined;
     store?: import("redux").Store | undefined;
 }>;

package/dist/iframe-container/__tests__/get-new-sdk-env.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/iframe-container/hooks/use-style-updates.d.ts

@@ -22,4 +22,5 @@ export declare const useStyleUpdates: (zeroHashAppURL: string, defaultStyles: St
     styles: StyleConfig;
     stylesLoaded: boolean;
     handleStyleConfig: (incomingStyles: Partial<StyleConfig>, eventOrigin: string) => boolean;
+    markStylesLoaded: () => void;
 };

package/dist/index.d.ts

@@ -1,4 +1,15 @@
-import { AppIdentifier, IInitializeParameters, IOpenModalParameters, IOpenOnboardingModalParameters, ISetFiltersParameters, ISetJWTParameters, ISetNavigateParameters, ISetUserOnboardingJWTParameters, IZeroHashSDK } from "./types";
+import { AppIdentifier, IInitializeParameters, IOpenModalParameters, IOpenOnboardingModalParameters, ISetFiltersParameters, ISetJWTParameters, ISetNavigateParameters, ISetThemeParameters, ISetUserOnboardingJWTParameters, IZeroHashSDK } from "./types";
+declare global {
+    interface Window {
+        /**
+         * Version of zh-web-sdk loaded on the host page. Embedded
+         * `@zerohash-sdk/*` web components read this and forward it to their
+         * iframe Faro logs as `zh_web_sdk_version`. Absent when the new SDKs
+         * are embedded directly without zh-web-sdk.
+         */
+        __ZH_WEB_SDK_VERSION__?: string;
+    }
+}
 export declare class ZeroHashSDK implements IZeroHashSDK {
     private rootQuerySelector;
     private onboardingInitialized;
@@ -12,7 +23,7 @@ export declare class ZeroHashSDK implements IZeroHashSDK {
      *
      * For more information, see {@code IInitializeParameters}
      */
-    constructor({ zeroHashOnboardingURL, rootQuerySelector, userOnboardingJWT, cryptoWithdrawalsJWT, fiatDepositsJWT, fiatWithdrawalsJWT, cryptoBuyJWT, cryptoSellJWT, fundJWT, profileJWT, cryptoAccountLinkJWT, cryptoAccountLinkPayoutsJWT, payoutsJWT, payJWT, fiatAccountLinkJWT, zeroHashAppsURL, }: IInitializeParameters);
+    constructor({ zeroHashOnboardingURL, rootQuerySelector, userOnboardingJWT, cryptoWithdrawalsJWT, fiatDepositsJWT, fiatWithdrawalsJWT, cryptoBuyJWT, cryptoSellJWT, fundJWT, profileJWT, cryptoAccountLinkJWT, cryptoAccountLinkPayoutsJWT, payoutsJWT, payJWT, fiatAccountLinkJWT, zeroHashAppsURL, env, theme, }: IInitializeParameters);
     /**
      * setJWT sets the JWT for the appIdentifier provided.
      * The JWT should be the JWT provided by ZeroHash via the platform
@@ -31,6 +42,12 @@ export declare class ZeroHashSDK implements IZeroHashSDK {
      * specific to Onboarding and is used to navigate to a specific page within the App.
      */
     setNavigate({ appIdentifier, navigate }: ISetNavigateParameters): void;
+    /**
+     * setTheme updates the theme forwarded to new @zerohash-sdk/*-react
+     * components. Accepts 'light', 'dark', or 'auto'. Has no effect on the
+     * legacy iframe path or the Connect Auth (Fund) component.
+     */
+    setTheme({ theme }: ISetThemeParameters): void;
     /**
      * setUserOnboardingJWT sets the JWT to be whatever value is provided.
      * The JWT should be the UserJWT provided by ZeroHash via the platform
@@ -61,6 +78,11 @@ export declare class ZeroHashSDK implements IZeroHashSDK {
     closeModal(appIdentifier: AppIdentifier): void;
     /**
      * openModal opens the modal for the appIdentifier provided.
+     *
+     * When the JWT payload contains `use_new_sdk: true`, the modal renders
+     * the corresponding `@zerohash-sdk/*-react` npm package instead of the
+     * legacy iframe. Apps that don't yet have a published React package
+     * (e.g. crypto-account-link) fall back to the iframe automatically.
      */
     openModal({ jwt, appIdentifier, filters, navigate, }: IOpenModalParameters): void;
     /**
@@ -74,5 +96,11 @@ export declare class ZeroHashSDK implements IZeroHashSDK {
      */
     closeOnboardingModal(): void;
 }
+/**
+ * Test-only: clear the set-once `_newSdkOrigin` pin so suites that
+ * construct `ZeroHashSDK` multiple times can exercise different envs in
+ * isolation. Not exported from the package; tests import it directly.
+ */
+export declare function _resetNewSdkOriginForTests(): void;
 export default ZeroHashSDK;
 export * from "./types";