connect.bookmarks

Read and modify the profile's favorites. Favorites are a tree: every entry is either a link (has a url) or a folder (url: ''), nested via parentId (null = top level).

• Capabilities: bookmarks.read (read), bookmarks.write (modify)
• Namespace: connect.bookmarks

An entry is { id, url, title, favicon, createdAt, kind, parentId }.

Walkthrough

Render the favorites and keep them fresh.

1. Declare the capabilities: bookmarks.read to list, bookmarks.write to modify:

   { "capabilities": ["bookmarks.read", "bookmarks.write"] }

2. Read what you need — list() for a flat set of links, getTree() for the nested structure.
3. Modify with add / createFolder / move / remove.
4. Re-read on onChanged — the event carries no diff, so re-fetch to stay current.

Methods

bookmarks.list()

A flat list of every link, at any depth — the common case.

How to use it

1. Call it; you get every link (no folders).
2. Render directly — no tree-walking needed.

Signature — connect.bookmarks.list() · Capability: bookmarks.read

Returns — Promise<Bookmark[]>. Folders are not included.

bookmarks.getTree()

The nested tree.

How to use it

1. Call it when you need folder structure.
2. Recurse children to render nested folders.

Signature — connect.bookmarks.getTree() · Capability: bookmarks.read

Returns — Promise<Bookmark[]> — roots first; folders carry a children array.

bookmarks.getChildren(parentId?)

Direct children of a folder.

How to use it

1. Pass a folder id, or omit / null for the top level.
2. Use it to lazy-load one folder at a time.

Signature — connect.bookmarks.getChildren(parentId?) · Capability: bookmarks.read

Parameters

Returns — Promise<Bookmark[]> — folders first.

bookmarks.add(url, title?, favicon?, parentId?)

Add a link.

How to use it

1. Pass at least the url; add title / parentId to place it in a folder.
2. Adding an already-favorited URL returns the existing entry (no duplicate).

Signature — connect.bookmarks.add(url, title?, favicon?, parentId?) · Capability: bookmarks.write

Parameters

Returns — Promise<Bookmark>.

bookmarks.createFolder(title, parentId?)

Create a folder.

How to use it

1. Pass a title (and optional parentId to nest it).
2. Use the returned id as a parentId for add / move.

Signature — connect.bookmarks.createFolder(title, parentId?) · Capability: bookmarks.write · Returns Promise<Bookmark>.

bookmarks.move(id, parentId?)

Re-parent an entry.

How to use it

1. Pass the entry id and the new parentId (null = top level).
2. You can't move a folder into itself or a descendant — that's refused.

Signature — connect.bookmarks.move(id, parentId?) · Capability: bookmarks.write

Parameters

Returns — Promise<Bookmark>. Refuses to move a folder into itself or its own descendant.

bookmarks.remove(url)

Delete a link by URL.

How to use it

1. Pass the url of the link to un-favorite.

Signature — connect.bookmarks.remove(url) · Capability: bookmarks.write · Returns Promise<void>.

bookmarks.removeById(id)

Delete by id.

How to use it

1. Pass an entry id.
2. Be careful with a folder id — it deletes the whole subtree.

Signature — connect.bookmarks.removeById(id) · Capability: bookmarks.write

Returns — Promise<void>. Deleting a folder takes its whole subtree with it.

Events

bookmarks.onChanged(cb)

Fires on any favorites change in the profile — yours or the user starring a page.

How to use it

1. Subscribe once.
2. On each fire, re-read with getTree / list (the event carries no diff).
3. Keep the returned function to unsubscribe.

Payload — none. The event carries no diff — re-read on each fire.

const off = connect.bookmarks.onChanged(async () => {
  render(await connect.bookmarks.getTree());
});

Notes

• Ordering inside a folder is by creation time; there's no explicit index yet.
• Feature-detect bookmarks.read / bookmarks.write independently.