# @cyc-seattle/gsuite-sdk 中文文档

规范地址：https://npmcn.com/package/%40cyc-seattle/gsuite-sdk/

版本：1\.0\.0
npm 元数据更新时间：2026-11-03T00:41:17.366Z
中文译文更新时间：2026-11-13T07:05:22.892Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：73.2 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- 首次发布：2026-10-12T19:27:11.776Z
- 最新版本发布：2026-11-03T00:41:16.972Z
- 近 30 天下载量：2141（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：6（近 12 个月 6 个）

## 中文简介

围绕 Google 工作空间 API 的域名不可知包装

## 安装

```sh
npm install @cyc-seattle/gsuite-sdk
```

也可以使用：`pnpm add @cyc-seattle/gsuite-sdk`、`yarn add @cyc-seattle/gsuite-sdk`、`bun add @cyc-seattle/gsuite-sdk`

## README

# @cyc-seattle/gsuite-sdk (中文(简体) )

围绕Google Workspace API进行打包:Admin SDK目录和组设置.

```sh
pnpm add @cyc-seattle/gsuite-sdk
```

每个客户都要一个 `GoogleAuth` 实例 `googleapis`。它使用应用程序默认证书(ADC),除非您通过一个密钥。 设定 `scopes` 你给API打电话.

## 目录和组设置

```ts
import { DirectoryClient, GroupSettingsClient } from "@cyc-seattle/gsuite-sdk";
import { google } from "googleapis";

const auth = new google.auth.GoogleAuth({
  scopes: [
    "https://www.googleapis.com/auth/admin.directory.group",
    "https://www.googleapis.com/auth/apps.groups.settings",
  ],
});
const members = await new DirectoryClient(auth).listMembers("team@example.org");
const settings = await new GroupSettingsClient(auth).getSettings("team@example.org");
```

### 客户选项

`DirectoryClient` 财务报告和审定财务报表 `GroupSettingsClient` 选择第二个参数 :

