karakeep-python-api 1.7.0__py3-none-any.whl → 1.9.0__py3-none-any.whl

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/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]

karakeep_python_api/karakeep_api.py

@@ -85,7 +85,7 @@ class KarakeepAPI:
     """
 
     # Version reflects the client library version, updated by bumpver
-    VERSION: str = "1.7.0"
+    VERSION: str = "1.9.0"
 
     def __init__(
         self,
@@ -891,16 +891,25 @@ class KarakeepAPI:
     def search_bookmarks(
         self,
         q: str,  # Search query is required
+        search_mode: Optional[Literal["fts", "semantic", "hybrid"]] = None,
         sort_order: Optional[Literal["asc", "desc", "relevance"]] = None,
         limit: Optional[int] = None,
         cursor: Optional[str] = None,
         include_content: bool = True,  # Default from spec
     ) -> Union[datatypes.PaginatedBookmarks, Dict[str, Any], List[Any]]:
         """
-        Search bookmarks. Corresponds to GET /bookmarks/search.
+        Search bookmarks using full-text, semantic or hybrid ranking.
+        Corresponds to GET /bookmarks/search.
 
         Args:
             q: The search query string.
+            search_mode: Search strategy (optional). "fts" is full-text search (API default),
+                         "semantic" ranks with bookmark embeddings, and "hybrid" fuses both.
+                         Hybrid falls back to full-text search when the query has no free-text
+                         terms or when embedding infrastructure is unavailable. Semantic hits
+                         below a minimum similarity are dropped, so "semantic" and "hybrid" may
+                         return fewer results than `limit`. Note that the semantic modes only
+                         support sort_order="relevance".
             sort_order: Sort order for results ("asc", "desc", "relevance"). Default from API is "relevance" (optional).
             limit: Maximum number of bookmarks to return (optional).
             cursor: Pagination cursor for the next page (optional).
@@ -916,6 +925,7 @@ class KarakeepAPI:
         """
         params = {
             "q": q,
+            "searchMode": search_mode,
             "sortOrder": sort_order,
             "limit": limit,
             "cursor": cursor,
@@ -1051,6 +1061,101 @@ class KarakeepAPI:
         # No Pydantic validation applied here as the spec defines a partial response (dict)
         return response_data
 
+    @optional_typecheck
+    def get_bookmark_readable_content(
+        self,
+        bookmark_id: str,
+        format: Optional[Literal["markdown", "text"]] = None,
+        max_chars: Optional[int] = None,
+        cursor: Optional[str] = None,
+        fetch_all: bool = False,
+    ) -> Union[datatypes.BookmarkReadableContent, Dict[str, Any], List[Any]]:
+        """
+        Get an agent-readable rendering of a bookmark's content.
+        Corresponds to GET /bookmarks/{bookmarkId}/content.
+
+        Link content is rendered from the extracted HTML; text and asset bookmarks use
+        their stored or extracted text. The endpoint returns a bounded chunk plus an
+        opaque `nextCursor`; pass that cursor back to continue reading, or set
+        `fetch_all=True` to let this method walk the cursors and return the whole
+        document as a single object.
+
+        Args:
+            bookmark_id: The ID (string) of the bookmark to read.
+            format: Readable representation, "markdown" or "text" (optional). If omitted
+                    together with a cursor, the cursor's own format is reused; otherwise
+                    the API defaults to "markdown".
+            max_chars: Maximum number of Unicode characters per chunk, 1 to 50000
+                       (optional, API default 12000). A chunk may end earlier, at a
+                       paragraph or line boundary.
+            cursor: Opaque continuation cursor returned as `nextCursor` by a previous
+                    response (optional).
+            fetch_all: If True, keep following `nextCursor` until the document is
+                       exhausted and return one merged object whose `content` is the
+                       concatenation of every chunk, with `nextCursor=None` and
+                       `truncated=False` (default: False).
+
+        Returns:
+            datatypes.BookmarkReadableContent: A chunk of readable content (or the whole
+            document when fetch_all is True).
+            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, or 409 if
+                      the bookmark content changed after the supplied cursor was issued).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        endpoint = f"bookmarks/{bookmark_id}/content"
+        params = {
+            "format": format,
+            "maxChars": max_chars,
+            "cursor": cursor,
+        }
+        response_data = self._call("GET", endpoint, params=params)
+
+        if fetch_all:
+            # Walk the cursor chain and merge the chunks. The raw dicts are merged
+            # rather than the validated models so that the loop behaves identically
+            # whether or not response validation is enabled.
+            if not isinstance(response_data, dict):
+                raise APIError(
+                    f"Unexpected response format for get_bookmark_readable_content: {response_data}"
+                )
+            merged = dict(response_data)
+            chunks = [merged.get("content", "")]
+            next_cursor = merged.get("nextCursor")
+            while next_cursor:
+                params["cursor"] = next_cursor
+                # The format is carried by the cursor itself, so it is left as passed.
+                page = self._call("GET", endpoint, params=params)
+                if not isinstance(page, dict):
+                    raise APIError(
+                        f"Unexpected response format for get_bookmark_readable_content: {page}"
+                    )
+                chunks.append(page.get("content", ""))
+                # Keep the latest range end/total: the server may only know the true
+                # total once it has rendered further into the document.
+                if "range" in page and "range" in merged:
+                    merged["range"] = {
+                        **page["range"],
+                        "start": merged["range"].get("start", 0),
+                    }
+                merged["contentVersion"] = page.get(
+                    "contentVersion", merged.get("contentVersion")
+                )
+                next_cursor = page.get("nextCursor")
+            merged["content"] = "".join(chunks)
+            merged["nextCursor"] = None
+            merged["truncated"] = False
+            response_data = merged
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        else:
+            # Response should match BookmarkReadableContent schema
+            return datatypes.BookmarkReadableContent.model_validate(response_data)
+
     @optional_typecheck
     def summarize_a_bookmark(self, bookmark_id: str) -> Dict[str, Any]:
         """
@@ -2182,7 +2287,7 @@ class KarakeepAPI:
     @optional_typecheck
     def upload_a_new_asset(
         self, file: str
-    ) -> Union[datatypes.Asset, Dict[str, Any], List[Any]]:
+    ) -> Union[datatypes.UploadedAsset, Dict[str, Any], List[Any]]:
         """
         Upload a new asset file. Corresponds to POST /assets.
 
