@dineway-ai/plugin-seo-graph 0.1.7

package/src/schema/index.ts

@@ -0,0 +1,175 @@
+import {
+	assembleGraph,
+	buildBreadcrumbList,
+	buildImageObject,
+	buildPiece,
+	buildSiteNavigationElement,
+	makeIds,
+	type GraphEntity,
+} from "@jdevalk/seo-graph-core";
+import type { PublicPageContext } from "dineway";
+import type { Blog } from "schema-dts";
+
+import type { SeoSettings } from "../settings.js";
+import { buildArticle } from "./article.js";
+import { buildBreadcrumbs } from "./breadcrumb.js";
+import { buildSiteEntity, getSiteEntityId } from "./organization.js";
+import { buildAuthorPerson } from "./person.js";
+import { buildWebPage } from "./webpage.js";
+import { buildWebSite } from "./website.js";
+
+const TRAILING_SLASH_RE = /\/$/;
+
+/**
+ * Build the complete JSON-LD schema graph for a page.
+ * Outputs a @graph array with distinct, linked nodes.
+ *
+ * Individual piece builders delegate to `@jdevalk/seo-graph-core`'s
+ * typed builders (`buildWebSite`, `buildWebPage`, `buildArticle`,
+ * `buildPiece<Organization>`, `buildPiece<Person>`) with thin
+ * Dineway-specific wrappers that map Dineway's page/settings model
+ * onto core's input types. This keeps both Dineway and joost.blog on
+ * the same code path for graph construction, not just the ID scheme.
+ */
+export function buildSchemaGraph(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	siteUrl: string,
+	siteName: string,
+	canonical: string | null,
+	ogTitle: string,
+	description: string | null,
+	locale: string,
+	keywords?: string[],
+	articleSection?: string,
+): Record<string, unknown> | null {
+	// No schema for 404 pages
+	if (page.path === "/404") return null;
+
+	const ids = makeIds({
+		siteUrl,
+		personUrl: settings.personUrl || undefined,
+	});
+
+	// Compute breadcrumbs early so the WebPage node can carry a
+	// back-reference (`breadcrumb: { "@id": ... }`) when present.
+	const crumbs = buildBreadcrumbs(page, settings, siteUrl);
+	const hasBreadcrumbs = crumbs !== null && crumbs.length > 1;
+	const pageUrl = canonical || page.url;
+	const siteEntityId = getSiteEntityId(settings, ids);
+
+	// Derive Blog @id when blog settings are configured.
+	const blogId = settings.blogUrl
+		? `${settings.blogUrl.replace(TRAILING_SLASH_RE, "")}/#blog`
+		: null;
+
+	const pieces: GraphEntity[] = [];
+
+	// 1. Site entity (Organization or Person) - always present
+	pieces.push(buildSiteEntity(settings, siteUrl, siteName, locale, ids) as GraphEntity);
+
+	// 2. WebSite - always present
+	const hasNavigation = settings.navigationItems.length > 0;
+	pieces.push(
+		buildWebSite(
+			settings,
+			siteUrl,
+			siteName,
+			settings.defaultDescription || null,
+			locale,
+			ids,
+			hasNavigation,
+		) as GraphEntity,
+	);
+
+	// 3. SiteNavigationElement - when navigation items are configured
+	if (hasNavigation) {
+		pieces.push(
+			buildSiteNavigationElement(
+				{
+					name: "Main navigation",
+					isPartOf: { "@id": ids.website },
+					items: settings.navigationItems,
+				},
+				ids,
+			) as GraphEntity,
+		);
+	}
+
+	// 4. Blog entity - when blog URL is configured
+	if (blogId && settings.blogUrl) {
+		pieces.push(
+			buildPiece<Blog>({
+				"@type": "Blog",
+				"@id": blogId,
+				name: settings.blogName || "Blog",
+				url: settings.blogUrl,
+				publisher: { "@id": siteEntityId },
+				inLanguage: locale,
+			}) as GraphEntity,
+		);
+	}
+
+	// 5. WebPage - always present
+	pieces.push(
+		buildWebPage(
+			page,
+			settings,
+			canonical,
+			ogTitle,
+			description,
+			locale,
+			ids,
+			hasBreadcrumbs,
+			siteEntityId,
+		) as GraphEntity,
+	);
+
+	// 6. BreadcrumbList - when derived/ruled with >1 crumb
+	if (hasBreadcrumbs) {
+		pieces.push(buildBreadcrumbList({ url: pageUrl, items: crumbs }, ids) as GraphEntity);
+	}
+
+	// 7. Primary ImageObject - when the page has an image
+	if (page.image) {
+		pieces.push(
+			buildImageObject(
+				{
+					pageUrl,
+					url: page.image,
+					width: 1200,
+					height: 675,
+					inLanguage: locale,
+				},
+				ids,
+			) as GraphEntity,
+		);
+	}
+
+	// 8. Article + Author Person - for content pages with article meta
+	if (page.kind === "content" && page.articleMeta?.publishedTime) {
+		const article = buildArticle(
+			page,
+			settings,
+			siteName,
+			canonical,
+			ogTitle,
+			description,
+			locale,
+			ids,
+			blogId,
+			keywords,
+			articleSection,
+		);
+		if (article) pieces.push(article as GraphEntity);
+
+		// For Organization sites the author Person is a distinct entity
+		// from the site entity, so emit it separately. For Person sites
+		// the site entity already is this Person — assembleGraph's
+		// first-wins dedupe keeps the richer site-entity version.
+		const author = buildAuthorPerson(settings, siteName, ids);
+		if (author) pieces.push(author as GraphEntity);
+	}
+
+	return assembleGraph(pieces, { warnOnDanglingReferences: true });
+}

