@spritz-finance/api-client 0.21.0 → 0.23.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
@@ -148,20 +148,22 @@ const user = await client.user.create({
148
148
  }
149
149
  ```
150
150
 
151
- Creating a user with an email that already exists will throw an error.
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.
152
152
 
153
- With an integrator secret configured, `user.create()` calls `POST /v1/integrator/users` on the REST API. A conflict throws a `ConflictError` (409); branch on its `problem.code`:
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_ALREADY_EXISTS` | The email already has a Spritz account | Connect the existing user (below) |
158
- | `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 | 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 |
159
161
 
160
- Without a secret it uses the legacy route, which does not accept Developer Console credentials.
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.
161
163
 
162
164
  ### Connecting an Existing User (Spritz Connect)
163
165
 
164
- When `user.create()` fails with `USER_ALREADY_EXISTS`, that email already has a Spritz account. Ask the user to authorize your integrator with Spritz Connect. Run these calls on your backend; both need integrator credentials (`integrationKey` + `integratorSecret`).
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`).
165
167
 
166
168
  ```typescript
167
169
  import { hasProblemCode } from '@spritz-finance/api-client'
@@ -169,11 +171,14 @@ import { hasProblemCode } from '@spritz-finance/api-client'
169
171
  try {
170
172
  return await client.user.create({ email })
171
173
  } catch (error) {
172
- if (!hasProblemCode(error, 'USER_ALREADY_EXISTS')) throw error
174
+ const needsConnect =
175
+ hasProblemCode(error, 'USER_ALREADY_EXISTS') ||
176
+ hasProblemCode(error, 'USER_SELECTION_REQUIRED')
177
+ if (!needsConnect) throw error
173
178
  }
174
179
 
175
- // 1. Start a session for the email that was rejected. Persist `state` with the
176
- // user's attempt so you can verify the callback.
180
+ // 1. Start a session for the account's email. Persist `state` with the user's
181
+ // attempt so you can verify the callback.
177
182
  const { authorizationUrl, sessionId, expiresAt } = await client.connect.createSession({
178
183
  redirectUri: 'https://api.example.com/spritz/connect/callback', // registered with Spritz
179
184
  state: crypto.randomUUID(),
@@ -191,17 +196,21 @@ const { apiKey, userId, email } = await client.connect.exchangeCode(code)
191
196
  // Store apiKey server-side only.
192
197
  ```
193
198
 
194
- `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.
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.
195
200
 
196
201
  ### Reauthorization
197
202
 
198
- If you need to recover a user's API key (e.g., the user already has a Spritz account, or you've lost access), use the OTP reauthorization flow:
203
+ > **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
+
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.
206
+
207
+ The legacy flow, for existing integrations only:
199
208
 
200
209
  ```typescript
201
- // Request an OTP code sent to the user's email
210
+ // Deprecated: request an OTP code sent to the user's email
202
211
  const { success } = await client.user.requestApiKey('bilbo@shiremail.net')
203
212
 
