rdstation-ruby-client 2.9.0 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3de60aebf7582be38403250a4d049f3428241b66a18acb085cdd71f542cb8a0
-  data.tar.gz: '0829e4b85cae5dd80c64395f6e460ebb315fee92853d81a5feb263adaa2e3efe'
+  metadata.gz: c499b97d9b81de525df7b34dc2f06d5e380c0c8b2238b25674b6f9302059018c
+  data.tar.gz: a703568e0f3dac1f44ae7f585a56cf1f4f6cf155d45b8993da46bde3f429dbff
 SHA512:
-  metadata.gz: 1206caba197401915572f9bb66dd2c45ad2c019d8ce5899d0667753043066cce96edfc39207054549de900cf57e3eb1179c6e4bcf58bed5bac459ef37d49cc12
-  data.tar.gz: c27a1e2c5d5d3ef4ddc3cfc1f0369f9be0cf09c040147fe1409bcc6d77a3c4d2fc7f697f3d40db2f83fbc2a0c79cad61e9378d4cbc3eedc9df0fe9ec9eaa91ef
+  metadata.gz: 84c2fa75ab56babd2b0e37d87d0068d44537f5c8e53a57c267ace3a65f5f0565be0c263475c4dac12aa29c37a737efc1e3d9083a54ed73a3a1246a3145373c0d
+  data.tar.gz: 75378898d369bda0ee3c2f848c1f56b5441be073c6ff9aad71b1956824bf6fcef09f5ec43cf2be65d62150a45e1a31a484958a0e1363423afac2fce91faa2a2a

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 2.10.0
+
+### Additions
+
+#### 1. Getting a Contact by Phone
+
+Returns data about a specific Contact
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.by_phone('phone')
+```
+
+#### 2. Getting a Contact by Identifier
+
+Returns data about a specific Contact
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.by_identifier('identifier_type', 'identifier_value')
+```
+
+
 ## 2.9.0
 
 ### Additions

data/README.md

@@ -124,7 +124,7 @@ client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'ref
 client.contacts.by_uuid('uuid')
 ```
 
-More info: https://developers.rdstation.com/reference/get_platform-contacts-identifier-value
+More info: https://developers.rdstation.com/reference/get_platform-contacts-identifier-value-1
 
 #### Getting a Contact by Email
 
@@ -135,7 +135,18 @@ client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'ref
 client.contacts.by_email('email')
 ```
 
-More info:  https://developers.rdstation.com/pt-BR/reference/contacts#methodGetDetailsuuid
+More info:  https://developers.rdstation.com/reference/get_platform-contacts-identifier-value-1
+
+#### Getting a Contact by Phone
+
+Returns data about a specific Contact
+
+```ruby
+client = RDStation::Client.new(access_token: 'access_token', refresh_token: 'refresh_token')
+client.contacts.by_phone('phone')
+```
+
+More info:  https://developers.rdstation.com/reference/get_platform-contacts-identifier-value-1
 
 #### Update a Contact by UUID
 

data/lib/rdstation/contacts.rb

@@ -10,21 +10,31 @@ module RDStation
     end
 
     #
-    # param uuid:
-    #   The unique uuid associated to each RD Station Contact.
+    # param identifier_type:
+    #   The type of identifier: :uuid, :email, or :phone
+    # param identifier_value:
+    #   The value of the identifier
     #
-    def by_uuid(uuid)
+    def by_identifier(identifier_type, identifier_value)
+      validate_by_identifier_args!(identifier_type, identifier_value)
+
       retryable_request(@authorization) do |authorization|
-        response = self.class.get(base_url(uuid), headers: authorization.headers)
+        path = build_identifier_path(identifier_type, identifier_value)
+        response = self.class.get(base_url(path), headers: authorization.headers)
         ApiResponse.build(response)
       end
     end
 
+    def by_uuid(uuid)
+      by_identifier(:uuid, uuid)
+    end
+
     def by_email(email)
