@nexpress/core 0.1.0

package/dist/seo.d.ts

@@ -0,0 +1,410 @@
+/**
+ * Phase 10.1 — sitemap entry shape. Mirrors the sitemap.org spec
+ * fields the framework cares about. Apps format these into XML
+ * (the reference app does that in `apps/web/src/app/sitemap.xml/
+ * route.ts`); the core helper stays format-agnostic so a future
+ * news-sitemap or video-sitemap variant can reuse the same
+ * collection walk.
+ */
+interface NpSitemapEntry {
+    /** Path-only — host is prepended by the consumer. Always starts with `/`. */
+    loc: string;
+    /** ISO timestamp for `<lastmod>`. Falls back to `updatedAt` then `createdAt`. */
+    lastmod?: string;
+    changefreq?: "always" | "hourly" | "daily" | "weekly" | "monthly" | "yearly" | "never";
+    priority?: number;
+    /**
+     * Phase 12.2 — hreflang alternates for translated content.
+     * The renderer emits an `<xhtml:link rel="alternate" hreflang="..." href="..."/>`
+     * entry per alternate, and the urlset gets the xhtml namespace
+     * declaration when any entry uses alternates.
+     */
+    alternates?: Array<{
+        hreflang: string;
+        href: string;
+    }>;
+}
+interface BuildSitemapOptions {
+    /**
+     * Cap per-collection at this many rows so a 100K-document blog
+     * doesn't bring the sitemap.xml endpoint to its knees. Default
+     * 5000 is the sitemaps.org recommended max per file. Sites with
+     * more rows than that per locale should pair this with the
+     * sitemap-index split (see `locale` below) so each child file
+     * stays under the cap.
+     */
+    perCollectionLimit?: number;
+    /** Restrict to specific collection slugs (default: all). */
+    collections?: string[];
+    /**
+     * Restrict to a single locale. When set:
+     *   - i18n collections filter rows to `locale = $locale` (so
+     *     each per-locale sitemap only enumerates its own URLs).
+     *   - non-i18n collections are emitted only for the configured
+     *     `defaultLocale`; other locales' sitemaps skip them so
+     *     a row never appears in two sibling sitemaps.
+     * Leaving this `undefined` keeps the unfiltered single-file
+     * behavior used when i18n is not configured.
+     */
+    locale?: string;
+}
+/**
+ * Sitemap-index entry — a pointer to a child `<urlset>` document
+ * (typically a per-locale sitemap). The `loc` is path-only; the
+ * renderer prepends the absolute origin.
+ */
+interface NpSitemapIndexEntry {
+    loc: string;
+    /** Optional ISO timestamp for `<lastmod>` on the child sitemap. */
+    lastmod?: string;
+}
+/**
+ * Walks every registered collection that opts into the sitemap
+ * via `seo.urlPath`, queries published documents, and emits a
+ * flat list of `NpSitemapEntry` rows. Anonymous read access is
+ * required — `findDocuments(slug, opts, undefined)` runs the
+ * collection's `access.read` callback with no user. Collections
+ * that gate reads (admin-only, member-only) won't surface in the
+ * sitemap, which is the right default.
+ *
+ * The function intentionally doesn't include the site root `/`
+ * by itself — sites add a fixed entry for the home page (and any
+ * other static routes like /search, /discussions) on top of the
+ * collection walk.
+ */
+declare function buildSitemap(options?: BuildSitemapOptions): Promise<NpSitemapEntry[]>;
+/**
+ * Renders an `NpSitemapEntry[]` plus the absolute host into an
+ * XML body suitable for `Content-Type: application/xml`. The
+ * loc path is URL-joined with the host without double-slashes;
+ * the host should NOT have a trailing slash. The output is
+ * sitemap.org 0.9 compliant.
+ */
+declare function renderSitemapXml(origin: string, entries: NpSitemapEntry[]): string;
+/**
+ * Phase 12.9 — render a sitemap-index document. Sites with i18n
+ * configured emit one of these at `/sitemap.xml` instead of a
+ * single `<urlset>`; each child sitemap holds the URLs for one
+ * locale so the per-file 50K-entry sitemaps.org cap is per-locale
+ * rather than shared across the whole site.
+ *
+ * The index itself is small (one `<sitemap>` per locale) so it
+ * doesn't need the `xhtml` namespace or alternates — those live
+ * inside the child `<urlset>` documents.
+ */
+declare function renderSitemapIndexXml(origin: string, entries: NpSitemapIndexEntry[]): string;
+
+/**
+ * Phase 10.3 — site-wide SEO defaults read from `np_settings`.
+ * Reads three existing keys + a new `seo` key:
+ *
+ *   - `site`        → { name, url }   (existing General settings)
+ *   - `description` → string           (existing General settings)
+ *   - `seo`         → { defaultOgImage, twitterHandle, defaultLocale }
+ *
+ * The shape is a flat merge so callers don't have to hop across
+ * keys to pre-fill metadata.
+ */
+interface NpSiteSeoSettings {
+    /** Site name shown in the title bar suffix and `og:site_name`. */
+    siteName: string;
+    /** Absolute origin used as the base for canonical URLs. */
+    siteUrl: string;
+    /** Default `<meta name="description">` when a page doesn't set its own. */
+    defaultDescription: string;
+    /**
+     * Default Open Graph image. Either an absolute URL or a path
+     * starting with `/` (which gets joined to `siteUrl`). `null` =
+     * no default; pages that don't set an image won't render an
+     * `og:image` tag.
+     */
+    defaultOgImage: string | null;
+    /** Twitter `@handle` (no leading `@`) for `twitter:site`. `null` = omit. */
+    twitterHandle: string | null;
+    /** BCP 47 locale tag for `og:locale`. Default `"en_US"`. */
+    defaultLocale: string;
+}
+declare const DEFAULT_SITE_SEO_SETTINGS: NpSiteSeoSettings;
+/**
+ * Reads the three settings keys that contribute to site-wide
+ * SEO and merges into a single flat object. Missing fields fall
+ * back to `DEFAULT_SITE_SEO_SETTINGS`. Read-only access — no
+ * permission gate; the values are surfaced in public HTML
+ * `<head>` tags.
+ */
+declare function getSiteSeoSettings(): Promise<NpSiteSeoSettings>;
+/**
+ * Caller-provided metadata for a single page. All fields are
+ * optional — anything missing falls back to the site-wide
+ * defaults from `getSiteSeoSettings()`.
+ */
+interface NpPageMetadataInput {
+    /** Page title (without site-name suffix; that's appended below). */
+    title?: string | null;
+    /** Page-specific description. Falls back to site default. */
+    description?: string | null;
+    /**
+     * Image URL for og:image / twitter:image. Either absolute or
+     * a path starting with `/` (joined to siteUrl). Falls back to
+     * `defaultOgImage`.
+     */
+    ogImage?: string | null;
+    /**
+     * Path of the current page (no origin). Used to build the
+     * canonical URL. Pass without query / hash; trailing `/` is
+     * normalized off.
+     */
+    path?: string;
+    /** OpenGraph type. Default `"website"`; posts use `"article"`. */
+    ogType?: "website" | "article" | "profile";
+    /**
+     * Article-specific dates (only honored when `ogType === "article"`).
+     * Pass `Date` instances — the helper formats to ISO 8601.
+     */
+    publishedTime?: Date | null;
+    modifiedTime?: Date | null;
+    /**
+     * Phase 12.2 — locale for the rendered page. Surfaces into
+     * `og:locale` so social cards label the language correctly.
+     * Optional; sites without i18n leave it unset and the helper
+     * omits `og:locale` from the output.
+     */
+    locale?: string;
+}
+/**
+ * Next.js Metadata shape — kept structurally typed here to avoid
+ * a hard dependency on the framework from core. The reference app
+ * casts the return to Next's `Metadata` (the field names match).
+ */
+interface NpPageMetadata {
+    title: string;
+    description: string;
+    alternates?: {
+        canonical: string;
+    };
+    openGraph?: {
+        title: string;
+        description: string;
+        siteName: string;
+        url: string;
+        type: "website" | "article" | "profile";
+        images?: Array<{
+            url: string;
+        }>;
+        locale?: string;
+        publishedTime?: string;
+        modifiedTime?: string;
+    };
+    twitter?: {
+        card: "summary" | "summary_large_image";
+        title: string;
+        description: string;
+        site?: string;
+        images?: string[];
+    };
+}
+/**
+ * Combines the page-level input with site-wide SEO defaults to
+ * produce a fully-resolved metadata object suitable for
+ * Next.js' `generateMetadata`. Title, description, and image
+ * fall back through to defaults; the OG and Twitter blocks are
+ * mirrored so both crawler families see consistent values.
+ */
+declare function buildPageMetadata(input?: NpPageMetadataInput): Promise<NpPageMetadata>;
+/**
+ * Validates a partial patch against the `seo` settings shape.
+ * Throws when fields are mistyped; returns the merged settings
+ * the admin endpoint should persist. Mirrors
+ * `validateCommunitySettingsPatch` in the community module.
+ */
+interface NpSeoSettingsPatch {
+    defaultOgImage?: string | null;
+    twitterHandle?: string | null;
+    defaultLocale?: string | null;
+}
+declare function validateSeoSettingsPatch(patch: unknown): NpSeoSettingsPatch;
+
+/**
+ * Phase 10.4 — Atom feed builder. Atom (RFC 4287) over RSS 2.0
+ * because Atom has tighter spec compliance, mandatory unique
+ * IDs, and timezone-correct timestamps that RSS 2.0 leaves
+ * underspecified. Most modern readers consume both, but new
+ * surfaces should write Atom.
+ *
+ * Sites declare which collections expose a feed by giving them
+ * `seo.urlPath` (already required for the sitemap, 10.1). The
+ * feed reuses the same anonymous-read query path so non-public
+ * rows never leak — same trust model as `/sitemap.xml`.
+ */
+interface NpFeedEntry {
+    /** Stable id (we use the absolute canonical URL). */
+    id: string;
+    title: string;
+    /** Short summary; HTML escaped on the way out. */
+    summary: string | null;
+    link: string;
+    /** Author display name; null when unavailable (e.g. anonymous post). */
+    author: string | null;
+    /** ISO 8601. The Atom `<updated>` element. */
+    updated: string;
+    /** ISO 8601. Optional — emitted as `<published>`. */
+    published: string | null;
+}
+interface BuildAtomFeedOptions {
+    collection?: string;
+    /** Cap entries per feed. Default 50 — most readers ignore beyond that. */
+    limit?: number;
+    /**
+     * Phase 12.4 — restrict an i18n collection's feed to one
+     * locale. Ignored on non-i18n collections. The Atom feed's
+     * top-level `<title>` / `<subtitle>` aren't translated by
+     * the framework — sites that want fully translated feeds
+     * pass their own language-specific siteName / description
+     * via custom site settings hooks.
+     */
+    locale?: string;
+    /**
+     * Phase F.7 — extra entries to merge into the feed alongside
+     * the collection walk. Supplied by the active theme's
+     * `impl.seo.feedEntries` hook through the route handler.
+     * Deduplicated against the collection-walk output by `id`
+     * (collection-walk wins on collision); the final list is
+     * sorted by `updated` desc and capped by `limit`.
+     */
+    extraEntries?: NpFeedEntry[];
+}
+/**
+ * Walks a single collection's published documents and returns a
+ * flat list of feed entries. Skips collections that don't
+ * declare `seo.urlPath` (the same opt-in the sitemap uses).
+ * Anonymous read access required — `findDocuments` runs the
+ * collection's `access.read` callback with no user.
+ */
+declare function buildAtomFeed(options?: BuildAtomFeedOptions): Promise<{
+    entries: NpFeedEntry[];
+    collection: string;
+} | null>;
+/**
+ * Renders the Atom 1.0 XML body. Doesn't depend on any specific
+ * runtime so it's safe to call from a route handler, a static
+ * builder, or a CLI exporter.
+ */
+declare function renderAtomFeed(options?: BuildAtomFeedOptions): Promise<string | null>;
+
+/**
+ * Phase 10.5 — JSON-LD structured data builders. Schema.org
+ * vocabulary, embedded into pages as
+ * `<script type="application/ld+json">{ ... }</script>`. The
+ * builders here produce plain objects; pages render them via
+ * the helper component the reference app declares
+ * (`@/components/json-ld`). Keeping the builders structural
+ * (no React dependency) lets non-Next consumers — static
+ * exporters, mobile bridges, plugin tests — emit the same
+ * shapes.
+ *
+ * Why JSON-LD over Microdata / RDFa: Google explicitly
+ * recommends JSON-LD as the preferred format for structured
+ * data, and it composes cleanly because it doesn't require
+ * splicing schema attributes into the page markup.
+ */
+declare const SCHEMA = "https://schema.org";
+interface BuildJsonLdContext {
+    /** Origin without trailing slash. Falls back to settings if omitted. */
+    origin?: string;
+}
+/**
+ * `WebSite` + `SearchAction` for the site root. Tells search
+ * engines the canonical site name and lets Google render a
+ * sitelinks searchbox in result pages — when the user types
+ * into it, the engine routes them straight to /search?q=… on
+ * the site instead of returning more SERP results.
+ */
+interface WebSiteJsonLd {
+    "@context": typeof SCHEMA;
+    "@type": "WebSite";
+    name: string;
+    url: string;
+    potentialAction?: {
+        "@type": "SearchAction";
+        target: {
+            "@type": "EntryPoint";
+            urlTemplate: string;
+        };
+        "query-input": string;
+    };
+}
+declare function buildWebSiteJsonLd(ctx?: BuildJsonLdContext): Promise<WebSiteJsonLd>;
+/**
+ * `BlogPosting` (a subtype of Article) for blog posts. Keeps
+ * the structural fields a search engine cares about — headline,
+ * dates, author, image, description — without trying to encode
+ * the body content.
+ */
+interface ArticleJsonLdInput {
+    /** Canonical URL of the article. */
+    url: string;
+    headline: string;
+    description?: string | null;
+    /** Absolute URL or `/`-rooted path. Resolved against `origin`. */
+    image?: string | null;
+    datePublished?: Date | string | null;
+    dateModified?: Date | string | null;
+    authorName?: string | null;
+    /** Schema.org type. Defaults to `BlogPosting`; forum threads use
+     *  `DiscussionForumPosting` via `buildDiscussionForumPostingJsonLd`. */
+    type?: "BlogPosting" | "Article";
+}
+interface ArticleJsonLd {
+    "@context": typeof SCHEMA;
+    "@type": "BlogPosting" | "Article";
+    headline: string;
+    url: string;
+    description?: string;
+    image?: string;
+    datePublished?: string;
+    dateModified?: string;
+    author?: {
+        "@type": "Person";
+        name: string;
+    };
+    publisher: {
+        "@type": "Organization";
+        name: string;
+        url: string;
+    };
+}
+declare function buildArticleJsonLd(input: ArticleJsonLdInput, ctx?: BuildJsonLdContext): Promise<ArticleJsonLd>;
+/**
+ * `DiscussionForumPosting` for member-authored forum threads.
+ * Same skeleton as `Article` but the type tells search engines
+ * (and surfaces like Google's "Forums" filter) that this is
+ * community discussion, not editorial content.
+ */
+interface DiscussionForumPostingJsonLd extends Omit<ArticleJsonLd, "@type"> {
+    "@type": "DiscussionForumPosting";
+}
+declare function buildDiscussionForumPostingJsonLd(input: ArticleJsonLdInput, ctx?: BuildJsonLdContext): Promise<DiscussionForumPostingJsonLd>;
+/**
+ * `Person` for member / user profile pages. Keeps the public
+ * fields a search engine could legitimately surface — handle,
+ * display name, profile URL, avatar.
+ */
+interface PersonJsonLdInput {
+    url: string;
+    name: string;
+    alternateName?: string | null;
+    image?: string | null;
+    description?: string | null;
+}
+interface PersonJsonLd {
+    "@context": typeof SCHEMA;
+    "@type": "Person";
+    name: string;
+    url: string;
+    alternateName?: string;
+    image?: string;
+    description?: string;
+}
+declare function buildPersonJsonLd(input: PersonJsonLdInput, ctx?: BuildJsonLdContext): Promise<PersonJsonLd>;
+
+export { type ArticleJsonLd, type ArticleJsonLdInput, type BuildAtomFeedOptions, type BuildJsonLdContext, type BuildSitemapOptions, DEFAULT_SITE_SEO_SETTINGS, type DiscussionForumPostingJsonLd, type NpFeedEntry, type NpPageMetadata, type NpPageMetadataInput, type NpSeoSettingsPatch, type NpSiteSeoSettings, type NpSitemapEntry, type NpSitemapIndexEntry, type PersonJsonLd, type PersonJsonLdInput, type WebSiteJsonLd, buildArticleJsonLd, buildAtomFeed, buildDiscussionForumPostingJsonLd, buildPageMetadata, buildPersonJsonLd, buildSitemap, buildWebSiteJsonLd, getSiteSeoSettings, renderAtomFeed, renderSitemapIndexXml, renderSitemapXml, validateSeoSettingsPatch };

