@sonordev/site-kit 8.2.0 → 8.4.0

package/dist/press-kit/articles/server-core.d.ts

@@ -0,0 +1,479 @@
+/**
+ * @sonordev/press-kit/articles/server
+ *
+ * Data and metadata helpers only (no React components). For `Article` / `ArticleList`
+ * in the App Router, import from `@sonordev/press-kit/articles/server-ui` so Next never
+ * treats `getAllArticleSlugs` / `generateArticleStaticParams` as client code.
+ */
+import type { Metadata } from 'next';
+import type { Article as ArticleRecord, ArticleAuthor, TopicCluster, ClusterNavigation } from './types';
+import { ArticleUnavailableError } from './public-reads';
+import { sanitizeExcerpt } from './excerpt';
+import { articleImageSchema, resolveRepresentativeImage } from './artwork';
+import { type PublicationRoutingOptions } from './routes';
+import { type NewsSitemapOptions } from './news-sitemap';
+export { sanitizeExcerpt, ArticleUnavailableError, resolveRepresentativeImage, articleImageSchema };
+export type { ArticleReadResult } from './public-reads';
+export declare function getArticleResult(slug: string, options?: {
+    site?: string;
+}): Promise<{
+    state: 'ready';
+    value: ArticleRecord;
+} | {
+    state: 'not_found';
+} | {
+    state: 'unavailable';
+    status?: number;
+} | {
+    state: 'unavailable';
+}>;
+export declare const SEO_LIMITS: {
+    readonly title: {
+        readonly min: 30;
+        readonly max: 60;
+        readonly recommended: 55;
+    };
+    readonly metaDescription: {
+        readonly min: 120;
+        readonly max: 160;
+        readonly recommended: 155;
+    };
+    readonly excerpt: {
+        readonly min: 100;
+        readonly max: 300;
+        readonly recommended: 200;
+    };
+    readonly slug: {
+        readonly max: 75;
+    };
+    readonly focusKeyphrase: {
+        readonly min: 2;
+        readonly max: 4;
+        readonly words: true;
+    };
+};
+export interface SeoValidationResult {
+    field: string;
+    value: string;
+    length: number;
+    limit: {
+        min?: number;
+        max: number;
+        recommended?: number;
+    };
+    status: 'good' | 'warning' | 'error';
+    message: string;
+}
+/**
+ * Validate SEO title (60 chars max, keyword-first recommended)
+ */
+export declare function validateSeoTitle(title: string, focusKeyphrase?: string): SeoValidationResult;
+/**
+ * Validate meta description (150-160 chars, benefit-driven)
+ */
+export declare function validateMetaDescription(description: string, focusKeyphrase?: string): SeoValidationResult;
+/**
+ * Full SEO validation for an article
+ */
+export declare function validateArticleSeo(post: Partial<ArticleRecord>): SeoValidationResult[];
+/**
+ * Fetch an article by slug (server-side)
+ *
+ * @param options.site - Sub-site host override. Omit to resolve from
+ *   NEXT_PUBLIC_SITE_URL.
+ */
+export declare function getArticle(slug: string, options?: {
+    site?: string;
+}): Promise<ArticleRecord | null>;
+/**
+ * Fetch an article by slug, or answer 404 when there isn't one.
+ *
+ * `getArticle` returns null for a mistyped or deleted slug, and the page
+ * used to carry on rendering a "not found" message with HTTP 200 and an
+ * indexable title: a soft 404 on every bad post URL. This calls Next's
+ * `notFound()` instead, so the
+ * route answers 404 with `noindex`.
+ *
+ * Call it from `generateMetadata` (or the page) before rendering `Article`:
+ * metadata resolves before anything streams, so the status is a real 404.
+ * The fetch is the same one `Article` and `generateArticleMetadata` make,
+ * and Next dedupes it within the render.
+ *
+ * @example
+ * ```tsx
+ * export async function generateMetadata({ params }) {
+ *   const { slug } = await params
+ *   await requireArticle(slug)
+ *   return generateArticleMetadata(slug, { siteName: 'Acme' })
+ * }
+ * ```
+ */
+export declare function requireArticle(slug: string, options?: {
+    site?: string;
+}): Promise<ArticleRecord>;
+/**
+ * Fetch all article slugs for static generation
+ */
+export declare function getAllArticleSlugs(): Promise<{
+    slug: string;
+    id?: string;
+    last_modified?: string;
+    article_type?: string;
+}[]>;
+/**
+ * Fetch article categories
+ */
+export declare function getArticleCategories(options?: {
+    site?: string;
+}): Promise<{
+    name: string;
+    slug: string;
+    post_count: number;
+}[]>;
+export interface PublicationMetadataOptions extends PublicationRoutingOptions {
+    /** Site name for og:site_name */
+    siteName?: string;
+    /** Base URL of the site */
+    siteUrl?: string;
+    /** URL path prefix for publication index and posts (default `/article`, e.g. `/insights`) */
+    /** Default OG image */
+    defaultImage?: string;
+    /** Twitter handle */
+    twitterHandle?: string;
+}
+export interface ArticleMetadataOptions extends PublicationMetadataOptions {
+    /**
+     * Declare the featured image (or `defaultImage`) as `openGraph.images` and
+     * `twitter.images`. Default true.
+     *
+     * Pass false when the post route has its own card, an
+     * `opengraph-image.tsx` beside the page. Next lets declared images beat
+     * that file, so leaving them in silently swaps the post's card for the raw
+     * photo. With false the `images` keys are left out entirely, not set to
+     * undefined: Next checks `hasOwnProperty('images')`, so even an undefined
+     * value hides the card.
+     */
+    images?: boolean;
+    /**
+     * What to do when the post doesn't exist. Default true: call Next's
+     * `notFound()`, so the route answers 404. False returns placeholder
+     * metadata marked `noindex` instead, for a page that renders its own
+     * missing-post state.
+     */
+    notFound?: boolean;
+}
+/**
+ * Generate metadata for an article page
+ */
+export declare function generateArticleMetadata(slug: string, options?: ArticleMetadataOptions): Promise<Metadata>;
+/**
+ * Generate metadata for the publication index page
+ */
+export declare function generatePublicationMetadata(options: PublicationMetadataOptions & {
+    title?: string;
+    description?: string;
+}): Metadata;
+/**
+ * Generate metadata for a category page
+ */
+export declare function generateArticleCategoryMetadata(categoryName: string, options?: PublicationMetadataOptions & {
+    categorySlug?: string;
+}): Metadata;
+/**
+ * What Next passes to a route's `generateStaticParams`: the parent segments'
+ * params. The publication helpers ignore it; it's typed so they can be exported
+ * directly as `generateStaticParams`.
+ */
+export interface NextStaticParamsProps {
+    params: unknown;
+}
+/**
+ * Generate static params for article pages.
+ *
+ * Export it directly for the default `/article/[slug]` routes:
+ *
+ *   export const generateStaticParams = generateArticleStaticParams
+ *
+ * With routing options, wrap it:
+ *
+ *   export function generateStaticParams() {
+ *     return generateArticleStaticParams(routing)
+ *   }
+ */
+export declare function generateArticleStaticParams(options?: PublicationRoutingOptions): Promise<{
+    slug: string;
+    category?: string;
+}[]>;
+export declare function generateArticleStaticParams(props: NextStaticParamsProps): Promise<{
+    slug: string;
+    category?: string;
+}[]>;
+/**
+ * Generate static params for category pages. Takes no arguments, so it can be
+ * exported directly:
+ *
+ *   export const generateStaticParams = generateCategoryStaticParams
+ */
+export declare function generateCategoryStaticParams(): Promise<{
+    category: string;
+}[]>;
+interface SitemapEntry {
+    url: string;
+    lastModified?: Date;
+    changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    priority?: number;
+    /** Image sitemap entries; Next's MetadataRoute.Sitemap renders them as <image:image>. */
+    images?: string[];
+}
+/**
+ * Generate sitemap entries for articles
+ */
+export interface ArticleSitemapOptions extends PublicationRoutingOptions {
+    includeCategories?: boolean;
+    includeClusters?: boolean;
+}
+export declare function generateArticleSitemap(siteUrl: string, options?: ArticleSitemapOptions): Promise<SitemapEntry[]>;
+/**
+ * Google News sitemap XML for posts published in the last two days. Serve it
+ * from a route (app/news-sitemap.xml/route.ts) and list it in robots.txt.
+ */
+export declare function generateNewsSitemap(options: NewsSitemapOptions & {
+    site?: string;
+}): Promise<string>;
+/**
+ * Generate JSON-LD schema for an article
+ */
+export declare function generateArticleSchema(post: ArticleRecord, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+    logoUrl?: string;
+}): object;
+/**
+ * Generate JSON-LD schema for publication index/listing page
+ */
+export declare function generateArticleListSchema(options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+    description?: string;
+}): object;
+/**
+ * Generate standalone FAQ schema (great for PAA inclusion)
+ */
+export declare function generateFaqSchema(faqItems: {
+    question: string;
+    answer: string;
+}[]): object | null;
+export interface HowToStep {
+    name: string;
+    text: string;
+    image?: string;
+    url?: string;
+}
+/**
+ * Generate HowTo schema for step-by-step posts
+ */
+export declare function generateHowToSchema(post: ArticleRecord, steps: HowToStep[], options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+}): object;
+export interface RssFeedOptions extends PublicationRoutingOptions {
+    siteUrl: string;
+    siteName: string;
+    description?: string;
+    language?: string;
+    copyright?: string;
+    managingEditor?: string;
+    webMaster?: string;
+    ttl?: number;
+    imageUrl?: string;
+    /** Most recent posts to include. Defaults to FEED_DEFAULT_ITEMS (20); older posts stay in the sitemap. */
+    maxItems?: number;
+}
+/**
+ * Fetch all published articles for RSS feed.
+ *
+ * Paginates with `per_page`/`page` — the only pagination params the deployed
+ * controller reads — accumulating up to FEED_MAX_POSTS. A mid-loop failure throws ArticleUnavailableError; a truncated archive must
+ * not be reported as a complete collection.
+ */
+export declare function getAllArticles(options?: {
+    maxPosts?: number; /** Sub-site host override (see getArticle). */
+    site?: string;
+}): Promise<ArticleRecord[]>;
+/**
+ * Generate RSS 2.0 feed XML
+ */
+export declare function generateRssFeed(options: RssFeedOptions): Promise<string>;
+/**
+ * Generate Atom feed XML
+ */
+export declare function generateAtomFeed(options: RssFeedOptions): Promise<string>;
+/**
+ * Fetch all active topic clusters for the project.
+ * Uses the real cluster data from Sonor API (not heuristic-based).
+ */
+export declare function getTopicClusters(options?: {
+    site?: string;
+}): Promise<TopicCluster[]>;
+/**
+ * Fetch a single topic cluster with its pillar and support articles.
+ */
+export declare function getTopicCluster(slug: string, options?: {
+    site?: string;
+}): Promise<TopicCluster | null>;
+/**
+ * Get cluster navigation context for an article.
+ * Returns the cluster name, pillar link, and sibling articles.
+ */
+export declare function getClusterNavigation(post: ArticleRecord): ClusterNavigation | null;
+/**
+ * Fetch posts by category for topic cluster organization
+ */
+export declare function getPostsByCategory(categorySlug: string, options?: {
+    site?: string;
+}): Promise<ArticleRecord[]>;
+/**
+ * Generate ItemList schema for a cluster's pillar page.
+ * Wraps supporting posts as a structured list Google can parse.
+ */
+export declare function generateClusterItemListSchema(cluster: TopicCluster, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+}): object;
+/**
+ * Generate Article schema with cluster relationship (isPartOf / hasPart).
+ * - Support articles get `isPartOf` pointing to the pillar.
+ * - Pillar articles get `hasPart` listing all supports.
+ */
+export declare function generateClusterArticleSchema(post: ArticleRecord, cluster: TopicCluster, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+    logoUrl?: string;
+}): object;
+/**
+ * Generate BreadcrumbList schema for a cluster-linked post.
+ * Path: Home > Article > Cluster > Article
+ */
+export declare function generateClusterBreadcrumbSchema(post: ArticleRecord, cluster: TopicCluster, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+}): object;
+/**
+ * Generate CollectionPage schema for a cluster landing page.
+ */
+export declare function generateClusterLandingSchema(cluster: TopicCluster, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+}): object;
+/**
+ * Generate metadata for a cluster landing page (Next.js generateMetadata).
+ */
+export declare function generateClusterPageMetadata(clusterSlug: string, options?: PublicationRoutingOptions & {
+    siteName?: string;
+    siteUrl?: string;
+}): Promise<{
+    title?: undefined;
+    description?: undefined;
+    openGraph?: undefined;
+} | {
+    title: string;
+    description: string;
+    openGraph: {
+        title: string;
+        description: string;
+        url: string;
+        type: string;
+    };
+}>;
+/**
+ * Generate "Related Insights" section data
+ */
+export declare function getRelatedInsights(currentSlug: string, options?: {
+    limit?: number;
+    category?: string; /** Sub-site host override (see getArticle). */
+    site?: string;
+}): Promise<ArticleRecord[]>;
+/**
+ * Generate BreadcrumbList schema for article navigation
+ */
+export declare function generateBreadcrumbSchema(post: ArticleRecord, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+}): object;
+/**
+ * Generate all relevant schemas for an article in a single array
+ * This is the recommended way to include multiple schemas.
+ * When post has E-E-A-T schema (post.schema), use it instead of generating Article/FAQ.
+ */
+export declare function generateAllArticleSchemas(post: ArticleRecord, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+    logoUrl?: string;
+}): object[];
+/**
+ * Fetch a single author by slug
+ */
+export declare function getAuthorBySlug(slug: string, options?: {
+    site?: string;
+}): Promise<ArticleAuthor | null>;
+/**
+ * Fetch an author's posts by slug.
+ *
+ * `offset` pages through the controller's existing offset support. Older API
+ * versions return a stripped `{name, slug}` author on this endpoint; when
+ * that shape is detected the full author row is hydrated via getAuthorBySlug
+ * (both fetches revalidate:60, so the extra hop is cached and disappears once
+ * the API returns the full row itself).
+ */
+export declare function getAuthorPosts(slug: string, limit?: number, offset?: number, options?: {
+    site?: string;
+}): Promise<{
+    author: ArticleAuthor | null;
+    posts: ArticleRecord[];
+    total: number;
+}>;
+/**
+ * Fetch all author slugs for static generation
+ */
+export declare function getAllAuthorSlugs(): Promise<{
+    slug: string;
+}[]>;
+/**
+ * Generate static params for author pages. Takes no arguments, so it can be
+ * exported directly:
+ *
+ *   export const generateStaticParams = generateAuthorStaticParams
+ */
+export declare function generateAuthorStaticParams(): Promise<{
+    slug: string;
+}[]>;
+/**
+ * Generate Next.js Metadata for an author page
+ */
+export declare function generateAuthorPageMetadata(author: ArticleAuthor, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+}): Metadata;
+/**
+ * Author JSON-LD: `generateAuthorSchema` (the author page's ProfilePage with
+ * the Person as mainEntity), `generateAuthorPersonSchema` (the bare Person for
+ * embedding), `generateArticleAuthorNode` (an article byline) and
+ * `authorEntityId` (the Person @id rule).
+ *
+ * The implementation lives in `./author-schema` because it is pure, and
+ * `AuthorPage` — which is exported from the client-stamped `articles` barrel —
+ * needs it. Importing it from here instead would drag this entire server module
+ * into the browser bundle. Re-exported so `@sonordev/press-kit/articles/server`
+ * keeps its existing public API.
+ */
+export { authorEntityId, generateArticleAuthorNode, generateAuthorPersonSchema, generateAuthorSchema, withArticleAuthorIdentity, type AuthorSchemaOptions, } from './author-schema';
+/** Sonor article document shape (alias of `Article` from `./types`) */
+export type { Article as ArticleRecord } from './types';
+export { articleCategorySlug, createPublicationRoutes, resolveArticleUrl, resolvePublicationUrl } from './routes';
+export type { ArticleRoutePost, PublicationRoutingOptions } from './routes';
+export { resolveArticleArtwork } from './artwork';
+export { wrapArticleTables, articleTableCss } from './article-tables';
+export { insertArticlePhotos, articlePhotoCss } from './article-photos';
+export type { ArticleEditorialPhoto } from './types';
+export { FEED_DEFAULT_ITEMS, NEWS_SITEMAP_MAX_URLS, NEWS_SITEMAP_WINDOW_MS, buildNewsSitemapXml, cdata, recentNewsPosts } from './news-sitemap';
+export type { NewsSitemapOptions, NewsSitemapPost } from './news-sitemap';
+export { getPublicationIssues, getPublicationIssue, getArticlePreview, createPublicationPreviewHandler, PUBLICATION_PREVIEW_COOKIE, PUBLICATION_PREVIEW_HEADERS } from './publication-reads';
+export type { PublicationIssue, PublicationIssueList, ArticlePreview } from './publication-reads';

