karakeep-python-api 1.4.0__tar.gz → 1.5.0__tar.gz

{karakeep_python_api-1.4.0/karakeep_python_api.egg-info → karakeep_python_api-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.4.0
+Version: 1.5.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -70,6 +70,7 @@ The development process involved:
 
 *   **Experimental Methods:** The included Pytest suite currently only covers a subset of the available API methods (primarily 'get all' endpoints and client initialization). Methods *not* explicitly tested should be considered **experimental**.
 *   **Ongoing Development:** The author intends to improve and validate methods as they are needed for personal use cases. Contributions and bug reports are welcome!
+* **Updating process**: I have local scripts to keep track of the changes in the OpenAPI specs on the server side. From time to time I go and use aider to make the code reflect the latest openapi and push that to the `dev` branch. When there is a new karakeep release, I will merge the `dev` branch to the `main` branch and create my own release. This way, `dev` hopefully is up to date with the latest code of karakeep, while `main` is up to date with the latest release of karakeep.
 
 ## API Method Coverage
 
@@ -116,7 +117,12 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `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`         |   ✅   |  ✅  |                                              |
-| `update_user`         |    ❌   |   ❌  |                                              |
+| `update_user`                    |   ❌   |  ❌  |                                              |
+| `get_all_backups`                |   ✅   |  ✅  | Tested in backup lifecycle test.            |
+| `trigger_a_new_backup`           |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 
 ## Installation
 

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.0}/README.md

@@ -35,6 +35,7 @@ The development process involved:
 
 *   **Experimental Methods:** The included Pytest suite currently only covers a subset of the available API methods (primarily 'get all' endpoints and client initialization). Methods *not* explicitly tested should be considered **experimental**.
 *   **Ongoing Development:** The author intends to improve and validate methods as they are needed for personal use cases. Contributions and bug reports are welcome!
+* **Updating process**: I have local scripts to keep track of the changes in the OpenAPI specs on the server side. From time to time I go and use aider to make the code reflect the latest openapi and push that to the `dev` branch. When there is a new karakeep release, I will merge the `dev` branch to the `main` branch and create my own release. This way, `dev` hopefully is up to date with the latest code of karakeep, while `main` is up to date with the latest release of karakeep.
 
 ## API Method Coverage
 
@@ -81,7 +82,12 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `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`         |   ✅   |  ✅  |                                              |
-| `update_user`         |    ❌   |   ❌  |                                              |
+| `update_user`                    |   ❌   |  ❌  |                                              |
+| `get_all_backups`                |   ✅   |  ✅  | Tested in backup lifecycle test.            |
+| `trigger_a_new_backup`           |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 
 ## Installation
 

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.0}/karakeep_python_api/datatypes.py

@@ -90,8 +90,10 @@ class BookmarkAsset(BaseModel):
         "video",
         "bookmarkAsset",
         "precrawledArchive",
+        "userUploaded",
         "unknown",
     ]
+    fileName: Optional[str] = None
 
 
 class Asset(BaseModel):
@@ -117,6 +119,7 @@ class Bookmark(BaseModel):
             "api", "web", "cli", "mobile", "extension", "singlefile", "rss", "import"
         ]
     ] = None