package/src/schema/organization.ts

@@ -0,0 +1,133 @@
+import { buildPiece } from "@jdevalk/seo-graph-core";
+import type { IdFactory } from "@jdevalk/seo-graph-core";
+import type { Organization, Person } from "schema-dts";
+
+import type { SeoSettings } from "../settings.js";
+
+const TRAILING_SLASH_RE = /\/$/;
+const NON_ALPHANUMERIC_RE = /[^a-z0-9]+/g;
+const EDGE_DASH_RE = /(^-|-$)/g;
+
+/**
+ * Build the Organization or Person node representing the site entity.
+ * Every page includes an Organization or Person node.
+ */
+export function buildSiteEntity(
+	settings: SeoSettings,
+	siteUrl: string,
+	siteName: string,
+	locale: string,
+	ids: IdFactory,
+): Record<string, unknown> {
+	const baseUrl = siteUrl.replace(TRAILING_SLASH_RE, "");
+
+	if (settings.siteRepresents === "organization") {
+		return buildOrganizationEntity(settings, baseUrl, siteName, locale, ids);
+	}
+
+	return buildPersonEntity(settings, baseUrl, siteName, locale, ids);
+}
+
+function buildOrganizationEntity(
+	settings: SeoSettings,
+	baseUrl: string,
+	siteName: string,
+	locale: string,
+	ids: IdFactory,
+): Record<string, unknown> {
+	const orgLogoId = `${baseUrl}/#/schema.org/ImageObject/logo`;
+
+	const piece = buildPiece<Organization>({
+		"@type": "Organization",
+		"@id": ids.organization(orgSlug(settings)),
+		name: settings.orgName || siteName,
+		url: baseUrl,
+	});
+
+	if (settings.orgLogoUrl) {
+		piece.logo = {
+			"@type": "ImageObject",
+			"@id": orgLogoId,
+			url: settings.orgLogoUrl,
+			contentUrl: settings.orgLogoUrl,
+			inLanguage: locale,
+		};
+		piece.image = { "@id": orgLogoId };
+	}
+
+	if (settings.socials.length > 0) {
+		piece.sameAs = settings.socials;
+	}
+
+	if (settings.publishingPrinciples) {
+		piece.publishingPrinciples = settings.publishingPrinciples;
+	}
+
+	return piece;
+}
+
+function buildPersonEntity(
+	settings: SeoSettings,
+	baseUrl: string,
+	siteName: string,
+	locale: string,
+	ids: IdFactory,
+): Record<string, unknown> {
+	const name = settings.personName || siteName;
+
+	const piece = buildPiece<Person>({
+		"@type": "Person",
+		"@id": ids.person,
+		name,
+		url: baseUrl,
+	});
+
+	if (settings.personDescription) {
+		piece.description = settings.personDescription.slice(0, 250);
+	}
+
+	if (settings.personJobTitle) {
+		piece.jobTitle = settings.personJobTitle;
+	}
+
+	if (settings.personImageUrl) {
+		piece.image = {
+			"@type": "ImageObject",
+			"@id": ids.personImage,
+			url: settings.personImageUrl,
+			contentUrl: settings.personImageUrl,
+			inLanguage: locale,
+			caption: name,
+		};
+	}
+
+	if (settings.socials.length > 0) {
+		piece.sameAs = settings.socials;
+	}
+
+	if (settings.publishingPrinciples) {
+		piece.publishingPrinciples = settings.publishingPrinciples;
+	}
+
+	return piece;
+}
+
+/**
+ * Get the @id reference for the site entity — either the site-wide
+ * Person or an Organization. Used by other pieces (Article, WebSite)
+ * that need to reference the publisher.
+ */
+export function getSiteEntityId(settings: SeoSettings, ids: IdFactory): string {
+	if (settings.siteRepresents === "organization") {
+		return ids.organization(orgSlug(settings));
+	}
+	return ids.person;
+}
+
+/**
+ * Slugify the organization name for use as the Organization @id slug.
+ */
+function orgSlug(settings: SeoSettings): string {
+	const name = settings.orgName || "site";
+	return name.toLowerCase().replace(NON_ALPHANUMERIC_RE, "-").replace(EDGE_DASH_RE, "") || "site";
+}

