Especificación: Sistema de puntos de fidelidad y canje en el checkout (Cart Fee API)

<?php
declare(strict_types=1);

class AgenticLab_Points_Manager {
    private const META_KEY = '_agenticlab_loyalty_points';

    public static function get_balance(int $user_id): int {
        return (int) get_user_meta($user_id, self::META_KEY, true);
    }

    public static function add_points(int $user_id, int $points, int $order_id = 0, string $reason = ''): bool {
        if ($points <= 0) return false;

        $current = self::get_balance($user_id);
        $new_balance = $current + $points;
        update_user_meta($user_id, self::META_KEY, $new_balance);

        self::log_transaction($user_id, $points, 'credit', $order_id, $reason);
        return true;
    }

    public static function debit_points(int $user_id, int $points, int $order_id = 0, string $reason = ''): bool {
        $current = self::get_balance($user_id);
        if ($points <= 0 || $current < $points) return false;

        $new_balance = $current - $points;
        update_user_meta($user_id, self::META_KEY, $new_balance);

        self::log_transaction($user_id, -$points, 'debit', $order_id, $reason);
        return true;
    }

    private static function log_transaction(int $user_id, int $points, string $type, int $order_id, string $reason): void {
        $log = get_user_meta($user_id, '_agenticlab_points_history', true) ?: [];
        $log[] = [
            'timestamp' => time(),
            'points'    => $points,
            'type'      => $type,
            'order_id'  => $order_id,
            'reason'    => $reason,
        ];
        update_user_meta($user_id, '_agenticlab_points_history', array_slice($log, -50)); // Храним последние 50 записей
    }
}