<?php

/**
 * Class to access a campaigns resources from the create send API.
 * This class includes functions to create and send campaigns,
 * along with accessing lists of campaign specific resources i.e reporting statistics
 * @author tobyb
 *
 */
class Thrive_Dash_Api_CampaignMonitor_Campaigns extends Thrive_Dash_Api_CampaignMonitor_Base {

	/**
	 * The base route of the campaigns resource.
	 * @var string
	 * @access private
	 */
	var $_campaigns_base_route;

	/**
	 * Constructor.
	 *
	 * @param $campaign_id string The campaign id to access (Ignored for create requests)
	 * @param $auth_details array Authentication details to use for API calls.
	 *        This array must take one of the following forms:
	 *        If using OAuth to authenticate:
	 *        array(
	 *          'access_token' => 'your access token',
	 *          'refresh_token' => 'your refresh token')
	 *
	 *        Or if using an API key:
	 *        array('api_key' => 'your api key')
	 * @param $protocol string The protocol to use for requests (http|https)
	 * @param $debug_level int The level of debugging required Thrive_Dash_Api_CampaignMonitor_Log_NONE | Thrive_Dash_Api_CampaignMonitor_Log_ERROR | Thrive_Dash_Api_CampaignMonitor_Log_WARNING | Thrive_Dash_Api_CampaignMonitor_Log_VERBOSE
	 * @param $host string The host to send API requests to. There is no need to change this
	 * @param $log Thrive_Dash_Api_CampaignMonitor_Log The logger to use. Used for dependency injection
	 * @param $serialiser the serialiser to use. Used for dependency injection
	 * @param $transport the transport to use. Used for dependency injection
	 *
	 * @access public
	 */
	function __construct(
		$campaign_id,
		$auth_details,
		$protocol = 'http',
		$debug_level = Thrive_Dash_Api_CampaignMonitor_Log_NONE,
		$host = 'api.createsend.com',
		$log = null,
		$serialiser = null,
		$transport = null
	) {

		parent::__construct( $auth_details, $protocol, $debug_level, $host, $log, $serialiser, $transport );
		$this->set_campaign_id( $campaign_id );
	}

	/**
	 * Change the campaign id used for calls after construction
	 *
	 * @param $campaign_id
	 *
	 * @access public
	 */
	function set_campaign_id( $campaign_id ) {
		$this->_campaigns_base_route = $this->_base_route . 'campaigns/' . $campaign_id . '/';
	}

	/**
	 * Creates a new campaign based on the provided campaign info.
	 * At least on of the ListIDs and Segments parameters must be provided
	 *
	 * @param string $client_id The client to create the campaign for
	 * @param array $campaign_info The campaign information to use during creation.
	 *     This array should be of the form
	 *     array(
	 *         'Subject' => string required The campaign subject
	 *         'Name' => string required The campaign name
	 *         'FromName' => string required The From name for the campaign
	 *         'FromEmail' => string required The From address for the campaign
	 *         'ReplyTo' => string required The Reply-To address for the campaign
	 *         'HtmlUrl' => string required A url to download the campaign HTML from
	 *         'TextUrl' => string optional A url to download the campaign
	 *           text version from. If not provided, text content will be
	 *           automatically generated from HTML content.
	 *         'ListIDs' => array<string> optional An array of list ids to send the campaign to
	 *         'SegmentIDs' => array<string> optional An array of segment ids to send the campaign to.
	 *     )
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be the ID of the newly created campaign
	 */
	function create( $client_id, $campaign_info ) {
		return $this->post_request( $this->_base_route . 'campaigns/' . $client_id . '.json', $campaign_info );
	}

	/**
	 * Creates a new campaign from a template based on the info provided.
	 * At least on of the ListIDs and Segments parameters must be provided
	 *
	 * @param string $client_id The client to create the campaign for
	 * @param array $campaign_info The campaign information to use during creation.
	 *     This array should be of the form
	 *     array(
	 *         'Subject' => string required The campaign subject
	 *         'Name' => string required The campaign name
	 *         'FromName' => string required The From name for the campaign
	 *         'FromEmail' => string required The From address for the campaign
	 *         'ReplyTo' => string required The Reply-To address for the campaign
	 *         'ListIDs' => array<string> optional An array of list ids to send the campaign to
	 *         'SegmentIDs' => array<string> optional An array of segment ids to send the campaign to
	 *         'TemplateID' => string required The ID of the template to use
	 *         'TemplateContent' => array required The content which will be used to fill the editable areas of the template
	 *     )
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be the ID of the newly created campaign
	 */
	function create_from_template( $client_id, $campaign_info ) {
		return $this->post_request( $this->_base_route . 'campaigns/' . $client_id . '/fromtemplate.json', $campaign_info );
	}

