<?php
namespace Components\Data\Contracts;

interface AnalyticsProvider
{
    /**
     * Returns the data required by the dashboard_summary component.
     * Keys:
     * - emailsSent (int)
     * - monthsAgo (int)
     * - beginningIso (string)
     * - bouncedPercent (int)
     * - bouncedCount (int)
     * - openedPercent (int)
     * - openedCount (int)
     * - clickPercent (int)
     * - clickCount (int)
     * - orderPercent (int)
     * - orderCount (int)
     * - mobilePercent (int)
     * - mobileCount (int)
     * - revenue (string)
     * - voucherSum (string)
     * - bot (string|null) beginning_of_time raw value
     */
    public function getDashboardSummary($refresh = false): array;

    /**
     * Returns performance data for a specific module or campaign item.
     * Keys:
     * - sent (int)
     * - opened (int)
     * - clicked (int)
     * - orders (int)
     * - revenue (string)
     * - openRate (float)
     * - clickRate (float)
     * - bounceRate (float)
     * - mobileRate (float)
     * - lastSent (string ISO date)
     */
    public function getModulePerformanceData(string $modKey = '', int $itemId = 0, array $options = []): array;

    /**
     * Returns performance data for a specific audience.
     *
     * @param int  $audienceId
     * @param bool $forceRefresh When true, bypass the cached result count and recompute.
     * Keys:
     * - total (int)
     */
    public function getAudiencePerformanceData(int $audienceId, bool $forceRefresh = false): array;
}
