PostBot - 内容同步助手

Appearance

🔌 PostBot SDK ​

PostBot SDK 是 PostBot 内容同步助手 的官方 TypeScript SDK，封装了引擎的任务、平台、账号、客户端、发布调度、工作流与认证接口，方便在自有系统、服务端脚本与 CI/CD 中集成 PostBot 能力。

NOTE

本文对应 PostBot SDK v1.0.0，要求 Node.js >= 18，包为纯 ESM。
npm 包已发布，可直接安装；也可以从 GitHub 仓库 克隆后执行 npm ci && npm run build 使用。

SDK 只包含 API 客户端与类型定义，不包含浏览器扩展或桌面端运行时。如需开箱即用的产品，请访问 PostBot 内容同步助手。

✨ 特性与适用场景 ​

  • 零运行时依赖：仅使用 Node.js 内置的 fetch、AbortController 与标准 Web API。
  • 统一客户端：App-Id、Bearer Token、超时与错误归一化一次配置。
  • 完整 API 模块：任务、平台、账号、客户端、发布调度、工作流、会话、通知与浏览器指纹。
  • 认证助手：开发者应用凭证、代理登录/注册/重置密码、直接登录与当前用户信息。
  • 类型安全：完整 TypeScript 声明、严格模式、ESM 入口与 source map。
  • 可预期错误：业务失败统一抛出 IamApiError，携带 code 与 HTTP status。

适用场景：

  • 企业 CMS / 内容后台的“同步到 PostBot”能力。
  • 服务端批量创建任务、定时发布与状态轮询。
  • 将发布流程接入 GitHub Actions、GitLab CI、crontab 等自动化链路。

📦 安装 ​

bash
# npm
npm install @gitcoffee-os/postbot-sdk

# pnpm
pnpm add @gitcoffee-os/postbot-sdk

要求 Node.js >= 18，使用 import 引入。

🚀 快速开始 ​

ts
import { PostbotClient, TaskApi } from '@gitcoffee-os/postbot-sdk';

const client = new PostbotClient({
  baseUrl: 'https://your-postbot-host', // 你的 PostBot 服务地址
  appId: 'your-app-id',
  token: 'user-access-token',
});

const tasks = new TaskApi(client);

// 分页查询任务
const page = await tasks.list({ page: 1, size: 20, status: 'FAILED' });
console.log(page.total, page.list);

// 创建并自动发布任务
const task = await tasks.create({
  name: '多平台文章',
  platformCodes: ['weixin', 'xiaohongshu'],
  data: {
    title: 'Hello PostBot',
    content: '<h2>Hello</h2><p>来自 SDK 的正文。</p>',
  },
  isAutoPublish: true,
});

console.log(task.id);

⚙️ 客户端配置 ​

ts
const client = new PostbotClient({
  baseUrl: 'https://your-postbot-host',
  appId: 'your-app-id',
  token: 'optional-token',
  timeoutMs: 30_000,
});

client.setToken('new-token'); // 登录后更新 Token
选项类型必填说明
baseUrlstring是引擎 API 根地址，末尾斜杠可有可无
appIdstring是应用标识，写入 App-Id 请求头
tokenstring否用户 Token，写入 Authorization: Bearer <token>
timeoutMsnumber否单次请求超时，默认 30000 毫秒

🔐 认证 ​

直接登录 ​

ts
import { PostbotClient, directLogin } from '@gitcoffee-os/postbot-sdk';

const { access_token, expires_in } = await directLogin(baseUrl, username, password);

const client = new PostbotClient({
  baseUrl,
  appId,
  token: access_token,
});

开发者应用代理登录 ​

ts
import { getAppToken, proxyLogin } from '@gitcoffee-os/postbot-sdk';

const appAccessToken = await getAppToken(iamBaseUrl, clientId, clientSecret);

const result = await proxyLogin({
  iamBaseUrl,
  appAccessToken,
  clientId,
  username,
  password,
  appId,
});

client.setToken(result.token);

