@spec copy(Magpie.Client.t(), binary(), binary()) ::
  {:ok, Magpie.FileMetadata.t() | Magpie.FolderMetadata.t()}
  | {:error, Magpie.Error.t()}

Copy a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be copied.

Returns the metadata of the copy.

Example

{:ok, %Magpie.FileMetadata{path_display: "/Tmp/second"}} =
  Magpie.Files.copy(client, "/Temp/first", "/Tmp/second")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-copy_v2

@spec create_folder(Magpie.Client.t(), binary()) ::
  {:ok, Magpie.FolderMetadata.t()} | {:error, Magpie.Error.t()}

Create a folder at a given path. Returns the new folder's Magpie.FolderMetadata.

Example

{:ok, %Magpie.FolderMetadata{id: "id:" <> _}} = Magpie.Files.create_folder(client, "/Path")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-create_folder

@spec create_folder_to_struct(Magpie.Client.t(), binary()) ::
  {:ok, Magpie.Folder.t()} | {:error, Magpie.Error.t()}

Same as create_folder/2 but returns {:ok, %Magpie.Folder{}}.

Deprecated: create_folder/2 itself returns a typed Magpie.FolderMetadata since 0.4.0.

@spec delete_folder(Magpie.Client.t(), binary(), map()) ::
  {:ok, Magpie.FileMetadata.t() | Magpie.FolderMetadata.t()}
  | {:error, Magpie.Error.t()}

Delete the file or folder at a given path. If the path is a folder, all its contents will be deleted too. A successful response indicates that the file or folder was deleted. The returned metadata will be the corresponding FileMetadata or FolderMetadata for the item at time of deletion, and not a DeletedMetadata object.

Returns the Magpie.FileMetadata or Magpie.FolderMetadata of the deleted item. opts accepts Dropbox's optional "parent_rev" field.

Example

{:ok, %Magpie.FileMetadata{}} =
  Magpie.Files.delete_folder(client, "/Homework/math/Prime_Numbers.txt")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-delete_v2

@spec delete_folder_to_struct(Magpie.Client.t(), binary()) ::
  {:ok, Magpie.Folder.t()} | {:error, Magpie.Error.t()}

Same as delete_folder/2 but returns {:ok, %Magpie.Folder{}}.

Deprecated: delete_folder/2 itself returns typed metadata since 0.4.0.

Download a file from a user's Dropbox.

Example

Magpie.Files.download client, "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-download

@spec download_file(Magpie.Client.t(), binary(), Path.t()) ::
  {:ok, %{path: Path.t(), headers: list() | map()}}
  | {:error, Magpie.Error.t() | File.posix()}

Streams a Dropbox file directly to destination without loading it into BEAM memory. The destination is replaced only after a successful response.

Returns {:ok, %{path: destination, headers: headers}}, a normalized Dropbox API error, or {:error, posix} for a local filesystem error.

Download a folder from the user's Dropbox as a zip file.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-download_zip

Export a file from the user's Dropbox to a portable format (for files that cannot be downloaded directly, e.g. Paper docs). opts accepts "export_format".

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-export

@spec get_metadata(Magpie.Client.t(), binary(), boolean(), boolean(), boolean()) ::
  {:ok, Magpie.Metadata.t()} | {:error, Magpie.Error.t()}

Returns the metadata for a file or folder as a Magpie.FileMetadata, Magpie.FolderMetadata or — with include_deleted — Magpie.DeletedMetadata.

Example

{:ok, %Magpie.FileMetadata{size: size, server_modified: %DateTime{}}} =
  Magpie.Files.get_metadata(client, "/mypdf.pdf")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_metadata

Get a preview for a file.

Example

Magpie.Files.get_preview client, "/mypdf.pdf"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_preview

Get a temporary link to stream content of a file. This link will expire in four hours and afterwards you will get 410 Gone. Content-Type of the link is determined automatically by the file's mime type.

Example

Magpie.Files.get_temporary_link client, "/video.mp4"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_preview

Get a one-time-use temporary upload link for a direct binary upload. commit_info takes the /files/upload argument fields, e.g. %{"path" => "/a.txt", "mode" => "add"}; duration is in seconds.

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_temporary_upload_link

Get a thumbnail for an image.

Example

Magpie.Files.get_thumbnail client, "/image.jpg"

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail

Get thumbnails for a list of images. We allow up to 25 thumbnails in a single batch.

Example

batch = %{ "path" => "/image.jpg", "format" => "jpeg", "size" => "w64h64"} entries = [batch] Magpie.Files.get_thumbnail_batch client, entries

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail_batch