	/**
	 * Sends a preview of an existing campaign to the specified recipients.
	 *
	 * @param array <string> $recipients The recipients to send the preview to.
	 * @param string $personalize How to personalize the campaign content. Valid options are:
	 *     'Random': Choose a random campaign recipient and use their personalisation data
	 *     'Fallback': Use the fallback terms specified in the campaign content
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be empty
	 */
	function send_preview( $recipients, $personalize = 'Random' ) {
		$preview_data = array(
			'PreviewRecipients' => $recipients,
			'Personalize'       => $personalize
		);

		return $this->post_request( $this->_campaigns_base_route . 'sendpreview.json', $preview_data );
	}

	/**
	 * Sends an existing campaign based on the scheduling information provided
	 *
	 * @param array $schedule The campaign scheduling information.
	 *     This array should be of the form
	 *     array (
	 *        'ConfirmationEmail' => string required The email address to send a confirmation email to,
	 *        'SendDate' => string required The date to send the campaign or 'immediately'.
	 *                      The date should be in the format 'y-M-d'
	 *     )
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be empty
	 */
	function send( $schedule ) {
		return $this->post_request( $this->_campaigns_base_route . 'send.json', $schedule );
	}

	/**
	 * Unschedules the campaign, moving it back into the drafts. If the campaign has been sent or is
	 * in the process of sending, this api request will fail.
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be empty
	 */
	function unschedule() {
		return $this->post_request( $this->_campaigns_base_route . 'unschedule.json', null );
	}

	/**
	 * Deletes an existing campaign from the system
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be empty
	 */
	function delete() {
		return $this->delete_request( trim( $this->_campaigns_base_route, '/' ) . '.json' );
	}

