@strivacity/sdk-angular 3.0.2 → 4.0.0-beta.0

package/src/lib/services/auth.service.ts

@@ -0,0 +1,131 @@
+import type { IdTokenClaims, SDKInstance } from '../../types';
+import { DestroyRef, Injectable, PLATFORM_ID, TransferState, inject, signal } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import { initFlow } from '@strivacity/sdk-core';
+import { STRIVACITY_SDK } from '../utils';
+import { SESSION_TRANSFER_KEY } from '../../server/session';
+
+/**
+ * Signal-based service exposing the Strivacity SDK state and actions to Angular components.
+ *
+ * Provided via `provideStrivacity()` (standalone) or `StrivacityAuthModule.forRoot()` (NgModule).
+ */
+@Injectable()
+export class StrivacityAuthService {
+	private readonly loadingSignal = signal(true);
+	private readonly languageSignal = signal(globalThis.navigator?.language ?? 'en-US');
+	private readonly isAuthenticatedSignal = signal(false);
+	private readonly idTokenClaimsSignal = signal<IdTokenClaims | null>(null);
+	private readonly accessTokenSignal = signal<string | null>(null);
+	private readonly refreshTokenSignal = signal<string | null>(null);
+	private readonly accessTokenExpiredSignal = signal(true);
+	private readonly accessTokenExpirationDateSignal = signal<number | null>(null);
+
+	readonly options = inject(STRIVACITY_SDK);
+	readonly sdk: SDKInstance = initFlow(this.options as never);
+	readonly loading = this.loadingSignal.asReadonly();
+	readonly language = this.languageSignal.asReadonly();
+	readonly isAuthenticated = this.isAuthenticatedSignal.asReadonly();
+	readonly idTokenClaims = this.idTokenClaimsSignal.asReadonly();
+	readonly accessToken = this.accessTokenSignal.asReadonly();
+	readonly refreshToken = this.refreshTokenSignal.asReadonly();
+	readonly accessTokenExpired = this.accessTokenExpiredSignal.asReadonly();
+	readonly accessTokenExpirationDate = this.accessTokenExpirationDateSignal.asReadonly();
+
+	constructor() {
+		if (this.options.serverSessionUri) {
+			const transferState = inject(TransferState);
+			const hydratedSession = transferState.get(SESSION_TRANSFER_KEY, undefined);
+
+			if (hydratedSession) {
+				this.sdk.session = hydratedSession;
+
+				if (isPlatformBrowser(inject(PLATFORM_ID))) {
+					transferState.remove(SESSION_TRANSFER_KEY);
+				}
+			}
+		}
+
+		void this.updateSession();
+
+		const subscription = this.sdk.subscribeToAllEvents(() => this.updateSession());
+		inject(DestroyRef).onDestroy(() => subscription.dispose());
+	}
+
+	init(...args: Parameters<typeof this.sdk.init>): ReturnType<typeof this.sdk.init> {
+		return this.sdk.init(...args);
+	}
+
+	subscribeToEvent(...args: Parameters<typeof this.sdk.subscribeToEvent>): ReturnType<typeof this.sdk.subscribeToEvent> {
+		return this.sdk.subscribeToEvent(...args);
+	}
+
+	subscribeToAllEvents(...args: Parameters<typeof this.sdk.subscribeToAllEvents>): ReturnType<typeof this.sdk.subscribeToAllEvents> {
+		return this.sdk.subscribeToAllEvents(...args);
+	}
+
+	checkAuthentication(...args: Parameters<typeof this.sdk.checkAuthentication>): ReturnType<typeof this.sdk.checkAuthentication> {
+		return this.sdk.checkAuthentication(...args);
+	}
+
+	tokenExchange(...args: Parameters<typeof this.sdk.tokenExchange>): ReturnType<typeof this.sdk.tokenExchange> {
+		return this.sdk.tokenExchange(...args);
+	}
+
+	handleCallback(...args: Parameters<typeof this.sdk.handleCallback>): ReturnType<typeof this.sdk.handleCallback> {
+		return this.sdk.handleCallback(...args);
+	}
+
+	refresh(): ReturnType<typeof this.sdk.refresh> {
+		return this.sdk.refresh();
+	}
+
+	revoke(): ReturnType<typeof this.sdk.revoke> {
+		return this.sdk.revoke();
+	}
+
+	logout(...args: Parameters<typeof this.sdk.logout>): ReturnType<typeof this.sdk.logout> {
+		return this.sdk.logout(...args);
+	}
+
+	login(...args: Parameters<typeof this.sdk.login>): ReturnType<typeof this.sdk.login> {
+		return this.sdk.login(...args);
+	}
+
+	register(...args: Parameters<typeof this.sdk.register>): ReturnType<typeof this.sdk.register> {
+		return this.sdk.register(...args);
+	}
+
+	entry(...args: Parameters<typeof this.sdk.entry>): ReturnType<typeof this.sdk.entry> {
+		return this.sdk.entry(...args);
+	}
+
+	private async updateSession(): Promise<void> {
+		const authenticated = await this.sdk.isAuthenticated;
+
+		if (this.loadingSignal()) {
+			this.loadingSignal.set(false);
+		}
+		if (this.sdk.language !== this.languageSignal()) {
+			this.languageSignal.set(this.sdk.language);
+		}
+		if (authenticated !== this.isAuthenticatedSignal()) {
+			this.isAuthenticatedSignal.set(authenticated);
+		}
+		if (this.sdk.idTokenClaims !== this.idTokenClaimsSignal()) {
+			this.idTokenClaimsSignal.set(this.sdk.idTokenClaims ?? null);
+		}
+		if (this.sdk.accessToken !== this.accessTokenSignal()) {
+			this.accessTokenSignal.set(this.sdk.accessToken ?? null);
+		}
+		if (this.sdk.refreshToken !== this.refreshTokenSignal()) {
+			this.refreshTokenSignal.set(this.sdk.refreshToken ?? null);
+		}
+		if (this.sdk.accessTokenExpired !== this.accessTokenExpiredSignal()) {
+			this.accessTokenExpiredSignal.set(this.sdk.accessTokenExpired);
+		}
+		if (this.sdk.accessTokenExpirationDate !== this.accessTokenExpirationDateSignal()) {
+			this.accessTokenExpirationDateSignal.set(this.sdk.accessTokenExpirationDate ?? null);
+		}
+	}
+}

