npm package: @sync2books/react
Description: React hooks for integrating Sync2Books Link component
Author: Sync2Books
Latest version: 1.0.0

# @sync2books/react

React hooks for integrating Sync2Books Link component into your React applications.

## Installation

```bash
npm install @sync2books/react
# or
yarn add @sync2books/react
# or
pnpm add @sync2books/react
```

## Requirements

- React 18.0.0 or higher
- React DOM 18.0.0 or higher

## Quick Start

```tsx
import { useSync2Books } from '@sync2books/react'

function App() {
  const { openLink, closeLink, isReady } = useSync2Books({
    companyId: 'your-company-id',
    integrationKey: 'quickbooks',
    applicationId: 'your-application-id',
    applicationName: 'Your App Name',
    apiKey: 'your-api-key',
    embedBaseUrl: 'https://app.sync2books.com', // Optional, defaults to window.location.origin
    onSuccess: (result) => {
      console.log('Connection successful!', result)
      // result.connectionId and result.integrationKey are available
    },
    onError: (error) => {
      console.error('Connection failed:', error)
    },
  })

  return (
    <div>
      <button onClick={() => openLink()} disabled={!isReady}>
        Connect QuickBooks
      </button>
      <button onClick={closeLink}>Close</button>
    </div>
  )
}
```

## API Reference

### `useSync2Books(config)`

Returns an object with the following properties:

- `openLink(args?)` - Opens the Sync2Books Link modal
- `closeLink()` - Closes the Link modal
- `isReady` - Boolean indicating if the Link widget is ready
- `isInitiated` - Boolean indicating if the widget has been initialized
- `instanceId` - Unique identifier for this widget instance

### Configuration Options

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `companyId` | `string` | Yes | The Sync2Books company ID |
| `integrationKey` | `'quickbooks' \| 'xero' \| 'sage'` | Yes | Default integration to show |
| `applicationId` | `string` | Yes | Your Sync2Books application ID |
| `applicationName` | `string` | Yes | Your application name |
| `apiKey` | `string` | Yes | Your Sync2Books API key |
| `embedBaseUrl` | `string` | No | Base URL for the embed (defaults to `window.location.origin`) |
| `integrations` | `Sync2BooksIntegrationOption[]` | No | List of available integrations |
| `instanceId` | `string` | No | Unique instance ID (auto-generated if not provided) |
| `onReady` | `() => void` | No | Callback when widget is ready |
| `onClose` | `() => void` | No | Callback when widget is closed |
| `onSuccess` | `(result: Sync2BooksLinkSuccess) => void` | No | Callback on successful connection |
| `onError` | `(error: Error) => void` | No | Callback on error |
| `onConnection` | `(connection: ConnectionCallbackArgs) => void` | No | Callback when connection is established |
| `onFinish` | `() => void` | No | Callback when flow completes |
| `onLinkError` | `(error: ErrorCallbackArgs) => void` | No | Structured error callback |

### `openLink(args?)`

Opens the Link modal. You can override the default `companyId` and `integrationKey`:

```tsx
openLink({
  companyId: 'different-company-id',
  integrationKey: 'xero',
  integrations: [
    { key: 'quickbooks', label: 'QuickBooks', enabled: true },
    { key: 'xero', label: 'Xero', enabled: true },
  ],
})
```

## Examples

### Multiple Integrations

```tsx
const { openLink } = useSync2Books({
  companyId: 'company-123',
  integrationKey: 'quickbooks',
  applicationId: 'app-123',
  applicationName: 'My App',
  apiKey: 'sk_live_...',
  integrations: [
    { key: 'quickbooks', label: 'QuickBooks Online', enabled: true },
    { key: 'xero', label: 'Xero', enabled: true },
    { key: 'sage', label: 'Sage', enabled: false },
  ],
})
```

### Handling Success

```tsx
const { openLink } = useSync2Books({
  // ... config
  onSuccess: (result) => {
    console.log('Connected!', result.connectionId, result.integrationKey)
    // Save connectionId to your database
    // Redirect user or update UI
  },
  onConnection: ({ connectionId, integrationKey }) => {
    // Alternative callback with Codat-style payload
    console.log('Connection established:', connectionId)
  },
})
```

## License

MIT