@ftai/artifact-hub-sdk (Node.js / TypeScript)

TypeScript / Node.js 客户端 SDK，用于向公司内部 artifact-hub 平台上传 AI 产物（HTML / 图片 / PDF / Markdown / Office 文档），获取可分享的短链。

基于 UnJS 生态 打造（ofetch, ufo, std-env, defu, mrmime, pathe, unbuild），跨运行时友好、原生 ESM + CJS 双格式输出、自带完整的 TypeScript 类型定义。

能力边界

SDK 覆盖上传（支持目录、原站地址等元数据）与续期。Bearer 凭证二选一：

• 上传 Token（aht_...）：平台签发，用于鉴权与归属，并可对它自己创建的产物续期（延长有效期）。
• Keycloak access token（JWT）：以登录用户的 SSO 身份直接上传，产物署名为本人（personal）。SSO 上传的产物没有 token 关联，不能续期。

其余管理端点（list/get/delete、以及会话重置 TTL）走浏览器会话（Cookie）鉴权，不在本 SDK 范围内。

安装

npm install @ftai/artifact-hub-sdk
# 或
pnpm add @ftai/artifact-hub-sdk

快速开始

1. 从环境变量配置（推荐）

凭证使用 ARTIFACT_HUB_ACCESS_TOKEN（SSO access token，优先）或 ARTIFACT_HUB_TOKEN（上传 Token）：

export ARTIFACT_HUB_URL="https://a.ftai.chat"
export ARTIFACT_HUB_ACCESS_TOKEN="eyJ..."   # SSO 直传
# 或：export ARTIFACT_HUB_TOKEN="aht_xxxxxxxx..."

import { Client, UploadRequest } from "@ftai/artifact-hub-sdk";

// 自动读取环境变量 ARTIFACT_HUB_URL / ARTIFACT_HUB_ACCESS_TOKEN（或 ARTIFACT_HUB_TOKEN）
const client = Client.fromEnv();

// 方式 A：Fluent Builder 风格（对齐 Rust SDK）
const request = UploadRequest.new("report.html", "<h1>周报内容</h1>")
  .setContentType("text/html")
  .setTitle("周报")
  .setTtlDays(30)          // 0 = 长期保留；不设 = 平台默认 7 天
  .setDirectory("研报/2026") // S3-key 风格目录，不设 = 根目录
  .setOriginalUrl("https://reports.internal/weekly/42");

const artifact = await client.upload(request);

console.log("🔗 分享：", client.viewUrl(artifact.public_id));
// 仅给 owner：可访问内网时跳原站，否则回退平台副本
console.log("👤 Owner：", client.redirectUrl(artifact.public_id));

方式 B：Plain Object 风格

const artifact = await client.upload({
  filename: "chart.png",
  data: buffer, // Buffer | Uint8Array | ArrayBuffer | Blob | string
  title: "趋势图",
  ttlDays: 14,
  directory: "charts/2026",
});

方式 C：直接上传本地磁盘文件（Node.js 环境）

const artifact = await client.uploadFile("./reports/annual.pdf", {
  title: "2026年度报告",
  ttlDays: 0, // 长期保留
});

2. 显式构造或 Builder 配置

import { Client, createClient } from "@ftai/artifact-hub-sdk";

// 显式创建
const client = createClient({
  baseUrl: "https://a.ftai.chat",
  token: "aht_xxx",
  timeout: 30000, // 30 秒超时
});

// 或使用 Builder 链式构造
const client2 = Client.builder()
  .baseUrl("https://a.ftai.chat")
  .token("aht_xxx")
  .timeout(30000)
  .build();

原站跳转

上传内网服务生成的报告时，可通过 original_url 保存其 HTTP/HTTPS 原地址：

const artifact = await client.upload({
  filename: "report.html",
  data: htmlContent,
  originalUrl: "https://reports.internal/weekly/42",
});

const shareUrl = client.viewUrl(artifact.public_id);     // /a/{id}：普通访客始终看平台副本
const ownerUrl = client.redirectUrl(artifact.public_id); // /r/{id}：仅发送给报告 owner

Owner 打开 /r/{id} 后，平台会顶层跳转到独立 HTTP 检测页，由该页面在浏览器中用 2 秒 超时分别并行请求原站和阴性对照 example.invalid 各 3 次，并计算成功 resolved 样本的平均 耗时。原站没有 resolved 样本时回退；阴性对照不 resolved 时前往原站；两组都 resolved 时， 仅在平均耗时差小于 5% 时视为无法可靠区分并回退。这样可避免平台 HTTPS 页面直接探测 HTTP 原站时的 mixed-content 阻断。普通分享链接 /a/{id} 不执行任何原站探测。

续期

延长产物有效期。语义是只延不缩：新到期时间取 max(当前到期, now + ttl_days)， 长期保留（无到期）的产物维持长期。只有当初上传该产物的上传 Token 能续期，ttl_days 必须为正数；用 SSO access token 配置的客户端不能续期（服务端返回 404）。

// public_id 来自 upload() 返回的 artifact.public_id
const updated = await client.renew(artifact.public_id, 30); // 至少再保留 30 天
console.log("新到期时间：", updated.expires_at);

该 Token 未创建的产物、或已过期（尚未被清理）的产物，续期抛出 ApiError（status: 404）。

错误处理

SDK 抛出继承自 ArtifactHubError 的结构化异常：

• ConfigError —— 配置缺失或非法（base URL、token 为空、环境变量缺失等）。
• HttpError —— 传输层失败（DNS 解析失败、网络超时、连接被拒等），可通过 .cause 获取底层异常。
• ApiError —— 服务端返回非 2xx 响应，包含：
  • status: number：HTTP 状态码（如 400、401、404、500 等）
  • code: string：服务端返回的错误代号（如 invalid_param, unauthorized），非 JSON 响应时为 "unknown"
  • apiMessage: string：错误详情说明

import { ApiError, ConfigError, HttpError } from "@ftai/artifact-hub-sdk";

try {
  await client.upload(req);
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`API 错误 [${err.status}] ${err.code}: ${err.apiMessage}`);
  } else if (err instanceof HttpError) {
    console.error("网络传输失败：", err.message, err.cause);
  } else if (err instanceof ConfigError) {
    console.error("配置错误：", err.message);
  }
}

UnJS 生态集成

本 SDK 基于以下 UnJS 库构建：

• ofetch：现代轻量 Fetch 封装，内置超时与异常处理。
• ufo：规范化 URL 路径拼接与清理。
• std-env：跨运行时安全读取环境变量。
• defu：配置深度合并与默认参数处理。
• mrmime：超快 MIME 类型推断。
• pathe：规范化跨平台文件路径。
• unbuild：现代零配置打包系统，输出 ESM / CJS / .d.ts。

开发与测试

# 在 sdk/node 目录下
npm install

# 运行测试
npm test

# 类型检查与打包构建
npm run typecheck
npm run build

说明

• 可预览类型：HTML（沙箱）、图片、PDF、Markdown（GitHub 风格）、Office（Word / Excel / PowerPoint，经微软 Office Web Viewer）。其它类型作为下载。
• 默认上传大小上限 50 MB。
• 查看需 Keycloak 登录，任意已登录员工可打开链接。