Documents: fetch, create, batchUpdate, and helpers for the common edits (read as text, append, insert, find and replace, fill a template).

Scopes. get-document and read-text use documents.readonly; everything else documents. drive.file works for documents the app created or the user opened with it. Copying a template, moving, sharing, exporting (PDF, Markdown, Word) and deleting a document are Drive calls (google-drive).

Values

READ_TEXT_KEYS

READ_TEXT_KEYS: Vec [
  "tabId"
]

Functions

append-text

fn (document-id: Str, text: Str): Map
fn (document-id: Str, text: Str, opts: Map): Map

Add text at the end of the document's body (first tab unless opts.tabId). End text with a newline to start a new paragraph after it. Scope: documents (or drive.file).

Example

::google::docs::documents/append-text("1AbCdEf", "Shipped the importer.\n")

// In a second tab
::google::docs::documents/append-text("1AbCdEf", "Notes\n", {tabId: "t.1"})

batch-update

fn (document-id: Str, requests: Vec): Map
fn (document-id: Str, requests: Vec, opts: Map): Map

POST /{id}:batchUpdate - apply a Vec of requests atomically, in order: if one is invalid, none apply. Returns {documentId, replies, writeControl}. Each request sees the indexes left by the one before it, so when you have several insertions or deletions, apply the highest index first. ::google::docs::requests builds requests; any request as a plain Map works too. Scope: documents (or drive.file).

Example

::req ::google::docs::requests

// Fails instead of applying if someone edited the document first
::google::docs::documents/batch-update("1AbCdEf", [
  ::req/insert-text("Status\n", 1),
  ::req/heading(1, 8, 1)
], {writeControl: {requiredRevisionId: "AOV_f4..."}})

batch-update-body

fn (requests: Vec, opts: Map): Map

The batchUpdate body (pure): {requests} plus writeControl from opts when set ({requiredRevisionId} fails the write if the document changed; {targetRevisionId} merges with changes since).

Example

::google::docs::documents/batch-update-body([{deleteHeader: {headerId: "h1"}}], {writeControl: {requiredRevisionId: "r1"}})
// {requests: [{deleteHeader: {headerId: "h1"}}], writeControl: {requiredRevisionId: "r1"}}

::google::docs::documents/batch-update-body([], {})  // {requests: []}

create-document

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

POST /v1/documents - create a blank document. Returns the resource with documentId. Only title applies: add content with append-text or batch-update. It lands in the authenticated user's My Drive root (move it with google-drive's move-file); a service account without domain-wide delegation owns it alone, so share it before anyone else can open it. Scope: documents (or drive.file).

Example

doc ::google::docs::documents/create-document("Weekly report")
doc.documentId

fill-template

fn (document-id: Str, values: Map): Map
fn (document-id: Str, values: Map, opts: Map): Map

Replace each {{key}} in the document with its value from values (values are converted with Str; null values are skipped). The usual template flow is google-drive's copy-file, then this on the copy. Scope: documents (or drive.file).

Example

copy ::google::drive::files/copy-file("1TemplateId", {name: "Welcome Ada"})
::google::docs::documents/fill-template(copy.id, {name: "Ada", plan: "Pro"})

get-document

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

GET /{id} - the document: documentId, title, revisionId, body (the first tab only), namedStyles, headers, footers. Pass {includeTabsContent: true} to get every tab under tabs instead, and suggestionsViewMode (e.g. "PREVIEW_WITHOUT_SUGGESTIONS") to choose how suggestions render. Scope: documents.readonly.

Example

doc ::google::docs::documents/get-document("1AbCdEf")
doc.title

// Every tab, with suggestions accepted
all-tabs ::google::docs::documents/get-document("1AbCdEf", {
  includeTabsContent: true,
  suggestionsViewMode: "PREVIEW_SUGGESTIONS_ACCEPTED"
})
length(all-tabs.tabs)

get-params

fn (opts: Map): Map

The query parameters get-document sends (pure): includeTabsContent, suggestionsViewMode, commentsViewMode, fields; only the ones you set.

Example

::google::docs::documents/get-params({includeTabsContent: true, fields: "title"})  // {includeTabsContent: true, fields: "title"}

insert-text

fn (document-id: Str, text: Str, index: Int): Map
fn (document-id: Str, text: Str, index: Int, opts: Map): Map

Insert text at a body index (first tab unless opts.tabId). An index must fall inside an existing paragraph; the document starts at 1. Scope: documents (or drive.file).

Example

// At the very start of the body
::google::docs::documents/insert-text("1AbCdEf", "Draft\n", 1)

read-text

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

The document as plain text, with every tab's body in tab order. Pass {tabId: "t.abc"} for one tab; an Err when that tab does not exist. Scope: documents.readonly.

Example

::google::docs::documents/read-text("1AbCdEf")

// One tab
::google::docs::documents/read-text("1AbCdEf", {tabId: "t.0"})

replace-text

fn (document-id: Str, search: Str, replacement: Str): Map
fn (document-id: Str, search: Str, replacement: Str, opts: Map): Map

Replace every occurrence of search with replacement in every tab. Case-sensitive unless {matchCase: false}; {searchByRegex: true} treats search as a regular expression; {tabIds: [...]} limits the tabs. The reply's replaceAllText.occurrencesChanged is the count. Scope: documents (or drive.file).

Example

reply ::google::docs::documents/replace-text("1AbCdEf", "2025", "2026")
reply.replies[0].replaceAllText.occurrencesChanged

// Case-insensitive
::google::docs::documents/replace-text("1AbCdEf", "acme", "Hot", {matchCase: false})