@strivacity/sdk-next 3.0.0-rc.0 → 3.0.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +226 -247
  3. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -1,3 +1,19 @@
1
+ # 3.0.0 (2026-04-09)
2
+
3
+ ### 🚀 Features
4
+
5
+ - ⚠️ EmbeddedFlow implemented ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
6
+ - ⚠️ NativeFlow entry function now returns an object instead of a string ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
7
+
8
+ ### ⚠️ Breaking Changes
9
+
10
+ - EmbeddedFlow implemented ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
11
+ - NativeFlow entry function now returns an object instead of a string ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
12
+
13
+ ### 🧱 Updated Dependencies
14
+
15
+ - Updated sdk-core to 3.0.0
16
+
1
17
  ## 3.0.0-rc.0 (2026-02-18)
2
18
 
3
19
  ### 🚀 Features
package/README.md CHANGED
@@ -1,10 +1,21 @@
1
1
  # @strivacity/sdk-next
2
2
 
3
- > **The SDK supports Next.js version 13 and above**
3
+ A Next.js library that integrates Strivacity's policy-driven authentication journeys into your application using the OAuth 2.0 PKCE flow. Supports `redirect`, `popup`, `native`, and `embedded` modes.
4
4
 
5
- ## Example App
5
+ See our [Developer Portal](https://www.strivacity.com/learn-support/developer-hub) to get started with developing with the Strivacity product.
6
+
7
+ ## Overview
8
+
9
+ This SDK allows you to integrate Strivacity's policy-driven journeys into your Next.js application. It wraps the `@strivacity/sdk-core` library as a React context provider and exposes a `useStrivacity` hook that provides authentication state and methods throughout your component tree. The SDK uses the OAuth 2.0 PKCE flow to authenticate with Strivacity. For detailed configuration options, available modes, and advanced usage refer to the [`@strivacity/sdk-core` documentation](https://github.com/Strivacity/sdk-js/blob/main/packages/sdk-core/README.md).
10
+
11
+ ## Demo Application
6
12
 
7
13
  - [Example app](https://github.com/Strivacity/sdk-js/tree/main/apps/next)
14
+ - [Headless example app](https://github.com/Strivacity/sdk-js/tree/main/apps/next-headless)
15
+
16
+ ## Requirements
17
+
18
+ - Next.js: 14+
8
19
 
9
20
  ## Install
10
21
 
@@ -14,47 +25,61 @@ npm install @strivacity/sdk-next
14
25
 
15
26
  ## Usage
16
27
 
17
- ### Wrap your app with `StyAuthProvider`
28
+ ### Initialization
18
29
 
19
- Add the `StyAuthProvider` to your `layout.tsx` file.
30
+ Wrap your application with `StyAuthProvider` in your root layout. Use the `'use client'` directive since the provider uses React context:
20
31
 
21
32
  ```tsx
33
+ // app/providers.tsx
22
34
  'use client';
23
35
 
24
36
  import { StyAuthProvider, type SDKOptions } from '@strivacity/sdk-next';
25
37
 
26
38
  const options: SDKOptions = {
27
- mode: 'redirect', // or 'popup' or 'native'
39
+ mode: 'redirect', // or 'popup', 'native', 'embedded'
28
40
  issuer: 'https://<YOUR_DOMAIN>',
29
41
  scopes: ['openid', 'profile'],
30
42
  clientId: '<YOUR_CLIENT_ID>',
31
43
  redirectUri: '<YOUR_REDIRECT_URI>',
32
44
  };
33
45
 
46
+ export function Providers({ children }: { children: React.ReactNode }) {
47
+ return <StyAuthProvider options={options}>{children}</StyAuthProvider>;
48
+ }
49
+ ```
50
+
51
+ ```tsx
52
+ // app/layout.tsx
53
+ import { Providers } from './providers';
54
+
34
55
  export default function RootLayout({ children }: { children: React.ReactNode }) {
35
56
  return (
36
- <html lang="en">
57
+ <html>
37
58
  <body>
38
- <StyAuthProvider options={options}>{children}</StyAuthProvider>
59
+ <Providers>{children}</Providers>
39
60
  </body>
40
61
  </html>
41
62
  );
42
63
  }
43
64
  ```
44
65
 
45
- ### How to use the SDK in your components:
66
+ Use the `useStrivacity` hook in any client component to access authentication state:
46
67
 
47
- #### Redirect or popup mode
68
+ ```tsx
69
+ 'use client';
48
70
 
49
- When using redirect or popup mode, the authentication flow involves two main components: a login page that initiates the authentication process, and a callback page that handles the response from the identity provider.
71
+ import { useStrivacity } from '@strivacity/sdk-next';
50
72
 
51
- In **redirect mode**, users are redirected to the identity provider's login page in the same browser window. After successful authentication, they are redirected back to your application's callback URL.
73
+ export default function MyComponent() {
74
+ const { loading, isAuthenticated, idTokenClaims } = useStrivacity();
75
+ }
76
+ ```
52
77
 
53
- In **popup mode**, the authentication happens in a popup window, allowing the main application to remain open while the user authenticates.
78
+ ### Redirect / Popup mode
54
79
 
55
- ##### Login page example
80
+ In `redirect` mode the user is taken to the identity provider in the same window; in `popup` mode authentication happens in a popup. Both are initiated the same way from code.
56
81
 
57
- The login page is where users start the authentication process. This component automatically triggers the login flow when the page loads, redirecting users to the identity provider for authentication.
82
+ #### Login page example
58
83
 
59
84
  ```tsx
60
85
  'use client';
@@ -77,9 +102,9 @@ export default function Login() {
77
102
  }
78
103
  ```
79
104
 
80
- ##### Callback page example
105
+ #### Callback page example
81
106
 
82
- The callback page handles the response from the identity provider after successful authentication. It processes the authentication result, extracts the tokens, and redirects users to their intended destination (typically a protected page like a profile or dashboard).
107
+ The callback page handles the response from the identity provider. It calls `handleCallback()` and redirects to `/profile` on success:
83
108
 
84
109
  ```tsx
85
110
  'use client';
@@ -111,16 +136,11 @@ export default function Callback() {
111
136
  }
112
137
  ```
113
138
 
114
- ##### Profile page example
115
-
116
- The profile page displays user information and authentication details after successful login. It uses the `useStrivacity` hook to access the authentication state and display relevant data such as access tokens, ID token claims, and expiration status.
117
-
118
- We check if the user is authenticated and display their profile information. If the user is not authenticated, we redirect them to the login page.
139
+ #### Profile page example
119
140
 
120
141
  ```tsx
121
142
  'use client';
122
143
 
123
- import Link from 'next/link';
124
144
  import { useStrivacity } from '@strivacity/sdk-next';
125
145
 
126
146
  export default function Profile() {
@@ -130,10 +150,6 @@ export default function Profile() {
130
150
  return <h1>Loading...</h1>;
131
151
  }
132
152
 
133
- if (!isAuthenticated) {
134
- return <Link href="/login" replace />;
135
- }
136
-
137
153
  return (
138
154
  <section>
139
155
  <dl>
@@ -173,11 +189,9 @@ export default function Profile() {
173
189
  }
174
190
  ```
175
191
 
176
- ##### Logout page example
177
-
178
- The logout page handles user logout by terminating their session. The `postLogoutRedirectUri` parameter is optional and specifies where users should be redirected after logout. If not provided, users will be redirected to the identity provider's logout page.
192
+ #### Logout page example
179
193
 
180
- This URI must be configured in the Admin Console as an allowed post-logout redirect URI for your application.
194
+ The `postLogoutRedirectUri` parameter is optional and specifies where users are redirected after logout. This URI must be configured in the Admin Console as an allowed post-logout redirect URI.
181
195
 
182
196
  ```tsx
183
197
  'use client';
@@ -208,15 +222,36 @@ export default function Logout() {
208
222
  }
209
223
  ```
210
224
 
211
- #### Native mode
225
+ #### Component example
212
226
 
213
- If you are using `native` mode, you can use the `StyLoginRenderer` component to render the login UI.
227
+ ```tsx
228
+ 'use client';
214
229
 
215
- To customize the UI components used in the authentication flows, define the `widgets` object in your component.
230
+ import { useStrivacity } from '@strivacity/sdk-next';
216
231
 
217
- ###### Example widgets
232
+ export default function Nav() {
233
+ const { isAuthenticated, idTokenClaims, login, logout } = useStrivacity();
234
+ const name = `${idTokenClaims?.given_name} ${idTokenClaims?.family_name}`;
235
+
236
+ return isAuthenticated ? (
237
+ <div>
238
+ <div>Welcome, {name}!</div>
239
+ <button onClick={() => logout()}>Logout</button>
240
+ </div>
241
+ ) : (
242
+ <div>
243
+ <div>Not logged in</div>
244
+ <button onClick={() => login()}>Log in</button>
245
+ </div>
246
+ );
247
+ }
248
+ ```
249
+
250
+ ### Native mode
251
+
252
+ In `native` mode the `StyLoginRenderer` component renders the authentication UI inline using your custom widget components. You can define custom components for each input type; see [Example widgets](https://github.com/Strivacity/sdk-js/tree/main/apps/next/src/components/widgets).
218
253
 
219
- The example widgets use SCSS for styling and Luxon for date handling. You'll need to install these dependencies:
254
+ The example widgets use SCSS for styling and Luxon for date handling:
220
255
 
221
256
  ```bash
222
257
  npm install sass luxon
@@ -253,112 +288,73 @@ export const widgets = {
253
288
  };
254
289
  ```
255
290
 
256
- You can find example widgets here: [Example widgets](https://github.com/Strivacity/sdk-js/tree/main/apps/next/src/components/widgets)
291
+ #### Login page example
257
292
 
258
- ##### Login page example
259
-
260
- The native mode login page provides a fully customizable authentication experience rendered directly within your application. Unlike redirect or popup modes, native mode keeps users on your site throughout the entire authentication process using the `StyLoginRenderer` component.
261
-
262
- This example demonstrates how to handle session management, implement callback functions for various authentication events, and manage URL parameters for session continuity.
293
+ The login page extracts `session_id` from the URL on load, cleans up the URL, and passes it to the renderer. When a `session_id` is present the renderer calls `startSession(sessionId)` to resume the existing flow instead of starting a new one.
263
294
 
264
295
  ```tsx
265
296
  'use client';
266
297
 
267
- import { Suspense, useEffect, useState } from 'react';
298
+ import { useEffect, useState } from 'react';
268
299
  import { useRouter } from 'next/navigation';
269
- import { useStrivacity, StyLoginRenderer, FallbackError, type LoginFlowState } from '@strivacity/sdk-next';
300
+ import { StyLoginRenderer, FallbackError, type LoginFlowState } from '@strivacity/sdk-next';
270
301
  import { widgets } from '@/components/widgets';
271
302
 
272
303
  export default function Login() {
273
304
  const router = useRouter();
274
- const { options, login } = useStrivacity();
275
305
  const [sessionId, setSessionId] = useState<string | null>(null);
276
306
 
277
- /**
278
- * Extract session_id from URL parameters and clean up the URL
279
- * This is necessary for maintaining session state across external login providers
280
- */
281
307
  useEffect(() => {
282
308
  if (window.location.search !== '') {
283
309
  const url = new URL(window.location.href);
284
- const sid = url.searchParams.get('session_id');
285
- setSessionId(sid);
310
+ setSessionId(url.searchParams.get('session_id'));
286
311
  url.search = '';
287
312
  window.history.replaceState({}, '', url.toString());
288
313
  }
289
314
  }, []);
290
315
 
291
- /**
292
- * Called when authentication is successful
293
- * Redirects user to the profile page
294
- */
295
- const onLogin = () => {
316
+ const onLogin = async () => {
296
317
  router.push('/profile');
297
318
  };
298
319
 
299
- /**
300
- * Called when native flow cannot handle the authentication
301
- * Falls back to redirect mode by navigating to the provided URL
302
- * @param error - FallbackError containing the fallback URL and message
303
- */
304
320
  const onFallback = (error: FallbackError) => {
305
321
  if (error.url) {
306
- console.log(`Fallback: ${error.url}`);
307
322
  window.location.href = error.url.toString();
308
323
  } else {
309
- console.error(`FallbackError without URL: ${error.message}`);
310
324
  alert(error);
311
325
  }
312
326
  };
313
327
 
314
- /**
315
- * Called when an error occurs during the authentication process
316
- * @param error - Error message describing what went wrong
317
- */
318
328
  const onError = (error: string) => {
319
- console.error(`Error: ${error}`);
320
329
  alert(error);
321
330
  };
322
331
 
323
- /**
324
- * Called when the authentication flow wants to display a global message
325
- * @param message - Message to display to the user
326
- */
327
332
  const onGlobalMessage = (message: string) => {
328
333
  alert(message);
329
334
  };
330
335
 
331
- /**
332
- * Called when the authentication flow transitions between states
333
- * Useful for tracking flow progress and inject custom logic such as logging or analytics
334
- * @param params - Object containing previous and current flow states
335
- */
336
336
  const onBlockReady = ({ previousState, state }: { previousState: LoginFlowState; state: LoginFlowState }) => {
337
337
  console.log('previousState', previousState);
338
338
  console.log('state', state);
339
339
  };
340
340
 
341
341
  return (
342
- <Suspense fallback={<span>Loading...</span>}>
343
- <StyLoginRenderer
344
- widgets={widgets}
345
- sessionId={sessionId}
346
- onFallback={onFallback}
347
- onLogin={() => void onLogin()}
348
- onError={onError}
349
- onGlobalMessage={onGlobalMessage}
350
- onBlockReady={onBlockReady}
351
- />
352
- </Suspense>
342
+ <StyLoginRenderer
343
+ widgets={widgets}
344
+ sessionId={sessionId}
345
+ onFallback={onFallback}
346
+ onLogin={() => void onLogin()}
347
+ onError={onError}
348
+ onGlobalMessage={onGlobalMessage}
349
+ onBlockReady={onBlockReady}
350
+ />
353
351
  );
354
352
  }
355
353
  ```
356
354
 
357
- ##### Callback page example
358
-
359
- The native mode callback page handles authentication responses when external identity providers redirect back to your application. This page checks for session IDs in the URL parameters and either continues the native flow or falls back to standard callback handling.
355
+ #### Callback page example
360
356
 
361
- This component is essential for handling social login providers (like Google, Facebook, etc.) that require redirect-based authentication even within native mode flows.
357
+ When a `session_id` is present in the URL the native flow is resumed by forwarding it to the login page. Otherwise the standard `handleCallback()` path is used:
362
358
 
363
359
  ```tsx
364
360
  'use client';
@@ -368,7 +364,6 @@ import { useRouter } from 'next/navigation';
368
364
  import { useStrivacity } from '@strivacity/sdk-next';
369
365
 
370
366
  export default function Callback() {
371
- const query = globalThis?.window ? Object.fromEntries(new URLSearchParams(globalThis.window.location.search)) : {};
372
367
  const router = useRouter();
373
368
  const { handleCallback } = useStrivacity();
374
369
 
@@ -390,46 +385,104 @@ export default function Callback() {
390
385
  })();
391
386
  }, []);
392
387
 
393
- if (query.error) {
394
- return (
395
- <section>
396
- <h1>Error in authentication</h1>
397
- <div>
398
- <h4>{query.error}</h4>
399
- <p>{query.error_description}</p>
400
- </div>
401
- </section>
402
- );
403
- } else {
404
- return (
405
- <section>
406
- <h1>Logging in...</h1>
407
- </section>
408
- );
409
- }
388
+ return (
389
+ <section>
390
+ <h1>Logging in...</h1>
391
+ </section>
392
+ );
410
393
  }
411
394
  ```
412
395
 
413
- ##### Profile page example
396
+ #### Entry page example
397
+
398
+ The entry page processes flows started by an external process (e.g. password reset) by calling `entry()` to extract the necessary parameters to resume the flow and forwarding them to the callback page:
399
+
400
+ ```tsx
401
+ 'use client';
402
+
403
+ import { useEffect } from 'react';
404
+ import { useRouter } from 'next/navigation';
405
+ import { useStrivacity } from '@strivacity/sdk-next';
406
+
407
+ export default function Entry() {
408
+ const router = useRouter();
409
+ const { entry } = useStrivacity();
410
+
411
+ useEffect(() => {
412
+ (async () => {
413
+ try {
414
+ const data = await entry();
415
+
416
+ if (data && Object.keys(data).length > 0) {
417
+ router.push(`/callback?${new URLSearchParams(data).toString()}`);
418
+ } else {
419
+ router.push('/');
420
+ }
421
+ } catch (error) {
422
+ console.error('Entry failed:', error);
423
+ router.push('/');
424
+ }
425
+ })();
426
+ }, []);
427
+
428
+ return (
429
+ <section>
430
+ <h1>Loading...</h1>
431
+ </section>
432
+ );
433
+ }
434
+ ```
435
+
436
+ #### Profile page example
414
437
 
415
438
  Same as the profile page example in redirect/popup mode.
416
439
 
417
- ##### Logout page example
440
+ #### Logout page example
418
441
 
419
442
  Same as the logout page example in redirect/popup mode.
420
443
 
444
+ ### Embedded mode
445
+
446
+ In `embedded` mode the `<sty-login>` web component (loaded via `bundle.js` from the cluster) handles rendering. Import the bundle at application startup to register the Strivacity web components:
447
+
448
+ ```tsx
449
+ // app/providers.tsx
450
+ 'use client';
451
+
452
+ import { useEffect } from 'react';
453
+ import { StyAuthProvider } from '@strivacity/sdk-next';
454
+
455
+ export function Providers({ children }: { children: React.ReactNode }) {
456
+ useEffect(() => {
457
+ void import(`${process.env.NEXT_PUBLIC_ISSUER}/assets/components/bundle.js`);
458
+ }, []);
459
+
460
+ return (
461
+ <StyAuthProvider
462
+ options={{
463
+ mode: 'embedded',
464
+ issuer: 'https://<YOUR_DOMAIN>',
465
+ scopes: ['openid', 'profile'],
466
+ clientId: '<YOUR_CLIENT_ID>',
467
+ redirectUri: '<YOUR_REDIRECT_URI>',
468
+ }}
469
+ >
470
+ {children}
471
+ </StyAuthProvider>
472
+ );
473
+ }
474
+ ```
475
+
421
476
  ## Logging
422
477
 
423
478
  The SDK supports optional logging to help you debug authentication flows and monitor SDK behavior. You can enable the built-in console logger or provide your own custom logger implementation.
424
479
 
425
480
  ### Using the Default Logger
426
481
 
427
- Enable the default console logger by adding the `logging` option when creating the SDK:
482
+ Enable the default console logger by adding the `logging` option:
428
483
 
429
484
  ```tsx
430
- 'use client';
431
-
432
- import { StyAuthProvider, type SDKOptions, DefaultLogging } from '@strivacity/sdk-next';
485
+ import { StyAuthProvider, DefaultLogging, type SDKOptions } from '@strivacity/sdk-next';
433
486
 
434
487
  const options: SDKOptions = {
435
488
  mode: 'redirect',
@@ -437,25 +490,13 @@ const options: SDKOptions = {
437
490
  scopes: ['openid', 'profile'],
438
491
  clientId: '<YOUR_CLIENT_ID>',
439
492
  redirectUri: '<YOUR_REDIRECT_URI>',
440
- logging: DefaultLogging, // Enable built-in console logging
493
+ logging: DefaultLogging,
441
494
  };
442
-
443
- export default function RootLayout({ children }: { children: React.ReactNode }) {
444
- return (
445
- <html lang="en">
446
- <body>
447
- <StyAuthProvider options={options}>{children}</StyAuthProvider>
448
- </body>
449
- </html>
450
- );
451
- }
452
495
  ```
453
496
 
454
- The default logger writes to the browser console and automatically prefixes messages with a correlation ID when available (via the `xEventId` property).
455
-
456
497
  ### Creating a Custom Logger
457
498
 
458
- You can provide your own logger by implementing the `SDKLogging` interface with four methods: `debug`, `info`, `warn`, and `error`. An optional `xEventId` property is honored for log correlation.
499
+ Implement the `SDKLogging` interface and pass your class to the `logging` option:
459
500
 
460
501
  ```typescript
461
502
  import type { SDKLogging } from '@strivacity/sdk-next';
@@ -464,7 +505,6 @@ export class MyLogger implements SDKLogging {
464
505
  xEventId?: string;
465
506
 
466
507
  debug(message: string): void {
467
- // Send to your logging pipeline
468
508
  console.debug(this.xEventId ? `[${this.xEventId}] ${message}` : message);
469
509
  }
470
510
 
@@ -482,161 +522,100 @@ export class MyLogger implements SDKLogging {
482
522
  }
483
523
  ```
484
524
 
485
- Then register your custom logger when creating the SDK:
486
-
487
- ```tsx
488
- import { StyAuthProvider } from '@strivacity/sdk-next';
489
- import { MyLogger } from './logging/MyLogger';
490
-
491
- const options: SDKOptions = {
492
- mode: 'redirect',
493
- issuer: 'https://<YOUR_DOMAIN>',
494
- scopes: ['openid', 'profile'],
495
- clientId: '<YOUR_CLIENT_ID>',
496
- redirectUri: '<YOUR_REDIRECT_URI>',
497
- logging: MyLogger, // Use your custom logger
498
- };
499
- ```
500
-
501
- ### Logger Interface
525
+ The `SDKLogging` interface requires `debug`, `info`, `warn`, and `error` methods. The optional `xEventId` property, when set by the SDK, provides a correlation ID to trace related log messages across the authentication flow.
502
526
 
503
- The `SDKLogging` interface requires the following methods:
527
+ ## API Documentation
504
528
 
505
- - **`debug(message: string): void`** - Log debug-level messages
506
- - **`info(message: string): void`** - Log informational messages
507
- - **`warn(message: string): void`** - Log warning messages
508
- - **`error(message: string, error: Error): void`** - Log error messages with error objects
509
-
510
- The optional `xEventId` property, when set by the SDK, provides a correlation ID to trace related log messages across the authentication flow.
511
-
512
- ### API Documentation
513
-
514
- #### `useStrivacity` hook
529
+ ### `useStrivacity` hook
515
530
 
516
531
  ```typescript
517
532
  useStrivacity<T extends PopupContext | RedirectContext | NativeContext>(): T;
518
533
  ```
519
534
 
520
- You can choose between `PopupContext`, `RedirectContext`, or `NativeContext` with the `mode` option when you configure the sdk options.
535
+ The hook returns a different context type depending on the `mode` configured in `StyAuthProvider`.
521
536
 
522
- **Properties**
537
+ **Shared properties (all modes)**
523
538
 
524
- - **`loading: boolean`**: Indicates if the session is being loaded.
525
- - **`isAuthenticated: boolean`**: Indicates whether the user is authenticated.
526
- - **`idTokenClaims: IdTokenClaims | null`**: Claims from the ID token or null if not available.
527
- - **`accessToken: string | null`**: The access token or null if not available.
528
- - **`refreshToken: string | null`**: The refresh token or null if not available.
529
- - **`accessTokenExpired: boolean`**: Indicates if the access token has expired.
530
- - **`accessTokenExpirationDate: number | null`**: Expiration date of the access token or null if not set.
539
+ - **`sdk: RedirectFlow | PopupFlow | NativeFlow`**: The underlying SDK flow instance.
540
+ - **`loading: boolean`**: `true` while the session is being initialized.
541
+ - **`options: SDKOptions`**: The configured SDK options.
542
+ - **`isAuthenticated: boolean`**: `true` when the user has a valid session.
543
+ - **`idTokenClaims: IdTokenClaims | null`**: Claims from the ID token, or `null` if not authenticated.
544
+ - **`accessToken: string | null`**: The current access token.
545
+ - **`refreshToken: string | null`**: The current refresh token.
546
+ - **`accessTokenExpired: boolean`**: `true` when the access token has expired.
547
+ - **`accessTokenExpirationDate: number | null`**: Expiration timestamp (Unix seconds) of the access token.
531
548
 
532
549
  ---
533
550
 
534
- Type: `RedirectContext`
535
- Represents the available methods for Redirect-based interactions.
551
+ **Type: `RedirectContext`**
536
552
 
537
- - **`login(options?: LoginOptions): Promise<void>`**: Initiates the login process by redirecting the user to the identity provider.
538
- - `options` (optional): Configuration options for login.
539
- - **`register(options?: RegisterOptions): Promise<void>`**: Registers a new user using a redirect flow.
540
- - `options` (optional): Configuration options for registration.
541
- - **`refresh(): Promise<void>`**: Refreshes the user's session using a redirect flow.
542
- - **`revoke(): Promise<void>`**: Revokes the current session tokens using a redirect flow.
543
- - **`logout(options?: LogoutOptions): Promise<void>`**: Logs out the user by redirecting to the identity provider.
544
- - `options` (optional): Configuration options for logout.
545
- - **`handleCallback(url?: string): Promise<void>`**: Handles the callback after a redirect-based authentication or token exchange.
546
- - `url` (optional): The URL to handle for the callback.
553
+ - **`login(options?: LoginOptions): Promise<void>`**: Initiates login by redirecting to the identity provider.
554
+ - **`register(options?: RegisterOptions): Promise<void>`**: Initiates registration using a redirect flow.
555
+ - **`refresh(): Promise<void>`**: Refreshes the user's session.
556
+ - **`revoke(): Promise<void>`**: Revokes the current session tokens.
557
+ - **`logout(options?: LogoutOptions): Promise<void>`**: Logs the user out via redirect.
558
+ - **`handleCallback(url?: string): Promise<void>`**: Processes the authorization callback after redirect.
559
+ - **`entry(): Promise<Record<string, string>>`**: Processes an externally-initiated flow URL and returns the parameters needed to resume the flow.
547
560
 
548
561
  ---
549
562
 
550
- Type: `PopupContext`
551
- Represents the available methods for Popup-based interactions.
563
+ **Type: `PopupContext`**
552
564
 
553
- - **`login(options?: LoginOptions): Promise<void>`**: Initiates the login process using a popup window.
554
- - `options` (optional): Configuration options for login.
555
- - **`register(options?: RegisterOptions): Promise<void>`**: Registers a new user using a popup flow.
556
- - `options` (optional): Configuration options for registration.
557
- - **`refresh(): Promise<void>`**: Refreshes the user's session using a popup.
558
- - **`revoke(): Promise<void>`**: Revokes the current session tokens using a popup flow.
559
- - **`logout(options?: LogoutOptions): Promise<void>`**: Logs out the user using a popup window.
560
- - `options` (optional): Configuration options for logout.
561
- - **`handleCallback(url?: string): Promise<void>`**: Handles the callback after a popup-based authentication or token exchange.
562
- - `url` (optional): The URL to handle for the callback.
565
+ - **`login(options?: LoginOptions): Promise<void>`**: Initiates login using a popup window.
566
+ - **`register(options?: RegisterOptions): Promise<void>`**: Initiates registration using a popup.
567
+ - **`refresh(): Promise<void>`**: Refreshes the user's session.
568
+ - **`revoke(): Promise<void>`**: Revokes the current session tokens.
569
+ - **`logout(options?: LogoutOptions): Promise<void>`**: Logs the user out via popup.
570
+ - **`handleCallback(url?: string): Promise<void>`**: Processes the authorization callback.
571
+ - **`entry(): Promise<Record<string, string>>`**: Processes an externally-initiated flow URL.
563
572
 
564
573
  ---
565
574
 
566
- Type: `NativeContext`
567
- Represents the available methods for native-based interactions.
575
+ **Type: `NativeContext`**
568
576
 
569
- - **`login(options?: LoginOptions): Promise<NativeFlowHandler>`**: Initiates the login process using a native flow.
570
- - `options` (optional): Configuration options for login.
571
- - **`register(options?: RegisterOptions): Promise<NativeFlowHandler>`**: Registers a new user using a native flow.
572
- - `options` (optional): Configuration options for registration.
577
+ - **`login(options?: LoginOptions): Promise<NativeFlowHandler>`**: Initiates login using the native flow.
578
+ - **`register(options?: RegisterOptions): Promise<NativeFlowHandler>`**: Initiates registration using the native flow.
573
579
  - **`refresh(): Promise<void>`**: Refreshes the user's session.
574
580
  - **`revoke(): Promise<void>`**: Revokes the current session tokens.
575
- - **`logout(options?: LogoutOptions): Promise<void>`**: Logs out the user by redirecting to the logout page.
576
- - `options` (optional): Configuration options for logout.
577
- - **`handleCallback(url?: string): Promise<void>`**: Handles the callback after a redirect-based authentication. This will be called automatically by the native flow handler during fallback.
578
- - `url` (optional): The URL to handle for the callback.
579
-
580
- #### `StyLoginRenderer` component
581
+ - **`logout(options?: LogoutOptions): Promise<void>`**: Logs the user out via redirect.
582
+ - **`handleCallback(url?: string): Promise<void>`**: Processes the authorization callback.
583
+ - **`entry(): Promise<Record<string, string>>`**: Processes an externally-initiated flow URL.
581
584
 
582
- The `StyLoginRenderer` component is used in native mode to render the authentication UI directly within your application. It provides a fully customizable login experience using your own UI components.
583
-
584
- ```typescript
585
- StyLoginRenderer: React.FC<{
586
- params?: NativeParams;
587
- widgets?: PartialRecord<WidgetType, React.ComponentType<any>>;
588
- sessionId?: string | null;
589
- onLogin?: (claims?: IdTokenClaims | null) => void;
590
- onFallback?: (error: FallbackError) => void;
591
- onError?: (error: any) => void;
592
- onGlobalMessage?: (message: string) => void;
593
- onBlockReady?: ({ previousState, state }: { previousState: LoginFlowState; state: LoginFlowState }) => void;
594
- }>;
595
- ```
596
-
597
- **Properties**
598
-
599
- - **`params?: NativeParams`** (optional): Additional parameters to pass to the native login flow. These parameters can include custom configuration options for the authentication process.
600
-
601
- - **`widgets?: PartialRecord<WidgetType, React.ComponentType<any>>`** (optional): A collection of React components that define the UI widgets used in the authentication flow. Each widget type (input, button, layout, etc.) can be customized with your own components.
585
+ ---
602
586
 
603
- - **`sessionId?: string | null`** (optional): The session ID for continuing an existing authentication session. This is typically extracted from URL parameters when returning from external identity providers.
587
+ ### `StyLoginRenderer` component
604
588
 
605
- - **`onLogin?: (claims?: IdTokenClaims | null) => void`** (optional): Callback function called when authentication is successful. Receives the ID token claims as a parameter.
589
+ Used in `native` mode to render the authentication UI with your own widget components.
606
590
 
607
- - **`onFallback?: (error: FallbackError) => void`** (optional): Callback function called when the native flow cannot handle the authentication and needs to fall back to redirect mode. The error parameter contains the fallback URL.
591
+ **Props**
608
592
 
609
- - **`onError?: (error: any) => void`** (optional): Callback function called when an error occurs during the authentication process. Use this to handle and display error messages to users.
593
+ - **`params?: NativeParams`**: Additional parameters for the native login flow.
594
+ - **`widgets?: PartialRecord<WidgetType, React.ComponentType>`**: Custom React components for each widget type used in the flow.
595
+ - **`sessionId?: string | null`**: Session ID for resuming an existing authentication session.
610
596
 
611
- - **`onGlobalMessage?: (message: string) => void`** (optional): Callback function called when the authentication flow wants to display a global message to the user (e.g., account lockout warnings, validation messages).
597
+ **Event callbacks**
612
598
 
613
- - **`onBlockReady?: ({ previousState, state }: { previousState: LoginFlowState; state: LoginFlowState }) => void`** (optional): Callback function called when the authentication flow transitions between states. Useful for tracking progress, implementing custom logging, or injecting analytics. Receives both the previous and current flow states.
599
+ - **`onLogin`**: Called on successful authentication. Receives `IdTokenClaims | null`.
600
+ - **`onFallback`**: Called when the native flow needs to fall back to redirect. Receives `FallbackError` with a fallback URL.
601
+ - **`onError`**: Called when an error occurs during authentication.
602
+ - **`onGlobalMessage`**: Called when the flow wants to display a global message (e.g. account lockout warning).
603
+ - **`onBlockReady`**: Called on flow state transitions. Receives `{ previousState: LoginFlowState; state: LoginFlowState }`. Useful for analytics and custom logging.
614
604
 
615
- **Widget Types**
605
+ ## Vulnerability Reporting
616
606
 
617
- The `widgets` prop accepts the following widget types:
607
+ The [Guidelines for responsible disclosure](https://www.strivacity.com/report-a-security-issue) details the procedure for disclosing security issues. Please do not report security vulnerabilities on the public issue tracker.
618
608
 
619
- - `checkbox`: For checkbox input fields
620
- - `date`: For date input fields
621
- - `input`: For text input fields
622
- - `layout`: For layout containers and form structure
623
- - `loading`: For loading indicators
624
- - `multiSelect`: For multi-select dropdown fields
625
- - `passcode`: For passcode input fields
626
- - `password`: For password input fields
627
- - `phone`: For phone number input fields
628
- - `select`: For single-select dropdown fields
629
- - `static`: For static text and display elements
630
- - `submit`: For form submission buttons
609
+ ## License
631
610
 
632
- Each widget component receives props specific to its type and function within the authentication flow.
611
+ @strivacity/sdk-next is available under the MIT License. See the [LICENSE](https://github.com/Strivacity/sdk-js/blob/main/LICENSE) file for more info.
633
612
 
634
- ### Links
613
+ ## Contributing
635
614
 
636
- [Example app](https://github.com/Strivacity/sdk-js/tree/main/apps/next)
615
+ Please see our [contributing guide](https://github.com/Strivacity/sdk-js/blob/main/CONTRIBUTING.md).
637
616
 
638
617
  ## Migrating to v3.0
639
618
 
640
619
  ### Entry API Major Changes
641
620
 
642
- Strivacity SDK's `entry()` API now returns a structured object instead of a plain string. To see examples of these changes, check the apps folder in this repository.
621
+ Strivacity SDK's `entry()` API now returns a structured object instead of a plain string. Check the example above in the usage section for more details.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@strivacity/sdk-next",
3
- "version": "3.0.0-rc.0",
3
+ "version": "3.0.0",
4
4
  "license": "MIT",
5
5
  "description": "Strivacity Next.js SDK client",
6
6
  "author": "strivacity <opensource@strivacity.com>",
@@ -9,7 +9,7 @@
9
9
  "url": "https://github.com/Strivacity/sdk-js"
10
10
  },
11
11
  "dependencies": {
12
- "@strivacity/sdk-core": "3.0.0-rc.0"
12
+ "@strivacity/sdk-core": "3.0.0"
13
13
  },
14
14
  "peerDependencies": {
15
15
  "next": ">=13"