<?php
/**
 * Brevo contacts resource.
 *
 * @package RewindBrevoFormBridge
 */

namespace RewindBrevoFormBridge\Api;

defined( 'ABSPATH' ) || exit;

/**
 * The contact push. Phase 3 ships upsert(); doi(), update() and
 * unlink_lists() arrive with later phases.
 *
 * @since 0.3.0
 */
class Contacts {

	/**
	 * API client.
	 *
	 * @var Client
	 */
	private Client $client;

	/**
	 * Constructor.
	 *
	 * @since 0.3.0
	 * @param Client $client API client.
	 */
	public function __construct( Client $client ) {
		$this->client = $client;
	}

	/**
	 * Create or update a contact via POST /contacts.
	 *
	 * Semantics to build against:
	 * - 201 = created; the body carries the new contact {id}.
	 * - 204 = updated; the body is EMPTY — Response already tolerates that.
	 * - 400 duplicate_parameter = the contact exists and updateEnabled was
	 *   false. The caller decides whether that is a soft success (a repeat
	 *   submitter on a feed that chose not to update) — we just report it.
	 *
	 * The payload is safe to log verbatim: the API key travels in a request
	 * header, never in the body.
	 *
	 * @since 0.3.0
	 * @param array $payload email, attributes, listIds, updateEnabled, ...
	 * @return Response
	 */
	public function upsert( array $payload ): Response {
		return $this->client->post( '/contacts', $payload );
	}
}
