<?php

namespace Modules\SmartStorage\Entities\Contracts;

use League\Flysystem\FilesystemAdapter;
use Modules\SmartStorage\Entities\SsSetting;

/**
 * A storage backend that Smart Storage can route files through.
 *
 * Backends self-register with the StorageDriverRegistry from the module's
 * service provider boot(). Each one knows how to build a raw Flysystem
 * adapter; the SmartStorageAdapter decorator then layers encryption,
 * indexing and access logging on top.
 */
interface StorageBackendDriver
{
    /** Stable machine key, e.g. "s3", "dropbox", "local". */
    public function key(): string;

    /** Human label for dropdowns. */
    public function label(): string;

    /**
     * True when this backend can actually be used in the current install
     * (required SDK/package present + minimum config). Unavailable backends
     * are shown but disabled in the UI.
     */
    public function isAvailable(): bool;

    /**
     * Validate the configured credentials. Return a list of human error
     * strings (empty array == OK).
     *
     * @return array<int,string>
     */
    public function validateConfig(SsSetting $settings): array;

    /**
     * Build the raw Flysystem adapter for this backend using the settings row.
     */
    public function makeAdapter(SsSetting $settings): FilesystemAdapter;
}
