<?php
/**
 * Integration base class.
 *
 * @package FormPilot
 * @since   1.0.0
 */

declare( strict_types = 1 );

namespace FormPilot\Integrations;

use FormPilot\Models\Form;
use FormPilot\Security\OutboundUrl;
use FormPilot\Settings\Settings;
use FormPilot\Webhooks\Webhook;

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

/**
 * One service a form can send its submissions to.
 *
 * An integration answers three questions and nothing else: what it needs to be
 * configured, where a submission should be sent, and what the body should look
 * like. It never performs the request, retries it, or writes to the log — those
 * belong to the delivery layer the webhooks already use, and reusing it is what
 * makes a new integration one class rather than one class and a queue.
 *
 * The four methods with a body here are the parts every service would otherwise
 * repeat; the abstract ones are what makes it a particular service.
 *
 * @since 1.0.0
 */
abstract class Integration {

	/**
	 * Returns the slug the configuration is stored under.
	 */
	abstract public function id(): string;

	/**
	 * Returns the name shown in the editor.
	 */
	abstract public function label(): string;

	/**
	 * Returns the settings this integration takes, per form.
	 *
	 * Each entry is an array with `key` and `type`, and optionally `label`,
	 * `description`, `choices` and `required`. The editor renders them and the
	 * save routine cleans them from this description alone, so an integration
	 * never writes markup or sanitising of its own.
	 *
	 * @return array<int, array<string, mixed>> The option definitions.
	 */
	abstract public function options(): array;

	/**
	 * Builds the body sent to the service.
	 *
	 * @param IntegrationContext   $context Submission being delivered.
	 * @param array<string, mixed> $config  Stored values for the form.
	 *
	 * @return array<string, mixed> The payload, encoded as JSON by the sender.
	 */
	abstract public function payload( IntegrationContext $context, array $config ): array;

	/**
	 * Returns the sentence explaining what to fill in.
	 *
	 * @return string The translated description, which may carry inline markup.
	 */
	public function description(): string {
		return '';
	}

	/**
	 * Determines whether the stored configuration is usable.
	 *
	 * Every option marked required must carry something. An integration with a
	 * rule the definitions cannot express overrides this.
	 *
	 * @param array<string, mixed> $config Stored values for one form.
	 *
	 * @return bool True when a submission can be sent.
	 */
	public function is_configured( array $config ): bool {
		foreach ( $this->options() as $option ) {
			if ( empty( $option['required'] ) ) {
				continue;
			}

			if ( '' === trim( (string) ( $config[ (string) $option['key'] ] ?? '' ) ) ) {
				return false;
			}
		}

		return true;
	}

	/**
	 * Determines whether a particular submission is worth sending.
	 *
	 * Lets an integration skip a submission it cannot use — a mailing list with
	 * no address to add — without that counting as a delivery that failed.
	 *
	 * @param IntegrationContext   $context Submission being delivered.
	 * @param array<string, mixed> $config  Stored values for the form.
	 *
	 * @return bool True when the delivery should go ahead.
	 */
	public function should_send( IntegrationContext $context, array $config ): bool {
		return true;
	}

	/**
	 * Returns where a submission should be delivered.
	 *
	 * The default is the shape most services take: one `webhook_url` option
	 * holding the whole address. A service that assembles its endpoint from an
	 * account id or a key overrides this.
	 *
	 * Returning null switches the integration off for that form, which is what a
	 * missing key or an unusable endpoint should do rather than a delivery that
	 * fails every time and fills the log with the same error.
	 *
	 * @param Form                 $form   Form being submitted.
	 * @param array<string, mixed> $config Stored values for that form.
	 *
	 * @return Webhook|null The endpoint, or null when there is nothing to send to.
	 */
	public function endpoint( Form $form, array $config ): ?Webhook {
		return $this->target( $this->option( $config, 'webhook_url' ) );
	}

	/**
	 * Describes the single URL option the default endpoint reads.
	 *
	 * @param string $label       Field label shown in the editor.
	 * @param string $placeholder Example address.
	 *
	 * @return array<string, mixed> The option definition.
	 */
	protected function url_option( string $label, string $placeholder ): array {
		return array(
			'key'         => 'webhook_url',
			'type'        => 'url',
			'label'       => $label,
			'placeholder' => $placeholder,
			'required'    => true,
		);
	}

	/**
	 * Reads one stored option.
	 *
	 * @param array<string, mixed> $config Stored values.
	 * @param string               $key    Option name.
	 */
	protected function option( array $config, string $key ): string {
		$value = $config[ $key ] ?? '';
		$value = is_scalar( $value ) ? trim( (string) $value ) : '';

		/*
		 * A credential the site set once, used by every form that did not enter
		 * one of its own. Only options the integration declared shared fall back:
		 * without that check a per form choice left empty would silently pick up
		 * an unrelated site wide value.
		 */
		if ( '' === $value && in_array( $key, $this->shared_keys(), true ) ) {
			return Settings::text( IntegrationRegistry::shared_key( $this->id(), $key ) );
		}

		return $value;
	}

	/**
	 * Returns the options that fall back to a site wide value.
	 *
	 * @return array<int, string> Option names.
	 */
	protected function shared_keys(): array {
		$keys = array();

		foreach ( $this->options() as $option ) {
			if ( ! empty( $option['shared'] ) ) {
				$keys[] = (string) $option['key'];
			}
		}

		return $keys;
	}

	/**
	 * Builds the endpoint this integration posts to.
	 *
	 * The key is prefixed so the delivery log and the retry run can tell an
	 * integration apart from a webhook somebody entered by hand.
	 *
	 * @param string                $url     Absolute endpoint.
	 * @param array<string, string> $headers Optional. Extra headers, such as authorisation.
	 *
	 * @return Webhook|null The endpoint, or null when the URL is unusable.
	 */
	protected function target( string $url, array $headers = array() ): ?Webhook {
		// Screened the same way a hand-entered webhook is; see OutboundUrl.
		if ( '' === $url || ! OutboundUrl::is_safe( $url ) ) {
			return null;
		}

		return new Webhook(
			key: IntegrationRegistry::PREFIX . $this->id(),
			name: $this->label(),
			url: $url,
			// Integrations authenticate with the service's own credentials; a
			// signature of ours would be one more header nobody reads.
			secret: '',
			headers: $headers,
			enabled: true
		);
	}
}