Build integrations
What a Connect package is, and how it reaches a tenant.
When Beetl has no integration for a system you use, you can write one. An integration is a
Connect package: a small TypeScript project written against the
@beetlio/connect SDK. The SDK is open source under the
Apache-2.0 license, so you can read its source and type definitions, run its examples, and open
issues on GitHub.
SDK source on GitHub
Source code, examples and issues for @beetlio/connect.
SDK user guide
The SDK's own guide to configuration, authentication, pagination and checkpoints.
What a package describes
A package describes one system. Its integration.ts file default-exports a single
defineIntegration(...) call with three parts:
| Part | What it declares |
|---|---|
| Metadata | A key, a display name, a description and an optional icon. |
| Connection | Where the API lives, how to authenticate, the settings a user fills in, and an optional connection test. |
| Syncs | One entry per stream of records, each with a record schema, and optionally settings and a checkpoint. |
The SDK derives a manifest from that definition, and Beetl builds the app's forms from it: the settings and credential fields on a new connection, and the syncs a user can add. Once a package is installed, that contract is fixed. A package does not choose how records are written. The person who adds a sync chooses Append or Replace in the app. For how these objects fit together in a tenant, see Connection types, connections and syncs.
Packages built with an SDK older than 0.5 are not supported and must be rebuilt. See Rebuilding older packages.
From code to a running sync
Write and test locally
Write integration.ts, then use the beetl-connect CLI to run a sync on your machine and inspect
the records it produces. See Local development and
Authoring a sync.
Pack
beetl-connect pack turns the project into a .tgz source package.
Upload
A TenantAdmin uploads the package under Settings → Tenant → Custom connection types. Beetl builds it and adds it as a connection type. See Pack and upload.
Connect and sync
Anyone in the tenant can create a connection from the new type and add syncs. See Integrations.
In this section
Guides
| Page | What it covers |
|---|---|
| Local development | Installing the SDK, running a sync on your machine with the beetl-connect CLI, and packing. |
| Authoring a sync | One complete package: settings, credentials, a record schema, checkpoints, logging and errors. |
| Authentication | Declaring credentials or OAuth, how tokens are refreshed, and how requests paginate, retry and handle rate limits. |
| Pack and upload | Packing a package, uploading it to a tenant, reading the build result, and removing a connection type. |
| Building with a coding agent | The workflow for writing an integration with a coding agent. |
Reference
| Page | What it covers |
|---|---|
| Write modes | Append and Replace, chosen for each sync when it is set up: what each does to the sync's dataset, how they work with checkpoints and partitioning, and the limits each run must fit. |
| The contract rule | What is fixed once a connection type is installed, and how to ship a change as a new connection type. |
| The sandbox | Where package code runs, what it can reach, the limits it has to fit in, and how failures look. |
| SDK reference | The public API of @beetlio/connect 0.6: exports, the integration definition, the sync context, auth helpers and CLI commands. |
Last updated on