<?php
/**
 * A marketplace the plugin can list on. Publishing, takedown and the queue depend only on this interface.
 *
 * Every method that talks to the marketplace applies the plugin's safety rules (pause, dry-run, rate limits)
 * and throw an exception on errors.
 *
 * @package Tidelist
 */

namespace Tidelist\Channel;

use Tidelist\Build\BuildResult;
use Tidelist\Log\Logger;

/**
 * Marketplace channel.
 *
 * A channel describes itself (label, countries, limits, settings, connect steps, error texts) and does the
 * marketplace work. The core reads these answers and contains no marketplace names or numbers.
 */
interface ChannelInterface {

	// Added to a password field's key in the settings form to remove the saved secret.
	const SECRET_CLEAR_SUFFIX = '__clear';

	/**
	 * Short machine ID (lower-case letters, digits and "-").
	 */
	public function id(): string;

	/**
	 * Name shown to the shop owner.
	 */
	public function label(): string;

	/**
	 * Whether the shop is connected to the marketplace account.
	 */
	public function is_connected(): bool;

	/**
	 * Address where the shop owner approves the connection.
	 *
	 * @param string $state        Random state value that comes back with the code.
	 * @param string $redirect_uri Registered return address.
	 */
	public function connect_url( string $state, string $redirect_uri ): string;

	/**
	 * Exchanges the one-time code from the return address for tokens and stores them.
	 *
	 * @param string $code         One-time code.
	 * @param string $redirect_uri Registered return address.
	 */
	public function exchange_code( string $code, string $redirect_uri ): void;

	/**
	 * Creates the advert. If the marketplace already has an advert with the same external ID, that one is
	 * linked instead (the outcome says so) and no duplicate is created.
	 *
	 * @param Listing $listing Listing.
	 */
	public function create( Listing $listing ): Outcome;

	/**
	 * Updates an advert.
	 *
	 * @param string  $remote_id Marketplace advert ID.
	 * @param Listing $listing   New listing.
	 */
	public function update( string $remote_id, Listing $listing ): Outcome;

	/**
	 * Takes an advert down without deleting it (it can be activated again).
	 *
	 * @param string $remote_id     Marketplace advert ID.
	 * @param string $remote_status Last known marketplace status.
	 * @param bool   $sold          True when the item was sold.
	 */
	public function deactivate( string $remote_id, string $remote_status, bool $sold ): Outcome;

	/**
	 * Puts a taken-down advert back online.
	 *
	 * @param string $remote_id Marketplace advert ID.
	 */
	public function activate( string $remote_id ): Outcome;

	/**
	 * Reads the current status of an advert.
	 *
	 * @param string $remote_id Marketplace advert ID.
	 */
	public function status( string $remote_id ): Outcome;

	/**
	 * Listing status (ListingStatus::*) for a marketplace advert status.
	 *
	 * @param string $remote_status Marketplace status.
	 */
	public function state_for( string $remote_status ): string;

	/**
	 * Why the marketplace rejected or blocked an advert, as readable text ("" if none).
	 *
	 * @param string $remote_id Marketplace advert ID.
	 */
	public function rejection_reason( string $remote_id ): string;

	/**
	 * Looks for an advert with this external ID on the connected account.
	 *
	 * @param string $external_id Shop item ID.
	 * @return Outcome|null Null when there is none.
	 */
	public function find_by_external_id( string $external_id ): ?Outcome;

	/**
	 * Every advert on the connected account (read-only), each as the marketplace returns it.
	 *
	 * @return array<int, array>
	 */
	public function remote_listings(): array;

	// ------------------------------------------------------------------ The channel describes itself.

	/**
	 * What the marketplace accepts (text lengths, photos, batch size).
	 */
	public function limits(): Limits;

	/**
	 * Whether an advert the marketplace holds back ("limited") really waits for the owner to pay. False when the
	 * owner's plan or package still has a free place for it, because the marketplace then activates it by itself
	 * a few minutes later. When this cannot be found out, the answer is true (the safe one: the batch stops).
	 *
	 * @param Outcome $outcome        The advert as the marketplace returned it.
	 * @param int     $others_waiting Adverts of the same batch that are already waiting for a place.
	 */
	public function awaits_payment( Outcome $outcome, int $others_waiting ): bool;

	/**
	 * Countries the channel works in: code => ['name' => string, 'currency' => string, 'beta' => bool].
	 * Empty when the marketplace is not country-specific.
	 *
	 * @return array<string, array{name:string, currency:string, beta:bool}>
	 */
	public function countries(): array;

