zipmark 0.0.1.beta.1

data/CONTRIBUTING.md

@@ -0,0 +1 @@
+fork -> test + code -> pull request

data/README.md

@@ -0,0 +1,71 @@
+# Zipmark Ruby Client
+
+The Zipmark Ruby Client library is used to interact with Zipmark's [API](https://dev.zipmark.com).
+
+## Installation
+
+### Requirements
+
+## Initialization
+
+## Usage Examples
+
+### Instantiating a client
+
+Application Identifier and Application Secret should be replaced with the vendor application identifier and secret provided by Zipmark.
+
+### Production Mode
+
+### Loading a Bill from a known Bill ID
+
+
+### Discovering available resources
+
+Resources will contain an array of all available resources.
+
+### Creating a new Bill
+
+Create a bill object, set required attributes, send it to Zipmark
+
+As an alternative, it is possible to build an object first and then save it afterwards
+
+
+### Updating an existing Bill
+
+Get the bill, make a change, send it back to Zipmark
+
+### Retrieving a list of all Bills
+
+Retrieve a list of all bills.
+
+Get the number of objects available.
+
+### Basic Iterator
+
+The Zipmark_Iterator class understands Zipmark's pagination system.  It loads one page of objects at a time and will retrieve more objects as necessary while iterating through the objects.
+
+Get the current object (returns null if the iterator has passed either end of the list)
+
+Get the next/previous object (returns null if the next/previous object would pass either end of the list)
+
+### Iterating through a list of all Bills
+
+The Zipmark_Iterator can be used to iterate through all objects of a given resource type.
+
+### Callback processing
+
+The client is able to process, verify and extract data from callbacks received from the Zipmark service.
+
+#### Loading a callback response
+
+#### Verifying a callback
+
+#### Retrieving the callback data
+
+Valid callbacks contain events, object types and objects.  The below functions will return their respective values/objects, or null if the callback is invalid.
+
+## API Documentation
+
+Please see the [Zipmark API](https://dev.zipmark.com) or contact Zipmark Support via [email](mailto:developers@zipmark.com) or [chat](http://bit.ly/zipmarkAPIchat) for more information.
+
+## Unit/Acceptance Tests

data/lib/zipmark/action.rb

@@ -0,0 +1,5 @@
+module Zipmark
+  class Action
+    attr_accessor :name, :method, :href, :accepts, :inputs
+  end
+end

data/lib/zipmark/adapters/httparty_adapter.rb

@@ -0,0 +1,47 @@
+module Zipmark
+  module Adapters
+    class HTTPartyAdapter
+      begin
+        require 'httparty'
+        include HTTParty
+      rescue LoadError
+        puts 'You must install httparty >= \'0.9.0\' to use Zipmark::Adapters::HTTPartyAdapter '
+      end
+
+      attr_accessor :username, :password, :production
+
+      def api_endpoint
+        production ? PRODUCTION_API_ENDPOINT : SANDBOX_API_ENDPOINT
+      end
+
+      def api_accept_mime
+        "application/vnd.com.zipmark.#{API_VERSION}+json"
+      end
+
+      def get(path)
+        self.class.get(path, adapter_options)
+      end
+
+      def post(path, body)
+        self.class.post(path, adapter_options.merge(:body => body.to_json))
+      end
+
+      def put(path, body)
+        self.class.put(path, adapter_options.merge(:body => body.to_json))
+      end
+
+      def delete(path)
+        self.class.delete(path, adapter_options)
+      end
+
+      private
+      def adapter_options
+        {
+          :base_uri => api_endpoint,
+          :digest_auth => { :username => username, :password => password },
+          :headers => { 'Content-Type' => 'application/json', 'Accept' => api_accept_mime }
+        }
+      end
+    end
+  end
+end

data/lib/zipmark/adapters/httpclient_adapter.rb

@@ -0,0 +1,61 @@
+module Zipmark
+  module Adapters
+    class HTTPClientAdapter
+      begin
+        require 'httpclient'
+      rescue LoadError
+        puts 'You must install httpclient to use Zipmark::Adapters::HTTClientAdapter '
+      end
+
+      attr_accessor :username, :password, :production
+
+      def httpclient
+        @httpclient ||= initialize_client
+      end
+
+      def initialize_client
+        client = HTTPClient.new
+        client.set_auth(api_endpoint, username, password)
+        return client
+      end
+
+      def api_endpoint
+        production ? PRODUCTION_API_ENDPOINT : SANDBOX_API_ENDPOINT
+      end
+
+      def api_accept_mime
+        "application/vnd.com.zipmark.#{API_VERSION}+json"
+      end
+
+      def get(path)
+        httpclient.get(url_for(path), adapter_options)
+      end
+
+      def post(path, body)
+        httpclient.post(url_for(path), adapter_options.merge(:body => body.to_json))
+      end
+
+      def put(path, body)
+        httpclient.put(url_for(path), adapter_options.merge(:body => body.to_json))
+      end
+
+      def delete(path)
+        httpclient.delete(url_for(path), adapter_options)
+      end
+
+      def url_for(path)
+        path = URI.parse(path)
+        if path.kind_of? URI::Generic
+          path = URI.parse(api_endpoint) + path
+        end
+      end
+
+      private
+      def adapter_options
+        {
+          :header => { 'Content-Type' => 'application/json', 'Accept' => api_accept_mime }
+        }
+      end
+    end
+  end
+end

data/lib/zipmark/auth.rb

@@ -0,0 +1,6 @@
+module Zipmark
+  module Auth
+    class Digest
+    end
+  end
+end

data/lib/zipmark/callback.rb

@@ -0,0 +1,72 @@
+module Zipmark
+  class Callback
+    attr_accessor :request, :errors
+
+    def initialize(request, options = {})
+      raise ArgumentError, "Request cannot be nil" unless request
+      @request = request
+      @errors = {}
+    end
+
+    def body
+      @request.raw_post
+    end
+
+    def event
+      raise "unimplemented"
+    end
+
+    def object
+      raise "unimplemented"
+    end
+
+    def object_type
+      raise "unimplemented"
+    end
+
+    def hashed_content
+      Digest::MD5.hexdigest(body) if body
+    end
+
+    def date
+      Time.parse(@request.headers["Date"]) if @request.headers["Date"]
+    end
+
+    def uri
+      @request.fullpath
+    end
+
+    def date_within_range?
+      date && date < Time.now + 15.minutes && date > Time.now - 15.minutes
+    end
+
+    def valid?
+      validate_date && validate_authorization
+    end
+
+    def validate_authorization
+      string_to_sign = ["POST",hashed_content,'application/json',date.rfc2822,uri,identifier].join("\n")
+      signed_string = ActiveSupport::Base64.encode64s(OpenSSL::HMAC.digest(OpenSSL::Digest::Digest.new('sha1'), secret, string_to_sign))
+      valid_authorization = "ZM #{ActiveSupport::Base64.encode64s(identifier)}:#{signed_string}"
+      if authorization_header == valid_authorization
+        return true
+      else
+        @errors[:authorization] = "Signature does not match."
+        return false
+      end
+    end
+
+    def validate_date
+      if date_within_range?
+        return true
+      else
+        @errors[:date] = "Date is not within bounds."
+        return false
+      end
+    end
+
+    def authorization_header
+      @request.headers["Authorization"]
+    end
+  end
+end

data/lib/zipmark/client.rb

@@ -0,0 +1,71 @@
+module Zipmark
+  # Public: The Zipmark API Client.
+  #
+  # Examples
+  #
+  #   client = Zipmark::Client.new("app-id", "app-secret", :production => false)
+  #   client.get("/")
+  #
+  class Client
+    # Public: Gets the Adapter.
+    attr_reader :adapter
+
+    # Public: Initialize a Zipmark Client
+    #
+    # application_id - The Identifier for your application
+    # application_secret - The Secret for your Application
+    # options - Hash options used to configure the Client (default: {})
+    #      :adapter - The Instance of an Adapter that wraps your preferred HTTP Client
+    #      :production - The Boolean determining if Production Mode is enabled
+    def initialize(application_id, application_secret, options = {})
+      @adapter = options[:adapter] || Zipmark::Adapters::HTTPClientAdapter.new
+      adapter.production = options[:production]
+      adapter.username = application_id
+      adapter.password = application_secret
+      @resources = load_resources
+    end
+
+
+    # Public: Send a GET Request to the given API Path
+    #
+    # path - A String which can be a relative path to the API root, or a full URL
+    def get(path)
+      adapter.get(path)
+    end
+
+    # Public: Send a POST Request to the given API Path
+    #
+    #  path - A String which can be a relative path to the API root, or a full URL
+    #  body - A Object which responds to to_json and represents the body of the POST
+    def post(path, body)
+      adapter.post(path, body)
+    end
+
+    # Public: Send a PUT Request to the given API Path
+    #
+    #  path - A String which can be a relative path to the API root, or a full URL
+    #  body - A Object which responds to to_json and represents the body of the PUT
+    def put(path, body)
+      adapter.put(path, body)
+    end
+
+    # Public: Send a DELETE Request to the given API Path
+    #
+    # path - A String which can be a relative path to the API root, or a full URL
+    def delete(path)
+      adapter.delete(path)
+    end
+
+    def method_missing(meth, *args, &block)
+      @resources[meth.to_s] || raise(NoMethodError, "No resource or method: '#{meth}'")
+    end
+
+    private
+    def load_resources
+      hash = {}
+      response = JSON.parse(get("/").body)
+      response["vendor_root"]["links"].each {|link| hash[link["rel"]] = Resource.new({ :client => self }.merge(link)) }
+      hash
+    end
+  end
+end

data/lib/zipmark/collection.rb

@@ -0,0 +1,27 @@
+module Zipmark
+  class Collection
+    include Enumerable
+
+    attr_accessor :iterator
+
+    def initialize(resource, iterator_class)
+      fetched_resource = resource.client.get(resource.href).body
+      @iterator = iterator_class.new(fetched_resource, :resource_name => resource.rel, :client => resource.client)
+    end
+
+    def items
+      iterator.current_items
+    end
+
+    def length
+      iterator.total_items
+    end
+
+    def each
+      # Wrapping in the being block ensures that the current_item is yielded once before next_item is called
+      begin
+        yield iterator.current_item
+      end while iterator.next_item
+    end
+  end
+end

data/lib/zipmark/documentation.rb

@@ -0,0 +1,4 @@
+module Zipmark
+  class Documentation
+  end
+end

data/lib/zipmark/entity.rb

@@ -0,0 +1,59 @@
+module Zipmark
+  class Entity
+    attr_accessor :attributes, :client, :resource_type, :errors, :dirty_attributes
+
+    def initialize(options={})
+      @errors = {}
+      @attributes = Util.stringify_keys(options)
+      @dirty_attributes = {}
+      @client = @attributes.delete("client")
+      @resource_type = @attributes.delete("resource_type")
+    end
+
+    def method_missing(meth, *args, &block)
+      if meth =~ /=$/
+        dirty_attributes[meth.to_s.sub(/=$/, '')] = args.first
+      else
+        dirty_attributes[meth.to_s] || attributes[meth.to_s]
+      end
+    end
+
+    def save
+      if url
+        response = client.put(url, resource_type => dirty_attributes)
+      else
+        response = client.post("/#{resource_type}s", resource_type => attributes)
+      end
+      apply_response(response)
+      return self
+    end
+
+    def apply_response(response)
+      object = JSON.parse(response.body)
+      if response.ok?
+        @attributes = object[resource_type]
+      elsif response.code == 422
+        @errors = object
+      else
+        raise Zipmark::Error.new(object)
+      end
+    end
+
+    def valid?
+      !!(id && errors.empty?)
+    end
+
+    def url
+      link = links.detect {|link| link["rel"] == "self" } if links && !links.empty?
+      link["href"] if link
+    end
+
+    def updated_at
+      Time.parse(attributes["updated_at"]) if attributes["updated_at"]
+    end
+
+    def  created_at
+      Time.parse(attributes["created_at"]) if attributes["created_at"]
+    end
+  end
+end

data/lib/zipmark/error.rb

@@ -0,0 +1,5 @@
+module Zipmark
+  class Error < StandardError
+    attr_accessor :classification, :messages, :code
+  end
+end

data/lib/zipmark/input.rb

@@ -0,0 +1,5 @@
+module Zipmark
+  class Input
+    attr_accessor :type, :required, :name, :title, :placeholder, :value
+  end
+end

data/lib/zipmark/iterator.rb

@@ -0,0 +1,71 @@
+require 'json'
+
+module Zipmark
+  class Iterator
+    attr_accessor :current_item, :json, :options
+
+    def initialize(json, options = {})
+      @json = JSON.parse(json)
+      @options = options
+      @current_item = items.first
+    end
+
+    def client
+      options[:client]
+    end
+
+    def collection
+      json[options[:resource_name]]
+    end
+
+    def metadata
+      json["meta"]
+    end
+
+    def links
+      json["links"]
+    end
+
+    def items
+      @items ||= collection.map {|item| Entity.new(item.merge(:client => options[:client], :resource_type => resource_singular)) }
+    end
+
+    def resource_singular
+      options[:resource_name].sub(/s$/, '')
+    end
+
+    def pagination
+      @pagination ||= Pagination.new(metadata["pagination"] ) if metadata
+    end
+
+    def next_item
+      item =  @items.fetch(@items.index(current_item) + 1) rescue nil
+      if item
+        @current_item = item
+      else
+        @current_item = fetch_item_from_next_page ? @items.fetch(0) : nil
+      end
+    end
+
+    def fetch_item_from_next_page
+      return if pagination.last_page?
+      self.json = JSON.parse(client.get(next_page["href"]).body)
+      @items = nil
+      @pagination = nil
+      @current_item = items.first
+      return true
+    end
+
+    def next_page
+      links.detect {|l| l["rel"] == "next"}
+    end
+
+    def total_items
+      pagination.total if pagination
+    end
+
+    def pages
+      pagination.pages if pagination
+    end
+  end
+end

data/lib/zipmark/link.rb

@@ -0,0 +1,4 @@
+module Zipmark
+  class Link
+  end
+end

data/lib/zipmark/pagination.rb

@@ -0,0 +1,34 @@
+module Zipmark
+  class Pagination
+    attr_accessor :pagination_hash
+
+    def initialize(hash)
+      raise ArgumentError, "expected hash" unless hash && hash.kind_of?(Hash)
+      @pagination_hash = hash
+    end
+
+    def pages
+      pagination_hash["total_pages"]
+    end
+
+    def total
+      pagination_hash["total"]
+    end
+
+    def per_page
+      pagination_hash["per_page"]
+    end
+
+    def current_page
+      pagination_hash["page"]
+    end
+
+    def first_page?
+      pagination_hash["first_page"]
+    end
+
+    def last_page?
+      pagination_hash["last_page"]
+    end
+  end
+end

data/lib/zipmark/resource.rb

@@ -0,0 +1,45 @@
+module Zipmark
+  class Resource
+    attr_accessor :options
+
+    def initialize(options={})
+      @options = Util.stringify_keys(options)
+    end
+
+    def all
+      Zipmark::Collection.new(self, Zipmark::Iterator)
+    end
+
+    def find(id)
+      json = client.get("/" + rel + "/" + id).body
+      object = JSON.parse(json)
+      Zipmark::Entity.new(object[resource_name].merge(:client => client, :resource_type => resource_name))
+    end
+
+    def build(options)
+      Zipmark::Entity.new(options.merge(:client => client, :resource_type => resource_name))
+    end
+
+    def create(options)
+      entity = build(options)
+      entity.save
+    end
+
+    def href
+      options["href"] || raise(Zipmark::ResourceError, "Resource did not specify href")
+    end
+
+    def rel
+      options["rel"] || raise(Zipmark::ResourceError, "Resource did not specify rel")
+    end
+
+    def resource_name
+      #TODO: This is a hack
+      rel.gsub(/s$/, '')
+    end
+
+    def client
+      options["client"] || raise(Zipmark::ClientError, "You must pass :client as an option")
+    end
+  end
+end

data/lib/zipmark/util.rb

@@ -0,0 +1,16 @@
+module Zipmark
+  # Public: Utility methods for the Zipmark API Client
+  class Util
+    # Public: Method which converts all of a hash's keys to strings
+    #
+    # hash - The hash whose keys you would like to convert
+    #
+    # Returns the converted Hash
+    def self.stringify_keys(hash)
+      hash.inject({}) do |options, (key, value)|
+        options[key.to_s] = value
+        options
+      end
+    end
+  end
+end

data/lib/zipmark/version.rb

@@ -0,0 +1,3 @@
+module Zipmark
+  VERSION = '0.0.1.beta.1'
+end

data/lib/zipmark.rb

@@ -0,0 +1,30 @@
+require 'zipmark/callback'
+require 'zipmark/client'
+require 'zipmark/collection'
+require 'zipmark/entity'
+require 'zipmark/error'
+require 'zipmark/iterator'
+require 'zipmark/pagination'
+require 'zipmark/resource'
+require 'zipmark/util'
+require 'zipmark/version'
+
+require 'zipmark/adapters/httpclient_adapter'
+
+# Public: Main module for the Zipmark API Client
+module Zipmark
+  # Public: URI String for the Zipmark Production API Endpoint.
+  PRODUCTION_API_ENDPOINT = 'https://api.zipmark.com'
+
+  # Public: URI String for the Zipmark Sandbox API Endpoint.
+  SANDBOX_API_ENDPOINT = 'https://sandbox.zipmark.com'
+
+  # Public: String Representing the Current Zipmark API Version
+  API_VERSION = 'v2'
+
+  # Public: Error that is raised when a client is expected but not found
+  class ClientError < StandardError; end
+
+  # Public: Error that is raised when a Resource is malformed or invalid
+  class ResourceError < StandardError; end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: zipmark
+version: !ruby/object:Gem::Version
+  version: 0.0.1.beta.1
+  prerelease: 6
+platform: ruby
+authors:
+- Jake Howerton
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-01 00:00:00.000000000 Z
+dependencies: []
+description: Simple Client Library to connect to the Zipmark API
+email: jake@zipmark.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/zipmark/action.rb
+- lib/zipmark/adapters/httparty_adapter.rb
+- lib/zipmark/adapters/httpclient_adapter.rb
+- lib/zipmark/auth.rb
+- lib/zipmark/callback.rb
+- lib/zipmark/client.rb
+- lib/zipmark/collection.rb
+- lib/zipmark/documentation.rb
+- lib/zipmark/entity.rb
+- lib/zipmark/error.rb
+- lib/zipmark/input.rb
+- lib/zipmark/iterator.rb
+- lib/zipmark/link.rb
+- lib/zipmark/pagination.rb
+- lib/zipmark/resource.rb
+- lib/zipmark/util.rb
+- lib/zipmark/version.rb
+- lib/zipmark.rb
+- CONTRIBUTING.md
+- README.md
+homepage: http://rubygems.org/gems/zipmark
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>'
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Zipmark API Client Library
+test_files: []