@haruhimemoe/next-kit 0.2.1 → 0.4.0

package/dist/seo/site.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @file src/seo/site.ts
+ * @desc The site description every seo helper reads (`Site`), the haruhime.moe organization the
+ *       four sites share, the "Primary keyword · host" title rule, and the small URL, date and
+ *       @id helpers the metadata, sitemap and JSON-LD builders share.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** One Open Graph image. A relative `url` resolves against the site's origin. */
+export type OgImage = {
+    url: string;
+    width?: number;
+    height?: number;
+    alt?: string;
+    type?: string;
+};
+/** The organization behind a site: schema.org Organization, and every page's publisher. */
+export type Organization = {
+    name: string;
+    /** Its home page, like https://www.haruhime.moe. Its @id is `${url}/#organization`. */
+    url: string;
+    logo?: string;
+    email?: string;
+    /** Profiles that are the same entity: GitHub org, Discord invite, npm org. */
+    sameAs?: readonly string[];
+};
+/** One site: what siteMetadata, pageMetadata, robots, sitemapEntries and the ld builders read. */
+export type Site = {
+    /** The product name, like "pools". og:site_name, applicationName, the WebSite name. */
+    name: string;
+    /** The canonical origin, like https://pools.haruhime.moe (www for haruhime.moe). */
+    url: string;
+    /** The home page's primary keyword, like "osu! tournament mappool builder". */
+    title: string;
+    /** What follows " · " in every title. Defaults to the host, like pools.haruhime.moe. */
+    titleSuffix?: string;
+    /** A shorter suffix, like "pools", for titles that would pass TITLE_MAX with the full one. */
+    shortTitleSuffix?: string;
+    /** The default description, 140 to 160 characters. */
+    description: string;
+    /** Open Graph locale. Defaults to en_US. */
+    locale?: string;
+    /** Twitter handles, with the @. */
+    twitter?: {
+        site?: string;
+        creator?: string;
+    };
+    /** The default preview image(s). Every page keeps them unless it passes its own. */
+    ogImages: readonly OgImage[];
+    organization: Organization;
+    /** The parent site of a tool (www.haruhime.moe): the WebSite's isPartOf. */
+    parent?: {
+        name: string;
+        url: string;
+    };
+};
+/** The haruhime.moe organization the four sites share (A6: one entity, one @id). */
+export declare const HARUHIME_ORG: Organization;
+/** The separator between a page's keyword and the site in every title. */
+export declare const TITLE_SEPARATOR = " \u00B7 ";
+/**
+ * @function origin
+ * @param url {string} a site or organization URL
+ * @returns {string} its origin, no trailing slash
+ * @throws {TypeError} when url isn't an absolute URL
+ */
+export declare const origin: (url: string) => string;
+/**
+ * @function absoluteUrl
+ * @param site {Pick<Site, "url">} the site
+ * @param path {string} a path starting with "/", or an absolute URL on the site's origin
+ * @returns {string} the absolute URL on the site's canonical origin
+ * @throws {Error} when path is relative or on another origin
+ */
+export declare const absoluteUrl: (site: Pick<Site, "url">, path: string) => string;
+/**
+ * @function nodeId
+ * @param url {string} a site or organization URL
+ * @param name {string} the fragment, like "organization", "website" or "app"
+ * @returns {string} a stable JSON-LD @id, like https://www.haruhime.moe/#organization
+ */
+export declare const nodeId: (url: string, name: string) => string;
+/** The longest title search results show in full; "auto" switches to the short suffix past it. */
+export declare const TITLE_MAX = 60;
+/**
+ * Which suffix a title gets: "full" (titleSuffix or the host), "short" (shortTitleSuffix, else
+ * full), "none" (the keyword alone), or "auto" (full, unless that passes TITLE_MAX and the site
+ * has a shortTitleSuffix).
+ */
+export type TitleSuffixMode = "auto" | "full" | "short" | "none";
+/**
+ * @function titleSuffix
+ * @param site {Site} the site
+ * @returns {string} what follows " · " in its titles: titleSuffix, or the host
+ */
+export declare const titleSuffix: (site: Site) => string;
+/**
+ * @function pageTitle
+ * @param site {Site} the site
+ * @param title {string} the page's primary keyword, like "Search osu! tournament mappools"
+ * @param mode {TitleSuffixMode} which suffix to add (default "full")
+ * @returns {string} "Primary keyword · host" (a suffix already there is never added twice)
+ * @throws {Error} when title is blank
+ */
+export declare const pageTitle: (site: Site, title: string, mode?: TitleSuffixMode) => string;
+/**
+ * @function isoDate
+ * @param value {string | Date | null | undefined} a date, maybe unknown
+ * @returns {string | undefined} ISO 8601, or undefined when missing or not a real date (never
+ *          a made-up one)
+ */
+export declare const isoDate: (value: string | Date | null | undefined) => string | undefined;
+/**
+ * @function compact
+ * @param object {T} an object that may hold undefined values
+ * @returns {T} the same keys minus the undefined ones (so exactOptionalPropertyTypes holds)
+ */
+export declare const compact: <T extends Record<string, unknown>>(object: T) => T;

