@spec count_pdfs(keyword()) :: non_neg_integer()

Returns the total PDF count, matching the optional status filter.

@spec create_pdf_from_upload(String.t(), String.t(), keyword()) ::
  {:ok, PhoenixKitCatalogue.Schemas.Pdf.t()} | {:error, term()}

Stores an uploaded PDF.

tmp_path is the local file from consume_uploaded_entry's callback. original_filename is the user's chosen name. byte_size is from entry.client_size.

Flow:

1. Storage.store_file/2 (core) — handles SHA-256 dedup, on-disk placement, multi-bucket redundancy. Same content uploaded twice (any name) returns the same file_uuid.
2. Upsert the per-file extraction row. If newly created, enqueue the worker — otherwise the previous extraction is reused.
3. Always insert a fresh phoenix_kit_cat_pdfs row so each upload gets its own per-name entry in the library.
4. Activity action: pdf.uploaded. Metadata flags content_dedup: true when the file row was a hit.

Returns {:ok, pdf} on success.

The persisted byte_size is read from the file on disk via File.stat!/1 — never from a browser-supplied value — so the recorded size always matches the actual stored bytes.

@spec get_extraction(PhoenixKitCatalogue.Schemas.Pdf.t() | Ecto.UUID.t()) ::
  PhoenixKitCatalogue.Schemas.PdfExtraction.t() | nil

Returns the extraction state for a PDF (or its file_uuid), or nil if the file has no extraction row yet.

@spec get_pdf(Ecto.UUID.t()) :: PhoenixKitCatalogue.Schemas.Pdf.t() | nil

Fetches a PDF by UUID. Returns nil if not found.

@spec get_pdf!(Ecto.UUID.t()) :: PhoenixKitCatalogue.Schemas.Pdf.t()

Fetches a PDF by UUID. Raises Ecto.NoResultsError if not found.

@spec list_pdfs(keyword()) :: [PhoenixKitCatalogue.Schemas.Pdf.t()]

Lists PDFs in the library, newest first.

Options

• :status — filter to a status string ("active" / "trashed"). Pass nil to include all. Defaults to "active".
• :limit (default 100), :offset (default 0)

@spec more_pdf_matches_for_item(
  PhoenixKitCatalogue.Schemas.Item.t(),
  Ecto.UUID.t(),
  keyword()
) :: [
  hit()
]

Loads additional hits for one PDF beyond what the initial grouped search returned. Used by the modal's per-PDF "Show more matches" expand action.

Returns a flat list of hit() ordered by page_number ASC (literal search) or similarity DESC (when a :trigram_query opt is given).

Options

• :offset (default 0)
• :limit (default 50)
• :trigram_query — when set, score by pg_trgm similarity against this string (matches the trigram fallback's ordering).

@spec permanently_delete_pdf(
  PhoenixKitCatalogue.Schemas.Pdf.t(),
  keyword()
) :: {:ok, PhoenixKitCatalogue.Schemas.Pdf.t()} | {:error, Ecto.Changeset.t()}

Permanently removes a phoenix_kit_cat_pdfs row.

When this is the last (active OR trashed) row referencing the underlying file_uuid, hands the file off to Storage.trash_file/1 so core's daily PruneTrashJob deletes the binary, cascading to the extraction and page rows.

@spec prune_orphan_page_contents() :: non_neg_integer()

Removes phoenix_kit_cat_pdf_page_contents rows that no phoenix_kit_cat_pdf_pages row references anymore. Safe to call any time.

Returns the number of rows removed. Suitable for wiring to a daily Oban cron once the corpus is large enough to care.

@spec restore_pdf(
  PhoenixKitCatalogue.Schemas.Pdf.t(),
  keyword()
) :: {:ok, PhoenixKitCatalogue.Schemas.Pdf.t()} | {:error, Ecto.Changeset.t()}

Restores a trashed PDF back to active.

@spec search_pdfs_for_item(
  PhoenixKitCatalogue.Schemas.Item.t(),
  keyword()
) :: [group()]

Searches the PDF library for any active PDF whose pages match one of the item's translated names.

Returns groups keyed by PDF, each with the total match count for the corpus plus the first :per_pdf hits (default 5). Use more_pdf_matches_for_item/3 to load additional hits within one PDF on demand (the "Show more matches" expand action).

Strategy:

1. Build the title list from the item's primary name + every enabled language's translated name. Drop blanks and duplicates.
2. Literal ILIKE ANY against the deduped page-content table — fast and precise. Joined to active phoenix_kit_cat_pdfs rows via file_uuid. Rows are window-ranked per PDF and window-counted per PDF in a single SQL pass; the outer query caps at rn <= per_pdf so the result is bounded by per_pdf × distinct PDFs that match.
3. If literal returns nothing, fall back to a pg_trgm similarity search using the longest title (default threshold 0.4) — same grouping shape, best similarity first within each PDF.

Trashed PDFs are excluded. Groups are ordered newest-PDF-first.

Options

• :per_pdf (default 5) — preview hits returned per PDF.
• :similarity_threshold (default 0.4) — trigram fallback threshold.

@spec trash_pdf(
  PhoenixKitCatalogue.Schemas.Pdf.t(),
  keyword()
) :: {:ok, PhoenixKitCatalogue.Schemas.Pdf.t()} | {:error, Ecto.Changeset.t()}

Soft-deletes a PDF: flips status to "trashed" and records trashed_at. Underlying file + extraction + page rows untouched (other live PDF entries may still reference them).