the86-client 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 the86-client.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,5 @@
+guard "minitest" do
+  watch(%r{^spec/(.*)_spec\.rb})
+  watch(%r{^lib/(.*)([^/]+)\.rb})     { |m| "spec/#{m[1]}#{m[2]}_spec.rb" }
+  watch(%r{^spec/spec_helper\.rb})    { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 SitePoint Pty Ltd
+
+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,80 @@
+The86::Client
+=============
+
+Ruby client for "The 86" conversation API server.
+
+Uses [Faraday][1] for HTTP transport, JSON encoding/decoding etc.
+
+Uses [Virtus][2] for DataMapper-style object attribute declaration.
+
+Uses [MiniTest][3] and [WebMock][4] for unit/integration testing (run `rake`).
+
+
+[1]: https://github.com/technoweenie/faraday
+[2]: https://github.com/solnic/virtus
+[3]: https://github.com/seattlerb/minitest
+[4]: https://github.com/bblimke/webmock
+
+
+Get Code, Run Tests
+-------------------
+
+    git clone REPO_PATH
+    cd the86-client
+    bundle install
+    bundle exec rake
+
+
+Install the Gem
+---------------
+
+    gem install the86-client
+
+
+Add to a Project
+----------------
+
+    echo 'gem "the86-client"' >> Gemfile
+    bundle
+
+
+Usage
+-----
+
+```ruby
+# The domain running The 86 discussion server.
+The86::Client.domain = "the86.yourdomain.com"
+
+# HTTP Basic Auth credentials allocated for your API client.
+The86::Client.credentials = ["username", "password"]
+
+# Create an end-user account:
+user = The86::Client.users.create(name: "John Citizen")
+oauth_token = user.access_tokens.first.token
+
+# Create a new conversation:
+conversation = The86::Client.site("example").conversations.create(
+  content: "Hello world!",
+  oauth_token: oauth_token
+)
+
+# Reply as another user:
+user = The86::Client.users.create(name: "Jane Taxpayer")
+conversation.posts.first.reply(
+  content: "I concur!",
+  oauth_token: user.access_tokens.first.token
+)
+
+# Follow up to a conversation:
+user = The86::Client.users.create(name: "Joe Six-pack")
+conversation.posts.create(
+  content: "What are you guys talking about?",
+  oauth_token: user.access_tokens.first.token
+)
+```
+
+
+Licence
+-------
+
+(c) SitePoint, 2012, MIT license.

data/Rakefile

@@ -0,0 +1,11 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+task default: :test
+
+# MiniTest
+require "rake/testtask"
+Rake::TestTask.new do |t|
+  ENV["TESTOPTS"] = "-v"
+  t.pattern = "spec/*_spec.rb"
+end

data/lib/the86-client.rb

@@ -0,0 +1,69 @@
+%w{
+  version
+  connection
+  errors
+  oauth_bearer_authorization
+
+  resource
+  resource_collection
+  user
+  site
+  post
+  conversation
+}.each { |r| require "the86-client/#{r}" }
+
+module The86
+  module Client
+
+    # API entry points.
+
+    def self.sites
+      ResourceCollection.new(
+        Connection.new,
+        "sites",
+        Site,
+        nil
+      )
+    end
+
+    def self.site(slug)
+      Site.new(slug: slug)
+    end
+
+    def self.users
+      ResourceCollection.new(
+        Connection.new,
+        "users",
+        User,
+        nil
+      )
+    end
+
+    # Configuration.
+    class << self
+
+      attr_writer :domain
+      attr_writer :credentials
+
+      def domain
+        @domain ||
+          raise("Domain not configured: #{name}.domain = \"example.org\"")
+      end
+
+      def credentials
+        @credentials ||
+          raise("Credentials not configured: #{name}.credentials = [username, password]")
+      end
+
+      def disable_https!
+        @scheme = "http"
+      end
+
+      def scheme
+        @scheme || "https"
+      end
+
+    end
+
+  end
+end

data/lib/the86-client/active_model.rb

@@ -0,0 +1,37 @@
+# Patches The86::Client::Resource to implement enough of
+# ActiveModel's interface to act as a form object.
+# Depends on ActiveModel being provided externally.
+
+module The86
+  module Client
+    class Resource
+
+      extend ActiveModel::Naming
+
+      include ActiveModel::Validations
+
+      # Model name relative to The86::Client namespace.
+      # Names form fields like post[...] instead of the86_client_post[...].
+      def self.model_name
+        ActiveModel::Name.new(self, The86::Client)
+      end
+
+      def to_model
+        self
+      end
+
+      def persisted?
+        !!id
+      end
+
+      def to_key
+        nil
+      end
+
+      def to_param
+        url_id
+      end
+
+    end
+  end
+end

data/lib/the86-client/connection.rb

@@ -0,0 +1,81 @@
+require "faraday"
+require "faraday_middleware"
+
+module The86
+  module Client
+    class Connection
+
+      def initialize
+        @faraday = Faraday.new(url) do |conn|
+          conn.request :json
+          conn.response :json
+          conn.basic_auth(*Client.credentials)
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      def prepend(*parameters)
+        @faraday.builder.insert(0, *parameters)
+      end
+
+      def get(options)
+        dispatch(:get, options)
+      end
+
+      def patch(options)
+        dispatch(:patch, options)
+      end
+
+      def post(options)
+        dispatch(:post, options)
+      end
+
+      def dispatch(method, options)
+        path = options.fetch(:path)
+        data = options[:data]
+        response = @faraday.run_request(method, path, data, @faraday.headers)
+        assert_http_status(response, options[:status])
+        response.body
+      end
+
+      private
+
+      def url
+        "%s://%s/api/v1" % [ Client.scheme, Client.domain ]
+      end
+
+      def assert_http_status(response, status)
+        case response.status
+        when nil, status then return
+        when 401
+          raise Unauthorized
+        when 422
+          raise ValidationFailed, "Validation failed: #{response.body.to_s}"
+        when 500
+          raise ServerError, internal_server_error_message(status, response)
+        else
+          raise Error, "Expected HTTP #{status}, got HTTP #{response.status}"
+        end
+      end
+
+      def internal_server_error_message(expected_status, response)
+        body = response.body
+        if body["type"] && body["message"] && body["backtrace"]
+          "Expected HTTP %d, got HTTP %d with error:\n%s\n%s\n\n%s" % [
+            expected_status,
+            response.status,
+            response.body["type"],
+            response.body["message"],
+            response.body["backtrace"].join("\n"),
+          ]
+        else
+          "Expected HTTP %d, got %d" % [
+            expected_status,
+            response.status,
+          ]
+        end
+      end
+
+    end
+  end
+end

data/lib/the86-client/conversation.rb

@@ -0,0 +1,14 @@
+module The86::Client
+  class Conversation < Resource
+
+    attribute :id, Integer
+    attribute :content, String # For creating new Conversation.
+    attribute :created_at, DateTime
+    attribute :updated_at, DateTime
+
+    path "conversations"
+    belongs_to :site
+    has_many :posts, ->{ Post }
+
+  end
+end

data/lib/the86-client/errors.rb

@@ -0,0 +1,20 @@
+module The86
+  module Client
+
+    class Error < StandardError
+    end
+
+    class ServerError < Error
+    end
+
+    class Unauthorized < Error
+      def message
+        "Unauthorized"
+      end
+    end
+
+    class ValidationFailed < Error
+    end
+
+  end
+end

data/lib/the86-client/oauth_bearer_authorization.rb

@@ -0,0 +1,21 @@
+module The86::Client
+
+  # A Faraday middleware which adds or overwrites the
+  # Authorization header with an OAuth2 bearer token.
+  # See: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-22
+  class OauthBearerAuthorization < Faraday::Middleware
+
+    AUTH_HEADER = "Authorization"
+
+    def initialize(app, token)
+      super(app)
+      @token = token
+    end
+
+    def call(env)
+      env[:request_headers][AUTH_HEADER] = "Bearer #{@token}"
+      @app.call(env)
+    end
+
+  end
+end

data/lib/the86-client/post.rb

@@ -0,0 +1,26 @@
+module The86::Client
+  class Post < Resource
+
+    attribute :id, Integer
+    attribute :content, String
+    attribute :in_reply_to_id, Integer
+    attribute :created_at, DateTime
+    attribute :updated_at, DateTime
+
+    path "posts"
+    belongs_to :conversation
+    has_one :user, ->{ User }
+    has_one :in_reply_to, ->{ Post }
+
+    def reply?
+      !!in_reply_to_id
+    end
+
+    def reply(attributes)
+      conversation.posts.create(
+          attributes.merge(in_reply_to_id: id)
+      )
+    end
+
+  end
+end

data/lib/the86-client/resource.rb

@@ -0,0 +1,149 @@
+require "virtus"
+
+module The86
+  module Client
+    class Resource
+
+      include Virtus
+
+      # Assigned by Virtus constructor.
+      attr_accessor :oauth_token
+
+      # Parent resource, see belongs_to.
+      attr_accessor :parent
+
+      ##
+      # Declarative API for subclasses.
+
+      class << self
+
+        # The path component for the collection, e.g. "discussions"
+        def path(path)
+          @path = path
+        end
+
+        # The name of the parent resource attribute.
+        # e.g: belongs_to :site
+        def belongs_to(name)
+          alias_method "#{name}=", :parent=
+          alias_method name, :parent
+        end
+
+        # The name of a child collection.
+        def has_many(name, class_proc)
+          define_method "#{name}=" do |items|
+            (@_has_many ||= {})[name] = items
+          end
+          define_method name do
+            has_many_reader(name, class_proc)
+          end
+        end
+
+        def has_one(name, class_proc)
+          define_method "#{name}=" do |instance|
+            (@_has_one ||= {})[name] = instance
+          end
+          define_method name do
+            has_one_reader(name, class_proc)
+          end
+        end
+
+      end
+
+      ##
+      # Class methods.
+
+      def self.collection_path(parent)
+        [parent && parent.resource_path, @path].compact.join("/")
+      end
+
+      ##
+      # Instance methods
+
+      # The value of the identifier in the URL; numeric ID or string slug.
+      # TODO: see ResourceCollection#find.
+      def url_id
+        id
+      end
+
+      def resource_path
+        "%s/%s" % [ self.class.collection_path(@parent), url_id ]
+      end
+
+      def save
+        id ? save_existing : save_new
+      end
+
+      def load
+        self.attributes = connection.get(
+          path: resource_path,
+          status: 200
+        )
+        self
+      end
+
+      def sendable_attributes
+        attributes.reject do |key, value|
+          [:id, :created_at, :updated_at].include?(key) ||
+            value.kind_of?(Resource) ||
+            value.nil?
+        end
+      end
+
+      def ==(other)
+        attributes == other.attributes &&
+          parent == other.parent
+      end
+
+      private
+
+      def save_new
+        self.attributes = connection.post(
+          path: self.class.collection_path(@parent),
+          data: sendable_attributes,
+          status: 201
+        )
+      end
+
+      def save_existing
+        self.attributes = connection.patch(
+          path: resource_path,
+          data: sendable_attributes,
+          status: 200
+        )
+      end
+
+      def connection
+        Connection.new.tap do |c|
+          c.prepend OauthBearerAuthorization, oauth_token if oauth_token
+        end
+      end
+
+      def has_many_reader(name, class_proc)
+        klass = class_proc.call
+        ResourceCollection.new(
+          connection,
+          klass.collection_path(self),
+          class_proc.call,
+          self,
+          (@_has_many || {})[name] || nil
+        )
+      rescue KeyError
+        raise Error, "No reference to children :#{name}"
+      end
+
+      def has_one_reader(name, class_proc)
+        klass = class_proc.call
+        record = (@_has_one || {}).fetch(name)
+        if record.is_a?(Resource)
+          record
+        else
+          @_has_one[name] = klass.new(record)
+        end
+      rescue KeyError
+        raise Error, "No reference to child :#{name}"
+      end
+
+    end
+  end
+end