@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()) ::
  {:ok, {integer(), integer()}} | {:error, term()}

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

Inserts a page break followed by the full text 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.

@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 connection_status() :: {:ok, %{email: String.t()}} | {:error, atom()}

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

@spec copy_document(String.t()) :: {: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.

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

@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 move_file(String.t(), String.t()) ::
  :ok
  | {:error,
     :invalid_file_id | :move_failed | :get_file_parents_failed | term()}

Move a file to a different folder 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 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 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}.