Read file content: read-document for any file (Paper docs and other export-only files are exported, everything else downloaded), byte-exact downloads, Range and chunked downloads past the response cap, exports, temporary links, and Dropbox's content_hash.

Results are ::dropbox/FileContent: bytes is always the raw body (the response's body-bytes), and text is filled in when the MIME type (from the file name; Dropbox sends no useful Content-Type) is textual. The file's metadata comes from the Dropbox-API-Result header and is attached as a DocFile.

Limits. Every single response is capped by the runtime's http.max-response-bytes (16 MiB by default, 120 s timeout): download switches to Range-chunked downloads (pinned to the file's rev) when a file is larger. Exports cannot be ranged. The whole file is held in memory either way.

Scopes. files.content.read.

Values

BLOCK_SIZE

BLOCK_SIZE: Int 4194304

DEFAULT_DOWNLOAD_CHUNK

DEFAULT_DOWNLOAD_CHUNK: Int 8388608

DOWNLOAD_LOCAL_KEYS

DOWNLOAD_LOCAL_KEYS: Vec [
  "range",
  "chunk-size"
]

FORMAT_ALIASES

FORMAT_ALIASES: Map {
  md: "markdown",
  markdown: "markdown",
  htm: "html",
  html: "html",
  txt: "plain_text",
  text: "plain_text",
  plain: "plain_text",
  plain_text: "plain_text"
}

FORMAT_MIMES

FORMAT_MIMES: Map {
  markdown: "text/markdown",
  html: "text/html",
  plain_text: "text/plain",
  pdf: "application/pdf",
  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  csv: "text/csv"
}

Functions

build-content

fn (file-id: Str, bytes: Bytes, entry: Map?, name: Str?, format: Str?, source: Str): ::dropbox/FileContent

Build a FileContent (pure) from bytes, the file's metadata entry (null when unknown), the output name (the export name for exports) and the export format (null for downloads). The MIME type comes from name, else from format.

content-hash

fn (content: Bytes | Str): Str
fn (content: Bytes | Str, block-size: Int): Str

Dropbox's content_hash of some content (pure): split it into 4 MiB blocks, SHA-256 each block, concatenate the raw digests, and SHA-256 that, as lowercase hex. An empty file hashes the empty string. Use it to skip downloads of unchanged files (compare with a metadata entry's content_hash) or to check a download. The 2-arity form takes another block size (for tests).

See https://www.dropbox.com/developers/reference/content-hash.

::dropbox::content/content-hash(Bytes("hello"))
// "9595c9df90075148eb06860365df33584b75bff782a510c6cd4883a419833d50"

download

fn (path: Str): ::dropbox/FileContent
fn (path: Str, opts: Map): ::dropbox/FileContent

POST files/download (content host) - a file's exact bytes as a FileContent, with its metadata from Dropbox-API-Result. Files larger than http.max-response-bytes are fetched again in Range chunks (download-chunked). Export-only files (Paper docs) fail with 409 unsupported_file: use read-document or export.

Options: rev (a specific revision), range: {start, end} (inclusive; end null for the rest) for a partial download, chunk-size for the chunked fallback, plus credentials.

pdf ::dropbox::content/download("/Reports/Q3.pdf")
pdf.mime-type    // "application/pdf"
pdf.bytes        // exact bytes
pdf.file.rev

download-arg

fn (path: Str, opts: Map): Map

The files/download argument (pure): path, or rev:<rev> when opts.rev is set (Dropbox deprecated the separate rev field in favour of a rev: path), plus other Dropbox arguments from opts.

download-chunked

fn (path: Str): ::dropbox/FileContent
fn (path: Str, opts: Map): ::dropbox/FileContent

Download a file in Range requests of opts.chunk-size bytes (default 8 MiB; keep it under http.max-response-bytes) and join them, so files larger than one response can be read. Every chunk asks for the rev the metadata reported, so a file changing mid-download cannot mix versions. The whole file is still held in memory.

