@syncbooks/addon-sdk

Build add-ons for SyncBooks. This SDK provides everything you need: API client, React hooks, UI components, and the postMessage bridge for communicating with the SyncBooks host.

Installation

npm install @syncbooks/addon-sdk

Quick Start

import { SyncBooksProvider, useSyncBooks, customers, ui } from '@syncbooks/addon-sdk';

export default function App() {
  return (
    <SyncBooksProvider>
      <MyAddon />
    </SyncBooksProvider>
  );
}

function MyAddon() {
  const { ready, organizationId, resource } = useSyncBooks();
  const [customerList, setCustomerList] = useState([]);

  useEffect(() => {
    if (ready) {
      customers.list({ limit: 10 }).then(res => setCustomerList(res.data));
    }
  }, [ready]);

  if (!ready) return <div>Loading...</div>;

  return (
    <div>
      <h1>Customers for org: {organizationId}</h1>
      <ul>
        {customerList.map(c => <li key={c._id}>{c.name}</li>)}
      </ul>
      <button onClick={() => ui.notify('Hello from addon!', 'success')}>
        Show Toast
      </button>
    </div>
  );
}

API Reference

Provider & Hook

| Export | Description | |--------|-------------| | <SyncBooksProvider> | Wrap your addon root. Initializes bridge + context. | | useSyncBooks() | Returns { ready, organizationId, userId, userRole, appId, scopes, token, resource } |

Navigation & UI

import { navigation, ui } from '@syncbooks/addon-sdk';

navigation.open('/invoices/123');       // Navigate SyncBooks to a page
ui.notify('Saved!', 'success');         // Show a toast in SyncBooks
ui.close();                             // Close the addon panel
ui.resize(500);                         // Resize the iframe

API Client (all resources)

Every resource follows the same pattern:

import { customers } from '@syncbooks/addon-sdk';

// List with pagination + filters
const { data, total, totalPages } = await customers.list({ page: 1, limit: 20, search: 'John' });

// Get single
const { data: customer } = await customers.get('customer_id');

// Create
const { data: newCustomer } = await customers.create({ name: 'Acme Corp', email: '[email protected]' });

// Update
const { data: updated } = await customers.update('customer_id', { phone: '+233...' });

// Delete
await customers.delete('customer_id');

Available Resources

Core: customers, invoices, products, payments, expenses, vendors, bills, estimates, creditNotes, purchaseOrders, accounts, journalEntries, generalLedger, bankTransactions, budgets, assets, inventory

HR/Payroll: employees, payroll

Projects: projects (also has .list() with projects.get(id) returning tasks/time via /projects/:id/tasks)

CRM: crm.leads, crm.opportunities, crm.contacts

Modules: helpdesk.tickets, subscriptions, fleet, ecommerce, reports

Utilities: me(), search(), config, notifications, notes, webhooks, events

UI Components

import { Button, Card, CardContent, Input, Table, Badge, Spinner } from '@syncbooks/addon-sdk/components';

All components are styled to match SyncBooks' design system.

Scopes

Your addon can only access data for scopes granted during installation. Common scopes:

customers.read    customers.write    customers.delete
invoices.read     invoices.write     invoices.delete
products.read     products.write     products.delete
payments.read     payments.write
expenses.read     expenses.write
employees.read    payroll.read
accounts.read     reports.read

Configuration

import { configureClient } from '@syncbooks/addon-sdk';

// For local development
configureClient({
  baseUrl: 'http://localhost:5000/api/addon/v1',
  token: 'your-test-token', // optional override
});