<?php

declare(strict_types=1);

namespace RedMCP;

use Redmine\Client\Client;
use Redmine\Client\NativeCurlClient;
use Redmine\Http\HttpClient;
use Redmine\Http\HttpFactory;
use Redmine\Serializer\PathSerializer;
use RuntimeException;
use SimpleXMLElement;
use Throwable;

final class RedmineClient
{
    private Client $client;

    public function __construct(Client $client)
    {
        $this->client = $client;
    }

    public static function fromCredentials(string $url, string $apiKeyOrUsername, ?string $password = null): self
    {
        return new self(new NativeCurlClient($url, $apiKeyOrUsername, $password));
    }

    /**
     * List Redmine issues.
     *
     * @param array<string,mixed> $params Standard Redmine issue list filters.
     *
     * @return array<string,mixed>
     */
    public function issues(array $params = []): array
    {
        return $this->listIssues($params);
    }

    /**
     * List Redmine issues.
     *
     * @param array<string,mixed> $params Standard Redmine issue list filters.
     *
     * @return array<string,mixed>
     */
    public function listIssues(array $params = []): array
    {
        $response = $this->client->getApi('issue')->list($params);
        if (!is_array($response)) {
            throw new RuntimeException('Could not list issues: ' . $this->stringifyError($response));
        }

        return $response;
    }

    /**
     * Alias for listIssues() that makes Redmine's built-in issue filters
     * explicit at call sites.
     *
     * Useful filters include project_id, tracker_id, status_id,
     * assigned_to_id, author_id, category_id, fixed_version_id, query_id,
     * created_on, updated_on, sort, offset, and limit.
     *
     * @param array<string,mixed> $filters Standard Redmine issue list filters.
     *
     * @return array<string,mixed>
     */
    public function filterIssues(array $filters = []): array
    {
        return $this->listIssues($filters);
    }

    /**
     * Search Redmine using the built-in /search.json endpoint.
     *
     * Typical params include project_id, all_words, titles_only, scope,
     * open_issues, issues, projects, news, documents, changesets, wiki_pages,
     * messages, offset, and limit.
     *
     * @param array<string,mixed> $params Standard Redmine search params.
     *
     * @return array<string,mixed>
     */
    public function search(string $query, array $params = []): array
    {
        $query = trim($query);
        if ($query === '') {
            throw new RuntimeException('Searching Redmine requires a non-empty query.');
        }

        return $this->getJson('/search', ['q' => $query] + $params) ?? [];
    }

    /**
     * Search only issues using Redmine's built-in /search.json endpoint.
     *
     * @param array<string,mixed> $params Additional Redmine search params.
     *
     * @return array<string,mixed>
     */
    public function searchIssues(string $query, array $params = []): array
    {
        return $this->search($query, ['issues' => '1'] + $params);
    }

    /**
     * List Redmine projects.
     *
     * @param array<string,mixed> $params Standard Redmine project list params.
     *
     * @return array<string,mixed>
     */
    public function projects(array $params = []): array
    {
        return $this->listProjects($params);
    }

    /**
     * List Redmine projects.
     *
     * @param array<string,mixed> $params Standard Redmine project list params.
     *
     * @return array<string,mixed>
     */
    public function listProjects(array $params = []): array
    {
        return $this->getJson('/projects', $params) ?? [];
    }

    /**
     * Fetch a Redmine project by numeric id or identifier.
     *
     * @param array<string,mixed> $params Standard Redmine project show params.
     *
     * @return array<string,mixed>
     */
    public function project(int|string $projectId, array $params = []): array
    {
        $projectId = trim((string) $projectId);
        if ($projectId === '') {
            throw new RuntimeException('Fetching a project requires a project id or identifier.');
        }

        $response = $this->getJson('/projects/' . rawurlencode($projectId), $params);
        if (!is_array($response)) {
            throw new RuntimeException('Could not fetch project ' . $projectId . '.');
        }

        return $response['project'] ?? $response;
    }

