WP-LIT-MCP/src/Integrations/Media/MediaGetAbility.php

<?php

declare(strict_types=1);

namespace LIT\MCP\Integrations\Media;

use LIT\MCP\Abilities\Ability;
use WP_Error;

final class MediaGetAbility implements Ability
{
    public function __construct(private MediaPresenter $presenter, private MediaUsageFinder $finder)
    {
    }

    public function name(): string
    {
        return 'lit/media-get';
    }

    public function label(): string
    {
        return 'Medium ansehen';
    }

    public function description(): string
    {
        return 'Liefert Metadaten eines Mediums: Datei, Maße, Größe, alle Bildgrößen mit URL, Alt-Text, '
            . 'Bildunterschrift, Beschreibung und die Verwendungsorte (Beitragsbild, Inhalte inkl. Divi, '
            . 'Bildfelder, Website-Icon, Logo). certainty "sicher" = per ID eingebunden, "möglicherweise" = nur '
            . 'die Datei-URL gefunden. Einträge ohne Leserecht erscheinen als "(nicht lesbar)". '
            . 'Vorschaubild über lit-media-preview.';
    }

    public function inputSchema(): array
    {
        return [
            'type' => 'object',
            'properties' => ['id' => ['type' => 'integer', 'minimum' => 1]],
            'required' => ['id'],
            'additionalProperties' => false,
        ];
    }

    public function outputSchema(): ?array
    {
        return MediaPresenter::fullSchema();
    }

    public function annotations(): array
    {
        return ['readonly' => true, 'destructive' => false, 'idempotent' => true];
    }

    public function isDirect(): bool
    {
        return false;
    }

    public function permission(array $input): bool|WP_Error
    {
        $attachment = MediaGuard::attachment($input['id'] ?? null, 'edit_post', true);

        return $attachment instanceof WP_Error ? $attachment : true;
    }

    public function execute(array $input): mixed
    {
        $attachment = MediaGuard::attachment($input['id'] ?? null, 'edit_post', true);
        if ($attachment instanceof WP_Error) {
            return $attachment;
        }

        return $this->presenter->full($attachment, $this->finder->usages((int) $attachment->ID));
    }
}