<?php

/**
 * Interface iCloudActions
 * Complete interface for cloud migration and file operations
 */
interface iCloudActions {
    /**
     * Initialize cloud application with bucket
     * @param string $bucket
     * @return mixed
     */
    public function upcasted_init( string $bucket );

    // ========== FILE OPERATIONS ==========
    /**
     * Upload file to S3 with duplicate protection
     * @param string $local_file_path
     * @param string $s3_relative_path
     * @return array|false
     */
    public function upload_file_to_s3( $local_file_path, $s3_relative_path = null );

    /**
     * Get attached file URL with cloud integration
     * @param string $file
     * @param int $attachment_id
     * @return string
     */
    public function upcasted_get_attached_file( $file, $attachment_id ) : string;

    /**
     * Delete attachment from cloud storage
     * @param int $post_id
     * @return mixed
     */
    public function upcasted_delete_attachment( $post_id );

    /**
     * Create new S3 bucket
     * @param string $bucketName
     * @return mixed
     */
    public function upcasted_create_bucket( string $bucketName );

    // ========== WORDPRESS FILTER/ACTION HOOKS ==========
    /**
     * Calculate image srcset with S3 URLs
     * @param array $sources
     * @param array $size_array
     * @param string $image_src
     * @param array $image_meta
     * @param int $attachment_id
     * @return array
     */
    public function upcasted_calculate_image_srcset(
        array $sources,
        array $size_array,
        string $image_src,
        array $image_meta,
        int $attachment_id
    );

    /**
     * Upload intermediate size to S3
     * @param string $attachment_path
     * @return string
     */
    public function upcasted_image_make_intermediate_size( string $attachment_path ) : string;

    /**
     * Update attachment metadata
     * @param array $data
     * @param int $post_id
     * @return array
     */
    public function upcasted_update_attachment_metadata( $data, $post_id );

    /**
     * Get attachment URL (S3 or local)
     * @param string $path
     * @param int $attachment_id
     * @return string
     */
    public function upcasted_get_attachment_url( $path, $attachment_id ) : string;

    /**
     * Check if MIME type is allowed for S3 upload
     * @param int|string $attachment_id_or_path
     * @return bool
     */
    public function upcasted_check_mime_type( $attachment_id_or_path );

    /**
     * Generate attachment metadata and upload to S3
     * @param array $metadata
     * @param int $attachment_id
     * @param string|null $context
     * @return array
     */
    public function upcasted_generate_attachment_metadata( $metadata, $attachment_id, $context = null );

    /**
     * Generate incremented filename for duplicates
     * @param string $file_name
     * @return string
     */
    public function upcasted_append_duplicate_name( $file_name ) : string;

}
