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

package/src/client/index.ts

@@ -0,0 +1,8 @@
+export * from '@strivacity/sdk-core/flows';
+export * from '@strivacity/sdk-core/handlers';
+export * from '@strivacity/sdk-core/utils';
+export * from './components.svelte';
+export * from './hooks.svelte';
+export * from './storages';
+export * from './types';
+export * from './utils';

package/src/client/storages.ts

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

package/src/client/types.ts

@@ -0,0 +1,299 @@
+import type {
+	IdTokenClaims,
+	RedirectFlow,
+	PopupFlow,
+	NativeFlow,
+	EmbeddedFlow,
+	initFlow,
+	NativeParams,
+	NativeFlowState,
+	SessionData,
+	NativeFlowMessage,
+	SDKInitConfig,
+} from '@strivacity/sdk-core';
+import type { FallbackError } from '@strivacity/sdk-core/utils';
+
+export * from '@strivacity/sdk-core/types';
+
+export type SDKContext<Flow extends RedirectFlow | PopupFlow | NativeFlow | EmbeddedFlow> = {
+	/**
+	 * The underlying Strivacity SDK flow instance.
+	 */
+	readonly sdk: Flow;
+
+	/**
+	 * A boolean indicating whether the SDK is still loading.
+	 */
+	readonly loading: boolean;
+
+	/**
+	 * BCP 47 language code representing the current language of the SDK.
+	 */
+	readonly language: string;
+
+	/**
+	 * A boolean ref indicating whether the user is authenticated.
+	 */
+	readonly isAuthenticated: boolean;
+
+	/**
+	 * The claims from the ID token, if available.
+	 */
+	readonly idTokenClaims: IdTokenClaims | null;
+
+	/**
+	 * The access token, if available.
+	 */
+	readonly accessToken: string | null;
+
+	/**
+	 * The refresh token, if available.
+	 */
+	readonly refreshToken: string | null;
+
+	/**
+	 * A boolean ref indicating whether the access token has expired.
+	 */
+	readonly accessTokenExpired: boolean;
+
+	/**
+	 * The expiration date of the access token, if available.
+	 */
+	readonly accessTokenExpirationDate: number | null;
+
+	/**
+	 * Subscribes to a specific SDK event.
+	 */
+	subscribeToEvent: Flow['subscribeToEvent'];
+
+	/**
+	 * Subscribes to all SDK events.
+	 */
+	subscribeToAllEvents: Flow['subscribeToAllEvents'];
+
+	/**
+	 * Checks whether the user is currently authenticated, optionally triggering a token refresh.
+	 */
+	checkAuthentication: Flow['checkAuthentication'];
+
+	/**
+	 * Initializes the SDK, loading metadata and restoring any persisted session.
+	 */
+	init: Flow['init'];
+
+	/**
+	 * Performs a token exchange using the provided parameters.
+	 */
+	tokenExchange: Flow['tokenExchange'];
+
+	/**
+	 * Handles the authentication callback by parsing the response from the given URL.
+	 */
+	handleCallback: Flow['handleCallback'];
+
+	/**
+	 * Refreshes the current access token using the refresh token.
+	 */
+	refresh: Flow['refresh'];
+
+	/**
+	 * Revokes the current tokens.
+	 */
+	revoke: Flow['revoke'];
+
+	/**
+	 * Logs the user out and optionally redirects to a post-logout URI.
+	 */
+	logout: Flow['logout'];
+
+	/**
+	 * Initiates the login flow.
+	 */
+	login: Flow['login'];
+
+	/**
+	 * Initiates the registration flow.
+	 */
+	register: Flow['register'];
+
+	/**
+	 * Handles the entry point URL of the authentication flow, typically used for embedded or native modes.
+	 */
+	entry: Flow['entry'];
+};
+
+export type SDKInstance = ReturnType<typeof initFlow>;
+
+export type LoginContext = {
+	/**
+	 * Whether a form submission or session initialization is in progress.
+	 */
+	loading: boolean;
+
+	/**
+	 * Current form field values, keyed by form ID then widget ID.
+	 */
+	forms: Record<string, Record<string, unknown>>;
+
+	/**
+	 * Current validation and info messages, keyed by form ID then widget ID.
+	 */
+	messages: Record<string, Record<string, NativeFlowMessage>>;
+
+	/**
+	 * The current login flow state returned by the backend.
+	 */
+	state: Partial<NativeFlowState>;
+
+	/**
+	 * Submits the form with the given ID and advances the login flow.
+	 *
+	 * @param formId - The ID of the form to submit.
+	 * @param customBody - Optional custom body to send with the form submission. If not provided, the current form values will be used.
+	 * @returns A promise that resolves when the form submission is complete.
+	 */
+	submitForm: (formId: string, customBody?: Record<string, unknown>) => Promise<void>;
+
+	/**
+	 * Redirects to the hosted login UI.
+	 *
+	 * @param message - Optional message to log before redirecting.
+	 * @returns A promise that resolves when the redirect is initiated.
+	 */
+	triggerFallback: (message?: string) => void;
+
+	/**
+	 * Signals that the login flow was closed by the user.
+	 */
+	triggerClose: () => void;
+
+	/**
+	 * Updates a single field value within a form before submission.
+	 *
+	 * @param formId - The ID of the form containing the field.
+	 * @param widgetId - The ID of the widget (field) to update.
+	 * @param value - The new value to set for the field.
+	 */
+	setFormValue: (formId: string, widgetId: string, value: unknown) => void;
+
+	/**
+	 * Sets a validation or info message on a specific widget.
+	 *
+	 * @param formId - The ID of the form containing the widget.
+	 * @param widgetId - The ID of the widget to set the message for.
+	 * @param value - The message to set, which can be a string or a structured NativeFlowMessage.
+	 */
+	setMessage: (formId: string, widgetId: string, value: NativeFlowMessage) => void;
+};
+
+export type StyAuthProviderProps = {
+	/**
+	 * The options to be used by the AuthProvider. These options are passed to the SDK during initialization.
+	 */
+	options: SDKInitConfig;
+
+	/**
+	 * A getter returning the session data to be used by the AuthProvider.
+	 *
+	 * Called reactively (inside a Svelte effect) whenever the returned value changes, so it should read from a
+	 * reactive source (e.g. a `$props()` field) rather than a plain snapshot. If not provided, the AuthProvider
+	 * will attempt to retrieve the session data from the SDK.
+	 */
+	session?: () => SessionData | null | undefined;
+};
+
+/**
+ * The reactive context value exposed to native login flow widgets via `useNativeLoginContext()` (key: `nativeFlowContext`).
+ */
+export type NativeFlowContextValue = {
+	/**
+	 * Whether a form submission or session initialization is in progress.
+	 */
+	loading: boolean;
+
+	/**
+	 * Current form field values, keyed by form ID then widget ID.
+	 */
+	forms: Record<string, Record<string, unknown>>;
+
+	/**
+	 * Current validation and info messages, keyed by form ID then widget ID.
+	 */
+	messages: Record<string, Record<string, NativeFlowMessage>>;
+
+	/**
+	 * The current login flow state returned by the backend.
+	 */
+	state: Partial<NativeFlowState>;
+
+	/**
+	 * Submits the form with the given ID and advances the login flow.
+	 *
+	 * @param formId - The ID of the form to submit.
+	 * @param customBody - Optional custom body to send with the form submission. If not provided, the current form values will be used.
+	 * @returns A promise that resolves when the form submission is complete.
+	 */
+	submitForm: (formId: string, customBody?: Record<string, unknown>) => Promise<void>;
+
+	/**
+	 * Redirects to the hosted login UI.
+	 *
+	 * @param message - Optional message to log before redirecting.
+	 */
+	triggerFallback: (message?: string) => void;
+
+	/**
+	 * Signals that the login flow was closed by the user.
+	 */
+	triggerClose: () => void;
+
+	/**
+	 * Updates a single field value within a form before submission.
+	 *
+	 * @param formId - The ID of the form containing the field.
+	 * @param widgetId - The ID of the widget (field) to update.
+	 * @param value - The new value to set for the field.
+	 */
+	setFormValue: (formId: string, widgetId: string, value: unknown) => void;
+
+	/**
+	 * Sets a validation or info message on a specific widget.
+	 *
+	 * @param formId - The ID of the form containing the widget.
+	 * @param widgetId - The ID of the widget to set the message for.
+	 * @param value - The message to set.
+	 */
+	setMessage: (formId: string, widgetId: string, value: NativeFlowMessage) => void;
+};
+
+export type UseNativeLoginOptions = {
+	/**
+	 * Optional parameters to be passed to the login session request. These parameters will be sent to the `authorizationUri` endpoint.
+	 */
+	params?: NativeParams;
+
+	/**
+	 * Called when the user successfully completes the login flow.
+	 */
+	onLogin?: (session: SessionData) => void | Promise<void>;
+
+	/**
+	 * Called when the fallback flow is triggered, typically due to an error or unsupported environment. Receives a `FallbackError` object containing the hosted URL to redirect to.
+	 */
+	onFallback?: (error: FallbackError) => void | Promise<void>;
+
+	/**
+	 * Called when the login flow is closed by the user.
+	 */
+	onClose?: () => void | Promise<void>;
+
+	/**
+	 * Called when an error occurs during the login session initialization or flow.
+	 */
+	onError?: (error: Error) => void | Promise<void>;
+
+	/**
+	 * Called when a global message is received during the login flow.
+	 */
+	onGlobalMessage?: (message: NativeFlowMessage) => void | Promise<void>;
+};

