Bear Integration with Drafts

17 Jan 2021

Late last year, I got involved in a discussion on the Drafts forum about resolving an issue with a Bear action that was a little outdated, and more recently in an ongoing thread about importing content from Bear into Drafts. Through looking at these, my interest was piqued and I decided to have a look at adding some Bear integration into the ThoughtAsylum Library for Drafts , TADpoLe.

• What is TADpoLe?
• What About the Existing Bear API?
• Does Bear Have an API?
• Translating Bear’s URL Scheme to Drafts
• Dealing with Bear Device Tokens
• Exporting to Bear
• Importing from Bear
• Easy Access in the ThoughtAsylum Action Group Suite
• Conclusion

What is TADpoLe?

TADpoLe is a collection of JavaScript code that I’ve put together while working with Drafts. It builds on Drafts’ existing scripting framework to provide functions to carry out useful things. There is more information about this on the TADpoLe page, and there’s a dedicated set of documentation available online.

What About the Existing Bear API?

In the Drafts forums’ integration guide for Bear, there is a link to a user created API to allow for user interaction with Bear. It hasn’t been updated in a while and I figured I could probably get a little bit more utility out of Bear’s URL scheme at this stage, especially with some of the updates in Drafts that have also occurred since that was released.

Does Bear Have an API?

Well, I wouldn’t call the URL scheme they offer an API, but it is an automation interface and that’s good enough for me to work with from Drafts.

The details about Bear’s URL scheme can be found on their website, and I would say that the developers have done a really nice job of building out a good range of functionality and documenting the interface really well.

Translating Bear’s URL Scheme to Drafts

At the time of creating the TADpoLe update (January 2021) I incorporated every x-callback-url option with the exception of the file attachment one (/add-file), as this didn’t seem to fit particularly well with Drafts’ plain text functionality, but I may revisit this at some point in the future.

Now, several of these x-callback-url functions are probably never, if ever going to be of great utility. Personally, I find being able to set the font and theme in Bear via a call to be of very limited use, but they were pretty easy to include and made the set of functionality more complete, so I put in a little extra effort to include them.

From those basic URL scheme equivalents, I also built out a few additional bits of functionality to combine elements, which I then made use of in the ThoughtAsylum Action Group Suite.

You can find out all about the available functions on the TadBear page on the TADpoLe documentation site.

Dealing with Bear Device Tokens

Draft provides a credentials store that allows data such as API keys to be stored and accessed safely. One of the interesting choices that the Bear developers have made in regards to the API is the use of device specific tokens to permit the API to be used. The tokens are accessible from the client applications, but they only apply to the client application on that device. Therefore, to store these in the credentials store, we need to be able to keep each device’s API key in the store.

The added complication here is being able to distinguish between devices. Drafts can distinguish the device model (e.g. an iPhone vs a Mac), and for most people, they are only likely to have one device of any particular type. But, what about those who have more than one device of the same type? Maybe they have a large iPad for home and a smaller one they travel with, or a desktop Mac at the office, and a personal Mac at home?

For these scenarios we need to ensure that we have a unique identifier, but Drafts doesn’t natively make one available. However, Drafts does support both iCloud and local storage areas. The iCloud storage area is shared across devices, but the local, as the name implies, is local to that device. We can therefore store the name of a credential associated with the device in the local storage, and use that to identify the correct API token from Drafts’ credentials store.

The TA_deviceTokenforBear() function is used to store and retrieve the API token for Bear on a device, and it in turn makes use of TA_deviceUUIDforBear(), which uses a UUID generation function from TADpoLe to generate and store an ID in a text file in local storage - LocalBearID.txt.

If the file exists, Drafts will reference the credentials store for the appropriate API token. If the file does not exist, then it will be created, and the user is prompted for the API token to be stored for future use.

Exporting to Bear

Given that Drafts is “the place where text starts”, providing something that allows you to export from Drafts to Bear is an obvious use case. While the share sheet can provide a simple direct transfer of content, the TA_exportDraftToBear() function will also carry across any tags associated with the draft and apply Bear tags to them when the draft is created in Bear. The function also returns the ID of the draft, so you could then use TA_openNote() to open the note in Bear should you so wish, or add a reference somewhere in Drafts, e.g. as inserting a URL to open the note.

Importing from Bear

As well as exporting into Bear, I was also able to add a function to import from Bear. Previously, to do this and get matching dates and the like involved working with Drafts’ native file format and manually carrying out imports. There were some scripts around that could help with this, but in 2020, Drafts received an update that allowed draft dates to be set to cover just such import scenarios. Linking this up with the Bear API was then pretty straight forward.

The TA_importNoteToDrafts() and TA_importNotesToDrafts() functions allow you to import a single Bear note specified by its Bear ID, or a set of notes specified by a search string and Bear tag (which could of course just match a single note). Any tags in Bear for a note are applied to the imported draft, and the creation date is also set.

Note that the modified date is not set as every time a draft is modified in any way, that date is set, meaning that when you set a modified date, it immediately gets superseded at the point of committing the update by the current date.

Both of the import functions also support assignment of additional tags, which can help when you want to identify a batch of drafts/imported notes.

Easy Access in the ThoughtAsylum Action Group Suite

While the basis of TADpoLe is very much to help others with creating their own actions, I also try and provide useful actions via the ThoughtAsylum Action Group Suite, a set of action groups that cover a wide range of functionality using TADpoLe as the basis for the majority of the functionality. Along with the Bear additions in TADpoLe, I therefore also added a range of actions that utilise the functions.

The actions are in many cases direct applications of the functions, but there are a number that make more sophisticated use of the Bear API functionality.

Below is a list of the action groups that currently¹ have Bear-related actions in them, and the action group sections they can be found in. The suite is also fully documented, so you can read about what each action does prior to downloading any of the groups.

• ThoughtAsylum - Export/Import/Share
  • Bear
    • TAD-Copy Bear Tags
    • TAD-Export Selection to Bear
    • TAD-Export Draft to Bear
    • TAD-Import Note From Bear
    • TAD-Import Notes From Bear
    • TAD-Bear Grab Selected URL
    • TAD-Bear Grab Clipboard URL
• ThoughtAsylum - Management
  • Tag Management
    • TAD-Add Bear Tag
• ThoughtAsylum - Power User
  • Information
    • TAD-Copy Device UUID for Bear
    • TAD-Display Device UUID for Bear
• ThoughtAsylum - Trove
  • Control Bear
    • TAD-Bear Set Font
    • TAD-Bear Set Theme
    • TAD-Bear Select Locked
    • TAD-Bear Select Today
    • TAD-Bear Select Todo
    • TAD-Bear Select Untagged
    • TAD-Bear Select Archive
    • TAD-Bear Select Trash
    • TAD-Delete Bear Tag
    • TAD-Rename Bear Tag
    • TAD-Show Tag in Bear

Please note that all of the suite’s action groups have a pre-requisite of the core ThoughtAsylum Action Group. This group provides common functionality across the groups, primarily through the set-up of TADpoLe and associated libraries.

Conclusion

Hopefully, this gives you a feel for the Bear functionality available to Drafts via the use of TADpoLe, and via the ThoughtAsylum Action Group Suite. If you have any issues, please feel free to reach out on the Drafts forums, and I, or one of the other forum members will assist wherever we can.

Do also let me know if you find this functionality useful. I build and share the functionality in TADpoLe and the ThoughtAsylum Action Group Suite to try and support the great community that’s built up around Drafts, and I’m always happy to hear when it’s helped people out.