@strivacity/sdk-core 2.3.0 → 3.0.0

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+# 3.0.0 (2026-04-09)
+
+### 🚀 Features
+
+- custom sdk mode added ([17812c6](https://github.com/Strivacity/sdk-js/commit/17812c6))
+- ⚠️  EmbeddedFlow implemented ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
+- ⚠️  NativeFlow entry function now returns an object instead of a string ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
+- popupUrlHandler refactored ([886f6ea](https://github.com/Strivacity/sdk-js/commit/886f6ea))
+
+### 🩹 Fixes
+
+- select and multiselect default value handling fixed ([25ecacd](https://github.com/Strivacity/sdk-js/commit/25ecacd))
+- widget type definitions fixed ([c2e9b12](https://github.com/Strivacity/sdk-js/commit/c2e9b12))
+
+### ⚠️  Breaking Changes
+
+- EmbeddedFlow implemented  ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
+- NativeFlow entry function now returns an object instead of a string  ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
+
+### 🧱 Updated Dependencies
+
+- Updated testing to 3.0.0
+
+## 3.0.0-rc.0 (2026-02-18)
+
+### 🚀 Features
+
+- ⚠️  EmbeddedFlow implemented ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
+- ⚠️  NativeFlow entry function now returns an object instead of a string ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
+- popupUrlHandler refactored ([886f6ea](https://github.com/Strivacity/sdk-js/commit/886f6ea))
+
+### ⚠️  Breaking Changes
+
+- EmbeddedFlow implemented  ([a0e3ad8](https://github.com/Strivacity/sdk-js/commit/a0e3ad8))
+- NativeFlow entry function now returns an object instead of a string  ([9a8942d](https://github.com/Strivacity/sdk-js/commit/9a8942d))
+
+### 🧱 Updated Dependencies
+
+- Updated testing to 3.0.0-rc.0
+
 ## 2.3.0 (2026-02-10)
 
 ### 🚀 Features

package/README.md

@@ -1,67 +1,90 @@
 # @strivacity/sdk-core
 
-## Example App
+A framework-agnostic JavaScript/TypeScript client that integrates Strivacity's policy-driven authentication journeys into any application using the OAuth 2.0 PKCE flow. Supports `redirect`, `popup`, `native`, and `embedded` modes.
+
+See our [Developer Portal](https://www.strivacity.com/learn-support/developer-hub) to get started with developing with the Strivacity product.
+
+## Overview
+
+This SDK provides the core authentication primitives for Strivacity's policy-driven journeys. It is a standalone JavaScript/TypeScript library with no framework dependencies that can be used directly or as the foundation for framework-specific SDKs (React, Vue, Angular, etc.). The SDK uses the OAuth 2.0 PKCE flow to authenticate with Strivacity.
+
+## Demo Application
 
 - [Example app](https://github.com/Strivacity/sdk-js/tree/main/apps/web-component)
 
-### Install
+## Install
 
 ```bash
 npm install @strivacity/sdk-core
 ```
 
-### Usage
+## Usage
+
+### Initialization
+
+Create a flow instance using the `initFlow` factory function:
 
 ```js
 import { initFlow } from '@strivacity/sdk-core';
 
 const sdk = initFlow({
-	mode: 'redirect', // or 'popup' or 'native'
+	mode: 'redirect', // or 'popup', 'native', 'embedded'
 	issuer: 'https://<YOUR_DOMAIN>',
 	scopes: ['openid', 'profile'],
 	clientId: '<YOUR_CLIENT_ID>',
 	redirectUri: '<YOUR_REDIRECT_URI>',
 });
+```
+
+### Redirect / Popup mode
 
+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.
+
+#### Login
+
+```js
 await sdk.login();
 ```
 
-### API Documentation
+#### Callback handling
 
-#### `initFlow(options: SDKOptions & { mode?: 'popup' | 'redirect' | 'native' }): PopupFlow | RedirectFlow | NativeFlow`
+Process the authorization callback after the identity provider redirects back to your application:
 
-The `initFlow` function initializes and returns an instance of either `PopupFlow`, `RedirectFlow`, or `NativeFlow`, based on the specified `mode`.
+```js
+await sdk.handleCallback();
+```
 
-**Parameters:**
+#### Logout
 
-- `options`: An object containing configuration options for the SDK.
+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.
 
-  **Type:** `SDKOptions & { mode?: 'popup' | 'redirect' | 'native' }`
+```js
+await sdk.logout({ postLogoutRedirectUri: location.origin });
+```
 
-  **Properties:**
+#### Token refresh
 
-  - `issuer` (string): The issuer URL of the OpenID Provider.
-  - `clientId` (string): The client identifier for the application.
-  - `redirectUri` (string): The URI to redirect to after authentication.
-  - `scopes` (Array<string>): The scopes to request during authentication.
-  - `responseType` (ResponseType): The response type requested from the OpenID Provider.
-  - `responseMode` (ResponseMode): The response mode to use.
-  - `storageTokenName` (string): The name of the token in storage.
-  - `storage` (SDKStorageType): A custom storage implementation.
+Refreshes the access token using the stored refresh token, keeping the session alive without requiring the user to log in again.
 
-  **Mode:**
+```js
+await sdk.refresh();
+```
+
+#### Token revocation
+
+Revokes the current access and refresh tokens on the server, invalidating the session immediately.
 
-  - `popup`: Uses a popup window for authentication. Returns an instance of `PopupFlow`.
-  - `redirect`: Uses a full-page redirect for authentication. Returns an instance of `RedirectFlow`.
-  - `native`: Uses a native flow for authentication. Returns an instance of `NativeFlow`.
+```js
+await sdk.revoke();
+```
 
-## Custom native flow
+### Native mode
 
-You can use the `NativeFlowHandler` class if there is no existing Strivacity implementation for your JavaScript framework, or if you want to build a fully custom authentication flow.
+In `native` mode, `login()` returns a `NativeFlowHandler` instance that drives the authentication UI step by step.
 
-If you are looking for example implementations for different frameworks, visit [packages](https://github.com/Strivacity/sdk-js/tree/main/packages).
+#### Login page example
 
-### Usage
+The login page extracts `session_id` from the URL on load and passes it to `startSession()` to resume an existing flow or start a new one:
 
 ```js
 import { initFlow } from '@strivacity/sdk-core';
@@ -74,60 +97,243 @@ const sdk = initFlow({
 	redirectUri: '<YOUR_REDIRECT_URI>',
 });
 
-// This will return with a `NativeFlowHandler` instance
+// Returns a NativeFlowHandler instance
 const handler = await sdk.login();
 
+// Extract session_id from URL if present
+const url = new URL(window.location.href);
+const sessionId = url.searchParams.get('session_id');
+
 // Start a new session or resume an existing one
-const state = await handler.startSession();
+const state = await handler.startSession(sessionId);
 
 if (state.finalizeUrl) {
-	// If the response contains a finalize URL, you can finalize the session
+	// Finalize the session when the flow is complete
 	await handler.finalizeSession(state.finalizeUrl);
 } else {
-	// Handle the response as needed
-	console.log('Form submitted successfully:', state);
+	// Render the form from state.widgets and handle user input
+	console.log('Current form state:', state);
 }
+```
 
-// Submit a form in the native flow
+#### Submitting a form
+
+```js
 const formState = await handler.submitForm('formId', {
-	// Your form data here
+	email: 'user@example.com',
+	password: 'secret',
 });
 
-if (state.finalizeUrl) {
-	// If the response contains a finalize URL, you can finalize the session
-	await handler.finalizeSession(state.finalizeUrl);
+if (formState.finalizeUrl) {
+	await handler.finalizeSession(formState.finalizeUrl);
+}
+```
+
+#### Callback page example
+
+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:
+
+```js
+const url = new URL(location.href);
+const sessionId = url.searchParams.get('session_id');
+
+if (sessionId) {
+	// Forward to login page with session_id to resume the native flow
+	window.location.href = `/login?session_id=${sessionId}`;
 } else {
-	// Handle the response as needed
-	console.log('Form submitted successfully:', state);
+	try {
+		await sdk.handleCallback();
+		window.location.href = '/profile';
+	} catch (error) {
+		console.error('Error during callback handling:', error);
+	}
 }
 ```
 
----
+#### Entry page example
+
+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:
+
+```js
+try {
+	const data = await sdk.entry();
+
+	if (data && Object.keys(data).length > 0) {
+		window.location.href = `/callback?${new URLSearchParams(data).toString()}`;
+	} else {
+		window.location.href = '/';
+	}
+} catch (error) {
+	console.error('Entry failed:', error);
+	window.location.href = '/';
+}
+```
+
+### Custom mode
+
+Custom mode lets you replace the built-in flow implementations with your own classes. This is useful when you need to proxy authentication through a backend server (BFF pattern) rather than communicating with the identity provider directly from the browser.
+
+Pass `mode: 'custom'` together with a `customFlow` class that extends one of the built-in flow base classes (`NativeFlow`, `EmbeddedFlow`, etc.):
+
+```ts
+import { initFlow } from '@strivacity/sdk-core';
+import { CustomNativeFlow } from './sdk/CustomNativeFlow';
 
-### API Documentation
+const sdk = initFlow({
+	mode: 'custom',
+	issuer: 'https://<YOUR_DOMAIN>',
+	scopes: ['openid', 'profile'],
+	clientId: '<YOUR_CLIENT_ID>',
+	redirectUri: '<YOUR_REDIRECT_URI>',
+	customFlow: CustomNativeFlow,
+});
+```
 
-#### `startSession(sessionId?: string | null): Promise<LoginFlowState | void>`
+#### Creating a custom flow class
 
-Starts a new authentication session. If a `sessionId` is provided, resumes the session; otherwise, initiates a new one.
+Extend `NativeFlow` (or `EmbeddedFlow`) and override the methods you need to change. The example below delegates session management to a backend API instead of calling the identity provider directly:
 
-#### `submitForm(formId?: string, body?: Record<string, unknown>): Promise<LoginFlowState>`
+```ts
+import type { NativeParams } from '@strivacity/sdk-core';
+import { NativeFlow } from '@strivacity/sdk-core/flows/NativeFlow';
+import { Session } from '@strivacity/sdk-core/utils/Session';
+import { CustomNativeFlowHandler } from './CustomNativeFlowHandler';
 
-Submits a form in the native flow. Optionally specify a form ID and request body.
+export class CustomNativeFlow extends NativeFlow {
+	override login(params: NativeParams = {}): CustomNativeFlowHandler {
+		this.dispatchEvent('loginInitiated', []);
+		return new CustomNativeFlowHandler(this, params);
+	}
 
-#### `finalizeSession(finalizeUrl: string): Promise<void>`
+	override register(params: NativeParams = {}): CustomNativeFlowHandler {
+		params.prompt = 'create';
+		return this.login(params);
+	}
 
-Finalizes the session using the provided URL. You can gather the finalize URL from the `LoginFlowState` returned by `startSession` or `submitForm`.
+	async fetchSessionData(): Promise<void> {
+		const response = await this.httpClient.request(new URL('/api/session/info', location.origin).toString(), { method: 'GET', credentials: 'include' });
 
----
+		this.session = Object.assign(new Session(), await response.json());
+
+		if (!this.accessTokenExpired) {
+			this.dispatchEvent('loggedIn', [{ claims: this.idTokenClaims! }]);
+		}
+	}
+
+	override async refresh(): Promise<void> {
+		const response = await this.httpClient.request(new URL('/api/session/refresh', location.origin).toString(), { method: 'POST', credentials: 'include' });
+
+		if (!response.ok) {
+			this.session = null;
+			this.dispatchEvent('tokenRefreshFailed', [{}]);
+			return;
+		}
+
+		this.session = Object.assign(new Session(), await response.json());
+		this.dispatchEvent('tokenRefreshed', [{ claims: this.idTokenClaims! }]);
+	}
+
+	override async logout(): Promise<void> {
+		this.dispatchEvent('logoutInitiated', []);
+
+		await this.httpClient.request(new URL('/api/session/logout', location.origin).toString(), { method: 'POST', credentials: 'include' });
+
+		this.session = null;
+	}
+}
+```
 
-## Event Subscription
+#### Creating a custom flow handler
+
+Extend `NativeFlowHandler` and override `startSession` and `finalizeSession` to communicate with your backend:
+
+```ts
+import type { LoginFlowState } from '@strivacity/sdk-core';
+import { NativeFlowHandler } from '@strivacity/sdk-core/handlers/NativeFlowHandler';
+import { CustomNativeFlow } from './CustomNativeFlow';
+
+export class CustomNativeFlowHandler extends NativeFlowHandler {
+	declare sdk: CustomNativeFlow;
+
+	override async startSession(sessionId?: string | null): Promise<LoginFlowState | void> {
+		if (sessionId) {
+			this.sessionId = sessionId;
+			return this.submitForm();
+		}
+
+		const response = await this.sdk.httpClient.request(new URL('/api/session/start', location.origin).toString(), {
+			method: 'POST',
+			credentials: 'include',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(this.params),
+		});
+
+		const data = await response.json();
+		this.sessionId = data.session_id;
+
+		return this.submitForm();
+	}
+
+	override async finalizeSession(finalizeUrl: string): Promise<void> {
+		const finalizeResponse = await this.sdk.httpClient.request(finalizeUrl, {
+			method: 'GET',
+			headers: { Authorization: `Bearer ${this.sessionId}` },
+			credentials: 'include',
+		});
+
+		const redirectUri = new URL(await finalizeResponse.text());
+
+		await this.sdk.httpClient.request(new URL('/api/session/finalize', location.origin).toString(), {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+				Authorization: `Bearer ${this.sessionId}`,
+			},
+			body: JSON.stringify(Object.fromEntries(redirectUri.searchParams)),
+			credentials: 'include',
+		});
+
+		await this.sdk.fetchSessionData();
+	}
+}
+```
 
-The SDK provides an event subscription system that allows you to listen to various authentication lifecycle events.
+### Event subscription
 
-### Usage
+The SDK provides an event system for listening to authentication lifecycle events:
 
 ```js
-import { initFlow } from '@strivacity/sdk-core';
+const { dispose } = sdk.subscribeToEvent('loggedIn', (eventData) => {
+	console.log('User logged in:', eventData);
+});
+
+// Later: unsubscribe
+dispose();
+```
+
+Available events:
+
+- **`init`**: Fired when the SDK is initialized.
+- **`loggedIn`**: Fired when a user successfully logs in.
+- **`loginInitiated`**: Fired when a login flow is initiated.
+- **`sessionLoaded`**: Fired when an existing session is loaded.
+- **`accessTokenExpired`**: Fired when the access token expires.
+- **`tokenRefreshed`**: Fired when access tokens are successfully refreshed.
+- **`tokenRefreshFailed`**: Fired when token refresh fails.
+- **`logoutInitiated`**: Fired when logout is initiated.
+- **`tokenRevoked`**: Fired when tokens are successfully revoked.
+- **`tokenRevokeFailed`**: Fired when token revocation fails.
+
+## Logging
+
+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.
+
+### Using the Default Logger
+
+Enable the default console logger by adding the `logging` option when calling `initFlow`:
+
+```js
+import { initFlow, DefaultLogging } from '@strivacity/sdk-core';
 
 const sdk = initFlow({
 	mode: 'redirect',
@@ -135,42 +341,145 @@ const sdk = initFlow({
 	scopes: ['openid', 'profile'],
 	clientId: '<YOUR_CLIENT_ID>',
 	redirectUri: '<YOUR_REDIRECT_URI>',
+	logging: DefaultLogging,
 });
+```
+
+The default logger writes to the browser console and automatically prefixes messages with a correlation ID when available (via the `xEventId` property).
+
+### Creating a Custom Logger
+
+Implement the `SDKLogging` interface and pass your class to the `logging` option:
+
+```typescript
+import type { SDKLogging } from '@strivacity/sdk-core';
+
+export class MyLogger implements SDKLogging {
+	xEventId?: string;
+
+	debug(message: string): void {
+		console.debug(this.xEventId ? `[${this.xEventId}] ${message}` : message);
+	}
+
+	info(message: string): void {
+		console.info(this.xEventId ? `[${this.xEventId}] ${message}` : message);
+	}
 
-// Subscribe to events
-function updateSession(eventData) {
-	console.log('Event received:', eventData);
-	// Handle the event as needed
+	warn(message: string): void {
+		console.warn(this.xEventId ? `[${this.xEventId}] ${message}` : message);
+	}
+
+	error(message: string, error: Error): void {
+		console.error(this.xEventId ? `[${this.xEventId}] ${message}` : message, error);
+	}
 }
+```
 
-sdk.subscribeToEvent('init', updateSession);
-sdk.subscribeToEvent('loggedIn', updateSession);
-sdk.subscribeToEvent('sessionLoaded', updateSession);
-sdk.subscribeToEvent('tokenRefreshed', updateSession);
-sdk.subscribeToEvent('tokenRefreshFailed', updateSession);
-sdk.subscribeToEvent('logoutInitiated', updateSession);
-sdk.subscribeToEvent('tokenRevoked', updateSession);
-sdk.subscribeToEvent('tokenRevokeFailed', updateSession);
+```js
+import { initFlow } from '@strivacity/sdk-core';
+import { MyLogger } from './logging/MyLogger';
+
+const sdk = initFlow({
+	// ...other options
+	logging: MyLogger,
+});
 ```
 
-### Available Events
+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.
 
-- **`init`**: Fired when the SDK is initialized
-- **`loggedIn`**: Fired when a user successfully logs in
-- **`sessionLoaded`**: Fired when an existing session is loaded
-- **`tokenRefreshed`**: Fired when access tokens are successfully refreshed
-- **`tokenRefreshFailed`**: Fired when token refresh fails
-- **`logoutInitiated`**: Fired when logout process is initiated
-- **`tokenRevoked`**: Fired when tokens are successfully revoked
-- **`tokenRevokeFailed`**: Fired when token revocation fails
+## API Documentation
 
-### API Documentation
+### `initFlow(options)`
 
-#### `subscribeToEvent(eventType: string, callback: (eventData: any) => void): void`
+```typescript
+initFlow(options: SDKOptions): PopupFlow | RedirectFlow | NativeFlow | EmbeddedFlow
+```
+
+The `initFlow` function creates and returns a flow instance based on the `mode` specified in `options`.
+
+**Parameters:**
+
+| Name               | Type                                                          | Required | Description                                                                    |
+| ------------------ | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------ |
+| `issuer`           | `string`                                                      | ✅       | The issuer URL of the OpenID Provider.                                         |
+| `clientId`         | `string`                                                      | ✅       | The client identifier for the application.                                     |
+| `redirectUri`      | `string`                                                      | ✅       | The URI to redirect to after authentication.                                   |
+| `mode`             | `'redirect' \| 'popup' \| 'native' \| 'embedded' \| 'custom'` | ⬜       | The authentication flow mode. Defaults to `'redirect'`.                        |
+| `scopes`           | `string[]`                                                    | ⬜       | The scopes to request. Defaults to `['openid']`.                               |
+| `responseType`     | `'code' \| 'id_token'`                                        | ⬜       | The response type.                                                             |
+| `responseMode`     | `'query' \| 'fragment'`                                       | ⬜       | The response mode.                                                             |
+| `storageTokenName` | `string`                                                      | ⬜       | Custom name for the session storage key. Defaults to `'sty.session'`.          |
+| `storage`          | `SDKStorageType`                                              | ⬜       | Custom storage implementation. Defaults to `LocalStorage`.                     |
+| `httpClient`       | `SDKHttpClientType`                                           | ⬜       | Custom HTTP client implementation.                                             |
+| `logging`          | `SDKLoggingType`                                              | ⬜       | Logging implementation class.                                                  |
+| `customFlow`       | `FlowType`                                                    | ⬜       | Custom flow class. Required when `mode` is `'custom'`. Must extend `BaseFlow`. |
+
+**Returns:** A flow instance (`PopupFlow`, `RedirectFlow`, `NativeFlow`, `EmbeddedFlow`, or your custom flow class) depending on the configured `mode`.
+
+---
+
+### Flow instance methods
+
+All flow instances share the following methods:
+
+- **`login(options?: LoginOptions): Promise<void | NativeFlowHandler>`**: Initiates login. In `native` mode returns a `NativeFlowHandler`.
+- **`register(options?: RegisterOptions): Promise<void | NativeFlowHandler>`**: Initiates registration.
+- **`entry(url?: string): Promise<Record<string, string>>`**: Processes an externally-initiated flow URL and returns parameters needed to resume the flow.
+- **`handleCallback(url?: string): Promise<void>`**: Processes the authorization callback.
+- **`refresh(): Promise<void>`**: Refreshes the session tokens.
+- **`revoke(): Promise<void>`**: Revokes the current session tokens.
+- **`logout(options?: LogoutOptions): Promise<void>`**: Logs the user out.
+- **`subscribeToEvent(eventType: string, callback: Function): { dispose(): void }`**: Subscribes to an authentication lifecycle event. Returns an object with a `dispose()` method to unsubscribe.
+
+**Session state getters:**
+
+- **`isAuthenticated: Promise<boolean>`**: Resolves to `true` when a valid session exists.
+- **`isAuthenticatedSync: boolean`**: Synchronous check for an active session.
+- **`idTokenClaims: IdTokenClaims | null`**: Claims from the ID token.
+- **`accessToken: string | null`**: The current access token.
+- **`refreshToken: string | null`**: The current refresh token.
+- **`accessTokenExpired: boolean`**: `true` when the access token has expired.
+- **`accessTokenExpirationDate: number | null`**: Expiration timestamp (Unix seconds) of the access token.
+
+---
+
+### `NativeFlowHandler`
 
-Subscribe to SDK events to handle authentication state changes.
+Returned by `NativeFlow.login()` and `NativeFlow.register()` to drive the step-by-step native authentication UI.
+
+- **`startSession(sessionId?: string | null): Promise<LoginFlowState | void>`**: Starts a new authentication session or resumes an existing one when `sessionId` is provided.
+- **`submitForm(formId?: string, body?: Record<string, unknown>): Promise<LoginFlowState>`**: Submits a form step in the authentication flow.
+- **`finalizeSession(finalizeUrl: string): Promise<void>`**: Finalizes the session using the URL returned in `LoginFlowState.finalizeUrl`.
+
+---
+
+### `subscribeToEvent(eventType, callback)`
+
+Subscribe to SDK lifecycle events.
 
 **Parameters:**
 
-- `eventType` (string): The type of event to listen for
-- `callback` (function): The function to call when the event is fired
+| Name        | Type                       | Required | Description                              |
+| ----------- | -------------------------- | -------- | ---------------------------------------- |
+| `eventType` | `string`                   | ✅       | The event type to listen for.            |
+| `callback`  | `(eventData: any) => void` | ✅       | The handler called when the event fires. |
+
+**Returns:** `{ dispose(): void }` — call `dispose()` to unsubscribe.
+
+## Vulnerability Reporting
+
+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.
+
+## License
+
+@strivacity/sdk-core is available under the MIT License. See the [LICENSE](https://github.com/Strivacity/sdk-js/blob/main/LICENSE) file for more info.
+
+## Contributing
+
+Please see our [contributing guide](https://github.com/Strivacity/sdk-js/blob/main/CONTRIBUTING.md).
+
+## Migrating to v3.0
+
+### Entry API Major Changes
+
+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.