package/src/client/utils.ts

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

package/src/errors.ts

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

package/src/server/index.ts

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

package/src/server/sdk.ts

@@ -0,0 +1,77 @@
+import type { RequestEvent, Handle } from '@sveltejs/kit';
+import type { SessionData } from '@strivacity/sdk-core/types';
+import type { SvelteKitServerSDK, SvelteKitServerSDKInitConfig } from './types';
+import { redirect } from '@sveltejs/kit';
+import { isSessionExpired } from '@strivacity/sdk-core/utils';
+import { createBaseServerSDK } from '@strivacity/sdk-core/server';
+
+/**
+ * Creates the Strivacity server SDK for SvelteKit: session management, auth route handlers, and the `handle` hook used in `hooks.server.ts`.
+ *
+ * @param {SvelteKitServerSDKInitConfig} initConfig - The configuration options for initializing the server SDK.
+ * @returns {SvelteKitServerSDK} The initialized server SDK instance.
+ */
+export function createServerSDK(initConfig: SvelteKitServerSDKInitConfig): SvelteKitServerSDK {
+	const base = createBaseServerSDK<RequestEvent>(
+		{
+			toRequest: (event) => event.request,
+		},
+		initConfig,
+	);
+
+	async function requireSession(event: RequestEvent, guardOpts: { returnTo?: string } = {}): Promise<SessionData> {
+		let session = await base.getSession(event);
+
+		if (session && isSessionExpired(session) && session.refresh_token) {
+			try {
+				session = await base.refreshSession(event);
+			} catch {
+				session = null;
+			}
+		}
+
+		if (!session) {
+			const loginUrl = ['embedded', 'native'].includes(base.options.mode) ? base.options.loginUri : `${base.options.authUrlPrefix}/login`;
+			const uri = new URL(loginUrl, event.url.origin);
+			const returnTo = guardOpts.returnTo ?? `${event.url.pathname}${event.url.search}`;
+
+			if (returnTo) {
+				uri.searchParams.set('returnTo', returnTo);
+			}
+
+			redirect(302, uri);
+		}
+
+		return session;
+	}
+
+	const handle: Handle = async ({ event, resolve }) => {
+		const response = await base.handler(event);
+
+		return response ?? resolve(event);
+	};
+
+	return {
+		get options() {
+			return base.options;
+		},
+		handle,
+		requireSession,
+		getSession: (event) => base.getSession(event),
+		updateSession: (session, event) => base.updateSession(session, event),
+		refreshSession: (event) => base.refreshSession(event),
+		revokeSession: (event) => base.revokeSession(event),
+		getEntrySession: (entryUrl) => base.getEntrySession(entryUrl),
+		completeLogin: (params, event) => base.completeLogin(params, event),
+		logout: (postLogoutRedirectUri, event) => base.logout(postLogoutRedirectUri, event),
+		handleLogin: (event) => base.handleLogin(event),
+		handleRegister: (event) => base.handleRegister(event),
+		handleCallback: (event) => base.handleCallback(event),
+		handleRefresh: (event) => base.handleRefresh(event),
+		handleRevoke: (event) => base.handleRevoke(event),
+		handleEntry: (event) => base.handleEntry(event),
+		handleLogout: (event) => base.handleLogout(event),
+		handleBackChannelLogout: (event) => base.handleBackChannelLogout(event),
+		handler: (event) => base.handler(event),
+	};
+}

