SDK packages

Choose the part your app needs.

Each package page is made from its checked-in package metadata and README.

@brydio/api

Typed access to Brydio projects, files, chats, and named connections from an app screen, and Brydio's AI from your own server. Version 0.1.0-alpha.61.

@brydio/api

Typed project, file, chat, and named-connection calls for a Brydio app screen. Every request travels through @brydio/app; the screen receives no token, cookie, API address, or connection credential.

import { api } from '@brydio/api';

const projects = await api.projects.list();
const issues = await api.connections.use('github').request({
  path: '/repos/brydio/brydio/issues',
  query: { state: 'open' },
});

The manifest needs the matching projects, files, chats, or exact connection:<name> host grant. Reads run after Brydio checks the current person. Writes wait for the person's Allow once approval.

Read the @brydio/api bridge section for the security boundary and wire contract.

Brydio's AI from your own server: @brydio/api/ai

For code you run yourself (a backend, a script, CI), not for an app. It takes a developer API key from Settings › Developer in Brydio, read from BRYDIO_API_KEY, and your Brydio's address from BRYDIO_API_URL:

import { ai } from '@brydio/api/ai';

const { summary } = await ai.summarize({ text: report, length: 'short' });

Never put a key in an app. Inside an app, a custom tool's handler calls model.generate with the model host grant instead, and needs no key. brydio validate refuses an app that holds a key or imports @brydio/api/ai. Read Brydio's AI.

This package is MIT licensed. While the SDK is 0.x, a minor version may contain a breaking change. Read the repository changelog before upgrading.

@brydio/app

The runtime a Brydio app's screen runs on, inside its worker: the tree, the bridge to the host, and the Preact adapter. Version 0.1.0-alpha.61.

@brydio/app

The runtime a Brydio screen uses to draw a catalogue tree and call its tools, data, navigation, toast, and host context bridge.

import { tools } from '@brydio/app';
import { mount } from '@brydio/app/preact';

function Home() {
  return (
    <bry-button
      label="Add item"
      onPress={() => tools.call('create_item', { title: 'New item' })}
    />
  );
}

void mount(Home);

The worker has no DOM, network, cookies, or storage. Brydio draws every element and checks every call. Read the bridge reference and the catalogue before adding a screen.

A custom tool's handler, which Brydio runs on its side, is typed with import type { Handler } from '@brydio/app/handler': its data, tools, connections, model and the app's own secrets (secrets.get, secrets.set). A screen has no way to read a secret, and no part of an app is given a Brydio credential. Read the security page.

This package is MIT licensed. While the SDK is 0.x, a minor version may contain a breaking change. Read the repository changelog before upgrading.

Finance handlers use the host-owned capabilities documented in Finance. Add the finance grant and use canonical saved records for payment links, document sources, purchase templates, budget metrics and accounting exports.

People handlers use client.people.call<T>(operation, input?) with the people grant. The host checks current HR authority and private-record access. See People.

@brydio/cli

brydio build, validate and dev: turn an app's source into the bundle Brydio loads. Version 0.1.0-alpha.61.

@brydio/cli

The brydio command builds, validates, tests, develops, and publishes a Brydio app.

bun add -d @brydio/cli
bunx brydio build
bunx brydio validate
bunx brydio test

