@spritz-finance/api-client 0.20.0 → 0.22.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/README.md CHANGED
@@ -63,6 +63,7 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
63
63
  - [Authentication](#authentication)
64
64
  - [Users](#users)
65
65
  - [Creating a User](#creating-a-user)
66
+ - [Connecting an Existing User (Spritz Connect)](#connecting-an-existing-user-spritz-connect)
66
67
  - [Reauthorization](#reauthorization)
67
68
  - [User Data](#user-data)
68
69
  - [Identity Verification](#identity-verification)
@@ -149,7 +150,48 @@ const user = await client.user.create({
149
150
 
150
151
  Creating a user with an email that already exists will throw an error.
151
152
 
152
- With an integrator secret configured, `user.create()` calls `POST /v1/integrator/users` on the REST API, and an existing email throws a `ConflictError` (409). Without a secret it uses the legacy route, which does not accept Developer Console credentials.
153
+ With an integrator secret configured, `user.create()` calls `POST /v1/integrator/users` on the REST API. A conflict throws a `ConflictError` (409); branch on its `problem.code`:
154
+
155
+ | `code` | Meaning | What to do |
156
+ | ------------------------- | --------------------------------------------------------- | --------------------------------- |
157
+ | `USER_ALREADY_EXISTS` | The email already has a Spritz account | Connect the existing user (below) |
158
+ | `USER_CREATE_IN_PROGRESS` | Another request is creating this user (`retryable: true`) | Retry shortly |
159
+
160
+ Without a secret it uses the legacy route, which does not accept Developer Console credentials.
161
+
162
+ ### Connecting an Existing User (Spritz Connect)
163
+
164
+ When `user.create()` fails with `USER_ALREADY_EXISTS`, that email already has a Spritz account. Ask the user to authorize your integrator with Spritz Connect. Run these calls on your backend; both need integrator credentials (`integrationKey` + `integratorSecret`).
165
+
166
+ ```typescript
167
+ import { hasProblemCode } from '@spritz-finance/api-client'
168
+
169
+ try {
170
+ return await client.user.create({ email })
171
+ } catch (error) {
172
+ if (!hasProblemCode(error, 'USER_ALREADY_EXISTS')) throw error
173
+ }
174
+
175
+ // 1. Start a session for the email that was rejected. Persist `state` with the
176
+ // user's attempt so you can verify the callback.
177
+ const { authorizationUrl, sessionId, expiresAt } = await client.connect.createSession({
178
+ redirectUri: 'https://api.example.com/spritz/connect/callback', // registered with Spritz
179
+ state: crypto.randomUUID(),
180
+ email: 'bilbo@shiremail.net',
181
+ })
182
+
183
+ // 2. Send the user to `authorizationUrl` unchanged (including its #fragment; don't log it).
184
+ // On iOS/Android open it in the system auth session (ASWebAuthenticationSession /
185
+ // Custom Tabs), never an embedded WebView. The hosted page shows the email, the user
186
+ // signs in to that account and approves.
187
+
188
+ // 3. Spritz redirects to your redirectUri with ?code=…&state=… (or error=access_denied |
189
+ // server_error | session_expired). Verify `state`, then exchange the code:
190
+ const { apiKey, userId, email } = await client.connect.exchangeCode(code)
191
+ // Store apiKey server-side only.
192
+ ```
193
+
194
+ `redirectUri` must exactly match a callback URL Spritz has registered for your integrator; ask your Spritz contact to register it. Sessions expire after 10 minutes and codes are single-use.
153
195
 
154
196
  ### Reauthorization
155
197