# @forteplatforms/sdk 中文文档

规范地址：https://npmcn.com/package/%40forteplatforms/sdk/

版本：1\.0\.536
npm 元数据更新时间：2026-11-15T18:55:45.765Z
中文译文更新时间：2026-11-15T09:50:29.955Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40forteplatforms/sdk
原文对照：https://npmcn.com/package/%40forteplatforms/sdk/?lang=original
项目主页：https://github.com/FortePlatforms/SDK#readme
源码仓库：https://github.com/FortePlatforms/SDK

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.5 MB，550 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-03-19T00:12:48.235Z
- 最新版本发布：2026-11-15T18:55:45.615Z
- 近 30 天下载量：4624（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：112（近 12 个月 112 个）

## 中文简介

Forte 平台的官方类型SDK脚本

## 安装

```sh
npm install @forteplatforms/sdk
```

也可以使用：`pnpm add @forteplatforms/sdk`、`yarn add @forteplatforms/sdk`、`bun add @forteplatforms/sdk`

## README

# 堡垒平台类型SDK

官方TypeScript SDK用于与Forte平台API互动.

## 安装

```bash
npm install @forteplatforms/sdk
```

## 认证

SDK支持三种认证模式,视其运行地点而定.

### 福尔特托管服务(无配置)

`FORTE_API_TOKEN` 自动设置和范围为服务项目:

```typescript
const client = new ForteClient();
```

### 客户端( 浏览器/ 移动)

请求 `client.users.*`,构造时没有参数。 浏览器发送 `Forte-User-Session-Token` 用户登录后自动 cookie 。 SDK套装 `credentials: 'include'` 所以饼干到达API的交叉原生地.

```typescript
const client = new ForteClient();
await client.users.renewSessionToken({ projectId });
```

执行 **没有** 通过 `apiToken` 从浏览器代码——这是服务器侧的秘密.

### 服务器侧 BFF 呼叫 `client.users.*` (无代号,每召授权)

在代理用户扫描的电话的BFF中,省略了符号并转发每个用户的会话符号作为 `authorization` 每次调用时的参数 :

```typescript
const client = new ForteClient();
await client.users.renewSessionToken({
  projectId,
  authorization: `Bearer ${userSessionToken}`,
});
```

### 外部服务器端呼叫 `client.projects.*` (显式)

```typescript
const client = new ForteClient({ apiToken: 'your_api_token_here' });
```

或者设定 `FORTE_API_TOKEN` (只有节点)和呼叫 `new ForteClient()`。 。 。 .

您可以从Forte平台仪表板生成 API 令牌.

## 快速启动

```typescript
import { ForteClient } from '@forteplatforms/sdk';

const client = new ForteClient();

// List your projects
const projects = await client.projects.listProjects();

// Get a specific project
const project = await client.projects.getProject({ projectId: 'your-project-id' });
```

## 处理错误

API 出错作为 HTTP 状态信息的例外 :

```typescript
try {
  const project = await client.projects.getProject({ projectId: 'invalid-id' });
} catch (error) {
  console.error('API error:', error);
}
```

## 用户自定义属性

在您的用户中存储任意的密钥值元数据 。 用于跟踪订阅级别,特征标志,首选项,或任何应用程序专用数据.

```typescript
// Set custom attributes on a user
const user = await client.projects.putUserCustomAttributes({
  projectId: 'your-project-id',
  userId: 'user-id',
  requestBody: {
    plan: 'pro',
    referral_source: 'google',
    onboarding_completed: 'true',
  },
});

console.log(user.customMetadataAttributes);
// { plan: 'pro', referral_source: 'google', onboarding_completed: 'true' }
```

**主要制约因素:**

-   密钥必须是1-64个字符:字母、数字、下划线和连字符
-   值为字符串
-   每次调用都会取代所有现有的属性——包括任何想要保存的属性

### 与现有属性合并

```typescript
// Read current attributes, then merge
const user = await client.projects.getProjectUser({
  projectId: 'your-project-id',
  userId: 'user-id',
});

await client.projects.putUserCustomAttributes({
  projectId: 'your-project-id',
  userId: 'user-id',
  requestBody: {
    ...user.customMetadataAttributes,
    plan: 'enterprise', // update one field
  },
});
```

## API 参考

### `client.projects`

管理Forte平台上的项目和服务.

### `client.users`

管理项目中的最终用户.

## 常见问题

### @forteplatforms/sdk 是什么？

Forte 平台的官方类型SDK脚本

### 如何安装 @forteplatforms/sdk？

在项目目录运行 npm install @forteplatforms/sdk，或使用 pnpm add / yarn add / bun add。

### @forteplatforms/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @forteplatforms/sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @forteplatforms/sdk 可以商用吗？

@forteplatforms/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @forteplatforms/sdk 的下载量有多少？

根据 npm 官方下载统计，@forteplatforms/sdk 在 2026/10/16 – 2026/11/14 这 30 天内被下载 4,624 次，日均约 154 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @forteplatforms/sdk 还在维护吗？

最新版本 1\.0\.536 发布于 2026/11/16（今天）；至今共发布 112 个版本，其中过去 12 个月发布了 112 个；首次发布于 2026/03/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。