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

declare( strict_types = 1 );

namespace PlugixaCrm\Core\Integrations;

use WP_Error;

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

/**
 * The contract every connector implements.
 *
 * A CONNECTOR IS NOT A MODULE, AND THE DIFFERENCE IS THE POINT. A module is a feature of this CRM: it
 * owns tables, routes and screens, and it works on its own. A connector is a *relationship with
 * something else* — WooCommerce, Google Calendar, Twilio — and everything hard about it is the other
 * end: whether the host plugin is installed, whether the credentials still work, when it last managed
 * to sync, and what to tell somebody when it stops. Those four questions are the whole of this
 * interface, and they are the questions the Integrations screen asks.
 *
 * A connector is normally *shipped* by a module, which registers it
 * through the `plugixa_crm_integrations` filter. See {@see IntegrationRegistry} for why registration
 * is a filter rather than a second directory glob.
 *
 * WHAT IS DELIBERATELY NOT HERE: `sync()`. Connectors do not agree on what syncing means — one
 * listens to WooCommerce hooks and writes as orders happen, another polls a REST API every five
 * minutes, a third receives webhooks and never polls at all. A `sync()` on this interface would be a
 * method most implementations lie about. Work that needs to happen later goes on the shared queue
 * ({@see \PlugixaCrm\Modules\Integrations\Repositories\JobRepository}) under a handler the connector
 * registers, which is a smaller and more honest contract.
 *
 * ALSO DELIBERATELY NOT HERE: `enabled()`. Whether a connector is switched on is FRAMEWORK state,
 * keyed on {@see id()}, and {@see State} owns it outright. Putting it here would mean three
 * connectors each writing their own option — which is exactly how `plugixa_crm_woo_connected` and
 * `plugixa_crm_forms_connected` came to exist under two different names, neither of which the
 * uninstaller swept. A connector may not disagree with its own switch.
 *
 * A CONNECTOR'S QUEUED WORK RUNS WITH NO CURRENT USER, AND THAT CONSTRAINS WHAT IT MAY CALL. Jobs
 * drain on cron, where `get_current_user_id()` is 0, so `Core\Security\Capabilities::user_can()`
 * opens with `user_can( 0, … )` and refuses everything. Call the concrete service —
 * `LeadService`, `ContactService`, `TaskService`, `OpportunityService`, `EntityTagService`,
 * `StreamService`, or {@see \PlugixaCrm\Modules\Integrations\Services\RecordEffects} — and NEVER
 * `Core\Entities\RecordWriter`, which checks a capability on every write and will refuse every job
 * silently enough to look like nothing happened. For the same reason, read through `RecordLoader`
 * rather than `Repository::query()`: `AccessPolicy::query_clauses()` injects `1 = 0` for a user id
 * of zero, so such a read returns no rows and reports no error.
 */
interface IntegrationInterface {

	/**
	 * Stable machine id: `woocommerce`, `google-calendar`. Used in URLs, option keys and job rows.
	 *
	 * IT OUTLIVES THE LABEL. Credentials, links and queued jobs are all keyed on it, so renaming one
	 * orphans a site's stored connection rather than renaming it. Choose it once.
	 */
	public function id(): string;

	/**
	 * What a human calls it. Translated.
	 */
	public function label(): string;

	/**
	 * One sentence on what connecting it does, for the card. Translated.
	 */
	public function description(): string;

	/**
	 * Whether this connector CAN be used on this site at all.
	 *
	 * Almost always "is the host plugin active?". Distinct from {@see connected()} on purpose: a
	 * WooCommerce connector on a site without WooCommerce is not disconnected, it is inapplicable,
	 * and telling somebody to "connect" it would send them looking for credentials that do not exist.
	 * {@see requirement()} is what the card says instead.
	 */
	public function available(): bool;

	/**
	 * Why it is unavailable, phrased for somebody who can fix it. Empty when available. Translated.
	 */
	public function requirement(): string;

