passaporteweb-client 0.0.10

data/lib/passaporte_web.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'rest_client'
+require 'multi_json'
+
+require "passaporte_web/version"
+require "passaporte_web/configuration"
+require "passaporte_web/http"
+require "passaporte_web/helpers"
+require "passaporte_web/attributable"
+require "passaporte_web/identity"
+require "passaporte_web/service_account"
+require "passaporte_web/service_account_member"
+require "passaporte_web/identity_service_account"
+
+module PassaporteWeb
+
+  def self.configuration
+    @configuration ||=  Configuration.new
+  end
+
+  def self.configure
+    yield(configuration) if block_given?
+  end
+
+end

data/lib/passaporte_web/attributable.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+module PassaporteWeb
+
+  module Attributable
+
+    def set_attributes(hash)
+      self.class::ATTRIBUTES.each do |attribute|
+        value = hash[attribute.to_s] if hash.has_key?(attribute.to_s)
+        value = hash[attribute.to_sym] if hash.has_key?(attribute.to_sym)
+        instance_variable_set("@#{attribute}".to_sym, value)
+      end
+    end
+    private :set_attributes
+
+  end
+
+end

data/lib/passaporte_web/configuration.rb

@@ -0,0 +1,41 @@
+# encoding: utf-8
+require 'base64'
+module PassaporteWeb
+
+  class Configuration
+    attr_accessor :url, :user_agent, :application_token, :application_secret, :user_token
+
+    def initialize
+      @url = 'https://app.passaporteweb.com.br'
+      @user_agent = "PassaporteWeb Ruby Client v#{PassaporteWeb::VERSION}"
+      @application_token = nil
+      @application_secret = nil
+      @user_token = nil
+    end
+
+    def application_credentials
+      check_tokens! :application_token, :application_secret
+      base64_credential('application', @application_token, @application_secret)
+    end
+
+    def user_credentials
+      check_tokens! :user_token
+      base64_credential('user', @user_token)
+    end
+
+    private
+
+    def check_tokens!(*tokens)
+      tokens.each do |token|
+        value = instance_variable_get("@#{token}".to_sym)
+        raise ArgumentError, "#{token} not set" if value.nil? || value.to_s.strip == ''
+      end
+    end
+
+    def base64_credential(type, user, password=nil)
+      return "Basic #{::Base64.strict_encode64("#{user}:#{password}")}" if type.eql? 'application'
+      return "Basic #{::Base64.strict_encode64(":#{user}")}" if type.eql? 'user'
+    end
+  end
+
+end

data/lib/passaporte_web/helpers.rb

@@ -0,0 +1,67 @@
+# encoding: utf-8
+require 'ostruct'
+module PassaporteWeb
+
+  class Helpers
+
+    # Converts pagination information from a Link header in a HTTP response to a Hash
+    #
+    # Example:
+    #   link_header = "<http://sandbox.app.passaporteweb.com.br/organizations/api/accounts/?page=3&limit=3>; rel=next, <http://sandbox.app.passaporteweb.com.br/organizations/api/accounts/?page=1&limit=3>; rel=prev, <http://sandbox.app.passaporteweb.com.br/organizations/api/accounts/?page=5&limit=3>; rel=last, <http://sandbox.app.passaporteweb.com.br/organizations/api/accounts/?page=1&limit=3>; rel=first"
+    #   PassaporteWeb::Helpers.meta_links_from_header(link_header)
+    #   => {limit: 3, next_page: 3, prev_page: 1, first_page: 1, last_page: 5}
+    def self.meta_links_from_header(link_header)
+      hash = {limit: nil, next_page: nil, prev_page: nil, first_page: nil, last_page: nil}
+      links = link_header.split(',').map(&:strip)
+
+      if link_header.match(/limit\=([0-9]+)/)
+        hash[:limit] = Integer($1)
+      end
+
+      links.each do |link|
+        if link.match(/page\=([0-9]+).*rel\=([a-z]+)/)
+          case $2
+          when 'next'
+            hash[:next_page] = Integer($1)
+          when 'prev'
+            hash[:prev_page] = Integer($1)
+          when 'first'
+            hash[:first_page] = Integer($1)
+          when 'last'
+            hash[:last_page] = Integer($1)
+          end
+        end
+      end
+
+      hash
+    end
+
+    # Converts a Hash recursevely to a OpenStruct object.
+    #
+    # Example:
+    #   hash = {a: 1, b: {c: 3, d: 4, e: {f: 6, g: 7}}}
+    #   os = PassaporteWeb::Helpers.convert_to_ostruct_recursive(hash)
+    #   os.a # => 1
+    #   os.b # => {c: 3, d: 4, e: {f: 6, g: 7}}
+    #   os.b.c # => 3
+    #   os.b.d # => 4
+    #   os.b.e # => {f: 6, g: 7}
+    #   os.b.e.f # => 6
+    #   os.b.e.g # => 7
+    def self.convert_to_ostruct_recursive(obj, options={})
+      result = obj
+      if result.is_a? Hash
+        result = result.dup
+        result.each do |key, val|
+          result[key] = convert_to_ostruct_recursive(val, options) unless (!options[:exclude].nil? && options[:exclude].include?(key))
+        end
+        result = OpenStruct.new result
+      elsif result.is_a? Array
+        result = result.map { |r| convert_to_ostruct_recursive(r, options) }
+      end
+      return result
+    end
+
+  end
+
+end

