Uploads: binary-safe simple uploads (one PUT) for small files, and resumable upload sessions (createUploadSession) for large ones. upload-file and replace-content pick for you: simple up to 4 MiB, a session above.

Content may be Bytes (sent verbatim), a Str (its UTF-8 bytes), or a Map/Vec (sent as JSON).

Upload sessions. create-upload-session returns an UploadSession with a pre-authenticated upload-url (keep it to resume). Bytes are PUT to it in order, in chunks that are multiples of 320 KiB (327,680 bytes) and under 60 MiB; the default is 10 MiB (opts.chunk-size, rounded down to a 320 KiB multiple; Microsoft recommends 5-10 MiB). Chunk PUTs carry no Authorization header (Graph may answer 401 if they do). A chunk whose connection drops is resent once, at once; any other failure (429, 5xx, 416) stops with an Err: call resume-upload later (for example from a run retry policy), which asks the session for nextExpectedRanges and sends the rest. A session expires when no chunk arrives before its expiration; 404 means start again. cancel-upload-session discards one.

Conflicts. opts.conflict is "replace" (default for upload-file; OneDrive keeps the old content as a version), "rename" or "fail".

Permissions. Files.ReadWrite (own drive), Files.ReadWrite.All, Sites.ReadWrite.All, or Sites.Selected / Files.SelectedOperations.Selected with a write grant. App-only cannot replace the content of a file protected by a sensitivity label.

Values

`CHUNK_ALIGN`

CHUNK_ALIGN: Int 327680

`DEFAULT_CHUNK_SIZE`

DEFAULT_CHUNK_SIZE: Int 10485760

`DEFAULT_CONFLICT`

DEFAULT_CONFLICT: Str "replace"

`MAX_CHUNK_SIZE`

MAX_CHUNK_SIZE: Int 62586880

`SIMPLE_UPLOAD_LIMIT`

SIMPLE_UPLOAD_LIMIT: Int 4194304

Functions

`align-chunk-size`

fn (size: Int): Int

Round a chunk size down to a multiple of 320 KiB (327,680 bytes), at least 320 KiB and under 60 MiB (pure).

`build-session-body`

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

The createUploadSession body (pure): {item: {@microsoft.graph.conflictBehavior, description?, fileSize?}, deferCommit?}. Unset options are omitted.

`cancel-upload-session`

fn (upload-url: Str): Bool
fn (upload-url: Str, opts: Map): Bool

DELETE an upload URL (no Authorization) - discard the session and its uploaded bytes. Returns true.

`chunk-bounds`

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

The [start, end) of the chunk beginning at offset (pure): end is offset + chunk-size, capped at total.

`classify-chunk-response`

fn (response: Result, assumed-offset: Int?): Map

Interpret the response to a chunk PUT (pure): {state: "complete", item} (200/201), {state: "incomplete", next-offset} (202, from nextExpectedRanges; assumed-offset when Graph lists none), or {state: "retry", error} for a dropped connection; an Err for an expired session (404), a range mismatch (416: call resume-upload), a name conflict (409) or any other failure (429/5xx carry retry-after).

`conflict-query`

fn (conflict: Str?): Str

`content-range`

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

The Content-Range for bytes start up to (not including) end of a total-byte upload: content-range(0, 26, 128) is "bytes 0-25/128" (pure).

`create-replace-session`

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

POST {item}/createUploadSession - open a session that replaces an existing file's content. opts as for create-upload-session, plus if-match (eTag).

`create-upload-session`

fn (parent: Any, name: Str): UploadSession
fn (parent: Any, name: Str, opts: Map): UploadSession

POST {parent}:/{name}:/createUploadSession - open a session for a new file name under parent (an id, "root", a /path, or a Map). opts.conflict (replace default, rename, fail), description, file-size (personal OneDrive: checks quota up front), defer-commit, drive. Returns an UploadSession.

`next-offset-from-ranges`

fn (ranges: Any): Int?

