@leancodepl/kratos 9.2.0 → 9.3.0

package/README.md

@@ -71,16 +71,24 @@ Manages Ory Kratos session and identity state with React Query integration.
 To use the library, you need to create new instance of Kratos client with `mkKratos` factory:
 
 ```typescript
-// kratosService.ts
-
-import { queryClient } from "./queryService"
+// traits.ts
 
-const traitsConfig = {
+export const traitsConfig = {
   Email: { trait: "email", type: "string" },
   GivenName: { trait: "given_name", type: "string" },
   RegulationsAccepted: { trait: "regulations_accepted", type: "boolean" },
 } as const
 
+export type AuthTraitsConfig = typeof traitsConfig
+```
+
+```typescript
+// kratosService.ts
+
+import { environment } from "./environments"
+import { queryClient } from "./queryService"
+import { traitsConfig } from "./traits"
+
 const {
   session: { sessionManager },
   providers: { KratosProviders },
@@ -99,9 +107,6 @@ export { KratosProviders }
 
 // flows
 export { LoginFlow, RecoveryFlow, RegistrationFlow, SettingsFlow, useLogout, VerificationFlow }
-
-// traits
-export type AuthTraitsConfig = typeof traitsConfig
 ```
 
 And then wrap your app with `KratosProviders` from `mkKratos`:
@@ -128,6 +133,74 @@ function App() {
 }
 ```
 
+### Extending session manager
+
+You can add new functionalities to the session manager by extending `BaseSessionManager` class:
+
+```typescript
+// session.ts
+
+import { BaseSessionManager } from "@leancodepl/kratos"
+import { queryClient } from "./queryService"
+import type { AuthTraitsConfig } from "./traits"
+
+export class SessionManager extends BaseSessionManager<AuthTraitsConfig> {
+  getTraits = async () => {
+    const identity = await this.getIdentity()
+
+    return identity?.traits
+  }
+
+  getEmail = async () => {
+    const traits = await this.getTraits()
+
+    return traits?.email
+  }
+
+  // Hooks for React components
+
+  useTraits = () => {
+    const { identity, isLoading, error } = this.useIdentity()
+
+    return {
+      traits: identity?.traits,
+      isLoading,
+      error,
+    }
+  }
+
+  useEmail = () => {
+    const { traits, isLoading, error } = this.useTraits()
+
+    return {
+      email: traits?.email,
+      isLoading,
+      error,
+    }
+  }
+}
+```
+
+```typescript
+// kratosService.ts
+
+import { environment } from "./environments"
+import { queryClient } from "./queryService"
+import { SessionManager } from "./session"
+import { traitsConfig } from "./traits"
+
+const {
+  session: { sessionManager },
+  providers: { KratosProviders },
+  flows: { LoginFlow, RegistrationFlow, SettingsFlow, VerificationFlow, RecoveryFlow, useLogout },
+} = mkKratos({
+  queryClient,
+  basePath: environment.authUrl,
+  traits: traitsConfig,
+  SessionManager,
+})
+```
+
 ### Session Management
 
 ```tsx
@@ -161,6 +234,7 @@ import { LoginFlow } from "./kratosService"
 function LoginPage() {
   return (
     <LoginFlow
+      loaderComponent={Loader}
       chooseMethodForm={ChooseMethodForm}
       secondFactorForm={SecondFactorForm}
       secondFactorEmailForm={SecondFactorEmailForm}
@@ -352,7 +426,7 @@ export const Input = ({ errors, ...props }: InputProps) => (
 ```tsx
 import { loginFlow } from "@leancodepl/kratos"
 import { LoginFlow, getErrorMessage } from "./kratosService"
-import type { AuthTraitsConfig } from "./kratosService"
+import type { AuthTraitsConfig } from "./traits"
 
 function LoginPage() {
   return (
@@ -364,28 +438,30 @@ function LoginPage() {
 }
 
 function ChooseMethodForm(props: loginFlow.ChooseMethodFormProps) {
-  if (props.isLoading) {
-    return <p>Loading login methods...</p>
-  }
-
-  const { Password, Google, Passkey, Apple, Facebook, errors, isSubmitting, isValidating } = props
+  const { errors, isSubmitting, isValidating } = props
 
   if (props.isRefresh) {
-    const { identifier } = props
+    const { passwordFields, Google, Passkey, Apple, Facebook, identifier } = props
 
     return (
       <div>
-        <h2>
-          Complete login process as <strong>{identifier}</strong>
-        </h2>
-
-        {Password && (
-          <Password>
-            <input placeholder="Password" />
-          </Password>
+        {identifier && (
+          <h2>
+            Complete login process as <strong>{identifier}</strong>
+          </h2>
         )}
 
-        <button type="submit">Login</button>
+        {passwordFields && (
+          <>
+            <passwordFields.Password>
+              <input placeholder="Password" />
+            </passwordFields.Password>
+
+            <passwordFields.Submit>
+              <button>Login</button>
+            </passwordFields.Submit>
+          </>
+        )}
 
         {Google && (
           <Google>
@@ -422,47 +498,43 @@ function ChooseMethodForm(props: loginFlow.ChooseMethodFormProps) {
     )
   }
 
-  const { Identifier } = props
+  const {
+    passwordFields: { Identifier, Password, Submit },
+    Google,
+    Passkey,
+    Apple,
+    Facebook,
+  } = props
 
   return (
     <div>
-      {Identifier && (
-        <Identifier>
-          <input placeholder="Identifier" />
-        </Identifier>
-      )}
+      <Identifier>
+        <input placeholder="Identifier" />
+      </Identifier>
 
-      {Password && (
-        <Password>
-          <input placeholder="Password" />
-        </Password>
-      )}
+      <Password>
+        <input placeholder="Password" />
+      </Password>
 
-      <button type="submit">Login</button>
+      <Submit>
+        <button>Login</button>
+      </Submit>
 
-      {Google && (
-        <Google>
-          <button>Sign in with Google</button>
-        </Google>
-      )}
+      <Google>
+        <button>Sign in with Google</button>
+      </Google>
 
-      {Apple && (
-        <Apple>
-          <button>Sign in with Apple</button>
-        </Apple>
-      )}
+      <Apple>
+        <button>Sign in with Apple</button>
+      </Apple>
 
-      {Facebook && (
-        <Facebook>
-          <button>Sign in with Facebook</button>
-        </Facebook>
-      )}
+      <Facebook>
+        <button>Sign in with Facebook</button>
+      </Facebook>
 
-      {Passkey && (
-        <Passkey>
-          <button>Sign in with Passkey</button>
-        </Passkey>
-      )}
+      <Passkey>
+        <button>Sign in with Passkey</button>
+      </Passkey>
 
       {errors && errors.length > 0 && (
         <div>
@@ -481,7 +553,7 @@ function ChooseMethodForm(props: loginFlow.ChooseMethodFormProps) {
 ```tsx
 import { registrationFlow } from "@leancodepl/kratos"
 import { RegistrationFlow, getErrorMessage } from "./kratosService"
-import type { AuthTraitsConfig } from "./kratosService"
+import type { AuthTraitsConfig } from "./traits"
 
 function RegisterPage() {
   return (