Merge pull request #7 from FoxNoseTech/feat/flux-introspection-sdk

feat: add Flux introspection support and API folder route descriptions (v0.4.0)

Author: loookashow

README.md

@@ -16,6 +16,7 @@ This is the official Python SDK for FoxNose Management and Flux APIs.
 - **Sync and async** - Both synchronous and asynchronous clients
 - **Automatic retries** - Configurable retry with exponential backoff
 - **JWT authentication** - Built-in token refresh support
+- **Flux introspection** - Discover routes and live schema via `/_router` and `/_schema`
 
 ## Documentation
 

docs/changelog.md

@@ -5,7 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.4.0] - 2026-02-25
+
+### Added
+
+- **Flux introspection methods** on sync and async clients:
+  - `get_router()` calls `GET /{api_prefix}/_router`
+  - `get_schema(folder_path)` calls `GET /{api_prefix}/{folder_path}/_schema`
+- **API folder route description support** in Management clients:
+  - `add_api_folder()` and `update_api_folder()` now accept:
+    - `description_get_one`
+    - `description_get_many`
+    - `description_search`
+    - `description_schema`
+- **`APIFolderSummary` model fields** for route descriptions:
+  - `description_get_one`
+  - `description_get_many`
+  - `description_search`
+  - `description_schema`
 
 ## [0.3.0] - 2026-02-10
 
@@ -62,7 +79,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Error handling guide
 - Code examples
 
-[Unreleased]: https://github.com/foxnose/python-sdk/compare/v0.3.0...HEAD
+[0.4.0]: https://github.com/foxnose/python-sdk/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/foxnose/python-sdk/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/foxnose/python-sdk/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/foxnose/python-sdk/releases/tag/v0.1.0

docs/flux-client.md

@@ -89,6 +89,34 @@ for item in results["results"]:
     print(item["data"]["title"])
 ```
 
+## Introspection Endpoints
+
+Use Flux introspection to discover available routes and live schema metadata at runtime.
+
+### Router Introspection
+
+```python
+router = client.get_router()
+print(router["api"])
+print(f"Discovered routes: {len(router['routes'])}")
+```
+
+### Schema Introspection
+
+```python
+schema = client.get_schema("blog-posts")
+print(schema["path"])
+print(schema["searchable_fields"])
+print(schema["json_schema"]["type"])
+```
+
+Async usage:
+
+```python
+router = await client.get_router()
+schema = await client.get_schema("blog-posts")
+```
+
 ## Query Parameters
 
 ### Filtering

docs/management-client.md

@@ -85,6 +85,35 @@ def publish_all(client, folder: FolderRef):
         # ...
 ```
 
+## API Folder Route Descriptions
+
+When connecting a folder to a Flux API, you can configure per-route descriptions used by Flux `/_router` introspection.
+
+```python
+connection = client.add_api_folder(
+    api_key="api-key",
+    folder_key="folder-key",
+    allowed_methods=["get_many", "get_one"],
+    description_get_one="Get one article by key",
+    description_get_many="List published articles",
+    description_search="Search published articles",
+    description_schema="Read article schema",
+)
+
+print(connection.description_schema)
+```
+
+To update descriptions later:
+
+```python
+updated = client.update_api_folder(
+    "api-key",
+    "folder-key",
+    description_get_many="Public article feed",
+    description_search="Search feed items",
+)
+```
+
 ## Folder Operations
 
 ### List Folders

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "foxnose-sdk"
-version = "0.3.0"
+version = "0.4.0"
 description = "Official Python client for FoxNose Management and Flux APIs"
 readme = "README.md"
 license = {text = "Apache-2.0"}

src/foxnose_sdk/__init__.py

@@ -154,4 +154,4 @@
     "APIRef",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"

src/foxnose_sdk/flux/client.py

