Overview - Mesa Docs

The Mesa TypeScript SDK is the ergonomic client for Mesa in Node.js and JavaScript runtimes. It wraps the generated @mesadev/rest client, reads the organization from the private key, verifies webhooks, and exposes a native virtual filesystem for repo I/O and shell execution. Node.js 18 or newer is required.

Installation

npm install @mesadev/sdk

Create a client

import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

const repos = await mesa.repos.list({ limit: 50 });
console.log(`found ${repos.repos.length} repos`);

Set MESA_PRIVATE_KEY in a trusted Node.js environment to call new Mesa() without an argument.

Client options

import { Mesa } from '@mesadev/sdk';

const mesa = new Mesa({ privateKey: 'mesa_private_key_acme_...', apiUrl: 'https://api.mesa.dev/v1',
  fetch: globalThis.fetch,
  userAgent: 'my-app/1.0.0',
  webhookSecret: 'whsec_...' });

string | undefined

Ed25519 private key. Omit it to read MESA_PRIVATE_KEY in Node.js.

string

REST API base URL. Defaults to https://api.mesa.dev/v1. http and https are accepted. Trailing slashes are stripped.

typeof globalThis.fetch | undefined

Custom fetch implementation for REST requests.

string | undefined

Appended to the SDK user agent. Node.js uses User-Agent; browser-like runtimes use X-Mesa-User-Agent.

string | undefined

Signing secret used by mesa.webhooks.receive(...).

Lifecycle

The TypeScript client does not hold an HTTP session and does not need to be closed. Reuse one Mesa instance where practical. Mounts sign one short-lived, layout-scoped access token locally from the client’s private key and use it for the mount’s whole lifetime. Definitions default to a 15 minute ttl and can run up to 4 hours. Set ttl on the definition: mesa.fs({ layout, ttl, authors }).mount().

Organization resolution

The client reads its organization from the private key. Resource methods always use that organization and do not accept an org value.

console.log(mesa.org.slug);
await mesa.repos.list();

Use mesa.org.get() when you need organization metadata from the API.

Resource APIs

API	Purpose
`mesa.repos`	Create, read, update, delete, sync upstreams, and read upstream sync history on repositories.
`mesa.content`	Read files, symlinks, and directory listings without mounting.
`mesa.changes`	Create, patch, and inspect Mesa changes.
`mesa.diffs`	Inspect diffs and conflicts between changes.
`mesa.bookmarks`	Manage branch-like bookmark refs.
`mesa.webhookTargets`	Manage outbound webhook targets.
`mesa.webhooks`	Verify incoming webhook requests and dispatch typed handlers.
`mesa.fs`	Define a layout and mount it as a virtual filesystem, or mint its scoped token. Call `mesa.fs({ layout, authors, ttl? })` then `.mount()` / `.token()`.
`mesa.org`	Read the private key’s organization slug with `mesa.org.slug`, or fetch organization metadata with `mesa.org.get()`.

Bulk repository tag updates are available through mesa.raw.

Response objects

High-level SDK methods return response data directly. They do not return generated HTTP wrapper objects.

const repos = await mesa.repos.list();
for (const repo of repos.repos) {
  console.log(repo.name, repo.head_change_id);
}

Generated response aliases such as GetRepoResponse live in @mesadev/rest.

Common types

Import SDK-owned types from @mesadev/sdk.

import type {
  FilesystemDefinition,
  FsMountRuntimeOptions,
  Layout,
  MesaOptions,
  WebhookEvent,
} from '@mesadev/sdk';
import { repo } from '@mesadev/sdk';

Type	Purpose
`MesaOptions`	Options accepted by the `Mesa` constructor.
`FsMountRuntimeOptions`	Runtime options for `definition.mount(...)` (`cache`, `telemetry`).
`FilesystemDefinition`	Layout, authors, and token lifetime bundled with the `layout()`, `mount()`, and `token()` operations they configure, returned by `mesa.fs({ layout, authors })`.
`AccessToken`	Short-lived credential returned by `definition.token()`, scoped to the layout that minted it, with `token` and ISO `expires_at` fields.
`Layout`	Raw path map validated by `mesa.fs(...)` and returned by `definition.layout()`. Serialize it for the CLI with `JSON.stringify(...)`.
`Repo` / `RepoOptions`	One layout repository declaration, produced by `repo(...)`.
`MesaFileSystem`	Native filesystem implementation returned by `mesa.fs({ layout, authors }).mount()`.
`ChangeInfo`	Change metadata returned by mounted filesystem change operations.
`ExecResult`	Output from `fs.bash().exec(...)`, re-exported from `just-bash`.
`WebhookEvent`	Discriminated union of webhook event payloads.

High-level REST method input types are inferred from the method signatures. If you need named REST schema types, import them from @mesadev/rest.

Error model

SDK-owned setup and webhook errors extend MesaError and expose a stable code field.

Exception	Code	Meaning
`MissingPrivateKeyError`	`MISSING_PRIVATE_KEY`	No private key was provided or available in the environment.
`MissingAccessTokenError`	`MISSING_ACCESS_TOKEN`	`MesaFileSystem.createAsync()` received an empty access token.
`InvalidApiUrlError`	`INVALID_API_URL`	`apiUrl` is malformed or uses a protocol other than `http` or `https`.
`InvalidOptionsError`	`INVALID_OPTIONS`	Local options are invalid, such as an empty layout or missing private-key authors.
`OrgResolutionError`	`ORG_RESOLUTION_FAILED`	An explicit `mesa.whoami()` request failed.
`MissingWebhookSecretError`	`MISSING_WEBHOOK_SECRET`	`mesa.webhooks.receive(...)` was called without a constructor `webhookSecret`.
`MesaWebhookVerificationError`	`WEBHOOK_VERIFICATION_FAILED`	Webhook signature, timestamp, JSON parsing, or payload validation failed.

API operations throw Mesa API error payloads directly when the server returns an error response. These payloads are not MesaError instances.

Raw generated client

mesa.raw exposes generated REST operations with authentication, base URL, fetch, and user-agent already wired in. Use it when the high-level SDK does not expose an operation or option yet.

const repo = await mesa.raw.getRepo({
  path: { org: 'acme', repo: 'app' },
});

Raw calls use the generated REST request shape (path, query, body) and return response data directly.

Complete example

import { Buffer } from 'node:buffer';
import { Mesa, repo } from '@mesadev/sdk';

const mesa = new Mesa({ privateKey: process.env.MESA_PRIVATE_KEY });

const created = await mesa.repos.create({ name: 'demo' });

const change = await mesa.changes.create({
  repo: created.name,
  base_change_id: created.head_change_id,
  message: 'Add README',
  authors: [{ name: 'Docs Bot', email: 'docs@example.com' }],
  files: [
    {
      path: 'README.md',
      content: Buffer.from('# Demo\n').toString('base64'),
    },
  ],
});

await mesa.bookmarks.move({
  repo: created.name,
  bookmark: created.default_bookmark,
  change_id: change.id,
});

const fs = await mesa
  .fs({
    layout: { '/workspace': repo(created.name, { mode: 'rw' }) },
    authors: [{ name: 'Docs Bot', email: 'docs@example.com' }],
  })
  .mount();
const data = await fs.readFileBuffer('/workspace/README.md');
console.log(Buffer.from(data).toString('utf8'));

​Installation

​Create a client

​Client options

​Lifecycle

​Organization resolution

​Resource APIs

​Response objects

​Common types

​Error model

​Raw generated client

​Complete example

Installation

Create a client

Client options

Lifecycle

Organization resolution

Resource APIs

Response objects

Common types

Error model

Raw generated client

Complete example