hot.dev/google-drive / ::google::drive::files

Drive files and folders: list/search, get, create folders and shortcuts, update metadata, rename, move, copy, trash/untrash, delete.

Shared drives work everywhere: supportsAllDrives=true is sent by default and listings include shared-drive items (includeItemsFromAllDrives=true). Pass driveId to search one shared drive (corpora then defaults to "drive"), or corpora: "allDrives" to search everything the user can reach.

Scopes. Reads use drive.readonly and writes drive by default; drive.file works for files your app created or the user opened with it, and drive.metadata.readonly is enough for listing and get-file. The default only matters for service accounts (see google-core).

Values

DEFAULT_PAGE_SIZE

DEFAULT_PAGE_SIZE: Int 1000

METADATA_KEYS

METADATA_KEYS: Vec [
  "parent",
  "parents",
  "description",
  "metadata"
]

Functions

build-metadata

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

Build a file metadata body (pure): name and mimeType (either may be null), parents from opts.parents (Vec or Str) or opts.parent, description, then any extra fields in opts.metadata (e.g. appProperties, properties, starred). Nulls are dropped.

copy-file

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

POST /files/{id}/copy - copy a file (not folders). changes sets the copy's metadata (name, parents, ...). Google Docs copies stay Google Docs.

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

create-shortcut

fn (target-id: Str, name: Str): Map
fn (target-id: Str, name: Str, opts: Map): Map

POST /files - create a shortcut to target-id (named name), optionally in opts.parent. Shortcuts are how one item appears in several folders, since shared-drive items have exactly one parent.

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.

ensure-folder

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

Return the first non-trashed folder named name under parent-id, creating it when missing. Handy for idempotent workflow output folders.

get-doc-file

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

get-file normalised to a ::google::drive/DocFile.

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).

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

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

list-folder

fn (folder-id: Str): Vec
fn (folder-id: Str, opts: Map): Vec
fn (folder-id: Str, opts: Map, limit: Int?): Vec

List the non-trashed direct children of a folder (all pages, or at most limit). opts.q is AND-ed with the folder filter. Use "root" for the My Drive root, or a shared drive id for its top level.

list-params

fn (opts: Map): Map

The query parameters list-files sends for opts (pure): shared-drive flags on, fields = ::google::drive/LIST_FIELDS, corpora: "drive" when driveId is given, then your Drive parameters (q, pageSize, pageToken, orderBy, spaces, corpora, driveId, fields, includeItemsFromAllDrives, ...). Nulls are dropped.

move-file

fn (id: Str, new-parent: Str): Map
fn (id: Str, new-parent: Str, opts: Map): Map

Move a file or folder into new-parent, removing its current parents (read first unless opts.removeParents is given). In shared drives an item has exactly one parent; moving between shared drives needs organizer rights.

move-params

fn (new-parent: Str, current-parents: Vec): Map

The addParents/removeParents parameters for moving to new-parent from current-parents (pure). The new parent is never removed.

rename-file

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

Rename a file or folder.

resolve-shortcut

fn (file: Map): Map
fn (file: Map, opts: Map): Map

Return the target's metadata when file is a shortcut (one hop; Drive does not allow shortcuts to shortcuts), else file itself. file needs mimeType and shortcutDetails.

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.

untrash-file

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

Restore a file or folder from the trash.

update-file

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

PATCH /files/{id} - update metadata (name, description, starred, appProperties, trashed, mimeType, ...). Null values in changes are dropped. Options: addParents, removeParents (comma-separated ids), keepRevisionForever, fields, credentials. Use ::google::drive::upload/update-file-content to replace content.