README

Watercoolr
===========

   pubsub via webhooks, or "twitter" for your applications


Input
======


Native watercoolr publishers
-----------------------------

Send POST request with JSON-encoded 'payload' parameter to

  http://watercoolr.example.com/publish

'payload' must provide at least channel name payload[:channel] and a message
payload[:message]. The message will be send to all subscribers of that channel.

 * Example

  resp = RestClient.post 'http://admin:admin@localhost:4567/channels', :data => ''
  id = JSON.parse(resp)["id"]
  resp = RestClient.post 'http://localhost:4567/subscribe', 
    :data => { :channel => id, 
               :url => 'http://localhost:8080/test-handler' }.to_json
  puts resp
  resp = RestClient.post 'http://localhost:4567/publish', 
    :payload => { :channel => id, :message => 'HAYYYY' }.to_json
  puts resp


You can use watercoolr to receive input from different web services,
supporting webhooks.


ping.fm
--------

http://ping.fm/ can provide IM, E-mail, web etc. input for your webhooks.
The information is coming via POST parameters - see also
http://groups.google.com/group/pingfm-developers/web/working-with-a-custom-url

Go to http://ping.fm/custom/ and in the "Custom URL:" box enter:

  http://watercoolr.example.com/pingfm

You need a channel with 'pingfm' type. During the system startup one such
channel is added by default. Just find it's name or create a new one - the
latest created will be used. You can add then subscribers to your 'pingfm' 
channel.

  * Example

  # on http://ping.fm/custom/ enter http://example.com/pingfm
  # optional - create 'pingfm' type channel 
  # or use the default one with id = '__pingfm__' 
  resp = RestClient.post 'http://admin:admin@localhost:4567/channels',
    :data => { :type => 'pingfm' }.to_json
  id = JSON.parse(resp)["id"]
  # register your subscribers and send them messages from IM, e-mail etc.


GitHub
-------

http://github.com/ can push notification for repository commits to your
webhooks. The all information is inside JSON-encoded 'payload' parameter.
See also: http://github.com/guides/post-receive-hooks

From your project pages go to "Admin"|"Service Hooks" and in the 
"Post-Receive URLs" box enter:

   http://watercoolr.example.com/github

You need a channel with 'github' type. During the system startup one such
channel is added by default. Just find it's name or create a new one - the
latest created will be used. You can add then subscribers to your 'github' 
channel.

  * Example

  # optional - create 'github' type channel 
  # or use the default one with id = '__github__' 
  resp = RestClient.post 'http://admin:admin@localhost:4567/channels',
    :data => { :type => 'github' }.to_json
  id = JSON.parse(resp)["id"]


PubSubHubbub
-----------

watercoolr can be PubSubHubbub CALLBACK ONLY for now. 
To get Atom notifications from some hub:

  1a. Create 'pubsubhubbub' type channel with some topic and a secret:

  resp = RestClient.post 'http://admin:admin@localhost:4567/channels',
    :data => { :type => 'pubsubhubbub', 
               :topic => 'http://example.com/feed',
               :secret => 'secret' }.to_json
  id = JSON.parse(resp)["id"]

  Or: 
  
  1b. If you will use Superfeedr for hub, register a channel with 
ID={secret superfeedr token}:

  TOKEN = 'YourSuperFeedrToken'.freeze
  resp = RestClient.post 'http://admin:admin@localhost:4567/channels', 
    :data => { :type => 'superfeedr', :id => TOKEN }.to_json
  id = JSON.parse(resp)["id"]

  2. Add subscribers like usual (provide channel secret if needed)

  3a. GAE PubSubHubBub

Go to http://pubsubhubbub.appspot.com/subscribe and
  - Callback: http://watercoolr.example.com/hub/callback/{channel_name}
  - Topic: same link to RSS/Atom link, used in channel creation
  - Verify type, Mode - your choice
  - Verify token: the channel secret (default = 'change_me')

  3b. Superfeedr 

In "Settings"|"Notifications" choose Type: "PubSubhubbub" and in the 
"Webhook URL" box enter:

  http://watercoolr.example.com/hub/callback/{YourSuperFeedrToken}


