hellotxt 1.0.0

data/.gitignore

@@ -0,0 +1,2 @@
+pkg/
+coverage/

data/History.txt

@@ -0,0 +1,4 @@
+== 1.0.0 / 2008-12-26
+
+* first gem release
+  * woohoo!

data/Manifest.txt

@@ -0,0 +1,14 @@
+.gitignore
+History.txt
+Manifest.txt
+README
+Rakefile
+bin/hellotxt
+lib/hellotxt.rb
+lib/hellotxt/client.rb
+lib/hellotxt/keyloader.rb
+spec/client_spec.rb
+spec/hellotxt_spec.rb
+spec/keyloader_spec.rb
+spec/spec_helper.rb
+spec/spec_responses.rb

data/README

@@ -0,0 +1,90 @@
+HelloTxt Ruby Client/Library
+
+== Authors
+
+* Kevin Williams (http://kevwil.github.com/)
+
+== CODE:
+
+http://github.com/kevwil/hellotxt/
+
+== DESCRIPTION:
+
+HelloTxt (http://hellotxt.com) is a simple service that makes updating your social networks a snap, and this is it's Ruby library.
+
+== FEATURES/PROBLEMS:
+
+* Installing the gem creates a 'hellotxt' shell script to post from the shell.
+* Keys are stored in a YAML file in your home directory (%USERPROFILE% in Windows).
+
+== SYNOPSIS:
+
+Shell usage:
+
+  $ hellotxt "This message will post to my default services."
+
+Everything after the 'hellotxt' command is what will be posted to the service. You could do the same thing without the quotes, and it would still work:
+
+  $ hellotxt updating from the command line is very handy for developers.
+
+If your keys have not been stored, it will ask for them.  These keys will be saved
+in a YAML file in your home directory and you won't be asked for them again.
+
+You can obtain your API key here: http://hellotxt.com/api/doc
+
+Library usage:
+
+  # Require the library and initialize it.
+  require 'hellotxt'
+  hellotxt = ::HelloTxt::Client.new('api_key', 'user_key')
+
+  # Ensure proper API and USER keys.
+  hellotxt.validate['status']
+  # => 'OK' if success, otherwise 'FAIL'
+
+  # Posting to all services.
+  hellotxt.post('The Dark Knight was amazing.')
+  # => {'status' => 'OK'} if success, otherwise 'FAIL'
+
+
+Check the source comments for more details.
+
+== REQUIREMENTS:
+
+Ruby!
+
+== INSTALL:
+
+  # From Rubyforge...
+  $ sudo gem install hellotxt
+
+*OR*
+
+  # From Github...
+  $ sudo gem sources -a http://gems.github.com (only need to do this once)
+  $ sudo gem install kevwil-hellotxt
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008-2009 Kevin Williams
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,38 @@
+# Look in the tasks/setup.rb file for the various options that can be
+# configured in this Rakefile. The .rake files in the tasks directory
+# are where the options are used.
+
+begin
+  require 'bones'
+  Bones.setup
+rescue LoadError
+  load 'tasks/setup.rb'
+end
+
+ensure_in_path 'lib'
+require 'hellotxt'
+
+task :default => 'spec:run'
+
+PROJ.name = 'hellotxt'
+PROJ.authors = ['Kevin Williams']
+PROJ.email = ['kevwil@gmail.com']
+PROJ.url = 'http://kevwil.github.com/hellotxt'
+PROJ.version = ENV['VERSION'] || HelloTxt::VERSION
+PROJ.rubyforge.name = 'hellotxt'
+PROJ.readme_file = 'README'
+
+PROJ.gem.need_tar = false
+
+PROJ.spec.opts << '--color'
+
+namespace :gem do
+  desc 'create a gemspec file to support github gems'
+  task :gemspec => 'gem:prereqs' do
+    File.open("#{PROJ.name}.gemspec", 'w+') do |f|
+      f.write PROJ.gem._spec.to_ruby
+    end
+  end
+end
+
+# EOF

data/bin/hellotxt

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+
+API_KEY = '1wno0aw653hyry87'
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), %w[.. lib hellotxt]))
+
+keyloader = ::HelloTxt::Keyloader.new
+unless keyloader.has_keys?
+  keyloader.api_key = API_KEY
+  print 'Enter your HelloTxt User API key (http://hellotxt.com/api/doc): '
+  keyloader.user_key = STDIN.gets.chomp
+  keyloader.save
+end
+
+# post message from ARGV
+
+hellotxt = ::HelloTxt::Client.new(keyloader.api_key, keyloader.user_key)
+
+s = hellotxt.validate
+if s['status'] == 'OK'
+  status = ARGV.join(' ')
+
+  # Might be a good idea to throw an exception here, instead of just bailing.
+  if status.nil? || status.empty?
+    puts 'Must provide a message to send.'
+    exit
+  end
+
+  post_result = hellotxt.post(status)
+
+  if post_result['status'] == 'FAIL'
+    puts post_result['message']
+  else
+    puts 'Message sent.'
+  end
+else
+  puts s['message']
+end
+
+# EOF

