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

Returns the active provider key, including connection slug if configured.

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

Send a batchUpdate request to a Google Doc.

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

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

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