简介

gstable-js 是 GStable 支付 API 的官方 Node.js 18+ 客户端，为你提供：

• 类型化资源 — GStableClient 暴露与 API 域一一对应的命名空间（商品、支付链接、收银会话、Webhook、账户、公开能力）。
• 零运行时依赖 — 使用平台自带的 fetch；发布 ESM 与 CJS，并附带 TypeScript 类型声明。
• 信封处理 — 解析标准 { code, message, data } 响应，成功时返回 data，失败时抛出 GStableError（及子类）。
• 两种 HTTP 模式 — 对 私有 根 URL 的鉴权调用，以及对 公开 端点的无 Authorization 调用（能力发现）。

架构（心智模型）

1. GStableClient 校验 apiKey，构造 GStableHttp，并为每个 API 域构造一个 *Resource 实例（product、account、payment link、capability、checkout session、webhook）。
2. 多数资源方法通过 http.requestJson 访问配置好的 私有 base URL，并携带 Bearer 令牌。
3. client.capability.all() 使用 http.requestPublicJson 访问 publicBaseUrl，不会为该请求发送 Authorization 头。

SDK 不包含的内容

• 仅控制台流程 — 在公开 API 中无法创建或修改商户账户；client.account 只读（列表 + 详情）。
• 面向浏览器的一等打包 — 包目标为 Node 18+。浏览器应用请通过你的后端调用 SDK，或由可信服务端代理请求。
• Webhook 签名校验助手 — SDK 通过管理 API 管理 Webhook 端点（create、update、refreshKey 等）。校验来自 GStable 的入站 HTTP 回调由应用自行实现（使用各技术栈的加密能力与 API 文档中的签名规则）。

环境要求

要求	说明
Node.js	≥ 18（全局 fetch）。
API key	控制台发放的密钥；切勿提交到 git。

权威定义

• 请求/响应字段 — API 文档。
• 方法 ↔ 路径映射 — Client 概览 及 API 参考 下的各资源页。

下一步

• 快速开始 — 最小可运行示例。
• 安装 — 包管理器、ESM/CJS、TypeScript。
• 客户端配置 — baseUrl、publicBaseUrl、调试开关。