<?php
/**
 * SocialPromoter Platform Connector Interface
 *
 * Every platform connector must implement this interface. Adding a new
 * platform means creating a class that implements this interface and
 * registering it in PKITS_SP_Platform_Registry — no other core files
 * need to change.
 *
 * @package PublisherKits_SocialPromoter
 */

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

/**
 * Interface PKITS_SP_Connector_Interface
 */
interface PKITS_SP_Connector_Interface {

	/**
	 * Machine-readable platform slug.
	 *
	 * Must be lowercase, no spaces. Used as database keys, CSS classes,
	 * and registry keys. Examples: 'x', 'facebook', 'linkedin', 'bluesky'.
	 *
	 * @return string
	 */
	public function get_slug();

	/**
	 * Human-readable platform label for display in the UI.
	 *
	 * @return string
	 */
	public function get_label();

	/**
	 * Short platform badge label (2-3 characters) shown in metabox checkboxes.
	 *
	 * Examples: 'X', 'FB', 'in'.
	 *
	 * @return string
	 */
	public function get_badge();

	/**
	 * Pricing tier required to use this platform.
	 *
	 * Returns 'free' or 'pro'. Used by the UI to show upgrade prompts.
	 *
	 * @return string
	 */
	public function get_tier();

	/**
	 * Maximum character limit for copy text on this platform.
	 *
	 * Returns 0 if no meaningful limit applies.
	 *
	 * @return int
	 */
	public function get_char_limit();

	/**
	 * Authentication type used by this connector.
	 *
	 * Returns one of: 'oauth1', 'oauth2', 'relay', 'apppassword'.
	 * Informs the Accounts page how to render the connect section.
	 *
	 * @return string
	 */
	public function get_auth_type();

	/**
	 * Credential fields shown on the Accounts page.
	 *
	 * Returns an array of field definitions. Each definition is an array with:
	 *   - id:    field key stored in app credentials
	 *   - label: human-readable label
	 *   - type:  'text' or 'password'
	 *
	 * Return an empty array for relay-based connectors (LinkedIn) that
	 * require no credentials to be entered by the user.
	 *
	 * @return array
	 */
	public function get_credential_fields();

	/**
	 * Description shown on the Accounts page below the platform heading.
	 *
	 * Use this for relay notes, billing warnings, or other platform-specific
	 * context that editors need before connecting.
	 *
	 * @return string HTML-safe string (will be escaped on output).
	 */
	public function get_accounts_description();

	/**
	 * Post content to this platform.
	 *
	 * @param array      $account    Connected account data (decrypted).
	 * @param string     $text       Social copy text.
	 * @param string     $url        Post URL (empty string if not applicable).
	 * @param array|null $image_data Image data from PKITS_SP_Image_Handler, or null.
	 * @return array|WP_Error Array with 'platform_post_id' on success, or WP_Error.
	 */
	public function post( array $account, $text, $url, $image_data );

	/*
	 * Engagement statistics are a Pro feature: the premium build adds a
	 * suffixed stats method to each connector. The free contract is posting
	 * and authentication only.
	 */
}
