Bookmarks

Overview

The API includes built-in support for bookmarking activities. Here's a quick example of how to use the bookmark API.

Adding Bookmarks

// Adding a bookmark to a new folder
let bookmark = try await feed.addBookmark(activityId: "activity_123")
// Adding to an existing folder
let bookmarkWithFolder = try await feed.addBookmark(
    activityId: "activity_123",
    request: .init(folderId: "folder_456")
)
// Update a bookmark (without a folder initially) - add custom data and move it to a new folder
let updatedBookmark = try await feed.updateBookmark(
    activityId: "activity_123",
    request: .init(
        custom: ["color": "blue"],
        newFolder: .init(
            custom: ["icon": "📁"],
            name: "New folder name"
        )
    )
)
// Update a bookmark - move it from one existing folder to another existing folder
let movedBookmark = try await feed.updateBookmark(
    activityId: "activity_123",
    request: .init(
        folderId: "folder_456",
        newFolderId: "folder_789"
    )
)

Removing Bookmarks

// Removing a bookmark
try await feed.deleteBookmark(
    activityId: "activity_123",
    folderId: "folder_456"
)

// When you read a feed we include the bookmark
try await feed.getOrCreate()
print(feed.state.activities[0].ownBookmarks)

Querying Bookmarks

// Query bookmarks
let query = BookmarksQuery(limit: 5)
let bookmarkList = client.bookmarkList(for: query)
let page1 = try await bookmarkList.get()

// Get next page
let page2 = try await bookmarkList.queryMoreBookmarks(limit: 3)

// Query by activity ID
let activityBookmarkList = client.bookmarkList(
    for: .init(
        filter: .equal(.activityId, "activity_123")
    )
)
let activityBookmarks = try await activityBookmarkList.get()

// Query by folder ID
let folderBookmarkList = client.bookmarkList(
    for: .init(
        filter: .equal(.folderId, "folder_456")
    )
)
let folderBookmarks = try await folderBookmarkList.get()

Bookmarks Queryable Built-In Fields

name	type	description	supported operations	example
`user_id`	string or list of strings	The ID of the user who owns the bookmark	`$in`, `$eq`	`{ user_id: { $eq: 'user_123' } }`
`activity_id`	string or list of strings	The ID of the activity that was bookmarked	`$in`, `$eq`	`{ activity_id: { $eq: 'activity_123' } }`
`folder_id`	string or list of strings	The ID of the folder containing the bookmark	`$eq`, `$in`, `$exists`	`{ folder_id: { $exists: true } }`
`created_at`	string, must be formatted as an RFC3339 timestamp	The time the bookmark was created	`$eq`, `$gt`, `$gte`, `$lt`, `$lte`	`{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }`
`updated_at`	string, must be formatted as an RFC3339 timestamp	The time the bookmark was last updated	`$eq`, `$gt`, `$gte`, `$lt`, `$lte`	`{ updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }`

Querying Bookmark Folders

// Query bookmark folders
let query = BookmarkFoldersQuery(limit: 5)
let bookmarkFolderList = client.bookmarkFolderList(for: query)
let page1 = try await bookmarkFolderList.get()

// Get next page
let page2 = try await bookmarkFolderList.queryMoreBookmarkFolders(limit: 3)

// Query by folder name (partial matching)
let projectFolderList = client.bookmarkFolderList(
    for: .init(
        filter: .contains(.folderName, "project")
    )
)
let projectFolders = try await projectFolderList.get()

Bookmark Folders Queryable Built-In Fields

name	type	description	supported operations	example
`user_id`	string or list of strings	The ID of the user who owns the folder	`$in`, `$eq`	`{ user_id: { $eq: 'user_123' } }`
`folder_name`	string or list of strings	The name of the bookmark folder	`$eq`, `$in`, `$contains`	`{ folder_name: { $contains: 'work' } }`
`created_at`	string, must be formatted as an RFC3339 timestamp	The time the folder was created	`$eq`, `$gt`, `$gte`, `$lt`, `$lte`	`{ created_at: { $gte: '2023-12-04T09:30:20.45Z' } }`
`updated_at`	string, must be formatted as an RFC3339 timestamp	The time the folder was last updated	`$eq`, `$gt`, `$gte`, `$lt`, `$lte`	`{ updated_at: { $gte: '2023-12-04T09:30:20.45Z' } }`

Managing Bookmark Folders

Update bookmark folder

The endpoint performs a partial update: only the fields you include in the request are changed, and each of those fields is completely overwritten.

Updating a bookmark folder sends feeds.bookmark_folder.updated event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

Delete bookmark folder

Use the delete bookmark folder endpoint to remove a folder by ID. All bookmarks in that folder are removed.

Deleting a bookmark folder sends feeds.bookmark_folder.deleted event to the clients of the user who owns the folder. There are no default client-side SDK handlers for this event, but you can add a custom handler if your UI needs to be updated.

// Add a bookmark with a new folder
let bookmark = try await feed.addBookmark(
    activityId: activity.id,
    request: .init(newFolder: .init(name: "Breakfast recipes", custom: ["icon": "🍳"]))
)

// Update the folder
let updatedFolder = try await client.updateBookmarkFolder(
    folderId: bookmark.folder!.id,
    request: .init(name: "Sweet Breakfast Recipes", custom: ["icon": "🥞"])
)

// Delete the folder (and all bookmarks in it)
try await client.deleteBookmarkFolder(folderId: updatedFolder.id)

Reactions

Comments