@spritz-finance/api-client 0.23.0 → 0.25.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,12 +63,12 @@ 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)
70
69
  - [Regional Compliance](#regional-compliance)
71
70
  - [Accepting Terms](#accepting-terms)
71
+ - [Spritz Agreements](#spritz-agreements)
72
72
  - [Accounts](#accounts)
73
73
  - [Bank Accounts](#bank-accounts)
74
74
  - [Debit Cards](#debit-cards)
@@ -148,61 +148,24 @@ const user = await client.user.create({
148
148
  }
149
149
  ```
150
150
 
151
- 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 Spritz Connect or a valid reauthorization, 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.
151
+ 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
152
 
153
153
  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
154
 
155
- | `code` | Meaning | What to do |
156
- | ------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
157
- | `USER_DELETED` | The account this email resolves to for you was deleted; closed accounts are not recreated | Contact Spritz support to restore it |
158
- | `USER_SELECTION_REQUIRED` | You are authorized for several Spritz accounts that use this email | Run Spritz Connect for the account you intend to use (below) |
159
- | `USER_ALREADY_EXISTS` | This call cannot return an existing account, including when reuse is disabled | Start Spritz Connect with the same email (below) |
160
- | `USER_CREATE_IN_PROGRESS` | Another request is creating this user (`retryable: true`) | Retry shortly |
155
+ | `code` | Meaning | What to do |
156
+ | ------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
157
+ | `USER_DELETED` | The account this email resolves to for you was deleted; closed accounts are not recreated | Contact Spritz support to restore it |
158
+ | `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 |
159
+ | `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 |
160
+ | `USER_CREATE_IN_PROGRESS` | Another request is creating this user (`retryable: true`) | Retry shortly |
161
161
 
162
162
  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.
163
163
 
164
- ### Connecting an Existing User (Spritz Connect)
165
-
166
- Spritz Connect lets a Spritz user authorize your integrator to act for an account you do not own. It is an explicit authorization choice: where reuse is enabled, `user.create()` returns your own or currently authorized account. Use Connect when it fails with `USER_ALREADY_EXISTS` (this call cannot return an existing account) or `USER_SELECTION_REQUIRED` (you are authorized for several accounts with that email and must pick one), or whenever you want access to a specific existing account. Run these calls on your backend; both need integrator credentials (`integrationKey` + `integratorSecret`).
167
-
168
- ```typescript
169
- import { hasProblemCode } from '@spritz-finance/api-client'
170
-
171
- try {
172
- return await client.user.create({ email })
173
- } catch (error) {
174
- const needsConnect =
175
- hasProblemCode(error, 'USER_ALREADY_EXISTS') ||
176
- hasProblemCode(error, 'USER_SELECTION_REQUIRED')
177
- if (!needsConnect) throw error
178
- }
179
-
180
- // 1. Start a session for the account's email. Persist `state` with the user's
181
- // attempt so you can verify the callback.
182
- const { authorizationUrl, sessionId, expiresAt } = await client.connect.createSession({
183
- redirectUri: 'https://api.example.com/spritz/connect/callback', // registered with Spritz
184
- state: crypto.randomUUID(),
185
- email: 'bilbo@shiremail.net',
186
- })
187
-
188
- // 2. Send the user to `authorizationUrl` unchanged (including its #fragment; don't log it).
189
- // On iOS/Android open it in the system auth session (ASWebAuthenticationSession /
190
- // Custom Tabs), never an embedded WebView. The hosted page shows the email, the user
191
- // signs in to that account and approves.
192
-
193
- // 3. Spritz redirects to your redirectUri with ?code=…&state=… (or error=access_denied |
194
- // server_error | session_expired). Verify `state`, then exchange the code:
195
- const { apiKey, userId, email } = await client.connect.exchangeCode(code)
196
- // Store apiKey server-side only.
197
- ```
198
-
199
- `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. Keys issued through Connect are bound to that authorization: once it is disconnected they stop working, and a later `user.create()` for the same email no longer reuses that account.
200
-
201
164
  ### Reauthorization
202
165
 
203
166
  > **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.
204
167
 
205
- 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 [Spritz Connect](#connecting-an-existing-user-spritz-connect) instead. Use Connect also to act for an account you do not own; keys issued through Connect stay bound to that authorization and are revoked when it is disconnected.
168
+ 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.
206
169
 
207
170
  The legacy flow, for existing integrations only:
208
171
 
@@ -387,6 +350,66 @@ const { termsAccepted } = await client.terms.accept({
387
350
 
388
351
  > **Retries:** this endpoint does not accept an idempotency key. If a request times out, call `user.getMe()` and check whether the `terms_acceptance` requirement is still outstanding before submitting again.
389
352
 
353
+ ### Spritz Agreements
354
+
355
+ Spritz agreements are the user's consent to Spritz's own Terms of Service, Privacy Policy and E-Sign Consent. They are separate from the provider terms above and from each deposit's authorization, and can be collected before KYC. `user.getMe()` returns their state as `agreements`:
356
+
357
+ - `status: 'action_required'`: show the agreements screen.
358
+ - `status: 'accepted'`: nothing to do.
359
+ - `status: 'unavailable'`: proceed without the screen. With `retryable: false`, no agreements are active yet; do not poll.
360
+
361
+ Your backend creates a presentation, and the user's own client submits the acceptance:
362
+
363
+ ```typescript
364
+ // Backend
365
+ const presentation = await client.agreements.present()
366
+ if ('nothingToPresent' in presentation) return
367
+
368
+ // Send these to the user's client:
369
+ const { presentationId, copySha256, submissionToken, statementKey, copy, items } = presentation
370
+ ```
371
+
372
+ On the client, render `copy[statementKey]` verbatim directly above a button labelled `copy.buttonLabel`, with each `copy.links` entry as a visible link. Do not translate or rephrase it. Link URLs are relative to the Spritz API origin (`https://platform.spritz.finance`, or `https://sandbox.spritz.finance` in sandbox). When the user taps the button, the client sends the acceptance itself:
373
+
374
+ ```typescript
375
+ // User's client, not your backend
376
+ const response = await fetch(`${SPRITZ_API_ORIGIN}/v1/agreements/acceptances`, {
377
+ method: 'POST',
378
+ headers: {
379
+ authorization: `Bearer ${submissionToken}`,
380
+ 'content-type': 'application/json',
381
+ },
382
+ body: JSON.stringify({
383
+ presentationId,
384
+ accept: items.map((item) => item.type), // every presented type
385
+ copySha256,
386
+ }),
387
+ })
388
+ if (!response.ok) {
389
+ const problem = await response.json() // application/problem+json; branch on problem.code (table below)
390
+ throw new Error(problem.code ?? `agreements acceptance failed: ${response.status}`)
391
+ }
392
+ const receipt = await response.json() // same shape as getReceipt()
393
+ ```
394
+
395
+ `copy.consentPattern` is `'clickwrap'` by default, as above. If it is `'esign_checkbox'`, also show an unchecked checkbox labelled `copy.esignCheckboxLabel` and send `esignCheckboxChecked` with the user's choice. When it is unchecked, leave `esign_consent` out of `accept`; E-Sign then stays outstanding and needs a new presentation later.
396
+
397
+ The `submissionToken` lasts 15 minutes and works only for its presentation. Spritz refuses an acceptance sent from your backend or from the network that created the presentation (`403 client_submission_required`), which is why this SDK does not send it. Repeating the same acceptance returns the original receipt. If the client loses the response, recover it from your backend with `client.agreements.getReceipt(presentationId)`.
398
+
399
+ | HTTP | `code` | What to do |
400
+ | ---- | ------------------------------------- | ---------------------------------------------------- |
401
+ | 400 | `invalid_agreement_selection` | Accept every presented type. |
402
+ | 403 | `client_submission_required` | Submit from the user's client, not your backend. |
403
+ | 409 | `presentation_consumed` | Recover the receipt with `getReceipt`. |
404
+ | 409 | `presentation_expired` | Create a new presentation. |
405
+ | 409 | `agreement_version_outdated` | New documents are active: present again. |
406
+ | 409 | `agreement_state_changed` | Refresh `getMe()` and present again. |
407
+ | 409 | `copy_mismatch` | Render the returned copy and present again. |
408
+ | 429 | `agreement_presentation_rate_limited` | Back off; at most ten presentations per user/minute. |
409
+ | 503 | `agreements_unavailable` | Retry later. |
410
+
411
+ Every acceptance `409` includes the current `agreements` state.
412
+
390
413
  ## Accounts
391
414
 
392
415
  Spritz supports four account types: **Bank Account**, **Debit Card**, **Bill**, and **Virtual Card**. All are referred to as "accounts" within the platform and share common properties (`id`, `type`, `userId`, `country`, `currency`, `createdAt`), with additional fields specific to each type.
@@ -1330,6 +1353,7 @@ ACH onramp lets users convert USD from their bank account into USDC delivered to
1330
1353
  6. **Client:** show the quote and ACH authorization message to the user
1331
1354
  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
1332
1355
  8. **Server:** track the deposit with `client.deposit.get(depositId)`, or reconcile a backlog by paging `client.deposit.list({ limit, cursor })`
1356
+ 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))
1333
1357
 
1334
1358
  ```typescript
1335
1359
  // Page the authenticated user's deposits, newest first
@@ -1423,8 +1447,9 @@ try {
1423
1447
  | `retryAfter` | `number` | Seconds to wait before retrying |
1424
1448
  | `suggestedAction` | `'auto_ramp' \| 'wait_for_settlement' \| (string & {})` | What the API suggests doing next; open so new values still parse |
1425
1449
  | `clearsAt` | `string \| null` | When a limit clears; `null` means not bounded by time |
1426
- | `availableAt` | `string \| null` | When the resource becomes available |
1450
+ | `availableAt` | `string \| null` | When a temporary block lifts (funding source, cancel cooldown) |
1427
1451
  | `permanent` | `boolean` | Whether retrying can ever succeed |
1452
+ | `reason` | `DepositCancelRefusalReason` | Why a deposit cannot be cancelled, on `deposit_not_cancellable` |
1428
1453
  | `realm` | `string` | Authentication realm, on some `401`s |
1429
1454
  | `scope` | `string` | Scope required for the resource, on some `401`s |
1430
1455
  | `resourceType` | `string` | Type of the missing resource; required on `404`s |