libbcel

Summary

The package libbcel is an Emacs library to interact with Basecamp, a project management web application.

Authentication

To make libbcel work, you first have to give it access to your Basecamp account. This is done through OAUTH2. If you already have a client id and secret, skip the next section. Otherwise, keep reading.

Obtaining a client id and secret

Login to https://basecamp.com/ and register an application at https://launchpad.37signals.com/integrations. You can use whatever values for most field:

• For the website URL, you can put any URL you want, it doesn’t matter. You can for example use the URL of your website or the URL of libbcel’s repository.
• Check “Basecamp 4” in the “Products” section.
• Set the redirect URI as “http://localhost:9321”. You can use a different port if you want to.

Once the application is registered, click its name to get a client id and client secret. These values must be saved in Emacs so libbcel can access them. If your init.el is private, you can just save these variables inside it. If you share your init.el, you will have to write these values in a different file that is loaded by your init.el. You should write something like this:

(setq libbcel-oauth-client-id "a89b23093a89b23093ffe2dd01938ffe2dd01938")
(setq libbcel-oauth-client-secret "8a9b23093a89b20393ffe2dd01938ffe2dd01983")

If you decided above for a redirect port different from 9321, you also have to specify that:

(setq libbcel-oauth-local-http-port 9000) ;; default is 9321

Authenticating

You have a client id, client secret and port number for the redirect URI (default is 9321). The authenticating protocol requires storing tokens. These tokens will be stored in the file whose path is in the variable libbcel-oauth-store-filename. The file is encrypted by default but you need to set your GPG identity in libbcel-oauth-store-encryption-keys. If you don’t want encryption, you can change the value of libbcel-oauth-store-filename so it doesn’t end with “.gpg”.

(setq libbcel-oauth-store-encryption-keys (list "8A9B23093A89B20393FFE2DD01938FFE2DD01983"))

The last variable you need to set is the account ID. This is the first number appearing after basecamp.com in the URL when you are on the Basecamp website.

(setq libbcel-client-account-id "928734324")

Trying

To try the setup, execute the code below (use M-: for example):

(libbcel-client-get-path
 "/projects.json"
 (lambda (projects)
   (switch-to-buffer (get-buffer-create "*libbcel-test*"))
   (erase-buffer)
   (insert (format "%s projects where returned" (length projects)))))

The first time you do that, a web browser window will open. This is normal. Login if not already done and allow access to the application. You should get a confirmation message in the web browser. This won’t happen again.

If everything went well, you will get a message with a number of projects after a second or two.

License

See COPYING. Copyright (c) 2019-2023 Damien Cassou.