Initial commit

Assisted-by: GLM 5.3

internal/payloads/dto.go

@@ -0,0 +1,335 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0
+
+package payloads
+
+import (
+	json "encoding/json/v2"
+	"fmt"
+	"strings"
+
+	"sourcedock.dev/petrbalvin/volumen/internal/biblio"
+	"sourcedock.dev/petrbalvin/volumen/internal/config"
+	"sourcedock.dev/petrbalvin/volumen/internal/identifiers"
+	"sourcedock.dev/petrbalvin/volumen/internal/post"
+)
+
+// Site is the /api/volumen/site payload: the [site] table as configured.
+type Site struct {
+	Title            string `json:"title"`
+	Description      string `json:"description"`
+	BaseURL          string `json:"base_url"`
+	Language         string `json:"language"`
+	Author           string `json:"author"`
+	FediverseCreator string `json:"fediverse_creator"`
+}
+
+// BuildSite reads the site block from the configuration.
+func BuildSite(cfg *config.Config) Site {
+	return Site{
+		Title:            cfg.Site.Title,
+		Description:      cfg.Site.Description,
+		BaseURL:          cfg.Site.BaseURL,
+		Language:         cfg.Site.Language,
+		Author:           cfg.Site.Author,
+		FediverseCreator: cfg.Site.FediverseCreator,
+	}
+}
+
+// Summary is the post shape used in list endpoints. Empty optional
+// fields are omitted rather than sent as null.
+type Summary struct {
+	Slug             string   `json:"slug,omitempty"`
+	Title            string   `json:"title,omitempty"`
+	Excerpt          string   `json:"excerpt"`
+	Date             string   `json:"date,omitempty"`
+	Lang             string   `json:"lang,omitempty"`
+	Tags             []string `json:"tags,omitempty"`
+	Author           string   `json:"author,omitempty"`
+	FediverseCreator string   `json:"fediverse_creator,omitempty"`
+
+	// DOI and ORCID carry the scholarly identifiers when the post has
+	// them: the bare identifier, normalised away from any doi.org URL or
+	// doi: prefix. A stored value that fails the syntax rule passes
+	// through untouched rather than vanishing from the read API.
+	DOI          string            `json:"doi,omitempty"`
+	ORCID        string            `json:"orcid,omitempty"`
+	Cover        string            `json:"cover,omitempty"`
+	CoverAlt     string            `json:"cover_alt,omitempty"`
+	CoverCaption string            `json:"cover_caption,omitempty"`
+	ReadingTime  int               `json:"reading_time"`
+	Translations map[string]string `json:"translations,omitempty"`
+	Series       string            `json:"series,omitempty"`
+	SeriesOrder  *int              `json:"series_order,omitempty"`
+	URL          string            `json:"url"`
+}
+
+// Meta is the SEO block attached to a post detail.
+type Meta struct {
+	URL     string         `json:"url"`
+	JSONLD  string         `json:"json_ld"`
+	OG      map[string]any `json:"og"`
+	Twitter map[string]any `json:"twitter"`
+}
+
+// Detail is Summary plus the body, rendered HTML, table of contents and
+// SEO metadata.
+type Detail struct {
+	Summary
+	Body string `json:"body"`
+	HTML string `json:"html"`
+	TOC  string `json:"toc"`
+	Meta Meta   `json:"meta"`
+
+	// Fields carries the frontmatter keys outside post.ReservedMetadata,
+	// the author's own. A post whose frontmatter holds only known keys
+	// omits the member.
+	Fields map[string]any `json:"fields,omitzero"`
+
+	// References is the structured bibliography from the post's refs
+	// frontmatter, resolved to identifiers; omitted when the post cites
+	// nothing.
+	References []biblio.Entry `json:"references,omitzero"`
+}
+
+// CountedName is one entry of the tag cloud and the series list.
+type CountedName struct {
+	Name  string `json:"name"`
+	Count int    `json:"count"`
+}
+
+// TagList is the /api/volumen/tags payload.
+type TagList struct {
+	Tags []CountedName `json:"tags"`
+}
+
+// SeriesList is the /api/volumen/series payload.
+type SeriesList struct {
+	Series []CountedName `json:"series"`
+}
+
+// SeriesDetail is the /api/volumen/series/{name} payload.
+type SeriesDetail struct {
+	Name  string    `json:"name"`
+	Count int       `json:"count"`
+	Posts []Summary `json:"posts"`
+}
+
+// Batch is the /api/volumen/posts/batch payload.
+type Batch struct {
+	Posts []Detail `json:"posts"`
+}
+
+// PostListBase carries the fields every paginated post list shares.
+type PostListBase struct {
+	PageSize int       `json:"page_size"`
+	Total    int       `json:"total"`
+	Posts    []Summary `json:"posts"`
+}
+
+// PageList is a page-numbered post list: it carries the page number and
+// the has_next/has_prev flags, and no cursor.
+type PageList struct {
+	PostListBase
+	Page    int  `json:"page"`
+	HasNext bool `json:"has_next"`
+	HasPrev bool `json:"has_prev"`
+}
+
+// CursorList is a cursor-paginated post list; next_cursor is always
+// present and is null when the cursor reached the end.
+type CursorList struct {
+	PostListBase
+	NextCursor *string `json:"next_cursor"`
+}
+
+// BuildSummary maps a post onto its API shape.
+func BuildSummary(p *post.Post) Summary {
+	summary := Summary{
+		Slug:             p.Slug(),
+		Title:            p.Title(),
+		Excerpt:          p.Excerpt(),
+		Date:             p.DateString(),
+		Lang:             p.Lang(),
+		Tags:             p.Tags(),
+		Author:           p.Author(),
+		FediverseCreator: p.FediverseCreator(),
+		DOI:              displayDOI(p.DOI()),
+		ORCID:            displayORCID(p.ORCID()),
+		Cover:            p.Cover(),
+		CoverAlt:         p.CoverAlt(),
+		CoverCaption:     p.CoverCaption(),
+		ReadingTime:      p.ReadingTime(),
+		Translations:     p.Translations(),
+		Series:           p.Series(),
+		URL:              fmt.Sprintf("/api/volumen/posts/%s", p.Slug()),
+	}
+	if order, ok := p.SeriesOrder(); ok {
+		summary.SeriesOrder = &order
+	}
+	return summary
+}
+
+// displayDOI normalises a stored DOI for the API: the bare identifier
+// when it is recognisable, the stored text trimmed when it is not, so a
+// hand-edited value is never silently dropped.
+func displayDOI(stored string) string {
+	bare := identifiers.NormalizeDOI(stored)
+	if bare == "" {
+		return ""
+	}
+	if !identifiers.ValidDOI(bare) {
+		return strings.TrimSpace(stored)
+	}
+	return bare
+}
+
+// displayORCID upper-cases a stored iD and keeps the raw text when the
+// shape is not an iD at all.
+func displayORCID(stored string) string {
+	id := identifiers.NormalizeORCID(stored)
+	if id == "" {
+		return ""
+	}
+	if !identifiers.ValidORCID(id) {
+		return strings.TrimSpace(stored)
+	}
+	return id
+}
+
+// BuildDetail maps a post onto its detail shape.
+func BuildDetail(p *post.Post, baseURL string) (Detail, error) {
+	htmlOut, err := p.HTML()
+	if err != nil {
+		return Detail{}, err
+	}
+	toc, err := p.TOC()
+	if err != nil {
+		return Detail{}, err
+	}
+	meta, err := BuildMeta(p, baseURL)
+	if err != nil {
+		return Detail{}, err
+	}
+	return Detail{
+		Summary:    BuildSummary(p),
+		Body:       p.Body,
+		HTML:       htmlOut,
+		TOC:        toc,
+		Meta:       meta,
+		Fields:     p.CustomFields(),
+		References: p.RefsLinked(),
+	}, nil
+}
+
+// BuildMeta builds the SEO and discovery metadata: a Schema.org Article
+// JSON-LD document plus OpenGraph and Twitter card fields.
+func BuildMeta(p *post.Post, baseURL string) (Meta, error) {
+	htmlOut, err := p.HTML()
+	if err != nil {
+		return Meta{}, err
+	}
+	plain := post.PlainText(htmlOut, 200)
+
+	base := trimTrailingSlash(baseURL)
+	url := "/api/volumen/posts/" + p.Slug()
+	if base != "" {
+		url = base + "/" + p.Slug()
+	}
+
+	title := p.Title()
+	if title == "" {
+		title = p.Slug()
+	}
+	description := p.Excerpt()
+	if description == "" {
+		description = plain
+	}
+	lang := p.Lang()
+	if lang == "" {
+		lang = "en"
+	}
+	dateStr := p.DateString()
+
+	article := map[string]any{
+		"@context":         "https://schema.org",
+		"@type":            "Article",
+		"headline":         title,
+		"description":      description,
+		"inLanguage":       lang,
+		"datePublished":    dateStr,
+		"dateModified":     dateStr,
+		"url":              url,
+		"mainEntityOfPage": map[string]any{"@type": "WebPage", "@id": url},
+	}
+	if author := p.Author(); author != "" {
+		person := map[string]any{"@type": "Person", "name": author}
+		if orcid := identifiers.ORCIDURL(p.ORCID()); orcid != "" {
+			person["identifier"] = orcid
+		}
+		article["author"] = person
+	} else if orcid := identifiers.ORCIDURL(p.ORCID()); orcid != "" {
+		article["author"] = map[string]any{
+			"@type":      "Person",
+			"identifier": orcid,
+		}
+	}
+	if doi := identifiers.DOIURL(p.DOI()); doi != "" {
+		article["identifier"] = doi
+	}
+	if citations := biblio.Citations(p.RefsLinked()); len(citations) > 0 {
+		article["citation"] = citations
+	}
+	if cover := p.Cover(); cover != "" {
+		article["image"] = []any{cover}
+	}
+	if tags := p.Tags(); len(tags) > 0 {
+		article["keywords"] = tags
+	}
+	if creator := p.FediverseCreator(); creator != "" {
+		article["creator"] = map[string]any{"@type": "Person", "name": creator}
+	}
+
+	og := map[string]any{
+		"og:type":                "article",
+		"og:title":               title,
+		"og:description":         description,
+		"og:url":                 url,
+		"og:locale":              lang,
+		"article:published_time": dateStr,
+	}
+	if cover := p.Cover(); cover != "" {
+		og["og:image"] = cover
+	}
+	if tags := p.Tags(); len(tags) > 0 {
+		og["article:tag"] = tags
+	}
+	if author := p.Author(); author != "" {
+		og["article:author"] = author
+	}
+
+	twitter := map[string]any{
+		"twitter:card":        "summary_large_image",
+		"twitter:title":       title,
+		"twitter:description": description,
+	}
+	if cover := p.Cover(); cover != "" {
+		twitter["twitter:image"] = cover
+	}
+	if creator := p.FediverseCreator(); creator != "" {
+		twitter["twitter:creator"] = creator
+	}
+
+	jsonLD, err := json.Marshal(article, json.Deterministic(true))
+	if err != nil {
+		return Meta{}, fmt.Errorf("encode json-ld: %w", err)
+	}
+	return Meta{
+		URL:     url,
+		JSONLD:  string(jsonLD),
+		OG:      og,
+		Twitter: twitter,
+	}, nil
+}
+
+func trimTrailingSlash(value string) string { return strings.TrimRight(value, "/") }