<?php

declare(strict_types=1);

namespace Australcode\Rewards\Domain\Wallet;

defined( 'ABSPATH' ) || exit;

/**
 * Read-side aggregation over the ledger for the Dashboard.
 *
 * Kept separate from BalanceDirectory (which reads the denormalized balances) and
 * TransactionRepository (per-user history) because these are time-windowed
 * GROUP BY rollups the concrete impl runs against wpdb: a per-day net series for
 * the trend sparkline, and the most active customers (top movers). All windows
 * are half-open [$from, $to) on UTC `created_at`, Active entries only.
 */
interface LedgerAnalytics {

	/**
	 * Net points_delta per calendar day (UTC), keyed by 'Y-m-d'. Days with no
	 * activity are omitted — the caller fills the gaps (e.g. for a sparkline).
	 *
	 * @return array<string,int>
	 */
	public function daily_series( string $from, string $to ): array;

	/**
	 * Most active customers in the window by absolute points moved, with their net
	 * delta over the same window. Ordered by volume desc.
	 *
	 * @return list<array{user_id:int,volume:int,net:int}>
	 */
	public function top_movers( string $from, string $to, int $limit ): array;
}