package/dist/seo/site.js

@@ -0,0 +1,111 @@
+/**
+ * @file src/seo/site.ts
+ * @desc The site description every seo helper reads (`Site`), the haruhime.moe organization the
+ *       four sites share, the "Primary keyword · host" title rule, and the small URL, date and
+ *       @id helpers the metadata, sitemap and JSON-LD builders share.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+/** The haruhime.moe organization the four sites share (A6: one entity, one @id). */
+export const HARUHIME_ORG = {
+    name: "haruhime.moe",
+    url: "https://www.haruhime.moe",
+    logo: "https://www.haruhime.moe/apple-icon.png",
+    email: "contact@haruhime.moe",
+    sameAs: [
+        "https://github.com/haruhimemoe",
+        "https://discord.gg/bKy9kjMV4y",
+        "https://www.npmjs.com/org/haruhimemoe",
+    ],
+};
+/** The separator between a page's keyword and the site in every title. */
+export const TITLE_SEPARATOR = " · ";
+/**
+ * @function origin
+ * @param url {string} a site or organization URL
+ * @returns {string} its origin, no trailing slash
+ * @throws {TypeError} when url isn't an absolute URL
+ */
+export const origin = (url) => new URL(url).origin;
+/**
+ * @function absoluteUrl
+ * @param site {Pick<Site, "url">} the site
+ * @param path {string} a path starting with "/", or an absolute URL on the site's origin
+ * @returns {string} the absolute URL on the site's canonical origin
+ * @throws {Error} when path is relative or on another origin
+ */
+export const absoluteUrl = (site, path) => {
+    const base = origin(site.url);
+    if (/^[a-z][a-z\d+.-]*:/i.test(path)) {
+        const url = new URL(path);
+        if (url.origin !== base)
+            throw new Error(`seo: ${path} is not on ${base}`);
+        return url.href;
+    }
+    if (!path.startsWith("/") || path.startsWith("//")) {
+        throw new Error(`seo: path "${path}" must start with one "/"`);
+    }
+    return `${base}${path}`;
+};
+/**
+ * @function nodeId
+ * @param url {string} a site or organization URL
+ * @param name {string} the fragment, like "organization", "website" or "app"
+ * @returns {string} a stable JSON-LD @id, like https://www.haruhime.moe/#organization
+ */
+export const nodeId = (url, name) => `${origin(url)}/#${name}`;
+/** The longest title search results show in full; "auto" switches to the short suffix past it. */
+export const TITLE_MAX = 60;
+/**
+ * @function titleSuffix
+ * @param site {Site} the site
+ * @returns {string} what follows " · " in its titles: titleSuffix, or the host
+ */
+export const titleSuffix = (site) => site.titleSuffix ?? new URL(site.url).host;
+/**
+ * @function pageTitle
+ * @param site {Site} the site
+ * @param title {string} the page's primary keyword, like "Search osu! tournament mappools"
+ * @param mode {TitleSuffixMode} which suffix to add (default "full")
+ * @returns {string} "Primary keyword · host" (a suffix already there is never added twice)
+ * @throws {Error} when title is blank
+ */
+export const pageTitle = (site, title, mode = "full") => {
+    const keyword = title.replace(/\s+/g, " ").trim();
+    if (!keyword)
+        throw new Error("seo: a page title can't be blank");
+    const full = titleSuffix(site);
+    const suffixes = [full, site.shortTitleSuffix]
+        .filter(Boolean)
+        .map((s) => `${TITLE_SEPARATOR}${s}`);
+    if (mode === "none" || suffixes.some((suffix) => keyword.endsWith(suffix)))
+        return keyword;
+    const long = `${keyword}${TITLE_SEPARATOR}${full}`;
+    const short = site.shortTitleSuffix
+        ? `${keyword}${TITLE_SEPARATOR}${site.shortTitleSuffix}`
+        : long;
+    if (mode === "short")
+        return short;
+    if (mode === "auto" && long.length > TITLE_MAX)
+        return short;
+    return long;
+};
+/**
+ * @function isoDate
+ * @param value {string | Date | null | undefined} a date, maybe unknown
+ * @returns {string | undefined} ISO 8601, or undefined when missing or not a real date (never
+ *          a made-up one)
+ */
+export const isoDate = (value) => {
+    if (value === null || value === undefined || value === "")
+        return undefined;
+    const time = value instanceof Date ? value.getTime() : Date.parse(value);
+    return Number.isNaN(time) ? undefined : new Date(time).toISOString();
+};
+/**
+ * @function compact
+ * @param object {T} an object that may hold undefined values
+ * @returns {T} the same keys minus the undefined ones (so exactOptionalPropertyTypes holds)
+ */
+export const compact = (object) => Object.fromEntries(Object.entries(object).filter(([, value]) => value !== undefined));

