<a href="https://www.withampersand.com/?utm_source=github&utm_medium=readme&utm_campaign=connectors-repo&utm_content=logo">
<img src="https://res.cloudinary.com/dycvts6vp/image/upload/v1723671980/ampersand-logo-black.svg" height="30" align="center" alt="Ampersand logo" >
</a>

Overview

Ampersand is a declarative platform for SaaS builders who are creating product integrations. It allows you to:

• Read data from your customer’s SaaS
• Write data to your customer’s SaaS
• Subscribe to events (creates, deletes, and field changes) in your customer’s SaaS

Ampersand Connectors

This is a Go library that makes it easier to make API calls to SaaS products such as Salesforce and Hubspot. It handles constructing the correct API requests given desired objects and fields.

It can be either be used as a standalone library, or as a part of the Ampersand platform, which offers additional benefits such as: - Handling auth flows - Orchestration of scheduled reads, real-time writes, or bulk writes - Handling API quotas from SaaS APIs - A dashboard for observability and troubleshooting

The key components of the Ampersand platform include:

• Manifest file (amp.yaml): Define all your integrations, the APIs to connect to, the objects and fields for reading or writing, and the configuration options you want to expose to your customers.

• Ampersand server: a managed service that keeps track of each of your customer’s configurations, and makes the appropriate API calls to your customer’s SaaS, while optimizing for cost, handling retries and error message parsing.

• Embeddable UI components: open-source React components that you can embed to allow your end users to customize and manage their integrations. See the repo for more info.

• Dashboard: Provides deep observability into customer integrations, allowing you to monitor & troubleshoot with detailed logs.

Add enterprise-grade integrations to your SaaS this week. Get started for free.

<img src="https://res.cloudinary.com/dycvts6vp/image/upload/v1724756323/media/hqukkkmpk96zavslpmw5.png" alt="Ampersand Overview" width="80%">

Using connectors

Supported connectors

Browse the providers directory to see a list of all the connectors that Ampersand supports, and which features are supported for each connector.

Examples

Visit the Ampersand docs to learn about how to use connectors as a part of the Ampersand platform.

See the examples directory for examples of how to use connectors as a standalone library.

Concurrency Safety

This codebase uses the future and simultaneously packages to provide safe concurrency primitives. Do NOT use the bare go keyword - always use these primitives instead.

Using the future package

For launching async operations that return a result:

// Instead of: go func() { ... }()
// Use future.Go for simple async operations:
result := future.Go(func() (User, error) {
    return fetchUser(id)
})
user, err := result.Await()

// With context support:
result := future.GoContext(ctx, func(ctx context.Context) (User, error) {
    return fetchUserWithContext(ctx, id)
})
user, err := result.AwaitContext(ctx)

Using the simultaneously package

For running multiple operations in parallel with controlled concurrency:

// Instead of launching multiple goroutines with: go func() { ... }()
// Use simultaneously.Do to run functions in parallel:
err := simultaneously.Do(maxConcurrent,
    func(ctx context.Context) error { return processItem1(ctx) },
    func(ctx context.Context) error { return processItem2(ctx) },
    func(ctx context.Context) error { return processItem3(ctx) },
)

// With context:
err := simultaneously.DoCtx(ctx, maxConcurrent, callbacks...)

Why? These primitives automatically handle panic recovery and prevent unbounded goroutine spawning, protecting against production outages.

Linter

One-time Setup

Build the custom linters:

make custom-gcl

Rebuild the linters from scratch. This is useful when the linter has been expanded with new plugins:

make linter-rebuild

Day-to-Day Usage

Run all linters:

make lint

Automatically apply formatting fixes:

make fix

Tests

Run the full test suite:

make test

Run tests with prettier, more readable output:

make test-pretty

Run tests in parallel to verify test isolation and correctness:

make test-parallel

Notes on parallelized tests: * -parallel=N: Runs up to N (ex:8) test functions concurrently. Useful for speeding up large test suites and for catching concurrency-related bugs. * -count=M: Runs the test M (ex:3) times. This helps catch flakiness or non-deterministic behavior in tests.

Contributors

Thankful to the OSS community for making Ampersand better every day.