@strimz/sdk-react 0.3.0 → 0.3.1
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 +55 -47
- package/package.json +4 -4
package/README.md
CHANGED
|
@@ -12,8 +12,7 @@
|
|
|
12
12
|
A small surface of React building blocks for Strimz: a context
|
|
13
13
|
provider, a drop-in payment button, an embedded checkout, and a few
|
|
14
14
|
typed hooks. Works with React 18 or 19, Next.js App Router
|
|
15
|
-
(`'use client'`), Remix, and Vite. No
|
|
16
|
-
imports required.
|
|
15
|
+
(`'use client'`), Remix, and Vite. No CSS imports required.
|
|
17
16
|
|
|
18
17
|
## Table of contents
|
|
19
18
|
|
|
@@ -21,9 +20,9 @@ imports required.
|
|
|
21
20
|
- [Quick start](#quick-start)
|
|
22
21
|
- [Components](#components)
|
|
23
22
|
- [Hooks](#hooks)
|
|
23
|
+
- [Types](#types)
|
|
24
24
|
- [Security](#security)
|
|
25
25
|
- [SSR and React Server Components](#ssr-and-react-server-components)
|
|
26
|
-
- [Bundle](#bundle)
|
|
27
26
|
- [Links](#links)
|
|
28
27
|
- [License](#license)
|
|
29
28
|
|
|
@@ -35,7 +34,8 @@ pnpm add @strimz/sdk-react
|
|
|
35
34
|
# yarn add @strimz/sdk-react
|
|
36
35
|
```
|
|
37
36
|
|
|
38
|
-
|
|
37
|
+
`react` and `react-dom` (`^18 || ^19`) are peer dependencies.
|
|
38
|
+
`@strimz/sdk` is a regular dependency and installs automatically.
|
|
39
39
|
|
|
40
40
|
## Quick start
|
|
41
41
|
|
|
@@ -45,7 +45,10 @@ import { StrimzProvider, StrimzPayButton } from '@strimz/sdk-react'
|
|
|
45
45
|
|
|
46
46
|
export default function Layout({ children }: { children: React.ReactNode }) {
|
|
47
47
|
return (
|
|
48
|
-
<StrimzProvider
|
|
48
|
+
<StrimzProvider
|
|
49
|
+
publishableKey={process.env.NEXT_PUBLIC_STRIMZ_PUBLISHABLE_KEY!}
|
|
50
|
+
checkoutOrigin="https://www.strimz.finance"
|
|
51
|
+
>
|
|
49
52
|
{children}
|
|
50
53
|
</StrimzProvider>
|
|
51
54
|
)
|
|
@@ -72,32 +75,38 @@ passes its `id` to the React component.
|
|
|
72
75
|
|
|
73
76
|
Wraps any tree that uses Strimz components or hooks. Exposes a
|
|
74
77
|
memoised `StrimzBrowserClient` and the hosted-checkout origin to its
|
|
75
|
-
descendants.
|
|
78
|
+
descendants. It throws on first render if you pass a secret key.
|
|
76
79
|
|
|
77
|
-
| Prop | Default | Notes
|
|
78
|
-
| ---------------- | ---------------------------- |
|
|
79
|
-
| `publishableKey` | required | `pk_test_…` or `pk_live_…`
|
|
80
|
-
| `apiBaseUrl` | `https://api.strimz.finance` | Override for staging
|
|
81
|
-
| `checkoutOrigin` | `https://strimz.finance` | Origin
|
|
80
|
+
| Prop | Default | Notes |
|
|
81
|
+
| ---------------- | ---------------------------- | ------------------------------------------- |
|
|
82
|
+
| `publishableKey` | required | `pk_test_…` or `pk_live_…` |
|
|
83
|
+
| `apiBaseUrl` | `https://api.strimz.finance` | Override for staging |
|
|
84
|
+
| `checkoutOrigin` | `https://strimz.finance` | Origin of the hosted checkout, with no path |
|
|
85
|
+
|
|
86
|
+
Set `checkoutOrigin="https://www.strimz.finance"`. Not yet: the default
|
|
87
|
+
`https://strimz.finance` redirects to `www`, so checkout results from
|
|
88
|
+
the popup or embed are dropped. Tracked in
|
|
89
|
+
[#291](https://github.com/StrimzLab/strimz/issues/291).
|
|
82
90
|
|
|
83
91
|
### `<StrimzPayButton />`
|
|
84
92
|
|
|
85
|
-
Drop-in checkout button for an existing session.
|
|
93
|
+
Drop-in checkout button for an existing session. It accepts every
|
|
94
|
+
standard `<button>` attribute as well as the props below.
|
|
86
95
|
|
|
87
96
|
| Prop | Default | Notes |
|
|
88
97
|
| -------------------- | ----------------- | ---------------------------------------------------------------- |
|
|
89
98
|
| `sessionId` | required | Returned by `strimz.paymentSessions.create(...)` on your backend |
|
|
90
99
|
| `mode` | `popup` | `popup` or `redirect` |
|
|
91
|
-
| `theme` | `auto` | `auto`, `light`, or `dark
|
|
100
|
+
| `theme` | `auto` | `auto`, `light`, or `dark`. Has no visual effect today |
|
|
92
101
|
| `size` | `md` | `sm`, `md`, or `lg` |
|
|
93
102
|
| `label` | `Pay with Strimz` | Override the button content |
|
|
94
103
|
| `onSuccess(txHash?)` | none | Fires on `strimz:checkout:success` postMessage |
|
|
95
104
|
| `onCancel()` | none | Fires on `strimz:checkout:cancel` or popup close |
|
|
96
|
-
| `onError(error)` | none |
|
|
105
|
+
| `onError(error)` | none | Typed `Error`; narrow with `instanceof StrimzCheckoutError` |
|
|
97
106
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
107
|
+
The button opens the hosted checkout. The hosted page handles wallet
|
|
108
|
+
connection and signing. In `mode="redirect"` the page navigates away,
|
|
109
|
+
so no callbacks fire; use your `successUrl` and webhooks instead.
|
|
101
110
|
|
|
102
111
|
### `<StrimzCheckoutEmbed />`
|
|
103
112
|
|
|
@@ -112,44 +121,50 @@ page rather than in a popup.
|
|
|
112
121
|
/>
|
|
113
122
|
```
|
|
114
123
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
```
|
|
124
|
+
| Prop | Default | Notes |
|
|
125
|
+
| -------------------- | -------- | ------------------------------------------- |
|
|
126
|
+
| `sessionId` | required | The session to pay |
|
|
127
|
+
| `height` | `600` | Iframe height |
|
|
128
|
+
| `theme` | system | `light` or `dark`; omit to follow the payer |
|
|
129
|
+
| `onSuccess(txHash?)` | none | Payment confirmed |
|
|
130
|
+
| `onCancel()` | none | Payer cancelled |
|
|
131
|
+
| `onError(error)` | none | Typed `Error` |
|
|
132
|
+
| `className`, `style` | none | Applied to the iframe wrapper |
|
|
125
133
|
|
|
126
134
|
The embed has no theme toggle of its own; your page decides.
|
|
127
135
|
|
|
128
136
|
## Hooks
|
|
129
137
|
|
|
130
|
-
- `
|
|
131
|
-
- `
|
|
132
|
-
- `
|
|
138
|
+
- `useStrimzContext()`. Returns `{ client, checkoutOrigin }` from the provider. Throws outside a `<StrimzProvider />`.
|
|
139
|
+
- `useStrimzClient()`. Returns the provider's `StrimzBrowserClient`.
|
|
140
|
+
- `useStrimzSession(sessionId, { pollIntervalMs })`. Returns `{ session, loading, error, refresh }`. Polls every 3000 ms by default and stops once the session is `confirmed`, `failed`, `expired` or `cancelled`.
|
|
141
|
+
- `useStrimzCheckout({ mode, onSuccess, onCancel, onError })`. Returns `{ open, close, status }` for a custom button. `status` is `idle`, `open`, `success`, `cancelled` or `error`.
|
|
133
142
|
|
|
134
143
|
```tsx
|
|
135
144
|
import { useStrimzSession } from '@strimz/sdk-react'
|
|
136
145
|
|
|
137
146
|
function PaymentStatus({ sessionId }: { sessionId: string }) {
|
|
138
|
-
const {
|
|
139
|
-
if (isLoading) return <Spinner />
|
|
147
|
+
const { session, error } = useStrimzSession(sessionId)
|
|
140
148
|
if (error) return <ErrorBanner error={error} />
|
|
141
|
-
return <
|
|
149
|
+
if (!session) return <Spinner />
|
|
150
|
+
return <p>Status: {session.status}</p>
|
|
142
151
|
}
|
|
143
152
|
```
|
|
144
153
|
|
|
145
|
-
|
|
146
|
-
|
|
154
|
+
## Types
|
|
155
|
+
|
|
156
|
+
`StrimzProviderProps`, `StrimzContextValue`, `UseStrimzSessionResult`,
|
|
157
|
+
`UseStrimzSessionOptions`, `UseStrimzCheckoutOptions`,
|
|
158
|
+
`UseStrimzCheckoutResult`, `CheckoutMode`, `StrimzPayButtonProps`,
|
|
159
|
+
`StrimzPayButtonTheme`, `StrimzPayButtonSize`,
|
|
160
|
+
`StrimzCheckoutEmbedProps` and `StrimzCheckoutTheme` are exported, as
|
|
161
|
+
is the `StrimzCheckoutError` class (`code`, `sessionId`, `message`).
|
|
147
162
|
|
|
148
163
|
## Security
|
|
149
164
|
|
|
150
165
|
- The checkout posts its result only to the page that opened it, using that page's exact origin, never `'*'`.
|
|
151
166
|
- A result is accepted only when it comes from `checkoutOrigin`, from this component's own iframe or popup, for the session it opened, and matches the shared message schema. Another page or frame cannot spoof a success event.
|
|
152
|
-
- `<StrimzProvider />` rejects secret keys (`sk_*`)
|
|
167
|
+
- `<StrimzProvider />` rejects secret keys (`sk_*`), so a misconfigured environment fails loudly.
|
|
153
168
|
|
|
154
169
|
## SSR and React Server Components
|
|
155
170
|
|
|
@@ -157,20 +172,13 @@ Every export is marked `'use client'`. Import from a Client Component
|
|
|
157
172
|
in Next.js App Router. Server Components should only ever see the
|
|
158
173
|
session id; never instantiate `StrimzBrowserClient` on the server.
|
|
159
174
|
|
|
160
|
-
## Bundle
|
|
161
|
-
|
|
162
|
-
Distributed as ESM + CJS. React is `external`, so the published
|
|
163
|
-
bundle is small (around 6 KB gzipped before tree-shaking). Inline
|
|
164
|
-
styles in `<StrimzPayButton />` keep the dependency surface at zero.
|
|
165
|
-
No Tailwind, no shadcn, no CSS imports required.
|
|
166
|
-
|
|
167
175
|
## Links
|
|
168
176
|
|
|
169
|
-
- [Documentation](https://strimz.finance/docs)
|
|
170
|
-
- [SDK reference](https://strimz.finance/docs/sdks/react)
|
|
171
|
-
- [Repository](https://github.com/StrimzLab/
|
|
177
|
+
- [Documentation](https://www.strimz.finance/docs)
|
|
178
|
+
- [SDK reference](https://www.strimz.finance/docs/sdks/react)
|
|
179
|
+
- [Repository](https://github.com/StrimzLab/strimz/tree/main/packages/sdk-react)
|
|
172
180
|
- [Changelog](./CHANGELOG.md)
|
|
173
|
-
- [Issues](https://github.com/StrimzLab/
|
|
181
|
+
- [Issues](https://github.com/StrimzLab/strimz/issues)
|
|
174
182
|
|
|
175
183
|
## License
|
|
176
184
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@strimz/sdk-react",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"description": "Strimz React components and hooks. Drop-in <StrimzPayButton/>, embedded checkout, typed hooks, and a context provider for the Strimz API.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Strimz <hello@strimz.finance>",
|
|
@@ -46,9 +46,9 @@
|
|
|
46
46
|
"LICENSE"
|
|
47
47
|
],
|
|
48
48
|
"dependencies": {
|
|
49
|
-
"@strimz/sdk": "0.10.
|
|
50
|
-
"@strimz/shared-
|
|
51
|
-
"@strimz/shared-
|
|
49
|
+
"@strimz/sdk": "0.10.3",
|
|
50
|
+
"@strimz/shared-types": "0.13.1",
|
|
51
|
+
"@strimz/shared-config": "0.7.1"
|
|
52
52
|
},
|
|
53
53
|
"peerDependencies": {
|
|
54
54
|
"react": "^18.0.0 || ^19.0.0",
|