package/dist/seo/sitemap.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file src/seo/sitemap.ts
+ * @desc sitemap.xml entries from static paths and records: absolute URLs on the canonical origin,
+ *       one entry per URL, and lastModified only when it's known and real (audit T4: an import
+ *       time or a made-up date teaches crawlers to ignore lastmod). Throws past 50,000 URLs, the
+ *       sitemaps.org cap for one file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import type { MetadataRoute } from "next";
+import { type Site } from "./site.js";
+/** The most URLs one sitemap file may list (sitemaps.org). */
+export declare const SITEMAP_MAX_URLS = 50000;
+/** How often a page changes, as sitemaps.org spells it. */
+export type ChangeFrequency = NonNullable<MetadataRoute.Sitemap[number]["changeFrequency"]>;
+/** One page: its path and what's known about it. */
+export type SitemapRecord = {
+    /** A path like "/pools/otdb-98", or an absolute URL on the site's origin. */
+    path: string;
+    /** When its content last changed. Missing or invalid: no lastmod (never a guess). */
+    lastModified?: string | Date | null;
+    changeFrequency?: ChangeFrequency;
+    /** 0 to 1. */
+    priority?: number;
+};
+/** One group: plain paths, records, or both. */
+export type SitemapGroup = readonly (string | SitemapRecord)[];
+/**
+ * @function sitemapEntries
+ * @param site {Site} the site
+ * @param groups {readonly SitemapGroup[]} static paths and dynamic records, in the order they
+ *        should appear
+ * @returns {MetadataRoute.Sitemap} one entry per URL (the first one wins), absolute URLs, and no
+ *          lastModified where it's unknown
+ * @throws {Error} when a path isn't on the site, a priority is outside 0 to 1, or there are
+ *         more than 50,000 URLs (split into sitemap files with generateSitemaps)
+ */
+export declare const sitemapEntries: (site: Site, groups: readonly SitemapGroup[]) => MetadataRoute.Sitemap;

