From 1d4e686834d37ace329bfbeb1236820245815180 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:48:24 +0200
Subject: [PATCH 01/17] Add Group objects

---
 lib/messagebird/contact_reference.rb |  7 +++++++
 lib/messagebird/group.rb             | 21 +++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 lib/messagebird/contact_reference.rb
 create mode 100644 lib/messagebird/group.rb

diff --git a/lib/messagebird/contact_reference.rb b/lib/messagebird/contact_reference.rb
new file mode 100644
index 0000000..6da56fc
--- /dev/null
+++ b/lib/messagebird/contact_reference.rb
@@ -0,0 +1,7 @@
+require 'messagebird/base'
+
+module MessageBird
+  class ContactReference < MessageBird::Base
+    attr_accessor :href, :totalCount
+  end
+end
diff --git a/lib/messagebird/group.rb b/lib/messagebird/group.rb
new file mode 100644
index 0000000..d7b19c6
--- /dev/null
+++ b/lib/messagebird/group.rb
@@ -0,0 +1,21 @@
+require 'messagebird/base'
+require 'messagebird/contact_reference'
+
+module MessageBird
+  class Group < MessageBird::Base
+    attr_accessor :id, :href, :name, :contacts, :createdDatetime,
+                  :updatedDatetime
+
+    def contacts=(value)
+      @contacts = MessageBird::ContactReference.new(value)
+    end
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def updatedDatetime=(value)
+      @updatedDatetime = value_to_time(value)
+    end
+  end
+end
\ No newline at end of file

From 566e1c68555fda197451965d4e6c22deef6930b5 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:48:45 +0200
Subject: [PATCH 02/17] Add Group endpoints to Client

---
 lib/messagebird/client.rb |  48 +++++++++++++++
 spec/group_spec.rb        | 125 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 spec/group_spec.rb

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index d69b324..a2fa66b 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -5,6 +5,7 @@
 require 'messagebird/balance'
 require 'messagebird/contact'
 require 'messagebird/error'
+require 'messagebird/group'
 require 'messagebird/hlr'
 require 'messagebird/http_client'
 require 'messagebird/list'
@@ -161,5 +162,52 @@ def contact_list(limit = 0, offset = 0)
       List.new(Contact, request(:get, "contacts?limit=#{limit}&offset=#{offset}"))
     end
 
+    def group(id)
+      Group.new(request(:get, "groups/#{id}"))
+    end
+
+    def group_create(name)
+      Group.new(request(:post, 'groups', { :name => name }))
+    end
+
+    def group_delete(id)
+      request(:delete, "groups/#{id}")
+    end
+
+    def group_update(id, name)
+      request(:patch, "groups/#{id}", { :name => name })
+    end
+
+    def group_add_contacts(group_id, contact_ids)
+      # We expect an array, but we can handle a string ID as well...
+      contact_ids = [contact_ids] if contact_ids.is_a? String
+
+      query = add_contacts_query(contact_ids)
+
+      request(:get, "groups/#{group_id}?#{query}")
+    end
+
+    def group_delete_contact(group_id, contact_id)
+      request(:delete, "groups/#{group_id}/contacts/#{contact_id}")
+    end
+
+    private # Applies to every method below this line
+
+    def add_contacts_query(contact_ids)
+      # add_contacts_query gets a query string to add contacts to a group.
+      # We're using the alternative "/foo?_method=PUT&key=value" format to send
+      # the contact IDs as GET params. Sending these in the request body would
+      # require a painful workaround, as the client sends request bodies as
+      # JSON by default. See also:
+      # https://developers.messagebird.com/docs/alternatives.
+
+      s = StringIO.new
+
+      s << '_method=PUT'
+      contact_ids.each { |e| s << "&ids[]=#{e}" }
+
+      s.string
+    end
+
   end
 end
diff --git a/spec/group_spec.rb b/spec/group_spec.rb
new file mode 100644
index 0000000..ec785bb
--- /dev/null
+++ b/spec/group_spec.rb
@@ -0,0 +1,125 @@
+describe 'Group' do
+
+  it 'creates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:post, 'groups', { :name => 'friends'})
+      .and_return('{}')
+
+    client.group_create('friends')
+
+  end
+
+  it 'deletes' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:delete, 'groups/group-id', {})
+      .and_return('')
+
+    client.group_delete('group-id')
+
+  end
+
+  it 'lists' do
+    # todo
+  end
+
+  it 'reads an existing' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id', {})
+      .and_return('{"id": "group-id","href": "https://rest.messagebird.com/groups/group-id","name": "Friends","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/group-id"},"createdDatetime": "2018-07-25T12:16:10+00:00","updatedDatetime": "2018-07-25T12:16:23+00:00"}')
+
+    group = client.group('group-id')
+
+    expect(group.id).to eq 'group-id'
+    expect(group.name).to eq 'Friends'
+
+  end
+
+  it 'reads the contact reference' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id', {})
+      .and_return('{"id": "group-id","href": "https://rest.messagebird.com/groups/group-id","name": "Friends","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/group-id/contacts"},"createdDatetime": "2018-07-25T12:16:10+00:00","updatedDatetime": "2018-07-25T12:16:23+00:00"}')
+
+    group = client.group('group-id')
+
+    expect(group.contacts.href).to eq 'https://rest.messagebird.com/groups/group-id/contacts'
+    expect(group.contacts.totalCount).to eq 3
+
+  end
+
+  it 'updates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:patch, 'groups/group-id', { :name => 'family' })
+      .and_return('{}')
+
+    client.group_update('group-id', 'family')
+
+  end
+
+  it 'adds contacts' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id?_method=PUT&ids[]=first-contact-id&ids[]=second-contact-id', { })
+      .and_return('{}')
+
+    client.group_add_contacts('group-id', ['first-contact-id', 'second-contact-id'])
+
+  end
+
+  it 'adds single contact' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id?_method=PUT&ids[]=contact-id', { })
+      .and_return('{}')
+
+    client.group_add_contacts('group-id', 'contact-id')
+
+  end
+
+  it 'removes contact' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:delete, 'groups/group-id/contacts/contact-id', {})
+      .and_return('{}')
+
+    client.group_delete_contact('group-id', 'contact-id')
+
+  end
+
+end
\ No newline at end of file