package/src/schema/person.ts

@@ -0,0 +1,54 @@
+import { buildPiece } from "@jdevalk/seo-graph-core";
+import type { IdFactory } from "@jdevalk/seo-graph-core";
+import type { Person } from "schema-dts";
+
+import type { SeoSettings } from "../settings.js";
+
+/**
+ * Build the author Person schema node. Returned as a separate piece
+ * only when the site represents an Organization — for Person sites
+ * the site entity already covers this node.
+ *
+ * Required fields are @type, @id, name. Names like "admin" are
+ * rejected per schema.org best practice.
+ */
+export function buildAuthorPerson(
+	settings: SeoSettings,
+	siteName: string,
+	ids: IdFactory,
+): Record<string, unknown> | null {
+	const name = settings.personName || siteName;
+
+	// Per spec: reject "admin" or similar invalid author names
+	if (!name || name.toLowerCase() === "admin") return null;
+
+	const piece = buildPiece<Person>({
+		"@type": "Person",
+		"@id": ids.person,
+		name,
+	});
+
+	if (settings.personDescription) {
+		piece.description = settings.personDescription.slice(0, 250);
+	}
+
+	if (settings.personUrl) {
+		piece.url = settings.personUrl;
+	}
+
+	if (settings.personImageUrl) {
+		piece.image = {
+			"@type": "ImageObject",
+			"@id": ids.personImage,
+			url: settings.personImageUrl,
+			contentUrl: settings.personImageUrl,
+			caption: name,
+		};
+	}
+
+	if (settings.socials.length > 0) {
+		piece.sameAs = settings.socials;
+	}
+
+	return piece;
+}

package/src/schema/webpage.ts

