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
| Name | Type | Description |
|---|
| data | Dict[str, Any] | Dict with url, title, and optional fields. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| bookmark_id | str | The unique identifier of the bookmark to retrieve. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| page | int = 1 | 1-based page number. |
| per_page | int = 25 | Number of items per page. |
| status | Optional[str] = None | Optional status filter. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| bookmark_id | str | The unique identifier of the bookmark to update. |
| data | Dict[str, Any] | A dictionary containing the fields to update for the bookmark (e.g., 'title', 'description', 'url'). |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| bookmark_id | str | The unique identifier of the bookmark to delete. |
Returns
| Type | Description |
|---|
bool | True if the bookmark was successfully trashed, False otherwise. |
archive_bookmark()
def archive_bookmark(self, bookmark_id: str) -> Optional[Bookmark]: ...
Archive a bookmark.
Parameters
| Name | Type | Description |
|---|
| bookmark_id | str | The unique identifier of the bookmark to archive. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| bookmark_id | str | The unique identifier of the bookmark to restore. |
Returns
| Type | Description |
|---|
Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)] | The restored Bookmark object if found and restored, otherwise None. |
search()
def search(self, query: str, limit: int = 20) -> List[Bookmark]: ...
Full-text search across bookmarks.
Parameters
| Name | Type | Description |
|---|
| query | str | The search string to query bookmarks. |
| limit | int = 20 | The maximum number of search results to return. |
Returns
| Type | Description |
|---|
List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)] | A list of Bookmark objects matching the search query. |
def list_tags(self) -> List[Tag]: ...
Return all tags.
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| data | Dict[str, Any] | A dictionary containing the 'name' for the new tag. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| tag_id | str | The unique identifier of the tag to delete. |
Returns
| Type | Description |
|---|
bool | True 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
| Name | Type | Description |
|---|
| tag_id | str | The unique identifier of the tag to update. |
| data | Dict[str, Any] | A dictionary containing the fields to update for the tag (e.g., 'name', 'color'). |
Returns
| Type | Description |
|---|
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
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| collection_id | str | The unique identifier of the collection to retrieve. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| data | Dict[str, Any] | A dictionary containing the 'name' for the new collection. |
Returns
| Type | Description |
|---|
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
| Name | Type | Description |
|---|
| collection_id | str | The unique identifier of the collection to add the bookmark to. |
| bookmark_id | str | The unique identifier of the bookmark to add. |
Returns
| Type | Description |
|---|
bool | True 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
| Name | Type | Description |
|---|
| collection_id | str | The unique identifier of the collection to remove the bookmark from. |
| bookmark_id | str | The unique identifier of the bookmark to remove. |
Returns
| Type | Description |
|---|
bool | True if the bookmark was successfully removed from the collection, False otherwise. |