karakeep-python-api 1.2.4__py3-none-any.whl → 1.3.1__py3-none-any.whl

karakeep_python_api/datatypes.py

@@ -17,8 +17,8 @@ class StatusTypes(str, Enum):
 
 
 class NumBookmarksByAttachedType(BaseModel):
-    ai: Optional[float] = None
-    human: Optional[float] = None
+    ai: Optional[int] = None
+    human: Optional[int] = None
 
 
 class TagShort(BaseModel):
@@ -30,7 +30,7 @@ class TagShort(BaseModel):
 class Tag(BaseModel):
     id: str
     name: str
-    numBookmarks: float
+    numBookmarks: int
     numBookmarksByAttachedType: NumBookmarksByAttachedType
 
 
@@ -112,6 +112,11 @@ class Bookmark(BaseModel):
     summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
     note: Optional[str] = None
     summary: Optional[str] = None
+    source: Optional[
+        Literal[
+            "api", "web", "cli", "mobile", "extension", "singlefile", "rss", "import"
+        ]
+    ] = None
     tags: List[TagShort]
     content: Union[
         ContentTypeLink, ContentTypeText, ContentTypeAsset, ContentTypeUnknown
@@ -121,7 +126,18 @@ class Bookmark(BaseModel):
 
 class PaginatedBookmarks(BaseModel):
     bookmarks: List[Bookmark]
-    nextCursor: Optional[str]
+    nextCursor: Optional[str] = ""
+
+
+class ListModel(BaseModel):
+    id: str
+    name: str
+    description: Optional[str] = None
+    icon: str
+    parentId: Optional[str]
+    type: Optional[Literal["manual", "smart"]] = "manual"
+    query: Optional[str] = None
+    public: bool
 
 
 class Highlight(BaseModel):
@@ -136,17 +152,11 @@ class Highlight(BaseModel):
     createdAt: str
 
 
-class ListModel(BaseModel):
-    id: str
-    name: str
-    description: Optional[str] = None
-    icon: str
-    parentId: Optional[str]
-    type: Optional[Literal["manual", "smart"]] = "manual"
-    query: Optional[str] = None
-    public: bool
-
-
 class PaginatedHighlights(BaseModel):
     highlights: List[Highlight]
-    nextCursor: Optional[str]
+    nextCursor: Optional[str] = ""
+
+
+class PaginatedTags(BaseModel):
+    tags: List[Tag]
+    nextCursor: Optional[str] = ""

karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.2.4"
+    VERSION: str = "1.3.1"
 
     def __init__(
         self,
@@ -758,6 +758,19 @@ class KarakeepAPI:
         summary: Optional[str] = None,
         createdAt: Optional[str] = None,  # ISO 8601 format string
         crawlPriority: Optional[Literal["low", "normal"]] = None,
+        importSessionId: Optional[str] = None,
+        source: Optional[
+            Literal[
+                "api",
+                "web",
+                "cli",
+                "mobile",
+                "extension",
+                "singlefile",
+                "rss",
+                "import",
+            ]
+        ] = None,
         # Link specific
         url: Optional[str] = None,
         precrawledArchiveId: Optional[str] = None,
@@ -783,6 +796,8 @@ class KarakeepAPI:
             summary: Optional summary content for the bookmark.
             createdAt: Optional creation timestamp override (ISO 8601 format string).
             crawlPriority: Optional either 'low' or 'normal'.
+            importSessionId: Optional import session ID for tracking imported bookmarks.
+            source: Optional source of the bookmark ("api", "web", "cli", "mobile", "extension", "singlefile", "rss", "import").
 
             --- Link Type Specific ---
             url: The URL for the link bookmark. Required if type='link'.
@@ -799,7 +814,9 @@ class KarakeepAPI:
             sourceUrl: Optional source URL where the asset originated.
 
         Returns:
-            datatypes.Bookmark: The created bookmark.
+            datatypes.Bookmark: The bookmark object.
+                               Returns with status 200 if the bookmark already exists,
+                               or status 201 if the bookmark was newly created.
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
@@ -825,6 +842,10 @@ class KarakeepAPI:
             request_body["createdAt"] = createdAt
         if crawlPriority is not None:
             request_body["crawlPriority"] = crawlPriority
+        if importSessionId is not None:
+            request_body["importSessionId"] = importSessionId
+        if source is not None:
+            request_body["source"] = source
 
         # Add type-specific fields and perform validation
         if type == "link":
@@ -911,7 +932,9 @@ class KarakeepAPI:
 
     @optional_typecheck
     def get_a_single_bookmark(
-        self, bookmark_id: str, include_content: bool = True  # Default from spec
+        self,
+        bookmark_id: str,
+        include_content: bool = True,  # Default from spec
     ) -> Union[datatypes.Bookmark, Dict[str, Any], List[Any]]:
         """
         Get a single bookmark by its ID. Corresponds to GET /bookmarks/{bookmarkId}.
@@ -1169,6 +1192,54 @@ class KarakeepAPI:
         # No Pydantic validation applied here as the spec defines a simple dict response
         return response_data
 
+    @optional_typecheck
+    def get_lists_of_a_bookmark(
+        self, bookmark_id: str
+    ) -> Union[List[datatypes.ListModel], Dict[str, Any], List[Any]]:
+        """
+        Get all lists associated with a specific bookmark. Corresponds to GET /bookmarks/{bookmarkId}/lists.
+
+        Args:
+            bookmark_id: The ID (string) of the bookmark.
+
+        Returns:
+            List[datatypes.ListModel]: A list of list objects associated with the bookmark.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 bookmark not found).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"bookmarks/{bookmark_id}/lists"
+        response_data = self._call("GET", endpoint)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            # Return raw data, which might be {"lists": [...]} or something else
+            return response_data
+        else:
+            # Response schema is {"lists": [ListModel]}, extract the list and validate
+            if (
+                isinstance(response_data, dict)
+                and "lists" in response_data
+                and isinstance(response_data["lists"], list)
+            ):
+                try:
+                    return [
+                        datatypes.ListModel.model_validate(lst)
+                        for lst in response_data["lists"]
+                    ]
+                except (
+                    Exception
+                ) as e:  # Catch validation errors during list comprehension
+                    logger.error(f"Validation failed for one or more lists: {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_lists_of_a_bookmark when validation is enabled: {response_data}"
+                )
+
     @optional_typecheck
     def get_highlights_of_a_bookmark(
         self, bookmark_id: str
@@ -1601,46 +1672,47 @@ class KarakeepAPI:
         return None  # Explicitly return None for 204
 
     @optional_typecheck
-    def get_all_tags(self) -> Union[List[datatypes.Tag], Dict[str, Any], List[Any]]:
+    def get_all_tags(
+        self,
+        name_contains: Optional[str] = None,
+        sort: Optional[Literal["name", "usage", "relevance"]] = None,
+        attached_by: Optional[Literal["ai", "human", "none"]] = None,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> Union[datatypes.PaginatedTags, Dict[str, Any], List[Any]]:
         """
         Get all tags for the current user. Corresponds to GET /tags.
 
+        Args:
+            name_contains: Filter tags by name substring (optional).
+            sort: Sort order for tags ("name", "usage", "relevance"). Default from API is "usage" (optional).
+            attached_by: Filter tags by how they were attached ("ai", "human", "none") (optional).
+            cursor: Pagination cursor for the next page (optional).
+            limit: Maximum number of tags to return (optional).
+
         Returns:
-            List[datatypes.Tag]: A list of tag objects, including bookmark counts.
+            datatypes.PaginatedTags: Paginated list of tags with nextCursor for pagination.
             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", "tags")
+        params = {
+            "nameContains": name_contains,
+            "sort": sort,
+            "attachedBy": attached_by,
+            "cursor": cursor,
+            "limit": limit,
+        }
+        response_data = self._call("GET", "tags", params=params)
 
         if self.disable_response_validation:
             logger.debug("Skipping response validation as requested.")
-            # Return raw data, which might be {"tags": [...]} or something else
             return response_data
         else:
-            # Response schema is {"tags": [Tag]}, extract the list and validate
-            if (
-                isinstance(response_data, dict)
-                and "tags" in response_data
-                and isinstance(response_data["tags"], list)
-            ):
-                try:
-                    return [
-                        datatypes.Tag.model_validate(tag)
-                        for tag in response_data["tags"]
-                    ]
-                except (
-                    Exception
-                ) as e:  # Catch validation errors during list comprehension
-                    logger.error(f"Validation failed for one or more tags: {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_tags when validation is enabled: {response_data}"
-                )
+            # Response should match PaginatedTags schema
+            return datatypes.PaginatedTags.model_validate(response_data)
 
     @optional_typecheck
     def create_a_new_tag(self, name: str) -> Dict[str, Any]:

karakeep_python_api/openapi_reference.json

@@ -94,6 +94,20 @@
             "type": "string",
             "nullable": true
           },
+          "source": {
+            "type": "string",
+            "nullable": true,
+            "enum": [
+              "api",
+              "web",
+              "cli",
+              "mobile",
+              "extension",
+              "singlefile",
+              "rss",
+              "import"
+            ]
+          },
           "tags": {
             "type": "array",
             "items": {
@@ -349,6 +363,50 @@
       "Cursor": {
         "type": "string"
       },
+      "List": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string",
+            "nullable": true
+          },
+          "icon": {
+            "type": "string"
+          },
+          "parentId": {
+            "type": "string",
+            "nullable": true
+          },
+          "type": {
+            "type": "string",
+            "enum": [
+              "manual",
+              "smart"
+            ],
+            "default": "manual"
+          },
+          "query": {
+            "type": "string",
+            "nullable": true
+          },
+          "public": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "icon",
+          "parentId",
+          "public"
+        ]
+      },
       "Highlight": {
         "type": "object",
         "properties": {
@@ -400,50 +458,6 @@
           "createdAt"
         ]
       },
-      "List": {
-        "type": "object",
-        "properties": {
-          "id": {
-            "type": "string"
-          },
-          "name": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string",
-            "nullable": true
-          },
-          "icon": {
-            "type": "string"
-          },
-          "parentId": {
-            "type": "string",
-            "nullable": true
-          },
-          "type": {
-            "type": "string",
-            "enum": [
-              "manual",
-              "smart"
-            ],
-            "default": "manual"
-          },
-          "query": {
-            "type": "string",
-            "nullable": true
-          },
-          "public": {
-            "type": "boolean"
-          }
-        },
-        "required": [
-          "id",
-          "name",
-          "icon",
-          "parentId",
-          "public"
-        ]
-      },
       "Tag": {
         "type": "object",
         "properties": {
@@ -693,6 +707,22 @@
                           "low",
                           "normal"
                         ]
+                      },
+                      "importSessionId": {
+                        "type": "string"
+                      },
+                      "source": {
+                        "type": "string",
+                        "enum": [
+                          "api",
+                          "web",
+                          "cli",
+                          "mobile",
+                          "extension",
+                          "singlefile",
+                          "rss",
+                          "import"
+                        ]
                       }
                     }
                   },
@@ -781,8 +811,18 @@
           }
         },
         "responses": {
+          "200": {
+            "description": "The bookmark already exists",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Bookmark"
+                }
+              }
+            }
+          },
           "201": {
-            "description": "The created bookmark",
+            "description": "The bookmark got created",
             "content": {
               "application/json": {
                 "schema": {
@@ -1135,6 +1175,20 @@
                     "summary": {
                       "type": "string",
                       "nullable": true
+                    },
+                    "source": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "api",
+                        "web",
+                        "cli",
+                        "mobile",
+                        "extension",
+                        "singlefile",
+                        "rss",
+                        "import"
+                      ]
                     }
                   },
                   "required": [
@@ -1245,6 +1299,20 @@
                     "summary": {
                       "type": "string",
                       "nullable": true
+                    },
+                    "source": {
+                      "type": "string",
+                      "nullable": true,
+                      "enum": [
+                        "api",
+                        "web",
+                        "cli",
+                        "mobile",
+                        "extension",
+                        "singlefile",
+                        "rss",
+                        "import"
+                      ]
                     }
                   },
                   "required": [
@@ -1469,6 +1537,70 @@
         }
       }
     },
+    "/bookmarks/{bookmarkId}/lists": {
+      "get": {
+        "description": "Get lists of a bookmark",
+        "summary": "Get lists of a bookmark",
+        "tags": [
+          "Bookmarks"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/BookmarkId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "The list of highlights",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "lists": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/List"
+                      }
+                    }
+                  },
+                  "required": [
+                    "lists"
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Bookmark not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "code": {
+                      "type": "string"
+                    },
+                    "message": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "code",
+                    "message"
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/bookmarks/{bookmarkId}/highlights": {
       "get": {
         "description": "Get highlights of a bookmark",
@@ -2292,6 +2424,60 @@
             "bearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "nameContains",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "name",
+                "usage",
+                "relevance"
+              ],
+              "default": "usage"
+            },
+            "required": false,
+            "name": "sort",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string",
+              "enum": [
+                "ai",
+                "human",
+                "none"
+              ]
+            },
+            "required": false,
+            "name": "attachedBy",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": false,
+            "name": "cursor",
+            "in": "query"
+          },
+          {
+            "schema": {
+              "type": "number",
+              "nullable": true
+            },
+            "required": false,
+            "name": "limit",
+            "in": "query"
+          }
+        ],
         "responses": {
           "200": {
             "description": "Object with all tags data.",
@@ -2305,10 +2491,15 @@
                       "items": {
                         "$ref": "#/components/schemas/Tag"
                       }
+                    },
+                    "nextCursor": {
+                      "type": "string",
+                      "nullable": true
                     }
                   },
                   "required": [
-                    "tags"
+                    "tags",
+                    "nextCursor"
                   ]
                 }
               }

{karakeep_python_api-1.2.4.dist-info → karakeep_python_api-1.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.2.4
+Version: 1.3.1
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 License: GPLv3

karakeep_python_api-1.3.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
+karakeep_python_api/__main__.py,sha256=QP_TbmgNZE6Fx7tHvWLYaUKoYIvcv-qFYdNXx_x__9A,31679
+karakeep_python_api/datatypes.py,sha256=WQwugxhxdLR24gIY3tnB5ZoW7H_DD9T5KDOR-mMQZN4,3838
+karakeep_python_api/karakeep_api.py,sha256=ZB2LxjYf0b_W6sIdAbjPhmIsCMYaj7aRnkg7-7XF4cA,98397
+karakeep_python_api/openapi_reference.json,sha256=XCk9W0XRYoGtEqlqHstqjIQPz4QDuYzEzxXfExc7UCc,97877
+karakeep_python_api-1.3.1.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+karakeep_python_api-1.3.1.dist-info/METADATA,sha256=Po19wuFL4NKleh7hnjRtEaBidyA9DbSzRFybHnr_bKw,16382
+karakeep_python_api-1.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+karakeep_python_api-1.3.1.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
+karakeep_python_api-1.3.1.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
+karakeep_python_api-1.3.1.dist-info/RECORD,,

karakeep_python_api-1.2.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-karakeep_python_api/__init__.py,sha256=qk3MeIIvnCNAyYzJrv8dMKVXvA4ejLU3mhB3xFzdLDY,606
-karakeep_python_api/__main__.py,sha256=QP_TbmgNZE6Fx7tHvWLYaUKoYIvcv-qFYdNXx_x__9A,31679
-karakeep_python_api/datatypes.py,sha256=EmEpjGgXz6faXDJ4fGJkT52wSW98WUovoCSCOPsJBME,3597
-karakeep_python_api/karakeep_api.py,sha256=-Xsz1CqdnOpbKuklo7Yb-a4ZsYiPzFxSZd_wdpZLX84,95389
-karakeep_python_api/openapi_reference.json,sha256=sA2b9_LnqnpJ8gscjT6kST93iSXAmeDMEBE7dEI4AGo,92730
-karakeep_python_api-1.2.4.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-karakeep_python_api-1.2.4.dist-info/METADATA,sha256=w16CnUqfIG_5us4U5yNqHI3V3alI-acOeDyzHK6i5jQ,16382
-karakeep_python_api-1.2.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-karakeep_python_api-1.2.4.dist-info/entry_points.txt,sha256=n0leQp_IX2NivoWuUcaR9ZHwAvl_6yt-NcHWuCJyxNo,62
-karakeep_python_api-1.2.4.dist-info/top_level.txt,sha256=X3VKqh9YAbPQp144db0Ko2C5Q2y6-nwpPgtnuCiSDmU,20
-karakeep_python_api-1.2.4.dist-info/RECORD,,