<?php

declare(strict_types=1);

namespace Numinix\SeekmodoSdk\Storage;

/**
 * Lightweight cache contract used by the SDK's tenant-snapshot poller
 * ({@see \Numinix\SeekmodoSdk\TenantSnapshot}) and the
 * {@see \Numinix\SeekmodoSdk\SignatureMismatchTracker}.
 *
 * Deliberately NOT PSR-16 — we don't want the SDK to pull in
 * `psr/simple-cache` just to bridge to a fundamentally identical
 * interface. Adapters are trivial:
 *
 *   - In-memory: {@see InMemoryCache} (default; for tests + CLI).
 *   - APCu:      {@see ApcuCache} (cPanel / single-host deployments).
 *   - WordPress: wrap `get_transient` / `set_transient`.
 *   - Laravel:   wrap the `\Illuminate\Contracts\Cache\Repository`.
 *
 * Two semantic constraints connectors should honour:
 *
 *   1. `set()` MUST accept any JSON-serializable PHP value — arrays,
 *      scalars, null. No object identity is required across get/set.
 *   2. `get()` MUST return `$default` when the key is missing OR the
 *      value has expired. Adapters that only support second-precision
 *      TTLs (e.g. WP transients) should round up.
 */
interface CacheInterface
{
    /**
     * @param mixed $default
     * @return mixed
     */
    public function get(string $key, $default = null);

    /**
     * @param mixed $value
     */
    public function set(string $key, $value, int $ttlSeconds): void;

    public function delete(string $key): void;
}