@@ -83,6 +83,16 @@ def search(
         path = self._build_path(folder_path, suffix="/_search")
         return self._transport.request("POST", path, json_body=body)
 
+    def get_router(self) -> Any:
+        """Return available routes and contracts under the configured API prefix."""
+        path = f"/{self.api_prefix}/_router"
+        return self._transport.request("GET", path)
+
+    def get_schema(self, folder_path: str) -> Any:
+        """Return live JSON Schema and metadata for the given folder path."""
+        path = self._build_path(folder_path, suffix="/_schema")
+        return self._transport.request("GET", path)
+
     def close(self) -> None:
         self._transport.close()
 
@@ -153,5 +163,15 @@ async def search(
         path = self._build_path(folder_path, suffix="/_search")
         return await self._transport.arequest("POST", path, json_body=body)
 
+    async def get_router(self) -> Any:
+        """Return available routes and contracts under the configured API prefix."""
+        path = f"/{self.api_prefix}/_router"
+        return await self._transport.arequest("GET", path)
+
+    async def get_schema(self, folder_path: str) -> Any:
+        """Return live JSON Schema and metadata for the given folder path."""
+        path = self._build_path(folder_path, suffix="/_schema")
+        return await self._transport.arequest("GET", path)
+
     async def aclose(self) -> None:
         await self._transport.aclose()

src/foxnose_sdk/management/client.py

@@ -543,19 +543,35 @@ def add_api_folder(
         folder_key: FolderRef,
         *,
         allowed_methods: list[str] | None = None,
+        description_get_one: str | None = None,
+        description_get_many: str | None = None,
+        description_search: str | None = None,
+        description_schema: str | None = None,
     ) -> APIFolderSummary:
         """Add a folder to an API.
 
         Args:
             api_key: Unique identifier of the API.
             folder_key: Unique identifier of the folder to add.
             allowed_methods: HTTP methods allowed for this folder (e.g., ["GET", "POST"]).
+            description_get_one: Optional short description for the get-one route.
+            description_get_many: Optional short description for the list route.
+            description_search: Optional short description for the search route.
+            description_schema: Optional short description for the schema route.
         """
         api_key = _resolve_key(api_key)
         folder_key = _resolve_key(folder_key)
         payload: dict[str, Any] = {"folder": folder_key}
-        if allowed_methods:
+        if allowed_methods is not None:
             payload["allowed_methods"] = allowed_methods
+        if description_get_one is not None:
+            payload["description_get_one"] = description_get_one
+        if description_get_many is not None:
+            payload["description_get_many"] = description_get_many
+        if description_search is not None:
+            payload["description_search"] = description_search
+        if description_schema is not None:
+            payload["description_schema"] = description_schema
         data = self.request(
             "POST", f"{self._api_folders_root(api_key)}/", json_body=payload
         )
@@ -581,19 +597,35 @@ def update_api_folder(
         folder_key: FolderRef,
         *,
         allowed_methods: list[str] | None = None,
+        description_get_one: str | None = None,
+        description_get_many: str | None = None,
+        description_search: str | None = None,
+        description_schema: str | None = None,
     ) -> APIFolderSummary:
         """Update a folder's configuration within an API.
 
         Args:
             api_key: Unique identifier of the API.
             folder_key: Unique identifier of the folder.
             allowed_methods: HTTP methods allowed for this folder.
+            description_get_one: Optional short description for the get-one route.
+            description_get_many: Optional short description for the list route.
+            description_search: Optional short description for the search route.
+            description_schema: Optional short description for the schema route.
         """
         api_key = _resolve_key(api_key)
         folder_key = _resolve_key(folder_key)
         payload: dict[str, Any] = {}
         if allowed_methods is not None:
             payload["allowed_methods"] = allowed_methods
+        if description_get_one is not None:
+            payload["description_get_one"] = description_get_one
+        if description_get_many is not None:
+            payload["description_get_many"] = description_get_many
+        if description_search is not None:
+            payload["description_search"] = description_search
+        if description_schema is not None:
+            payload["description_schema"] = description_schema
         data = self.request(
             "PUT", f"{self._api_folders_root(api_key)}/{folder_key}/", json_body=payload
         )
@@ -2515,12 +2547,24 @@ async def add_api_folder(
         folder_key: FolderRef,
         *,
         allowed_methods: list[str] | None = None,
+        description_get_one: str | None = None,
+        description_get_many: str | None = None,
+        description_search: str | None = None,
+        description_schema: str | None = None,
     ) -> APIFolderSummary:
         api_key = _resolve_key(api_key)
         folder_key = _resolve_key(folder_key)
         payload: dict[str, Any] = {"folder": folder_key}
-        if allowed_methods:
+        if allowed_methods is not None:
             payload["allowed_methods"] = allowed_methods
+        if description_get_one is not None:
+            payload["description_get_one"] = description_get_one
+        if description_get_many is not None:
+            payload["description_get_many"] = description_get_many
+        if description_search is not None:
+            payload["description_search"] = description_search
+        if description_schema is not None:
+            payload["description_schema"] = description_schema
         data = await self.request(
             "POST", f"{self._api_folders_root(api_key)}/", json_body=payload
         )
@@ -2542,12 +2586,24 @@ async def update_api_folder(
         folder_key: FolderRef,
         *,
         allowed_methods: list[str] | None = None,
+        description_get_one: str | None = None,
+        description_get_many: str | None = None,
+        description_search: str | None = None,
+        description_schema: str | None = None,
     ) -> APIFolderSummary:
         api_key = _resolve_key(api_key)
         folder_key = _resolve_key(folder_key)
         payload: dict[str, Any] = {}
         if allowed_methods is not None:
             payload["allowed_methods"] = allowed_methods
+        if description_get_one is not None:
+            payload["description_get_one"] = description_get_one
+        if description_get_many is not None:
+            payload["description_get_many"] = description_get_many
+        if description_search is not None:
+            payload["description_search"] = description_search
+        if description_schema is not None:
+            payload["description_schema"] = description_schema
         data = await self.request(
             "PUT", f"{self._api_folders_root(api_key)}/{folder_key}/", json_body=payload
         )

src/foxnose_sdk/management/models.py

@@ -297,6 +297,10 @@ class APIFolderSummary(BaseModel):
     api: str | None = None
     path: str | None = None
     allowed_methods: list[str] | None = None
+    description_get_one: str | None = None
+    description_get_many: str | None = None
+    description_search: str | None = None
+    description_schema: str | None = None
     created_at: datetime | None = None