# Developer guide

Add one-tap USDC payments to your app, API, or agent with the **Checkout Widget** on the frontend and the **BeepClient** on the backend. Payments settle directly between non-custodial vaults and produce machine-verifiable receipts.

### Installation

```typescript
npm install @beep-it/checkout-widget @beep-it/sdk-core

```

### Quick Start

```tsx
import React from 'react';
import { CheckoutWidget } from '@beep-it/checkout-widget';

function App() {
  return (
    <CheckoutWidget
      publishableKey="your-publishable-key"
      primaryColor="#007bff"
      labels={{
        scanQr: 'Scan QR Code to Pay',
        paymentLabel: 'My Store Checkout',
      }}
      assets={[
        {
          assetId: 'product-uuid-123',
          quantity: 2,
          name: 'Premium Coffee',
          description: 'Fresh roasted arabica beans',
        },
      ]}
      serverUrl="https://your-beep-server.com" // optional
    />
  );
}
```

### Asset Types

The widget supports two types of assets:

#### 1. Existing Product References (`BeepPurchaseAsset`)

Reference pre-created products by their ID:

```tsx
const assets = [
  {
    assetId: 'product-uuid-123',
    quantity: 1,
    name: 'Coffee', // optional override
    description: 'Premium blend', // optional override
  },
];
```

#### 2. On-the-Fly Product Creation (`CreateProductPayload`)

Create products dynamically during checkout. These items are created as products in your merchant account on the server (persisted for audit and reuse). They may be hidden from public listings by default.

```tsx
const assets = [
  {
    name: 'Custom Item',
    price: '25.50',
    quantity: 2,
    description: 'Custom product description',
  },
];
```

### Props

| Prop                  | Type                                            | Required | Description                                                      |
| --------------------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------- |
| `publishableKey`      | `string`                                        | ✅        | BEEP publishable key for browser-safe authentication             |
| `primaryColor`        | `string`                                        | ❌        | Primary color for styling (hex format, e.g., "#007bff")          |
| `labels`              | `object`                                        | ✅        | Customizable text labels                                         |
| `labels.scanQr`       | `string`                                        | ✅        | Text shown above QR code                                         |
| `labels.paymentLabel` | `string`                                        | ❌        | Label displayed in Solana Pay wallets (default: "Beep Checkout") |
| `assets`              | `(BeepPurchaseAsset \| CreateProductPayload)[]` | ✅        | Items to purchase                                                |
| `serverUrl`           | `string`                                        | ❌        | Custom BEEP server URL (defaults to production)                  |

#### Asset Props

**BeepPurchaseAsset**

| Prop          | Type     | Required | Description                  |
| ------------- | -------- | -------- | ---------------------------- |
| `assetId`     | `string` | ✅        | UUID of existing product     |
| `quantity`    | `number` | ✅        | Number of items              |
| `name`        | `string` | ❌        | Override product name        |
| `description` | `string` | ❌        | Override product description |

**CreateProductPayload**

| Prop          | Type     | Required | Description                             |
| ------------- | -------- | -------- | --------------------------------------- |
| `name`        | `string` | ✅        | Product display name                    |
| `price`       | `string` | ✅        | Price in decimal format (e.g., "25.50") |
| `quantity`    | `number` | ❌        | Number of items (default: 1)            |
| `description` | `string` | ❌        | Product description                     |

### Features

#### Core Functionality

* **Sui Network Integration**: Generates native Sui USDC payment requests
* **Real-time Status Polling**: Verifies payment confirmation directly from the Sui RPC
* **Flexible Asset Support**: Mix existing products with on-the-fly product creation (persisted)
* **Payment Label Support**: Custom labels appear in wallet interfaces
* **Wallet Address Display**: Shows copyable recipient address for desktop users

#### User Experience

* **Loading States**: Smooth loading indicators during setup and polling
* **Error Handling**: Comprehensive error boundaries and user-friendly error messages
* **Success Animation**: Clear payment confirmation state
* **Responsive Design**: Works on desktop and mobile devices
* **Customizable Theming**: Primary color theming throughout the widget

#### Developer Experience

* **TypeScript Support**: Full type safety with comprehensive interfaces
* **Zero CSS Dependencies**: Inline styles prevent conflicts with host applications
* **Error Boundaries**: Isolated error handling prevents widget crashes from affecting host app
* **Comprehensive Logging**: Detailed console logging for debugging

### Usage Examples

#### Simple Single Product

```tsx
<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#10b981"
  labels={{ scanQr: 'Pay with Crypto' }}
  assets={[
    {
      assetId: 'coffee-product-uuid',
      quantity: 1,
    },
  ]}
/>
```

#### Multiple Products with Custom Labels

```tsx
<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#3b82f6"
  labels={{
    scanQr: 'Scan to complete your order',
    paymentLabel: 'Coffee Shop - Downtown',
  }}
  assets={[
    {
      assetId: 'coffee-uuid',
      quantity: 2,
      name: 'Espresso',
    },
    {
      assetId: 'pastry-uuid',
      quantity: 1,
      name: 'Croissant',
    },
  ]}
/>
```

#### Dynamic Product Creation

```tsx
<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#ef4444"
  labels={{
    scanQr: 'Pay for custom service',
    paymentLabel: 'Consulting Services',
  }}
  assets={[
    {
      name: '1-Hour Consultation',
      price: '150.00',
      quantity: 1,
      description: 'Professional consulting session',
    },
  ]}
/>
```

#### Mixed Asset Types

```tsx
<CheckoutWidget
  apiKey="your-api-key"
  primaryColor="#8b5cf6"
  labels={{ scanQr: 'Complete your purchase' }}
  assets={[
    // Existing product
    {
      assetId: 'existing-product-uuid',
      quantity: 1,
    },
    // Dynamic product
    {
      name: 'Rush Delivery',
      price: '15.00',
      quantity: 1,
    },
  ]}
/>
```

### Payment Flow

1. **Initialization Phase**: The widget prepares a signed USDC-on-Sui payment request.
2. **Display Phase**: Shows QR code and total amount to user
3. **Polling Phase**: Automatically checks transaction finality via Sui RPC
4. **Completion**: Displays success state when payment is confirmed on-chain

### Error Handling

The widget includes comprehensive error handling:

* **Configuration Errors**: Invalid API keys, missing assets
* **Network Errors**: API connection issues, timeouts
* **Payment Errors**: Failed transactions, expired payments
* **Component Errors**: Isolated error boundaries prevent crashes

### Sui Payment Integration

The widget generates Sui-native Payment URLs with:

* **Recipient**: Developer's Sui wallet address
* **Amount**: Total calculated from all assets in USDC
* **SPL Token**: Token address for payment
* **Reference**: Unique tracking identifier
* **Label**: Custom payment label for wallet display
* **Message**: Descriptive payment message

### Development

```sh
# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the package
pnpm build

# Run tests in watch mode
pnpm test:watch

# Run development showcase
pnpm dev
```

### Environment Variables

The widget respects these environment variables:

* `REACT_APP_BEEP_SERVER_URL`: Default server URL if not provided via props

### TypeScript Support

Full TypeScript support with exported interfaces:

```tsx
import { CheckoutWidget, MerchantWidgetProps, MerchantWidgetState } from '@beep-it/checkout-widget';

import { BeepPurchaseAsset, CreateProductPayload } from '@beep-it/sdk-core';
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://documentation.justbeep.it/product-overview/beep-pay/developer-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.