@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.
Files changed (2) hide show
  1. package/README.md +75 -22
  2. package/package.json +4 -4
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
  [![License: MIT](https://img.shields.io/badge/License-MIT-02C76A.svg)](./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
- sign one EIP-3009 authorisation, and the Strimz relayer broadcasts
60
- the on-chain transaction. Your webhook receives `payment.completed`
61
- the moment it confirms.
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
- - **Automatic idempotency.** Every mutating call ships an idempotency key (`strimz_<uuid>`) so a network retry won't double-charge. Override with `{ idempotencyKey }` in the second argument if you want to dedupe across separate calls.
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 }`). `listAuto(...)` (where exposed) returns an async iterator you can `for await` over.
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.paymentSessions.retrieve(sessionId)
154
+ const session = await strimz.checkout.session(sessionId)
135
155
  ```
136
156
 
137
- The browser client exposes a strict subset of read-only resource
138
- methods. It refuses secret keys at construction time so a
139
- misconfigured environment fails loud.
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.refunds.create({ ... })
211
+ await strimz.paymentSessions.create({ ... })
159
212
  } catch (err) {
160
- if (err instanceof StrimzValidationError) {
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/Strimz/tree/main/packages/sdk)
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/Strimz/issues)
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.2",
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.0",
73
- "@strimz/shared-crypto": "0.2.6",
74
- "@strimz/shared-types": "0.13.0"
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",