prontoforms 0.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aa48580fd863fe9681a3ba6f901415e0775c082929532bd63e8c93de86bf121
-  data.tar.gz: 5a21dd84aef6f4da5d285fa1587aebf79fec6d279aa10048efa0f1c6a29a1f48
+  metadata.gz: cf9bb12142b5957e341f48804ce06b73f8842cdcbe8e2831e34823299ca73017
+  data.tar.gz: c3760f082616943fa75dd0fad8f4bf0554390d75bea741f448baead8ce97bdfc
 SHA512:
-  metadata.gz: 80299aa7c0a311c26467325e425b6f9ec39c5eda4692a9d613b40a07fe267b7751a88ecdca714071292a6f827520c35781bba0202023e9fd877dd3d6e851e0d4
-  data.tar.gz: '08f2da72649027dee6103e24b7d932047069d9e9ebabd36b1688928ec6f2359100d4d2d6a2e22eeef4e17e1b5941752b306b9351c37a86f65dc980adf1c0c15a'
+  metadata.gz: 4a5da5f5afda87fd00f326deba55c97169aad8918347f308df002c2525420e92d8a22983199a2bf498afa0b8a55ea32be25549a5b20ce86fb0578123100733c8
+  data.tar.gz: 8f0312762f55f92b0a3d5383fef1cc1558b9e65a7ba8d7c2f770c63a97d0ef695976e542459b839bf76966f05daf776c4b8aff9dad5ca4dad690448ed64c31da

data/.github/workflows/checks.yml

@@ -0,0 +1,66 @@
+name: Checks
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  test:
+    name: Run automated tests
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up ruby
+      uses: actions/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+
+    - name: Install dependencies
+      run: |
+        gem install bundler -v 2.1.4
+        bundle install
+
+    - name: Test
+      run: bundle exec rake
+
+    - name: Report test coverage
+      uses: paambaati/codeclimate-action@v2.7.4
+      env:
+        CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
+
+  rubocop:
+    name: Rubocop
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: 2.6
+
+    - name: Install Code Scanning integration
+      run: bundle add code-scanning-rubocop --version 0.3.0 --skip-install
+
+    - name: Install dependencies
+      run: |
+        gem install bundler -v 2.1.4
+        bundle install
+
+    - name: Rubocop run
+      run: |
+        bash -c "
+          bundle exec rubocop --require code_scanning --format CodeScanning::SarifFormatter -o rubocop.sarif
+          [[ $? -ne 2 ]]
+        "
+
+    - name: Upload Sarif output
+      uses: github/codeql-action/upload-sarif@v1
+      with:
+        sarif_file: rubocop.sarif

data/.gitignore

@@ -7,5 +7,9 @@
 /spec/reports/
 /tmp/
 
+Gemfile.lock
+
 # rspec failure tracking
 .rspec_status
+
+**/.DS_Store

data/.rubocop.yml

@@ -0,0 +1,12 @@
+AllCops:
+  TargetRubyVersion: 2.6
+  NewCops: enable
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Layout/FirstHashElementIndentation:
+  Enabled: false

data/.travis.yml

@@ -1,6 +1,16 @@
 ---
+os: linux
+dist: xenial
 language: ruby
 cache: bundler
 rvm:
   - 2.6.0
 before_install: gem install bundler -v 2.1.4
+before_script:
+  - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter
+  - chmod +x ./cc-test-reporter
+  - ./cc-test-reporter before-build
+script:
+  - bundle exec rspec
+after_script:
+  - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# prontoforms changelog
+
+## [Unreleased]
+### Added
+* Added Form resource
+* Can retrieve forms by form space
+
+## [v0.3.1] - 15 Sep 2020
+### Removed
+* Unused `InvalidHttpVerb` error class
+
+## [v0.3.0] - 15 Sep 2020
+### Added
+* Autogenerated documentation via YARD.
+
+### Changed
+* Errors now provide a message describing the issue
+* `ProntoForms::Client` now raises error on invalid resource definition.
+
+## [v0.2.0] - 26 Aug 2020
+### Bugfixes
+* Corrected pagination of resource lists
+
+## [v0.1.0] - 25 Aug 2020
+* Initial release
+
+[Unreleased]: https://github.com/paulholden2/prontoforms/compare/v0.3.1...HEAD
+[v0.1.0]: https://github.com/paulholden2/prontoforms/releases/tag/v0.1.0
+[v0.2.0]: https://github.com/paulholden2/prontoforms/releases/tag/v0.2.0
+[v0.3.0]: https://github.com/paulholden2/prontoforms/releases/tag/v0.3.0
+[v0.3.1]: https://github.com/paulholden2/prontoforms/releases/tag/v0.3.1

