@spritz-finance/api-client 0.22.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',
@@ -40542,13 +40542,18 @@ type CreateConnectSessionParams = PathRequestBody<'/v1/integrator/connect/sessio
40542
40542
  type ConnectSession = PathResponse<'/v1/integrator/connect/sessions', 'post'>;
40543
40543
  type ConnectTokenExchange = PathResponse<'/v1/integrator/connect/token', 'post'>;
40544
40544
  /**
40545
- * 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.
40546
40547
  *
40547
- * Use it when `user.createUser` fails with a `ConflictError` whose
40548
- * `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:
40549
40554
  *
40550
40555
  * 1. `createSession({ redirectUri, state, email })` on your backend, passing the
40551
- * email that was rejected. Send the user to `authorizationUrl` unchanged
40556
+ * email of the account. Send the user to `authorizationUrl` unchanged
40552
40557
  * (it carries a `#return_token` fragment; never log it). On mobile open it
40553
40558
  * in the system auth session, not a WebView.
40554
40559
  * 2. Spritz redirects to `redirectUri` with `code` and your `state`, or with
@@ -43849,22 +43854,50 @@ declare class UserService {
43849
43854
  private client;
43850
43855
  constructor(client: SpritzClient);
43851
43856
  /**
43852
- * 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.
43853
43860
  *
43854
- * With integrator HMAC credentials (`integrationKey` + `integratorSecret`, as issued
43855
- * by the Developer Console) this calls `POST /v1/integrator/users` on the REST API.
43856
- * Without a secret it uses the legacy `/users/integration` route, which does not
43857
- * 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.
43858
43866
  *
43859
- * On the REST route a conflict is a `ConflictError` (409). Branch on `problem.code`:
43860
- * `USER_ALREADY_EXISTS` means the email already has a Spritz account, so use Spritz
43861
- * Connect (`client.connect.createSession` with that email) to have the existing user
43862
- * authorize the integrator; `USER_CREATE_IN_PROGRESS` means another request is
43863
- * 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.
43864
43875
  */
43865
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
+ */
43866
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
+ */
43867
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
+ */
43868
43901
  authorizeApiKeyWithOTP(args: AuthorizeApiKeyParams): Promise<AuthorizeApiKeyResponse>;
43869
43902
  /**
43870
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.22.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",