    /**
     * List Redmine users.
     *
     * @param array<string,mixed> $params Standard Redmine user list params.
     *
     * @return array<string,mixed>
     */
    public function users(array $params = []): array
    {
        return $this->listUsers($params);
    }

    /**
     * List Redmine users.
     *
     * @param array<string,mixed> $params Standard Redmine user list params.
     *
     * @return array<string,mixed>
     */
    public function listUsers(array $params = []): array
    {
        return $this->getJson('/users', $params) ?? [];
    }

    /**
     * Fetch one Redmine user.
     *
     * @param array<string,mixed> $params Standard Redmine user show params.
     *
     * @return array<string,mixed>
     */
    public function user(int $userId, array $params = []): array
    {
        if ($userId <= 0) {
            throw new RuntimeException('Fetching a user requires a positive user id.');
        }

        $response = $this->getJson('/users/' . rawurlencode((string) $userId), $params);
        if (!is_array($response)) {
            throw new RuntimeException('Could not fetch user #' . $userId . '.');
        }

        return $response['user'] ?? $response;
    }

    /**
     * List memberships for a Redmine project.
     *
     * @param array<string,mixed> $params Standard Redmine membership list params.
     *
     * @return array<string,mixed>
     */
    public function projectMemberships(int|string $projectId, array $params = []): array
    {
        $projectId = trim((string) $projectId);
        if ($projectId === '') {
            throw new RuntimeException('Fetching project memberships requires a project id or identifier.');
        }

        return $this->getJson('/projects/' . rawurlencode($projectId) . '/memberships', $params) ?? [];
    }

    /**
     * Fetch a normal Redmine issue.
     *
     * @param array<int,string> $issueIncludes Standard Redmine issue includes:
     *                                         journals, attachments, children,
     *                                         relations, changesets.
     *
     * @return array<string,mixed>
     */
    public function issue(int $issueId, array $issueIncludes = ['journals', 'attachments']): array
    {
        $issueResponse = $this->client->getApi('issue')->show($issueId, ['include' => $issueIncludes]);
        if (!is_array($issueResponse)) {
            throw new RuntimeException('Could not fetch issue #' . $issueId . ': ' . $this->stringifyError($issueResponse));
        }

        return $issueResponse['issue'] ?? $issueResponse;
    }

    /**
     * Create a Redmine issue.
     *
     * Typical fields include project_id, subject, description, tracker_id,
     * status_id, priority_id, assigned_to_id, category_id, parent_issue_id,
     * parent_id, uploads, due_date, and start_date.
     *
     * @param array<string,mixed> $fields
     *
     * @return array<string,mixed>
     */
    public function createIssue(array $fields): array
    {
        if (!isset($fields['project_id']) || !isset($fields['subject'])) {
            throw new RuntimeException('Creating an issue requires at least project_id and subject.');
        }

        $response = $this->postJson('/issues', ['issue' => $fields]);

        return is_array($response['issue'] ?? null) ? $response['issue'] : $response;
    }

    /**
     * Update a Redmine issue.
     *
     * By default this uses the normal Redmine issue REST API and does not send
     * a Helpdesk email. To send a customer-visible Helpdesk response, pass
     * ['send_helpdesk_email' => true] with a notes field, or call
     * sendHelpdeskIssueResponse() directly.
     *
     * Typical fields include notes, subject, status_id, priority_id,
     * assigned_to_id, private_notes, parent_issue_id, parent_id, category_id,
     * uploads, due_date, and tracker_id.
     *
     * @param array<string,mixed> $fields
     */
    public function updateIssue(int $issueId, array $fields, array $options = []): bool
    {
        if ($fields === []) {
            throw new RuntimeException('Updating an issue requires at least one field.');
        }

        if (!empty($options['send_helpdesk_email'])) {
            if (!isset($fields['notes']) || trim((string) $fields['notes']) === '') {
                throw new RuntimeException('Sending a Helpdesk email requires a non-empty notes field.');
            }
            if (!empty($fields['private_notes'])) {
                throw new RuntimeException('A private note cannot be sent as a Helpdesk email.');
            }

            $issueFields = $fields;
            unset($issueFields['notes'], $issueFields['private_notes']);
            if ($issueFields !== []) {
                $this->updateIssue($issueId, $issueFields);
            }

            $this->sendHelpdeskIssueResponse($issueId, (string) $fields['notes'], $options);

            return true;
        }

        $this->putJson('/issues/' . rawurlencode((string) $issueId), ['issue' => $fields]);

        return true;
    }

