<?php
namespace flow\social\publisher;
if (!defined('WPINC'))
	die;

/**
 * Flow-Flow Publishing Interface.
 *
 * Contract for all network-specific publishers.
 * Each publisher is responsible for dispatching a single post
 * to its target social network via the relevant API.
 *
 * @package   FlowFlow
 * @author    Looks Awesome <email@looks-awesome.com>
 * @link      http://looks-awesome.com
 * @copyright Looks Awesome
 */
interface FFPublisherInterface {

	/**
	 * Get the network identifier (e.g. 'facebook', 'instagram', 'linkedin', 'youtube').
	 *
	 * @return string
	 */
	public function getNetwork();

	/**
	 * Publish content to the target network.
	 *
	 * @param array $postData {
	 *     @type string $text       The post body / caption.
	 *     @type string $link       Optional URL to share.
	 *     @type array  $media      Optional media attachments [{url, type, mime}].
	 *     @type string $account_id The target account/page/channel identifier.
	 *     @type string $token      The OAuth access token.
	 *     @type array  $extra      Network-specific extra fields (e.g. YouTube privacy, tags).
	 * }
	 *
	 * @return array {
	 *     @type bool   $success    Whether the publish succeeded.
	 *     @type string $post_id    The remote post ID returned by the API (if any).
	 *     @type string $post_url   The permalink to the published post (if any).
	 *     @type string $error      Error message on failure.
	 *     @type array  $raw        Raw API response for debugging.
	 * }
	 */
	public function publish(array $postData);

	/**
	 * Check whether the current credentials are valid for publishing.
	 *
	 * @param string $token The OAuth access token.
	 * @return bool
	 */
	public function canPublish($token);
}