package/src/server/storages.ts

@@ -0,0 +1,22 @@
+import type { RequestEvent } from '@sveltejs/kit';
+import type { ServerStorage, SDKStorage, SessionIdCookieStorageOptions } from './types';
+import { createSessionIdCookieStorage as createSessionIdCookieStorageBase } from '@strivacity/sdk-core/storages/server';
+
+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 configuring the session-id cookie storage.
+ * @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<RequestEvent>(
+		{
+			toRequest: (event) => event.request,
+		},
+		storage,
+		options,
+	);
+}

package/src/server/types.ts

@@ -0,0 +1,49 @@
+import type { Handle, RequestEvent } from '@sveltejs/kit';
+import type {
+	ServerSDKOptions,
+	ServerSDKInitConfig,
+	SDKStorage,
+	SessionData,
+	CookieOptions,
+	LogoutTokenClaims,
+	BaseServerSDK,
+} from '@strivacity/sdk-core/types';
+
+export * from '@strivacity/sdk-core/types';
+
+export type SvelteKitServerStorage = SDKStorage<
+	[event?: RequestEvent],
+	[event?: RequestEvent, cookieOptions?: CookieOptions],
+	[event?: RequestEvent, cookieOptions?: CookieOptions]
+> & {
+	deleteByLogoutToken?(token: LogoutTokenClaims): Promise<void>;
+};
+
+export type SvelteKitServerSDKOptions<
+	Storage extends SvelteKitServerStorage = SvelteKitServerStorage,
+	StateStorage extends SDKStorage = SDKStorage,
+> = ServerSDKOptions<RequestEvent, Storage, StateStorage>;
+
+export type SvelteKitServerSDKInitConfig<
+	Storage extends SvelteKitServerStorage = SvelteKitServerStorage,
+	StateStorage extends SDKStorage = SDKStorage,
+> = ServerSDKInitConfig<RequestEvent> & Partial<SvelteKitServerSDKOptions<Storage, StateStorage>>;
+
+export type SvelteKitServerSDK = BaseServerSDK<RequestEvent> & {
+	/**
+	 * A SvelteKit `Handle` hook that intercepts and serves the `authUrlPrefix` auth routes.
+	 * Mount it in `src/hooks.server.ts`, optionally combined with your own hooks via `sequence()`.
+	 */
+	handle: Handle;
+
+	/**
+	 * Guard for `+page.server.ts`/`+layout.server.ts` `load()` functions: returns the current session, or throws a SvelteKit `redirect()` to the login page if unauthenticated.
+	 *
+	 * @param {RequestEvent} event - The SvelteKit request event.
+	 * @param {Object} [options] - Optional options for the session requirement.
+	 * @param {string} [options.returnTo] - Optional relative path to redirect to after login. Defaults to the current page.
+	 * @returns {Promise<SessionData>} A promise that resolves to the current session data if authenticated.
+	 * @throws {Redirect} Throws a SvelteKit `redirect()` to the login page if unauthenticated.
+	 */
+	requireSession(event: RequestEvent, options?: { returnTo?: string }): Promise<SessionData>;
+};

