<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Integrations;

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

/**
 * A connector's settings — the ones that are not secrets.
 *
 * WHY THIS IS NOT {@see Credentials}, WHICH IS THE ONLY INTERESTING DECISION HERE. That store
 * encrypts the whole bag, and its documented and correct failure mode is that a rotated salt makes
 * `get()` return an empty array so the screen can say "sign in again". For an API key that is the
 * right answer. For an option bag it is a disaster with no symptom: on the day somebody rotates their
 * salts after a suspected breach, the opportunity threshold silently becomes 0 (off), the configured
 * tags vanish, the follow-up task stops being created, and **nothing errors anywhere**. The site owner
 * is already dealing with an incident and their CRM quietly stops doing half of what they set it up
 * to do.
 *
 * Nothing kept here is a bearer token. An amount, a pipeline id, a list of tag ids and a checkbox are
 * configuration, and configuration should survive a key rotation exactly as the rest of the site's
 * settings do.
 *
 * NOT `plugixa_crm_settings` EITHER. That option is autoloaded on every page load of the entire site,
 * including every front-end request that never touches the CRM. A per-connector bag belongs to the
 * connector.
 *
 * THE PREFIX IS CHOSEN SO THE UNINSTALL SWEEP ALREADY CATCHES IT.
 * {@see \PlugixaCrm\Modules\Integrations\Module} deletes every option matching
 * `plugixa_crm_integration_%` on `plugixa_crm_uninstall`, and this prefix starts with it. Renaming it
 * to something that does not — `plugixa_crm_woo_options`, say — leaves configuration on disk after
 * the plugin is deleted, which is precisely how the two legacy `*_connected` flags came to leak.
 *
 * DEFAULTS ARE NOT STORED HERE, AND THAT IS DELIBERATE. A bag written by an older build has no key
 * for an option added later, so {@see value()} takes a fallback and the caller resolves it from the
 * connector's `options_schema()`. If the client owned defaults instead, a save from a stale bundle
 * would omit the key entirely and the server would read null, cast it, and conclude "off" for a
 * checkbox whose default is on. Absent-means-default is only ever reached for an option that did not
 * exist when the bag was written — which is exactly the case where taking the default is right.
 */
final class Options {

	/**
	 * Option prefix. The connector id completes it.
	 *
	 * Deliberately inside {@see Credentials::PREFIX}'s namespace so the uninstall sweep needs no
	 * second pattern. See the class docblock.
	 */
	public const PREFIX = 'plugixa_crm_integration_opts_';

	/**
	 * Everything stored for one connector, with no defaults applied.
	 *
	 * @param string $integration Connector id.
	 *
	 * @return array<string, string>
	 */
	public function get( string $integration ): array {
		$stored = get_option( self::option( $integration ), array() );

		if ( ! is_array( $stored ) ) {
			return array();
		}

		$clean = array();

		foreach ( $stored as $key => $value ) {
			if ( is_scalar( $value ) ) {
				$clean[ (string) $key ] = (string) $value;
			}
		}

		return $clean;
	}

	/**
	 * One stored value, or the fallback when this site has never set it.
	 *
	 * EVERY VALUE IS A STRING, GOING BOTH WAYS. The client normalises on the way out — see
	 * `shared/SchemaField.tsx`, whose docblock records why a number arriving as a number in one
	 * browser and a string in another is the one thing that must never happen — and this keeps the
	 * server's half of that bargain. Callers cast at the point of use, where they know whether they
	 * wanted an int, a float or a list.
	 *
	 * @param string $integration Connector id.
	 * @param string $key         Option key.
	 * @param string $fallback    What the connector's schema says the default is.
	 */
	public function value( string $integration, string $key, string $fallback = '' ): string {
		$all = $this->get( $integration );

		return array_key_exists( $key, $all ) ? $all[ $key ] : $fallback;
	}

	/**
	 * Replace everything stored for one connector.
	 *
	 * @param string               $integration Connector id.
	 * @param array<string, mixed> $values      Option key => value.
	 */
	public function put( string $integration, array $values ): bool {
		$clean = array();

		foreach ( $values as $key => $value ) {
			if ( is_scalar( $value ) ) {
				$clean[ (string) $key ] = (string) $value;
			}
		}

		// autoload 'no': read when a connector runs, not when a visitor loads a page. The switch that
		// IS on the hot path lives in {@see State} and is autoloaded on its own.
		return update_option( self::option( $integration ), $clean, false );
	}

	/**
	 * Merge values over what is stored.
	 *
	 * @param string               $integration Connector id.
	 * @param array<string, mixed> $values      Option key => value.
	 */
	public function merge( string $integration, array $values ): bool {
		return $this->put( $integration, array_merge( $this->get( $integration ), $values ) );
	}

	/**
	 * Forget one connector's options.
	 *
	 * NOT CALLED WHEN A CONNECTOR IS SWITCHED OFF, and this is the same rule
	 * {@see IntegrationInterface::disable()} states for synced data: somebody switching WooCommerce
	 * off for an afternoon has not asked to lose the threshold and the pipeline they chose. Only
	 * `forget()` on the connector — the explicit, destructive action — reaches this.
	 *
	 * @param string $integration Connector id.
	 */
	public function forget( string $integration ): void {
		delete_option( self::option( $integration ) );
	}

	/**
	 * @param string $integration Connector id.
	 */
	private static function option( string $integration ): string {
		return self::PREFIX . sanitize_key( $integration );
	}
}