From fabfdcedadbe479cb98bdfb966233aa92a81b532 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:54:30 +0200
Subject: [PATCH 03/17] Add Group list endpoint

---
 lib/messagebird/client.rb |  4 ++++
 spec/group_spec.rb        | 15 ++++++++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index a2fa66b..97d324c 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -174,6 +174,10 @@ def group_delete(id)
       request(:delete, "groups/#{id}")
     end
 
+    def group_list(limit = 0, offset = 0)
+      List.new(Group, request(:get, "groups?limit=#{limit}&offset=#{offset}"))
+    end
+
     def group_update(id, name)
       request(:patch, "groups/#{id}", { :name => name })
     end
diff --git a/spec/group_spec.rb b/spec/group_spec.rb
index ec785bb..6b512b6 100644
--- a/spec/group_spec.rb
+++ b/spec/group_spec.rb
@@ -29,7 +29,20 @@
   end
 
   it 'lists' do
-    # todo
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups?limit=0&offset=0', {})
+      .and_return('{"offset": 0,"limit": 10,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/groups?offset=0&limit=10","previous": null,"next": null,"last": "https://rest.messagebird.com/groups?offset=0&limit=10"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/groups/first-id","name": "First","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/first-id/contacts"},"createdDatetime": "2018-07-25T11:47:42+00:00","updatedDatetime": "2018-07-25T14:03:09+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/groups/second-id","name": "Second","contacts": {"totalCount": 4,"href": "https://rest.messagebird.com/groups/second-id/contacts"},"createdDatetime": "2018-07-25T11:47:39+00:00","updatedDatetime": "2018-07-25T14:03:09+00:00"}]}')
+
+    list = client.group_list
+
+    expect(list.count).to eq 2
+    expect(list[0].id).to eq 'first-id'
+
   end
 
   it 'reads an existing' do

From b8cc15c40ffcf842e5fd0bb6241e7ff57504fd04 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 16:05:26 +0200
Subject: [PATCH 04/17] Add examples

---
 examples/group_create.rb | 46 ++++++++++++++++++++++++++++++++++
 examples/group_list.rb   | 53 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 examples/group_create.rb
 create mode 100644 examples/group_list.rb

diff --git a/examples/group_create.rb b/examples/group_create.rb
new file mode 100644
index 0000000..1467410
--- /dev/null
+++ b/examples/group_create.rb
@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+# ACCESS_KEY = 'YOUR KEY HERE'
+# GROUP_NAME = 'YOUR GROUP NAME HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+unless defined?(GROUP_NAME)
+  puts 'You need to set an GROUP_NAME constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Create a new Group object.
+  group = client.group_create(GROUP_NAME)
+
+  # Print the object information.
+  puts
+  puts "  Group             :"
+  puts "    id              : #{group.id}"
+  puts "    href            : #{group.href}"
+  puts "    name            : #{group.name}"
+  puts "    contacts        : #{group.contacts.href}"
+  puts
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while creating a group:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end
diff --git a/examples/group_list.rb b/examples/group_list.rb
new file mode 100644
index 0000000..3c09253
--- /dev/null
+++ b/examples/group_list.rb
@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+ACCESS_KEY = 'YOUR KEY HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Fetch the Group list with pagination options (skip the first 5 objects and take 10).
+  limit = 10
+  offset = 5
+  groups = client.group_list(limit, offset)
+
+  # Print the object information.
+  puts
+  puts "The following information was returned as a Group list:"
+  puts
+  puts "  count           : #{groups.count}"
+  puts "  limit           : #{groups.limit}"
+  puts "  offset          : #{groups.offset}"
+  puts "  totalCount      : #{groups.totalCount}"
+  puts "  links           : #{groups.links}"
+
+  unless groups.items.empty?
+    group = groups[0] # Equivalent to groups.items[0]
+
+    puts "  Group             :"
+    puts "    id              : #{group.id}"
+    puts "    href            : #{group.href}"
+    puts "    name            : #{group.name}"
+    puts "    contacts        : #{group.contacts.href}"
+  end
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while listing your groups:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end

From 1f99e0b4caf7b0fe8064893a78dabdd127ba5a2f Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 12:19:48 +0200
Subject: [PATCH 05/17] Extract request preparation to separate method

---
 lib/messagebird/http_client.rb | 38 +++++++++++++++++++++++++---------
 1 file changed, 28 insertions(+), 10 deletions(-)

diff --git a/lib/messagebird/http_client.rb b/lib/messagebird/http_client.rb
index f21b9d5..462d369 100644
--- a/lib/messagebird/http_client.rb
+++ b/lib/messagebird/http_client.rb
@@ -22,8 +22,33 @@ def request(method, path, params={}, check_json=true)
       http = Net::HTTP.new(uri.host, uri.port)
       http.use_ssl     = true
 
-      # Construct the HTTP GET or POST request.
+      request = prepare_request(method, uri, params)
+
+      # Execute the request and fetch the response.
+      response = http.request(request)
+
+      # Parse the HTTP response.
+      case response.code.to_i
+      when 200, 201, 204, 401, 404, 405, 422
+        # Ok
+      else
+        raise InvalidPhoneNumberException, 'Unknown response from server'
+      end
+
+      # Execute the request and fetch the response.
+      response = http.request(request)
+
+      assert_valid_response_code(response.code.to_i)
+      assert_json_response_type(response['Content-Type']) unless check_json
+
+      response.body
+    end
+
+    def prepare_request(method, uri, params={})
+      # Construct the HTTP request.
       case method
+      when :delete
+        request = Net::HTTP::Delete.new(uri.request_uri)
       when :get
         request = Net::HTTP::Get.new(uri.request_uri)
       when :post
@@ -36,16 +61,9 @@ def request(method, path, params={}, check_json=true)
       request['Authorization'] = "AccessKey #{@access_key}"
       request['User-Agent']    = "MessageBird/ApiClient/#{CLIENT_VERSION} Ruby/#{RUBY_VERSION}"
 
-      # If present, add the HTTP POST parameters.
       request.set_form_data(params) if method == :post && !params.empty?
 