package/src/lib/services/index.ts

@@ -0,0 +1,2 @@
+export { StrivacityAuthService } from './auth.service';
+export { StrivacityNativeLoginService } from './native-login.service';

package/src/lib/services/native-login.service.ts

@@ -0,0 +1,172 @@
+import type { NativeFlowMessage, NativeFlowState, NativeParams, NativeLoginOptions } from '../../types';
+import { DestroyRef, Injectable, inject, signal } from '@angular/core';
+import { FallbackError } from '@strivacity/sdk-core/utils/errors';
+import { unflattenObject } from '@strivacity/sdk-core/utils';
+import { StrivacityAuthService } from './auth.service';
+
+@Injectable()
+export class StrivacityNativeLoginService {
+	private readonly authService = inject(StrivacityAuthService);
+	private readonly sdk = this.authService.sdk;
+	private readonly abortController = new AbortController();
+	private options: NativeLoginOptions = {};
+
+	private readonly loadingSignal = signal(true);
+	private readonly formsSignal = signal<Record<string, Record<string, unknown>>>({});
+	private readonly messagesSignal = signal<Record<string, Record<string, NativeFlowMessage>>>({});
+	private readonly stateSignal = signal<Partial<NativeFlowState>>({});
+
+	readonly loading = this.loadingSignal.asReadonly();
+	readonly forms = this.formsSignal.asReadonly();
+	readonly messages = this.messagesSignal.asReadonly();
+	readonly state = this.stateSignal.asReadonly();
+
+	constructor() {
+		inject(DestroyRef).onDestroy(() => this.abortController.abort());
+	}
+
+	/**
+	 * Starts a native login flow session. Should be called once, from the page component that owns this service.
+	 *
+	 * @param {NativeLoginOptions} [options] - Optional options for the login session.
+	 */
+	async start(options: NativeLoginOptions = {}): Promise<void> {
+		this.options = options;
+
+		await this.sdk.init();
+
+		try {
+			await this.startSession(options.params);
+		} catch (error) {
+			if (error instanceof DOMException && error.name === 'AbortError') {
+				return;
+			}
+
+			this.sdk.logging?.error('Error fetching authorization URI', error as Error);
+			await this.options.onError?.(error as Error);
+			this.loadingSignal.set(false);
+		}
+	}
+
+	async submitForm(formId: string, customBody?: Record<string, unknown>): Promise<void> {
+		try {
+			this.loadingSignal.set(true);
+
+			const nextState = await this.sdk.submitForm(formId, customBody ?? unflattenObject(this.formsSignal()[formId] ?? {}));
+
+			if (nextState) {
+				await this.handleResponse(nextState);
+			}
+		} catch (error) {
+			if (error instanceof FallbackError) {
+				this.sdk.logging?.error('Fallback error occurred', error);
+				await this.options.onFallback?.(error);
+			} else {
+				this.sdk.logging?.error('Error submitting form', error as Error);
+				await this.options.onError?.(error as Error);
+			}
+		}
+	}
+
+	setFormValue(formId: string, widgetId: string, value: unknown): void {
+		const forms = { ...this.formsSignal() };
+
+		forms[formId] = { ...(forms[formId] ?? {}), [widgetId]: value === '' ? null : value };
+		this.formsSignal.set(forms);
+	}
+
+	setMessage(formId: string, widgetId: string, value: NativeFlowMessage): void {
+		const messages = { ...this.messagesSignal() };
+
+		messages[formId] = { ...(messages[formId] ?? {}), [widgetId]: value };
+		this.messagesSignal.set(messages);
+	}
+
+	triggerFallback(message?: string): void {
+		this.sdk.logging?.warn(message ? `Triggering fallback due to: ${message}` : 'Triggering fallback');
+
+		const hostedUrl = this.stateSignal().hostedUrl;
+
+		if (!hostedUrl) {
+			const error = new Error('No hosted URL provided');
+			this.sdk.logging?.error('Fallback error', error);
+			throw error;
+		}
+
+		void this.options.onFallback?.(new FallbackError(new URL(hostedUrl)));
+	}
+
+	triggerClose(): void {
+		this.sdk.logging?.debug('Triggering close');
+		void this.options.onClose?.();
+	}
+
+	private async startSession(loginParams: NativeParams = {}): Promise<void> {
+		try {
+			this.loadingSignal.set(true);
+
+			const nextState = await this.sdk.startSession(loginParams);
+
+			if (nextState) {
+				await this.handleResponse(nextState);
+			}
+		} catch (error) {
+			if (error instanceof FallbackError) {
+				this.sdk.logging?.error('Fallback error occurred', error);
+				await this.options.onFallback?.(error);
+			} else {
+				this.sdk.logging?.error('Error starting session', error as Error);
+				await this.options.onError?.(error as Error);
+			}
+		}
+	}
+
+	private async handleResponse(nextState: Partial<NativeFlowState>): Promise<void> {
+		if (this.sdk.session) {
+			return await this.options.onLogin?.(this.sdk.session);
+		}
+
+		const currentState = this.stateSignal();
+		const newState: NativeFlowState = {
+			hostedUrl: nextState.hostedUrl ?? currentState.hostedUrl,
+			finalizeUrl: nextState.finalizeUrl ?? currentState.finalizeUrl,
+			screen: nextState.screen ?? currentState.screen,
+			forms: nextState.forms ?? currentState.forms,
+			layout: nextState.layout ?? currentState.layout,
+			messages: nextState.messages ?? {},
+			branding: nextState.branding ?? currentState.branding,
+		};
+
+		if (newState.screen !== currentState.screen) {
+			const nextForms: Record<string, Record<string, unknown>> = {};
+			const nextMessages: Record<string, Record<string, NativeFlowMessage>> = {};
+
+			for (const form of newState.forms ?? []) {
+				nextForms[form.id] = {};
+				nextMessages[form.id] = {};
+			}
+
+			this.formsSignal.set(nextForms);
+			this.messagesSignal.set(nextMessages);
+		} else {
+			this.sdk.logging?.info(`Updating screen: ${newState.screen}`);
+		}
+
+		const nextMessageMap = { ...this.messagesSignal() };
+
+		for (const formId of Object.keys(newState.messages ?? {})) {
+			if (formId === 'global') {
+				await this.options.onGlobalMessage?.(newState.messages!.global!);
+			} else {
+				nextMessageMap[formId] = newState.messages![formId] ?? {};
+			}
+		}
+
+		this.messagesSignal.set(nextMessageMap);
+		this.stateSignal.set(newState);
+
+		if (!newState.finalizeUrl) {
+			this.loadingSignal.set(false);
+		}
+	}
+}

