@strivacity/sdk-core 3.0.3 → 4.0.0-beta.0

package/testing/tests/handlers/native.spec.ts

@@ -0,0 +1,283 @@
+import { beforeEach, describe, test, expect } from 'vitest';
+import { createOptions, createFakeBaseFlow } from '@strivacity/testing/mocks/sdk';
+import { worker, http, HttpResponse } from '@strivacity/testing/mocks/msw';
+import { getDefaultFlowState, ProtocolError, OidcError, ServerError, NetworkError, SessionExpiredError, FallbackError } from '../../../src/utils';
+import { redirectCallbackHandler } from '../../../src/handlers/redirect';
+import { submitFormHandler, startSessionHandler, finalizeSessionHandler } from '../../../src/handlers/native';
+
+describe('startSessionHandler', () => {
+	let params: Parameters<typeof startSessionHandler>[0];
+
+	beforeEach(() => {
+		globalThis.location.href = 'https://brandtegrity.io';
+		params = { base: createFakeBaseFlow(), options: createOptions(), flowState: getDefaultFlowState(), params: {} };
+	});
+
+	test('should start session correctly', async () => {
+		worker.use(
+			http.get('https://brandtegrity.io/oauth2/auth', () =>
+				HttpResponse.text('https://brandtegrity.io/login?session_id=abc123&short_app_id=app&language=hu-HU'),
+			),
+			http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.json({ screen: 'identification' })),
+		);
+
+		await expect(startSessionHandler(params)).resolves.toEqual({ screen: 'identification' });
+
+		expect(params.flowState.sessionId).toBe('abc123');
+		expect(params.flowState.shortAppId).toBe('app');
+		expect(params.flowState.language).toBe('hu-HU');
+	});
+
+	test('should continue session correctly', async () => {
+		worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.json({ screen: 'identification' })));
+		params.params = { sessionId: 'abc123' };
+
+		await expect(startSessionHandler(params)).resolves.toEqual({ screen: 'identification' });
+
+		expect(params.base.dispatchEvent).toHaveBeenCalledWith('flowInitiated', []);
+		expect(params.flowState.sessionId).toBe('abc123');
+	});
+
+	describe('should exchange the code for tokens correctly', () => {
+		test('w/o serverSessionUri', async () => {
+			worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => HttpResponse.text('https://brandtegrity.io/callback?code=abc123')));
+
+			await startSessionHandler(params);
+
+			expect(globalThis.location.href).not.toBe('https://brandtegrity.io/callback?code=abc123');
+			expect(params.base.tokenExchange).toHaveBeenCalledWith({ code: 'abc123' });
+		});
+
+		test('w/ serverSessionUri', async () => {
+			worker.use(http.get('https://brandtegrity.io/login', () => HttpResponse.text('https://brandtegrity.io/callback?code=abc123')));
+			params.options = createOptions({ serverSessionUri: 'https://brandtegrity.io/login' });
+
+			await startSessionHandler(params);
+
+			expect(globalThis.location.href).toBe('https://brandtegrity.io/callback?code=abc123');
+			expect(params.base.tokenExchange).not.toHaveBeenCalled();
+		});
+	});
+
+	test('should reject with a ProtocolError when neither code nor session_id are present', async () => {
+		worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => HttpResponse.text('https://brandtegrity.io/login?something=else')));
+
+		await expect(startSessionHandler(params)).rejects.toThrow(new ProtocolError('Neither "code" nor "session_id" is present in the response'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(ProtocolError));
+	});
+
+	test('should reject with an OidcError when the response contains an error', async () => {
+		worker.use(
+			http.get('https://brandtegrity.io/oauth2/auth', () =>
+				HttpResponse.text('https://brandtegrity.io/login?error=access_denied&error_description=nope&error_uri=https://example.com/error'),
+			),
+		);
+
+		await expect(startSessionHandler(params)).rejects.toThrow(new OidcError('access_denied', 'nope', 'https://example.com/error'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(OidcError));
+	});
+
+	test('should reject with a ProtocolError when the redirect URI does not match the configured redirectUri', async () => {
+		worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => HttpResponse.text('https://invalid.domain/callback?code=abc123')));
+
+		await expect(startSessionHandler(params)).rejects.toThrow(new ProtocolError('Invalid redirect URI'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(ProtocolError));
+	});
+
+	describe('should reject with an error when the HTTP request fails', () => {
+		test('HTTP 400', async () => {
+			worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => new HttpResponse(null, { status: 400 })));
+
+			await expect(startSessionHandler(params)).rejects.toThrow(new ProtocolError('Failed to start login session'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(ProtocolError));
+		});
+
+		test('HTTP 429', async () => {
+			worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => new HttpResponse(null, { status: 429 })));
+
+			await expect(startSessionHandler(params)).rejects.toThrow(new ServerError('Failed to start login session', 429));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(ServerError));
+		});
+
+		test('HTTP 500', async () => {
+			worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => new HttpResponse(null, { status: 500 })));
+
+			await expect(startSessionHandler(params)).rejects.toThrow(new ServerError('Failed to start login session', 500));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(ServerError));
+		});
+
+		test('HTTP 503', async () => {
+			worker.use(http.get('https://brandtegrity.io/oauth2/auth', () => HttpResponse.error()));
+
+			await expect(startSessionHandler(params)).rejects.toThrow(new NetworkError('Network request failed: https://brandtegrity.io/oauth2/auth'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Start login session error', expect.any(NetworkError));
+		});
+	});
+});
+
+describe('submitFormHandler', () => {
+	let params: Parameters<typeof submitFormHandler>[0];
+
+	beforeEach(() => {
+		globalThis.location.href = 'https://brandtegrity.io';
+		params = { base: createFakeBaseFlow(), options: createOptions(), flowState: { ...getDefaultFlowState(), sessionId: 'abc123' } };
+	});
+
+	test('should submit the login form and return the resulting flow state', async () => {
+		worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.json({ screen: 'identification' })));
+
+		await expect(submitFormHandler(params)).resolves.toEqual({ screen: 'identification' });
+	});
+
+	test('should submit to the form-specific endpoint when a formId is provided', async () => {
+		worker.use(http.post('https://brandtegrity.io/flow/api/v1/form/identifier', () => HttpResponse.json({ screen: 'password' })));
+		params.formId = 'identifier';
+
+		await expect(submitFormHandler(params)).resolves.toEqual({ screen: 'password' });
+	});
+
+	test('should finalize the session when a finalizeUrl is present in the response', async () => {
+		worker.use(
+			http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.json({ finalizeUrl: 'https://brandtegrity.io/finalize' })),
+			http.get('https://brandtegrity.io/finalize', () => HttpResponse.text('https://brandtegrity.io/callback?code=abc123')),
+		);
+		params.options = createOptions({ serverSessionUri: 'https://brandtegrity.io/login' });
+
+		await submitFormHandler(params);
+
+		expect(globalThis.location.href).toBe('https://brandtegrity.io/callback?code=abc123');
+	});
+
+	test('should throw when the session ID is missing', async () => {
+		params.flowState = getDefaultFlowState();
+
+		await expect(submitFormHandler(params)).rejects.toThrow(new Error('Session ID is missing. Cannot submit form.'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Failed to submit form', expect.any(Error));
+	});
+
+	describe('should reject with an error when the HTTP request fails', () => {
+		test('HTTP 403 rejects with a SessionExpiredError', async () => {
+			worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => new HttpResponse(null, { status: 403 })));
+
+			await expect(submitFormHandler(params)).rejects.toThrow(SessionExpiredError);
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(SessionExpiredError));
+		});
+
+		test('HTTP 400 with a hostedUrl falls back to the hosted UI', async () => {
+			worker.use(
+				http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.json({ hostedUrl: 'https://brandtegrity.io/hosted' }, { status: 400 })),
+			);
+
+			await expect(submitFormHandler(params)).rejects.toThrow(FallbackError);
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(FallbackError));
+		});
+
+		test('HTTP 400 without a hostedUrl', async () => {
+			worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => new HttpResponse(null, { status: 400 })));
+
+			await expect(submitFormHandler(params)).rejects.toThrow(new ProtocolError('Failed to submit login form'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(ProtocolError));
+		});
+
+		test('HTTP 429', async () => {
+			worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => new HttpResponse(null, { status: 429 })));
+
+			await expect(submitFormHandler(params)).rejects.toThrow(new ServerError('Failed to submit login form', 429));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(ServerError));
+		});
+
+		test('HTTP 500', async () => {
+			worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => new HttpResponse(null, { status: 500 })));
+
+			await expect(submitFormHandler(params)).rejects.toThrow(new ServerError('Failed to submit login form', 500));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(ServerError));
+		});
+
+		test('HTTP 503', async () => {
+			worker.use(http.post('https://brandtegrity.io/flow/api/v1/init', () => HttpResponse.error()));
+
+			await expect(submitFormHandler(params)).rejects.toThrow(new NetworkError('Network request failed: https://brandtegrity.io/flow/api/v1/init'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Form submission failed', expect.any(NetworkError));
+		});
+	});
+});
+
+describe('finalizeSessionHandler', () => {
+	let params: Parameters<typeof finalizeSessionHandler>[0];
+
+	beforeEach(() => {
+		globalThis.location.href = 'https://brandtegrity.io';
+		params = {
+			base: createFakeBaseFlow(),
+			options: createOptions(),
+			flowState: { ...getDefaultFlowState(), sessionId: 'abc123' },
+			url: 'https://brandtegrity.io/finalize',
+		};
+	});
+
+	describe('should finalize session correctly', () => {
+		test('w/o serverSessionUri', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => HttpResponse.text('https://brandtegrity.io/callback?code=abc123')));
+			params.options.callbackHandler = redirectCallbackHandler;
+
+			await finalizeSessionHandler(params);
+
+			expect(globalThis.location.href).not.toBe('https://brandtegrity.io/callback?code=abc123');
+			expect(params.base.tokenExchange).toHaveBeenCalledWith({ code: 'abc123' });
+		});
+
+		test('w/ serverSessionUri', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => HttpResponse.text('https://brandtegrity.io/callback?code=abc123')));
+			params.options = createOptions({ serverSessionUri: 'https://brandtegrity.io/login' });
+
+			await finalizeSessionHandler(params);
+
+			expect(globalThis.location.href).toBe('https://brandtegrity.io/callback?code=abc123');
+			expect(params.base.tokenExchange).not.toHaveBeenCalled();
+		});
+	});
+
+	test('should throw when the session ID is missing', async () => {
+		params.flowState = getDefaultFlowState();
+
+		await expect(finalizeSessionHandler(params)).rejects.toThrow(new Error('Session ID is missing. Cannot finalize login session.'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Failed to finalize login session', expect.any(Error));
+	});
+
+	test('should reject with a ProtocolError when the redirect URI does not match the configured redirectUri', async () => {
+		worker.use(http.get('https://brandtegrity.io/finalize', () => HttpResponse.text('https://invalid.domain/callback?code=abc123')));
+
+		await expect(finalizeSessionHandler(params)).rejects.toThrow(new ProtocolError('Invalid redirect URI'));
+		expect(params.options.logging?.error).toHaveBeenCalledWith('Finalize login session error', expect.any(ProtocolError));
+	});
+
+	describe('should reject with an error when the HTTP request fails', () => {
+		test('HTTP 400', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => new HttpResponse(null, { status: 400 })));
+
+			await expect(finalizeSessionHandler(params)).rejects.toThrow(new ProtocolError('Failed to finalize login session'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Finalize login session error', expect.any(ProtocolError));
+		});
+
+		test('HTTP 429', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => new HttpResponse(null, { status: 429 })));
+
+			await expect(finalizeSessionHandler(params)).rejects.toThrow(new ServerError('Failed to finalize login session', 429));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Finalize login session error', expect.any(ServerError));
+		});
+
+		test('HTTP 500', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => new HttpResponse(null, { status: 500 })));
+
+			await expect(finalizeSessionHandler(params)).rejects.toThrow(new ServerError('Failed to finalize login session', 500));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Finalize login session error', expect.any(ServerError));
+		});
+
+		test('HTTP 503', async () => {
+			worker.use(http.get('https://brandtegrity.io/finalize', () => HttpResponse.error()));
+
+			await expect(finalizeSessionHandler(params)).rejects.toThrow(new NetworkError('Network request failed: https://brandtegrity.io/finalize'));
+			expect(params.options.logging?.error).toHaveBeenCalledWith('Finalize login session error', expect.any(NetworkError));
+		});
+	});
+});

