# @brightoutcome/guidistry-client 中文文档

规范地址：https://npmcn.com/package/%40brightoutcome/guidistry-client/

版本：0\.9\.1
npm 元数据更新时间：2026-11-06T21:25:17.273Z
中文译文更新时间：2026-11-08T15:38:43.587Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40brightoutcome/guidistry-client
原文对照：https://npmcn.com/package/%40brightoutcome/guidistry-client/?lang=original
项目主页：https://github.com/BrightOutcome-Inc/guidistry/tree/main/clients/typescript#readme
源码仓库：https://github.com/BrightOutcome-Inc/guidistry

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

- 包体积（解压后）：291 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：aws-amplify ^6\.10\.0
- 首次发布：2026-10-17T17:48:29.837Z
- 最新版本发布：2026-11-06T21:25:17.108Z
- 近 30 天下载量：2399（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Guidistry API 的客户端和签名助手

## 安装

```sh
npm install @brightoutcome/guidistry-client
```

也可以使用：`pnpm add @brightoutcome/guidistry-client`、`yarn add @brightoutcome/guidistry-client`、`bun add @brightoutcome/guidistry-client`

## README

# @ brightoutcome/ guidistry- 客户端

输入客户端和登录助手 [指导](https://github.com/BrightOutcome-Inc/guidistry) API (英语). 每个路径,参数和响应类型都是从API的OpenAPI合同中生成的,所以一个API更改显示为类型错误.

```
npm install @brightoutcome/guidistry-client aws-amplify
```

## 设置一次

```ts
import { createGuidistryClient } from "@brightoutcome/guidistry-client";
import { configureAuth, getAccessToken } from "@brightoutcome/guidistry-client/auth";

configureAuth(); // Guidistry QA user pool

let activeContext: string | null = null; // a membership ID from GET /v1/me

export const api = createGuidistryClient({
  baseUrl: import.meta.env.VITE_GUIDISTRY_API_URL ?? "/guidistry/api",
  getAccessToken,
  getContext: () => activeContext,
});
export const setContext = (membershipId: string | null) => {
  activeContext = membershipId;
};
```

## 签名( 先识别)

```ts
import { confirmSignIn, startSignIn } from "@brightoutcome/guidistry-client/auth";

const start = await startSignIn(api, "gloria@example.org");
if (start.kind === "sso") {
  // later: redirect to the organization's sign-in (not used in January)
} else {
  const { nextStep } = start.output;
  // "CONTINUE_SIGN_IN_WITH_FIRST_FACTOR_SELECTION": show nextStep.availableChallenges
  //    (EMAIL_OTP, WEB_AUTHN, PASSWORD, …) and send the choice:
  //    await confirmSignIn({ challengeResponse: "EMAIL_OTP" })
  // "CONFIRM_SIGN_IN_WITH_EMAIL_CODE": await confirmSignIn({ challengeResponse: code })
  // "CONFIRM_SIGN_IN_WITH_PASSWORD":   await confirmSignIn({ challengeResponse: password })
  // "DONE": signed in
}
```

在第一次登录后,提供密码: `registerPasskey()`。用 `signOut()`。 。 。 .

## 给API打电话

```ts
const { data: me } = await api.GET("/v1/me");
// me.memberships: the contexts this person can act in; pick one with setContext(m.id)

const { data: people } = await api.GET("/v1/people", { params: { query: { q: "lind" } } });

await api.POST("/v1/invitations", {
  body: { email: "new@clinic.org", role: "provider", names: { given: "Mara", family: "Whitfield" } },
});
```

程序模板(称为API课程)和程序:

```ts
const { data: templates } = await api.GET("/v1/courses");
// each: name, current_version ("v1.3"), versions (e.g. Groups / Community / Solo), levels, rights

const { data: owl } = await api.GET("/v1/courses/{course_id}/content", {
  params: { path: { course_id: templates![0].id }, query: { version: "groups", view: "participant" } },
});
// owl.modules[].topics[].blocks[]: text blocks carry sanitized `html`; media carry a short-lived `signed_url`

const { data: program } = await api.POST("/v1/programs", {
  body: { name: "Lakeside OWL", course_id: templates![0].id, version_key: "groups" },
});
await api.GET("/v1/programs/{program_id}/content", { params: { path: { program_id: program!.id } } });
```

已签名的媒体链接过期( 默认为两个小时): 获取内容而不是存储 .

调用失败 `GuidistryError` 与 `status` 财务报告和审定财务报表 `problem` (标题,细节, request id). A 类 `409` 从大多数端点表示"选择上下文"(人物拥有不止一个会员).

## 版本

语义化版本:新大版本指破解API更改后随手取出. 发行版本仅由Guidistry管道(npm可信赖的出版)发布.

## 常见问题

### @brightoutcome/guidistry-client 是什么？

Guidistry API 的客户端和签名助手

### 如何安装 @brightoutcome/guidistry-client？

在项目目录运行 npm install @brightoutcome/guidistry-client，或使用 pnpm add / yarn add / bun add。

### @brightoutcome/guidistry-client 支持 TypeScript 吗？

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

### @brightoutcome/guidistry-client 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @brightoutcome/guidistry-client 可以商用吗？

@brightoutcome/guidistry-client 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @brightoutcome/guidistry-client 的下载量有多少？

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

### @brightoutcome/guidistry-client 还在维护吗？

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