+    userId: str
     tags: List[TagShort]
     content: Union[
         ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
@@ -138,6 +141,8 @@ class ListModel(BaseModel):
     type: Optional[Literal["manual", "smart"]] = "manual"
     query: Optional[str] = None
     public: bool
+    hasCollaborators: bool
+    userRole: Literal["owner", "editor", "viewer", "public"]
 
 
 class Highlight(BaseModel):
@@ -160,3 +165,14 @@ class PaginatedHighlights(BaseModel):
 class PaginatedTags(BaseModel):
     tags: List[Tag]
     nextCursor: Optional[str] = ""
+
+
+class Backup(BaseModel):
+    id: str
+    userId: str
+    assetId: Optional[str]
+    createdAt: str
+    size: float
+    bookmarkCount: int
+    status: Literal["pending", "success", "failure"]
+    errorMessage: Optional[str] = None

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.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.4.0"
+    VERSION: str = "1.5.0"
 
     def __init__(
         self,
@@ -134,7 +134,7 @@ class KarakeepAPI:
 
         # Configure logger based on verbose setting
         log_level = "DEBUG" if self.verbose else "INFO"
-        logger.remove()  # Remove default handler
+        # logger.remove()  # Remove default handler
         if self.verbose:
             logger.add(
                 sys.stderr,
@@ -1301,6 +1301,7 @@ class KarakeepAPI:
             "video",
             "bookmarkAsset",
             "precrawledArchive",
+            "userUploaded",
             "unknown",
         ],
     ) -> Union[datatypes.BookmarkAsset, Dict[str, Any], List[Any]]:
@@ -1311,7 +1312,8 @@ class KarakeepAPI:
             bookmark_id: The ID (string) of the bookmark.
             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".
+                        "bannerImage", "fullPageArchive", "video", "bookmarkAsset", "precrawledArchive",
+                        "userUploaded", "unknown".
 
         Returns:
             datatypes.BookmarkAsset: The attached asset object.
@@ -2058,7 +2060,15 @@ class KarakeepAPI:
         Get statistics about the current authenticated user's data. Corresponds to GET /users/me/stats.
 
         Returns:
-            dict: A dictionary containing user statistics ('numBookmarks', 'numFavorites', 'numArchived', etc.).
+            dict: A dictionary containing user statistics including:
+                  - numBookmarks, numFavorites, numArchived, numTags, numLists, numHighlights
+                  - bookmarksByType: breakdown by content type (link, text, asset)
+                  - topDomains: most bookmarked domains
+                  - totalAssetSize: total size of stored assets
+                  - assetsByType: breakdown of assets by type
+                  - bookmarkingActivity: activity metrics (thisWeek, thisMonth, thisYear, byHour, byDayOfWeek)
+                  - tagUsage: most used tags
+                  - bookmarksBySource: breakdown by source (api, web, cli, mobile, extension, singlefile, rss, import)
                   Validation is not performed on this response type by default.
 
         Raises:
@@ -2175,6 +2185,186 @@ class KarakeepAPI:
             # Response should match Asset schema
             return datatypes.Asset.model_validate(response_data)
 
+    @optional_typecheck
+    def get_all_backups(
+        self,
+    ) -> Union[List[datatypes.Backup], Dict[str, Any], List[Any]]:
+        """
+        Get all backups for the current user. Corresponds to GET /backups.
+
+        Returns:
+            List[datatypes.Backup]: A list of backup objects.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails.
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        response_data = self._call("GET", "backups")
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            # Return raw data, which might be {"backups": [...]} or something else
+            return response_data
+        else:
+            # Response schema is {"backups": [Backup]}, extract the list and validate
+            if (
+                isinstance(response_data, dict)
+                and "backups" in response_data
+                and isinstance(response_data["backups"], list)
+            ):
+                try:
+                    return [
+                        datatypes.Backup.model_validate(backup)
+                        for backup in response_data["backups"]
+                    ]
+                except (
+                    Exception
+                ) as e:  # Catch validation errors during list comprehension
+                    logger.error(f"Validation failed for one or more backups: {e}")
+                    raise  # Re-raise the validation error
+            else:
+                # Raise error if format is unexpected and validation is enabled
+                raise APIError(
+                    f"Unexpected response format for get_all_backups when validation is enabled: {response_data}"
+                )
+
+    @optional_typecheck
+    def trigger_a_new_backup(
+        self,
+    ) -> Union[datatypes.Backup, Dict[str, Any], List[Any]]:
+        """
+        Trigger a new backup. Corresponds to POST /backups.
+
+        Returns:
+            datatypes.Backup: The created backup object.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails.
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        response_data = self._call("POST", "backups")
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match Backup schema
+            return datatypes.Backup.model_validate(response_data)
+
+    @optional_typecheck
+    def get_a_single_backup(
+        self, backup_id: str
+    ) -> Union[datatypes.Backup, Dict[str, Any], List[Any]]:
+        """
+        Get a single backup by its ID. Corresponds to GET /backups/{backupId}.
+
+        Args:
+            backup_id: The ID (string) of the backup to retrieve.
+
+        Returns:
+            datatypes.Backup: The requested backup object.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 backup not found).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"backups/{backup_id}"
+        response_data = self._call("GET", endpoint)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match Backup schema
+            return datatypes.Backup.model_validate(response_data)
+
+    @optional_typecheck
+    def delete_a_backup(self, backup_id: str) -> None:
+        """
+        Delete a backup by its ID. Corresponds to DELETE /backups/{backupId}.
+
+        Args:
+            backup_id: The ID (string) of the backup to delete.
+
+        Returns:
+            None: Returns None upon successful deletion (204 No Content).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 backup not found).
+        """
+        endpoint = f"backups/{backup_id}"
+        self._call("DELETE", endpoint)  # Expects 204 No Content
+        return None  # Explicitly return None for 204
+
+    @optional_typecheck
+    def download_a_backup(self, backup_id: str) -> bytes:
+        """
+        Download the backup file (zip archive) by its ID. Corresponds to GET /backups/{backupId}/download.
+
+        Args:
+            backup_id: The ID (string) of the backup to download.
+
+        Returns:
+            bytes: The raw backup file content (zip archive).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 backup not found).
+            ValueError: If backup_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 (zip file) rather than JSON.
+        """
+        # Validate backup_id
+        if not backup_id or not backup_id.strip():
+            raise ValueError("backup_id cannot be empty")
+
+        backup_id = backup_id.strip()
+
+        # Validate backup_id format (basic check for reasonable ID format)
+        if len(backup_id) < 5:  # Assuming backup IDs are at least 5 characters
+            raise ValueError(f"backup_id appears to be invalid: {backup_id}")
+
+        endpoint = f"backups/{backup_id}/download"
+
+        # Override the Accept header to get the zip file instead of JSON
+        extra_headers = {"Accept": "application/zip"}
+
+        if self.verbose:
+            logger.debug(f"Downloading backup: {backup_id}")
+
+        response_data = self._call("GET", endpoint, extra_headers=extra_headers)
+
+        # The _call method should return bytes for non-JSON responses
+        if isinstance(response_data, bytes):
+            if self.verbose:
+                logger.debug(
+                    f"Downloaded backup {backup_id}: {len(response_data)} bytes"
+                )
+            return response_data
+        elif response_data is None:
+            # Handle empty response
+            if self.verbose:
+                logger.debug(f"Downloaded empty backup {backup_id}")
+            return b""
+        else:
+            # This shouldn't happen with the updated _call method, but handle gracefully
+            error_msg = f"Expected bytes from backup download endpoint for backup {backup_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)
+
     @optional_typecheck
     def get_a_single_asset(self, asset_id: str) -> bytes:
         """

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.0}/karakeep_python_api/openapi_reference.json

