npm package: @pocketdns/react-sdk
Description: React SDK for PocketDNS - iframe wrapper around the domain management frontend
Author: PocketDNS
Latest version: 1.0.1

# PocketDNS React SDK

A simple React SDK that provides an iframe wrapper around the PocketDNS frontend for seamless domain registration and management.

## Installation

```bash
npm install @pocketdns/react-sdk
```

## Quick Start

```tsx
import React from 'react';
import { PocketDNS } from '@pocketdns/react-sdk';

function App() {
  const handleDomainRegistered = (data) => {
    console.log('Domain registered:', data);
  };

  const handleError = (error) => {
    console.error('SDK Error:', error);
  };

  return (
    <div>
      <h1>Domain Registration</h1>
      <PocketDNS
        config={{
          baseUrl: 'https://your-domain.com',
          theme: {
            primaryColor: '#4F46E5',
            backgroundColor: '#FFFFFF',
            textColor: '#1F2937',
            borderRadius: '8px'
          }
        }}
        width="100%"
        height={600}
        onDomainRegistered={handleDomainRegistered}
        onError={handleError}
      />
    </div>
  );
}

export default App;
```

## Configuration

### EmbeddedDomainsProps

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `config` | `EmbeddedDomainsConfig` | Required | Configuration object for the SDK |
| `width` | `string \| number` | `'100%'` | Width of the iframe |
| `height` | `string \| number` | `600` | Height of the iframe |
| `className` | `string` | `''` | CSS class name for the iframe |
| `style` | `React.CSSProperties` | `{}` | Inline styles for the iframe |
| `onDomainRegistered` | `function` | Optional | Callback when a domain is registered |
| `onDomainSelected` | `function` | Optional | Callback when a domain is selected |
| `onCheckoutCompleted` | `function` | Optional | Callback when checkout is completed |
| `onError` | `function` | Optional | Callback for error handling |
| `defaultDomain` | `string` | Optional | Pre-populate the search with this domain |

### PocketDNSConfig

```tsx
interface PocketDNSConfig {
  baseUrl?: string;
  theme?: {
    primaryColor?: string;
    backgroundColor?: string;
    textColor?: string;
    borderRadius?: string;
  };
}
```

## Event Callbacks

### onDomainRegistered

Called when a user successfully registers a domain:

```tsx
const handleDomainRegistered = (data: DomainRegistrationData) => {
  console.log('Domain:', data.domain);
  console.log('Registrant:', data.registrant_name);
  console.log('Email:', data.registrant_email);
};
```

### onDomainSelected

Called when a user selects a domain for registration:

```tsx
const handleDomainSelected = (domain: string) => {
  console.log('Selected domain:', domain);
};
```

### onCheckoutCompleted

Called when the checkout process is completed:

```tsx
const handleCheckoutCompleted = (data: any) => {
  console.log('Checkout completed:', data);
};
```

### onError

Called when an error occurs:

```tsx
const handleError = (error: string) => {
  console.error('Error:', error);
};
```

## Advanced Usage

### Custom Styling

You can customize the appearance using the theme configuration:

```tsx
<EmbeddedDomains
  config={{
    theme: {
      primaryColor: '#10B981', // Emerald green
      backgroundColor: '#F9FAFB', // Light gray
      textColor: '#111827', // Dark gray
      borderRadius: '12px'
    }
  }}
  className="my-custom-iframe"
  style={{ boxShadow: '0 10px 25px rgba(0,0,0,0.1)' }}
/>
```

## TypeScript Support

The SDK is built with TypeScript and provides full type definitions:

```tsx
import { 
  PocketDNS, 
  PocketDNSProps, 
  DomainRegistrationData 
} from '@pocketdns/react-sdk';

const MyComponent: React.FC = () => {
  const token = "<token>"; // Retrieved securely from backend

  const handleRegistration = (data: DomainRegistrationData) => {
    // Fully typed callback data
    console.log(data.domain, data.registrant_name);
  };

  const config: PocketDNSProps['config'] = {
    baseUrl: 'https://domains.example.com'
  };

  return (
    <PocketDNS
      token={token}
      config={config}
      onDomainRegistered={handleRegistration}
    />
  );
};
```

## Security Considerations

The iframe uses the following sandbox attributes for security:
- `allow-scripts` - Allows JavaScript execution
- `allow-same-origin` - Allows same-origin requests
- `allow-forms` - Allows form submissions
- `allow-popups` - Allows popups for payment processing
- `allow-popups-to-escape-sandbox` - Required for payment flows

## Browser Support

This SDK supports all modern browsers that support:
- ES6+ JavaScript features
- PostMessage API
- iframe sandbox attributes
- React 16.8+ (hooks)

## Development

To build the SDK locally:

```bash
git clone <repository>
cd sdk
npm install
npm run build
```

## License

MIT