<?php
/**
 * @package PlugixaCrm
 */

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Integrations;

use WP_Error;

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

/**
 * Things a connector can be ASKED to do, once, by somebody who meant it.
 *
 * IT EXISTS BECAUSE A SIDE EFFECT HIDING INSIDE A SAVE IS A BUG WITH A LONG FUSE. WooCommerce's
 * historical import used to start from {@see IntegrationInterface::connect()}: press Save, and the
 * connector walked every order the shop had ever taken. That is defensible exactly once, on the day
 * somebody first connects it, and indefensible on every subsequent save — and because
 * `Backfill::start()` enqueues under a fixed dedupe key that only collapses onto a still-PENDING
 * job, the second save really did start the whole walk again. Nothing in the UI said so.
 *
 * The fix is not a cleverer guard inside `connect()`. It is a button that says "Import order
 * history", which is a different sentence from "Save", and which a person presses on purpose.
 *
 * OPTIONAL, AND CHECKED WITH `instanceof`, like {@see IntegrationOptionsInterface}. Most connectors
 * will implement it eventually — "Test connection" and "Resync now" are the two every third-party
 * API wants — but a connector that has nothing to offer should not have to write two empty methods
 * to say so.
 *
 * AN ACTION IS EXPECTED TO BE CHEAP AND TO DELEGATE. It runs inside an admin's REST request, so it
 * must not be the work itself: it queues the work and returns. Anything that could take longer than
 * a page load belongs on the shared queue, where the Configure screen's job log can show what
 * happened to it.
 */
interface IntegrationActionsInterface {

	/**
	 * What this connector can be asked to do.
	 *
	 * `confirm` is the prompt shown before running, for anything a person could regret. Omit it for
	 * an action that is merely useful — a connection test needs no ceremony — and supply it for
	 * anything that writes records, costs money at the other end, or takes an hour.
	 *
	 * @return array<int, array{key: string, label: string, description: string, confirm?: string}>
	 */
	public function actions(): array;

	/**
	 * Run one.
	 *
	 * MUST REFUSE A KEY IT DOES NOT KNOW rather than doing nothing and reporting success. The
	 * controller checks the connector is installed and that the caller may administer the site; only
	 * the connector knows whether `resync-everything` is one of its own.
	 *
	 * @param string $key One of {@see actions()}'s keys.
	 *
	 * @return true|WP_Error An error message a human can act on, never a code alone.
	 */
	public function run_action( string $key ): bool|WP_Error;
}