@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 其他费用
运行时间、代理或确定性测试.