<?php
/**
 * Uninstall lifecycle handler (#127).
 *
 * Runs on Freemius's `after_uninstall` action — NEVER via uninstall.php.
 * WP core gives uninstall.php absolute precedence: if that file exists,
 * core deletes the SDK's registered uninstall hook and never runs it,
 * silencing the Freemius uninstall event AND the free/premium
 * sibling-build guard (design F2/F3). UninstallLifecycleTest pins the
 * file's absence.
 *
 * Data posture (design D2/D3): removal of content is OPT-IN via the
 * toggle, default OFF — chat logs and consent receipts are the site
 * owner's business records as data controller (decision 15). Secrets,
 * transients and schedules go on EVERY uninstall (D5). All `fs_*` rows
 * are the SDK's and are never touched (D3: fs_accounts/fs_active_plugins
 * are SHARED with every other Freemius plugin on the site).
 *
 * Design: docs/design/UNINSTALL_LIFECYCLE_DESIGN.md (approved 2026-08-12).
 *
 * 🪞 The manifest constants below are pinned by UninstallLifecycleTest
 * (D9): adding a lifecycle-relevant surface — a cron hook, a CPT, a
 * secret-shaped option, a table — without its manifest entry detonates
 * the pin in the same commit.
 *
 * @package AnswerRails
 */

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

class AnswerRails_Uninstall {

    /** Toggle option (D2). Default OFF; read raw at uninstall time. */
    const TOGGLE_OPTION = 'answerrails_delete_data_on_uninstall';

    /**
     * The prefix owning every plugin option (D6). Toggle-ON removal is
     * prefix SQL because the dynamic families (api_metrics_{api},
     * daily_aggregated_{date}, moderation_band_{n}, ...) make
     * enumeration impossible — verified live on prod (design Appendix A).
     */
    const OPTION_PREFIX = 'answerrails_';

    /**
     * Secrets purged on EVERY uninstall, toggle-independent (D5.1).
     * A stranded key in wp_options is a security liability with no
     * countervailing business-record argument.
     */
    const SECRET_OPTIONS = array(
        'answerrails_provider_openai_api_key',
        'answerrails_provider_gemini_api_key',
        'answerrails_provider_mistral_api_key',
        'answerrails_provider_anthropic_api_key',
        'answerrails_recaptcha_secret',
        // Legacy licence rows: migration 1.9.0 deletes them (#95);
        // re-deleted defensively for an install that uninstalls without
        // ever running that migration.
        'answerrails_license_key',
        'answerrails_license_data',
        'answerrails_license_status',
        // Pre-1.2.0 provider key (renamed to provider_openai_api_key;
        // migration 1.2.0 deletes the old row) — defensive, same class
        // as the licence rows. Surfaced by this file's own manifest pin.
        'answerrails_chat_api_key',
    );

    /** Cron hooks cleared on EVERY uninstall (D5.3). */
    const CRON_HOOKS = array(
        'answerrails_hourly_sync',
        'answerrails_purge_old_logs',
        // F6: the migrations runner's pending single event is cleared
        // nowhere else.
        'answerrails_run_migrations',
        // Legacy daily-check event — cleared once by migration 1.9.0;
        // defensive here for never-migrated installs.
        'answerrails_daily_license_check',
        // F9: installs that ran the pre-#95 self-updater carry this event
        // with no listener. Migration 1.10.0 owns the running-install fix;
        // this is the uninstall backstop.
        'puc_cron_check_updates-answerrails',
    );

    /**
     * Cron hooks whose events carry ARGUMENTS (#377 D8 step 6), cleared on
     * every uninstall BY HOOK (wp_unschedule_hook()): core's
     * wp_clear_scheduled_hook($hook) with no args clears only the events
     * whose args are [], so the CRON_HOOKS loop would leave these in place.
     */
    const ARG_CRON_HOOKS = array(
        // One recovery re-check per Down chat endpoint, args [$api].
        'answerrails_recovery_probe',
    );

    /** Plugin CPTs whose posts + postmeta go with the toggle ON (D6.2). */
    const POST_TYPES = array('answerrails_chatlog', 'answerrails_consent', 'answerrails_idea', 'answerrails_kb');

    /**
     * Retired post-type names, swept on uninstall as well (#331 D5).
     *
     * Same class as the legacy licence option rows above, and here for the
     * same reason: migration 1.12.0 renames these, but an install whose
     * FILES were updated and which is then deleted before the migration
     * ever runs would keep its rows forever. The migration cannot help
     * there — it never fired.
     *
     * ⚠ Kept SEPARATE from POST_TYPES, not merged into it, because
     * POST_TYPES means "what this plugin registers" and is parity-pinned
     * against the register_post_type() sites. These names are registered
     * NOWHERE, by design.
     */
    const LEGACY_POST_TYPES = array('ar_chatlog', 'ar_consent', 'ar_idea', 'ar_knowledge');

    /** Custom table (unprefixed name) dropped with the toggle ON (D6.3). */
    const TABLE = 'answerrails_knowledge_chunks';

