Thingamajig

Thingamajig offers an OOPy API to interact with a local Things 3 Mac app instance. Use it to create and manipulate todos and more.

Usage

This README is severaly lacking in instructions. Here's some sample code that might give you an intuitive feel of how to use it:

  # List all projects
  Thingamajig.new.projects.each do |project|
    puts "Found project #{project.name} with #{project.todos.count} todos"
  end

  # Find a project
  project = Thingamajig::Project.find_by(name: "Home")

  # List all todos (that have not been logged yet)
  project.todos.each do |todo|
    puts "Todo: #{todo.name}"
    puts todo.notes
  end

  # List all "active" todos (i.e. showing up in Today)
  project.todos(Thingamajig::Todo.predicate_active).each do |todo|
    # Reschedule them to tomorrow
    todo.activation_date = 1.day.from_now
  end

  # Create new Todo with a name and some notes
  todo = project.create_todo!("Fix drainage", "Is it just clogged, or should we replace the plumbing?")

  # Schedule it for a future date
  todo.activation_date = 5.days.from_now

  # Show it in the GUI
  todo.show

  # Or complete it
  todo.complete!

  # List all projects under the Area named "Work"
  Thingamajig::Area.find_by(name: "Work").projects.flat_map do |project|
    # For each project, get the todos that are active and have status "open" (not completed or cancelled)
    project.todos(Thingamajig::Todo.predicate_active.and(Thingamajig::Todo.predicate_open))
  end

  # Check whether Things is in focus
  Thingamajig.new.frontmost? # => false

Naming

If you're tired of typing "Thingamajig" out in full, feel free to alias it:

Things = Thingamajig

I do. Sadly RubyGems is littered with Things-related gems that haven't been updated in 8 years and don't work with Things 2, let alone Things 3, but they're still hogging all the best names. things, thingies, things-client, things-rb, ... even thingamabob is taken.

Installation

Add this line to your application's Gemfile:

gem 'thingamajig'

And then execute:

$ bundle

Or install it yourself as:

$ gem install thingamajig

Example Usage

I use Thingamajig extensively in my personal automated workflows. You can find the source code here: https://github.com/dv/dotworkflows

Research

A lot of this was done through trial-and-error. Helpful resources:

The official documentation by Cultured Code (beware, it's full of mistakes).
Example of connecting to the underlying SQLite3 database: https://github.com/lucbeaulieu/KanbanView

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Fork it ( https://github.com/dv/thingamajig/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

dv/thingamajig