proxyRegister 用于注册，proxyForgotPassword 用于重置密码。所有 IAM 请求默认 30 秒超时，可通过参数中的 timeoutMs 覆盖。

当前用户 ​

ts
import { getUserInfo } from '@gitcoffee-os/postbot-sdk';

const user = await getUserInfo(iamBaseUrl, token, appId);
console.log(user.preferred_username ?? user.username);

🧩 核心模块 ​

模块主要方法说明
TaskApilist listAll get create update delete batchDelete bindContent任务 CRUD、批量删除、内容绑定
PlatformApilistPaged list get create update remove batchRemove平台字典
AccountApilistPaged list get findBySession save update remove batchRemove媒体账号
ClientApilistPaged list get register update remove batchRemove扩展 / 桌面 / 云端客户端
WorkflowApiexecuteWorkflow getExecutionStatus retryExecution listDefinitions工作流编排
AutoPublishApitrigger getStatus listJobs listLogs自动发布调度与日志
FingerprintApiload save remove账号浏览器指纹
SessionApilistPaged list getSessionBot 会话（只读）
NotifyApisend通用通知
IAM helpersgetAppToken proxyLogin proxyRegister proxyForgotPassword directLogin getUserInfo认证与用户信息

发布调度 ​

ts
import { AutoPublishApi } from '@gitcoffee-os/postbot-sdk';

const autoPublish = new AutoPublishApi(client);

await autoPublish.trigger(123); // 忽略定时时间，立即编排 Job
const job = await autoPublish.getStatus(123);
const jobs = await autoPublish.listJobs({ taskId: 123, status: 'FAILED', limit: 20 });
const logs = await autoPublish.listLogs({ taskId: 123, limit: 20 });

工作流 ​

ts
import { WorkflowApi } from '@gitcoffee-os/postbot-sdk';

const workflow = new WorkflowApi(client);

const execution = await workflow.executeWorkflow('STATUS_QUERY', { taskId: 123 });
const status = await workflow.getExecutionStatus(execution.executionId);
await workflow.retryExecution(execution.executionId);
const definitions = await workflow.listDefinitions();

⚠️ 错误处理 ​

后端可能以 HTTP 200 + 业务码返回失败，SDK 会统一转换为 IamApiError：

ts
import { IamApiError } from '@gitcoffee-os/postbot-sdk';

try {
  await tasks.get(123);
} catch (err) {
  if (err instanceof IamApiError) {
    console.error(err.code);   // 如 USER.TOKEN_EXPIRED、NOT_LOGIN
    console.error(err.status); // HTTP 状态码
    console.error(err.message);
  } else {
    throw err;
  }
}

自定义传输层可复用底层工具：

ts
import { isSuccessCode, toApiError } from '@gitcoffee-os/postbot-sdk';

if (!isSuccessCode(body.code)) {
  throw toApiError(body, status);
}

⏱️ 超时与安全 ​

  • PostbotClient 的每个请求都会在 timeoutMs 后中止，响应体读取阶段同样受超时保护。
  • IAM 助手默认 DEFAULT_IAM_TIMEOUT_MS（30 秒），可按调用覆盖。
  • 生产环境必须使用 HTTPS；SDK 不会替调用方校验证书或协议。
  • clientSecret、用户密码与 Token 由调用方保管，不要把 clientSecret 放进浏览器或前端产物。
  • SDK 不持久化任何凭据，也不发送遥测数据。

🖥️ 运行时与兼容性 ​

  • 运行时：Node.js >= 18（依赖全局 fetch、AbortController）。
  • 开发与测试：Node.js >= 20（Vitest 4 要求）。
  • 纯 ESM，使用 import 引入；类型声明随包发布。
  • getAppToken 使用 Node.js Buffer 生成 Basic Auth，仅适用于 Node.js 环境；其余客户端逻辑不依赖 Node 专有 API。
  • 版本遵循 Semantic Versioning，变更记录见 CHANGELOG。

📚 相关资源 ​