Merge branch 'master' into 202104_deprecate_misnamed_methods

Author: smoucka

CHANGELOG.md

@@ -1,5 +1,7 @@
 ## CHANGELOG
-### Unreleased
+### [Unreleased]
+- Update - Add people/search endpoint.
+- Update - Add data-privacy/deletion-request endpoint.
 - Deprecate - Rename List API methods: getListDetails, updateListDetails, subscribeMembersToList, unsubscribeMembersFromList, getGroupMemberIdentifiers, getAllExclusionsOnList
 - Deprecate - Rename Metric API methods: getMetricTimeline, exportMetricData
 
@@ -41,3 +43,5 @@
 
 ### 1.0
 - As this changelog was created after 2.0.0, please refer to the README for version 1 https://github.com/klaviyo/php-klaviyo/tree/d388ca998dff55b2a7e420c2c7aa2cd221365d1c
+
+[Unreleased]: https://github.com/klaviyo/php-klaviyo/compare/2.2.5...HEAD

README.md

@@ -149,6 +149,21 @@ $client->profiles->getAllProfileMetricsTimeline( 'ProfileId' );
 
 #Get a specific metric for a profile
 $client->profiles->getProfileMetricTimeline( 'ProfileId', 'MetricId' );
+
+#Get a profile's ID by its email address
+$client->profiles->getProfileIdByEmail('[email protected]');
+```
+
+### You can request a privacy-compliant profile deletion given an identifying property
+```php
+#Request profile deletion by email
+$client->dataprivacy->requestProfileDeletion('[email protected]');
+
+#Request profile deletion by phone number
+$client->dataprivacy->requestProfileDeletion('1-234-567-8910', 'phone_number');
+
+#Request profile deletion by person ID
+$client->dataprivacy->requestProfileDeletion('abc123', 'person_id');
 ```
 
 ## Exceptions

src/DataPrivacy.php

@@ -0,0 +1,59 @@
+<?php
+
+namespace Klaviyo;
+
+use Klaviyo\Exception\KlaviyoException;
+
+/**
+ * Class DataPrivacy
+ * @package Klaviyo
+ */
+class DataPrivacy extends KlaviyoAPI
+{
+    /**
+     * Data Privacy endpoint constants
+     */
+    const ENDPOINT_DATA_PRIVACY = 'data-privacy';
+    const ENDPOINT_DELETION_REQUEST = 'deletion-request';
+
+    /**
+     * Data Privacy arguments
+     */
+    const PHONE_NUMBER = 'phone_number';
+    const PERSON_ID = 'person_id';
+
+    const PROFILE_DELETION_VALID_ID_TYPES = [
+        self::EMAIL,
+        self::PHONE_NUMBER,
+        self::PERSON_ID,
+    ];
+
+    /**
+     * Request a data privacy-compliant deletion for the person record corresponding
+     * to an email address, phone number, or person identifier. If multiple person
+     * records exist for the provided identifier, only one of them will be deleted.
+     *
+     * @link https://www.klaviyo.com/docs/api/v2/data-privacy#post-deletion-request
+     *
+     * @param $identifier string Value by which to identify the profile being deleted.
+     * @param $idType string Identifier type e.g. email, phone_number, person_id.
+     * @return mixed
+     * @throws KlaviyoException
+     */
+    public function requestProfileDeletion($identifier, $idType = self::EMAIL)
+    {
+        if (!in_array($idType, self::PROFILE_DELETION_VALID_ID_TYPES)) {
+            throw new KlaviyoException(
+                sprintf(
+                    'Invalid id_type provided, must be one of: %s',
+                    implode(', ', self::PROFILE_DELETION_VALID_ID_TYPES)
+                )
+            );
+        }
+
+        $options = $this->createParams($idType, $identifier);
+        $path = sprintf('%s/%s', self::ENDPOINT_DATA_PRIVACY, self::ENDPOINT_DELETION_REQUEST);
+
+        return $this->v2Request($path, $options, self::HTTP_POST);
+    }
+}

src/KlaviyoAPI.php

@@ -58,9 +58,10 @@ abstract class KlaviyoAPI
     /**
      * Klaviyo API arguments
      */
-    const PROFILES = 'profiles';
     const COUNT = 'count';
+    const EMAIL = 'email';
     const PAGE = 'page';
+    const PROFILES = 'profiles';
     const SINCE = 'since';
     const SORT = 'sort';
 
@@ -123,7 +124,7 @@ protected function v1Request( $path, $options = [], $method = self::HTTP_GET )
     /**
      * Make private v2 API request
      *
-     * @param $path Endpoint to call
+     * @param string $path Endpoint to call
      * @param array $options API params to add to request
      * @param string $method HTTP method for request
      * @return mixed
@@ -176,13 +177,11 @@ private function handleResponse( $response, $statusCode, $isPublic )
     {
         if ( $statusCode == 403 ) {
             throw new KlaviyoAuthenticationException(self::ERROR_INVALID_API_KEY, $statusCode);
-        } else if ( $statusCode == 404 ) {
-            throw new KlaviyoResourceNotFoundException( self::ERROR_RESOURCE_DOES_NOT_EXIST, $statusCode);
         } else if ( $statusCode == 429 ) {
             throw new KlaviyoRateLimitException(
-                $this->returnRateLimit( $this->decodeJsonResponse( $response ), $statusCode )
+                $this->returnRateLimit( $this->decodeJsonResponse( $response ) )
             );
-        } else if ( $statusCode != 200 ) {
+        } else if ($statusCode < 200 || $statusCode >= 300) {
             throw new KlaviyoApiException($this->decodeJsonResponse( $response )['detail'], $statusCode);
         }
 
@@ -354,7 +353,7 @@ private function returnRateLimit ( $response )
      * Return formatted options.
      *
      * @param string $paramName Name of API Param to create
-     * @param $paramValue Value of API params to create
+     * @param mixed $paramValue Value of API params to create
      */
     protected function createParams( $paramName, $paramValue )
     {

src/Profiles.php

@@ -11,6 +11,8 @@ class Profiles extends KlaviyoAPI
     const PERSON = 'person';
     const METRICS = 'metrics';
     const METRIC = 'metric';
+    const PEOPLE = 'people';
+    const SEARCH = 'search';
     const TIMELINE = 'timeline';
 
     /**
@@ -130,4 +132,18 @@ public function getProfileMetricTimeline( $personId, $metricId, $since = null, $
         return $this->v1Request( $path, $params );
     }
 
+    /**
+     * Get ID of profile by email address.
+     *
+     * @param string $email Email address of desired profile.
+     * @return mixed
+     * @throws Exception\KlaviyoException
+     */
+    public function getProfileIdByEmail($email)
+    {
+        $params = $this->createRequestBody([self::EMAIL => $email]);
+        $path = sprintf('%s/%s', self::PEOPLE, self::SEARCH);
+
+        return $this->v2Request($path, $params);
+    }
 }