Skip to main content

BookmarkService

Facade over the repository and search index.

Handles validation, cache invalidation, and cross-entity operations (e.g. removing a tag also strips it from all bookmarks).

Methods​


create_bookmark()​

def create_bookmark(self, data: Dict[str, Any]) -> Tuple[Optional[Bookmark], Optional[str]]: ...

Validate and persist a new bookmark.

Parameters​

NameTypeDescription
dataDict[str, Any]Dict with url, title, and optional fields.

Returns​

TypeDescription
Tuple[Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], Optional[str]]Tuple of (bookmark, None) on success or (None, error_message) on failure.

get_bookmark()​

def get_bookmark(self, bookmark_id: str) -> Optional[Bookmark]: ...

Retrieve a bookmark by ID, using cache when available.

Parameters​

NameTypeDescription
bookmark_idstrThe unique identifier of the bookmark to retrieve.

Returns​

TypeDescription
Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]The Bookmark object if found, otherwise None.

list_bookmarks()​

def list_bookmarks(
self, page: int = 1, per_page: int = 25, status: Optional[str] = None
) -> Tuple[List[Bookmark], int]: ...

Return a paginated list of bookmarks.

Parameters​

NameTypeDescription
pageint = 11-based page number.
per_pageint = 25Number of items per page.
statusOptional[str] = NoneOptional status filter.

Returns​

TypeDescription
Tuple[List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], int]Tuple of (bookmarks_list, total_count).

update_bookmark()​

def update_bookmark(self, bookmark_id: str, data: Dict[str, Any]) -> Tuple[Optional[Bookmark], Optional[str]]: ...

Partially update a bookmark.

Parameters​

NameTypeDescription
bookmark_idstrThe unique identifier of the bookmark to update.
dataDict[str, Any]A dictionary containing the fields to update for the bookmark (e.g., 'title', 'description', 'url').

Returns​

TypeDescription
Tuple[Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], Optional[str]]A tuple containing the updated Bookmark object and None on success, or None and an error message on failure.

delete_bookmark()​

def delete_bookmark(self, bookmark_id: str) -> bool: ...

Soft-delete by trashing the bookmark.

Parameters​

NameTypeDescription
bookmark_idstrThe unique identifier of the bookmark to delete.

Returns​

TypeDescription
boolTrue if the bookmark was successfully trashed, False otherwise.

archive_bookmark()​

def archive_bookmark(self, bookmark_id: str) -> Optional[Bookmark]: ...

Archive a bookmark.

Parameters​

NameTypeDescription
bookmark_idstrThe unique identifier of the bookmark to archive.

Returns​

TypeDescription
Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]The archived Bookmark object if found and archived, otherwise None.

restore_bookmark()​

def restore_bookmark(self, bookmark_id: str) -> Optional[Bookmark]: ...

Restore a bookmark to active status.

Parameters​

NameTypeDescription
bookmark_idstrThe unique identifier of the bookmark to restore.

Returns​

TypeDescription
Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]The restored Bookmark object if found and restored, otherwise None.

def search(self, query: str, limit: int = 20) -> List[Bookmark]: ...

Full-text search across bookmarks.

Parameters​

NameTypeDescription
querystrThe search string to query bookmarks.
limitint = 20The maximum number of search results to return.

Returns​

TypeDescription
List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]A list of Bookmark objects matching the search query.

list_tags()​

def list_tags(self) -> List[Tag]: ...

Return all tags.

Returns​

TypeDescription
List[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)]A list of all Tag objects.

create_tag()​

def create_tag(self, data: Dict[str, Any]) -> Tuple[Optional[Tag], Optional[str]]: ...

Validate and persist a new tag.

Parameters​

NameTypeDescription
dataDict[str, Any]A dictionary containing the 'name' for the new tag.

Returns​

TypeDescription
Tuple[Optional[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)], Optional[str]]A tuple containing the created Tag object and None on success, or None and an error message on failure.

delete_tag()​

def delete_tag(self, tag_id: str) -> bool: ...

Delete a tag and strip it from all bookmarks.

Parameters​

NameTypeDescription
tag_idstrThe unique identifier of the tag to delete.

Returns​

TypeDescription
boolTrue if the tag was successfully deleted, False otherwise.

update_tag()​

def update_tag(self, tag_id: str, data: Dict[str, Any]) -> Tuple[Optional[Tag], Optional[str]]: ...

Update a tag's name or colour.

Parameters​

NameTypeDescription
tag_idstrThe unique identifier of the tag to update.
dataDict[str, Any]A dictionary containing the fields to update for the tag (e.g., 'name', 'color').

Returns​

TypeDescription
Tuple[Optional[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)], Optional[str]]A tuple containing the updated Tag object and None on success, or None and an error message on failure.

list_collections()​

def list_collections(self) -> List[Collection]: ...

Return all collections.

Returns​

TypeDescription
List[[Collection](../../../models/collection/collection.md?sid=app_models_collection_collection)]A list of all Collection objects.

get_collection()​

def get_collection(self, collection_id: str) -> Optional[Collection]: ...

Retrieve a collection by ID.

Parameters​

NameTypeDescription
collection_idstrThe unique identifier of the collection to retrieve.

Returns​

TypeDescription
Optional[[Collection](../../../models/collection/collection.md?sid=app_models_collection_collection)]The Collection object if found, otherwise None.

create_collection()​

def create_collection(self, data: Dict[str, Any]) -> Tuple[Optional[Collection], Optional[str]]: ...

Create a new collection.

Parameters​

NameTypeDescription
dataDict[str, Any]A dictionary containing the 'name' for the new collection.

Returns​

TypeDescription
Tuple[Optional[[Collection](../../../models/collection/collection.md?sid=app_models_collection_collection)], Optional[str]]A tuple containing the created Collection object and None on success, or None and an error message on failure.

add_to_collection()​

def add_to_collection(self, collection_id: str, bookmark_id: str) -> bool: ...

Add a bookmark to a collection.

Parameters​

NameTypeDescription
collection_idstrThe unique identifier of the collection to add the bookmark to.
bookmark_idstrThe unique identifier of the bookmark to add.

Returns​

TypeDescription
boolTrue if the bookmark was successfully added to the collection, False otherwise.

remove_from_collection()​

def remove_from_collection(self, collection_id: str, bookmark_id: str) -> bool: ...

Remove a bookmark from a collection.

Parameters​

NameTypeDescription
collection_idstrThe unique identifier of the collection to remove the bookmark from.
bookmark_idstrThe unique identifier of the bookmark to remove.

Returns​

TypeDescription
boolTrue if the bookmark was successfully removed from the collection, False otherwise.