<?php
/**
 * Who is asking, resolved once per request from a verified Session Token
 * (PLAN.md §5.4). Every capability receives one; nothing downstream re-reads
 * headers or trusts request parameters for identity.
 *
 * @package AgentAdapt
 */

defined( 'ABSPATH' ) || exit;

/**
 * Request context.
 */
final class AgentAdapt_Context {

	/**
	 * Build a context.
	 *
	 * @param string              $client_id      Agent client_id.
	 * @param string              $client_hash    Agent hash.
	 * @param string              $agent_name     Display name from client metadata.
	 * @param array<string,mixed> $agent_meta     Client metadata document.
	 * @param int                 $subject_id     Internal subject id (never the raw sub).
	 * @param string              $session_id     Session.
	 * @param string              $wc_session_key WooCommerce session key backing the Session's cart.
	 * @param int                 $user_id        Signed-in account, 0 when signed out.
	 * @param string[]            $scopes         Granted account scopes.
	 * @param string              $channel        api|mcp|web|conversation.
	 */
	public function __construct(
		public readonly string $client_id,
		public readonly string $client_hash,
		public readonly string $agent_name,
		public readonly array $agent_meta,
		public readonly int $subject_id,
		public readonly string $session_id,
		public readonly string $wc_session_key,
		public readonly int $user_id,
		public readonly array $scopes,
		public readonly string $channel
	) {}

	/**
	 * Whether the Session is signed in to an account.
	 */
	public function signed_in(): bool {
		return $this->user_id > 0;
	}

	/**
	 * Whether a scope was granted. `poppy:write` does not imply `poppy:read`.
	 *
	 * @param string $scope Scope.
	 */
	public function has_scope( string $scope ): bool {
		return in_array( $scope, $this->scopes, true );
	}
}