<?php

declare(strict_types=1);

namespace Instinctor\Core\Auth;

/**
 * Authentication driver interface.
 *
 * On WordPress: delegates to WP core functions.
 * On Standalone: own user table, bcrypt, JWT/session tokens.
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Return the current authenticated user object, or null if not logged in.
     * The returned object must expose at minimum: ->ID, ->user_email, ->display_name, ->roles[]
     */
    public function user(): ?object;

    /**
     * Return the current user's ID, or 0 if not logged in.
     */
    public function userId(): int;

    /**
     * Whether the current request has an authenticated user.
     */
    public function check(): bool;

    /**
     * Whether the current user has a given capability/role.
     *
     * @param string $capability  e.g. 'manage_options', 'edit_posts'
     * @param mixed  ...$args     Optional additional arguments (e.g. post ID for edit_post)
     */
    public function can(string $capability, mixed ...$args): bool;

    /**
     * Whether the current user is an admin (has manage_options capability).
     */
    public function isAdmin(): bool;

    /**
     * Attempt to log in with email + password.
     * Returns true on success, false on failure.
     */
    public function login(string $email, string $password, bool $remember = false): bool;

    /**
     * Log out the current user.
     */
    public function logout(): void;
}