@@ -0,0 +1,84 @@
+import { buildWebPage as coreBuildWebPage, type WebPageType } from "@jdevalk/seo-graph-core";
+import type { IdFactory, Reference } from "@jdevalk/seo-graph-core";
+import type { PublicPageContext } from "dineway";
+
+import type { SeoSettings } from "../settings.js";
+
+const COLLECTION_PAGE_PATHS = new Set(["/", "/posts", "/posts/", "/videos", "/videos/"]);
+
+const PROFILE_PAGE_PATHS = new Set(["/about", "/about/"]);
+
+/**
+ * Determine the WebPage @type based on the page path.
+ */
+function getWebPageType(page: PublicPageContext): WebPageType {
+	const path = page.path || "/";
+
+	if (PROFILE_PAGE_PATHS.has(path)) return "ProfilePage";
+	if (COLLECTION_PAGE_PATHS.has(path)) return "CollectionPage";
+	if (path.startsWith("/categories/")) return "CollectionPage";
+	if (path.startsWith("/tags/")) return "CollectionPage";
+
+	return "WebPage";
+}
+
+/**
+ * Build the WebPage schema node.
+ * Every page includes a WebPage node.
+ *
+ * When `hasBreadcrumbs` is true, a `breadcrumb` back-reference is
+ * added pointing at the BreadcrumbList entity. Callers are
+ * responsible for emitting the matching BreadcrumbList piece.
+ */
+export function buildWebPage(
+	page: PublicPageContext,
+	settings: SeoSettings,
+	canonical: string | null,
+	ogTitle: string,
+	description: string | null,
+	locale: string,
+	ids: IdFactory,
+	hasBreadcrumbs: boolean,
+	siteEntityId: string,
+): Record<string, unknown> {
+	const pageUrl = canonical || page.url;
+	const type = getWebPageType(page);
+
+	// Homepage and ProfilePage carry an `about` reference to the site entity.
+	const isAboutPage = type === "ProfilePage" || (page.path || "/") === "/";
+	const about: Reference | undefined = isAboutPage ? { "@id": siteEntityId } : undefined;
+
+	// Primary image reference when the page has an image.
+	const primaryImage: Reference | undefined = page.image
+		? { "@id": ids.primaryImage(pageUrl) }
+		: undefined;
+
+	// Copyright fields from settings.
+	const copyrightHolder: Reference | undefined = settings.copyrightYear
+		? { "@id": siteEntityId }
+		: undefined;
+
+	return coreBuildWebPage(
+		{
+			url: pageUrl,
+			name: ogTitle,
+			isPartOf: { "@id": ids.website },
+			inLanguage: locale,
+			description: description || undefined,
+			breadcrumb: hasBreadcrumbs ? { "@id": ids.breadcrumb(pageUrl) } : undefined,
+			datePublished: page.articleMeta?.publishedTime
+				? new Date(page.articleMeta.publishedTime)
+				: undefined,
+			dateModified: page.articleMeta?.modifiedTime
+				? new Date(page.articleMeta.modifiedTime)
+				: undefined,
+			about,
+			primaryImage,
+			copyrightHolder,
+			copyrightYear: settings.copyrightYear || undefined,
+			license: settings.licenseUrl || undefined,
+		},
+		ids,
+		type,
+	);
+}

package/src/schema/website.ts

@@ -0,0 +1,52 @@
+import { buildWebSite as coreBuildWebSite } from "@jdevalk/seo-graph-core";
+import type { IdFactory } from "@jdevalk/seo-graph-core";
+
+import type { SeoSettings } from "../settings.js";
+import { getSiteEntityId } from "./organization.js";
+
+const TRAILING_SLASH_RE = /\/$/;
+
+/**
+ * Build the WebSite schema node.
+ * Every page includes a WebSite node with SearchAction.
+ */
+export function buildWebSite(
+	settings: SeoSettings,
+	siteUrl: string,
+	siteName: string,
+	siteDescription: string | null,
+	locale: string,
+	ids: IdFactory,
+	hasNavigation: boolean,
+): Record<string, unknown> {
+	const baseUrl = siteUrl.replace(TRAILING_SLASH_RE, "");
+
+	const piece = coreBuildWebSite(
+		{
+			url: `${baseUrl}/`,
+			name: siteName,
+			publisher: { "@id": getSiteEntityId(settings, ids) },
+			inLanguage: locale,
+			description: siteDescription || undefined,
+			hasPart: hasNavigation ? { "@id": ids.navigation } : undefined,
+		},
+		ids,
+	);
+
+	// SearchAction with Google's query-input extension — not in schema-dts
+	// types, so set directly on the result.
+	piece.potentialAction = {
+		"@type": "SearchAction",
+		target: {
+			"@type": "EntryPoint",
+			urlTemplate: `${baseUrl}/search?q={search_term_string}`,
+		},
+		"query-input": {
+			"@type": "PropertyValueSpecification",
+			valueRequired: "http://schema.org/True",
+			valueName: "search_term_string",
+		},
+	};
+
+	return piece;
+}