@swype-org/deposit 0.3.0

package/README.md

@@ -0,0 +1,175 @@
+# @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.tryblink.xyz',
+  hostedFlowOrigin: 'https://pay.tryblink.xyz',
+  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
+```