Add filter_subscribers method

.env.dist.testing

@@ -1,4 +1,5 @@
 CONVERTKIT_API_BROADCAST_ID="8697158"
+CONVERTKIT_API_CUSTOM_FIELD_ID="264073"
 CONVERTKIT_API_FORM_ID="2765139"
 CONVERTKIT_API_FORM_ID_2="2780977"
 CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"

.env.example

@@ -11,6 +11,7 @@ CONVERTKIT_OAUTH_CLIENT_ID=
 CONVERTKIT_OAUTH_CLIENT_SECRET=
 CONVERTKIT_OAUTH_REDIRECT_URI="https://convertkit-github.local/wp-admin/options-general.php?page=_wp_convertkit_settings"
 CONVERTKIT_API_BROADCAST_ID="8697158"
+CONVERTKIT_API_CUSTOM_FIELD_ID="264073"
 CONVERTKIT_API_FORM_ID="2765139"
 CONVERTKIT_API_FORM_ID_2="2780977"
 CONVERTKIT_API_LEGACY_FORM_URL="https://app.convertkit.com/landing_pages/470099"

phpcs.xml

@@ -72,7 +72,7 @@
     <!-- Permit slightly longer line lengths -->
     <rule ref="Generic.Files.LineLength">
         <properties>
-            <property name="lineLimit" value="150"/>
+            <property name="lineLimit" value="160"/>
             <property name="absoluteLineLimit" value="0"/>
         </properties>
     </rule>

src/ConvertKit_API.php

@@ -348,13 +348,13 @@ public function get_resource(string $url)
     /**
      * Performs an API request using Guzzle.
      *
-     * @param string                                                                                                     $endpoint API Endpoint.
-     * @param string                                                                                                     $method   Request method.
-     * @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args     Request arguments.
+     * @param string                                                                                                  $endpoint API Endpoint.
+     * @param string                                                                                                  $method   Request method.
+     * @param array<string, bool|integer|float|string|null|array<int|string, bool|integer|float|string|array<mixed>>> $args     Request arguments.
      *
      * @throws \Exception If JSON encoding arguments failed.
      *
-     * @return mixed|object
+     * @return false|mixed
      */
     public function request(string $endpoint, string $method, array $args = [])
     {

src/ConvertKit_API_Traits.php

@@ -945,6 +945,74 @@ public function create_subscribers(array $subscribers, string $callback_url = ''
         );
     }
 
