@strimz/sdk 0.10.2 → 0.10.3
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/README.md +75 -22
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
[](./LICENSE)
|
|
10
10
|
|
|
11
11
|
The server-side client for the
|
|
12
|
-
[Strimz API](https://strimz.finance/docs/api/overview). Typed
|
|
12
|
+
[Strimz API](https://www.strimz.finance/docs/api/overview). Typed
|
|
13
13
|
resources for every endpoint, end-to-end TypeScript types derived
|
|
14
14
|
from the
|
|
15
15
|
[`@strimz/shared-types`](https://www.npmjs.com/package/@strimz/shared-types)
|
|
@@ -21,10 +21,12 @@ code path.
|
|
|
21
21
|
|
|
22
22
|
- [Install](#install)
|
|
23
23
|
- [Quick start](#quick-start)
|
|
24
|
+
- [Options](#options)
|
|
24
25
|
- [Resources](#resources)
|
|
25
26
|
- [Behaviour](#behaviour)
|
|
26
27
|
- [Webhook verification](#webhook-verification)
|
|
27
28
|
- [Browser client](#browser-client)
|
|
29
|
+
- [EIP-712 builders](#eip-712-builders)
|
|
28
30
|
- [Error handling](#error-handling)
|
|
29
31
|
- [Runtime support](#runtime-support)
|
|
30
32
|
- [Links](#links)
|
|
@@ -55,10 +57,25 @@ const session = await strimz.paymentSessions.create({
|
|
|
55
57
|
console.log(session.checkoutUrl)
|
|
56
58
|
```
|
|
57
59
|
|
|
58
|
-
Redirect the customer to `session.checkoutUrl`. They connect a wallet
|
|
59
|
-
|
|
60
|
-
the
|
|
61
|
-
the moment it
|
|
60
|
+
Redirect the customer to `session.checkoutUrl`. They connect a wallet
|
|
61
|
+
and approve two signature prompts (an EIP-3009 authorisation and the
|
|
62
|
+
Strimz `PayIntent`), and the Strimz relayer broadcasts the on-chain
|
|
63
|
+
transaction. Your webhook receives `payment.completed` the moment it
|
|
64
|
+
confirms.
|
|
65
|
+
|
|
66
|
+
## Options
|
|
67
|
+
|
|
68
|
+
| Option | Default | Notes |
|
|
69
|
+
| ------------ | ---------------------------- | ------------------------------------------- |
|
|
70
|
+
| `apiKey` | required | `sk_test_…` or `sk_live_…` |
|
|
71
|
+
| `baseUrl` | `https://api.strimz.finance` | Override the API host |
|
|
72
|
+
| `timeoutMs` | `30000` | Per-request timeout |
|
|
73
|
+
| `maxRetries` | `3` | Retries for network errors, `5xx` and `429` |
|
|
74
|
+
| `onRequest` | none | Callback before each request, for logging |
|
|
75
|
+
| `onResponse` | none | Callback after each response, for logging |
|
|
76
|
+
| `fetch` | `globalThis.fetch` | Inject a mock or polyfill |
|
|
77
|
+
|
|
78
|
+
`client.mode` is `'test'` or `'live'`, read from the key prefix.
|
|
62
79
|
|
|
63
80
|
## Resources
|
|
64
81
|
|
|
@@ -85,9 +102,11 @@ signatures and response types come from
|
|
|
85
102
|
## Behaviour
|
|
86
103
|
|
|
87
104
|
- **Mode auto-detection.** Live versus test mode is derived from the API key prefix (`sk_test_` or `sk_live_`). The server client refuses publishable keys; use the [browser client](#browser-client) for those.
|
|
88
|
-
- **
|
|
105
|
+
- **Idempotency keys.** Every `POST` and `PATCH` sends an `X-Strimz-Idempotency-Key` header (`strimz_<uuid>`). Pass `{ idempotencyKey }` in the options argument to set your own. `generateIdempotencyKey()` and `isValidIdempotencyKey()` are exported. Not yet: the API doesn't dedupe on this key, so a retried call can run twice. Tracked in [#292](https://github.com/StrimzLab/strimz/issues/292).
|
|
89
106
|
- **Retries.** Network errors, `5xx` responses on idempotent calls, and `429`s are retried up to 3 times with exponential backoff and jitter. `Retry-After` is respected on 429.
|
|
90
|
-
- **Pagination.** `list(...)` returns one page (`{ data, nextCursor, hasMore }`). `
|
|
107
|
+
- **Pagination.** `list(...)` returns one page (`{ data, nextCursor, hasMore }`). Pass `nextCursor` as `cursor` to get the next one.
|
|
108
|
+
- **Refunds.** Not yet: `refunds.create` throws, because the API returns `{ refund, signingInstructions }` and the SDK expects a bare refund. Call `POST /v1/refunds` directly for now. Tracked in [#294](https://github.com/StrimzLab/strimz/issues/294).
|
|
109
|
+
- **Version header.** Not yet: the `X-Strimz-Sdk-Version` header is always `0.0.0`. Tracked in [#296](https://github.com/StrimzLab/strimz/issues/296).
|
|
91
110
|
- **Typed errors.** The SDK throws on failure rather than returning `{ ok: false }`. Catch the base `StrimzError` or narrow with `instanceof` (see [Error handling](#error-handling)).
|
|
92
111
|
|
|
93
112
|
## Webhook verification
|
|
@@ -120,7 +139,8 @@ export async function POST(req: Request) {
|
|
|
120
139
|
`verifyWebhookSignature` does a constant-time comparison and rejects
|
|
121
140
|
any timestamp older than 5 minutes by default. `parseWebhookEvent`
|
|
122
141
|
returns a discriminated union, so a `switch` over `event.type` is
|
|
123
|
-
exhaustively checked by TypeScript.
|
|
142
|
+
exhaustively checked by TypeScript. `signWebhookPayload` builds a
|
|
143
|
+
signature header for your own tests.
|
|
124
144
|
|
|
125
145
|
## Browser client
|
|
126
146
|
|
|
@@ -131,33 +151,66 @@ const strimz = new StrimzBrowserClient({
|
|
|
131
151
|
publishableKey: process.env.NEXT_PUBLIC_STRIMZ_PUBLISHABLE_KEY!,
|
|
132
152
|
})
|
|
133
153
|
|
|
134
|
-
const session = await strimz.
|
|
154
|
+
const session = await strimz.checkout.session(sessionId)
|
|
135
155
|
```
|
|
136
156
|
|
|
137
|
-
The browser client
|
|
138
|
-
|
|
139
|
-
|
|
157
|
+
The browser client has two resources, both on the public checkout and
|
|
158
|
+
token routes:
|
|
159
|
+
|
|
160
|
+
| Resource | Methods |
|
|
161
|
+
| ---------- | ---------------------------------------------------------------- |
|
|
162
|
+
| `checkout` | `session`, `plan`, `merchant`, `subscriptionStatus`, `planTerms` |
|
|
163
|
+
| `tokens` | `retrieve`, `permitNonce` |
|
|
164
|
+
|
|
165
|
+
`selectPaymentPath` and `selectSubscriptionPath` map a token's
|
|
166
|
+
capabilities to the signing flow to use. The browser client refuses
|
|
167
|
+
secret keys at construction time so a misconfigured environment fails
|
|
168
|
+
loud.
|
|
140
169
|
|
|
141
170
|
For a full hosted-checkout UX with components and hooks, use
|
|
142
171
|
[`@strimz/sdk-react`](https://www.npmjs.com/package/@strimz/sdk-react).
|
|
143
172
|
|
|
173
|
+
## EIP-712 builders
|
|
174
|
+
|
|
175
|
+
`@strimz/sdk/eip712` builds the typed data a wallet signs:
|
|
176
|
+
`buildReceiveWithAuthorizationTypedData`, `buildPermitTypedData`,
|
|
177
|
+
`buildPayIntentTypedData` and `buildSubscriptionIntentTypedData`, with
|
|
178
|
+
their `*_TYPES` constants. Hosted checkout uses them; you only need
|
|
179
|
+
them if you build your own signing UI.
|
|
180
|
+
|
|
144
181
|
## Error handling
|
|
145
182
|
|
|
146
|
-
Every error thrown by the SDK is a typed subclass of `StrimzError
|
|
183
|
+
Every error thrown by the SDK is a typed subclass of `StrimzError`.
|
|
184
|
+
Each carries `code`, `httpStatus`, `requestId`, `param` and `details`.
|
|
185
|
+
|
|
186
|
+
| Class | When |
|
|
187
|
+
| --------------------------- | ----------------------------------------------- |
|
|
188
|
+
| `StrimzAuthenticationError` | `401`, or a secret key in a browser |
|
|
189
|
+
| `StrimzPermissionError` | `403` |
|
|
190
|
+
| `StrimzNotFoundError` | `404` |
|
|
191
|
+
| `StrimzIdempotencyError` | `409` with code `idempotency_error` |
|
|
192
|
+
| `StrimzValidationError` | `422` |
|
|
193
|
+
| `StrimzRateLimitError` | `429`, with `retryAfterMs` |
|
|
194
|
+
| `StrimzNetworkError` | The request never got a response |
|
|
195
|
+
| `StrimzTimeoutError` | The request hit `timeoutMs` |
|
|
196
|
+
| `StrimzModeMismatchError` | Exported, but the client doesn't throw it today |
|
|
197
|
+
|
|
198
|
+
Any other status, including `400 invalid_request`, is a plain
|
|
199
|
+
`StrimzError`; check `err.code`. `classifyError(httpStatus, body)` maps
|
|
200
|
+
a status and error body to the right class.
|
|
147
201
|
|
|
148
202
|
```ts
|
|
149
203
|
import {
|
|
150
204
|
StrimzError,
|
|
151
205
|
StrimzAuthenticationError,
|
|
152
|
-
StrimzValidationError,
|
|
153
206
|
StrimzRateLimitError,
|
|
154
207
|
StrimzNotFoundError,
|
|
155
208
|
} from '@strimz/sdk/errors'
|
|
156
209
|
|
|
157
210
|
try {
|
|
158
|
-
await strimz.
|
|
211
|
+
await strimz.paymentSessions.create({ ... })
|
|
159
212
|
} catch (err) {
|
|
160
|
-
if (err instanceof
|
|
213
|
+
if (err instanceof StrimzError && err.code === 'invalid_request') {
|
|
161
214
|
console.error('validation failed on', err.param, ':', err.message)
|
|
162
215
|
} else if (err instanceof StrimzRateLimitError) {
|
|
163
216
|
await sleep(err.retryAfterMs)
|
|
@@ -171,7 +224,7 @@ try {
|
|
|
171
224
|
```
|
|
172
225
|
|
|
173
226
|
The full code list is documented at
|
|
174
|
-
[strimz.finance/docs/errors](https://strimz.finance/docs/errors).
|
|
227
|
+
[strimz.finance/docs/errors](https://www.strimz.finance/docs/errors).
|
|
175
228
|
|
|
176
229
|
## Runtime support
|
|
177
230
|
|
|
@@ -184,15 +237,15 @@ The full code list is documented at
|
|
|
184
237
|
| Bun | Should work, not regularly tested |
|
|
185
238
|
| Browsers | Use `StrimzBrowserClient` from `@strimz/sdk/browser` |
|
|
186
239
|
|
|
187
|
-
`StrimzClient` refuses to start in a browser runtime: a page, a web worker, an Electron renderer, or React Native. It throws `StrimzAuthenticationError` with code `secret_key_in_browser` and a message that never contains the key. Node with a DOM shim such as jsdom, Deno, Bun, Vercel Edge and Cloudflare Workers count as servers. There is no option to turn the check off. Create payment sessions on your server and pass the session id to the browser; see [strimz.finance/docs/checkout/server-sessions](https://strimz.finance/docs/checkout/server-sessions).
|
|
240
|
+
`StrimzClient` refuses to start in a browser runtime: a page, a web worker, an Electron renderer, or React Native. It throws `StrimzAuthenticationError` with code `secret_key_in_browser` and a message that never contains the key. Node with a DOM shim such as jsdom, Deno, Bun, Vercel Edge and Cloudflare Workers count as servers. There is no option to turn the check off. Create payment sessions on your server and pass the session id to the browser; see [strimz.finance/docs/checkout/server-sessions](https://www.strimz.finance/docs/checkout/server-sessions).
|
|
188
241
|
|
|
189
242
|
## Links
|
|
190
243
|
|
|
191
|
-
- [Documentation](https://strimz.finance/docs)
|
|
192
|
-
- [API reference](https://strimz.finance/docs/api/overview)
|
|
193
|
-
- [Repository](https://github.com/StrimzLab/
|
|
244
|
+
- [Documentation](https://www.strimz.finance/docs)
|
|
245
|
+
- [API reference](https://www.strimz.finance/docs/api/overview)
|
|
246
|
+
- [Repository](https://github.com/StrimzLab/strimz/tree/main/packages/sdk)
|
|
194
247
|
- [Changelog](./CHANGELOG.md)
|
|
195
|
-
- [Issues](https://github.com/StrimzLab/
|
|
248
|
+
- [Issues](https://github.com/StrimzLab/strimz/issues)
|
|
196
249
|
|
|
197
250
|
## License
|
|
198
251
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@strimz/sdk",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.3",
|
|
4
4
|
"description": "The Strimz SDK. Typed client for server and edge runtimes. Handles HTTP, retries, idempotency, pagination, EIP-712 typed-data building, and webhook signature verification.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Strimz <hello@strimz.finance>",
|
|
@@ -69,9 +69,9 @@
|
|
|
69
69
|
],
|
|
70
70
|
"dependencies": {
|
|
71
71
|
"zod": "^3.24.1",
|
|
72
|
-
"@strimz/shared-config": "0.7.
|
|
73
|
-
"@strimz/shared-crypto": "0.2.
|
|
74
|
-
"@strimz/shared-types": "0.13.
|
|
72
|
+
"@strimz/shared-config": "0.7.1",
|
|
73
|
+
"@strimz/shared-crypto": "0.2.7",
|
|
74
|
+
"@strimz/shared-types": "0.13.1"
|
|
75
75
|
},
|
|
76
76
|
"devDependencies": {
|
|
77
77
|
"@types/node": "^22.10.5",
|