<?php
/**
 * Audit helper — the shared spine that every Easy Invoice / Pro / Addon
 * write-path can call to record a meaningful action.
 *
 * Design:
 *   • Free plugin owns the calling surface (`easy_invoice_audit_log(...)`).
 *   • The call fires an action hook (`easy_invoice_audit_event`).
 *   • The Team Roles addon's AuditLogger subscribes to that hook to write
 *     a row to its custom table — but only when the addon is active.
 *   • Webhooks (and any future addon) can subscribe to the same hook to
 *     fan out to webhook subscribers / SIEM forwarders / Slack alerts.
 *
 * Sites without the Team Roles addon never gain a wp_easy_invoice_audit_log
 * table — the call becomes a no-op write but the action still fires for
 * other listeners. Behaviour identical to before for those sites.
 */

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

if (!function_exists('easy_invoice_audit_log')) {
    /**
     * Record an auditable event.
     *
     * @param string                       $action         Short verb key, e.g. 'invoice_sent', 'payment_refunded'. ≤ 60 chars.
     * @param string                       $resource_type  e.g. 'invoice', 'quote', 'payment', 'client', 'user', 'system'.
     * @param int|string|null              $resource_id    Optional resource id (post ID, user ID, etc.).
     * @param array<string,mixed>          $details        Free-form context. Anything sensitive (PII, card numbers) MUST be redacted by the caller.
     */
    function easy_invoice_audit_log(string $action, string $resource_type = '', $resource_id = null, array $details = []): void {
        /**
         * Fired once per auditable event.
         *
         * Subscribers (in order of expected interest):
         *   • EasyInvoicePro\Addons\TeamRoles\AuditLogger::log  — writes the row
         *   • EasyInvoicePro\Addons\Webhooks\EventBridge        — fans out 'audit.event_logged'
         *   • SIEM / Slack / external forwarders                — user-installed
         *
         * @param string               $action
         * @param string               $resource_type
         * @param int|string|null      $resource_id
         * @param array<string,mixed>  $details
         */
        do_action('easy_invoice_audit_event', $action, $resource_type, $resource_id, $details);
    }
}