@businessdash/sdk 0.9.60 → 0.9.80

package/src/seo-core/local.ts

@@ -0,0 +1,333 @@
+/**
+ * Local SEO: the pages that win "plumber in Ashford" and "buy X near me".
+ *
+ * ## What this adds over the builders in `@businessdash/sdk/seo`
+ *
+ * Those are primitives — `service()`, `localBusiness()`, `product()`,
+ * `breadcrumb()` — each producing one JSON-LD node. Correct, and not the thing
+ * a consumer actually needs, because a local landing page is not one node. It
+ * is a `Service` scoped to an area, the `LocalBusiness` that provides it, and
+ * a `BreadcrumbList` placing it in the site, plus the meta tags that carry the
+ * place name into the title and description.
+ *
+ * Assembling that by hand for every service × area combination is where local
+ * SEO dies: someone ships 400 pages that all claim `areaServed: "Nationwide"`,
+ * or 400 identical titles, and the pages compete with each other instead of
+ * ranking.
+ *
+ * So these return a `SeoInput` — meta AND structured data together — that
+ * composes with `resolveSeo()` like any other layer.
+ *
+ * ## The multiplication is the point, and the risk
+ *
+ * `servicesTimesAreas()` exists because service × area is a Cartesian product
+ * and doing it by hand is how mistakes scale. It is also how thin content
+ * scales, so it takes a `describe` callback rather than templating a sentence
+ * for you: pages that differ only by a swapped town name are what "doorway
+ * pages" means, and Google has a specific penalty for them.
+ *
+ * @module
+ */
+
+import {
+	breadcrumb,
+	type JsonLdNode,
+	type LocalBusinessInput,
+	localBusiness,
+	product as productNode,
+	service as serviceNode,
+} from "../seo.js";
+
+import type { SeoInput } from "./index.js";
+
+/** A place the org serves. */
+export type ServiceArea = {
+	/** URL segment, e.g. `ashford`. */
+	slug: string;
+	/** Display name, e.g. `Ashford`. */
+	name: string;
+	/** Optional region for disambiguation — `Kent`, `WA`. */
+	region?: string;
+};
+
+/** One thing the org does. */
+export type ServiceOffering = {
+	slug: string;
+	name: string;
+	description: string;
+};
+
+export type LocalServicePageInput = {
+	/** Absolute site origin, no trailing slash. */
+	siteUrl: string;
+	service: ServiceOffering;
+	area: ServiceArea;
+	/**
+	 * Path of THIS page, e.g. `/services/drain-cleaning/ashford`.
+	 *
+	 * Required, and used as the canonical. A service-area page without its own
+	 * canonical is the single most common way these get deduplicated away by
+	 * search engines — they look near-identical, so one is picked and the rest
+	 * are dropped.
+	 */
+	path: string;
+	/**
+	 * The page's own copy.
+	 *
+	 * A callback rather than a template, deliberately. Generating 400 pages
+	 * whose only difference is the town name produces doorway pages, which are
+	 * penalised rather than ranked. Write something true about serving that
+	 * place, or do not generate the page.
+	 */
+	describe?: (input: { service: ServiceOffering; area: ServiceArea }) => {
+		title?: string;
+		description?: string;
+	};
+	/** The org, for the `LocalBusiness` node the `Service` points at. */
+	business?: LocalBusinessInput;
+	/** Extra crumbs before this page. Home is added automatically. */
+	breadcrumbs?: Array<{ name: string; url: string }>;
+	ogImage?: string;
+	noIndex?: boolean;
+};
+
+function areaLabel(area: ServiceArea): string {
+	return area.region ? `${area.name}, ${area.region}` : area.name;
+}
+
+/**
+ * SEO for one service in one place.
+ *
+ * ```ts
+ * const seo = resolveSeo(
+ *   layoutDefaults,
+ *   localServicePageSeo({ siteUrl, service, area, path }),
+ * )
+ * ```
+ */
+export function localServicePageSeo(input: LocalServicePageInput): SeoInput {
+	const label = areaLabel(input.area);
+	const written = input.describe?.({
+		service: input.service,
+		area: input.area,
+	});
+
+	const title = written?.title ?? `${input.service.name} in ${label}`;
+	const description =
+		written?.description ??
+		`${input.service.description} Serving ${label} and the surrounding area.`;
+
+	const canonical = `${input.siteUrl.replace(/\/+$/, "")}${input.path}`;
+
+	const jsonLd: JsonLdNode[] = [
+		serviceNode({
+			siteUrl: input.siteUrl,
+			slug: input.service.slug,
+			title: input.service.name,
+			description,
+			// The whole point of the page: this service, in THIS place. A node
+			// that omits it is indistinguishable from the generic service page.
+			areaServed: [label],
+		}),
+	];
+
+	if (input.business) jsonLd.push(localBusiness(input.business));
+
+	jsonLd.push(
+		breadcrumb({
+			siteUrl: input.siteUrl,
+			items: [
+				{ name: "Home", url: input.siteUrl },
+				...(input.breadcrumbs ?? []),
+				{ name: `${input.service.name} in ${label}`, url: canonical },
+			],
+		}),
+	);
+
+	return {
+		title,
+		description,
+		canonical,
+		...(input.ogImage ? { ogImage: input.ogImage } : {}),
+		...(input.noIndex === undefined ? {} : { noIndex: input.noIndex }),
+		jsonLd,
+	};
+}
+
+export type LocalProductPageInput = {
+	siteUrl: string;
+	path: string;
+	product: {
+		name: string;
+		description?: string;
+		sku?: string;
+		brand?: string;
+		image?: string | string[];
+		/** Integer cents — the money rule everywhere in this codebase. */
+		priceCents?: number;
+		currency?: string;
+		availability?: "InStock" | "OutOfStock" | "PreOrder";
+		/**
+		 * Average rating and how many reviews it came from.
+		 *
+		 * Both required together, and omitted entirely when `reviewCount` is 0.
+		 * An `AggregateRating` with zero reviews is invalid structured data —
+		 * Google rejects the whole Product node for it, so a product with no
+		 * reviews yet would lose its price and availability too.
+		 */
+		avgRating?: number;
+		reviewCount?: number;
+		/**
+		 * Cheapest and dearest variant, in cents.
+		 *
+		 * When a product has variants at different prices, a single `price` is
+		 * a lie in one direction or the other. `AggregateOffer` states the
+		 * range, which is what shopping surfaces display.
+		 */
+		priceRangeCents?: { low: number; high: number };
+	};
+	breadcrumbs?: Array<{ name: string; url: string }>;
+	noIndex?: boolean;
+};
+
+/**
+ * SEO for a product page.
+ *
+ * Pairs with the AI Distribution product feed: the feed gets the product into
+ * the engines' catalogues, this markup is what their crawlers verify when they
+ * land on the page. One without the other is half the job — a feed entry with
+ * no matching page markup reads as unverified.
+ */
+export function productPageSeo(input: LocalProductPageInput): SeoInput {
+	const canonical = `${input.siteUrl.replace(/\/+$/, "")}${input.path}`;
+	const p = input.product;
+
+	const jsonLd: JsonLdNode[] = [
+		productNode({
+			url: canonical,
+			name: p.name,
+			...(p.description ? { description: p.description } : {}),
+			...(p.image ? { image: p.image } : {}),
+			...(p.brand ? { brand: p.brand } : {}),
+			...(p.sku ? { sku: p.sku } : {}),
+			...(p.priceCents === undefined
+				? {}
+				: {
+						offer: {
+							priceCents: p.priceCents,
+							...(p.currency ? { currency: p.currency } : {}),
+							...(p.availability ? { availability: p.availability } : {}),
+						},
+					}),
+		}),
+		breadcrumb({
+			siteUrl: input.siteUrl,
+			items: [
+				{ name: "Home", url: input.siteUrl },
+				...(input.breadcrumbs ?? []),
+				{ name: p.name, url: canonical },
+			],
+		}),
+	];
+
+	// Ratings and price ranges are patched onto the Product node rather than
+	// passed to `product()`, whose input covers a single offer. Both are what
+	// turn a plain result into a rich one — stars and a price range are the
+	// whole visual difference in a shopping surface.
+	const productJson = jsonLd[0] as JsonLdNode;
+	if (
+		typeof p.avgRating === "number" &&
+		typeof p.reviewCount === "number" &&
+		p.reviewCount > 0
+	) {
+		productJson["aggregateRating"] = {
+			"@type": "AggregateRating",
+			ratingValue: p.avgRating,
+			reviewCount: p.reviewCount,
+		};
+	}
+	if (p.priceRangeCents && p.priceRangeCents.high > p.priceRangeCents.low) {
+		productJson["offers"] = {
+			"@type": "AggregateOffer",
+			priceCurrency: p.currency ?? "USD",
+			lowPrice: (p.priceRangeCents.low / 100).toFixed(2),
+			highPrice: (p.priceRangeCents.high / 100).toFixed(2),
+			...(p.availability
+				? { availability: `https://schema.org/${p.availability}` }
+				: {}),
+		};
+	}
+
+	return {
+		title: p.name,
+		...(p.description ? { description: p.description } : {}),
+		canonical,
+		...(p.image
+			? { ogImage: Array.isArray(p.image) ? p.image[0] : p.image }
+			: {}),
+		// Products are things people buy, so the card should show the thing.
+		ogType: "product",
+		...(input.noIndex === undefined ? {} : { noIndex: input.noIndex }),
+		jsonLd,
+	};
+}
+
+export type ServicesTimesAreasInput = {
+	siteUrl: string;
+	services: readonly ServiceOffering[];
+	areas: readonly ServiceArea[];
+	/** Build the path for one combination. */
+	path: (service: ServiceOffering, area: ServiceArea) => string;
+	describe?: LocalServicePageInput["describe"];
+	business?: LocalBusinessInput;
+	/**
+	 * Skip combinations the org does not actually serve.
+	 *
+	 * Worth using. A page for a service you do not offer in a place you do not
+	 * cover is a page that ranks, gets clicked, and produces a call you have to
+	 * turn down — which costs more than the traffic was worth.
+	 */
+	include?: (service: ServiceOffering, area: ServiceArea) => boolean;
+};
+
+/** One generated combination: where it lives, and its SEO. */
+export type LocalPagePlan = {
+	path: string;
+	service: ServiceOffering;
+	area: ServiceArea;
+	seo: SeoInput;
+};
+
+/**
+ * Every service × area combination, as a list of pages to generate.
+ *
+ * Returns plans rather than rendering anything: which router builds them, and
+ * how, is the framework's business. Feed the result to Next's
+ * `generateStaticParams`, Astro's `getStaticPaths`, a SvelteKit `entries`
+ * export, or a loop in a build script.
+ */
+export function servicesTimesAreas(
+	input: ServicesTimesAreasInput,
+): LocalPagePlan[] {
+	const plans: LocalPagePlan[] = [];
+	for (const service of input.services) {
+		for (const area of input.areas) {
+			if (input.include && !input.include(service, area)) continue;
+			const path = input.path(service, area);
+			plans.push({
+				path,
+				service,
+				area,
+				seo: localServicePageSeo({
+					siteUrl: input.siteUrl,
+					service,
+					area,
+					path,
+					...(input.describe ? { describe: input.describe } : {}),
+					...(input.business ? { business: input.business } : {}),
+				}),
+			});
+		}
+	}
+	return plans;
+}

