<?php
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Abstrakte Basisklasse für alle Storage-Provider.
 *
 * Jeder Adapter implementiert diese Methoden. Callers arbeiten immer
 * über CCGAL_Storage::adapter()-> und kennen den konkreten Provider nicht.
 */
abstract class CCGAL_Storage_Adapter {

	// ── Provider-Identität ────────────────────────────────────────────────

	abstract public function get_provider_key(): string;

	abstract public function get_folder_label(): string;

	// ── Auth ──────────────────────────────────────────────────────────────

	abstract public function is_connected(): bool;

	/** Registriert provider-spezifische WP-Hooks (OAuth-Actions etc.). */
	abstract public function register_hooks(): void;

	// ── Ordner-ID-Extraktion ──────────────────────────────────────────────

	/** Extrahiert die Ordner-ID aus URL, rohem Input oder gibt ID unverändert zurück. */
	abstract public function sanitize_folder_id( string $raw ): string;

	// ── Storage-Operationen ───────────────────────────────────────────────

	/**
	 * Listet Dateien eines Ordners auf.
	 *
	 * @return array{files: array, next_page_token: string}|WP_Error
	 *   files: normalisierte File-Objekte (id, name, mimeType, size, createdTime,
	 *          thumbnailLink, imageMediaMetadata{width,height})
	 */
	abstract public function list_folder(
		string $folder_id,
		int $page_size = 20,
		string $page_token = '',
		string $order_by = 'name_natural'
	);

	/** @return array|WP_Error */
	abstract public function get_file_meta( string $file_id );

	/** @return true|WP_Error */
	abstract public function download_to_file( string $file_id, string $dest_path );

	/** @return string|WP_Error */
	abstract public function get_media_download_url( string $file_id );

	/** @return true|WP_Error */
	abstract public function stream_to_output( string $file_id, $callback = null, string $range = '' );

	/** @return true|WP_Error */
	abstract public function download_thumbnail( string $file_id, int $max_dim, string $dest_path );

	/** @return array file_id => {name, width, height, thumbnailLink} */
	abstract public function get_folder_file_map( string $folder_id, bool $force_refresh = false ): array;

	/** @return string|WP_Error */
	abstract public function get_folder_name( string $folder_id );

	abstract public function file_in_folder( string $file_id, string $folder_id ): bool;

	// ── Konkrete Helfer (für alle Provider identisch) ─────────────────────

	/**
	 * Bereinigt eine Datei-ID. Erlaubt [A-Za-z0-9_\-:] — der Doppelpunkt
	 * ist nötig für Dropbox-IDs (Format id:abc123).
	 */
	/**
	 * Statischer Helfer für Stellen ohne Adapter-Instanz (z. B. Tracking).
	 */
	public static function sanitize( string $id ): string {
		$id = preg_replace( '/[^A-Za-z0-9_\-:]/', '', (string) $id );
		if ( strlen( $id ) > 128 ) {
			$id = substr( $id, 0, 128 );
		}
		return $id;
	}

	public function sanitize_file_id( string $id ): string {
		$id = preg_replace( '/[^A-Za-z0-9_\-:]/', '', (string) $id );
		if ( strlen( $id ) > 128 ) {
			$id = substr( $id, 0, 128 );
		}
		return $id;
	}

	/**
	 * Passt einen Thumbnail-Link auf eine Zielgröße an.
	 * Default: Link unverändert zurückgeben.
	 * Google-Drive-Adapter überschreibt dies mit CDN-URL-Manipulation.
	 */
	public function resize_thumbnail_link( string $link, int $max_dim ): string {
		return $link;
	}

	public static function is_image_mime( string $mime ): bool {
		return 0 === strpos( (string) $mime, 'image/' );
	}

	public static function is_video_mime( string $mime ): bool {
		return 0 === strpos( (string) $mime, 'video/' );
	}

	public static function is_media_mime( string $mime ): bool {
		return self::is_image_mime( $mime ) || self::is_video_mime( $mime );
	}
}
