# TypeScript SDK (https://docs.getaviato.com/integrations/typescript)





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 SDK [#add-the-sdk]

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](https://github.com/getaviato/aviato/tree/master/packages/sdk-ts).

## Define a plugin [#define-a-plugin]

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.

<PluginExample />

## Mount its HTTP handler [#mount-its-http-handler]

`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:

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

The repository's [Hono fixture](https://github.com/getaviato/aviato/tree/master/packages/fixtures/hono) is a runnable integration example.

## Connect the plugin to the agent [#connect-the-plugin-to-the-agent]

Set both variables on the database agent:

```dotenv
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 incrementally [#extend-incrementally]

The SDK supports actions, computed fields, hooks, segments, custom search, write overrides, charts, and [custom datasources](/integrations/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.


## TypeScript plugin example

```ts
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");
        },
    });
}
```