task_helper 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 51608c11313019a92faf2883d4eccefbff7ee436
+  data.tar.gz: 50fbda3969ac23aaeca972c5374f6dbc476a633f
+SHA512:
+  metadata.gz: 9c2626aba9b0d710000be2c6d3f4c5fb82fb303dfbf101dd731f45be5fd56246560ac80048118354078d003709d95a0fae6a8c4a5943d1693a75727c664240fe
+  data.tar.gz: db5c31c47fcf0fe63196fd1e2bd13c34a66d88147559b2891674fd05c7ba32fcc70697e805b38953f6dc1b70be168561fa12ab25cbb8efbbadb486b1f16f2b7a

data/.gitignore

@@ -0,0 +1,30 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/support/fixtures/**/*.json
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalisation:
+/.bundle/
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+--require spec_helper

data/.ruby-gemset

@@ -0,0 +1 @@
+mth

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.1.1

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 JC Wilcox
+
+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,317 @@
+# TaskHelper
+
+Offers a clean Ruby interface for interacting with
+the MyTaskHelper.com API.
+
+Includes wrapper classes for Database, Form, Field, and Record.
+These classes offer shorthand methods for common API calls, as
+well as convenient methods to read the data returned from the API.
+
+Also includes an `API` module, which can be used to directly access
+any available route in the API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'task_helper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install task_helper
+
+## Usage
+
+### Resources
+
+TaskHelper provides a ruby interface to four MyTaskHelper resources:
+
+* Database
+* Form
+* Field
+* Record
+
+This gem offers classes to interact with each of these resources in
+an ActiveRecord like fashion. Each class contains methods for fetching
+objects from the API, readers for attributes of retrieved objects,
+and methods to navigate between related resources.
+
+#### Database
+
+This class offers functionality to retrieve and interact with databases
+in MyTaskHelper.
+
+##### API Access Methods
+
+The `TaskHelper::Database` class offers singleton methods, which mimic the
+functionality of their ActiveRecord counterparts.
+
+###### All
+
+`TaskHelper::Database.all` returns an Array of all databases returned from
+'mytaskhelper.com/apps.json'.
+
+    TaskHelper::Database.all # GET 'apps.json'
+    => [#<TaskHelper::Database>, ...]
+
+###### Find
+
+`TaskHelper::Database.find` accepts a string corresponding to the id of a
+database in MyTaskHelper, and returns the database (if any) found at
+'mytaskhelper.com/apps/:id.json'.
+
+    TaskHelper::Database.find('foobar123') # GET 'apps/foobar123.json'
+    => #<TaskHelper::Database id: 'foobar123'>
+
+###### Find By
+
+`TaskHelper::Database.find_by` accepts a hash of search parameters, passes those
+parameters to the 'mytaskhelper.com/apps/search.json' route, and returns the
+corresponding database (if any are found).
+
+    TaskHelper::Database.find_by(name: 'Foo Bar') # GET 'apps/search.json?name=Foo%20Bar'
+    => #<TaskHelper::Database name: 'Foo Bar'>
+
+##### Attributes
+
+A database object contains the following attributes:
+
+* id
+* name
+* dtypes_count
+* entities_count
+* properties_count
+* created_at
+* updated_at
+
+##### Relations
+
+`TaskHelper::Database` objects respond to the `.forms` method, which returns
+an Array of `TaskHelper::Form`s associated with that database.
+
+    database = TaskHelper::Database.find('foobar123')
+    database.forms # GET 'apps/foobar123/entities.json'
+    => [#<TaskHelper::Form app_id: 'foobar123'>, ...]
+
+#### Form
+
+This class offers functionality to retrieve and interact with forms
+in MyTaskHelper.
+
+##### API Access Methods
+
+The `TaskHelper::Form` class offers singleton methods, which mimic the
+functionality of their ActiveRecord counterparts.
+
+###### All
+
+`TaskHelper::Form.all` returns an Array of all forms associated with
+any database from 'mytaskhelper.com/apps.json'.
+
+    TaskHelper::Form.all
+    => [#<TaskHelper::Form>, ...]
+
+###### Find
+
+`TaskHelper::Form.find` accepts two named parameters: database and form.
+Each parameter should be a string corresponding to the id of that resource,
+and returns the form (if any) found at
+'mytaskhelper.com/apps/:database/entities/:form.json'.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    TaskHelper::Form.find(params) # GET 'apps/foobar123/entities/baz456.json'
+    => #<TaskHelper::Form id: 'baz456'>
+
+###### Find By
+
+`TaskHelper::Form.find_by` accepts a hash of search parameters, passes those
+parameters to the 'mytaskhelper.com/apps/search/entities/search.json' route,
+and returns the corresponding form (if any are found).
+
+    search = { database_name: 'Foo Bar', form_name: 'Baz' }
+    TaskHelper::Form.find_by(search) # GET 'apps/search/entities/search.json?database_name=Foo%20Bar&form_name=Baz'
+    => #<TaskHelper::Form name: 'Baz'>
+
+##### Attributes
+
+A form object contains the following attributes:
+
+* id
+* app_id
+* name
+* desc
+* post_action
+* position
+* sort_by
+* asc
+* per_page
+* allow_delete
+* new_widget
+* records_widget
+* target_page
+* allow_database
+* send_emails
+* settings
+
+##### Relations
+
+`TaskHelper::Form` objects respond to the `.database` method, which returns
+the database associated with the form.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    form.database # GET 'apps/foobar123.json'
+    => #<TaskHelper::Database id: 'foobar123'>
+
+`TaskHelper::Form` objects also respond to the `.fields` method, which returns
+an Array of `TaskHelper::Field`s associated with that form.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    form.fields # GET 'apps/foobar123/entities/baz456/properties.json'
+    => [#<TaskHelper::Field entity_id: 'baz456'>, ...]
+
+`TaskHelper::Form` objects also respond to the `.records` method, which returns
+a Lazy Enumerator for fetching the records associated with the form.
+The enumerator loops through the pages of records found at
+'mytaskhelper.com/apps/:app_id/dtypes/entity/:entity_id.json',
+and flattens the results into an Enumerator of `TaskHelper::Record`s.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    records = form.records
+    => #<Enumerator::Lazy: #<Enumerator::Lazy: 1..5>:flat_map> # 5 pages of records
+    records.first(3) # GET 'apps/foobar123/dtypes/entity/baz456.json?page=1'
+    => [#<TaskHelper::Record entity_id: 'baz456'>, ...]
+
+#### Field
+
+This class offers functionality for interacting with fields
+in MyTaskHelper.
+
+##### API Access
+
+Presently, `TaskHelper::Field`s can only be retrieved through their
+associated form. (see `TaskHelper::Form#fields` above)
+
+##### Attributes
+
+A field object contains the following attributes:
+
+* id
+* entity_id
+* name
+* desc
+* type_name
+* default
+* validate_options
+* position
+* visible
+* size
+* cols
+* rows
+* initial
+* pretty_type_name
+* formula_field
+* formula_operation
+* start_from
+* step
+
+##### Relations
+
+`TaskHelper::Field` objects respond to the `.form` method, which returns
+the form associated with the field.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    => #<TaskHelper::Form id: 'baz456'>
+    field = form.fields.first
+    => #<TaskHelper::Field entity_id: 'baz456'>
+    field.form
+    => #<TaskHelper::Form id: 'baz456'>
+
+#### Record
+
+This class offers functionality for interacting with form records
+in MyTaskHelper.
+
+##### API Access
+
+Presently, `TaskHelper::Records`s can only be retrieved through their
+associated form. (see `TaskHelper::Form#records` above)
+
+##### Attributes
+
+A record object contains the following attributes:
+
+* id
+* app_id
+* entity_id
+* approved
+* values
+* created_at
+* updated_at
+
+##### Accessing Values
+
+`TaskHelper::Record#values` returns a hash, with the ids of fields associated
+with the record's form as keys, and the values of those fields for the record
+as values.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    => #<TaskHelper::Form id: 'baz456'>
+    record = form.records.first
+    => #<TaskHelper::Record entity_id: 'baz456'>
+    record.values
+    => { 'abc123' => 'Yes', 'def456' => false, 'ghi789' => 17 }
+
+For convenience, `TaskHelper::Record` objects offer a `.pretty_values` method,
+which parses the values hash, and replaces the field ids with field names.
+
+    form.fields
+    => [#<TaskHelper::Field id: 'abc123' name: 'Winner?'>, ...]
+    record.pretty_values
+    => { 'Winner?' => 'Yes', 'Jackpot?' => false, 'Prize' => 17 }
+
+The value of a given field can be also be accessed by `TaskHelper::Record#[]`
+which accepts a field name, and returns the value of that field.
+
+    record['Prize']
+    => 17
+
+##### Relations
+
+`TaskHelper::Record` objects respond to the `.form` method, which returns
+the form associated with the record.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    => #<TaskHelper::Form id: 'baz456'>
+    record = form.records.first
+    => #<TaskHelper::Record entity_id: 'baz456'>
+    record.form
+    => #<TaskHelper::Form id: 'baz456'>
+
+`TaskHelper::Record` objects also respond to the `.fields` method, which
+returns and array of fields associated with the record's form.
+
+    params = { database: 'foobar123', form: 'baz456' }
+    form = TaskHelper::Form.find(params)
+    => #<TaskHelper::Form id: 'baz456'>
+    record = form.records.first
+    => #<TaskHelper::Record entity_id: 'baz456'>
+    record.fields
+    => [#<TaskHelper::Field entity_id: 'baz456'>, ...]
+
+## Contributing
+
+1. Fork it ( http://github.com/xDAGRONx/task_helper/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,4 @@
+require "bundler/gem_tasks"
+require 'task_helper'
+
+load './lib/tasks/spec_setup.rake'

data/lib/task_helper/api/cache.rb

@@ -0,0 +1,28 @@
+module TaskHelper
+  module API
+    class Cache
+      def initialize(limit: 10)
+        @limit = limit
+        @calls = []
+      end
+
+      def get(**args)
+        new_call = Call.new(args)
+        cached_call = @calls.find { |call| call == new_call }
+        if cached_call
+          cached_call.run
+        else
+          @calls << new_call
+          sort_calls.pop if @calls.size > @limit
+          new_call.run
+        end
+      end
+
+      private
+
+      def sort_calls
+        @calls.sort! { |x, y| y.time <=> x.time }
+      end
+    end
+  end
+end

data/lib/task_helper/api/call.rb

@@ -0,0 +1,48 @@
+module TaskHelper
+  module API
+    class Call
+      MissingAPIKey = Class.new(StandardError)
+
+      attr_reader :route, :params, :time
+      protected :route, :params
+
+      def initialize(route:, params: {}, timeout: 314, time: Time.now)
+        @params = { rest_api_key: API.rest_api_key }.merge(params)
+        if @params[:rest_api_key].nil?
+          raise MissingAPIKey, "Rest API key not provided. " \
+            "Either pass it as a param or use " \
+            "'TaskHelper::API.rest_api_key = key' " \
+            "to set it for all future calls."
+        end
+        @route = "#{BASE_URL}/#{route}"
+        @timeout = timeout
+        @time = time
+        set_end_time
+      end
+
+      def run
+        @time = Time.now
+        if expired? || !@result
+          set_end_time
+          @result = HTTParty.get(@route, query: @params).parsed_response
+        else
+          @result
+        end
+      end
+
+      def expired?
+        @end_time < Time.now
+      end
+
+      def ==(other_call)
+        @route == other_call.route && @params == other_call.params
+      end
+
+      private
+
+      def set_end_time
+        @end_time = @time + @timeout
+      end
+    end
+  end
+end

data/lib/task_helper/api.rb

@@ -0,0 +1,23 @@
+module TaskHelper
+  module API
+    BASE_URL = 'https://mytaskhelper.com'
+
+    class << self
+      attr_accessor :rest_api_key
+    end
+
+    def get(args)
+      @cache.get(args)
+    end
+
+    def set_cache(args={})
+      @cache = Cache.new(args)
+    end
+
+    def self.extended(base)
+      base.set_cache
+    end
+
+    extend self
+  end
+end

data/lib/task_helper/base.rb

@@ -0,0 +1,55 @@
+module TaskHelper
+  class Base
+    class << self
+      attr_accessor :data_members
+      protected :data_members=
+    end
+
+    def initialize(args = {})
+      @info = {}
+      (args || {}).each_pair do |k, v|
+        @info[k.to_sym] = v
+      end
+    end
+
+    def to_h
+      @info.dup
+    end
+
+    def id
+      fetch(:id)
+    end
+
+    def created_at
+      Time.parse(fetch(:created_at)) if fetch(:created_at)
+    end
+
+    def updated_at
+      Time.parse(fetch(:updated_at)) if fetch(:updated_at)
+    end
+
+    def ==(other)
+      id == other.id
+    end
+
+    protected
+
+    def fetch(attribute)
+      @info[attribute.to_sym]
+    end
+
+    private
+
+    def self.inherited(base)
+      base.extend(API)
+      base.data_members = %i(id)
+    end
+
+    def self.data_member(*names)
+      names.each do |name|
+        define_method(name) { fetch(name.to_sym) }
+        data_members << name.to_sym
+      end
+    end
+  end
+end

data/lib/task_helper/database.rb

@@ -0,0 +1,30 @@
+module TaskHelper
+  class Database < Base
+    data_member :name, :dtypes_count, :entities_count, :properties_count
+
+    def self.all
+      get(route: 'apps.json')['databases'].map { |d| new d }
+    end
+
+    def self.find_by_name(name)
+      find_by(name: name)
+    end
+
+    def self.find_by(search)
+      if response = get(route: 'apps/search.json', params: search)
+        new response['database'] if response['database']
+      end
+    end
+
+    def self.find(id)
+      if response = get(route: "apps/#{id}.json")
+        new response['database'] if response['database']
+      end
+    end
+
+    def forms
+      @forms ||= Form.get(route: "apps/#{id}/entities.json")['forms']
+        .map { |form| Form.new(form, database: self) }
+    end
+  end
+end

data/lib/task_helper/field.rb

@@ -0,0 +1,20 @@
+module TaskHelper
+  class Field < Base
+    data_member :entity_id, :name, :desc, :type_name, :default,
+                :validate_options, :position, :visible, :size, :cols,
+                :rows, :initial, :pretty_type_name, :formula_field,
+                :formula_operation, :start_from, :step
+
+    def initialize(args = {}, form: nil, **params)
+      @form = form
+      super(args.merge(params))
+    end
+
+    def form
+      @form ||=
+        Database.all.each do |d|
+          break Form.find(database: d.id, form: entity_id) || next
+        end
+    end
+  end
+end

data/lib/task_helper/form.rb

@@ -0,0 +1,57 @@
+module TaskHelper
+  class Form < Base
+    data_member :app_id, :name, :desc, :post_action, :position, :sort_by, :asc,
+                :per_page, :allow_delete, :new_widget, :records_widget,
+                :target_page, :allow_database, :send_emails, :settings
+
+    def self.all
+      Database.all.lazy.flat_map { |db| db.forms }
+    end
+
+    def self.find_by(search)
+      if response = get(route: 'apps/search/entities/search.json', params: search)
+        new response['form'] if response['form']
+      end
+    end
+
+    def self.find(database:, form:)
+      if response = get(route: "apps/#{database}/entities/#{form}.json")
+        new response['form'] if response['form']
+      end
+    end
+
+    def initialize(args = {}, database: nil, **params)
+      @database = database
+      super(args.merge(params))
+    end
+
+    def database
+      @database ||= Database.find(app_id)
+    end
+
+    def fields
+      @fields ||= Field.get(
+        route: "apps/#{app_id}/entities/#{id}/properties.json")['fields']
+          .map { |field| Field.new(field, form: self) }
+    end
+
+    def records
+      if fields.any?
+        @records ||= (1..page_count).lazy.flat_map do |page|
+          record_page(page).lazy.map { |record| Record.new(record, form: self) }
+        end
+      end
+    end
+
+    private
+
+    def page_count
+      database.dtypes_count / per_page + 1
+    end
+
+    def record_page(page = 1)
+      Record.get(route: "apps/#{app_id}/dtypes/entity/#{id}.json",
+                 params: { page: page })['records']
+    end
+  end
+end

data/lib/task_helper/record.rb

@@ -0,0 +1,29 @@
+module TaskHelper
+  class Record < Base
+    data_member :app_id, :entity_id, :approved, :values
+
+    def initialize(args = {}, form: nil, **params)
+      @form = form
+      super(args.merge(params))
+    end
+
+    def form
+      @form ||= Form.find(database: app_id, form: entity_id)
+    end
+
+    def fields
+      form.fields
+    end
+
+    def [](field_name)
+      pretty_values[field_name]
+    end
+
+    def pretty_values
+      @pretty_values ||= values.each_with_object({}) do |(k,v), r|
+        field = fields.find { |f| f.id == k }
+        r[field.name] = v
+      end
+    end
+  end
+end