<?php
// If this file is called directly, abort.
if ( ! defined( 'WPINC' ) ) {
    die;
}

/**
 * Contract for a repository host adapter (GitHub, Gitea, ...).
 *
 * @since 1.1.0
 */
interface Repository_Provider {
    public function get_id(): string;

    public function get_label(): string;

    /**
     * Normalized repo metadata. Returns null on any failure.
     *
     * Shape:
     *   [
     *     'owner' => [ 'avatar_url' => string, 'login' => string, 'html_url' => string ],
     *     'updated_at'         => string (ISO 8601),
     *     'language'           => string,
     *     'license'            => [ 'name' => string ],
     *     'stargazers_count'   => int,
     *     'forks_count'        => int,
     *     'open_issues_count'  => int,
     *   ]
     */
    public function get_repo_data(): ?array;

    /** Direct URL to the latest release zip asset, or null. */
    public function get_release_url(): ?string;

    /** Tag name of the latest release, or 'Unknown'. */
    public function get_latest_version(): string;

    /** Public URL of the repo, for the 'View Repo' button. */
    public function get_repo_browse_url(): string;

    /**
     * Owner profile data: [ 'avatar_url', 'login', 'html_url' ].
     * Returns null on failure.
     */
    public function get_owner_data( string $owner_login ): ?array;
}