data/lib/hellotxt.rb

@@ -0,0 +1,54 @@
+$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__))
+
+module HelloTxt
+
+  # :stopdoc:
+  VERSION = '1.0.0'
+  LIBPATH = ::File.expand_path(::File.dirname(__FILE__)) + ::File::SEPARATOR
+  PATH = ::File.dirname(LIBPATH) + ::File::SEPARATOR
+  # :startdoc:
+
+  # Returns the version string for the library.
+  #
+  def self.version
+    VERSION
+  end
+
+  # Returns the library path for the module. If any arguments are given,
+  # they will be joined to the end of the libray path using
+  # <tt>File.join</tt>.
+  #
+  def self.libpath( *args )
+    args.empty? ? LIBPATH : ::File.join(LIBPATH, args.flatten)
+  end
+
+  # Returns the lpath for the module. If any arguments are given,
+  # they will be joined to the end of the path using
+  # <tt>File.join</tt>.
+  #
+  def self.path( *args )
+    args.empty? ? PATH : ::File.join(PATH, args.flatten)
+  end
+
+  # Utility method used to rquire all files ending in .rb that lie in the
+  # directory below this file that has the same name as the filename passed
+  # in. Optionally, a specific _directory_ name can be passed in such that
+  # the _filename_ does not have to be equivalent to the directory.
+  #
+  def self.require_all_libs_relative_to( fname, dir = nil )
+    dir ||= ::File.basename(fname, '.*')
+    search_me = ::File.expand_path(
+        ::File.join(::File.dirname(fname), dir, '*', '*.rb'))
+
+    Dir.glob(search_me).sort.each {|rb| require rb}
+  end
+
+end  # module Hellotxt
+
+#HelloTxt.require_all_libs_relative_to(__FILE__)
+module HelloTxt
+  autoload :Keyloader, 'hellotxt/keyloader'
+  autoload :Client, 'hellotxt/client'
+end
+
+# EOF

data/lib/hellotxt/client.rb

@@ -0,0 +1,109 @@
+# HelloTxt Ruby Client
+require 'net/http'
+require 'rexml/document'
+
+module HelloTxt
+
+  # MUST NOT end with a trailing slash, as this string is interpolated like this:
+  # "#{API_URL}/user.services"
+  API_URL = 'http://hellotxt.com/api/v1'
+
+  class Client
+
+  	def initialize(api_key, user_key)
+  		@api_key = api_key
+  		@user_key = user_key
+  	end
+
+  	# Validates API key and USER key
+  	# if successful returns:
+  	#   {'status' => 'OK'}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def validate
+  	  response = get_response('user.validate')
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			return status_ok
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Returns a list of services the user has set up through HelloTxt
+  	# if successful returns:
+    #   {'status' => 'OK', 'services' => [{'id' => 'serviceid', 'name' => 'servicename', 'code' => 'servicecode', 'inhome' => 'checked', 'friend' => 'checked', 'collegue' => 'checked'}, ...]}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def user_services
+  	  response = get_response('user.services')
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			services = status_ok()
+  			services['services'] = []
+  			response.elements.each('rsp/services/service') do |service|
+  				services['services'].push({'id' => service.attributes['id'],
+  											'name' => service.attributes['name'],
+  											'code' => service.elements['code'].text,
+  											'inhome' => service.elements['inhome'].text,
+  											'friend' => service.elements['friend'].text,
+  											'collegue' => service.elements['collegue'].text})
+  			end
+  			return services
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Posts a message to the user's social services
+  	# Arguments:
+  	# body = message body
+  	# Optional arguments:
+  	# title = title of the posted message, only used if the service supports it
+  	# group = service group type; either 'inhome', 'friend', 'collegue'
+  	# image = raw bytes of an image to post
+  	# debug = set debug to 1 to avoid posting test data
+  	# if successful returns:
+  	#   {'status' => 'OK'}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def post(body, title = '', group = 'inhome', image = '', debug = 0)
+  	  response = get_response('user.post',
+  	                          'body' => body, 'title' => title,
+  	                          'group' => group, 'image' => image,
+  	                          'debug' => debug)
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			return status_ok
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	private
+
+    # Gets a particular hellotxt response.
+    # <tt>type</tt>: The service type (ex. 'user.services'). Gets appended to <tt>API_URL</tt>.
+    # <tt>parameters</tt>: Optional (depending on the <tt>type</tt>) parameters to be passed along
+    # with the request.  The API key and USER key are merged with this on every call.
+    def get_response(type, parameters = {})
+      parameters.merge!('api_key' => @api_key, 'user_key' => @user_key)
+  		REXML::Document.new(http_request("#{API_URL}/method/#{type}", parameters))
+    end
+
+    # This makes the actual HTTP request.
+  	def http_request(url, parameters)
+  		response = Net::HTTP.post_form(URI.parse(url), parameters)
+  		return response.body
+  	end
+
+    # Successful response.
+  	def status_ok
+  		return {'status' => 'OK'}
+  	end
+
+    # Failed response.
+  	def status_fail(response)
+  		return {'status' => 'FAIL', 'message' => response.elements['rsp/message'].text}
+  	end
+
+  end
+
+end

