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

Create a blank document in the documents folder. Returns {:ok, %{doc_id, name, url}}.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

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

Create a document from a template by copying and filling variables.

1. Copies the template Google Doc to the documents folder
2. Replaces all {{variable}} placeholders with values
3. Persists the document record with variable_values and template link
4. Returns {:ok, %{doc_id, url}}

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

Create a blank template in the templates folder. Returns {:ok, %{doc_id, name, url}}.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

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

Move a document to the deleted/documents folder.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

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

Move a template to the deleted/templates folder.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

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

Detect {{ variables }} in a Google Doc's text content.

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

Get the Google Drive URL for the documents folder.

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

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

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)
• :name — document name (for activity metadata)

@spec fetch_thumbnails_async([map()], pid()) :: :ok

Fetch thumbnails for a list of Drive files asynchronously.

Spawns a task per file that sends {:thumbnail_result, file_id, data_uri} back to the caller. Also persists thumbnails to the DB.

@spec get_folder_ids() :: map()

Get the folder IDs (auto-discovers if not cached).

@spec list_documents_from_db() :: [map()]

List documents from the local DB. Returns maps compatible with the LiveView.

@spec list_templates_from_db() :: [map()]

List templates from the local DB. Returns maps compatible with the LiveView.

@spec load_cached_thumbnails([String.t()] | any()) :: %{
  required(String.t()) => String.t()
}

Load cached thumbnails from DB for a list of google_doc_ids.

@spec log_manual_action(
  String.t(),
  keyword()
) :: :ok

Log a manual user action to the activity feed.

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

Move a file into the managed documents folder and classify it as a document.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

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

Move a file into the managed templates folder and classify it as a template.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

@spec persist_thumbnail(String.t(), String.t()) :: :ok

Persist a thumbnail data URI to the DB by google_doc_id.

@spec refresh_folders() :: map()

Re-discover folder IDs from Drive.

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

Persist the file's current parent folder as its accepted location.

Options

• :actor_uuid — UUID of the user performing the action (for activity logging)

@spec sync_from_drive() :: :ok | {:error, :sync_failed}

Sync local DB with Google Drive.

Fetches file lists from both Drive folders, upserts all found files, marks DB records as "lost" if their google_doc_id is no longer in Drive, and recovers "lost" records that reappear.

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

Get the Google Drive URL for the templates folder.

@spec upsert_document_from_drive(map(), map()) ::
  {:ok, PhoenixKitDocumentCreator.Schemas.Document.t()}
  | {:error, Ecto.Changeset.t()}

Upsert a document record from a Google Drive file map.

@spec upsert_template_from_drive(map(), map()) ::
  {:ok, PhoenixKitDocumentCreator.Schemas.Template.t()}
  | {:error, Ecto.Changeset.t()}

Upsert a template record from a Google Drive file map.