README

== Randypot ==
  Randypot is a Ruby client for Kandypot (the sweetest karma service ever deployed)

  This is an introduction about how to use it. You can see specs/lib/randypot_spec.rb for more details.

== Randypot configuration ==

  Configuration can be set through a YAML with a content like this:
  
    kandypot_server:
      service_url: http://kandypot.com/api
      app_key: putyourappkeyhere
      app_token: andhereputthetoken

  Randypot will load it from these files if they are present (settings from each file overrides those loaded from the previous one):
    1.- /etc/randypot/configuration.yml,
    2.- ~/.randypot/configuration.yml
    3.- RAILS_ROOT/config/randypot.yml
    4.- randypot.yml

  Also we can pass to Randypot the location of the configuration file doing something like this:

    Randypot.configure '/my/special/place.yml'

  This will override any setting loaded from previous YAMLs.

  If we don't want to have it in a YAML we can also do the same with:

    Randypot.configure do |config|
      config.service_url = "http://kandypot.com/api"
      config.app_key     = "putyourappkeyhere"
      config.app_token   = "andhereputthetoken"
    end

  Again, this settings will be used spite of settings loaded from any YAML file.

== Randypot content creations ==
  Once the configuration is set we can make calls like this to the service (option one: with the class method):

    Randypot.creation(
      :content_type => 'photo',
      :content_source => 'ugc',
      :activity_at => Time.now,
      :member => 'wadus@example.com',
      :content => 'http://example.com/wadus.jpg')

  But we also can do the same this way:

    Randypot.creation.photo.ugc(
      :member => 'wadus@example.com',
      :content => 'http://example.com/wadus.jpg'
    )

  But also we can get an instance for a member (option two: with the instance method):

    randy = Randypot.new('randy@example.com')
  
  And do just the same with this even more fancy syntax:

    randy.creates.photo.ugc 'http://example.com/wadus.jpg'

== Randypot content reactions ==
  Again we got the two options. With the class method:

    Randypot.reaction.comment.photo.ugc(
      :member  => 'randy@example.com',
      :creator => 'wadus@example.com',
      :content => 'http://example.com/waduspage')
  
  Or with the instance method:

    randy = Randypot.new('randy@example.com')
    randy.reacts.comment.photo.ugc(
      :creator => 'wadus@example.com',
      :content => 'http://example.com/waduspage')

== Randypot relationships ==
  
  With the class method:

    Randypot.relationship.friend(
      :member  => 'randy@example.com',
      :member_b => 'wadus@example.com') 

  Or with the instance method:

    randy = Randypot.new('randy@example.com')
    randy.relationships.friend 'wadus@example.com'

== Randypot members ==

  To get a CSV list with the current Randypot members and their kandypot sizes you can call:

    ranking = Randypot.members

  You'll obtain an raw Randypot::Response instance and the CVS list will be accesible through its "body" method (ranking.body).

  Randypot'll store the results in local cache files to optimize its bandwith needs, avoiding data transfers if Kandypot confirms that no modification has been made since the last request.

  Randypot'll also parse the CVS response storing the result within the #parsed accessor of the response (Randypot.members.parsed).
  
  The parsed members is an array of Struct objects that responds to #hash, #candies, #updated_at and so on. To list each member with its candies we can do something like this:

    Randypot.members.parsed.each do |member|
      puts User.find_by_hash(member.hash).name + ': ' + member.candies
    end

== Randypot member ==

  To get the current data of a member in JSON format you can call the class method "member" with her or his email as argument. As with Randypot.members, you'll get an Randypot::Responce instance:

    json = Randypot.member("randy@example.com").body

  Randypot'll store the user's data in a local cache file to use it if Kandypot comfirms no modifications on it.

  Randypot'll parse the JSON data for us and it'll be accesible through the #hash, #candies, #updated_at:

    parsed = Randypot.member("email@example.com").parsed

    puts "Randy's hash: " + parsed.hash
    puts "Randy's candies: " + parsed.candies.to_s
    puts "Randy's last update: " + parsed.updated_at.format('long')

  But here the second option, the instance option, comes again. The cool way to do this is with an instance of Randypot:

    randy = Randypot.new("email@example.com")

  This instance has the #hash, #candies, #updated_at methods just the same as the object returned by #parsed method of the Randypot's member class method. So we can equally do with "randy" what we've done with "parsed": 

    puts "Randy's hash: " + randy.hash
    puts "Randy's candies: " + randy.candies.to_s
    puts "Randy's last update: " + randy.updated_at.format('long')