@spritz-finance/api-client 0.16.0 → 0.18.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
@@ -90,6 +90,7 @@ const transactionData = await client.paymentRequest.getWeb3PaymentParams({
90
90
  - [Virtual Accounts](#virtual-accounts)
91
91
  - [Supported Tokens](#supported-tokens)
92
92
  - [ACH Onramp (Direct Debit)](#ach-onramp-direct-debit)
93
+ - [Checking Eligibility](#checking-eligibility)
93
94
  - [Sandbox](#sandbox)
94
95
  - [Bypassing KYC](#bypassing-kyc)
95
96
  - [Webhooks](#webhooks)
@@ -1008,6 +1009,7 @@ const accounts = await client.virtualAccounts.list()
1008
1009
 
1009
1010
  ACH onramp lets users convert USD from their bank account into USDC delivered to a Solana wallet. The integration is a short server-side flow with one client-side Plaid step:
1010
1011
 
1012
+ 0. **Server:** check that the bank deposit option can be offered at all with `client.achDebit.checkEligibility({ email })` (see [Checking Eligibility](#checking-eligibility))
1011
1013
  1. **Server:** create a Plaid link token with `client.bankAccount.createLinkToken()`
1012
1014
  2. **Client:** run Plaid Link and send the public token/account IDs back to your server
1013
1015
  3. **Server:** complete linking with `client.bankAccount.completeLinking(...)`
@@ -1051,6 +1053,97 @@ For a complete walkthrough with code examples, request/response schemas, and dep
1051
1053
 
1052
1054
  A standalone sandbox demo is available at `scripts/sandbox/ach-onramp.html`. Run `yarn build && node scripts/sandbox/evidence-server.mjs`, then open `http://localhost:3001/ach-onramp.html` to test the SDK-backed flow and save redacted QC evidence.
1053
1055
 
1056
+ ### Checking Eligibility
1057
+
1058
+ 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:
1059
+
1060
+ ```typescript
1061
+ const { eligible } = await client.achDebit.checkEligibility({ email: 'user@example.com' })
1062
+
1063
+ if (eligible) {
1064
+ // Offer the bank deposit option
1065
+ }
1066
+ ```
1067
+
1068
+ This route authenticates as the integrator over HMAC and takes no user bearer key, because the address it asks about need not belong to an existing user yet.
1069
+
1070
+ Eligibility only moves in one direction — once an address is eligible it stays eligible — so `eligible: false` may be transient. Re-check it rather than caching the negative against the address.
1071
+
1072
+ Once the user exists, stop asking: the capabilities on `client.user.getUserAccess()` become the source of truth for whether the option is available to them.
1073
+
1074
+ ## Error Handling
1075
+
1076
+ Every non-2xx REST response throws an `APIError` subclass chosen by status (`BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`, `RateLimitError`, `InternalServerError`). Transport failures throw `APIConnectionError`, and a timeout throws `APIConnectionTimeoutError`.
1077
+
1078
+ When the response carries an RFC 9457 problem body, it is parsed onto `error.problem` as typed `ProblemDetails`. Branch on the problem `type` or `code` rather than on the status, which is rarely specific enough:
1079
+
1080
+ ```typescript
1081
+ import { hasProblemType } from '@spritz-finance/api-client'
1082
+
1083
+ try {
1084
+ await client.deposit.create(input, options)
1085
+ } catch (error) {
1086
+ if (hasProblemType(error, 'urn:problem-type:idempotency-conflict')) {
1087
+ // The same idempotency key was used with a different request body.
1088
+ }
1089
+
1090
+ throw error
1091
+ }
1092
+ ```
1093
+
1094
+ `hasProblemType` and `hasProblemCode` are type guards: inside the branch, `error` is narrowed to an `APIError` whose `problem.type` (or `problem.code`) is the literal you passed. `isAPIError(error)` narrows without checking either.
1095
+
1096
+ ### `ProblemDetails`
1097
+
1098
+ | Field | Type | Notes |
1099
+ | ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
1100
+ | `type` | `string` | Problem type URI — the stable thing to branch on |
1101
+ | `title` | `string` | Short summary of the problem type |
1102
+ | `status` | `number` | HTTP status restated in the body |
1103
+ | `detail` | `string` | Human-facing explanation of this occurrence |
1104
+ | `instance` | `string` | URI for this specific occurrence |
1105
+ | `code` | `string` | Machine-readable cause, when exactly one thing failed |
1106
+ | `field` | `string` | The offending request field, alongside `code` |
1107
+ | `errors` | `Array<{ field, message, code? }>` | Field-level causes, when more than one thing failed |
1108
+ | `retryable` | `boolean` | Whether the same request may succeed later |
1109
+ | `retryAfter` | `number` | Seconds to wait before retrying |
1110
+ | `suggestedAction` | `'auto_ramp' \| 'wait_for_settlement' \| (string & {})` | What the API suggests doing next; open so new values still parse |
1111
+ | `clearsAt` | `string \| null` | When a limit clears; `null` means not bounded by time |
1112
+ | `availableAt` | `string \| null` | When the resource becomes available |
1113
+ | `permanent` | `boolean` | Whether retrying can ever succeed |
1114
+ | `realm` | `string` | Authentication realm, on some `401`s |
1115
+ | `scope` | `string` | Scope required for the resource, on some `401`s |
1116
+ | `resourceType` | `string` | Type of the missing resource; required on `404`s |
1117
+ | `resourceId` | `string` | Id of the missing resource; required on `404`s |
1118
+
1119
+ Every field is optional. The payload is untrusted, so a field appears only when the response carried it with its documented type — anything malformed is dropped, inherited properties are ignored, and a malformed body never turns into a thrown parse error. `problem` itself is undefined for transport failures, non-JSON bodies, and payloads with nothing documented in them.
1120
+
1121
+ Some fields only appear on certain problems — `realm`/`scope` on some `401`s, `resourceType`/`resourceId` on `404`s — so check before reading them:
1122
+
1123
+ ```typescript
1124
+ if (isAPIError(error) && error.status === 404) {
1125
+ logger.warn(`missing ${error.problem?.resourceType}: ${error.problem?.resourceId}`)
1126
+ }
1127
+ ```
1128
+
1129
+ The original parsed payload is always preserved on `error.error`, so fields `ProblemDetails` does not model stay reachable for logging:
1130
+
1131
+ ```typescript
1132
+ if (isAPIError(error)) {
1133
+ logger.warn({
1134
+ status: error.status,
1135
+ problem: error.problem,
1136
+ payload: error.error, // untouched, including fields not modelled above
1137
+ requestId: error.requestId,
1138
+ traceId: error.traceId,
1139
+ })
1140
+ }
1141
+ ```
1142
+
1143
+ `requestId` and `traceId` are lifted onto the error from the `x-amzn-requestid` and `x-amzn-trace-id` response headers, and remain available under `error.headers`.
1144
+
1145
+ > **`detail` is for trusted consumers.** The SDK exposes upstream problem details faithfully, including `detail`, which is written for the integrator rather than for an end user. Decide what is safe to forward at your own frontend boundary — the SDK does not make that call for you.
1146
+
1054
1147
  ## Sandbox
1055
1148
 
1056
1149
  Use `Environment.Sandbox` for development and testing. The sandbox environment is available at `https://sandbox.spritz.finance`.