204
- // Confirm with the OTP code the user provides
213
+ // Deprecated: confirm with the OTP code the user provides
205
214
  const { apiKey, userId, email } = await client.user.authorizeApiKeyWithOTP({
206
215
  email: 'bilbo@shiremail.net',
207
216
  otp: '123456',
@@ -29,7 +29,20 @@ interface paths {
29
29
  put?: never;
30
30
  /**
31
31
  * Create an auto-ramp account
32
- * @description Creates a new auto-ramp account for the authenticated user. The account is a virtual bank account that automatically converts fiat deposits to crypto. The address must be valid for the specified network, and the network/token combination must be supported for your region.
32
+ * @description Creates an auto-ramp account for the authenticated user. The account is a
33
+ * virtual bank account that automatically converts fiat deposits to crypto. The
34
+ * address must be valid for the specified network, and the network/token
35
+ * combination must be supported for your region.
36
+ *
37
+ * **Idempotent per (`address`, `network`, `token`).** If the user already
38
+ * has an account for that combination, the request returns that account with
39
+ * `201` instead of creating another. Store the returned `id`; do not treat a
40
+ * `201` as proof that a new account was created.
41
+ *
42
+ * **Conflict** (`409`): branch on the problem `code`, not the title or detail.
43
+ * `AUTO_RAMP_ACCOUNT_CREATE_IN_PROGRESS` (`retryable: true`) means another
44
+ * request is creating an account for the same `address`, `network`, and
45
+ * `token`. Retry after a short delay to receive the same account.
33
46
  */
34
47
  post: operations["postV1Auto-ramp-accounts"];
35
48
  delete?: never;
@@ -440,9 +453,9 @@ interface paths {
440
453
  * | `us` | United States | `routingNumber`, `accountNumber` | ACH, RTP, Wire |
441
454
  * | `ca` | Canada | `institutionNumber`, `transitNumber`, `accountNumber` | EFT |
442
455
  * | `uk` | United Kingdom | `sortCode`, `accountNumber` | FPS |
443
- * | `iban` | Europe / SEPA | `iban`, `bic` | SEPA |
456
+ * | `iban` | Europe / SEPA | `iban` | SEPA |
444
457
  *
445
- * For `iban` accounts the beneficiary's address is required. When `ownership` is
458
+ * For `iban` accounts `bic` is optional. The beneficiary's address is required. When `ownership` is
446
459
  * `personal` it is taken from your verified identity; when `thirdParty` you must
447
460
  * supply `accountHolder.address`, including its `country`.
448
461
  *
@@ -1413,7 +1426,7 @@ interface paths {
1413
1426
  *
1414
1427
  * The response includes the user's API key (`ak_...`), which is returned only once at creation - store it securely.
1415
1428
  *
1416
- * **Conflict**: If a user with the given email already exists, the request fails with `409 Conflict`. In that case, use Spritz Connect (`POST /v1/integrator/connect/sessions`) with the same `email` to have the existing user authorize this integrator; the hosted page shows that email and only that account can approve. A concurrent request to create a user with the same email also returns `409 Conflict`; retry shortly.
1429
+ * **Conflict** (`409`): branch on the problem `code`, not the title or detail. `USER_ALREADY_EXISTS` means the email already has a Spritz account: use Spritz Connect (`POST /v1/integrator/connect/sessions`) with the same `email` to have the existing user authorize this integrator; the hosted page shows that email and only that account can approve. `USER_CREATE_IN_PROGRESS` (`retryable: true`) means another request is already creating a user with this email; retry shortly.
1417
1430
  */
1418
1431
  post: operations["postV1IntegratorUsers"];
1419
1432
  delete?: never;
@@ -3063,6 +3076,75 @@ interface operations {
3063
3076
  };
3064
3077
  };
3065
3078
  };
3079
+ /** @description Response for status 400 */
3080
+ 400: {
3081
+ headers: {
3082
+ [name: string]: unknown;
3083
+ };
3084
+ content: {
3085
+ "application/problem+json": {
3086
+ /**
3087
+ * @description A URI reference that identifies the problem type
3088
+ * @default about:blank
3089
+ * @example urn:problem-type:auth:unauthorized
3090
+ */
3091
+ type: string;
3092
+ /**
3093
+ * @description A short, human-readable summary of the problem type
3094
+ * @example Unauthorized
3095
+ */
3096
+ title: string;
3097
+ /**
3098
+ * @description The HTTP status code
3099
+ * @example 400
3100
+ */
3101
+ status: number;
3102
+ /** @description A human-readable explanation specific to this occurrence */
3103
+ detail?: string;
3104
+ /**
3105
+ * @description A URI reference that identifies the specific occurrence
3106
+ * @example /errors/1234567890
3107
+ */
3108
+ instance?: string;
3109
+ /**
3110
+ * @description Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight.
3111
+ * @example transaction_limit
3112
+ */
3113
+ code?: string;
3114
+ /**
3115
+ * @description The offending request field, present alongside `code`.
3116
+ * @example amountUsd
3117
+ */
3118
+ field?: string;
3119
+ /**
3120
+ * @description Whether retrying the same request later may succeed without changing its inputs.
3121
+ * @example true
3122
+ */
3123
+ retryable?: boolean;
3124
+ /**
3125
+ * @description Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead.
3126
+ * @example 5
3127
+ */
3128
+ retryAfter?: number;
3129
+ /** @enum {string} */
3130
+ suggestedAction?: "auto_ramp" | "wait_for_settlement";
3131
+ /**
3132
+ * Format: date-time
3133
+ * @description Earliest known time the current temporary condition may clear.
3134
+ */
3135
+ clearsAt?: string | null;
3136
+ /**
3137
+ * Format: date-time
3138
+ * @description When a temporarily ineligible funding source may become available again.
3139
+ */
3140
+ availableAt?: string | null;
3141
+ /** @description Whether the current funding-source restriction will not clear automatically. */
3142
+ permanent?: boolean;
3143
+ } & {
3144
+ [key: string]: unknown;
3145
+ };
3146
+ };
3147
+ };
3066
3148
  /** @description Response for status 401 */
3067
3149
  401: {
3068
3150
  headers: {
@@ -3106,6 +3188,75 @@ interface operations {
3106
3188
  };
3107
3189
  };
3108
3190
  };
3191
+ /** @description Response for status 403 */
3192
+ 403: {
3193
+ headers: {
3194
+ [name: string]: unknown;
3195
+ };
3196
+ content: {
3197
+ "application/problem+json": {
3198
+ /**
3199
+ * @description A URI reference that identifies the problem type
3200
+ * @default about:blank
3201
+ * @example urn:problem-type:auth:unauthorized
3202
+ */
3203
+ type: string;
3204
+ /**
3205
+ * @description A short, human-readable summary of the problem type
3206
+ * @example Unauthorized
3207
+ */
3208
+ title: string;
3209
+ /**
3210
+ * @description The HTTP status code
3211
+ * @example 400
3212
+ */
3213
+ status: number;
3214
+ /** @description A human-readable explanation specific to this occurrence */
3215
+ detail?: string;
3216
+ /**
3217
+ * @description A URI reference that identifies the specific occurrence
3218
+ * @example /errors/1234567890
3219
+ */
3220
+ instance?: string;
3221
+ /**
3222
+ * @description Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight.
3223
+ * @example transaction_limit
3224
+ */
3225
+ code?: string;
3226
+ /**
3227
+ * @description The offending request field, present alongside `code`.
3228
+ * @example amountUsd
3229
+ */
3230
+ field?: string;
3231
+ /**
3232
+ * @description Whether retrying the same request later may succeed without changing its inputs.
3233
+ * @example true
3234
+ */
3235
+ retryable?: boolean;
3236
+ /**
3237
+ * @description Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead.
3238
+ * @example 5
3239
+ */
3240
+ retryAfter?: number;
3241
+ /** @enum {string} */
3242
+ suggestedAction?: "auto_ramp" | "wait_for_settlement";
3243
+ /**
3244
+ * Format: date-time
3245
+ * @description Earliest known time the current temporary condition may clear.
3246
+ */
3247
+ clearsAt?: string | null;
3248
+ /**
3249
+ * Format: date-time
3250
+ * @description When a temporarily ineligible funding source may become available again.
3251
+ */
3252
+ availableAt?: string | null;
3253
+ /** @description Whether the current funding-source restriction will not clear automatically. */
3254
+ permanent?: boolean;
3255
+ } & {
3256
+ [key: string]: unknown;
3257
+ };
3258
+ };
3259
+ };
3109
3260
  /** @description Response for status 404 */
3110
3261
  404: {
3111
3262
  headers: {
@@ -3139,6 +3290,75 @@ interface operations {
3139
3290
  };
3140
3291
  };
3141
3292
  };
3293
+ /** @description Response for status 409 */
3294
+ 409: {
3295
+ headers: {
3296
+ [name: string]: unknown;
3297
+ };
3298
+ content: {
3299
+ "application/problem+json": {
3300
+ /**
3301
+ * @description A URI reference that identifies the problem type
3302
+ * @default about:blank
3303
+ * @example urn:problem-type:auth:unauthorized
3304
+ */
3305
+ type: string;
3306
+ /**
3307
+ * @description A short, human-readable summary of the problem type
3308
+ * @example Unauthorized
3309
+ */
3310
+ title: string;
3311
+ /**
3312
+ * @description The HTTP status code
3313
+ * @example 400
3314
+ */
3315
+ status: number;
3316
+ /** @description A human-readable explanation specific to this occurrence */
3317
+ detail?: string;
3318
+ /**
3319
+ * @description A URI reference that identifies the specific occurrence
3320
+ * @example /errors/1234567890
3321
+ */
3322
+ instance?: string;
3323
+ /**
3324
+ * @description Machine-readable cause, present when exactly one thing failed. Branch on this, never on `detail`, which is human-facing copy and may change. For deposit limits the vocabulary matches the `reason` values the limits API returns pre-flight.
3325
+ * @example transaction_limit
3326
+ */
3327
+ code?: string;
3328
+ /**
3329
+ * @description The offending request field, present alongside `code`.
3330
+ * @example amountUsd
3331
+ */
3332
+ field?: string;
3333
+ /**
3334
+ * @description Whether retrying the same request later may succeed without changing its inputs.
3335
+ * @example true
3336
+ */
3337
+ retryable?: boolean;
3338
+ /**
3339
+ * @description Seconds to wait before retrying, present alongside `retryable: true`. Mirrors the `Retry-After` response header and is meant for short backoffs the server chose (load shedding); for a condition that clears on its own schedule, `clearsAt` carries the absolute time instead.
3340
+ * @example 5
3341
+ */
3342
+ retryAfter?: number;
3343
+ /** @enum {string} */
3344
+ suggestedAction?: "auto_ramp" | "wait_for_settlement";
3345
+ /**
3346
+ * Format: date-time
3347
+ * @description Earliest known time the current temporary condition may clear.
3348
+ */
3349
+ clearsAt?: string | null;
3350
+ /**
3351
+ * Format: date-time
3352
+ * @description When a temporarily ineligible funding source may become available again.
3353
+ */
3354
+ availableAt?: string | null;
3355
+ /** @description Whether the current funding-source restriction will not clear automatically. */
3356
+ permanent?: boolean;
3357
+ } & {
3358
+ [key: string]: unknown;
3359
+ };
3360
+ };
3361
+ };
3142
3362
  /** @description Response for status 500 */
3143
3363
  500: {
3144
3364
  headers: {
@@ -4003,7 +4223,7 @@ interface operations {
4003
4223
  /**
4004
4224
  * Format: date-time
4005
4225
  * @description Creation timestamp
4006
- * @example 2026-10-06T16:12:43.523Z
4226
+ * @example 2026-10-08T15:15:02.544Z
4007
4227
  */
4008
4228
  createdAt?: string;
4009
4229
  }[];
@@ -4168,7 +4388,7 @@ interface operations {
4168
4388
  "application/json": {
4169
4389
  /**
4170
4390
  * @description Destination account ID
4171
- * @example 6ac51dfb61ca9c031e3c0433
4391
+ * @example 6ac7b3760f2ad32d458d1b1f
4172
4392
  */
4173
4393
  accountId: string;
4174
4394
  /**
@@ -4196,7 +4416,7 @@ interface operations {
4196
4416
  "application/x-www-form-urlencoded": {
4197
4417
  /**
4198
4418
  * @description Destination account ID
4199
- * @example 6ac51dfb61ca9c031e3c0433
4419
+ * @example 6ac7b3760f2ad32d458d1b1f
4200
4420
  */
4201
4421
  accountId: string;
4202
4422
  /**
@@ -4224,7 +4444,7 @@ interface operations {
4224
4444
  "multipart/form-data": {
4225
4445
  /**
4226
4446
  * @description Destination account ID
4227
- * @example 6ac51dfb61ca9c031e3c0433
4447
+ * @example 6ac7b3760f2ad32d458d1b1f
4228
4448
  */
4229
4449
  accountId: string;
4230
4450
  /**
@@ -4271,7 +4491,7 @@ interface operations {
4271
4491
  /**
4272
4492
  * Format: date-time
4273
4493
  * @description When the quote was created
4274
- * @example 2026-10-06T16:12:43.457Z
4494
+ * @example 2026-10-08T15:15:02.532Z
4275
4495
  */
4276
4496
  createdAt: string;
4277
4497
  /** @description Exact USD value collected by Spritz and the token route used to fund it. The exact token quantity is returned by the transaction endpoint. */
@@ -4310,7 +4530,7 @@ interface operations {
4310
4530
  rail: "ach_standard" | "ach_same_day" | "rtp" | "wire" | "eft" | "sepa" | "faster_payments" | "push_to_card" | "bill_pay" | "card_deposit";
4311
4531
  /**
4312
4532
  * @description Destination account ID
4313
- * @example 6ac51dfb61ca9c031e3c0434
4533
+ * @example 6ac7b3760f2ad32d458d1b20
4314
4534
  */
4315
4535
  accountId: string;
4316
4536
  /** @description True when this quote does not lock the destination amount. EUR quotes remain estimates; actual settlement is reported by the off-ramp resource. */
@@ -4567,7 +4787,7 @@ interface operations {
4567
4787
  /**
4568
4788
  * Format: date-time
4569
4789
  * @description When the quote was created
4570
- * @example 2026-10-06T16:12:43.457Z
4790
+ * @example 2026-10-08T15:15:02.532Z
4571
4791
  */
4572
4792
  createdAt: string;
4573
4793
  /** @description Exact USD value collected by Spritz and the token route used to fund it. The exact token quantity is returned by the transaction endpoint. */
@@ -4606,7 +4826,7 @@ interface operations {
4606
4826
  rail: "ach_standard" | "ach_same_day" | "rtp" | "wire" | "eft" | "sepa" | "faster_payments" | "push_to_card" | "bill_pay" | "card_deposit";
4607
4827
  /**
4608
4828
  * @description Destination account ID
4609
- * @example 6ac51dfb61ca9c031e3c0434
4829
+ * @example 6ac7b3760f2ad32d458d1b20
4610
4830
  */
4611
4831
  accountId: string;
4612
4832
  /** @description True when this quote does not lock the destination amount. EUR quotes remain estimates; actual settlement is reported by the off-ramp resource. */
@@ -5202,7 +5422,7 @@ interface operations {
5202
5422
  /**
5203
5423
  * Format: date-time
5204
5424
  * @description When the quote was created
5205
- * @example 2026-10-06T16:12:43.457Z
5425
+ * @example 2026-10-08T15:15:02.532Z
5206
5426
  */
5207
5427
  createdAt: string;
5208
5428
  /** @description Exact USD value collected by Spritz and the token route used to fund it. The exact token quantity is returned by the transaction endpoint. */
@@ -5241,7 +5461,7 @@ interface operations {
5241
5461
  rail: "ach_standard" | "ach_same_day" | "rtp" | "wire" | "eft" | "sepa" | "faster_payments" | "push_to_card" | "bill_pay" | "card_deposit";
5242
5462
  /**
5243
5463
  * @description Destination account ID
5244
- * @example 6ac51dfb61ca9c031e3c0434
5464
+ * @example 6ac7b3760f2ad32d458d1b20
5245
5465
  */
5246
5466
  accountId: string;
5247
5467
  /** @description True when this quote does not lock the destination amount. EUR quotes remain estimates; actual settlement is reported by the off-ramp resource. */
@@ -5544,7 +5764,7 @@ interface operations {
5544
5764
  currency: string;
5545
5765
  /**
5546
5766
  * @description Destination account ID
5547
- * @example 6ac51dfb61ca9c031e3c0435
5767
+ * @example 6ac7b3760f2ad32d458d1b21
5548
5768
  */
5549
5769
  accountId: string;
5550
5770
  /**
@@ -5835,7 +6055,7 @@ interface operations {
5835
6055
  currency: string;
5836
6056
  /**
5837
6057
  * @description Destination account ID
5838
- * @example 6ac51dfb61ca9c031e3c0435
6058
+ * @example 6ac7b3760f2ad32d458d1b21
5839
6059
  */
5840
6060
  accountId: string;
5841
6061
  /**
@@ -6076,7 +6296,7 @@ interface operations {
6076
6296
  method: "account";
6077
6297
  /**
6078
6298
  * @description Destination account to reissue the payout to. Omit to reuse the off-ramp's original destination account.
6079
- * @example 6ac51dfb61ca9c031e3c0436
6299
+ * @example 6ac7b3760f2ad32d458d1b22
6080
6300
  */
6081
6301
  accountId?: string;
6082
6302
  };
@@ -6094,7 +6314,7 @@ interface operations {
6094
6314
  method: "account";
6095
6315
  /**
6096
6316
  * @description Destination account to reissue the payout to. Omit to reuse the off-ramp's original destination account.
6097
- * @example 6ac51dfb61ca9c031e3c0436
6317
+ * @example 6ac7b3760f2ad32d458d1b22
6098
6318
  */
6099
6319
  accountId?: string;
6100
6320
  };
@@ -6112,7 +6332,7 @@ interface operations {
6112
6332
  method: "account";
6113
6333
  /**
6114
6334
  * @description Destination account to reissue the payout to. Omit to reuse the off-ramp's original destination account.
6115
- * @example 6ac51dfb61ca9c031e3c0436
6335
+ * @example 6ac7b3760f2ad32d458d1b22
6116
6336
  */
6117
6337
  accountId?: string;
6118
6338
  };
@@ -6178,7 +6398,7 @@ interface operations {
6178
6398
  currency: string;
6179
6399
  /**
6180
6400
  * @description Destination account ID
6181
- * @example 6ac51dfb61ca9c031e3c0435
6401
+ * @example 6ac7b3760f2ad32d458d1b21
6182
6402
  */
6183
6403
  accountId: string;
6184
6404
  /**
@@ -8321,10 +8541,10 @@ interface operations {
8321
8541
  */
8322
8542
  iban: string;
8323
8543
  /**
8324
- * @description Bank Identifier Code (SWIFT) of the account's bank.
8544
+ * @description Bank Identifier Code (SWIFT) of the account's bank. Optional for SEPA; supplying it can improve routing.
8325
8545
  * @example COBADEFFXXX
8326
8546
  */
8327
- bic: string;
8547
+ bic?: string;
8328
8548
  /**
8329
8549
  * @description Name of the account's bank
8330
8550
  * @example Commerzbank
@@ -8567,10 +8787,10 @@ interface operations {
8567
8787
  */
8568
8788
  iban: string;
8569
8789
  /**
8570
- * @description Bank Identifier Code (SWIFT) of the account's bank.
8790
+ * @description Bank Identifier Code (SWIFT) of the account's bank. Optional for SEPA; supplying it can improve routing.
8571
8791
  * @example COBADEFFXXX
8572
8792
  */
8573
- bic: string;
8793
+ bic?: string;
8574
8794
  /**
8575
8795
  * @description Name of the account's bank
8576
8796
  * @example Commerzbank
@@ -8813,10 +9033,10 @@ interface operations {
8813
9033
  */
8814
9034
  iban: string;
8815
9035
  /**
8816
- * @description Bank Identifier Code (SWIFT) of the account's bank.
9036
+ * @description Bank Identifier Code (SWIFT) of the account's bank. Optional for SEPA; supplying it can improve routing.
8817
9037
  * @example COBADEFFXXX
8818
9038
  */
8819
- bic: string;
9039
+ bic?: string;
8820
9040
  /**
8821
9041
  * @description Name of the account's bank
8822
9042
  * @example Commerzbank
@@ -17949,7 +18169,7 @@ interface operations {
17949
18169
  data: {
17950
18170
  /**
17951
18171
  * @description Unique identifier for the debit card
17952
- * @example 6ac51dfb61ca9c031e3c043a
18172
+ * @example 6ac7b3760f2ad32d458d1b26
17953
18173
  */
17954
18174
  id: string;
17955
18175
  /** @enum {string} */
@@ -18397,7 +18617,7 @@ interface operations {
18397
18617
  "application/json": {
18398
18618
  /**
18399
18619
  * @description Unique identifier for the debit card
18400
- * @example 6ac51dfb61ca9c031e3c043a
18620
+ * @example 6ac7b3760f2ad32d458d1b26
18401
18621
  */
18402
18622
  id: string;
18403
18623
  /** @enum {string} */
@@ -18614,7 +18834,7 @@ interface operations {
18614
18834
  "application/json": {
18615
18835
  /**
18616
18836
  * @description Unique identifier for the debit card
18617
- * @example 6ac51dfb61ca9c031e3c043a
18837
+ * @example 6ac7b3760f2ad32d458d1b26
18618
18838
  */
18619
18839
  id: string;
18620
18840
  /** @enum {string} */
@@ -19135,7 +19355,7 @@ interface operations {
19135
19355
  "application/json": {
19136
19356
  /**
19137
19357
  * @description Unique identifier for the debit card
19138
- * @example 6ac51dfb61ca9c031e3c043a
19358
+ * @example 6ac7b3760f2ad32d458d1b26
19139
19359
  */
19140
19360
  id: string;
19141
19361
  /** @enum {string} */
@@ -20525,7 +20745,7 @@ interface operations {
20525
20745
  accessToken: string;
20526
20746
  /**
20527
20747
  * @description The internal ID of the authorized user
20528
- * @example 6ac51dfb61ca9c031e3c043e
20748
+ * @example 6ac7b3760f2ad32d458d1b2a
20529
20749
  */
20530
20750
  userId: string;
20531
20751
  /**
@@ -20541,7 +20761,7 @@ interface operations {
20541
20761
  /**
20542
20762
  * Format: date-time
20543
20763
  * @description ISO 8601 timestamp when token expires
20544
- * @example 2026-10-06T17:12:43.834Z
20764
+ * @example 2026-10-08T16:15:02.830Z
20545
20765
  */
20546
20766
  expiresAt: string;
20547
20767
  };
@@ -20740,7 +20960,7 @@ interface operations {
20740
20960
  /**
20741
20961
  * Format: date-time
20742
20962
  * @description ISO 8601 timestamp of when the integrator was created
20743
- * @example 2026-10-06T16:12:43.833Z
20963
+ * @example 2026-10-08T15:15:02.830Z
20744
20964
  */
20745
20965
  createdAt: string;
20746
20966
  };
@@ -20953,7 +21173,7 @@ interface operations {
20953
21173
  "application/json": {
20954
21174
  /**
20955
21175
  * @description The internal ID of the newly created user
20956
- * @example 6ac51dfb61ca9c031e3c0440
21176
+ * @example 6ac7b3760f2ad32d458d1b2c
20957
21177
  */
20958
21178
  userId: string;
20959
21179
  /**
@@ -21297,7 +21517,7 @@ interface operations {
21297
21517
  depositId: string;
21298
21518
  /**
21299
21519
  * @description Spritz user ID associated with the returned deposit
21300
- * @example 6ac51dfb61ca9c031e3c043d
21520
+ * @example 6ac7b3760f2ad32d458d1b29
21301
21521
  */
21302
21522
  userId: string;
21303
21523
  /**
@@ -21509,7 +21729,7 @@ interface operations {
21509
21729
  depositId: string;
21510
21730
  /**
21511
21731
  * @description Spritz user ID associated with the returned deposit
21512
- * @example 6ac51dfb61ca9c031e3c043d
21732
+ * @example 6ac7b3760f2ad32d458d1b29
21513
21733
  */
21514
21734
  userId: string;
21515
21735
  /**
@@ -21702,7 +21922,7 @@ interface operations {
21702
21922
  "application/json": {
21703
21923
  /**
21704
21924
  * @description Unique identifier for the webhook
21705
- * @example 6ac51dfb61ca9c031e3c043f
21925
+ * @example 6ac7b3760f2ad32d458d1b2b
21706
21926
  */
21707
21927
  id: string;
21708
21928
  /** @description List of event types this webhook is subscribed to */
@@ -21933,7 +22153,7 @@ interface operations {
21933
22153
  "application/json": {
21934
22154
  /**
21935
22155
  * @description Unique identifier for the webhook
21936
- * @example 6ac51dfb61ca9c031e3c043f
22156
+ * @example 6ac7b3760f2ad32d458d1b2b
21937
22157
  */
21938
22158
  id: string;
21939
22159
  /** @description List of event types this webhook is subscribed to */
@@ -23901,7 +24121,7 @@ interface operations {
23901
24121
  "application/json": {
23902
24122
  /**
23903
24123
  * @description Unique identifier for the webhook
23904
- * @example 6ac51dfb61ca9c031e3c043f
24124
+ * @example 6ac7b3760f2ad32d458d1b2b
23905
24125
  */
23906
24126
  id: string;
23907
24127
  /** @description List of event types this webhook is subscribed to */
@@ -24318,7 +24538,7 @@ interface operations {
24318
24538
  /**
24319
24539
  * Format: date-time
24320
24540
  * @description ISO 8601 timestamp when the old secret will expire. Only present if a grace period was specified.
24321
- * @example 2026-10-06T16:17:43.835Z
24541
+ * @example 2026-10-08T15:20:02.830Z
24322
24542
  */
24323
24543
  oldSecretExpiresAt?: string;
24324
24544
  };
@@ -24489,7 +24709,7 @@ interface operations {
24489
24709
  "application/json": {
24490
24710
  /**
24491
24711
  * @description Unique identifier for the user
24492
- * @example 6ac51dfb61ca9c031e3c043b
24712
+ * @example 6ac7b3760f2ad32d458d1b27
24493
24713
  */
24494
24714
  id: string;
24495
24715
  /**
@@ -24506,7 +24726,7 @@ interface operations {
24506
24726
  /**
24507
24727
  * Format: date-time
24508
24728
  * @description ISO 8601 timestamp of when the user was created
24509
- * @example 2026-10-06T16:12:43.824Z
24729
+ * @example 2026-10-08T15:15:02.821Z
24510
24730
  */
24511
24731
  signedUpAt: string;
24512
24732
  /**
@@ -24886,7 +25106,7 @@ interface operations {
24886
25106
  "application/json": {
24887
25107
  /**
24888
25108
  * @description Unique identifier for the user
24889
- * @example 6ac51dfb61ca9c031e3c043b
25109
+ * @example 6ac7b3760f2ad32d458d1b27
24890
25110
  */
24891
25111
  id: string;
24892
25112
  /**
@@ -24903,7 +25123,7 @@ interface operations {
24903
25123
  /**
24904
25124
  * Format: date-time
24905
25125
  * @description ISO 8601 timestamp of when the user was created
24906
- * @example 2026-10-06T16:12:43.824Z
25126
+ * @example 2026-10-08T15:15:02.821Z
24907
25127
  */
24908
25128
  signedUpAt: string;
24909
25129
  /**
@@ -25383,7 +25603,7 @@ interface operations {
25383
25603
  "application/json": {
25384
25604
  /**
25385
25605
  * @description Unique identifier for the user
25386
- * @example 6ac51dfb61ca9c031e3c043b
25606
+ * @example 6ac7b3760f2ad32d458d1b27
25387
25607
  */
25388
25608
  id: string;
25389
25609
  /**
@@ -25400,7 +25620,7 @@ interface operations {
25400
25620
  /**
25401
25621
  * Format: date-time
25402
25622
  * @description ISO 8601 timestamp of when the user was created
25403
- * @example 2026-10-06T16:12:43.824Z
25623
+ * @example 2026-10-08T15:15:02.821Z
25404
25624
  */
25405
25625
  signedUpAt: string;
25406
25626
  /**
@@ -40322,13 +40542,18 @@ type CreateConnectSessionParams = PathRequestBody<'/v1/integrator/connect/sessio
40322
40542
  type ConnectSession = PathResponse<'/v1/integrator/connect/sessions', 'post'>;
40323
40543
  type ConnectTokenExchange = PathResponse<'/v1/integrator/connect/token', 'post'>;
40324
40544
  /**
40325
- * Spritz Connect: let an existing Spritz user authorize your integrator.
40545
+ * Spritz Connect: let a Spritz user authorize your integrator to act for an account
40546
+ * you do not own.
40326
40547
  *
40327
- * Use it when `user.createUser` fails with a `ConflictError` whose
40328
- * `problem.code` is `USER_ALREADY_EXISTS` (the email already has a Spritz account):
40548
+ * Where reuse is enabled, `user.createUser` returns your own or currently
40549
+ * authorized account. Connect explicitly grants access to a selected existing
40550
+ * account. Use it when create fails with `USER_ALREADY_EXISTS` (this call cannot
40551
+ * return an existing account, including when reuse is disabled), when it fails with `USER_SELECTION_REQUIRED`
40552
+ * (you are authorized for several accounts with that email and must pick one), or
40553
+ * whenever you want access to a specific existing account:
40329
40554
  *
40330
40555
  * 1. `createSession({ redirectUri, state, email })` on your backend, passing the
40331
- * email that was rejected. Send the user to `authorizationUrl` unchanged
40556
+ * email of the account. Send the user to `authorizationUrl` unchanged
40332
40557
  * (it carries a `#return_token` fragment; never log it). On mobile open it
40333
40558
  * in the system auth session, not a WebView.
40334
40559
  * 2. Spritz redirects to `redirectUri` with `code` and your `state`, or with
@@ -43629,22 +43854,50 @@ declare class UserService {
43629
43854
  private client;
43630
43855
  constructor(client: SpritzClient);
43631
43856
  /**
43632
- * Create a user under the integrator and return their API key.
43857
+ * Create an account under your integrator and return its access key.
43858
+ * With an integrator secret this uses POST /v1/integrator/users; without
43859
+ * one it uses the deprecated /users/integration route.
43633
43860
  *
43634
- * With integrator HMAC credentials (`integrationKey` + `integratorSecret`, as issued
43635
- * by the Developer Console) this calls `POST /v1/integrator/users` on the REST API.
43636
- * Without a secret it uses the legacy `/users/integration` route, which does not
43637
- * accept Developer Console credentials.
43861
+ * Where reuse is enabled, a normalized email (trimmed, lowercased) resolves
43862
+ * first to your own account, then to one currently authorized account.
43863
+ * A repeat returns the same userId and current email with a fresh apiKey.
43864
+ * Older keys can stay valid until revoked. Where reuse is disabled, handle
43865
+ * USER_ALREADY_EXISTS for any existing account.
43638
43866
  *
43639
- * On the REST route a conflict is a `ConflictError` (409). Branch on `problem.code`:
43640
- * `USER_ALREADY_EXISTS` means the email already has a Spritz account, so use Spritz
43641
- * Connect (`client.connect.createSession` with that email) to have the existing user
43642
- * authorize the integrator; `USER_CREATE_IN_PROGRESS` means another request is
43643
- * creating that user, so retry shortly.
43867
+ * Cross-tenant creation requires an approved rollout for your integrator.
43868
+ * An email held elsewhere grants no access to that account. Both routes
43869
+ * carry coded errors: USER_DELETED (the account resolved for you is closed),
43870
+ * USER_SELECTION_REQUIRED (several authorized matches), USER_ALREADY_EXISTS
43871
+ * (this call cannot return an existing account), USER_CREATE_IN_PROGRESS
43872
+ * (retryable), and AUTHORIZATION_LOOKUP_UNAVAILABLE (retryable 503).
43873
+ * Use hasProblemCode rather than branching on error text. Connect grants
43874
+ * explicit access to an existing account; it does not link identities.
43644
43875
  */
43645
43876
  createUser(args: CreateUserParams): Promise<CreateUserResponse>;
43877
+ /**
43878
+ * Alias of `createUser`: create the account for an email under your integrator, or
43879
+ * reuse the one you already have, and return an API key for it. See `createUser`
43880
+ * for the create-and-reuse contract and the conflict codes.
43881
+ */
43646
43882
  create(args: CreateUserParams): Promise<CreateUserResponse>;
43883
+ /**
43884
+ * Send a one-time code to an email for the legacy key recovery flow.
43885
+ *
43886
+ * @deprecated The email-only recovery flow is being retired: an email can belong to
43887
+ * more than one Spritz account, so a code cannot say which account it is for. To
43888
+ * recover the key of an account in your tenant where account reuse is enabled,
43889
+ * call `createUser` again with the same email: it returns the same `userId` with a
43890
+ * fresh `apiKey`. Where reuse is disabled it returns `USER_ALREADY_EXISTS`; use
43891
+ * Spritz Connect (`client.connect`) instead, also for an account you do not own.
43892
+ * Keeps working until the legacy routes are removed.
43893
+ */
43647
43894
  requestApiKey(email: string): Promise<RequestApiKeyResponse>;
43895
+ /**
43896
+ * Exchange a one-time code from `requestApiKey` for the account's API key.
43897
+ *
43898
+ * @deprecated See `requestApiKey`: recover keys with `createUser` or Spritz Connect.
43899
+ * Keeps working until the legacy routes are removed.
43900
+ */
43648
43901
  authorizeApiKeyWithOTP(args: AuthorizeApiKeyParams): Promise<AuthorizeApiKeyResponse>;
43649
43902
  /**
43650
43903
  * Fetch the authenticated user's profile from the REST API (`GET /v1/users/me`).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spritz-finance/api-client",
3
- "version": "0.21.0",
3
+ "version": "0.23.0",
4
4
  "packageManager": "yarn@1.22.22",
5
5
  "description": "Typescript library for interacting with the Spritz Finance API",
6
6
  "type": "module",