diff --git a/CHANGELOG.md b/CHANGELOG.md index ff07da4..e89338d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,10 @@ ## CHANGELOG +v1.39 (2020-10-17) + **Features and Improvements** + + * Added new models support: CustomField + v1.38 (2019-05-11) **Features and Improvements** diff --git a/README.md b/README.md index 1afa3d0..dd76b8f 100644 --- a/README.md +++ b/README.md @@ -212,6 +212,21 @@ Actions: * Update a contact - `client.contacts.update` * Delete a contact - `client.contacts.destroy` +### Custom Fields + +```ruby +client = BaseCRM::Client.new(access_token: "") +client.custom_fields # => BaseCRM::CustomFieldsService +``` + +Actions: +* Retrieve all custom fields - `client.custom_fields.all('contact')` + * `all` excepts the following `resource_type` parameters: + * `lead` + * `contact` + * `deal` + * `prospect_and_customer` + ### Deal ```ruby diff --git a/lib/basecrm.rb b/lib/basecrm.rb index 57fd3bc..9db9d98 100644 --- a/lib/basecrm.rb +++ b/lib/basecrm.rb @@ -17,6 +17,7 @@ require 'basecrm/models/call' require 'basecrm/models/call_outcome' require 'basecrm/models/contact' +require 'basecrm/models/custom_field' require 'basecrm/models/deal' require 'basecrm/models/deal_source' require 'basecrm/models/deal_unqualified_reason' @@ -48,6 +49,7 @@ require 'basecrm/services/calls_service' require 'basecrm/services/call_outcomes_service' require 'basecrm/services/contacts_service' +require 'basecrm/services/custom_fields_service' require 'basecrm/services/deals_service' require 'basecrm/services/deal_sources_service' require 'basecrm/services/deal_unqualified_reasons_service' @@ -109,6 +111,14 @@ def accounts @accounts ||= AccountsService.new(@http_client) end + # Access all Custom Field related actions. + # @see CustomFieldsService + # @see CustomField + # + # @return [CustomFieldsService] Service object for resources. + def custom_fields + @custom_fields ||= CustomFieldsService.new(@http_client) + end # Access all AssociatedContacts related actions. # @see AssociatedContactsService # @see AssociatedContact diff --git a/lib/basecrm/models/custom_field.rb b/lib/basecrm/models/custom_field.rb new file mode 100644 index 0000000..48cbfa5 --- /dev/null +++ b/lib/basecrm/models/custom_field.rb @@ -0,0 +1,20 @@ +module BaseCRM + class CustomField < Model + # @!attribute [r] created_at + # @return [DateTime] Date and time of the account's creation in UTC (ISO8601 format). + # @!attribute [r] updated_at + # @return [DateTime] Date and time of the last update in UTC (ISO8601 format). + # @!attribute [r] id + # @return [Integer] Unique identifier of the custom field. + # @!attribute [r] name + # @return [String] Name of the custom field. + # @!attribute [r] type + # @return [String] Type of the custom field. + # @!attribute [r] choices + # @return [Array] Represents choices that can be used for this particular custom field (applicable only for multi_select_list and list). + # @!attribute [r] for_organisation + # @return [Boolean] Whether custom field should be available on Contact: Company (applicable only for resource_type=contact). + # @!attribute [r] for_contact + # @return [Boolean] Whether custom field should be available on Contact: Person (applicable only for resource_type=contact). + end +end diff --git a/lib/basecrm/services/custom_fields_service.rb b/lib/basecrm/services/custom_fields_service.rb new file mode 100644 index 0000000..07a4fd8 --- /dev/null +++ b/lib/basecrm/services/custom_fields_service.rb @@ -0,0 +1,37 @@ +module BaseCRM + class CustomFieldsService + RESOURCE_TYPES = %w[lead contact deal prospect_and_customer].freeze + + def initialize(client) + @client = client + end + + # Retrieve custom field details for a resource type + # + # get '/:resource_type/custom_fields' + # + # Returns detailed information about your custom fields + # + # @return [Array] Array of CustomField + def all(resource_type) + raise IncorrectResourceType unless RESOURCE_TYPES.include?(resource_type) + + _, _, root = @client.get("/#{resource_type}/custom_fields", {}) + root[:items].map { |item| CustomField.new(item[:data]) } + end + + private + + def validate_type!(custom_field) + raise TypeError unless custom_field.is_a?(CustomField) || custom_field.is_a?(Hash) + end + + def extract_params!(custom_field, *args) + params = custom_field.to_h.select { |k, _| args.include?(k) } + raise ArgumentError, "one of required attributes is missing. Expected: #{args.join(',')}" if params.count != args.length + params + end + + class IncorrectResourceType < StandardError; end + end +end diff --git a/lib/basecrm/version.rb b/lib/basecrm/version.rb index 4a7ec27..2ecdb9c 100644 --- a/lib/basecrm/version.rb +++ b/lib/basecrm/version.rb @@ -1,3 +1,3 @@ module BaseCRM - VERSION = "1.3.8" + VERSION = "1.3.9" end diff --git a/spec/services/custom_fields_service_spec.rb b/spec/services/custom_fields_service_spec.rb new file mode 100644 index 0000000..ed67e57 --- /dev/null +++ b/spec/services/custom_fields_service_spec.rb @@ -0,0 +1,21 @@ +require 'spec_helper' + +describe BaseCRM::CustomFieldsService do + describe 'Responds to' do + subject { client.custom_fields } + + it { should respond_to :all } + end + + describe :all do + it "returns an array" do + expect(client.custom_fields.all('contact')).to be_instance_of(Array) + end + + it 'raises IncorrectResourceType if resource type not approved' do + expect do + client.custom_fields.all('not_valid') + end.to raise_exception(BaseCRM::CustomFieldsService::IncorrectResourceType) + end + end +end