package/src/server/utils.ts

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

package/src/types.ts

@@ -0,0 +1,2 @@
+export * from './client/types';
+export * from './server/types';

package/svelte.config.js

@@ -0,0 +1,5 @@
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+
+export default {
+	preprocess: vitePreprocess(),
+};

package/testing/fixtures/AuthProviderHost.svelte

@@ -0,0 +1,29 @@
+<script lang="ts">
+	import { createStyAuthProvider } from '../../src/client/components.svelte';
+	import type { StyAuthProviderProps, SDKContext, RedirectFlow, PopupFlow, NativeFlow, EmbeddedFlow, SessionData } from '../../src/types';
+	import StrivacityConsumer from './StrivacityConsumer.svelte';
+
+	type Flow = RedirectFlow | PopupFlow | NativeFlow | EmbeddedFlow;
+
+	const { options, initialSession = null }: { options: StyAuthProviderProps['options']; initialSession?: SessionData | null } = $props();
+
+	let session = $state<SessionData | null | undefined>(initialSession);
+
+	const ctx: SDKContext<Flow> = createStyAuthProvider({ options, session: () => session });
+	let childInstance: { getContextValue: () => SDKContext<Flow> } | undefined;
+
+	export function getContextValue() {
+		return ctx;
+	}
+
+	export function setSession(value: SessionData | null | undefined) {
+		session = value;
+	}
+
+	// exposes what a descendant reads via useStrivacity(), to verify createStyAuthProvider's context reaches its children
+	export function getChildContextValue() {
+		return childInstance?.getContextValue();
+	}
+</script>
+
+<StrivacityConsumer bind:this={childInstance} />

