livefyre 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

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

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Mashable, Inc
+
+MIT License
+
+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/README.md

@@ -0,0 +1,147 @@
+# Livefyre
+
+Interface library for Livefyre's API. Currently a mishmash of the v2 and v3 APIs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'livefyre'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install livefyre
+
+## Documentation
+
+Full documentation is available [on GitHub](http://mashable.github.com/livefyre/frames.html).
+
+You can generate full documentation yourself from the source tree. Requires the yard-tomdoc plugin.
+
+    yard --plugin yard-tomdoc -o doc
+
+## Usage
+
+You can set a default configuration object for Livefyre, which will prevent you from having to pass a client to
+all your object proxies manually.
+
+    Livefyre.config = {
+      :network      => "foo.fyre.co",
+      :network_key  => "blorgons",
+      :site_id      => 1234,
+      :site_key     => "minerva",
+      :system_token => "your_long_lived_system_token",
+      :domain       => "zor.t123.livefyre.com"
+    }
+
+If you're using this gem from Rails, we recommend doing this from an initializer.
+
+Once that's set, you're ready to start talking to Livefyre.
+
+    domain = Livefyre::Domain.new
+    domain.set_pull_url "http://foo.bar/users/{id}/pull/"
+
+    user = Livefyre::User.new("some_user_id")
+    user.refresh # Invoke ping-to-pull
+
+## Using with Rails
+
+Integration with Rails is straightforward, but does require some setup.
+
+### Controller integration
+
+You need to add a route to your routes file to handle profile pull requests from Livefyre. That'll look something like:
+
+    get "/livefyre/:id/pull", :to => "users#pull"
+
+Of course, you need a matching controller action
+
+    def pull
+      # Checks the validity of the JWT that Livefyre sends with pull requests. Throws an exception if it's no good.
+      validate_livefyre_request!
+
+      user = User.find(params[:id])
+
+      # livefile_profile will attempt to generate valid Livefire profile dump from the passed user record by guessing at field names.
+      # You can pass overides in a hash as the second option, or you can always generate your own data structure.
+      render :json => livefire_profile(user, :image => user.profile_image_url).to_json
+    end
+
+Finally, you'll need to set up a pull URL. Since this is done via the API, you are expected to do it manually. From a Rails console is fine, though
+you may do it any other way you please, too. Livefyre will substitute the string "{id}" for the user ID it wants data for.
+
+    Livefyre::Domain.new.set_pull_url "http://your.domain.com/livefyre/{id}/pull"
+
+You may want to invoke user updates when you save the user record.
+
+    def update
+      # ... user record updates here!
+      Livefyre::User.new( user._id ).refresh
+    end
+
+Or you can have the gem do it automatically from the model:
+
+    class User < ActiveRecord::Base
+      # ...
+
+      livefyre_user :update_on => [:email, :display_name]
+    end
+
+You can even have the gem do your ping updated asynchronously with Resque
+
+    class User < ActiveRecord::Base
+      # ...
+
+      livefyre_user :update_on => [:email, :display_name], :defer => true
+    end
+
+This will enqueue a ping-to-pull job in the "livefyre" queue. Make sure you have a worker running that'll handle that queue!
+
+### View integration
+
+
+In the location that you want to use your comment form, include something like the following:
+
+    <%= livefyre_comments post.id, post.title, post_url(post), post.tags %>
+
+You'll also need to boot Livefyre with Javascript. In your application.js, you'll want to include the Livefyre loader in your manifest:
+
+    //=require livefyre.js
+
+And then somewhere in your application.js, you'll want to actually boot:
+
+    window.initLivefyre({
+      login: function() {
+          // Things to do when the user clicks the "sign in" link. You probably want to
+          // take your user through a login cycle in a popup window, which includes calling
+          // the livefyre_login(user_id, user_name) method.
+          window.location = "/login";
+        },
+      logout: function() {
+          // things to do when the user clicks the "sign out" link. You probably want to take
+          // your user through the logout cycle, including a call to livefyre_logout.
+          window.location = "/logout";
+        },
+      viewProfile: function(handlers, author) {
+          // Handler for when a user's name is clicked in a comment
+          window.location = "/" + author;
+        },
+      editProfile: function(handlers, author) {
+          // Handler for when a user wants to edit their profile from the Livefyre user dropdown.
+          window.location = "/" + author + "/edit";
+        }
+    });
+
+That's it!
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,10 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new('spec')
+rescue LoadError => e
+  # Pass
+end
+
+task :default => :spec

data/app/assets/javascripts/livefyre.js.coffee

@@ -0,0 +1,72 @@
+defaultDelegate = (options) ->
+  authDelegate = new fyre.conv.RemoteAuthDelegate()
+  authDelegate.login        = (handlers) ->
+    if options.login
+      options.login(handlers)
+
+  authDelegate.logout       = (handlers) ->
+    if options.logout
+      options.logout(handlers)
+  authDelegate.viewProfile  = (handlers, author) ->
+    if options.viewProfile
+      if options.viewProfile(handlers, author)
+        handlers.success()
+
+  authDelegate.editProfile  = (handlers, author) ->
+    if options.editProfile
+      if options.editProfile(handlers, author)
+        handlers.success()
+
+loadScriptAsync = null
+(->
+  __loadedScripts = []
+  fjs = null
+  loadScriptAsync = (source, id, content, options) ->
+    content = null if !content
+    return if (document.getElementById(id))
+    return if __loadedScripts[id]
+    __loadedScripts[id] = true
+    fjs = document.getElementsByTagName('script')[0] unless fjs
+    js = document.createElement("script")
+    js.id = id
+    js.async = true
+    js.src = source
+    js.innerHTML = content
+    js[k] = v for k, v of options if options
+
+    fjs.parentNode.insertBefore(js, fjs)
+    js
+)()
+
+livefyreInitialized = false
+@initLivefyre = (options) ->
+  if livefyreInitialized
+    throw "Livefyre has already been initialized"
+  livefyreInitialized = true
+  e = document.getElementById(options.element_id || "livefyre_comments")
+  if e
+    options.config ||=
+      checksum: e.getAttribute("data-checksum")
+      collectionMeta: e.getAttribute("data-collection-meta")
+      articleId: e.getAttribute("data-article-id")
+      siteId: e.getAttribute("data-site-id")
+      el: e.id
+
+    options.network ||= e.getAttribute("data-network")
+    options.domain  ||= e.getAttribute("data-domain")
+    options.root    ||= e.getAttribute("data-root")
+
+    @FYRE_LOADED_CB = ->
+      opts =
+        network: options.network
+        authDelegate: options.delegate || defaultDelegate(options)
+
+      fyre.conv.load opts, [options.config], ->
+        token = $.cookie(options.cookie_name || "livefyre_utoken")
+        if token
+          try
+            fyre.conv.login(token)
+          catch error
+            window.console.log "Error logging in:", e if window.console
+
+    element = loadScriptAsync "http://#{options.root}/wjs/v3.0/javascripts/livefyre.js", null, null, {"data-lf-domain": options.network}

data/app/assets/javascripts/livefyre.js.js

@@ -0,0 +1,117 @@
+// Generated by CoffeeScript 1.3.3
+(function() {
+  var defaultDelegate, livefyreInitialized, loadScriptAsync;
+
+  defaultDelegate = function(options) {
+    var authDelegate;
+    authDelegate = new fyre.conv.RemoteAuthDelegate();
+    authDelegate.login = function(handlers) {
+      if (options.login) {
+        return options.login(handlers);
+      }
+    };
+    authDelegate.logout = function(handlers) {
+      if (options.logout) {
+        return options.logout(handlers);
+      }
+    };
+    authDelegate.viewProfile = function(handlers, author) {
+      if (options.viewProfile) {
+        if (options.viewProfile(handlers, author)) {
+          return handlers.success();
+        }
+      }
+    };
+    return authDelegate.editProfile = function(handlers, author) {
+      if (options.editProfile) {
+        if (options.editProfile(handlers, author)) {
+          return handlers.success();
+        }
+      }
+    };
+  };
+
+  loadScriptAsync = null;
+
+  (function() {
+    var fjs, __loadedScripts;
+    __loadedScripts = [];
+    fjs = null;
+    return loadScriptAsync = function(source, id, content, options) {
+      var js, k, v;
+      if (!content) {
+        content = null;
+      }
+      if (document.getElementById(id)) {
+        return;
+      }
+      if (__loadedScripts[id]) {
+        return;
+      }
+      __loadedScripts[id] = true;
+      if (!fjs) {
+        fjs = document.getElementsByTagName('script')[0];
+      }
+      js = document.createElement("script");
+      js.id = id;
+      js.async = true;
+      js.src = source;
+      js.innerHTML = content;
+      if (options) {
+        for (k in options) {
+          v = options[k];
+          js[k] = v;
+        }
+      }
+      fjs.parentNode.insertBefore(js, fjs);
+      return js;
+    };
+  })();
+
+  livefyreInitialized = false;
+
+  this.initLivefyre = function(options) {
+    var e, element;
+    if (livefyreInitialized) {
+      throw "Livefyre has already been initialized";
+    }
+    livefyreInitialized = true;
+    e = document.getElementById(options.element_id || "livefyre_comments");
+    if (e) {
+      options.config || (options.config = {
+        checksum: e.getAttribute("data-checksum"),
+        collectionMeta: e.getAttribute("data-collection-meta"),
+        articleId: e.getAttribute("data-article-id"),
+        siteId: e.getAttribute("data-site-id"),
+        el: e.id
+      });
+      options.network || (options.network = e.getAttribute("data-network"));
+      options.domain || (options.domain = e.getAttribute("data-domain"));
+      options.root || (options.root = e.getAttribute("data-root"));
+      this.FYRE_LOADED_CB = function() {
+        var opts;
+        opts = {
+          network: options.network,
+          authDelegate: options.delegate || defaultDelegate(options)
+        };
+        return fyre.conv.load(opts, [options.config], function() {
+          var token;
+          token = $.cookie(options.cookie_name || "livefyre_utoken");
+          if (token) {
+            try {
+              return fyre.conv.login(token);
+            } catch (error) {
+              if (window.console) {
+                return window.console.log("Error logging in:", e);
+              }
+            }
+          }
+        });
+      };
+      return element = loadScriptAsync("http://" + options.root + "/wjs/v3.0/javascripts/livefyre.js", null, null, {
+        "data-lf-domain": options.network
+      });
+    }
+  };
+
+}).call(this);

data/lib/livefyre/client.rb

@@ -0,0 +1,117 @@
+module Livefyre
+  # Public: Primary interface to the Livefyre API
+  class Client
+    extend Forwardable
+    # Public: Valid roles for #set_user_role
+    ROLES = %w(admin member none outcast owner)
+
+    # Public: Valid scopes for #set_user_role
+    SCOPES = %w(domain site conv)
+
+    attr_accessor :host, :key, :options, :system_token, :http_client
+
+    def_delegators :http_client, :get, :post, :delete, :put
+
+    # Public: Create a new Livefyre client.
+    #
+    # options - [Hash] array of options to pass to the client for initialization
+    # :host         - your Livefyre network_host
+    # :key          - your Livefyre network_key
+    # :system_token - your Livefyre long-lived system user key
+    def initialize(options = {})
+      @options = options.clone
+      @host = options.delete(:network) || options.delete(:host)
+      raise "Invalid host" if @host.nil?
+      @http_client = Faraday.new(:url => "http://#{@host}")
+
+      @key = options.delete(:secret) || options.delete(:key) || options.delete(:network_key)
+      raise "Invalid secret key" if @key.nil?
+
+      @system_token = options.delete(:system_token)
+      raise "Invalid system token" if @system_token.nil?
+    end
+
+    # Public: Sign a data structure with this client's network key.
+    #
+    # Returns [String] A signed JWT token
+    def sign(data)
+      JWT.encode(data, @key)
+    end
+
+    # Public: Validates and decodes a JWT token
+    #
+    # Returns [Hash] A hash of data passed from the token
+    # Raises [JWT::DecodeError] if invalid token contents or signature
+    def validate(data)
+      JWT.decode(data, @key)
+    end
+
+    # Public: Create a {Livefyre::User} with this client's credentials.
+    #
+    # uid          - the user ID to create a Livefyre user for. This should be the ID used to reference this user in Livefyre's system.
+    # display_name - the displayed name for this user. Optional.
+    #
+    # Returns [Livefyre::User]
+    def user(uid, display_name = nil)
+      User.new(uid, self, display_name)
+    end
+
+    # Public: Sets a user's role (affiliation) in a given scope.
+    #
+    # user_id   - The user ID (without the host) to set roles for
+    # role      - The {ROLES role} to set.
+    # scope     - The {SCOPES scope} for which to set this role.
+    # scope_id  - In the case that the given scope requires identification, specifies which scope to operate on.
+    #
+    # Examples
+    #
+    #   set_user_role(1234, "owner", "domain")
+    #   set_user_role(1234, "moderator", "site", site_id)
+    #   set_user_role(1234, "moderator", "conv", conversation_id)
+    #
+    #
+    # Returns [Bool] true on success
+    # Raises APIException if the request failed
+    def set_user_role(user_id, role, scope = 'domain', scope_id = nil)
+      raise "Invalid scope" unless SCOPES.include? scope
+      raise "Invalid role" unless ROLES.include? role
+
+      post_data = {
+        :affiliation => role,
+        :lftoken => system_token,
+      }
+      case scope
+      when "domain"
+        post_data[:domain_wide] = 1
+      when "conv"
+        raise "Invalid scope_id" if scope_id.nil?
+        post_data[:conv_id] = scope_id
+      when "site"
+        raise "Invalid scope_id" if scope_id.nil?
+        post_data[:site_id] = scope_id
+      end
+      result = post "/api/v1.1/private/management/user/#{jid(user_id)}/role/", post_data
+      if result.success?
+        true
+      else
+        raise APIException.new(result.body)
+      end
+    end
+
+    # Public: Transform the given ID into a jid
+    #
+    # id - a string value to compose the JID with
+    #
+    # Returns [String] JID
+    def jid(id)
+      "%s@%s" % [id, host]
+    end
+
+    # Internal: Returns a cleaner string representation of this object
+    #
+    # Returns [String] representation of this class
+    def to_s
+      "#<#{self.class.name}:0x#{object_id.to_s(16).rjust(14, "0")} host='#{host}' key='#{key}'>"
+    end
+  end
+end

data/lib/livefyre/controller_extensions.rb

@@ -0,0 +1,58 @@
+module Livefyre
+  # Public: Controller extensions for Rails. Adds methods to be called from your controller to integrate with Livefyre.
+  module Controller
+    extend ActiveSupport::Concern
+
+    # Public: Creates the Livefyre session cookies. Should be called when the user logs in.
+    def livefyre_login(id, display_name)
+      cookie = (Livefyre.config[:cookie_options] || {}).clone || {:path => "/", :expires => Time.now + 1.year}
+      expiry = cookie.delete(:expires) || (Time.now + 1.year)
+
+      token = {
+        :domain  => Livefyre.client.host,
+        :user_id => id,
+        :expires => expiry.to_i,
+        :display_name => display_name
+      }
+
+      name = cookie.delete(:name) || "livefyre_utoken"
+      cookies[name] = cookie.merge(:value => JWT.encode(token, Livefyre.client.key), :expires => expiry)
+    end
+
+    # Public: Destroys the Livefyre session cookies. Should be called when the user logs out
+    def livefyre_logout
+      name = (Livefyre.config[:cookie_options] || {})[:name] || "livefyre_utoken"
+      cookies.delete(name)
+    end
+
+    # Public: Attempt to generate valid Livefire profile dump from the passed user record by guessing at field names.
+    #
+    # user   - The user record to generate data from. Assumes it's ActiveModel-ish.
+    # values - [Hash] of values to force values for, rather than guessing at.
+    #
+    # Returns [Hash] suitable for conversion to JSON
+    def livefire_profile(user, values = {})
+      {
+        :id            => user.id,
+        :display_name  => user.try(:display_name) || user.try(:name) || user.try(:username),
+        :email         => user.try(:email),
+        :profile       => url_for(user),
+        :settings_url  => url_for(:edit, user),
+        :bio           => user.try(:bio) || user.try(:about),
+        :name          => {
+          :first_name  => user.try(:first_name),
+          :last_name   => user.try(:last_name),
+        }
+      }.merge defaults
+    end
+
+    # Public: Check the validity of the JWT that Livefyre sends with pull requests.
+    #
+    # Raises [JWT::DecodeError] if the token is invalid or missing.
+    def validate_livefyre_request!
+      token = JWT.decode params[:lftoken], Livefyre.client.key
+      raise JWT::DecodeError unless token["domain"] == Livefyre.client.host
+      return true
+    end
+  end
+end