Transfers files through the signed URLs returned by the Gaiia API.

File metadata and signed URLs still come from normal GraphQL operations. Downloads first select a file's URL, then fetch it directly:

{:ok, %{"pdf" => %{"url" => url}}} =
  Gaiia.Queries.invoice(client, %{"id" => invoice_id}, "pdf { url }")

{:ok, contents} = Gaiia.Files.download(url)
# Or, without holding the file in memory:
{:ok, path} = Gaiia.Files.download_to(url, "invoice.pdf")

Signed URLs expire. Re-run the GraphQL query to obtain a fresh URL rather than retrying an expired URL.

Uploads use two GraphQL mutations around one raw file transfer:

upload_input = %{"name" => "invoice.pdf", "contentType" => "application/pdf"}

{:ok, %{"uploadUrl" => %{"url" => url, "fileKey" => file_key}}} =
  Gaiia.Mutations.create_document_upload_url(
    client,
    %{"input" => upload_input},
    "uploadUrl { url fileKey }"
  )

:ok = Gaiia.Files.upload(url, {:file, "invoice.pdf"}, "application/pdf")

document_input = %{
  "fileKey" => file_key,
  "name" => "Invoice",
  "accountId" => account_id
}

{:ok, document} =
  Gaiia.Mutations.create_document(
    client,
    %{"input" => document_input},
    "document { id name }"
  )

The signed file host receives neither the Gaiia API key nor a GraphQL request. Contract and ticket-comment attachment uploads follow the same three stages with their corresponding generated mutations.