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).

Constructor

Signature

def BookmarkService() - > None

Methods

`create_bookmark()`

@classmethod
def create_bookmark(
    data: Dict[str, Any]
) - > Tuple[Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], Optional[str]]

Validate and persist a new bookmark. Returns a tuple of (bookmark, None) on success or (None, error_message) on failure.

Parameters

Name	Type	Description
data	`Dict[str, Any]`	A dictionary containing bookmark data, including 'url' and 'title', and optional fields.

Returns

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

`get_bookmark()`

@classmethod
def get_bookmark(
    bookmark_id: str
) - > Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_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()`

@classmethod
def list_bookmarks(
    page: int = 1,
    per_page: int = 25,
    status: Optional[str] = None
) - > Tuple[List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], int]

Return a paginated list of bookmarks. Returns a tuple of (bookmarks_list, total_count).

Parameters

Name	Type	Description
page	`int` = 1	The 1-based page number for pagination.
per_page	`int` = 25	The number of bookmarks to return per page.
status	`Optional[str]` = None	An optional status to filter bookmarks by.

Returns

Type	Description
`Tuple[List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], int]`	A tuple containing a list of bookmarks and the total count of bookmarks.

`update_bookmark()`

@classmethod
def update_bookmark(
    bookmark_id: str,
    data: Dict[str, Any]
) - > Tuple[Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)], Optional[str]]

Partially update a bookmark. Returns a tuple of (bookmark, None) on success or (None, error_message) on failure.

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.

Returns

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

`delete_bookmark()`

@classmethod
def delete_bookmark(
    bookmark_id: str
) - > bool

Soft-delete a bookmark by marking it as trashed. Returns True if the bookmark was found and marked for deletion, False otherwise.

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 soft-deleted, False otherwise.

`archive_bookmark()`

@classmethod
def archive_bookmark(
    bookmark_id: str
) - > Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]

Archive a bookmark, changing its status to archived. Returns the archived bookmark or None if not found.

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, otherwise None.

`restore_bookmark()`

@classmethod
def restore_bookmark(
    bookmark_id: str
) - > Optional[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]

Restore a bookmark to active status. Returns the restored bookmark or None if not found.

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, otherwise None.

`search()`

@classmethod
def search(
    query: str,
    limit: int = 20
) - > List[[Bookmark](../../../models/bookmark/bookmark.md?sid=app_models_bookmark_bookmark)]

Perform a full-text search across all bookmarks. Returns a list of matching bookmarks.

Parameters

Name	Type	Description
query	`str`	The search query string.
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 bookmarks that match the search query.

`list_tags()`

@classmethod
def list_tags() - > List[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)]

Return all available tags.

Returns

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

`create_tag()`

@classmethod
def create_tag(
    data: Dict[str, Any]
) - > Tuple[Optional[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)], Optional[str]]

Validate and persist a new tag. Returns a tuple of (tag, None) on success or (None, error_message) on failure.

Parameters

Name	Type	Description
data	`Dict[str, Any]`	A dictionary containing tag data, including 'name' and optional 'color'.

Returns

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

`delete_tag()`

@classmethod
def delete_tag(
    tag_id: str
) - > bool

Delete a tag and remove it from all associated bookmarks. Returns True if the tag was found and deleted, False otherwise.

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()`

@classmethod
def update_tag(
    tag_id: str,
    data: Dict[str, Any]
) - > Tuple[Optional[[Tag](../../../models/tag/tag.md?sid=app_models_tag_tag)], Optional[str]]

Update a tag's name or color. Returns the updated tag or None if not found.

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, such as 'name' or 'color'.

Returns

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

`list_collections()`

@classmethod
def list_collections() - > List[[Collection](../../../models/collection/collection.md?sid=app_models_collection_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()`

@classmethod
def get_collection(
    collection_id: str
) - > Optional[[Collection](../../../models/collection/collection.md?sid=app_models_collection_collection)]

Retrieve a collection by its unique identifier.

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()`

@classmethod
def create_collection(
    data: Dict[str, Any]
) - > Tuple[Optional[[Collection](../../../models/collection/collection.md?sid=app_models_collection_collection)], Optional[str]]

Create a new collection. Returns the created collection or None with an error message if creation fails.

Parameters

Name	Type	Description
data	`Dict[str, Any]`	A dictionary containing collection data, including a 'name'.

Returns

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

`add_to_collection()`

@classmethod
def add_to_collection(
    collection_id: str,
    bookmark_id: str
) - > bool

Add a bookmark to a specified collection. Returns True if the bookmark was successfully added, False otherwise.

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()`

@classmethod
def remove_from_collection(
    collection_id: str,
    bookmark_id: str
) - > bool

Remove a bookmark from a specified collection. Returns True if the bookmark was successfully removed, False otherwise.

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.

Constructor​

Signature​

Methods​

create_bookmark()​

Parameters​

Returns​

get_bookmark()​

Parameters​

Returns​

list_bookmarks()​

Parameters​

Returns​

update_bookmark()​

Parameters​

Returns​

delete_bookmark()​

Parameters​

Returns​

archive_bookmark()​

Parameters​

Returns​

restore_bookmark()​

Parameters​

Returns​

search()​

Parameters​

Returns​

list_tags()​

Returns​

create_tag()​

Parameters​

Returns​

delete_tag()​

Parameters​

Returns​

update_tag()​

Parameters​

Returns​

list_collections()​

Returns​

get_collection()​

Parameters​

Returns​

create_collection()​

Parameters​

Returns​

add_to_collection()​

Parameters​

Returns​

remove_from_collection()​

Parameters​

Returns​

Constructor

Signature

Methods

`create_bookmark()`

Parameters

Returns

`get_bookmark()`

Parameters

Returns

`list_bookmarks()`

Parameters

Returns

`update_bookmark()`

Parameters

Returns

`delete_bookmark()`

Parameters

Returns

`archive_bookmark()`

Parameters

Returns

`restore_bookmark()`

Parameters

Returns

`search()`

Parameters

Returns

`list_tags()`

Returns

`create_tag()`

Parameters

Returns

`delete_tag()`

Parameters

Returns

`update_tag()`

Parameters

Returns

`list_collections()`

Returns

`get_collection()`

Parameters

Returns

`create_collection()`

Parameters

Returns

`add_to_collection()`

Parameters

Returns

`remove_from_collection()`

Parameters

Returns