# @gathertown/webhook-object-sdk 中文文档

规范地址：https://npmcn.com/package/%40gathertown/webhook-object-sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-09-04T10:11:43.388Z
中文译文更新时间：2026-11-16T00:00:38.103Z
软件包许可：MIT OR Apache-2\.0

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

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

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

- 包体积（解压后）：86.1 kB，22 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：2 个
- 首次发布：2026-07-20T13:28:15.130Z
- 最新版本发布：2026-09-04T10:11:43.222Z
- 近 30 天下载量：36820（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

为 Guard webhook 对象( Smart Objects) 发送事件输入的客户端 : 标准的Webhooks签名,再试,以及一个全价发送API.

## 安装

```sh
npm install @gathertown/webhook-object-sdk
```

也可以使用：`pnpm add @gathertown/webhook-object-sdk`、`yarn add @gathertown/webhook-object-sdk`、`bun add @gathertown/webhook-object-sdk`

## README

# @gathertown/webhook-object-sdk (英语)

用于向 Gather webhook 对象( Smart Objects) 发送事件的打出客户端 。 处理 电线协议的分部分(标准Webhooks v1 签名、重试、速率限制和 完全类型安全后的错误解码 `send`。 。 。 .

事件类型和有效载荷形状来自 [`@gathertown/webhook-object-types`](https://www.npmjs.com/package/@gathertown/webhook-object-types), (中文(简体) ), 生成自 Gather 服务器执行的相同定义。 当新的能力船, 这个SDK通过一个类型包来取出它们,不需要SDK放出.

## 使用量

每个智能对象都是一个 `(url, secret)` ,对齐,从Gather中对象的QQ菜单中复制. 秘密是每个对象的:一个对象的密钥永远不会认证另一个对象.

```ts
import { createWebhookObjectClient, secretFromEnv } from "@gathertown/webhook-object-sdk"

const counter = createWebhookObjectClient({
  url: process.env.GATHER_COUNTER_URL!,
  secret: secretFromEnv("GATHER_COUNTER_SECRET"), // whsec_…, read from the environment
})

await counter.send("counter.increment", { by: 2 }) // data type inferred from the event type
await counter.send("counter.reset") // empty-payload events take no data argument
await counter.ping() // verify url + secret; returns the object's declared capabilities
```

`secret` 接受原始数据 `whsec_…` 弦,所以它直接插进任何秘密 您已经掌握了管理权限。 不透明手柄是上面推荐的硬化: `secretFromEnv(name)` 读取变量本身,如果它有的话,一个手柄会自行修改 到达日志或 `JSON.stringify`赤裸的绳子不能 对于来自其他地方的数值(a) 秘密经理,一个非节点运行时间, `unsafeSecretLiteral(value)` 包裹; 名称 使硬码的秘密易于被审查.

每个事件也可以作为具有相同打字功能的命名空间糖; snake case 电线名称成为骆驼Case方法 :

```ts
await counter.counter.increment({ by: 2 })
await counter.counter.reset()
await lamp.switch.setState({ on: true }) // → switch.set_state
```

流利的表面来自生成的事件结合,并辅以 `Proxy`,这样新的 能力通过零SDK变化的打字机包来出现.

### 对象目录

要保持数个物体(收件箱,灯具,柜台,.)的手头,要建立一个取名的目录. 一个 条目的可选 `preset` 缩小其 `send` 编辑时间到预设的事件 宣布,所以将灯的事件接入收件箱是类型错误,而不是运行时间404.

```ts
import { createWebhookObjectCatalog } from "@gathertown/webhook-object-sdk"

const office = createWebhookObjectCatalog({
  supportInbox: { url: INBOX_URL, secret: secretFromEnv("GATHER_INBOX_SECRET"), preset: "inbox" },
  buildLamp: { url: LAMP_URL, secret: secretFromEnv("GATHER_LAMP_SECRET"), preset: "switch" },
})

await office.supportInbox.send("activity.add", { id: "pr-142", text: "PR #142 merged" })
await office.buildLamp.send("switch.toggle")
```

## 电线行为

-   与 `standardwebhooks` 参考图书馆: HMAC-SHA256 over `${webhook-id}.${webhook-timestamp}.${body}`,作为 `webhook-id` 编号 : `webhook-timestamp` 编号 : `webhook-signature` 头. 确切的序列体是签名和 发送未变.
-   一个 `webhook-id` 每起事件( UUID), 重复使用; 服务器取消最后 10 个 每个物体的IDs,所以重试是一能. 每一次重试均以新的时间戳重新签名.
-   仅检索瞬间故障(429, 5xx, 网络错误), 荣誉 `RateLimit-Reset` 编号 : `Retry-After`,以指数回放 + 抖动 否则。 4xx的失败永远不会重试.
-   通过 a 可取消 `signal` (单位:千美元)`AbortSignal`在配置中:中止将取消飞行中的请求 和任何待决退缩 `aborted` 错误.
-   在服务器的 4 KB 机身盖客户端上拒绝有效载荷,但明显错误而不是 接收器的制服 `404`。 。 。 .
-   拒绝`https` 构造时的 URL( 签名认证但不加密) , 与 a 一个 `http` 预留 `localhost` 当地的发展继续运作.
-   永远不暴露秘密:错误信息永远不会包含它,不透明处理的形式 此外,在登录或序列化时,还要自行编辑.
-   失败投出 `WebhookObjectError` 带有 `code` 映射服务器的错误正体 (单位:千美元)`not_found`, (中文(简体) ), `capability_not_declared`, (中文(简体) ), `token_revoked`,.)加上客户端代码 (单位:千美元)`payload_too_large`, (中文(简体) ), `invalid_secret`, (中文(简体) ), `invalid_url`, (中文(简体) ), `network_error`, (中文(简体) ), `aborted`, (中文(简体) ), `unexpected_response`) (中文(简体) ).

全球用途 `fetch` 财务报告和审定财务报表 `crypto.randomUUID` 默认(节点19+,现代浏览器,Deno, 劳工。 两者都通过配置可以压倒一切. 弹出 `fetch` 和(或) `newWebhookId` 其他费用 运行时间、代理或确定性测试.

## 常见问题

### @gathertown/webhook-object-sdk 是什么？

为 Guard webhook 对象\( Smart Objects\) 发送事件输入的客户端 : 标准的Webhooks签名,再试,以及一个全价发送API\.

### 如何安装 @gathertown/webhook-object-sdk？

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

### @gathertown/webhook-object-sdk 支持 TypeScript 吗？

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

### @gathertown/webhook-object-sdk 支持 ESM 还是 CommonJS？

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

### @gathertown/webhook-object-sdk 需要什么版本的 Node\.js？

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

### @gathertown/webhook-object-sdk 可以商用吗？

@gathertown/webhook-object-sdk 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @gathertown/webhook-object-sdk 的下载量有多少？

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

### @gathertown/webhook-object-sdk 还在维护吗？

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

