rallio 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04a1b0410f3446004d68353fb670ea94971bfbf2
-  data.tar.gz: 86bf9e90c057f0a76bc23caa041d18b7f393ee38
+  metadata.gz: 1e09140384dd4ab0295ebfd128a49328538a8e37
+  data.tar.gz: a01df9d158fd7a6985f63fb7bd8b3b1506f31edb
 SHA512:
-  metadata.gz: dc8845c14a63db683ce8eea98fbff1fb71200467aed893a18e053708a1befdebb6ed38a36619c32ff623f2bdb26805ebb5337ac4e1da3dafc9679bacb302af50
-  data.tar.gz: fd31f9811b8c639514c0e5e5db4f39fac9743c523aba43c031e96e7cd50d4ef8ba01de4dd4e04cfb6531de81646367cd53984f3e8a0b61c1e9c1a7e97c4c937c
+  metadata.gz: 295ca0a315f2adf7c0c88c8e5f16e4ba24bc01657d9ae53646735e80010baa6583f54823ecc205af7d109a777b338cc5b625ae0e6ca6013251f1cbc86f8a19b7
+  data.tar.gz: c191d0f8bf882bf02f5d3fec612750d567d7cb486bd7f88603936b5453c2b141529e991c90a1bcff376d25508f9f7b7e21de533c859334dec46006ab1c7ce518

data/lib/rallio/access_token.rb

@@ -1,15 +1,34 @@
 module Rallio
+  # Represents an access token object as it comes from Rallio.
+  #
+  # @!attribute [rw] access_token
+  #   Access token string
+  # @!attribute [rw] user_id
+  # @!attribute [rw] expires_at
+  #   @return [DateTime, nil] expiration DateTime or nil if access token never expires
+  # @!attribute [rw] scopes
+  #   List of oauth scopes for the access token
   class AccessToken < Base
     attribute :access_token, String
     attribute :user_id, Integer
     attribute :expires_at, DateTime
     attribute :scopes, String
 
+    # Creates new access token for user_id.
+    #
+    # NOTE: These token do not expire so it is suggested (recommended) that the
+    #       token be cached and reused whenever possible.
+    #
+    # @param user_id [Integer]
+    # @return [Rallio::AccessToken]
     def self.create(user_id:)
       response = self.post("/users/#{user_id}/access_tokens", headers: app_credentials)
       new response.parsed_response
     end
 
+    # Destroys access_token
+    #
+    # @return [true, nil] true if successful or nil
     def destroy
       headers = { 'Authorization' => "Bearer #{access_token}" }
       self.class.delete('/access_token', headers: headers)

data/lib/rallio/account.rb

@@ -1,4 +1,13 @@
 module Rallio
+  # Represents an account object as it comes from Rallio.
+  #
+  # @!attribute [rw] id
+  # @!attribute [rw] name
+  # @!attribute [rw] short_name
+  # @!attribute [rw] url
+  # @!attribute [rw] city
+  # @!attribute [rw] country_code
+  # @!attribute [rw] time_zone
   class Account < Base
     attribute :id, Integer
     attribute :name, String
@@ -8,19 +17,33 @@ module Rallio
     attribute :country_code, String
     attribute :time_zone, String
 
-    def reviews(access_token:)
-      Review.all(type: type, id: id, access_token: access_token)
-    end
-
+    # Retreives accounts.
+    #
+    # @param franchisor_id [Integer] franchisor_id to get accounts for
+    # @return [Array<Rallio::Account>]
     def self.for(franchisor_id:)
       response = self.get("/franchisors/#{franchisor_id}/accounts", headers: app_credentials)
       response.parsed_response['accounts'].map { |a| new a }
     end
 
+    # Creates an account.
+    #
+    # @param franchisor_id [Integer] franchisor_id to create account under
+    # @param payload [Hash]
+    # @option payload [Hash] :account data to create account with
+    # @return [Hash] hash of account created
     def self.create(franchisor_id:, payload:)
       self.post("/franchisors/#{franchisor_id}/accounts", headers: app_credentials, body: payload).parsed_response
     end
 
+    # Retreives reviews for the account.
+    #
+    # @param access_token [String] user access token for API access to account
+    # @return [Array<Rallio::Review>]
+    def reviews(access_token:)
+      Review.all(type: type, id: id, access_token: access_token)
+    end
+
     private
 
     def type

data/lib/rallio/account_ownership.rb

@@ -1,4 +1,11 @@
 module Rallio
