<?php

declare(strict_types=1);

namespace Australcode\Rewards\Domain\Wallet;

/**
 * Read/write seam for the per-customer "blocked" flag (B6). A blocked customer
 * stops earning automatic order points and stops redeeming; manual admin
 * adjustments still apply (an admin override). Backed by the is_blocked column on
 * wp_acrwd_balances.
 *
 * Deliberately separate from the Balance VO and BalanceRepository: the flag lives
 * on the balances row but is written in isolation (a targeted column update) so
 * the wallet write-path — which upserts only points/lifetime/tier columns — never
 * touches it, and the Balance VO constructor keeps its small, stable signature.
 *
 * CORE (both builds): the flag is only SET by the Pro customer tools, but the
 * read side (is_blocked / blocked_among) feeds the earn and redeem guards, which
 * must run in the free build too.
 */
interface CustomerBlock {

	public function is_blocked( int $user_id ): bool;

	/**
	 * Sets (or clears) the blocked flag. Creates a zero-balance row if the customer
	 * has none yet, so a customer can be blocked before they have earned anything.
	 */
	public function set_blocked( int $user_id, bool $blocked ): void;

	/**
	 * Blocks or unblocks many customers at once. Returns the number processed.
	 *
	 * @param int[] $user_ids
	 */
	public function set_blocked_many( array $user_ids, bool $blocked ): int;

	public function count_blocked(): int;

	/**
	 * Of the given user ids, the subset currently blocked — one query, for tagging
	 * a page of the Customers list without an N+1.
	 *
	 * @param int[] $user_ids
	 * @return int[]
	 */
	public function blocked_among( array $user_ids ): array;
}
