TypeScript SDK
Add actions, computed fields, and hooks to a JavaScript or TypeScript application.
The @getaviato/sdk npm package creates an HTTP plugin. Your database connector calls it with signed requests. The plugin can use the connector's Data API with the caller's permissions.
For NestJS applications, use the NestJS integration for modules, decorated handlers, and dependency-injected provider plugins.
Add the SDK
Install the SDK in a Node.js 22 or newer application:
npm install @getaviato/sdkThe package includes JavaScript and TypeScript declarations; no monorepo dependencies are required. The npm package README describes installation and optional ORM helpers.
Define a plugin
This example defines a single-record action and reads the selected customer through the connector. The exact example below is typechecked against the SDK in CI.
import { createAviatoPlugin, IntercomPlugin, StripePlugin, ZendeskPlugin } from "@getaviato/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");
},
});
}
/** The customers layout, declared in code: the dashboard shows it read-only. */
export function addCustomerLayout(plugin: ReturnType<typeof createPlugin>) {
return plugin.layout("customers", {
label: "Clients",
icon: "users",
fieldOrder: ["name", "email", "plan", "mrr"],
fields: { mrr: { label: "MRR", widget: "currency", currency: "EUR", readOnly: true }, internal_notes: { hidden: true } },
searchFields: ["name", "email"],
defaultSort: "-created_at",
relations: [{ name: "owner", kind: "belongsTo", foreignKey: ["owner_id"], target: "users", targetKey: ["id"] }],
});
}
/** Optional: set STRIPE_WIDGET_KEY on the customer connector, never in this declaration.
* Nest services can call this with their injected AviatoPlugin during onModuleInit.
* For injected plugin factories, see the NestJS forFeature example.
*/
export function addBillingWidgets(plugin: ReturnType<typeof createPlugin>) {
return plugin.use(new StripePlugin({ credentialEnv: "STRIPE_WIDGET_KEY", readOnly: true }).invoices({ collection: "customers", name: "stripe-invoices", customerId: { field: "stripe_customer_id" } }));
}
/** Set ZENDESK_WIDGET_TOKEN on the customer connector with users:read / tickets:read scopes. */
export function addSupportWidgets(plugin: ReturnType<typeof createPlugin>, subdomain: string) {
return plugin.use(
new ZendeskPlugin({ subdomain, credentialEnv: "ZENDESK_WIDGET_TOKEN", readOnly: true })
.user({ collection: "customers", name: "support-user", userId: { field: "zendesk_user_id" } })
.tickets({ collection: "customers", name: "support-tickets", userId: { field: "zendesk_user_id" } })
.ticket({ collection: "issues", name: "support-ticket", ticketId: { field: "zendesk_ticket_id" } }),
);
}
/** Set INTERCOM_WIDGET_TOKEN on the customer connector; the Intercom app needs read-only scopes. */
export function addIntercomWidgets(plugin: ReturnType<typeof createPlugin>) {
return plugin.use(new IntercomPlugin({ region: "eu", credentialEnv: "INTERCOM_WIDGET_TOKEN", readOnly: true }).contact({ collection: "customers", name: "intercom-contact", externalId: { field: "id" } }));
}
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:
app.all('/aviato/*', (context) => plugin.fetch(context.req.raw));The same handler can be mounted in any server framework that provides standard Request and Response objects.
Connect the plugin to the connector
Set both variables on the database connector:
AVIATO_PLUGIN_URL=https://your-app.example.com/aviato
AVIATO_PLUGIN_SECRET=replace-with-your-standard-webhooks-secretUse the same secret when creating the plugin. The plugin URL must be reachable by the connector. Signed plugin calls do not use an end-user browser session.
Check collection names at compile time
aviato typegen --out src/aviato.ts generates an AviatoSchema type from your database. Pass it as createAviatoPlugin<AviatoSchema>(…), and a misspelled collection or field fails to compile. While you develop, aviato dev reloads the plugin's manifest every second. See Typed plugins and local development.
Test your handlers
@getaviato/sdk/testing (SDK 0.4.0+) calls your actions, forms, computed fields, hooks, write overrides, segments, search, charts and custom datasources without a connector. Handlers receive a fake admin caller (change it with actingAs), and context.data, context.getRecords() and any DataClient built from the caller hit an in-memory Data API you seed with records.
import { createPluginTest } from "@getaviato/sdk/testing";
import { createPlugin } from "./plugin";
/** Call from any test runner (Vitest, Jest, Bun, node:test): failed assertions throw. */
export async function confirmSelectionTest() {
const aviato = createPluginTest(createPlugin("whsec_dGVzdA==")).withRecords("customers", [{ id: "42", name: "Acme" }]);
const result = await aviato.executeAction("customers", "Confirm selection", { recordIds: ["42"] });
result.assertSuccess("Customer selected");
aviato.data.assertNothingWritten();
// Run the same action as another role.
await aviato.actingAs({ role: "viewer" }).executeAction("customers", "Confirm selection", { recordIds: ["42"] });
}
The test kit offers executeAction, resolveForm, computeField, runHooks, writeField, resolveSegment, search, computeChart, and for custom datasources listCustomRecords, getCustomRecord, createCustomRecord, updateCustomRecord, deleteCustomRecord and listChanges. Action results assert with assertSuccess, assertError, assertHtml, assertFile, assertRedirect, assertWebhook and assertInvalidated; writes assert with data.assertCreated, assertUpdated, assertDeleted and assertNothingWritten. Assertions throw, so they work with any test runner. Values go through a JSON round trip, as on the wire. The fake Data API supports equality, $eq, $ne and $in filters; other operators fail, so test complex filters against a real connector.
Extend incrementally
The SDK supports actions, computed fields, hooks, segments, custom search, write overrides, charts, custom datasources, and native custom summaries and forms. Use plugin.summary(collection, document) for a record overview and ui.form(document) for an action layout. The shared UI format includes metric strips, property rows, reusable components, local state, and field presets. 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 connector Data API for governed record access and validate any other side effects yourself.
Resource limits
Plugin requests are limited to 10 MiB before signature verification. Bulk action record reads run with bounded concurrency. Global action targets arrive with the selected search and code segment resolved into context.filter, including when an approved action is replayed.
Generated files remain available for five minutes and expire automatically, even if nobody downloads them. The TypeScript SDK holds at most 128 pending files and 64 MiB of file contents per plugin instance. Download pending files before generating more; exceeding either limit returns a resource-exhausted error.
Provider integrations
Register a typed StripePlugin with plugin.use(new StripePlugin(...)). 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.