<?php
namespace R2_Offload\Storage;

defined( 'ABSPATH' ) || exit;

/**
 * Common contract every storage backend implements.
 *
 * Object keys passed to these methods are already prefixed (provider-agnostic
 * full object path, e.g. "wp-content/uploads/2024/01/img.jpg").
 */
interface Storage_Client {

	/** True when SDK/transport present AND credentials configured. */
	public function is_available(): bool;

	/**
	 * Upload a local file to the given object key.
	 *
	 * @return array{name:string,size:int}
	 * @throws \RuntimeException on hard failure.
	 */
	public function upload_file( string $local_path, string $object_name, string $mime = '' ): array;

	/**
	 * HEAD an object.
	 *
	 * @return array{size:int,md5:string,etag:string}|null Null when object absent.
	 */
	public function head_object( string $object_name ): ?array;

	/** Download an object to a local path. */
	public function download_object( string $object_name, string $target_path ): bool;

	/** Delete an object (best-effort, never throws). */
	public function delete_object( string $object_name ): void;

	/**
	 * Connectivity / credential check.
	 *
	 * @return array{ok:bool,message:string}
	 */
	public function test_connection(): array;
}
