hot.dev/microsoft-onedrive / ::microsoft::onedrive::content

Read file content: read-document for any file (as stored, PDF or HTML conversion, or text), byte-exact downloads, Range and chunked downloads past the response cap, format conversion, and thumbnails.

Results are ::microsoft::onedrive/FileContent: bytes is always the raw body (a JSON file stays bytes), and text is filled in when the file is textual by MIME type or extension.

How downloads work. GET {item}/content answers 302 Found with a short-lived pre-authenticated URL, which Hot follows (without the Authorization header). Range requests go straight to the item's @microsoft.graph.downloadUrl (valid about an hour, no token), as Graph requires.

Limits. Every single response is capped by the runtime's http.max-response-bytes (16 MiB by default): download switches to Range-chunked downloads when a file is larger. Format conversion (?format=pdf / html) only accepts source files up to 2 MB.

Permissions. Files.Read / Files.Read.All (delegated), Files.Read.All or Sites.Read.All (app-only; conversion is documented as needing Files.ReadWrite.All app-only), or Sites.Selected / Files.SelectedOperations.Selected with a grant.

Values

CONVERT_MIME

CONVERT_MIME: Map {
  pdf: "application/pdf",
  html: "text/html",
  jpg: "image/jpeg",
  glb: "model/gltf-binary"
}

DEFAULT_DOWNLOAD_CHUNK

DEFAULT_DOWNLOAD_CHUNK: Int 8388608

DOWNLOAD_URL_KEY

DOWNLOAD_URL_KEY: Str "@microsoft.graph.downloadUrl"

FORMATS

FORMATS: Vec [
  "auto",
  "original",
  "pdf",
  "html",
  "text"
]

Functions

content-path

fn (item: Any, opts: Map): Str

convert

fn (item: Any, format: Str): ::microsoft::onedrive/FileContent
fn (item: Any, format: Str, opts: Map): ::microsoft::onedrive/FileContent

GET {item}/content?format={format} - download a file converted by Graph: "pdf" (Word, Excel, PowerPoint, RTF, ODF, HTML, Markdown, EML/MSG, TIFF, Loop, ...), "html" (Loop, Fluid, Whiteboard) or "jpg" (with opts.width and opts.height). The source must be at most 2 MB. Returns a FileContent with source: "convert".

pdf ::microsoft::onedrive::content/convert("/Specs/Design.docx", "pdf")

convert-params

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

The query parameters for a conversion (pure): format, plus width / height (required by Graph for jpg).

download

fn (item: Any): ::microsoft::onedrive/FileContent
fn (item: Any, opts: Map): ::microsoft::onedrive/FileContent

GET {item}/content - download a file's exact bytes as a FileContent (Hot follows Graph's 302 to the pre-authenticated URL). When the file is larger than http.max-response-bytes, it is fetched again in Range chunks (download-chunked). Shared items (remoteItem) are read from the owner's drive. opts.range: {start, end} downloads a slice.

pdf ::microsoft::onedrive::content/download("/Contracts/MSA.pdf")
pdf.mime-type   // "application/pdf"
pdf.bytes

download-chunked

fn (item: Any): ::microsoft::onedrive/FileContent
fn (item: Any, opts: Map): ::microsoft::onedrive/FileContent

Download a file in Range requests of opts.chunk-size bytes (default 8 MiB; keep it under http.max-response-bytes) from its download URL and join them, so files larger than one response can be read. The whole file is still held in memory.

download-range

fn (item: Any, start: Int, end: Int?): ::microsoft::onedrive/FileContent
fn (item: Any, start: Int, end: Int?, opts: Map): ::microsoft::onedrive/FileContent

Download bytes start..end (inclusive) of a file with a Range request on its pre-authenticated download URL (Graph ignores Range on /content). Returns a FileContent with source: "range".

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 (item: Any): Str
fn (item: Any, opts: Map): Str

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

fetch-ranges

fn (url: Str, ranges: Vec, index: 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.

item-and-url

fn (item: Any, opts: Map): Map

Fetch an item (following remoteItem) and its pre-authenticated @microsoft.graph.downloadUrl. Returns {item, url}; an Err for folders.

list-thumbnails

fn (item: Any): Vec
fn (item: Any, opts: Map): Vec

GET {item}/thumbnails - thumbnail sets (id, small, medium, large, each {url, width, height}; the URLs are short-lived and pre-authenticated).

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" (pure).

read-document

fn (item: Any): ::microsoft::onedrive/FileContent
fn (item: Any, format: Str?): ::microsoft::onedrive/FileContent
fn (item: Any, format: Str?, opts: Map): ::microsoft::onedrive/FileContent

Read any file as a FileContent with its DocFile attached, for RAG ingestion and file-triggered workflows. Shared items are followed to the owner's drive; folders return an Err. See read-plan for the formats:

• "auto" (default) / "original" - the stored bytes: Office files as-is for a text extractor (hot.dev/libreoffice, pandoc, ...), text set for .txt / .md / .csv / .json and other text
• "pdf" - a PDF: converted by Graph when the file is convertible and at most 2 MB, otherwise (or when conversion fails) the original
• "html" - Loop / Whiteboard as HTML, otherwise the original
• "text" - text files only; an Err for binaries

format on the result says what you got (original, pdf, html or text); check mime-type too.

doc ::microsoft::onedrive::content/read-document("/Specs/Design.docx", "pdf")
doc.format        // "pdf" (or "original" when the docx was over 2 MB)
doc.file.version  // eTag, for incremental re-indexing

read-document-text

fn (item: Any): Str
fn (item: Any, opts: Map): Str

read-document returning just the text; an Err when the result is not textual (Office files, PDFs, images: extract text elsewhere).

read-plan

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

Decide how read-document reads a file (pure): {action: "download" | "convert" | "error", format, reason?}. format is auto/null (as stored), original, pdf, html or text.

• pdf: a .pdf downloads; a convertible file (Office, ODF, RTF, HTML, Markdown, EML/MSG, TIFF, Loop, ...) up to 2 MB converts; anything else, or larger, downloads as stored (format: "original")
• html: Loop / Fluid / Whiteboard up to 2 MB convert; others as stored
• text: textual files (.txt, .md, .csv, .json, text/*, ...) download; others are an error (extract text elsewhere)

thumbnail

fn (item: Any): ::microsoft::onedrive/FileContent
fn (item: Any, size: Str): ::microsoft::onedrive/FileContent
fn (item: Any, size: Str, opts: Map): ::microsoft::onedrive/FileContent

Download one thumbnail image: size is "small", "medium" (default) or "large", from set opts.set (default "0"). Returns a FileContent with source: "thumbnail".

with-file

fn (content: Result, item: Map, format: Str): ::microsoft::onedrive/FileContent