---
title: "Manage your Files"
description: "Upload, list, and delete files attached to your runs"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Manage your Files}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(formr)

# So this vignette runs offline, API calls are replayed from pre-recorded
# responses (vcr cassettes shipped with the package). With a real server you
# would instead call formr_api_authenticate() with your own host/credentials.
.formr_vcr <- requireNamespace("vcr", quietly = TRUE) &&
  nzchar(system.file("extdata/vcr_cassettes", package = "formr"))

if (.formr_vcr) {
  vcr::vcr_configure(
    dir = system.file("extdata/vcr_cassettes", package = "formr"),
    filter_sensitive_data = list(
      "formr-client-id-redacted"     = "dummy_client_id",
      "formr-client-secret-redacted" = "dummy_client_secret",
      "formr-host-redacted"          = "api.localhost"
    )
  )
  vcr::use_cassette("formr_api_authenticate", {
    formr_api_authenticate(host = "http://api.localhost",
      client_id = "dummy_client_id", client_secret = "dummy_client_secret",
      verbose = FALSE)
  })
}
```

Most complex studies require more than just survey spreadsheets. For example, you might need to host images for experimental stimuli.

While the [Project Workflow](manage-your-projects.html) (`formr_api_push_project`) syncs your `files/` folder automatically, the functions below give you direct, granular control over the file storage of your run.

## Listing Files

To see what files are currently attached to your run, use `formr_api_files()`. This returns a data frame containing the file names, their public URLs, and upload timestamps.

```{r, eval = .formr_vcr}
# List all files attached to the study
vcr::use_cassette("formr_api_upload_delete_flow", {
  files <- formr_api_files("test-run")
})

# View the first few files
head(files)
```

The returned `url` column is particularly useful if you need to embed these assets in external emails or websites.

## Uploading Files

You can upload files individually or in bulk. This is useful for quickly patching a missing image or adding a new stimulus without re-syncing the entire project.

### Single File
```{r, eval = FALSE}
# Not run: needs a live formr server.
# Upload a single logo
formr_api_upload_file("my-study-name", path = "assets/logo.png")
```

### Multiple Files or Directories
The function is flexible: you can pass a vector of paths or a directory. If you pass a directory, `formr` will upload all files directly inside it.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Upload multiple specific files
formr_api_upload_file("my-study-name", path = c("assets/img1.jpg", "assets/img2.jpg"))

# Upload an entire folder of stimuli
formr_api_upload_file("my-study-name", path = "assets/stimuli/")
```

## Deleting Files

To keep your run clean, you can remove obsolete files.

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Delete a specific file
formr_api_delete_file("my-study-name", file_name = "old_logo.png")

# Delete a list of files
formr_api_delete_file("my-study-name", file_name = c("test1.jpg", "test2.jpg"))
```

### Cleaning Up (Delete All)
If you are restructuring your study and want to start fresh, you can wipe all files. **Use this with caution.**

```{r, eval = FALSE}
# Not run: needs a live formr server.
# Delete ALL files (prompts for confirmation)
formr_api_delete_all_files("my-study-name")
```