@gathertown/webhook-object-sdk

中文文档
0.3.0发布于 2026/09/04MIT OR Apache-2.0TypeScriptCommonJS近 30 天下载 3.7万

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

中文使用文档
文档目录3 节
  1. 使用量
  2. 对象目录
  3. 电线行为

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

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

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

使用量

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

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方法 :

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

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

对象目录

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

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 共发布 4 个版本,首次发布于 2026/07/20;过去 12 个月发布了 4 个版本。

版本发布日期距今
0.3.0latest2026/09/042 个月前
0.2.02026/07/293 个月前
0.1.12026/07/203 个月前
0.1.02026/07/203 个月前

关于 @gathertown/webhook-object-sdk 的常见问题

@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 和提交记录判断。