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

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

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

## Environments

The SDK supports multiple environments:

- **Production**: `https://web-sdk.zerohash.com`
- **Certification/Sandbox**: `https://web-sdk.cert.zerohash.com`

```typescript
const sdk = new ZeroHashSDK({
  zeroHashAppsURL: "https://web-sdk.cert.zerohash.com" // Use cert environment
});
```

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

## API Reference

### Constructor

```typescript
new ZeroHashSDK(config: IInitializeParameters)
```

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

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

## License

MIT