-      retryable_request(@authorization) do |authorization|
-        response = self.class.get(base_url("email:#{email}"), headers: authorization.headers)
-        ApiResponse.build(response)
-      end
+      by_identifier(:email, email)
+    end
+
+    def by_phone(phone)
+      by_identifier(:phone, phone)
     end
 
     # The Contact hash may contain the following parameters:
@@ -63,6 +73,30 @@ module RDStation
 
     private
 
+    def validate_by_identifier_args!(identifier_type, identifier_value)
+      unless valid_identifier_type?(identifier_type)
+        raise ArgumentError, "Invalid identifier type: #{identifier_type}"
+      end
+
+      if identifier_value.nil? || identifier_value.to_s.empty?
+        raise ArgumentError, 'identifier_value cannot be nil or empty'
+      end
+    end
+
+    def valid_identifier_type?(type)
+      %i[uuid email phone].include?(type)
+    end
+
+    def build_identifier_path(identifier_type, identifier_value)
+      encoded_value = URI.encode_www_form_component(identifier_value.to_s)
+      case identifier_type
+      when :uuid
+        encoded_value
+      when :email, :phone
+        "#{identifier_type}:#{encoded_value}"
+      end
+    end
+
     def base_url(path = '')
       "#{RDStation.host}/platform/contacts/#{path}"
     end

data/lib/rdstation/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RDStation
-  VERSION = '2.9.0'
+  VERSION = '2.10.0'
 end

data/spec/lib/rdstation/contacts_spec.rb

@@ -5,11 +5,20 @@ RSpec.describe RDStation::Contacts do
   let(:invalid_uuid) { 'invalid_uuid' }
   let(:valid_email) { 'valid@email.com' }
   let(:invalid_email) { 'invalid@email.com' }
+  let(:special_chars_email) { 'valid+user@example.com' }
+  let(:valid_phone) { '11999999999' }
+  let(:invalid_phone) { '11888888888' }
 
   let(:endpoint_with_valid_uuid) { "https://api.rd.services/platform/contacts/#{valid_uuid}" }
   let(:endpoint_with_invalid_uuid) { "https://api.rd.services/platform/contacts/#{invalid_uuid}" }
   let(:endpoint_with_valid_email) { "https://api.rd.services/platform/contacts/email:#{valid_email}" }
   let(:endpoint_with_invalid_email) { "https://api.rd.services/platform/contacts/email:#{invalid_email}" }
+  let(:endpoint_with_special_chars_email) do
+    encoded_email = URI.encode_www_form_component(special_chars_email)
+    "https://api.rd.services/platform/contacts/email:#{encoded_email}"
+  end
+  let(:endpoint_with_valid_phone) { "https://api.rd.services/platform/contacts/phone:#{valid_phone}" }
+  let(:endpoint_with_invalid_phone) { "https://api.rd.services/platform/contacts/phone:#{invalid_phone}" }
 
   let(:valid_access_token) { 'valid_access_token' }
   let(:invalid_access_token) { 'invalid_access_token' }
@@ -25,7 +34,6 @@ RSpec.describe RDStation::Contacts do
     described_class.new(authorization: RDStation::Authorization.new(access_token: invalid_access_token))
   end
 
-
   let(:valid_headers) do
     {
       'Authorization' => "Bearer #{valid_access_token}",
@@ -108,142 +116,290 @@ RSpec.describe RDStation::Contacts do
     }
   end
 
-  describe '#by_uuid' do
-    it 'calls retryable_request' do
-      expect(contact_with_valid_token).to receive(:retryable_request)
-      contact_with_valid_token.by_uuid('valid_uuid')
-    end
+  describe '#by_identifier' do
+    describe 'with identifier_type :uuid' do
+      it 'calls retryable_request' do
+        expect(contact_with_valid_token).to receive(:retryable_request)
+        contact_with_valid_token.by_identifier(:uuid, valid_uuid)
+      end
 