Output
=======

"Normal" subscribers (webhooks)
--------------------------------

watercoolr can push notifications to normal webhooks. Information is divided on two
parts (similar to github):

  - meta-information (user names, passwords etc.) inside the 'data' JSON-encoded
    parameter
  - actual data (message) - 'payload' JSON-encoded parameter

To prevent security information leaks, all subscribers are created with type='debug'
by default. For such subscribers, 'data' parameter is not send during the POSTs.
This kind of subscribers are suitable for example for debugging (PostBin etc.).
To have the 'data' parameter send to the hook, set the subscriber type to any string,
different from 'debug':

  * Example

  resp = RestClient.post 'http://admin:admin@localhost:4567/channels',
    :data => { :type => 'pingfm' }.to_json
  id = JSON.parse(resp)["id"]

  puts "adding subscribers to channel #{id}"
  resp = RestClient.post 'http://localhost:4567/subscribe', 
    :data => { :channel => id, 
               :type => 'local', 
               :url => 'http://localhost:4567/hook/xmpp/secret/', 
               :username => 'me_jid@jabber.com',
               :password => 'secret',
               :to => 'some_jid@xmpp.org' }.to_json
  puts resp
   
  resp = RestClient.post 'http://localhost:4567/subscribe',
    :data => { :channel => id, :url => 'http://postbin.org/xxxYYY' }.to_json
  puts resp    

  resp = RestClient.post 'http://localhost:4567/publish', 
    :data => { :channel => id, :message => 'HAYYYY' }.to_json
  puts resp


Small webhooks library
-----------------------

To be easier to start with watercoolr, it provides a small library of ready to use 
webhooks, accessable on the same system, where watercoolr is deployed.
If the site URL is http://localhost:4567/ , the URLs for webhooks will be: 

  http://localhost:4567/hook/:NAME/:SECRET/

where :NAME is one of ff (FriendFeed), twitter, xmpp or prowl and :SECRET is 
a special user, created during the initial deployment:

  DB[:users] << { :name => 'all', :password => '...', :service => 'hooks' }

You can create also secret token per webhook, with :name => 'ff', 'twitter' or 'xmpp'

  DB[:users] << { :name => 'all', :password => 'secret', :service => 'hooks' }
  DB[:users] << { :name => 'xmpp', :password => 'token', :service => 'hooks' }

xmpp webhook will be on URL: http://localhost:4567/hook/xmpp/token/ and all other
webhooks - on URL: http://localhost:4567/hook/:name/secret/

Webhooks can be used like watercoolr subscribers or called directly with POST request
and 'data' amd 'payload' parameters from other services (github etc.)


Pushing to iPhone
------------------

'prowl' webhook can be used to push notifications to iPhone.

  resp = RestClient.post 'http://localhost:4567/subscribe',
    :data => { :channel => id,
               :type => 'local',
               :url => 'http://localhost:4567/hook/prowl/secret/',
               :apikey => 'PROWL_APIKEY',
               :priority => 2}.to_json
  puts resp    

  resp = RestClient.post 'http://localhost:4567/publish', 
    :data => { :channel => id, :title => 'Alert!' :message => 'Call me!' }.to_json
  puts resp
  
For Prowl API details see: http://forums.cocoaforge.com/viewtopic.php?f=45&t=20339


messagepub subscribers
-----------------------

http://messagepub.com/ can send message to twitter, XMPP (jabber), SMS etc.
There also have a ruby wrapper around their API

  gem install messagepub --no-rdoc --no-ri

In order to use their services, subscribers with 'messagepub' type and additional
data (channels, propagation etc.) need to be used. See also:
http://messagepub.com/documentation/api .

 * Example

  mp = { 
    :recipient => [
       {:position => 1, :channel => 'email', :address => 'me@example.com'},
       {:position => 2, :channel => 'twitter', :address => 'thetwitter'}
  ]}
 
  resp = RestClient.post('http://localhost:4567/subscribe',
    :data => { :channel => id, :type => 'messagepub', :url => 'YOURAPIKEY',
               :escalation => 30, :recipients => mp }.to_json)
  puts resp