data/Gemfile

@@ -1,4 +1,10 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in prontoforms.gemspec
 gemspec
+
+group :development, :test do
+  gem 'simplecov', '~> 0.17.1'
+end

data/README.md

@@ -1,7 +1,12 @@
 # ProntoForms
 
+[![Build Status](https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fpaulholden2%2Fprontoforms%2Fbadge%3Fref%3Dmaster&style=flat)](https://actions-badge.atrox.dev/paulholden2/prontoforms/goto?ref=master) [![Gem Version](https://badge.fury.io/rb/prontoforms.svg)](https://badge.fury.io/rb/prontoforms) [![Inline docs](http://inch-ci.org/github/paulholden2/prontoforms.svg?branch=master)](http://inch-ci.org/github/paulholden2/prontoforms) [![Maintainability](https://api.codeclimate.com/v1/badges/e47cd40058313e1c1c38/maintainability)](https://codeclimate.com/github/paulholden2/prontoforms/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/e47cd40058313e1c1c38/test_coverage)](https://codeclimate.com/github/paulholden2/prontoforms/test_coverage)
+
 A library for interacting with the ProntoForms REST API in Ruby applications.
 
+Note: version 0.4.0 included a breaking change, and has been yanked from
+RubyGems. If you are using it, please upgrade to 1.x or revert to 0.3.1.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,7 +25,16 @@ Or install it yourself as:
 
 ## Usage
 
-Check back later
+To get started, first [create a ProntoForms API key] in your ProntoForms
+account. Then you can begin using the API client in your Ruby application:
+
+```rb
+client = ProntoForms::Client.new(api_key_id, api_key_secret)
+client.form_spaces # Returns all FormSpaces in your account
+```
+
+Review [the documentation](https://rubydoc.info/github/paulholden2/prontoforms)
+for more information on how to use this library to interact with ProntoForms.
 
 ## Development
 
@@ -37,3 +51,5 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/paulho
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[create a ProntoForms API key]: https://support.prontoforms.com/hc/en-us/articles/217496468-Setup-an-API-Application-on-ProntoForms#Create

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/console

@@ -1,14 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "prontoforms"
+require 'bundler/setup'
+require 'prontoforms'
+require 'irb'
 
-# You can add fixtures and/or initialization code here to make experimenting
-# with your gem easier. You can also use a different console, if you like.
-
-# (If you use this, don't forget to add pry to your Gemfile!)
-# require "pry"
-# Pry.start
-
-require "irb"
 IRB.start(__FILE__)

data/bin/setup

@@ -1,8 +1,8 @@
 #!/usr/bin/env bash
+# frozen_string_literal: true
+
 set -euo pipefail
 IFS=$'\n\t'
 set -vx
 
 bundle install
-
-# Do any other automated setup that you need to do here

data/lib/prontoforms.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 require 'prontoforms/version'
 require 'prontoforms/client'
 
 module ProntoForms
-  class Error < StandardError; end
+  # Base error class.
+  class Error < StandardError
+    attr_reader :message
+
+    def initialize(message)
+      @message = message
+    end
+  end
 end

data/lib/prontoforms/client.rb

@@ -1,40 +1,102 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'json'
 require 'prontoforms/resource_list'
 require 'prontoforms/form_space'
 require 'prontoforms/form_submission'
+require 'prontoforms/user'
 
 module ProntoForms
+  # Allows you to retrieve resources from ProntoForms and perform other
+  # functions with the API.
   class Client
-    attr_reader :api_key_id, :api_key_secret
+    # @return [String] ProntoForms API key ID
+    attr_reader :api_key_id
+    # @return [String] ProntoForms API key secret
+    attr_reader :api_key_secret
 
+    # Create a client and use provided API credentials
+    # @param api_key_id Your ProntoForms REST API key
+    # @param api_key_secret Your ProntoForms REST API secret
     def initialize(api_key_id, api_key_secret)
       @api_key_id = api_key_id
       @api_key_secret = api_key_secret
     end
 
-    def self.resource(method, verb: :get, resource:, url: resource.resource_name)
-      # TODO: Raise error if verb is invalid
-
+    # Defines a resource that can be retrieved in a list
+    # @return [nil]
+    # @api private
+    # @!macro [attach] resource_list
+    #   @method $1
+    #   Retrieve a list of $2 resources
+    #   @return [ResourceList] A ResourceList containing $2 results
+    def self.resource_list(method, resource, url = resource.resource_name)
       define_method(method) do |query: {}|
-        res = connection.send(verb) do |req|
+        res = connection.get do |req|
           req.url url
           query.each { |k, v| req.params[k] = v }
         end
-        if res.success?
-          ResourceList.new(JSON.parse(res.body), 0, 20, method, resource, self)
-        else
-          nil
-        end
+
+        data = JSON.parse(res.body)
+
+        return nil if data.fetch('pageData').size.zero?
+
+        ResourceList.new(data, { 'p' => 0, 's' => 100 }.merge(query), method,
+                         resource, self)
       end
     end
 
-    resource :form_spaces, resource: FormSpace
-    resource :form_submissions, resource: FormSubmission
+    resource_list :form_spaces, FormSpace
+    resource_list :form_submissions, FormSubmission
+
+    # Retrieve a user by identifier
+    # @param id [String] The user identifier
+    # @return [User] A User object for the requested user
+    def user(id)
+      raise ArgumentError, 'id must be provided' if id.nil?
+
+      res = connection.get do |req|
+        req.url "users/#{id}"
+      end
+
+      User.new(JSON.parse(res.body), self)
+    end
+
+    # Retrieve a form space by its identifier
+    # @param id [String] The form space identifier
+    # @return [FormSpace] A FormSpace object
+    def form_space(id)
+      raise ArgumentError, 'id must be provided' if id.nil?
+
+      res = connection.get do |req|
+        req.url "formspaces/#{id}"
+      end
+
+      FormSpace.new(JSON.parse(res.body), self)
+    end
+
+    # Retrieve a form submission by identifier
+    # @param id [String] The form submission identifier
+    # @return [FormSubmission] A FormSubmission object
+    def form_submission(id)
+      return nil if id.nil?
+
+      res = connection.get do |req|
+        req.url "data/#{id}"
+      end
+
+      FormSubmission.new(JSON.parse(res.body), self)
+    end
 
+    # Create a connection that can be used to execute a request against the
+    # ProntoForms API.
+    # @return [Faraday::Connection]
+    # @api private
     def connection
       Faraday.new(url: 'https://api.prontoforms.com/api/1.1') do |conn|
         conn.basic_auth(api_key_id, api_key_secret)
+        conn.use Faraday::Response::RaiseError
       end
     end
   end

data/lib/prontoforms/document.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'prontoforms/resource'
+
+module ProntoForms
+  # A Document is a configuration that generates output data or files when
+  # attached to a form.
+  class Document < Resource
+    def self.resource_name
+      'documents'
+    end
+
+    # @return [String] The Document identifier
+    property :id, key: 'identifier'
+    # @return [String] Document type
+    property :type, key: 'type'
+    # @return [String] Document name
+    property :name, key: 'name'
+    # @return [String] Document descriptiojn
+    property :description, key: 'description'
+    # @return [String] Document form version
+    property :form_document_version, key: 'formDocumentVersion'
+    # @return [Boolean] Whether the document is standard (system generated)
+    property :standard, key: 'standard'
+    # @return [String] Whether the document auto-links to new forms
+    property :auto_link, key: 'autoLink'
+
+    alias standard? standard
+    alias auto_link? auto_link
+  end
+end

data/lib/prontoforms/form.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'prontoforms/resource'
+require 'prontoforms/form_iteration'
+
+module ProntoForms
+  # A form includes inputs, validations, logic, and other configuration that
+  # facilitates data capture for a specific purpose.
+  class Form < Resource
+    def self.resource_name
+      'forms'
+    end
+
+    # @return [String] The Form identifier
+    property :id, key: 'identifier'
+    # @return [String] Form name
+    property :name, key: 'name'
+    # @return [String] Form description
+    property :description, key: 'description'
+    # @return [String] Form state
+    property :state, key: 'state'
+
+    # Get the Form's form space ID
+    # @return [String] Form space identifier
+    def form_space_id
+      parent.id
+    end
+
+    def active_version_id
+      full_data.dig('activeVersion', 'identifier')
+    end
+
+    def current_version
+      res = client.connection.get do |req|
+        req.url "#{url}/iterations/#{active_version_id}"
+      end
+
+      FormIteration.new(JSON.parse(res.body), client, self)
+    end
+
+    def iteration(id)
+      raise ArgumentError, 'id must be provided' if id.nil?
+
+      res = client.connection.get do |req|
+        req.url "#{url}/iterations/#{id}"
+      end
+
+      FormIteration.new(JSON.parse(res.body), client, self)
+    end
+
+    def iterations(query: {})
+      res = client.connection.get do |req|
+        req.url "#{url}/iterations"
+      end
+
+      ResourceList.new(JSON.parse(res.body), {
+        'p' => 0,
+        's' => 100
+      }.merge(query), :iterations, FormIteration, client, self)
+    end
+
+    private
+
+    def full_data
+      return @full_data unless @full_data.nil?
+
+      @full_data = client.form_space(form_space_id).form(id).data
+      @full_data
+    end
+
+    def url
+      "formspaces/#{form_space_id}/forms/#{id}"
+    end
+  end
+end

data/lib/prontoforms/form_iteration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'prontoforms/resource'
+
+module ProntoForms
+  # A form iteration is a form configuration, distinct from a form version
+  # in that version numbers increment when a form iteration is deployed.
+  class FormIteration < Resource
+    def self.resource_name
+      'iterations'
+    end
+
+    # @return [String] The form iteration identifier
+    property :id, key: 'identifier'
+    # @return [Integer] Version number
+    property :version, key: 'version'
+    # @return [String] Form iteration state
+    property :state, key: 'state'
+    # @return [String] Initiation method for the form iteration
+    property :initiation_method, key: 'initiationMethod'
+    # @return [String] Can dispatched forms of this iteration be declined
+    property :dispatched_declinable, key: 'dispatchDeclinable'
+
+    alias can_decline_dispatch? dispatched_declinable
+
+    # @return [Array] Array of document IDs attached to this iteration
+    def document_ids
+      full_data.fetch('documentIds')
+    end
+
+    private
+
+    def full_data
+      return @full_data unless @full_data.nil?
+
+      @full_data = parent.iteration(id).data
+      @full_data
+    end
+  end
+end

data/lib/prontoforms/form_space.rb

@@ -1,10 +1,57 @@
+# frozen_string_literal: true
+
 require 'prontoforms/resource'
+require 'prontoforms/form'
+require 'prontoforms/document'
 
 module ProntoForms
+  # Represents a form space resource in ProntoForms. Form spaces are the
+  # primary organizational unit for forms, data sources, destinations, and
+  # other resources.
   class FormSpace < Resource
+    # @return [String] The FormSpace identifier
     property :id, key: 'identifier'
+    # @return [String] The FormSpace name
     property :name, key: 'name'
+    # @return [String] The address that error emails are sent to
     property :problem_contact_email, key: 'problemContactEmail'
+    # @return [Boolean] Whether updates are automatically pushed to devices
     property :push_updates_to_device, key: 'pushUpdatesToDevice'
+
+    # Get all documents in the form space
+    # @return [ResourceList] A ResourceList containing Document objects
+    def documents
+      res = client.connection.get do |req|
+        req.url "formspaces/#{id}/documents"
+      end
+
+      ResourceList.new(JSON.parse(res.body), {
+        'p' => 0,
+        's' => 100
+      }, :documents, Document, self)
+    end
+
+    def form(form_id)
+      res = client.connection.get do |req|
+        req.url "formspaces/#{id}/forms/#{form_id}"
+      end
+
+      data = JSON.parse(res.body)
+      Form.new(data, client, self)
+    end
+
+    # Get all forms in the form space
+    # @return [ResourceList] A ResourceList containing Form objects
+    def forms(query: {})
+      res = client.connection.get do |req|
+        req.url "formspaces/#{id}/forms"
+        query.each { |k, v| req.params[k] = v }
+      end
+
+      ResourceList.new(JSON.parse(res.body), {
+        'p' => 0,
+        's' => 100
+      }.merge(query), :forms, Form, client, self)
+    end
   end
 end

data/lib/prontoforms/form_submission.rb

@@ -1,36 +1,137 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'prontoforms/resource'
 
 module ProntoForms
+  # A FormSubmission represents submitted form data in ProntoForms. It
+  # includes various metadata about the submission as well.
   class FormSubmission < Resource
-    def self.resource_name() 'data'; end
+    def self.resource_name
+      'data'
+    end
 
+    # @return [String] The FormSubmission identifier
     property :id, key: 'identifier'
+    # @return [String] Submission reference number
     property :reference_number, key: 'referenceNumber'
+    # @return [String] Submission state. One of: Complete, Processing,
+    #                  Dispatched
     property :state, key: 'state'
+    # @return [String] Submission data state
     property :data_state, key: 'dataState'
+    # @return [Boolean] Has the submission data been persisted on the server
     property :data_persisted, key: 'dataPersisted'
+    # @return [String] The form's version identifier
     property :form_version_id, key: 'formVersionId'
+    # @return [String] The form's identifier
     property :form_id, key: 'formId'
+    # @return [String] Submitter's user identifier
     property :user_id, key: 'userId'
+    # @return [String] Submitter's username
     property :username, key: 'username'
-    # Aliases
-    property :data_persisted?, key: 'dataPersisted'
-    property :submitter_id, key: 'userId'
-    property :submitter_username, key: 'username'
 
+    alias data_persisted? data_persisted
+    alias submitter_id user_id
+    alias submitter_username username
+
+    # @return [DateTime] Timestamp the submission was received by the server
     property :server_receive_date do
       str = data.fetch('serverReceiveDate')
       str.nil? ? nil : DateTime.strptime(str)
     end
 
+    # Retrieve the pages containing the form questions and answers
+    # @return [Hash] Hash of questions and answers for the FormSubmission
     def pages
+      document.fetch('pages')
+    end
+
+    # Retrieve the dispatching User, if the form was dispatched
+    # @return [User] The user that dispatched the form, or nil
+    def dispatcher
+      return nil unless dispatched?
+
+      client.user(document.dig('dispatcher', 'identifier'))
+    end
+
+    # Check if the form was dispatched
+    # @return [Boolean] True if the form was dispatched; false otherwise
+    def dispatched?
+      !document.dig('dispatcher', 'identifier').nil?
+    end
+
+    # Retrieve the form space for the form submission
+    # @return [FormSpace] Form space for the submission's form
+    def form_space
+      client.form_space(full_data.dig('form', 'formSpaceId'))
+    end
+
+    # Retrieve the form for the form submission
+    # @return [Form] Form for the submission
+    def form
+      form_space.form(full_data.dig('form', 'formId'))
+    end
+
+    # Retrieve the current version of the form
+    # @return [FormIteration] The form iteration
+    def form_version
+      form.current_version
+    end
+
+    # Retrieve all documents attached to this form submission
+    # @return [Array] Documents attached to the form submission
+    def documents(populate: false)
+      ids = form_version.document_ids
+      if populate
+        ids.map { |id| form.iteration(id) }
+      else
+        ids
+      end
+    end
+
+    # Download a specific document. The Document must have been attached to
+    # the form's current version at the time of submission.
+    # @return [IO] Data stream for the document
+    def download_document(document)
+      io = StringIO.new
+      client.connection.get do |req|
+        req.url "#{url}/documents/#{document.id}"
+        req.options.on_data = proc { |chunk| io << chunk }
+      end
+      io.rewind
+      io
+    end
+
+    private
+
+    def url
+      "#{resource_name}/#{id}"
+    end
+
+    def full_data
+      return @full_data unless @full_data.nil?
+
+      @full_data = client.form_submission(id).data
+      @full_data
+    end
+
+    # Returns additional data about the submission. Uses cached data,
+    # otherwise it loads and returns the data via #document!
+    def document
+      return @document unless @document.nil?
+
+      document!
+    end
+
+    # Force loads the submission document
+    def document!
       res = client.connection.get do |req|
         req.url "#{resource_name}/#{id}/document.json"
       end
-      if res.success?
-        JSON.parse(res.body).fetch('pages')
-      end
+
+      @document = JSON.parse(res.body)
+      @document
     end
   end
 end

data/lib/prontoforms/resource.rb

@@ -1,19 +1,29 @@
+# frozen_string_literal: true
+
 require 'date'
 
 module ProntoForms
+  # Base class for resource-related classes.
   class Resource
-    attr_reader :data, :client, :parent
+    # @return [Hash] Retrieve raw JSON data associated with this resource
+    attr_reader :data
+    # @return [Client] API client
+    attr_reader :client
+    # @return [Resource] Parent object (applicable to child resources)
+    attr_reader :parent
 
+    # Defines a property of the resource
+    # @return [nil]
+    # @api private
     def self.property(name, key: nil, &block)
-      define_method(name) {
+      define_method(name) do
         if block_given?
           instance_eval(&block)
         elsif !key.nil?
-          data.fetch(key)
-        else
-          nil
+          key = [key] unless key.is_a?(Array)
+          key.inject(data) { |obj, k| obj.fetch(k) }
         end
-      }
+      end
     end
 
     def initialize(data, client, parent = nil)
@@ -22,11 +32,13 @@ module ProntoForms
       @parent = parent
     end
 
+    # The resource's identifier
     def self.resource_name
-      name = self.to_s.split("::").last
+      name = to_s.split('::').last
       "#{name.downcase}s"
     end
 
+    # The resource's identifier
     def resource_name
       self.class.resource_name
     end

data/lib/prontoforms/resource_list.rb

@@ -1,25 +1,46 @@
+# frozen_string_literal: true
+
 require 'prontoforms/resource'
 
 module ProntoForms
+  # A wrapper for retrieving paged resources.
   class ResourceList < Resource
-    attr_reader :limit, :offset, :method, :resource, :client, :parent
+    # @return [Hash] Query parameters for this resource list for e.g. filters
+    attr_reader :query
+    # @return [Symbol] Method to send to parent object (usually the client)
+    attr_reader :method
+    # @return [Class] Resource class
+    attr_reader :resource
+    # @return [Client] API client
+    attr_reader :client
+    # @return [Resource] Parent object (for child resources)
+    attr_reader :parent
 
-    def initialize(data, offset, limit, method, resource, client, parent = nil)
+    # Initialize the resource list
+    # TODO: splat
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(data, query, method, resource, client, parent = nil)
       super(data, client)
-      @limit = limit
-      @offset = offset
+      @query = query
       @method = method
       @resource = resource
+      @parent = parent
     end
+    # rubocop:enable Metrics/ParameterLists
 
+    # Retrieve the next page of results, using the same number of items per
+    # page as the original request.
+    # @return [ResourceList] A ResourceList with the next set of results
     def next
-      client.send(method, limit: limit, offset: offset + limit)
+      client.send(method, query: query.merge({ 'p' => query['p'] + 1 }))
     end
 
+    # Retrieve the result set
+    # @return [Array] Array of resource objects
     def items
-      @data.fetch('pageData').map { |item|
+      @data.fetch('pageData').map do |item|
         resource.new(item, client, parent)
-      }
+      end
     end
   end
 end

data/lib/prontoforms/user.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'prontoforms/resource'
+
+module ProntoForms
+  # A ProntoForms user account.
+  class User < Resource
+    def self.resource_name
+      'users'
+    end
+
+    # @return [String] The User identifier
+    property :id, key: 'identifier'
+    # @return [String] The user's username
+    property :username, key: 'username'
+    # @return [String] The user's role
+    property :role, key: 'role'
+    # @return [String] The user's email address
+    property :email, key: 'email'
+    # @return [String] The user's first name
+    property :first_name, key: 'firstName'
+    # @return [String] The user's last name
+    property :last_name, key: 'lastName'
+    # @return [String] The user's preferred locale
+    property :locale, key: 'locale'
+
+    # Get a display name consisting of the first name followed by last name
+    # e.g. "John Doe"
+    # @return [String] The display name for the user
+    def display_name
+      "#{first_name} #{last_name}"
+    end
+  end
+end

data/lib/prontoforms/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module ProntoForms
-  VERSION = '0.1.0'
+  VERSION = '2.0.0'
 end

data/prontoforms.gemspec

@@ -1,16 +1,19 @@
+# frozen_string_literal: true
+
 require_relative 'lib/prontoforms/version'
 
+# rubocop:disable Layout/LineLength
 Gem::Specification.new do |spec|
-  spec.name          = 'prontoforms'
-  spec.version       = ProntoForms::VERSION
-  spec.authors       = ['Paul Holden']
-  spec.email         = ['paul@holdensoftware.com']
+  spec.name = 'prontoforms'
+  spec.version = ProntoForms::VERSION
+  spec.authors = ['Paul Holden']
+  spec.email = ['paul@codelunker.com']
 
-  spec.summary       = 'A library for using the ProntoForms REST API in Ruby applications.'
-  spec.description   = 'A library for using the ProntoForms REST API in Ruby applications.'
-  spec.homepage      = 'https://github.com/paulholden2/prontoforms'
-  spec.license       = 'MIT'
-  spec.required_ruby_version = Gem::Requirement.new('>= 2.3.0')
+  spec.summary = 'A library for using the ProntoForms REST API in Ruby applications.'
+  spec.description = 'A library for using the ProntoForms REST API in Ruby applications.'
+  spec.homepage = 'https://github.com/paulholden2/prontoforms'
+  spec.license = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
 
   spec.metadata['allowed_push_host'] = 'https://rubygems.org'
 
@@ -19,17 +22,27 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/paulholden2/prontoforms/blog/master/CHANGELOG.md'
 
   # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
-  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  # The `git ls-files -z` loads the files in the RubyGem that have been added
+  # into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
   end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
   spec.add_dependency 'faraday', '~> 1.0'
 
   spec.add_development_dependency 'bundler', '~> 2.0'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
   spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.82.0'
+  spec.add_development_dependency 'sinatra', '~> 2.0'
+  spec.add_development_dependency 'sinatra-contrib', '~> 2.0'
+  spec.add_development_dependency 'webmock', '~> 3.6'
+  spec.add_development_dependency 'yard', '~> 0.9'
 end
+# rubocop:enable Layout/LineLength

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prontoforms
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Paul Holden
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-08-25 00:00:00.000000000 Z
+date: 2020-12-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -42,16 +42,16 @@ dependencies:
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: 12.3.3
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -66,19 +66,90 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.82.0
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sinatra-contrib
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A library for using the ProntoForms REST API in Ruby applications.
 email:
-- paul@holdensoftware.com
+- paul@codelunker.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/checks.yml"
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -86,10 +157,14 @@ files:
 - bin/setup
 - lib/prontoforms.rb
 - lib/prontoforms/client.rb
+- lib/prontoforms/document.rb
+- lib/prontoforms/form.rb
+- lib/prontoforms/form_iteration.rb
 - lib/prontoforms/form_space.rb
 - lib/prontoforms/form_submission.rb
 - lib/prontoforms/resource.rb
 - lib/prontoforms/resource_list.rb
+- lib/prontoforms/user.rb
 - lib/prontoforms/version.rb
 - prontoforms.gemspec
 homepage: https://github.com/paulholden2/prontoforms
@@ -108,14 +183,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.1.4
 signing_key:
 specification_version: 4
 summary: A library for using the ProntoForms REST API in Ruby applications.

data/Gemfile.lock

@@ -1,39 +0,0 @@
-PATH
-  remote: .
-  specs:
-    prontoforms (0.1.0)
-      faraday (~> 1.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    diff-lcs (1.4.4)
-    faraday (1.0.1)
-      multipart-post (>= 1.2, < 3)
-    multipart-post (2.1.1)
-    rake (10.5.0)
-    rspec (3.9.0)
-      rspec-core (~> 3.9.0)
-      rspec-expectations (~> 3.9.0)
-      rspec-mocks (~> 3.9.0)
-    rspec-core (3.9.2)
-      rspec-support (~> 3.9.3)
-    rspec-expectations (3.9.2)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-mocks (3.9.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.9.0)
-    rspec-support (3.9.3)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.0)
-  prontoforms!
-  rake (~> 10.0)
-  rspec (~> 3.0)
-
-BUNDLED WITH
-   2.1.4