-    context 'with a valid auth token' do
-      context 'when the contact exists' do
-        let(:contact) do
-          { 'name' => 'Lead', 'email' => 'valid@email.com' }
+      context 'with a valid auth token' do
+        context 'when the contact exists' do
+          let(:contact) do
+            { 'name' => 'Lead', 'email' => 'valid@email.com' }
+          end
+
+          before do
+            stub_request(:get, endpoint_with_valid_uuid)
+              .with(headers: valid_headers)
+              .to_return(status: 200, body: contact.to_json)
+          end
+
+          it 'returns the contact' do
+            response = contact_with_valid_token.by_identifier(:uuid, valid_uuid)
+            expect(response).to eq(contact)
+          end
         end
 
+        context 'when the contact does not exist' do
+          before do
+            stub_request(:get, endpoint_with_invalid_uuid)
+              .with(headers: valid_headers)
+              .to_return(not_found_response)
+          end
+
+          it 'raises a not found error' do
+            expect do
+              contact_with_valid_token.by_identifier(:uuid, invalid_uuid)
+            end.to raise_error(RDStation::Error::NotFound)
+          end
+        end
+      end
+
+      context 'with an invalid auth token' do
         before do
           stub_request(:get, endpoint_with_valid_uuid)
-            .with(headers: valid_headers)
-            .to_return(status: 200, body: contact.to_json)
+            .with(headers: invalid_token_headers)
+            .to_return(invalid_token_response)
         end
 
-        it 'returns the contact' do
-          response = contact_with_valid_token.by_uuid('valid_uuid')
-          expect(response).to eq(contact)
+        it 'raises an invalid token error' do
+          expect do
+            contact_with_invalid_token.by_identifier(:uuid, valid_uuid)
+          end.to raise_error(RDStation::Error::Unauthorized)
         end
       end
 
-      context 'when the contact does not exist' do
+      context 'with an expired auth token' do
         before do
-          stub_request(:get, endpoint_with_invalid_uuid)
-            .with(headers: valid_headers)
-            .to_return(not_found_response)
+          stub_request(:get, endpoint_with_valid_uuid)
+            .with(headers: expired_token_headers)
+            .to_return(expired_token_response)
         end
 
-        it 'raises a not found error' do
+        it 'raises a expired token error' do
           expect do
-            contact_with_valid_token.by_uuid(invalid_uuid)
-          end.to raise_error(RDStation::Error::NotFound)
+            contact_with_expired_token.by_identifier(:uuid, valid_uuid)
+          end.to raise_error(RDStation::Error::ExpiredAccessToken)
         end
       end
-    end
 
-    context 'with an invalid auth token' do
-      before do
-        stub_request(:get, endpoint_with_valid_uuid)
-          .with(headers: invalid_token_headers)
-          .to_return(invalid_token_response)
-      end
+      describe 'with non-string identifier_value' do
+        let(:numeric_uuid) { 123 }
+        let(:endpoint_with_numeric_uuid) do
+          "https://api.rd.services/platform/contacts/#{numeric_uuid}"
+        end
 
-      it 'raises an invalid token error' do
-        expect do
-          contact_with_invalid_token.by_uuid(valid_uuid)
-        end.to raise_error(RDStation::Error::Unauthorized)
+        before do
+          stub_request(:get, endpoint_with_numeric_uuid)
+            .with(headers: valid_headers)
+            .to_return(status: 200, body: {}.to_json)
+        end
+
+        it 'converts identifier_value to string before building the path' do
+          response = contact_with_valid_token.by_identifier(:uuid, numeric_uuid)
+          expect(response).to eq({})
+        end
       end
     end
 
-    context 'with an expired auth token' do
-      before do
-        stub_request(:get, endpoint_with_valid_uuid)
-          .with(headers: expired_token_headers)
-          .to_return(expired_token_response)
+    describe 'with identifier_type :email' do
+      it 'calls retryable_request' do
+        expect(contact_with_valid_token).to receive(:retryable_request)
+        contact_with_valid_token.by_identifier(:email, valid_email)
       end
 
