ConvertKit_API_Traits.php

<?php
/**
 * ConvertKit API Traits
 *
 * @author ConvertKit
 */

namespace ConvertKit_API;

/**
 * ConvertKit API Traits
 */
trait ConvertKit_API_Traits
{
    /**
     * ConvertKit OAuth Application Client ID
     *
     * @var string
     */
    protected $client_id = '';

    /**
     * ConvertKit OAuth Application Client Secret
     *
     * @var string
     */
    protected $client_secret = '';

    /**
     * Access Token
     *
     * @var string
     */
    protected $access_token = '';

    /**
     * API Key
     *
     * @var string
     */
    protected $api_key = '';

    /**
     * OAuth Authorization URL
     *
     * @var string
     */
    protected $oauth_authorize_url = 'https://app.kit.com/oauth/authorize';

    /**
     * OAuth Token URL
     *
     * @var string
     */
    protected $oauth_token_url = 'https://api.kit.com/oauth/token';

    /**
     * Version of ConvertKit API
     *
     * @var string
     */
    protected $api_version = 'v4';

    /**
     * ConvertKit API URL
     *
     * @var string
     */
    protected $api_url_base = 'https://api.kit.com/';


    /**
     * Gets the current account
     *
     * @see https://developers.kit.com/api-reference/accounts/get-current-account
     *
     * @return false|mixed
     */
    public function get_account()
    {
        return $this->get('account');
    }

    /**
     * List the account's colors
     *
     * @see https://developers.kit.com/api-reference/accounts/list-colors
     *
     * @return false|mixed
     */
    public function get_account_colors()
    {
        return $this->get('account/colors');
    }

    /**
     * Updates the account's colors
     *
     * @param array<string, string> $colors Hex colors.
     *
     * @see https://developers.kit.com/api-reference/accounts/update-colors
     *
     * @return false|mixed
     */
    public function update_account_colors(array $colors)
    {
        return $this->put(
            'account/colors',
            ['colors' => $colors]
        );
    }

    /**
     * Gets the Creator Profile
     *
     * @see https://developers.kit.com/api-reference/accounts/get-creator-profile
     *
     * @return false|mixed
     */
    public function get_creator_profile()
    {
        return $this->get('account/creator_profile');
    }

    /**
     * Gets email stats
     *
     * @see https://developers.kit.com/api-reference/accounts/get-email-stats
     *
     * @return false|mixed
     */
    public function get_email_stats()
    {
        return $this->get('account/email_stats');
    }

    /**
     * Get growth stats
     *
     * @param \DateTime|null $starting Gets stats for time period beginning on this date. Defaults to 90 days ago.
     * @param \DateTime|null $ending   Gets stats for time period ending on this date. Defaults to today.
     *
     * @see https://developers.kit.com/api-reference/accounts/get-growth-stats
     *
     * @return false|mixed
     */
    public function get_growth_stats(\DateTime|null $starting = null, \DateTime|null $ending = null)
    {
        return $this->get(
            'account/growth_stats',
            [
                'starting' => (!is_null($starting) ? $starting->format('Y-m-d') : ''),
                'ending'   => (!is_null($ending) ? $ending->format('Y-m-d') : ''),
            ]
        );
    }

