@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.
Files changed (2) hide show
  1. package/README.md +55 -47
  2. 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 Tailwind, no shadcn, no CSS
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
- `@strimz/sdk` and `react@^18 || ^19` are peer dependencies.
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 publishableKey={process.env.NEXT_PUBLIC_STRIMZ_PUBLISHABLE_KEY!}>
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 used to filter `postMessage` |
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 | Fires on `strimz:checkout:error` with a `StrimzCheckoutError` |
105
+ | `onError(error)` | none | Typed `Error`; narrow with `instanceof StrimzCheckoutError` |
97
106
 
98
- Internally the button uses Reown AppKit to connect a wallet, asks
99
- the customer for a single EIP-3009 signature, and resolves once the
100
- on-chain transaction confirms.
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
- Renders the same UI as the hosted page, but inline. Useful for
116
- cart-style flows where you don't want to lose the buyer's context.
117
-
118
- The embedded checkout follows the payer's system light or dark
119
- preference. Pass `theme="light"` or `theme="dark"` to pin it to your
120
- page's look:
121
-
122
- ```tsx
123
- <StrimzCheckoutEmbed sessionId={session.id} theme="dark" />
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
- - `useStrimzClient()`. Returns the singleton `StrimzBrowserClient`.
131
- - `useStrimzSession(sessionId, { pollIntervalMs })`. Polls a session until it reaches a terminal state. Backed by TanStack Query.
132
- - `useStrimzCheckout({ mode, onSuccess, onCancel, onError })`. Imperative checkout opener for custom UI.
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 { data, isLoading, error } = useStrimzSession(sessionId)
139
- if (isLoading) return <Spinner />
147
+ const { session, error } = useStrimzSession(sessionId)
140
148
  if (error) return <ErrorBanner error={error} />
141
- return <p>Status: {data.status}</p>
149
+ if (!session) return <Spinner />
150
+ return <p>Status: {session.status}</p>
142
151
  }
143
152
  ```
144
153
 
145
- Bring your own `QueryClient`, or wrap with `<QueryClientProvider>` if
146
- you don't already have one.
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_*`) at construction time, so a misconfigured environment fails loudly.
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/Strimz/tree/main/packages/sdk-react)
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/Strimz/issues)
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.0",
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.2",
50
- "@strimz/shared-config": "0.7.0",
51
- "@strimz/shared-types": "0.13.0"
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",