# ZeroHash Web SDK

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

```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 ZeroHashSDK, { AppIdentifier } from 'zh-web-sdk';

// Initialize SDK once
const sdk = new ZeroHashSDK({
  zeroHashAppsURL: "https://web-sdk.zerohash.com",
  env: "prod",
  theme: "light"
});

// Open a modal
sdk.openModal({
  appIdentifier: AppIdentifier.FUND,
  jwt: "<JWT_TOKEN_HERE>"
});

// Close when done
sdk.closeModal(AppIdentifier.FUND);
```

## Environments

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"
});
```

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 |
| `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
new ZeroHashSDK(config: IInitializeParameters)
```

**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;
}
```

### 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
});
```

#### `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.

### Ways to provide JWTs

You only need to provide the JWT once. If it was set during initialization or via `setJWT`, calling `openModal` without a `jwt` uses the token already set for that app. Passing `jwt` to `openModal` sets or updates it. Either way the SDK reads the same token to decide whether to render the next-generation UI, so no change to how you call `openModal` is needed.

**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';
```

## 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

## License

MIT