connectors

README

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
• Coming soon: 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.

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.

Provider	Auth Connector	Deep Connector	Authorization Method
Salesforce	example	example	OAuth2, Authorization Code
Adobe	example		OAuth2, Client Credentials
Anthropic	example		API Key
Blueshift	example		Basic Auth

Contributors

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

Documentation

Index

• Variables
• type AuthMetadataConnector
• type Connector
• type DeleteConnector
• type DeleteParams
• type DeleteResult
• type ErrorWithStatus
• type ListObjectMetadataResult
• type ObjectMetadataConnector
• type ReadConnector
• type ReadParams
• type ReadResult
• type URLConnector
• type WebhookVerifierConnector
• type WriteConnector
• type WriteParams
• type WriteResult

Variables

var Fields = datautils.NewStringSet // nolint:gochecknoglobals

Types

type AuthMetadataConnector

type AuthMetadataConnector interface {
	Connector

	// GetPostAuthInfo returns authentication metadata.
	GetPostAuthInfo(ctx context.Context) (*common.PostAuthInfo, error)
}

AuthMetadataConnector is an interface that extends the Connector interface with the ability to retrieve metadata information about authentication.

type Connector

type Connector interface {
	fmt.Stringer

	// JSONHTTPClient returns the underlying JSON HTTP client. This is useful for
	// testing, or for calling methods that aren't exposed by the Connector
	// interface directly. Authentication and token refreshes will be handled automatically.
	JSONHTTPClient() *common.JSONHTTPClient

	// HTTPClient returns the underlying HTTP client. This is useful for proxy requests.
	HTTPClient() *common.HTTPClient

	// Provider returns the connector provider.
	Provider() providers.Provider
}

Connector is an interface that can be used to implement a connector with basic configuration about the provider.

type DeleteConnector

type DeleteConnector interface {
	Connector

	Delete(ctx context.Context, params DeleteParams) (*DeleteResult, error)
}

DeleteConnector is an interface that extends the Connector interface with delete capabilities.

type DeleteParams

type DeleteParams = common.DeleteParams

We re-export the following types so that they can be used by consumers of this library.

type DeleteResult

type DeleteResult = common.DeleteResult

We re-export the following types so that they can be used by consumers of this library.

type ErrorWithStatus

type ErrorWithStatus = common.HTTPStatusError //nolint:errname

We re-export the following types so that they can be used by consumers of this library.

type ListObjectMetadataResult

type ListObjectMetadataResult = common.ListObjectMetadataResult

We re-export the following types so that they can be used by consumers of this library.

type ObjectMetadataConnector

type ObjectMetadataConnector interface {
	Connector

	ListObjectMetadata(ctx context.Context, objectNames []string) (*ListObjectMetadataResult, error)
}

ObjectMetadataConnector is an interface that extends the Connector interface with the ability to list object metadata.

type ReadConnector

type ReadConnector interface {
	Connector

	// Read reads a page of data from the connector. This can be called multiple
	// times to read all the data. The caller is responsible for paging, by
	// passing the NextPage value correctly, and by terminating the loop when
	// Done is true. The caller is also responsible for handling errors.
	// Authentication corner cases are handled internally, but all other errors
	// are returned to the caller.
	Read(ctx context.Context, params ReadParams) (*ReadResult, error)
}

ReadConnector is an interface that extends the Connector interface with read capabilities.

type ReadParams

type ReadParams = common.ReadParams

We re-export the following types so that they can be used by consumers of this library.

type ReadResult

type ReadResult = common.ReadResult

We re-export the following types so that they can be used by consumers of this library.

type URLConnector

type URLConnector interface {
	Connector

	// GetURL returns the URL of some resource. The resource is provider-specific.
	// The URL is returned as a string, or an error is returned if the URL cannot be
	// retrieved. The precise meaning of the resource is provider-specific, and the
	// caller should consult the provider's documentation for more information.
	// The args parameter is a map of key-value pairs that can be used to customize
	// the URL. The keys and values are provider-specific, and the caller should
	// consult the provider's documentation for more information. Certain providers
	// may ignore the args parameter entirely if it's unnecessary.
	GetURL(resource string, args map[string]any) (string, error)
}

URLConnector is an interface that extends the Connector interface with the ability to retrieve URLs for resources.

type WebhookVerifierConnector

type WebhookVerifierConnector interface {
	Connector

	// VerifyWebhookMessage verifies the signature of a webhook message.
	VerifyWebhookMessage(ctx context.Context, params *common.WebhookVerificationParameters) (bool, error)
}

type WriteConnector

type WriteConnector interface {
	Connector

	Write(ctx context.Context, params WriteParams) (*WriteResult, error)
}

WriteConnector is an interface that extends the Connector interface with write capabilities.

type WriteParams

type WriteParams = common.WriteParams

We re-export the following types so that they can be used by consumers of this library.

type WriteResult

type WriteResult = common.WriteResult

We re-export the following types so that they can be used by consumers of this library.