@spritz-finance/api-client 0.24.0 → 0.26.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
@@ -68,6 +68,7 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
68
68
  - [Identity Verification](#identity-verification)
69
69
  - [Regional Compliance](#regional-compliance)
70
70
  - [Accepting Terms](#accepting-terms)
71
+ - [Spritz Agreements](#spritz-agreements)
71
72
  - [Accounts](#accounts)
72
73
  - [Bank Accounts](#bank-accounts)
73
74
  - [Debit Cards](#debit-cards)
@@ -349,6 +350,66 @@ const { termsAccepted } = await client.terms.accept({
349
350
 
350
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.
351
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
+
352
413
  ## Accounts
353
414
 
354
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.
@@ -1289,7 +1350,7 @@ ACH onramp lets users convert USD from their bank account into USDC delivered to
1289
1350
  3. **Server:** complete linking with `client.bankAccount.completeLinking(...)`
1290
1351
  4. **Server:** find an active funding source and fetch limits with `client.fundingSource.getDepositLimits(id)`
1291
1352
  5. **Server:** prepare a quote with `client.deposit.prepare(...)`
1292
- 6. **Client:** show the quote and ACH authorization message to the user
1353
+ 6. **Client:** show the quote and ACH authorization `message` to the user. If your UI lays out the amounts from `summary` itself, show `authorizationStatement` word for word instead. That's only allowed when `messageVersion` is `fomo_v2`; for any other version, show `message` in full
1293
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
1294
1355
  8. **Server:** track the deposit with `client.deposit.get(depositId)`, or reconcile a backlog by paging `client.deposit.list({ limit, cursor })`
1295
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))
@@ -1335,7 +1396,9 @@ A standalone sandbox demo is available at `scripts/sandbox/ach-onramp.html`. Run
1335
1396
  Before you show a bank deposit option to someone who is not yet a Spritz user, ask whether it is available for their email address:
1336
1397
 
1337
1398
  ```typescript
1338
- const { eligible } = await client.achDebit.checkEligibility({ email: 'user@example.com' })
1399
+ const { eligible } = await client.achDebit.checkEligibility({
1400
+ email: 'user@example.com',
1401
+ })
1339
1402
 
1340
1403
  if (eligible) {
1341
1404
  // Offer the bank deposit option
@@ -1456,7 +1519,10 @@ const { onRampId, depositId, status } = await client.sandbox.simulateAutoRampDep
1456
1519
  })
1457
1520
 
1458
1521
  // Advance the same on-ramp
1459
- await client.sandbox.simulateAutoRampDeposit(accountId, { amount: '2525.00', depositId })
1522
+ await client.sandbox.simulateAutoRampDeposit(accountId, {
1523
+ amount: '2525.00',
1524
+ depositId,
1525
+ })
1460
1526
 
1461
1527
  const onRamp = await client.onrampPayment.get(onRampId)
1462
1528
  ```