✅ refactor(auth): add decode_jwt/decode_jwt_async to Datasy; deprecate fs.decode (#50)

- Add AuthMixin (security/auth.py) with _active_key property and merged exception handling
- Add decode_jwt and decode_jwt_async methods to Datasy
- 🔴 Mark fs.decode and fs.decode_async as deprecated (FutureWarning)
- Add utils.py with deprecated() decorator (sync/async support)
- Update migration.py go_page for Flet 0.28.x and 0.80.x compatibility
- Update tests to use data.decode_jwt_async()
- 📝 Update docs: basic-jwt, route-protection, api/reference, showcase, migration guide, changelog

Author: Daxexs

docs/advanced/basic-jwt.md

@@ -115,7 +115,7 @@ Kzuz8LYM/PJmIWIBTo2mqDwp/Iv2EbMKw0Jjn0cgnZINs9UciQqhxX4R49I3
 -----END RSA PRIVATE KEY-----"""
 ```
 
-In this example we are going to do very similar with the [`Route-protection`](route-protection.md#example) example, we have only configured the `secret_key`, used the [`login`](route-protection.md#login) method `time_expiry` parameter and used the [`decode`](#decode) function of `FletEasy` to get the payload stored in the decoded client storage.
+In this example we are going to do very similar with the [`Route-protection`](route-protection.md#example) example, we have only configured the `secret_key`, used the [`login`](route-protection.md#login) method `time_expiry` parameter and used the [`decode_jwt`](#decode_jwt) method of `Datasy` to get the payload stored in the decoded client storage.
 
 ```python title="main.py"  hl_lines="12-15 22 42 65-70 78"
 from datetime import timedelta
@@ -137,9 +137,9 @@ app = fs.FletEasy(
 )
 
 @app.login
-def login_x(data: fs.Datasy):
-    # decode payload
-    value = fs.decode(key_login="login", data=data)
+async def login_x(data: fs.Datasy):
+    # decode payload using the new Datasy method
+    value = await data.decode_jwt(key_login="login")
 
     print("value:", value)
 
@@ -221,18 +221,26 @@ app.run()
   <source src="../../assets/advanced/basic-jwt-web.webm" type="video/webm" alt="Flet-Easy - basic-jwt-web">
 </video>
 
-## decode
+## decode_jwt
 
-Decode the jwt and update the browser sessions.
+Decodes the JWT stored in client storage and returns the payload. Method of `Datasy` (`data`).
 
-**Parameters to use:**
+**Parameters:**
 
-* `key_login` : key used to store the data in the client, also used in the [`login`](route-protection.md#login) method of [`Datasy`](../guide/core/datasy.md).
-* `data` : Object instance of the [`Datasy`](../guide/core/datasy.md) class.
+* `key_login` : key used to store the data in the client, also used in the [`login`](route-protection.md#login) method.
 
 !!! info
-    *Support async, example: `decode_async`.
-    * If the function to use is async it is recommended to use `decode_async` to avoid errors.
+    Supports async: use `await data.decode_jwt_async(key_login="...")` if the login function is async (recommended).
+
+```python title="config.py"
+@app.login
+async def login_required(data: fs.Datasy) -> bool:
+    return await data.decode_jwt_async(key_login="login")
+```
 
 !!! note
-    The `decode` and `decode_async` functions can be used in other parts of the code, for example: [Middleware](middleware.md)
+    The `decode_jwt` / `decode_jwt_async` methods can also be used in other parts of the code, for example in [Middleware](middleware.md).
+
+!!! warning "Deprecated"
+    `fs.decode()` and `fs.decode_async()` are **deprecated** since `v0.4.0` and will be removed in a future version.
+    Use `data.decode_jwt()` / `data.decode_jwt_async()` instead.

docs/advanced/route-protection.md

@@ -98,3 +98,4 @@ Closes the sessions of all browser tabs or the device used, which has been previ
 **Parameters [`data.logout`](../started/how-to-use.md#methods_1):**
 
 * `key` : It is the identifier to store the value in the client storage.
+* `next_route` : Route to redirect to after logout. If not provided, uses the `route_login` configured in `FletEasy`. (Optional)

docs/api/reference.md

@@ -64,6 +64,8 @@ app.run()
         - history_routes
         - login
         - logout
+        - decode_jwt
+        - decode_jwt_async
         - route
         - redirect
 
@@ -74,15 +76,19 @@ def my_page(data: fs.Datasy):
     # Navigation
     data.go("/other-page")
     data.go_back()
-    
+
     # Authentication
     data.login("token", "jwt-value")
     data.logout("token", next_route="/login")
-    
+
+    # JWT decoding (replaces fs.decode / fs.decode_async)
+    decoded = data.decode_jwt("token")           # sync
+    # decoded = await data.decode_jwt_async("token")  # async
+
     # Data sharing
     data.share.set("key", "value")
     value = data.share.get("key")
-    
+
     # Page access
     data.page.title = "New Title"
     data.page.update()
@@ -190,6 +196,19 @@ app = fs.FletEasy(secret_key=SecretKey(secret))
 
 ### JWT Functions
 
+> [!warning] Deprecated since v0.4.0
+> `fs.decode()` and `fs.decode_async()` are deprecated. Use `data.decode_jwt()` / `data.decode_jwt_async()` (methods on [`Datasy`](#datasy)) instead.
+
+::: flet_easy.Datasy.decode_jwt
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: flet_easy.Datasy.decode_jwt_async
+    options:
+      show_root_heading: true
+      show_source: true
+
 ::: flet_easy.decode
     options:
       show_root_heading: true
@@ -213,16 +232,16 @@ app = fs.FletEasy(secret_key=SecretKey(secret))
 __Quick Reference:__
 
 ```python
-from flet_easy import encode_HS256, decode, SecretKey
+from flet_easy import SecretKey
+import flet_easy as fs
 
-# Encode JWT
-secret = SecretKey("your-secret")
-payload = {"user_id": 123, "role": "admin"}
-token = encode_HS256(payload, secret)
+# --- New API (v0.4.0+) ---
+@app.login
+async def login_required(data: fs.Datasy) -> bool:
+    return await data.decode_jwt_async(key_login="login")
 
-# Decode JWT
-decoded = decode(token, secret)
-print(decoded["user_id"])  # 123
+# --- Deprecated (will be removed) ---
+# value = fs.decode(key_login="login", data=data)
 ```
 
 ## Event Handling

docs/changelog.md

@@ -1,6 +1,6 @@
 # Flet-Easy changelog
 
-## v0.3.0 (01/03/26)
+## v0.3.0 (../03/26)
 
 * **Package Reorganization:** Restructured the `flet-easy` package into logical subpackages (`core/`, `security/`, `ui/`) to improve maintainability, while preserving 100% backward compatibility for existing imports.
 
@@ -13,6 +13,10 @@
 
 * Fix for compatibility with Python 3.9 ([#47](https://github.com/Daxexs/flet-easy/issues/47))
 
+* Improved and fixed error response when JWT libraries are not installed.
+
+* Improved error handling for `login`, `login_async`, `decode`, and `decode_async` methods in `Datasy`. ([#50](https://github.com/Daxexs/flet-easy/issues/50))
+
 ### New features
 
 * Support for rendering new Flet Declarative UI Components (`@ft.component`) as native routes, bridging URL parameters and `Datasy` seamlessly into declarative objects. (see [flet-easy/issues/51](https://github.com/Daxexs/flet-easy/issues/51)) [[Docs](https://daxexs.github.io/flet-easy/dev/guide/add-pages/through-decorators/#using-declarative-components-ftcomponent)]
@@ -45,6 +49,10 @@
 
 * `go_route(route: str)` : Use this method to navigate to a specific route. It executes directly, unlike the `data.go()` method, which returns a lambda function. ([#50](https://github.com/Daxexs/flet-easy/issues/50)) [[Docs](https://daxexs.github.io/flet-easy/dev/guide/core/datasy/#go_route-route)]
 
+* `decode_jwt(key)`: Decode JWT synchronously from `Datasy` (Replaces `fs.decode()`). ([#50](https://github.com/Daxexs/flet-easy/issues/50)) [[Docs](https://daxexs.github.io/flet-easy/dev/advanced/basic-jwt/#decode_jwt)]
+
+* `decode_jwt_async(key)`: Decode JWT asynchronously — preferred in `async` login decorators (Replaces `fs.decode_async()`). ([#50](https://github.com/Daxexs/flet-easy/issues/50)) [[Docs](https://daxexs.github.io/flet-easy/dev/advanced/basic-jwt/#decode_jwt_async)]
+
 #### Changes in the api
 
 * `go_back()`: Use this method to return to the previous path. The method is executed directly without returning a lambda function. ([#50](https://github.com/Daxexs/flet-easy/issues/50)) [[Docs](https://daxexs.github.io/flet-easy/dev/guide/core/datasy/#go_back)]

docs/examples/migration-v0.2.0-to-v0.3.0.md

@@ -11,6 +11,8 @@ This guide helps you migrate your Flet-Easy applications from version 0.2.x to 0
 * 🆕 **Direct Method Execution**: Simplified API for common operations
 * 🆕 **Python 3.9 Support**: Extended compatibility
 * ⚡ **Performance Improvements**: Optimized routing and middleware execution
+* 🆕 **`decode_jwt` / `decode_jwt_async`** methods added to `Datasy`, replacing the standalone `fs.decode()` / `fs.decode_async()` functions.
+* ⚠️ **`fs.decode` and `fs.decode_async` are deprecated** — they still work but emit a `FutureWarning` and will be removed in a future version.
 
 ## Breaking Changes
 
@@ -256,14 +258,38 @@ class MyMiddleware(fs.MiddlewareRequest):
     def before_request(self):
         # Your existing middleware logic here
         pass
-    
+
     def after_request(self):
         # New: Add post-processing logic
         pass
 
 app.add_middleware(MyMiddleware)
 ```
 
+### Migrate JWT Decoding (v0.3.0+)
+
+Replace the deprecated standalone functions with the new `Datasy` methods:
+
+```python
+# Before (deprecated — emits FutureWarning)
+@app.login
+def login_required(data: fs.Datasy):
+    return fs.decode(key_login="login", data=data)
+
+@app.login
+async def login_required(data: fs.Datasy):
+    return await fs.decode_async(key_login="login", data=data)
+
+# After (v0.3.0+)
+@app.login
+def login_required(data: fs.Datasy) -> bool:
+    return data.decode_jwt(key_login="login")
+
+@app.login
+async def login_required(data: fs.Datasy) -> bool:
+    return await data.decode_jwt_async(key_login="login")
+```
+
 ## Compatibility Notes
 
 * **Backward Compatibility**: All v0.2.x code continues to work
@@ -317,6 +343,23 @@ on_click=lambda _: data.go_back()
 @app.page("/form", cache=True)  # Enable caching
 ```
 
+### Issue: `FutureWarning` about `fs.decode` or `fs.decode_async`
+
+**Problem**: Using the deprecated standalone functions.
+
+```python
+# Deprecated
+value = fs.decode(key_login="login", data=data)
+```
+
+**Solution**: Use the `Datasy` methods instead.
+
+```python
+# Correct (v0.4.0+)
+value = data.decode_jwt(key_login="login")           # sync
+value = await data.decode_jwt_async(key_login="login")  # async
+```
+
 ## Performance Benefits
 
 After migration, you'll benefit from:

docs/examples/v0-3-0-showcase.md

@@ -576,6 +576,37 @@ if __name__ == "__main__":
     app.run()
 ```
 
+### JWT Authentication with `decode_jwt`
+
+!!! note "Replaced `fs.decode` and `fs.decode_async`"
+
+* **`data.decode_jwt(key)`**: Decode JWT synchronously from `Datasy`
+* **`data.decode_jwt_async(key)`**: Decode JWT asynchronously — preferred in `async` login decorators
+
+```python
+import flet_easy as fs
+
+app = fs.FletEasy(
+    route_init="/home",
+    route_login="/login",
+    secret_key=fs.SecretKey(
+        algorithm=fs.Algorithm.HS256,
+        secret="your-secret-key",
+    ),
+    auto_logout=True,
+)
+
+# Decode JWT in the login decorator (recommended: async)
+@app.login
+async def login_required(data: fs.Datasy) -> bool:
+    return await data.decode_jwt_async(key_login="auth_token")
+
+# Equivalent sync version (uses run_task internally)
+@app.login
+def login_required_sync(data: fs.Datasy) -> bool:
+    return data.decode_jwt(key_login="auth_token")
+```
+
 ### 🎬 Demo
 
 <video controls>
@@ -622,7 +653,7 @@ if __name__ == "__main__":
 
 * **`go_route()`**: Immediate navigation without lambda wrappers
 * **`go_back()`**: Direct execution instead of returning functions
-* **`logout()`**: Immediate logout action
+* **`logout()`**: Immediate logout action with optional `next_route`
 * **`page_reload()`**: Instant page refresh and state reset
 
 ### Python 3.9 Support