karakeep-python-api 1.0.0__tar.gz → 1.2.0__tar.gz

{karakeep_python_api-1.0.0/karakeep_python_api.egg-info → karakeep_python_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.0.0
+Version: 1.2.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -81,7 +81,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | Method Name                      | Pytest | CLI  | Remarks                                      |
 | -------------------------------- | :----: | :--: | -------------------------------------------- |
 | `get_all_bookmarks`              |   ✅   |  ✅  | Tested with pagination.                      |
-| `create_a_new_bookmark`          |   ✅   |  ❌  | Pytest for `type="link"` via fixture. CLI not directly tested. |
+| `create_a_new_bookmark`          |   ✅   |  ❌  | Pytest for `type="link"` via fixture and `type="asset"` via PDF test. CLI not directly tested. |
 | `search_bookmarks`               |   ✅   |  ✅  | Seems to be nondeterministic and fails if using more than 3 words        |
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
@@ -112,6 +112,8 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_highlight`         |   ❌   |  ❌  |                                              |
 | `delete_a_highlight`             |   ❌   |  ❌  | Works from the CLI; not yet added to Pytest. |
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
+| `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 
@@ -137,7 +139,7 @@ This package can be used as a Python library or as a command-line interface (CLI
 
 The client can be configured using the following environment variables:
 
-*   `KARAKEEP_PYTHON_API_BASE_URL`: **Required**. The full base URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://your-karakeep.example.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
+*   `KARAKEEP_PYTHON_API_ENDPOINT`: **Required**. The full URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://karakeep.domain.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
 *   `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
 *   `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
 *   `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
@@ -146,7 +148,7 @@ The client can be configured using the following environment variables:
 
 ### Command Line Interface (CLI)
 
-The CLI dynamically generates commands based on the API methods. You need to provide your API key and base URL either via environment variables (recommended) or command-line options.
+The CLI dynamically generates commands based on the API methods. You need to provide your API key and endpoint either via environment variables (recommended) or command-line options.
 
 **Basic Structure:**
 
@@ -171,8 +173,8 @@ python -m karakeep_python_api get-all-bookmarks --help
 python -m karakeep_python_api get-all-tags
 
 # Get the first page of bookmarks with a limit, overriding env vars if needed
-# Note: Ensure the base URL includes the /api/v1/ path
-python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
+# Note: The /api/v1/ path will be automatically appended if not present
+python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
 
 # Get all lists and pipe the JSON output to jq to extract the first list
 python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -196,14 +198,14 @@ import os
 from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
 
 # Ensure required environment variables are set
-# Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
+# Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
 # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
 
 try:
     # Initialize the client (reads from env vars by default)
     client = KarakeepAPI(
         # Optionally override env vars:
-        # base_url="https://another.karakeep.com",
+        # api_endpoint="https://karakeep.domain.com/api/v1/",
         # api_key="another_key",
         # verbose=True,
         # disable_response_validation=False
@@ -233,7 +235,7 @@ except AuthenticationError as e:
 except APIError as e:
     print(f"An API error occurred: {e}")
 except ValueError as e:
-    # Handles missing API key/base URL during initialization
+    # Handles missing API key/endpoint during initialization
     print(f"Configuration error: {e}")
 except Exception as e:
     print(f"An unexpected error occurred: {e}")
@@ -242,15 +244,19 @@ except Exception as e:
 
 ## Community Scripts
 
-Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
+Community Scripts are a bunch of scripts made to solve specific issues. They are made by the community so don't hesitate to submit yours or open an issue if you have a bug. They also serve as example of how to use the API.
 
-| Example Script | Description | Documentation |
-|----------------|-------------|---------------|
-| **Add Time-to-Read Tags** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. Includes systemd service and timer files for automated periodic execution. | [`README.md`](./examples/add_time_to_read_tag/README.md) |
-| **List to Tag Converter** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list. | [`README.md`](./examples/list_to_tag/README.md) |
-| **Omnivore Highlights Importer** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing. | [`README.md`](./examples/omnivore_highlights_importer/README.md) |
-| **Omnivore Archiving Status Updater** | Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/omnivore_archiving_status_updater/README.md) |
-| **Pocket Archiving Status Updater** | Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/pocket_archiving_status_updater/README.md) |
+They can be found in the [./community_scripts](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts) folder. Don't hesitate to submit yours, the contribution guidelines are in the community_scripts directory README.md file.
+
+| Community Script | Description                                                                                                | Documentation |
+|----------------|--------------------------------------------------------------------------------------------------------------|---------------|
+| **Karakeep-Time-Tagger** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. Includes systemd service and timer files for automated periodic execution. | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-time-tagger) |
+| **Karakeep-List-To-Tag** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list.                                                                                        | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-list-to-tag) |
+| **Omnivore2Karakeep-Highlights** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing.                                | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-highlights) |
+| **Omnivore2Karakeep-Archived** | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly.                                 | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-archived) |
+| **pocket2karakeep-archived** by [@youenchene](https://github.com/youenchene) | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly.                                   | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/pocket2karakeep-archived) |
+| **Karakeep-Archive-Before-Date** by [@youenchene](https://github.com/youenchene) | Allow you to archive all not archived post before a given date                                                                                                                         | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-archive-before-date) |
+| **Freshrss-To-Karakeep**  |  Syncs some links from Freshrss to Karakeep      | [`Link`](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep) |
 
 ## Development
 
@@ -261,7 +267,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
     ```bash
     uv pip install -e ".[dev]"
     ```
-4.  Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
+4.  Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
 5.  Run tests:
 
     ```bash

{karakeep_python_api-1.0.0 → karakeep_python_api-1.2.0}/README.md

@@ -46,7 +46,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | Method Name                      | Pytest | CLI  | Remarks                                      |
 | -------------------------------- | :----: | :--: | -------------------------------------------- |
 | `get_all_bookmarks`              |   ✅   |  ✅  | Tested with pagination.                      |
-| `create_a_new_bookmark`          |   ✅   |  ❌  | Pytest for `type="link"` via fixture. CLI not directly tested. |
+| `create_a_new_bookmark`          |   ✅   |  ❌  | Pytest for `type="link"` via fixture and `type="asset"` via PDF test. CLI not directly tested. |
 | `search_bookmarks`               |   ✅   |  ✅  | Seems to be nondeterministic and fails if using more than 3 words        |
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
@@ -77,6 +77,8 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_highlight`         |   ❌   |  ❌  |                                              |
 | `delete_a_highlight`             |   ❌   |  ❌  | Works from the CLI; not yet added to Pytest. |
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
+| `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 
@@ -102,7 +104,7 @@ This package can be used as a Python library or as a command-line interface (CLI
 
 The client can be configured using the following environment variables:
 
-*   `KARAKEEP_PYTHON_API_BASE_URL`: **Required**. The full base URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://your-karakeep.example.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
+*   `KARAKEEP_PYTHON_API_ENDPOINT`: **Required**. The full URL of your Karakeep API, including the `/api/v1/` path (e.g., `https://karakeep.domain.com/api/v1/` or `https://try.karakeep.app/api/v1/`).
 *   `KARAKEEP_PYTHON_API_KEY`: **Required**. Your Karakeep API key (Bearer token).
 *   `KARAKEEP_PYTHON_API_VERIFY_SSL`: Set to `false` to disable SSL certificate verification (default: `true`).
 *   `KARAKEEP_PYTHON_API_VERBOSE`: Set to `true` to enable verbose debug logging for the client and CLI (default: `false`).
@@ -111,7 +113,7 @@ The client can be configured using the following environment variables:
 
 ### Command Line Interface (CLI)
 
-The CLI dynamically generates commands based on the API methods. You need to provide your API key and base URL either via environment variables (recommended) or command-line options.
+The CLI dynamically generates commands based on the API methods. You need to provide your API key and endpoint either via environment variables (recommended) or command-line options.
 
 **Basic Structure:**
 
@@ -136,8 +138,8 @@ python -m karakeep_python_api get-all-bookmarks --help
 python -m karakeep_python_api get-all-tags
 
 # Get the first page of bookmarks with a limit, overriding env vars if needed
-# Note: Ensure the base URL includes the /api/v1/ path
-python -m karakeep_python_api --base-url https://my.karakeep.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
+# Note: The /api/v1/ path will be automatically appended if not present
+python -m karakeep_python_api --base-url https://karakeep.domain.com/api/v1/ --api-key YOUR_API_KEY get-all-bookmarks --limit 10
 
 # Get all lists and pipe the JSON output to jq to extract the first list
 python -m karakeep_python_api get-all-lists | jq '.[0]'
@@ -161,14 +163,14 @@ import os
 from karakeep_python_api import KarakeepAPI, APIError, AuthenticationError, datatypes
 
 # Ensure required environment variables are set
-# Example: os.environ["KARAKEEP_PYTHON_API_BASE_URL"] = "https://your-karakeep.example.com/api/v1/"
+# Example: os.environ["KARAKEEP_PYTHON_API_ENDPOINT"] = "https://karakeep.domain.com/api/v1/"
 # Example: os.environ["KARAKEEP_PYTHON_API_KEY"] = "your_secret_api_key"
 
 try:
     # Initialize the client (reads from env vars by default)
     client = KarakeepAPI(
         # Optionally override env vars:
-        # base_url="https://another.karakeep.com",
+        # api_endpoint="https://karakeep.domain.com/api/v1/",
         # api_key="another_key",
         # verbose=True,
         # disable_response_validation=False
@@ -198,7 +200,7 @@ except AuthenticationError as e:
 except APIError as e:
     print(f"An API error occurred: {e}")
 except ValueError as e:
-    # Handles missing API key/base URL during initialization
+    # Handles missing API key/endpoint during initialization
     print(f"Configuration error: {e}")
 except Exception as e:
     print(f"An unexpected error occurred: {e}")
@@ -207,15 +209,19 @@ except Exception as e:
 
 ## Community Scripts
 
-Examples of the API being used can be found in the [`./examples`](./examples) folder. Don't hesitate to submit yours!
+Community Scripts are a bunch of scripts made to solve specific issues. They are made by the community so don't hesitate to submit yours or open an issue if you have a bug. They also serve as example of how to use the API.
 
-| Example Script | Description | Documentation |
-|----------------|-------------|---------------|
-| **Add Time-to-Read Tags** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. Includes systemd service and timer files for automated periodic execution. | [`README.md`](./examples/add_time_to_read_tag/README.md) |
-| **List to Tag Converter** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list. | [`README.md`](./examples/list_to_tag/README.md) |
-| **Omnivore Highlights Importer** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing. | [`README.md`](./examples/omnivore_highlights_importer/README.md) |
-| **Omnivore Archiving Status Updater** | Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/omnivore_archiving_status_updater/README.md) |
-| **Pocket Archiving Status Updater** | Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly. | [`README.md`](./examples/pocket_archiving_status_updater/README.md) |
+They can be found in the [./community_scripts](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts) folder. Don't hesitate to submit yours, the contribution guidelines are in the community_scripts directory README.md file.
+
+| Community Script | Description                                                                                                | Documentation |
+|----------------|--------------------------------------------------------------------------------------------------------------|---------------|
+| **Karakeep-Time-Tagger** | Automatically adds time-to-read tags (`0-5m`, `5-10m`, etc.) to bookmarks based on content length analysis. Includes systemd service and timer files for automated periodic execution. | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-time-tagger) |
+| **Karakeep-List-To-Tag** | Converts a Karakeep list into tags by adding a specified tag to all bookmarks within that list.                                                                                        | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-list-to-tag) |
+| **Omnivore2Karakeep-Highlights** | Imports highlights from Omnivore export data to Karakeep, with intelligent position detection and bookmark matching. Supports dry-run mode for testing.                                | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-highlights) |
+| **Omnivore2Karakeep-Archived** | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Omnivore by reading export data and updating Karakeep accordingly.                                 | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/omnivore2karakeep-archived) |
+| **pocket2karakeep-archived** by [@youenchene](https://github.com/youenchene) | (Should not be needed anymore) Fixes the archived status of bookmarks imported from Pocket by reading export data and updating Karakeep accordingly.                                   | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/pocket2karakeep-archived) |
+| **Karakeep-Archive-Before-Date** by [@youenchene](https://github.com/youenchene) | Allow you to archive all not archived post before a given date                                                                                                                         | [`Link`](https://github.com/thiswillbeyourgithub/karakeep_python_api/tree/main/community_scripts/karakeep-archive-before-date) |
+| **Freshrss-To-Karakeep**  |  Syncs some links from Freshrss to Karakeep      | [`Link`](https://github.com/thiswillbeyourgithub/freshrss_to_karakeep) |
 
 ## Development
 
@@ -226,7 +232,7 @@ Examples of the API being used can be found in the [`./examples`](./examples) fo
     ```bash
     uv pip install -e ".[dev]"
     ```
-4.  Set the required environment variables (`KARAKEEP_PYTHON_API_BASE_URL`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
+4.  Set the required environment variables (`KARAKEEP_PYTHON_API_ENDPOINT`, `KARAKEEP_PYTHON_API_KEY`) for running tests against a live instance.
 5.  Run tests:
 
     ```bash

{karakeep_python_api-1.0.0 → karakeep_python_api-1.2.0}/karakeep_python_api/__main__.py

@@ -59,9 +59,9 @@ def serialize_output(data: Any) -> Any:
 # Shared options for the API client
 shared_options = [
     click.option(
-        "--base-url",
-        envvar="KARAKEEP_PYTHON_API_BASE_URL",
-        help="Full Karakeep API base URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
+        "--api-endpoint",
+        envvar="KARAKEEP_PYTHON_API_ENDPOINT",
+        help="Full Karakeep API endpoint URL, including /api/v1/ (e.g., https://instance.com/api/v1/).",
     ),
     click.option(
         "--api-key",
@@ -151,7 +151,7 @@ def print_openapi_spec(ctx, param, value):
 @click.pass_context
 def cli(
     ctx,
-    base_url,
+    api_endpoint,
     api_key,
     verify_ssl,
     verbose,
@@ -167,7 +167,7 @@ def cli(
     # Ensure the context object exists
     ctx.ensure_object(dict)
 
-    # --- Strict Check for API Key and Base URL ---
+    # --- Strict Check for API Key and Endpoint ---
     # Check for API key (must be provided via arg or env)
     resolved_api_key = api_key or os.environ.get("KARAKEEP_PYTHON_API_KEY")
     if not resolved_api_key:
@@ -175,16 +175,18 @@ def cli(
             "API Key is required. Provide --api-key option or set KARAKEEP_PYTHON_API_KEY environment variable."
         )
 
-    # Check for Base URL (must be provided via arg or env)
-    resolved_base_url = base_url or os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
-    if not resolved_base_url:
+    # Check for API endpoint (must be provided via arg or env)
+    resolved_api_endpoint = api_endpoint or os.environ.get(
+        "KARAKEEP_PYTHON_API_ENDPOINT"
+    )
+    if not resolved_api_endpoint:
         raise click.UsageError(
-            "API Base URL is required. Provide --base-url option or set KARAKEEP_PYTHON_API_BASE_URL environment variable. "
+            "API endpoint is required. Provide --api-endpoint option or set KARAKEEP_PYTHON_API_ENDPOINT environment variable. "
             "The URL must include the API path, e.g., 'https://your-instance.com/api/v1/'."
         )
 
     # Store common API parameters in the context for commands to use
-    ctx.obj["BASE_URL"] = resolved_base_url  # Store the resolved URL
+    ctx.obj["API_ENDPOINT"] = resolved_api_endpoint  # Store the resolved endpoint
     ctx.obj["API_KEY"] = resolved_api_key  # Store the resolved key
     ctx.obj["VERIFY_SSL"] = verify_ssl
     ctx.obj["VERBOSE"] = verbose
@@ -231,7 +233,7 @@ def create_click_command(
         def command_func(ctx, **kwargs):
             """Dynamically generated command function wrapper."""
             # Retrieve API parameters from context, ensuring API key is present now
-            base_url = ctx.obj["BASE_URL"]
+            api_endpoint = ctx.obj["API_ENDPOINT"]
             api_key = ctx.obj["API_KEY"]
             verify_ssl = ctx.obj["VERIFY_SSL"]
             verbose = ctx.obj["VERBOSE"]
@@ -250,7 +252,7 @@ def create_click_command(
                 # Method generation already happened during inspection phase or initial load
                 api = KarakeepAPI(
                     api_key=api_key,
-                    base_url=base_url,
+                    api_endpoint=api_endpoint,
                     verify_ssl=verify_ssl,
                     verbose=verbose,
                     disable_response_validation=disable_validation,  # Pass flag to constructor

{karakeep_python_api-1.0.0 → karakeep_python_api-1.2.0}/karakeep_python_api/datatypes.py

@@ -78,7 +78,7 @@ class ContentTypeAsset(BaseModel):
     content: Optional[str] = None
 
 
-class Asset(BaseModel):
+class BookmarkAsset(BaseModel):
     id: str
     assetType: Literal[
         "screenshot",
@@ -92,6 +92,13 @@ class Asset(BaseModel):
     ]
 
 
+class Asset(BaseModel):
+    assetId: str
+    contentType: str
+    size: float
+    fileName: str
+
+
 class Bookmark(BaseModel):
     id: str
     createdAt: str
@@ -107,7 +114,7 @@ class Bookmark(BaseModel):
     content: Union[
         ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
     ]
-    assets: List[Asset]
+    assets: List[BookmarkAsset]
 
 
 class PaginatedBookmarks(BaseModel):
@@ -135,6 +142,7 @@ class ListModel(BaseModel):
     parentId: Optional[str]
     type: Optional[Literal["manual", "smart"]] = "manual"
     query: Optional[str] = None
+    public: bool
 
 
 class PaginatedHighlights(BaseModel):