zh-web-sdk 2.17.0 → 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,6 +1,6 @@
 # ZeroHash Web SDK
 
-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.
+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.
 
 ## Installation
 
@@ -25,19 +25,21 @@ 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"
+    zeroHashAppsURL: "https://web-sdk.zerohash.com",
+    env: "prod",
+    theme: "light"
   }), []);
 
-  const handleOpenCryptoBuy = () => {
+  const handleOpenFund = () => {
     sdk.openModal({
-      appIdentifier: AppIdentifier.CRYPTO_BUY,
+      appIdentifier: AppIdentifier.FUND,
       jwt: "<JWT_TOKEN_HERE>"
     });
   };
 
   return (
-    <button onClick={handleOpenCryptoBuy}>
-      Buy Crypto
+    <button onClick={handleOpenFund}>
+      Fund Account
     </button>
   );
 };
@@ -52,45 +54,52 @@ import ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';
 
 // Initialize SDK once
 const sdk = new ZeroHashSDK({
-  zeroHashAppsURL: "https://web-sdk.zerohash.com"
+  zeroHashAppsURL: "https://web-sdk.zerohash.com",
+  env: "prod",
+  theme: "light"
 });
 
 // Open a modal
 sdk.openModal({
-  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  appIdentifier: AppIdentifier.FUND,
   jwt: "<JWT_TOKEN_HERE>"
 });
 
 // Close when done
-sdk.closeModal(AppIdentifier.CRYPTO_BUY);
+sdk.closeModal(AppIdentifier.FUND);
 ```
 
 ## Environments
 
-The SDK supports multiple environments:
-
-- **Production**: `https://web-sdk.zerohash.com`
-- **Certification/Sandbox**: `https://web-sdk.cert.zerohash.com`
+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" // Use cert environment
+  zeroHashAppsURL: "https://web-sdk.cert.zerohash.com",
+  env: "cert"
 });
 ```
 
+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
 
 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 |
-| `FUND` | Fund account operations |
 | `PROFILE` | User profile management |
 | `CRYPTO_ACCOUNT_LINK` | Link cryptocurrency accounts |
 | `CRYPTO_ACCOUNT_LINK_PAYOUTS` | Link crypto accounts for payouts |
@@ -110,7 +119,9 @@ new ZeroHashSDK(config: IInitializeParameters)
 
 ```typescript
 {
-  zeroHashAppsURL: string;          // Required: Base URL for ZeroHash apps
+  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
@@ -138,7 +149,7 @@ Opens a modal for the specified app.
 
 ```typescript
 sdk.openModal({
-  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  appIdentifier: AppIdentifier.FUND,
   jwt?: string,           // Optional: Set or update JWT
   filters?: Filters,      // Optional: Filter options
   navigate?: Page         // Optional: Navigation parameters
@@ -150,7 +161,7 @@ sdk.openModal({
 Closes the modal for the specified app.
 
 ```typescript
-sdk.closeModal(AppIdentifier.CRYPTO_BUY);
+sdk.closeModal(AppIdentifier.FUND);
 ```
 
 #### `setJWT(params)`
@@ -160,7 +171,7 @@ Set or update the JWT for a specific app.
 ```typescript
 sdk.setJWT({
   jwt: "<JWT_TOKEN>",
-  appIdentifier: AppIdentifier.CRYPTO_BUY
+  appIdentifier: AppIdentifier.FUND
 });
 ```
 
@@ -169,7 +180,7 @@ sdk.setJWT({
 Check if a modal is currently open.
 
 ```typescript
-const isOpen = sdk.isModalOpen(AppIdentifier.CRYPTO_BUY);
+const isOpen = sdk.isModalOpen(AppIdentifier.FUND);
 ```
 
 #### `setFilters(params)`
@@ -178,7 +189,7 @@ Set filters for a specific app.
 
 ```typescript
 sdk.setFilters({
-  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  appIdentifier: AppIdentifier.FUND,
   filters: {
     getAssets: {
       stablecoin: true
@@ -187,6 +198,14 @@ sdk.setFilters({
 });
 ```
 
+#### `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.
@@ -197,14 +216,15 @@ sdk.setFilters({
 ```typescript
 const sdk = new ZeroHashSDK({
   zeroHashAppsURL: "https://web-sdk.zerohash.com",
-  cryptoBuyJWT: jwt
+  env: "prod",
+  fundJWT: jwt
 });
 ```
 
 **2. When opening a modal:**
 ```typescript
 sdk.openModal({
-  appIdentifier: AppIdentifier.CRYPTO_BUY,
+  appIdentifier: AppIdentifier.FUND,
   jwt: jwt
 });
 ```
@@ -213,7 +233,7 @@ sdk.openModal({
 ```typescript
 sdk.setJWT({
   jwt: newJwt,
-  appIdentifier: AppIdentifier.CRYPTO_BUY
+  appIdentifier: AppIdentifier.FUND
 });
 ```
 
@@ -230,14 +250,6 @@ import ZeroHashSDK, {
 } 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 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)

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";