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

{karakeep_python_api-1.1.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.1.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`         |   ✅   |  ✅  |                                              |
 
@@ -246,14 +248,15 @@ Community Scripts are a bunch of scripts made to solve specific issues. They are
 
 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 |
-|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| 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) |
+| **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
 

{karakeep_python_api-1.1.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`         |   ✅   |  ✅  |                                              |
 
@@ -211,14 +213,15 @@ Community Scripts are a bunch of scripts made to solve specific issues. They are
 
 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 |
-|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| 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) |
+| **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
 

{karakeep_python_api-1.1.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):

{karakeep_python_api-1.1.0 → karakeep_python_api-1.2.0}/karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.1.0"
+    VERSION: str = "1.2.0"
 
     def __init__(
         self,
@@ -105,7 +105,7 @@ class KarakeepAPI:
         Args:
             api_key: Karakeep API key (Bearer token).
                      Defaults to KARAKEEP_PYTHON_API_KEY environment variable if not provided.
-            api_endpoint: Override the base URL for the API. Must be provided either as an argument
+            api_endpoint: Override the endpoint 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.
@@ -131,47 +131,47 @@ class KarakeepAPI:
         self.api_key = resolved_api_key
         logger.debug("API Key loaded successfully.")
 
-        # --- Base URL Validation ---
+        # --- Endpoint Validation ---
         env_endpoint = os.environ.get("KARAKEEP_PYTHON_API_ENDPOINT")
         logger.debug(
             f"Checked KARAKEEP_PYTHON_API_ENDPOINT environment variable, found: '{env_endpoint}'"
         )
-        logger.debug(f"Base URL provided as argument: '{api_endpoint}'")
+        logger.debug(f"Endpoint provided as argument: '{api_endpoint}'")
 
         if api_endpoint:
             self.api_endpoint = api_endpoint
-            logger.info(f"Using provided base URL: {self.api_endpoint}")
+            logger.info(f"Using provided endpoint: {self.api_endpoint}")
         elif env_endpoint:
             self.api_endpoint = env_endpoint
             logger.info(
-                f"Using base URL from KARAKEEP_PYTHON_API_ENDPOINT: {self.api_endpoint}"
+                f"Using endpoint from KARAKEEP_PYTHON_API_ENDPOINT: {self.api_endpoint}"
             )
         else:
             # No api_endpoint from arg or env var - raise error as per requirement
             raise ValueError(
-                "API base URL is required. Provide 'api_endpoint' argument or set KARAKEEP_PYTHON_API_ENDPOINT environment variable."
+                "API endpoint is required. Provide 'api_endpoint' argument or set KARAKEEP_PYTHON_API_ENDPOINT environment variable."
             )
 
-        # Ensure base URL ends with /api/v1/
+        # Ensure endpoint 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 /api/v1: {self.api_endpoint}"
+                f"Appended trailing slash to endpoint ending in /api/v1: {self.api_endpoint}"
             )
         elif resolved_url.endswith("/api/v1/"):
             # Already ends correctly, do nothing
-            logger.debug(f"Base URL already ends with /api/v1/: {self.api_endpoint}")
+            logger.debug(f"Endpoint already ends with /api/v1/: {self.api_endpoint}")
         else:
             # 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_endpoint = resolved_url + "/api/v1/"
-            logger.info(f"Appended /api/v1/ to base URL: {self.api_endpoint}")
+            logger.info(f"Appended /api/v1/ to endpoint: {self.api_endpoint}")
 
-        logger.debug(f"Final API Base URL after /api/v1/ check: {self.api_endpoint}")
+        logger.debug(f"Final API Endpoint after /api/v1/ check: {self.api_endpoint}")
 
         # --- Load and Parse OpenAPI Spec ---
         if openapi_spec_path is None:
