Abilities API: Превращение плагинов и тем в Agent-Callable

<?php
declare(strict_types=1);

/**
* Author: Artur Yusupov (Fullstack Agentic Lab)
* Package: @agentic-lab/abilities
* Module: CommercePromoCodeAbility
* Standard: WordPress 7.0+ Abilities API / WooCommerce HPOS / PHP 8.4
*/

namespace AgenticLab\Abilities;

use WC_Coupon;
use WP_Error;
use Throwable;

final class CommercePromoCodeAbility
{
  public static function register(): void
  {
      if (!function_exists('wp_register_ability')) {
          return;
      }

      wp_register_ability('agentic-lab/generate-promo-code', [
          'label'               => __('Создать скидочный промокод для клиента', 'agentic-lab'),
          'description'         => __('Генерирует персональный скидочный купон WooCommerce с заданным процентом скидки и ограничением по времени.', 'agentic-lab'),
          'category'            => 'ecommerce',
          'idempotent'          => true,

          // JSON Schema Draft 7 входных параметров для ИИ-агента
          'parameters_schema'   => [
              'type'       => 'object',
              'properties' => [
                  'discount_percent' => [
                      'type'        => 'integer',
                      'minimum'     => 1,
                      'maximum'     => 50,
                      'description' => 'Процент скидки на заказ (от 1 до 50%).',
                  ],
                  'customer_email'   => [
                      'type'        => 'string',
                      'format'      => 'email',
                      'description' => 'Email покупателя, для которого генерируется персональный купон.',
                  ],
                  'expiry_days'      => [
                      'type'        => 'integer',
                      'minimum'     => 1,
                      'maximum'     => 30,
                      'default'     => 7,
                      'description' => 'Количество дней до истечения срока действия купона.',
                  ],
                  'idempotency_key'  => [
                      'type'        => 'string',
                      'description' => 'Уникальный UUIDv4 запроса для предотвращения повторной генерации купона.',
                  ],
              ],
              'required'   => ['discount_percent', 'customer_email', 'idempotency_key'],
              'additionalProperties' => false,
          ],

          // Проверка прав доступа: только персонал магазина может создавать купоны
          'permission_callback' => static function (): bool {
              return current_user_can('manage_woocommerce');
          },

          // Исполняемый колбэк при вызове агентом
          'execute_callback'    => [self::class, 'execute'],
      ]);
  }

  /**
   * @param array<string, mixed> $args Входные аргументы после валидации схемы
   * @return array<string, mixed>|WP_Error
   */
  public static function execute(array $args): array|WP_Error
  {
      $idempotencyKey = (string) $args['idempotency_key'];
      $cacheKey = 'agentic_ability_promo_' . md5($idempotencyKey);

      // 1. Проверка идемпотентности: исключаем повторное создание при ретрае агента
      $cachedResult = get_transient($cacheKey);
      if ($cachedResult !== false && is_array($cachedResult)) {
          return $cachedResult;
      }

      $discount = (int) $args['discount_percent'];
      $email    = sanitize_email((string) $args['customer_email']);
      $days     = (int) ($args['expiry_days'] ?? 7);

      // Генерация уникального человекочитаемого кода купона
      $couponCode = strtoupper(sprintf('GIFT-%d-%s', $discount, wp_generate_password(6, false)));

      try {
          $coupon = new WC_Coupon();
          $coupon->set_code($couponCode);
          $coupon->set_discount_type('percent');
          $coupon->set_amount($discount);
          $coupon->set_individual_use(true);
          $coupon->set_usage_limit(1); // Одноразовый купон
          $coupon->set_customer_email([$email]);
          $coupon->set_date_expires(time() + ($days * DAY_IN_SECONDS));
          $coupon->set_description(sprintf('Сгенерировано AI-агентом для %s', $email));

          $couponId = $coupon->save();

          if ($couponId === 0) {
              return new WP_Error('coupon_creation_failed', __('Ошибка сохранения купона в WooCommerce.', 'agentic-lab'));
          }

          $response = [
              'success'          => true,
              'coupon_id'        => $couponId,
              'coupon_code'      => $couponCode,
              'discount_percent' => $discount,
              'customer_email'   => $email,
              'expires_at'       => gmdate('Y-m-d H:i:s', time() + ($days * DAY_IN_SECONDS)),
          ];

          // Сохраняем результат в транзиентах на 24 часа для гарантии идемпотентности
          set_transient($cacheKey, $response, DAY_IN_SECONDS);

          // Системный аудит вызова способности
          do_action('wp_ability_executed', 'agentic-lab/generate-promo-code', $response, get_current_user_id());

          return $response;
      } catch (Throwable $e) {
          return new WP_Error(
              'ability_execution_error',
              sprintf(__('Сбой выполнения способности: %s', 'agentic-lab'), $e->getMessage())
          );
      }
  }
}

// Регистрация в хуке ядра WordPress 7.0
add_action('wp_register_abilities', [CommercePromoCodeAbility::class, 'register']);