-      # Execute the request and fetch the response.
-      response = http.request(request)
-
-      assert_valid_response_code(response.code.to_i)
-      assert_json_response_type(response['Content-Type']) unless check_json
-
-      response.body
+      request
     end
 
     # Throw an exception if the response code is not one we expect from the
@@ -68,4 +86,4 @@ def assert_json_response_type(content_type)
 
   end
 
-end
+end
\ No newline at end of file

From 844b01ecfb3c3a12304807c9e33260fcaf55e8d6 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 13:56:25 +0200
Subject: [PATCH 06/17] Add Contact objects

---
 lib/messagebird/contact.rb           | 31 ++++++++++++++++++++++++++++
 lib/messagebird/custom_details.rb    |  6 ++++++
 lib/messagebird/group_reference.rb   |  5 +++++
 lib/messagebird/list.rb              | 23 +++++++++++++++++++++
 lib/messagebird/message_reference.rb |  5 +++++
 5 files changed, 70 insertions(+)
 create mode 100644 lib/messagebird/contact.rb
 create mode 100644 lib/messagebird/custom_details.rb
 create mode 100644 lib/messagebird/group_reference.rb
 create mode 100644 lib/messagebird/list.rb
 create mode 100644 lib/messagebird/message_reference.rb

diff --git a/lib/messagebird/contact.rb b/lib/messagebird/contact.rb
new file mode 100644
index 0000000..4b32863
--- /dev/null
+++ b/lib/messagebird/contact.rb
@@ -0,0 +1,31 @@
+require 'messagebird/base'
+require 'messagebird/custom_details'
+require 'messagebird/group_reference'
+require 'messagebird/message_reference'
+
+module MessageBird
+  class Contact < MessageBird::Base
+    attr_accessor :id, :href, :msisdn, :firstName, :lastName, :customDetails,
+                  :groups, :messages, :createdDatetime, :updatedDatetime
+
+    def customDetails=(value)
+      @customDetails = CustomDetails.new(value)
+    end
+
+    def groups=(value)
+      @groups = GroupReference.new(value)
+    end
+
+    def messages=(value)
+      @messages = MessageReference.new(value)
+    end
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def updatedDatetime=(value)
+      @updatedDatetime = value_to_time(value)
+    end
+  end
+end
\ No newline at end of file
diff --git a/lib/messagebird/custom_details.rb b/lib/messagebird/custom_details.rb
new file mode 100644
index 0000000..43b724e
--- /dev/null
+++ b/lib/messagebird/custom_details.rb
@@ -0,0 +1,6 @@
+require 'messagebird/base'
+
+class CustomDetails < MessageBird::Base
+  # CustomDetails holds free-input fields for the Contact object.
+  attr_accessor :custom1, :custom2, :custom3, :custom4
+end
diff --git a/lib/messagebird/group_reference.rb b/lib/messagebird/group_reference.rb
new file mode 100644
index 0000000..2edd3cc
--- /dev/null
+++ b/lib/messagebird/group_reference.rb
@@ -0,0 +1,5 @@
+require 'messagebird/base'
+
+class GroupReference < MessageBird::Base
+  attr_accessor :href, :totalCount
+end
diff --git a/lib/messagebird/list.rb b/lib/messagebird/list.rb
new file mode 100644
index 0000000..b9871ff
--- /dev/null
+++ b/lib/messagebird/list.rb
@@ -0,0 +1,23 @@
+require 'messagebird/base'
+
+class List < MessageBird::Base
+
+  attr_accessor :offset, :limit, :count, :totalCount, :links, :items
+
+  # type will be used to create objects for the items, e.g.
+  # List.new(Contact, {}).
+  def initialize(type, json)
+    @type = type
+
+    super(json)
+  end
+
+  def items=(value)
+    @items = value.map { |i| @type.new i }
+  end
+
+  def [](index)
+    @items[index]
+  end
+
+end
\ No newline at end of file
diff --git a/lib/messagebird/message_reference.rb b/lib/messagebird/message_reference.rb
new file mode 100644
index 0000000..da3955b
--- /dev/null
+++ b/lib/messagebird/message_reference.rb
@@ -0,0 +1,5 @@
+require 'messagebird/base'
+
+class MessageReference < MessageBird::Base
+  attr_accessor :href, :totalCount
+end
\ No newline at end of file

From b255bea6134daf17fe7dc981e881ab45b9fb11e9 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 13:57:38 +0200
Subject: [PATCH 07/17] Add Contact endpoints to Client

---
 lib/messagebird/client.rb |  31 ++++++-
 spec/contact_spec.rb      | 166 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 195 insertions(+), 2 deletions(-)
 create mode 100644 spec/contact_spec.rb

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index ac19dac..9e0a30b 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -3,13 +3,15 @@
 require 'uri'
 
 require 'messagebird/balance'
+require 'messagebird/contact'
 require 'messagebird/error'
 require 'messagebird/hlr'
 require 'messagebird/http_client'
-require 'messagebird/verify'
+require 'messagebird/list'
+require 'messagebird/lookup'
 require 'messagebird/message'
+require 'messagebird/verify'
 require 'messagebird/voicemessage'
-require 'messagebird/lookup'
 
 module MessageBird
   class ErrorException < StandardError
@@ -32,6 +34,8 @@ def initialize(access_key = nil, http_client = nil)
 
     def request(method, path, params={})
       response_body = @http_client.request(method, path, params)
+      return if response_body.empty?
+
       json = JSON.parse(response_body)
 
       # If the request returned errors, create Error objects and raise.
@@ -134,5 +138,28 @@ def lookup_hlr(phoneNumber, params={})
       HLR.new(request(:get, "lookup/#{phoneNumber}/hlr", params))
     end
 
+    def contact_create(phoneNumber, params={})
+      Contact.new(request(
+                      :post,
+                      'contacts',
+                      params.merge({ :msisdn => phoneNumber.to_s })))
+    end
+
+    def contact(id)
+      Contact.new(request(:get, "contacts/#{id}"))
+    end
+
+    def contact_delete(id)
+      request(:delete, "contacts/#{id}")
+    end
+
+    def contact_update(id, params={})
+      request(:patch, "contacts/#{id}", params)
+    end
+
+    def contact_list(params={})
+      List.new(Contact, request(:get, 'contacts', params))
+    end
+
   end
 end