package/src/lib/storages.ts

@@ -0,0 +1,12 @@
+export {
+	COOKIE_CONTEXT,
+	COOKIE_CHUNK_SIZE,
+	createCacheAPIStorage,
+	createIndexedDBStorage,
+	createLocalStorage,
+	createMemoryStorage,
+	createServerMemoryStorage,
+	createSessionStorage,
+	createWorkerStorage,
+	handleWorkerStorageRequests,
+} from '@strivacity/sdk-core/storages';

package/src/lib/utils.ts

@@ -0,0 +1,39 @@
+import type { Provider, ModuleWithProviders } from '@angular/core';
+import type { AngularSDKInitConfig } from '../types';
+import { CUSTOM_ELEMENTS_SCHEMA, NgModule, InjectionToken } from '@angular/core';
+import { StrivacityAuthService } from './services/auth.service';
+
+export const STRIVACITY_SDK = new InjectionToken<AngularSDKInitConfig>('strivacity-sdk');
+
+/**
+ * Provides the Strivacity SDK configuration and the `StrivacityAuthService` as dependency injection providers.
+ *
+ * This function is used to supply the Strivacity SDK configuration to the application
+ * by binding it to the `STRIVACITY_SDK` token, and to register `StrivacityAuthService` as an injectable.
+ *
+ * @param {AngularSDKInitConfig} config The SDK configuration options.
+ * @returns {Provider[]} The providers to add to the application (or component) injector.
+ */
+export function provideStrivacity(config: AngularSDKInitConfig): Provider[] {
+	return [{ provide: STRIVACITY_SDK, useValue: config }, StrivacityAuthService];
+}
+
+@NgModule({
+	schemas: [CUSTOM_ELEMENTS_SCHEMA],
+})
+export class StrivacityAuthModule {
+	/**
+	 * Registers the Strivacity SDK configuration and the `StrivacityAuthService` as dependency injection providers.
+	 *
+	 * This is the `NgModule`-based equivalent of `provideStrivacity()`, for applications that still bootstrap via `NgModule`.
+	 *
+	 * @param {AngularSDKInitConfig} options The SDK configuration options.
+	 * @returns {ModuleWithProviders<StrivacityAuthModule>} The module along with its providers, to be imported once at the root of the application.
+	 */
+	static forRoot(options: AngularSDKInitConfig): ModuleWithProviders<StrivacityAuthModule> {
+		return {
+			ngModule: StrivacityAuthModule,
+			providers: [provideStrivacity(options)],
+		};
+	}
+}