The next byte to send from an upload session's nextExpectedRanges (pure): the start of the first range (["26-"] is 26, ["12345-55232", "77829-99375"] is 12345); null when the list is empty or missing.

`put-chunk`

fn (upload-url: Str, chunk: Bytes, start: Int, total: Int): Any

PUT one chunk to an upload URL, without an Authorization header, with its Content-Range. Returns the raw response or a transport Err.

`put-content`

fn (path: Str, bytes: Bytes, mime-type: Str?, conflict: Str?, opts: Map): Map

`replace-content`

fn (item: Any, content: Any, mime-type: Str?): Map
fn (item: Any, content: Any, mime-type: Str?, opts: Map): Map

Replace an existing file's content (a new version): a simple PUT to {item}/content up to 4 MiB, an upload session above. opts.if-match (eTag) guards against overwriting someone else's change. Returns the driveItem.

`resume-upload`

fn (upload-url: Str, content: Any): Map
fn (upload-url: Str, content: Any, opts: Map): Map

Continue an interrupted upload of content to upload-url: ask the session where it stands, then send the rest. Returns the driveItem.

item ::microsoft::onedrive::upload/resume-upload(saved-upload-url, bytes)

`start-session`

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

`to-bytes`

fn (content: Any): Bytes

Upload content as Bytes: Bytes pass through, a Str becomes its UTF-8 bytes, null is empty, anything else is JSON-encoded (pure).

`to-session`

fn (body: Map): UploadSession

`upload-file`

fn (parent: Any, name: Str, content: Any, mime-type: Str?): Map
fn (parent: Any, name: Str, content: Any, mime-type: Str?, opts: Map): Map

Upload content as name under parent (an id, "root", a /path or a Map): a simple PUT up to 4 MiB, an upload session above (or with opts.resumable: true). opts.conflict (replace default, rename, fail), chunk-size, drive. Returns the driveItem.

item ::microsoft::onedrive::upload/upload-file("/Reports", "q3.csv", "region,total\nwest,42\n", "text/csv")
big ::microsoft::onedrive::upload/upload-file("root", "video.mp4", video-bytes, "video/mp4", {conflict: "rename"})

`upload-large`

fn (parent: Any, name: Str, content: Any): Map
fn (parent: Any, name: Str, content: Any, opts: Map): Map

Upload content as name under parent through an upload session (any size). Returns the driveItem. See create-upload-session and upload-to-session for opts.

`upload-loop`

fn (upload-url: Str, bytes: Bytes, offset: Int, chunk-size: Int, attempt: Int, policy: Map): Map

`upload-session-status`

fn (upload-url: Str): Map
fn (upload-url: Str, opts: Map): Map

GET an upload URL (no Authorization) - how far the session got: {next-offset, next-expected-ranges, expiration}. An Err when the session is gone (404).

`upload-small`

fn (parent: Any, name: Str, content: Any, mime-type: Str?): Map
fn (parent: Any, name: Str, content: Any, mime-type: Str?, opts: Map): Map

PUT {parent}:/{name}:/content - create or replace a file in one request (best up to 4 MiB; Graph accepts up to 250 MB, but a session survives dropped connections). opts.conflict (replace default, rename, fail), drive. Returns the driveItem.

`upload-to-session`

fn (upload-url: Str, content: Any): Map
fn (upload-url: Str, content: Any, opts: Map): Map

Send content to an open session's upload-url, starting at byte 0 (or opts.offset), in opts.chunk-size chunks (default 10 MiB, rounded down to a 320 KiB multiple). Returns the created driveItem.

Types

`UploadSession`

UploadSession type {
    upload-url: Str,
    expiration: Str?,
    next-expected-ranges: Vec
}

An open upload session.

upload-url - the pre-authenticated URL for chunk PUTs; treat it as a secret, and keep it to resume
expiration - when the session lapses without activity
next-expected-ranges - Graph's nextExpectedRanges

::sharing ::versions