	/**
	 * Settings of this channel, stored under the channel's own key. One entry per field:
	 * key, label, type (text|password|number|checkbox|select|url|tel), group (application|advert), default,
	 * and optionally options (value => label), help (text), secret (true: stored encrypted, never shown again).
	 *
	 * @return array<int, array>
	 */
	public function settings_schema(): array;

	/**
	 * The saved values of the settings fields. A secret field is not returned as text: it is true when a secret is
	 * saved and false when not.
	 *
	 * @return array<string, mixed>
	 */
	public function settings_values(): array;

	/**
	 * Checks what the owner typed in this channel's settings form and saves it. Only the fields present in the input
	 * are looked at, so one wizard step can be saved alone. A password field left empty keeps the saved secret;
	 * "<key>__clear" removes it.
	 *
	 * @param array $input Submitted values by key (unslashed, unsanitized).
	 * @return array<int, array{0:string, 1:string}> Messages for the owner: ['error'|'warning'|'success', text].
	 */
	public function save_settings( array $input ): array;

	/**
	 * Whether the owner has given everything the channel needs to build an advert besides the connection (for
	 * example a city or a region).
	 */
	public function is_configured(): bool;

	/**
	 * The steps of the connect wizard in order. Each step: id, title, done (bool), type, plus the type's own data:
	 * choice (field: settings key whose options are countries()), guide (intro, items, note), fields (fields: keys
	 * from settings_schema()), oauth (intro, connect_label, reconnect_label), status (business_note).
	 * A guide item is ['text' => string, 'link' => ['url', 'label'], 'copy' => string, 'code' => string].
	 *
	 * @return array<int, array>
	 */
	public function connect_steps(): array;

	/**
	 * Marketplace rejections in plain language. Each entry: match (a regular expression for the raw text, or an
	 * HTTP status as "status:429"), what (what happened), fix (what to do).
	 *
	 * @return array<int, array{match:string, what:string, fix:string}>
	 */
	public function error_catalogue(): array;

	/**
	 * Categories and category attributes.
	 */
	public function taxonomy(): Taxonomy;

	// ------------------------------------------------------------------ Building an advert.

	/**
	 * Currency of the adverts.
	 */
	public function currency(): string;

	/**
	 * Shop price in the advert currency (the channel's exchange rate; a shop that sells in the same currency keeps its price).
	 *
	 * @param float $shop_price Price in the shop currency.
	 */
	public function convert_price( float $shop_price ): float;

	/**
	 * The channel's own price rule, applied after the conversion (for example a clearance rule). Returns the
	 * price unchanged when the channel has no rule or it is off. The Pro add-on's price rules come after this.
	 *
	 * @param float      $price       Price in the advert currency.
	 * @param int|string $category_id Marketplace category ID (0 if unknown).
	 */
	public function adjust_price( float $price, $category_id ): float;

	/**
	 * Attribute codes the channel sets itself in complete_listing(), so the attribute mapping does not offer them.
	 *
	 * @return string[]
	 */
	public function managed_attributes(): array;

	/**
	 * Adds what only this marketplace needs (location, delivery, advertiser type) to a built listing and reports
	 * what is missing as errors or warnings.
	 *
	 * @param Listing     $listing     Listing (changed in place).
	 * @param BuildResult $result      Result that takes errors and warnings.
	 * @param array       $definitions Attribute definitions of the listing's category.
	 */
	public function complete_listing( Listing $listing, BuildResult $result, array $definitions ): void;

	/**
	 * The exact data sent to the marketplace for a listing (shown in the preview).
	 *
	 * @param Listing $listing Listing.
	 */
	public function request_body( Listing $listing ): array;

	// ------------------------------------------------------------------ The connection.

	/**
	 * State of the connection (credentials saved, account, expiry).
	 */
	public function connection(): Connection;

	/**
	 * Address the marketplace sends the owner back to after the consent screen ('' if the channel needs none).
	 */
	public function redirect_uri(): string;

	/**
	 * Forgets the connected account's tokens.
	 */
	public function disconnect(): void;

	/**
	 * Read-only check of the connection; returns a sentence for the owner.
	 *
	 * @throws \Tidelist\Channel\Exception\ChannelException On failure.
	 */
	public function test_connection(): string;

	/**
	 * Reads the connected account from the marketplace and stores its display name.
	 *
	 * @return string Display name.
	 * @throws \Tidelist\Channel\Exception\ChannelException On failure.
	 */
	public function load_account(): string;

	/**
	 * Daily upkeep of the connection (renews tokens, warns before it runs out).
	 *
	 * @param Logger $log Logger.
	 */
	public function maintain( Logger $log ): void;
}