@@ -45,6 +45,10 @@
         "type": "string",
         "example": "ieidlxygmwj87oxz5hxttoc8"
       },
+      "BackupId": {
+        "type": "string",
+        "example": "ieidlxygmwj87oxz5hxttoc8"
+      },
       "Bookmark": {
         "type": "object",
         "properties": {
@@ -108,6 +112,9 @@
               "import"
             ]
           },
+          "userId": {
+            "type": "string"
+          },
           "tags": {
             "type": "array",
             "items": {
@@ -317,8 +324,13 @@
                     "video",
                     "bookmarkAsset",
                     "precrawledArchive",
+                    "userUploaded",
                     "unknown"
                   ]
+                },
+                "fileName": {
+                  "type": "string",
+                  "nullable": true
                 }
               },
               "required": [
@@ -336,6 +348,7 @@
           "favourited",
           "taggingStatus",
           "summarizationStatus",
+          "userId",
           "tags",
           "content",
           "assets"
@@ -397,6 +410,18 @@
           },
           "public": {
             "type": "boolean"
+          },
+          "hasCollaborators": {
+            "type": "boolean"
+          },
+          "userRole": {
+            "type": "string",
+            "enum": [
+              "owner",
+              "editor",
+              "viewer",
+              "public"
+            ]
           }
         },
         "required": [
@@ -404,7 +429,9 @@
           "name",
           "icon",
           "parentId",
-          "public"
+          "public",
+          "hasCollaborators",
+          "userRole"
         ]
       },
       "Highlight": {
@@ -573,6 +600,14 @@
         "required": true,
         "name": "assetId",
         "in": "path"
+      },
+      "BackupId": {
+        "schema": {
+          "$ref": "#/components/schemas/BackupId"
+        },
+        "required": true,
+        "name": "backupId",
+        "in": "path"
       }
     }
   },
@@ -1189,6 +1224,9 @@
                         "rss",
                         "import"
                       ]
+                    },
+                    "userId": {
+                      "type": "string"
                     }
                   },
                   "required": [
@@ -1198,7 +1236,8 @@
                     "archived",
                     "favourited",
                     "taggingStatus",
-                    "summarizationStatus"
+                    "summarizationStatus",
+                    "userId"
                   ]
                 }
               }
