<?php

namespace App\FiveM\Contracts;

use App\FiveM\DTOs\CharacterData;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Collection;

/**
 * A single seam between this app's controllers and whichever FiveM
 * framework (QBCore, Qbox, ESX) the connected server actually runs. Swap
 * `config('fivem.framework')` and every Player/Admin controller keeps
 * working unchanged, because they only ever talk to this interface.
 */
interface FrameworkAdapter
{
    public function findByCitizenId(string $citizenId): ?CharacterData;

    public function findByLicense(string $license): ?CharacterData;

    /** @return Collection<int, CharacterData> */
    public function findAllByLicense(string $license): Collection;

    public function paginateCharacters(int $perPage = 25, ?string $search = null): LengthAwarePaginator;

    /** @return Collection<int, array{id: int|string, model: string, plate: string, garage: ?string}> */
    public function vehiclesForCitizen(string $citizenId): Collection;

    /** @return Collection<int, array{id: int|string, label: string, garage: ?string}> */
    public function housesForCitizen(string $citizenId): Collection;

    /** @return Collection<string, array{label: string, grades: array}> */
    public function allJobs(): Collection;

    /** @return Collection<string, array{label: string, grades: array}> */
    public function allGangs(): Collection;

    /**
     * Ranks characters by a money account for the "Leaderboard" page.
     * $account must be one of 'cash' | 'bank' | 'crypto' (adapters reject
     * anything else, since the value is interpolated into a raw SQL
     * JSON-path expression for the QBCore/Qbox implementation).
     *
     * @return Collection<int, CharacterData>
     */
    public function topByMoney(string $account = 'bank', int $limit = 20): Collection;

    /**
     * Adjust a character's money account (cash/bank/crypto). Must be
     * executed inside a DB transaction with a row lock by the caller
     * (see App\Services\EconomyService) — the adapter itself only knows
     * how to translate the operation into the framework's column/JSON shape.
     */
    public function adjustMoney(string $citizenId, string $account, int $delta): void;

    /** @return LengthAwarePaginator<int, array{id: int|string, citizen_id: string, model: string, plate: string, garage: ?string}> */
    public function paginateVehicles(int $perPage = 25, ?string $search = null): LengthAwarePaginator;

    /** Used by Admin\VehicleManagerController — removes an owned vehicle record. */
    public function deleteVehicle(int|string $vehicleId): void;

    /** Used by Admin\ItemManagerController — grants an inventory item to a character. */
    public function giveItem(string $citizenId, string $itemName, int $amount): void;
}
