em-campfire is a library for interacting with the Campfire chat application. It was extracted from the Scamp v1 bot framework.

gem install em-campfire or put gem 'em-campfire' in your Gemfile.

require 'em-campfire'

EM.run {
  connection = EM::Campfire.new(:subdomain => "foo", :api_key => "jhhekrlfjnksdjnliyherkjb", :verbose => true)

  # Join a room, you will need the room id
  connection.join(10101)

  # Stream a room, need to join it first
  connection.join(2345) {|id| connection.stream(id) }

  # Dump out any message we get
  connection.on_message do |msg|
    puts msg.inspect
  end

  # Give lib a chance to connect
  EM::Timer.new(10) do
    # Say something on a specific channel
    connection.say "foofoofoo", 10101

    # Paste something
    connection.paste "foo\nfoo\nfoo", 10101

    # Play a sound
    connection.play "nyan", 10101
  end
}

For more features see the examples.

There are a few optional parameters you can create an EM::Campfire with:

require 'em-campfire'

EM.run {
  connection = EM::Campfire.new(
    :subdomain => "foo",
    :api_key => "jhhekrlfjnksdjnliyherkjb",
    :verbose => true,
    :logger => Logger::Syslog.new('process_name', Syslog::LOG_PID | Syslog::LOG_CONS),
    :cache => custom_cache_object,
    :ignore_self => true,
    :ignore_timestamps => true,
    :user_agent => "my bot"
  )

  # more code
}

If set to true sets the log level to DEBUG, defaults to false.

em-campfire uses a Logger instance from stdlib by default, you can switch this out by passing in your own logger instance.

em-campfire caches responses from the Campfire API and issues conditional requests using ETags. By default it uses an in-memory cache of data returned, and this is fine for most people, but if you want something custom, possibly more permanent, you can pass in your own cache object.

The cache object should conform to the get/set API of the redis-rb lib (making that a drop-in replacement). Just make sure that you use the synchrony driver.

em-campfire receives messages that it posted on it's streaming connections. By default it processes these just as it would any other message. set :ignore_self to true to make it ignore messages it sends.

Campfire sends periodic timestamp messages. They're useless for most applications, so set this option and they will be totally ignored.

Sets the User-Agent header for the EventMachine::HttpRequests to Campfire. Defaults to "em-campfire".

I've tested it in Ruby >= 1.9.3.

• See if http connection/cacheing/failure handling can be abstracted
• Allow user to pass success/error callbacks
• Re-try failed HTTP requests
• Maybe encapsulate actions in objects, for instance a Room object

em-campfire was written primarily to support Scamp/scamp-campfire so I've implemented the features required for that first. There are other features left-over that I didn't need and I'll get round to at some point. If you need one before then ping me and I might write it, or a pull request is of course welcome.

See the Campfire API for reference:

• Messages (recent, highlight, unhighlight)
• Rooms (updating, locking, unlocking, leaving)
• Transcripts
• Uploads
• Search
• Account

• Will Jessop (will@willj.net)

See the CONTRIBUTING file