package/testing/tests/handlers/popup.spec.ts

@@ -0,0 +1,206 @@
+import { describe, test, expect, vi, afterEach } from 'vitest';
+import { createFakePopup, postMessageFromPopup } from '@strivacity/testing/mocks/window';
+import { popupUrlHandler, popupCallbackHandler } from '../../../src/handlers';
+import { PopupBlockedError, PopupClosedError } from '../../../src/utils';
+
+describe('popupUrlHandler', () => {
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	test('should throw a PopupBlockedError when the popup is blocked', async () => {
+		vi.spyOn(window, 'open').mockReturnValue(null);
+
+		await expect(popupUrlHandler('https://example.com/')).rejects.toThrow(PopupBlockedError);
+	});
+
+	test('should navigate the popup and resolve with the posted message data', async () => {
+		const popup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+		const promise = popupUrlHandler('https://example.com/');
+
+		postMessageFromPopup(popup, { code: 'abc' });
+
+		await expect(promise).resolves.toEqual({ code: 'abc' });
+		expect(popup.location.replace).toHaveBeenCalledWith('https://example.com/');
+		expect(popup.focus).toHaveBeenCalled();
+		expect(popup.close).toHaveBeenCalled();
+	});
+
+	test('should invoke a popup handler function instead of navigating', async () => {
+		const popup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+		const handler = vi.fn();
+
+		const promise = popupUrlHandler(handler);
+
+		// Let the awaited handler call settle before the internal message listener is registered.
+		await Promise.resolve();
+
+		postMessageFromPopup(popup, { code: 'abc' });
+
+		await expect(promise).resolves.toEqual({ code: 'abc' });
+		expect(handler).toHaveBeenCalledWith(popup);
+		expect(popup.location.replace).not.toHaveBeenCalled();
+	});
+
+	test('should ignore messages from an unrelated source', async () => {
+		const popup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+		const promise = popupUrlHandler('https://example.com/');
+		let settled = false;
+		void promise.then(() => (settled = true));
+
+		postMessageFromPopup({}, { code: 'wrong' });
+		await Promise.resolve();
+		expect(settled).toBe(false);
+
+		postMessageFromPopup(popup, { code: 'abc' });
+		await expect(promise).resolves.toEqual({ code: 'abc' });
+	});
+
+	test('should reject with a PopupClosedError when the popup is closed by the user', async () => {
+		vi.useFakeTimers();
+		const popup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+		const promise = popupUrlHandler('https://example.com/');
+		const assertion = expect(promise).rejects.toThrow(PopupClosedError);
+
+		popup.closed = true;
+		await vi.advanceTimersByTimeAsync(500);
+
+		await assertion;
+	});
+
+	test('cleans up its message listener when the popup is closed by the user, not just the timer', async () => {
+		vi.useFakeTimers();
+		const popup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+		const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+
+		const promise = popupUrlHandler('https://example.com/');
+		promise.catch(() => {});
+
+		popup.closed = true;
+		await vi.advanceTimersByTimeAsync(500);
+		await expect(promise).rejects.toThrow(PopupClosedError);
+
+		expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+	});
+
+	test('completion-wins race — a redirect message that beats the close-detection tick resolves exactly once, and a late message afterward is a harmless no-op', async () => {
+		for (let i = 0; i < 20; i++) {
+			vi.useFakeTimers();
+			const popup = createFakePopup();
+			vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+			const promise = popupUrlHandler('https://example.com/');
+
+			postMessageFromPopup(popup, { code: 'abc' });
+			await Promise.resolve();
+			popup.closed = true;
+			await vi.advanceTimersByTimeAsync(500);
+
+			await expect(promise).resolves.toEqual({ code: 'abc' });
+
+			vi.useRealTimers();
+		}
+	});
+
+	test('completion-wins race — the close-detection tick beats a redirect message, rejects exactly once, and the late message afterward is a harmless no-op', async () => {
+		for (let i = 0; i < 20; i++) {
+			vi.useFakeTimers();
+			const popup = createFakePopup();
+			vi.spyOn(window, 'open').mockReturnValue(popup as unknown as Window);
+
+			const promise = popupUrlHandler('https://example.com/');
+			// NOTE: attached immediately so fake-timer microtask flushing below never reports this as an unhandled rejection.
+			promise.catch(() => {});
+
+			popup.closed = true;
+			await vi.advanceTimersByTimeAsync(500);
+
+			expect(() => postMessageFromPopup(popup, { code: 'abc' })).not.toThrow();
+			await expect(promise).rejects.toThrow(PopupClosedError);
+
+			vi.useRealTimers();
+		}
+	});
+
+	test('should close a leftover popup from a previous call', async () => {
+		vi.useFakeTimers();
+		const firstPopup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValueOnce(firstPopup as unknown as Window);
+
+		void popupUrlHandler('https://example.com/first');
+
+		const secondPopup = createFakePopup();
+		vi.spyOn(window, 'open').mockReturnValueOnce(secondPopup as unknown as Window);
+
+		const secondPromise = popupUrlHandler('https://example.com/second');
+
+		expect(firstPopup.close).toHaveBeenCalled();
+
+		postMessageFromPopup(secondPopup, { code: 'abc' });
+
+		await expect(secondPromise).resolves.toEqual({ code: 'abc' });
+	});
+});
+
+describe('popupCallbackHandler', () => {
+	afterEach(() => {
+		globalThis.location.href = 'https://example.com/';
+	});
+
+	test('should post parsed query parameters to the opener window', () => {
+		const postMessage = vi.fn();
+		vi.spyOn(window, 'opener', 'get').mockReturnValue({ postMessage });
+		globalThis.location.href = 'https://example.com/callback?code=abc&state=xyz';
+
+		void popupCallbackHandler();
+
+		expect(postMessage).toHaveBeenCalledWith({ code: 'abc', state: 'xyz' }, '*');
+	});
+
+	test('should parse parameters from the fragment when responseMode is "fragment"', () => {
+		const postMessage = vi.fn();
+		vi.spyOn(window, 'opener', 'get').mockReturnValue({ postMessage });
+		globalThis.location.href = 'https://example.com/callback#code=abc&state=xyz';
+
+		void popupCallbackHandler(undefined, 'fragment');
+
+		expect(postMessage).toHaveBeenCalledWith({ code: 'abc', state: 'xyz' }, '*');
+	});
+
+	test('should post an invalid_request error when a parameter is duplicated', () => {
+		const postMessage = vi.fn();
+		vi.spyOn(window, 'opener', 'get').mockReturnValue({ postMessage });
+		globalThis.location.href = 'https://example.com/callback?code=abc&code=def';
+
+		void popupCallbackHandler();
+
+		expect(postMessage).toHaveBeenCalledWith(expect.objectContaining({ error: 'invalid_request' }), '*');
+	});
+
+	test('should do nothing when there is no opener window', () => {
+		vi.spyOn(window, 'opener', 'get').mockReturnValue(null);
+		globalThis.location.href = 'https://example.com/callback?code=abc';
+
+		expect(() => void popupCallbackHandler()).not.toThrow();
+	});
+
+	test('should return a promise that never settles', async () => {
+		vi.spyOn(window, 'opener', 'get').mockReturnValue(null);
+
+		let settled = false;
+		void popupCallbackHandler().then(() => (settled = true));
+
+		await Promise.resolve();
+		await Promise.resolve();
+
+		expect(settled).toBe(false);
+	});
+});