+    /**
+     * Filter subscribers based on engagement.
+     *
+     * @param array<int, array<string, mixed>> $all                 Array of filter conditions where ALL must be met (AND logic). Each condition can have.
+     *                                                              - 'type' (string).
+     *                                                              - 'count_greater_than' (int|null).
+     *                                                              - 'count_less_than' (int|null).
+     *                                                              - 'after' (\DateTime|null).
+     *                                                              - 'before' (\DateTime|null).
+     *                                                              - 'any' (array<int|string, mixed>|null).
+     * @param boolean                          $include_total_count To include the total count of records in the response, use true.
+     * @param string                           $after_cursor        Return results after the given pagination cursor.
+     * @param string                           $before_cursor       Return results before the given pagination cursor.
+     * @param integer                          $per_page            Number of results to return.
+     *
+     * @since 2.4.0
+     *
+     * @see https://developers.kit.com/api-reference/subscribers/filter-subscribers-based-on-engagement
+     *
+     * @return mixed
+     */
+    public function filter_subscribers(
+        array $all = [],
+        bool $include_total_count = false,
+        string $after_cursor = '',
+        string $before_cursor = '',
+        int $per_page = 100
+    ) {
+        $options = [];
+
+        foreach ($all as $condition) {
+            $option = [];
+
+            if (array_key_exists('count_greater_than', $condition) && $condition['count_greater_than'] !== null) {
+                $option['count_greater_than'] = $condition['count_greater_than'];
+            }
+
+            if (array_key_exists('count_less_than', $condition) && $condition['count_less_than'] !== null) {
+                $option['count_less_than'] = $condition['count_less_than'];
+            }
+
+            if (array_key_exists('after', $condition) && $condition['after'] instanceof \DateTime) {
+                $option['after'] = $condition['after']->format('Y-m-d');
+            }
+
+            if (array_key_exists('before', $condition) && $condition['before'] instanceof \DateTime) {
+                $option['before'] = $condition['before']->format('Y-m-d');
+            }
+
+            if (array_key_exists('any', $condition) && !empty($condition['any'])) {
+                $option['any'] = (array) $condition['any'];
+            }
+
+            $options[] = $option;
+        }//end foreach
+
+        return $this->post(
+            'subscribers/filter',
+            $this->build_total_count_and_pagination_params(
+                ['all' => $options],
+                $include_total_count,
+                $after_cursor,
+                $before_cursor,
+                $per_page
+            )
+        );
+    }
+
     /**
      * Get the ConvertKit subscriber ID associated with email address if it exists.
      * Return false if subscriber not found.
@@ -1468,6 +1536,8 @@ public function create_webhook(string $url, string $event, string $parameter = '
             case 'subscriber.subscriber_bounce':
             case 'subscriber.subscriber_complain':
             case 'purchase.purchase_create':
+            case 'custom_field.field_created':
+            case 'custom_field.field_deleted':
                 $eventData = ['name' => $event];
                 break;
 
@@ -1508,6 +1578,13 @@ public function create_webhook(string $url, string $event, string $parameter = '
                 ];
                 break;
 
+            case 'custom_field.field_value_updated':
+                $eventData = [
+                    'name'            => $event,
+                    'custom_field_id' => $parameter,
+                ];
+                break;
+
             default:
                 throw new \InvalidArgumentException(sprintf('The event %s is not supported', $event));
         }//end switch
@@ -1617,6 +1694,36 @@ public function create_custom_fields(array $labels, string $callback_url = '')
         );
     }
 
+    /**
+     * Bulk update subscriber custom field values
+     *
+     * @param array<array<string,string|integer>> $custom_field_values Array of custom field values to update.
+     * - 'subscriber_id' (int)    Subscriber ID.
+     * - 'subscriber_custom_field_id' (int)  Custom Field ID.
+     * - 'value' (string|integer) Value to update.
+     * @param string                              $callback_url        URL to notify for large batch size when async processing complete.
+     *
+     * @since 2.4.0
+     *
+     * @see https://developers.kit.com/api-reference/custom-fields/bulk-update-subscriber-custom-field-values
+     *
+     * @return mixed|object
+     */
+    public function update_subscriber_custom_field_values(array $custom_field_values, string $callback_url = '')
+    {
+        // Build parameters.
+        $options = ['custom_field_values' => $custom_field_values];
+        if (!empty($callback_url)) {
+            $options['callback_url'] = $callback_url;
+        }
+
+        // Send request.
+        return $this->post(
+            'bulk/custom_fields/subscribers',
+            $options
+        );
+    }
+
     /**
      * Update a custom field.
      *
@@ -1854,15 +1961,15 @@ public function strip_html_head_body_tags(string $markup)
     /**
      * Adds total count and pagination parameters to the given array of existing API parameters.
      *
-     * @param array<string, string|integer|bool> $params              API parameters.
-     * @param boolean                            $include_total_count Return total count of records.
-     * @param string                             $after_cursor        Return results after the given pagination cursor.
-     * @param string                             $before_cursor       Return results before the given pagination cursor.
-     * @param integer                            $per_page            Number of results to return.
+     * @param array<string, string|integer|boolean|list<array<string, mixed>>> $params              API parameters.
+     * @param boolean                                                          $include_total_count Return total count of records.
+     * @param string                                                           $after_cursor        Return results after the given pagination cursor.
+     * @param string                                                           $before_cursor       Return results before the given pagination cursor.
+     * @param integer                                                          $per_page            Number of results to return.
      *
      * @since 2.0.0
      *
-     * @return array<string, string|integer|bool>
+     * @return array<string, string|int|bool|list<array<string, mixed>>>
      */
     private function build_total_count_and_pagination_params(
         array $params = [],
@@ -1888,8 +1995,8 @@ private function build_total_count_and_pagination_params(
     /**
      * Performs a GET request to the API.
      *
-     * @param string                                                             $endpoint API Endpoint.
-     * @param array<string, int|string|boolean|array<string, int|string>|string> $args     Request arguments.
+     * @param string                                                                                 $endpoint API Endpoint.
+     * @param array<string, int|string|boolean|array<string, int|string>|list<array<string, mixed>>> $args     Request arguments.
      *
      * @return false|mixed
      */
@@ -1901,8 +2008,8 @@ public function get(string $endpoint, array $args = [])
     /**
      * Performs a POST request to the API.
      *
-     * @param string                                                                                                     $endpoint API Endpoint.
-     * @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args     Request arguments.
+     * @param string                                                                                                            $endpoint API Endpoint.
+     * @param array<string, bool|integer|float|string|null|array<int|string, array<string|mixed>|boolean|integer|float|string>> $args     Request arguments.
      *
      * @return false|mixed
      */
@@ -1940,9 +2047,9 @@ public function delete(string $endpoint, array $args = [])
     /**
      * Performs an API request.
      *
-     * @param string                                                                                                     $endpoint API Endpoint.
-     * @param string                                                                                                     $method   Request method.
-     * @param array<string, bool|integer|float|string|null|array<int|string, float|integer|string|array<string|string>>> $args     Request arguments.
+     * @param string                                                                                                          $endpoint API Endpoint.
+     * @param string                                                                                                          $method   Request method.
+     * @param array<string, bool|integer|float|string|null|array<int|string, bool|integer|float|string|array<string, mixed>>> $args     Request arguments.
      *
      * @throws \Exception If JSON encoding arguments failed.
      *

tests/ConvertKitAPIKeyTest.php

@@ -475,6 +475,33 @@ public function testCreateCustomFields()
         $result = $this->api->create_custom_fields($labels);
     }
 
+    /**
+     * Test that update_subscriber_custom_field_values() throws a ClientException
+     * as this is only supported using OAuth.
+     *
+     * @since   2.4.0
+     *
+     * @return void
+     */
+    public function testUpdateSubscriberCustomFieldValues()
+    {
+        $this->expectException(ClientException::class);
+        $result = $this->api->update_subscriber_custom_field_values(
+            [
+                [
+                    'subscriber_id' => 1,
+                    'subscriber_custom_field_id' => (int) $_ENV['CONVERTKIT_API_CUSTOM_FIELD_ID'],
+                    'value' => '100',
+                ],
+                [
+                    'subscriber_id' => 2,
+                    'subscriber_custom_field_id' => (int) $_ENV['CONVERTKIT_API_CUSTOM_FIELD_ID'],
+                    'value' => '200',
+                ],
+            ]
+        );
+    }
+
     /**
      * Test that get_purchases() throws a ClientException
      * as this is only supported using OAuth.