Implements 2.0 Contacts Endpoint methods and Conversation Search

README.md

@@ -51,6 +51,44 @@ $client = new IntercomClient('<insert_token_here>', null, ['Intercom-Version' =>
 
 For more information about API Versioning, please check the [API Versioning Documentation](https://developers.intercom.com/building-apps/docs/api-versioning) and the [API changelog](https://developers.intercom.com/building-apps/docs/api-changelog).
 
+## Contacts
+Warning: This resource is only available on version 2.0 of the Intercom API.
+
+```php
+/** Create a contact */
+$client->contacts->create([
+    "type" => "user",
+    "email" => "test@example.com",
+    "custom_attributes" => ['foo' => 'bar']
+]);
+
+/** Update a contact */
+$client->contacts->update([
+    "email" => "test@example.com",
+    "custom_attributes" => ['foo' => 'bar']
+]);
+
+/** Permanently delete a contact */
+$client->contacts->deleteContact("570680a8a1bcbca8a90001b9");
+
+/** Get a contact by ID */
+$client->contacts->getContact("570680a8a1bcbca8a90001b9");
+
+/** Search for contacts */
+$query = ['field' => 'name', 'operator' => '=', 'value' => 'Alice'];
+$client->contacts->search([
+    "query" => $query,
+    "sort" => ["field" => "name", "order" => "ascending"],
+    "pagination" => ["per_page" => 10]
+]);
+
+/** Get next page of conversation search results */
+$client->contacts->nextSearch($query, $response->pages);
+
+/** List all contacts */
+$client->contacts->getContacts([]);
+```
+
 ## Users
 
 ```php
@@ -172,17 +210,6 @@ $client->leads->scrollLeads();
 
 See [here](https://github.com/intercom/intercom-php#scroll) for more info on using the scroll parameter
 
-## Customers
-
-```php
-/** Search for customers */
-$client->customers->search([
-    "query" => ['field' => 'name', 'operator' => '=', 'value' => 'Alice'],
-    "sort" => ["field" => "name", "order" => "ascending"],
-    "pagination" => ["per_page" => 10]
-]);
-```
-
 ## Visitors
 
 Retrieve `user_id` of a visitor via [the JavaScript API](https://developers.intercom.com/docs/intercom-javascript#section-intercomgetvisitorid)
@@ -312,6 +339,18 @@ $client->companies->getCompanyUsers("531ee472cce572a6ec000006");
 /** List users belonging to a company by company_id */
 $client->companies->getCompanies(["type" => "user", "company_id" => "3"]);
 
+/**
+ * Add companies to a contact with IDs
+ * First parameter is contact ID, second is company ID
+ */
+$client->companies->attachContact("570680a8a1bcbca8a90001b9", "531ee472cce572a6ec000006");
+
+/**
+ * Detach company from contact
+ * First parameter is contact ID, second is company ID
+ */
+$client->companies->detachContact("570680a8a1bcbca8a90001b9", "531ee472cce572a6ec000006");
+
 ```
 
 ## Admins
@@ -363,6 +402,17 @@ $client->conversations->getConversation("1234", [
     "display_as" => "plaintext"
 ])
 
+/** Search for conversations (API version >= 2.0) */
+$query = ['field' => 'updated_at', 'operator' => '>', 'value' => '1560436784'];
+$client->conversations->search([
+    "query" => $query,
+    "sort" => ["field" => "updated_at", "order" => "ascending"],
+    "pagination" => ["per_page" => 10]
+]);
+
+/** Get next page of conversation search results (API version > 2.0) */
+$client->conversations->nextSearch($query, $response->pages);
+
 /**
  * Reply to a conversation
  * See more options here: https://developers.intercom.io/reference#replying-to-a-conversation
@@ -465,6 +515,12 @@ You can grab the next page of results using the client:
 $client->nextPage($response->pages);
 ```
 
+In API version 2.0 subsequent pages for listing contacts can be retreived with:
+
+```php
+$client->nextCursor($response->pages);
+```
+
 ## Scroll
 
 The first time you use the scroll API you can just send a simple GET request.

src/IntercomClient.php

@@ -56,11 +56,6 @@ class IntercomClient
      */
     public $users;
 
-    /**
-     * @var IntercomCustomers $customers
-     */
-    public $customers;
-
     /**
      * @var IntercomEvents $events
      */
@@ -71,6 +66,11 @@ class IntercomClient
      */
     public $companies;
 
+    /**
+     * @var IntercomContacts $contacts
+     */
+    public $contacts;
+
     /**
      * @var IntercomMessages $messages
      */
@@ -141,7 +141,7 @@ class IntercomClient
     public function __construct(string $appIdOrToken, string $password = null, array $extraRequestHeaders = [])
     {
         $this->users = new IntercomUsers($this);
-        $this->customers = new IntercomCustomers($this);
+        $this->contacts = new IntercomContacts($this);
         $this->events = new IntercomEvents($this);
         $this->companies = new IntercomCompanies($this);
         $this->messages = new IntercomMessages($this);
@@ -265,6 +265,40 @@ public function nextPage($pages)
         return $this->handleResponse($response);
     }
 
+    /**
+     * Returns the next page of the result for a search query.
+     *
+     * @param  string $path
+     * @param  array $query
+     * @param  stdClass $pages
+     * @return stdClass
+     */
+    public function nextSearchPage(string $path, array $query, $pages)
+    {
+        $options = [
+            "query" => $query,
+            "pagination" => [
+                "per_page" => $pages->per_page,
+                "starting_after" => $pages->next->starting_after,
+            ]
+        ];
+        $response = $this->post($path, $options);
+        return $this->handleResponse($response);
+    }
+
+    /**
+     * Returns the next page of the result for a cursor based search.
+     *
+     * @param string $path
+     * @param string $startingAfter
+     * @return stdClass
+     */
+    public function nextCursorPage(string $path, string $startingAfter)
+    {
+        $response = $this->get($path . "?starting_after=" . $startingAfter);
+        return $this->handleResponse($response);
+    }
+
     /**
      * Gets the rate limit details.
      *

src/IntercomCompanies.php

@@ -33,6 +33,39 @@ public function update($options)
         return $this->create($options);
     }
 
+    /**
+     * Attaches a Contact to a Company.
+     *
+     * @see    https://developers.intercom.io/reference#attach-contact-to-company
+     * @param  string $contactId
+     * @param  string $companyId
+     * @param  array $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function attachContact(string $contactId, string $companyId, array $options = [])
+    {
+        $path = $this->companyAttachPath($contactId);
+        $options = array_merge($options, ["id" => $companyId]);
+        return $this->client->post($path, $options);
+    }
+
+    /**
+     * Detaches a Contact from a Company.
+     *
+     * @see    https://developers.intercom.io/reference#detach-contact-from-company
+     * @param  string $contactId
+     * @param  string $companyId
+     * @param  array $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function detachContact(string $contactId, string $companyId, array $options = [])
+    {
+        $path = $this->companyDetachPath($contactId, $companyId);
+        return $this->client->delete($path, $options);
+    }
+
     /**
      * Returns list of Companies.
      *
@@ -94,4 +127,23 @@ public function companyUsersPath($id)
     {
         return 'companies/' . $id . '/users';
     }
+
+    /**
+     * @param string $contactId
+     * @return string
+     */
+    public function companyAttachPath(string $contactId)
+    {
+        return 'contacts/' . $contactId . '/companies';
+    }
+
+    /**
+     * @param string $contactId
+     * @param string $companyId
+     * @return string
+     */
+    public function companyDetachPath(string $contactId, string $companyId)
+    {
+        return 'contacts/' . $contactId . '/companies/' . $companyId;
+    }
 }

src/IntercomContacts.php

@@ -0,0 +1,131 @@
+<?php
+
+namespace Intercom;
+
+use Http\Client\Exception;
+use stdClass;
+
+class IntercomContacts extends IntercomResource
+{
+    /**
+     * Creates a Contact.
+     *
+     * @see    https://developers.intercom.com/intercom-api-reference/reference#create-contact
+     * @param  array $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function create(array $options)
+    {
+        return $this->client->post("contacts", $options);
+    }
+
+    /**
+     * Updates a Contact.
+     *
+     * @see    https://developers.intercom.com/intercom-api-reference/reference#update-contact
+     * @param  array $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function update(array $options)
+    {
+        return $this->client->put("contacts", $options);
+    }
+
+    /**
+     * Lists Contacts.
+     *
+     * @see    https://developers.intercom.com/intercom-api-reference/reference#list-contacts
+     * @param  array $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function getContacts(array $options = [])
+    {
+        return $this->client->get('contacts', $options);
+    }
+
+    /**
+     * Gets a single Contact based on the Intercom ID.
+     *
+     * @see    https://developers.intercom.com/intercom-api-reference/reference#get-contact
+     * @param  string $id
+     * @param  array  $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function getContact(string $id, array $options = [])
+    {
+        $path = $this->contactPath($id);
+        return $this->client->get($path, $options);
+    }
+
+    /**
+     * Permenently Deletes a single Contact based on the Intercom ID.
+     *
+     * @see    https://developers.intercom.com/intercom-api-reference/reference#delete-contact
+     * @param  string $id
+     * @param  array  $options
+     * @return stdClass
+     * @throws Exception
+     */
+    public function deleteContact(string $id, array $options = [])
+    {
+        $path = $this->contactPath($id);
+        return $this->client->delete($path, $options);
+    }
+
+    /**
+     * Returns list of Contacts that match search query.
+     *
+     * @see     https://developers.intercom.com/reference#search-for-contacts
+     * @param   array $options
+     * @return  stdClass
+     * @throws  Exception
+     */
+    public function search(array $options)
+    {
+        $path = 'contacts/search';
+        return $this->client->post($path, $options);
+    }
+
+    /**
+     * Returns next page of Contacts that match search query.
+     *
+     * @see     https://developers.intercom.com/intercom-api-reference/reference#pagination-search
+     * @param   array $query
+     * @param   stdClass $pages
+     * @return  stdClass
+     * @throws  Exception
+     */
+    public function nextSearch(array $query, $pages)
+    {
+        $path = 'contacts/search';
+        return $this->client->nextSearchPage($path, $query, $pages);
+    }
+
+    /**
+     * Returns next page of a Contacts list.
+     *
+     * @see     https://developers.intercom.com/intercom-api-reference/reference#pagination
+     * @param   stdClass $pages
+     * @return  stdClass
+     * @throws  Exception
+     */
+    public function nextCursor($pages)
+    {
+        $path = 'contacts';
+        $starting_after = $pages->next->starting_after;
+        return $this->client->nextCursorPage($path, $starting_after);
+    }
+
+    /**
+     * @param string $id
+     * @return string
+     */
+    public function contactPath(string $id)
+    {
+        return 'contacts/' . $id;
+    }
+}