<?php
/**
 * Per-error-code customer guidance (2.6.2, P1 error-handling review item 2).
 *
 * One map from the machine-readable `_doig_error_code` to a short plain
 * hint and the matching troubleshooting deep link, shared by every admin
 * surface that renders a failure: the Dashboard Failed table and the
 * block-editor sidebar (localised as `doigSidebar.errorGuidance`).
 *
 * The raw `_doig_error_message` stays authoritative and is always shown -
 * guidance AUGMENTS it with "what do I do now", it never replaces it.
 *
 * @package Dynamic_OG_Image_Generator
 */

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

class DOIG_Error_Guidance {

	/**
	 * The guidance map. Codes not listed render without guidance - that is
	 * fine and expected for rare or self-explanatory codes.
	 *
	 * Docs paths resolve through DOIG_Plugin::docs_url() so UTM tagging and
	 * the docs base URL stay in one place. Anchors are the Docusaurus slugs
	 * of the matching user-docs/troubleshooting.md headings - update them
	 * together.
	 *
	 * @return array<string, array{hint: string, path: string}>
	 */
	public static function map() {
		return array(
			'host_returned_error'        => array(
				'hint' => __( 'Your site answered the capture request with an error - usually a firewall, security plugin or bot protection blocking uncached requests. The guide shows a ten-second way to confirm it.', 'dynamic-og-image-generator' ),
				'path' => 'troubleshooting#your-site-returned-http-403-or-another-error-to-the-screenshot-service',
			),
			'licence_inactive'           => array(
				'hint' => __( 'Renew or upgrade your PlugUpp licence, then use Regenerate Now.', 'dynamic-og-image-generator' ),
				'path' => 'troubleshooting#screenshot-shows-failed',
			),
			'proxy_unavailable'          => array(
				'hint' => __( 'The screenshot service was temporarily unreachable. It retries automatically - if this keeps happening, check the service status page.', 'dynamic-og-image-generator' ),
				'path' => 'troubleshooting#screenshot-shows-failed',
			),
			'unauthorized_site'          => array(
				'hint' => __( 'This site is not registered under your licence. Reconnect the plugin from this site, or check which sites your licence covers in your PlugUpp account.', 'dynamic-og-image-generator' ),
				'path' => 'troubleshooting',
			),
			'private_site_not_supported' => array(
				'hint' => __( 'Screenshots need a live, publicly reachable website - local development sites and sites without a domain name cannot be captured.', 'dynamic-og-image-generator' ),
				'path' => 'troubleshooting',
			),
			'cross_domain_not_allowed'   => array(
				'hint' => __( 'Capturing a URL on a different domain than this site requires an active paid licence, or a capture URL on your own domain.', 'dynamic-og-image-generator' ),
				'path' => 'features/per-post-controls',
			),
		);
	}

	/**
	 * Guidance for one code, with the docs path resolved to a full URL.
	 *
	 * @param string $code The `_doig_error_code` value.
	 * @return array{hint: string, url: string}|null Null when unmapped.
	 */
	public static function get( $code ) {
		$map = self::map();
		if ( ! isset( $map[ $code ] ) ) {
			return null;
		}
		return array(
			'hint' => $map[ $code ]['hint'],
			'url'  => DOIG_Plugin::docs_url( $map[ $code ]['path'] ),
		);
	}

	/**
	 * The full map with resolved URLs, for wp_localize_script.
	 *
	 * @return array<string, array{hint: string, url: string}>
	 */
	public static function localised() {
		$out = array();
		foreach ( array_keys( self::map() ) as $code ) {
			$out[ $code ] = self::get( $code );
		}
		return $out;
	}
}