@@ -258,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_endpoint}")
+        logger.debug(f"  Endpoint: {self.api_endpoint}")
         logger.debug(f"  Verify SSL: {self.verify_ssl}")
         logger.debug(f"  Verbose: {self.verbose}")
         logger.debug(
@@ -295,26 +295,29 @@ class KarakeepAPI:
         data: Optional[
             Union[BaseModel, dict, list, str, bytes]
         ] = None,  # More specific type hint
+        files: Optional[Dict[str, Any]] = None,
         extra_headers: Optional[Dict[str, str]] = None,
-    ) -> Union[Dict[str, Any], List[Any], None]:
+    ) -> Union[Dict[str, Any], List[Any], None, bytes]:
         """
         Internal method to make an HTTP call to the Karakeep API. Handles authentication,
         request formatting, response parsing, and error handling.
 
         Args:
             method: HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE').
-            endpoint: API endpoint path relative to the base URL (e.g., 'bookmarks' or 'bookmarks/some_id').
+            endpoint: API endpoint path relative to the endpoint (e.g., 'bookmarks' or 'bookmarks/some_id').
                       Path parameters (like {bookmarkId}) MUST be substituted *before* calling _call.
             params: Dictionary of URL query parameters. Values should be primitive types suitable for URLs.
             data: Request body data. Can be a Pydantic model, dict, list, bytes, or str.
                   - Pydantic models, dicts, and lists will be automatically JSON-encoded
                     with 'Content-Type: application/json' unless overridden in extra_headers.
                   - For bytes or str, ensure 'Content-Type' is set correctly via extra_headers if needed.
+            files: Dictionary for file uploads (multipart/form-data). If provided, data parameter is ignored.
             extra_headers: Additional headers to include or override default headers.
 
         Returns:
-            The parsed JSON response from the API as a dict or list, or None for 204 No Content responses.
-            The calling wrapper method is responsible for further parsing/validation into specific Pydantic models.
+            The parsed JSON response from the API as a dict or list, None for 204 No Content responses,
+            or raw bytes for non-JSON responses. The calling wrapper method is responsible for further
+            parsing/validation into specific Pydantic models.
 
         Raises:
             AuthenticationError: If authentication fails (401).
@@ -346,7 +349,16 @@ class KarakeepAPI:
         # Determine Content-Type, prioritizing extra_headers
         content_type = headers.get("Content-Type")
 
-        if data is not None:
+        # Handle file uploads (multipart/form-data)
+        if files is not None:
+            # When files are provided, let requests handle Content-Type automatically
+            # Don't set Content-Type header for multipart uploads
+            if "Content-Type" in headers:
+                # Remove Content-Type if it was set, let requests set it for multipart
+                headers.pop("Content-Type")
+            # Don't process data when files are provided
+            request_body_arg = None
+        elif data is not None:
             if isinstance(data, BaseModel):
                 # Serialize Pydantic model to JSON bytes
                 request_body_arg = data.model_dump_json(
@@ -471,6 +483,7 @@ class KarakeepAPI:
                         url=url,
                         params=request_params,  # Use params with stringified booleans
                         data=request_body_arg,  # Serialized data (bytes or str)
+                        files=files,  # File uploads for multipart/form-data
                         headers=headers,
                         verify=self.verify_ssl,
                         timeout=60,  # Increased default timeout
@@ -515,28 +528,42 @@ class KarakeepAPI:
                     logger.debug("  Body: None (204 No Content or empty response body)")
                 return None
 
-            # Attempt to parse successful response as JSON
-            try:
-                result = response.json()
+            # Check if the response is expected to be JSON based on Accept header
+            accept_header = headers.get("Accept", "application/json")
+            expects_json = "application/json" in accept_header
+
+            # Attempt to parse successful response as JSON if we expect JSON
+            if expects_json:
+                try:
+                    result = response.json()
+                    if self.verbose:
+                        # Log parsed response body carefully
+                        log_resp_str = repr(result)
+                        if len(log_resp_str) > 1000:
+                            log_resp_str = log_resp_str[:1000] + "...(truncated)"
+                        logger.debug(f"  Body (JSON Parsed): {log_resp_str}")
+                    # Return the raw parsed JSON (dict/list). Deserialization into
+                    # specific Pydantic models should happen in the calling wrapper method.
+                    return result
+                except json.JSONDecodeError as e:
+                    # Handle cases where the response is successful (2xx) but not valid JSON
+                    logger.error(
+                        f"API Error: Failed to decode JSON response from {method} {url}. Status: {response.status_code}. Content: {response.text[:500]}..."
+                    )
+                    # Raise APIError as the response format is unexpected
+                    raise APIError(
+                        message=f"Failed to parse successful API response JSON from {url}: {e}. Response text: {response.text[:200]}...",
+                        status_code=response.status_code,
+                    ) from e
+            else:
+                # For non-JSON responses (like asset downloads), return raw bytes
                 if self.verbose:
-                    # Log parsed response body carefully
-                    log_resp_str = repr(result)
-                    if len(log_resp_str) > 1000:
-                        log_resp_str = log_resp_str[:1000] + "...(truncated)"
-                    logger.debug(f"  Body (JSON Parsed): {log_resp_str}")
-                # Return the raw parsed JSON (dict/list). Deserialization into
-                # specific Pydantic models should happen in the calling wrapper method.
-                return result
-            except json.JSONDecodeError as e:
-                # Handle cases where the response is successful (2xx) but not valid JSON
-                logger.error(
-                    f"API Error: Failed to decode JSON response from {method} {url}. Status: {response.status_code}. Content: {response.text[:500]}..."
-                )
-                # Raise APIError as the response format is unexpected
-                raise APIError(
-                    message=f"Failed to parse successful API response JSON from {url}: {e}. Response text: {response.text[:200]}...",
-                    status_code=response.status_code,
-                ) from e
+                    content_type = response.headers.get("Content-Type", "unknown")
+                    content_length = len(response.content)
+                    logger.debug(
+                        f"  Body (Binary): {content_length} bytes, Content-Type: {content_type}"
+                    )
+                return response.content
 
         except requests.exceptions.HTTPError as e:
             # Handle 4xx/5xx errors raised by response.raise_for_status()
@@ -1180,7 +1207,7 @@ class KarakeepAPI:
             "precrawledArchive",
             "unknown",
         ],
-    ) -> Union[datatypes.Asset, Dict[str, Any], List[Any]]:
+    ) -> Union[datatypes.BookmarkAsset, Dict[str, Any], List[Any]]:
         """
         Attach a new asset to a bookmark. Corresponds to POST /bookmarks/{bookmarkId}/assets.
 
