@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 +18 -45
- package/dist/spritz-api-client.cjs +58 -58
- package/dist/spritz-api-client.d.ts +7253 -4261
- package/dist/spritz-api-client.mjs +58 -58
- package/package.json +1 -1
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
|
-
|
|
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.
|
|
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
|
|
156
|
-
| ------------------------- |
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
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
|
-
|
|
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
|
-
###
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
169
|
+
The legacy flow, for existing integrations only:
|
|
199
170
|
|
|
200
171
|
```typescript
|
|
201
|
-
//
|
|
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
|
-
//
|
|
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
|
|
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 |
|