-      it 'raises a expired token error' do
-        expect do
-          contact_with_expired_token.by_uuid(valid_uuid)
-        end.to raise_error(RDStation::Error::ExpiredAccessToken)
+      context 'with a valid auth token' do
+        context 'when the contact exists' do
+          let(:contact) do
+            { 'name' => 'Lead', 'email' => 'valid@email.com' }
+          end
+
+          before do
+            stub_request(:get, endpoint_with_valid_email)
+              .with(headers: valid_headers)
+              .to_return(status: 200, body: contact.to_json)
+          end
+
+          it 'returns the contact' do
+            response = contact_with_valid_token.by_identifier(:email, valid_email)
+            expect(response).to eq(contact)
+          end
+        end
+
+        context 'when the contact does not exist' do
+          before do
+            stub_request(:get, endpoint_with_invalid_email)
+              .with(headers: valid_headers)
+              .to_return(not_found_response)
+          end
+
+          it 'raises a not found error' do
+            expect do
+              contact_with_valid_token.by_identifier(:email, invalid_email)
+            end.to raise_error(RDStation::Error::NotFound)
+          end
+        end
       end
-    end
-  end
 
-  describe '#by_email' do
-    it 'calls retryable_request' do
-      expect(contact_with_valid_token).to receive(:retryable_request)
-      contact_with_valid_token.by_email('x@xpto.com')
-    end
+      context 'with an invalid auth token' do
+        before do
+          stub_request(:get, endpoint_with_valid_email)
+            .with(headers: invalid_token_headers)
+            .to_return(invalid_token_response)
+        end
 
-    context 'with a valid auth token' do
-      context 'when the contact exists' do
-        let(:contact) do
-          { 'name' => 'Lead', 'email' => 'valid@email.com' }
+        it 'raises an invalid token error' do
+          expect do
+            contact_with_invalid_token.by_identifier(:email, valid_email)
+          end.to raise_error(RDStation::Error::Unauthorized)
         end
+      end
 
+      context 'with an expired auth token' do
         before do
           stub_request(:get, endpoint_with_valid_email)
+            .with(headers: expired_token_headers)
+            .to_return(expired_token_response)
+        end
+
+        it 'raises a expired token error' do
+          expect do
+            contact_with_expired_token.by_identifier(:email, valid_email)
+          end.to raise_error(RDStation::Error::ExpiredAccessToken)
+        end
+      end
+
+      context 'when the email contains characters that must be URL encoded' do
+        let(:contact) do
+          { 'name' => 'Lead', 'email' => special_chars_email }
+        end
+
+        before do
+          stub_request(:get, endpoint_with_special_chars_email)
             .with(headers: valid_headers)
             .to_return(status: 200, body: contact.to_json)
         end
 
-        it 'returns the contact' do
-          response = contact_with_valid_token.by_email(valid_email)
+        it 'encodes identifier_value in the request path' do
+          response = contact_with_valid_token.by_identifier(:email, special_chars_email)
           expect(response).to eq(contact)
         end
       end
+    end
+
+    describe 'with identifier_type :phone' do
+      it 'calls retryable_request' do
+        expect(contact_with_valid_token).to receive(:retryable_request)
+        contact_with_valid_token.by_identifier(:phone, valid_phone)
+      end
+
+      context 'with a valid auth token' do
+        context 'when the contact exists' do
+          let(:contact) do
+            { 'name' => 'Lead', 'phone' => valid_phone }
+          end
+
+          before do
+            stub_request(:get, endpoint_with_valid_phone)
+              .with(headers: valid_headers)
+              .to_return(status: 200, body: contact.to_json)
+          end
+
+          it 'returns the contact' do
+            response = contact_with_valid_token.by_identifier(:phone, valid_phone)
+            expect(response).to eq(contact)
+          end
+        end
+
+        context 'when the contact does not exist' do
+          before do
+            stub_request(:get, endpoint_with_invalid_phone)
+              .with(headers: valid_headers)
+              .to_return(not_found_response)
+          end
+
+          it 'raises a not found error' do
+            expect do
+              contact_with_valid_token.by_identifier(:phone, invalid_phone)
+            end.to raise_error(RDStation::Error::NotFound)
+          end
+        end
+      end
 
-      context 'when the contact does not exist' do
+      context 'with an invalid auth token' do
         before do