@@ -1191,7 +1218,7 @@ class KarakeepAPI:
                         "bannerImage", "fullPageArchive", "video", "bookmarkAsset", "precrawledArchive", "unknown".
 
         Returns:
-            datatypes.Asset: The attached asset object.
+            datatypes.BookmarkAsset: The attached asset object.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
@@ -1208,8 +1235,8 @@ class KarakeepAPI:
             logger.debug("Skipping response validation as requested.")
             return response_data
         else:
-            # Response should match Asset schema
-            return datatypes.Asset.model_validate(response_data)
+            # Response should match BookmarkAsset schema
+            return datatypes.BookmarkAsset.model_validate(response_data)
 
     @optional_typecheck
     def replace_asset(self, bookmark_id: str, asset_id: str, new_asset_id: str) -> None:
@@ -1943,3 +1970,125 @@ class KarakeepAPI:
         response_data = self._call("GET", "users/me/stats")
         # No Pydantic validation applied here as the spec defines a simple dict response
         return response_data
+
+    @optional_typecheck
+    def upload_a_new_asset(
+        self, file: str
+    ) -> Union[datatypes.Asset, Dict[str, Any], List[Any]]:
+        """
+        Upload a new asset file. Corresponds to POST /assets.
+
+        Args:
+            file: Path to the file to upload.
+
+        Returns:
+            datatypes.Asset: Details about the uploaded asset (assetId, contentType, size, fileName).
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            FileNotFoundError: If the specified file does not exist.
+            APIError: If the API request fails (e.g., unsupported file type, file too large).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        import os
+        import mimetypes
+
+        # Validate file path exists
+        if not os.path.isfile(file):
+            raise FileNotFoundError(f"File not found: {file}")
+
+        # Get filename from path
+        file_name = os.path.basename(file)
+
+        # Detect MIME type
+        mime_type, _ = mimetypes.guess_type(file)
+        if mime_type is None:
+            mime_type = "application/octet-stream"
+
+        if self.verbose:
+            logger.debug(
+                f"Uploading asset: {file} (filename: {file_name}, type: {mime_type})"
+            )
+
+        # Prepare file for upload
+        try:
+            with open(file, "rb") as f:
+                file_content = f.read()
+            # Note: The 'file' key must match the OpenAPI spec parameter name
+            files = {"file": (file_name, file_content, mime_type)}
+            response_data = self._call("POST", "assets", files=files)
+        except IOError as e:
+            raise APIError(f"Failed to read file {file}: {e}") from e
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match Asset schema
+            return datatypes.Asset.model_validate(response_data)
+
+    @optional_typecheck
+    def get_a_single_asset(self, asset_id: str) -> bytes:
+        """
+        Get the raw content of an asset by its ID. Corresponds to GET /assets/{assetId}.
+
+        Args:
+            asset_id: The ID (string) of the asset to retrieve.
+
+        Returns:
+            bytes: The raw asset content. The Content-Type is determined by the asset type.
+                   Use response headers to determine the actual content type if needed.
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 asset not found).
+            ValueError: If asset_id is empty or invalid.
+
+        Note:
+            This method always returns raw bytes regardless of the disable_response_validation setting,
+            as the response is binary content rather than JSON.
+        """
+        # Validate asset_id
+        if not asset_id or not asset_id.strip():
+            raise ValueError("asset_id cannot be empty")
+
+        asset_id = asset_id.strip()
+
+        # Validate asset_id format (basic check for reasonable ID format)
+        if len(asset_id) < 5:  # Assuming asset IDs are at least 5 characters
+            raise ValueError(f"asset_id appears to be invalid: {asset_id}")
+
+        endpoint = f"assets/{asset_id}"
+
+        # Override the Accept header to get raw content instead of JSON
+        # This is crucial for the assets endpoint to return binary data
+        extra_headers = {"Accept": "*/*"}
+
+        if self.verbose:
+            logger.debug(f"Retrieving asset: {asset_id}")
+
+        response_data = self._call("GET", endpoint, extra_headers=extra_headers)
+
+        # The _call method should return bytes for non-JSON responses when Accept is not application/json
+        if isinstance(response_data, bytes):
+            if self.verbose:
+                logger.debug(f"Retrieved asset {asset_id}: {len(response_data)} bytes")
+            return response_data
+        elif response_data is None:
+            # Handle empty response (valid for some assets like empty files)
+            if self.verbose:
+                logger.debug(f"Retrieved empty asset {asset_id}")
+            return b""
+        else:
+            # This shouldn't happen with the updated _call method, but handle gracefully
+            error_msg = f"Expected bytes from asset endpoint for asset {asset_id}, got {type(response_data).__name__}"
+            if isinstance(response_data, (dict, list)):
+                # If we got JSON, it might be an error response that wasn't caught
+                error_detail = (
+                    str(response_data)[:200] + "..."
+                    if len(str(response_data)) > 200
+                    else str(response_data)
+                )
+                error_msg += f". Response content: {error_detail}"
+
+            logger.error(error_msg)
+            raise APIError(error_msg)

{karakeep_python_api-1.1.0 → karakeep_python_api-1.2.0}/karakeep_python_api/openapi_reference.json

@@ -25,10 +25,6 @@
       }
     },
     "schemas": {
-      "AssetId": {
-        "type": "string",
-        "example": "ieidlxygmwj87oxz5hxttoc8"
-      },
       "BookmarkId": {
         "type": "string",
         "example": "ieidlxygmwj87oxz5hxttoc8"
@@ -45,6 +41,10 @@
         "type": "string",
         "example": "ieidlxygmwj87oxz5hxttoc8"
       },
+      "AssetId": {
+        "type": "string",
+        "example": "ieidlxygmwj87oxz5hxttoc8"
+      },
       "Bookmark": {
         "type": "object",
         "properties": {
@@ -488,17 +488,33 @@
           "highlights",
           "nextCursor"
         ]
-      }
-    },
-    "parameters": {
-      "AssetId": {
-        "schema": {
-          "$ref": "#/components/schemas/AssetId"
+      },
+      "Asset": {
+        "type": "object",
+        "properties": {
+          "assetId": {
+            "type": "string"
+          },
+          "contentType": {
+            "type": "string"
+          },
+          "size": {
+            "type": "number"
+          },
+          "fileName": {
+            "type": "string"
+          }
         },
-        "required": true,
-        "name": "assetId",
-        "in": "path"
+        "required": [
+          "assetId",
+          "contentType",
+          "size",
+          "fileName"
+        ]
       },
+      "File to be uploaded": {}
+    },
+    "parameters": {
       "BookmarkId": {
         "schema": {
           "$ref": "#/components/schemas/BookmarkId"
@@ -530,6 +546,14 @@
         "required": true,
         "name": "highlightId",
         "in": "path"
+      },
+      "AssetId": {
+        "schema": {
+          "$ref": "#/components/schemas/AssetId"
+        },
+        "required": true,
+        "name": "assetId",
+        "in": "path"
       }
     }
   },
@@ -3031,6 +3055,74 @@
           }
         }
       }
+    },
+    "/assets": {
+      "post": {
+        "description": "Upload a new asset",
+        "summary": "Upload a new asset",
+        "tags": [
+          "Assets"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "description": "The data to create the asset with.",
+          "content": {
+            "multipart/form-data": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "file": {
+                    "$ref": "#/components/schemas/File to be uploaded"
+                  }
+                },
+                "required": [
+                  "file"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Details about the created asset",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Asset"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/assets/{assetId}": {
+      "get": {
+        "description": "Get asset by its id",
+        "summary": "Get a single asset",
+        "tags": [
+          "Assets"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AssetId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Asset content. Content type is determined by the asset type."
+          }
+        }
+      }
     }
   }
 }

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.1.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`         |   ✅   |  ✅  |                                              |
 
@@ -246,14 +248,15 @@ Community Scripts are a bunch of scripts made to solve specific issues. They are
 
 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 |
-|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
+| 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) |
+| **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
 

{karakeep_python_api-1.1.0 → karakeep_python_api-1.2.0}/setup.py

@@ -7,7 +7,7 @@ with open("README.md", "r") as readme:
 
 setup(
     name="karakeep_python_api",
-    version="1.1.0",
+    version="1.2.0",
     description="Community python client for the Karakeep API.",  # Simplified description
     long_description=long_description,
     long_description_content_type="text/markdown",

{karakeep_python_api-1.1.0 → karakeep_python_api-1.2.0}/tests/test_karakeep_api.py

@@ -237,7 +237,7 @@ def test_openapi_spec_accessible(karakeep_client: KarakeepAPI):
     # The closest CLI equivalent is dumping the spec file content
     try:
         logger.info("\n  Running CLI equivalent: --dump-openapi-specification")
-        # This command doesn't require API key or base URL
+        # This command doesn't require API key or endpoint
         subprocess.run(
             "python -m karakeep_python_api --dump-openapi-specification",
             shell=True,
@@ -803,4 +803,89 @@ def test_get_current_user_stats(karakeep_client: KarakeepAPI):
         pytest.fail(f"An unexpected error occurred running the CLI command: {e}")
 
 
+def test_asset_lifecycle_with_pdf(karakeep_client: KarakeepAPI):
+    """Test creating a PDF bookmark, verifying its asset, and deleting it."""
+    pdf_file_path = "tests/PDF Bookmark Sample.pdf"
+    uploaded_asset_id = None
+    created_bookmark_id = None
+
+    # Generate unique title to avoid collisions
+    timestamp = int(time.time())
+    random_suffix = "".join(random.choices(string.ascii_lowercase + string.digits, k=6))
+    bookmark_title = f"Test PDF Bookmark {timestamp}-{random_suffix}"
+
+    try:
+        # 1. Upload the PDF asset
+        logger.info(f"\nUploading PDF asset from: {pdf_file_path}")
+        uploaded_asset = karakeep_client.upload_a_new_asset(file=pdf_file_path)
+        assert isinstance(uploaded_asset, datatypes.Asset)
+        assert uploaded_asset.assetId, "Uploaded asset must have an ID"
+        assert "pdf" in uploaded_asset.contentType.lower(), "Asset should be PDF type"
+        assert (
+            uploaded_asset.fileName == "PDF Bookmark Sample.pdf"
+        ), "Asset filename should match the original file"
+        uploaded_asset_id = uploaded_asset.assetId
+        logger.info(f"✓ PDF uploaded with asset ID: {uploaded_asset_id}")
+
+        # 2. Create a PDF bookmark using the uploaded asset
+        logger.info(f"\nCreating PDF bookmark with title: '{bookmark_title}'")
+        bookmark = karakeep_client.create_a_new_bookmark(
+            type="asset",
+            asset_type="pdf",
+            assetId=uploaded_asset_id,
+            title=bookmark_title,
+            fileName="PDF Bookmark Sample.pdf",
+        )
+        assert isinstance(bookmark, datatypes.Bookmark)
+        assert bookmark.id, "Created bookmark must have an ID"
+        assert bookmark.title == bookmark_title, "Bookmark title should match"
+        created_bookmark_id = bookmark.id
+        logger.info(f"✓ PDF bookmark created with ID: {created_bookmark_id}")
+
+        # 3. Verify the bookmark has the correct asset
+        logger.info(f"\nVerifying bookmark {created_bookmark_id} has the PDF asset")
+        retrieved_bookmark = karakeep_client.get_a_single_bookmark(
+            bookmark_id=created_bookmark_id
+        )
+        assert isinstance(retrieved_bookmark, datatypes.Bookmark)
+        assert (
+            len(retrieved_bookmark.assets) > 0
+        ), "Bookmark should have at least one asset"
+
+        # Check that our uploaded asset is among the bookmark's assets
+        asset_ids = [asset.id for asset in retrieved_bookmark.assets]
+        assert (
+            uploaded_asset_id in asset_ids
+        ), f"Uploaded asset {uploaded_asset_id} should be attached to bookmark"
+        logger.info(f"✓ Verified bookmark contains the PDF asset {uploaded_asset_id}")
+
+        # 4. Retrieve and verify the asset content
+        logger.info(f"\nRetrieving asset content for ID: {uploaded_asset_id}")
+        asset_content = karakeep_client.get_a_single_asset(asset_id=uploaded_asset_id)
+        assert isinstance(asset_content, bytes), "Asset content should be bytes"
+        assert len(asset_content) > 0, "Asset content should not be empty"
+        assert asset_content.startswith(b"%PDF"), "PDF should start with PDF header"
+        logger.info(f"✓ Retrieved PDF asset content ({len(asset_content)} bytes)")
+
+    except FileNotFoundError:
+        pytest.skip(f"PDF test file not found: {pdf_file_path}")
+    except (APIError, AuthenticationError) as e:
+        pytest.fail(f"API error during PDF asset test: {e}")
+    except Exception as e:
+        pytest.fail(f"Unexpected error during PDF asset test: {e}")
+    finally:
+        # 5. Clean up: Delete the bookmark
+        if created_bookmark_id:
+            logger.info(f"\nCleaning up: Deleting bookmark {created_bookmark_id}")
+            try:
+                karakeep_client.delete_a_bookmark(bookmark_id=created_bookmark_id)
+                logger.info(f"✓ Successfully deleted bookmark {created_bookmark_id}")
+            except Exception as e:
+                logger.info(
+                    f"  Error during cleanup - failed to delete bookmark {created_bookmark_id}: {e}"
+                )
+        else:
+            logger.info("\nNo bookmark to clean up")
+
+
 # --- End of Tests ---