<?php
/**
 * PayPal payout helpers (parsing, formatting).
 *
 * Small utility surface for code that needs to interpret the structured
 * description blob a PayPal payout carries. Kept method-local so the
 * cross-method ajax payload builder doesn't have to know the PayPal JSON
 * shape — it just hands the raw description to a helper and gets back a
 * human-readable headline + a raw blob for debugging disclosure.
 *
 * @package    AffiliateWP
 * @subpackage Payouts/Methods/PayPal
 * @since      2.33.0
 */

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

if ( ! function_exists( 'affwp_paypal_format_failure_error' ) ) {

	/**
	 * Turns a PayPal payout description (or any error column value) into a
	 * pair of admin-facing strings.
	 *
	 * Drives the failed-payout error rendering in the Payouts drawer. The
	 * Summary's red "This payout failed" card and the Details panel's
	 * "Error" row both consume the same shape so the same fix point covers
	 * both surfaces.
	 *
	 * Behaviour:
	 *
	 * - Input is JSON-decodable + carries a non-empty `error` field:
	 *   headline = that field; raw = pretty-printed JSON.
	 * - Input is JSON-decodable but the `error` field is missing/empty:
	 *   headline = a generic fallback; raw = pretty-printed JSON (so support
	 *   can still inspect the structured payload).
	 * - Input is a plain (non-JSON) string: headline = the string; raw = NULL
	 *   so the disclosure UI doesn't render an empty "Show raw provider
	 *   response" toggle for a string that's already fully visible.
	 * - Input is empty: headline = NULL, raw = NULL (caller should skip
	 *   rendering the error block entirely).
	 *
	 * @since 2.33.0
	 *
	 * @param string $description The raw description column value as stored
	 *                            in the payouts table (PayPal JSON, plain
	 *                            string, or empty).
	 * @return array {
	 *     Headline + raw blob for the drawer's error rendering.
	 *
	 *     @type string|null $headline Human-readable failure message.
	 *     @type string|null $raw      Pretty-printed JSON for the disclosure,
	 *                                 or NULL when there is no structured
	 *                                 payload to disclose.
	 * }
	 */
	function affwp_paypal_format_failure_error( $description ) {

		$description = is_string( $description ) ? trim( $description ) : '';

		if ( '' === $description ) {
			return array(
				'headline' => null,
				'raw'      => null,
			);
		}

		$decoded = json_decode( $description, true );

		if ( ! is_array( $decoded ) ) {
			return array(
				'headline' => $description,
				'raw'      => null,
			);
		}

		$headline = '';
		if ( ! empty( $decoded['error'] ) && is_string( $decoded['error'] ) ) {
			$headline = trim( $decoded['error'] );
		}

		if ( '' === $headline ) {
			$headline = __( 'PayPal reported a failure. Expand the raw response for the provider payload.', 'affiliate-wp' );
		}

		/*
		 * Pretty-print so the disclosure surface is readable when expanded.
		 * JSON_UNESCAPED_SLASHES + JSON_UNESCAPED_UNICODE keep PayPal URLs
		 * and any non-ASCII characters in their natural form.
		 */
		$raw = wp_json_encode(
			$decoded,
			JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
		);

		if ( false === $raw ) {
			$raw = $description;
		}

		return array(
			'headline' => $headline,
			'raw'      => $raw,
		);
	}
}