download-range

fn (path: Str, start: Int, end: Int): ::dropbox/FileContent
fn (path: Str, start: Int, end: Int, opts: Map): ::dropbox/FileContent

Download bytes start..end (inclusive) of a file.

download-ranges

fn (size: Int, chunk-size: Int): Vec

Split size bytes into inclusive [start, end] ranges of at most chunk-size bytes (pure). download-ranges(10, 4) is [[0, 3], [4, 7], [8, 9]].

download-text

fn (path: Str): Str
fn (path: Str, opts: Map): Str

Download a file and decode it as UTF-8 text.

export

fn (path: Str): ::dropbox/FileContent
fn (path: Str, format: Str?): ::dropbox/FileContent
fn (path: Str, format: Str?, opts: Map): ::dropbox/FileContent

POST files/export (content host) - export a file that cannot be downloaded directly (Paper docs, cloud docs) as a FileContent. format is checked by export-format when opts.entry (the file's metadata) is given; null uses the file's default (export_as). Dropbox answers 409 retry_error while an export is not ready yet (is-retryable is true for it).

md ::dropbox::content/export("/Notes/Roadmap.paper", "markdown")
md.text

export-format

fn (entry: Map?, format: Str?): Str?

Pick the export format for an export-only file (pure). entry is its metadata (null when unknown); format is a Dropbox format name or an alias (md/markdown, html, text/txt for plain_text), or "auto"/null. "auto" prefers markdown when the file offers it, else the file's default export_as. When the entry lists export_options, a format outside them is an Err naming the options. Returns null to let Dropbox use the default.

::dropbox::content/export-format({export_info: {export_as: "html", export_options: ["html", "markdown"]}}, "auto")
// "markdown"

fetch-ranges

fn (arg: Map, ranges: Vec, index: Int, acc: Bytes, opts: Map): Bytes
fn (path: Str): Map
fn (path: Str, opts: Map): Map

POST files/get_temporary_link - a direct download link for a file, valid for four hours: {metadata, link}. Anyone with the link can download the file, so treat it as a secret. Not available for export-only files.

hash-loop

fn (data: Bytes, block-size: Int, offset: Int, acc: Bytes): Bytes

is-size-limit-error

fn (result: Result): Bool

True when a request failed because the response exceeded http.max-response-bytes.

matches-content-hash

fn (content: Bytes | Str, expected: Str?): Bool

True when content hashes to expected (a metadata entry's content_hash). False for a null or empty expected.

range-header

fn (start: Int, end: Int?): Str

An HTTP Range value for bytes start..end inclusive (end null for "to the end"): range-header(0, 1023) is "bytes=0-1023".

read-document

fn (path: Str): ::dropbox/FileContent
fn (path: Str, format: Str?): ::dropbox/FileContent
fn (path: Str, format: Str?, opts: Map): ::dropbox/FileContent

Read any file as a FileContent with its DocFile attached.

  • Paper docs and other export-only files are exported in format ("auto" by default: Markdown when offered, else the file's default export); see export-format for the names.
  • Other files are downloaded as stored (format is ignored): text is set for textual types (.txt, .md, .csv, .json, ...) and bytes always holds the exact content.
  • Folders and deleted entries return an Err.
doc ::dropbox::content/read-document("/Notes/Roadmap.paper", "markdown")
doc.text             // Markdown, ready for chunking and embedding
doc.file.version     // the rev, for incremental re-indexing

read-document-text

fn (path: Str): Str
fn (path: Str, format: Str?): Str
fn (path: Str, format: Str?, opts: Map): Str

read-document, returning just the text; an Err when the result is not textual (a PDF, an image, ...).

response-bytes

fn (response: Map): Bytes

The exact body of a response as Bytes: body-bytes (never the auto-decoded body), else a Str body's UTF-8 bytes, else empty.