    /**
     * List forms.
     *
     * @param string  $status              Form status (active|archived|trashed|all).
     * @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.
     *
     * @see https://developers.kit.com/api-reference/forms/list-forms
     *
     * @return mixed|array<int,\stdClass>
     */
    public function get_forms(
        string $status = 'active',
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            'forms',
            $this->build_total_count_and_pagination_params(
                [
                    'type'   => 'embed',
                    'status' => $status,
                ],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List landing pages.
     *
     * @param string  $status              Form status (active|archived|trashed|all).
     * @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.
     *
     * @see https://developers.kit.com/api-reference/forms/list-forms
     *
     * @return mixed|array<int,\stdClass>
     */
    public function get_landing_pages(
        string $status = 'active',
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            'forms',
            $this->build_total_count_and_pagination_params(
                [
                    'type'   => 'hosted',
                    'status' => $status,
                ],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Bulk add subscribers to forms
     *
     * @param array<array<string,string>> $forms_subscribers_ids Array of arrays comprising of `form_id`, `subscriber_id` and optional `referrer` URL.
     * @param string                      $callback_url          URL to notify for large batch size when async processing complete.
     *
     * @since 2.1.0
     *
     * @see https://developers.kit.com/api-reference/forms/bulk-add-subscribers-to-forms
     *
     * @return mixed|object
     */
    public function add_subscribers_to_forms(array $forms_subscribers_ids, string $callback_url = '')
    {
        // Build parameters.
        $options = ['additions' => $forms_subscribers_ids];
        if (!empty($callback_url)) {
            $options['callback_url'] = $callback_url;
        }

        // Send request.
        return $this->post(
            'bulk/forms/subscribers',
            $options
        );
    }

    /**
     * Add subscriber to form by email address
     *
     * @param integer $form_id       Form ID.
     * @param string  $email_address Email Address.
     * @param string  $referrer      Referrer.
     *
     * @see https://developers.kit.com/api-reference/forms/add-subscriber-to-form-by-email-address
     *
     * @return false|mixed
     */
    public function add_subscriber_to_form_by_email(int $form_id, string $email_address, string $referrer = '')
    {
        // Build parameters.
        $options = ['email_address' => $email_address];

        if (!empty($referrer)) {
            $options['referrer'] = $referrer;
        }

        // Send request.
        return $this->post(
            sprintf('forms/%s/subscribers', $form_id),
            $options
        );
    }

    /**
     * Add subscriber to form
     *
     * @param integer $form_id       Form ID.
     * @param integer $subscriber_id Subscriber ID.
     * @param string  $referrer      Referrer URL.
     *
     * @see https://developers.kit.com/api-reference/forms/add-subscriber-to-form
     *
     * @since 2.0.0
     *
     * @return false|mixed
     */
    public function add_subscriber_to_form(int $form_id, int $subscriber_id, string $referrer = '')
    {
        // Build parameters.
        $options = [];

        if (!empty($referrer)) {
            $options['referrer'] = $referrer;
        }

        // Send request.
        return $this->post(
            sprintf('forms/%s/subscribers/%s', $form_id, $subscriber_id),
            $options
        );
    }

    /**
     * Adds a subscriber to a legacy form by subscriber ID
     *
     * @param integer $form_id       Legacy Form ID.
     * @param integer $subscriber_id Subscriber ID.
     *
     * @since 2.0.0
     *
     * @return false|mixed
     */
    public function add_subscriber_to_legacy_form(int $form_id, int $subscriber_id)
    {
        return $this->post(sprintf('landing_pages/%s/subscribers/%s', $form_id, $subscriber_id));
    }

    /**
     * List subscribers for a form
     *
     * @param integer        $form_id             Form ID.
     * @param string         $subscriber_state    Subscriber State (active|bounced|cancelled|complained|inactive).
     * @param \DateTime|null $created_after       Filter subscribers who have been created after this date.
     * @param \DateTime|null $created_before      Filter subscribers who have been created before this date.
     * @param \DateTime|null $added_after         Filter subscribers who have been added to the form after this date.
     * @param \DateTime|null $added_before        Filter subscribers who have been added to the form before this date.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/forms/list-subscribers-for-a-form
     *
     * @return false|mixed
     */
    public function get_form_subscriptions(
        int $form_id,
        string $subscriber_state = 'active',
        \DateTime|null $created_after = null,
        \DateTime|null $created_before = null,
        \DateTime|null $added_after = null,
        \DateTime|null $added_before = null,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Build parameters.
        $options = [];

        if (!empty($subscriber_state)) {
            $options['status'] = $subscriber_state;
        }
        if (!is_null($created_after)) {
            $options['created_after'] = $created_after->format('Y-m-d');
        }
        if (!is_null($created_before)) {
            $options['created_before'] = $created_before->format('Y-m-d');
        }
        if (!is_null($added_after)) {
            $options['added_after'] = $added_after->format('Y-m-d');
        }
        if (!is_null($added_before)) {
            $options['added_before'] = $added_before->format('Y-m-d');
        }

        // Send request.
        return $this->get(
            sprintf('forms/%s/subscribers', $form_id),
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List sequences
     *
     * @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.
     *
     * @see https://developers.kit.com/api-reference/sequences/list-sequences
     *
     * @return false|mixed
     */
    public function get_sequences(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            'sequences',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a sequence
     *
     * @param string                              $name                       The name of the sequence.
     * @param string                              $email_address              The sending email address to use. Uses the account's sending email address if not provided.
     * @param integer                             $email_template_id          Id of the email template to use.
     * @param array<string>                       $send_days                  The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
     * @param integer                             $send_hour                  The hour of the day to send the sequence at. Must be an integer between 0 and 23.
     * @param string                              $time_zone                  The timezone to use for the sequence. Must be a valid IANA timezone string.
     * @param boolean                             $active                     Use `true` to activate the sequence, `false` to deactivate it.
     * @param boolean                             $repeat                     When `true`, subscribers can restart the sequence multiple times.
     * @param boolean                             $hold                       When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email.
     * @param array<string,string|array<integer>> $exclude_subscriber_sources The subscriber sources to exclude from the sequence. Uses the account's default exclude subscriber sources if not provided.
     *
     * @see https://developers.kit.com/api-reference/sequences/create-a-sequence
     *
     * @return mixed|object
     */
    public function create_sequence(
        string $name,
        string $email_address = '',
        int $email_template_id = 0,
        array $send_days = [],
        int $send_hour = 0,
        string $time_zone = '',
        bool $active = true,
        bool $repeat = false,
        bool $hold = false,
        array $exclude_subscriber_sources = []
    ) {
        $options = [
            'name'              => $name,
            'email_address'     => $email_address,
            'email_template_id' => $email_template_id,
            'send_hour'         => $send_hour,
            'time_zone'         => $time_zone,
            'active'            => $active,
            'repeat'            => $repeat,
            'hold'              => $hold,
        ];
        if (count($send_days)) {
            $options['send_days'] = $send_days;
        }
        if (count($exclude_subscriber_sources)) {
            $options['exclude_subscriber_sources'] = $exclude_subscriber_sources;
        }

        // Iterate through options, removing blank entries.
        foreach ($options as $key => $value) {
            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        // Send request.
        return $this->post(
            'sequences',
            $options
        );
    }

    /**
     * Get a sequence.
     *
     * @param integer $id Sequence ID.
     *
     * @see https://developers.kit.com/api-reference/sequences/get-a-sequence
     *
     * @return mixed|object
     */
    public function get_sequence(int $id)
    {
        return $this->get(sprintf('sequences/%s', $id));
    }

    /**
     * Updates a sequence
     *
     * @param integer                             $sequence_id                Sequence ID.
     * @param string                              $name                       The name of the sequence.
     * @param string                              $email_address              The sending email address to use. Uses the account's sending email address if not provided.
     * @param integer                             $email_template_id          Id of the email template to use.
     * @param array<string>                       $send_days                  The days of the week to send the sequence on. Must be one of: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
     * @param integer                             $send_hour                  The hour of the day to send the sequence at. Must be an integer between 0 and 23.
     * @param string                              $time_zone                  The timezone to use for the sequence. Must be a valid IANA timezone string.
     * @param boolean                             $active                     Use `true` to activate the sequence, `false` to deactivate it.
     * @param boolean                             $repeat                     When `true`, subscribers can restart the sequence multiple times.
     * @param boolean                             $hold                       When `true`, subscribers added via Visual Automations stay in the sequence after receiving the last email.
     * @param array<string,string|array<integer>> $exclude_subscriber_sources The subscriber sources to exclude from the sequence. Uses the account's default exclude subscriber sources if not provided.
     *
     * @see https://developers.kit.com/api-reference/sequences/create-a-sequence
     *
     * @return mixed|object
     */
    public function update_sequence(
        int $sequence_id,
        string $name = '',
        string $email_address = '',
        int $email_template_id = 0,
        array $send_days = [],
        int $send_hour = 0,
        string $time_zone = '',
        bool $active = true,
        bool $repeat = false,
        bool $hold = false,
        array $exclude_subscriber_sources = []
    ) {
        $options = [
            'name'              => $name,
            'email_address'     => $email_address,
            'email_template_id' => $email_template_id,
            'send_days'         => $send_days,
            'send_hour'         => $send_hour,
            'time_zone'         => $time_zone,
            'active'            => $active,
            'repeat'            => $repeat,
            'hold'              => $hold,
        ];
        if (count($exclude_subscriber_sources)) {
            $options['exclude_subscriber_sources'] = $exclude_subscriber_sources;
        }

        // Iterate through options, removing blank entries.
        foreach ($options as $key => $value) {
            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        // Send request.
        return $this->put(
            sprintf('sequences/%s', $sequence_id),
            $options
        );
    }

    /**
     * Deletes a sequence.
     *
     * @param integer $id Sequence ID.
     *
     * @see https://developers.kit.com/api-reference/sequences/delete-a-sequence
     *
     * @return mixed|object
     */
    public function delete_sequence(int $id)
    {
        return $this->delete(sprintf('sequences/%s', $id));
    }

    /**
     * Adds subscriber to sequence by email address
     *
     * @param integer $sequence_id   Sequence ID.
     * @param string  $email_address Email Address.
     *
     * @see https://developers.kit.com/api-reference/sequences/add-subscriber-to-sequence-by-email-address
     *
     * @return false|mixed
     */
    public function add_subscriber_to_sequence_by_email(int $sequence_id, string $email_address)
    {
        return $this->post(
            sprintf('sequences/%s/subscribers', $sequence_id),
            ['email_address' => $email_address]
        );
    }

    /**
     * Adds subscriber to sequence
     *
     * @param integer $sequence_id   Sequence ID.
     * @param integer $subscriber_id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/sequences/add-subscriber-to-sequence
     *
     * @since 2.0.0
     *
     * @return false|mixed
     */
    public function add_subscriber_to_sequence(int $sequence_id, int $subscriber_id)
    {
        return $this->post(sprintf('sequences/%s/subscribers/%s', $sequence_id, $subscriber_id));
    }

    /**
     * List subscribers for a sequence
     *
     * @param integer        $sequence_id         Sequence ID.
     * @param string         $subscriber_state    Subscriber State (active|bounced|cancelled|complained|inactive).
     * @param \DateTime|null $created_after       Filter subscribers who have been created after this date.
     * @param \DateTime|null $created_before      Filter subscribers who have been created before this date.
     * @param \DateTime|null $added_after         Filter subscribers who have been added to the form after this date.
     * @param \DateTime|null $added_before        Filter subscribers who have been added to the form before this date.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/sequences/list-subscribers-for-a-sequence
     *
     * @return false|mixed
     */
    public function get_sequence_subscriptions(
        int $sequence_id,
        string $subscriber_state = 'active',
        \DateTime|null $created_after = null,
        \DateTime|null $created_before = null,
        \DateTime|null $added_after = null,
        \DateTime|null $added_before = null,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Build parameters.
        $options = [];

        if (!empty($subscriber_state)) {
            $options['status'] = $subscriber_state;
        }
        if (!is_null($created_after)) {
            $options['created_after'] = $created_after->format('Y-m-d');
        }
        if (!is_null($created_before)) {
            $options['created_before'] = $created_before->format('Y-m-d');
        }
        if (!is_null($added_after)) {
            $options['added_after'] = $added_after->format('Y-m-d');
        }
        if (!is_null($added_before)) {
            $options['added_before'] = $added_before->format('Y-m-d');
        }

        // Send request.
        return $this->get(
            sprintf('sequences/%s/subscribers', $sequence_id),
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List sequence emails
     *
     * @param integer $sequence_id         Sequence ID.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/sequence-emails/list-sequence-emails
     *
     * @return false|mixed
     */
    public function get_sequence_emails(
        int $sequence_id,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            sprintf('sequences/%s/emails', $sequence_id),
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a sequence email
     *
     * @param integer            $sequence_id       Sequence ID.
     * @param string             $subject           Subject line of the email.
     * @param integer            $delay_value       Number of days or hours to wait before sending this email after the previous one.
     * @param string             $delay_unit        Unit for the send delay. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay.
     * @param string|null        $preview_text      Preview text shown in email clients before the email is opened.
     * @param string|null        $content           HTML body content of the email.
     * @param integer|null       $email_template_id ID of the email template to use for layout and styling.
     * @param boolean            $published         Whether the email is active and will be sent to subscribers.
     * @param array<string>|null $send_days         Days of the week this email may be sent. Defaults to all 7 days (inherits the sequence schedule). Pass a subset to restrict delivery, or null to reset to all days.
     * @param integer|null       $position          Zero-based position of the email in the sequence. Assigned automatically after the last email if omitted.
     *
     * @see https://developers.kit.com/api-reference/sequence-emails/create-a-sequence-email
     *
     * @return mixed|object
     */
    public function create_sequence_email(
        int $sequence_id,
        string $subject,
        int $delay_value,
        string $delay_unit,
        string|null $preview_text = null,
        string|null $content = null,
        int|null $email_template_id = null,
        bool $published = false,
        array|null $send_days = null,
        int|null $position = null,
    ) {
        $options = [
            'subject'     => $subject,
            'delay_value' => $delay_value,
            'delay_unit'  => $delay_unit,
            'published'   => $published,
            'send_days'   => $send_days,
        ];

        if (!empty($preview_text)) {
            $options['preview_text'] = $preview_text;
        }
        if (!empty($content)) {
            $options['content'] = $content;
        }
        if (!empty($email_template_id)) {
            $options['email_template_id'] = $email_template_id;
        }
        if (!empty($position)) {
            $options['position'] = $position;
        }

        // Send request.
        return $this->post(
            sprintf('sequences/%s/emails', $sequence_id),
            $options
        );
    }

    /**
     * Get a sequence email.
     *
     * @param integer $sequence_id Sequence ID.
     * @param integer $email_id    Email ID.
     *
     * @see https://developers.kit.com/api-reference/sequence-emails/get-a-sequence-email
     *
     * @return mixed|object
     */
    public function get_sequence_email(int $sequence_id, int $email_id)
    {
        return $this->get(sprintf('sequences/%s/emails/%s', $sequence_id, $email_id));
    }

    /**
     * Updates a sequence
     *
     * @param integer            $sequence_id       Sequence ID.
     * @param integer            $email_id          Sequence Email ID.
     * @param string|null        $subject           Subject line of the email.
     * @param integer|null       $delay_value       Number of days or hours to wait before sending this email after the previous one.
     * @param string|null        $delay_unit        Unit for the send delay. Use `days` for schedule-aware delivery, `hours` for a fixed hourly delay.
     * @param string|null        $preview_text      Preview text shown in email clients before the email is opened.
     * @param string|null        $content           HTML body content of the email.
     * @param integer|null       $email_template_id ID of the email template to use for layout and styling.
     * @param boolean|null       $published         Whether the email is active and will be sent to subscribers.
     * @param array<string>|null $send_days         Days of the week this email may be sent. Defaults to all 7 days (inherits the sequence schedule). Pass a subset to restrict delivery, or null to reset to all days.
     * @param integer|null       $position          Zero-based position of the email in the sequence. Assigned automatically after the last email if omitted.
     *
     * @see https://developers.kit.com/api-reference/sequences/create-a-sequence
     *
     * @return mixed|object
     */
    public function update_sequence_email(
        int $sequence_id,
        int $email_id,
        string|null $subject = null,
        int|null $delay_value = null,
        string|null $delay_unit = null,
        string|null $preview_text = null,
        string|null $content = null,
        int|null $email_template_id = null,
        bool|null $published = null,
        array|null $send_days = null,
        int|null $position = null,
    ) {
        // Build parameters.
        $options = ['send_days' => $send_days];

        if (!is_null($subject)) {
            $options['subject'] = $subject;
        }
        if (!is_null($delay_value)) {
            $options['delay_value'] = $delay_value;
        }
        if (!is_null($delay_unit)) {
            $options['delay_unit'] = $delay_unit;
        }
        if (!is_null($preview_text)) {
            $options['preview_text'] = $preview_text;
        }
        if (!is_null($content)) {
            $options['content'] = $content;
        }
        if (!is_null($email_template_id)) {
            $options['email_template_id'] = $email_template_id;
        }
        if (!is_null($published)) {
            $options['published'] = $published;
        }
        if (!is_null($send_days)) {
            $options['send_days'] = $send_days;
        }
        if (!is_null($position)) {
            $options['position'] = $position;
        }

        // Send request.
        return $this->put(
            sprintf('sequences/%s/emails/%s', $sequence_id, $email_id),
            $options
        );
    }

    /**
     * Deletes a sequence email.
     *
     * @param integer $sequence_id Sequence ID.
     * @param integer $email_id    Email ID.
     *
     * @see https://developers.kit.com/api-reference/sequence-emails/delete-a-sequence-email
     *
     * @return mixed|object
     */
    public function delete_sequence_email(int $sequence_id, int $email_id)
    {
        return $this->delete(sprintf('sequences/%s/emails/%s', $sequence_id, $email_id));
    }

   /**
    * List snippets
    *
    * @param boolean     $archived            When `true`, returns only archived snippets. Defaults to `false`.
    * @param boolean     $include_content     When `true`, includes both the content and document fields for each snippet in the response. Defaults to `false`.
    * @param string|null $snippet_type        Filter snippets by type. Use inline for text snippets or block for rich-text block snippets.
    * @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.
    *
    * @see https://developers.kit.com/api-reference/snippets/list-snippets
    *
    * @return false|mixed
    */
    public function get_snippets(
        bool $archived = false,
        bool $include_content = false,
        string|null $snippet_type = null,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        $options = [
            'archived'        => $archived,
            'include_content' => $include_content,
        ];
        if (!is_null($snippet_type)) {
            $options['snippet_type'] = $snippet_type;
        }
        return $this->get(
            'snippets',
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a snippet
     *
     * @param string $name         Name of the snippet.
     * @param string $snippet_type Type of snippet. Must be one of: `inline`, `block`.
     * @param string $content      Content of the snippet.
     *
     * @see https://developers.kit.com/api-reference/snippets/create-a-snippet
     *
     * @return mixed|object
     */
    public function create_snippet(
        string $name,
        string $snippet_type,
        string $content
    ) {
        $options = [
            'name'         => $name,
            'snippet_type' => $snippet_type,
        ];

        switch ($snippet_type) {
            case 'inline':
                $options['content'] = $content;
                break;

            case 'block':
            default:
                $options['document_attributes'] = ['value_html' => $content];
                break;
        }

        // Send request.
        return $this->post(
            'snippets',
            $options
        );
    }

    /**
     * Get a snippet.
     *
     * @param integer $id Snippet ID.
     *
     * @see https://developers.kit.com/api-reference/snippets/get-a-snippet
     *
     * @return mixed|object
     */
    public function get_snippet(int $id)
    {
        return $this->get(sprintf('snippets/%s', $id));
    }

    /**
     * Updates a snippet
     *
     * @param integer $snippet_id   Snippet ID.
     * @param string  $name         Name of the snippet.
     * @param string  $snippet_type Type of snippet. Must be one of: `inline`, `block`.
     * @param boolean $archived     Pass `true` to archive or `false` to restore the snippet.
     * @param string  $content      Content of the snippet.
     *
     * @see https://developers.kit.com/api-reference/snippets/update-a-snippet
     *
     * @return mixed|object
     */
    public function update_snippet(
        int $snippet_id,
        string $name = '',
        string $snippet_type = '',
        bool $archived = false,
        string $content = ''
    ) {
        $options = [
            'name'         => $name,
            'snippet_type' => $snippet_type,
            'archived'     => $archived,
        ];

        switch ($snippet_type) {
            case 'inline':
                $options['content'] = $content;
                break;

            case 'block':
            default:
                $options['document_attributes'] = ['value_html' => $content];
                break;
        }

        // Iterate through options, removing blank entries.
        foreach ($options as $key => $value) {
            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        // Send request.
        return $this->put(
            sprintf('snippets/%s', $snippet_id),
            $options
        );
    }

    /**
     * List tags.
     *
     * @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.
     *
     * @see https://developers.kit.com/api-reference/tags/list-tags
     *
     * @since 2.0.0
     *
     * @return mixed|array<int,\stdClass>
     */
    public function get_tags(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            'tags',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a tag.
     *
     * @param string $tag Tag Name.
     *
     * @see https://developers.kit.com/api-reference/tags/create-a-tag
     *
     * @return false|mixed
     */
    public function create_tag(string $tag)
    {
        return $this->post(
            'tags',
            ['name' => $tag]
        );
    }

    /**
     * Bulk create tags.
     *
     * @param array<int,string> $tags         Tag Names.
     * @param string            $callback_url URL to notify for large batch size when async processing complete.
     *
     * @since 1.1.0
     *
     * @see https://developers.kit.com/api-reference/tags/bulk-create-tags
     *
     * @return false|mixed
     */
    public function create_tags(array $tags, string $callback_url = '')
    {
        // Build parameters.
        $options = [
            'tags' => [],
        ];
        foreach ($tags as $i => $tag) {
            $options['tags'][] = [
                'name' => (string) $tag,
            ];
        }

        if (!empty($callback_url)) {
            $options['callback_url'] = $callback_url;
        }

        // Send request.
        return $this->post(
            'bulk/tags',
            $options
        );
    }

    /**
     * Updates the name of a tag.
     *
     * @param integer $tag_id Tag ID.
     * @param string  $name   New name.
     *
     * @since 2.2.1
     *
     * @see https://developers.kit.com/api-reference/tags/update-tag-name
     *
     * @return false|mixed
     */
    public function update_tag_name(int $tag_id, string $name)
    {
        return $this->put(sprintf('tags/%s', $tag_id), ['name' => $name]);
    }

    /**
     * Tags the given subscribers with the given existing Tags.
     *
     * @param array<int,array<string>> $taggings     Taggings, in the format:
     *   [
     *    [
     *      "tag_id" => 0,
     *      "subscriber_id" => 0
     *    ],
     *    [
     *      "tag_id" => 1,
     *      "subscriber_id" => 1
     *    ],
     *   ].
     * @param string                   $callback_url URL to notify for large batch size when async processing complete.
     *
     * @since 2.2.1
     *
     * @see https://developers.kit.com/api-reference/tags/bulk-tag-subscribers
     *
     * @return false|mixed
     */
    public function tag_subscribers(array $taggings, string $callback_url = '')
    {
        // Build parameters.
        $options = ['taggings' => $taggings];
        if (!empty($callback_url)) {
            $options['callback_url'] = $callback_url;
        }

        // Send request.
        return $this->post(
            'bulk/tags/subscribers',
            $options
        );
    }

    /**
     * Tag a subscriber by email address.
     *
     * @param integer $tag_id        Tag ID.
     * @param string  $email_address Email Address.
     *
     * @see https://developers.kit.com/api-reference/tags/tag-a-subscriber-by-email-address
     *
     * @return false|mixed
     */
    public function tag_subscriber_by_email(int $tag_id, string $email_address)
    {
        return $this->post(
            sprintf('tags/%s/subscribers', $tag_id),
            ['email_address' => $email_address]
        );
    }

    /**
     * Tag a subscriber.
     *
     * @param integer $tag_id        Tag ID.
     * @param integer $subscriber_id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/tags/tag-a-subscriber
     *
     * @return false|mixed
     */
    public function tag_subscriber(int $tag_id, int $subscriber_id)
    {
        return $this->post(sprintf('tags/%s/subscribers/%s', $tag_id, $subscriber_id));
    }

    /**
     * Remove tag from subscriber.
     *
     * @param integer $tag_id        Tag ID.
     * @param integer $subscriber_id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/tags/remove-tag-from-subscriber
     *
     * @return false|mixed
     */
    public function remove_tag_from_subscriber(int $tag_id, int $subscriber_id)
    {
        return $this->delete(sprintf('tags/%s/subscribers/%s', $tag_id, $subscriber_id));
    }

    /**
     * Remove tag from subscriber by email address.
     *
     * @param integer $tag_id        Tag ID.
     * @param string  $email_address Subscriber email address.
     *
     * @see https://developers.kit.com/api-reference/tags/remove-tag-from-subscriber-by-email-address
     *
     * @return false|mixed
     */
    public function remove_tag_from_subscriber_by_email(int $tag_id, string $email_address)
    {
        return $this->delete(
            sprintf('tags/%s/subscribers', $tag_id),
            ['email_address' => $email_address]
        );
    }

    /**
     * List subscribers for a tag
     *
     * @param integer        $tag_id              Tag ID.
     * @param string         $subscriber_state    Subscriber State (active|bounced|cancelled|complained|inactive).
     * @param \DateTime|null $created_after       Filter subscribers who have been created after this date.
     * @param \DateTime|null $created_before      Filter subscribers who have been created before this date.
     * @param \DateTime|null $tagged_after        Filter subscribers who have been tagged after this date.
     * @param \DateTime|null $tagged_before       Filter subscribers who have been tagged before this date.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/tags/list-subscribers-for-a-tag
     *
     * @return false|mixed
     */
    public function get_tag_subscriptions(
        int $tag_id,
        string $subscriber_state = 'active',
        \DateTime|null $created_after = null,
        \DateTime|null $created_before = null,
        \DateTime|null $tagged_after = null,
        \DateTime|null $tagged_before = null,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Build parameters.
        $options = [];

        if (!empty($subscriber_state)) {
            $options['status'] = $subscriber_state;
        }
        if (!is_null($created_after)) {
            $options['created_after'] = $created_after->format('Y-m-d');
        }
        if (!is_null($created_before)) {
            $options['created_before'] = $created_before->format('Y-m-d');
        }
        if (!is_null($tagged_after)) {
            $options['tagged_after'] = $tagged_after->format('Y-m-d');
        }
        if (!is_null($tagged_before)) {
            $options['tagged_before'] = $tagged_before->format('Y-m-d');
        }

        // Send request.
        return $this->get(
            sprintf('tags/%s/subscribers', $tag_id),
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List email templates.
     *
     * @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.0.0
     *
     * @see https://developers.kit.com/api-reference/email-templates/list-email-templates
     *
     * @return false|mixed
     */
    public function get_email_templates(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'email_templates',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List posts.
     *
     * @param boolean $include_content     To include the content field on each post in the response, use true.
     * @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.5.0
     *
     * @see https://developers.kit.com/api-reference/posts/list-posts
     *
     * @return false|mixed
     */
    public function get_posts(
        bool $include_content = false,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'posts',
            $this->build_total_count_and_pagination_params(
                ['include_content' => $include_content],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Get a post.
     *
     * @param integer $id Post ID.
     *
     * @since 2.5.0
     *
     * @see https://developers.kit.com/api-reference/posts/get-a-post
     *
     * @return mixed|object
     */
    public function get_post(int $id)
    {
        return $this->get(sprintf('posts/%s', $id));
    }

    /**
     * List subscribers.
     *
     * @param string         $subscriber_state    Subscriber State (active|bounced|cancelled|complained|inactive).
     * @param string         $email_address       Search susbcribers by email address. This is an exact match search.
     * @param \DateTime|null $created_after       Filter subscribers who have been created after this date.
     * @param \DateTime|null $created_before      Filter subscribers who have been created before this date.
     * @param \DateTime|null $updated_after       Filter subscribers who have been updated after this date.
     * @param \DateTime|null $updated_before      Filter subscribers who have been updated before this date.
     * @param string         $sort_field          Sort Field (id|updated_at|cancelled_at).
     * @param string         $sort_order          Sort Order (asc|desc).
     * @param array<string>  $include             Additional fields to include: attribution, tags, location, canceled_at.
     * @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.0.0
     *
     * @see https://developers.kit.com/api-reference/subscribers/list-subscribers
     *
     * @return false|mixed
     */
    public function get_subscribers(
        string $subscriber_state = 'active',
        string $email_address = '',
        \DateTime|null $created_after = null,
        \DateTime|null $created_before = null,
        \DateTime|null $updated_after = null,
        \DateTime|null $updated_before = null,
        string $sort_field = 'id',
        string $sort_order = 'desc',
        array $include = [],
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Build parameters.
        $options = [];

        if (!empty($subscriber_state)) {
            $options['status'] = $subscriber_state;
        }
        if (!empty($email_address)) {
            $options['email_address'] = $email_address;
        }
        if (!is_null($created_after)) {
            $options['created_after'] = $created_after->format('Y-m-d');
        }
        if (!is_null($created_before)) {
            $options['created_before'] = $created_before->format('Y-m-d');
        }
        if (!is_null($updated_after)) {
            $options['updated_after'] = $updated_after->format('Y-m-d');
        }
        if (!is_null($updated_before)) {
            $options['updated_before'] = $updated_before->format('Y-m-d');
        }
        if (!empty($sort_field)) {
            $options['sort_field'] = $sort_field;
        }
        if (!empty($sort_order)) {
            $options['sort_order'] = $sort_order;
        }
        if (!empty($include)) {
            $options['include'] = implode(',', $include);
        }

        // Send request.
        return $this->get(
            'subscribers',
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a subscriber.
     *
     * Behaves as an upsert. If a subscriber with the provided email address does not exist,
     * it creates one with the specified first name and state. If a subscriber with the provided
     * email address already exists, it updates the first name.
     *
     * @param string                $email_address    Email Address.
     * @param string                $first_name       First Name.
     * @param string                $subscriber_state Subscriber State (active|bounced|cancelled|complained|inactive).
     * @param array<string, string> $fields           Custom Fields.
     *
     * @since 2.0.0
     *
     * @see https://developers.kit.com/api-reference/subscribers/create-a-subscriber
     *
     * @return mixed
     */
    public function create_subscriber(
        string $email_address,
        string $first_name = '',
        string $subscriber_state = '',
        array $fields = []
    ) {
        // Build parameters.
        $options = ['email_address' => $email_address];

        if (!empty($first_name)) {
            $options['first_name'] = $first_name;
        }
        if (!empty($subscriber_state)) {
            $options['state'] = $subscriber_state;
        }
        if (count($fields)) {
            $options['fields'] = $fields;
        }

        // Send request.
        return $this->post(
            'subscribers',
            $options
        );
    }

    /**
     * Bulk create subscribers.
     *
     * @param array<int,array<string,string>> $subscribers  Subscribers.
     * @param string                          $callback_url URL to notify for large batch size when async processing complete.
     *
     * @since 2.0.0
     *
     * @see https://developers.kit.com/api-reference/subscribers/bulk-create-subscribers
     *
     * @return mixed
     */
    public function create_subscribers(array $subscribers, string $callback_url = '')
    {
        // Build parameters.
        $options = ['subscribers' => $subscribers];

        if (!empty($callback_url)) {
            $options['callback_url'] = $callback_url;
        }

        // Send request.
        return $this->post(
            'bulk/subscribers',
            $options
        );
    }

    /**
     * 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.
     *
     * @param string $email_address Email Address.
     *
     * @throws \InvalidArgumentException If the email address is not a valid email format.
     *
     * @see https://developers.kit.com/api-reference/subscribers/get-a-subscriber
     *
     * @return false|integer
     */
    public function get_subscriber_id(string $email_address)
    {
        $subscribers = $this->get(
            'subscribers',
            ['email_address' => $email_address]
        );

        if (!$subscribers instanceof \stdClass) {
            return false;
        }

        if (!is_array($subscribers->subscribers)) {
            return false;
        }

        if (!count($subscribers->subscribers)) {
            return false;
        }

        if (!$subscribers->subscribers[0] instanceof \stdClass) {
            return false;
        }

        if (!is_int($subscribers->subscribers[0]->id)) {
            return false;
        }

        // Return the subscriber's ID.
        return $subscribers->subscribers[0]->id;
    }

    /**
     * Get a subscriber.
     *
     * @param integer $subscriber_id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/subscribers/get-a-subscriber
     *
     * @return mixed|integer
     */
    public function get_subscriber(int $subscriber_id)
    {
        return $this->get(sprintf('subscribers/%s', $subscriber_id));
    }

    /**
     * Update a subscriber.
     *
     * @param integer               $subscriber_id Existing Subscriber ID.
     * @param string                $first_name    New First Name.
     * @param string                $email_address New Email Address.
     * @param array<string, string> $fields        Updated Custom Fields.
     *
     * @see https://developers.kit.com/api-reference/subscribers/update-a-subscriber
     *
     * @return mixed
     */
    public function update_subscriber(
        int $subscriber_id,
        string $first_name = '',
        string $email_address = '',
        array $fields = []
    ) {
        // Build parameters.
        $options = [];

        if (!empty($first_name)) {
            $options['first_name'] = $first_name;
        }
        if (!empty($email_address)) {
            $options['email_address'] = $email_address;
        }
        if (!empty($fields)) {
            $options['fields'] = $fields;
        }

        // Send request.
        return $this->put(
            sprintf('subscribers/%s', $subscriber_id),
            $options
        );
    }

    /**
     * Unsubscribe subscriber by email address.
     *
     * @param string $email_address Email Address.
     *
     * @see https://developers.kit.com/api-reference/subscribers/unsubscribe-subscriber
     *
     * @return mixed|object
     */
    public function unsubscribe_by_email(string $email_address)
    {
        return $this->post(
            sprintf(
                'subscribers/%s/unsubscribe',
                $this->get_subscriber_id($email_address)
            )
        );
    }

    /**
     * Unsubscribe subscriber.
     *
     * @param integer $subscriber_id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/subscribers/unsubscribe-subscriber
     *
     * @return mixed|object
     */
    public function unsubscribe(int $subscriber_id)
    {
        return $this->post(sprintf('subscribers/%s/unsubscribe', $subscriber_id));
    }

    /**
     * Get the email statistics for a specific subscriber.
     *
     * @param integer $id Subscriber ID.
     *
     * @see https://developers.kit.com/api-reference/subscribers/list-stats-for-a-subscriber
     *
     * @return mixed|object
     */
    public function get_subscriber_stats(int $id)
    {
        return $this->get(sprintf('subscribers/%s/stats', $id));
    }

    /**
     * List tags for a subscriber.
     *
     * @param integer $subscriber_id       Subscriber ID.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/subscribers/list-tags-for-a-subscriber
     *
     * @return mixed|array<int,\stdClass>
     */
    public function get_subscriber_tags(
        int $subscriber_id,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        return $this->get(
            sprintf('subscribers/%s/tags', $subscriber_id),
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * List broadcasts.
     *
     * @param \DateTime|null $sent_after          Get broadcasts sent after the given date.
     * @param \DateTime|null $sent_before         Get broadcasts sent before the given date.
     * @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.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/list-broadcasts
     *
     * @return false|mixed
     */
    public function get_broadcasts(
        \DateTime|null $sent_after = null,
        \DateTime|null $sent_before = null,
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Build parameters.
        $options = [];

        if (!is_null($sent_after)) {
            $options['sent_after'] = $sent_after->format('Y-m-d');
        }
        if (!is_null($sent_before)) {
            $options['sent_before'] = $sent_before->format('Y-m-d');
        }

        // Send request.
        return $this->get(
            'broadcasts',
            $this->build_total_count_and_pagination_params(
                $options,
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a broadcast.
     *
     * @param string               $subject           The broadcast email's subject.
     * @param string               $content           The broadcast's email HTML content.
     * @param string               $description       An internal description of this broadcast.
     * @param boolean              $public            Specifies whether or not this is a public post.
     * @param \DateTime|null       $published_at      Specifies the time that this post was published (applicable
     *                                                only to public posts).
     * @param \DateTime|null       $send_at           Time that this broadcast should be sent; leave blank to create
     *                                                a draft broadcast. If set to a future time, this is the time that
     *                                                the broadcast will be scheduled to send.
     * @param string               $email_address     Sending email address; leave blank to use your account's
     *                                                default sending email address.
     * @param string               $email_template_id ID of the email template to use; leave blank to use your
     *                                                account's default email template.
     * @param string               $thumbnail_alt     Specify the ALT attribute of the public thumbnail image
     *                                                (applicable only to public posts).
     * @param string               $thumbnail_url     Specify the URL of the thumbnail image to accompany the broadcast
     *                                                post (applicable only to public posts).
     * @param string               $preview_text      Specify the preview text of the email.
     * @param array<string,string> $subscriber_filter Filter subscriber(s) to send the email to.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/create-a-broadcast
     *
     * @return mixed|object
     */
    public function create_broadcast(
        string $subject = '',
        string $content = '',
        string $description = '',
        bool $public = false,
        \DateTime|null $published_at = null,
        \DateTime|null $send_at = null,
        string $email_address = '',
        string $email_template_id = '',
        string $thumbnail_alt = '',
        string $thumbnail_url = '',
        string $preview_text = '',
        array $subscriber_filter = []
    ) {
        $options = [
            'email_template_id' => $email_template_id,
            'email_address'     => $email_address,
            'content'           => $content,
            'description'       => $description,
            'public'            => $public,
            'published_at'      => (!is_null($published_at) ? $published_at->format('Y-m-d H:i:s') : ''),
            'send_at'           => (!is_null($send_at) ? $send_at->format('Y-m-d H:i:s') : ''),
            'thumbnail_alt'     => $thumbnail_alt,
            'thumbnail_url'     => $thumbnail_url,
            'preview_text'      => $preview_text,
            'subject'           => $subject,
        ];
        if (count($subscriber_filter)) {
            $options['subscriber_filter'] = $subscriber_filter;
        }

        // Iterate through options, removing blank entries.
        foreach ($options as $key => $value) {
            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        // If the post isn't public, remove some options that don't apply.
        if (!$public) {
            unset($options['published_at'], $options['thumbnail_alt'], $options['thumbnail_url']);
        }

        // Send request.
        return $this->post(
            'broadcasts',
            $options
        );
    }

    /**
     * Get a broadcast.
     *
     * @param integer $id Broadcast ID.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/get-a-broadcast
     *
     * @return mixed|object
     */
    public function get_broadcast(int $id)
    {
        return $this->get(sprintf('broadcasts/%s', $id));
    }

    /**
     * Get stats for a broadcast.
     *
     * @param integer $id Broadcast ID.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-broadcast
     *
     * @return mixed|object
     */
    public function get_broadcast_stats(int $id)
    {
        return $this->get(sprintf('broadcasts/%s/stats', $id));
    }

    /**
     * List link clicks for a specific broadcast.
     *
     * @param integer $id            Broadcast ID.
     * @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.2.1
     *
     * @see https://developers.kit.com/api-reference/broadcasts/get-link-clicks-for-a-broadcast
     *
     * @return false|mixed
     */
    public function get_broadcast_link_clicks(
        int $id,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            sprintf('broadcasts/%s/clicks', $id),
            $this->build_total_count_and_pagination_params(
                after_cursor: $after_cursor,
                before_cursor: $before_cursor,
                per_page: $per_page
            )
        );
    }

    /**
     * List stats for a list of broadcasts.
     *
     * @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.2.1
     *
     * @see https://developers.kit.com/api-reference/broadcasts/get-stats-for-a-list-of-broadcasts
     *
     * @return false|mixed
     */
    public function get_broadcasts_stats(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'broadcasts/stats',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }


    /**
     * Update a broadcast.
     *
     * @param integer              $id                Broadcast ID.
     * @param string               $subject           The broadcast email's subject.
     * @param string               $content           The broadcast's email HTML content.
     * @param string               $description       An internal description of this broadcast.
     * @param boolean              $public            Specifies whether or not this is a public post.
     * @param \DateTime|null       $published_at      Specifies the time that this post was published (applicable
     *                                                only to public posts).
     * @param \DateTime|null       $send_at           Time that this broadcast should be sent; leave blank to create
     *                                                a draft broadcast. If set to a future time, this is the time that
     *                                                the broadcast will be scheduled to send.
     * @param string               $email_address     Sending email address; leave blank to use your account's
     *                                                default sending email address.
     * @param string               $email_template_id ID of the email template to use; leave blank to use your
     *                                                account's default email template.
     * @param string               $thumbnail_alt     Specify the ALT attribute of the public thumbnail image
     *                                                (applicable only to public posts).
     * @param string               $thumbnail_url     Specify the URL of the thumbnail image to accompany the broadcast
     *                                                post (applicable only to public posts).
     * @param string               $preview_text      Specify the preview text of the email.
     * @param array<string,string> $subscriber_filter Filter subscriber(s) to send the email to.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/update-a-broadcast
     *
     * @return mixed|object
     */
    public function update_broadcast(
        int $id,
        string $subject = '',
        string $content = '',
        string $description = '',
        bool $public = false,
        \DateTime|null $published_at = null,
        \DateTime|null $send_at = null,
        string $email_address = '',
        string $email_template_id = '',
        string $thumbnail_alt = '',
        string $thumbnail_url = '',
        string $preview_text = '',
        array $subscriber_filter = []
    ) {
        $options = [
            'email_template_id' => $email_template_id,
            'email_address'     => $email_address,
            'content'           => $content,
            'description'       => $description,
            'public'            => $public,
            'published_at'      => (!is_null($published_at) ? $published_at->format('Y-m-d H:i:s') : ''),
            'send_at'           => (!is_null($send_at) ? $send_at->format('Y-m-d H:i:s') : ''),
            'thumbnail_alt'     => $thumbnail_alt,
            'thumbnail_url'     => $thumbnail_url,
            'preview_text'      => $preview_text,
            'subject'           => $subject,
        ];
        if (count($subscriber_filter)) {
            $options['subscriber_filter'] = $subscriber_filter;
        }

        // Iterate through options, removing blank entries.
        foreach ($options as $key => $value) {
            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        // If the post isn't public, remove some options that don't apply.
        if (!$public) {
            unset($options['published_at'], $options['thumbnail_alt'], $options['thumbnail_url']);
        }

        // Send request.
        return $this->put(
            sprintf('broadcasts/%s', $id),
            $options
        );
    }

    /**
     * Deletes a broadcast.
     *
     * @param integer $id Broadcast ID.
     *
     * @see https://developers.kit.com/api-reference/broadcasts/delete-a-broadcast
     *
     * @return mixed|object
     */
    public function delete_broadcast(int $id)
    {
        return $this->delete(sprintf('broadcasts/%s', $id));
    }

    /**
     * List webhooks.
     *
     * @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.0.0
     *
     * @see https://developers.kit.com/api-reference/webhooks/list-webhooks
     *
     * @return false|mixed
     */
    public function get_webhooks(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'webhooks',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a webhook.
     *
     * @param string $url       URL to receive event.
     * @param string $event     Event to subscribe to.
     * @param string $parameter Optional parameter depending on the event.
     *
     * @see https://developers.kit.com/api-reference/webhooks/create-a-webhook
     *
     * @throws \InvalidArgumentException If the event is not supported.
     *
     * @return mixed|object
     */
    public function create_webhook(string $url, string $event, string $parameter = '')
    {
        // Depending on the event, build the required event array structure.
        switch ($event) {
            case 'subscriber.subscriber_activate':
            case 'subscriber.subscriber_unsubscribe':
            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;

            case 'subscriber.form_subscribe':
                $eventData = [
                    'name'    => $event,
                    'form_id' => $parameter,
                ];
                break;

            case 'subscriber.course_subscribe':
            case 'subscriber.course_complete':
                $eventData = [
                    'name'      => $event,
                    'course_id' => $parameter,
                ];
                break;

            case 'subscriber.link_click':
                $eventData = [
                    'name'            => $event,
                    'initiator_value' => $parameter,
                ];
                break;

            case 'subscriber.product_purchase':
                $eventData = [
                    'name'       => $event,
                    'product_id' => $parameter,
                ];
                break;

            case 'subscriber.tag_add':
            case 'subscriber.tag_remove':
                $eventData = [
                    'name'   => $event,
                    'tag_id' => $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

        // Send request.
        return $this->post(
            'webhooks',
            [
                'target_url' => $url,
                'event'      => $eventData,
            ]
        );
    }

    /**
     * Delete a webhook.
     *
     * @param integer $id Webhook ID.
     *
     * @see https://developers.kit.com/api-reference/webhooks/delete-a-webhook
     *
     * @return mixed|object
     */
    public function delete_webhook(int $id)
    {
        return $this->delete(sprintf('webhooks/%s', $id));
    }

    /**
     * List custom fields.
     *
     * @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.
     *
     * @see https://developers.kit.com/api-reference/custom-fields/list-custom-fields
     *
     * @return false|mixed
     */
    public function get_custom_fields(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'custom_fields',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Create a custom field.
     *
     * @param string $label Custom Field label.
     *
     * @see https://developers.kit.com/api-reference/custom-fields/create-a-custom-field
     *
     * @return mixed|object
     */
    public function create_custom_field(string $label)
    {
        return $this->post(
            'custom_fields',
            ['label' => $label]
        );
    }

    /**
     * Bulk create custom fields.
     *
     * @param array<string> $labels       Custom Fields labels.
     * @param string        $callback_url URL to notify for large batch size when async processing complete.
     *
     * @see https://developers.kit.com/api-reference/custom-fields/bulk-create-custom-fields
     *
     * @return mixed|object
     */
    public function create_custom_fields(array $labels, string $callback_url = '')
    {
        // Build parameters.
        $options = [
            'custom_fields' => [],
        ];
        foreach ($labels as $i => $label) {
            $options['custom_fields'][] = [
                'label' => (string) $label,
            ];
        }

        if (!empty($callback_url)) {
            $options['callback_url'] = $callback_url;
        }

        // Send request.
        return $this->post(
            'bulk/custom_fields',
            $options
        );
    }

    /**
     * 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.
     *
     * @param integer $id    Custom Field ID.
     * @param string  $label Updated Custom Field label.
     *
     * @see https://developers.kit.com/api-reference/custom-fields/update-a-custom-field
     *
     * @return mixed|object
     */
    public function update_custom_field(int $id, string $label)
    {
        return $this->put(
            sprintf('custom_fields/%s', $id),
            ['label' => $label]
        );
    }

    /**
     * Delete custom field.
     *
     * @param integer $id Custom Field ID.
     *
     * @see https://developers.kit.com/api-reference/custom-fields/delete-custom-field
     *
     * @return mixed|object
     */
    public function delete_custom_field(int $id)
    {
        return $this->delete(sprintf('custom_fields/%s', $id));
    }

    /**
     * List purchases.
     *
     * @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.
     *
     * @see https://developers.kit.com/api-reference/purchases/list-purchases
     *
     * @return false|mixed
     */
    public function get_purchases(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'purchases',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Get a purchase.
     *
     * @param integer $purchase_id Purchase ID.
     *
     * @see https://developers.kit.com/api-reference/purchases/get-a-purchase
     *
     * @return mixed|object
     */
    public function get_purchase(int $purchase_id)
    {
        return $this->get(sprintf('purchases/%s', $purchase_id));
    }

    /**
     * Create a purchase.
     *
     * @param string                         $email_address    Email Address.
     * @param string                         $transaction_id   Transaction ID.
     * @param array<string,int|float|string> $products         Products.
     * @param string                         $currency         ISO Currency Code.
     * @param string|null                    $first_name       First Name.
     * @param string|null                    $status           Order Status.
     * @param float                          $subtotal         Subtotal.
     * @param float                          $tax              Tax.
     * @param float                          $shipping         Shipping.
     * @param float                          $discount         Discount.
     * @param float                          $total            Total.
     * @param \DateTime|null                 $transaction_time Transaction date and time.
     *
     * @see https://developers.kit.com/api-reference/purchases/create-a-purchase
     *
     * @return mixed|object
     */
    public function create_purchase(
        string $email_address,
        string $transaction_id,
        array $products,
        string $currency = 'USD',
        string|null $first_name = null,
        string|null $status = null,
        float $subtotal = 0,
        float $tax = 0,
        float $shipping = 0,
        float $discount = 0,
        float $total = 0,
        \DateTime|null $transaction_time = null
    ) {
        // Build parameters.
        $options = [
            // Required fields.
            'email_address'    => $email_address,
            'transaction_id'   => $transaction_id,
            'products'         => $products,
            'currency'         => $currency, // Required, but if not provided, API will default to USD.

            // Optional fields.
            'first_name'       => $first_name,
            'status'           => $status,
            'subtotal'         => $subtotal,
            'tax'              => $tax,
            'shipping'         => $shipping,
            'discount'         => $discount,
            'total'            => $total,
            'transaction_time' => (!is_null($transaction_time) ? $transaction_time->format('Y-m-d H:i:s') : ''),
        ];

        // Iterate through options, removing blank and null entries.
        foreach ($options as $key => $value) {
            if (is_null($value)) {
                unset($options[$key]);
                continue;
            }

            if (is_string($value) && strlen($value) === 0) {
                unset($options[$key]);
            }
        }

        return $this->post('purchases', $options);
    }

    /**
     * List segments.
     *
     * @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.0.0
     *
     * @see https://developers.kit.com/api-reference/segments/list-segments
     *
     * @return false|mixed
     */
    public function get_segments(
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        // Send request.
        return $this->get(
            'segments',
            $this->build_total_count_and_pagination_params(
                [],
                $include_total_count,
                $after_cursor,
                $before_cursor,
                $per_page
            )
        );
    }

    /**
     * Converts any relative URls to absolute, fully qualified HTTP(s) URLs for the given
     * DOM Elements.
     *
     * @param \DOMNodeList<\DOMElement> $elements  Elements.
     * @param string                    $attribute HTML Attribute.
     * @param string                    $url       Absolute URL to prepend to relative URLs.
     *
     * @return void
     */
    public function convert_relative_to_absolute_urls(\DOMNodeList $elements, string $attribute, string $url) // phpcs:ignore Squiz.Commenting.FunctionComment.IncorrectTypeHint, Generic.Files.LineLength.TooLong
    {
        // Store DOMNodeList in array, as iteration stops if a node is modified.
        $nodes = [];
        foreach ($elements as $element) {
            $nodes[] = $element;
        }

        foreach ($nodes as $element) {
            // Skip if the attribute's value is empty.
            if (empty($element->getAttribute($attribute))) {
                continue;
            }

            // Skip if the attribute's value is a fully qualified URL.
            if (filter_var($element->getAttribute($attribute), FILTER_VALIDATE_URL)) {
                continue;
            }

            // Skip if this is a Google Font CSS URL.
            if (strpos($element->getAttribute($attribute), '//fonts.googleapis.com') !== false) {
                continue;
            }

            // Remove element if it's rocket-loader.min.js. Including it prevents landing page redirects from working.
            if (strpos($element->getAttribute($attribute), 'rocket-loader.min.js') !== false) {
                if ($element->parentNode instanceof \DOMNode) {
                    $element->parentNode->removeChild($element);
                }
                continue;
            }

            // If here, the attribute's value is a relative URL, missing the http(s) and domain.
            // Prepend the URL to the attribute's value.
            $element->setAttribute($attribute, $url . $element->getAttribute($attribute));
        }//end foreach
    }

    /**
     * Returns the HTML within the DOMDocument's <body> tag as a string.
     *
     * @param \DOMDocument $dom DOM Document.
     *
     * @since 2.1.0
     *
     * @return string
     */
    public function get_body_html(\DOMDocument $dom)
    {
        $body = $dom->getElementsByTagName('body')->item(0);

        if (! $body instanceof \DOMElement) {
            return '';
        }

        $html = '';
        foreach ($body->childNodes as $child) { // phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
            $html .= $dom->saveHTML($child);
        }

        return $html;
    }

    /**
     * Adds total count and pagination parameters to the given array of existing API parameters.
     *
     * @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|int|bool|list<array<string, mixed>>>
     */
    private function build_total_count_and_pagination_params(
        array $params = [],
        bool $include_total_count = false,
        string $after_cursor = '',
        string $before_cursor = '',
        int $per_page = 100
    ) {
        $params['include_total_count'] = $include_total_count;
        if (!empty($after_cursor)) {
            $params['after'] = $after_cursor;
        }
        if (!empty($before_cursor)) {
            $params['before'] = $before_cursor;
        }
        if (!empty($per_page)) {
            $params['per_page'] = $per_page;
        }

        return $params;
    }

    /**
     * Performs a GET request to the API.
     *
     * @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
     */
    public function get(string $endpoint, array $args = [])
    {
        return $this->request($endpoint, 'GET', $args);
    }

    /**
     * Performs a POST request to the API.
     *
     * @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
     */
    public function post(string $endpoint, array $args = [])
    {
        return $this->request($endpoint, 'POST', $args);
    }

    /**
     * Performs a PUT request to the API.
     *
     * @param string                                                                                                   $endpoint API Endpoint.
     * @param array<string, bool|integer|float|string|null|array<int|string, array<int>|boolean|integer|float|string>> $args     Request arguments.
     *
     * @return false|mixed
     */
    public function put(string $endpoint, array $args = [])
    {
        return $this->request($endpoint, 'PUT', $args);
    }

    /**
     * Performs a DELETE request to the API.
     *
     * @param string                                                     $endpoint API Endpoint.
     * @param array<string, int|string|array<string, int|string>|string> $args     Request arguments.
     *
     * @return false|mixed
     */
    public function delete(string $endpoint, array $args = [])
    {
        return $this->request($endpoint, 'DELETE', $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, bool|integer|float|string|array<string, mixed>>> $args     Request arguments.
     *
     * @throws \Exception If JSON encoding arguments failed.
     *
     * @return false|mixed
     */
    abstract public function request(string $endpoint, string $method, array $args = []);

    /**
     * Returns the headers to use in an API request.
     *
     * @param string  $type Accept and Content-Type Headers.
     * @param boolean $auth Include authorization header.
     *
     * @since 2.0.0
     *
     * @return array<string,string>
     */
    abstract public function get_request_headers(string $type = 'application/json', bool $auth = true);

    /**
     * Returns the maximum amount of time to wait for
     * a response to the request before exiting.
     *
     * @since 2.0.0
     *
     * @return integer     Timeout, in seconds.
     */
    abstract public function get_timeout();

    /**
     * Returns the user agent string to use in all HTTP requests.
     *
     * @since 2.0.0
     *
     * @return string
     */
    abstract public function get_user_agent();
}