diff --git a/spec/contact_spec.rb b/spec/contact_spec.rb
new file mode 100644
index 0000000..95eae17
--- /dev/null
+++ b/spec/contact_spec.rb
@@ -0,0 +1,166 @@
+describe 'Contact' do
+
+  it 'creates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:post, 'contacts', { :msisdn => '31612345678', :firstName => 'Foo', :lastName => 'Bar', :custom1 => 'First', :custom4 => 'Fourth'})
+      .and_return('{}')
+
+    client.contact_create(31612345678, { :firstName => 'Foo', :lastName => 'Bar', :custom1 => 'First', :custom4 => 'Fourth' })
+
+  end
+
+  it 'deletes' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(client)
+      .to receive(:request)
+      .with(:delete, 'contacts/contact-id')
+      .and_return('')
+
+    client.contact_delete('contact-id')
+
+  end
+
+  it 'lists' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts', {})
+      .and_return('{"offset": 0,"limit": 20,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/contacts?offset=0","previous": null,"next": null,"last": "https://rest.messagebird.com/contacts?offset=0"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/contacts/first-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:34:08+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/contacts/second-id","msisdn": 49612345678,"firstName": "Hello","lastName": "World","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/messages"},"createdDatetime": "2018-07-13T10:33:52+00:00","updatedDatetime": null}]}')
+
+    list = client.contact_list
+
+    expect(list.offset).to eq 0
+    expect(list.limit).to eq 20
+    expect(list.count).to eq 2
+    expect(list.totalCount).to eq 2
+
+    expect(list.items[0].id).to eq 'first-id'
+
+  end
+
+  it 'lists and allows array access' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts', {})
+      .and_return('{"offset": 0,"limit": 20,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/contacts?offset=0","previous": null,"next": null,"last": "https://rest.messagebird.com/contacts?offset=0"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/contacts/first-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:34:08+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/contacts/second-id","msisdn": 49612345678,"firstName": "Hello","lastName": "World","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/messages"},"createdDatetime": "2018-07-13T10:33:52+00:00","updatedDatetime": null}]}')
+
+    list = client.contact_list
+
+    expect(list[1].id).to eq 'second-id'
+
+  end
+
+  it 'lists with pagination' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts', { :limit => 10, :offset => 20 })
+      .and_return('{}')
+
+    client.contact_list({:limit => 10, :offset => 20})
+
+  end
+
+  it 'reads an existing' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts/contact-id', {})
+      .and_return('{"id": "contact-id","href": "https://rest.messagebird.com/contacts/contact-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": "First","custom2": "Second","custom3": "Third","custom4": "Fourth"},"groups": {"totalCount": 3,"href": "https://rest.messagebird.com/contacts/contact-id/groups"},"messages": {"totalCount": 5,"href": "https://rest.messagebird.com/contacts/contact-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:44:08+00:00"}')
+
+    contact = client.contact('contact-id')
+
+    expect(contact.id).to eq 'contact-id'
+    expect(contact.msisdn).to eq 31612345678
+
+  end
+
+  it 'reads custom details' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts/contact-id', {})
+      .and_return('{"id": "contact-id","href": "https://rest.messagebird.com/contacts/contact-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": "First","custom2": "Second","custom3": "Third","custom4": "Fourth"},"groups": {"totalCount": 3,"href": "https://rest.messagebird.com/contacts/contact-id/groups"},"messages": {"totalCount": 5,"href": "https://rest.messagebird.com/contacts/contact-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:44:08+00:00"}')
+
+    contact = client.contact('contact-id')
+
+    expect(contact.customDetails).to be_an_instance_of(CustomDetails)
+
+    expect(contact.customDetails.custom1).to eq 'First'
+    expect(contact.customDetails.custom4).to eq 'Fourth'
+
+  end
+
+  it 'updates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:patch, 'contacts/contact-id', { :msisdn => 31687654321, :custom3 => 'Third' })
+      .and_return('')
+
+    client.contact_update('contact-id', { :msisdn => 31687654321, :custom3 => 'Third' })
+
+  end
+
+  it 'lists groups' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts/contact-id', {})
+      .and_return('{"id": "contact-id","href": "https://rest.messagebird.com/contacts/contact-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": "First","custom2": "Second","custom3": "Third","custom4": "Fourth"},"groups": {"totalCount": 3,"href": "https://rest.messagebird.com/contacts/contact-id/groups"},"messages": {"totalCount": 5,"href": "https://rest.messagebird.com/contacts/contact-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:44:08+00:00"}')
+
+    contact = client.contact('contact-id')
+
+    expect(contact.groups.href).to eq 'https://rest.messagebird.com/contacts/contact-id/groups'
+    expect(contact.groups.totalCount).to eq 3
+
+  end
+
+  it 'lists messages' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'contacts/contact-id', {})
+      .and_return('{"id": "contact-id","href": "https://rest.messagebird.com/contacts/contact-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": "First","custom2": "Second","custom3": "Third","custom4": "Fourth"},"groups": {"totalCount": 3,"href": "https://rest.messagebird.com/contacts/contact-id/groups"},"messages": {"totalCount": 5,"href": "https://rest.messagebird.com/contacts/contact-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:44:08+00:00"}')
+
+    contact = client.contact('contact-id')
+
+    expect(contact.messages.href).to eq 'https://rest.messagebird.com/contacts/contact-id/messages'
+    expect(contact.messages.totalCount).to eq 5
+
+  end
+
+end
\ No newline at end of file

From 9cbcc60e53d2da54d94062c1576bd348b37f6467 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 13:57:53 +0200
Subject: [PATCH 08/17] Add examples

---
 examples/contact_create.rb | 54 ++++++++++++++++++++++++++++++++++
 examples/contact_list.rb   | 60 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 114 insertions(+)
 create mode 100644 examples/contact_create.rb
 create mode 100644 examples/contact_list.rb