@@ -1313,6 +1352,9 @@
                         "rss",
                         "import"
                       ]
+                    },
+                    "userId": {
+                      "type": "string"
                     }
                   },
                   "required": [
@@ -1322,7 +1364,8 @@
                     "archived",
                     "favourited",
                     "taggingStatus",
-                    "summarizationStatus"
+                    "summarizationStatus",
+                    "userId"
                   ]
                 }
               }
@@ -1703,6 +1746,7 @@
                       "video",
                       "bookmarkAsset",
                       "precrawledArchive",
+                      "userUploaded",
                       "unknown"
                     ]
                   }
@@ -1737,8 +1781,13 @@
                         "video",
                         "bookmarkAsset",
                         "precrawledArchive",
+                        "userUploaded",
                         "unknown"
                       ]
+                    },
+                    "fileName": {
+                      "type": "string",
+                      "nullable": true
                     }
                   },
                   "required": [
@@ -3122,6 +3171,10 @@
                       "green",
                       "blue"
                     ]
+                  },
+                  "note": {
+                    "type": "string",
+                    "nullable": true
                   }
                 }
               }
@@ -3386,6 +3439,35 @@
                         ]
                       },
                       "maxItems": 10
+                    },
+                    "bookmarksBySource": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "source": {
+                            "type": "string",
+                            "nullable": true,
+                            "enum": [
+                              "api",
+                              "web",
+                              "cli",
+                              "mobile",
+                              "extension",
+                              "singlefile",
+                              "rss",
+                              "import"
+                            ]
+                          },
+                          "count": {
+                            "type": "number"
+                          }
+                        },
+                        "required": [
+                          "source",
+                          "count"
+                        ]
+                      }
                     }
                   },
                   "required": [
@@ -3400,7 +3482,8 @@
                     "totalAssetSize",
                     "assetsByType",
                     "bookmarkingActivity",
-                    "tagUsage"
+                    "tagUsage",
+                    "bookmarksBySource"
                   ]
                 }
               }
@@ -3632,6 +3715,341 @@
           }
         }
       }
