node-osx-notifier

A NodeJS Server for sending notifications to OSX Mountain Lion's Notification Center.

Synopsis

OSX Mountain Lion comes packaged with a built-in notification center. For whatever reason, Apple sandboxed the notification center API to apps hosted in its App Store. The end result? A potentially useful API shackled to Apple's ecosystem.

Thankfully, Eloy Durán put together a set of sweet osx apps that allow terminal access to the sandboxed API. node-osx-notifier wraps these apps with a simple express server, exposing an HTTP interface to the closed API.

It's not perfect, and the implementor will quickly notice its limitations. However, it's a start and any pull requests are accepted and encouraged!

Installation

The following command will install the notification server. Use -g to install the server as a global binary.

[sudo] npm install [-g] node-osx-notifier

Running The Server

Running the server is easy peasy. If you installed the server globally, then starting the server is as easy as:

node-osx-notifier [port] [host]

The port and host will default to 1337 and localhost respectively.

Testing The Server

You can then test that the server is running correctly by making a request to it. The simplest request uses the querystring over HTTP GET:

curl "http://localhost:1337/info?message=test"

{
  "status": "* Notification delivered."
}

You can also use the JSON interface to POST the same content to the server:

curl -H "Content-Type: application/json" -X POST -d '{"message":"test"}' "http://localhost:1338/info"

{
  "status": "* Notification delivered."
}

The HTTP API

For starters, you want to pick from one of three notification types. The notification types are designated by the path of the server request. Each notification type changes the icon and section in the notification center:

• info http://localhost:1337/info used for basic notifications
  • 
• pass http://localhost:1337/pass used for showing that a job has passed
  • 
• fail http://localhost:1337/fail used for showing that a job has failed
  • 

In addition, you will also need to pass parameters (as JSON POST-data or a querystring) that tells the server what to do for a given notification type. Since the server acts as a wrapper, these parameters match the command-line options defined by the underlying apps. For completeness, those parameters are outlined below:

At a minimum, you have to specify either the -message , the -remove option or the -list option.

-message VALUE [required]

The message body of the notification.

-title VALUE

The title of the notification. This defaults to ‘Terminal’.

-subtitle VALUE

The subtitle of the notification.

-group ID

Specifies the ‘group’ a notification belongs to. For any ‘group’ only one notification will ever be shown, replacing previously posted notifications.

A notification can be explicitely removed with the -remove option, describe below.

Examples are:

• The sender’s name to scope the notifications by tool.
• The sender’s process ID to scope the notifications by a unique process.
• The current working directory to scope notifications by project.

-remove ID [required]

Removes a notification that was previously sent with the specified ‘group’ ID, if one exists. If used with the special group "ALL", all message are removed.

-list ID [required]

Lists details about the specified ‘group’ ID. If used with the special group "ALL", details about all currently active messages are displayed.

The output of this command is tab-separated, which makes it easy to parse.

-activate ID

Specifies which application should be activated when the user clicks the notification.

You can find the bundle identifier of an application in its Info.plist file inside the application bundle.

Examples are:

• com.apple.Terminal to activate Terminal.app
• com.apple.Safari to activate Safari.app

-open URL

Specifies a resource to be opened when the user clicks the notification. This can be a web or file URL, or any custom URL scheme.

-execute COMMAND

Specifies a shell command to run when the user clicks the notification.

Licence

This project is dual licensed under the MIT license and defers to any licensing defined by the underlying apps.