imified 0.0.2

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+*.swp
+.bundle
+Gemfile.lock
+pkg/*
+vendor/*
+lib/imified.yml

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in imified.gemspec
+gemspec

data/README.rdoc

@@ -0,0 +1,61 @@
+== Imified
+
+Easily IM enable your Ruby or Rails applications with one simple API.
+
+The Imified gem aims to be as flexible as possible while helping you
+easily integrate instant messaging into your application.
+
+Imified was designed to be as simple as possible. For the first implementation
+it will simply contain the public API methods specified on the Imified website.
+(http://www.imified.com/developers/api)
+
+== Create an Imified account
+
+1. Create your FREE accout at http://www.imified.com/account/sign_up.
+
+2. Create your bot.
+   Imified will ask you to provide the following information:
+
+   - Name
+   - Screen Name
+   - URL (Note: Leave this blank until you need it.)
+
+3. Create a screenname for your bot.
+   Choose one of the following services:
+
+   - Jabber (www.jabber.org)
+   - AIM (www.aim.com)
+   - MSN (signup.live.com)
+   - YAHOO (http://edit.yahoo.com/registration?.intl=us&new=1&.done=http%3A//mail.yahoo.com&.src=ym)
+   - Google Talk (www.google.com/talk)
+   - Twitter (www.twitter.com)
+
+4. Login to your imified bot and connect the bot to the newly created account.
+
+== Installation
+
+Install the gem:
+
+  gem install imified
+
+Setup IMified when your application initializes:
+
+  Imified.setup do |config|
+    config.botkey = 'botkey of the bot you want to use'
+    config.email_address = 'your imified account email address'
+    config.password = 'your imified account password'
+  end
+
+== Usage
+
+  # Send a message to a user or list of users.
+  Imified.send_message("Welcome to Imified", :to => 'userkey')
+
+  # Fetch the user details for a specific user.
+  Imified.get_user(userkey)
+
+  # Fetch a list of all of the users known to the bot.
+  Imified.get_all_users
+
+  # Update the status of your bot
+  Imified.update_status

data/Rakefile

@@ -0,0 +1 @@
+require 'bundler/gem_tasks'

data/imified.gemspec

@@ -0,0 +1,28 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "imified/version"
+
+Gem::Specification.new do |s|
+  s.name        = "imified"
+  s.version     = Imified::VERSION
+  s.authors     = ["Joe Karayusuf"]
+  s.email       = ["jkarayusuf@gmail.com"]
+  s.homepage    = "https://github.com/karayusuf/imified"
+  s.summary     = %q{ API for sending Text/Instant Messages using IMified.com }
+  s.description = %q{ The IMified API exposes methods for sending messages,
+                      fetching user details, and updating status. To get started,
+                      you'll need to sign up for a free developer account at:
+                      http://imified.com/account/signup }
+
+  s.rubyforge_project = "imified"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.add_dependency 'activesupport', '2.3.11'
+
+  s.add_development_dependency 'rspec'
+
+end

data/lib/imified/request.rb

@@ -0,0 +1,39 @@
+# request.rb
+#
+# Net::HTTP::Post wrapper
+#
+# All API calls for requesting user details and sending messages
+# should be sent via HTTP POST to the following URL:
+# https://www.imified.com/api/bot/.
+#
+# Authentication is managed using Basic HTTP authentication.
+# Every request must include the Authorization HTTP header
+# with your IMified username and password.
+#
+class Imified::Request < Net::HTTP::Post
+  URL = URI.parse(Imified::URL)
+
+  # Construct a Net::HTTP::Post object.
+  # Prepare basic authentication using the username and
+  # password specified in the configuration.
+  #
+  # == Usage
+  #   Imified::Request.new
+  #
+  # @return[Net::HTTP::Post]
+  def initialize(api_method = 'getallusers')
+    Imified.validate_configuration!
+    super(URL.path)
+
+    self.basic_auth Imified.email_address, Imified.password
+    self.add_field 'apimethod', api_method
+    self.add_field 'botkey', Imified.botkey
+  end
+
+  # Submit the request to Imified.
+  def submit
+    http = Net::HTTP.new(URL.host, URL.port)
+    http.use_ssl = true
+    http.start { |send| send.request(self) }.body
+  end
+end

data/lib/imified/version.rb

@@ -0,0 +1,3 @@
+module Imified
+  VERSION = "0.0.2"
+end

data/lib/imified.rb

@@ -0,0 +1,120 @@
+require 'active_support'
+require 'net/https'
+require 'uri'
+
+module Imified
+  autoload :Request, 'imified/request'
+  autoload :User,    'imified/user'
+  autoload :Version, 'imified/version'
+
+  # Imified API url
+  URL = 'https://www.imified.com/api/bot/'
+
+  # User's unique botkey
+  mattr_accessor :botkey
+
+  # User's Imified account name
+  mattr_accessor :email_address
+
+  # User's Imified account password
+  mattr_accessor :password
+
+  # Default way to setup Imified.
+  # To be used during initialization.
+  #
+  # == Example:
+  #
+  #   Imified.setup do |config|
+  #     config.botkey = 'the bot you would like to use'
+  #     config.email_address = 'your imified email address'
+  #     config.password = 'your imified password'
+  #   end
+  #
+  def self.setup
+    yield self
+  end
+
+  # Validate that the Imified module has been configured
+  # with the users account information. Raise an error
+  # containing instructions to properly configure the
+  # module.
+  #
+  def Imified.validate_configuration!
+    if Imified.botkey.nil? ||
+       Imified.email_address.nil? ||
+       Imified.password.nil?
+      raise ArgumentError, "Invalid Configuration.
+        In order to use the Imified API, you must
+        first run the setup and provide your account
+        information.
+
+        This can be done using the following syntax:
+
+        Imified.setup do |config|
+          config.botkey = 'your botkey'
+          config.email_address = 'your email address'
+          config.password = 'your password'
+        end"
+    end
+  end
+
+  # Fetch a list of all of the bots known users.
+  # Includes a total count of the users.
+  #
+  # == Example
+  #
+  #   Imified.get_all_users
+  #
+  # == Return
+  #
+  #   Successful Response:
+  #     <rsp stat="ok">
+  #       <users count="2">
+  #         <user>
+  #           <status>Online</status>
+  #           <extendedstatus>Working on an IMified bot</extendedstatus>
+  #           <userkey>123456789</userkey>
+  #           <screenname>user_screenname</screenname> *deprecated
+  #           <user>user_screenname</user>
+  #           <network>AIM</network>
+  #           <created>2007-09-26 13:30:25</created>
+  #           <lastonline>2007-09-28 15:20:15</lastonline>
+  #           <lastcall>2007-09-28 15:20:15</lastcall>
+  #         </user>
+  #         <user>
+  #           <status>Offline</status>
+  #           <extendedstatus></extendedstatus>
+  #           <userkey>123456789</userkey>
+  #           <screenname>user_screenname</screenname> *deprecated
+  #           <user>user_screenname</user>
+  #           <network>Jabber</network>
+  #           <created>2007-09-26 13:30:25</created>
+  #           <lastonline>2007-09-28 15:20:15</lastonline>
+  #           <lastcall>2007-09-28 15:20:15</lastcall>
+  #         </user>
+  #       </users>
+  #     </rsp>
+  #
+  #   Failed Response:
+  #     <rsp stat="fail">
+  #       <err msg="error message text"/>
+  #     </rsp>
+  #
+  def Imified.get_all_users
+    request = Imified::Request.new
+    response = request.submit
+  end
+
+  def Imified.get_user(userkey)
+    request = Imified::Request.new('getuser')
+    request.add_field 'userkey', userkey
+    response = request.submit
+  end
+
+  def Imified.send_message(msg, options)
+    request = Imified::Request.new('send')
+    request.add_field 'userkey', options[:to]
+    request.add_field 'msg', msg
+    response = request.submit
+  end
+end

data/spec/imified_spec.rb

@@ -0,0 +1,144 @@
+require 'spec_helper'
+
+describe Imified do
+
+  it "should know the Imified URL" do
+    Imified::URL.should eql('https://www.imified.com/api/bot/')
+  end
+
+  context "when the user is specifying their accout information" do
+    before(:each) do
+      Imified.setup do |config|
+        config.botkey = 'my botkey'
+        config.email_address = 'my email address'
+        config.password = 'my super secret password'
+      end
+    end
+
+    it "should set the botkey to the specified value" do
+      Imified.botkey.should eql('my botkey')
+    end
+
+    it "should set the email address to the specified value" do
+      Imified.email_address.should eql('my email address')
+    end
+
+    it "should set the password to the specified value" do
+      Imified.password.should eql('my super secret password')
+    end
+
+  end
+
+  context "when sending a message to a user" do
+    let(:mock_request) { double('imified_request').as_null_object }
+    let(:mock_response) { double('imfiied_response').as_null_object }
+
+    before(:each) do
+      Imified::Request.stub(:new).and_return(mock_request)
+      mock_request.stub(:submit).and_return(mock_response)
+    end
+
+    it "should prepare a new request to 'send'" do
+      Imified::Request.
+        should_receive(:new).
+        with('send').
+        and_return(mock_request)
+      Imified.send_message('Rspec message', :to => 'userkey')
+    end
+
+    it "should add the specified message to the request" do
+      mock_request.
+        should_receive(:add_field).
+        with('msg', 'a message to send')
+      Imified.send_message('a message to send', :to => 'a user')
+    end
+
+    it "should add the specified userkey to the request" do
+      mock_request.
+        should_receive(:add_field).
+        with('userkey', 'someones userkey')
+      Imified.send_message('A Message', :to => 'someones userkey')
+    end
+
+    it "should submit the request" do
+      mock_request.should_receive(:submit)
+      Imified.send_message('A Message', :to => 'someones userkey')
+    end
+  end
+
+  context "when fetching a list of the bot's users" do
+    let(:mock_request) { double('imified_request').as_null_object }
+    let(:mock_response) { double('imfiied_response').as_null_object }
+
+    before(:each) do
+      Imified::Request.stub(:new).and_return(mock_request)
+      mock_request.stub(:submit).and_return(mock_response)
+    end
+
+    it "should prepare a new request" do
+      Imified::Request.should_receive(:new)
+      Imified.get_all_users
+    end
+
+    it "should submit the request" do
+      mock_request.should_receive(:submit)
+      Imified.get_all_users
+    end
+  end
+
+  context "when fetching details for a specified user" do
+    let(:mock_request) { double('imified_request').as_null_object }
+    let(:mock_response) { double('imified_response').as_null_object }
+
+    before(:each) do
+      Imified::Request.stub(:new).and_return(mock_request)
+      mock_request.stub(:submit).and_return(mock_response)
+    end
+
+    it "should prepare a new request to 'getuser'" do
+      Imified::Request.
+        should_receive(:new).
+        with('getuser')
+      Imified.get_user('someones userkey')
+    end
+
+    it "should add the specified userkey to the request" do
+      mock_request.
+        should_receive(:add_field).
+        with('userkey', 'someones userkey')
+      Imified.get_user('someones userkey')
+    end
+
+    it "should submit the request" do
+      mock_request.should_receive(:submit)
+      Imified.get_user('userkey')
+    end
+  end
+
+  context "when validating the configuration" do
+    it "should not raise an error if all of the values are set" do
+      Imified.setup do |config|
+        config.botkey = 'botkey'
+        config.email_address = 'test email'
+        config.password = 'super secret'
+      end
+
+      expect { Imified.validate_configuration! }.to_not raise_error(ArgumentError)
+    end
+
+    it "should raise an error if the botkey has not been specified" do
+      Imified.stub(:botkey).and_return(nil)
+      expect { Imified.validate_configuration! }.to raise_error(ArgumentError)
+    end
+
+    it "should raise an error if the email address has not been specified" do
+      Imified.stub(:email_address).and_return(nil)
+      expect { Imified.validate_configuration! }.to raise_error(ArgumentError)
+    end
+
+    it "should raise an error if the password has not been specified" do
+      Imified.stub(:password).and_return(nil)
+      expect { Imified.validate_configuration! }.to raise_error(ArgumentError)
+    end
+  end
+end

data/spec/request_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+describe Imified::Request do
+
+  it "should validate the user's imified configuration" do
+    Imified.
+      should_receive(:validate_configuration!).
+      and_return(nil)
+    Imified::Request.new
+  end
+
+  it "should use the imified url" do
+    Imified::Request::URL.should == URI.parse('https://www.imified.com/api/bot/')
+  end
+
+  it "should use basic authentication" do
+    Imified::Request.any_instance.
+      should_receive(:basic_auth).
+      with('rspec_email_address', 'rspec_password')
+    Imified::Request.new
+  end
+
+  it "should default to the 'getallusers' api method" do
+    request = Imified::Request.new
+    request.get_fields('apimethod').should eql(['getallusers'])
+  end
+
+  it "should allow the 'getuser' method to be used" do
+    request = Imified::Request.new('getuser')
+    request.get_fields('apimethod').should eql(['getuser'])
+  end
+
+  context "when being submitted with valid account information" do
+    let(:mock_net_http) { double('net_http').as_null_object }
+    let(:mock_net_http_response) { double('net_http_response').as_null_object }
+
+    before(:each) { Net::HTTP.stub!(:new).and_return(mock_net_http) }
+
+    it "should build an HTTP request" do
+      Net::HTTP.should_receive(:new).
+        with(Imified::Request::URL.host, Imified::Request::URL.port)
+      Imified::Request.new.submit
+    end
+
+    it "should use ssl" do
+      mock_net_http.should_receive(:use_ssl=).with(true)
+      Imified::Request.new.submit
+    end
+
+    it "should send the request" do
+      mock_net_http.should_receive(:start).and_return(mock_net_http_response)
+      mock_net_http_response.should_receive(:body)
+      Imified::Request.new.submit
+    end
+  end
+
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,15 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'imified'
+
+RSpec.configure do |config|
+  config.mock_framework = :rspec
+
+  # Default configuration for tests.
+  config.before(:each) do
+    Imified.email_address = 'rspec_email_address'
+    Imified.password = 'rspec_password'
+    Imified.botkey = 'rspec_botkey'
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: imified
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Joe Karayusuf
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-08-07 00:00:00.000000000 -04:00
+default_executable: 
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: &70288113780800 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - =
+      - !ruby/object:Gem::Version
+        version: 2.3.11
+  type: :runtime
+  prerelease: false
+  version_requirements: *70288113780800
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70288113780260 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70288113780260
+description: ! " The IMified API exposes methods for sending messages,\n                      fetching
+  user details, and updating status. To get started,\n                      you'll
+  need to sign up for a free developer account at:\n                      http://imified.com/account/signup "
+email:
+- jkarayusuf@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- README.rdoc
+- Rakefile
+- imified.gemspec
+- lib/imified.rb
+- lib/imified/request.rb
+- lib/imified/version.rb
+- spec/imified_spec.rb
+- spec/request_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: https://github.com/karayusuf/imified
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: imified
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: API for sending Text/Instant Messages using IMified.com
+test_files:
+- spec/imified_spec.rb
+- spec/request_spec.rb
+- spec/spec_helper.rb