    /**
     * @return array<string,mixed>
     */
    public function issueWithStructure(int $issueId): array
    {
        return $this->issue($issueId, ['journals', 'attachments', 'children', 'relations']);
    }

    /**
     * @return array<string,mixed>
     */
    public function listIssueChildren(int $issueId, array $params = []): array
    {
        return $this->listIssues(['parent_id' => $issueId] + $params);
    }

    public function setIssueParent(int $issueId, int $parentIssueId): bool
    {
        if ($parentIssueId <= 0) {
            throw new RuntimeException('Setting an issue parent requires a positive parent_issue_id.');
        }

        return $this->updateIssue($issueId, ['parent_issue_id' => $parentIssueId]);
    }

    public function clearIssueParent(int $issueId): bool
    {
        return $this->updateIssue($issueId, ['parent_issue_id' => null]);
    }

    /**
     * @return array<string,mixed>
     */
    public function listIssueRelations(int $issueId): array
    {
        return $this->getJson('/issues/' . rawurlencode((string) $issueId) . '/relations') ?? [];
    }

    /**
     * @return array<string,mixed>
     */
    public function issueRelation(int $relationId): array
    {
        if ($relationId <= 0) {
            throw new RuntimeException('Fetching an issue relation requires a positive relation id.');
        }

        $response = $this->getJson('/relations/' . rawurlencode((string) $relationId));
        if (!is_array($response)) {
            throw new RuntimeException('Could not fetch issue relation #' . $relationId . '.');
        }

        return $response['relation'] ?? $response;
    }

    /**
     * @param array<string,mixed> $fields
     *
     * @return array<string,mixed>
     */
    public function createIssueRelation(int $issueId, array $fields): array
    {
        if (!isset($fields['issue_to_id']) || (int) $fields['issue_to_id'] <= 0) {
            throw new RuntimeException('Creating an issue relation requires a positive issue_to_id.');
        }

        $fields += ['relation_type' => 'relates'];
        $response = $this->postJson('/issues/' . rawurlencode((string) $issueId) . '/relations', ['relation' => $fields]);

        return is_array($response['relation'] ?? null) ? $response['relation'] : $response;
    }

    public function removeIssueRelation(int $relationId): bool
    {
        if ($relationId <= 0) {
            throw new RuntimeException('Removing an issue relation requires a positive relation id.');
        }

        $this->deleteJson('/relations/' . rawurlencode((string) $relationId));

        return true;
    }

    /**
     * @return array<string,mixed>
     */
    public function listProjectIssueCategories(int|string $projectId): array
    {
        $projectId = trim((string) $projectId);
        if ($projectId === '') {
            throw new RuntimeException('Listing issue categories requires a project id or identifier.');
        }

        return $this->getJson('/projects/' . rawurlencode($projectId) . '/issue_categories') ?? [];
    }

    /**
     * @return array<string,mixed>
     */
    public function issueCategory(int $categoryId): array
    {
        if ($categoryId <= 0) {
            throw new RuntimeException('Fetching an issue category requires a positive category id.');
        }

        $response = $this->getJson('/issue_categories/' . rawurlencode((string) $categoryId));
        if (!is_array($response)) {
            throw new RuntimeException('Could not fetch issue category #' . $categoryId . '.');
        }

        return $response['issue_category'] ?? $response;
    }