Get a thumbnail for an image or document, addressed by path or shared link. resource is %{".tag" => "path", "path" => ...} or %{".tag" => "link", "url" => ...}; opts accepts "format", "size" and "mode".

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-get_thumbnail_v2

@spec move(Magpie.Client.t(), binary(), binary()) ::
  {:ok, Magpie.FileMetadata.t() | Magpie.FolderMetadata.t()}
  | {:error, Magpie.Error.t()}

Move a file or folder to a different location in the user's Dropbox. If the source path is a folder all its contents will be moved.

Returns the metadata at the new location.

Example

{:ok, %Magpie.FolderMetadata{name: "algebra"}} =
  Magpie.Files.move(client, "/Homework/math", "/Homework/algebra")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-move_v2

Permanently delete the file or folder at a given path. Requires a Dropbox Business account with Advanced or Enterprise plan. opts accepts "parent_rev".

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-permanently_delete

@spec restore(Magpie.Client.t(), binary(), binary()) ::
  {:ok, Magpie.FileMetadata.t()} | {:error, Magpie.Error.t()}

Restore a file to a specific revision. Returns the restored file's Magpie.FileMetadata.

Example

{:ok, %Magpie.FileMetadata{rev: rev}} =
  Magpie.Files.restore(client, "/root/word.docx", "a1c10ce0dd78")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-restore

Searches for files and folders.

options accepts the SearchOptions fields, e.g. %{"path" => "/Photos", "max_results" => 100, "filename_only" => true}.

Each match's "metadata" is decoded into a Magpie.FileMetadata / Magpie.FolderMetadata struct (see Magpie.Metadata.decode_matches/1); the rest of the match ("match_type", "highlights") is kept as is.

Example

{:ok, %{"matches" => [%{"metadata" => %Magpie.FileMetadata{}} | _]}} =
  Magpie.Files.search(client, "word.docx", %{"path" => "/root"})

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-search_v2

Fetches the next page of search results returned from search/3.

Example

Magpie.Files.search_continue(client, cursor)

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-search-continue_v2

Returns a lazy Stream over all search matches, fetching pages through search/3 + search_continue/2 on demand. Raises Magpie.Error if a page request fails.

Example

client
|> Magpie.Files.search_stream("report", %{"path" => "/Work"})
|> Enum.take(50)
|> Enum.map(fn %{"metadata" => %Magpie.FileMetadata{} = file} -> file.path_display end)

Create a new file with the contents of the local file at file. Returns the Magpie.FileMetadata of the uploaded file.

Example

{:ok, %Magpie.FileMetadata{content_hash: hash}} =
  Magpie.Files.upload(client, "/mypdf.pdf", "/mypdf.pdf")

More info at: https://www.dropbox.com/developers/documentation/http/documentation#files-upload

@spec upload_data(Magpie.Client.t(), binary(), iodata(), keyword()) ::
  {:ok, Magpie.FileMetadata.t()} | {:error, Magpie.Error.t()}

Uploads binary or iodata content, selecting a single request or an upload session from its byte size. For an enumerable whose size is not known in advance, use upload_stream/4.

Uploads the local file at local_path to path in the user's Dropbox, picking the right strategy automatically:

• files up to :session_threshold bytes go through a single /files/upload call;
• larger files are streamed through an upload session (start → append_v2 × N → finish) in chunks of :chunk_size bytes, without ever loading the whole file into memory.

Returns {:ok, %Magpie.FileMetadata{}} on success, {:error, %Magpie.Error{}} on Dropbox errors, or {:error, posix} when the local file cannot be read.

Options

• :chunk_size — upload session chunk size in bytes (default 8 MiB)
• :session_threshold — size above which an upload session is used (default 150 MiB, the Dropbox limit for single-request uploads)
• :mode — "add" (default) or "overwrite"
• :autorename — default true
• :mute — default false

Example

{:ok, %Magpie.FileMetadata{size: size, content_hash: hash}} =
  Magpie.Files.upload_file(client, "/Backup/db.dump", "priv/db.dump")

@spec upload_stream(Magpie.Client.t(), binary(), Enumerable.t(), keyword()) ::
  {:ok, Magpie.FileMetadata.t()} | {:error, Magpie.Error.t()}

Streams an enumerable of binary or iodata chunks into a Dropbox upload session. Chunks from the enumerable may have any size; Magpie buffers at most one configured upload chunk and sends the final partial chunk with the commit request.