fastapi-rtk 2.20.0__tar.gz → 2.21.0__tar.gz

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-rtk
-Version: 2.20.0
+Version: 2.21.0
 Summary: A package that provides a set of tools to build a FastAPI application with a Class-Based CRUD API.
 Project-URL: Homepage, https://codeberg.org/datatactics/fastapi-rtk
 Project-URL: Issues, https://codeberg.org/datatactics/fastapi-rtk/issues
@@ -119,7 +119,7 @@ project/
 1. Install FastAPI React Toolkit:
 
    ```bash
-   pip install fastapi-rtk
+   pip install fastapi-rtk aiosqlite  # aiosqlite: async driver for the sqlite URI below (asyncpg for Postgres)
    mkdir -p app
    touch run.py app/__init__.py app/app.py app/config.py app/models.py app/apis.py
    ```
@@ -231,6 +231,7 @@ project/
    - `GET /api/v1/items/_image/{filename}` - Serve image files (If image column is present)
    - `GET /api/v1/items/_file/{filename}` - Serve file downloads (If file column is present)
    - `GET /api/v1/items/_info` - Get metadata about the model, including which columns can be added, edited, filtered, etc.
+   - `GET /api/v1/items/_lookup/{column}` - Search a column's values, or resolve ids to labels, for form and filter inputs (If the column is enabled in `lookup_columns`)
    - `POST /api/v1/items/bulk/{handler}` - Bulk operations, if set on the API class
    - `GET /api/v1/items/download` - Download items as CSV
    - `GET /api/v1/items/` - List items
@@ -249,6 +250,14 @@ project/
 
 2. Project files:
 
+   **webapp/.env**
+
+   The path the app is served under, with a trailing slash; `index.html` reads it as `%VITE_BASE_PATH%`.
+
+   ```bash
+   VITE_BASE_PATH=/
+   ```
+
    **webapp/index.html**
 
    ```html
@@ -295,7 +304,7 @@ project/
 
    createRoot(document.getElementById("root")).render(
      <StrictMode>
-       <MantineProvider>
+       <MantineProvider getStyleNonce={() => window.nonce}>
          <Provider baseUrl={BASE_PATH + "api/v1"}>
            <BrowserRouter basename={BASE_PATH}>
              <App />
@@ -326,8 +335,9 @@ import { createReactNativeAdapters } from "fastapi-rtk/react-native-adapters";
 const rnAdapters = createReactNativeAdapters({
   asyncStorage,
   fileSystem,
-  sharing,
+  sharing, // optional
   webBrowser,
+  oauthRedirectUrl: "myapp://oauth", // required for OAuth sign-in; one URL or a map per provider
 });
 
 <Provider baseUrl="https://api.example.com/api/v1" adapters={rnAdapters}>

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/README.md

@@ -60,7 +60,7 @@ project/
 1. Install FastAPI React Toolkit:
 
    ```bash
-   pip install fastapi-rtk
+   pip install fastapi-rtk aiosqlite  # aiosqlite: async driver for the sqlite URI below (asyncpg for Postgres)
    mkdir -p app
    touch run.py app/__init__.py app/app.py app/config.py app/models.py app/apis.py
    ```
@@ -172,6 +172,7 @@ project/
    - `GET /api/v1/items/_image/{filename}` - Serve image files (If image column is present)
    - `GET /api/v1/items/_file/{filename}` - Serve file downloads (If file column is present)
    - `GET /api/v1/items/_info` - Get metadata about the model, including which columns can be added, edited, filtered, etc.
+   - `GET /api/v1/items/_lookup/{column}` - Search a column's values, or resolve ids to labels, for form and filter inputs (If the column is enabled in `lookup_columns`)
    - `POST /api/v1/items/bulk/{handler}` - Bulk operations, if set on the API class
    - `GET /api/v1/items/download` - Download items as CSV
    - `GET /api/v1/items/` - List items
@@ -190,6 +191,14 @@ project/
 
 2. Project files:
 
+   **webapp/.env**
+
+   The path the app is served under, with a trailing slash; `index.html` reads it as `%VITE_BASE_PATH%`.
+
+   ```bash
+   VITE_BASE_PATH=/
+   ```
+
    **webapp/index.html**
 
    ```html
