<?php
namespace SparkPost;

/**
 * SDK class for querying the Message Events API
 *
 * @see https://developers.sparkpost.com/api/#/reference/message-events
 */
class MessageEvent extends APIResource
{
  public $endpoint = 'message-events';

  /**
   * Method for issuing search requests to the Message Events API.
   *
   * The method passes-through all of the query parameters - the valid ones are listed at
   * @link https://developers.sparkpost.com/api/#/reference/message-events/events-documentation/search-for-message-events
   *
   * @param array $queryParams  The query parameters.  Note that a query parameter containing an array
   * is collapsed into a comma-separated list.
   *
   * @return array The result of the query.
   */
  public function search(Array $queryParams)
  {
    // check for DateTime objects & replace them with the formatted string equivalent
    foreach(["from", "to"] as $dateTimeParam) {
      if (isset($queryParams[$dateTimeParam]) && $queryParams[$dateTimeParam] instanceof \DateTime) {
        // the message events API doesn't allow the seconds or GMT offset, so strip them
        $queryParams[$dateTimeParam] = substr($queryParams[$dateTimeParam]->format(\DateTime::ATOM), 0, 16);
      }
    }

    return $this->get(null, $queryParams);
  }

  /**
   * List descriptions of the event fields that could be included in a response from the MessageEvent::search() method.
   *
   * @return array The event field descriptions.
   */
  public function documentation() {
    return $this->get("events/documentation");
  }

  /**
   * List examples of the event data that will be included in a response from the MessageEvent::search() method.
   */
  public function samples(Array $events) {
    return $this->get("events/samples", ["events"=>$events]);
  }
}