    /** Batch size for CPT deletion (D6.2 — a 100k-conversation site must not time out). */
    const DELETE_BATCH = 1000;

    /**
     * `after_uninstall` entry point.
     *
     * Steps run in a fixed order with per-step guards (D1): one failure
     * must not abort the rest — the secrets purge in particular must
     * survive a broken later step, which is why it runs first.
     */
    public static function run() {
        $steps = array('purge_secrets', 'purge_transients', 'clear_cron');

        if (self::delete_all_requested()) {
            $steps[] = 'delete_content';
            $steps[] = 'drop_table';
            $steps[] = 'delete_options'; // Last: takes the toggle row itself.
        }

        foreach ($steps as $step) {
            try {
                self::$step();
            } catch (\Throwable $e) {
                error_log('AnswerRails uninstall: step ' . $step . ' failed: ' . $e->getMessage()); // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- operational failure diagnostic: deliberately loud so a partial uninstall reaches server logs without WP_DEBUG
            }
        }
    }

    /** D2: the opt-in, read raw — no settings abstraction at uninstall time. */
    public static function delete_all_requested() {
        return (bool) get_option(self::TOGGLE_OPTION, false);
    }

    /** D5.1 — enumerated secrets, deleted by name. */
    private static function purge_secrets() {
        foreach (self::SECRET_OPTIONS as $option) {
            delete_option($option);
        }
    }

    /**
     * D5.2 — every plugin transient, including session-keyed rows
     * (answerrails_consent_state_{id}) that only prefix SQL can catch.
     * Both value and timeout rows, both transient flavours.
     */
    private static function purge_transients() {
        global $wpdb;

        $prefixes = array(
            '_transient_' . self::OPTION_PREFIX,
            '_transient_timeout_' . self::OPTION_PREFIX,
            '_site_transient_' . self::OPTION_PREFIX,
            '_site_transient_timeout_' . self::OPTION_PREFIX,
        );
        foreach ($prefixes as $prefix) {
            $wpdb->query(
                $wpdb->prepare(
                    "DELETE FROM {$wpdb->options} WHERE option_name LIKE %s",
                    $wpdb->esc_like($prefix) . '%'
                )
            );
        }
    }

    /** D5.3 — all schedules, recurring and single. */
    private static function clear_cron() {
        foreach (self::CRON_HOOKS as $hook) {
            wp_clear_scheduled_hook($hook);
        }
        foreach (self::ARG_CRON_HOOKS as $hook) {
            wp_unschedule_hook($hook);
        }
    }

    /**
     * D6.2 — plugin CPT posts + their postmeta, batched. Direct $wpdb
     * on purpose: wp_delete_post() fires hooks and rebuilds caches per
     * post, which is both pointless and slow while the plugin is being
     * removed.
     */
    private static function delete_content() {
        global $wpdb;

        // #331 D5: the retired names are swept alongside the current ones,
        // for an install deleted before migration 1.12.0 ever ran.
        $types        = array_merge(self::POST_TYPES, self::LEGACY_POST_TYPES);
        $placeholders = implode(',', array_fill(0, count($types), '%s'));

        do {
            // phpcs:disable WordPress.Security, WordPress.DB -- uninstall-time direct deletion; no user input beyond the fixed CPT manifest (placeholders generated from it; IDs intval'd).
            $ids = $wpdb->get_col(
                $wpdb->prepare(
                    "SELECT ID FROM {$wpdb->posts} WHERE post_type IN ($placeholders) LIMIT " . self::DELETE_BATCH,
                    $types
                )
            );
            if (empty($ids)) {
                break;
            }
            $id_list = implode(',', array_map('intval', $ids));
            $wpdb->query("DELETE FROM {$wpdb->postmeta} WHERE post_id IN ($id_list)");
            $wpdb->query("DELETE FROM {$wpdb->posts} WHERE ID IN ($id_list)");
            // phpcs:enable WordPress.Security
        } while (count($ids) === self::DELETE_BATCH);
    }

    /** D6.3 — the chunks table (migration 1.3.0). */
    private static function drop_table() {
        global $wpdb;
        $wpdb->query("DROP TABLE IF EXISTS {$wpdb->prefix}" . self::TABLE); // phpcs:ignore WordPress.Security, WordPress.DB -- fixed table name from the pinned manifest; uninstall-time DDL.
    }

    /**
     * D6.4 — every remaining plugin option, by prefix. Sweeps the
     * literal keys, the dynamic families, the orphans (#155's
     * answerrails_logging_mode class) and, last of all, the toggle row.
     * fs_* rows do not match the prefix and are untouched (D3).
     */
    private static function delete_options() {
        global $wpdb;
        $wpdb->query(
            $wpdb->prepare(
                "DELETE FROM {$wpdb->options} WHERE option_name LIKE %s",
                $wpdb->esc_like(self::OPTION_PREFIX) . '%'
            )
        );
        wp_cache_flush();
    }
}