brydio dev serves a local build for a Brydio workspace that permits development apps. brydio login signs in to the app registry (https://registry.brydio.com), and brydio publish validates, pictures, signs when a key is configured, and uploads one immutable app version there, under a tag (latest unless --tag) and an access (workspace or --access public). brydio pack lists what would ship, brydio version raises the manifest's version, brydio tag, deprecate, access and retire change an app on the registry, and brydio upgrade-sdk moves every @brydio/* pin to one SDK version.

Read the publish checklist for every check and refusal code. Start a new Preact app from anywhere with npm create @brydio/app my-app; @brydio/create-app carries the templates and writes exact registry versions instead of checkout links.

This package needs Bun 1.3 or newer and is MIT licensed. While the SDK is 0.x, a minor version may contain a breaking change. Read the repository changelog before upgrading.

@brydio/create-app

Create a working Brydio app from the packaged Preact or plain template. Version 0.1.0-alpha.61.

@brydio/create-app

Create a Brydio app from the packaged Preact template:

npm create @brydio/app my-app
cd my-app
bun run test
bun run dev

Use --template plain after the app name for Brydio's framework-free element functions instead. The generated app uses exact registry versions of the Brydio SDK and includes a manifest, one screen, one collection, and tests.

The generated project and this initializer require Bun 1.3 or newer. This package is MIT licensed.

@brydio/fake-host

A pretend Brydio for testing an app's screens: builds the app, runs a built screen in a worker, draws nothing, and answers its tools from fixtures. Version 0.1.0-alpha.61.

@brydio/fake-host

A local Brydio host for screen tests. It runs a built screen in a worker, checks the same tree rules and budgets, answers tools from fixtures, and lets a test inspect or act on the drawn tree.

import { afterEach, expect, test } from 'bun:test';
import { testApp } from '@brydio/fake-host';

const app = await testApp(import.meta.dir);
afterEach(() => app.stopAll());

test('adds an item', async () => {
  const host = app.start('home', { fixtures: { items: [] } });

  await host.mounted();
  host.press(await host.waitFor(() => host.byText('Add item')));
  expect(host.calls.map(call => call.tool)).toEqual(['create_item']);
});

A custom tool's handler is tested the same way, without a worker: runHandler gives it the client Brydio gives it, with the same refusals. Secrets are only the names the manifest declares, need the secrets grant, and a value the handler held comes back as [secret], as Brydio would pass it on.

import { runHandler } from '@brydio/fake-host';
import listInvoices from '../src/handlers/list_invoices.ts';
import manifest from '../.brydio/app.json';

test('asks for the key before listing', async () => {
  const run = await runHandler(listInvoices, {}, { manifest, secrets: {} });

  expect(run.result).toEqual({ message: 'Set the API key in the app’s settings first.' });
});

A screen placed as a public-page runs for a visitor with no account. Start it with visitor: true to get the context Brydio gives one (role anonymous) and only the answers Brydio gives one: reads of publicRead collections, creates in publicSubmit ones, and tools marked public. A public tool's handler runs the same way with caller: { role: 'anonymous' }.

Run the app's tests with brydio test. The command builds once, then runs its *.test.ts files against that build.

This package is MIT licensed. While the SDK is 0.x, a minor version may contain a breaking change. Read the repository changelog before upgrading.

Custom tools marked write: true use asks: 'allow' | 'deny' | 'hold', just like generated writes. A held write does not execute its handler until the person agrees. Supplying a managed model fixture also requires the model host grant when a manifest is provided.

Use FakeHandlerOptions.finance for explicit Finance fixtures. Finance and provider, metrics or signing grants are checked separately; write methods refuse read tools, and accountant export starts require a screen caller. These fixtures do not fabricate settlements or provider access. See Finance.

Use FakeHandlerOptions.people for explicit native HR fixtures. Supply results keyed by operation, or an async call(operation, input) function. No fixture means people_unavailable. The fake checks the People grant, visitors and read/write boundary; it does not fabricate HR authority. See People.

@brydio/manifest

The shape of a Brydio app's manifest, its collections' schemas, and the checks that say what is wrong with one. Version 0.1.0-alpha.61.

@brydio/manifest

The schema and validation rules for .brydio/app.json. It covers app identity, placements, screens, collections, generated and custom tools, grants, and migrations.

import { defineManifest } from '@brydio/manifest';

export const manifest = defineManifest({
  name: 'checklist',
  version: '0.1.0',
  screens: { home: { entry: 'screens/home.js' } },
  placements: [{ kind: 'project-widget', screen: 'home', label: 'Checklist', sizes: ['medium', 'large'] }],
});

Read the manifest reference for every field, schema type, grant, migration operation, and limit. The publish checklist lists every validation code and its refusal message.

This package is MIT licensed. While the SDK is 0.x, a minor version may contain a breaking change. Read the repository changelog before upgrading.

@brydio/ui

The catalogue of elements a Brydio app draws with: their names, settings and events. Version 0.1.0-alpha.61.

@brydio/ui

The catalogue of elements a Brydio app draws with: their names, settings and events, as data (CATALOGUE) and as types. brydio validate, the worker runtime and the fake host all read it. Brydio's own packages/app/src/apps/catalogue/elements.ts is the original, and test/catalogue.test.ts holds the two to each other.

@brydio/ui/web: the same elements as web components

For HTML views only: an MCP App from an outside server, or anything Brydio shows outside its own window. Link the build and write the elements:

<script type="module" src="…/@brydio/ui/web"></script>
<bry-button label="Save" variant="primary"></bry-button>

Each element has the catalogue's name, its settings as properties and as kebab-case attributes (hideLabel is hide-label; a list or a record is JSON), and its events as DOM events of the same name (press, change, …) that bubble out of the element. The classes are made from CATALOGUE when the build loads, so an element added to the catalogue is here after a build, with no second copy to write.

App screens don't use this. Brydio draws them with its own React kit, and nothing built on the SDK needs the web components.

Why Lit

The web components are built on Lit, pinned to one major version (lit 3 in package.json).

  • It's small: about 5 KB.
  • It's maintained by Google, and it's what Adobe Spectrum's web components are built on.
  • It adds nothing beyond the web component standard that we'd have to migrate away from. A Lit element is a custom element with reactive properties and a template.

FAST wasn't chosen: when it changed course, Microsoft's own toolkit for extension UIs, built on it, was deprecated rather than rewritten, and every extension using it was stranded. Stencil and similar tools weren't chosen because they compile to a runtime we wouldn't own.

Lit is imported in exactly one file, src/web/base.ts. Every element extends its BryElement and takes html and css from there, so replacing Lit means changing that file and rebuilding. test/web.test.ts fails if any other file imports it.