package/dist/seo/sitemap.js

@@ -0,0 +1,50 @@
+/**
+ * @file src/seo/sitemap.ts
+ * @desc sitemap.xml entries from static paths and records: absolute URLs on the canonical origin,
+ *       one entry per URL, and lastModified only when it's known and real (audit T4: an import
+ *       time or a made-up date teaches crawlers to ignore lastmod). Throws past 50,000 URLs, the
+ *       sitemaps.org cap for one file.
+ * @author David @dvhsh (https://dvh.sh)
+ * @created Mon Sep 28, 2026
+ * @modified Mon Sep 28, 2026
+ */
+import { absoluteUrl, compact, isoDate } from "./site.js";
+/** The most URLs one sitemap file may list (sitemaps.org). */
+export const SITEMAP_MAX_URLS = 50_000;
+const toEntry = (site, item) => {
+    const record = typeof item === "string" ? { path: item } : item;
+    const { priority } = record;
+    if (priority !== undefined && !(priority >= 0 && priority <= 1)) {
+        throw new RangeError(`seo: sitemap priority for ${record.path} must be 0 to 1`);
+    }
+    return compact({
+        url: absoluteUrl(site, record.path),
+        lastModified: isoDate(record.lastModified),
+        changeFrequency: record.changeFrequency,
+        priority,
+    });
+};
+/**
+ * @function sitemapEntries
+ * @param site {Site} the site
+ * @param groups {readonly SitemapGroup[]} static paths and dynamic records, in the order they
+ *        should appear
+ * @returns {MetadataRoute.Sitemap} one entry per URL (the first one wins), absolute URLs, and no
+ *          lastModified where it's unknown
+ * @throws {Error} when a path isn't on the site, a priority is outside 0 to 1, or there are
+ *         more than 50,000 URLs (split into sitemap files with generateSitemaps)
+ */
+export const sitemapEntries = (site, groups) => {
+    const byUrl = new Map();
+    for (const group of groups) {
+        for (const item of group) {
+            const entry = toEntry(site, item);
+            if (!byUrl.has(entry.url))
+                byUrl.set(entry.url, entry);
+        }
+    }
+    if (byUrl.size > SITEMAP_MAX_URLS) {
+        throw new Error(`seo: ${byUrl.size} sitemap URLs, over the ${SITEMAP_MAX_URLS} a sitemap file may list. Split it with generateSitemaps.`);
+    }
+    return [...byUrl.values()];
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haruhimemoe/next-kit",
-  "version": "0.2.1",
-  "description": "The Next.js server plumbing packs.haruhime.moe and pools.haruhime.moe share: JSON route helpers, rate limits and budgets in MongoDB, bearer machine auth, zod env parsing, a connect-once MongoDB client with safe index builds, better-auth with osu! sign-in, and the signed-in marker and account store for the browser.",
+  "version": "0.4.0",
+  "description": "The Next.js plumbing the haruhime.moe tools share: JSON route helpers, rate limits and budgets in MongoDB, bearer machine auth, zod env parsing, a connect-once MongoDB client with safe index builds, better-auth with osu! sign-in, the signed-in marker and account store for the browser, and SEO: metadata, robots.txt, sitemaps, JSON-LD and llms.txt.",
   "keywords": [
     "nextjs",
     "next.js",
@@ -10,7 +10,11 @@
     "osu!",
     "mongodb",
     "rate limit",
-    "zod"
+    "zod",
+    "seo",
+    "json-ld",
+    "sitemap",
+    "llms.txt"
   ],
   "homepage": "https://github.com/haruhimemoe/next-kit#readme",
   "bugs": "https://github.com/haruhimemoe/next-kit/issues",
@@ -46,6 +50,10 @@
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
     },
+    "./seo": {
+      "types": "./dist/seo/index.d.ts",
+      "default": "./dist/seo/index.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [