@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 +24 -15
- package/dist/spritz-api-client.d.ts +47 -14
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -148,20 +148,22 @@ const user = await client.user.create({
|
|
|
148
148
|
}
|
|
149
149
|
```
|
|
150
150
|
|
|
151
|
-
|
|
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.
|
|
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
|
|
156
|
-
| ------------------------- |
|
|
157
|
-
| `
|
|
158
|
-
| `
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
176
|
-
//
|
|
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
|
-
|
|
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
|
-
//
|
|
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
|
-
//
|
|
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
|
|
40545
|
+
* Spritz Connect: let a Spritz user authorize your integrator to act for an account
|
|
40546
|
+
* you do not own.
|
|
40546
40547
|
*
|
|
40547
|
-
*
|
|
40548
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
43855
|
-
*
|
|
43856
|
-
*
|
|
43857
|
-
*
|
|
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
|
-
*
|
|
43860
|
-
*
|
|
43861
|
-
*
|
|
43862
|
-
*
|
|
43863
|
-
*
|
|
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`).
|