@businessdash/sdk 0.9.60 → 0.9.80

package/src/seed.ts

@@ -0,0 +1,7 @@
+/**
+ * `@businessdash/sdk/seed` — schema push and data seeding from any build step.
+ *
+ * @module
+ */
+
+export * from "./seed-core/index.js";

package/src/seo-core/blog.ts

@@ -0,0 +1,216 @@
+/**
+ * SEO for blog posts and blog listings.
+ *
+ * ## Why a post needs more than a title
+ *
+ * A `BlogPosting` node is what turns a link in search results into a dated,
+ * attributed article card. Without it a post competes as a bare URL, and the
+ * publish date — the thing readers use to decide whether it is still true —
+ * never appears.
+ *
+ * ## Gated posts stay indexed, and say so
+ *
+ * A subscriber-only post should still be findable: being discoverable is how
+ * anyone subscribes. But serving a full article to a crawler and a paywall to
+ * a reader is **cloaking**, which is penalised.
+ *
+ * The correct answer is schema.org's paywall markup — `isAccessibleForFree:
+ * false` plus a `hasPart` naming the gated region. That tells a crawler the
+ * content is restricted, so the difference between what it sees and what a
+ * reader sees is declared rather than deceptive.
+ *
+ * @module
+ */
+
+import { article, breadcrumb, type JsonLdNode } from "../seo.js";
+
+import type { MetaTag, SeoInput } from "./index.js";
+
+/** A blog post, as it arrives from the platform. */
+export type BlogPostSeoSource = {
+	title: string;
+	slug: string;
+	excerpt?: string | null;
+	imageUrl?: string | null;
+	publishedAt?: string | null;
+	updatedAt?: string | null;
+	authorName?: string | null;
+	tags?: string[];
+	/**
+	 * `public` is open. Anything else is gated — the platform writes both
+	 * `members`/`subscribers` and `followers`/`paid` into this column, so
+	 * anything that is not `public` is treated as restricted.
+	 */
+	accessLevel?: string | null;
+};
+
+export type BlogPostSeoInput = {
+	siteUrl: string;
+	post: BlogPostSeoSource;
+	/** Path of this post, e.g. `/blog/my-post`. Defaults to `/blog/{slug}`. */
+	path?: string;
+	/** Extra crumbs between Home and the post. */
+	breadcrumbs?: Array<{ name: string; url: string }>;
+	/**
+	 * CSS selector wrapping the gated body, for the paywall markup.
+	 *
+	 * Defaults to `.biab-post-body`. It only has to match the element your
+	 * template actually hides — a selector that matches nothing makes the
+	 * markup a claim you are not backing up.
+	 */
+	paywallSelector?: string;
+};
+
+function isGated(accessLevel: string | null | undefined): boolean {
+	const value = (accessLevel ?? "public").trim();
+	// Anything unrecognised counts as gated. Being wrong the other way means
+	// declaring open access for content that is actually restricted, which is
+	// the cloaking case.
+	return value !== "public" && value !== "";
+}
+
+/**
+ * SEO for one blog post.
+ *
+ * ```ts
+ * const seo = resolveSeo(layoutDefaults, blogPostSeo({ siteUrl, post }))
+ * ```
+ */
+export function blogPostSeo(input: BlogPostSeoInput): SeoInput {
+	const { post } = input;
+	const path = input.path ?? `/blog/${post.slug}`;
+	const canonical = `${input.siteUrl.replace(/\/+$/, "")}${path}`;
+	const gated = isGated(post.accessLevel);
+
+	const description = post.excerpt?.trim() || undefined;
+
+	const node = article({
+		siteUrl: input.siteUrl,
+		headline: post.title,
+		description: description ?? post.title,
+		slug: post.slug,
+		pubDate: post.publishedAt ?? new Date(0).toISOString(),
+		...(post.updatedAt ? { updatedDate: post.updatedAt } : {}),
+		...(post.authorName ? { authorName: post.authorName } : {}),
+		...(post.imageUrl ? { heroImageUrl: post.imageUrl } : {}),
+	}) as JsonLdNode;
+
+	// The post's real URL, which may not be `/blog/{slug}` if the consumer
+	// routes differently. `article()` assumes that shape; correct it here
+	// rather than shipping a mainEntityOfPage that 404s.
+	node["mainEntityOfPage"] = canonical;
+	node["url"] = canonical;
+	if (post.tags?.length) node["keywords"] = post.tags.join(", ");
+
+	// Paywall markup — see the note at the top of this module.
+	node["isAccessibleForFree"] = !gated;
+	if (gated) {
+		node["hasPart"] = {
+			"@type": "WebPageElement",
+			isAccessibleForFree: false,
+			cssSelector: input.paywallSelector ?? ".biab-post-body",
+		};
+	}
+
+	const extraMeta: MetaTag[] = [];
+	if (post.publishedAt) {
+		extraMeta.push({
+			property: "article:published_time",
+			content: post.publishedAt,
+		});
+	}
+	if (post.updatedAt) {
+		extraMeta.push({
+			property: "article:modified_time",
+			content: post.updatedAt,
+		});
+	}
+	if (post.authorName) {
+		extraMeta.push({ property: "article:author", content: post.authorName });
+	}
+	for (const tag of post.tags ?? []) {
+		extraMeta.push({ property: "article:tag", content: tag });
+	}
+
+	return {
+		title: post.title,
+		...(description ? { description } : {}),
+		canonical,
+		...(post.imageUrl ? { ogImage: post.imageUrl } : {}),
+		// Not "website": social cards for articles show the date and byline.
+		ogType: "article",
+		...(post.tags?.length ? { keywords: post.tags } : {}),
+		extraMeta,
+		jsonLd: [
+			node,
+			breadcrumb({
+				siteUrl: input.siteUrl,
+				items: [
+					{ name: "Home", url: input.siteUrl },
+					{ name: "Blog", url: `${input.siteUrl.replace(/\/+$/, "")}/blog` },
+					...(input.breadcrumbs ?? []),
+					{ name: post.title, url: canonical },
+				],
+			}),
+		],
+	};
+}
+
+export type BlogListingSeoInput = {
+	siteUrl: string;
+	/** Path of the listing, e.g. `/blog` or `/blog/tag/plumbing`. */
+	path?: string;
+	title?: string;
+	description?: string;
+	posts: readonly BlogPostSeoSource[];
+	/** Path builder, when posts do not live at `/blog/{slug}`. */
+	postPath?: (post: BlogPostSeoSource) => string;
+	/**
+	 * Page number, for paginated archives.
+	 *
+	 * Pages 2+ are marked `noindex, follow` by convention: the individual posts
+	 * are what should rank, and thin archive pages competing with them splits
+	 * the signal. Links are still followed so the posts stay reachable.
+	 */
+	page?: number;
+};
+
+/**
+ * SEO for a blog index or archive.
+ *
+ * Emits a `Blog` node with an `ItemList` of the posts on this page, so a
+ * crawler can see the structure without fetching every post.
+ */
+export function blogListingSeo(input: BlogListingSeoInput): SeoInput {
+	const base = input.siteUrl.replace(/\/+$/, "");
+	const path = input.path ?? "/blog";
+	const canonical = `${base}${path}`;
+	const postPath =
+		input.postPath ?? ((p: BlogPostSeoSource) => `/blog/${p.slug}`);
+	const page = input.page ?? 1;
+
+	const node: JsonLdNode = {
+		"@context": "https://schema.org",
+		"@type": "Blog",
+		url: canonical,
+		...(input.title ? { name: input.title } : {}),
+		...(input.description ? { description: input.description } : {}),
+		blogPost: input.posts.map((post) => ({
+			"@type": "BlogPosting",
+			headline: post.title,
+			url: `${base}${postPath(post)}`,
+			...(post.publishedAt ? { datePublished: post.publishedAt } : {}),
+			...(post.imageUrl ? { image: post.imageUrl } : {}),
+		})),
+	};
+
+	return {
+		...(input.title ? { title: input.title } : {}),
+		...(input.description ? { description: input.description } : {}),
+		canonical,
+		// Thin archive pages competing with the posts themselves splits the
+		// signal; the posts are what should rank.
+		...(page > 1 ? { noIndex: true } : {}),
+		jsonLd: [node],
+	};
+}

