npm package: @swype-org/deposit
Description: Lightweight merchant deposit SDK — open a hosted payment flow, handle completion, zero dependencies
Latest version: 0.3.6

# @swype-org/deposit

Lightweight merchant deposit SDK — open a hosted Blink payment flow, handle completion, zero runtime dependencies.

## Quick Start

```bash
npm install @swype-org/deposit
```

```typescript
import { Deposit } from '@swype-org/deposit';

const deposit = new Deposit({ signer: '/api/sign-payment' });

document.getElementById('deposit-btn')!.addEventListener('click', async () => {
  try {
    const { transfer: result } = await deposit.requestDeposit({
      amount: 50,
      chainId: 8453,
      address: '0x...', // destination wallet
      token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    });
    console.log('Transfer complete:', result.id, result.status);
  } catch (error) {
    console.error('Transfer failed:', error);
  }
});
```

> **Important:** `requestDeposit()` must be called from a user-gesture handler (click, keypress, etc.) so the browser allows the iframe to open.

## React Hook

A dedicated React entry point eliminates all boilerplate:

```bash
npm install @swype-org/deposit react
```

```tsx
import { useBlinkDeposit } from '@swype-org/deposit/react';

function DepositButton() {
  const { status, result, error, displayMessage, requestDeposit } = useBlinkDeposit({
    signer: '/api/sign-payment',
  });

  return (
    <>
      <button
        onClick={() =>
          requestDeposit({ amount: 50, chainId: 8453, address: '0x...', token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913' })
        }
        disabled={status === 'signer-loading'}
      >
        {status === 'signer-loading' ? 'Preparing…' : 'Deposit'}
      </button>
      {error && <p>{displayMessage}</p>}
      {result && <p>Transfer {result.transfer.id} complete!</p>}
    </>
  );
}
```

The hook returns reactive `status`, `result`, `error`, `displayMessage`, and `isActive` values, plus `requestDeposit`, `focus`, and `close` actions. It manages the `Deposit` lifecycle and cleans up on unmount.

## How It Works

```
Merchant App / SDK              Merchant Signer                Hosted Flow (iframe)
     │                               │                               │
     │  1. requestDeposit(request)    │                               │
     │──────────────────────────────► │                               │
     │                                │  2. signer(data) or POST URL  │
     │                                │  (includes webviewBaseUrl)    │
     │  3. { signature, payload, ...} │                               │
     │◄───────────────────────────────│                               │
     │                                                                │
     │  4. SDK builds URL, opens iframe                               │
     │───────────────────────────────────────────────────────────────► │
     │                                                                │
     │  5. User completes payment in hosted flow                      │
     │                                                                │
     │  6. postMessage: blink:transfer-complete                       │
     │◄──────────────────────────────────────────────────────────────  │
     │                                                                │
     │  7. Promise resolves with DepositResult                        │
```

## Configuration

```typescript
const deposit = new Deposit({
  signer: '/api/sign-payment',
  webviewBaseUrl: 'https://pay.blink.cash',
  hostedFlowOrigin: 'https://pay.blink.cash',
  containerElement: document.getElementById('deposit-root')!,
  signerTimeoutMs: 15_000,
  flowTimeoutMs: 300_000,
  debug: false,
});
```

## Error Handling

Every error is a `DepositError` with a machine-readable `code`:

| Code                     | Meaning                                         |
| ------------------------ | ----------------------------------------------- |
| `DEPOSIT_DISMISSED`     | User closed the transfer before completing      |
| `SIGNER_REQUEST_FAILED`  | Signer returned a non-2xx response              |
| `SIGNER_NETWORK_ERROR`   | Network failure reaching the signer             |
| `SIGNER_RESPONSE_INVALID`| Signer response missing required fields         |
| `SIGNER_TIMEOUT`         | Signer did not respond within `signerTimeoutMs` |
| `FLOW_TIMEOUT`           | Entire flow exceeded `flowTimeoutMs`            |
| `INVALID_REQUEST`        | Bad input (amount, address, etc.)               |

```typescript
import { DepositError, getDisplayMessage } from '@swype-org/deposit';

try {
  await deposit.requestDeposit({ /* ... */ });
} catch (err) {
  if (err instanceof DepositError) {
    showToast(getDisplayMessage(err));
  }
}
```

## Events

```typescript
transfer.on('complete', (result) => { /* DepositResult */ });
transfer.on('error', (error) => { /* DepositError */ });
transfer.on('close', () => { /* iframe closed */ });
transfer.on('status-change', (status) => { /* DepositStatus */ });
```

## Lifecycle

```typescript
transfer.focus();   // No-op — retained for API compatibility
transfer.close();   // Close the iframe without waiting for completion
transfer.destroy(); // Tear down and release all resources (call on unmount)
```

## TypeScript

All types are exported:

```typescript
import type {
  DepositConfig,
  DepositStatus,
  DepositRequest,
  DepositResult,
  SignerFunction,
  SignerRequest,
  SignerResponse,
  TransferSummary,
} from '@swype-org/deposit'; 

import type { DepositErrorCode } from '@swype-org/deposit';
```

## Backward Compatibility

The previous `Checkout`-named symbols are re-exported as deprecated aliases:

```typescript
import { Checkout } from '@swype-org/deposit';       // deprecated alias for Transfer
import { CheckoutError } from '@swype-org/deposit';   // deprecated alias for DepositError
import { useBlinkCheckout } from '@swype-org/deposit/react'; // deprecated alias for useBlinkDeposit
```