package/dist/press-kit/articles/server-ui.d.ts

@@ -0,0 +1,31 @@
+import 'server-only';
+/**
+ * @sonordev/press-kit/articles/server-ui
+ *
+ * RSC-safe `Article` and `ArticleList` without sharing a bundle with `articles/server`
+ * data helpers. Importing them from `articles/server` pulled hook-heavy chunks that
+ * received a synthetic `'use client'` during the site-kit build, which broke
+ * `generateStaticParams` and other server-only callers.
+ *
+ * Use `@sonordev/press-kit/articles/server` for getArticle, getAllArticleSlugs,
+ * metadata, RSS, etc.
+ */
+export { Article } from './Article';
+export type { ArticleServerProps, ArticleStyles } from './Article';
+export { ArticleList } from './ArticleList';
+export type { ArticleListServerProps, ArticleListStyles } from './ArticleList';
+export { ClusterLandingPage } from './ClusterLandingPage';
+export type { ClusterLandingPageProps } from './ClusterLandingPage';
+export { ClusterNavigation } from './ClusterNavigation';
+export type { ClusterNavigationProps } from './ClusterNavigation';
+export { PublicationLayout, PublicationPage, ArticlePage, CategoryPage } from './PublicationLayout';
+export type { PublicationLayoutProps, PublicationPageProps, ArticlePageProps, CategoryPageProps, } from './PublicationLayout';
+export { PublicationSidebar } from './PublicationSidebar';
+export type { PublicationSidebarProps } from './PublicationSidebar';
+export { RelatedPosts } from './RelatedPosts';
+export { articleCategorySlug, createPublicationRoutes, resolveArticleUrl, resolvePublicationUrl } from './routes';
+export type { ArticleRoutePost, PublicationRoutingOptions } from './routes';
+export { resolveArticleArtwork } from './artwork';
+export { wrapArticleTables, articleTableCss } from './article-tables';
+export { insertArticlePhotos, articlePhotoCss } from './article-photos';
+export type { ArticleEditorialPhoto } from './types';