package/src/seo-core/commerce.ts

@@ -0,0 +1,138 @@
+/**
+ * SEO for storefront listings — the category and collection pages.
+ *
+ * A product page has `productPageSeo`. The page ABOVE it needs different
+ * markup: `CollectionPage` with an `ItemList`, so a crawler can see what the
+ * category contains without fetching every product, and so the listing ranks
+ * for the category term instead of competing with its own products.
+ *
+ * @module
+ */
+
+import { breadcrumb, type JsonLdNode } from "../seo.js";
+
+import type { SeoInput } from "./index.js";
+
+/** A product as it appears in a listing. */
+export type ListedProduct = {
+	name: string;
+	/** Path or absolute URL of the product page. */
+	url: string;
+	image?: string | null;
+	/** Integer cents. */
+	priceCents?: number | null;
+	currency?: string | null;
+	availability?: "InStock" | "OutOfStock" | "PreOrder";
+};
+
+export type ProductListingSeoInput = {
+	siteUrl: string;
+	/** Path of the listing, e.g. `/shop` or `/shop/tools`. */
+	path: string;
+	title?: string;
+	description?: string;
+	products: readonly ListedProduct[];
+	breadcrumbs?: Array<{ name: string; url: string }>;
+	/**
+	 * Page number for paginated listings.
+	 *
+	 * Pages 2+ are `noindex, follow`: the products are what should rank, and a
+	 * thin page-7 of a category competes with them for the same term. Links are
+	 * still followed so every product stays reachable.
+	 */
+	page?: number;
+	/**
+	 * True when the listing is filtered or sorted.
+	 *
+	 * Faceted URLs are the classic crawl trap — colour × size × sort multiplies
+	 * into thousands of near-identical pages that eat crawl budget and split
+	 * ranking. A filtered view should point its canonical at the unfiltered
+	 * category, which is what this does.
+	 */
+	filtered?: boolean;
+	/** Unfiltered category path, used as the canonical when `filtered`. */
+	unfilteredPath?: string;
+};
+
+/** SEO for a storefront category or collection page. */
+export function productListingSeo(input: ProductListingSeoInput): SeoInput {
+	const base = input.siteUrl.replace(/\/+$/, "");
+	const page = input.page ?? 1;
+
+	// A filtered view canonicalises to the category it filters, so the facets
+	// consolidate rather than compete.
+	const canonicalPath =
+		input.filtered && input.unfilteredPath ? input.unfilteredPath : input.path;
+	const canonical = `${base}${canonicalPath}`;
+
+	const absolute = (url: string) =>
+		/^[a-z][a-z0-9+.-]*:|^\/\//i.test(url)
+			? url
+			: `${base}${url.startsWith("/") ? "" : "/"}${url}`;
+
+	const node: JsonLdNode = {
+		"@context": "https://schema.org",
+		"@type": "CollectionPage",
+		url: canonical,
+		...(input.title ? { name: input.title } : {}),
+		...(input.description ? { description: input.description } : {}),
+		mainEntity: {
+			"@type": "ItemList",
+			numberOfItems: input.products.length,
+			itemListElement: input.products.map((product, index) => ({
+				"@type": "ListItem",
+				position: index + 1,
+				item: {
+					"@type": "Product",
+					name: product.name,
+					url: absolute(product.url),
+					...(product.image ? { image: absolute(product.image) } : {}),
+					...(typeof product.priceCents === "number"
+						? {
+								offers: {
+									"@type": "Offer",
+									price: (product.priceCents / 100).toFixed(2),
+									priceCurrency: product.currency ?? "USD",
+									...(product.availability
+										? {
+												availability: `https://schema.org/${product.availability}`,
+											}
+										: {}),
+								},
+							}
+						: {}),
+				},
+			})),
+		},
+	};
+
+	return {
+		...(input.title ? { title: input.title } : {}),
+		...(input.description ? { description: input.description } : {}),
+		canonical,
+		// Either reason is enough on its own to keep the page out of the index.
+		...(page > 1 || input.filtered ? { noIndex: page > 1 } : {}),
+		jsonLd: [
+			node,
+			breadcrumb({
+				siteUrl: input.siteUrl,
+				items: [
+					{ name: "Home", url: input.siteUrl },
+					...(input.breadcrumbs ?? []),
+					...(input.title ? [{ name: input.title, url: canonical }] : []),
+				],
+			}),
+		],
+	};
+}
+
+/**
+ * SEO for cart, checkout, account and order-confirmation pages.
+ *
+ * These must never be indexed. A cart URL in search results is at best useless
+ * and at worst a leak — order confirmations have been indexed with customer
+ * details in the query string more than once, by more than one large retailer.
+ */
+export function transactionalPageSeo(title: string): SeoInput {
+	return { title, noIndex: true, canonical: null };
+}