data/lib/hellotxt/keyloader.rb

@@ -0,0 +1,58 @@
+require 'yaml'
+
+module HelloTxt
+
+  class KeyloadingError < Exception; end
+
+  # manages the YAML file containing the keys - encryption might be nice, might be overkill
+  class Keyloader
+
+    # Path to YAML file containing keys
+    attr_accessor :keyfile
+
+    # hellotxt uses this as the key for the registered application
+    attr_accessor :api_key
+
+    # hellotxt uses this as the key for the user
+    attr_accessor :user_key
+
+    KEY_PATH = (RUBY_PLATFORM =~ /mswin32/ ? ENV['USERPROFILE'] : ENV['HOME'])
+    KEY_FILE = '.hellotxt_keys.yml'
+
+    def initialize(keyfile = File.expand_path(File.join(KEY_PATH, KEY_FILE)))
+      @api_key = nil
+      @keyfile = keyfile
+
+      # load keys on init
+      load_keys!
+    end
+
+    # load a new set of keys
+    def load_keys(keyfile)
+      if File.exist?(keyfile) and File.readable?(keyfile)
+        data = YAML::load_file(keyfile)
+        @keyfile = keyfile if @keyfile.nil?
+        @api_key = data['api_key']
+        @user_key = data['user_key']
+      end
+    end
+
+    # load keys using the known keyfile
+    def load_keys!
+      load_keys(@keyfile)
+    end
+
+    # if keys have been loaded successfully
+    def has_keys?
+      return true unless @api_key.nil? or @user_key.nil?
+      return false
+    end
+
+    # save key data to keyfile
+    def save
+      File.open( @keyfile, 'w+' ) do |out|
+        YAML::dump( {'api_key' => @api_key, 'user_key' => @user_key}, out )
+      end
+    end
+  end
+end

data/spec/client_spec.rb

@@ -0,0 +1,133 @@
+
+require File.join(File.dirname(__FILE__), %w[spec_helper])
+
+describe HelloTxt::Client, "with expected results" do
+
+  before(:each) do
+    @client = HelloTxt::Client.new('a','b')
+    @params = {'api_key' => 'a', 'user_key' => 'b'}
+  end
+
+  it "should validate keys successfully" do
+    init_ok_response 'user.validate'
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.validate
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('OK')
+  end
+
+  it "should list the user's services properly" do
+    init_service_response
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.user_services
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('OK')
+    result['services'].should_not be_nil
+    result['services'].should_not be_empty
+    result['services'].length.should eql(5)
+    result['services'].first['name'].should eql('twitter')
+  end
+
+  it "should post a message to the service" do
+    init_ok_response 'user.post'
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+    @params.merge!('body' => 'foo', 'title' => '',
+    'group' => 'inhome', 'image' => '',
+    'debug' => 0)
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.post('foo')
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('OK')
+  end
+
+end
+
+describe HelloTxt::Client, "with error messages" do
+  before(:each) do
+    @client = HelloTxt::Client.new('a','b')
+    @params = {'api_key' => 'a', 'user_key' => 'b'}
+  end
+
+  it "should handle a failed validate cleanly" do
+    init_fail_response 'user.validate'
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.validate
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('FAIL')
+    result['message'].should_not be_nil
+  end
+
+  it "should handle a failed user's services cleanly" do
+    init_fail_response 'user.services'
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.user_services
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('FAIL')
+    result['message'].should_not be_nil
+  end
+
+  it "should handle a failed user post cleanly" do
+    init_fail_response 'user.post'
+
+    uri = URI.parse "#{HelloTxt::API_URL}/method/#{@service_type}"
+
+    # mock the http call
+    http_resp = mock('response')
+    http_resp.expects(:body).returns(@response)
+    @params.merge!({'group' => 'inhome', 'title' => '',
+                    'image' => '', 'body' => 'test message', 'debug' => 0})
+    Net::HTTP.expects(:post_form).with(uri, @params).returns(http_resp)
+
+    # call and verify
+    result = @client.post('test message')
+    result.should_not be_empty
+    result['status'].should_not be_nil
+    result['status'].should eql('FAIL')
+    result['message'].should_not be_nil
+  end
+
+end