package/testing/fixtures/Harness.svelte

@@ -0,0 +1,30 @@
+<script lang="ts">
+	import { setContext } from 'svelte';
+	import type { Component } from 'svelte';
+	import { STRIVACITY_SDK } from '../../src/client/hooks.svelte';
+	import type { SDKContext, RedirectFlow, PopupFlow, NativeFlow, EmbeddedFlow } from '../../src/types';
+
+	type Flow = RedirectFlow | PopupFlow | NativeFlow | EmbeddedFlow;
+
+	const {
+		context,
+		component: Child,
+		componentProps = {},
+		// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	}: { context?: SDKContext<Flow>; component: Component<any, any>; componentProps?: Record<string, unknown> } = $props();
+
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	let instance: any;
+
+	// setContext must run synchronously during this component's own initialization so the child
+	// component instantiated below can read it via getContext during its own initialization.
+	if (context) {
+		setContext(STRIVACITY_SDK, context);
+	}
+
+	export function getInstance() {
+		return instance;
+	}
+</script>
+
+<Child {...componentProps} bind:this={instance} />

package/testing/fixtures/NativeLoginConsumer.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+	import { useNativeLogin } from '../../src/client/hooks.svelte';
+	import type { UseNativeLoginOptions, LoginContext } from '../../src/types';
+	import NativeLoginContextConsumer from './NativeLoginContextConsumer.svelte';
+
+	const { options = {} }: { options?: UseNativeLoginOptions } = $props();
+
+	const login: LoginContext = useNativeLogin(options);
+	let childInstance: { getContextValue: () => LoginContext } | undefined;
+
+	export function getLogin() {
+		return login;
+	}
+
+	// exposes what a descendant widget sees via useNativeLoginContext(), to verify it resolves to the same context
+	export function getChildContext() {
+		return childInstance?.getContextValue();
+	}
+</script>
+
+<NativeLoginContextConsumer bind:this={childInstance} />

package/testing/fixtures/NativeLoginContextConsumer.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import { useNativeLoginContext } from '../../src/client/hooks.svelte';
+	import type { LoginContext } from '../../src/types';
+
+	const context: LoginContext = useNativeLoginContext();
+
+	export function getContextValue() {
+		return context;
+	}
+</script>

package/testing/fixtures/StrivacityConsumer.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+	import { useStrivacity } from '../../src/client/hooks.svelte';
+	import type { SDKContext, RedirectFlow, PopupFlow, NativeFlow, EmbeddedFlow } from '../../src/types';
+
+	const ctx: SDKContext<RedirectFlow | PopupFlow | NativeFlow | EmbeddedFlow> = useStrivacity();
+
+	export function getContextValue() {
+		return ctx;
+	}
+</script>