@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 +69 -3
- package/dist/spritz-api-client.cjs +47 -47
- package/dist/spritz-api-client.d.ts +13332 -3965
- package/dist/spritz-api-client.mjs +47 -47
- package/package.json +1 -1
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({
|
|
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, {
|
|
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
|
```
|