<?php

declare(strict_types=1);

namespace Instinctor\Core\Storage;

/**
 * Storage driver interface.
 *
 * All paths passed to driver methods are relative to the storage root
 * (e.g. "instinctor-chat/screenshot-1234.png").
 * Absolute resolution is handled internally by each driver.
 */

if (!defined('ABSPATH')) exit;
interface DriverInterface
{
    /**
     * Absolute path to the storage root directory (no trailing slash).
     * Optionally append a subdirectory: basedir('instinctor-chat') → /var/www/uploads/instinctor-chat
     */
    public function basedir(string $sub = ''): string;

    /**
     * Public URL to the storage root (no trailing slash).
     * Optionally append a subdirectory: baseurl('instinctor-chat') → https://example.com/wp-content/uploads/instinctor-chat
     */
    public function baseurl(string $sub = ''): string;

    /**
     * Absolute path to a file at the given relative path.
     */
    public function path(string $rel): string;

    /**
     * Public URL for a file at the given relative path.
     */
    public function url(string $rel): string;

    /**
     * Create a directory (and any missing parents) relative to storage root.
     * Returns true on success or if the directory already exists.
     */
    public function mkdir(string $rel): bool;

    /**
     * Write raw string data to a file at the given relative path.
     * Creates parent directories automatically.
     * Returns true on success.
     */
    public function put(string $rel, string $data): bool;

    /**
     * Read the contents of a file. Returns false if file does not exist.
     */
    public function get(string $rel): string|false;

    /**
     * Delete a file. Returns true on success or if file did not exist.
     */
    public function delete(string $rel): bool;

    /**
     * Check whether a file exists at the given relative path.
     */
    public function exists(string $rel): bool;

    /**
     * Return the file size in bytes. Returns 0 if file does not exist.
     */
    public function size(string $rel): int;

    /**
     * Detect the MIME type of a file at the given absolute or relative path.
     * Returns 'application/octet-stream' as fallback.
     */
    public function mime(string $path): string;
}
