teamsnap_rb 1.3.3 → 2.0.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f0239f7246eecc56c771e8a38313131be8be7ee5
-  data.tar.gz: 58a567e81b97aa5057131841d5330a3b09106392
+  metadata.gz: a93f427c06bd23b1c461e7972a5be914b48afa1c
+  data.tar.gz: b49a4d94aa26ee91aea101677ad74f3d3941b1bb
 SHA512:
-  metadata.gz: 05a720ecb0301f7b8531e6dc7649b2d94ba405baa322bb12af48798fb921462cc3ccd26168a1f5a16be6c9b2d719198ca0decdfc4335fe3863a4f93833fa9aec
-  data.tar.gz: d3f5ff84adf69cfe375efc974514af485c4515c9cf552df95e73090c4abda44e7378f42aa3a7014809c0460f6ad160b9b7600c634b19549291a6475e505aeed8
+  metadata.gz: 9485d5d81583191d1d4027d61e050b6e99f1312f732d045faa7a9951f4b1e5ba31a3536ea2cd9b757d0acc22fef45863e8a655944e9e8dd6bb3dae8b9d3d03e7
+  data.tar.gz: 18ba0a37191961fe69074e67f13a82dffb2ef208094423118c9eb15f6dc092d9f0f63d18f4c921139d311579cacb7c10d2ef75099ebcf4f08ebe2c6a315d3a82

data/CHANGELOG.md

@@ -14,3 +14,9 @@ v1.3.3
 
 - Have the ability to search for a /schemas endpoint and create the collections
   off of the schema endpoint instead of hitting each endpoint individually
+
+v2.0.0.beta
+------
+
+- Full CRUD actions available along with TeamSnap::Response option for better
+  control-flow statements.

data/README.md

