@spritz-finance/api-client 0.22.0 → 0.24.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,7 +63,6 @@ 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)
67
66
  - [Reauthorization](#reauthorization)
68
67
  - [User Data](#user-data)
69
68
  - [Identity Verification](#identity-verification)
@@ -148,60 +147,32 @@ const user = await client.user.create({
148
147
  }
149
148
  ```
150
149
 
151
- Creating a user with an email that already exists will throw an error.
150
+ Where account reuse is enabled, `user.create()` is idempotent per integrator and normalized email (trimmed, lowercased). A repeat for an email that already has an account in your tenant, or an account you currently have authorized access to through an existing authorization, returns `200` with the same `userId`, its current `email` and a freshly minted `apiKey`; older keys may stay valid until revoked. Reuse never changes the account, so repeating the call is also how you recover a lost key. Where reuse is disabled, repeats return `USER_ALREADY_EXISTS`; handle both outcomes. Cross-tenant creation requires an approved rollout for your integrator and never grants access to another tenant's account.
152
151
 
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`:
152
+ With an integrator secret configured, `user.create()` calls `POST /v1/integrator/users` on the REST API; without one it uses the legacy `/users/integration` route, which does not accept Developer Console credentials. Both resolve the email the same way. The remaining `409` outcomes throw a `ConflictError` with a stable `problem.code` (branch on it with `hasProblemCode`):
154
153
 
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 |
154
+ | `code` | Meaning | What to do |
155
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
156
+ | `USER_DELETED` | The account this email resolves to for you was deleted; closed accounts are not recreated | Contact Spritz support to restore it |
157
+ | `USER_SELECTION_REQUIRED` | You are authorized for several Spritz accounts that use this email | Contact Spritz support to choose the account you intend to use |
158
+ | `USER_ALREADY_EXISTS` | The email already has an account this call cannot return, including any existing account when reuse is disabled | If your integrator created it, use the API key you stored; otherwise contact Spritz support |
159
+ | `USER_CREATE_IN_PROGRESS` | Another request is creating this user (`retryable: true`) | Retry shortly |
159
160
 
160
- Without a secret it uses the legacy route, which does not accept Developer Console credentials.
161
+ An `InternalServerError` with `problem.code` `AUTHORIZATION_LOOKUP_UNAVAILABLE` (status `503`, `retryable: true`, `retryAfter: 5`) means the authorization lookup is temporarily unavailable; retry shortly. The legacy route reports the same codes in its error body, so `hasProblemCode` works on both. Creating an account never tells you about accounts you are not authorized for.
161
162
 
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
- ```
163
+ ### Reauthorization
193
164
 
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.
165
+ > **Deprecated.** `user.requestApiKey()` and `user.authorizeApiKeyWithOTP()` are the legacy email-only key recovery flow. An email can belong to more than one Spritz account, so a code sent to it cannot say which account it is for, and the flow is being retired. Both methods keep working until the legacy routes are removed; do not build new integrations on them.
195
166
 
196
- ### Reauthorization
167
+ Where account reuse is enabled, recover the API key of an account in your tenant by calling `user.create()` again with the same email: it returns the same `userId` with a fresh `apiKey` (see [Creating a User](#creating-a-user)). Where reuse is disabled, the repeat returns `USER_ALREADY_EXISTS`: use the API key you stored for the account, or contact Spritz support.
197
168
 
198
- If you need to recover a user's API key (e.g., the user already has a Spritz account, or you've lost access), use the OTP reauthorization flow:
169
+ The legacy flow, for existing integrations only:
199
170
 
200
171
  ```typescript
201
- // Request an OTP code sent to the user's email
172
+ // Deprecated: request an OTP code sent to the user's email
202
173
  const { success } = await client.user.requestApiKey('bilbo@shiremail.net')
203
174
 
204
- // Confirm with the OTP code the user provides
175
+ // Deprecated: confirm with the OTP code the user provides
205
176
  const { apiKey, userId, email } = await client.user.authorizeApiKeyWithOTP({
206
177
  email: 'bilbo@shiremail.net',
207
178
  otp: '123456',
@@ -1321,6 +1292,7 @@ ACH onramp lets users convert USD from their bank account into USDC delivered to
1321
1292
  6. **Client:** show the quote and ACH authorization message to the user
1322
1293
  7. **Server:** create the deposit with `client.deposit.create(input, { idempotencyKey })`; Spritz runs risk checks before initiating the ACH pull. Persist one unique key per deposit intent and reuse it verbatim on retries so a timed-out request replays the original response instead of authorizing a second debit
1323
1294
  8. **Server:** track the deposit with `client.deposit.get(depositId)`, or reconcile a backlog by paging `client.deposit.list({ limit, cursor })`
1295
+ 9. **Server (optional):** while `deposit.cancellable` is true, let the user call it off with `client.deposit.cancel(depositId)` (see [Cancelling a Deposit](docs/ach-onramp-guide.md#cancelling-a-deposit))
1324
1296
 
1325
1297
  ```typescript
1326
1298
  // Page the authenticated user's deposits, newest first
@@ -1414,8 +1386,9 @@ try {
1414
1386
  | `retryAfter` | `number` | Seconds to wait before retrying |
1415
1387
  | `suggestedAction` | `'auto_ramp' \| 'wait_for_settlement' \| (string & {})` | What the API suggests doing next; open so new values still parse |
1416
1388
  | `clearsAt` | `string \| null` | When a limit clears; `null` means not bounded by time |
1417
- | `availableAt` | `string \| null` | When the resource becomes available |
1389
+ | `availableAt` | `string \| null` | When a temporary block lifts (funding source, cancel cooldown) |
1418
1390
  | `permanent` | `boolean` | Whether retrying can ever succeed |
1391
+ | `reason` | `DepositCancelRefusalReason` | Why a deposit cannot be cancelled, on `deposit_not_cancellable` |
1419
1392
  | `realm` | `string` | Authentication realm, on some `401`s |
1420
1393
  | `scope` | `string` | Scope required for the resource, on some `401`s |
1421
1394
  | `resourceType` | `string` | Type of the missing resource; required on `404`s |