package/testing/tests/handlers/redirect.spec.ts

@@ -0,0 +1,70 @@
+import { describe, test, expect, vi } from 'vitest';
+import { redirectUrlHandler, redirectCallbackHandler } from '../../../src/handlers';
+import { ProtocolError } from '../../../src/utils';
+
+describe('redirectUrlHandler', () => {
+	test('should reject when no URL is provided', async () => {
+		await expect(redirectUrlHandler()).rejects.toThrow('No URL provided for redirection');
+	});
+
+	test('should call location.assign on the current window by default', async () => {
+		const assignSpy = vi.spyOn(window.location, 'assign').mockImplementation(() => undefined);
+
+		await redirectUrlHandler('https://example.com/');
+
+		expect(assignSpy).toHaveBeenCalledWith('https://example.com/');
+	});
+
+	test('should call location.replace when locationMethod is "replace"', async () => {
+		const replaceSpy = vi.spyOn(window.location, 'replace').mockImplementation(() => undefined);
+
+		await redirectUrlHandler('https://example.com/', { locationMethod: 'replace' });
+
+		expect(replaceSpy).toHaveBeenCalledWith('https://example.com/');
+	});
+
+	test('should redirect the top window when targetWindow is "top"', async () => {
+		const topAssign = vi.fn();
+		vi.spyOn(window, 'top', 'get').mockReturnValue({ location: { assign: topAssign } } as unknown as Window & typeof globalThis);
+
+		await redirectUrlHandler('https://example.com/', { targetWindow: 'top' });
+
+		expect(topAssign).toHaveBeenCalledWith('https://example.com/');
+	});
+
+	test('should resolve without navigating when the target window is unavailable', async () => {
+		vi.spyOn(window, 'self', 'get').mockReturnValue(undefined as unknown as Window & typeof globalThis);
+
+		await expect(redirectUrlHandler('https://example.com/')).resolves.toBeUndefined();
+	});
+});
+
+describe('redirectCallbackHandler', () => {
+	test('should reject when no URL is provided', async () => {
+		await expect(redirectCallbackHandler('')).rejects.toThrow('No URL provided for redirect callback handling');
+	});
+
+	test('should parse parameters from the query string by default', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback?code=abc&state=xyz')).resolves.toEqual({ code: 'abc', state: 'xyz' });
+	});
+
+	test('should parse parameters from the fragment when responseMode is "fragment"', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback#code=abc&state=xyz', 'fragment')).resolves.toEqual({ code: 'abc', state: 'xyz' });
+	});
+
+	test('should resolve with an empty object when there are no parameters', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback')).resolves.toEqual({});
+	});
+
+	test('should reject with a ProtocolError when a parameter is duplicated', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback?code=abc&code=def')).rejects.toThrow(ProtocolError);
+	});
+
+	test('should not read a code delivered in the fragment when configured for query mode', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback#code=abc&state=xyz')).resolves.toEqual({});
+	});
+
+	test('should not read a code delivered in the query when configured for fragment mode', async () => {
+		await expect(redirectCallbackHandler('https://example.com/callback?code=abc&state=xyz', 'fragment')).resolves.toEqual({});
+	});
+});

