# @zerohash-sdk/crypto-withdrawals-react

A React SDK that enables frontend React applications to seamlessly integrate with the Connect Crypto Withdrawals product.

Connect Crypto Withdrawals provides a secure, customizable flow for withdrawing crypto assets directly within your application.

## Requirements

- React 18.0.0 or higher
- React DOM 18.0.0 or higher

## Installation

```bash
npm install @zerohash-sdk/crypto-withdrawals-react
```

## Getting Started

### 1. Import the CryptoWithdrawals Component

```tsx
import { CryptoWithdrawals } from '@zerohash-sdk/crypto-withdrawals-react';
```

### 2. Add the CryptoWithdrawals Component to Your App

```tsx
function App() {
  const jwt = 'your-jwt-token'; // Obtain this from your backend

  return (
    <CryptoWithdrawals
      jwt={jwt}
      env="prod" // or "cert" for testing
      theme="auto" // 'auto' (default), 'light', or 'dark'
    />
  );
}
```

### 3. Configure Event Callbacks (Optional)

```tsx
function App() {
  const jwt = 'your-jwt-token';

  return (
    <CryptoWithdrawals
      jwt={jwt}
      env="prod"
      theme="auto"
      onCompleted={({ withdrawalRequestId }) => {
        console.log('Withdrawal completed:', withdrawalRequestId);
      }}
      onFailed={({ withdrawalRequestId, statusDetails }) => {
        // statusDetails is the only explanation of the failure available.
        console.log('Withdrawal failed:', withdrawalRequestId, statusDetails);
      }}
      onError={({ errorCode, reason }) => {
        console.log('Error:', errorCode, 'Reason:', reason);
      }}
      onClose={() => console.log('Widget closed')}
      onEvent={({ type, data }) => console.log('Event:', type, data)}
      onLoaded={() => console.log('Widget loaded and ready')}
    />
  );
}
```

## Complete Example

```tsx
import React from 'react';
import { CryptoWithdrawals } from '@zerohash-sdk/crypto-withdrawals-react';

function App() {
  const jwt = 'your-jwt-token';

  return (
    <div className="App">
      <h1>My App</h1>

      <CryptoWithdrawals
        jwt={jwt}
        env="prod"
        theme="auto"
        onCompleted={({ withdrawalRequestId }) => {
          console.log('Withdrawal request:', withdrawalRequestId);
        }}
        onFailed={({ withdrawalRequestId }) => console.log('Withdrawal failed:', withdrawalRequestId)}
        onError={({ errorCode, reason }) => console.log('Error:', errorCode, reason)}
        onClose={() => console.log('Widget closed')}
        onEvent={({ type, data }) => console.log('Event type:', type, 'Event data:', data)}
        onLoaded={() => console.log('Widget loaded and ready')}
      />
    </div>
  );
}

export default App;
```

## API Reference

### CryptoWithdrawals Component Props

| Prop          | Type                                                                    | Required | Default  | Description                                              |
| ------------- | ----------------------------------------------------------------------- | -------- | -------- | -------------------------------------------------------- |
| `jwt`         | `string`                                                                | Yes      | -        | JWT token for authentication with Connect                |
| `env`         | `"prod" \| "cert" \| "dev" \| "local"`                                  | No       | `"prod"` | Target environment                                       |
| `theme`       | `"auto" \| "light" \| "dark"`                                           | No       | `"auto"` | Theme mode for the interface                             |
| `onCompleted` | `({ withdrawalRequestId, status, assetId, networkId, amount }) => void` | No       | -        | Callback when the withdrawal flow completes successfully |
| `onFailed`    | `({ withdrawalRequestId }) => void`                                     | No       | -        | Callback when a withdrawal ends in a failed state        |
| `onError`     | `({ errorCode, reason }) => void`                                       | No       | -        | Callback for error events                                |
| `onClose`     | `() => void`                                                            | No       | -        | Callback when the widget is closed                       |
| `onEvent`     | `({ type, data }) => void`                                              | No       | -        | Callback for general events                              |
| `onLoaded`    | `() => void`                                                            | No       | -        | Callback when the widget is loaded and ready             |

### `onCompleted` payload

`onCompleted` receives `{ withdrawalRequestId, status, assetId, networkId, amount }`.
What `status` and `amount` mean depends on the flow that completed:

| Flow             | `status`    | `amount`                                |
| ---------------- | ----------- | --------------------------------------- |
| Classic (manual) | `SUBMITTED` | The requested amount, before fees       |
| Auth             | `CONFIRMED` | The net amount the destination received |

`SUBMITTED` means the withdrawal was submitted, not confirmed on-chain.
`assetId` is the asset ticker (e.g. `BTC`, `USDC`) and `networkId` the network
chain code (e.g. `bitcoin`, `ethereum`).

### `onFailed` and `onError` on a failed withdrawal

A failed withdrawal fires **both** `onFailed` and `onError`, so existing
integrations that only implemented `onError` keep working.

`onFailed` is the correct callback: it carries the withdrawal's details,
including `statusDetails`, the only explanation of the failure available. Build
against `onFailed`, and if you handle both, guard against counting one failure
twice. Firing `onError` for a failed withdrawal is deprecated and will be
removed in a future major version.

## More Information & Support

For comprehensive documentation or support about Connect, visit our [Documentation Page](https://docs.zerohash.com/).