	/**
	 * Whether this connector is CONFIGURED — not whether it is switched on.
	 *
	 * THE MEANING NARROWED IN 3.36.0, AND THE OLD ONE WAS A LIE. This used to read as "is it on?",
	 * and the card said Connected or Not connected accordingly — but nothing anywhere consulted it
	 * before doing work. "Disconnecting" WooCommerce changed a chip on a screen and the shop went on
	 * syncing. Being on is now {@see State}'s answer and is enforced at the point of work; this one
	 * answers only "does it have what it needs to run".
	 *
	 * The two sentences sit side by side on the card and both read correctly: a connector can be
	 * configured and switched off, or switched on and missing half its settings.
	 *
	 * A CONNECTOR WITH NO CREDENTIALS RETURNS {@see available()}, AND THAT IS HONEST RATHER THAN
	 * LAZY. WooCommerce runs in the same process; there is nothing to enter, so "nothing to
	 * configure" IS "configured". Only a connector with a {@see settings_schema()} has a second
	 * question to answer here.
	 *
	 * MUST NOT MAKE A NETWORK CALL. This is asked once per card every time the screen renders, so a
	 * connector that reached out here would make the page as slow as the slowest third party and
	 * would fail to render at all when one is down. Reachability belongs in {@see health()}, which is
	 * asked about one connector at a time and on request.
	 */
	public function connected(): bool;

	/**
	 * How the connection is actually doing.
	 *
	 * @return array{status: string, message: string} `status` is `ok`, `warning` or `error`.
	 *
	 * MAY make a network call, and callers must assume it does. `warning` is the interesting value:
	 * it is for a connection that works but is degraded — a token expiring soon, a sync that has not
	 * run since Tuesday — and having it stops a connector reporting `ok` right up to the moment it
	 * reports `error`.
	 */
	public function health(): array;

	/**
	 * The fields the connect form should show.
	 *
	 * @return array<int, array{key: string, label: string, type: string, help?: string, required?: bool}>
	 *
	 * `type` is `text`, `password` or `url`. Anything typed into a `password` field is stored through
	 * {@see Credentials} and never sent back to the client — {@see \PlugixaCrm\Modules\Integrations\Http\IntegrationsController}
	 * returns a placeholder instead, because a settings screen that renders a stored API key is a
	 * key readable by anybody who can open the browser's devtools on a shared machine.
	 */
	public function settings_schema(): array;

	/**
	 * Store a connection.
	 *
	 * MUST BE IDEMPOTENT, AND MUST NOT START WORK. This is a save button, and a save button gets
	 * pressed twice. Until 3.36.0 the WooCommerce connector started its historical import from here,
	 * and `Backfill::start()` enqueues under the dedupe key `backfill` — which {@see
	 * \PlugixaCrm\Modules\Integrations\Repositories\JobRepository::enqueue()} collapses only onto a
	 * job that is still PENDING. So once the first import had finished, every later save walked all
	 * 200,000 orders again, silently, on the site of whoever had just corrected a typo.
	 *
	 * Work that a human is asking for belongs behind a button that says so — see
	 * {@see IntegrationActionsInterface}.
	 *
	 * @param array<string, string> $input Values matching {@see settings_schema()}.
	 *
	 * @return true|WP_Error An error message a human can act on, never a code alone.
	 */
	public function connect( array $input ): bool|WP_Error;

	/**
	 * Forget the connection.
	 *
	 * MUST NOT DELETE SYNCED DATA. Disconnecting is "stop talking to them", not "undo everything you
	 * learned" — somebody reconnecting an hour later after rotating a key expects their contacts to
	 * still be there. Deleting the links is what {@see \PlugixaCrm\Modules\Integrations\Repositories\LinkRepository::forget_integration()}
	 * is for, and it is a separate, explicit action.
	 */
	public function disconnect(): void;
}