PhoenixKitDocumentCreator.Documents (PhoenixKitDocumentCreator v0.2.5)

Copy Markdown View Source

Context module for managing templates and documents via Google Drive.

Google Drive is the single source of truth for file content. This module mirrors file metadata (name, google_doc_id, status, thumbnails, variables) to the local database for fast listing and audit tracking.

API layers

This module provides combined operations (Drive + DB). For direct access:

Summary

Functions

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

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

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

Move a document to the deleted/documents folder.

Move a template to the deleted/templates folder.

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

Get the Google Drive URL for the documents folder.

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

Fetch thumbnails for a list of Drive files asynchronously.

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

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

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

Load cached thumbnails from DB for a list of google_doc_ids.

Log a manual user action to the activity feed.

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

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

Persist a thumbnail data URI to the DB by google_doc_id.

Re-discover folder IDs from Drive.

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

Sync local DB with Google Drive.

Get the Google Drive URL for the templates folder.

Upsert a document record from a Google Drive file map.

Upsert a template record from a Google Drive file map.

Functions

create_document(name \\ "Untitled Document", opts \\ [])

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

create_document_from_template(template_file_id, variable_values, opts \\ [])

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

create_template(name \\ "Untitled Template", opts \\ [])

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

delete_document(file_id, opts \\ [])

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

delete_template(file_id, opts \\ [])

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

detect_variables(file_id)

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

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

documents_folder_url()

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

Get the Google Drive URL for the documents folder.

export_pdf(file_id, opts \\ [])

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

fetch_thumbnails_async(files, caller_pid)

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

get_folder_ids()

@spec get_folder_ids() :: map()

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

list_documents_from_db()

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

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

list_templates_from_db()

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

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

load_cached_thumbnails(google_doc_ids)

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

Load cached thumbnails from DB for a list of google_doc_ids.

log_manual_action(action, opts \\ [])

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

Log a manual user action to the activity feed.

move_to_documents(file_id, opts \\ [])

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

move_to_templates(file_id, opts \\ [])

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

persist_thumbnail(google_doc_id, data_uri)

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

Persist a thumbnail data URI to the DB by google_doc_id.

refresh_folders()

@spec refresh_folders() :: map()

Re-discover folder IDs from Drive.

set_correct_location(file_id, opts \\ [])

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

sync_from_drive()

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

templates_folder_url()

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

Get the Google Drive URL for the templates folder.

upsert_document_from_drive(file, extra_attrs \\ %{})

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

upsert_template_from_drive(file, extra_attrs \\ %{})

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