carehq 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d3d40aabe2a58bfa22dfd36fd4e4ae83b49e9e89bdc4e7e3031fdd217b204718
+  data.tar.gz: 5dc6072646b3caef0a22234634d3c8dc2c41474ad9fd5c4fa3146039077aaed3
+SHA512:
+  metadata.gz: f81342e9a3f80254ea673b38de329fcff8611335756490a5a598b7b45f5f5ca50bec23f5cd583284ae79eec2cd0d9a97dfe5264667d79259511d33bc5e96bd46
+  data.tar.gz: 906d32aa18a01523966b36ae8765b428d718a5479dbbc89f231b5d59cb30ab959616c53bc496888f6dbfabdc468b8f0b6ac30fb8537d9affa8f71e9c4a267e72

data/lib/carehq/exceptions.rb

@@ -0,0 +1,79 @@
+
+class APIException < StandardError
+
+    # An error occurred while processing an API the request.
+
+    attr_reader :status_code
+    attr_reader :hint
+    attr_reader :arg_errors
+
+    def initialize(status_code, hint=nil, arg_errors=nil)
+
+        # The status code associated with the error
+        @status_code = status_code
+
+        # A hint providing additional information as to why this error
+        # occurred.
+        @hint = hint
+
+        # A dictionary of errors relating to the arguments (parameters) sent
+        # to the API endpoint (e.g `{'arg_name': ['error1', ...]}`).
+        @arg_errors = arg_errors
+
+        super()
+    end
+
+    def APIException.get_class_by_status_code(error_type, default=nil)
+
+        class_map = {
+            400 => InvalidRequest,
+            401 => Unauthorized,
+            403 => Forbidden,
+            405 => Forbidden,
+            404 => NotFound,
+            429 => RateLimitExceeded
+        }
+
+        if class_map.has_key? error_type
+            return class_map[error_type]
+
+        elsif default
+            return default
+
+        end
+
+        return APIException
+
+    end
+
+end
+
+class Forbidden < APIException
+
+    # The request is not not allowed, most likely the HTTP method used to call
+    # the API endpoint is incorrect or the API key (via its associated account)
+    # does not have permission to call the endpoint and/or perform the action.
+
+end
+
+class InvalidRequest < APIException
+    # Not a valid request, most likely a missing or invalid parameter.
+end
+
+class NotFound < APIException
+
+    # The endpoint you are calling or the document you referenced doesn't exist.
+
+end
+
+class RateLimitExceeded < APIException
+
+    # You have exceeded the number of API requests allowed per second.
+
+end
+
+class Unauthorized < APIException
+
+    # The API credentials provided are not valid.
+
+end

data/lib/carehq.rb

@@ -0,0 +1,140 @@
+require 'digest'
+require 'httparty'
+
+
+class HTTPartyWrapper
+    include HTTParty
+
+    query_string_normalizer proc {|query|
+        query.map do |key, value|
+            value.kind_of?(Array) ?
+                value.map {|v| "#{key}=#{v}"} : "#{key}=#{value}"
+        end.join('&')
+    }
+end
+
+
+class APIClient
+
+    # A client for the CareHQ API.
+
+    attr_reader :rate_limit
+    attr_reader :rate_limit_reset
+    attr_reader :rate_limit_remaining
+
+    def initialize(
+        account_id,
+        api_key,
+        api_secret,
+        api_base_url: 'https://api.carehq.co.uk',
+        timeout: nil
+    )
+
+        # The Id of the CareHQ account the API key relates to
+        @account_id = account_id
+
+        # A key used to authenticate API calls to an account
+        @api_key = api_key
+
+        # A secret used to generate a signature for each API request
+        @api_secret = api_secret
+
+        # The base URL to use when calling the API
+        @api_base_url = api_base_url
+
+        # The period of time before requests to the API should timeout
+        @timeout = timeout
+
+        # NOTE: Rate limiting information is only available after a request
+        # has been made.
+
+        # The maximum number of requests per second that can be made with the
+        # given API key.
+        @rate_limit = nil
+
+        # The time (seconds since epoch) when the current rate limit will
+        # reset.
+        @rate_limit_reset = nil
+
+        # The number of requests remaining within the current limit before the
+        # next reset.
+        @rate_limit_remaining = nil
+    end
+
+    def request(method, path, params: nil, data: nil)
+        # Call the API
+
+        # Filter out params/data set to `nil` and ensure all arguments are
+        # converted to strings.
+
+        if params
+            params.delete_if {|k, v| v.nil?}
+        end
+
+        if data
+            data.delete_if {|k, v| v.nil?}
+        end
+
+        # Build the signature
+        signature_data = method.downcase == 'get' ? params : data
+
+        signature_values = []
+        (signature_data or {}).each_pair do |key, value|
+            signature_values.push(key)
+            if value.kind_of?(Array)
+                signature_values.concat(value)
+            else
+                signature_values.push(value)
+            end
+        end
+
+        signature_body = signature_values.join ''
+
+        timestamp = Time.now.to_f.to_s
+
+        signature_hash = Digest::SHA1.new
+        signature_hash.update timestamp
+        signature_hash.update signature_body
+        signature_hash.update @api_secret
+        signature = signature_hash.hexdigest
+
+        # Build the headers
+        headers = {
+            'Accept' => 'application/json',
+            'X-CareHQ-AccountId' => @account_id,
+            'X-CareHQ-APIKey' => @api_key,
+            'X-CareHQ-Signature' => signature,
+            'X-CareHQ-Timestamp' => timestamp
+        }
+
+        # Make the request
+        url = [@api_base_url, '/v1/', path].join ''
+        response = HTTPartyWrapper.method(method.downcase).call(
+            url,
+            {
+                :query => params,
+                :headers => headers,
+                :body => data,
+                :timeout => @timeout
+            }
+        )
+
+        # Raise an error related to the response
+
+        # Handle a successful response
+        if [200, 204].include? response.code
+            return response
+        end
+
+        error_cls = APIException.get_class_by_status_code(response.code)
+        raise error_cls.new(
+            response.code,
+            response['hint'],
+            response['arg_errors']
+        )
+
+    end
+
+end
+
+require 'carehq/exceptions'

metadata

@@ -0,0 +1,59 @@
+--- !ruby/object:Gem::Specification
+name: carehq
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Anthony Blackshaw
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-09-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.20.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.20.0
+description: CareHQ API client for Ruby.
+email: ant@crmhq.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/carehq.rb
+- lib/carehq/exceptions.rb
+homepage: https://github.com/CareHQ/carehq-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: CareHQ API client
+test_files: []