Skip to content
TypeScript SDK

Bring the Appaloft operation catalog into your TypeScript product.

@appaloft/sdk is the typed client published on npm. It exposes Appaloft projects, deployments, resources, servers, domains, and more as stable facades so internal tools, consoles, and automation scripts use the same API path.

Install SDKView npm package

Create a project

import { createAppaloftClient } from "@appaloft/sdk";

const appaloft = createAppaloftClient({
  baseUrl: "https://app.appaloft.com",
  auth: { kind: "product-session", cookie },
});

const project = await appaloft.projects.create({
  body: { name: "acme-web" },
});

if (!project.ok) {
  console.error(project.error.code, project.error.message);
}

Common facades

appaloft.projects.create

Create a project

appaloft.projects.list

List projects

appaloft.resources.show

Read resource details

appaloft.deployments.create

Start a deployment

appaloft.servers.show

Read server status

appaloft.domainBindings.create

Bind a domain

Code examples

Initialize the client

Create an Appaloft client inside a server, worker, or internal tool. Auth material comes from your trusted environment.

import { createAppaloftClient } from "@appaloft/sdk";

export const appaloft = createAppaloftClient({
  baseUrl: process.env.APPALOFT_BASE_URL ?? "https://app.appaloft.com",
  auth: () => ({
    kind: "deploy-token",
    token: process.env.APPALOFT_TOKEN!,
  }),
  headers: { "x-app-name": "internal-ops" },
});

Create a project

Facades are grouped by operation area. Project operations live under the plural projects group.

const created = await appaloft.projects.create({
  body: {
    name: "acme-web",
    description: "Marketing site and API workers",
  },
});

if (!created.ok) {
  throw new Error(created.error.message);
}

console.log("project", created.data);

List and inspect

Query operations use the same ok/error result shape, which makes Appaloft status easy to embed in your own dashboard.

const projects = await appaloft.projects.list();

if (projects.ok) {
  for (const project of projects.data as unknown[]) {
    console.log(project);
  }
}

const resource = await appaloft.resources.show({
  pathParams: { resourceId: "res_123" },
});

Handle errors

Do not parse error strings. Use code, category, and retryable to decide whether to show guidance, retry, or escalate.

const result = await appaloft.deployments.create({
  body: {
    projectId: "prj_123",
    resourceId: "res_123",
    source: { kind: "git", ref: "main" },
  },
});

if (!result.ok) {
  if (result.error.retryable) {
    console.warn("retry later", result.error.code);
  } else {
    console.error(result.error.category, result.error.message);
  }
}

One operation catalog

The SDK is generated from the Appaloft operation catalog, the same source used by the CLI, HTTP/API, Web console, and MCP/tool gateway. Product integrations do not need a second hand-written endpoint map.

Built for product integration

Use it inside dashboards, workers, internal platforms, agent gateways, or migration scripts to create projects, read resources, start deployments, and inspect status. Team permissions, auth, and error semantics still belong to the Appaloft control plane.

Result model

Facade calls return an ok/error shape. Read data on success; on failure use structured error code, category, message, and retryable fields instead of parsing strings.

The SDK uses plural groups: projects.create, not project.create. Auth material should come from a trusted server session, token handoff, or secure backend environment; do not bake cookies or tokens into frontend source.