<?php
/**
 * Trusted schema integration contributor contract (Architecture V2).
 *
 * Integrations may contribute specialized entities with source metadata.
 * Output must still pass sanitization; readiness bypass is opt-in per type.
 *
 * @package SEOvaultSEO\Schema
 */

namespace SEOvaultSEO\Schema;

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Contract for objective domain integrations (e.g. WooCommerce Product).
 */
interface SchemaIntegrationContributor {

	/**
	 * Stable integration identifier (used in source_ref).
	 *
	 * @return string
	 */
	public function get_integration_id();

	/**
	 * Collect tagged schema contributions for an object/context.
	 *
	 * Each item must be:
	 * array{source:'integration', source_ref:string, schema:array}
	 *
	 * @param \WP_Post|\WP_Term|\WP_User|null $object Render object.
	 * @return array<int,array{source:string,source_ref:string,schema:array}>
	 */
	public function collect_tagged_schemas( $object );

	/**
	 * Schema.org types this integration owns for the current object.
	 *
	 * Owned types suppress competing non-integration Product-like contributions
	 * on the same page (manual/template/extension). Custom JSON still wins via
	 * documented source precedence / replace path.
	 *
	 * @param \WP_Post|\WP_Term|\WP_User|null $object Render object.
	 * @return string[]
	 */
	public function owned_types( $object );

	/**
	 * Whether a sanitized integration node may bypass readiness blockers.
	 *
	 * Sanitization always applies. Default should be false unless documented.
	 *
	 * @param string $type    Primary @type.
	 * @param array  $node    Sanitized node.
	 * @param array  $context Gate context (may include source_ref).
	 * @return bool
	 */
	public function is_trusted_type( $type, array $node, array $context = array() );
}
