@spec get_latest_cursor(Magpie.Client.t(), binary(), map()) :: Magpie.response()

Gets a cursor for future changes without returning existing entries.

opts accepts the same string-keyed Dropbox argument map as list_folder/3, including "recursive", "include_deleted" and other listing fields. Defaults remain Dropbox's defaults; omitting opts keeps the existing path-only request. Returns {:ok, %{"cursor" => cursor}} or the existing API error tuple.

Persist this cursor when intentionally starting from the current state, then use list_folder_continue/2 or Magpie.Storage.continue_list/3 to read later changes. This skips the initial contents; use a full listing for a baseline snapshot or state reconstruction.

Example

{:ok, %{"cursor" => cursor}} =
  Magpie.Files.ListFolder.get_latest_cursor(client, "/path", %{
    "recursive" => true,
    "include_deleted" => true
  })

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

@spec list_folder(Magpie.Client.t(), binary(), map()) :: Magpie.response()

Starts returning the contents of a folder. opts accepts the other /files/list_folder argument fields, e.g. "recursive", "limit", "include_deleted" and "include_restorable_info".

Example

{:ok, %{"entries" => [%Magpie.FolderMetadata{} | _], "cursor" => cursor, "has_more" => true}} =
  Magpie.Files.ListFolder.list_folder(client, "/path")

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

@spec list_folder_continue(Magpie.Client.t(), binary()) :: Magpie.response()

Once a cursor has been retrieved from list_folder, use this to paginate through all files and retrieve updates to the folder, following the same rules as documented for list_folder.

Example

Magpie.Files.ListFolder.list_folder_continue(client, cursor)

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

@spec list_revisions(Magpie.Client.t(), binary(), number(), map()) ::
  Magpie.response()

Return revisions of a file, each a Magpie.FileMetadata. opts accepts the other /files/list_revisions argument fields, e.g. "mode", "before_rev" and "include_restorable_info".

Example

{:ok, %{"entries" => [%Magpie.FileMetadata{rev: rev} | _], "is_deleted" => false}} =
  Magpie.Files.ListFolder.list_revisions(client, "/report.pdf")

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

@spec longpoll(Magpie.Client.t(), binary(), pos_integer()) :: Magpie.response()

A longpoll endpoint to wait for changes on an account.

Blocks for at most timeout seconds (30 to 480), plus up to 90 seconds of jitter Dropbox adds to spread out clients. The request waits that long for the response, whatever receive_timeout the client configures.

This endpoint lives on its own host (Magpie.notify_url/0) and takes no access token — Dropbox rejects the call when one is sent.

Example

Magpie.Files.ListFolder.longpoll(client, cursor)

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

Returns a lazy Stream over all entries of a folder, fetching pages through list_folder/2 + list_folder_continue/2 on demand — no cursor handling needed. Raises Magpie.Error if a page request fails.

Example

client
|> Magpie.Files.ListFolder.stream("/Photos")
|> Stream.filter(&match?(%Magpie.FileMetadata{}, &1))
|> Enum.map(& &1.name)