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, resolves the default organization for you, 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 omit privateKey from the constructor.

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. In Node.js, the SDK reads MESA_PRIVATE_KEY when no explicit credential is supplied.

{ privateKey: string } | { accessToken: string } | undefined

A credential group holding either a private key or an existing access token. A client built from an access token forwards that token unchanged and cannot mint another one.

string

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

string

Optional VCS gateway override. Only use when self-hosting Mesa.

string | undefined

Optional organization check. Private-key and access-token clients derive the organization from the credential and only accept a matching value.

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. Private-key mounts sign one short-lived, scoped access token locally and use it for the mount’s whole lifetime, while a client built from an access token forwards that token unchanged. Private-key mounts default to 15 minutes and can run up to 4 hours. Layout mounts work the same way, with the ttl carried on the definition: mesa.fs({ layout, ttl }).mount().

Organization resolution

Private-key and access-token clients read the organization from the credential. A constructor or per-call org value is optional, but it must match that organization.

await mesa.repos.list();
await mesa.repos.list({ org: 'acme' });

Resource namespaces

Namespace	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.apiKeys`	Create, list, and revoke Mesa API keys (deprecated).
`mesa.tokens`	Sign short-lived, scoped access tokens locally from a private key.
`mesa.webhookTargets`	Manage outbound webhook targets.
`mesa.webhooks`	Verify incoming webhook requests and dispatch typed handlers.
`mesa.fs`	Mount repos as a virtual filesystem and run Bash commands. Call `mesa.fs({ layout })` to build a layout definition; `mesa.fs.mount({ repos })` mounts the canonical `/<org>/<repo>` paths.
`mesa.org`	Fetch organization metadata.

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 { FsLayoutDefinition, FsMountReposOptions, MesaOptions, RepoConfig, WebhookEvent } from '@mesadev/sdk';

Type	Purpose
`MesaOptions`	Constructor options for `new Mesa(...)`.
`FsMountReposOptions`	Options for `mesa.fs.mount(...)`.
`FsLayoutDefinition`	Layout bundled with its `layout()`, `mount()`, and `token()` operations, returned by `mesa.fs({ layout })`.
`LayoutSpec` / `Layout`	Raw path map passed to `mesa.fs(...)`, and the prepared layout the definition exposes.
`RepoConfig`	Pin a mounted repo to a bookmark or change.
`MesaFileSystem`	Native filesystem implementation returned by `mesa.fs.mount(...)` and `mesa.fs({ layout }).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
`MissingCredentialError`	`MISSING_CREDENTIAL`	No credential was provided or available in the environment.
`InvalidApiUrlError`	`INVALID_API_URL`	`apiUrl` or `vcsUrl` is malformed or uses a protocol other than `http` or `https`.
`InvalidOptionsError`	`INVALID_OPTIONS`	Local options are invalid, such as mounting zero repositories.
`OrgResolutionError`	`ORG_RESOLUTION_FAILED`	The SDK could not resolve caller identity through `/whoami`.
`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 } from '@mesadev/sdk';

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

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

const change = await mesa.changes.create({
  repo: repo.name,
  base_change_id: repo.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: repo.name,
  bookmark: repo.default_bookmark,
  change_id: change.id,
});

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

​Installation

​Create a client

​Client options

​Lifecycle

​Organization resolution

​Resource namespaces

​Response objects

​Common types

​Error model

​Raw generated client

​Complete example

Installation

Create a client

Client options

Lifecycle

Organization resolution

Resource namespaces

Response objects

Common types

Error model

Raw generated client

Complete example