data/lib/passaporte_web/http.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+require 'base64'
+module PassaporteWeb
+
+  class Http # :nodoc:
+
+    def self.get(path='/', params={}, type='application')
+      get_or_delete(:get, path, params, type)
+    end
+
+    def self.put(path='/', body={}, params={}, type='application')
+      put_or_post(:put, path, body, params, type)
+    end
+
+    def self.post(path='/', body={}, params={}, type='application')
+      put_or_post(:post, path, body, params, type)
+    end
+
+    def self.delete(path='/', params={}, type='application')
+      get_or_delete(:delete, path, params, type)
+    end
+
+    def self.custom_auth_get(user, password, path='/', params={})
+      credentials = "Basic #{::Base64.strict_encode64("#{user}:#{password}")}"
+      custom_params = common_params('application').merge({authorization: credentials})
+      RestClient.get(
+        pw_url(path),
+        {params: params}.merge(custom_params)
+      )
+    end
+
+    private
+
+    def self.put_or_post(method, path, body, params, type)
+      RestClient.send(
+        method,
+        pw_url(path),
+        encoded_body(body),
+        {params: params}.merge(common_params(type))
+      )
+    end
+
+    def self.get_or_delete(method, path, params, type)
+      RestClient.send(
+        method,
+        pw_url(path),
+        {params: params}.merge(common_params(type))
+      )
+    end
+
+    def self.pw_url(path)
+      "#{PassaporteWeb.configuration.url}#{path}"
+    end
+
+    def self.common_params(type)
+      {
+        authorization: (type == 'application' ? PassaporteWeb.configuration.application_credentials : PassaporteWeb.configuration.user_credentials),
+        content_type: :json,
+        accept: :json,
+        user_agent: PassaporteWeb.configuration.user_agent
+      }
+    end
+
+    def self.encoded_body(body)
+      body.is_a?(Hash) ? MultiJson.encode(body) : body
+    end
+
+  end
+
+end

data/lib/passaporte_web/identity.rb

