gistfile1.txt

Cu.import("resource://services-cloudsync/main.js");

let service = Cc["@mozilla.org/cloudsync/service;1"]
                  .getService(Components.interfaces.nsISupports)
                  .wrappedJSObject;
    service.whenLoaded().then(() => {

      // Cloudsync is ready, do work

      CloudSync.Local.id; // local device id
      CloudSync.Local.name; // local device name
      CloudSync.Tabs.{add,remove}EventListener("Change", callback); // listen for tab change events
      CloudSync.Tabs.setRemoteTabs([...]);
        * {
            client: {
              id:
              name:
              isMobile:
            },
            tabs: [ {title: , urlHistory: , icon: }, ... ]
            timestamp:
          }
      CloudSync.getLocalTabs();
        * {
            title:
            urlHistory:
            icon:
            lastUsed:
          }

      var folder = CloudSync.Bookmarks.getRootFolder("My Adapter");
      CloudSync.Bookmarks.deleteRootFolder("My Adapter");
      folder.{add,remove}EventListener("ChangeBookmark", callback(guid)); // listen for bookmark change events
      folder.{add,remove}EventListener("RemoveBookmark", callback(guid)); // listen for bookmark remove events
      folder.{add,remove}EventListener("AddBookmark", callback(guid)); // listen for bookmark add events
      folder.{add,remove}EventListener("MoveBookmark", callback(guid)); // listen for bookmark move events
      folder.{add,remove}EventListener("RemoveRootFolder", callback(guid)); // listen for bookmark root folder remove events
      folder.getLocalBookmarks(); // returns a list of bookmarks
        * {
            id: // guid
            parent: // guid
            dateAdded:
            lastModified:
            uri: // null for FOLDER and SEPARATOR
            title:
            type: // should be one of folder.{BOOKMARK, FOLDER, SEPARATOR},
            index: // must be unique among folder items
          }
      folder.getLocalBookmarksByGuid([guid, ...]); // returns a list of bookmarks corresponding to the list of guids
        * {
            id: // guid
            parent: // guid
            dateAdded:
            lastModified:
            uri: // null for FOLDER and SEPARATOR
            title:
            type: // should be one of folder.{BOOKMARK, FOLDER, SEPARATOR},
            index: // must be unique among folder items
          }
      folder.mergeRemoteBookmarks([...]);
        * {
            id: // guid
            parent: // guid
            dateAdded:
            lastModified:
            uri: // null for FOLDER and SEPARATOR
            title:
            type: // should be one of folder.{BOOKMARK, FOLDER, SEPARATOR},
            index: // must be unique among folder items
            deleted:
          }
        * if id doesn't exist and !deleted, create bookmark
        * if id exists and deleted, delete bookmark
        * if id exists and !deleted, update bookmark
          * only given fields are updated (omit fields to leave them unchanged)

      CloudSync.Adapter.register("My Adapter"); // call once when addon is installed
      CloudSync.Adapter.unregister("My Adapter"); // call once when addon is removed

    });

Possible additions to the API:

• folder.clearLocalBookmarks();
• folder.rename("Renamed Adapter");

Can you give some idea of the recommended usage of this API?

The functions that interact with the underlying data should be async.

Updated docs here: https://gist.github.com/modeswitch/905a91be8982c298e309