<?php

namespace App\Services\Storage;

use CodeIgniter\HTTP\Files\UploadedFile;
use CodeIgniter\HTTP\ResponseInterface;

interface FileStorageInterface
{
    /**
     * Upload from a CI4 UploadedFile or a local filesystem path.
     *
     * @param array{content_type?: string} $options
     */
    public function upload(UploadedFile|string $source, string $key, array $options = []): string;

    /**
     * Upload raw string/binary content.
     *
     * @param array{content_type?: string} $options
     */
    public function put(string $key, string $contents, array $options = []): string;

    public function exists(string $key): bool;

    public function delete(string $key): bool;

    public function read(string $key): string;

    /** Download object to a local temp file and return its path. */
    public function downloadToTemp(string $key): string;

    public function streamDownload(string $key, ?string $downloadName = null): ResponseInterface;

    public function temporaryUrl(string $key, int $ttlSeconds = 900): string;

    public function url(string $key): string;

    public function copy(string $fromKey, string $toKey): bool;
}