	/**
	 * Gets all email addresses on the current clients suppression list
	 *
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The suppressed email address
	 *             'ListID' => The ID of the list this subscriber comes from
	 *         }
	 *     )
	 * }
	 */
	function get_recipients(
		$page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'recipients.json', $page_number,
			$page_size, $order_field, $order_direction, '?' );
	}

	/**
	 * Gets all bounces recorded for a campaign
	 *
	 * @param string $since The date to start getting bounces from
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The email that bounced
	 *             'ListID' => The ID of the list the subscriber was on
	 *             'BounceType' => The type of bounce
	 *             'Date' => The date the bounce message was received
	 *             'Reason' => The reason for the bounce
	 *         }
	 *     )
	 * }
	 * )
	 */
	function get_bounces(
		$since = '', $page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'bounces.json?date=' . urlencode( $since ),
			$page_number, $page_size, $order_field, $order_direction );
	}

	/**
	 * Gets the lists a campaign was sent to
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'Lists' =>  array(
	 *         {
	 *             'ListID' => The list id
	 *             'Name' => The list name
	 *         }
	 *     ),
	 *     'Segments' => array(
	 *         {
	 *             'ListID' => The list id of the segment
	 *             'SegmentID' => The id of the segment
	 *             'Title' => The title of the segment
	 *         }
	 *     )
	 * }
	 */
	function get_lists_and_segments() {
		return $this->get_request( $this->_campaigns_base_route . 'listsandsegments.json' );
	}

	/**
	 * Gets a summary of all campaign reporting statistics
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'Recipients' => The total recipients of the campaign
	 *     'TotalOpened' => The total number of opens recorded
	 *     'Clicks' => The total number of recorded clicks
	 *     'Unsubscribed' => The number of recipients who unsubscribed
	 *     'Bounced' => The number of recipients who bounced
	 *     'UniqueOpened' => The number of recipients who opened
	 *     'WebVersionURL' => The url of the web version of the campaign
	 *     'WebVersionTextURL' => The url of the web version of the text version of the campaign
	 *     'WorldviewURL' => The public Worldview URL for the campaign
	 *     'Forwards' => The number of times the campaign has been forwarded to a friend
	 *     'Likes' => The number of times the campaign has been 'liked' on Facebook
	 *     'Mentions' => The number of times the campaign has been tweeted about
	 *     'SpamComplaints' => The number of recipients who marked the campaign as spam
	 * }
	 */
	function get_summary() {
		return $this->get_request( $this->_campaigns_base_route . 'summary.json' );
	}

	/**
	 * Gets the email clients that subscribers used to open the campaign
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * array(
	 *     {
	 *         Client => The email client name
	 *         Version => The email client version
	 *         Percentage => The percentage of subscribers who used this email client
	 *         Subscribers => The actual number of subscribers who used this email client
	 *     }
	 * )
	 */
	function get_email_client_usage() {
		return $this->get_request( $this->_campaigns_base_route . 'emailclientusage.json' );
	}

	/**
	 * Gets all opens recorded for a campaign since the provided date
	 *
	 * @param string $since The date to start getting opens from
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The email address of the subscriber who opened
	 *             'ListID' => The list id of the list containing the subscriber
	 *             'Date' => The date of the open
	 *             'IPAddress' => The ip address where the open originated
	 *             'Latitude' => The geocoded latitude from the IP address
	 *             'Longitude' => The geocoded longitude from the IP address
	 *             'City' => The geocoded city from the IP address
	 *             'Region' => The geocoded region from the IP address
	 *             'CountryCode' => The geocoded two letter country code from the IP address
	 *             'CountryName' => The geocoded full country name from the IP address
	 *         }
	 *     )
	 * }
	 */
	function get_opens(
		$since = '', $page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'opens.json?date=' . urlencode( $since ),
			$page_number, $page_size, $order_field, $order_direction );
	}

	/**
	 * Gets all clicks recorded for a campaign since the provided date
	 *
	 * @param string $since The date to start getting clicks from
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The email address of the subscriber who clicked
	 *             'ListID' => The list id of the list containing the subscriber
	 *             'Date' => The date of the click
	 *             'IPAddress' => The ip address where the click originated
	 *             'URL' => The url that the subscriber clicked on
	 *             'Latitude' => The geocoded latitude from the IP address
	 *             'Longitude' => The geocoded longitude from the IP address
	 *             'City' => The geocoded city from the IP address
	 *             'Region' => The geocoded region from the IP address
	 *             'CountryCode' => The geocoded two letter country code from the IP address
	 *             'CountryName' => The geocoded full country name from the IP address
	 *         }
	 *     )
	 * }
	 */
	function get_clicks(
		$since = '', $page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'clicks.json?date=' . urlencode( $since ),
			$page_number, $page_size, $order_field, $order_direction );
	}

	/**
	 * Gets all unsubscribes recorded for a campaign since the provided date
	 *
	 * @param string $since The date to start getting unsubscribes from
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The email address of the subscriber who unsubscribed
	 *             'ListID' => The list id of the list containing the subscriber
	 *             'Date' => The date of the unsubscribe
	 *             'IPAddress' => The ip address where the unsubscribe originated
	 *         }
	 *     )
	 * }
	 */
	function get_unsubscribes(
		$since = '', $page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'unsubscribes.json?date=' . urlencode( $since ),
			$page_number, $page_size, $order_field, $order_direction );
	}

	/**
	 * Gets all spam complaints recorded for a campaign since the provided date
	 *
	 * @param string $since The date to start getting spam complaints from
	 * @param int $page_number The page number to get
	 * @param int $page_size The number of records per page
	 * @param string $order_field The field to order the record set by ('EMAIL', 'LIST', 'DATE')
	 * @param string $order_direction The direction to order the record set ('ASC', 'DESC')
	 *
	 * @access public
	 * @return Thrive_Dash_Api_CampaignMonitor_Result A successful response will be an object of the form
	 * {
	 *     'ResultsOrderedBy' => The field the results are ordered by
	 *     'OrderDirection' => The order direction
	 *     'PageNumber' => The page number for the result set
	 *     'PageSize' => The page size used
	 *     'RecordsOnThisPage' => The number of records returned
	 *     'TotalNumberOfRecords' => The total number of records available
	 *     'NumberOfPages' => The total number of pages for this collection
	 *     'Results' => array(
	 *         {
	 *             'EmailAddress' => The email address of the subscriber who unsubscribed
	 *             'ListID' => The list id of the list containing the subscriber
	 *             'Date' => The date of the unsubscribe
	 *         }
	 *     )
	 * }
	 */
	function get_spam(
		$since = '', $page_number = null, $page_size = null, $order_field = null,
		$order_direction = null
	) {
		return $this->get_request_paged( $this->_campaigns_base_route . 'spam.json?date=' . urlencode( $since ),
			$page_number, $page_size, $order_field, $order_direction );
	}
}