@callback delete_file(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  file_path :: String.t()
) ::
  :ok | {:error, term()}

Deletes a file from the storage provider.

Parameters

• bucket - The bucket configuration
• file_path - Path to the file in storage

Returns

• :ok - File deleted successfully
• {:error, reason} - Failed to delete file

@callback file_exists?(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  file_path :: String.t()
) ::
  boolean()

Checks if a file exists in the storage provider.

Parameters

• bucket - The bucket configuration
• file_path - Path to the file in storage

Returns

• true if file exists, false otherwise

@callback public_url(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  file_path :: String.t()
) ::
  String.t() | nil

Gets a public URL for a file in the storage provider.

Parameters

• bucket - The bucket configuration
• file_path - Path to the file in storage

Returns

• Public URL string or nil if not applicable

@callback retrieve_file(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  file_path :: String.t(),
  destination_path :: String.t()
) :: :ok | {:error, term()}

Retrieves a file from the storage provider.

Parameters

• bucket - The bucket configuration
• file_path - Path to the file in storage
• destination_path - Local path where to save the file

Returns

• {:ok, file_path} - File retrieved successfully
• {:error, reason} - Failed to retrieve file

@callback signed_download_url(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  file_path :: String.t(),
  opts :: keyword()
) :: {:ok, String.t()} | {:error, term()}

A short-lived URL that downloads file_path straight from the bucket, answered with the response headers given in opts instead of the object's stored ones — so a file the app would never show in place (an uploaded HTML page, an SVG) downloads from the bucket rather than rendering on the bucket's origin.

Options

• :disposition - the Content-Disposition the bucket must answer with
• :content_type - the Content-Type the bucket must answer with
• :expires_in - seconds the URL stays valid

Returns

• {:ok, url} - a signed URL
• {:error, reason} - no URL could be signed; the caller proxies instead

Optional: a provider without it is proxied for such files.

@callback store_file(
  bucket :: PhoenixKit.Modules.Storage.Bucket.t(),
  source_path :: String.t(),
  destination_path :: String.t(),
  opts :: keyword()
) :: {:ok, String.t()} | {:error, term()}

Stores a file in the storage provider.

Parameters

• bucket - The bucket configuration
• source_path - Path to the source file on local filesystem
• destination_path - Relative path where to store the file
• opts - Additional options

Returns

• {:ok, url} - File stored successfully, returns public URL
• {:error, reason} - Failed to store file

@callback test_connection(bucket :: PhoenixKit.Modules.Storage.Bucket.t()) ::
  :ok | {:error, term()}

Tests the connection to the storage provider.

Parameters

• bucket - The bucket configuration

Returns

• :ok - Connection successful
• {:error, reason} - Connection failed