Google Drive API v3 bindings: files and folders, search, Google Docs export for text pipelines, binary-safe and resumable uploads, chunked downloads, shared drives, permissions, revisions, and change sync with push notifications. Credentials and scopes come from google-core.

Namespaces

::google::drive::files - list/search, get, create folder, update, rename, move, copy, trash, delete, shortcuts
::google::drive::query - a q query builder with proper escaping
::google::drive::content - read-document, download, export, chunked download, export-format map
::google::drive::upload - multipart and resumable uploads, content updates
::google::drive::permissions - sharing
::google::drive::drives - shared drives and about
::google::drive::revisions - revision history
::google::drive::changes - change feed, watch channels, webhook parsing

Every function has an options arity taking an opts Map. Its Drive query parameters use Drive's own names (q, pageSize, fields, driveId, ...); its credential keys (token, refresh-token, service-account, subject, scopes, retry, ...) are handled by google-core: they override context for that call and are masked in call records.

Quick start

::files ::google::drive::files
::content ::google::drive::content
::q ::google::drive::query

hits ::files/list-all-files({q: ::q/all-of(::q/name-contains("roadmap"), ::q/not-trashed())}, 50)
doc ::content/read-document(first(hits).id, "markdown")
doc.text

Values

`API_ROOT`

API_ROOT: Str "https://www.googleapis.com"

`BASE_URL`

BASE_URL: Str "https://www.googleapis.com/drive/v3"

`DOCUMENT_MIME`

DOCUMENT_MIME: Str "application/vnd.google-apps.document"

`DRAWING_MIME`

DRAWING_MIME: Str "application/vnd.google-apps.drawing"

`FILE_FIELDS`

FILE_FIELDS: Str "id,name,mimeType,size,modifiedTime,createdTime,parents,md5Checksum,sha1Checksum,sha256Checksum,driveId,webViewLink,exportLinks,trashed,version,headRevisionId,shortcutDetails"

`FILE_SCOPE`

FILE_SCOPE: Str "https://www.googleapis.com/auth/drive.file"

`FOLDER_MIME`

FOLDER_MIME: Str "application/vnd.google-apps.folder"

`FORM_MIME`

FORM_MIME: Str "application/vnd.google-apps.form"

`GOOGLE_APPS_PREFIX`

GOOGLE_APPS_PREFIX: Str "application/vnd.google-apps."

`LIST_FIELDS`

LIST_FIELDS: Str "nextPageToken,incompleteSearch,files(id,name,mimeType,size,modifiedTime,createdTime,parents,md5Checksum,sha1Checksum,sha256Checksum,driveId,webViewLink,exportLinks,trashed,version,headRevisionId,shortcutDetails)"

`METADATA_READ_SCOPE`

METADATA_READ_SCOPE: Str "https://www.googleapis.com/auth/drive.metadata.readonly"

`PRESENTATION_MIME`

PRESENTATION_MIME: Str "application/vnd.google-apps.presentation"

`READ_SCOPE`

READ_SCOPE: Str "https://www.googleapis.com/auth/drive.readonly"

`SCOPE`

SCOPE: Str "https://www.googleapis.com/auth/drive"

`SCRIPT_MIME`

SCRIPT_MIME: Str "application/vnd.google-apps.script"

`SHORTCUT_MIME`

SHORTCUT_MIME: Str "application/vnd.google-apps.shortcut"

`SPREADSHEET_MIME`

SPREADSHEET_MIME: Str "application/vnd.google-apps.spreadsheet"

`UPLOAD_URL`

UPLOAD_URL: Str "https://www.googleapis.com/upload/drive/v3"

`VID_MIME`

VID_MIME: Str "application/vnd.google-apps.vid"

Functions

`api-root`

fn (): Str

The API root, https://www.googleapis.com unless the google.drive.api-root context variable points at a proxy or emulator.

Context Vars: google.drive.api-root

`as-vec`

fn (value: Any): Vec

`base-mime`

fn (content-type: Str?): Str?

A Content-Type without parameters, lowercased: "text/plain; charset=utf-8" becomes "text/plain".

`compact`

fn (body: Map): Map

Drop null values from a request body (Drive bodies never carry JSON null for unset fields).

`content-from-bytes`

fn (file-id: Str, bytes: Bytes, mime-type: Str?, source: Str): FileContent

Build a FileContent from raw bytes and their MIME type.

`content-from-response`

fn (file-id: Str, response: Map, source: Str): FileContent

Build a FileContent from an HTTP response: body-bytes (never the auto-decoded body, so a JSON file stays bytes and 123 stays text) and the Content-Type header.

`content-text`

fn (content: Map): Str

The text of a FileContent: its text, or the UTF-8 decoding of bytes (invalid sequences become U+FFFD).

`create-folder` alias of `::google::drive::files/create-folder`

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

POST /files - create a folder. A Str second argument is the parent folder id; an opts Map takes parent/parents, description, metadata, Drive parameters and credentials. Scope: drive (or drive.file).

folder ::google::drive::files/create-folder("Reports", "1AbCparent")
folder.id

`creds`

fn (opts: Map): Map