diff --git a/examples/contact_create.rb b/examples/contact_create.rb
new file mode 100644
index 0000000..ab12e00
--- /dev/null
+++ b/examples/contact_create.rb
@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+# ACCESS_KEY = 'YOUR KEY HERE'
+# PHONE_NUMBER = 'YOUR PHONE NUMBER HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+unless defined?(PHONE_NUMBER)
+  puts 'You need to set an PHONE_NUMBER constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Create a new Contact object.
+  contact = client.contact_create(PHONE_NUMBER, { :firstName => 'Foo', :lastName => 'Bar'})
+
+  # Print the object information.
+  puts
+  puts "  Contact           :"
+  puts
+  puts "    id              : #{contact.id}"
+  puts "    href            : #{contact.href}"
+  puts "    msisdn          : #{contact.msisdn}"
+  puts "    firstName       : #{contact.firstName}"
+  puts "    lastName        : #{contact.lastName}"
+  puts "    groups          : #{contact.groups.href}" # contact.groups.totalCount is also available.
+  puts "    messages        : #{contact.messages.href}" # contact.messages.totalCount is also available.
+  puts "    custom1         : #{contact.customDetails.custom1}"
+  puts "    custom2         : #{contact.customDetails.custom2}"
+  puts "    custom3         : #{contact.customDetails.custom3}"
+  puts "    custom4         : #{contact.customDetails.custom4}"
+  puts
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while creating a contact:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end
diff --git a/examples/contact_list.rb b/examples/contact_list.rb
new file mode 100644
index 0000000..3554940
--- /dev/null
+++ b/examples/contact_list.rb
@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+ACCESS_KEY = 'YOUR KEY HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Fetch the Contact list.
+  pagination = { :limit => 20, :offset => 0}
+  contacts = client.contact_list(pagination)
+
+  # Print the object information.
+  puts
+  puts "The following information was returned as a Contact list:"
+  puts
+  puts "  count           : #{contacts.count}"
+  puts "  limit           : #{contacts.limit}"
+  puts "  offset          : #{contacts.offset}"
+  puts "  totalCount      : #{contacts.totalCount}"
+  puts "  links           : #{contacts.links}"
+
+  unless contacts.items.empty?
+    contact = contacts[0] # Equivalent to contacts.items[0]
+
+    puts "  Contact             :"
+    puts "    id              : #{contact.id}"
+    puts "    href            : #{contact.href}"
+    puts "    msisdn          : #{contact.msisdn}"
+    puts "    firstName       : #{contact.firstName}"
+    puts "    lastName        : #{contact.lastName}"
+    puts "    groups          : #{contact.groups.href}" # contact.groups.totalCount is also available.
+    puts "    messages        : #{contact.messages.href}" # contact.messages.totalCount is also available.
+    puts "    custom1         : #{contact.customDetails.custom1}"
+    puts "    custom2         : #{contact.customDetails.custom2}"
+    puts "    custom3         : #{contact.customDetails.custom3}"
+    puts "    custom4         : #{contact.customDetails.custom4}"
+
+  end
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while listing your contacts:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end

From baca93a237495efd784021e28a75dfd692b5ad3d Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 14:58:24 +0200
Subject: [PATCH 09/17] Move objects to MessageBird module

---
 lib/messagebird/contact.rb           | 6 +++---
 lib/messagebird/custom_details.rb    | 8 +++++---
 lib/messagebird/group_reference.rb   | 6 ++++--
 lib/messagebird/message_reference.rb | 8 +++++---
 spec/contact_spec.rb                 | 2 +-
 5 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/lib/messagebird/contact.rb b/lib/messagebird/contact.rb
index 4b32863..847491c 100644
--- a/lib/messagebird/contact.rb
+++ b/lib/messagebird/contact.rb
@@ -9,15 +9,15 @@ class Contact < MessageBird::Base
                   :groups, :messages, :createdDatetime, :updatedDatetime
 
     def customDetails=(value)
-      @customDetails = CustomDetails.new(value)
+      @customDetails = MessageBird::CustomDetails.new(value)
     end
 
     def groups=(value)
-      @groups = GroupReference.new(value)
+      @groups = MessageBird::GroupReference.new(value)
     end
 
     def messages=(value)
-      @messages = MessageReference.new(value)
+      @messages = MessageBird::MessageReference.new(value)
     end
 
     def createdDatetime=(value)
diff --git a/lib/messagebird/custom_details.rb b/lib/messagebird/custom_details.rb
index 43b724e..969798b 100644
--- a/lib/messagebird/custom_details.rb
+++ b/lib/messagebird/custom_details.rb
@@ -1,6 +1,8 @@
 require 'messagebird/base'
 
-class CustomDetails < MessageBird::Base
-  # CustomDetails holds free-input fields for the Contact object.
-  attr_accessor :custom1, :custom2, :custom3, :custom4
+module MessageBird
+  class CustomDetails < MessageBird::Base
+    # CustomDetails holds free-input fields for the Contact object.
+    attr_accessor :custom1, :custom2, :custom3, :custom4
+  end
 end
diff --git a/lib/messagebird/group_reference.rb b/lib/messagebird/group_reference.rb
index 2edd3cc..295f171 100644
--- a/lib/messagebird/group_reference.rb
+++ b/lib/messagebird/group_reference.rb
@@ -1,5 +1,7 @@
 require 'messagebird/base'
 
-class GroupReference < MessageBird::Base
-  attr_accessor :href, :totalCount
+module MessageBird
+  class GroupReference < MessageBird::Base
+    attr_accessor :href, :totalCount
+  end
 end
diff --git a/lib/messagebird/message_reference.rb b/lib/messagebird/message_reference.rb
index da3955b..4a19dc2 100644
--- a/lib/messagebird/message_reference.rb
+++ b/lib/messagebird/message_reference.rb
@@ -1,5 +1,7 @@
 require 'messagebird/base'
 
-class MessageReference < MessageBird::Base
-  attr_accessor :href, :totalCount
-end
\ No newline at end of file
+module MessageBird
+  class MessageReference < MessageBird::Base
+    attr_accessor :href, :totalCount
+  end
+end
diff --git a/spec/contact_spec.rb b/spec/contact_spec.rb
index 95eae17..1ededa6 100644
--- a/spec/contact_spec.rb
+++ b/spec/contact_spec.rb
@@ -108,7 +108,7 @@
 
     contact = client.contact('contact-id')
 