package/src/server/errors.ts

@@ -0,0 +1 @@
+export * from '@strivacity/sdk-core/utils/errors';

package/src/server/index.ts

@@ -0,0 +1,6 @@
+export * from './errors';
+export * from './sdk';
+export * from './session';
+export * from './storages';
+export * from './types';
+export * from './utils';

package/src/server/ng-package.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "../../../../node_modules/ng-packagr/ng-package.schema.json",
+  "lib": {
+    "entryFile": "./index.ts"
+  }
+}

package/src/server/sdk.ts

@@ -0,0 +1,113 @@
+import type { AngularServerRequest, AngularServerSDK, AngularServerSDKInitConfig } from './types';
+import { Router } from 'express';
+import { createBaseServerSDK } from '@strivacity/sdk-core/server';
+import { applyResponse, toWebRequest } from './utils';
+
+function getRouteHandlers(base: ReturnType<typeof createBaseServerSDK<AngularServerRequest | undefined>>): Router {
+	const router = Router();
+
+	router.get('/login', async (req, res, next) => {
+		try {
+			const response = await base.handleLogin(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/register', async (req, res, next) => {
+		try {
+			const response = await base.handleRegister(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/callback', async (req, res, next) => {
+		try {
+			const response = await base.handleCallback(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/refresh', async (req, res, next) => {
+		try {
+			const response = await base.handleRefresh(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/revoke', async (req, res, next) => {
+		try {
+			const response = await base.handleRevoke(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/entry', async (req, res, next) => {
+		try {
+			const response = await base.handleEntry(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.get('/logout', async (req, res, next) => {
+		try {
+			const response = await base.handleLogout(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+	router.post('/backchannel-logout', async (req, res, next) => {
+		try {
+			const response = await base.handleBackChannelLogout(req);
+			await applyResponse(response, res);
+		} catch (error) {
+			next(error);
+		}
+	});
+
+	return router;
+}
+
+/**
+ * Creates the server-side Strivacity SDK: an Express router exposing the auth endpoints and session helpers that can be reused elsewhere on the server.
+ *
+ * @param {AngularServerSDKInitConfig} initConfig - The SDK configuration options.
+ * @returns {AngularServerSDK} The server-side SDK instance.
+ */
+export function createServerSDK(initConfig: AngularServerSDKInitConfig): AngularServerSDK {
+	const base = createBaseServerSDK<AngularServerRequest | undefined>(
+		{
+			toRequest: (req) => toWebRequest(req as AngularServerRequest),
+		},
+		initConfig,
+	);
+
+	return {
+		get options() {
+			return base.options;
+		},
+		handlers: getRouteHandlers(base),
+		getSession: (req) => base.getSession(req),
+		updateSession: (session, req) => base.updateSession(session, req),
+		refreshSession: (req) => base.refreshSession(req),
+		revokeSession: (req) => base.revokeSession(req),
+		getEntrySession: (entryUrl) => base.getEntrySession(entryUrl),
+		completeLogin: (params, req) => base.completeLogin(params, req),
+		logout: (postLogoutRedirectUri, req) => base.logout(postLogoutRedirectUri, req),
+		handleLogin: (req) => base.handleLogin(req),
+		handleRegister: (req) => base.handleRegister(req),
+		handleCallback: (req) => base.handleCallback(req),
+		handleRefresh: (req) => base.handleRefresh(req),
+		handleRevoke: (req) => base.handleRevoke(req),
+		handleEntry: (req) => base.handleEntry(req),
+		handleLogout: (req) => base.handleLogout(req),
+		handleBackChannelLogout: (req) => base.handleBackChannelLogout(req),
+		handler: (req) => base.handler(req),
+	};
+}

package/src/server/session.ts

@@ -0,0 +1,30 @@
+import type { EnvironmentProviders } from '@angular/core';
+import type { AngularServerSDK, SessionData } from './types';
+import { REQUEST, TransferState, inject, makeStateKey, provideAppInitializer } from '@angular/core';
+
+export const SESSION_TRANSFER_KEY = makeStateKey<SessionData | null>('sty.session');
+
+/**
+ * Loads the current session from the encrypted cookie storage (using Angular's `REQUEST` token) before the app
+ * renders, and hands it over to the client through `TransferState`, so `StrivacityAuthService` can hydrate without
+ * an extra round-trip or a loading flash.
+ *
+ * Add this to the server-only `ApplicationConfig` (e.g. `app.config.server.ts`), alongside `provideServerRendering()`.
+ *
+ * @param {AngularServerSDK | undefined} serverSdk - The server SDK instance created via `createServerSDK()`, or `undefined` when server-side sessions aren't configured (a no-op in that case).
+ * @returns {EnvironmentProviders} The providers to add to the server `ApplicationConfig`.
+ */
+export function provideStrivacityServerSession(serverSdk: AngularServerSDK | undefined): EnvironmentProviders {
+	return provideAppInitializer(async () => {
+		const request = inject(REQUEST);
+
+		if (!request || !serverSdk) {
+			return;
+		}
+
+		const transferState = inject(TransferState);
+		const session = await serverSdk.getSession(request);
+
+		transferState.set(SESSION_TRANSFER_KEY, session);
+	});
+}

package/src/server/storages.ts

@@ -0,0 +1,25 @@
+import type { ServerStorage, AngularServerRequest } from './types';
+import type { SDKStorage, SessionIdCookieStorageOptions } from '@strivacity/sdk-core/types';
+import { createSessionIdCookieStorage as createSessionIdCookieStorageBase } from '@strivacity/sdk-core/storages/server';
+import { toWebRequest } from './utils';
+
+export * from '@strivacity/sdk-core/storages';
+
+/**
+ * Creates a session storage that puts a random unique id value cookie on the client and keeping the actual session data in the given `storage`.
+ *
+ * @param {SDKStorage} storage - The storage used to persist session data, keyed by a randomly generated session id.
+ * @param {SessionIdCookieStorageOptions} [options] - Options for the session ID cookie, including default cookie attributes and a UUID generator function.
+ * @param {Partial<ServerCookieOptions>} [options.defaultCookieOptions] - Default cookie attributes for the session ID cookie.
+ * @param {() => string} [options.uuidGenerator] - Function to generate a new UUID for the session ID. Defaults to `() => crypto.randomUUID()`.
+ * @returns {ServerStorage} An object implementing the ServerStorage interface for managing sessions indexed by a session-id cookie.
+ */
+export function createSessionIdCookieStorage(storage: SDKStorage, options?: SessionIdCookieStorageOptions): ServerStorage {
+	return createSessionIdCookieStorageBase<AngularServerRequest>(
+		{
+			toRequest: (req) => toWebRequest(req),
+		},
+		storage,
+		options,
+	);
+}

package/src/server/types.ts

@@ -0,0 +1,32 @@
+import type { Request as ExpressRequest, Response as ExpressResponse, Router } from 'express';
+import type { BaseServerSDK, CookieOptions, LogoutTokenClaims, ServerSDKInitConfig, ServerSDKOptions, SDKStorage } from '@strivacity/sdk-core/types';
+
+export * from '@strivacity/sdk-core/types';
+
+export type AngularServerRequest = ExpressRequest | Request;
+
+export type AngularServerStorage = SDKStorage<
+	[req?: AngularServerRequest],
+	[req?: ExpressRequest, res?: ExpressResponse, cookieOptions?: CookieOptions],
+	[req?: ExpressRequest, res?: ExpressResponse, cookieOptions?: CookieOptions]
+> & {
+	deleteByLogoutToken?(token: LogoutTokenClaims): Promise<void>;
+};
+
+export type AngularServerSDKOptions<
+	Storage extends AngularServerStorage = AngularServerStorage,
+	StateStorage extends SDKStorage = SDKStorage,
+> = ServerSDKOptions<Storage, StateStorage>;
+
+export type AngularServerSDKInitConfig<
+	Storage extends AngularServerStorage = AngularServerStorage,
+	StateStorage extends SDKStorage = SDKStorage,
+> = ServerSDKInitConfig & Partial<AngularServerSDKOptions<Storage, StateStorage>>;
+
+export type AngularServerSDK<TEvent extends AngularServerRequest | undefined = AngularServerRequest | undefined> = BaseServerSDK<TEvent> & {
+	/**
+	 * The Express router exposing the authentication endpoints.
+	 * Mount it under `authUrlPrefix`, e.g. `app.use('/auth', sdk.router)`.
+	 */
+	readonly handlers: Router;
+};

package/src/server/utils.ts

@@ -0,0 +1,74 @@
+import type { Response as ExpressResponse } from 'express';
+import type { AngularServerRequest } from './types';
+import { Readable } from 'node:stream';
+
+export * from '@strivacity/sdk-core/utils';
+
+/**
+ * Converts an incoming Express request (or an already-standard `Request`, e.g. Angular's SSR `REQUEST` token) into a standard Web `Request`.
+ *
+ * @param {AngularServerRequest} req - The incoming request.
+ * @returns {Request} The equivalent Web `Request` object.
+ */
+export function toWebRequest(req: AngularServerRequest): Request {
+	if (req instanceof Request) {
+		return req;
+	}
+
+	const url = new URL(req.originalUrl, `${req.protocol}://${req.get('host')}`);
+	const headers = new Headers();
+
+	for (const [key, value] of Object.entries(req.headers)) {
+		if (value === undefined) {
+			continue;
+		}
+
+		for (const v of Array.isArray(value) ? value : [value]) {
+			headers.append(key, v);
+		}
+	}
+
+	const hasBody = req.method !== 'GET' && req.method !== 'HEAD';
+
+	return new Request(url, {
+		method: req.method,
+		headers,
+		...(hasBody ? { body: Readable.toWeb(req), duplex: 'half' } : {}),
+	} as RequestInit);
+}
+
+/**
+ * Writes a standard Web `Response` (built by the shared server SDK core) onto the Express response.
+ *
+ * @param {Response} response - The `Response` to write.
+ * @param {ExpressResponse} res - The Express response to write to.
+ */
+export async function applyResponse(response: Response, res: ExpressResponse): Promise<void> {
+	res.status(response.status);
+
+	for (const [key, value] of response.headers.entries()) {
+		if (key.toLowerCase() === 'set-cookie') {
+			continue;
+		}
+
+		res.setHeader(key, value);
+	}
+
+	const setCookies = response.headers.getSetCookie();
+
+	if (setCookies.length) {
+		res.setHeader('set-cookie', setCookies);
+	}
+
+	if (!response.body) {
+		res.end();
+		return;
+	}
+
+	await new Promise<void>((resolve, reject) => {
+		Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0])
+			.pipe(res)
+			.on('finish', resolve)
+			.on('error', reject);
+	});
+}