@@ -0,0 +1,216 @@
+# encoding: utf-8
+module PassaporteWeb
+
+  # Represents an Identity on PassaporteWeb, i.e. a person. When you sign up for PassaporteWeb, your 'account'
+  # there is an Identity.
+  class Identity
+    include Attributable
+
+    ATTRIBUTES = [:accounts, :birth_date, :country, :cpf, :email, :first_name, :gender, :is_active, :language, :last_name, :nickname, :notifications, :send_myfreecomm_news, :send_partner_news, :services, :timezone, :update_info_url, :uuid, :password, :password2, :must_change_password, :inhibit_activation_message, :tos]
+    UPDATABLE_ATTRIBUTES = [:first_name, :last_name, :nickname, :cpf, :birth_date, :gender, :send_myfreecomm_news, :send_partner_news, :country, :language, :timezone]
+    CREATABLE_ATTRIBUTES = *(UPDATABLE_ATTRIBUTES + [:email, :password, :password2, :must_change_password, :tos])
+
+    attr_accessor *UPDATABLE_ATTRIBUTES
+    attr_reader *(ATTRIBUTES - UPDATABLE_ATTRIBUTES)
+    attr_reader :errors
+
+    # Finds an Identity by it's UUID. Returns the Identity instance with all fields set if successful.
+    # Raises a <tt>RestClient::ResourceNotFound</tt> exception if no Identity exists with the supplied
+    # UUID.
+    #
+    # If <tt>include_expired_accounts</tt> is passed as <tt>true</tt>, brings information about all
+    # accounts the Identity is related, regardless of the account's expiration date.
+    #
+    # If <tt>include_other_services</tt> is passed as <tt>true</tt>, brings information about accounts
+    # of all services the Identity is related to (not just the current logged in service / application).
+    #
+    # API method: <tt>/accounts/api/identities/:uuid/</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/usuarios.html#get-accounts-api-identities-uuid
+    def self.find(uuid, include_expired_accounts=false, include_other_services=false)
+      response = Http.get(
+        "/accounts/api/identities/#{uuid}/",
+        {include_expired_accounts: include_expired_accounts, include_other_services: include_other_services}
+      )
+      attributes_hash = MultiJson.decode(response.body)
+      load_identity(attributes_hash)
+    end
+
+    # Finds an Identity by it's email (emails are unique on PassaporteWeb). Returns the Identity instance
+    # with all fields set if successful. Raises a <tt>RestClient::ResourceNotFound</tt> exception if no
+    # Identity exists with the supplied email.
+    #
+    # If <tt>include_expired_accounts</tt> is passed as <tt>true</tt>, brings information about all
+    # accounts the Identity is related, regardless of the account's expiration date.
+    #
+    # If <tt>include_other_services</tt> is passed as <tt>true</tt>, brings information about accounts
+    # of all services the Identity is related to (not just the current logged in service / application).
+    #
+    # API method: <tt>GET /accounts/api/identities/?email=:email</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/usuarios.html#get-accounts-api-identities-email-email
+    def self.find_by_email(email, include_expired_accounts=false, include_other_services=false)
+      response = Http.get(
+        "/accounts/api/identities/",
+        {email: email, include_expired_accounts: include_expired_accounts, include_other_services: include_other_services}
+      )
+      attributes_hash = MultiJson.decode(response.body)
+      load_identity(attributes_hash)
+    end
+
+    # Checks if an Identity exists on PassaporteWeb and if the password is correct. Returns an instance of
+    # Identity for the supplied email if the password is correct (although with only basic attributes set).
+    # Returns <tt>false</tt> if the password is wrong or if no Identity exists on PassaporteWeb with
+    # the supplied email. Use it to validate that a user is who he says he is.
+    #
+    # API method: <tt>GET /accounts/api/auth/</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/usuarios.html#get-accounts-api-auth
+    def self.authenticate(email, password)
+      response = Http.custom_auth_get(
+        email,
+        password,
+        "/accounts/api/auth/"
+      )
+      raise "unexpected response: #{response.code} - #{response.body}" unless response.code == 200
+      attributes_hash = MultiJson.decode(response.body)
+      load_identity(attributes_hash)
+    rescue *[RestClient::Unauthorized] => e
+      false
+    end
+
+    # Checks if the supplied password is correct for the current Identity. Returns <tt>true</tt> if the
+    # password matches or <tt>false</tt> if the password is wrong. Use it to validate that a user is who
+    # he says he is.
+    #
+    # API method: <tt>GET /accounts/api/auth/</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/usuarios.html#get-accounts-api-auth
+    def authenticate(password)
+      raise ArgumentError, "email must be set" if (self.email.nil? || self.email.to_s.empty?)
+      response = Http.custom_auth_get(
+        self.email,
+        password,
+        "/accounts/api/auth/"
+      )
+      raise "unexpected response: #{response.code} - #{response.body}" unless response.code == 200
+      true
+    rescue *[RestClient::Unauthorized] => e
+      false
+    end
+
+    # Instanciates a new Identity with the supplied attributes. Only the attributes listed
+    # on <tt>Identity::CREATABLE_ATTRIBUTES</tt> are used when creating an Identity and
+    # on <tt>Identity::UPDATABLE_ATTRIBUTES</tt> are used when updating an Identity.
+    #
+    # Example:
+    #
+    #   identity = PassaporteWeb::Identity.new(
+    #     email: 'fulano@detal.com.br',
+    #     password: '123456',
+    #     password2: '123456',
+    #     must_change_password: false,
+    #     tos: true,
+    #     first_name: 'Fulano',
+    #     last_name: 'de Tal',
+    #     nickname: 'Fulaninho',
+    #     cpf: '342.766.570-40',
+    #     birth_date: '1983-04-19',
+    #     gender: 'M',
+    #     send_myfreecomm_news: true,
+    #     send_partner_news: false,
+    #     country: 'Brasil',
+    #     language: 'pt_BR',
+    #     timezone: 'GMT-3'
+    #   )
+    def initialize(attributes={})
+      set_attributes(attributes)
+      @errors = {}
+    end
+
+    # Returns a hash with all attribures of the identity.
+    def attributes
+      ATTRIBUTES.inject({}) do |hash, attribute|
+        hash[attribute] = self.send(attribute)
+        hash
+      end
+    end
+
+    # Compares one Identity with another, returns true if they have the same UUID.
+    def ==(other)
+      self.uuid == other.uuid
+    end
+
+    # Returns true if both Identity are the same object.
+    def ===(other)
+      self.object_id == other.object_id
+    end
+
+    # Saves the Identity on PassaporteWeb, creating it if new or updating it if existing. Returns true
+    # if successfull or false if not. In case of failure, it will fill the <tt>errors</tt> attribute
+    # with the reason for the failure to save the object.
+    #
+    # The attributes <tt>first_name</tt>, <tt>last_name</tt>, <tt>cpf</tt> and <tt>inhibit_activation_message</tt>
+    # are optional. <tt>password2</tt> and <tt>password</tt> fields are required even if the parameter
+    # <tt>must_change_password</tt> is used.
+    #
+    # API methods:
+    # * <tt>POST /accounts/api/create/</tt> (on create)
+    # * <tt>PUT /accounts/api/identities/:uuid/</tt> (on update)
+    #
+    # API documentation:
+    # * https://app.passaporteweb.com.br/static/docs/usuarios.html#post-accounts-api-create
+    # * https://app.passaporteweb.com.br/static/docs/usuarios.html#get-accounts-api-identities-email-email
+    #
+    # Example:
+    #
+    #   identity = Identity.find_by_email('foo@bar.com')
+    #   identity.save # => true
+    #   identity.cpf = '12'
+    #   identity.save # => false
+    #   identity.errors # => {"cpf" => ["Certifique-se de que o valor tenha no mínimo 11 caracteres (ele possui 2)."]}
+    def save
+      # TODO validar atributos?
+      response = (persisted? ? update : create)
+      raise "unexpected response: #{response.code} - #{response.body}" unless response.code == 200
+      attributes_hash = MultiJson.decode(response.body)
+      set_attributes(attributes_hash)
+      @persisted = true
+      @errors = {}
+      true
+    rescue *[RestClient::Conflict, RestClient::BadRequest] => e
+      @errors = MultiJson.decode(e.response.body)
+      false
+    end
+
+    def persisted?
+      !self.uuid.nil? && @persisted == true
+    end
+
+    private
+
+    def self.load_identity(attributes)
+      identity = self.new(attributes)
+      identity.instance_variable_set(:@persisted, true)
+      identity
+    end
+
+    def create
+      Http.post("/accounts/api/create/", create_body)
+    end
+
+    def update
+      Http.put("/accounts/api/identities/#{self.uuid}/", update_body)
+    end
+
+    def update_body
+      self.attributes.select { |key, value| UPDATABLE_ATTRIBUTES.include?(key) && !value.nil? }
+    end
+
+    def create_body
+      self.attributes.select { |key, value| CREATABLE_ATTRIBUTES.include?(key) && !value.nil? }
+    end
+
+  end
+
+end

