<?php
/**
 * Public API: protect your own forms with Spam Eater.
 *
 * Print the hidden fields inside your form, then check the submission in the
 * code that handles it:
 *
 *     // In the form.
 *     if ( function_exists( 'accessnow_spam_eater_field' ) ) {
 *         echo accessnow_spam_eater_field( 'my-form' ); // Already escaped.
 *     }
 *
 *     // In the handler.
 *     if ( function_exists( 'accessnow_spam_eater_is_spam' ) && accessnow_spam_eater_is_spam() ) {
 *         return new WP_Error( 'spam', sprintf( 'Your submission was blocked. [Ref: %s]', accessnow_spam_eater_fail_code() ) );
 *     }
 *
 * The check reads $_POST, so send the form as ordinary form data (a normal POST,
 * or FormData through fetch() or a REST route), never as a JSON body. Each POST
 * is checked on its own, so a multi-step form sends the fields with every step.
 *
 * The fields are filled by a small script that loads automatically on any page
 * where accessnow_spam_eater_field() was called. If your form is drawn in the
 * browser after the page loads, call window.accessnowSpamEater.fill() once its
 * markup is in the page (and turn on "Load the Spam Eater script on every page"
 * if the page itself printed no fields).
 *
 * Everything is controlled by Settings → Spam Eater → Custom forms. When that is
 * off, accessnow_spam_eater_field() returns '' and accessnow_spam_eater_is_spam()
 * returns false, so callers can use them unconditionally.
 *
 * @package AccessNow\SpamEater
 */

defined( 'ABSPATH' ) || exit;

/**
 * Hidden-field HTML to print inside a custom form.
 *
 * @param string $context Optional short name of the form (letters, digits, - and _), used in the field ID.
 * @return string Escaped HTML, or '' when custom forms are not protected.
 */
function accessnow_spam_eater_field( $context = '' ) {
	return \AccessNow\SpamEater\Plugin::instance()->api_field( $context );
}

/**
 * Whether the submission in the current request is spam.
 *
 * Contexts:
 * - 'full' (default): every check: IP block list, honeypot, JavaScript, timing and interaction.
 * - 'basic': IP block list and honeypot only, for requests that can't carry the script's values.
 * - 'login': honeypot only. Use it for login forms, which an IP block must never lock out.
 *
 * A blocked submission is counted, logged (when the log is on) and, for a filled
 * honeypot, counted towards an IP block. The result is cached for the request.
 *
 * @param string $context 'full', 'basic' or 'login'.
 * @return bool True when the submission should be refused.
 */
function accessnow_spam_eater_is_spam( $context = 'full' ) {
	return \AccessNow\SpamEater\Plugin::instance()->api_is_spam( $context );
}

/**
 * Reference code of the last failed check in this request (for example 'SE-C2'), or ''.
 *
 * Show it in the error message: visitors can quote it, and it tells you which
 * check failed without revealing how to get past it.
 *
 * @return string
 */
function accessnow_spam_eater_fail_code() {
	return \AccessNow\SpamEater\Plugin::instance()->api_fail_code();
}