@@ -236,7 +245,7 @@ project/
 
    createRoot(document.getElementById("root")).render(
      <StrictMode>
-       <MantineProvider>
+       <MantineProvider getStyleNonce={() => window.nonce}>
          <Provider baseUrl={BASE_PATH + "api/v1"}>
            <BrowserRouter basename={BASE_PATH}>
              <App />
@@ -267,8 +276,9 @@ import { createReactNativeAdapters } from "fastapi-rtk/react-native-adapters";
 const rnAdapters = createReactNativeAdapters({
   asyncStorage,
   fileSystem,
-  sharing,
+  sharing, // optional
   webBrowser,
+  oauthRedirectUrl: "myapp://oauth", // required for OAuth sign-in; one URL or a map per provider
 });
 
 <Provider baseUrl="https://api.example.com/api/v1" adapters={rnAdapters}>

fastapi_rtk-2.21.0/fastapi_rtk/_version.py

@@ -0,0 +1 @@
+__version__ = "2.21.0"

fastapi_rtk-2.21.0/fastapi_rtk/agent_docs/adapters/claude/skill.frontmatter

@@ -0,0 +1,2 @@
+name: rtk-developer
+description: 'Use when building, modifying or debugging anything in a fastapi-rtk project: Python models, ModelRestApi or BaseApi endpoints, pre/post hooks, permissions, migrations, file uploads, bulk operations, or the React side (Provider setup, ApiProvider, useApi, NextGenDataGrid, useForms, dialogs, JsonForms). Also on any mention of fastapi-rtk or "rtk backend" / "rtk frontend", and in any project importing from `fastapi_rtk` or the `fastapi-rtk` JS package, where it is preferred over plain FastAPI or React guidance.'

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/fastapi_rtk/agent_docs/guide/backend.md

@@ -39,7 +39,7 @@ FILE_ALLOWED_EXTENSIONS = ["pdf", "csv", "docx", "xlsx"]  # optional
 IMG_ALLOWED_EXTENSIONS = ["jpg", "jpeg", "png", "gif"]    # optional
 ```
 
-Always use an **async** driver (`aiosqlite`, `asyncpg`). The toolkit is async-first and sync drivers will raise at runtime.
+Prefer an **async** driver (`aiosqlite`, `asyncpg`): the toolkit is async-first and the async path is the tested one. A sync URL falls back to a sync engine and session, and `SQLAInterface` runs the sync session calls through `smart_run`.
 
 ## 3. App initialization (`app/app.py`)
 
@@ -142,18 +142,18 @@ class Item(Model):
 
 ## 5. REST APIs: `ModelRestApi`
 
-Registers a full CRUD surface:
+Registers a full CRUD surface under `/api/{version}/{resource_name}` (`version` defaults to `v1`):
 
-- `GET /items`: list (supports pagination, filters, sort via query params)
-- `POST /items`: create
-- `GET /items/{id}`: detail
-- `PUT /items/{id}`: update
-- `DELETE /items/{id}`: delete
-- `GET /items/_info`: metadata (columns, filters, permissions), which the frontend uses
-- `GET /items/_lookup/{column}?mode=add|edit|search`: paged values of one column (see "Column lookup" in §8)
-- `GET /items/download`: CSV export
-- `POST /items/bulk/{handler}`: bulk operations (see §12)
-- `GET /items/_file/{filename}` / `_image/{filename}`: served when the model has file/image columns
+- `GET /api/v1/items`: list (supports pagination, filters, sort via query params)
+- `POST /api/v1/items`: create
+- `GET /api/v1/items/{id}`: detail
+- `PUT /api/v1/items/{id}`: update
+- `DELETE /api/v1/items/{id}`: delete
+- `GET /api/v1/items/_info`: metadata (columns, filters, permissions), which the frontend uses
+- `GET /api/v1/items/_lookup/{column}?mode=add|edit|search`: paged values of one column (see "Column lookup" in §8)
+- `GET /api/v1/items/download`: CSV export
+- `POST /api/v1/items/bulk/{handler}`: bulk operations (see §12)
+- `GET /api/v1/items/_file/{filename}` / `_image/{filename}`: served when the model has file/image columns
 
 ```python
 from fastapi_rtk import ModelRestApi, SQLAInterface, g
@@ -260,7 +260,7 @@ By default every column is listed, shown, added, edited. Override per-operation:
 class ItemApi(ModelRestApi):
     datamodel = SQLAInterface(Item)
 
-    list_columns = ["id", "name", "category.name"]            # GET /items
+    list_columns = ["id", "name", "category.name"]            # GET /api/v1/items
     show_columns = ["id", "name", "description", "category"]
     add_columns = ["name", "description", "category"]
     edit_columns = ["name", "description"]                    # can't reassign category
@@ -297,7 +297,7 @@ More per-Api knobs:
 
 ### Column lookup
 
-`/_info` ships only the first `max_page_size` options of a relation; `GET /items/_lookup/{column}` searches and pages the values of one column instead. Query params, bound as one `LookupQuerySchema` (per-Api `lookup_query_schema`): `mode` (required: `add`, `edit` or `search`; any other value is 422), `search` (text the values must contain, matched by `FilterSearch` like the list route's `search` param), `page` (zero-based, default 0), `page_size` (default and cap `max_page_size`), `ids` (a JSON list of primary keys to resolve, default `[]`). The response is `LookupResponse`, `{"count": int, "values": [...]}`: `{"id", "value"}` entries for a relation (`value` is `str(item)`), distinct non-null scalars in ascending order for a plain column. The route is dropped from `routes` when no column is lookup-enabled in any mode.
+`/_info` ships only the first `max_page_size` options of a relation; `GET /api/v1/items/_lookup/{column}` searches and pages the values of one column instead. Query params, bound as one `LookupQuerySchema` (per-Api `lookup_query_schema`): `mode` (required: `add`, `edit` or `search`; any other value is 422), `search` (text the values must contain, matched by `FilterSearch` like the list route's `search` param), `page` (zero-based, default 0), `page_size` (default and cap `max_page_size`), `ids` (a JSON list of primary keys to resolve, default `[]`). The response is `LookupResponse`, `{"count": int, "values": [...]}`: `{"id", "value"}` entries for a relation (`value` is `str(item)`), distinct non-null scalars in ascending order for a plain column. The route is dropped from `routes` when no column is lookup-enabled in any mode.
 
 - Query validation (400, before access): `ids` that is not JSON (`json_invalid`) or not a list (`list_type`), a negative `page` (`greater_than_equal`), a `page_size` below 1 (`greater_than`).
 - Gating order: 401 (route protected, no user), 404 `COLUMN_NOT_FOUND` (column not lookup-enabled in that mode), 403 (user lacks `can_post` for `add`, `can_put` for `edit`, `can_get` for `search`). There is no `can_lookup` permission; `"lookup"` in `exclude_protected_routes` skips the 401 and 403 checks.
@@ -414,7 +414,7 @@ class Item(Model):
 When these columns exist, `ModelRestApi` automatically:
 
 - switches POST/PUT to `multipart/form-data`
-- exposes `GET /items/_file/{filename}` and `GET /items/_image/{filename}`
+- exposes `GET /api/v1/items/_file/{filename}` and `GET /api/v1/items/_image/{filename}`
 - grants `can_file` / `can_image` permissions
 
 ### File managers
@@ -574,12 +574,13 @@ class ReadingApi(ModelRestApi):
     download_page_size = 5000
 ```
 
-Set it to a resolver when the size depends on the query. It receives the Api, the session, and the `DBQueryParams` the export runs with. Sync and async both work, resolved through `safe_call`, so a sync one runs inline rather than on a worker thread:
+Set it to a resolver when the size depends on the query. It receives the Api, the session, and the `DBQueryParams` the export runs with. Sync and async both work, resolved through `safe_call`, so a sync one runs inline rather than on a worker thread. Declare it in the class body as a `@staticmethod`: a plain method is called with `self` prepended and raises `TypeError`.
 
 ```python
 class ReadingApi(ModelRestApi):
     datamodel = SQLAInterface(Reading)
 
+    @staticmethod
     def download_page_size(api, session, params):
         return 1000 if params.get("filters") else 250
 ```
@@ -619,9 +620,9 @@ Top-level shape: `dict[role_name, list[[api_glob, permission_glob]]]`. Both fiel
 
 ### The admin role sits outside `ROLES`
 
-`Setting.AUTH_ROLE_ADMIN` (`setting.py:368`, default `DEFAULT_ADMIN_ROLE = "Admin"` from `const.py:71`) names a role that is deliberately absent from `ROLES`, reachable as `g.admin_role` (`globals.py:141-147`). It holds **every permission of every registered Api**, and a `ROLES` edit cannot narrow that: `_associate_permission_with_api` (`fastapi_react_toolkit.py:506`) writes one `PermissionApi` row per `(permission, api)` taken from each Api's exposed routes plus one per `ROLES` entry, then `_associate_role_with_permission_api` (`:545`) grants the admin role every one of those rows except the ones whose permission name contains `|` (`:566-576`). The per-route row for the same permission is a different row and is never excluded, so piping a `ROLES` entry to hide something from the admin role is a no-op. The cleanup pass also exempts that role from disassociation by name, so an existing grant row survives every restart.
+`Setting.AUTH_ROLE_ADMIN` (`setting.py:368`, default `DEFAULT_ADMIN_ROLE = "Admin"` from `const.py:74`) names a role that is deliberately absent from `ROLES`, reachable as `g.admin_role` (`globals.py:142-149`). It holds **every permission of every registered Api**, and a `ROLES` edit cannot narrow that: `_associate_permission_with_api` (`fastapi_react_toolkit.py:506`) writes one `PermissionApi` row per `(permission, api)` taken from each Api's exposed routes plus one per `ROLES` entry, then `_associate_role_with_permission_api` (`:545`) grants the admin role every one of those rows except the ones whose permission name contains `|` and that a `ROLES` role other than the public role lists (`:562-577`; a piped entry listed only under the public role is still granted to admin). The per-route row for the same permission is a different row and is never excluded, so piping a `ROLES` entry to hide something from the admin role is a no-op. The cleanup pass also exempts that role from disassociation by name, so an existing grant row survives every restart.
 
-Revoking a permission from it means setting `AUTH_ROLE_ADMIN` to `None` or to an existing `ROLES` role name (which strips the blanket grant entirely, since `if g.admin_role:` guards it), or checking inside the route.
+Revoking a permission from it means setting `AUTH_ROLE_ADMIN` to `None` (which strips the blanket grant entirely, since `if g.admin_role:` guards it), or checking inside the route. Pointing `AUTH_ROLE_ADMIN` at an existing `ROLES` role name revokes nothing: that role becomes the admin role, receives the blanket grant, and is exempt from cleanup.
 
 ### Asking whether a user holds a permission
 
@@ -661,7 +662,7 @@ A name listed in an Api's `base_permissions` that no exposed route carries becom
 
 ### What the browser gets
 
-`GET auth/user` sets `permissions` to the **Api names** the user holds any grant on, not permission names: `select(Api.name).join(PermissionApi).join(PermissionApi.roles).where(Role.id.in_(user role ids)).distinct()` (`security/sqla/apis.py:134-151`), typed as `AuthUser.permissions: string[]` in the JS client. So a browser-side gate can ask "any grant on Api A" and cannot distinguish `can_get` from `can_post`; per-permission detail reaches the frontend through an Api's `_info` response instead (`permissions`, `schemas.py:83`). Prefer that Api-level fact over publishing a role list in the frontend config, and keep the enforcing check server-side.
+`GET auth/user` sets `permissions` to the **Api names** the user holds any grant on, not permission names: `select(Api.name).join(PermissionApi).join(PermissionApi.roles).where(Role.id.in_(user role ids)).distinct()` (`security/sqla/apis.py:155-166`), typed as `AuthUser.permissions: string[]` in the JS client. So a browser-side gate can ask "any grant on Api A" and cannot distinguish `can_get` from `can_post`; per-permission detail reaches the frontend through an Api's `_info` response instead (`InfoResponse.permissions`, `schemas.py:302`). Prefer that Api-level fact over publishing a role list in the frontend config, and keep the enforcing check server-side.
 
 ### Route guards
 
@@ -717,7 +718,7 @@ A `"backend": "jwt"` client (for clients without a browser cookie store, such as
 
 ```bash
 fastapi-rtk db init
-fastapi-rtk db migrate -m "add items"
+fastapi-rtk db migrate --message "add items"
 fastapi-rtk db upgrade
 fastapi-rtk db downgrade
 

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/fastapi_rtk/agent_docs/guide/frontend.md

@@ -10,7 +10,7 @@ The toolkit expects Mantine as the UI kit. Use `Stack`, `Group`, `Grid`, `Simple
 pnpm add fastapi-rtk @mantine/core @mantine/dates @mantine/form @mantine/hooks dayjs react-router
 ```
 
-Peer deps: the four `@mantine/*` packages (`^9.0.0`), `react` / `react-dom` (`^19.2.3`), `dayjs` (`^1.11.0`) and `react-router` (`^7.5.3 || ^8.0.0`). Everything else (mantine-react-table, TanStack Query, zustand, i18next, JsonForms) is bundled inside `fastapi-rtk`. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
+Peer deps: the four `@mantine/*` packages (`^9.4.0`), `react` / `react-dom` (`^19.2.3`), `dayjs` (`^1.11.0`) and `react-router` (`^7.5.3 || ^8.0.0`), plus the optional `@jsonforms/core` / `@jsonforms/react` (`^3.6.0`), needed only when importing from `fastapi-rtk/jsonforms` (every other subpath, its types included, works without them). TanStack Query (`^5.52.1`), zustand, i18next, react-i18next, yup, lodash, clsx and dompurify are regular dependencies, installed with `fastapi-rtk`; only mantine-react-table (patched), mantine-form-yup-resolver and the JsonForms copy behind the built-in forms are bundled inside it. When the app's own TanStack Query or react-i18next resolves to the same copy, its `useQuery` / `useQueryClient` / `useTranslation` inside a `Provider` read the Provider's `QueryClient` and i18next instance, since `Provider` always creates its own `QueryClient`; `rq` / `i18nr` / `useTranslation` imported from `fastapi-rtk` always do. Outside a `Provider`, the app's `useTranslation` keeps the app's own i18next instance. To keep the app's own instance inside a `Provider` as well, pass it as `langProps.i18n`. Mantine >= 9.4.1 requires fastapi-rtk >= 2.8.0; older releases loop forever in the grid's `useColumns` ("Maximum update depth exceeded").
 
 **Provider order is load-bearing.** Mantine must wrap the fastapi-rtk `Provider`, and the stylesheet order matters: Mantine CSS first, fastapi-rtk CSS last (RTK overrides).
 
@@ -105,7 +105,7 @@ function ItemsPage() {
 | `data`                                         | Current list/page payload for the bound resource                                         |
 | `info`                                         | The `/_info` response for the resource (`add_columns`, `edit_columns`, `permissions`, …) |
 | `loading` / `dataLoading` / `infoLoading`      | Aggregate + per-stream fetch flags                                                       |
-| `error` / `dataError` / `infoError`            | Aggregate + per-stream error objects (`{message, originalError}`)                        |
+| `error` / `dataError` / `infoError`            | Aggregate `{message, originalError}` object + the per-stream raw query `Error` objects   |
 | `getEntry(id)`                                 | `GET /{resource}/{id}`                                                                   |
 | `addEntry(item)`                               | `POST /{resource}`                                                                       |
 | `updateEntry(id, item)`                        | `PUT /{resource}/{id}`                                                                   |
@@ -147,7 +147,7 @@ await addEntry({ name: "x" }); // POST /{resource}
 await updateEntry(id, { name: "y" }); // PUT  /{resource}/{id}
 ```
 
-**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports `@tanstack/react-query` as `rq` (`export * as rq from '@tanstack/react-query'` in `api/src/index.ts:38`, surfaced by `core/src/index.ts:94`; the sibling `mrt` namespace re-exports `mantine-react-table` from `core/src/index.ts:95`, with long-form aliases `reactQuery` / `mantineReactTable`). Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
+**Option B, use the TanStack Query namespace `rq`.** `fastapi-rtk` re-exports its `@tanstack/react-query` as `rq` (`export * as rq from './rq'` in `externals/src/index.ts`, surfaced by `core/src/index.ts:94`; import it from there rather than from `@tanstack/react-query`, since an app's own copy sees the Provider's `QueryClient` only when it resolves to the same install; the sibling `mrt` namespace re-exports the bundled `mantine-react-table` the same way, with long-form aliases `reactQuery` / `mantineReactTable` at `core/src/index.ts:96`). The same namespaces, plus `ld` (lodash), `zs` (zustand), `yup` and `i18nr` (react-i18next), are importable from `fastapi-rtk` or `fastapi-rtk/externals`; importing them from `fastapi-rtk/api`, `/utils`, `/zustand` or `/contexts` is deprecated. Wrap a `useApi` action (or any toolkit-provided async function) in `rq.useQuery` / `rq.useMutation` so the result participates in the shared query cache (invalidation, refetch-on-focus, devtools). Never call raw `fetch` from the `queryFn` / `mutationFn`, since that re-introduces the exact problems `useCustomFetch` has.
 
 ```jsx
 import { useApi, rq } from "fastapi-rtk";
@@ -169,7 +169,7 @@ function ReportsPanel({ id }) {
 }
 ```
 
-**Combine with `useApi` for cross-resource updates.** Use a `useApi` action for the bound resource and `rq.useMutation` wrapping a sibling `useApi` action for the second resource. To refresh the bound resource's grid after a mutation, call `refetch({ force: true })` from `useApi()` inside `onSuccess`, which hits the same query the grid renders from (`['data', path, queryParamsJSON, lang]` in `useProvideApi.js`). Toolkit-internal key shape is an implementation detail; use the `useApi` helpers to invalidate rather than constructing the key yourself.
+**Combine with `useApi` for cross-resource updates.** Use a `useApi` action for the bound resource and `rq.useMutation` wrapping a sibling `useApi` action for the second resource. To refresh the bound resource's grid after a mutation, call `refetch({ force: true })` from `useApi()` inside `onSuccess`, which hits the same query the grid renders from (`['data', path, queryParamsJSON, lang]` in `useProvideApi.ts`). Toolkit-internal key shape is an implementation detail; use the `useApi` helpers to invalidate rather than constructing the key yourself.
 
 **Last resort: `useCustomFetch`.** Still exported for legacy call sites. Signature: `useCustomFetch(url, { autoInvoke, initialLoading, clearDataOnRefetch, ...fetchOptions })`; returns `{ data, loading, error, refetch, abort, resetError }`. `refetch()` re-runs the request with the URL + options bound at hook creation; there is no `execute(...)` and no per-call body override. If you need either, switch to `rq.useMutation`.
 
@@ -202,12 +202,22 @@ info?.forEach((api) => /* render menu entry for api.path */);
 ```jsx
 import { useAuth } from "fastapi-rtk";
 
-const { user, signin, signout, oauth_signin, update, resetPassword, refetch } =
-  useAuth();
-
-await signin(username, password); // positional args, NOT an object
-await oauth_signin("google", /* popup */ false);
+const {
+  user,
+  error,
+  signin,
+  signout,
+  oauthSignin,
+  oauthCallback,
+  update,
+  resetPassword,
+  refetch,
+} = useAuth();
+
+await signin({ username, password }); // a single credentials object
+await oauthSignin("google", /* popup */ false); // oauth_signin is the deprecated alias
 await signout();
+error?.message; // { message, originalError } of the last failed action, or undefined
 
 user?.username;
 user?.roles; // string[] of role names
@@ -216,7 +226,7 @@ user?.permissions; // string[] of API NAMES the user holds any grant on
 
 Gate routes/components on `user` and `user.roles`. The Provider keeps the session via cookie, so `user` is populated on every page load automatically.
 
-An OAuth provider configured with `"backend": "jwt"` is for clients without a browser cookie store (React Native on `createReactNativeAdapters`, whose bearer transport stores the token); web apps default to `cookie` providers, since a bearer transport on web keeps the token in `localStorage`, readable by any script on the origin. A web app can still opt into JWT: `adapters={{ authTransport: createBearerTransport(webAdapters.storage) }}`, the provider's `redirect_url` at an app route, and `oauthCallback("google", window.location.search)` on that route. On React Native: point the provider's `redirect_url` at the app's deep link (`myapp://oauth/google`), pass the same URL as `createReactNativeAdapters({ ..., oauthRedirectUrl })` (a string for every provider, or `{ google: "myapp://oauth/google", github: "..." }` keyed by provider name), and call `oauthSignin("google", false)` (no popup). A provider missing from that map fails before any browser opens (`error` is `Could not sign in`, `originalError` names the provider). iOS ends the session on any URL with the redirect URL's scheme (so `myapp://oauth/google` and `myapp://oauth/github` are not told apart there), Android on the first deep link starting with it; for an `https` redirect on iOS 17.4+ pass `oauthPreferUniversalLinks: true` (needs the Associated Domains entitlement) to match host and path instead. The RN opener runs `webBrowser.openAuthSessionAsync(loginUrl, oauthRedirectUrl, { preferUniversalLinks })` and hands the redirected URL back, and `oauthSignin` forwards its `code` / `state` to `auth/oauth-authorized/<provider>`, stores the returned token through `authTransport.persistLogin`, and refetches the user; a failure sets `error` to `Could not sign in`. An app that receives the redirect another way calls `oauthCallback("google", redirectQuery)` from `useAuth()` with that URL's query string.
+An OAuth provider configured with `"backend": "jwt"` is for clients without a browser cookie store (React Native on `createReactNativeAdapters`, whose bearer transport stores the token); web apps default to `cookie` providers, since a bearer transport on web keeps the token in `localStorage`, readable by any script on the origin. A web app can still opt into JWT: `adapters={{ authTransport: createBearerTransport(webAdapters.storage) }}`, the provider's `redirect_url` at an app route, and `oauthCallback("google", window.location.search)` on that route. On React Native: point the provider's `redirect_url` at the app's deep link (`myapp://oauth/google`), pass the same URL as `createReactNativeAdapters({ ..., oauthRedirectUrl })` (a string for every provider, or `{ google: "myapp://oauth/google", github: "..." }` keyed by provider name), and call `oauthSignin("google", false)` (no popup). A provider missing from that map fails before any browser opens (`error.message` is `Could not sign in`, `error.originalError` names the provider). iOS ends the session on any URL with the redirect URL's scheme (so `myapp://oauth/google` and `myapp://oauth/github` are not told apart there), Android on the first deep link starting with it; for an `https` redirect on iOS 17.4+ pass `oauthPreferUniversalLinks: true` (needs the Associated Domains entitlement) to match host and path instead. The RN opener runs `webBrowser.openAuthSessionAsync(loginUrl, oauthRedirectUrl, { preferUniversalLinks })` and hands the redirected URL back, and `oauthSignin` forwards its `code` / `state` to `auth/oauth-authorized/<provider>`, stores the returned token through `authTransport.persistLogin`, and refetches the user; a failure sets `error.message` to `Could not sign in`. An app that receives the redirect another way calls `oauthCallback("google", redirectQuery)` from `useAuth()` with that URL's query string.
 
 **`user.permissions` holds Api names, not permission names.** `auth/user` builds it as `select(Api.name)` joined through the user's roles (backend reference §14, "What the browser gets"), so `user.permissions.includes("ItemApi")` answers "has any grant on that Api" and nothing finer: `can_get` and `can_post` are indistinguishable there. It is the right gate for "may this user reach this resource at all", and it beats shipping a role list through the frontend config, since it follows the grants themselves and leaves no second list to keep in step. For per-verb detail read `useApi().info.permissions` (§5), which is that Api's `/_info` intersected with the user's grants.
 
@@ -403,7 +413,7 @@ const { t } = useTranslation(); // or: translation.t
 <LanguageSelector />;
 ```
 
-`useLang` reads/writes the selected language to localStorage. The translation function `t(key)` comes from react-i18next via `useTranslation()` (also re-exported from `fastapi-rtk`) or via the `translation` field on `useLang()`. Source strings double as the English keys; a German dictionary ships built-in. Extend or override through the `Provider`'s `langProps` prop: `langProps.getI18nProps.translations` takes `{locale: {key: value}}`, `langProps.i18n` accepts a full i18next instance, and `langProps.MRTLocalization` overrides the grid's Mantine React Table strings.
+`useLang` reads/writes the selected language to localStorage. The translation function `t(key)` comes from the `useTranslation()` exported by `fastapi-rtk` (the react-i18next one, which the Provider wires to its i18next instance, as it does `i18nr.Trans`; the one imported from `react-i18next` itself sees it only when the app's react-i18next resolves to the same install) or via the `translation` field on `useLang()`. Source strings double as the English keys; a German dictionary ships built-in. Extend or override through the `Provider`'s `langProps` prop: `langProps.getI18nProps.translations` takes `{locale: {key: value}}`, `langProps.i18n` accepts a full i18next instance, and `langProps.MRTLocalization` overrides the grid's Mantine React Table strings.
 
 ## 13. Standard routes: `UserMenu`
 
@@ -473,7 +483,7 @@ Cookie login is on by default on the backend; the JWT endpoint exists only when
 
 ## 15. Other notable exports
 
-- Every context hook accepts safe-context options: `useApi({ throwOnError: false })` returns `undefined` instead of throwing outside its provider (same option on the other hooks).
+- Every context hook accepts safe-context options: `useApi({ throwOnError: false })` returns the `defaultValue` option (an empty object `{}` unless you pass one) instead of throwing outside its provider (same option on the other hooks).
 - Headless fetcher layer for code outside any provider: `buildRequest`, `getItems` / `getItem` / `createItem` / `updateItem` / `deleteItem` / `getInfo`, `formCreateItem` / `formUpdateItem`, `uploadItems` / `downloadItems`, `postBulk`, plus `useAdapters` / `webAdapters`.
 - Legacy `DataGrid` is still exported alongside `NextGenDataGrid`; standalone `ActionIcons` (`Actions`, `Add`, `Delete`, `Download`, `Edit`, `Refresh`, `Upload`, `View`) and `Filter` compose custom layouts.
 - Utilities: `deepMerge`, `parseFromValuesOrFunc`, `createSafeContext`, `getItemId`, `urlJoin`, `Memoizer`, `FastAPIRTKLogger`; hooks `useActionIcon`, `useSyncValues`, `useTrueOnce`.

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/fastapi_rtk/agent_docs/guide/jsonforms.md

@@ -92,7 +92,7 @@ const customizer = {
 - `componentProps` : the fully computed Mantine props the built-in would have used: `value`, `onChange` (already wired to JsonForms `handleChange(path, value)`), `onBlur`, `label`, `description`, `required`, `disabled`, `error`, plus `uischema.options.props` and `ifProps` (§2). Spread it onto a value-based Mantine input and the field is controlled and validated for free.
 - `jsonFormsProps` : the raw control props (`data`, `handleChange`, `path`, `schema`, `uischema`, `enabled`, `errors`, `visible`, `id`). Reach here when `componentProps` is not enough, or call `useCommonProps(jsonFormsProps)` (from `fastapi-rtk`) to have the library rebuild the `handleChange(path, value)` wrapper for you.
 
-`key` is a **renderer name** (`Text`, `Number`, `Integer`, `Boolean`, `Date`, `DateTime`, `Time`, `Enum`, `EnumArray`, `OneOfEnum`, `File`, `Image`, `Json`, `Object`, `Label`, `Table`, `Array`, `Array.Accordion`), a **JsonForms path / field name** (`status`, `details.category`), or `all`. Precedence when several match: `all` < renderer-name < path (slots deep-merge in that order, most specific wins). Since 2.8.0 every structural wrapper is addressable too: `Table.Thead` / `Table.Tbody` / `Table.Empty`, `Table.Header.*` (`Tr`, `Actions`, `Validation`, `Toolbar`, `Wrapper`, `Flex`), `Table.Row.*` (`Tr`, `Td`, `Actions`, `Grid`, `Up`, `Down`, `Remove`), per-row / per-cell addressing (`Table.Row.{index}`, `Table.Row.{index}.{subPath}`, `Table.Row.{subPath}`), `Array.Stack` / `Array.Items` / `Array.Empty` / `Array.Header.*` / `Array.Item.*` / `Array.DeleteDialog`, `File.Box` / `Image.Box`, and `Label.{text}`. (Collision escape: when a real field is named `all`, the wildcard moves to the exported `specialKey.all`.)
+`key` is a **renderer name** (`Text`, `Number`, `Integer`, `Boolean`, `Date`, `DateTime`, `Time`, `Enum`, `EnumArray`, `OneOfEnum`, `File`, `Image`, `Json`, `Object`, `Label`, `Table`, `Array`, `Array.Accordion`), a **JsonForms path / field name** (`status`, `details.category`), or `all`. Precedence when several match: `all` < renderer-name < path (slots deep-merge in that order, most specific wins). Since 2.8.0 every structural wrapper is addressable too: `Table.Thead` / `Table.Tbody` / `Table.Empty`, `Table.Header.*` (`Tr`, `Actions`, `Validation`, `Toolbar`, `Wrapper`, `Flex`), `Table.Row.*` (`Tr`, `Td`, `Actions`, `Grid`, `Up`, `Down`, `Remove`), per-row / per-cell addressing (`Table.Row.{index}`, `Table.Row.{index}.{subPath}`, `Table.Row.{subPath}`), `Array.Stack` / `Array.Items` / `Array.Empty` / `Array.Header.*` / `Array.Item.*` / `Array.DeleteDialog`, `File.Box` / `Image.Box`, and `Label.{text}`. (Collision escape: when the resource's `list_columns` contains a column named `all`, the wildcard key becomes `_all`; read it at runtime as `useApi().specialKey.all`, which is `all` outside an `ApiProvider`.)
 
 **Write the component** as a plain Mantine component. For a blob field, `JSON.parse` on read and `JSON.stringify` on write; keep spreading `{...componentProps}` so the label / description / error wrapper still renders:
 

{fastapi_rtk-2.20.0 → fastapi_rtk-2.21.0}/tests/unit/cli/test_cli.py

@@ -7,6 +7,8 @@ import zipfile
 
 import typer.main
 import typer.testing
+import yaml
+
 from fastapi_rtk.cli.cli import app, main
 from fastapi_rtk.cli.commands.agent.adapters import AgentsMDAdapter, ClaudeAdapter
 from fastapi_rtk.cli.commands.agent.base import AbstractAgentAdapter
@@ -290,6 +292,17 @@ class TestInstallAgentDocs:
         assert skill.startswith("---\nname: rtk-developer\n")
         assert GUIDE_TARGET in skill
 
+    def test_skill_frontmatter_is_valid_yaml(self, tmp_path):
+        runner.invoke(
+            app, ["agent", "install", "--directory", str(tmp_path), "--claude"]
+        )
+        skill = (tmp_path / SKILL_TARGET / "SKILL.md").read_text()
+        frontmatter = yaml.safe_load(skill.split("---\n")[1])
+        assert frontmatter["name"] == "rtk-developer"
+        assert frontmatter["description"].startswith(
+            "Use when building, modifying or debugging anything in a fastapi-rtk project: "
+        )
+
     def test_guide_and_skill_carry_the_same_pointers(self, tmp_path):
         runner.invoke(
             app, ["agent", "install", "--directory", str(tmp_path), "--claude"]

fastapi_rtk-2.20.0/fastapi_rtk/_version.py

@@ -1 +0,0 @@
-__version__ = "2.20.0"

fastapi_rtk-2.20.0/fastapi_rtk/agent_docs/adapters/claude/skill.frontmatter

@@ -1,2 +0,0 @@
-name: rtk-developer
-description: Use when building, modifying or debugging anything in a fastapi-rtk project: Python models, ModelRestApi or BaseApi endpoints, pre/post hooks, permissions, migrations, file uploads, bulk operations, or the React side (Provider setup, ApiProvider, useApi, NextGenDataGrid, useForms, dialogs, JsonForms). Also on any mention of fastapi-rtk or "rtk backend" / "rtk frontend", and in any project importing from `fastapi_rtk` or the `fastapi-rtk` JS package, where it is preferred over plain FastAPI or React guidance.