+    },
+    "/backups": {
+      "get": {
+        "description": "Get all backups",
+        "summary": "Get all backups",
+        "tags": [
+          "Backups"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Object with all backups data.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "backups": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string"
+                          },
+                          "userId": {
+                            "type": "string"
+                          },
+                          "assetId": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "createdAt": {
+                            "type": "string"
+                          },
+                          "size": {
+                            "type": "number"
+                          },
+                          "bookmarkCount": {
+                            "type": "number"
+                          },
+                          "status": {
+                            "type": "string",
+                            "enum": [
+                              "pending",
+                              "success",
+                              "failure"
+                            ]
+                          },
+                          "errorMessage": {
+                            "type": "string",
+                            "nullable": true
+                          }
+                        },
+                        "required": [
+                          "id",
+                          "userId",
+                          "assetId",
+                          "createdAt",
+                          "size",
+                          "bookmarkCount",
+                          "status"
+                        ]
+                      }
+                    }
+                  },
+                  "required": [
+                    "backups"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "description": "Trigger a new backup",
+        "summary": "Trigger a new backup",
+        "tags": [
+          "Backups"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Backup created successfully",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "userId": {
+                      "type": "string"
+                    },
+                    "assetId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "size": {
+                      "type": "number"
+                    },
+                    "bookmarkCount": {
+                      "type": "number"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "success",
+                        "failure"
+                      ]
+                    },
+                    "errorMessage": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "userId",
+                    "assetId",
+                    "createdAt",
+                    "size",
+                    "bookmarkCount",
+                    "status"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/backups/{backupId}": {
+      "get": {
+        "description": "Get backup by its id",
+        "summary": "Get a single backup",
+        "tags": [
+          "Backups"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BackupId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Object with backup data.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "id": {
+                      "type": "string"
+                    },
+                    "userId": {
+                      "type": "string"
+                    },
+                    "assetId": {
+                      "type": "string",
+                      "nullable": true
+                    },
+                    "createdAt": {
+                      "type": "string"
+                    },
+                    "size": {
+                      "type": "number"
+                    },
+                    "bookmarkCount": {
+                      "type": "number"
+                    },
+                    "status": {
+                      "type": "string",
+                      "enum": [
+                        "pending",
+                        "success",
+                        "failure"
+                      ]
+                    },
+                    "errorMessage": {
+                      "type": "string",
+                      "nullable": true
+                    }
+                  },
+                  "required": [
+                    "id",
+                    "userId",
+                    "assetId",
+                    "createdAt",
+                    "size",
+                    "bookmarkCount",
+                    "status"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Backup not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "description": "Delete backup by its id",
+        "summary": "Delete a backup",
+        "tags": [
+          "Backups"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BackupId"
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "No content - the backup was deleted"
+          },
+          "404": {
+            "description": "Backup not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/backups/{backupId}/download": {
+      "get": {
+        "description": "Download backup file",
+        "summary": "Download a backup",
+        "tags": [
+          "Backups"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BackupId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Backup file (zip archive)",
+            "content": {
+              "application/zip": {
+                "schema": {}
+              }
+            }
+          },
+          "404": {
+            "description": "Backup not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
     }
   }
 }

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.0/karakeep_python_api.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.4.0
+Version: 1.5.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3
@@ -70,6 +70,7 @@ The development process involved:
 
 *   **Experimental Methods:** The included Pytest suite currently only covers a subset of the available API methods (primarily 'get all' endpoints and client initialization). Methods *not* explicitly tested should be considered **experimental**.
 *   **Ongoing Development:** The author intends to improve and validate methods as they are needed for personal use cases. Contributions and bug reports are welcome!
+* **Updating process**: I have local scripts to keep track of the changes in the OpenAPI specs on the server side. From time to time I go and use aider to make the code reflect the latest openapi and push that to the `dev` branch. When there is a new karakeep release, I will merge the `dev` branch to the `main` branch and create my own release. This way, `dev` hopefully is up to date with the latest code of karakeep, while `main` is up to date with the latest release of karakeep.
 
 ## API Method Coverage
 
@@ -116,7 +117,12 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `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`         |   ✅   |  ✅  |                                              |
-| `update_user`         |    ❌   |   ❌  |                                              |
+| `update_user`                    |   ❌   |  ❌  |                                              |
+| `get_all_backups`                |   ✅   |  ✅  | Tested in backup lifecycle test.            |
+| `trigger_a_new_backup`           |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `get_a_single_backup`            |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `delete_a_backup`                |   ✅   |  ❌  | Tested in backup lifecycle test.            |
+| `download_a_backup`              |   ✅   |  ❌  | Tested in backup lifecycle test.            |
 
 ## Installation
 

{karakeep_python_api-1.4.0 → karakeep_python_api-1.5.0}/setup.py

@@ -7,7 +7,7 @@ with open("README.md", "r") as readme:
 
 setup(
     name="karakeep_python_api",
-    version="1.4.0",
+    version="1.5.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.4.0 → karakeep_python_api-1.5.0}/tests/test_karakeep_api.py

@@ -892,4 +892,134 @@ def test_asset_lifecycle_with_pdf(karakeep_client: KarakeepAPI):
             logger.info("\nNo bookmark to clean up")
 
 
+def test_backup_lifecycle(karakeep_client: KarakeepAPI):
+    """Test creating, retrieving, downloading, and deleting a backup."""
+    created_backup_id = None
+
+    try:
+        # 1. Get initial backup count
+        logger.info("\nGetting initial backup list")
+        initial_backups = karakeep_client.get_all_backups()
+        assert isinstance(initial_backups, list), "Response should be a list"
+        initial_backup_count = len(initial_backups)
+        logger.info(f"  Initial backup count: {initial_backup_count}")
+
+        # 2. Trigger a new backup
+        logger.info("\nTriggering a new backup")
+        created_backup = karakeep_client.trigger_a_new_backup()
+        assert isinstance(created_backup, datatypes.Backup), (
+            "Response should be a Backup model"
+        )
+        assert created_backup.id, "Created backup must have an ID"
+        assert created_backup.status in ["pending", "success", "failure"], (
+            "Backup status should be one of the valid enum values"
+        )
+        created_backup_id = created_backup.id
+        logger.info(f"✓ Successfully triggered backup with ID: {created_backup_id}")
+        logger.info(f"  Backup status: {created_backup.status}")
+
+        # 3. Verify the backup appears in get_all_backups
+        logger.info(f"\nVerifying backup {created_backup_id} appears in backup list")
+        current_backups = karakeep_client.get_all_backups()
+        assert len(current_backups) >= initial_backup_count + 1, (
+            "Backup count should increase after creation"
+        )
+        assert any(backup.id == created_backup_id for backup in current_backups), (
+            "Created backup should be present in the list of all backups"
+        )
+        logger.info(
+            f"✓ Verified backup {created_backup_id} is present in get_all_backups"
+        )
+
+        # 4. Get the backup by ID to verify it exists
+        logger.info(f"\nRetrieving backup {created_backup_id} by ID")
+        retrieved_backup = karakeep_client.get_a_single_backup(
+            backup_id=created_backup_id
+        )
+        assert isinstance(retrieved_backup, datatypes.Backup)
+        assert retrieved_backup.id == created_backup_id
+        logger.info(f"✓ Successfully retrieved backup by ID")
+        logger.info(f"  Status: {retrieved_backup.status}")
+        logger.info(f"  Bookmark count: {retrieved_backup.bookmarkCount}")
+        logger.info(f"  Size: {retrieved_backup.size} bytes")
+
+        # 5. Try to download the backup (only if status is "success")
+        if retrieved_backup.status == "success" and retrieved_backup.assetId:
+            logger.info(f"\nAttempting to download backup {created_backup_id}")
+            try:
+                backup_data = karakeep_client.download_a_backup(
+                    backup_id=created_backup_id
+                )
+                assert isinstance(backup_data, bytes), (
+                    "Downloaded backup should be bytes"
+                )
+                assert len(backup_data) > 0, "Downloaded backup should not be empty"
+                # Verify it's a zip file by checking the magic number
+                assert backup_data.startswith(b"PK\x03\x04") or backup_data.startswith(
+                    b"PK\x05\x06"
+                ), "Downloaded file should be a valid ZIP archive"
+                logger.info(
+                    f"✓ Successfully downloaded backup ({len(backup_data)} bytes)"
+                )
+            except APIError as e:
+                # Some backups might not be downloadable immediately, log but don't fail
+                logger.info(f"  Note: Could not download backup: {e}")
+        else:
+            logger.info(
+                f"  Skipping download test (status: {retrieved_backup.status}, assetId: {retrieved_backup.assetId})"
+            )
+
+        # 6. Test CLI equivalent for getting all backups
+        logger.info("\n  Running CLI equivalent: get-all-backups")
+        try:
+            subprocess.run(
+                "python -m karakeep_python_api get-all-backups",
+                shell=True,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            logger.info("✓ CLI command executed successfully.")
+        except subprocess.CalledProcessError as e:
+            logger.info(f"  CLI command failed with exit code {e.returncode}")
+            logger.info(f"  Stdout: {e.stdout}")
+            logger.info(f"  Stderr: {e.stderr}")
+            pytest.fail(f"CLI command 'get-all-backups' failed: {e}")
+
+    except (APIError, AuthenticationError) as e:
+        pytest.fail(f"API error during backup lifecycle test: {e}")
+    except Exception as e:
+        pytest.fail(f"An unexpected error occurred during backup lifecycle test: {e}")
+    finally:
+        # 7. Clean up: Delete the backup
+        if created_backup_id:
+            logger.info(f"\nCleaning up: Deleting backup {created_backup_id}")
+            try:
+                karakeep_client.delete_a_backup(backup_id=created_backup_id)
+                logger.info(f"✓ Successfully deleted backup {created_backup_id}")
+
+                # 8. Verify the backup is deleted
+                try:
+                    karakeep_client.get_a_single_backup(backup_id=created_backup_id)
+                    pytest.fail(
+                        f"Backup {created_backup_id} should not exist after deletion, but get_a_single_backup succeeded."
+                    )
+                except APIError as e:
+                    assert e.status_code == 404, (
+                        f"Expected 404 Not Found when getting deleted backup, but got status {e.status_code}"
+                    )
+                    logger.info(
+                        f"✓ Confirmed backup {created_backup_id} is deleted (received 404)"
+                    )
+
+            except (APIError, AuthenticationError) as e:
+                logger.info(
+                    f"  Error during cleanup - failed to delete backup {created_backup_id}: {e}"
+                )
+            except Exception as e:
+                logger.info(f"  Unexpected error during cleanup: {e}")
+        else:
+            logger.info("\nNo backup to clean up")
+
+
 # --- End of Tests ---