<?php

/**
 * @package     MokoSuiteBackup
 * @subpackage  com_mokosuitebackup
 * @author      Moko Consulting <hello@mokoconsulting.tech>
 * @copyright   Copyright (C) 2026 Moko Consulting. All rights reserved.
 * @license     GNU General Public License version 3 or later; see LICENSE
 */

namespace Joomla\Component\MokoSuiteBackup\Administrator\Engine;

defined('_JEXEC') or die;

interface RemoteUploaderInterface
{
	/**
	 * Upload a file to remote storage.
	 *
	 * @param   string  $localPath   Absolute path to the local file
	 * @param   string  $remoteName  Filename to use on the remote end
	 *
	 * @return  array{success: bool, message: string, remote_path?: string}
	 */
	public function upload(string $localPath, string $remoteName): array;

	/**
	 * Delete a previously-uploaded file from remote storage.
	 *
	 * Used by retention pruning so that expiring a local backup also removes
	 * its archive from every remote destination. Implementations should treat
	 * an already-absent remote file as success (idempotent delete), so a
	 * partially-cleaned destination never blocks pruning.
	 *
	 * @param   string  $remoteName  Filename on the remote end (the same
	 *                               $remoteName that was passed to upload())
	 *
	 * @return  array{success: bool, message: string}
	 */
	public function delete(string $remoteName): array;

	/**
	 * Test the connection / credentials without uploading.
	 *
	 * @return  array{success: bool, message: string}
	 */
	public function testConnection(): array;
}