-   `rootUrl` 向谷歌以外的地方发送请求,例如 [工作空间假](https://npmcn.com/package/%40cyc-seattle/gsuite-sdk/#readme-workspace-fake). googleapis只使用它的起源.
-   `pacing` 套装 `safeCall`等待时间 : `requestDelayMs` 在每项请求之前(违约500起)和 `retryDelayMs` 在重试瞬间错误(默认为6000)之前.

```ts
const directory = new DirectoryClient(auth, { rootUrl, pacing: { requestDelayMs: 0, retryDelayMs: 0 } });
```

## 检索

`safeCall` 结束请求 。 它在请求和重试瞬间错误之间等待,例如速率限制和5xx响应.

```ts
import { safeCall } from "@cyc-seattle/gsuite-sdk";

await safeCall(() => row.save());
```

`safeCall(request, pacing)` 一样 `pacing` 作为客户.

## 工作空间假

`@cyc-seattle/gsuite-sdk/fake` 设置目录和组设置 API。 它服务于呼叫 `DirectoryClient` 财务报告和审定财务报表 `GroupSettingsClient` 做,从记忆.

```ts
import { ManualClock, WorkspaceModel, startFakeServer } from "@cyc-seattle/gsuite-sdk/fake";

const clock = new ManualClock();
const fake = await startFakeServer({ model: new WorkspaceModel({ clock }) });
const directory = new DirectoryClient(auth, { rootUrl: fake.rootUrl, pacing: { requestDelayMs: 0, retryDelayMs: 0 } });
// ...
await fake.close();
```

`startFakeServer` 在自由回放端口上监听, 除非给出 `host` 财务报告和审定财务报表 `port`。客户端仍然需要一个认证对象,但假的忽略了它的代号。 A 类 `GoogleAuth` 谁 `authClient` 是一个 `UserRefreshClient` 持有任何访问符不需要 ADC . `test/features/world.ts` 建立一个.

`WorkspaceModel` 拥有团体、成员和设置。 在单位测试中直接使用,或在测试前播种:通过 `{ settled: true }` 改为 `insertGroup` 或者说 `insertMember` 以跳过新组延迟。 其选项:

| 选项 | 默认 | 它会做什么 |
| --- | --- | --- |
| `clock` | 系统 | 模特儿看时间的地方. `ManualClock` 继续前进 `advance(ms)`。 。 。 . |
| `newGroupDelayMs` | 60 000 个 | 新组拒绝成员插入多久 |
| `pageSize` | 200个 | 列表返回的最大页面 |

它和谷歌一样回答:

| 大小写 | 状态 | 原因 | 消息 |
| --- | --- | --- | --- |
| 一个未知的组 | 404 (韩语) | `notFound` | `Resource Not Found: groupKey` |
| 一个未知成员 | 404 (韩语) | `notFound` | `Resource Not Found: memberKey` |
| 成员插入一个组合中仍然太新 | 404 (韩语) | `notFound` | `Resource Not Found: groupKey` |
| 已经是成员了 | 409个 | `duplicate` | `Member already exists.` |
| 已经存在的组 | 409个 | `duplicate` | `Entity already exists.` |
| 成员构成周期 | 412号 | `conditionNotMet` | `Cyclic memberships not allowed` |
| 未知组的设置 | 404 (韩语) | `notFound` | `Not Found` |

Google不记录循环状态或设置404消息. 假的跟JSON API的公约一样.

衍生的会籍没有被模拟,因为SDK只读取直接会籍.

分组设置在 Atom XML 中回答, 除非请求请求 `alt=json`就像谷歌一样.

### 容器图像

每期发布 `ghcr.io/cyc-seattle/workspace-fake:<version>` 财务报告和审定财务报表 `:latest`从 `Dockerfile`假的忽略了认证符 所以任何无记名符号都有效.

-   它在8080号口听. `PORT` 改变这一点.
-   `NEW_GROUP_DELAY_MS` 设定新组拒绝成员插入的长度(默认为6000)。 准备吧 `0` 立即播种一个团体及其成员.
-   `GET /healthz` 返回 200.
-   它以 uid 1000 运行,没有写入文件,因此它使用只读的根文件系统工作,所有的能力被放弃.
-   通过目录 API 种子 : `POST /admin/directory/v1/groups`,则 `POST .../groups/<group>/members`。 。 。 .

```sh
docker run -p 8080:8080 -e NEW_GROUP_DELAY_MS=0 ghcr.io/cyc-seattle/workspace-fake
```

## 发展

`mise run test` 运行单元测试 `test/`。 。 。 . `mise run integration` 运行 Gherkin 特性 `features/` 在测试过程中开始的. `mise run ci` 运行两者, 之后 `check`。见 `AGENTS.md`。 。 。 .

## 释放

每次合并到 `main` 一旦CI通过,就会从PR标题中释放. 标题必须是常规承诺. `fix:` 使补丁发布, `feat:` 轻度释放,以及 `!` 类型之后是主释放。 类型,例如: `docs:`, (中文(简体) ), `build:`,以及 `test:` 释放什么。 语义-放行发布为npm并创建了GitHub发布.

## 常见问题

### @cyc-seattle/gsuite-sdk 是什么？

围绕 Google 工作空间 API 的域名不可知包装

### 如何安装 @cyc-seattle/gsuite-sdk？

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

### @cyc-seattle/gsuite-sdk 支持 TypeScript 吗？

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

### @cyc-seattle/gsuite-sdk 支持 ESM 还是 CommonJS？

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

### @cyc-seattle/gsuite-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyc-seattle/gsuite-sdk 可以商用吗？

@cyc-seattle/gsuite-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyc-seattle/gsuite-sdk 的下载量有多少？

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

### @cyc-seattle/gsuite-sdk 还在维护吗？

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