@teamhanko/hanko-frontend-sdk 2.7.0 → 3.1.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 +101 -15
- package/dist/Hanko.d.ts +0 -10
- package/dist/lib/Cookie.d.ts +2 -0
- package/dist/lib/Dto.d.ts +0 -10
- package/dist/lib/Navigation.d.ts +2 -0
- package/dist/lib/client/Client.d.ts +1 -1
- package/dist/lib/client/HttpClient.d.ts +4 -1
- package/dist/lib/client/UserClient.d.ts +0 -12
- package/dist/lib/events/Relay.d.ts +1 -1
- package/dist/lib/events/SessionState.d.ts +1 -5
- package/dist/lib/flow-api/State.d.ts +52 -13
- package/dist/lib/flow-api/types/action.d.ts +226 -0
- package/dist/lib/flow-api/types/flow.d.ts +50 -0
- package/dist/lib/flow-api/types/flowError.d.ts +10 -0
- package/dist/lib/flow-api/types/input.d.ts +202 -0
- package/dist/lib/flow-api/types/payload.d.ts +187 -0
- package/dist/lib/flow-api/types/state.d.ts +21 -0
- package/dist/sdk.cjs +1 -1
- package/dist/sdk.cjs.map +1 -1
- package/dist/sdk.modern.js +1 -1
- package/dist/sdk.modern.js.map +1 -1
- package/dist/sdk.module.js +1 -1
- package/dist/sdk.module.js.map +1 -1
- package/dist/sdk.umd.js +1 -1
- package/dist/sdk.umd.js.map +1 -1
- package/package.json +9 -9
package/README.md
CHANGED
|
@@ -42,6 +42,8 @@ yarn add @teamhanko/hanko-frontend-sdk
|
|
|
42
42
|
pnpm install @teamhanko/hanko-frontend-sdk
|
|
43
43
|
```
|
|
44
44
|
|
|
45
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
46
|
+
|
|
45
47
|
## Usage
|
|
46
48
|
|
|
47
49
|
Import as a module:
|
|
@@ -63,6 +65,8 @@ With a script tag via CDN:
|
|
|
63
65
|
</script>
|
|
64
66
|
```
|
|
65
67
|
|
|
68
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
69
|
+
|
|
66
70
|
### Options
|
|
67
71
|
|
|
68
72
|
You can pass certain options, when creating a new `Hanko` instance:
|
|
@@ -79,6 +83,8 @@ const defaultOptions = {
|
|
|
79
83
|
const hanko = new Hanko("http://localhost:3000", defaultOptions);
|
|
80
84
|
```
|
|
81
85
|
|
|
86
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
87
|
+
|
|
82
88
|
### Session Events
|
|
83
89
|
|
|
84
90
|
You can bind callback functions to different custom events. The callback function will be called when the event happens
|
|
@@ -138,6 +144,8 @@ hanko.onUserDeleted(() => {
|
|
|
138
144
|
|
|
139
145
|
Please Take a look into the [docs](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/) for more details.
|
|
140
146
|
|
|
147
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
148
|
+
|
|
141
149
|
### Session Management
|
|
142
150
|
|
|
143
151
|
The SDK provides methods to manage user sessions and retrieve user information.
|
|
@@ -148,26 +156,58 @@ Fetches the current user's profile information.
|
|
|
148
156
|
|
|
149
157
|
- **Returns**: A `User` object containing the user’s profile details. The object includes:
|
|
150
158
|
- `user_id`: A unique string identifier for the user.
|
|
151
|
-
- `passkeys`: An optional array of
|
|
152
|
-
- `security_keys`: An optional array of
|
|
153
|
-
- `mfa_config`: An optional configuration
|
|
154
|
-
- `emails`: An optional array of email objects (e.g., `{ address: string,
|
|
155
|
-
- `username`: An optional username object (e.g., `{ id: string, username: string }`).
|
|
159
|
+
- `passkeys`: An optional array of registered passkeys (`WebauthnCredential[]`).
|
|
160
|
+
- `security_keys`: An optional array of registered security keys (`WebauthnCredential[]`).
|
|
161
|
+
- `mfa_config`: An optional MFA configuration (`{ auth_app_set_up, totp_enabled, security_keys_enabled }`).
|
|
162
|
+
- `emails`: An optional array of email objects (e.g., `{ id: string, address: string, is_verified: boolean, is_primary: boolean, identities?: Identity[] }`).
|
|
163
|
+
- `username`: An optional username object (e.g., `{ id: string, username: string, created_at: string, updated_at: string }`).
|
|
164
|
+
- `metadata`: An optional custom metadata object (`{ public_metadata?, unsafe_metadata? }`).
|
|
165
|
+
- `identities`: An optional array of linked third-party identities (e.g., `{ id: string, provider: string, identity_id?: string }`).
|
|
156
166
|
- `created_at`: A string timestamp (ISO 8601) of when the user was created.
|
|
157
167
|
- `updated_at`: A string timestamp (ISO 8601) of when the user was last updated.
|
|
168
|
+
- `name`, `given_name`, `family_name`, `picture`: Optional profile fields, populated when the user signed up via a third-party provider.
|
|
158
169
|
- **Errors**: `UnauthorizedError` (invalid or expired session), `TechnicalError` (server or network issues).
|
|
159
170
|
|
|
160
171
|
```typescript
|
|
161
172
|
try {
|
|
162
|
-
const user = await hanko.
|
|
173
|
+
const user = await hanko.getCurrentUser();
|
|
163
174
|
console.log("User profile:", user);
|
|
164
175
|
// Example output:
|
|
165
176
|
// {
|
|
166
177
|
// user_id: "123e4567-e89b-12d3-a456-426614174000",
|
|
167
|
-
//
|
|
168
|
-
//
|
|
178
|
+
// passkeys: [{
|
|
179
|
+
// id: "d6df75e0-8a2b-4c6d-9b6e-1a2b3c4d5e6f",
|
|
180
|
+
// name: "MacBook Touch ID",
|
|
181
|
+
// public_key: "...",
|
|
182
|
+
// attestation_type: "none",
|
|
183
|
+
// aaguid: "08987058-cadc-4b81-b6e1-30de50dcbe96",
|
|
184
|
+
// created_at: "2025-01-01T10:00:00Z",
|
|
185
|
+
// transports: "internal",
|
|
186
|
+
// backup_eligible: "true",
|
|
187
|
+
// backup_state: "true"
|
|
188
|
+
// }],
|
|
189
|
+
// security_keys: [],
|
|
190
|
+
// mfa_config: { auth_app_set_up: false, totp_enabled: false, security_keys_enabled: false },
|
|
191
|
+
// emails: [{
|
|
192
|
+
// id: "f2882293-3c39-451d-a7cb-4cf3375e0c66",
|
|
193
|
+
// address: "user@example.com",
|
|
194
|
+
// is_verified: true,
|
|
195
|
+
// is_primary: true,
|
|
196
|
+
// identities: []
|
|
197
|
+
// }],
|
|
198
|
+
// username: {
|
|
199
|
+
// id: "a1b2c3d4-3c39-451d-a7cb-4cf3375e0c66",
|
|
200
|
+
// username: "johndoe",
|
|
201
|
+
// created_at: "2025-01-01T10:00:00Z",
|
|
202
|
+
// updated_at: "2025-01-01T10:00:00Z"
|
|
203
|
+
// },
|
|
204
|
+
// metadata: { public_metadata: {}, unsafe_metadata: {} },
|
|
205
|
+
// identities: [],
|
|
169
206
|
// created_at: "2025-01-01T10:00:00Z",
|
|
170
|
-
// updated_at: "2025-04-01T12:00:00Z"
|
|
207
|
+
// updated_at: "2025-04-01T12:00:00Z",
|
|
208
|
+
// name: "John Doe",
|
|
209
|
+
// given_name: "John",
|
|
210
|
+
// family_name: "Doe"
|
|
171
211
|
// }
|
|
172
212
|
} catch (error) {
|
|
173
213
|
console.error("Failed to fetch user profile:", error);
|
|
@@ -179,9 +219,12 @@ try {
|
|
|
179
219
|
|
|
180
220
|
Checks the validity of the current session.
|
|
181
221
|
|
|
182
|
-
- **Returns**: A SessionCheckResponse object containing:
|
|
222
|
+
- **Returns**: A `SessionCheckResponse` object containing:
|
|
183
223
|
- `is_valid`: A boolean indicating whether the session is valid.
|
|
184
|
-
- `
|
|
224
|
+
- `expiration_time`: An optional string timestamp (ISO 8601) when the session expires.
|
|
225
|
+
- `user_id`: An optional string with the ID of the user the session belongs to.
|
|
226
|
+
- `idle_expires_at`: An optional string timestamp (ISO 8601) indicating when the session will expire due to inactivity, if idle timeouts are configured.
|
|
227
|
+
- `claims`: An optional object with the session's claims, including:
|
|
185
228
|
- `subject`: The user ID or session identifier.
|
|
186
229
|
- `session_id`: The unique session identifier.
|
|
187
230
|
- `expiration`: A string timestamp (ISO 8601) when the session expires.
|
|
@@ -198,6 +241,9 @@ try {
|
|
|
198
241
|
// Example output:
|
|
199
242
|
// {
|
|
200
243
|
// is_valid: true,
|
|
244
|
+
// expiration_time: "2025-04-25T12:00:00Z",
|
|
245
|
+
// user_id: "123e4567-e89b-12d3-a456-426614174000",
|
|
246
|
+
// idle_expires_at: "2025-04-25T11:00:00Z",
|
|
201
247
|
// claims: {
|
|
202
248
|
// subject: "123e4567-e89b-12d3-a456-426614174000",
|
|
203
249
|
// session_id: "789abc",
|
|
@@ -243,6 +289,8 @@ try {
|
|
|
243
289
|
}
|
|
244
290
|
```
|
|
245
291
|
|
|
292
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
293
|
+
|
|
246
294
|
### Translation of outgoing emails
|
|
247
295
|
|
|
248
296
|
If you use the main `Hanko` client provided by the Frontend SDK, you can use the `lang` parameter in the options when
|
|
@@ -251,6 +299,8 @@ language to use for outgoing emails. If you have disabled email delivery through
|
|
|
251
299
|
`email.send` event, the value for the `lang` parameter is reflected in the JWT payload of the token contained in the
|
|
252
300
|
webhook request in the "Language" claim.
|
|
253
301
|
|
|
302
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
303
|
+
|
|
254
304
|
### Custom session claim type safety
|
|
255
305
|
|
|
256
306
|
The Hanko backend allows you to define custom claims that are added to issued session JWTs
|
|
@@ -297,6 +347,8 @@ async function session() {
|
|
|
297
347
|
};
|
|
298
348
|
```
|
|
299
349
|
|
|
350
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
351
|
+
|
|
300
352
|
## FlowAPI
|
|
301
353
|
|
|
302
354
|
The SDK offers a TypeScript-based interface for managing authentication and profile flows with Hanko, enabling the
|
|
@@ -304,6 +356,12 @@ development of custom frontends with the Hanko FlowAPI. It handles state transit
|
|
|
304
356
|
validation, and event dispatching, while also providing built-in support for auto-stepping and passkey autofill.
|
|
305
357
|
This guide explores its core functionality and usage patterns.
|
|
306
358
|
|
|
359
|
+
For the full reference of every action, input, and payload type available per flow and state, see the generated
|
|
360
|
+
[API reference](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/) — look under the **Flow Actions**,
|
|
361
|
+
**Flow Inputs**, **Flow Payloads**, **Flow Errors**, and **Flow Types** categories in the sidebar.
|
|
362
|
+
|
|
363
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
364
|
+
|
|
307
365
|
### Initializing a New Flow
|
|
308
366
|
|
|
309
367
|
Start a new authentication or profile flow using the `createState` method on a Hanko instance. Options allow you to control
|
|
@@ -328,6 +386,8 @@ const state = await hanko.createState("login", {
|
|
|
328
386
|
- **cacheKey**: `string` - The key used for localStorage caching (default: "hanko-flow-state").
|
|
329
387
|
|
|
330
388
|
|
|
389
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
390
|
+
|
|
331
391
|
### Understanding the State Object
|
|
332
392
|
|
|
333
393
|
The `state` object represents the current step in the flow. It contains properties and methods to interact with the flow.
|
|
@@ -348,6 +408,8 @@ The `state` object represents the current step in the flow. It contains properti
|
|
|
348
408
|
- **excludeAutoSteps**: `AutoStepExclusion` - An array of `StateNames` excluded from auto-stepping.
|
|
349
409
|
|
|
350
410
|
|
|
411
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
412
|
+
|
|
351
413
|
### Action Availability
|
|
352
414
|
|
|
353
415
|
Actions can be enabled or disabled based on the backend configuration or the user's state and properties. You can check
|
|
@@ -361,6 +423,8 @@ if (state.actions.example_action.enabled) {
|
|
|
361
423
|
}
|
|
362
424
|
```
|
|
363
425
|
|
|
426
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
427
|
+
|
|
364
428
|
### Accessing Action Inputs
|
|
365
429
|
|
|
366
430
|
Each action in `state.actions` has an `inputs` property defining expected input fields.
|
|
@@ -369,16 +433,20 @@ Each action in `state.actions` has an `inputs` property defining expected input
|
|
|
369
433
|
console.log(state.actions.continue_with_login_identifier.inputs);
|
|
370
434
|
// Example output:
|
|
371
435
|
// {
|
|
436
|
+
// identifier: { name: "identifier", type: "string", required: false },
|
|
437
|
+
// email: { name: "email", type: "string", required: false },
|
|
372
438
|
// username: {
|
|
373
|
-
//
|
|
439
|
+
// name: "username",
|
|
374
440
|
// type: "string",
|
|
375
|
-
//
|
|
376
|
-
//
|
|
377
|
-
//
|
|
441
|
+
// required: true,
|
|
442
|
+
// min_length: 3,
|
|
443
|
+
// max_length: 20
|
|
378
444
|
// }
|
|
379
445
|
// }
|
|
380
446
|
```
|
|
381
447
|
|
|
448
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
449
|
+
|
|
382
450
|
### Running an Action
|
|
383
451
|
|
|
384
452
|
Actions transition the flow to a new state. Use the `run` method on an action, passing input values and optional configuration.
|
|
@@ -401,6 +469,8 @@ if (state.name === "login_init") {
|
|
|
401
469
|
- **Events**: By default, `run` triggers `onBeforeStateChange` before the action and `onAfterStateChange` after the new state is loaded.
|
|
402
470
|
- **Validation Errors**: If the action fails due to invalid input (e.g., wrong format or length), `newState.error` will be set to "invalid_form_data", and specific errors will be attached to the related input fields (see "Error Handling" below).
|
|
403
471
|
|
|
472
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
473
|
+
|
|
404
474
|
### Event Handlers
|
|
405
475
|
|
|
406
476
|
The SDK dispatches events via the Hanko instance to track state changes.
|
|
@@ -441,6 +511,8 @@ hanko.onAfterStateChange(({ state }) => {
|
|
|
441
511
|
});
|
|
442
512
|
```
|
|
443
513
|
|
|
514
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
515
|
+
|
|
444
516
|
### Controlling the AfterStateChanged Event
|
|
445
517
|
|
|
446
518
|
You can disable the automatic `onAfterStateChange` event and dispatch it manually after custom logic.
|
|
@@ -458,6 +530,8 @@ if (state.name === "login_init") {
|
|
|
458
530
|
}
|
|
459
531
|
```
|
|
460
532
|
|
|
533
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
534
|
+
|
|
461
535
|
### Auto-Steps
|
|
462
536
|
|
|
463
537
|
Auto-steps automatically advance the flow for certain states, reducing manual intervention.
|
|
@@ -493,6 +567,8 @@ hanko.onAfterStateChange(({ state }) => {
|
|
|
493
567
|
});
|
|
494
568
|
```
|
|
495
569
|
|
|
570
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
571
|
+
|
|
496
572
|
### Error Handling
|
|
497
573
|
|
|
498
574
|
#### Input Errors
|
|
@@ -516,6 +592,8 @@ if (state.name === "error") {
|
|
|
516
592
|
}
|
|
517
593
|
```
|
|
518
594
|
|
|
595
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
596
|
+
|
|
519
597
|
### Caching Flow State
|
|
520
598
|
|
|
521
599
|
Persist and recover flow state using `localStorage`.
|
|
@@ -568,14 +646,22 @@ const recoveredState = await State.deserialize(hanko, serialized, {
|
|
|
568
646
|
This allows integration with other storage mechanisms.
|
|
569
647
|
|
|
570
648
|
|
|
649
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
650
|
+
|
|
571
651
|
## Bugs
|
|
572
652
|
|
|
573
653
|
Found a bug? Please report on our [GitHub](https://github.com/teamhanko/hanko/issues) page.
|
|
574
654
|
|
|
655
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
656
|
+
|
|
575
657
|
## Documentation
|
|
576
658
|
|
|
577
659
|
To see the latest documentation, please click [here](https://teamhanko.github.io/hanko/jsdoc/hanko-frontend-sdk/).
|
|
578
660
|
|
|
661
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
|
662
|
+
|
|
579
663
|
## License
|
|
580
664
|
|
|
581
665
|
The `hanko-frontend-sdk` project is licensed under the [MIT License](LICENSE).
|
|
666
|
+
|
|
667
|
+
[⬆ Back to top](#hanko-frontend-sdk)
|
package/dist/Hanko.d.ts
CHANGED
|
@@ -76,16 +76,6 @@ declare class Hanko extends Listener {
|
|
|
76
76
|
* @subcategory FlowAPI
|
|
77
77
|
*/
|
|
78
78
|
createState(flowName: FlowName, config?: StateCreateConfig): Promise<import("./lib/flow-api/types/flow").AnyState>;
|
|
79
|
-
/**
|
|
80
|
-
* Retrieves the current user's profile information.
|
|
81
|
-
*
|
|
82
|
-
* @public
|
|
83
|
-
* @deprecated
|
|
84
|
-
* @returns {Promise<User>} A promise that resolves to the user object
|
|
85
|
-
* @throws {UnauthorizedError} If the user is not authenticated
|
|
86
|
-
* @throws {TechnicalError} If an unexpected error occurs
|
|
87
|
-
*/
|
|
88
|
-
getUser(): Promise<User>;
|
|
89
79
|
/**
|
|
90
80
|
* Retrieves the current user's profile information.
|
|
91
81
|
*
|
package/dist/lib/Cookie.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import { CookieAttributes } from "js-cookie";
|
|
|
2
2
|
/**
|
|
3
3
|
* Options for Cookie
|
|
4
4
|
*
|
|
5
|
+
* @ignore
|
|
5
6
|
* @category SDK
|
|
6
7
|
* @subcategory Internal
|
|
7
8
|
* @property {string=} cookieName - The name of the session cookie set from the SDK. Defaults to "hanko".
|
|
@@ -17,6 +18,7 @@ export type CookieSameSite = "strict" | "Strict" | "lax" | "Lax" | "none" | "Non
|
|
|
17
18
|
/**
|
|
18
19
|
* A class to manage cookies.
|
|
19
20
|
*
|
|
21
|
+
* @ignore
|
|
20
22
|
* @category SDK
|
|
21
23
|
* @subcategory Internal
|
|
22
24
|
* @param {CookieOptions} options - The options that can be used
|
package/dist/lib/Dto.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ import { HttpClient, HttpClientOptions } from "./HttpClient";
|
|
|
4
4
|
*
|
|
5
5
|
* @abstract
|
|
6
6
|
* @category SDK
|
|
7
|
-
* @subcategory
|
|
7
|
+
* @subcategory Advanced
|
|
8
8
|
* @param {string} api - The URL of your Hanko API instance
|
|
9
9
|
* @param {HttpClientOptions} options - The options that can be used
|
|
10
10
|
*/
|
|
@@ -6,6 +6,7 @@ export type SessionTokenLocation = "cookie" | "sessionStorage";
|
|
|
6
6
|
/**
|
|
7
7
|
* This class wraps an XMLHttpRequest to maintain compatibility with the fetch API.
|
|
8
8
|
*
|
|
9
|
+
* @ignore
|
|
9
10
|
* @category SDK
|
|
10
11
|
* @subcategory Internal
|
|
11
12
|
* @param {XMLHttpRequest} xhr - The request to be wrapped.
|
|
@@ -25,6 +26,7 @@ declare class Headers {
|
|
|
25
26
|
/**
|
|
26
27
|
* This class wraps an XMLHttpRequest to maintain compatibility with the fetch API.
|
|
27
28
|
*
|
|
29
|
+
* @ignore
|
|
28
30
|
* @category SDK
|
|
29
31
|
* @subcategory Internal
|
|
30
32
|
* @param {XMLHttpRequest} xhr - The request to be wrapped.
|
|
@@ -57,6 +59,7 @@ declare class Response {
|
|
|
57
59
|
/**
|
|
58
60
|
* Options for the HttpClient
|
|
59
61
|
*
|
|
62
|
+
* @ignore
|
|
60
63
|
* @category SDK
|
|
61
64
|
* @subcategory Internal
|
|
62
65
|
* @property {number=} timeout - The http request timeout in milliseconds.
|
|
@@ -82,7 +85,7 @@ export interface HttpClientOptions {
|
|
|
82
85
|
* we can easily return to the fetch API.
|
|
83
86
|
*
|
|
84
87
|
* @category SDK
|
|
85
|
-
* @subcategory
|
|
88
|
+
* @subcategory Advanced
|
|
86
89
|
* @param {string} api - The URL of your Hanko API instance
|
|
87
90
|
* @param {HttpClientOptions} options - The options the HttpClient must be provided
|
|
88
91
|
*/
|
|
@@ -8,18 +8,6 @@ import { User } from "../flow-api/types/payload";
|
|
|
8
8
|
* @extends {Client}
|
|
9
9
|
*/
|
|
10
10
|
declare class UserClient extends Client {
|
|
11
|
-
/**
|
|
12
|
-
* Fetches the current user.
|
|
13
|
-
*
|
|
14
|
-
* @return {Promise<User>}
|
|
15
|
-
* @throws {UnauthorizedError}
|
|
16
|
-
* @throws {RequestTimeoutError}
|
|
17
|
-
* @throws {TechnicalError}
|
|
18
|
-
* @deprecated
|
|
19
|
-
* @see https://docs.hanko.io/api/public#tag/User-Management/operation/IsUserAuthorized
|
|
20
|
-
* @see https://docs.hanko.io/api/public#tag/User-Management/operation/listUser
|
|
21
|
-
*/
|
|
22
|
-
getCurrent(): Promise<User>;
|
|
23
11
|
/**
|
|
24
12
|
* Fetches the current user.
|
|
25
13
|
*
|
|
@@ -6,7 +6,7 @@ import { HankoOptions } from "../../Hanko";
|
|
|
6
6
|
* and uses broadcast channels for inter-tab communication.
|
|
7
7
|
*
|
|
8
8
|
* @category SDK
|
|
9
|
-
* @subcategory
|
|
9
|
+
* @subcategory Advanced
|
|
10
10
|
* @extends Dispatcher
|
|
11
11
|
* @param {string} api - The API endpoint URL.
|
|
12
12
|
* @param {HankoOptions} options - The internal configuration options of the SDK.
|
|
@@ -11,17 +11,13 @@ export interface State {
|
|
|
11
11
|
/**
|
|
12
12
|
* Manages session state persistence using localStorage.
|
|
13
13
|
*
|
|
14
|
+
* @param {string} storageKey - The key used to store session state in localStorage.
|
|
14
15
|
* @category SDK
|
|
15
16
|
* @subcategory Internal
|
|
16
17
|
*/
|
|
17
18
|
export declare class SessionState {
|
|
18
19
|
private readonly storageKey;
|
|
19
20
|
private readonly defaultState;
|
|
20
|
-
/**
|
|
21
|
-
* Creates an instance of SessionState.
|
|
22
|
-
*
|
|
23
|
-
* @param {string} storageKey - The key used to store session state in localStorage.
|
|
24
|
-
*/
|
|
25
21
|
constructor(storageKey: string);
|
|
26
22
|
/**
|
|
27
23
|
* Loads the current session state from localStorage.
|
|
@@ -6,16 +6,57 @@ import { Action as ActionType } from "./types/action";
|
|
|
6
6
|
import { AnyState, FlowName, FlowResponse } from "./types/flow";
|
|
7
7
|
import { autoSteps } from "./auto-steps";
|
|
8
8
|
import { passkeyAutofillActivationHandlers } from "./passkey-autofill-activation";
|
|
9
|
+
/**
|
|
10
|
+
* The names of states that support an automatic follow-up step (see {@link State#autoStep}).
|
|
11
|
+
* @category SDK
|
|
12
|
+
* @subcategory Flow Types
|
|
13
|
+
*/
|
|
9
14
|
export type AutoSteppedStates = keyof typeof autoSteps;
|
|
15
|
+
/**
|
|
16
|
+
* The names of states that support WebAuthn passkey autofill activation (see {@link State#passkeyAutofillActivation}).
|
|
17
|
+
* @category SDK
|
|
18
|
+
* @subcategory Flow Types
|
|
19
|
+
*/
|
|
10
20
|
export type PasskeyAutofillStates = keyof typeof passkeyAutofillActivationHandlers;
|
|
21
|
+
/**
|
|
22
|
+
* Controls which {@link AutoSteppedStates} should be skipped when initializing a {@link State}
|
|
23
|
+
* (`"all"` to skip every automatic step).
|
|
24
|
+
* @category SDK
|
|
25
|
+
* @subcategory Flow Types
|
|
26
|
+
*/
|
|
11
27
|
export type AutoStepExclusion = AutoSteppedStates[] | "all";
|
|
28
|
+
/**
|
|
29
|
+
* Maps every action available in a given {@link StateName} to an {@link Action} instance bound to
|
|
30
|
+
* that action's concrete input value types. This is the type of {@link State#actions}.
|
|
31
|
+
* @template TState - The state name to look up actions for.
|
|
32
|
+
* @category SDK
|
|
33
|
+
* @subcategory Flow Types
|
|
34
|
+
*/
|
|
12
35
|
export type ActionMap<TState extends StateName> = {
|
|
13
36
|
[K in keyof Actions[TState]]: Action<Actions[TState][K] extends ActionType<infer TInputs> ? TInputs : never>;
|
|
14
37
|
};
|
|
38
|
+
/**
|
|
39
|
+
* Identifies an action that was (or can be) run, and the state it is associated with.
|
|
40
|
+
* @category SDK
|
|
41
|
+
* @subcategory Flow Types
|
|
42
|
+
* @property {string} name - The name of the action.
|
|
43
|
+
* @property {StateName} relatedStateName - The name of the state the action belongs to.
|
|
44
|
+
*/
|
|
15
45
|
export type ActionInfo = {
|
|
16
46
|
name: string;
|
|
17
47
|
relatedStateName: StateName;
|
|
18
48
|
};
|
|
49
|
+
/**
|
|
50
|
+
* Configuration options accepted when constructing a new {@link State}.
|
|
51
|
+
* @interface
|
|
52
|
+
* @category SDK
|
|
53
|
+
* @subcategory Flow Types
|
|
54
|
+
* @property {boolean} [dispatchAfterStateChangeEvent] - Whether to dispatch a state-change event after this state is created.
|
|
55
|
+
* @property {AutoStepExclusion} [excludeAutoSteps] - States to exclude from automatic stepping.
|
|
56
|
+
* @property {ActionInfo} [previousAction] - The action that led to this state, if any.
|
|
57
|
+
* @property {boolean} [isCached] - Whether this state was loaded from cache rather than fetched from the backend.
|
|
58
|
+
* @property {string} [cacheKey] - The cache key associated with this state.
|
|
59
|
+
*/
|
|
19
60
|
export interface StateInitConfig {
|
|
20
61
|
dispatchAfterStateChangeEvent?: boolean;
|
|
21
62
|
excludeAutoSteps?: AutoStepExclusion;
|
|
@@ -23,9 +64,20 @@ export interface StateInitConfig {
|
|
|
23
64
|
isCached?: boolean;
|
|
24
65
|
cacheKey?: string;
|
|
25
66
|
}
|
|
67
|
+
/**
|
|
68
|
+
* Configuration options accepted when creating the initial {@link State} of a flow.
|
|
69
|
+
* @category SDK
|
|
70
|
+
* @subcategory Flow Types
|
|
71
|
+
* @property {boolean} [loadFromCache] - Whether to attempt loading a previously cached state instead of fetching a fresh one.
|
|
72
|
+
*/
|
|
26
73
|
export type StateCreateConfig = Pick<StateInitConfig, "dispatchAfterStateChangeEvent" | "excludeAutoSteps" | "cacheKey"> & {
|
|
27
74
|
loadFromCache?: boolean;
|
|
28
75
|
};
|
|
76
|
+
/**
|
|
77
|
+
* Configuration options accepted when running an {@link Action}.
|
|
78
|
+
* @category SDK
|
|
79
|
+
* @subcategory Flow Types
|
|
80
|
+
*/
|
|
29
81
|
export type ActionRunConfig = Pick<StateInitConfig, "dispatchAfterStateChangeEvent">;
|
|
30
82
|
type SerializedState = FlowResponse<any> & {
|
|
31
83
|
flow_name: FlowName;
|
|
@@ -62,13 +114,6 @@ export declare class State<TState extends StateName = StateName> {
|
|
|
62
114
|
readonly excludeAutoSteps: AutoStepExclusion;
|
|
63
115
|
readonly autoStep?: TState extends AutoSteppedStates ? () => Promise<AnyState> : never;
|
|
64
116
|
readonly passkeyAutofillActivation: TState extends PasskeyAutofillStates ? () => Promise<void> : never;
|
|
65
|
-
/**
|
|
66
|
-
* Constructs a new State instance.
|
|
67
|
-
* @param {Hanko} hanko - The Hanko instance for API interactions.
|
|
68
|
-
* @param {FlowName} flowName - The name of the flow this state belongs to.
|
|
69
|
-
* @param {FlowResponse<TState>} response - The flow response containing state data.
|
|
70
|
-
* @param {StateInitConfig} [options={}] - Configuration options for state initialization.
|
|
71
|
-
*/
|
|
72
117
|
constructor(hanko: Hanko, flowName: FlowName, response: FlowResponse<TState>, options?: StateInitConfig);
|
|
73
118
|
/**
|
|
74
119
|
* Builds the action map for this state, wrapping it in a Proxy to handle undefined actions.
|
|
@@ -171,12 +216,6 @@ export declare class Action<TInputs> {
|
|
|
171
216
|
readonly name: string;
|
|
172
217
|
readonly inputs: TInputs;
|
|
173
218
|
private readonly parentState;
|
|
174
|
-
/**
|
|
175
|
-
* Constructs a new Action instance.
|
|
176
|
-
* @param {ActionType<TInputs>} action - The action type definition.
|
|
177
|
-
* @param {State} parentState - The state this action belongs to.
|
|
178
|
-
* @param {boolean} [enabled=true] - Whether the action is enabled.
|
|
179
|
-
*/
|
|
180
219
|
constructor(action: ActionType<TInputs>, parentState: State, enabled?: boolean);
|
|
181
220
|
/**
|
|
182
221
|
* Creates a disabled action instance.
|