npm package: @sync2books/vue
Description: Vue 3 composables for integrating Sync2Books Link component
Author: Sync2Books
Latest version: 1.0.0

# @sync2books/vue

Vue 3 composables for integrating Sync2Books Link component into your Vue applications.

## Installation

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

## Requirements

- Vue 3.3.0 or higher

## Quick Start

```vue
<template>
  <div>
    <button @click="handleOpenLink" :disabled="!isReady">
      Connect QuickBooks
    </button>
    <button @click="closeLink">Close</button>
  </div>
</template>

<script setup lang="ts">
import { useSync2Books } from '@sync2books/vue'

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)
  },
})

const handleOpenLink = () => {
  openLink()
}
</script>
```

## API Reference

### `useSync2Books(config)`

Returns a reactive object with the following properties:

- `openLink(args?)` - Opens the Sync2Books Link modal
- `closeLink()` - Closes the Link modal
- `isReady` - Ref boolean indicating if the Link widget is ready
- `isInitiated` - Ref boolean indicating if the widget has been initialized
- `instanceId` - Ref string with 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` | No | Your application name |
| `apiKey` | `string` | Yes | Your Sync2Books API key |
| `apiBaseUrl` | `string` | No | Base URL for the API |
| `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`:

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

## Examples

### Multiple Integrations

```vue
<script setup lang="ts">
import { useSync2Books } from '@sync2books/vue'

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 },
  ],
})
</script>
```

### Handling Success

```vue
<script setup lang="ts">
import { useSync2Books } from '@sync2books/vue'

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)
  },
})
</script>
```

## License

MIT