TypeScript SDK

The @aviato/sdk package creates an HTTP plugin. Your database agent calls it with signed requests. The plugin can use the agent's Data API with the caller's permissions.

Add the SDKCopy Anchor Link

In this monorepo, depend on @aviato/sdk with workspace:*. For an external application, use a published package version that matches your agent release. The package source lives in packages/sdk-ts.

Define a pluginCopy Anchor Link

This example defines a single-record action and reads the selected customer through the agent. The exact example below is typechecked against the SDK in CI.

import { createAviatoPlugin } from "@aviato/sdk";

export function createPlugin(secret: string) {
    return createAviatoPlugin({ secret, basePath: "/aviato" }).action({
        collection: "customers",
        name: "Confirm selection",
        scope: "single",
        execute: async (context) => {
            const records = await context.getRecords();
            if (records.length !== 1) {
                return context.error("Select one customer you can read");
            }
            return context.success("Customer selected");
        },
    });
}

Mount its HTTP handlerCopy Anchor Link

plugin.fetch(request) accepts a standard Request and returns a Response. Forward requests below /aviato/ from your HTTP framework to that handler without changing their signed body or path.

For a Hono application, the mounting pattern is:

app.all('/aviato/*', (context) => plugin.fetch(context.req.raw));

The repository's Hono fixture is a runnable integration example.

Connect the plugin to the agentCopy Anchor Link

Set both variables on the database agent:

AVIATO_PLUGIN_URL=https://your-app.example.com/aviato
AVIATO_PLUGIN_SECRET=replace-with-your-standard-webhooks-secret

Use the same secret when creating the plugin. The plugin URL must be reachable by the agent. Signed plugin calls do not use an end-user browser session.

Extend incrementallyCopy Anchor Link

The SDK supports actions, computed fields, hooks, segments, custom search, write overrides, charts, and custom datasources. Start with one operation and test both allowed and denied callers.

Direct calls from your plugin to another service or database do not automatically inherit Aviato's permissions. Use the agent Data API for governed record access and validate any other side effects yourself.