package/dist/seo.js

@@ -0,0 +1,44 @@
+import {
+  DEFAULT_SITE_SEO_SETTINGS,
+  buildArticleJsonLd,
+  buildAtomFeed,
+  buildDiscussionForumPostingJsonLd,
+  buildPageMetadata,
+  buildPersonJsonLd,
+  buildSitemap,
+  buildWebSiteJsonLd,
+  getSiteSeoSettings,
+  renderAtomFeed,
+  renderSitemapIndexXml,
+  renderSitemapXml,
+  validateSeoSettingsPatch
+} from "./chunk-DP2PREDU.js";
+import "./chunk-VGTPQXNQ.js";
+import "./chunk-4ZLMEKFX.js";
+import "./chunk-FZ7O6DWI.js";
+import "./chunk-SBCVAC2Z.js";
+import "./chunk-ZCINJSS4.js";
+import "./chunk-WV272MPW.js";
+import "./chunk-473S4TER.js";
+import "./chunk-V2UNHGAP.js";
+import "./chunk-OROPGO65.js";
+import "./chunk-JJL74ZPK.js";
+import "./chunk-XANPEOJC.js";
+import "./chunk-M43PGOQY.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  DEFAULT_SITE_SEO_SETTINGS,
+  buildArticleJsonLd,
+  buildAtomFeed,
+  buildDiscussionForumPostingJsonLd,
+  buildPageMetadata,
+  buildPersonJsonLd,
+  buildSitemap,
+  buildWebSiteJsonLd,
+  getSiteSeoSettings,
+  renderAtomFeed,
+  renderSitemapIndexXml,
+  renderSitemapXml,
+  validateSeoSettingsPatch
+};
+//# sourceMappingURL=seo.js.map