package/src/sitemap-core/index.ts

@@ -0,0 +1,296 @@
+/**
+ * `@businessdash/sdk/sitemap` — build a sitemap that matches YOUR site.
+ *
+ * ## Why the platform cannot do this alone
+ *
+ * BusinessDash knows an org has 40 blog posts. It does not know whether their
+ * site renders them at `/blog/[slug]`, `/updates/[slug]`, `/news/[slug]`, or
+ * not at all. Guessing produces a sitemap full of URLs that 404 — which is
+ * meaningfully worse than a smaller sitemap, because a crawler that finds
+ * broken URLs in your sitemap discounts the whole file.
+ *
+ * So the split is: the platform emits the URLs whose shape it owns (site-builder
+ * pages, legal documents, programmatic pages — it defines those route
+ * patterns), and this merges in the rest using paths YOU declare.
+ *
+ * ## Everything is opt-in, and the default is omission
+ *
+ * A mobile mechanic has no store. If you do not declare `routes.product`, no
+ * product URLs are emitted — and even if you did, the platform would refuse the
+ * data because the org has no `ecommerce.storefront` entitlement. Two
+ * independent gates, both defaulting to "no".
+ *
+ * That asymmetry is deliberate. A missing URL costs you the indexing of one
+ * page, which Google will usually find by crawling anyway. A sitemap full of
+ * 404s costs you trust in every URL in the file. When unsure, this omits.
+ *
+ * ```ts
+ * const xml = await buildSitemap({
+ *   client,
+ *   siteId: SITE_ID,
+ *   baseUrl: 'https://acme.com',
+ *   staticPaths: ['/', '/about', '/contact'],
+ *   routes: {
+ *     blog: '/blog',     // → /blog/{slug}
+ *     product: '/store', // → /store/{id}
+ *     // no `legal` key → the platform already emits those at their own slugs
+ *   },
+ * })
+ * ```
+ *
+ * @module
+ */
+
+import { BiabAccessRejectedError } from "../errors.js";
+import { isReservedPagePath } from "../reserved-paths.js";
+
+/** Where a kind of platform content lives on YOUR site. */
+export type SitemapRoutes = {
+	/**
+	 * Path prefix for blog posts — `/blog` yields `/blog/{slug}`.
+	 *
+	 * Omit if you do not render a blog. Requires the `blog.public`
+	 * entitlement; without it the platform returns nothing and this skips the
+	 * section rather than failing.
+	 */
+	blog?: string;
+	/**
+	 * Path prefix for products — `/store` yields `/store/{id}`.
+	 *
+	 * Omit if you do not sell anything. Requires `ecommerce.storefront`.
+	 */
+	product?: string;
+	/**
+	 * Prefix for the org's legal pages, if you mounted them somewhere other
+	 * than the site root.
+	 *
+	 * Usually omitted: the platform already emits legal URLs at their own
+	 * slugs (`/privacy`), which is where the SDK's catch-all serves them.
+	 * Set it only if your catch-all lives under a prefix.
+	 */
+	legal?: string;
+};
+
+export type SitemapEntry = {
+	/** Absolute URL. */
+	loc: string;
+	/** ISO 8601. Omitted when nothing meaningful is known. */
+	lastmod?: string;
+};
+
+export type BuildSitemapOptions = {
+	client: SitemapClientLike;
+	siteId: string;
+	/** Your canonical origin, e.g. `https://acme.com`. No trailing slash needed. */
+	baseUrl: string;
+	/**
+	 * Paths you hand-wrote in your own repo — the homepage, an about page, a
+	 * landing page. The platform cannot know these exist.
+	 *
+	 * Always include `/`. A sitemap without the homepage is a common and
+	 * entirely self-inflicted omission.
+	 */
+	staticPaths?: string[];
+	routes?: SitemapRoutes;
+	/** How many blog posts to enumerate. Default 1000. */
+	blogLimit?: number;
+	/** How many products to enumerate. Default 1000. */
+	productLimit?: number;
+	/**
+	 * Called when a section is skipped, with the reason.
+	 *
+	 * Worth logging during setup: "skipped products — org has no
+	 * ecommerce.storefront entitlement" is the difference between a deliberate
+	 * omission and a silent one you discover months later in Search Console.
+	 */
+	onSkip?: (section: string, reason: string) => void;
+};
+
+/** The subset of the SDK client this needs. */
+export type SitemapClientLike = {
+	blog: {
+		listPosts(input?: { limit?: number }): Promise<{
+			posts: Array<{ slug: string; updatedAt?: string | null }>;
+		}>;
+	};
+	storefront: {
+		listProducts(input?: { limit?: number }): Promise<{
+			products: Array<{ id: string; updatedAt?: string | null }>;
+		}>;
+	};
+	site(siteId: string): {
+		sitemapEntries(): Promise<{ entries: SitemapEntry[] }>;
+	};
+};
+
+function joinUrl(baseUrl: string, path: string): string {
+	const base = baseUrl.replace(/\/+$/, "");
+	const suffix = path.startsWith("/") ? path : `/${path}`;
+	return `${base}${suffix === "/" ? "/" : suffix.replace(/\/+$/, "")}`;
+}
+
+function escapeXml(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/**
+ * True when a failure means "this org does not have that surface".
+ *
+ * A missing entitlement is a normal answer for most orgs, not an error — a
+ * plumber has no storefront. Anything else (a network fault, a bad key) is also
+ * swallowed per-section, because a sitemap that renders four of five sections
+ * is far better than one that 500s: a crawler retries a partial sitemap and
+ * gives up on an error page.
+ */
+function isExpectedAbsence(cause: unknown): boolean {
+	return cause instanceof BiabAccessRejectedError;
+}
+
+/**
+ * Collect every URL for the site, deduplicated and ordered.
+ *
+ * Sections fail independently — one unreachable surface never takes the
+ * sitemap down with it.
+ */
+export async function collectSitemapEntries(
+	options: BuildSitemapOptions,
+): Promise<SitemapEntry[]> {
+	const { client, baseUrl, routes = {} } = options;
+	const seen = new Map<string, SitemapEntry>();
+
+	function add(path: string, lastmod?: string | null): void {
+		// The customer dashboard and the other token-gated surfaces never enter
+		// a sitemap — `/portal`, `/quotes/accept`, `/contracts/sign`,
+		// `/invoices/pay`. Each is per-customer and behind a token, so a crawler
+		// following one lands on a login redirect. That reads as a soft 404 and
+		// drags on the trust of every other URL in the file, quite apart from
+		// publishing the shape of a private area.
+		//
+		// Filtered here rather than only on the platform side because a
+		// consumer can pass `staticPaths: ['/portal']` by hand, and this is the
+		// last place to catch it.
+		if (isReservedPagePath(path)) return;
+
+		const loc = joinUrl(baseUrl, path);
+		// First writer wins: a hand-declared static path outranks the same URL
+		// discovered from content, because the consumer said it explicitly.
+		if (seen.has(loc)) return;
+		seen.set(loc, lastmod ? { loc, lastmod } : { loc });
+	}
+
+	// 1. Your own routes, first, so they take precedence on collision.
+	for (const path of options.staticPaths ?? []) add(path);
+
+	// 2. What the platform owns the shape of: site-builder pages, legal
+	//    documents, programmatic pages. These arrive as full paths.
+	try {
+		const { entries } = await client.site(options.siteId).sitemapEntries();
+		for (const entry of entries) {
+			// Already absolute from the platform — re-join so a consumer serving
+			// under a different origin than the org's primary domain still gets
+			// their own host rather than the platform's idea of it.
+			const path = entry.loc.replace(/^https?:\/\/[^/]+/, "");
+			add(path || "/", entry.lastmod);
+		}
+	} catch (cause) {
+		options.onSkip?.(
+			"platform",
+			isExpectedAbsence(cause)
+				? "org is not entitled to programmatic pages"
+				: "platform sitemap was unreachable",
+		);
+	}
+
+	// 3. Blog — only when you told us where it lives.
+	if (routes.blog) {
+		try {
+			const { posts } = await client.blog.listPosts({
+				limit: options.blogLimit ?? 1000,
+			});
+			for (const post of posts) {
+				add(`${routes.blog}/${post.slug}`, post.updatedAt ?? null);
+			}
+		} catch (cause) {
+			options.onSkip?.(
+				"blog",
+				isExpectedAbsence(cause)
+					? "org has no blog.public entitlement"
+					: "blog posts were unreachable",
+			);
+		}
+	} else {
+		options.onSkip?.("blog", "no routes.blog declared");
+	}
+
+	// 4. Products — same rule.
+	if (routes.product) {
+		try {
+			const { products } = await client.storefront.listProducts({
+				limit: options.productLimit ?? 1000,
+			});
+			for (const product of products) {
+				add(`${routes.product}/${product.id}`, product.updatedAt ?? null);
+			}
+		} catch (cause) {
+			options.onSkip?.(
+				"products",
+				isExpectedAbsence(cause)
+					? "org has no ecommerce.storefront entitlement"
+					: "products were unreachable",
+			);
+		}
+	} else {
+		options.onSkip?.("products", "no routes.product declared");
+	}
+
+	return [...seen.values()];
+}
+
+/** Serialise entries as a sitemap document. */
+export function renderSitemapXml(entries: SitemapEntry[]): string {
+	const body = entries
+		.map((entry) => {
+			const lastmod = entry.lastmod
+				? `\n    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`
+				: "";
+			return `  <url>\n    <loc>${escapeXml(entry.loc)}</loc>${lastmod}\n  </url>`;
+		})
+		.join("\n");
+
+	return (
+		'<?xml version="1.0" encoding="UTF-8"?>\n' +
+		'<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n' +
+		(body ? `${body}\n` : "") +
+		"</urlset>\n"
+	);
+}
+
+/**
+ * The whole thing: collect, then serialise.
+ *
+ * Never throws. A sitemap route that 500s is worse than one that returns fewer
+ * URLs — crawlers retry a thin sitemap and back off from an error page.
+ */
+export async function buildSitemap(
+	options: BuildSitemapOptions,
+): Promise<string> {
+	const entries = await collectSitemapEntries(options);
+	return renderSitemapXml(entries);
+}
+
+/**
+ * A sitemap with only the homepage in it.
+ *
+ * The fallback when BusinessDash is unconfigured or unreachable. Deliberately
+ * NOT an empty `<urlset>`: an empty sitemap affirmatively tells a crawler the
+ * site has no pages, which is a worse claim than saying nothing. One honest URL
+ * is the smallest truthful document.
+ */
+export function minimalSitemapXml(baseUrl: string): string {
+	return renderSitemapXml([{ loc: joinUrl(baseUrl, "/") }]);
+}