<?php
/**
 * Read and write helpers for WordPress posts.
 *
 * @package Postlinkly
 * @since   1.0.0
 */

declare(strict_types=1);

namespace Postlinkly\Post;

/**
 * Read and write helpers for WordPress posts.
 *
 * Small façade over `get_post`, `get_posts`, and the link-count post meta.
 * Returns Postlinkly's own immutable `PostModel` so call sites never see
 * raw `WP_Post` shape leaks.
 *
 * Repository is intentionally thin — the heavy logic (suggestion engine,
 * link insertion, broken-link scanning) lives in its own module and
 * consumes this repository.
 *
 * @since 1.0.0
 */
final class PostRepository {

	/**
	 * Post-meta key for outbound internal link count.
	 */
	public const META_OUTBOUND_INTERNAL = 'postlinkly_outbound_internal_count';

	/**
	 * Post-meta key for inbound internal link count.
	 */
	public const META_INBOUND_INTERNAL = 'postlinkly_inbound_internal_count';

	/**
	 * Post-meta key for outbound external link count.
	 */
	public const META_OUTBOUND_EXTERNAL = 'postlinkly_outbound_external_count';

	/**
	 * Returns a PostModel for the given post ID, or null when not found.
	 *
	 * Treats trashed posts as findable (callers may want to surface them
	 * in admin tables). Callers who want only published content should
	 * filter on `$model->status === 'publish'` themselves.
	 *
	 * @since 1.0.0
	 *
	 * @param int $id Post identifier.
	 *
	 * @return PostModel|null Hydrated model, or null when no post exists for $id.
	 */
	public function find( int $id ): ?PostModel {
		if ( $id <= 0 ) {
			return null;
		}
		$post = get_post( $id );
		if ( null === $post ) {
			return null;
		}

		return new PostModel(
			(int) $post->ID,
			PostModel::TYPE_POST,
			(string) $post->post_title,
			(string) $post->post_status,
			(string) $post->post_name
		);
	}

	/**
	 * Returns PostModels for a list of IDs, in input order.
	 *
	 * Skips IDs that don't resolve to a post. Returns an empty array for
	 * an empty input.
	 *
	 * @since 1.0.0
	 *
	 * @param array<int, int|string> $ids Post identifiers.
	 *
	 * @return array<int, PostModel>
	 */
	public function find_many( array $ids ): array {
		$out = array();
		foreach ( $ids as $id ) {
			$model = $this->find( (int) $id );
			if ( null !== $model ) {
				$out[] = $model;
			}
		}
		return $out;
	}

	/**
	 * Returns the stored link counts for a post.
	 *
	 * Counts default to zero when the meta key is absent — fresh posts
	 * haven't been scanned yet and report zero in every direction.
	 *
	 * @since 1.0.0
	 *
	 * @param int $post_id Post identifier.
	 *
	 * @return array{inbound: int, outbound: int, external: int}
	 */
	public function get_link_counts( int $post_id ): array {
		return array(
			'inbound'  => (int) get_post_meta( $post_id, self::META_INBOUND_INTERNAL, true ),
			'outbound' => (int) get_post_meta( $post_id, self::META_OUTBOUND_INTERNAL, true ),
			'external' => (int) get_post_meta( $post_id, self::META_OUTBOUND_EXTERNAL, true ),
		);
	}

	/**
	 * Writes the link counts for a post.
	 *
	 * Negative values are clamped to zero. The three metas are written
	 * unconditionally — partial updates are not supported because the
	 * scanner always recomputes all three together.
	 *
	 * @since 1.0.0
	 *
	 * @param int $post_id  Post identifier.
	 * @param int $inbound  Inbound internal link count.
	 * @param int $outbound Outbound internal link count.
	 * @param int $external Outbound external link count.
	 *
	 * @return void
	 */
	public function update_link_counts( int $post_id, int $inbound, int $outbound, int $external ): void {
		update_post_meta( $post_id, self::META_INBOUND_INTERNAL, max( 0, $inbound ) );
		update_post_meta( $post_id, self::META_OUTBOUND_INTERNAL, max( 0, $outbound ) );
		update_post_meta( $post_id, self::META_OUTBOUND_EXTERNAL, max( 0, $external ) );
	}
}