Hooks agents et abilities

happenboard_register_abilities

Action Free src/Service/Abilities/Bootstrap.php

Signature

do_action( 'happenboard_register_abilities' )

Exemple

add_action( 'happenboard_register_abilities', function () {
    \HappenBoard\Service\Abilities\Registry::ability(
        'list-sponsors',
        array(
            'namespace'     => 'acme',
            'label'         => 'List sponsors',
            'description'   => 'Returns the sponsor names attached to an event.',
            'category'      => 'happenboard-events',
            'cap'           => 'happenboard_manage_events',
            'input_schema'  => array(
                'type'       => 'object',
                'properties' => array( 'event_id' => array( 'type' => 'integer' ) ),
                'required'   => array( 'event_id' ),
            ),
            'output_schema' => array( 'type' => 'array', 'items' => array( 'type' => 'string' ) ),
            'execute'       => fn ( $input ) => acme_sponsors_for( (int) $input['event_id'] ),
        )
    );
} );

Remarques

• Aucun argument. wp_register_ability() et le Registry de HappenBoard sont disponibles ici.
• Registry::ability( $name, $args ) prend label, description, category, cap, execute, input_schema et output_schema, plus les options namespace (par défaut happenboard), write, destructive et mcp_public.
• Utilisez votre propre espace de noms, comme dans l’exemple, et une des catégories de l’extension gratuite : happenboard-events, happenboard-booking, happenboard-attendees ou happenboard-site. WordPress refuse une ability dont la catégorie n’existe pas.
• HappenBoard Pro déclare ses abilities sur cette action en priorité 10, puis déclenche happenboard_pro_register_abilities.

happenboard_pro_register_abilities

Action Pro src/Service/Abilities/Bootstrap.php

Signature

do_action( 'happenboard_pro_register_abilities' )

Exemple

add_action( 'happenboard_pro_register_abilities', function () {
    \HappenBoard\Service\Abilities\Registry::ability(
        'flag-sponsor-ticket',
        array(
            'namespace'     => 'acme',
            'label'         => 'Flag a sponsor ticket',
            'description'   => 'Marks one ticket type as a sponsor ticket.',
            'category'      => 'happenboard-commerce',
            'cap'           => 'happenboard_manage_tickets',
            'write'         => true,
            'input_schema'  => array(
                'type'       => 'object',
                'properties' => array( 'ticket_id' => array( 'type' => 'integer' ) ),
                'required'   => array( 'ticket_id' ),
            ),
            'output_schema' => array( 'type' => 'object', 'properties' => array( 'ok' => array( 'type' => 'boolean' ) ) ),
            'execute'       => fn ( $input ) => array( 'ok' => acme_flag_sponsor_ticket( (int) $input['ticket_id'] ) ),
        )
    );
} );

Remarques

• Aucun argument. Il ne se déclenche jamais quand la surface agents est fermée ou que Pro est inactif.
• La catégorie happenboard-commerce n’existe que si Pro est actif : les abilities qui l’utilisent se déclarent sur ce hook.
• Mettez write à true pour tout ce qui modifie des données : l’ability utilise alors la limite d’écriture, est annoncée sur happenboard_ability_executed et s’appelle en POST. Ajoutez destructive pour exiger confirm: true.
• Les abilities de Pro utilisent l’espace de noms happenboard-pro. Gardez les vôtres dans le vôtre.

happenboard_ability_executed

Action Free src/Service/Abilities/Registry.php

Signature

do_action( 'happenboard_ability_executed', string $name, array $input, mixed $result, string $status )

Paramètres

$name string

Nom complet de l’ability, par exemple happenboard/create-event.

$input array<string,mixed>

Les données d’entrée, validées par le schéma de l’ability. Elles peuvent contenir des identifiants secrets : masquez-les avant de les stocker, comme le fait le journal des agents.

$result mixed

Ce que l’ability a renvoyé, ou le WP_Error par lequel l’appel a été refusé.

$status string

ok, error (l’ability a dit non, par exemple pour une réservation qui n’est pas en attente), failed (une exception a été interceptée), rate_limited, unconfirmed (un appel destructif sans confirm: true) ou forbidden (l’utilisateur n’a pas la permission).

Exemple

add_action(
    'happenboard_ability_executed',
    function ( $name, $input, $result, $status ) {
        if ( ! in_array( $status, array( 'forbidden', 'rate_limited' ), true ) ) {
            return;
        }
        error_log( sprintf(
            'Agent call %s by user %d: %s (%s)',
            $name,
            get_current_user_id(),
            $status,
            is_wp_error( $result ) ? $result->get_error_message() : ''
        ) );
    },
    10,
    4
);

Remarques

• Quatre arguments sont passés : enregistrez le hook avec 10, 4.
• Les lectures ne le déclenchent jamais. Seules les abilities déclarées avec write via le Registry de HappenBoard le font.
• Un appel forbidden le déclenche depuis le contrôle de permission, avant l’exécution, une fois par ability et par requête, et seulement pour un utilisateur connecté. $result est alors une erreur happenboard_forbidden (HTTP 403).
• Une exception levée par un écouteur est interceptée : elle ne peut pas transformer une écriture terminée en erreur. Elle arrête quand même les écouteurs suivants, dont le journal des agents en priorité 10.

happenboard_abuse_guard_denial_threshold

Action Free src/Service/Security/AbuseGuard.php

Signature

do_action( 'happenboard_abuse_guard_denial_threshold', int $actor_id, int $count )

Paramètres

$actor_id int

Identifiant de l’utilisateur connecté. Un appel sans utilisateur connecté est refusé avant tout comptage.

$count int

Refus dans la fenêtre en cours : toujours 10, le seuil.

Exemple

add_action(
    'happenboard_abuse_guard_denial_threshold',
    function ( $actor_id, $count ) {
        wp_mail(
            get_option( 'admin_email' ),
            'HappenBoard : refus répétés pour un agent',
            sprintf( 'L\'utilisateur %d a été refusé %d fois en cinq minutes.', $actor_id, $count )
        );
    },
    10,
    2
);

Remarques

• Deux arguments sont passés : enregistrez le hook avec 10, 2.
• Seuls les refus de permission comptent, en lecture comme en écriture. Une requête qui liste les abilities, comme le fait un client MCP pour ses outils, compte au plus un refus, quel que soit le nombre d’abilities interdites à l’utilisateur. Les appels limités par le débit ou non confirmés ne comptent pas.
• Il se déclenche une fois par fenêtre. Chaque refus relance la fenêtre de cinq minutes : un appelant qui insiste ne le redéclenche qu’après cinq minutes de calme puis dix nouveaux refus.