<?php

namespace App\Services\Link;

/**
 * Counter storage behind LinkClickCounterBuffer.
 *
 * Exists so the buffered path is testable. Production uses Redis hashes; tests use
 * an in-memory array, so "counts are buffered, then flushed in one UPDATE" is
 * verified rather than assumed. Implementations throw on failure — the buffer
 * catches and writes through to the database instead.
 */
interface ClickCounterStore
{
    public function increment(string $hash, string $field, int $by = 1): void;

    public function put(string $hash, string $field, string $value): void;

    /**
     * Read and clear in one atomic step, so a click landing mid-flush is counted in
     * this batch or the next, never dropped.
     *
     * @return array<string, string>
     */
    public function drain(string $hash): array;
}