karakeep-python-api 0.2.3__py3-none-any.whl → 1.1.0__py3-none-any.whl

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/datatypes.py

@@ -135,6 +135,7 @@ class ListModel(BaseModel):
     parentId: Optional[str]
     type: Optional[Literal["manual", "smart"]] = "manual"
     query: Optional[str] = None
+    public: bool
 
 
 class PaginatedHighlights(BaseModel):

karakeep_python_api/karakeep_api.py

@@ -77,7 +77,7 @@ class KarakeepAPI:
 
     Attributes:
         api_key (str): The API key used for authentication.
-        api_base_url (str): The base URL of the Karakeep API instance.
+        api_endpoint (str): The endpoint of the Karakeep API instance, including /api/v1 (e.g., https://instance.com/api/v1/).
         openapi_spec (dict): The parsed content of the OpenAPI specification file.
         verify_ssl (bool): Whether SSL verification is enabled.
         verbose (bool): Whether verbose logging is enabled.
@@ -85,17 +85,19 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "0.2.3"
+    VERSION: str = "1.1.0"
 
     def __init__(
         self,
         api_key: Optional[str] = None,
-        base_url: Optional[str] = None,
+        api_endpoint: Optional[str] = None,
         openapi_spec_path: Optional[str] = None,  # Allow None, default handled below
         verify_ssl: bool = True,
         verbose: bool = False,
         disable_response_validation: Optional[bool] = None,
-        rate_limit: float = 0.0,  # Minimum interval between API calls in seconds
+        rate_limit: Union[
+            float, int
+        ] = 0.0,  # Minimum interval between API calls in seconds
     ):
         """
         Initialize the Karakeep API client.
@@ -103,8 +105,9 @@ class KarakeepAPI:
         Args:
             api_key: Karakeep API key (Bearer token).
                      Defaults to KARAKEEP_PYTHON_API_KEY environment variable if not provided.
-            base_url: Override the base URL for the API. Must be provided either as an argument
-                      or via the KARAKEEP_PYTHON_API_BASE_URL environment variable.
+            api_endpoint: Override the base URL for the API. Must be provided either as an argument
+                          or via the KARAKEEP_PYTHON_API_ENDPOINT environment variable.
+                          Example: 'https://karakeep.domain.com/api/v1/'
             openapi_spec_path: Path to the OpenAPI JSON specification file.
                                Defaults to 'openapi_reference.json' alongside the package code if not provided.
                                The loaded spec is available via the `openapi_spec` attribute.
@@ -129,46 +132,46 @@ class KarakeepAPI:
         logger.debug("API Key loaded successfully.")
 
         # --- Base URL Validation ---
-        env_base_url = os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
+        env_endpoint = os.environ.get("KARAKEEP_PYTHON_API_ENDPOINT")
         logger.debug(
-            f"Checked KARAKEEP_PYTHON_API_BASE_URL environment variable, found: '{env_base_url}'"
+            f"Checked KARAKEEP_PYTHON_API_ENDPOINT environment variable, found: '{env_endpoint}'"
         )
-        logger.debug(f"Base URL provided as argument: '{base_url}'")
+        logger.debug(f"Base URL provided as argument: '{api_endpoint}'")
 
-        if base_url:
-            self.api_base_url = base_url
-            logger.info(f"Using provided base URL: {self.api_base_url}")
-        elif env_base_url:
-            self.api_base_url = env_base_url
+        if api_endpoint:
+            self.api_endpoint = api_endpoint
+            logger.info(f"Using provided base URL: {self.api_endpoint}")
+        elif env_endpoint:
+            self.api_endpoint = env_endpoint
             logger.info(
-                f"Using base URL from KARAKEEP_PYTHON_API_BASE_URL: {self.api_base_url}"
+                f"Using base URL from KARAKEEP_PYTHON_API_ENDPOINT: {self.api_endpoint}"
             )
         else:
-            # No base_url from arg or env var - raise error as per requirement
+            # No api_endpoint from arg or env var - raise error as per requirement
             raise ValueError(
-                "API base URL is required. Provide 'base_url' argument or set KARAKEEP_PYTHON_API_BASE_URL environment variable."
+                "API base URL is required. Provide 'api_endpoint' argument or set KARAKEEP_PYTHON_API_ENDPOINT environment variable."
             )
 
-        # Ensure base URL ends with /v1/
-        resolved_url = self.api_base_url  # Use a temporary variable for checks
-        if resolved_url.endswith("/v1"):
-            # Ends with /v1, needs a slash
-            self.api_base_url = resolved_url + "/"
+        # Ensure base URL ends with /api/v1/
+        resolved_url = self.api_endpoint  # Use a temporary variable for checks
+        if resolved_url.endswith("/api/v1"):
+            # Ends with /api/v1, needs a slash
+            self.api_endpoint = resolved_url + "/"
             logger.info(
-                f"Appended trailing slash to base URL ending in /v1: {self.api_base_url}"
+                f"Appended trailing slash to base URL ending in /api/v1: {self.api_endpoint}"
             )
-        elif resolved_url.endswith("/v1/"):
+        elif resolved_url.endswith("/api/v1/"):
             # Already ends correctly, do nothing
-            logger.debug(f"Base URL already ends with /v1/: {self.api_base_url}")
+            logger.debug(f"Base URL already ends with /api/v1/: {self.api_endpoint}")
         else:
-            # Doesn't end with /v1 or /v1/, append /v1/
-            # First, remove any existing trailing slash to avoid //v1/
+            # Doesn't end with /api/v1 or /api/v1/, append /api/v1/
+            # First, remove any existing trailing slash to avoid //api/v1/
             if resolved_url.endswith("/"):
                 resolved_url = resolved_url[:-1]
-            self.api_base_url = resolved_url + "/v1/"
-            logger.info(f"Appended /v1/ to base URL: {self.api_base_url}")
+            self.api_endpoint = resolved_url + "/api/v1/"
+            logger.info(f"Appended /api/v1/ to base URL: {self.api_endpoint}")
 
-        logger.debug(f"Final API Base URL after /v1/ check: {self.api_base_url}")
+        logger.debug(f"Final API Base URL after /api/v1/ check: {self.api_endpoint}")
 
         # --- Load and Parse OpenAPI Spec ---
         if openapi_spec_path is None:
@@ -255,7 +258,7 @@ class KarakeepAPI:
         # self.verbose is still used for conditional logging within the class methods.
 
         logger.debug("KarakeepAPI client initialized.")
-        logger.debug(f"  Base URL: {self.api_base_url}")
+        logger.debug(f"  Base URL: {self.api_endpoint}")
         logger.debug(f"  Verify SSL: {self.verify_ssl}")
         logger.debug(f"  Verbose: {self.verbose}")
         logger.debug(
@@ -317,9 +320,9 @@ class KarakeepAPI:
             AuthenticationError: If authentication fails (401).
             APIError: For other HTTP errors or request issues.
         """
-        # Ensure endpoint doesn't start with / if base_url ends with /
+        # Ensure endpoint doesn't start with / if endpoint ends with /
         safe_endpoint = endpoint.lstrip("/")
-        url = urljoin(self.api_base_url, safe_endpoint)
+        url = urljoin(self.api_endpoint, safe_endpoint)
 
         # Default headers
         headers = {
@@ -905,15 +908,21 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def update_a_bookmark(self, bookmark_id: str, update_data: dict) -> Dict[str, Any]:
+    def update_a_bookmark(
+        self,
+        bookmark_id: str,
+        update_data: Dict[str, Any],
+    ) -> Dict[str, Any]:
         """
         Update a bookmark by its ID. Corresponds to PATCH /bookmarks/{bookmarkId}.
-        Allows updating fields like 'archived', 'favourited', 'summary', 'note', 'title', etc.
+        Allows updating various bookmark fields including metadata, content, and status.
 
         Args:
             bookmark_id: The ID (string) of the bookmark to update.
-            update_data: A dictionary containing the fields to update (e.g., `{"archived": True}`).
-                         See the OpenAPI spec for allowed fields in the request body.
+            update_data: Dictionary containing the fields to update. Supported keys include:
+                        'title', 'archived', 'favourited', 'note', 'summary', 'createdAt',
+                        'url', 'description', 'author', 'publisher', 'datePublished',
+                        'dateModified', 'text', 'assetContent'.
 
         Returns:
             dict: A dictionary representing the updated bookmark (partial representation).
@@ -922,8 +931,13 @@ class KarakeepAPI:
                   Validation is not performed on this response type by default.
 
         Raises:
+            ValueError: If update_data is empty or no valid fields are provided to update.
             APIError: If the API request fails (e.g., 404 bookmark not found).
         """
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("update_data must contain at least one field to update.")
+
         endpoint = f"bookmarks/{bookmark_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
         # The response schema is a subset of Bookmark, return as dict as specified in spec
@@ -979,7 +993,9 @@ class KarakeepAPI:
         """
         # Validate that at least one tag source is provided
         if not tag_ids and not tag_names:
-            raise ValueError("At least one of 'tag_ids' or 'tag_names' must be provided")
+            raise ValueError(
+                "At least one of 'tag_ids' or 'tag_names' must be provided"
+            )
 
         # Validate input types
         if tag_ids is not None and not isinstance(tag_ids, list):
@@ -997,7 +1013,9 @@ class KarakeepAPI:
         if tag_names:
             for i, tag_name in enumerate(tag_names):
                 if not isinstance(tag_name, str) or not tag_name.strip():
-                    raise ValueError(f"Tag name at index {i} must be a non-empty string")
+                    raise ValueError(
+                        f"Tag name at index {i} must be a non-empty string"
+                    )
 
         # Construct the tags_data dict in the format expected by the API
         tags_list = []
@@ -1050,7 +1068,9 @@ class KarakeepAPI:
         """
         # Validate that at least one tag source is provided
         if not tag_ids and not tag_names:
-            raise ValueError("At least one of 'tag_ids' or 'tag_names' must be provided")
+            raise ValueError(
+                "At least one of 'tag_ids' or 'tag_names' must be provided"
+            )
 
         # Validate input types
         if tag_ids is not None and not isinstance(tag_ids, list):
@@ -1068,7 +1088,9 @@ class KarakeepAPI:
         if tag_names:
             for i, tag_name in enumerate(tag_names):
                 if not isinstance(tag_name, str) or not tag_name.strip():
-                    raise ValueError(f"Tag name at index {i} must be a non-empty string")
+                    raise ValueError(
+                        f"Tag name at index {i} must be a non-empty string"
+                    )
 
         # Construct the tags_data dict in the format expected by the API
         tags_list = []
@@ -1145,16 +1167,28 @@ class KarakeepAPI:
 
     @optional_typecheck
     def attach_asset(
-        self, bookmark_id: str, asset_data: dict
+        self,
+        bookmark_id: str,
+        asset_id: str,
+        asset_type: Literal[
+            "screenshot",
+            "assetScreenshot",
+            "bannerImage",
+            "fullPageArchive",
+            "video",
+            "bookmarkAsset",
+            "precrawledArchive",
+            "unknown",
+        ],
     ) -> Union[datatypes.Asset, Dict[str, Any], List[Any]]:
         """
         Attach a new asset to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/assets.
 
         Args:
             bookmark_id: The ID (string) of the bookmark.
-            asset_data: Dictionary specifying the asset to attach. Must contain "id" (string) and "assetType" (string enum).
-                        Example: `{"id": "asset_id_string", "assetType": "screenshot"}`
-                        See `datatypes.AssetType` enum for possible asset types.
+            asset_id: The ID (string) of the asset to attach.
+            asset_type: The type of asset being attached. Must be one of: "screenshot", "assetScreenshot",
+                        "bannerImage", "fullPageArchive", "video", "bookmarkAsset", "precrawledArchive", "unknown".
 
         Returns:
             datatypes.Asset: The attached asset object.
@@ -1164,6 +1198,9 @@ class KarakeepAPI:
             APIError: If the API request fails (e.g., 404 bookmark not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct the asset data dict as expected by the API
+        asset_data = {"id": asset_id, "assetType": asset_type}
+
         endpoint = f"bookmarks/{bookmark_id}/assets"
         response_data = self._call("POST", endpoint, data=asset_data)
 
@@ -1175,9 +1212,7 @@ class KarakeepAPI:
             return datatypes.Asset.model_validate(response_data)
 
     @optional_typecheck
-    def replace_asset(
-        self, bookmark_id: str, asset_id: str, new_asset_data: dict
-    ) -> None:
+    def replace_asset(self, bookmark_id: str, asset_id: str, new_asset_id: str) -> None:
         """
         Replace an existing asset associated with a bookmark with a new one.
         Corresponds to PUT /bookmarks/{bookmarkId}/assets/{assetId}.
@@ -1185,8 +1220,7 @@ class KarakeepAPI:
         Args:
             bookmark_id: The ID (string) of the bookmark.
             asset_id: The ID (string) of the asset to be replaced.
-            new_asset_data: Dictionary specifying the new asset ID. Must contain "assetId" (string).
-                            Example: `{"assetId": "new_asset_id_string"}`
+            new_asset_id: The ID (string) of the new asset to replace with.
 
         Returns:
             None: Returns None upon successful replacement (204 No Content).
@@ -1194,6 +1228,9 @@ class KarakeepAPI:
         Raises:
             APIError: If the API request fails (e.g., 404 bookmark or asset not found).
         """
+        # Construct the request body as expected by the API
+        new_asset_data = {"assetId": new_asset_id}
+
         endpoint = f"bookmarks/{bookmark_id}/assets/{asset_id}"
         self._call("PUT", endpoint, data=new_asset_data)  # Expects 204 No Content
         return None  # Explicitly return None for 204
@@ -1270,6 +1307,7 @@ class KarakeepAPI:
         parent_id: Optional[str] = None,
         list_type: Optional[Literal["manual", "smart"]] = "manual",
         query: Optional[str] = None,
+        public: bool = False,
     ) -> Union[datatypes.ListModel, Dict[str, Any], List[Any]]:
         """
         Create a new list (manual or smart). Corresponds to POST /lists.
@@ -1281,6 +1319,7 @@ class KarakeepAPI:
             parent_id: Optional parent list ID for nested lists.
             list_type: The type of list ('manual' or 'smart'). Default is 'manual'.
             query: Optional query string for smart lists (required if list_type is 'smart').
+            public: Whether the list is public (default: False).
 
         Returns:
             datatypes.ListModel: The created list object.
@@ -1300,6 +1339,7 @@ class KarakeepAPI:
             "name": name,
             "icon": icon,
             "type": list_type,
+            "public": public,
         }
 
         # Add optional fields if provided
@@ -1367,25 +1407,56 @@ class KarakeepAPI:
 
     @optional_typecheck
     def update_a_list(
-        self, list_id: str, update_data: dict
+        self,
+        list_id: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        icon: Optional[str] = None,
+        parent_id: Optional[str] = None,
+        query: Optional[str] = None,
+        public: Optional[bool] = None,
     ) -> Union[datatypes.ListModel, Dict[str, Any], List[Any]]:
         """
         Update a list by its ID. Corresponds to PATCH /lists/{listId}.
-        Allows updating fields like "name", "description", "icon", "parentId", "query".
+        Allows updating various list fields including name, description, icon, parent relationship, query, and public status.
 
         Args:
             list_id: The ID (string) of the list to update.
-            update_data: A dictionary containing the fields to update (e.g., `{"name": "new name"}`).
-                         See the OpenAPI spec for allowed fields.
+            name: Optional new name for the list (1-40 characters).
+            description: Optional new description for the list (0-100 characters, can be None to clear).
+            icon: Optional new icon for the list.
+            parent_id: Optional new parent list ID (can be None to remove parent relationship).
+            query: Optional new query string for smart lists (minimum 1 character).
+            public: Optional new public status for the list.
 
         Returns:
             datatypes.ListModel: The updated list object.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
+            ValueError: If no fields are provided to update.
             APIError: If the API request fails (e.g., 404 list not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct update_data from provided arguments, excluding None values that weren't explicitly passed
+        update_data = {}
+        if name is not None:
+            update_data["name"] = name
+        if description is not None:
+            update_data["description"] = description
+        if icon is not None:
+            update_data["icon"] = icon
+        if parent_id is not None:
+            update_data["parentId"] = parent_id
+        if query is not None:
+            update_data["query"] = query
+        if public is not None:
+            update_data["public"] = public
+
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("At least one field must be provided to update.")
+
         endpoint = f"lists/{list_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
 
@@ -1594,23 +1665,28 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def update_a_tag(self, tag_id: str, update_data: dict) -> Dict[str, Any]:
+    def update_a_tag(self, tag_id: str, update_data: Dict[str, Any]) -> Dict[str, Any]:
         """
         Update a tag by its ID. Currently only supports updating the "name".
         Corresponds to PATCH /tags/{tagId}.
 
         Args:
             tag_id: The ID (string) of the tag to update.
-            update_data: A dictionary containing the fields to update. Must include "name" (string).
-                         Example: `{"name": "new tag name"}`
+            update_data: Dictionary containing the fields to update. Supported keys include:
+                        'name' (string).
 
         Returns:
             dict: A dictionary containing the updated tag information with "id" and "name" fields.
                   Validation is not performed on this response type by default.
 
         Raises:
+            ValueError: If update_data is empty or no valid fields are provided to update.
             APIError: If the API request fails (e.g., 404 tag not found).
         """
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("update_data must contain at least one field to update.")
+
         endpoint = f"tags/{tag_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
         # Response schema is a simple dict with id and name, return as dict
@@ -1693,8 +1769,8 @@ class KarakeepAPI:
     def create_a_new_highlight(
         self,
         bookmark_id: str,
-        start_offset: float,
-        end_offset: float,
+        start_offset: Union[float, int],
+        end_offset: Union[float, int],
         color: Optional[Literal["yellow", "red", "green", "blue"]] = "yellow",
         text: Optional[str] = None,
         note: Optional[str] = None,
@@ -1796,7 +1872,9 @@ class KarakeepAPI:
 
     @optional_typecheck
     def update_a_highlight(
-        self, highlight_id: str, update_data: dict
+        self,
+        highlight_id: str,
+        color: Optional[Literal["yellow", "red", "green", "blue"]] = None,
     ) -> Union[datatypes.Highlight, Dict[str, Any], List[Any]]:
         """
         Update a highlight by its ID. Currently only supports updating the "color".
@@ -1804,17 +1882,26 @@ class KarakeepAPI:
 
         Args:
             highlight_id: The ID (string) of the highlight to update.
-            update_data: A dictionary containing the fields to update. Must include "color" (string enum).
-                         See `datatypes.Color` enum. Example: `{"color": "red"}`
+            color: Optional new color for the highlight ("yellow", "red", "green", "blue").
 
         Returns:
             datatypes.Highlight: The updated highlight object.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
+            ValueError: If no fields are provided to update.
             APIError: If the API request fails (e.g., 404 highlight not found).
             pydantic.ValidationError: If response validation fails (and is not disabled).
         """
+        # Construct update_data from provided arguments, excluding None values
+        update_data = {}
+        if color is not None:
+            update_data["color"] = color
+
+        # Ensure at least one field is being updated
+        if not update_data:
+            raise ValueError("At least one field must be provided to update.")
+
         endpoint = f"highlights/{highlight_id}"
         response_data = self._call("PATCH", endpoint, data=update_data)
 

karakeep_python_api/openapi_reference.json

@@ -426,13 +426,17 @@
           "query": {
             "type": "string",
             "nullable": true
+          },
+          "public": {
+            "type": "boolean"
           }
         },
         "required": [
           "id",
           "name",
           "icon",
-          "parentId"
+          "parentId",
+          "public"
         ]
       },
       "Tag": {
@@ -1982,6 +1986,9 @@
                   "query": {
                     "type": "string",
                     "minLength": 1
+                  },
+                  "public": {
+                    "type": "boolean"
                   }
                 }
               }

{karakeep_python_api-0.2.3.dist-info → karakeep_python_api-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 0.2.3
+Version: 1.1.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -52,6 +52,7 @@ A community-developed Python client for the [Karakeep](https://karakeep.app/) AP
   - [Environment Variables](#environment-variables)
   - [Command Line Interface (CLI)](#command-line-interface-cli)
   - [Python Library](#python-library)
+- [Community Scripts](#community-scripts)
 - [Development](#development)
 - [License](#license)
 
@@ -136,7 +137,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`).
@@ -145,7 +146,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:**
 
@@ -170,8 +171,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]'
@@ -195,14 +196,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
@@ -232,23 +233,27 @@ 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}")
 
 ```
 
-### Usage Examples
+## 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. | [`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 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) |
 
 ## Development
 
@@ -259,7 +264,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.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
+karakeep_python_api/__main__.py,sha256=X1GXwRvAAw8qFmMm2MKdmPNYkmlmEUUQalJX9kWxrS0,32402
+karakeep_python_api/datatypes.py,sha256=vcDqS8r_LRMLqrIvHZIqkvUSiucprz58jOAeC82QwHY,3415
+karakeep_python_api/karakeep_api.py,sha256=nvpynAk4S5G1-sjf0T4sl9kYjHyV12bQobd8fiMLVlg,85276
+karakeep_python_api/openapi_reference.json,sha256=9bvTkzHbgtUg-xg6T6zF3bSdxBMW1Rn5nC-l2jH6FoQ,80553
+karakeep_python_api-1.1.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+karakeep_python_api-1.1.0.dist-info/METADATA,sha256=bGJws2bLSvGXZwi6mFlpnh0NhVBXtjsSDZqybwgyQ8E,15732
+karakeep_python_api-1.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karakeep_python_api-1.1.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
+karakeep_python_api-1.1.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
+karakeep_python_api-1.1.0.dist-info/RECORD,,

karakeep_python_api-0.2.3.dist-info/RECORD

@@ -1,11 +0,0 @@
-karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
-karakeep_python_api/__main__.py,sha256=UfL6R-S3rJB7PH3iqTicNq0cvtumnrG_FVyKK36bqdE,32327
-karakeep_python_api/datatypes.py,sha256=CScuMq5oT4YwvGH8Af_Oo60xGmC622d74f4WPUw7l8Q,3398
-karakeep_python_api/karakeep_api.py,sha256=NYGvU0UIK95k841cz7Y9thWnoTAaWMRVuny7JGLjYQA,81921
-karakeep_python_api/openapi_reference.json,sha256=Ku1cO_N4QPLQc7sK8L7FRt2T68QyPCwTGA7RK-046iU,80379
-karakeep_python_api-0.2.3.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-karakeep_python_api-0.2.3.dist-info/METADATA,sha256=b6rRzFPf1OvnALa37p7CXKnzWQt6Aa3yUQK9k7Lq1UQ,13649
-karakeep_python_api-0.2.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-karakeep_python_api-0.2.3.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
-karakeep_python_api-0.2.3.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
-karakeep_python_api-0.2.3.dist-info/RECORD,,