-          stub_request(:get, endpoint_with_invalid_email)
-            .with(headers: valid_headers)
-            .to_return(not_found_response)
+          stub_request(:get, endpoint_with_valid_phone)
+            .with(headers: invalid_token_headers)
+            .to_return(invalid_token_response)
         end
 
-        it 'raises a not found error' do
+        it 'raises an invalid token error' do
           expect do
-            contact_with_valid_token.by_email(invalid_email)
-          end.to raise_error(RDStation::Error::NotFound)
+            contact_with_invalid_token.by_identifier(:phone, valid_phone)
+          end.to raise_error(RDStation::Error::Unauthorized)
         end
       end
-    end
 
-    context 'with an invalid auth token' do
-      before do
-        stub_request(:get, endpoint_with_valid_email)
-          .with(headers: invalid_token_headers)
-          .to_return(invalid_token_response)
+      context 'with an expired auth token' do
+        before do
+          stub_request(:get, endpoint_with_valid_phone)
+            .with(headers: expired_token_headers)
+            .to_return(expired_token_response)
+        end
+
+        it 'raises a expired token error' do
+          expect do
+            contact_with_expired_token.by_identifier(:phone, valid_phone)
+          end.to raise_error(RDStation::Error::ExpiredAccessToken)
+        end
       end
+    end
 
-      it 'raises an invalid token error' do
+    describe 'with invalid identifier_type' do
+      it 'raises an ArgumentError' do
         expect do
-          contact_with_invalid_token.by_email(valid_email)
-        end.to raise_error(RDStation::Error::Unauthorized)
+          contact_with_valid_token.by_identifier(:invalid, 'some_value')
+        end.to raise_error(ArgumentError, /Invalid identifier type/)
       end
     end
 
-    context 'with an expired auth token' do
-      before do
-        stub_request(:get, endpoint_with_valid_email)
-          .with(headers: expired_token_headers)
-          .to_return(expired_token_response)
+    describe 'with invalid identifier_value' do
+      it 'raises ArgumentError when identifier_value is nil' do
+        expect do
+          contact_with_valid_token.by_identifier(:email, nil)
+        end.to raise_error(ArgumentError, /identifier_value cannot be nil or empty/)
       end
 
-      it 'raises a expired token error' do
+      it 'raises ArgumentError when identifier_value is an empty string' do
         expect do
-          contact_with_expired_token.by_email(valid_email)
-        end.to raise_error(RDStation::Error::ExpiredAccessToken)
+          contact_with_valid_token.by_identifier(:email, '')
+        end.to raise_error(ArgumentError, /identifier_value cannot be nil or empty/)
       end
     end
   end
 
+  describe '#by_uuid' do
+    it 'delegates to by_identifier with :uuid' do
+      expect(contact_with_valid_token).to receive(:by_identifier).with(:uuid, valid_uuid)
+      contact_with_valid_token.by_uuid(valid_uuid)
+    end
+  end
+
+  describe '#by_email' do
+    it 'delegates to by_identifier with :email' do
+      expect(contact_with_valid_token).to receive(:by_identifier).with(:email, valid_email)
+      contact_with_valid_token.by_email(valid_email)
+    end
+  end
+
+  describe '#by_phone' do
+    it 'delegates to by_identifier with :phone' do
+      expect(contact_with_valid_token).to receive(:by_identifier).with(:phone, valid_phone)
+      contact_with_valid_token.by_phone(valid_phone)
+    end
+  end
+
   describe '#update' do
     it 'calls retryable_request' do
       expect(contact_with_valid_token).to receive(:retryable_request)

data/spec/spec_helper.rb

@@ -1,2 +1,3 @@
 require 'rdstation-ruby-client'
 require 'webmock/rspec'
+require 'uri'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rdstation-ruby-client
 version: !ruby/object:Gem::Version
-  version: 2.9.0
+  version: 2.10.0
 platform: ruby
 authors:
 - Paulo L F Casaretto
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-14 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -218,7 +218,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.4.20
 signing_key:
 specification_version: 4
 summary: Ruby API wrapper for RD Station