Aviato / docs
Plugins & integrations

Go SDK

Serve an Aviato plugin from a Go application.

View Markdown

The Go SDK lives in the github.com/getaviato/aviato-go module and requires Go 1.25 or newer. The source is available in the Go SDK repository.

go get github.com/getaviato/[email protected]

Create and mount a plugin

package main

import (
    "context"
    "log"
    "net/http"
    "os"

    aviato "github.com/getaviato/aviato-go"
)

func main() {
    plugin := aviato.MustNew(aviato.Options{
        Secret: os.Getenv("AVIATO_PLUGIN_SECRET"),
        BasePath: "/aviato",
    })
    plugin.Action("customers", "Confirm selection", aviato.ScopeSingle,
        func(ctx context.Context, action *aviato.ActionContext) (aviato.Result, error) {
            if _, err := action.Records(ctx); err != nil {
                return nil, err
            }
            return action.Success("Customer selected", "customers"), nil
        })
    http.Handle("/aviato/", plugin.Handler())
    log.Fatal(http.ListenAndServe(":4100", nil))
}

Configure AVIATO_PLUGIN_URL and AVIATO_PLUGIN_SECRET on the connector, using the same secret as your Go process. Terminate HTTPS in front of your service when it is exposed outside a trusted network.

Name collections with constants

aviato typegen --out internal/aviato/schema.go generates a constant for each collection and field of your database, such as aviatoschema.Orders and aviatoschema.OrdersCustomerID, so the compiler catches a misspelled name. While you develop, aviato dev reloads the plugin's manifest every second. See Typed plugins and local development.

Framework adapters

The SDK includes Gin and Echo adapters. See the mounting examples for standard HTTP, Gin, and Echo applications.

Custom summaries and forms

Register a record overview with plugin.Summary(collection, document). Build its JSON with aviato.UIDocument, aviato.UIComponent, and aviato.UIBind, or load a shared JSON document. Action layouts use aviato.WithFormUI(aviato.UIForm(document)) alongside the action's data schema. See Custom summaries and forms for metric strips, property rows, reusable components, state, and the native component vocabulary. The dashboard renders these components without an iframe or customer browser code.

Test your handlers

Use the aviatotest harness for local handler tests with a fake caller and seeded Data API. Test both the returned action result and changes made through the Data API with h.Data().AssertUpdated(t, …) and the other write assertions. h.ActingAs(caller) runs handlers as another caller. The harness uses the same method names as the TypeScript and Laravel test kits. See the SDK README for the harness API.

Provider integrations

Register a typed StripePlugin with plugin.Use(stripe). It implements the common IntegrationPlugin contract and provides customer, subscription, and invoice widgets. Bind each widget to an ID column on the current record or one related record. Credentials stay in the customer connector's environment, and provider requests run on that connector.

See Stripe widgets for language-specific examples, credential requirements, permissions, and release availability, or start with the Plugins & integrations overview.

For customer support data, Zendesk widgets provide a typed ZendeskPlugin with user profiles, requested-ticket lists, and individual tickets. Its OAuth scopes are verified by the customer connector before each data request.

To show an Intercom contact with open conversation and ticket counts, see Intercom widgets and its typed IntercomPlugin. The connector reads the access token from its own environment.

Edit on GitHub

On this page