<?php

namespace App\Domain\Manga\Domain\Contract\Client;

use App\Domain\Manga\Domain\Exception\MangadexAuthenticationException;

interface MangadexClientInterface
{
    /**
     * @throws \App\Domain\Manga\Domain\Exception\MangadexAuthenticationException
     */
    public function authenticate(): void;

    /**
     * @throws \App\Domain\Manga\Domain\Exception\MangadexAuthenticationException
     */
    public function refreshToken(): void;

    /**
     * @return array{
     *     result: string,
     *     data: array<array{
     *         id: string,
     *         attributes: array{
     *             title: array<string, string>,
     *             description: array<string, string>,
     *             year: ?int,
     *             status: string,
     *             tags: array<array{attributes: array{name: array<string, string>}}>
     *         },
     *         relationships: array<array{
     *             type: string,
     *             attributes: array{name: string|null, fileName: string|null}
     *         }>
     *     }>
     * }
     */
    public function searchManga(string $title): array;

    /**
     * @param string[] $mangaIds
     * @return array{
     *     statistics: array<string, array{
     *         rating: array{average: float}
     *     }>
     * }
     */
    public function getMangaRatings(array $mangaIds): array;

    /**
     * @return array{
     *     data: array<array{
     *         id: string,
     *         attributes: array{
     *             chapter: string,
     *             title: ?string,
     *             volume: ?string
     *         }
     *     }>,
     *     total: int
     * }
     */
    public function getMangaFeed(string $mangaId, int $offset = 0, int $limit = 500, string $order = 'asc'): array;

    /**
     * @return array{
     *     result: string,
     *     volumes: array<string, array{
     *         volume: string,
     *         chapters: array<string, array{chapter: string}>
     *     }>
     * }
     */
    public function getMangaAggregate(string $mangaId): array;

    /**
     * @return array{
     *     result: string,
     *     data: array{
     *         id: string,
     *         attributes: array{
     *             title: array<string, string>,
     *             description: array<string, string>,
     *             year: ?int,
     *             status: string,
     *             tags: array<array{attributes: array{name: array<string, string>}}>
     *         },
     *         relationships: array<array{
     *             type: string,
     *             attributes: array{name: string|null, fileName: string|null}
     *         }>
     *     }
     * }
     */
    public function getManga(string $mangaId): array;

    /**
     * @return array{
     *     data: array<array{
     *         id: string,
     *         attributes: array{
     *             title: array<string, string>,
     *             description: array<string, string>,
     *             year: ?int,
     *             status: string,
     *             tags: array<array{attributes: array{name: array<string, string>}}>
     *         },
     *         relationships: array<array{
     *             type: string,
     *             attributes: array{name: string|null, fileName: string|null}
     *         }>
     *     }>
     * }
     */
    public function getMangaRecommendations(string $mangaId): array;
}