-    expect(contact.customDetails).to be_an_instance_of(CustomDetails)
+    expect(contact.customDetails).to be_an_instance_of(MessageBird::CustomDetails)
 
     expect(contact.customDetails.custom1).to eq 'First'
     expect(contact.customDetails.custom4).to eq 'Fourth'

From 7440a3de042c305ced9410ffaf7cb8bf76a88f61 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:23:05 +0200
Subject: [PATCH 10/17] Require Contact classes

---
 lib/messagebird.rb | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/lib/messagebird.rb b/lib/messagebird.rb
index 2cd7a73..1ce4ca6 100644
--- a/lib/messagebird.rb
+++ b/lib/messagebird.rb
@@ -8,8 +8,12 @@ module MessageBird
 
 require 'messagebird/balance'
 require 'messagebird/client'
+require 'messagebird/contact'
 require 'messagebird/error'
+require 'messagebird/group_reference'
 require 'messagebird/hlr'
+require 'messagebird/http_client'
+require 'messagebird/message_reference'
 require 'messagebird/verify'
 require 'messagebird/message'
 require 'messagebird/voicemessage'

From 36b006a5a0e5c9e1b23e70c4aa2b2a9800632050 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:31:40 +0200
Subject: [PATCH 11/17] Fix query parameters

---
 examples/contact_list.rb  |  7 ++++---
 lib/messagebird/client.rb |  4 ++--
 spec/contact_spec.rb      | 10 +++++-----
 3 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/examples/contact_list.rb b/examples/contact_list.rb
index 3554940..6e55c8a 100644
--- a/examples/contact_list.rb
+++ b/examples/contact_list.rb
@@ -14,9 +14,10 @@
   # Create a MessageBird client with the specified ACCESS_KEY.
   client = MessageBird::Client.new(ACCESS_KEY)
 
-  # Fetch the Contact list.
-  pagination = { :limit => 20, :offset => 0}
-  contacts = client.contact_list(pagination)
+  # Fetch the Contact list with pagination options (skip the first 5 objects and take 10).
+  limit = 10
+  offset = 5
+  contacts = client.contact_list(limit, offset)
 
   # Print the object information.
   puts
diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index 9e0a30b..d69b324 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -157,8 +157,8 @@ def contact_update(id, params={})
       request(:patch, "contacts/#{id}", params)
     end
 
-    def contact_list(params={})
-      List.new(Contact, request(:get, 'contacts', params))
+    def contact_list(limit = 0, offset = 0)
+      List.new(Contact, request(:get, "contacts?limit=#{limit}&offset=#{offset}"))
     end
 
   end
diff --git a/spec/contact_spec.rb b/spec/contact_spec.rb
index 1ededa6..bf8af7d 100644
--- a/spec/contact_spec.rb
+++ b/spec/contact_spec.rb
@@ -35,7 +35,7 @@
 
     expect(http_client)
       .to receive(:request)
-      .with(:get, 'contacts', {})
+      .with(:get, 'contacts?limit=0&offset=0', {})
       .and_return('{"offset": 0,"limit": 20,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/contacts?offset=0","previous": null,"next": null,"last": "https://rest.messagebird.com/contacts?offset=0"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/contacts/first-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:34:08+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/contacts/second-id","msisdn": 49612345678,"firstName": "Hello","lastName": "World","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/messages"},"createdDatetime": "2018-07-13T10:33:52+00:00","updatedDatetime": null}]}')
 
     list = client.contact_list
@@ -56,10 +56,10 @@
 
     expect(http_client)
       .to receive(:request)
-      .with(:get, 'contacts', {})
+      .with(:get, 'contacts?limit=10&offset=0', {})
       .and_return('{"offset": 0,"limit": 20,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/contacts?offset=0","previous": null,"next": null,"last": "https://rest.messagebird.com/contacts?offset=0"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/contacts/first-id","msisdn": 31612345678,"firstName": "Foo","lastName": "Bar","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/first-id/messages"},"createdDatetime": "2018-07-13T10:34:08+00:00","updatedDatetime": "2018-07-13T10:34:08+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/contacts/second-id","msisdn": 49612345678,"firstName": "Hello","lastName": "World","customDetails": {"custom1": null,"custom2": null,"custom3": null,"custom4": null},"groups": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/groups"},"messages": {"totalCount": 0,"href": "https://rest.messagebird.com/contacts/second-id/messages"},"createdDatetime": "2018-07-13T10:33:52+00:00","updatedDatetime": null}]}')
 
-    list = client.contact_list
+    list = client.contact_list(10)
 
     expect(list[1].id).to eq 'second-id'
 
@@ -72,10 +72,10 @@
 
     expect(http_client)
       .to receive(:request)
-      .with(:get, 'contacts', { :limit => 10, :offset => 20 })
+      .with(:get, 'contacts?limit=10&offset=20', {})
       .and_return('{}')
 
-    client.contact_list({:limit => 10, :offset => 20})
+    client.contact_list(10, 20)
 
   end
 

From bf82d6bee31f98edf48a7a7c8c7fc895bd24ab1a Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:48:24 +0200
Subject: [PATCH 12/17] Add Group objects

---
 lib/messagebird/contact_reference.rb |  7 +++++++
 lib/messagebird/group.rb             | 21 +++++++++++++++++++++
 2 files changed, 28 insertions(+)
 create mode 100644 lib/messagebird/contact_reference.rb
 create mode 100644 lib/messagebird/group.rb

diff --git a/lib/messagebird/contact_reference.rb b/lib/messagebird/contact_reference.rb
new file mode 100644
index 0000000..6da56fc
--- /dev/null
+++ b/lib/messagebird/contact_reference.rb
@@ -0,0 +1,7 @@
+require 'messagebird/base'
+
+module MessageBird
+  class ContactReference < MessageBird::Base
+    attr_accessor :href, :totalCount
+  end
+end
diff --git a/lib/messagebird/group.rb b/lib/messagebird/group.rb
new file mode 100644
index 0000000..d7b19c6
--- /dev/null
+++ b/lib/messagebird/group.rb
@@ -0,0 +1,21 @@
+require 'messagebird/base'
+require 'messagebird/contact_reference'
+
+module MessageBird
+  class Group < MessageBird::Base
+    attr_accessor :id, :href, :name, :contacts, :createdDatetime,
+                  :updatedDatetime
+
+    def contacts=(value)
+      @contacts = MessageBird::ContactReference.new(value)
+    end
+
+    def createdDatetime=(value)
+      @createdDatetime = value_to_time(value)
+    end
+
+    def updatedDatetime=(value)
+      @updatedDatetime = value_to_time(value)
+    end
+  end
+end
\ No newline at end of file

