@stableops/api-sdk 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +184 -0
- package/README.md +117 -0
- package/README.zh-CN.md +107 -0
- package/dist/chunk-B2JLHYXK.mjs +83 -0
- package/dist/chunk-B2JLHYXK.mjs.map +1 -0
- package/dist/index.d.mts +247 -0
- package/dist/index.d.ts +247 -0
- package/dist/index.js +481 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +453 -0
- package/dist/index.mjs.map +1 -0
- package/dist/mock.d.mts +74 -0
- package/dist/mock.d.ts +74 -0
- package/dist/mock.js +268 -0
- package/dist/mock.js.map +1 -0
- package/dist/mock.mjs +219 -0
- package/dist/mock.mjs.map +1 -0
- package/dist/webhooks.d.mts +44 -0
- package/dist/webhooks.d.ts +44 -0
- package/dist/webhooks.js +134 -0
- package/dist/webhooks.js.map +1 -0
- package/dist/webhooks.mjs +37 -0
- package/dist/webhooks.mjs.map +1 -0
- package/package.json +87 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,184 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
https://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction, and
|
|
10
|
+
distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by the copyright
|
|
13
|
+
owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all other entities
|
|
16
|
+
that control, are controlled by, or are under common control with that entity.
|
|
17
|
+
For the purposes of this definition, "control" means (i) the power, direct or
|
|
18
|
+
indirect, to cause the direction or management of such entity, whether by
|
|
19
|
+
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
20
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
21
|
+
|
|
22
|
+
"You" (or "Your") shall mean an individual or Legal Entity exercising
|
|
23
|
+
permissions granted by this License.
|
|
24
|
+
|
|
25
|
+
"Source" form shall mean the preferred form for making modifications, including
|
|
26
|
+
but not limited to software source code, documentation source, and configuration
|
|
27
|
+
files.
|
|
28
|
+
|
|
29
|
+
"Object" form shall mean any form resulting from mechanical transformation or
|
|
30
|
+
translation of a Source form, including but not limited to compiled object code,
|
|
31
|
+
generated documentation, and conversions to other media types.
|
|
32
|
+
|
|
33
|
+
"Work" shall mean the work of authorship, whether in Source or Object form,
|
|
34
|
+
made available under the License, as indicated by a copyright notice that is
|
|
35
|
+
included in or attached to the work (an example is provided in the Appendix
|
|
36
|
+
below).
|
|
37
|
+
|
|
38
|
+
"Derivative Works" shall mean any work, whether in Source or Object form, that
|
|
39
|
+
is based on (or derived from) the Work and for which the editorial revisions,
|
|
40
|
+
annotations, elaborations, or other modifications represent, as a whole, an
|
|
41
|
+
original work of authorship. For the purposes of this License, Derivative Works
|
|
42
|
+
shall not include works that remain separable from, or merely link (or bind by
|
|
43
|
+
name) to the interfaces of, the Work and Derivative Works thereof.
|
|
44
|
+
|
|
45
|
+
"Contribution" shall mean any work of authorship, including the original
|
|
46
|
+
version of the Work and any modifications or additions to that Work or
|
|
47
|
+
Derivative Works thereof, that is intentionally submitted to Licensor for
|
|
48
|
+
inclusion in the Work by the copyright owner or by an individual or Legal Entity
|
|
49
|
+
authorized to submit on behalf of the copyright owner. For the purposes of this
|
|
50
|
+
definition, "submitted" means any form of electronic, verbal, or written
|
|
51
|
+
communication sent to the Licensor or its representatives, including but not
|
|
52
|
+
limited to communication on electronic mailing lists, source code control
|
|
53
|
+
systems, and issue tracking systems that are managed by, or on behalf of, the
|
|
54
|
+
Licensor for the purpose of discussing and improving the Work, but excluding
|
|
55
|
+
communication that is conspicuously marked or otherwise designated in writing by
|
|
56
|
+
the copyright owner as "Not a Contribution."
|
|
57
|
+
|
|
58
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf
|
|
59
|
+
of whom a Contribution has been received by Licensor and subsequently
|
|
60
|
+
incorporated within the Work.
|
|
61
|
+
|
|
62
|
+
2. Grant of Copyright License. Subject to the terms and conditions of this
|
|
63
|
+
License, each Contributor hereby grants to You a perpetual, worldwide,
|
|
64
|
+
non-exclusive, no-charge, royalty-free, irrevocable copyright license to
|
|
65
|
+
reproduce, prepare Derivative Works of, publicly display, publicly perform,
|
|
66
|
+
sublicense, and distribute the Work and such Derivative Works in Source or
|
|
67
|
+
Object form.
|
|
68
|
+
|
|
69
|
+
3. Grant of Patent License. Subject to the terms and conditions of this
|
|
70
|
+
License, each Contributor hereby grants to You a perpetual, worldwide,
|
|
71
|
+
non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
|
|
72
|
+
section) patent license to make, have made, use, offer to sell, sell, import,
|
|
73
|
+
and otherwise transfer the Work, where such license applies only to those patent
|
|
74
|
+
claims licensable by such Contributor that are necessarily infringed by their
|
|
75
|
+
Contribution(s) alone or by combination of their Contribution(s) with the Work
|
|
76
|
+
to which such Contribution(s) was submitted. If You institute patent litigation
|
|
77
|
+
against any entity (including a cross-claim or counterclaim in a lawsuit)
|
|
78
|
+
alleging that the Work or a Contribution incorporated within the Work
|
|
79
|
+
constitutes direct or contributory patent infringement, then any patent licenses
|
|
80
|
+
granted to You under this License for that Work shall terminate as of the date
|
|
81
|
+
such litigation is filed.
|
|
82
|
+
|
|
83
|
+
4. Redistribution. You may reproduce and distribute copies of the Work or
|
|
84
|
+
Derivative Works thereof in any medium, with or without modifications, and in
|
|
85
|
+
Source or Object form, provided that You meet the following conditions:
|
|
86
|
+
|
|
87
|
+
(a) You must give any other recipients of the Work or Derivative Works a copy of
|
|
88
|
+
this License; and
|
|
89
|
+
|
|
90
|
+
(b) You must cause any modified files to carry prominent notices stating that
|
|
91
|
+
You changed the files; and
|
|
92
|
+
|
|
93
|
+
(c) You must retain, in the Source form of any Derivative Works that You
|
|
94
|
+
distribute, all copyright, patent, trademark, and attribution notices from the
|
|
95
|
+
Source form of the Work, excluding those notices that do not pertain to any part
|
|
96
|
+
of the Derivative Works; and
|
|
97
|
+
|
|
98
|
+
(d) If the Work includes a "NOTICE" text file as part of its distribution, then
|
|
99
|
+
any Derivative Works that You distribute must include a readable copy of the
|
|
100
|
+
attribution notices contained within such NOTICE file, excluding those notices
|
|
101
|
+
that do not pertain to any part of the Derivative Works, in at least one of the
|
|
102
|
+
following places: within a NOTICE text file distributed as part of the
|
|
103
|
+
Derivative Works; within the Source form or documentation, if provided along
|
|
104
|
+
with the Derivative Works; or, within a display generated by the Derivative
|
|
105
|
+
Works, if and wherever such third-party notices normally appear. The contents of
|
|
106
|
+
the NOTICE file are for informational purposes only and do not modify the
|
|
107
|
+
License. You may add Your own attribution notices within Derivative Works that
|
|
108
|
+
You distribute, alongside or as an addendum to the NOTICE text from the Work,
|
|
109
|
+
provided that such additional attribution notices cannot be construed as
|
|
110
|
+
modifying the License.
|
|
111
|
+
|
|
112
|
+
You may add Your own copyright statement to Your modifications and may provide
|
|
113
|
+
additional or different license terms and conditions for use, reproduction, or
|
|
114
|
+
distribution of Your modifications, or for any such Derivative Works as a whole,
|
|
115
|
+
provided Your use, reproduction, and distribution of the Work otherwise complies
|
|
116
|
+
with the conditions stated in this License.
|
|
117
|
+
|
|
118
|
+
5. Submission of Contributions. Unless You explicitly state otherwise, any
|
|
119
|
+
Contribution intentionally submitted for inclusion in the Work by You to the
|
|
120
|
+
Licensor shall be under the terms and conditions of this License, without any
|
|
121
|
+
additional terms or conditions. Notwithstanding the above, nothing herein shall
|
|
122
|
+
supersede or modify the terms of any separate license agreement you may have
|
|
123
|
+
executed with Licensor regarding such Contributions.
|
|
124
|
+
|
|
125
|
+
6. Trademarks. This License does not grant permission to use the trade names,
|
|
126
|
+
trademarks, service marks, or product names of the Licensor, except as required
|
|
127
|
+
for reasonable and customary use in describing the origin of the Work and
|
|
128
|
+
reproducing the content of the NOTICE file.
|
|
129
|
+
|
|
130
|
+
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
|
|
131
|
+
writing, Licensor provides the Work (and each Contributor provides its
|
|
132
|
+
Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
133
|
+
KIND, either express or implied, including, without limitation, any warranties
|
|
134
|
+
or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
135
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
136
|
+
appropriateness of using or redistributing the Work and assume any risks
|
|
137
|
+
associated with Your exercise of permissions under this License.
|
|
138
|
+
|
|
139
|
+
8. Limitation of Liability. In no event and under no legal theory, whether in
|
|
140
|
+
tort (including negligence), contract, or otherwise, unless required by
|
|
141
|
+
applicable law (such as deliberate and grossly negligent acts) or agreed to in
|
|
142
|
+
writing, shall any Contributor be liable to You for damages, including any
|
|
143
|
+
direct, indirect, special, incidental, or consequential damages of any
|
|
144
|
+
character arising as a result of this License or out of the use or inability to
|
|
145
|
+
use the Work (including but not limited to damages for loss of goodwill, work
|
|
146
|
+
stoppage, computer failure or malfunction, or any and all other commercial
|
|
147
|
+
damages or losses), even if such Contributor has been advised of the
|
|
148
|
+
possibility of such damages.
|
|
149
|
+
|
|
150
|
+
9. Accepting Warranty or Additional Liability. While redistributing the Work or
|
|
151
|
+
Derivative Works thereof, You may choose to offer, and charge a fee for,
|
|
152
|
+
acceptance of support, warranty, indemnity, or other liability obligations
|
|
153
|
+
and/or rights consistent with this License. However, in accepting such
|
|
154
|
+
obligations, You may act only on Your own behalf and on Your sole
|
|
155
|
+
responsibility, not on behalf of any other Contributor, and only if You agree
|
|
156
|
+
to indemnify, defend, and hold each Contributor harmless for any liability
|
|
157
|
+
incurred by, or claims asserted against, such Contributor by reason of your
|
|
158
|
+
accepting any such warranty or additional liability.
|
|
159
|
+
|
|
160
|
+
END OF TERMS AND CONDITIONS
|
|
161
|
+
|
|
162
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
163
|
+
|
|
164
|
+
To apply the Apache License to your work, attach the following boilerplate
|
|
165
|
+
notice, with the fields enclosed by brackets "[]" replaced with your own
|
|
166
|
+
identifying information. (Don't include the brackets!) The text should be
|
|
167
|
+
enclosed in the appropriate comment syntax for the file format. We also
|
|
168
|
+
recommend that a file or class name and description of purpose be included on
|
|
169
|
+
the same "printed page" as the copyright notice for easier identification
|
|
170
|
+
within third-party archives.
|
|
171
|
+
|
|
172
|
+
Copyright [yyyy] [name of copyright owner]
|
|
173
|
+
|
|
174
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
175
|
+
you may not use this file except in compliance with the License.
|
|
176
|
+
You may obtain a copy of the License at
|
|
177
|
+
|
|
178
|
+
https://www.apache.org/licenses/LICENSE-2.0
|
|
179
|
+
|
|
180
|
+
Unless required by applicable law or agreed to in writing, software
|
|
181
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
182
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
183
|
+
See the License for the specific language governing permissions and
|
|
184
|
+
limitations under the License.
|
package/README.md
ADDED
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# StableOps API SDK
|
|
2
|
+
|
|
3
|
+
Official TypeScript SDK for the StableOps API.
|
|
4
|
+
|
|
5
|
+
[中文文档](./README.zh-CN.md)
|
|
6
|
+
|
|
7
|
+
StableOps turns on-chain stablecoin transfers into familiar payment primitives:
|
|
8
|
+
payment orders, deterministic status transitions, signed webhooks, retries, and
|
|
9
|
+
confirmation tracking. You bring the receiving addresses or custody setup;
|
|
10
|
+
StableOps watches supported chains, matches transfers, tracks confirmations,
|
|
11
|
+
checks reorgs, and delivers webhook events to your application.
|
|
12
|
+
|
|
13
|
+
This SDK is intended for server-side TypeScript and JavaScript applications that
|
|
14
|
+
create payment orders, query normalized chain events, manage webhook endpoints,
|
|
15
|
+
and verify webhook signatures.
|
|
16
|
+
|
|
17
|
+
## Features
|
|
18
|
+
|
|
19
|
+
- Type-safe client for payment orders, events, and webhook endpoints.
|
|
20
|
+
- Built-in request retry behavior for transient failures.
|
|
21
|
+
- Explicit idempotency support for write operations.
|
|
22
|
+
- Constant-time webhook signature verification.
|
|
23
|
+
- In-process mock server for tests, examples, and local demos.
|
|
24
|
+
- Self-contained public types with no StableOps workspace dependencies.
|
|
25
|
+
- Dual CJS and ESM builds with generated TypeScript declarations.
|
|
26
|
+
|
|
27
|
+
## Requirements
|
|
28
|
+
|
|
29
|
+
- Node.js 18 or newer.
|
|
30
|
+
- A StableOps API key.
|
|
31
|
+
- A server-side environment. Do not expose your API key in browser code.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pnpm add @stableops/api-sdk
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @stableops/api-sdk
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
yarn add @stableops/api-sdk
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { StableOps } from '@stableops/api-sdk'
|
|
51
|
+
|
|
52
|
+
const stableops = new StableOps({
|
|
53
|
+
apiKey: process.env.STABLEOPS_API_KEY!,
|
|
54
|
+
organizationSlug: 'demo',
|
|
55
|
+
environment: 'sandbox',
|
|
56
|
+
})
|
|
57
|
+
|
|
58
|
+
const order = await stableops.paymentOrders.create(
|
|
59
|
+
{
|
|
60
|
+
merchantOrderId: 'order_123',
|
|
61
|
+
amount: '49.00',
|
|
62
|
+
settlementAsset: 'USDC',
|
|
63
|
+
acceptedAssets: [
|
|
64
|
+
{ chain: 'base-sepolia', asset: 'USDC' },
|
|
65
|
+
{ chain: 'ethereum-sepolia', asset: 'USDC' },
|
|
66
|
+
],
|
|
67
|
+
metadata: { customerId: 'cus_123', plan: 'pro_monthly' },
|
|
68
|
+
},
|
|
69
|
+
{ idempotencyKey: 'order_123:create' },
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
console.log(order.paymentInstructions)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Webhook verification and the mock server use explicit Node-only subpath exports:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
import {
|
|
79
|
+
SIGNATURE_HEADER,
|
|
80
|
+
verifySignature,
|
|
81
|
+
} from '@stableops/api-sdk/webhooks'
|
|
82
|
+
import { MockServer } from '@stableops/api-sdk/mock'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The default `@stableops/api-sdk` entry does not import Node `crypto` or `http`
|
|
86
|
+
modules, so edge-compatible server runtimes can use the API client when they
|
|
87
|
+
provide `fetch`, `AbortController`, and `crypto.randomUUID`.
|
|
88
|
+
|
|
89
|
+
Return only the order id, amount, and `paymentInstructions` to your frontend.
|
|
90
|
+
The actual API key and order creation flow should stay on your server.
|
|
91
|
+
|
|
92
|
+
## Documentation
|
|
93
|
+
|
|
94
|
+
For complete guides, API references, payment lifecycle details, webhook
|
|
95
|
+
verification, and wallet integration examples, see the official documentation:
|
|
96
|
+
|
|
97
|
+
- English docs: https://stableops.dev/en/docs
|
|
98
|
+
- Chinese docs: https://stableops.dev/zh/docs
|
|
99
|
+
|
|
100
|
+
## Supported Chains and Assets
|
|
101
|
+
|
|
102
|
+
This SDK supports:
|
|
103
|
+
|
|
104
|
+
- Chains: Ethereum, Base, Arbitrum, Polygon, TRON, Solana, and supported testnets.
|
|
105
|
+
- Assets: USDC and USDT.
|
|
106
|
+
|
|
107
|
+
StableOps may support a subset of chain/asset pairs per environment and
|
|
108
|
+
organization configuration. Use the dashboard or API configuration for the
|
|
109
|
+
source of truth in production. See the official docs for the latest supported
|
|
110
|
+
chains, assets, and environment-specific setup:
|
|
111
|
+
|
|
112
|
+
- https://stableops.dev/en/docs
|
|
113
|
+
- https://stableops.dev/zh/docs
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
This SDK is licensed under `Apache-2.0`. See [LICENSE](./LICENSE).
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
# StableOps API SDK
|
|
2
|
+
|
|
3
|
+
StableOps 官方 TypeScript SDK。
|
|
4
|
+
|
|
5
|
+
[View English README](./README.md)
|
|
6
|
+
|
|
7
|
+
StableOps 将链上稳定币转账抽象成开发者熟悉的支付基础设施:Payment Order、确定性的状态机、签名 Webhook、失败重试和确认数跟踪。你负责业务订单、收款地址或托管设置;StableOps 负责链上扫描、转账匹配、确认数推进、重组检查和 Webhook 投递。
|
|
8
|
+
|
|
9
|
+
这个 SDK 适合服务端 TypeScript / JavaScript 应用,用于创建支付订单、查询标准化链上事件、管理 Webhook Endpoint,并验证 Webhook 签名。
|
|
10
|
+
|
|
11
|
+
## 功能
|
|
12
|
+
|
|
13
|
+
- 类型友好的 Payment Orders、Events、Webhook Endpoints API。
|
|
14
|
+
- 对临时错误内置重试策略。
|
|
15
|
+
- 写请求显式支持幂等键。
|
|
16
|
+
- 内置常量时间 Webhook 签名验证。
|
|
17
|
+
- 提供进程内 Mock Server,便于测试、示例和本地演示。
|
|
18
|
+
- Public types 已内联,不依赖 StableOps 内部 workspace 包。
|
|
19
|
+
- 同时输出 CJS、ESM 和 TypeScript 类型声明。
|
|
20
|
+
|
|
21
|
+
## 环境要求
|
|
22
|
+
|
|
23
|
+
- Node.js 18 或更高版本。
|
|
24
|
+
- StableOps API Key。
|
|
25
|
+
- 服务端运行环境。不要把 API Key 暴露到浏览器代码里。
|
|
26
|
+
|
|
27
|
+
## 安装
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pnpm add @stableops/api-sdk
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
npm install @stableops/api-sdk
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
yarn add @stableops/api-sdk
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## 快速开始
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { StableOps } from '@stableops/api-sdk'
|
|
45
|
+
|
|
46
|
+
const stableops = new StableOps({
|
|
47
|
+
apiKey: process.env.STABLEOPS_API_KEY!,
|
|
48
|
+
organizationSlug: 'demo',
|
|
49
|
+
environment: 'sandbox',
|
|
50
|
+
})
|
|
51
|
+
|
|
52
|
+
const order = await stableops.paymentOrders.create(
|
|
53
|
+
{
|
|
54
|
+
merchantOrderId: 'order_123',
|
|
55
|
+
amount: '49.00',
|
|
56
|
+
settlementAsset: 'USDC',
|
|
57
|
+
acceptedAssets: [
|
|
58
|
+
{ chain: 'base-sepolia', asset: 'USDC' },
|
|
59
|
+
{ chain: 'ethereum-sepolia', asset: 'USDC' },
|
|
60
|
+
],
|
|
61
|
+
metadata: { customerId: 'cus_123', plan: 'pro_monthly' },
|
|
62
|
+
},
|
|
63
|
+
{ idempotencyKey: 'order_123:create' },
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
console.log(order.paymentInstructions)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Webhook 验签和 Mock Server 使用独立的 Node.js 子路径入口:
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
import {
|
|
73
|
+
SIGNATURE_HEADER,
|
|
74
|
+
verifySignature,
|
|
75
|
+
} from '@stableops/api-sdk/webhooks'
|
|
76
|
+
import { MockServer } from '@stableops/api-sdk/mock'
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
默认的 `@stableops/api-sdk` 入口不引入 Node `crypto` 或 `http` 模块。因此,只要
|
|
80
|
+
服务端 Edge Runtime 提供 `fetch`、`AbortController` 和 `crypto.randomUUID`,
|
|
81
|
+
就可以使用 API Client。
|
|
82
|
+
|
|
83
|
+
前端只需要拿到订单 id、金额和 `paymentInstructions`。API Key 和创建订单的逻辑应始终放在服务端。
|
|
84
|
+
|
|
85
|
+
## 官方文档
|
|
86
|
+
|
|
87
|
+
完整接入指南、API Reference、支付订单生命周期、Webhook 验签和钱包集成示例,请查看官方文档:
|
|
88
|
+
|
|
89
|
+
- 中文文档:https://stableops.dev/zh/docs
|
|
90
|
+
- English docs:https://stableops.dev/en/docs
|
|
91
|
+
|
|
92
|
+
## 支持的链和资产
|
|
93
|
+
|
|
94
|
+
当前 SDK 支持:
|
|
95
|
+
|
|
96
|
+
- 链:Ethereum、Base、Arbitrum、Polygon、TRON、Solana 以及支持的测试网。
|
|
97
|
+
- 资产:USDC 和 USDT。
|
|
98
|
+
|
|
99
|
+
实际可用的 chain/asset 组合可能受环境和组织配置影响。生产环境请以 Dashboard 或 API 配置为准。
|
|
100
|
+
最新支持范围和环境配置请参考官方文档:
|
|
101
|
+
|
|
102
|
+
- https://stableops.dev/zh/docs
|
|
103
|
+
- https://stableops.dev/en/docs
|
|
104
|
+
|
|
105
|
+
## License
|
|
106
|
+
|
|
107
|
+
本 SDK 使用 `Apache-2.0` 许可证。详见 [LICENSE](./LICENSE)。
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
// src/signature.ts
|
|
2
|
+
import { createHmac, timingSafeEqual } from "crypto";
|
|
3
|
+
var SIGNATURE_HEADER = "X-Product-Signature";
|
|
4
|
+
var EVENT_ID_HEADER = "X-Event-Id";
|
|
5
|
+
var DELIVERY_ID_HEADER = "X-Delivery-Id";
|
|
6
|
+
var DEFAULT_TOLERANCE_SECONDS = 5 * 60;
|
|
7
|
+
function buildSignatureHeader({
|
|
8
|
+
secret,
|
|
9
|
+
timestamp,
|
|
10
|
+
rawBody
|
|
11
|
+
}) {
|
|
12
|
+
return buildSignatureHeaderForSecrets({
|
|
13
|
+
secrets: [secret],
|
|
14
|
+
timestamp,
|
|
15
|
+
rawBody
|
|
16
|
+
});
|
|
17
|
+
}
|
|
18
|
+
function buildSignatureHeaderForSecrets({
|
|
19
|
+
secrets,
|
|
20
|
+
timestamp,
|
|
21
|
+
rawBody
|
|
22
|
+
}) {
|
|
23
|
+
const payload = `${timestamp}.${rawBody}`;
|
|
24
|
+
const signatures = secrets.filter((secret) => secret.length > 0).map((secret) => createHmac("sha256", secret).update(payload).digest("hex"));
|
|
25
|
+
return `t=${timestamp},${signatures.map((signature) => `v1=${signature}`).join(",")}`;
|
|
26
|
+
}
|
|
27
|
+
function verifySignature(input) {
|
|
28
|
+
if (!input.header) return { ok: false, reason: "missing_header" };
|
|
29
|
+
const parsed = parseHeader(input.header);
|
|
30
|
+
if (!parsed) return { ok: false, reason: "invalid_format" };
|
|
31
|
+
const now = input.now ?? Math.floor(Date.now() / 1e3);
|
|
32
|
+
const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
|
|
33
|
+
if (Math.abs(now - parsed.timestamp) > tolerance) {
|
|
34
|
+
return { ok: false, reason: "timestamp_expired" };
|
|
35
|
+
}
|
|
36
|
+
const payload = `${parsed.timestamp}.${input.rawBody}`;
|
|
37
|
+
for (const secret of input.secrets) {
|
|
38
|
+
if (!secret) continue;
|
|
39
|
+
const expected = createHmac("sha256", secret).update(payload).digest("hex");
|
|
40
|
+
for (const signature of parsed.signatures) {
|
|
41
|
+
if (safeEqualHex(expected, signature)) {
|
|
42
|
+
return { ok: true, timestamp: parsed.timestamp };
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return { ok: false, reason: "bad_signature" };
|
|
47
|
+
}
|
|
48
|
+
function parseHeader(header) {
|
|
49
|
+
let timestamp = null;
|
|
50
|
+
const signatures = [];
|
|
51
|
+
for (const segment of header.split(",")) {
|
|
52
|
+
const [key, value] = segment.trim().split("=");
|
|
53
|
+
if (!key || !value) continue;
|
|
54
|
+
if (key === "t") {
|
|
55
|
+
const ts = Number(value);
|
|
56
|
+
if (Number.isFinite(ts)) timestamp = ts;
|
|
57
|
+
} else if (key === "v1") {
|
|
58
|
+
signatures.push(value);
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
if (timestamp === null || signatures.length === 0) return null;
|
|
62
|
+
return { timestamp, signatures };
|
|
63
|
+
}
|
|
64
|
+
function safeEqualHex(a, b) {
|
|
65
|
+
if (!isSha256Hex(a) || !isSha256Hex(b)) return false;
|
|
66
|
+
const aBuffer = Buffer.from(a, "hex");
|
|
67
|
+
const bBuffer = Buffer.from(b, "hex");
|
|
68
|
+
return timingSafeEqual(aBuffer, bBuffer);
|
|
69
|
+
}
|
|
70
|
+
function isSha256Hex(value) {
|
|
71
|
+
return /^[a-f0-9]{64}$/i.test(value);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export {
|
|
75
|
+
SIGNATURE_HEADER,
|
|
76
|
+
EVENT_ID_HEADER,
|
|
77
|
+
DELIVERY_ID_HEADER,
|
|
78
|
+
DEFAULT_TOLERANCE_SECONDS,
|
|
79
|
+
buildSignatureHeader,
|
|
80
|
+
buildSignatureHeaderForSecrets,
|
|
81
|
+
verifySignature
|
|
82
|
+
};
|
|
83
|
+
//# sourceMappingURL=chunk-B2JLHYXK.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/signature.ts"],"sourcesContent":["import { createHmac, timingSafeEqual } from 'node:crypto'\n\n// 与服务端 webhook 签名格式保持一致:\n// X-Product-Signature: t=<unix_ts>,v1=<hmac_sha256(t.rawBody)>\n// SDK 内联实现,避免发布包依赖内部 workspace 包。\n\nexport const SIGNATURE_HEADER = 'X-Product-Signature'\nexport const EVENT_ID_HEADER = 'X-Event-Id'\nexport const DELIVERY_ID_HEADER = 'X-Delivery-Id'\nexport const DEFAULT_TOLERANCE_SECONDS = 5 * 60\n\nexport type SignatureBuildInput = {\n secret: string\n timestamp: number\n rawBody: string\n}\n\nexport type MultiSignatureBuildInput = {\n secrets: readonly string[]\n timestamp: number\n rawBody: string\n}\n\nexport type VerifyInput = {\n secrets: readonly string[]\n header: string | undefined\n rawBody: string\n now?: number\n toleranceSeconds?: number\n}\n\nexport type VerifyResult =\n | { ok: true; timestamp: number }\n | {\n ok: false\n reason:\n | 'missing_header'\n | 'invalid_format'\n | 'timestamp_expired'\n | 'bad_signature'\n }\n\nexport function buildSignatureHeader({\n secret,\n timestamp,\n rawBody,\n}: SignatureBuildInput): string {\n return buildSignatureHeaderForSecrets({\n secrets: [secret],\n timestamp,\n rawBody,\n })\n}\n\nexport function buildSignatureHeaderForSecrets({\n secrets,\n timestamp,\n rawBody,\n}: MultiSignatureBuildInput): string {\n const payload = `${timestamp}.${rawBody}`\n const signatures = secrets\n .filter((secret) => secret.length > 0)\n .map((secret) => createHmac('sha256', secret).update(payload).digest('hex'))\n return `t=${timestamp},${signatures.map((signature) => `v1=${signature}`).join(',')}`\n}\n\nexport function verifySignature(input: VerifyInput): VerifyResult {\n if (!input.header) return { ok: false, reason: 'missing_header' }\n const parsed = parseHeader(input.header)\n if (!parsed) return { ok: false, reason: 'invalid_format' }\n\n const now = input.now ?? Math.floor(Date.now() / 1000)\n const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS\n if (Math.abs(now - parsed.timestamp) > tolerance) {\n return { ok: false, reason: 'timestamp_expired' }\n }\n\n const payload = `${parsed.timestamp}.${input.rawBody}`\n for (const secret of input.secrets) {\n if (!secret) continue\n const expected = createHmac('sha256', secret).update(payload).digest('hex')\n for (const signature of parsed.signatures) {\n if (safeEqualHex(expected, signature)) {\n return { ok: true, timestamp: parsed.timestamp }\n }\n }\n }\n return { ok: false, reason: 'bad_signature' }\n}\n\nfunction parseHeader(\n header: string,\n): { timestamp: number; signatures: string[] } | null {\n let timestamp: number | null = null\n const signatures: string[] = []\n for (const segment of header.split(',')) {\n const [key, value] = segment.trim().split('=')\n if (!key || !value) continue\n if (key === 't') {\n const ts = Number(value)\n if (Number.isFinite(ts)) timestamp = ts\n } else if (key === 'v1') {\n signatures.push(value)\n }\n }\n if (timestamp === null || signatures.length === 0) return null\n return { timestamp, signatures }\n}\n\nfunction safeEqualHex(a: string, b: string): boolean {\n if (!isSha256Hex(a) || !isSha256Hex(b)) return false\n const aBuffer = Buffer.from(a, 'hex')\n const bBuffer = Buffer.from(b, 'hex')\n return timingSafeEqual(aBuffer, bBuffer)\n}\n\nfunction isSha256Hex(value: string): boolean {\n return /^[a-f0-9]{64}$/i.test(value)\n}\n"],"mappings":";AAAA,SAAS,YAAY,uBAAuB;AAMrC,IAAM,mBAAmB;AACzB,IAAM,kBAAkB;AACxB,IAAM,qBAAqB;AAC3B,IAAM,4BAA4B,IAAI;AAiCtC,SAAS,qBAAqB;AAAA,EACnC;AAAA,EACA;AAAA,EACA;AACF,GAAgC;AAC9B,SAAO,+BAA+B;AAAA,IACpC,SAAS,CAAC,MAAM;AAAA,IAChB;AAAA,IACA;AAAA,EACF,CAAC;AACH;AAEO,SAAS,+BAA+B;AAAA,EAC7C;AAAA,EACA;AAAA,EACA;AACF,GAAqC;AACnC,QAAM,UAAU,GAAG,SAAS,IAAI,OAAO;AACvC,QAAM,aAAa,QAChB,OAAO,CAAC,WAAW,OAAO,SAAS,CAAC,EACpC,IAAI,CAAC,WAAW,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK,CAAC;AAC7E,SAAO,KAAK,SAAS,IAAI,WAAW,IAAI,CAAC,cAAc,MAAM,SAAS,EAAE,EAAE,KAAK,GAAG,CAAC;AACrF;AAEO,SAAS,gBAAgB,OAAkC;AAChE,MAAI,CAAC,MAAM,OAAQ,QAAO,EAAE,IAAI,OAAO,QAAQ,iBAAiB;AAChE,QAAM,SAAS,YAAY,MAAM,MAAM;AACvC,MAAI,CAAC,OAAQ,QAAO,EAAE,IAAI,OAAO,QAAQ,iBAAiB;AAE1D,QAAM,MAAM,MAAM,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACrD,QAAM,YAAY,MAAM,oBAAoB;AAC5C,MAAI,KAAK,IAAI,MAAM,OAAO,SAAS,IAAI,WAAW;AAChD,WAAO,EAAE,IAAI,OAAO,QAAQ,oBAAoB;AAAA,EAClD;AAEA,QAAM,UAAU,GAAG,OAAO,SAAS,IAAI,MAAM,OAAO;AACpD,aAAW,UAAU,MAAM,SAAS;AAClC,QAAI,CAAC,OAAQ;AACb,UAAM,WAAW,WAAW,UAAU,MAAM,EAAE,OAAO,OAAO,EAAE,OAAO,KAAK;AAC1E,eAAW,aAAa,OAAO,YAAY;AACzC,UAAI,aAAa,UAAU,SAAS,GAAG;AACrC,eAAO,EAAE,IAAI,MAAM,WAAW,OAAO,UAAU;AAAA,MACjD;AAAA,IACF;AAAA,EACF;AACA,SAAO,EAAE,IAAI,OAAO,QAAQ,gBAAgB;AAC9C;AAEA,SAAS,YACP,QACoD;AACpD,MAAI,YAA2B;AAC/B,QAAM,aAAuB,CAAC;AAC9B,aAAW,WAAW,OAAO,MAAM,GAAG,GAAG;AACvC,UAAM,CAAC,KAAK,KAAK,IAAI,QAAQ,KAAK,EAAE,MAAM,GAAG;AAC7C,QAAI,CAAC,OAAO,CAAC,MAAO;AACpB,QAAI,QAAQ,KAAK;AACf,YAAM,KAAK,OAAO,KAAK;AACvB,UAAI,OAAO,SAAS,EAAE,EAAG,aAAY;AAAA,IACvC,WAAW,QAAQ,MAAM;AACvB,iBAAW,KAAK,KAAK;AAAA,IACvB;AAAA,EACF;AACA,MAAI,cAAc,QAAQ,WAAW,WAAW,EAAG,QAAO;AAC1D,SAAO,EAAE,WAAW,WAAW;AACjC;AAEA,SAAS,aAAa,GAAW,GAAoB;AACnD,MAAI,CAAC,YAAY,CAAC,KAAK,CAAC,YAAY,CAAC,EAAG,QAAO;AAC/C,QAAM,UAAU,OAAO,KAAK,GAAG,KAAK;AACpC,QAAM,UAAU,OAAO,KAAK,GAAG,KAAK;AACpC,SAAO,gBAAgB,SAAS,OAAO;AACzC;AAEA,SAAS,YAAY,OAAwB;AAC3C,SAAO,kBAAkB,KAAK,KAAK;AACrC;","names":[]}
|