+  # Represents an account ownership object as it comes from Rallio.
+  #
+  # @!attribute [rw] user_id
+  # @!attribute [rw] account_id
+  # @!attribute [rw] account_name
+  # @!attribute [rw] account_franchisor_id
+  # @!attribute [rw] account_franchisor_name
   class AccountOwnership < OwnershipsBase
     attribute :user_id, Integer
     attribute :account_id, Integer
@@ -6,10 +13,12 @@ module Rallio
     attribute :account_franchisor_id, Integer
     attribute :account_franchisor_name, String
 
+    # (see Rallio::FranchisorOwnership#self.url_segment)
     def self.url_segment
       'account_ownerships'
     end
 
+    # (see Rallio::FranchisorOwnership#self.response_key)
     def self.response_key
       'account_ownership'
     end

data/lib/rallio/base.rb

@@ -5,6 +5,10 @@ module Rallio
 
     base_uri 'https://app.rallio.com/api/v1'
 
+    # The credentials that can be used in the headers of any request requiring
+    # app level credentials
+    #
+    # @return [Hash] credentials hash
     def self.app_credentials
       {
         'X-Application-ID' => Rallio.application_id,

data/lib/rallio/franchisor.rb

@@ -1,10 +1,17 @@
 module Rallio
   class Franchisor < Account
+    # Retreives all franchisors for a given application.
+    #
+    # @return [Array<Rallio::Franchisor>]
     def self.all
       response = self.get('/franchisors', headers: app_credentials)
       response.parsed_response['franchisors'].map { |f| new(f) }
     end
 
+    # Retreives all accounts for the Rallio::Franchisor
+    # @see Rallio::Account
+    #
+    # @return [Array<Rallio::Account>]
     def accounts
       Rallio::Account.for(franchisor_id: id)
     end

data/lib/rallio/franchisor_ownership.rb

@@ -1,13 +1,24 @@
 module Rallio
+  # Represents a franchisor ownership as it comes from Rallio.
+  #
+  # @!attribute [rw] user_id
+  # @!attribute [rw] franchisor_id
+  # @!attribute [rw] franchisor_name
   class FranchisorOwnership < OwnershipsBase
     attribute :user_id, Integer
     attribute :franchisor_id, Integer
     attribute :franchisor_name, String
 
+    # Url segment used by base class to build correct endpoint.
+    #
+    # @return [String]
     def self.url_segment
       'franchisor_ownerships'
     end
 
+    # Key used to extract response object from API response hash.
+    #
+    # @return [String]
     def self.response_key
       'franchisor_ownership'
     end

data/lib/rallio/ownerships_base.rb

@@ -1,16 +1,32 @@
 module Rallio
   class OwnershipsBase < Base
+    # Ownerships for access_token and url segment defined in class.
+    #
+    # @param access_token [String] user access token to get ownerships for
     def self.for(access_token:)
       headers = { 'Authorization' => "Bearer #{access_token}" }
       response = self.get("/#{url_segment}", headers: headers)
       response.parsed_response["#{url_segment}"].map { |a| new(a) }
     end
 
+    # Create new ownership.
+    #
+    # @param user_id [Integer] user id to create ownership for
+    # @param payload [Hash]
+    # @option payload [Integer] :franchisor_id franchisor to link to user_id
+    # @option payload [Integer] :account_id account to link to user_id
+    # @return [Rallio::FranchisorOwnership, Rallio::AccountOwnership]
+    #   object representing new ownership
     def self.create(user_id:, payload:)
       response = self.post("/users/#{user_id}/#{url_segment}", headers: app_credentials, body: payload)
       new response.parsed_response["#{response_key}"]
     end
 
+    # Destroy ownership for user.
+    #
+    # @param user_id [Integer] user id to destory ownership for
+    # @param object_id [Integer] can be either a franchisor_id or an account_id
+    #   depending on what class this is called from
     def self.destroy(user_id:, object_id:)
       self.delete("/users/#{user_id}/#{url_segment}/#{object_id}", headers: app_credentials)
     end

data/lib/rallio/review.rb

@@ -1,4 +1,23 @@
 module Rallio
+  # Represents a review object as it comes from Rallio.
+  #
+  # @!attribute [rw] id
+  # @!attribute [rw] account_id
+  # @!attribute [rw] account_name
+  # @!attribute [rw] network
+  # @!attribute [rw] posted_at
+  # @!attribute [rw] user_name
+  # @!attribute [rw] user_image
+  # @!attribute [rw] rating
+  # @!attribute [rw] message
+  # @!attribute [rw] comments
+  # @!attribute [rw] liked
+  # @!attribute [rw] url
+  # @!attribute [rw] can_reply
+  # @!attribute [rw] location_name
+  # @!attribute [rw] location_image_url
+  # @!attribute [rw] review_reply
+  # @!attribute [rw] review_reply_at
   class Review < Base
     attribute :id, Integer
     attribute :account_id, Integer
@@ -18,12 +37,23 @@ module Rallio
     attribute :review_reply, String
     attribute :review_reply_at, DateTime
 
+    # Retreives reviews.
+    #
+    # @param type [String] one of accounts or franchisors to get reviews for
+    # @param id [Integer] account or franchisor id to get reviews for
+    # @param access_token [String] user access token to use for authorization
+    # @return [Array<Rallio::Review>]
     def self.all(type:, id:, access_token:)
       headers = { 'Authorization' => "Bearer #{access_token}" }
       response = self.get("/#{type}/#{id}/reviews", headers: headers)
       response.parsed_response['reviews'].map { |r| new(r) }
     end
 
+    # Replies to review.
+    #
+    # @param message [String] text used for reply
+    # @param access_token [String] user access token to use for authorization
+    # @return [Hash] reply hash that was created
     def reply(message:, access_token:)
       headers = { 'Authorization' => "Bearer #{access_token}" }
       self.class.post("/reviews/#{id}/reply", headers: headers, body: { message: message })

data/lib/rallio/sign_on_token.rb

@@ -1,9 +1,20 @@
 module Rallio
+  # Represents a sign on token object as it comes from Rallio.
+  #
+  # @!attribute [rw] token
+  # @!attribute [rw] expires_at
+  #   DateTime token and url will become invalid.
+  # @!attribute [rw] url
+  #   Url to redirect user to for SSO with token embedded
   class SignOnToken < Base
     attribute :token, String
     attribute :expires_at, DateTime
     attribute :url, String
 
+    # Creates new sign on token for user_id.
+    #
+    # @param user_id [Integer]
+    # @return [Rallio::SignOnToken]
     def self.create(user_id:)
       response = self.post("/users/#{user_id}/sign_on_tokens", headers: app_credentials)
       new response.parsed_response['sign_on_token']

data/lib/rallio/user.rb

@@ -1,36 +1,69 @@
 module Rallio
+  # Represents a user object as it comes from Rallio.
+  #
+  # @!attribute [rw] id
+  # @!attribute [rw] email
+  # @!attribute [rw] first_name
+  # @!attribute [rw] last_name
   class User < Base
     attribute :id, Integer
     attribute :email, String
     attribute :first_name, String
     attribute :last_name, String
-    attribute :accounts, Array[Account]
-    attribute :franchisors, Array[Franchisor]
+    # This may not be needed anymore, API still in flux
+    #attribute :accounts, Array[Account]
+    #attribute :franchisors, Array[Franchisor]
 
     attr_writer :access_token
 
+    # Lists accessible users on Rallio's platform for application.
+    #
+    # @return [Array<Rallio::User>] array of users accessible to application
     def self.accessible_users
       response = self.get('/accessible_users', headers: app_credentials)
       response.parsed_response['users'].map { |u| User.new(u) }
     end
 
+    # Create a user on the Rallio platform.
+    #
+    # @param user [Hash] user info used to create new user
+    # @option user [String] :email unique email address
+    # @option user [String] :first_name
+    # @option user [String] :last_name
+    # @return [Rallio::User] user object that was just created
     def self.create(user:)
       response = self.post('/users', headers: app_credentials, body: { user: user })
       new response.parsed_response['user']
     end
 
+    # Creates new single signon for user to be redirected to.
+    # @see Rallio::SignOnToken
+    #
+    # @return [Rallio::SignOnToken]
     def sign_on_token
       SignOnToken.create(user_id: id)
     end
 
+    # Creates or returns the API access token for user.
+    # @see Rallio::AccessToken
+    #
+    # @return [Rallio::AccessToken]
     def access_token
       @access_token ||= AccessToken.create(user_id: id)
     end
 
+    # Retreives account ownerships for user.
+    # @see Rallio::AccountOwnership
+    #
+    # @return [Array<Rallio::AccountOwnership>] array of user's account ownerships
     def account_ownerships
       AccountOwnership.for(access_token: access_token.access_token)
     end
 
+    # Retreives franchisor ownerships for user.
+    # @see Rallio::FranchisorOwnership
+    #
+    # @return [Array<Rallio::FranchisorOwnership>] array of user's franchisor ownerships
     def franchisor_ownerships
       FranchisorOwnership.for(access_token: access_token.access_token)
     end

data/lib/rallio/version.rb

@@ -1,3 +1,3 @@
 module Rallio
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rallio
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - JD Guzman