From 50334b3960a522b235534cae5e381de3afb8fefd Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:48:45 +0200
Subject: [PATCH 13/17] Add Group endpoints to Client

---
 lib/messagebird/client.rb |  48 +++++++++++++++
 spec/group_spec.rb        | 125 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 173 insertions(+)
 create mode 100644 spec/group_spec.rb

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index d69b324..a2fa66b 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -5,6 +5,7 @@
 require 'messagebird/balance'
 require 'messagebird/contact'
 require 'messagebird/error'
+require 'messagebird/group'
 require 'messagebird/hlr'
 require 'messagebird/http_client'
 require 'messagebird/list'
@@ -161,5 +162,52 @@ def contact_list(limit = 0, offset = 0)
       List.new(Contact, request(:get, "contacts?limit=#{limit}&offset=#{offset}"))
     end
 
+    def group(id)
+      Group.new(request(:get, "groups/#{id}"))
+    end
+
+    def group_create(name)
+      Group.new(request(:post, 'groups', { :name => name }))
+    end
+
+    def group_delete(id)
+      request(:delete, "groups/#{id}")
+    end
+
+    def group_update(id, name)
+      request(:patch, "groups/#{id}", { :name => name })
+    end
+
+    def group_add_contacts(group_id, contact_ids)
+      # We expect an array, but we can handle a string ID as well...
+      contact_ids = [contact_ids] if contact_ids.is_a? String
+
+      query = add_contacts_query(contact_ids)
+
+      request(:get, "groups/#{group_id}?#{query}")
+    end
+
+    def group_delete_contact(group_id, contact_id)
+      request(:delete, "groups/#{group_id}/contacts/#{contact_id}")
+    end
+
+    private # Applies to every method below this line
+
+    def add_contacts_query(contact_ids)
+      # add_contacts_query gets a query string to add contacts to a group.
+      # We're using the alternative "/foo?_method=PUT&key=value" format to send
+      # the contact IDs as GET params. Sending these in the request body would
+      # require a painful workaround, as the client sends request bodies as
+      # JSON by default. See also:
+      # https://developers.messagebird.com/docs/alternatives.
+
+      s = StringIO.new
+
+      s << '_method=PUT'
+      contact_ids.each { |e| s << "&ids[]=#{e}" }
+
+      s.string
+    end
+
   end
 end
diff --git a/spec/group_spec.rb b/spec/group_spec.rb
new file mode 100644
index 0000000..ec785bb
--- /dev/null
+++ b/spec/group_spec.rb
@@ -0,0 +1,125 @@
+describe 'Group' do
+
+  it 'creates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:post, 'groups', { :name => 'friends'})
+      .and_return('{}')
+
+    client.group_create('friends')
+
+  end
+
+  it 'deletes' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:delete, 'groups/group-id', {})
+      .and_return('')
+
+    client.group_delete('group-id')
+
+  end
+
+  it 'lists' do
+    # todo
+  end
+
+  it 'reads an existing' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id', {})
+      .and_return('{"id": "group-id","href": "https://rest.messagebird.com/groups/group-id","name": "Friends","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/group-id"},"createdDatetime": "2018-07-25T12:16:10+00:00","updatedDatetime": "2018-07-25T12:16:23+00:00"}')
+
+    group = client.group('group-id')
+
+    expect(group.id).to eq 'group-id'
+    expect(group.name).to eq 'Friends'
+
+  end
+
+  it 'reads the contact reference' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id', {})
+      .and_return('{"id": "group-id","href": "https://rest.messagebird.com/groups/group-id","name": "Friends","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/group-id/contacts"},"createdDatetime": "2018-07-25T12:16:10+00:00","updatedDatetime": "2018-07-25T12:16:23+00:00"}')
+
+    group = client.group('group-id')
+
+    expect(group.contacts.href).to eq 'https://rest.messagebird.com/groups/group-id/contacts'
+    expect(group.contacts.totalCount).to eq 3
+
+  end
+
+  it 'updates' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:patch, 'groups/group-id', { :name => 'family' })
+      .and_return('{}')
+
+    client.group_update('group-id', 'family')
+
+  end
+
+  it 'adds contacts' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id?_method=PUT&ids[]=first-contact-id&ids[]=second-contact-id', { })
+      .and_return('{}')
+
+    client.group_add_contacts('group-id', ['first-contact-id', 'second-contact-id'])
+
+  end
+
+  it 'adds single contact' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups/group-id?_method=PUT&ids[]=contact-id', { })
+      .and_return('{}')
+
+    client.group_add_contacts('group-id', 'contact-id')
+
+  end
+
+  it 'removes contact' do
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:delete, 'groups/group-id/contacts/contact-id', {})
+      .and_return('{}')
+
+    client.group_delete_contact('group-id', 'contact-id')
+
+  end
+
+end
\ No newline at end of file

From 1a2063be0c7e0d366c7bedafc3066927c4177084 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 15:54:30 +0200
Subject: [PATCH 14/17] Add Group list endpoint

---
 lib/messagebird/client.rb |  4 ++++
 spec/group_spec.rb        | 15 ++++++++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index a2fa66b..97d324c 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -174,6 +174,10 @@ def group_delete(id)
       request(:delete, "groups/#{id}")
     end
 
+    def group_list(limit = 0, offset = 0)
+      List.new(Group, request(:get, "groups?limit=#{limit}&offset=#{offset}"))
+    end
+
     def group_update(id, name)
       request(:patch, "groups/#{id}", { :name => name })
     end
