<?php

declare(strict_types=1);

namespace Australcode\Rewards\Domain\Wallet;

/**
 * Query-side seam for the points-expiry sweep. Separate from TransactionRepository
 * (whose many in-memory fakes shouldn't grow these methods); the concrete impl
 * talks to wpdb directly.
 */
interface ExpiryGateway {

	/**
	 * Active Earn entries whose expires_at is at or before $now, oldest first.
	 *
	 * @return Transaction[]
	 */
	public function due( string $now ): array;

	/**
	 * Active Earn entries expiring within the half-open window [$from, $to),
	 * soonest first — the "expiring soon" Dashboard panel (Pro). Limited to $limit.
	 *
	 * @return Transaction[]
	 */
	public function upcoming( string $from, string $to, int $limit ): array;

	/**
	 * Marks the given entry ids as Expired (append-only; the balance is debited
	 * separately with a compensating Expire entry).
	 *
	 * @param int[] $ids
	 */
	public function mark_expired( array $ids ): void;
}