The google-core part of opts (credentials, scopes, retry), passed through to ::google::api.

`delete-file` alias of `::google::drive::files/delete-file`

fn (id: Str): Bool
fn (id: Str, opts: Map): Bool

DELETE /files/{id} - permanently delete a file or folder, skipping the trash (a folder's descendants owned by the user go too). Irreversible; prefer trash-file. Shared-drive items need the organizer role. Returns true.

`download-file` alias of `::google::drive::content/download-file`

fn (id: Str): ::google::drive/FileContent
fn (id: Str, opts: Map): ::google::drive/FileContent

GET /files/{id}?alt=media - download a blob file's bytes as a FileContent (Google Docs/Sheets/Slides have no bytes: use read-document or export-file). When the file is larger than http.max-response-bytes, it is fetched again in Range chunks (download-file-chunked).

Options: range: {start, end} (inclusive; end null for the rest) for a partial download, chunk-size for the chunked fallback, acknowledgeAbuse: true to download a file flagged as abusive (owner-only otherwise), plus credentials.

pdf ::google::drive::content/download-file("1AbCfile")
pdf.mime-type   // "application/pdf"
pdf.bytes       // exact bytes

`encode-id`

fn (id: Str): Str

URL-encode an id for a path segment.

`export-file` alias of `::google::drive::content/export-file`

fn (id: Str, mime-type: Str): ::google::drive/FileContent
fn (id: Str, mime-type: Str, opts: Map): ::google::drive/FileContent

GET /files/{id}/export - export a Google-native file to mime-type (see EXPORT_FORMATS / export-mime-type), as a FileContent. When Drive refuses with its 10 MB export limit, the file's exportLinks URL for the same type is used instead.

csv ::google::drive::content/export-file(sheet-id, "text/csv")
csv.text

`get-file` alias of `::google::drive::files/get-file`

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

GET /files/{id} - file metadata. fields defaults to ::google::drive/FILE_FIELDS; pass {fields: "*"} for everything. Scope: drive.readonly (or drive.metadata.readonly / drive.file).

`is-folder`

fn (mime-type: Str?): Bool

True for a folder MIME type.

`is-google-native`

fn (mime-type: Str?): Bool

True for Google Workspace types (application/vnd.google-apps.*) other than folders and shortcuts: Docs, Sheets, Slides, Drawings, Forms, ... These have no bytes of their own and are exported.

`is-textual-mime`

fn (mime-type: Str?): Bool

True when content of this MIME type is text: text/*, JSON, XML, SVG, JavaScript, CSV/TSV, Markdown, and the Apps Script JSON export.

`json`

fn (scope: Str, method: Str, full-url: Str, body: Any, opts: Map): Any

::google::api/json with this package's conventions: scope default, credential opts, JSON or empty body.

`list-all-files` alias of `::google::drive::files/list-all-files`

fn (opts: Map): Vec
fn (opts: Map, limit: Int?): Vec

Follow nextPageToken and return every matching file (a Vec of Drive file resources), or at most limit. Uses pageSize: 1000 (or limit when smaller) unless opts sets one. Takes the same opts as list-files.

pdfs ::google::drive::files/list-all-files({q: "mimeType = 'application/pdf' and trashed = false"}, 500)

`list-files` alias of `::google::drive::files/list-files`

fn (): Map
fn (query: Str): Map
fn (opts: Map): Map

GET /files - one page of files. Returns Drive's {files, nextPageToken?, incompleteSearch}; follow nextPageToken with {pageToken: ...} or use list-all-files. A Str argument is a q query. Drive includes trashed files unless q says trashed = false.

Options: q, pageSize (max 1000), pageToken, orderBy (e.g. "modifiedTime desc", "folder,name"), fields, spaces ("drive", "appDataFolder"), corpora ("user", "drive", "domain", "allDrives"), driveId, includeItemsFromAllDrives, plus google-core credential keys.

page ::google::drive::files/list-files({
  q: ::google::drive::query/all-of(::google::drive::query/name-contains("Q3"), ::google::drive::query/not-trashed()),
  orderBy: "modifiedTime desc",
  pageSize: 50
})
page.files

`query-params`

fn (defaults: Map, opts: Map): Map
fn (defaults: Map, opts: Map, local-keys: Vec): Map

Build a call's query parameters: defaults, overridden by the Drive parameters in opts (credential keys and the function's own local-keys are removed), with nulls dropped. Pass a key as null in opts to drop a default.

`read-document` alias of `::google::drive::content/read-document`

fn (id: Str): ::google::drive/FileContent
fn (id: Str, format: Str?): ::google::drive/FileContent
fn (id: Str, format: Str?, opts: Map): ::google::drive/FileContent

Read any file as a FileContent with its DocFile attached.

Shortcuts are followed to their target.
Google-native files (Docs, Sheets, Slides, Drawings, Apps Script) are exported in format ("auto" by default: Docs markdown, Sheets csv of the first sheet, Slides text, Drawings svg); see export-mime-type for the names. Over 10 MB, exportLinks is used.
Other files are downloaded as stored and format is ignored (check mime-type; text is set for textual types).
Folders return an Err.

doc ::google::drive::content/read-document("1AbCdoc", "markdown")
doc.text            // Markdown, ready for chunking and embedding
doc.file.modified   // for incremental re-indexing

`to-doc-file`

fn (file: Map): DocFile

Normalise a Drive file resource (as returned by get-file, list-files, changes) into a DocFile. Missing fields become null/false.

`to-doc-files`

fn (files: Vec): Vec

to-doc-file over a Vec of Drive file resources.

`to-int`

fn (value: Any): Int?

Drive returns int64 fields (size, version) as strings; parse to Int, or null when absent or malformed.

`trash-file` alias of `::google::drive::files/trash-file`

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

Move a file or folder to the trash (recoverable for 30 days). Prefer this to delete-file.

`upload-file` alias of `::google::drive::upload/upload-file`

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

Create a file with content. A Str fourth argument is the parent folder id; an opts Map takes parent/parents, description, metadata (extra fields such as appProperties), convert-to ("document", "spreadsheet", "presentation": convert on upload, e.g. a .docx or .csv into a Google Doc/Sheet), resumable: true to force a resumable upload, chunk-size, Drive parameters (keepRevisionForever, ocrLanguage, useContentAsIndexableText, fields) and credentials. Returns the file resource.

file ::google::drive::upload/upload-file("report.csv", csv-text, "text/csv", folder-id)
sheet ::google::drive::upload/upload-file("report", csv-text, "text/csv", {parent: folder-id, convert-to: "spreadsheet"})

`upload-url`

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

A Drive v3 upload URL (/upload/drive/v3...) with params.

`url`

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

A Drive v3 URL: path (e.g. "/files/abc") plus non-null params as a query string.

Types

`DocFile`

DocFile type {
    provider: Str,
    id: Str,
    name: Str,
    mime-type: Str,
    path: Str?,
    size: Int?,
    modified: Str?,
    created: Str?,
    parents: Vec,
    drive-id: Str?,
    web-url: Str?,
    version: Str?,
    revision-id: Str?,
    md5: Str?,
    sha256: Str?,
    hashes: Map,
    is-folder: Bool,
    is-google-native: Bool,
    is-shortcut: Bool,
    shortcut-target-id: Str?,
    trashed: Bool,
    export-formats: Vec,
    raw: Map
}

Provider-neutral file metadata, shaped so a future documents package can treat Drive, OneDrive, Dropbox and Box alike.

Fields

provider - "google-drive"
id, name, mime-type
path - always null: Drive addresses files by id and has no path
size - bytes (Int); null for Google-native files and folders
modified, created - RFC 3339 timestamps
parents - parent folder ids
drive-id - the shared drive id, null in My Drive
web-url - the browser link (webViewLink)
version - Drive's monotonically increasing file version (use as an etag)
revision-id - the head revision id (blob files only)
md5, sha256 - content checksums (blob files only)
hashes - every checksum Drive gave, under md5, sha1 and sha256 (blob files only; empty otherwise)
is-folder, is-google-native, is-shortcut, shortcut-target-id
trashed
export-formats - MIME types available via exportLinks
raw - the Drive file resource as returned

`FileContent`

FileContent type {
    file-id: Str,
    name: Str?,
    mime-type: Str?,
    size: Int,
    bytes: Bytes,
    text: Str?,
    source: Str,
    format: Str?,
    file: DocFile?
}

Downloaded or exported file content. bytes is always the exact response body (binary safe); text is the UTF-8 decoding when mime-type is textual, else null.

Fields

file-id, name
mime-type - the MIME type of bytes (export target or stored type)
size - length(bytes)
bytes, text
source - "download", "export", "export-link" (the >10 MB export fallback), "range", or "chunked"
format - the export format asked for (read-document), else null
file - the DocFile (set by read-document)

hot.dev/google-drive ::changes

Values

API_ROOT

BASE_URL

DOCUMENT_MIME

DRAWING_MIME

FILE_FIELDS

FILE_SCOPE

FOLDER_MIME

FORM_MIME

GOOGLE_APPS_PREFIX

LIST_FIELDS

METADATA_READ_SCOPE

PRESENTATION_MIME

READ_SCOPE

SCOPE

SCRIPT_MIME

SHORTCUT_MIME

SPREADSHEET_MIME

UPLOAD_URL

VID_MIME

Functions

api-root

as-vec

base-mime

compact

content-from-bytes

content-from-response

content-text

create-folder alias of ::google::drive::files/create-folder

creds

delete-file alias of ::google::drive::files/delete-file

download-file alias of ::google::drive::content/download-file

encode-id

export-file alias of ::google::drive::content/export-file

get-file alias of ::google::drive::files/get-file

is-folder

is-google-native

is-textual-mime

json

list-all-files alias of ::google::drive::files/list-all-files

list-files alias of ::google::drive::files/list-files

query-params

read-document alias of ::google::drive::content/read-document

to-doc-file

to-doc-files

to-int

trash-file alias of ::google::drive::files/trash-file

upload-file alias of ::google::drive::upload/upload-file

upload-url

url