chore(oauth): adds method documentation and types refactoring (#772)

* chore(oauth): adds method documentation and types refactoring

* chore(oauth): make use of interfaces since it is the recommendation

Author: ArtieReus

.changeset/silly-hornets-invite.md

@@ -0,0 +1,5 @@
+---
+"@cloudoperators/juno-oauth": patch
+---
+
+Improving types and addind method documentation

packages/oauth/src/tokenSession.ts

@@ -67,6 +67,37 @@ interface TokenSessionParams {
   onUpdate: (_state: TokenSessionState) => void
 }
 
+/**
+ * Creates a token-based session where the provided token is validated, parsed,
+ * and extended with the specified options. The resulting authentication state
+ * is returned when the callback method is triggered.
+ *
+ * @param params.token - The token to be validated, parsed, and extended with the given options.
+ * @param params.onUpdate - A callback function invoked on login and logout events.
+ * @param params.initialLogin - A boolean indicating whether the login should be performed immediately
+ *                              on the first call, triggering the callback method.
+ * @param params.options - Additional options to extend the token data.
+ *                         See the following documentation for details on the returned auth data structure
+ *                         and usage of the `options` parameter:
+ *                         [Juno Auth Data Documentation](https://github.com/cloudoperators/juno/blob/main/packages/oauth/README.md#auth-data)
+ *
+ * @returns An object containing the following methods:
+ * - `login()`: Triggers the login process.
+ * - `logout()`: Triggers the logout process.
+ * - `currentState()`: Returns the current authentication state.
+ *
+ * @example
+ * ```typescript
+ * const session = tokenSession({
+ *   token: jwtToken,
+ *   options: {
+ *     groups: [`organization:${demoOrg}`],
+ *   },
+ *   onUpdate: (authData) => {
+ *     saveAuthData(authData);
+ *   },
+ * });
+ */
 export default function tokenSession(params: TokenSessionParams): TokenSessionReturnType {
   const { token, onUpdate, initialLogin, options } = params || {}