    /**
     * @param array<string,mixed> $fields
     *
     * @return array<string,mixed>
     */
    public function createIssueCategory(int|string $projectId, array $fields): array
    {
        $projectId = trim((string) $projectId);
        if ($projectId === '') {
            throw new RuntimeException('Creating an issue category requires a project id or identifier.');
        }
        if (!isset($fields['name']) || trim((string) $fields['name']) === '') {
            throw new RuntimeException('Creating an issue category requires a non-empty name.');
        }

        $response = $this->postJson('/projects/' . rawurlencode($projectId) . '/issue_categories', ['issue_category' => $fields]);

        return is_array($response['issue_category'] ?? null) ? $response['issue_category'] : $response;
    }

    /**
     * @param array<string,mixed> $fields
     *
     * @return array<string,mixed>
     */
    public function updateIssueCategory(int $categoryId, array $fields): array
    {
        if ($fields === []) {
            throw new RuntimeException('Updating an issue category requires at least one field.');
        }

        $response = $this->putJson('/issue_categories/' . rawurlencode((string) $categoryId), ['issue_category' => $fields]);

        return is_array($response['issue_category'] ?? null) ? $response['issue_category'] : $response;
    }

    /**
     * @return array<string,mixed>
     */
    public function attachment(int $attachmentId): array
    {
        if ($attachmentId <= 0) {
            throw new RuntimeException('Fetching an attachment requires a positive attachment id.');
        }

        $response = $this->getJson('/attachments/' . rawurlencode((string) $attachmentId));
        if (!is_array($response)) {
            throw new RuntimeException('Could not fetch attachment #' . $attachmentId . '.');
        }

        return $response['attachment'] ?? $response;
    }

    /**
     * @param array<string,mixed> $source
     *
     * @return array<string,mixed>
     */
    public function uploadAttachment(array $source): array
    {
        $source = $this->normalizeAttachmentUploadSource($source);
        $filename = isset($source['filename']) ? trim((string) $source['filename']) : '';
        $contentType = trim((string) ($source['content_type'] ?? 'application/octet-stream'));
        if ($contentType === '') {
            $contentType = 'application/octet-stream';
        }

        if (isset($source['path'])) {
            $path = (string) $source['path'];
            if (!is_file($path) || !is_readable($path)) {
                throw new RuntimeException('Uploading an attachment from path requires a readable local file.');
            }
            $bytes = file_get_contents($path);
            if ($bytes === false) {
                throw new RuntimeException('Could not read attachment file: ' . $path);
            }
            if ($filename === '') {
                $filename = basename($path);
            }
        } elseif (isset($source['base64_content'])) {
            if ($filename === '') {
                throw new RuntimeException('Uploading base64 attachment content requires filename.');
            }
            $decoded = base64_decode((string) $source['base64_content'], true);
            if ($decoded === false) {
                throw new RuntimeException('Attachment base64_content is not valid base64.');
            }
            $bytes = $decoded;
        } else {
            throw new RuntimeException('Uploading an attachment requires either path or base64_content.');
        }

        if ($filename === '') {
            throw new RuntimeException('Uploading an attachment requires filename.');
        }

        $response = $this->rawRequest(
            'POST',
            PathSerializer::create('/uploads.json', ['filename' => $filename])->getPath(),
            'application/octet-stream',
            $bytes
        );
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Redmine upload failed with HTTP ' . $status . ': ' . $response->getContent());
        }

        $decoded = $this->decodeJsonResponse($response, 'Redmine upload');
        $upload = is_array($decoded['upload'] ?? null) ? $decoded['upload'] : $decoded;
        if (isset($source['description'])) {
            $upload['description'] = (string) $source['description'];
        }
        $upload += [
            'filename' => $filename,
            'content_type' => $contentType,
        ];

