跳到正文
TypeScript SDK

把 Appaloft operation catalog 接进你的 TypeScript 产品。

@appaloft/sdk 是发布到 npm 的类型化客户端。它把 Appaloft 的 projects、deployments、resources、servers、domains 等操作暴露成稳定 facade，让内部工具、控制台和自动化脚本走同一条 API 路径。

安装 SDK查看 npm 包

创建 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);
}

常用 facade

appaloft.projects.create

创建项目

appaloft.projects.list

列出项目

appaloft.resources.show

读取资源详情

appaloft.deployments.create

发起部署

appaloft.servers.show

读取服务器状态

appaloft.domainBindings.create

绑定域名

代码示例

初始化客户端

在服务端、worker 或内部工具里创建 Appaloft client。认证材料由你的可信环境注入。

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" },
});

创建项目

facade 按 operation group 组织；项目相关操作在复数 projects 下。

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);

读取列表和详情

查询类操作同样返回 ok/error 结果，方便把 Appaloft 状态嵌进自己的 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" },
});

处理错误

不要解析错误字符串；使用 code、category 和 retryable 字段决定提示、重试或升级人工处理。

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);
  }
}

同一套操作目录

SDK 由 Appaloft operation catalog 生成，和 CLI、HTTP/API、Web console、MCP/tool gateway 使用同一组操作 key。你不需要为产品集成维护另一套手写 endpoint 映射。

适合产品集成

在 dashboard、后台任务、内部平台、agent gateway 或迁移脚本里创建项目、读取资源、发起部署、查看状态。团队权限、认证和错误语义仍由 Appaloft control plane 拥有。

结果模型

facade 返回 ok/error 结构。成功时读取 data，失败时使用结构化 error code、category、message 和 retryable 字段，而不是解析字符串。

SDK 使用复数 group：projects.create，不是 project.create。认证材料应来自受信任的服务端会话、token handoff 或安全后端环境，不要把 cookie/token 写进前端源码。