@spec create_file(bucket_id(), file_id() | nil, any(), permissions() | nil) ::
  {:ok, Appwrite.Types.File.t()}
  | {:error, Appwrite.Exceptions.AppwriteException.t()}

Create (upload) a new file in a bucket.

Accepts the file as a map with base64-encoded content (e.g. from a LiveView file hook).

Parameters

• bucket_id (String.t()): The ID of the bucket.

• file_id (String.t() | nil): Unique file ID. Auto-generated if nil.

• file (any): The file data to upload.

• permissions ([String.t()] | nil): Optional permission strings.

Returns

• {:ok, File.t()} on success.
• {:error, AppwriteException.t()} on failure.

LiveView Usage

Step 1 — fileInput.js hook

export default {
  mounted() {
    this.el.addEventListener("change", async (e) => {
      let file = e.target.files[0];
      if (file) {
        let reader = new FileReader();
        reader.onload = (event) => {
          let base64Content = event.target.result.split(",")[1];
          this.pushEvent("file_selected", {
            name: file.name, size: file.size, type: file.type, content: base64Content
          });
        };
        reader.readAsDataURL(file);
      }
    });
  },
};

Step 2 — Handle in LiveView

def handle_event("file_selected", %{"name" => name, "content" => content, ...}, socket) do
  {:noreply, assign(socket, :file_content, %{"name" => name, "data" => content, ...})}
end

def handle_event("save", _params, socket) do
  {:ok, _file} = Appwrite.Services.Storage.create_file(bucket_id, nil, socket.assigns.file_content)
  {:noreply, socket}
end

@spec delete_file(bucket_id(), file_id()) ::
  {:ok, :deleted} | {:error, Appwrite.Exceptions.AppwriteException.t()}

Delete a file by its unique ID.

Parameters

• bucket_id (String.t()): The ID of the bucket.
• file_id (String.t()): The ID of the file.

Returns

• {:ok, :deleted} on success.
• {:error, AppwriteException.t()} on failure.

@spec get_file(bucket_id(), file_id()) ::
  {:ok, Appwrite.Types.File.t()}
  | {:error, Appwrite.Exceptions.AppwriteException.t()}

Get a file's metadata by its unique ID.

Parameters

• bucket_id (String.t()): The ID of the bucket.
• file_id (String.t()): The ID of the file.

Returns

• {:ok, File.t()} on success.
• {:error, AppwriteException.t()} on failure.

@spec get_file_download(String.t(), String.t()) ::
  {:ok, String.t()} | {:error, Appwrite.Exceptions.AppwriteException.t()}

Build a file download URL.

Returns a URL that, when visited, triggers a browser download of the file (via a Content-Disposition: attachment header).

Parameters

• bucket_id (String.t()): The ID of the bucket.
• file_id (String.t()): The ID of the file.

Returns

• {:ok, String.t()} containing the download URL on success.
• {:error, AppwriteException.t()} if parameters are missing.

@spec get_file_preview(String.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, Appwrite.Exceptions.AppwriteException.t()}

Build a file preview URL.

Generates a preview of an image file. Supports optional resize and customization options as a keyword list.

Parameters

• bucket_id (String.t()): The ID of the bucket.
• file_id (String.t()): The ID of the file.
• options (keyword()): Optional preview settings such as width, height, gravity, quality, border_width, border_color, border_radius, opacity, rotation, background, output.

Returns

• {:ok, String.t()} containing the preview URL on success.
• {:error, AppwriteException.t()} if parameters are missing.

@spec get_file_view(String.t(), String.t()) ::
  {:ok, String.t()} | {:error, Appwrite.Exceptions.AppwriteException.t()}

Build a file view URL.

Returns a URL that renders the file inline in the browser (no Content-Disposition: attachment header).

Parameters

• bucket_id (String.t()): The ID of the bucket.
• file_id (String.t()): The ID of the file.

Returns

• {:ok, String.t()} containing the view URL on success.
• {:error, AppwriteException.t()} if parameters are missing.

@spec list_files(bucket_id(), queries() | nil, String.t() | nil) ::
  {:ok, Appwrite.Types.FileList.t()}
  | {:error, Appwrite.Exceptions.AppwriteException.t()}

List files in a bucket.

Parameters

• bucket_id (String.t()): The ID of the bucket.

• queries ([String.t()] | nil): Query strings to filter the results.

• search (String.t() | nil): Search term to filter files by name.

Returns

• {:ok, FileList.t()} on success.
• {:error, AppwriteException.t()} on failure.