<?php
declare(strict_types=1);

namespace Instinctor\Core;

/**
 * Platform-connection consent gate.
 *
 * WordPress.org's plugin guidelines (7 & 9) require that any outbound HTTP
 * call from the plugin to a remote service the plugin author controls is
 * gated behind an explicit, default-OFF opt-in. This class is that gate.
 *
 * Usage at every wp_remote_* / file_get_contents that targets
 * platform.instinctor.com:
 *
 *     if (!\Instinctor\Core\PlatformConsent::granted()) {
 *         return new \WP_Error('platform_consent', 'Instinctor platform features are disabled in Settings.');
 *     }
 *
 * On STANDALONE mode (INSTINCTOR_ENV=standalone) the consent is implicit
 * — the install IS the platform, no separate consent surface — so
 * granted() returns true. On WP mode it reads the `instinctor_platform_consent`
 * option (added 2.1.956). A first-run admin notice surfaces the opt-in
 * the first time an admin loads a wp-admin page after installing.
 *
 * Outbound calls covered by this gate (full list in readme.txt under
 * "External services"):
 *   - Mailer relay (transactional email)
 *   - License validation + tier sync
 *   - Plugin update polling
 *   - Designer profile + marketplace
 *   - Affiliate/partners signup + stats
 *   - AI relays: Instagent help, Section generator, Chat AI replies
 *   - SMS relay
 *   - Curated section / 3D image library
 *   - Daily anonymized usage analytics (already opt-in)
 *
 * @since 2.1.956
 */
class PlatformConsent
{
    private const OPTION_KEY      = 'instinctor_platform_consent';
    private const SEEN_OPTION_KEY = 'instinctor_platform_consent_seen';

    /**
     * Has the site owner opted in to Instinctor platform features?
     *
     * Standalone: always true (the install IS the platform).
     * WordPress: reads the `instinctor_platform_consent` option. Default false.
     */
    public static function granted(): bool
    {
        if (defined('INSTINCTOR_ENV') && INSTINCTOR_ENV === 'standalone') {
            return true;
        }
        if (function_exists('get_option')) {
            return get_option(self::OPTION_KEY, '0') === '1';
        }
        // Fallback if WP isn't loaded for some reason — fail closed.
        return false;
    }

    /**
     * Grant consent. Idempotent; safe to call repeatedly.
     */
    public static function grant(): void
    {
        if (function_exists('update_option')) {
            update_option(self::OPTION_KEY, '1');
            update_option(self::SEEN_OPTION_KEY, '1');
        }
    }

    /**
     * Revoke consent. Sets seen=1 so the first-run notice doesn't re-appear.
     */
    public static function revoke(): void
    {
        if (function_exists('update_option')) {
            update_option(self::OPTION_KEY, '0');
            update_option(self::SEEN_OPTION_KEY, '1');
        }
    }

    /**
     * Has the user been shown the opt-in notice at least once?
     * Drives the first-run admin notice — if false, the notice renders;
     * once the user clicks Connect OR Dismiss, this flips to true.
     */
    public static function seen(): bool
    {
        if (defined('INSTINCTOR_ENV') && INSTINCTOR_ENV === 'standalone') {
            return true;
        }
        if (function_exists('get_option')) {
            return get_option(self::SEEN_OPTION_KEY, '0') === '1';
        }
        return true;
    }

    /**
     * Mark the notice as seen WITHOUT changing consent. Used when the user
     * clicks "No thanks" / dismisses without opting in.
     */
    public static function markSeen(): void
    {
        if (function_exists('update_option')) {
            update_option(self::SEEN_OPTION_KEY, '1');
        }
    }
}
