Design the API

[iamnewton]

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. (e.g. I'm always frustrated when [...])

I love Things and I love the command line. I'd like to be able to fire off todos to Things in the background from the command line so I don't have to change context.

Describe the solution you'd like
A clear and concise description of what you want to happen

A simple, yet elegant API that wraps the x-callback-url style parameters into something that plays nice with NodeJS.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered

None at this moment.

Additional context
Add any other context or screenshots about the feature request here

https://culturedcode.com/things/support/articles/2803573/

[iamnewton]

Conversion Function

A mock function that would be called to convert any form of data that comes in to something that Things would accept.

const encode = (data: Object): x-callback-url => `things:///json?data=${encodeURIComponent(JSON.stringify(data))}`;

Sample CLI call

A mock CLI to showcase how data is expected to be used and can help formulate/dictate how the API should respond.

things add <title> [options]

note: should I allow for multiple todos?

Examples

things add <title> --on="today" --at="6p" --in="work"

Options Breakdown

• --on=<date [time] string>
  • Input: date string | date time string | some keywords
  • Things API: when
  • accepts the @ part to set reminders
  • should validate input based on rules from Things docs
• --at=<date string>
  • Input: only a date string
  • Things API: to deadline
• --in=<id | title>
  • Input: area | area-id | project | project-id | heading
  • Things API: list | list-id | heading
  • will need to search through todos to figure if valid?
    • this might slow things down
    • should test to see how the API responds if all 3 parts of this are sent in as parameters

Other Options

• --tag=<tag1, tag2>: array of strings
• --checklist: ? Not sure if i want to support adding in a checklist on creation of a Todo; seems clunky
• --notes=<file | string>

Notes

• tag(s): should be multiple flags, allow spaces, and be merged into a comma separated list
• when: look up docs
• list-id takes precendence over for list
• creation-date should be set to now

Sample API call

things.add(title, on, at, in, options) {
    return {
        type: 'to-do',
        operation: 'create',
        attributes: {
            title,
            'creation-date': new Date().toISOString(),
            // determines when to show up in "Today"; uses natural language
            // if `@<time>`, sets a reminder
            when: on || 'today',
            deadline: at || undefined,

            notes: options.notes || undefined,
            'checklist-items': options.checklist || undefined,
            tags: options.tags,

            heading: in?,
            list: in?,
            'list-id': in?,
        }
    }
}

Open Questions?

1. Should the API call return the Object as JSON? Or should it return the x-callback-url? Or the string but without the protocol?
2. Does the Things API support multiple data points, such as heading, list, list-id all having the same value or will I have to undefine/nullify those values to only send the one value required?
3. Should the API handle multiple todos or should it be a separate API function?

[iamnewton]

Counter Proposal

I don't think this counter-proposal affects the API, in the end, but it's interesting to see something like this in action. Would be very similar to how Fantastical does its intuitive language entry for calendar events.

Sample CLI call

things add <title> on <datetime> at <reminder> in <area|project|heading>