package/dist/seo.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/settings-FOBIESPB.js

@@ -0,0 +1,17 @@
+import {
+  DEFAULT_COMMUNITY_SETTINGS,
+  getCommunitySettings,
+  updateCommunitySettings,
+  validateCommunitySettingsPatch
+} from "./chunk-PPBWRKO2.js";
+import "./chunk-ZCINJSS4.js";
+import "./chunk-XANPEOJC.js";
+import "./chunk-M43PGOQY.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  DEFAULT_COMMUNITY_SETTINGS,
+  getCommunitySettings,
+  updateCommunitySettings,
+  validateCommunitySettingsPatch
+};
+//# sourceMappingURL=settings-FOBIESPB.js.map

package/dist/settings-FOBIESPB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/spam-adapter-XX3G737Z.js

@@ -0,0 +1,12 @@
+import {
+  getSpamAdapter,
+  resetSpamAdapter,
+  setSpamAdapter
+} from "./chunk-JKXAPSU4.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  getSpamAdapter,
+  resetSpamAdapter,
+  setSpamAdapter
+};
+//# sourceMappingURL=spam-adapter-XX3G737Z.js.map

package/dist/spam-adapter-XX3G737Z.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/strings-VAE47B2C.js

@@ -0,0 +1,29 @@
+import {
+  addStrings,
+  getAllStrings,
+  getStrings,
+  resetStrings,
+  resetTranslationCache,
+  setStrings,
+  t,
+  tSync
+} from "./chunk-QVJ2HCAX.js";
+import "./chunk-4ZLMEKFX.js";
+import "./chunk-FZ7O6DWI.js";
+import "./chunk-SBCVAC2Z.js";
+import "./chunk-ZCINJSS4.js";
+import "./chunk-JJL74ZPK.js";
+import "./chunk-XANPEOJC.js";
+import "./chunk-M43PGOQY.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  addStrings,
+  getAllStrings,
+  getStrings,
+  resetStrings,
+  resetTranslationCache,
+  setStrings,
+  t,
+  tSync
+};
+//# sourceMappingURL=strings-VAE47B2C.js.map

package/dist/strings-VAE47B2C.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/templates-IFVJMCJ6.js

@@ -0,0 +1,12 @@
+import {
+  getPluginTemplatesForCollection,
+  registerPluginTemplates,
+  resetPluginTemplates
+} from "./chunk-CRUQBZUF.js";
+import "./chunk-PZ5AY32C.js";
+export {
+  getPluginTemplatesForCollection,
+  registerPluginTemplates,
+  resetPluginTemplates
+};
+//# sourceMappingURL=templates-IFVJMCJ6.js.map

package/dist/templates-IFVJMCJ6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}