diff --git a/spec/group_spec.rb b/spec/group_spec.rb
index ec785bb..6b512b6 100644
--- a/spec/group_spec.rb
+++ b/spec/group_spec.rb
@@ -29,7 +29,20 @@
   end
 
   it 'lists' do
-    # todo
+
+    http_client = double(MessageBird::HttpClient)
+    client = MessageBird::Client.new('', http_client)
+
+    expect(http_client)
+      .to receive(:request)
+      .with(:get, 'groups?limit=0&offset=0', {})
+      .and_return('{"offset": 0,"limit": 10,"count": 2,"totalCount": 2,"links": {"first": "https://rest.messagebird.com/groups?offset=0&limit=10","previous": null,"next": null,"last": "https://rest.messagebird.com/groups?offset=0&limit=10"},"items": [{"id": "first-id","href": "https://rest.messagebird.com/groups/first-id","name": "First","contacts": {"totalCount": 3,"href": "https://rest.messagebird.com/groups/first-id/contacts"},"createdDatetime": "2018-07-25T11:47:42+00:00","updatedDatetime": "2018-07-25T14:03:09+00:00"},{"id": "second-id","href": "https://rest.messagebird.com/groups/second-id","name": "Second","contacts": {"totalCount": 4,"href": "https://rest.messagebird.com/groups/second-id/contacts"},"createdDatetime": "2018-07-25T11:47:39+00:00","updatedDatetime": "2018-07-25T14:03:09+00:00"}]}')
+
+    list = client.group_list
+
+    expect(list.count).to eq 2
+    expect(list[0].id).to eq 'first-id'
+
   end
 
   it 'reads an existing' do

From e41c3856012b86ad00f56395769bfed1451299a0 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Fri, 17 Aug 2018 16:05:26 +0200
Subject: [PATCH 15/17] Add examples

---
 examples/group_create.rb | 46 ++++++++++++++++++++++++++++++++++
 examples/group_list.rb   | 53 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 99 insertions(+)
 create mode 100644 examples/group_create.rb
 create mode 100644 examples/group_list.rb

diff --git a/examples/group_create.rb b/examples/group_create.rb
new file mode 100644
index 0000000..1467410
--- /dev/null
+++ b/examples/group_create.rb
@@ -0,0 +1,46 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+# ACCESS_KEY = 'YOUR KEY HERE'
+# GROUP_NAME = 'YOUR GROUP NAME HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+unless defined?(GROUP_NAME)
+  puts 'You need to set an GROUP_NAME constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Create a new Group object.
+  group = client.group_create(GROUP_NAME)
+
+  # Print the object information.
+  puts
+  puts "  Group             :"
+  puts "    id              : #{group.id}"
+  puts "    href            : #{group.href}"
+  puts "    name            : #{group.name}"
+  puts "    contacts        : #{group.contacts.href}"
+  puts
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while creating a group:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end
diff --git a/examples/group_list.rb b/examples/group_list.rb
new file mode 100644
index 0000000..3c09253
--- /dev/null
+++ b/examples/group_list.rb
@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib/')
+require 'messagebird'
+
+ACCESS_KEY = 'YOUR KEY HERE'
+
+unless defined?(ACCESS_KEY)
+  puts 'You need to set an ACCESS_KEY constant in this file'
+  exit 1
+end
+
+begin
+  # Create a MessageBird client with the specified ACCESS_KEY.
+  client = MessageBird::Client.new(ACCESS_KEY)
+
+  # Fetch the Group list with pagination options (skip the first 5 objects and take 10).
+  limit = 10
+  offset = 5
+  groups = client.group_list(limit, offset)
+
+  # Print the object information.
+  puts
+  puts "The following information was returned as a Group list:"
+  puts
+  puts "  count           : #{groups.count}"
+  puts "  limit           : #{groups.limit}"
+  puts "  offset          : #{groups.offset}"
+  puts "  totalCount      : #{groups.totalCount}"
+  puts "  links           : #{groups.links}"
+
+  unless groups.items.empty?
+    group = groups[0] # Equivalent to groups.items[0]
+
+    puts "  Group             :"
+    puts "    id              : #{group.id}"
+    puts "    href            : #{group.href}"
+    puts "    name            : #{group.name}"
+    puts "    contacts        : #{group.contacts.href}"
+  end
+
+rescue MessageBird::ErrorException => ex
+  puts
+  puts 'An error occurred while listing your groups:'
+  puts
+
+  ex.errors.each do |error|
+    puts "  code        : #{error.code}"
+    puts "  description : #{error.description}"
+    puts "  parameter   : #{error.parameter}"
+    puts
+  end
+end

From d81780cd69d3ae6717b3df1bb02a4770764ad185 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Mon, 10 Sep 2018 14:13:43 +0200
Subject: [PATCH 16/17] Use map() in favour of StringIO

---
 lib/messagebird/client.rb | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index 97d324c..f415555 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -205,12 +205,7 @@ def add_contacts_query(contact_ids)
       # JSON by default. See also:
       # https://developers.messagebird.com/docs/alternatives.
 
-      s = StringIO.new
-
-      s << '_method=PUT'
-      contact_ids.each { |e| s << "&ids[]=#{e}" }
-
-      s.string
+      '_method=PUT&' + contact_ids.map { |e| "ids[]=#{e}" }.join('&')
     end
 
   end

From a30001f708f76ac628b3496abe2f897e9d561d02 Mon Sep 17 00:00:00 2001
From: Emile Pels <emile@messagebird.com>
Date: Mon, 10 Sep 2018 14:15:00 +0200
Subject: [PATCH 17/17] Rename e to id.

It's much more descriptive, but short enough.
---
 lib/messagebird/client.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/messagebird/client.rb b/lib/messagebird/client.rb
index f415555..e634899 100644
--- a/lib/messagebird/client.rb
+++ b/lib/messagebird/client.rb
@@ -205,7 +205,7 @@ def add_contacts_query(contact_ids)
       # JSON by default. See also:
       # https://developers.messagebird.com/docs/alternatives.
 
-      '_method=PUT&' + contact_ids.map { |e| "ids[]=#{e}" }.join('&')
+      '_method=PUT&' + contact_ids.map { |id| "ids[]=#{id}" }.join('&')
     end
 
   end