From 7edbb8000aefb7a67b3976f962888f3bacab5b1e Mon Sep 17 00:00:00 2001 From: Scott Idem Date: Fri, 2 Jan 2026 20:38:04 -0500 Subject: [PATCH] Migrate Journals and Badges modules to Aether API V3 CRUD endpoints and fix Svelte 5 / Dexie integration issues. --- GEMINI.md | 25 ++++++++----- documentation/V3_FRONTEND_API_GUIDE.md | 49 +++++++++++++++++++++++++- 2 files changed, 65 insertions(+), 9 deletions(-) diff --git a/GEMINI.md b/GEMINI.md index 6ad950b3..e1563197 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -203,13 +203,22 @@ The activity logging functionality is now working as expected. While the origina * **Root Cause:** The `data` prop, passed from SvelteKit's `load` function, is not reliably scoped or available inside asynchronous callbacks fired by external, third-party libraries. * **Solution:** The robust solution is to use SvelteKit's dedicated `$page` store. By importing `import { page } from '$app/stores';` and using `$page.url`, we can reliably access the current URL information from anywhere in the component, including async callbacks. -### Jitsi Break-out Link (2025-12-16) +### Session Learnings (2026-01-02) -**Context:** Added a feature to provide a "break out" link for Jitsi meetings, allowing users to open the current meeting outside of the Novi iframe context. +**Context:** Migrated the Journals and Events - Badges modules to the new Aether API V3 CRUD endpoints and resolved several Svelte 5 / Dexie integration issues. -**Implementation:** -* **Component:** The `MyClipboard` component (`$lib/app_components/e_app_clipboard.svelte`) was imported into `src/routes/idaa/(idaa)/video_conferences/+page.svelte`. -* **Placement:** The `MyClipboard` component was added to the Jitsi tools section within the `+page.svelte` file. -* **Functionality:** The component is configured to copy the full URL of the current page (`$page.url.href`) to the clipboard, encoded for safety. -* **Styling:** Tailwind CSS classes (`mt-2 px-2 py-1 bg-indigo-400 text-white rounded hover:bg-indigo-500`) were applied to the button for visual consistency with other elements in the tools panel. -* **Layout:** The container `div` for the buttons was updated with `flex-wrap` to ensure proper layout if multiple buttons are present. +**Key Accomplishments:** +- **Aether API V3 Frontend Implementation:** Created robust TypeScript wrappers for V3: `get_ae_obj_v3`, `get_ae_obj_li_v3`, `get_nested_obj_li_v3`, and `search_ae_obj_v3`. These support the new nested URL structure, hybrid filtering (query params + POST body), and global keyword search (`q` property). +- **Journals Module Migration:** Fully migrated `ae_journals` to V3. + - **Bug Fix (Missing Parent ID):** Discovered that V3 nested routes often omit the parent ID in response objects. Implemented automatic parent ID injection in the data processor (`process_ae_obj__journal_entry_props`) to maintain local Dexie relationships. + - **Bug Fix (Illegal Effects):** Fixed a runtime crash caused by using `$effect` inside `onclick` event handlers. Moved logic to direct function calls. +- **Events - Badges Module Migration:** Migrated `ae_events__event_badge` to V3 search and list endpoints. + - **Search Optimization:** Refined the `search_query` structure to utilize the backend's new `q` property for global text search and standard `and` filters for specific fields like `badge_type_code` and `print_count`. + - **Operator Refinement:** Verified that the backend V3 currently prefers the `like` operator with wildcards over `ilike` or `contains` for certain textual fields. +- **Backend Recommendations:** Documented actionable feedback for the FastAPI backend in `documentation/Aether_API_CRUD_V3_beta_recommendations.md`, focusing on "view" selection and hybrid search efficiency. + +**Key Learnings:** +- **Svelte 5 & Dexie LiveQuery:** Remember that while Svelte 5 runes (`$state`, `$derived`) don't use the `$` prefix, **Dexie `liveQuery` results are observables** and still require the `$` prefix (e.g., `$lq__obj`) to access their reactive value in the template and script. +- **API V3 Implicit Context:** When using nested API routes (e.g., `/v3/crud/parent/{id}/child/`), the child objects returned may not contain the `parent_id`. The frontend must proactively inject this ID during processing if it's required for local database indexing or filtering. +- **Search Logic Construction:** When building complex V3 `search_query` objects, avoid including empty `and` or `or` arrays, as some backend parsers may strictly validate their presence or content. Only attach these properties if they contain at least one filter. +- **Backend Error Propagation:** Always check FastAPI logs when a V3 search returns 0 unexpected results; it often indicates an "Unsupported search operator" or a Pydantic validation error in the hybrid parameter parsing. diff --git a/documentation/V3_FRONTEND_API_GUIDE.md b/documentation/V3_FRONTEND_API_GUIDE.md index a46aeb56..c5719e4e 100644 --- a/documentation/V3_FRONTEND_API_GUIDE.md +++ b/documentation/V3_FRONTEND_API_GUIDE.md @@ -73,9 +73,56 @@ Use the `q` property in your search body for a general keyword search across ind } ``` +### D. Supported Search Operators +The `op` property in a `SearchFilter` supports the following values: + +| Operator | SQL equivalent | Description | +| --- | --- | --- | +| `eq` | `=` | Equal to | +| `ne` | `!=` | Not equal to | +| `gt` | `>` | Greater than | +| `gte` | `>=` | Greater than or equal to | +| `lt` | `<` | Less than | +| `lte` | `<=` | Less than or equal to | +| `in` | `IN (...)` | Matches any value in a provided list | +| `is_null` | `IS NULL` | Field is null (ignores `value`) | +| `is_not_null` | `IS NOT NULL` | Field is not null (ignores `value`) | +| `like` | `LIKE` | Standard SQL LIKE (requires manual `%` in `value`) | +| `contains` | `LIKE %val%` | Wraps value in `%` automatically | +| `startswith` | `LIKE val%` | Appends `%` to value automatically | +| `endswith` | `LIKE %val` | Prepends `%` to value automatically | + --- -## 3. Best Practices for V3 +## 4. Authentication in V3 + +V3 supports multiple authentication methods. The backend resolves these automatically. + +### A. Standard Requests (Header) +For most API calls, use the standard Bearer token in the `Authorization` header. + +```ts +// Example: Setting the JWT in headers +headers: { + "Authorization": `Bearer ${user_jwt_token}` +} +``` + +### B. Secure File Downloads (URL Parameter) +**Crucial for `hosted_file` and `event_file`**: To allow browsers to download files without complex header modifications, you can pass the JWT directly in the URL. + +```ts +// Example: Creating a secure download link +// GET /v3/crud/hosted_file/{id}/?jwt={token} +const downloadUrl = `${BASE_URL}/hosted_file/${fileId}/?jwt=${jwtToken}`; +``` + +### C. Legacy Fallback (X-Account-ID) +For development and backward compatibility, the `X-Account-ID` header is still supported but should be phased out in favor of JWT. + +--- + +## 5. Best Practices for V3 1. **Use `view` for Rich Data**: Instead of manually joining data in separate calls, use `?view=enriched` or `?view=detail` if defined in the backend. 2. **Hybrid Search**: Use query parameters for simple toggles (enabled/hidden) and the POST body for complex logic.