@spritz-finance/api-client 0.15.0 → 0.17.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 +84 -0
- package/dist/spritz-api-client.cjs +70 -70
- package/dist/spritz-api-client.d.ts +621 -42
- package/dist/spritz-api-client.mjs +68 -68
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1034,12 +1034,96 @@ console.log(deposit.status, deposit.debitStatus, deposit.releaseStatus)
|
|
|
1034
1034
|
|
|
1035
1035
|
Authorization is derived from the verified ACH funding source — no wallet signature is required.
|
|
1036
1036
|
|
|
1037
|
+
**A backend `create` must send `clientIp`** — the public address your edge observed for the authorizing client, distinct from your backend's own address. The generated type marks it optional because the contract allows omitting it only for a direct client submission authenticated with a `submissionToken`, which this SDK does not send; a backend create without it fails at runtime, not at compile time.
|
|
1038
|
+
|
|
1039
|
+
```typescript
|
|
1040
|
+
const deposit = await client.deposit.create(
|
|
1041
|
+
{ preparationId: preparation.preparationId, clientIp: req.ip },
|
|
1042
|
+
{ idempotencyKey }
|
|
1043
|
+
)
|
|
1044
|
+
```
|
|
1045
|
+
|
|
1046
|
+
To move submission onto the customer's device, pass `clientNetwork: { ipAddresses: [req.ip] }` to `prepare` and forward the returned `submissionToken` to that client. The client then calls `POST /v1/deposits/direct` itself with `Authorization: Bearer ach_submit_...` as its only credential — no user API key, no integrator key, no HMAC headers — plus the `Idempotency-Key` header and a body of just `{ preparationId }`. This SDK signs every REST call with integrator HMAC, so that request should not go through it; see the [ACH Onramp Integration Guide](docs/ach-onramp-guide.md) for the full request.
|
|
1047
|
+
|
|
1037
1048
|
If risk checks block the create step, the API returns 409 before any ACH debit is pulled. Prepare a new quote before retrying; blocked create attempts consume the original `preparationId`.
|
|
1038
1049
|
|
|
1039
1050
|
For a complete walkthrough with code examples, request/response schemas, and deposit lifecycle documentation, see the **[ACH Onramp Integration Guide](docs/ach-onramp-guide.md)**.
|
|
1040
1051
|
|
|
1041
1052
|
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.
|
|
1042
1053
|
|
|
1054
|
+
## Error Handling
|
|
1055
|
+
|
|
1056
|
+
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`.
|
|
1057
|
+
|
|
1058
|
+
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:
|
|
1059
|
+
|
|
1060
|
+
```typescript
|
|
1061
|
+
import { hasProblemType } from '@spritz-finance/api-client'
|
|
1062
|
+
|
|
1063
|
+
try {
|
|
1064
|
+
await client.deposit.create(input, options)
|
|
1065
|
+
} catch (error) {
|
|
1066
|
+
if (hasProblemType(error, 'urn:problem-type:idempotency-conflict')) {
|
|
1067
|
+
// The same idempotency key was used with a different request body.
|
|
1068
|
+
}
|
|
1069
|
+
|
|
1070
|
+
throw error
|
|
1071
|
+
}
|
|
1072
|
+
```
|
|
1073
|
+
|
|
1074
|
+
`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.
|
|
1075
|
+
|
|
1076
|
+
### `ProblemDetails`
|
|
1077
|
+
|
|
1078
|
+
| Field | Type | Notes |
|
|
1079
|
+
| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------- |
|
|
1080
|
+
| `type` | `string` | Problem type URI — the stable thing to branch on |
|
|
1081
|
+
| `title` | `string` | Short summary of the problem type |
|
|
1082
|
+
| `status` | `number` | HTTP status restated in the body |
|
|
1083
|
+
| `detail` | `string` | Human-facing explanation of this occurrence |
|
|
1084
|
+
| `instance` | `string` | URI for this specific occurrence |
|
|
1085
|
+
| `code` | `string` | Machine-readable cause, when exactly one thing failed |
|
|
1086
|
+
| `field` | `string` | The offending request field, alongside `code` |
|
|
1087
|
+
| `errors` | `Array<{ field, message, code? }>` | Field-level causes, when more than one thing failed |
|
|
1088
|
+
| `retryable` | `boolean` | Whether the same request may succeed later |
|
|
1089
|
+
| `retryAfter` | `number` | Seconds to wait before retrying |
|
|
1090
|
+
| `suggestedAction` | `'auto_ramp' \| 'wait_for_settlement' \| (string & {})` | What the API suggests doing next; open so new values still parse |
|
|
1091
|
+
| `clearsAt` | `string \| null` | When a limit clears; `null` means not bounded by time |
|
|
1092
|
+
| `availableAt` | `string \| null` | When the resource becomes available |
|
|
1093
|
+
| `permanent` | `boolean` | Whether retrying can ever succeed |
|
|
1094
|
+
| `realm` | `string` | Authentication realm, on some `401`s |
|
|
1095
|
+
| `scope` | `string` | Scope required for the resource, on some `401`s |
|
|
1096
|
+
| `resourceType` | `string` | Type of the missing resource; required on `404`s |
|
|
1097
|
+
| `resourceId` | `string` | Id of the missing resource; required on `404`s |
|
|
1098
|
+
|
|
1099
|
+
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.
|
|
1100
|
+
|
|
1101
|
+
Some fields only appear on certain problems — `realm`/`scope` on some `401`s, `resourceType`/`resourceId` on `404`s — so check before reading them:
|
|
1102
|
+
|
|
1103
|
+
```typescript
|
|
1104
|
+
if (isAPIError(error) && error.status === 404) {
|
|
1105
|
+
logger.warn(`missing ${error.problem?.resourceType}: ${error.problem?.resourceId}`)
|
|
1106
|
+
}
|
|
1107
|
+
```
|
|
1108
|
+
|
|
1109
|
+
The original parsed payload is always preserved on `error.error`, so fields `ProblemDetails` does not model stay reachable for logging:
|
|
1110
|
+
|
|
1111
|
+
```typescript
|
|
1112
|
+
if (isAPIError(error)) {
|
|
1113
|
+
logger.warn({
|
|
1114
|
+
status: error.status,
|
|
1115
|
+
problem: error.problem,
|
|
1116
|
+
payload: error.error, // untouched, including fields not modelled above
|
|
1117
|
+
requestId: error.requestId,
|
|
1118
|
+
traceId: error.traceId,
|
|
1119
|
+
})
|
|
1120
|
+
}
|
|
1121
|
+
```
|
|
1122
|
+
|
|
1123
|
+
`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`.
|
|
1124
|
+
|
|
1125
|
+
> **`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.
|
|
1126
|
+
|
|
1043
1127
|
## Sandbox
|
|
1044
1128
|
|
|
1045
1129
|
Use `Environment.Sandbox` for development and testing. The sandbox environment is available at `https://sandbox.spritz.finance`.
|