harleytt-gvoice-ruby

= gvoice-ruby

== Introduction

gvoice-ruby is a library for interacting with Google's Voice service (previously GrandCentral) using ruby. As Google does not yet publish an official API for Google Voice gvoice-ruby uses the ruby libcurl library (Curb) to interact with the web service itself by using the HTTP verbs POST and GET to send and retrieve information to the Google Voice service.

gvoice-ruby is currently a very preliminary project with limited functionality basically confined to returning arrays of voicemail or sms objects and sending sms messages, or connecting calls. It cannot cancel calls already in progress. It currently works under ruby 1.8.7-p302 and 1.9.2-p0 on my computer running Mac OS X 10.6 (Snow Leopard). It is not guaranteed to work anywhere else and has very few tests.

However, you should be able to run bundle install after running git clone as outlined below and it should function.

== Prerequisites

1.) Ruby 1.8.7 or 1.9.2

2.) Bundler 1.0 (gem install bundler)

== Installing

Install the gem:

$ gem install gvoice-ruby

or

Clone the git repository:

$ git clone git://github.com/kgautreaux/gvoice-ruby.git

then:

$ cd gvoice-ruby

and:

$ bundle install

This should install all the required gems provided you have the right permissions.

To run the test suite:

$ bundle exec rake

== Examples

Please see the bin/ directory for examples of using the library to accomplish some tasks. You must run bundle exec 'command' in order for the program to work, i.e.

$ cd gvoice-ruby
$ bundle exec bin/gv-notifier

== Known Issues

1.) You have to run 'bundle exec bin/"command"' and it must be run in the context of the gvoice-ruby directory.

2.) It does some wicked monkeypatching to run on both 1.9.2 and 1.8.7 mostly due to the new Date class in Ruby 1.9.2.

3.) It is technically a library but it doesn't document any sort of API thus far.

== BUGS

1.) It has few tests.

2.) If the Google Voice service changes in any way it will break.

3.) If the libraries used change it will break.

4.) It is somewhat tightly coupled to the private post and fetch_page methods (sms and voicemail arrays depend upon these methods).

5.) It is not RESTful in any way.

6.) It cannot yet cancel calls very well, but it can initiate them.

7.) It is my first attempt at writing a library and is not idiomatic ruby.

8.) It requires rubygems but doesn't set RUBYOPT environment variable.

9.) It requires the file compatibility.rb which monkeypatches the Array and Symbol classes on Ruby < 1.9 to enable sorting.

10.) You cannot change any of the Google Voice settings using this library.

11.) The library loads a specific YAML file that must be in place for anything to work as the script has no logical defaults.

12.) Minimal to no error handling present. Fail silent...Fail deep.

13.) The library doesn't post the id of sms messages it sends so they don't get associated with any conversation in Google Voice.

14.) On Ruby 1.9 and above the library monkeypatches it's own call method to reformat dates.

== Thanks

Thanks to Chad Smith for posting the URL for accessing the Google Voice service as listed on http://posttopic.com/topic/google-voice-add-on-development#post-27