karakeep-python-api 1.0.0__py3-none-any.whl → 1.2.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

@@ -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):

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,12 +85,12 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.0.0"
+    VERSION: str = "1.2.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,
@@ -105,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 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.
                                Defaults to 'openapi_reference.json' alongside the package code if not provided.
                                The loaded spec is available via the `openapi_spec` attribute.
@@ -130,47 +131,47 @@ class KarakeepAPI:
         self.api_key = resolved_api_key
         logger.debug("API Key loaded successfully.")
 
-        # --- Base URL Validation ---
-        env_base_url = os.environ.get("KARAKEEP_PYTHON_API_BASE_URL")
+        # --- Endpoint Validation ---
+        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"Endpoint 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 endpoint: {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 endpoint 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 endpoint 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 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 /v1: {self.api_base_url}"
+                f"Appended trailing slash to endpoint 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"Endpoint 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 endpoint: {self.api_endpoint}")
 
-        logger.debug(f"Final API Base URL after /v1/ check: {self.api_base_url}")
+        logger.debug(f"Final API Endpoint after /api/v1/ check: {self.api_endpoint}")
 
         # --- Load and Parse OpenAPI Spec ---
         if openapi_spec_path is None:
@@ -257,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"  Endpoint: {self.api_endpoint}")
         logger.debug(f"  Verify SSL: {self.verify_ssl}")
         logger.debug(f"  Verbose: {self.verbose}")
         logger.debug(
@@ -294,34 +295,37 @@ 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).
             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 = {
@@ -345,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(
@@ -470,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
@@ -514,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()
@@ -1179,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.
 
@@ -1190,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:
@@ -1207,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:
@@ -1306,6 +1334,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.
@@ -1317,6 +1346,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.
@@ -1336,6 +1366,7 @@ class KarakeepAPI:
             "name": name,
             "icon": icon,
             "type": list_type,
+            "public": public,
         }
 
         # Add optional fields if provided
@@ -1410,10 +1441,11 @@ class KarakeepAPI:
         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 various list fields including name, description, icon, parent relationship, and 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.
@@ -1422,6 +1454,7 @@ class KarakeepAPI:
             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.
@@ -1444,6 +1477,8 @@ class KarakeepAPI:
             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:
@@ -1935,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/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": {
@@ -426,13 +426,17 @@
           "query": {
             "type": "string",
             "nullable": true
+          },
+          "public": {
+            "type": "boolean"
           }
         },
         "required": [
           "id",
           "name",
           "icon",
-          "parentId"
+          "parentId",
+          "public"
         ]
       },
       "Tag": {
@@ -484,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"
@@ -526,6 +546,14 @@
         "required": true,
         "name": "highlightId",
         "in": "path"
+      },
+      "AssetId": {
+        "schema": {
+          "$ref": "#/components/schemas/AssetId"
+        },
+        "required": true,
+        "name": "assetId",
+        "in": "path"
       }
     }
   },
@@ -1982,6 +2010,9 @@
                   "query": {
                     "type": "string",
                     "minLength": 1
+                  },
+                  "public": {
+                    "type": "boolean"
                   }
                 }
               }
@@ -3024,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.0.0.dist-info → karakeep_python_api-1.2.0.dist-info}/METADATA

@@ -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.2.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=VHUuSTifTnVnxYOA9TUGvGK4GiZLcXgQA8AqBQ6Kqgs,3529
+karakeep_python_api/karakeep_api.py,sha256=wB2lTB0uHeiXr7sN9yikp5FkiRI1Dw4IDRRCOanf7HM,91802
+karakeep_python_api/openapi_reference.json,sha256=J1dyFeXgcV6boh851xU3J3YRTz_5ixrGQjtxkJEj1RU,82686
+karakeep_python_api-1.2.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+karakeep_python_api-1.2.0.dist-info/METADATA,sha256=VfqCwjsuJGhvTu5jTMtmJobLaVAVB5-NObs9URUqKus,15970
+karakeep_python_api-1.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karakeep_python_api-1.2.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
+karakeep_python_api-1.2.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
+karakeep_python_api-1.2.0.dist-info/RECORD,,

karakeep_python_api-1.0.0.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=Fpyc3A4Gph3czirIDztsvzbtnegmkDLmiJNDCdgTt04,84749
-karakeep_python_api/openapi_reference.json,sha256=Ku1cO_N4QPLQc7sK8L7FRt2T68QyPCwTGA7RK-046iU,80379
-karakeep_python_api-1.0.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-karakeep_python_api-1.0.0.dist-info/METADATA,sha256=joWnEpuTHNzpSr4U4EJ-Xb48YK8_YU-rrYHW9HWGsAg,14026
-karakeep_python_api-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-karakeep_python_api-1.0.0.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
-karakeep_python_api-1.0.0.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
-karakeep_python_api-1.0.0.dist-info/RECORD,,