        return $upload;
    }

    /**
     * @param array<string,mixed> $source
     *
     * @return array<string,mixed>
     */
    private function normalizeAttachmentUploadSource(array $source): array
    {
        if (isset($source['file']) && is_array($source['file'])) {
            $file = $source['file'];
            unset($source['file']);
            foreach ([
                'path' => 'path',
                'filename' => 'filename',
                'name' => 'filename',
                'content_type' => 'content_type',
                'mime_type' => 'content_type',
                'mimeType' => 'content_type',
                'media_type' => 'content_type',
                'description' => 'description',
                'base64_content' => 'base64_content',
                'base64' => 'base64_content',
                'data' => 'base64_content',
                'blob' => 'base64_content',
                'data_url' => 'data_url',
                'url' => 'data_url',
            ] as $from => $to) {
                if (!isset($source[$to]) && isset($file[$from])) {
                    $source[$to] = $file[$from];
                }
            }
        }

        foreach ([
            'name' => 'filename',
            'mime_type' => 'content_type',
            'mimeType' => 'content_type',
            'media_type' => 'content_type',
            'base64' => 'base64_content',
            'data' => 'base64_content',
            'blob' => 'base64_content',
        ] as $from => $to) {
            if (!isset($source[$to]) && isset($source[$from])) {
                $source[$to] = $source[$from];
            }
        }

        if (isset($source['data_url']) || (isset($source['base64_content']) && str_starts_with((string) $source['base64_content'], 'data:'))) {
            $dataUrl = (string) ($source['data_url'] ?? $source['base64_content']);
            $parsed = $this->parseAttachmentDataUrl($dataUrl);
            $source['base64_content'] = $parsed['base64_content'];
            if (!isset($source['content_type'])) {
                $source['content_type'] = $parsed['content_type'];
            }
            if (!isset($source['filename']) || trim((string) $source['filename']) === '') {
                $source['filename'] = $this->defaultAttachmentFilename((string) $source['content_type']);
            }
        }

        return $source;
    }

    /**
     * @return array{content_type:string,base64_content:string}
     */
    private function parseAttachmentDataUrl(string $dataUrl): array
    {
        if (!preg_match('/^data:([^;,]+)?(?:;[^,]*)?;base64,(.*)$/s', $dataUrl, $matches)) {
            throw new RuntimeException('Attachment data_url must be a base64 data URL.');
        }

        $contentType = trim($matches[1] !== '' ? $matches[1] : 'application/octet-stream');

        return [
            'content_type' => $contentType !== '' ? $contentType : 'application/octet-stream',
            'base64_content' => $matches[2],
        ];
    }

    private function defaultAttachmentFilename(string $contentType): string
    {
        return match (strtolower($contentType)) {
            'application/pdf' => 'attachment.pdf',
            'text/plain' => 'attachment.txt',
            'text/csv' => 'attachment.csv',
            'application/json' => 'attachment.json',
            'image/jpeg' => 'attachment.jpg',
            'image/png' => 'attachment.png',
            'image/gif' => 'attachment.gif',
            default => 'attachment.bin',
        };
    }

    /**
     * @return array<string,mixed>
     */
    public function updateAttachment(int $attachmentId, array $fields): array
    {
        if ($fields === []) {
            throw new RuntimeException('Updating an attachment requires at least one field.');
        }

        $response = $this->putJson('/attachments/' . rawurlencode((string) $attachmentId), ['attachment' => $fields]);

        return is_array($response['attachment'] ?? null) ? $response['attachment'] : $response;
    }

    /**
     * @return array<string,mixed>
     */
    public function downloadAttachment(int $attachmentId, string $destinationPath, bool $includeBase64 = false, int $maxBase64Bytes = 262144): array
    {
        $destinationPath = $this->safeDownloadPath($destinationPath);
        $response = $this->rawRequest('GET', '/attachments/download/' . rawurlencode((string) $attachmentId));
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Redmine attachment download failed with HTTP ' . $status . ': ' . $response->getContent());
        }

        $bytes = $response->getContent();
        if (file_put_contents($destinationPath, $bytes) === false) {
            throw new RuntimeException('Could not write attachment download to ' . $destinationPath . '.');
        }

        $result = [
            'attachment_id' => $attachmentId,
            'path' => $destinationPath,
            'bytes' => strlen($bytes),
            'content_type' => $response->getContentType(),
        ];
        if ($includeBase64 && strlen($bytes) <= $maxBase64Bytes) {
            $result['base64_content'] = base64_encode($bytes);
        } elseif ($includeBase64) {
            $result['base64_omitted'] = true;
            $result['base64_limit_bytes'] = $maxBase64Bytes;
        }

        return $result;
    }

    /**
     * Send a Helpdesk email response for an existing Helpdesk-backed issue.
     *
     * This uses the RedmineUP Helpdesk API endpoint that corresponds to sending
     * a note with the Helpdesk UI's "Send note" checkbox enabled.
     *
     * @param array<string,mixed> $options Optional to_address, cc_address,
     *                                     bcc_address, and status_id fields.
     *
     * @return array<string,mixed>
     */
    public function sendHelpdeskIssueResponse(int $issueId, string $content, array $options = []): array
    {
        if (trim($content) === '') {
            throw new RuntimeException('Sending a Helpdesk response requires non-empty content.');
        }

        $message = [
            'issue_id' => $issueId,
            'content' => $content,
        ];
        if (isset($options['status_id'])) {
            $message['status_id'] = $options['status_id'];
        }

        $payload = ['message' => $message];
        foreach (['to_address', 'cc_address', 'bcc_address'] as $key) {
            if (isset($options[$key])) {
                $payload[$key] = $options[$key];
            }
        }

        $response = $this->postJson('/helpdesk/email_note', $payload);
        if (!isset($response['message']) || !is_array($response['message'])) {
            throw new RuntimeException('Helpdesk email response returned unexpected JSON.');
        }

        return $response['message'];
    }

    /**
     * Delete a Redmine issue.
     */
    public function deleteIssue(int $issueId): bool
    {
        $issueApi = $this->client->getApi('issue');
        $issueApi->remove($issueId);
        $this->assertLastApiResponseSucceeded($issueApi, 'delete issue #' . $issueId);

        return true;
    }

    /**
     * Alias for deleteIssue().
     */
    public function removeIssue(int $issueId): bool
    {
        return $this->deleteIssue($issueId);
    }

    /**
     * @param array<int,string> $issueIncludes Standard Redmine issue includes.
     *
     * @return array<string,mixed>
     */
    public function issueWithHelpdesk(int $issueId, int $messageLimit = 100, array $issueIncludes = ['journals', 'attachments']): array
    {
        return $this->getIssueWithHelpdeskContext($issueId, $messageLimit, $issueIncludes);
    }

    /**
     * @param array<int,string> $issueIncludes Standard Redmine issue includes.
     *
     * @return array<string,mixed>
     */
    public function getIssueWithHelpdeskContext(
        int $issueId,
        int $messageLimit = 100,
        array $issueIncludes = ['journals', 'attachments']
    ): array
    {
        $issue = $this->issue($issueId, $issueIncludes);

        $ticket = $this->helpdeskTicketByIssue($issueId);
        $messages = $this->helpdeskMessagesByIssue($issueId, $messageLimit);

        return [
            'issue' => $issue,
            'helpdesk' => [
                'available' => $ticket !== null || $messages !== [],
                'ticket' => $ticket,
                'journal_messages' => $messages,
            ],
            'meta' => [
                'issue_id' => $issueId,
                'issue_includes' => array_values($issueIncludes),
                'helpdesk_sources' => [
                    'ticket' => '/helpdesk_search/issues/' . $issueId . '/ticket',
                    'messages' => '/helpdesk_search/issues/' . $issueId . '/messages',
                ],
            ],
        ];
    }

    /**
     * @return array<string,mixed>|null
     */
    public function helpdeskTicketByIssue(int $issueId): ?array
    {
        return $this->getHelpdeskTicketByIssue($issueId);
    }

    /**
     * @return array<string,mixed>|null
     */
    public function getHelpdeskTicketByIssue(int $issueId): ?array
    {
        $response = $this->getJson('/helpdesk_search/issues/' . rawurlencode((string) $issueId) . '/ticket', [], [403, 404]);
        if (!is_array($response) || !isset($response['helpdesk_ticket']) || !is_array($response['helpdesk_ticket'])) {
            return null;
        }

        return $response['helpdesk_ticket'];
    }

    /**
     * @return array<int,mixed>
     */
    public function helpdeskMessagesByIssue(int $issueId, int $limit = 100): array
    {
        return $this->getHelpdeskMessagesByIssue($issueId, $limit);
    }

    /**
     * @return array<int,mixed>
     */
    public function getHelpdeskMessagesByIssue(int $issueId, int $limit = 100): array
    {
        $response = $this->getJson(
            '/helpdesk_search/issues/' . rawurlencode((string) $issueId) . '/messages',
            ['limit' => max(1, min($limit, 200))],
            [403, 404]
        );
        if (!is_array($response) || !isset($response['journal_messages']) || !is_array($response['journal_messages'])) {
            return [];
        }

        return $response['journal_messages'];
    }

    /**
     * @param array<string,mixed> $params
     *
     * @return array<string,mixed>|null
     */
    private function getJson(string $path, array $params = [], array $nullStatuses = []): ?array
    {
        if (!$this->client instanceof HttpClient) {
            throw new RuntimeException('Configured Redmine client cannot issue raw HTTP requests.');
        }

        $requestPath = $this->buildPath($path, $params);
        $response = $this->client->request(HttpFactory::makeJsonRequest('GET', $requestPath));
        $status = $response->getStatusCode();

        if (in_array($status, $nullStatuses, true)) {
            return null;
        }
        if ($status >= 400) {
            throw new RuntimeException('Redmine GET ' . $requestPath . ' failed with HTTP ' . $status . ': ' . $response->getContent());
        }

        $body = $response->getContent();
        if ($body === '') {
            return [];
        }

        try {
            $decoded = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
        } catch (Throwable $exception) {
            throw new RuntimeException('Redmine GET ' . $requestPath . ' returned invalid JSON.', 0, $exception);
        }

        if (!is_array($decoded)) {
            throw new RuntimeException('Redmine GET ' . $requestPath . ' returned invalid JSON.');
        }

        return $decoded;
    }

    /**
     * @param array<string,mixed> $payload
     *
     * @return array<string,mixed>
     */
    private function postJson(string $path, array $payload): array
    {
        $requestPath = $this->buildPath($path, []);
        $encoded = json_encode($payload);
        if ($encoded === false) {
            throw new RuntimeException('Could not encode Redmine POST payload.');
        }

        $response = $this->rawRequest('POST', $requestPath, 'application/json', $encoded);
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Redmine POST ' . $requestPath . ' failed with HTTP ' . $status . ': ' . $response->getContent());
        }

        return $this->decodeJsonResponse($response, 'Redmine POST ' . $requestPath);
    }

    /**
     * @param array<string,mixed> $payload
     *
     * @return array<string,mixed>
     */
    private function putJson(string $path, array $payload): array
    {
        $requestPath = $this->buildPath($path, []);
        $encoded = json_encode($payload);
        if ($encoded === false) {
            throw new RuntimeException('Could not encode Redmine PUT payload.');
        }

        $response = $this->rawRequest('PUT', $requestPath, 'application/json', $encoded);
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Redmine PUT ' . $requestPath . ' failed with HTTP ' . $status . ': ' . $response->getContent());
        }

        return $this->decodeJsonResponse($response, 'Redmine PUT ' . $requestPath);
    }

    private function deleteJson(string $path): void
    {
        $requestPath = $this->buildPath($path, []);
        $response = $this->rawRequest('DELETE', $requestPath);
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Redmine DELETE ' . $requestPath . ' failed with HTTP ' . $status . ': ' . $response->getContent());
        }
    }

    private function rawRequest(string $method, string $path, string $contentType = '', string $content = ''): \Redmine\Http\Response
    {
        if (!$this->client instanceof HttpClient) {
            throw new RuntimeException('Configured Redmine client cannot issue raw HTTP requests.');
        }

        return $this->client->request(HttpFactory::makeRequest($method, $path, $contentType, $content));
    }

    /**
     * @return array<string,mixed>
     */
    private function decodeJsonResponse(\Redmine\Http\Response $response, string $action): array
    {
        $body = $response->getContent();
        if ($body === '') {
            return [];
        }

        try {
            $decoded = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
        } catch (Throwable $exception) {
            throw new RuntimeException($action . ' returned invalid JSON.', 0, $exception);
        }

        if (!is_array($decoded)) {
            throw new RuntimeException($action . ' returned invalid JSON.');
        }

        return $decoded;
    }

    /**
     * @param array<string,mixed> $params
     */
    private function buildPath(string $path, array $params): string
    {
        return PathSerializer::create($path . '.json', $params)->getPath();
    }

    private function safeDownloadPath(string $path): string
    {
        $path = trim($path);
        if ($path === '' || str_contains($path, "\0")) {
            throw new RuntimeException('Attachment download requires a safe local destination path.');
        }

        $directory = dirname($path);
        $realDirectory = realpath($directory);
        if ($realDirectory === false || !is_dir($realDirectory)) {
            throw new RuntimeException('Attachment download destination directory does not exist: ' . $directory);
        }

        $resolved = $realDirectory . DIRECTORY_SEPARATOR . basename($path);
        $repoRoot = realpath(dirname(__DIR__, 2));
        $tmpRoot = realpath(sys_get_temp_dir());
        foreach (array_filter([$repoRoot, $tmpRoot]) as $allowedRoot) {
            if ($resolved === $allowedRoot || str_starts_with($resolved, $allowedRoot . DIRECTORY_SEPARATOR)) {
                return $resolved;
            }
        }

        throw new RuntimeException('Attachment downloads must write under /tmp or the repository tree.');
    }

    /**
     * @param mixed $api
     */
    private function assertLastApiResponseSucceeded($api, string $action): void
    {
        if (!method_exists($api, 'getLastResponse')) {
            return;
        }

        $response = $api->getLastResponse();
        $status = $response->getStatusCode();
        if ($status >= 400) {
            throw new RuntimeException('Could not ' . $action . ': HTTP ' . $status . ': ' . $response->getContent());
        }
    }

    /**
     * @param mixed $response
     *
     * @return array<string,mixed>
     */
    private function xmlResponseToArray($response): array
    {
        if ($response instanceof SimpleXMLElement) {
            $encoded = json_encode($response);
            if ($encoded === false) {
                throw new RuntimeException('Could not encode Redmine XML response.');
            }

            $decoded = json_decode($encoded, true);
            if (is_array($decoded)) {
                return $decoded;
            }
        }

        if ($response === '') {
            return [];
        }

        throw new RuntimeException('Unexpected Redmine response: ' . $this->stringifyError($response));
    }

    /**
     * @param mixed $value
     */
    private function stringifyError($value): string
    {
        if ($value === false) {
            return 'empty response';
        }
        if (is_scalar($value)) {
            return (string) $value;
        }

        return 'unexpected response';
    }
}