<?php

declare(strict_types=1);

namespace Australcode\Rewards\Domain\Wallet;

/**
 * Read-model for listing balances across users (admin Customers view).
 *
 * Deliberately separate from BalanceRepository: the repository is a write-path
 * collaborator with many in-memory test fakes, and adding list/count methods
 * there would force every fake to implement them. This interface is the
 * query-side seam instead.
 */
interface BalanceDirectory {

	/**
	 * Balances ordered by points_balance desc (highest first).
	 *
	 * @return Balance[]
	 */
	public function paginate( int $limit, int $offset ): array;

	/**
	 * Balances whose user matches a search term (display name, email, login or a
	 * numeric user id), ordered by points_balance desc.
	 *
	 * @return Balance[]
	 */
	public function search( string $term, int $limit, int $offset ): array;

	public function count(): int;

	/**
	 * Number of balances matching a search term (see search()).
	 */
	public function count_search( string $term ): int;

	/**
	 * Aggregate program totals across all balances.
	 *
	 * @return array{members:int,outstanding:int,lifetime_earned:int,lifetime_redeemed:int}
	 */
	public function totals(): array;
}