@@ -12,37 +12,139 @@
 _Note: You'll need an OAuth2 Token from TeamSnap. Checkout our API docs
 [here](http://developer.teamsnap.com/documentation/apiv3/)_
 
-```
-λ gem install teamsnap_rb
-λ irb
-> TeamSnap.init(:token => "abc123...")
-> t = TeamSnap::Team.find(1)
-=> #<TeamSnap::Team::...>
-> t.name
-=> "TeamSnap"
-> rs = client.bulk_load(:team_id => 1, :types => "team,member")
-=> [#<TeamSnap::Team:...>,
- #<TeamSnap::Member:...>,
- # ...
- #<TeamSnap::Member:...>]
-> rs[1].first_name
-=> "Andrew"
-```
-
-## Backup Cache
-
-By default when calling TeamSnap.init(...), there is a backup cache of the API root response used
-to setup all relevant classes. This is primarily used so CI testing and deploy jobs do not have to 
-connect to the API to complete.
-
-This creates a .teamsnap\_rb file in your ./tmp directory (./tmp/.teamsnap_rb). If you would like to turn this functionality
-off, just set ```:backup_cache => false``` in your init options. Alternatively, you can set the location
-of the backup by passing a string location of where to store the file. e.g.
-```:backup_cache => "./another/location/.teamsnap_rb_file"```
+    λ gem install teamsnap_rb
+    λ irb
+    TeamSnap.init(:client_id => XXXXX, :client_secret => XXXXX)
+    => true
+
+    # Now you have your base connection to the API under:
+    TeamSnap.root_client
+    => #<TeamSnap::Client:...>
+
+    # The below imply usage of:
+    client = TeamSnap.root_client
+
+    t = TeamSnap::Team.find(client, 1)
+    => #<TeamSnap::Team::...>
+    t.name
+    => "TeamSnap"
+    rs = client.bulk_load(client, {:team_id => 1, :types => "team,member"})
+    => [
+    =>   #<TeamSnap::Team:...>,
+    =>   #<TeamSnap::Member:...>,
+    =>   # ...
+    =>   #<TeamSnap::Member:...>
+    => ]
+    rs[1].first_name
+    => "Andrew"
+
+
+    #########################
+         Class Syntax
+    #########################
+     - raises error on exception
+     - returns Object(TeamSnap::Class) / Objects(Array) as response
+
+    # find
+    team = TeamSnap::Team.find(client, XXX)
+
+    # create
+    team = TeamSnap::Team.create(client, {:attribute_name => value})
+
+    # update
+    team = TeamSnap::Team.update(client, {:id => XXX, :attribute_name => value})
+
+    # delete
+    no_team = TeamSnap::Team.delete(client, id)
+
+    # search
+    teams = TeamSnap::Team.search(client, {:filter_on => filter_value})
+
+    # command
+    team = TeamSnap::Team.command_name(client, {:attr => val})
+
+
+    #########################
+         Api Class Syntax
+    #########################
+     - returns TeamSnap::Response object with select methods
+     - optionally converts attributes hash into template: { data: {}}
+
+    # find
+    response = TeamSnap::Api.run(client, :find, :members, 1)
+    => #<TeamSnap::Response:...>
+    response.success?
+    => true
+    member = response.objects.first
+    => #<TeamSnap::Member:...>
+    response.errors?
+    => false
+    response.message
+    => "Data retrieved successfully"
+
+    # create
+    response = TeamSnap::Api.run(client, :create, TeamSnap::Member, {:attr_name => attr_value}, true)
+    => #<TeamSnap::Response:...>
+    response.success?
+    => false
+    response.errors?
+    => true
+    response.message
+    => "first_name can't be blank; team_id can't be blank"
+
+    # update
+    TeamSnap::Api.run(client, :update, :member, {}, true)
+    => #<TeamSnap::Response:...>
+
+    # delete
+    TeamSnap::Api.run(client, :delete, :members, id)
+    => #<TeamSnap::Response:...>
+
+    # search & other queries
+    TeamSnap::Api.run(client, :search, TeamSnap::Member, {:team_id => some_team_id})
+    => #<TeamSnap::Response:...>
+
+    # commands
+    TeamSnap::Api.run(client, :command, :member, {:optional_attr => value})
+    => #<TeamSnap::Response:...>
+
+
+    #########################
+       Client Object Calls
+    #########################
+     - returns TeamSnap::Response object with select methods
+     - automatically translates attributes to / from template: { data: {}}
+
+    # find
+    client.api(:find, :forum_posts, 1)
+    => #<TeamSnap::Response:...>
+
+    # search and other 'queries' (arguments patch 'as-is')
+    client.api(:search, TeamSnap::ForumPost, {:forum_topic_id => 2})
+    => #<TeamSnap::Response:...>
+
+    # create (arguments post in template data format)
+    client.api(:create, :forum_post, forum_post_success)
+    => #<TeamSnap::Response:...>
+
+    # update (arguments post in template data format)
+    client.api(:update, TeamSnap::ForumPost, forum_patch_success)
+    => #<TeamSnap::Response:...>
+
+    # delete
+    client.api(:delete, :forum_posts, 1)
+    => #<TeamSnap::Response:...>
+
+    # commands (arguments post 'as-is')
+    client.api(:command_name, :forum_post, {})
+    => #<TeamSnap::Response:...>
+
+    # queries (arguments sent in href key/value pairs)
+    client.api(:query_name, :members, {})
+    => #<TeamSnap::Response:...>
+
 
 
 ## Todo
 
-- Literate style docs?
 - Cache items with threadsafe Hash (https://github.com/headius/thread_safe).
-- Implement create, update and delete.

data/lib/config/inflecto.rb

@@ -0,0 +1,13 @@
+Inflecto.inflections do |inflect|
+  inflect.irregular "broadcast_sms", "broadcast_smses"
+  inflect.irregular "division_member_preferences", "division_members_preferences"
+  inflect.irregular "division_preferences", "divisions_preferences"
+  inflect.irregular "member_preferences", "member_preferences"
+  inflect.irregular "member_preferences", "members_preferences"
+  inflect.irregular "opponent_results", "opponent_results"
+  inflect.irregular "opponent_results", "opponents_results"
+  inflect.irregular "team_preferences", "team_preferences"
+  inflect.irregular "team_preferences", "teams_preferences"
+  inflect.irregular "team_results", "team_results"
+  inflect.irregular "team_results", "teams_results"
+end

data/lib/config/oj.rb

@@ -0,0 +1,5 @@
+Oj.default_options = {
+  :mode => :compat,
+  :symbol_keys => true,
+  :class_cache => true
+}

data/lib/teamsnap.rb

@@ -1,219 +1,61 @@
-require "faraday"
-require "typhoeus"
-require "typhoeus/adapters/faraday"
-require "oj"
-require "inflecto"
-require "virtus"
-require "date"
-require "securerandom"
+%w(
+    faraday typhoeus typhoeus/adapters/faraday oj inflecto virtus
+    date securerandom
+  ).each { |x| require x }
 
-require_relative "teamsnap/version"
-
-Oj.default_options = {
-  :mode => :compat,
-  :symbol_keys => true,
-  :class_cache => true
-}
-
-Faraday::Request.register_middleware(
-  :teamsnap_auth_middleware => -> { TeamSnap::AuthMiddleware }
-)
-
-Inflecto.inflections do |inflect|
-  inflect.irregular "broadcast_sms", "broadcast_smses"
-  inflect.irregular "member_preferences", "member_preferences"
-  inflect.irregular "member_preferences", "members_preferences"
-  inflect.irregular "opponent_results", "opponent_results"
-  inflect.irregular "opponent_results", "opponents_results"
-  inflect.irregular "team_preferences", "team_preferences"
-  inflect.irregular "team_preferences", "teams_preferences"
-  inflect.irregular "team_results", "team_results"
-  inflect.irregular "team_results", "teams_results"
-end
+%w(
+    config/inflecto config/oj teamsnap/version teamsnap/api
+    teamsnap/auth_middleware teamsnap/client teamsnap/collection teamsnap/item
+    teamsnap/response teamsnap/structure
+  ).each { |x| require_relative x }
 
 module TeamSnap
-  EXCLUDED_RELS = %w(me apiv2_root root self dude sweet random xyzzy schemas)
+  EXCLUDED_RELS = %w(me apiv2_root root self dude sweet random xyzzy schemas
+                     authorization plans_all tsl_photos)
   DEFAULT_URL = "https://apiv3.teamsnap.com"
   Error = Class.new(StandardError)
   NotFound = Class.new(TeamSnap::Error)
 
-  class AuthMiddleware < Faraday::Middleware
-    def initialize(app, options)
-      @options = options
-      super(app)
-    end
-
-    def call(env)
-      if token
-        env[:request_headers].merge!({"Authorization" => "Bearer #{token}"})
-      elsif client_id && client_secret
-        query_params = Hash[URI.decode_www_form(env.url.query || "")]
-          .merge({
-            hmac_client_id: client_id,
-            hmac_nonce: SecureRandom.uuid,
-            hmac_timestamp: Time.now.to_i
-          })
-        env.url.query = URI.encode_www_form(query_params)
-
-        env.request_headers["X-Teamsnap-Hmac"] = OpenSSL::HMAC.hexdigest(
-          digest, client_secret, message_hash(env)
-        )
-      end
-
-      @app.call(env)
-    end
-
-    def token
-      @token ||= @options[:token]
-    end
-
-    def client_id
-      @client_id ||= @options[:client_id]
-    end
-
-    def client_secret
-      @client_secret ||= @options[:client_secret]
-    end
-
-    def digest
-      OpenSSL::Digest.new("sha256")
-    end
-
-    def message_hash(env)
-      digest.hexdigest(
-        query_string(env) + message(env)
-      )
-    end
-
-    def query_string(env)
-      "/?" + env.url.query.to_s
-    end
-
-    def message(env)
-      env.body || ""
-    end
-  end
-
   class << self
-    def collection(href, resp, parsed_collection)
-      Module.new do
-        define_singleton_method(:included) do |descendant|
-          descendant.send(:include, TeamSnap::Item)
-          descendant.extend(TeamSnap::Collection)
-          descendant.instance_variable_set(:@href, href)
-          descendant.instance_variable_set(:@resp, resp)
-          descendant.instance_variable_set(:@parsed_collection, parsed_collection)
-        end
-      end
-    end
-
-    def hashify(arr)
-      arr.to_h
-    rescue NoMethodError
-      arr.inject({}) { |hash, (key, value)| hash[key] = value; hash }
-    end
+    attr_accessor :client_id, :client_secret, :root_client, :token, :url
 
     def init(opts = {})
-      opts[:url] ||= DEFAULT_URL
-      unless opts.include?(:token) || (
-        opts.include?(:client_id) && opts.include?(:client_secret)
-      )
-        raise ArgumentError.new(
-          "You must provide a :token or :client_id and :client_secret pair to '.init'"
-        )
-      end
-
-      self.client = Faraday.new(
-        :url => opts.fetch(:url),
-        :parallel_manager => Typhoeus::Hydra.new
-      ) do |c|
-        c.request :teamsnap_auth_middleware, {
-          :token => opts[:token],
-          :client_id => opts[:client_id],
-          :client_secret => opts[:client_secret]
-        }
-        c.adapter :typhoeus
+      unless opts[:token] || (opts[:client_id] && opts[:client_secret])
+        raise ArgumentError.new("You must provide a :token or :client_id and :client_secret pair to '.init'")
       end
 
-      collection = TeamSnap.run_init(:get, "/", {})
+      ##   setup variables required
+      self.client_id = opts.fetch(:client_id) {}
+      self.client_secret = opts.fetch(:client_secret) {}
+      self.token = opts.fetch(:token) {}
+      self.url = opts.fetch(:url) { DEFAULT_URL }
 
-      classes = []
+      ##   create universally accessible TeamSnap.root_client
+      self.root_client = TeamSnap::Client.new(:token => token)
 
-      schema = collection
-        .fetch(:links) { [] }
-        .find { |link| link[:rel] == "schemas" } || {}
-
-      if schema[:href]
-        href_to_rel = collection
-          .fetch(:links) { [] }
-          .reject { |link| EXCLUDED_RELS.include?(link[:rel]) }
-          .map { |link| [link[:href], link[:rel]]}
-          .to_h
-
-        resp = client.get(schema[:href])
-        if resp.status == 200
-          collections = Oj.load(resp.body)
-          classes = collections.map { |collection|
-            col = collection.fetch(:collection) { {} }
-            if rel = href_to_rel[col[:href]]
-              create_collection_class(rel, col[:href], nil, col)
-            end
-          }
-          .compact
-        else
-          error_message = TeamSnap.parse_error(resp)
-          raise TeamSnap::Error.new(error_message)
-        end
-      else
-        client.in_parallel do
-          classes = collection
-            .fetch(:links) { [] }
-            .map { |link| classify_rel(link) }
-            .compact
-        end
-      end
-      classes.each { |cls| cls.parse_collection }
+      ##   Make the apiv3 root call. collection is parsed JSON
+      collection = TeamSnap.run(root_client, :get, "/", {})
 
-      apply_endpoints(self, collection) && true
-    end
+      ##   Setup Dynamic Classes from the collection
+      TeamSnap::Structure.init(root_client, collection)
 
-    def run_init(via, href, args = {}, opts = {})
-      begin
-        resp = client_send(via, href, args)
-      rescue Faraday::TimeoutError
-        warn("Connection to API failed. Initializing with empty class structure")
-        {:links => []}
-      else
-        if resp.success?
-          Oj.load(resp.body).fetch(:collection)
-        else
-          error_message = parse_error(resp)
-          raise TeamSnap::Error.new(error_message)
-        end
-      end
+      ##   Queries and Commands parsing for shortcut methods
+      TeamSnap::Collection.apply_endpoints(self, collection) && true
     end
 
-    def run(via, href, args = {})
-      resp = client_send(via, href, args)
-      if resp.success?
-        Oj.load(resp.body).fetch(:collection)
-      else
-        if resp.headers["content-type"].match("json")
-          error_message = parse_error(resp)
-          raise TeamSnap::Error.new(error_message)
-        else
-          raise TeamSnap::Error.new("`#{via}` call was unsuccessful. " +
-            "Unexpected response content-type. " +
-            "Check TeamSnap APIv3 connection")
-        end
-      end
+    def run(client, via, href, args = {})
+      resp = client_send(client, via, href, args)
+      return TeamSnap::Response.load_collection(resp)
+    rescue Faraday::TimeoutError
+      warn("Connection to API failed with TimeoutError")
+      {:links => []}
     end
 
-    def client_send(via, href, args)
+    def client_send(client, via, href, args)
       case via
-      when :get
+      when :get, :delete
         client.send(via, href, args)
-      when :post
+      when :patch, :post
         client.send(via, href) do |req|
           req.body = Oj.dump(args)
         end
@@ -222,187 +64,5 @@ module TeamSnap
       end
     end
 
-    def parse_error(resp)
-      begin
-        Oj.load(resp.body)
-          .fetch(:collection)
-          .fetch(:error)
-          .fetch(:message)
-      rescue KeyError
-        resp.body
-      end
-    end
-
-    def load_items(collection)
-      collection
-        .fetch(:items) { [] }
-        .map { |item|
-          data = parse_data(item).merge(:href => item[:href])
-          type = type_of(item)
-          cls = load_class(type, data)
-
-          cls.new(data).tap { |obj|
-            obj.send(:load_links, item.fetch(:links) { [] })
-          }
-        }
-    end
-
-    def apply_endpoints(obj, collection)
-      collection
-        .fetch(:queries) { [] }
-        .each { |endpoint| register_endpoint(obj, endpoint, :via => :get) }
-
-      collection
-        .fetch(:commands) { [] }
-        .each { |endpoint| register_endpoint(obj, endpoint, :via => :post) }
-    end
-
-    private
-
-    attr_accessor :client
-
-    def classify_rel(link)
-      return if EXCLUDED_RELS.include?(link.fetch(:rel))
-
-      rel = link.fetch(:rel)
-      href = link.fetch(:href)
-      resp = client.get(href)
-
-      create_collection_class(rel, href, resp, nil)
-    end
-
-    def create_collection_class(rel, href, resp, collection)
-      name = Inflecto.classify(rel)
-      TeamSnap.const_set(
-        name, Class.new { include TeamSnap.collection(href, resp, collection) }
-      ) unless TeamSnap.const_defined?(name, false)
-    end
-
-    def register_endpoint(obj, endpoint, opts)
-      rel = endpoint.fetch(:rel)
-      href = endpoint.fetch(:href)
-      valid_args = endpoint.fetch(:data) { [] }
-        .map { |datum| datum.fetch(:name).to_sym }
-      via = opts.fetch(:via)
-
-      obj.define_singleton_method(rel) do |*args|
-        args = Hash[*args]
-
-        unless args.all? { |arg, _| valid_args.include?(arg) }
-          raise ArgumentError.new(
-            "Invalid argument(s). Valid argument(s) are #{valid_args.inspect}"
-          )
-        end
-
-        TeamSnap.load_items(
-          TeamSnap.run(via, href, args)
-        )
-      end
-    end
-
-    def parse_data(item)
-      data = item
-        .fetch(:data)
-        .map { |datum|
-          name = datum.fetch(:name)
-          value = datum.fetch(:value)
-          type = datum.fetch(:type) { :default }
-
-          value = DateTime.parse(value) if value && type == "DateTime"
-
-          [name, value]
-        }
-      TeamSnap.hashify(data)
-    end
-
-    def type_of(item)
-      item
-        .fetch(:data)
-        .find { |datum| datum.fetch(:name) == "type" }
-        .fetch(:value)
-    end
-
-    def load_class(type, data)
-      TeamSnap.const_get(Inflecto.camelize(type), false).tap { |cls|
-        unless cls.include?(Virtus::Model::Core)
-          cls.class_eval do
-            include Virtus.value_object
-
-            values do
-              attribute :href, String
-              data.each { |name, value| attribute name, value.class }
-            end
-          end
-        end
-      }
-    end
-  end
-
-  module Item
-    private
-
-    def load_links(links)
-      links.each do |link|
-        next if EXCLUDED_RELS.include?(link.fetch(:rel))
-
-        rel = link.fetch(:rel)
-        href = link.fetch(:href)
-        is_singular = rel == Inflecto.singularize(rel)
-
-        define_singleton_method(rel) {
-          instance_variable_get("@#{rel}") || instance_variable_set(
-            "@#{rel}", -> {
-              coll = TeamSnap.load_items(
-                TeamSnap.run(:get, href)
-              )
-              is_singular ? coll.first : coll
-            }.call
-          )
-        }
-      end
-    end
-  end
-
-  module Collection
-    def href
-      self.instance_variable_get(:@href)
-    end
-
-    def resp
-      self.instance_variable_get(:@resp)
-    end
-
-    def parsed_collection
-      self.instance_variable_get(:@parsed_collection)
-    end
-
-    def parse_collection
-      if resp
-        if resp.status == 200
-          collection = Oj.load(resp.body)
-            .fetch(:collection) { [] }
-        else
-          error_message = TeamSnap.parse_error(resp)
-          raise TeamSnap::Error.new(error_message)
-        end
-      elsif parsed_collection
-        collection = parsed_collection
-      end
-
-      TeamSnap.apply_endpoints(self, collection)
-      enable_find if respond_to?(:search)
-    end
-
-    private
-
-    def enable_find
-      define_singleton_method(:find) do |id|
-        search(:id => id).first.tap do |object|
-          raise TeamSnap::NotFound.new(
-            "Could not find a #{self} with an id of '#{id}'."
-          ) unless object
-        end
-      end
-    end
   end
 end