<?php
/**
 * Ability: wp-agent/delete-term
 *
 * Löscht einen Term endgültig aus einer Taxonomie. Anders als bei Beiträgen
 * kennt WordPress für Terme keinen Papierkorb: wp_delete_term() entfernt den
 * Term sofort und unumkehrbar, es gibt keinen wp-agent/restore-term-Gegenpart.
 *
 * wp_delete_term() gibt laut WordPress-Kern-Dokumentation drei unterschiedliche
 * "kein Fehler, aber auch kein Erfolg"-Werte zurück, die diese Ability
 * unterscheidet statt sie pauschal als Erfolg zu werten:
 *   - true:  gelöscht.
 *   - false: der Term existierte zum Zeitpunkt des Aufrufs bereits nicht mehr.
 *   - 0:     WordPress verweigert das Löschen des Standard-Terms der Taxonomie
 *            (z. B. die Default-Kategorie aus der Option default_category).
 *   - WP_Error: sonstiger Fehler.
 *
 * @package WPAgentCompanion
 */

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

function wpagent_ability_delete_term(): array {
	return array(
		'label'               => __( 'Term löschen', 'wp-agent-companion' ),
		'description'         => __( 'Löscht einen Term endgültig aus einer Taxonomie (WordPress kennt für Terme keinen Papierkorb). Verweigert das Löschen des Standard-Terms einer Taxonomie (z. B. die Default-Kategorie). Verifiziert per Re-Read, dass der Term danach nicht mehr existiert.', 'wp-agent-companion' ),
		'category'            => 'wp-agent',
		'input_schema'        => array(
			'type'       => 'object',
			'properties' => array(
				'term_id'  => array( 'type' => 'integer' ),
				'taxonomy' => array(
					'type'        => 'string',
					'description' => __( 'Muss eine registrierte Taxonomie sein (z. B. category, post_tag).', 'wp-agent-companion' ),
				),
			),
			'required'   => array( 'term_id', 'taxonomy' ),
		),
		'output_schema'       => array(
			'type'       => 'object',
			'properties' => array(
				'term_id'  => array( 'type' => 'integer' ),
				'taxonomy' => array( 'type' => 'string' ),
				'deleted'  => array( 'type' => 'boolean' ),
				'verified' => array( 'type' => 'boolean' ),
			),
		),
		'execute_callback'    => 'wpagent_exec_delete_term',
		'permission_callback' => 'wpagent_perm_edit_posts',
		'meta'                => array(
			'show_in_rest' => true,
			'annotations'  => array(
				'readonly'    => false,
				// Terme haben in WordPress keinen Papierkorb: jedes Löschen ist
				// unumkehrbar, deshalb abweichend von den sonst überall
				// destructive:false gesetzten Companion-Abilities (analog zu
				// wp-agent/delete-post mit force=true).
				'destructive' => true,
				// Der Endzustand ("Term existiert nicht mehr") ändert sich durch
				// wiederholte Aufrufe nicht, auch wenn ein Re-Run nach dem ersten
				// erfolgreichen Löschen mit 404 statt Erfolg antwortet (der Term
				// existiert dann schlicht bereits nicht mehr).
				'idempotent'  => true,
			),
		),
	);
}

/**
 * @param mixed $input
 * @return array|WP_Error
 */
function wpagent_exec_delete_term( $input ) {
	$input    = is_array( $input ) ? $input : array();
	$term_id  = (int) ( $input['term_id'] ?? 0 );
	$taxonomy = (string) ( $input['taxonomy'] ?? '' );

	if ( '' === $taxonomy || ! taxonomy_exists( $taxonomy ) ) {
		return new WP_Error( 'wpagent_bad_taxonomy', sprintf( __( 'Unbekannte Taxonomie "%s".', 'wp-agent-companion' ), $taxonomy ), array( 'status' => 400 ) );
	}
	if ( 'product_shipping_class' === $taxonomy ) {
		return new WP_Error(
			'wpagent_wc_shipping_class_requires_specialized_delete',
			__( 'WooCommerce-Versandklassen können nicht remote gelöscht werden. WordPress kann parallele Fremdzuweisungen nicht race-frei verifizieren. Entferne eine leere Versandklasse nur manuell in der WooCommerce-Verwaltung.', 'wp-agent-companion' ),
			array( 'status' => 409 )
		);
	}

	$term = get_term( $term_id, $taxonomy );
	if ( ! $term || is_wp_error( $term ) ) {
		return new WP_Error( 'wpagent_no_term', __( 'Term nicht gefunden.', 'wp-agent-companion' ), array( 'status' => 404 ) );
	}

	// Feingranulare Capability der konkreten Taxonomie (get_taxonomy()->cap),
	// fail-closed analog zu wpagent_post_type_cap() in helpers.php.
	$tax_object = get_taxonomy( $taxonomy );
	$delete_cap = ( $tax_object && isset( $tax_object->cap->delete_terms ) && '' !== (string) $tax_object->cap->delete_terms )
		? (string) $tax_object->cap->delete_terms
		: 'do_not_allow';
	if ( ! current_user_can( $delete_cap ) ) {
		return new WP_Error( 'wpagent_forbidden', __( 'Keine Berechtigung, Terme in dieser Taxonomie zu löschen.', 'wp-agent-companion' ), array( 'status' => 403 ) );
	}

	$res = wp_delete_term( $term_id, $taxonomy );
	if ( is_wp_error( $res ) ) {
		return $res;
	}
	if ( false === $res || 0 === $res ) {
		// false: Term existierte bereits nicht mehr (Race). 0: WordPress
		// verweigert das Löschen des Standard-Terms dieser Taxonomie (z. B. die
		// Default-Kategorie), siehe Datei-Kommentar oben.
		return new WP_Error(
			'wpagent_delete_failed',
			__( 'Löschen fehlgeschlagen. Möglicherweise ist dies der Standard-Term dieser Taxonomie (z. B. die Default-Kategorie) und wird von WordPress geschützt.', 'wp-agent-companion' ),
			array( 'status' => 400 )
		);
	}

	$still_exists = get_term( $term_id, $taxonomy );
	$verified     = ( ! $still_exists || is_wp_error( $still_exists ) );

	return array(
		'term_id'  => $term_id,
		'taxonomy' => $taxonomy,
		'deleted'  => $verified,
		'verified' => $verified,
	);
}
