<?php

declare(strict_types=1);

namespace Plugin\tnt_stabila_shop\src\Helper;

/**
 * Pure builder for the JSON payload delivered to a merchant-configured outbound
 * webhook when the {@see AlertChannelRouter::CHANNEL_WEBHOOK} channel fires.
 *
 * The shape is deterministic and JSON-serializable: the same inputs always yield
 * the same associative array in the same key order, so the payload is fully unit
 * testable. The function is pure — no I/O, no globals and NO clock: the event
 * timestamp is PASSED IN by the caller rather than read from {@see time()}, so a
 * test can assert an exact payload for a fixed instant.
 *
 * Caller-supplied {@see $extra} context is merged UNDER the canonical top-level
 * keys, i.e. it can add new keys but can never overwrite severity/message/shop/
 * timestamp, keeping the core contract stable for downstream consumers.
 */
final class WebhookPayloadBuilder
{
    /**
     * Build the deterministic webhook payload.
     *
     * @param string               $severity  Sentry severity label (e.g. "warning", "error", "fatal").
     * @param string               $message   Human-readable alert message / exception summary.
     * @param string               $shopName  Identifier of the originating shop (name or URL).
     * @param int                  $timestamp Event time as a Unix timestamp, PASSED IN by the caller.
     * @param array<string, mixed> $extra     Optional extra context merged under the canonical keys.
     * @return array<string, mixed> Deterministic, JSON-serializable payload.
     */
    public static function build(
        string $severity,
        string $message,
        string $shopName,
        int $timestamp,
        array $extra = []
    ): array {
        // Extra context first, then the canonical keys, so the core contract can
        // never be overwritten by caller-supplied extras.
        return \array_merge($extra, [
            'severity'  => $severity,
            'message'   => $message,
            'shop'      => $shopName,
            'timestamp' => $timestamp,
        ]);
    }
}
