@spec active_integration_uuid() :: String.t() | nil

Returns the uuid of the active Google integration, or nil if none has been chosen.

The settings value at document_creator_settings.google_connection is expected to be a UUIDv7 (the integration row's storage uuid). Older installs may have a legacy "google" or "google:name" string here; this function detects that, resolves it to the matching integration's uuid, rewrites the setting, and returns the uuid. Subsequent calls read the migrated value directly.

@spec append_template(String.t(), String.t(), keyword()) ::
  {:ok, {integer(), integer()}} | {:error, term()}

Append a template's content to an existing Google Doc via batchUpdate.

Inserts a paragraph break, a page break, then the content of template_doc_id into target_doc_id. Returns {:ok, {start_index, end_index}} representing the character range of the inserted content — callers use this for section-scoped substitution.

Paragraph text is inserted via a single insertText, same as before this function also handled tables. Tables are NOT part of that flattened text — there is no Docs API primitive for "paste another document's table here" — so they are rebuilt in two extra batchUpdate passes, reusing the exact pattern already proven for image-grid tables (table_image_inserts/3 -> re-fetch -> match_new_tables/3 -> fill_table_cells/3):

1. flatten_template_with_table_markers/1 walks the template like get_document_text/1 does, but emits a unique marker token at each table's position (instead of silently dropping it) and captures the table's {rows, columns, cell text} separately, in document order. The marked-up text is inserted via the same single insertText as before.
2. Re-fetch, locate the markers (find_table_marker_ranges/1), and replace each with a bare table of the right size (table_skeleton_requests/2) in one batchUpdate.
3. Re-fetch again, identify the newly-inserted tables (match_new_tables/3, reused as-is), and fill every cell with its captured text, character and paragraph style, and column widths (build_table_fill_requests/3, private) in one batchUpdate. Any {{var}} placeholder that lived inside a table cell is now physically present in the document, so it substitutes normally in Composer.apply_substitutions/4 like any other text.

Templates with no tables skip steps 2-3 entirely — this reduces to exactly the previous single-insertText behaviour, with no extra Docs API calls.

Formatting fidelity: table column widths (tableStyle.tableColumnProperties, fixed-width columns only — evenly distributed is insertTable's own default) are captured during flatten and replayed via updateTableColumnProperties in the Phase 2 (cell-fill) batch, targeting the table's real post-insert startIndex from the re-fetch already done for cell matching — NOT the Phase 1b skeleton batch, since insertTable's own location index cannot be trusted as the resulting table's position (verified live: Google inserts an implicit paragraph break ahead of a table landing mid-paragraph, shifting its real startIndex by one from the requested location — see table_column_width_requests/2's doc). Per-run character style — bold, italic, font size, foreground color — is captured for both table cell text and the section's own (non-table) body text, and replayed via updateTextStyle immediately after the corresponding insertText. Every inserted character is covered by an explicit range, including bold: false/italic: false for plain runs, so freshly inserted text can never silently inherit formatting from neighboring content already in the target document.

Paragraph-level style — alignment, line spacing, space above/below, named style type (headings), start/first-line indentation — is captured the same way and replayed via updateParagraphStyle (paragraph_style_requests/2), same anti-inheritance guarantee: every field is always stated explicitly. List bullets are replayed via createParagraphBullets (paragraph_bullet_requests/2), resolving bulleted vs numbered from the source and mapping to Google's own default preset for that family — this reproduces glyph family, not an arbitrary custom glyph/format exactly (see extract_bullet_info/2's doc).

The leading insertText(insert_index, "\n") exists ONLY to make this safe for the appended section's own first paragraph. insertPageBreak inserts an inline element — it does not split a paragraph — and, without it, the appended content would start one position before the target document's own closing character. Verified live: that closing character is not a separate, shiftable paragraph separator, it's the document's shared terminal marker, so inserting immediately before it (as this function did before this "\n" was added) always continued the target's existing last paragraph — meaning updateParagraphStyle/ createParagraphBullets on the appended section's first paragraph (they target whole paragraphs, not sub-ranges) silently reformatted the preceding section's trailing text too. A first attempt at fixing this tried detecting the condition instead of forcing it (skip styling that first paragraph only when the target's own last paragraph didn't already end in "\n") — that check always came back "safe" for real documents, since a paragraph's own trailing "\n", when present, IS the shared terminal marker rather than a boundary the appended content lands after, so the check was inert and still corrupted the preceding paragraph live. Explicitly inserting a real paragraph break first, ahead of the page break, is what actually guarantees the appended section starts in a fresh, empty paragraph — the same guarantee a table's cells already get for free from a bare insertTable. content_start shifts by one extra unit accordingly (insert_index + 2, not + 1) to land after both the new paragraph break and the page break; every offset downstream (body_runs, body_paragraphs, the table marker pipeline) is anchored at content_start and unaffected by the shift itself.

Known limitations: cell shading, borders, and merged cells are not restored — insertTable creates a bare table beyond the column widths above. Nested tables (a table inside a table cell) are not supported.

Options (used in tests):

• :get_fn — overrides get_document/1 (used for both the template fetch and every target-document re-fetch)
• :batch_fn — overrides batch_update/2

@spec batch_update(String.t(), [map()]) :: {:ok, map()} | {:error, term()}

Send a batchUpdate request to a Google Doc.

@spec build_image_batch_requests([map()], map()) :: [map()]

Builds the list of batchUpdate request maps to substitute image tags.

fills is a map keyed by variable name; each value carries kind, default_width_px, separator (atom or nil), and media — a list of %{uri, width_px, height_px}.

Empty media list = the tag is still deleted (cleared).

@spec build_single_image_request(
  String.t(),
  keyword()
) :: map()

Builds a single image insert request map.

Options:

• :insertion_index — document character index for insertion (required)
• :config — map with :default_width_px, :opacity, :z_index (required)

When z_index > 0, emits a createPositionedObject with layout = "WRAP_TEXT". When z_index <= 0, emits insertInlineImage (default inline behaviour). Opacity application requires a follow-up UpdateEmbeddedObjectPropertiesRequest with the object ID returned by the batchUpdate response — not emitted here. A Logger warning is written when opacity != 1.0. This is a documented no-op (open risk) per the spec's "Open Risks" section: applying transparency requires a second batchUpdate pass after the initial insert, using the embedded object ID from the first response. Not yet implemented.

@spec cached_folder_id_keys() :: [String.t()]

Folder-settings keys holding discovered folder IDs (cleared on config change).

@spec connection_status() :: {:ok, %{email: String.t()}} | {:error, atom()}

Check if connected. Returns {:ok, %{email: email}} or {:error, reason}.

Page content width in points = pageSize.width − marginLeft − marginRight. Falls back to 468pt (US Letter with 1" margins) if anything is missing.

@spec copy_document(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Copy a Google Doc for use as the base of a composed document.

Returns {:ok, new_doc_id}. The copy is named by its source doc ID so it can be identified for best-effort cleanup on rollback before a final name is applied.

@spec copy_file(String.t(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, :invalid_file_id | :copy_failed | term()}

Copy a file in Google Drive. Returns the new file's ID.

@spec create_document(
  String.t(),
  keyword()
) ::
  {:ok, %{doc_id: String.t(), name: String.t(), url: String.t() | nil}}
  | {:error, :create_document_failed | term()}

Create a new blank Google Doc in a specific folder.

@spec create_folder(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, :create_folder_failed | term()}

Create a folder in Google Drive. Optionally specify a parent folder. Returns {:ok, folder_id}.

@spec delete_document(String.t()) :: :ok | {:error, term()}

Delete (trash) a Google Doc. Used for best-effort cleanup after a failed composition. Returns :ok or {:error, reason}.

@spec discover_folders() :: %{
  templates_folder_id: String.t() | nil,
  documents_folder_id: String.t() | nil,
  deleted_templates_folder_id: String.t() | nil,
  deleted_documents_folder_id: String.t() | nil
}

Discover templates, documents, and deleted folder IDs. Looks for folders by name in Drive root, creating them if they don't exist. Caches results in Settings.

@spec document_content_range(String.t()) :: {:ok, {1, integer()}} | {:error, term()}

Return the range {1, end_index} of the current content in a Google Doc.

Used by the Composer to pin section 0's range before any sections are appended. The range starts at index 1 because Google Docs body content always begins at 1.

@spec ensure_folder_path(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Walk a path like "clients/active/templates", creating folders as needed. Returns {:ok, leaf_folder_id}.

@spec export_pdf(String.t()) ::
  {:ok, binary()} | {:error, :invalid_file_id | :pdf_export_failed | term()}

Export a Google Doc as PDF. Returns {:ok, pdf_binary}.

@spec fetch_thumbnail(term()) ::
  {:ok, String.t()}
  | {:error,
     :no_doc_id
     | :no_thumbnail
     | :thumbnail_link_failed
     | :thumbnail_fetch_failed
     | :invalid_file_id
     | term()}

Fetch a document thumbnail as a base64 data URI via the Drive API.

@spec file_location(term()) ::
  {:ok, %{folder_id: String.t(), path: String.t(), trashed: boolean()}}
  | {:error, :invalid_file_id | :not_found | term()}

Resolve the current parent folder and path for a Drive file.

@spec file_status(term()) ::
  {:ok, %{trashed: boolean(), parents: [String.t()]}}
  | {:ok, :not_found}
  | {:error, :invalid_file_id | term()}

Fetch Google Drive file metadata needed for sync classification.

Phase B — emits insertInlineImage requests for each cell, last-first so earlier inserts don't shift later indices. One image per cell; extra cells beyond the media list are ignored.

@spec find_folder_by_name(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, :not_found | :folder_search_failed | term()}

Find a folder by name, optionally within a parent folder. Returns {:ok, folder_id} or {:error, :not_found}.

@spec find_image_tag_ranges(map(), [String.t()]) :: [
  %{name: String.t(), start_index: integer(), end_index: integer()}
]

Scans a documents.get response for image tag occurrences.

Returns a flat list of %{name, start_index, end_index} covering every occurrence in body content, headers, footers, and table cells, restricted to the names supplied.

Offset note: Regex.scan(..., return: :index) returns byte offsets; Google Docs startIndex counts UTF-16 code units. The implementation converts byte offsets to UTF-16 code-unit counts via :unicode.characters_to_binary/3 so supplementary-plane codepoints (emoji, rare CJK) are counted as the two units a surrogate pair occupies.

@spec find_or_create_folder(
  String.t(),
  keyword()
) :: {:ok, String.t()} | {:error, term()}

Find a folder by name, or create it if it doesn't exist. Optionally specify a parent folder. Returns {:ok, folder_id}.

@spec find_table_marker_ranges(map()) :: [
  %{marker_index: integer(), start_index: integer(), end_index: integer()}
]

Phase 1a of the append-with-tables pipeline (see append_template/3): locate flatten_template_with_table_markers/1 marker tokens in an already-fetched document. Mirrors find_text_var_ranges/2's UTF-16 index arithmetic (Regex.scan(..., return: :index) yields byte offsets; Google Docs indices count UTF-16 code units).

@spec flatten_template_with_table_markers(map()) :: {String.t(), [map()]}

Phase 0 of the append-with-tables pipeline (see append_template/3).

Flattens a template document's body the same way get_document_text/1 does for paragraphs, but instead of silently skipping table blocks, emits a unique marker token at each table's position and captures its structure separately.

This is a distinct code path from get_document_text/1 — that function's existing behaviour (silently skipping tables) is relied on by its other callers (Documents.detect_variables/1, Documents.image_slots_for_template/1) and is intentionally left untouched.

Returns {text, tables}. tables is a list of %{marker_index: pos_integer(), rows: pos_integer(), columns: pos_integer(), cell_texts: [String.t()]}, one entry per table, in document order. cell_texts is row-major (row 0's cells left-to-right, then row 1's, ...), one entry per table cell — the same order extract_table_cells/1 and the cell-fill phase (build_table_fill_requests/3, both private) enumerate cells in.

Nested tables (a table inside a table cell) are not supported: a cell's text is captured from its paragraph blocks only, same limitation the top-level flatten has.

This is a thin wrapper around flatten_template_with_table_markers_and_styles/1 that drops its 3rd/4th return values (body_runs/body_paragraphs) — kept at its original 2-tuple arity so existing callers are unaffected by the style-capture addition.

@spec flatten_template_with_table_markers_and_styles(map()) ::
  {String.t(), [map()], [map()], [map()]}

Same walk as flatten_template_with_table_markers/1, additionally capturing per-run character style (bold, italic, font size, foreground color) and per-paragraph style (alignment, line spacing, space above/below, named style type, indentation, list bullet) — see append_template/3's "Formatting fidelity" doc section.

Returns {text, tables, body_runs, body_paragraphs}:

• text, tables — identical to flatten_template_with_table_markers/1, except each table map in tables gains three keys: column_properties (the source table's tableStyle.tableColumnProperties, normalized to %{width_type, magnitude, unit}, one per column, [] if the source table has none), cell_runs (one run-list per cell, parallel to cell_texts, same order — see text_style_requests/2's run shape) and cell_paragraphs (one paragraph-span-list per cell, parallel to cell_texts, same order — see paragraph_style_requests/2's span shape).
• body_runs — the non-table body text's per-run style spans, same run shape as a cell_runs entry, with start_offset/length in UTF-16 units relative to the start of text (table markers consume offset but contribute no run — they're deleted before any style request referencing them would apply).
• body_paragraphs — the non-table body text's per-paragraph style spans, same shape as a cell_paragraphs entry, offsets relative to the start of text.

@spec folder_settings_key() :: String.t()

The Settings key used for folder configuration.

@spec get_credentials() :: {:ok, map()} | {:error, atom()}

Get stored OAuth credentials via PhoenixKit.Integrations.

@spec get_document(String.t()) :: {:ok, map()} | {:error, term()}

Read a Google Doc's full content.

@spec get_document_text(String.t()) :: {:ok, String.t()} | {:error, term()}

Extract plain text content from a Google Doc (for variable detection).

@spec get_edit_url(term()) :: String.t() | nil

Get the edit URL for a Google Doc.

@spec get_folder_config() :: map()

Get configured folder paths and names from Settings, with defaults.

@spec get_folder_ids() :: map()

Get cached folder IDs from Settings, or discover them.

@spec get_folder_url(term()) :: String.t() | nil

Get the Google Drive folder URL.

Per-image width in points for N columns sharing content_width_pt.

@spec list_folder_files(String.t()) :: {:ok, [map()]} | {:error, term()}

List Google Docs directly in a Drive folder (non-recursive, fully paginated).

Returns {:ok, [%{"id" => ..., "name" => ..., "modifiedTime" => ..., "thumbnailLink" => ..., "parents" => [...]}]}.

For recursive traversal across subfolders, use PhoenixKitDocumentCreator.GoogleDocsClient.DriveWalker.walk_tree/2.

@spec list_subfolders(String.t()) :: {:ok, [map()]} | {:error, term()}

List subfolders within a parent folder (non-recursive, fully paginated). Returns {:ok, [%{"id" => ..., "name" => ...}]}.

@spec match_new_tables([map()], [non_neg_integer()], [non_neg_integer()]) ::
  {:ok, [map()]} | :mismatch

Identifies which of tables_asc (table elements from the re-fetched document, ascending by start index) are the tables Phase 1 just inserted, returning them in slot order.

pre_existing_starts and new_slot_starts are start indices captured from the pre-Phase-1 document. Phase 1's deletes/inserts shift the absolute indices of everything after a placeholder, so a startIndex set-difference misclassifies a pre-existing table located after a placeholder (its index moves and no longer matches the snapshot). Table order is never changed by inserts, though, so we reconstruct the pre/new interleaving from the original indices and read it off the post-Phase-1 tables positionally — robust regardless of where pre-existing tables sit relative to the placeholders.

Returns {:ok, new_tables} aligned with new_slot_starts sorted ascending, or :mismatch when the table count doesn't line up (e.g. Phase 1 partially failed) so the caller can skip filling rather than fill the wrong tables.

@spec migrate_folders_to_root(String.t()) ::
  {:ok, %{moved: [String.t()], skipped: [String.t()]}}
  | {:error, [{String.t(), term()}]}

Move the top-level Drive folders (templates, documents, deleted) into root_folder_id. For each folder the cached ID is tried first; when absent, the folder is located by name in the Drive root. Moving the deleted folder carries its sub-folders along automatically.

Clears cached folder IDs on full success so they are re-discovered from the new location on next use.

Returns {:ok, %{moved: [labels], skipped: [labels]}} or {:error, [{label, reason}]} if any move fails.

@spec move_file(String.t(), String.t()) ::
  :ok
  | {:error,
     :invalid_file_id
     | :move_failed
     | :get_file_parents_failed
     | :drive_file_not_found
     | term()}

Move a file to a different folder in Google Drive.

@spec paragraph_bullet_requests(integer(), [map()]) :: [map()]

Builds createParagraphBullets requests replaying captured list membership (see extract_bullet_info/2's doc for what "replaying" means here — glyph family, not exact glyph/format). Contiguous spans (no gap in offsets, same source listId) are merged into a single request spanning the whole run, so consecutive list items land in one target list (numbered items continuing count 1, 2, 3, ... instead of each restarting at 1) rather than length(spans) separate single-paragraph lists.

Spans with no bullet (not a list item) or zero length (see paragraph_style_requests/2) are excluded before grouping.

Requests are emitted in DESCENDING range order: createParagraphBullets strips leading tabs from paragraphs in its range, which shifts every later index — applying the highest range first means any shift lands only below ranges that are already done, the same reasoning as every other index-shifting pass in this module.

@spec paragraph_style_requests(integer(), [map()]) :: [map()]

Builds updateParagraphStyle requests replaying captured paragraph style (alignment, line spacing, space above/below, named style type, start/first-line indentation — see flatten_template_with_table_markers_and_styles/1's cell_paragraphs / body_paragraphs), anchored at base_index the same way text_style_requests/2 anchors character runs.

Every field is always included in the request, including values that merely reproduce Google's own default (alignment: "START", lineSpacing: 100.0, zero spacing/indentation, namedStyleType: "NORMAL_TEXT") — the same anti-inheritance guarantee text_style_fields/1 applies to bold/italic: a newly split paragraph in the target document otherwise inherits alignment/spacing/named style from whatever paragraph sat at the insertion point (e.g. an appended section's plain paragraph picking up CENTER alignment from a neighboring heading), not from the source template.

Unlike text_style_requests/2, spans are never merged — each paragraph gets its own request, since paragraphs are already discrete units (no benefit to coalescing, even when two adjacent ones share identical style). A span whose length is 0 (a paragraph with no textRun at all — doesn't happen for a real, non-empty paragraph, since even a blank line carries a "\n"-only run) is skipped: with zero characters, it contributes no offset and doesn't exist as distinct content in the inserted text either.

Ranges deliberately use the paragraph's own natural (un-stripped) length, even for a table cell's last paragraph whose text had its trailing newline stripped before insertion (see cell_fill_requests/4) — the cell's pre-existing bare paragraph supplies that newline structurally either way, so the natural length lands the range exactly on it. See cell_paragraph_spans/2's doc for the full argument.

Safe to batch immediately after the insert/fill it styles: like character style changes, paragraph style changes never shift document indices.

@spec rename_file(String.t(), String.t()) ::
  :ok | {:error, :invalid_file_id | :rename_failed | term()}

Rename a file in Google Drive.

@spec replace_all_text(String.t(), map()) :: {:ok, map()} | {:error, term()}

Replace all {{variable}} placeholders in a Google Doc. Keys are wrapped in {{ }} automatically.

@spec resolved_folder_paths(map()) :: {String.t(), String.t(), String.t()}

Compute the three Drive paths (templates, documents, deleted) given a folder config map.

@spec substitute_all_sections(String.t(), [map()], %{
  required(non_neg_integer()) => {integer(), integer()}
}) :: :ok | {:error, term()}

Substitute all sections' variables and image params into a Google Doc in a single atomic pass per phase (text then image).

sections is a list of %{position, variable_values, image_params} maps. ranges maps each section position to its {start_index, end_index} in the document. All positions must have a range entry — section 0's range must be provided explicitly (use document_content_range/1 after copy, before append).

Each {{key}} placeholder in the document is matched against the section whose range contains it; that section's variable_values[key] supplies the replacement. Placeholders outside all section ranges are left untouched.

Text substitution runs before image substitution (per image-substitution.md) and the document is re-fetched between the two phases so image indices are accurate after text edits. All operations within a phase are batched in a single batchUpdate in reverse-index order so no substitution shifts the indices of another.

@spec substitute_images(String.t(), map(), keyword()) ::
  {:ok, map() | :noop} | {:error, term()}

Two-step image substitution: GET the document, build the batch, send it.

fills is the same shape as build_image_batch_requests/2.

Options (used in tests):

• :get_fn — overrides get_document/1
• :batch_fn — overrides batch_update/2

@spec table_column_width_requests(integer(), [map()]) :: [map()]

Column-width companion used by build_table_fill_requests/3 (Phase 2, NOT the Phase 1b skeleton batch — see below). table_start_index must be a table's real, post-insert startIndex from a re-fetched document (the same value extract_table_cells/1's caller already has via match_new_tables/3's matched table element), never the location.index an insertTable request was given. column_properties is a table's captured column_properties list (see flatten_template_with_table_markers_and_styles/1), index-aligned to the table's columns.

Verified live against the real Docs API: insertTable at location.index = 8 produced a table whose actual startIndex was 9, one past the requested location — Google inserts an implicit paragraph break ahead of a table landing mid-paragraph, and updateTableColumnProperties rejects the un-adjusted index with INVALID_ARGUMENT: The provided table start location is invalid. This is exactly why finish_append_template/6 re-fetches after the skeleton batch before filling cells — this function rides along on that same re-fetch instead of trying to predict the offset analytically.

Only FIXED_WIDTH columns produce a request — EVENLY_DISTRIBUTED (or a column with no captured property) is already what a bare insertTable produces, so emitting a request for it would be a no-op round trip. One request per fixed column (the Docs API's columnIndices field lets one request retarget several columns sharing an identical width, but per- column source widths are rarely identical in practice, so this keeps the mapping simple and correct over minimizing request count).

Phase A — emits batchUpdate requests that delete the placeholder range and create a Google Docs table at its start index. After a doc re-fetch, fill_table_cells/3 populates the table.

@spec table_skeleton_requests([map()], %{required(integer()) => map()}) :: [map()]

Phase 1b of the append-with-tables pipeline (see append_template/3): for each located marker, delete the marker text and insert a bare table of its captured dimensions at that position. Sorted descending by start_index (same convention as substitute_all_text/4 and build_image_batch_requests/3) so earlier replacements in the list don't shift the indices of markers still to be processed.

Column widths are deliberately NOT applied here even though the table's captured column_properties are available at this point — see table_column_width_requests/2's doc for why insertTable's location index cannot be trusted as the resulting table's real tableStartLocation.

@spec text_style_requests(integer(), [map()]) :: [map()]

Builds updateTextStyle requests replaying captured per-run character style (see flatten_template_with_table_markers_and_styles/1's cell_runs / body_runs), anchored at base_index — the same index the corresponding insertText used. Adjacent runs sharing identical style are merged into one range first, but every non-empty run is still covered, including a plain run's explicit bold: false/italic: false — this is deliberate: a freshly inserted blob of text otherwise inherits its style from whatever character precedes it in the target document, so leaving a plain run unstyled would silently pick up bold/italic from neighboring content (seen live: an appended section's plain paragraph inheriting bold from an adjacent heading).

Safe to batch immediately after the insert it styles: text style changes never shift document character indices, so nothing else in the same batch needs to account for these requests' presence.

@spec upload_image_for_embedding(binary(), String.t(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Upload a raw image binary to Drive and return a public, embeddable URL.

Used when inserting an image into a Google Doc via insertInlineImage, which requires a fetchable URL (not raw bytes). Uploads the binary to Drive, grants anyone-with-link read access, and returns an lh3.googleusercontent.com/d/<id> URL that Google's image fetcher can read without following a redirect.

• data — raw image bytes
• mime_type — MIME type string, e.g. "image/jpeg"
• opts — optional keyword list; supports :name (file name, defaults to "embed-image")

@spec validate_file_id(term()) :: {:ok, String.t()} | {:error, :invalid_file_id}

Validate a Google Drive file/folder ID. Returns {:ok, id} or {:error, :invalid_file_id}.