data/lib/passaporte_web/identity_service_account.rb

@@ -0,0 +1,91 @@
+# encoding: utf-8
+module PassaporteWeb
+
+  # Also represents a ServiceAccount, but uses diffetent API endpoints to list and create them
+  # from a existing Identity.
+  class IdentityServiceAccount
+    include Attributable
+
+    ATTRIBUTES = [:membership_details_url, :plan_slug, :roles, :url, :expiration, :service_data, :account_data, :add_member_url, :name, :uuid]
+    CREATABLE_ATTRIBUTES = [:plan_slug, :expiration, :name, :uuid]
+
+    attr_accessor *CREATABLE_ATTRIBUTES
+    attr_reader *(ATTRIBUTES - CREATABLE_ATTRIBUTES)
+    attr_reader :identity, :errors
+
+    # Finds all service accounts of the supplied Identity on the current authenticated application.
+    # Returns an array of IdentityServiceAccount.
+    #
+    # API method: <tt>GET /organizations/api/identities/:uuid/accounts/</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/account_manager.html#get-organizations-api-identities-uuid-accounts
+    def self.find_all(identity, include_expired_accounts=false, role=nil)
+      params = {include_expired_accounts: include_expired_accounts}
+      params[:role] = role unless (role.nil? || role.to_s.empty?)
+      response = Http.get("/organizations/api/identities/#{identity.uuid}/accounts/", params)
+      raw_accounts = MultiJson.decode(response.body)
+      raw_accounts.map { |raw_account| load_identity_service_account(identity, raw_account) }
+    end
+
+    # Instanciates a new ServiceAccount to be created for the supplied Identity on the current
+    # authenticated application. See #save
+    def initialize(identity, attributes={})
+      set_attributes(attributes)
+      @identity = identity
+      @persisted = false
+      @errors = {}
+    end
+
+    # Creates a new ServiceAccount for the supplied Identity on the current authenticated application.
+    # The supplied Identity will be the ServiceAccount's owner. You should supply either the <tt>name</tt>
+    # or the (service account's) <tt>uuid</tt> attribute. If the latter is supplied, the supplied Identity
+    # must already be owner of at least one other ServiceAccount on the same group / organization.
+    #
+    # Returns true in case of success, false otherwise (along with failure reasons on #errors).
+    #
+    # API method: <tt>POST /organizations/api/identities/:uuid/accounts/</tt>
+    #
+    # API documentation: https://app.passaporteweb.com.br/static/docs/account_manager.html#post-organizations-api-identities-uuid-accounts
+    def save
+      # TODO validar atributos?
+      response = Http.post("/organizations/api/identities/#{self.identity.uuid}/accounts/", create_body)
+      raise "unexpected response: #{response.code} - #{response.body}" unless response.code == 201
+      attributes_hash = MultiJson.decode(response.body)
+      set_attributes(attributes_hash)
+      @persisted = true
+      @errors = {}
+      true
+    rescue *[RestClient::BadRequest] => e
+      @persisted = false
+      @errors = MultiJson.decode(e.response.body)
+      false
+    end
+
+    # Returns true if the IdentityServiceAccount exists on PassaporteWeb
+    def persisted?
+      @persisted == true
+    end
+
+    # Returns a hash with all attribures of the IdentityServiceAccount
+    def attributes
+      ATTRIBUTES.inject({}) do |hash, attribute|
+        hash[attribute] = self.send(attribute)
+        hash
+      end
+    end
+
+    private
+
+    def create_body
+      self.attributes.select { |key, value| CREATABLE_ATTRIBUTES.include?(key) && !value.nil? }
+    end
+
+    def self.load_identity_service_account(identity, attributes={})
+      isa = self.new(identity, attributes)
+      isa.instance_variable_set(:@persisted, true)
+      isa
+    end
+
+  end
+
+end