npm package: @keychain-pay/send
Description: Keychain Send Widget - Embeddable remittance for sending money globally to India and more
Author: Keychain
Latest version: 1.0.1

# @keychain-pay/send

Embeddable widget for sending money globally via Keychain. Add a "Send Money" button to your app in minutes.

## Installation

```bash
npm install @keychain-pay/send
# or
yarn add @keychain-pay/send
# or
pnpm add @keychain-pay/send
```

## Quick Start

### React

```tsx
import { SendButton } from '@keychain-pay/send/react';

function App() {
  return (
    <SendButton
      onSuccess={(result) => {
        console.log('Payment link created!', result.linkUrl);
        // Share this link with the recipient
      }}
    />
  );
}
```

### Vanilla JavaScript

```html
<script src="https://unpkg.com/@keychain-pay/send"></script>
<button id="send-btn">Send Money</button>

<script>
  const keychain = new KeychainSend({
    onSuccess: (result) => {
      alert('Share this link: ' + result.linkUrl);
    }
  });

  document.getElementById('send-btn').onclick = () => {
    keychain.open();
  };
</script>
```

## React Components

### SendButton

Ready-to-use button that opens the send widget.

```tsx
import { SendButton } from '@keychain-pay/send/react';

<SendButton
  amount={5000}           // Pre-fill $50
  country="IN"            // Recipient country
  variant="primary"       // 'primary' | 'outline' | 'minimal'
  size="md"               // 'sm' | 'md' | 'lg'
  onSuccess={(result) => {
    console.log('Link:', result.linkUrl);
  }}
>
  Send $50 to India
</SendButton>
```

### useSend Hook

For more control over the send flow.

```tsx
import { useSend } from '@keychain-pay/send/react';

function App() {
  const { open, isOpen, close } = useSend({
    defaultCountry: 'IN',
    onSuccess: (result) => {
      console.log('Success!', result);
    },
  });

  return (
    <div>
      <button onClick={() => open({ amount: 10000 })}>
        Send $100
      </button>
      {isOpen && <p>Widget is open...</p>}
    </div>
  );
}
```

### SendWidget (Inline Embed)

Embed the send flow directly in your page without a modal.

```tsx
import { SendWidget } from '@keychain-pay/send/react';

<SendWidget
  height={600}
  country="IN"
  onSuccess={(result) => console.log(result)}
/>
```

## Vanilla JavaScript API

### KeychainSend Class

```js
import { KeychainSend } from '@keychain-pay/send';

const keychain = new KeychainSend({
  defaultCountry: 'IN',
  onSuccess: (result) => {
    console.log('Link created:', result.linkUrl);
  },
  onError: (error) => {
    console.error('Error:', error.message);
  },
  onClose: () => {
    console.log('Widget closed');
  },
});

// Open the widget
keychain.open({
  amount: 10000,  // $100 in cents
  memo: 'Birthday gift',
});

// Check if open
keychain.isOpen();

// Close programmatically
keychain.close();

// Cleanup
keychain.destroy();
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `baseUrl` | string | `https://checkout.keychainpay.com` | Keychain checkout URL |
| `defaultCountry` | string | `IN` | Default recipient country |
| `defaultCurrency` | string | `INR` | Default recipient currency |
| `onSuccess` | function | - | Called when link is created |
| `onError` | function | - | Called on error |
| `onClose` | function | - | Called when widget closes |

## SendOptions

Options passed to `open()`:

| Option | Type | Description |
|--------|------|-------------|
| `amount` | number | Amount in USD cents (e.g., 10000 = $100) |
| `memo` | string | Description/note for the payment |
| `country` | string | Recipient country code (e.g., 'IN') |
| `currency` | string | Recipient currency code (e.g., 'INR') |

## SendResult

Result returned on success:

```ts
interface SendResult {
  success: boolean;
  linkId: string;          // Payment link ID
  linkUrl: string;         // Shareable URL
  amountUsd: number;       // Amount in USD cents
  amountRecipient: number; // Amount in recipient currency (smallest unit)
  recipientCurrency: string;
  exchangeRate: number;
  link: object;            // Full link data
}
```

## Supported Countries

Currently supporting remittance to:
- India (IN) - INR

More countries coming soon.

## License

MIT