package/testing/tests/index.spec.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect, vi, afterEach } from 'vitest';
+import { createOptions } from '@strivacity/testing/mocks/sdk';
+import * as index from '../../src/index';
+import { UnsupportedFlowError } from '../../src/utils/errors';
+import { createRedirectFlow } from '../../src/flows/redirect';
+import { createPopupFlow } from '../../src/flows/popup';
+import { createEmbeddedFlow } from '../../src/flows/embedded';
+import { createNativeFlow } from '../../src/flows/native';
+
+vi.mock('../../src/flows/redirect');
+vi.mock('../../src/flows/popup');
+vi.mock('../../src/flows/embedded');
+vi.mock('../../src/flows/native');
+
+test('should export the correct things', () => {
+	const expectedExports = ['initFlow'];
+
+	expect(Object.keys(index)).toEqual(expectedExports);
+});
+
+describe('initFlow', () => {
+	afterEach(() => {
+		vi.clearAllMocks();
+	});
+
+	test('mode: "redirect"', () => {
+		const options = createOptions({ mode: 'redirect' });
+		const flow = { type: 'redirect' };
+		vi.mocked(createRedirectFlow).mockReturnValue(flow);
+
+		expect(index.initFlow(options as never)).toBe(flow);
+		expect(createRedirectFlow).toHaveBeenCalledWith(options);
+		expect(createPopupFlow).not.toHaveBeenCalled();
+		expect(createEmbeddedFlow).not.toHaveBeenCalled();
+		expect(createNativeFlow).not.toHaveBeenCalled();
+	});
+
+	test('mode: "popup"', () => {
+		const options = createOptions({ mode: 'popup' });
+		const flow = { type: 'popup' };
+		vi.mocked(createPopupFlow).mockReturnValue(flow);
+
+		expect(index.initFlow(options as never)).toBe(flow);
+		expect(createPopupFlow).toHaveBeenCalledWith(options);
+		expect(createRedirectFlow).not.toHaveBeenCalled();
+		expect(createEmbeddedFlow).not.toHaveBeenCalled();
+		expect(createNativeFlow).not.toHaveBeenCalled();
+	});
+
+	test('mode: "embedded"', () => {
+		const options = createOptions({ mode: 'embedded' });
+		const flow = { type: 'embedded' };
+		vi.mocked(createEmbeddedFlow).mockReturnValue(flow);
+
+		expect(index.initFlow(options as never)).toBe(flow);
+		expect(createEmbeddedFlow).toHaveBeenCalledWith(options);
+		expect(createRedirectFlow).not.toHaveBeenCalled();
+		expect(createPopupFlow).not.toHaveBeenCalled();
+		expect(createNativeFlow).not.toHaveBeenCalled();
+	});
+
+	test('mode: "native"', () => {
+		const options = createOptions({ mode: 'native' });
+		const flow = { type: 'native' };
+		vi.mocked(createNativeFlow).mockReturnValue(flow);
+
+		expect(index.initFlow(options as never)).toBe(flow);
+		expect(createNativeFlow).toHaveBeenCalledWith(options);
+		expect(createRedirectFlow).not.toHaveBeenCalled();
+		expect(createPopupFlow).not.toHaveBeenCalled();
+		expect(createEmbeddedFlow).not.toHaveBeenCalled();
+	});
+
+	test('should throw UnsupportedFlowError when called with an unsupported mode', () => {
+		// @ts-expect-error: Testing unsupported mode
+		expect(() => index.initFlow({ mode: 'unsupported' })).throw(UnsupportedFlowError);
+	});
+});