pingfm 1.0.0

data/.gitignore

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

data/History.txt

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

data/Manifest.txt

@@ -0,0 +1,25 @@
+.gitignore
+History.txt
+Manifest.txt
+README
+Rakefile
+bin/pingfm
+lib/pingfm.rb
+lib/pingfm/client.rb
+lib/pingfm/keyloader.rb
+spec/keyloader_spec.rb
+spec/pingfm_spec.rb
+spec/spec_helper.rb
+tasks/ann.rake
+tasks/bones.rake
+tasks/gem.rake
+tasks/git.rake
+tasks/manifest.rake
+tasks/notes.rake
+tasks/post_load.rake
+tasks/rdoc.rake
+tasks/rubyforge.rake
+tasks/setup.rb
+tasks/spec.rake
+tasks/svn.rake
+tasks/test.rake

data/README

@@ -0,0 +1,101 @@
+Ping.fm Ruby Client/Library
+
+== Authors
+
+* Krunoslav Husak (http://h00s.net)
+* Dale Campbell (http://corrupt.save-state.net)
+* Kevin Williams (http://almostserio.us)
+
+== CODE:
+
+http://pingfm.rubyforge.org/
+
+== DESCRIPTION:
+
+Ping.fm (http://ping.fm) is a simple service that makes updating your social networks a snap, and this it's Ruby library.
+
+== FEATURES/PROBLEMS:
+
+* Installing the gem creates a 'pingfm' shell script to post from the shell.
+* Keys are stored in a YAML file in your home directory (under Linux/OSX).
+
+== SYNOPSIS:
+
+Shell usage:
+
+  $ pingfm This message will post to my default services.
+
+Everything after the 'pingfm' command is what will be posted to the service.  You
+may also include the message within quotes (ex. using the client within a shell script).
+
+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 keys here:
+
+* User API Key - http://ping.fm/key/
+* Application API Key - http://ping.fm/developers/
+
+Library usage:
+
+  # Require the library and initialize it.
+  require 'pingfm'
+  pingfm = Pingfm::Client.new('api_key', 'user_app_key')
+
+  # Ensure proper API and User App keys.
+  pingfm.validate['status']
+  # => 'OK' if success, otherwise 'FAIL'
+
+  # Grab latest 5 posts.
+  pingfm.latest(5)  # => {'messages' => [...]}
+
+  # Posting to all services.
+  pingfm.post('The Dark Knight was amazing.')
+  # => {'status' => 'OK'} if success, otherwise 'FAIL'
+
+  # Post using custom user trigger; must be defined on the Ping.fm site.
+  pingfm.tpost('The message here.', '#something_custom', 'Optional Title')
+  # => {'status' => 'OK'} if success, otherwise 'FAIL'
+
+
+Check the source comments for more details.
+
+== REQUIREMENTS:
+
+Ruby!
+
+== INSTALL:
+
+  # From Rubyforge...
+  $ sudo gem install pingfm
+
+*OR*
+
+  # From Github...
+  $ sudo gem sources -a http://gems.github.com (only need to do this once)
+  $ sudo gem install oshuma-pingfm
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2008 Krunoslav Husak, Dale Campbell, 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,31 @@
+# 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.
+
+load 'tasks/setup.rb'
+
+ensure_in_path 'lib'
+require 'pingfm'
+
+task :default => 'spec:run'
+
+PROJ.name = 'pingfm'
+PROJ.authors = ['Krunoslav Husak', 'Dale Campbell', 'Kevin Williams']
+PROJ.email = ['dale@save-state.net', 'kevwil@gmail.com']
+PROJ.url = 'http://pingfm.rubyforge.org/'
+PROJ.version = ENV['VERSION'] || Pingfm.version
+PROJ.rubyforge.name = 'pingfm'
+PROJ.readme_file = 'README'
+
+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/pingfm

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+
+# TODO: Move this into a YAML config?
+API_KEY = '5fcb8b7041d5c32c7e1e60dc076989ba'
+
+require File.expand_path(
+    File.join(File.dirname(__FILE__), '..', 'lib', 'pingfm'))
+
+keyloader = ::Pingfm::Keyloader.new
+unless keyloader.has_keys?
+  keyloader.api_key = API_KEY
+  print 'Enter your Ping.fm User API key (http://ping.fm/key/): '
+  keyloader.app_key = STDIN.gets.chomp
+  keyloader.save
+end
+
+# post message from ARGV
+
+pingfm = ::Pingfm::Client.new(keyloader.api_key, keyloader.app_key)
+
+s = pingfm.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 = pingfm.post(status)
+
+  if s['status'] == 'FAIL'
+    puts s['message']
+  else
+    puts 'Message sent.'
+  end
+else
+  puts s['message']
+end
+
+# EOF

data/lib/pingfm.rb

@@ -0,0 +1,56 @@
+# $Id$
+
+# Equivalent to a header guard in C/C++
+# Used to prevent the class/module from being loaded more than once
+unless defined? Pingfm
+
+module Pingfm
+
+  # :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)
+  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)
+  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 Pingfm
+
+Pingfm.require_all_libs_relative_to __FILE__
+
+end  # unless defined?
+
+# EOF

data/lib/pingfm/client.rb

@@ -0,0 +1,219 @@
+# Ping.fm Ruby Client
+require 'net/http'
+require 'rexml/document'
+
+module Pingfm
+
+  # MUST NOT end with a trailing slash, as this string is interpolated like this:
+  # "#{API_URL}/user.services"
+  API_URL = 'http://api.ping.fm/v1'
+
+  class Client
+
+  	def initialize(api_key, user_app_key)
+  		@api_key = api_key
+  		@user_app_key = user_app_key
+  	end
+
+  	# Validates API key and user APP 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
+
+    # Return a complete list of supported services
+    # if successful returns:
+    #   {'status' => 'OK', 'services' => [{'id' => 'serviceid', 'name' => 'servicename', 'trigger' => 'servicetrigger', 'url' => 'serviceurl', 'icon' => 'serviceicon'}, ...]}
+    # if unsuccessful returns:
+    #   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+    def system_services
+      response = get_response('system.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'],
+                                     'trigger' => service.elements['trigger'].text,
+                                     'url'     => service.elements['url'].text,
+                                     'icon'    => service.elements['icon'].text})
+        end
+        return services
+      else
+        return status_fail(response)
+      end
+    end
+
+  	# Returns a list of services the user has set up through Ping.fm
+  	# if successful returns:
+    #   {'status' => 'OK', 'services' => [{'id' => 'serviceid', 'name' => 'servicename', 'trigger' => 'servicetrigger', 'url' => 'serviceurl', 'icon' => 'serviceicon', 'methods' => 'status,blog'}, ...]}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def 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'],
+  											'trigger' => service.elements['trigger'].text,
+  											'url' => service.elements['url'].text,
+  											'icon' => service.elements['icon'].text,
+  											'methods' => service.elements['methods'].text})
+  			end
+  			return services
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Returns a user's custom triggers
+  	# if successful returns:
+  	#   {'status' => 'OK', 'triggers' => [{'id' => 'triggerid', 'method' => 'triggermethod', 'services' => [{'id' => 'serviceid', 'name' => 'servicename'}, ...]}, ...]}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def triggers
+  	  response = get_response('user.triggers')
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			triggers = status_ok
+  			triggers['triggers'] = []
+  			response.elements.each('rsp/triggers/trigger') do |trigger|
+  				triggers['triggers'].push({'id' => trigger.attributes['id'], 'method' => trigger.attributes['method'], 'services' => []})
+
+  				trigger.elements.each('services/service') do |service|
+  					triggers['triggers'].last['services'].push({'id' => service.attributes['id'], 'name' => service.attributes['name']})
+  				end
+  			end
+  			return triggers
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Returns the last <tt>limit</tt> messages a user has posted through Ping.fm
+  	# Optional arguments:
+  	# limit = limit the results returned, default is 25
+  	# order = which direction to order the returned results by date, default is DESC (descending)
+  	# if successful returns:
+  	#   {'status' => 'OK', 'messages' => [{'id' => 'messageid', 'method' => 'messsagemethod', 'rfc' => 'date', 'unix' => 'date', 'title' => 'messagetitle', 'body' => 'messagebody', 'services' => [{'id' => 'serviceid', 'name' => 'servicename'}, ...]}, ...]}
+  	# if unsuccessful returns:
+  	#   {'status' => 'FAIL', 'message' => 'message what went wrong'}
+  	def latest(limit = 25, order = 'DESC')
+  	  response = get_response('user.latest', 'limit' => limit, 'order' => order)
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			latest = status_ok
+  			latest['messages'] = []
+  			response.elements.each('rsp/messages/message') do |message|
+  				latest['messages'].push({})
+  				latest['messages'].last['id'] = message.attributes['id']
+  				latest['messages'].last['method'] = message.attributes['method']
+  				latest['messages'].last['rfc'] = message.elements['date'].attributes['rfc']
+  				latest['messages'].last['unix'] = message.elements['date'].attributes['unix']
+
+  				if message.elements['*/title'] != nil
+  					latest['messages'].last['title'] = message.elements['*/title'].text
+  				else
+  					latest['messages'].last['title'] = ''
+  				end
+          if message.elements['location'] != nil
+            latest['messages'].last['location'] = message.elements['location'].text
+          else
+            latest['messages'].last['location'] = ''
+          end
+  				latest['messages'].last['body'] = message.elements['*/body'].text
+  				latest['messages'].last['services'] = []
+  				message.elements.each('services/service') do |service|
+  					latest['messages'].last['services'].push({'id' => service.attributes['id'], 'name' => service.attributes['name']})
+  				end
+  			end
+  			return latest
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Posts a message to the user's Ping.fm services
+  	# Arguments:
+  	# body = message body
+  	# Optional arguments:
+  	# title = title of the posted message, title is required for 'blog' post method
+  	# post_method = posting method; either 'default', 'blog', 'microblog' or 'status.'
+  	# service = a single service to post to
+  	# 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 = '', post_method = 'default', service = '', debug = 0)
+  	  response = get_response('user.post',
+  	                          'body' => body, 'title' => title,
+  	                          'post_method' => post_method, 'service' => service,
+  	                          'debug' => debug)
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			return status_ok
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	# Posts a message to the user's Ping.fm services using one of their custom triggers
+  	# Arguments:
+  	# body = message body
+  	# trigger = custom trigger the user has defined from the Ping.fm website
+  	# Optional arguments:
+  	# title = title of the posted message, title is required for 'blog' post method
+  	# 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 tpost(body, trigger, title = '', debug = 0)
+  	  response = get_response('user.tpost',
+  	                          'body' => body, 'title' => title,
+  	                          'trigger' => trigger, 'debug' => debug)
+  		if response.elements['rsp'].attributes['status'] == 'OK'
+  			return status_ok
+  		else
+  			return status_fail(response)
+  		end
+  	end
+
+  	private
+
+    # Gets a particular ping.fm 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 app key are merged with this on every call.
+    def get_response(type, parameters = {})
+      parameters.merge!('api_key' => @api_key, 'user_app_key' => @user_app_key)
+  		REXML::Document.new(http_request("#{API_URL}/#{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