@@ -2190,7 +2295,7 @@ class KarakeepAPI:
             file: Path to the file to upload.
 
         Returns:
-            datatypes.Asset: Details about the uploaded asset (assetId, contentType, size, fileName).
+            datatypes.UploadedAsset: Details about the uploaded asset (assetId, contentType, size, fileName).
             If response validation is disabled, returns the raw API response (dict/list).
 
         Raises:
@@ -2233,7 +2338,7 @@ class KarakeepAPI:
             return response_data
         else:
             # Response should match Asset schema
-            return datatypes.Asset.model_validate(response_data)
+            return datatypes.UploadedAsset.model_validate(response_data)
 
     @optional_typecheck
     def get_all_backups(
@@ -2480,3 +2585,326 @@ class KarakeepAPI:
 
             logger.error(error_msg)
             raise APIError(error_msg)
+
+    @optional_typecheck
+    def get_asset_signed_url(
+        self, asset_id: str
+    ) -> Union[datatypes.SignedAssetUrl, Dict[str, Any], List[Any]]:
+        """
+        Get a temporary signed URL for downloading an asset.
+        Corresponds to GET /assets/{assetId}/signed-url.
+
+        The returned URL embeds its own signature and expiry, so it can be fetched
+        without an API key. This is the way to hand an asset to something that cannot
+        send the Authorization header (a browser tab, a media player, an <img> tag)
+        without proxying the bytes through get_a_single_asset.
+
+        Args:
+            asset_id: The ID (string) of the asset to sign.
+
+        Returns:
+            datatypes.SignedAssetUrl: The asset id, the temporary URL and its expiry.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails.
+            ValueError: If asset_id is empty.
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        if not asset_id or not asset_id.strip():
+            raise ValueError("asset_id cannot be empty")
+
+        endpoint = f"assets/{asset_id.strip()}/signed-url"
+        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 SignedAssetUrl schema
+            return datatypes.SignedAssetUrl.model_validate(response_data)
+
+    # --- Admin: Job Triggers ---
+
+    @optional_typecheck
+    def admin_trigger_recrawl(
+        self,
+        crawl_status: Literal["success", "failure", "pending", "all"] = "all",
+        run_inference: bool = False,
+        modified_within_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Trigger a recrawl of link bookmarks. Admin only.
+        Corresponds to POST /admin/jobs/trigger/recrawl.
+
+        Args:
+            crawl_status: Filter bookmarks by their current crawl status.
+                          Use "failure" to retry only failed crawls. Default: "all".
+            run_inference: Whether to run AI inference after crawling. Default: False.
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
+
+        Returns:
+            dict: A dictionary with a "success" boolean field.
+
+        Raises:
+            APIError: If the API request fails (e.g., 403 admin access required).
+        """
+        body: Dict[str, Any] = {
+            "crawlStatus": crawl_status,
+            "runInference": run_inference,
+        }
+        # Omitted rather than sent as null: the spec has no null case and the
+        # absence of the key is what means "no time window".
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
+        return self._call("POST", "admin/jobs/trigger/recrawl", data=body)
+
+    @optional_typecheck
+    def admin_trigger_reindex(
+        self,
+        modified_within_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Trigger a reindex of bookmarks in the search engine. Admin only.
+        Corresponds to POST /admin/jobs/trigger/reindex.
+
+        Without modified_within_seconds this clears the existing index and re-queues
+        every bookmark. With it, only bookmarks modified within that window are
+        re-queued and the existing index is left in place, which makes it usable as a
+        cheap catch-up job rather than a full rebuild.
+
+        Args:
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to reindex everything
+                                     from scratch (optional).
+
+        Returns:
+            dict: A dictionary with a "success" boolean field.
+
+        Raises:
+            APIError: If the API request fails (e.g., 403 admin access required).
+        """
+        # The request body is optional in the spec, so nothing is sent when no window
+        # is given; that keeps the "clear and rebuild" behaviour byte-identical to
+        # what older servers expect.
+        body = (
+            None
+            if modified_within_seconds is None
+            else {"modifiedWithinSeconds": modified_within_seconds}
+        )
+        return self._call("POST", "admin/jobs/trigger/reindex", data=body)
+
+    @optional_typecheck
+    def admin_trigger_inference(
+        self,
+        type: Literal["tag", "summarize"],
+        status: Literal["success", "failure", "pending", "all"] = "all",
+        modified_within_seconds: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """
+        Trigger AI inference (tagging or summarization) on bookmarks. Admin only.
+        Corresponds to POST /admin/jobs/trigger/inference.
+
+        Args:
+            type: The type of inference to run: "tag" for AI tagging,
+                  "summarize" for AI summarization.
+            status: Filter bookmarks by their current inference status.
+                    Use "failure" to retry only failed ones. Default: "all".
+            modified_within_seconds: Only process bookmarks modified within this many
+                                     seconds. Must be > 0. Omit to process all matching
+                                     bookmarks (optional).
+
+        Returns:
+            dict: A dictionary with a "success" boolean field.
+
+        Raises:
+            APIError: If the API request fails (e.g., 403 admin access required).
+        """
+        body: Dict[str, Any] = {"type": type, "status": status}
+        # See admin_trigger_recrawl: the key is omitted rather than sent as null.
+        if modified_within_seconds is not None:
+            body["modifiedWithinSeconds"] = modified_within_seconds
+        return self._call("POST", "admin/jobs/trigger/inference", data=body)
+
+    # --- Feeds ---
+
+    @optional_typecheck
+    def get_all_feeds(
+        self,
+    ) -> Union[List[datatypes.Feed], Dict[str, Any], List[Any]]:
+        """
+        Get all RSS feed subscriptions for the current user. Corresponds to GET /feeds.
+
+        Returns:
+            List[datatypes.Feed]: A list of feed 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", "feeds")
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        if (
+            isinstance(response_data, dict)
+            and "feeds" in response_data
+            and isinstance(response_data["feeds"], list)
+        ):
+            return [
+                datatypes.Feed.model_validate(feed) for feed in response_data["feeds"]
+            ]
+        raise APIError(
+            f"Unexpected response format for get_all_feeds when validation is enabled: {response_data}"
+        )
+
+    @optional_typecheck
+    def create_a_new_feed(
+        self,
+        name: str,
+        url: str,
+        enabled: bool = True,
+        import_tags: bool = False,
+    ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
+        """
+        Create a new RSS feed subscription. Corresponds to POST /feeds.
+
+        Args:
+            name: Display name for the feed (1-100 characters).
+            url: The RSS feed URL.
+            enabled: Whether the feed is active and will be fetched (default: True).
+            import_tags: Whether to import tags from the feed items (default: False).
+
+        Returns:
+            datatypes.Feed: The created feed object.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g., 400 quota exceeded).
+            pydantic.ValidationError: If response validation fails (and is not disabled).
+        """
+        feed_data = {
+            "name": name,
+            "url": url,
+            "enabled": enabled,
+            "importTags": import_tags,
+        }
+        response_data = self._call("POST", "feeds", data=feed_data)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        return datatypes.Feed.model_validate(response_data)
+
+    @optional_typecheck
+    def get_a_single_feed(
+        self, feed_id: str
+    ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
+        """
+        Get a single RSS feed by its ID. Corresponds to GET /feeds/{feedId}.
+
+        Args:
+            feed_id: The ID (string) of the feed to retrieve.
+
+        Returns:
+            datatypes.Feed: The requested feed object.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 feed not found).
+        """
+        response_data = self._call("GET", f"feeds/{feed_id}")
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        return datatypes.Feed.model_validate(response_data)
+
+    @optional_typecheck
+    def update_a_feed(
+        self,
+        feed_id: str,
+        name: Optional[str] = None,
+        url: Optional[str] = None,
+        enabled: Optional[bool] = None,
+        import_tags: Optional[bool] = None,
+    ) -> Union[datatypes.Feed, Dict[str, Any], List[Any]]:
+        """
+        Update an RSS feed subscription. Corresponds to PATCH /feeds/{feedId}.
+
+        Args:
+            feed_id: The ID (string) of the feed to update.
+            name: Optional new display name for the feed (1-100 characters).
+            url: Optional new feed URL.
+            enabled: Optional new enabled state.
+            import_tags: Optional new importTags flag.
+
+        Returns:
+            datatypes.Feed: The updated feed object.
+            If response validation is disabled, returns the raw API response (dict/list).
+
+        Raises:
+            ValueError: If no fields are provided to update.
+            APIError: If the API request fails (e.g., 404 feed not found).
+        """
+        update_data: Dict[str, Any] = {}
+        if name is not None:
+            update_data["name"] = name
+        if url is not None:
+            update_data["url"] = url
+        if enabled is not None:
+            update_data["enabled"] = enabled
+        if import_tags is not None:
+            update_data["importTags"] = import_tags
+
+        if not update_data:
+            raise ValueError("At least one field must be provided to update.")
+
+        response_data = self._call("PATCH", f"feeds/{feed_id}", data=update_data)
+
+        if self.disable_response_validation:
+            logger.debug("Skipping response validation as requested.")
+            return response_data
+        return datatypes.Feed.model_validate(response_data)
+
+    @optional_typecheck
+    def delete_a_feed(self, feed_id: str) -> None:
+        """
+        Delete an RSS feed subscription. Corresponds to DELETE /feeds/{feedId}.
+
+        Previously imported bookmarks are not affected.
+
+        Args:
+            feed_id: The ID (string) of the feed to delete.
+
+        Returns:
+            None: Returns None upon successful deletion (204 No Content).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 feed not found).
+        """
+        self._call("DELETE", f"feeds/{feed_id}")
+        return None
+
+    @optional_typecheck
+    def fetch_a_feed(self, feed_id: str) -> None:
+        """
+        Trigger an immediate fetch of an RSS feed. Corresponds to POST /feeds/{feedId}/fetch.
+
+        The fetch is enqueued and processed asynchronously by the server.
+
+        Args:
+            feed_id: The ID (string) of the feed to fetch.
+
+        Returns:
+            None: Returns None upon successful enqueue (204 No Content).
+
+        Raises:
+            APIError: If the API request fails (e.g., 404 feed not found).
+        """
+        self._call("POST", f"feeds/{feed_id}/fetch")
+        return None