karakeep-python-api 1.7.0__tar.gz → 1.9.0__tar.gz

{karakeep_python_api-1.7.0/karakeep_python_api.egg-info → karakeep_python_api-1.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: karakeep_python_api
-Version: 1.7.0
+Version: 1.9.0
 Summary: Community python client for the Karakeep API.
 Home-page: https://github.com/thiswillbeyourgithub/karakeep_python_api/
 Keywords: rss,karakeep,hoarder,data-hoarding,python,api,feeds,openapi
@@ -82,6 +82,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
 | `update_a_bookmark`              |   ✅   |  ✅  | Tested for title updates.                    |
+| `get_bookmark_readable_content`  |   ✅   |  ❌  | Chunk merging tested offline; live test reads a text bookmark. |
 | `summarize_a_bookmark`           |   ❌   |  ❌  |                                              |
 | `attach_tags_to_a_bookmark`      |   ✅   |  ❌  |  |
 | `detach_tags_from_a_bookmark`    |   ✅   |  ❌  |  |
@@ -110,6 +111,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
 | `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_asset_signed_url`           |   ✅   |  ❌  | Tested in PDF asset lifecycle test (downloads without an API key). |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 | `update_user`                    |   ❌   |  ❌  |                                              |
@@ -118,6 +120,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `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.            |
+| `admin_trigger_recrawl`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_reindex`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_inference`        |   ❌   |  ❌  | Request body construction tested offline only. |
 
 ## Installation
 
@@ -281,4 +286,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
 
 ---
 
-*This README was generated with assistance from [aider.chat](https://aider.chat).*
+*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*

{karakeep_python_api-1.7.0 → karakeep_python_api-1.9.0}/README.md

@@ -50,6 +50,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `get_a_single_bookmark`          |   ✅   |  ❌  |  |
 | `delete_a_bookmark`              |   ✅   |  ❌  |  |
 | `update_a_bookmark`              |   ✅   |  ✅  | Tested for title updates.                    |
+| `get_bookmark_readable_content`  |   ✅   |  ❌  | Chunk merging tested offline; live test reads a text bookmark. |
 | `summarize_a_bookmark`           |   ❌   |  ❌  |                                              |
 | `attach_tags_to_a_bookmark`      |   ✅   |  ❌  |  |
 | `detach_tags_from_a_bookmark`    |   ✅   |  ❌  |  |
@@ -78,6 +79,7 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `update_a_highlight`             |   ❌   |  ❌  |                                              |
 | `upload_a_new_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
 | `get_a_single_asset`             |   ✅   |  ❌  | Tested in PDF asset lifecycle test.         |
+| `get_asset_signed_url`           |   ✅   |  ❌  | Tested in PDF asset lifecycle test (downloads without an API key). |
 | `get_current_user_info`          |   ✅   |  ❌  | Pytest: Tested indirectly during client init. CLI not directly tested. |
 | `get_current_user_stats`         |   ✅   |  ✅  |                                              |
 | `update_user`                    |   ❌   |  ❌  |                                              |
@@ -86,6 +88,9 @@ Methods or CLI commands marked with ❌ should be used with caution as their beh
 | `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.            |
+| `admin_trigger_recrawl`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_reindex`          |   ❌   |  ❌  | Request body construction tested offline only. |
+| `admin_trigger_inference`        |   ❌   |  ❌  | Request body construction tested offline only. |
 
 ## Installation
 
@@ -249,4 +254,4 @@ They can be found in the [./community_scripts](https://github.com/thiswillbeyour
 
 ---
 
-*This README was generated with assistance from [aider.chat](https://aider.chat).*
+*This README was generated with assistance from [aider.chat](https://aider.chat), and later kept up to date with [Claude Code](https://claude.com/claude-code).*

{karakeep_python_api-1.7.0 → karakeep_python_api-1.9.0}/karakeep_python_api/__main__.py

@@ -538,7 +538,23 @@ def create_click_command(
                     ctx.exit(1)
 
                 # Serialize and print the result
-                if result is not None:
+                if isinstance(result, (bytes, bytearray)):
+                    # Binary payloads (e.g. download_a_backup, get_a_single_asset)
+                    # cannot be JSON encoded: write them raw to stdout so the
+                    # output can be redirected straight into a file.
+                    logger.debug(f"Writing {len(result)} raw bytes to stdout.")
+                    stdout_buffer = getattr(sys.stdout, "buffer", None)
+                    if stdout_buffer is not None:
+                        stdout_buffer.write(result)
+                        stdout_buffer.flush()
+                    else:
+                        # Some test/capture harnesses replace sys.stdout with a
+                        # text-only stream that has no .buffer attribute.
+                        sys.stdout.write(
+                            bytes(result).decode("utf-8", errors="surrogateescape")
+                        )
+                        sys.stdout.flush()
+                elif result is not None:
                     output_data = serialize_output(result)
                     # Use ensure_ascii_output flag to control JSON encoding
                     click.echo(

{karakeep_python_api-1.7.0 → karakeep_python_api-1.9.0}/karakeep_python_api/datatypes.py

@@ -53,6 +53,15 @@ class ContentTypeLink(BaseModel):
     favicon: Optional[str] = None
     htmlContent: Optional[str] = None
     contentAssetId: Optional[str] = None
+    # Reader-view triage produced by the crawler: readerViewStatus says whether a
+    # distraction-free rendering could be extracted, readerViewScore (0-100) how
+    # confident that extraction is, and preferredPreview which of the available
+    # renderings the UI should show by default.
+    readerViewStatus: Optional[
+        Literal["readable", "not_readable", "uncertain", "unavailable"]
+    ] = None
+    readerViewScore: Optional[int] = None
+    preferredPreview: Optional[Literal["reader_view", "screenshot", "overview"]] = None
     crawledAt: Optional[str] = None
     crawlStatus: Optional[Literal["success", "failure", "pending"]] = None
     author: Optional[str] = None
@@ -100,22 +109,43 @@ class BookmarkAsset(BaseModel):
     fileName: Optional[str] = None
 
 
-class Asset(BaseModel):
+class UploadedAsset(BaseModel):
     assetId: str
     contentType: str
     size: float
     fileName: str
 
 
+# Backwards-compatible alias: the upstream OpenAPI schema was renamed
+# from "Asset" to "UploadedAsset".
+Asset = UploadedAsset
+
+
+class SignedAssetUrl(BaseModel):
+    assetId: str
+    # Temporary download URL that carries its own signature, so it works without
+    # the Authorization header and can be handed to a browser or media player.
+    signedUrl: str
+    expiresAt: str
+
+
 class Bookmark(BaseModel):
     id: str
+    # firstCreatedAt records the original creation time when a bookmark is
+    # recreated/re-imported, so it can predate createdAt. Optional in the spec
+    # and absent on Karakeep servers older than the one that introduced it.
+    firstCreatedAt: Optional[str] = None
     createdAt: str
     modifiedAt: Optional[str]
     title: Optional[str] = None
     archived: bool
     favourited: bool
-    taggingStatus: Literal["success", "failure", "pending"]
+    taggingStatus: Optional[Literal["success", "failure", "pending"]] = None
     summarizationStatus: Optional[Literal["success", "failure", "pending"]] = None
+    # Status of the vector-embedding job used by semantic/hybrid search. The
+    # spec marks it required-but-nullable, so no default is given here: a
+    # missing key is a genuine mismatch with the documented server response.
+    embeddingStatus: Optional[Literal["success", "failure", "pending"]]
     note: Optional[str] = None
     summary: Optional[str] = None
     source: Optional[
@@ -131,6 +161,28 @@ class Bookmark(BaseModel):
     assets: List[BookmarkAsset]
 
 
+class ReadableContentRange(BaseModel):
+    # Offsets are in Unicode characters over the *rendered* content, not bytes:
+    # start is inclusive, end is exclusive, and total is the full rendered length.
+    start: int
+    end: int
+    total: int
+
+
+class BookmarkReadableContent(BaseModel):
+    bookmarkId: str
+    bookmarkType: Literal["link", "text", "asset"]
+    format: Literal["markdown", "text"]
+    content: str
+    # Hash of the rendered content the cursor was issued against. The server
+    # answers 409 if the bookmark changed between two chunks, so this value must
+    # not be mixed across a paginated read.
+    contentVersion: str
+    range: ReadableContentRange
+    nextCursor: Optional[str]
+    truncated: bool
+
+
 class PaginatedBookmarks(BaseModel):
     bookmarks: List[Bookmark]
     nextCursor: Optional[str] = ""
@@ -184,3 +236,14 @@ class Backup(BaseModel):
     bookmarkCount: int
     status: Literal["pending", "success", "failure"]
     errorMessage: Optional[str] = None
+
+
+class Feed(BaseModel):
+    id: str
+    name: str
+    url: str
+    enabled: bool
+    importTags: bool
+    lastFetchedStatus: Optional[Literal["success", "failure", "pending"]]
+    lastFetchedAt: Optional[str]
+    lastSuccessfulFetchAt: Optional[str]