@leancodepl/kratos 8.4.0 → 8.5.1

package/index.cjs.js

@@ -7,7 +7,23 @@ var jsxRuntime = require('react/jsx-runtime');
 var rxjs = require('rxjs');
 var yn = require('yn');
 
-function createKratosClient(configuration) {
+/**
+ * Creates Ory Kratos FrontendApi client with axios and credentials configuration.
+ * 
+ * Initializes a Kratos client for browser-based applications with automatic
+ * cookie handling and CORS support for authentication flows.
+ * 
+ * @param configuration - Kratos client configuration parameters
+ * @returns Configured FrontendApi instance for Kratos operations
+ * @example
+ * ```typescript
+ * import { createKratosClient } from '@leancodepl/kratos';
+ * 
+ * const kratosClient = createKratosClient({
+ *   basePath: 'https://auth.example.com'
+ * });
+ * ```
+ */ function createKratosClient(configuration) {
     return new client.FrontendApi(new client.Configuration(configuration), undefined, axios.create({
         withCredentials: true
     }));
@@ -151,7 +167,24 @@ var kratosContext = /*#__PURE__*/ react.createContext({
     },
     excludeScripts: false
 });
-function useKratosContext() {
+/**
+ * Access Kratos context data with components and error handling.
+ * 
+ * Retrieves the current Kratos context including UI components, error handlers,
+ * and configuration. Throws error if components are not initialized.
+ * 
+ * @returns Kratos context data with initialized components
+ * @throws Error when Kratos context components are not initialized
+ * @example
+ * ```typescript
+ * import { useKratosContext } from '@leancodepl/kratos';
+ * 
+ * function LoginComponent() {
+ *   const { components, useHandleFlowError } = useKratosContext();
+ *   // Use components and error handling...
+ * }
+ * ```
+ */ function useKratosContext() {
     var context = react.useContext(kratosContext);
     if (context.components === undefined) {
         throw new Error("Kratos context components were not initialized");
@@ -838,7 +871,30 @@ function _object_spread$g(target) {
     }
     return target;
 }
-function KratosContextProvider(param) {
+/**
+ * Provides Kratos context to child components with customizable configuration.
+ * 
+ * Sets up the React context for Kratos integration, allowing customization of
+ * UI components, error handling, and script loading behavior.
+ * 
+ * @param components - Partial override of default Kratos UI components
+ * @param useHandleFlowError - Custom error handler for authentication flows
+ * @param excludeScripts - Whether to exclude script node execution
+ * @param children - Child React components
+ * @returns JSX element providing Kratos context
+ * @example
+ * ```typescript
+ * import { KratosContextProvider } from '@leancodepl/kratos';
+ * 
+ * function App() {
+ *   return (
+ *     <KratosContextProvider>
+ *       <LoginPage />
+ *     </KratosContextProvider>
+ *   );
+ * }
+ * ```
+ */ function KratosContextProvider(param) {
     var _param_components = param.components, components = _param_components === void 0 ? {} : _param_components, useHandleFlowError = param.useHandleFlowError, excludeScripts = param.excludeScripts, children = param.children;
     var _useContext = react.useContext(kratosContext), baseComponents = _useContext.components, baseUseHandleFlowError = _useContext.useHandleFlowError, baseExcludeScripts = _useContext.excludeScripts;
     var value = react.useMemo(function() {
@@ -916,7 +972,28 @@ function _define_property$g(obj, key, value) {
     }
     return obj;
 }
-var BaseSessionManager = /*#__PURE__*/ function() {
+/**
+ * Manages Kratos session state with RxJS observables for authentication status.
+ * 
+ * Provides reactive session management with automatic status checking, user identity
+ * tracking, and AAL (Authenticator Assurance Level) handling for multi-factor authentication.
+ * 
+ * @param authUrl - Base URL for Kratos authentication endpoints
+ * @param loginRoute - Application route for login page
+ * @example
+ * ```typescript
+ * import { BaseSessionManager } from '@leancodepl/kratos';
+ * 
+ * const sessionManager = new BaseSessionManager(
+ *   'https://auth.example.com',
+ *   '/login'
+ * );
+ * 
+ * sessionManager.isLoggedIn.subscribe(loggedIn => {
+ *   console.log('User logged in:', loggedIn);
+ * });
+ * ```
+ */ var BaseSessionManager = /*#__PURE__*/ function() {
     function BaseSessionManager(authUrl, loginRoute) {
         var _this = this;
         _class_call_check(this, BaseSessionManager);
@@ -1385,7 +1462,29 @@ function _unsupported_iterable_to_array$6(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$6(o, minLen);
 }
-function useReauthenticationFlow(param) {
+/**
+ * Manages Kratos reauthentication flow for elevated security operations.
+ * 
+ * Handles reauthentication flow creation and submission for operations requiring
+ * fresh authentication, such as changing passwords or accessing sensitive data.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param onReauthenticated - Callback executed with session after successful reauthentication
+ * @returns Object with current flow and submit function
+ * @example
+ * ```typescript
+ * import { useReauthenticationFlow } from '@leancodepl/kratos';
+ * 
+ * function ReauthForm() {
+ *   const { flow, submit } = useReauthenticationFlow({
+ *     kratosClient,
+ *     onReauthenticated: (session) => navigate('/secure-area')
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useReauthenticationFlow(param) {
     var kratosClient = param.kratosClient, onReauthenticated = param.onReauthenticated;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array$5(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -1581,7 +1680,33 @@ function _unsupported_iterable_to_array$5(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$5(o, minLen);
 }
-function useRecoveryFlow(param) {
+/**
+ * Manages Kratos account recovery flow state and form submission.
+ * 
+ * Handles recovery flow creation, retrieval, and submission with automatic error handling,
+ * URL parameter management, and continue-with callbacks for post-recovery actions.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param onSessionAlreadyAvailable - Callback when session already exists
+ * @param onContinueWith - Optional callback for post-recovery actions
+ * @param searchParams - URL search parameters for flow state
+ * @param updateSearchParams - Function to update URL search parameters
+ * @returns Object with current flow, submit function, and recovery status
+ * @example
+ * ```typescript
+ * import { useRecoveryFlow } from '@leancodepl/kratos';
+ * 
+ * function RecoveryForm() {
+ *   const { flow, submit, isRecovering } = useRecoveryFlow({
+ *     kratosClient,
+ *     onSessionAlreadyAvailable: () => navigate('/dashboard'),
+ *     updateSearchParams: (params) => setSearchParams(params)
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useRecoveryFlow(param) {
     var kratosClient = param.kratosClient, onSessionAlreadyAvailable = param.onSessionAlreadyAvailable, onContinueWith = param.onContinueWith, _param_searchParams = param.searchParams, searchParams = _param_searchParams === void 0 ? {} : _param_searchParams, updateSearchParams = param.updateSearchParams;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array$4(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -1805,7 +1930,33 @@ function _unsupported_iterable_to_array$4(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$4(o, minLen);
 }
-function useSettingsFlow(param) {
+/**
+ * Manages Kratos user settings flow state and form submission.
+ * 
+ * Handles settings flow creation, retrieval, and submission for profile updates,
+ * password changes, and security settings management.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param params - Optional Axios request parameters
+ * @param onContinueWith - Optional callback for post-settings actions
+ * @param searchParams - URL search parameters for flow state
+ * @param updateSearchParams - Function to update URL search parameters
+ * @returns Object with current flow and submit function
+ * @example
+ * ```typescript
+ * import { useSettingsFlow } from '@leancodepl/kratos';
+ * 
+ * function UserSettingsForm() {
+ *   const { flow, submit } = useSettingsFlow({
+ *     kratosClient,
+ *     onContinueWith: (actions) => console.log('Settings updated'),
+ *     updateSearchParams: (params) => setSearchParams(params)
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useSettingsFlow(param) {
     var kratosClient = param.kratosClient, params = param.params, onContinueWith = param.onContinueWith, _param_searchParams = param.searchParams, searchParams = _param_searchParams === void 0 ? {} : _param_searchParams, updateSearchParams = param.updateSearchParams;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array$3(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -2032,7 +2183,35 @@ function _unsupported_iterable_to_array$3(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$3(o, minLen);
 }
-function useLoginFlow(param) {
+/**
+ * Manages Kratos login flow state and form submission.
+ * 
+ * Handles login flow creation, retrieval, and submission with automatic error handling,
+ * URL parameter management, and session callbacks. Supports multi-factor authentication
+ * and refresh flows.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param returnTo - URL to redirect after successful login
+ * @param onLoggedIn - Callback executed when user successfully logs in
+ * @param onSessionAlreadyAvailable - Callback when session already exists
+ * @param searchParams - URL search parameters for flow state
+ * @param updateSearchParams - Function to update URL search parameters
+ * @returns Object with current flow and submit function
+ * @example
+ * ```typescript
+ * import { useLoginFlow } from '@leancodepl/kratos';
+ * 
+ * function LoginForm() {
+ *   const { flow, submit } = useLoginFlow({
+ *     kratosClient,
+ *     onLoggedIn: (session) => navigate('/dashboard'),
+ *     updateSearchParams: (params) => setSearchParams(params)
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useLoginFlow(param) {
     var kratosClient = param.kratosClient, returnTo = param.returnTo, onLoggedIn = param.onLoggedIn, onSessionAlreadyAvailable = param.onSessionAlreadyAvailable, _param_searchParams = param.searchParams, searchParams = _param_searchParams === void 0 ? {} : _param_searchParams, updateSearchParams = param.updateSearchParams;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array$2(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -2266,7 +2445,33 @@ function _unsupported_iterable_to_array$2(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$2(o, minLen);
 }
-function useRegisterFlow(param) {
+/**
+ * Manages Kratos registration flow state and form submission.
+ * 
+ * Handles registration flow creation, retrieval, and submission with automatic error handling,
+ * URL parameter management, and continue-with callbacks for post-registration actions.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param onSessionAlreadyAvailable - Callback when session already exists
+ * @param onContinueWith - Optional callback for post-registration actions
+ * @param searchParams - URL search parameters for flow state
+ * @param updateSearchParams - Function to update URL search parameters
+ * @returns Object with current flow, submit function, and registration status
+ * @example
+ * ```typescript
+ * import { useRegisterFlow } from '@leancodepl/kratos';
+ * 
+ * function RegisterForm() {
+ *   const { flow, submit, isRegistered } = useRegisterFlow({
+ *     kratosClient,
+ *     onSessionAlreadyAvailable: () => navigate('/dashboard'),
+ *     updateSearchParams: (params) => setSearchParams(params)
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useRegisterFlow(param) {
     var kratosClient = param.kratosClient, onSessionAlreadyAvailable = param.onSessionAlreadyAvailable, onContinueWith = param.onContinueWith, _param_searchParams = param.searchParams, searchParams = _param_searchParams === void 0 ? {} : _param_searchParams, updateSearchParams = param.updateSearchParams;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array$1(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -2444,7 +2649,33 @@ function _unsupported_iterable_to_array$1(o, minLen) {
     if (n === "Map" || n === "Set") return Array.from(n);
     if (n === "Arguments" || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(n)) return _array_like_to_array$1(o, minLen);
 }
-function useVerificationFlow(param) {
+/**
+ * Manages Kratos email/phone verification flow state and form submission.
+ * 
+ * Handles verification flow creation, retrieval, and submission with automatic error handling,
+ * URL parameter management, and verification status tracking.
+ * 
+ * @param initialFlowId - Optional initial flow ID to start with
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param onVerified - Callback executed when verification is successful
+ * @param searchParams - URL search parameters for flow state
+ * @param updateSearchParams - Function to update URL search parameters
+ * @returns Object with current flow, submit function, and reset function
+ * @example
+ * ```typescript
+ * import { useVerificationFlow } from '@leancodepl/kratos';
+ * 
+ * function VerifyEmailForm() {
+ *   const { flow, submit, reset } = useVerificationFlow({
+ *     kratosClient,
+ *     onVerified: () => navigate('/dashboard'),
+ *     updateSearchParams: (params) => setSearchParams(params)
+ *   });
+ * 
+ *   return <form onSubmit={submit}>...</form>;
+ * }
+ * ```
+ */ function useVerificationFlow(param) {
     var initialFlowId = param.initialFlowId, kratosClient = param.kratosClient, onVerified = param.onVerified, _param_searchParams = param.searchParams, searchParams = _param_searchParams === void 0 ? {} : _param_searchParams, updateSearchParams = param.updateSearchParams;
     var useHandleFlowError = useKratosContext().useHandleFlowError;
     var _useState = _sliced_to_array(react.useState(), 2), flow = _useState[0], setFlow = _useState[1];
@@ -2658,7 +2889,31 @@ function _ts_generator(thisArg, body) {
         };
     }
 }
-function useLogoutFlow(param) {
+/**
+ * Manages Kratos user logout flow with callback support.
+ * 
+ * Provides a logout function that creates and executes logout flow,
+ * handling token invalidation and redirect logic.
+ * 
+ * @param kratosClient - Configured Kratos FrontendApi client
+ * @param returnTo - Optional URL to redirect after logout
+ * @param onLoggedOut - Optional callback executed after successful logout
+ * @returns Object with logout function
+ * @example
+ * ```typescript
+ * import { useLogoutFlow } from '@leancodepl/kratos';
+ * 
+ * function LogoutButton() {
+ *   const { logout } = useLogoutFlow({
+ *     kratosClient,
+ *     returnTo: '/login',
+ *     onLoggedOut: () => console.log('User logged out')
+ *   });
+ * 
+ *   return <button onClick={logout}>Logout</button>;
+ * }
+ * ```
+ */ function useLogoutFlow(param) {
     var kratosClient = param.kratosClient, returnTo = param.returnTo, onLoggedOut = param.onLoggedOut;
     var logout = react.useCallback(/*#__PURE__*/ _async_to_generator(function() {
         var flow;
@@ -3898,10 +4153,48 @@ function mkCard(flowType) {
         }, props));
     };
 }
-var LoginCard = mkCard("login");
-var VerificationCard = mkCard("verification");
-var RegistrationCard = mkCard("registration");
-var RecoveryCard = mkCard("recovery");
+/**
+ * Pre-built login card component for Kratos login flows.
+ * 
+ * Renders a complete login form with support for password, passkey, OIDC,
+ * multi-factor authentication, and identifier-first flows.
+ * 
+ * @param flow - Kratos login flow object
+ * @param onSubmit - Form submission handler
+ * @param className - Optional CSS class name
+ * @returns JSX element with login form
+ */ var LoginCard = mkCard("login");
+/**
+ * Pre-built verification card component for Kratos verification flows.
+ * 
+ * Renders a complete verification form for email/phone verification processes.
+ * 
+ * @param flow - Kratos verification flow object
+ * @param onSubmit - Form submission handler
+ * @param className - Optional CSS class name
+ * @returns JSX element with verification form
+ */ var VerificationCard = mkCard("verification");
+/**
+ * Pre-built registration card component for Kratos registration flows.
+ * 
+ * Renders a complete registration form with support for profile fields,
+ * password, passkey, and OIDC registration methods.
+ * 
+ * @param flow - Kratos registration flow object
+ * @param onSubmit - Form submission handler
+ * @param className - Optional CSS class name
+ * @returns JSX element with registration form
+ */ var RegistrationCard = mkCard("registration");
+/**
+ * Pre-built recovery card component for Kratos account recovery flows.
+ * 
+ * Renders a complete recovery form for password reset and account recovery processes.
+ * 
+ * @param flow - Kratos recovery flow object
+ * @param onSubmit - Form submission handler
+ * @param className - Optional CSS class name
+ * @returns JSX element with recovery form
+ */ var RecoveryCard = mkCard("recovery");
 // the user might need to logout on the second factor page.
 function isLoggedIn(flow) {
     if ("requested_aal" in flow && flow.requested_aal === client.AuthenticatorAssuranceLevel.Aal2) {
@@ -4279,7 +4572,32 @@ function TotpSettingsSection(param) {
     });
 }
 
-function UserSettingsCard(param) {
+/**
+ * Pre-built settings card component for Kratos settings flows.
+ * 
+ * Renders different settings sections based on flow type: profile, password,
+ * passkey, TOTP, lookup secrets, or OIDC settings management.
+ * 
+ * @param flow - Kratos settings flow object
+ * @param flowType - Type of settings flow to render
+ * @param onSubmit - Form submission handler
+ * @param className - Optional CSS class name
+ * @returns JSX element with settings form or null if flow type unavailable
+ * @example
+ * ```typescript
+ * import { UserSettingsCard } from '@leancodepl/kratos';
+ * 
+ * function ProfileSettings() {
+ *   return (
+ *     <UserSettingsCard
+ *       flow={settingsFlow}
+ *       flowType="profile"
+ *       onSubmit={handleSubmit}
+ *     />
+ *   );
+ * }
+ * ```
+ */ function UserSettingsCard(param) {
     var flow = param.flow, flowType = param.flowType, onSubmit = param.onSubmit, className = param.className;
     var _useKratosContext = useKratosContext(), _useKratosContext_components = _useKratosContext.components, ProfileSettingsSectionWrapper = _useKratosContext_components.ProfileSettingsSectionWrapper, PasswordSettingsSectionWrapper = _useKratosContext_components.PasswordSettingsSectionWrapper, WebAuthnSettingsSectionWrapper = _useKratosContext_components.WebAuthnSettingsSectionWrapper, LookupSecretSettingsSectionWrapper = _useKratosContext_components.LookupSecretSettingsSectionWrapper, OidcSettingsSectionWrapper = _useKratosContext_components.OidcSettingsSectionWrapper, TotpSettingsSectionWrapper = _useKratosContext_components.TotpSettingsSectionWrapper, UiMessages = _useKratosContext_components.UiMessages, excludeScripts = _useKratosContext.excludeScripts;
     useScriptNodes({
@@ -4318,6 +4636,7 @@ function UserSettingsCard(param) {
                 TotpSettingsSectionWrapper: TotpSettingsSectionWrapper
             });
         }
+        return null;
     }();
     if (!$flow) return null;
     return /*#__PURE__*/ jsxRuntime.jsxs(UserAuthForm, {