@sonordev/site-kit 8.2.0 → 8.4.0

package/dist/press-kit/articles/PublicationSidebar.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @sonordev/press-kit/articles - Article Sidebar Component
+ *
+ * A reusable sidebar for article pages with categories, recent posts,
+ * tags, newsletter signup, and custom widgets.
+ */
+import React from 'react';
+import { type PublicationRoutingOptions } from './routes';
+export interface PublicationSidebarProps {
+    /** Sonor API URL */
+    apiUrl?: string;
+    /** Project API key */
+    apiKey?: string;
+    /** Sub-site host for multi-site projects. Omit to resolve from NEXT_PUBLIC_SITE_URL. */
+    site?: string;
+    /** Show categories widget */
+    showCategories?: boolean;
+    /** Show recent posts widget */
+    showRecentPosts?: boolean;
+    /** Number of recent posts to show */
+    recentPostsCount?: number;
+    /** Show tags widget */
+    showTags?: boolean;
+    /** Show search widget */
+    showSearch?: boolean;
+    /** Base URL for article links */
+    basePath?: string;
+    routing?: PublicationRoutingOptions;
+    /** Custom class name */
+    className?: string;
+    /** Current category filter (for highlighting) */
+    currentCategory?: string;
+    /** Additional widgets to render */
+    children?: React.ReactNode;
+}
+export declare function PublicationSidebar({ apiUrl, apiKey, site, showCategories, showRecentPosts, recentPostsCount, showTags, showSearch, basePath, routing, className, currentCategory, children, }: PublicationSidebarProps): Promise<React.JSX.Element | null>;

package/dist/press-kit/articles/RelatedPosts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @sonordev/press-kit/articles - Related articles component
+ *
+ * Fetches and displays related articles via Sonor API
+ */
+import React from 'react';
+import type { Article } from './types';
+import { type PublicationRoutingOptions } from './routes';
+interface RelatedPostsServerProps {
+    apiUrl?: string;
+    apiKey?: string;
+    currentPostId: string;
+    limit?: number;
+    /** Sub-site host for multi-site projects. Omit to resolve from NEXT_PUBLIC_SITE_URL. */
+    site?: string;
+    className?: string;
+    basePath?: string;
+    routing?: PublicationRoutingOptions;
+    renderItem?: (post: Article) => React.ReactNode;
+}
+export declare function RelatedPosts({ apiUrl, apiKey, currentPostId, limit, site, className, basePath, routing, renderItem, }: RelatedPostsServerProps): Promise<React.JSX.Element | null>;
+export {};

package/dist/press-kit/articles/ServiceCallout.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @sonordev/press-kit/articles - Service Callout / CTA Component
+ *
+ * Renders a promotional call-to-action section within articles.
+ * Automatically generated by Signal AI during article creation, linking
+ * article content to the business's relevant services.
+ *
+ * Two variants:
+ * - 'featured' (default): Full-width gradient banner with button
+ * - 'inline': Compact card with icon accent
+ *
+ * Uses site-kit brand tokens (--sk-primary, --sk-bg, etc.) for theming.
+ * Supports full Tailwind override via `styles` prop.
+ *
+ * @example
+ * ```tsx
+ * <ServiceCallout
+ *   title="Ready to build your MVP?"
+ *   description="Our team specializes in lean SaaS builds."
+ *   cta="Get Started"
+ *   url="/services/application-development"
+ * />
+ * ```
+ */
+import React from 'react';
+export interface ServiceCalloutProps {
+    title: string;
+    description?: string;
+    cta?: string;
+    url: string;
+    variant?: 'featured' | 'inline';
+    /** Override default styles with Tailwind classes */
+    styles?: {
+        wrapper?: string;
+        title?: string;
+        description?: string;
+        button?: string;
+    };
+    /** Strip all default styles (BYO Tailwind) */
+    unstyled?: boolean;
+}
+export declare function ServiceCallout({ title, description, cta, url, variant, styles, unstyled, }: ServiceCalloutProps): React.JSX.Element;
+/**
+ * Renders all service callouts for an article.
+ * First callout uses 'featured' variant, subsequent use 'inline'.
+ */
+export declare function ServiceCallouts({ callouts, styles, unstyled, }: {
+    callouts: Array<{
+        title: string;
+        description?: string;
+        cta?: string;
+        url: string;
+    }>;
+    styles?: ServiceCalloutProps['styles'];
+    unstyled?: boolean;
+}): React.JSX.Element | null;

package/dist/press-kit/articles/TableOfContents.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @sonordev/press-kit/articles - Table of Contents Component
+ */
+import React from 'react';
+import type { TableOfContentsProps } from './types';
+export declare function TableOfContents({ content, className, maxDepth, }: TableOfContentsProps): React.JSX.Element | null;

package/dist/press-kit/articles/article-photos.d.ts

@@ -0,0 +1,9 @@
+import type { ArticleEditorialPhoto } from './types';
+/**
+ * Inserts approved public photo snapshots at explicitly authored placements.
+ * Missing/duplicate headings, unmatched sections and photos already in the body
+ * are skipped. Never changes the author's paragraphs, headings or other markup.
+ * This is a layout transform, not a sanitizer for the original article HTML.
+ */
+export declare function insertArticlePhotos(html: string, photos?: ArticleEditorialPhoto[] | null): string;
+export declare const articlePhotoCss = "\n.sk-article-photo { margin: 2em 0; max-width: 100%; }\n.sk-article-photo img { display: block; width: 100%; max-width: 100%; height: auto; border-radius: var(--sk-radius, 0.75rem); }\n.sk-article-photo figcaption { margin-top: 0.65em; color: var(--sk-text-secondary, inherit); font-size: 0.875em; line-height: 1.5; overflow-wrap: anywhere; }\n";

package/dist/press-kit/articles/article-styles.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Scoped CSS for Article and ArticleList default rendering.
+ *
+ * Injected via `<style>` in the server component output so consumers
+ * get a polished article with zero configuration.
+ *
+ * All colours use `--sk-*` CSS custom properties with `color-mix()` fallbacks
+ * that adapt to both light and dark host sites. The host can set:
+ *
+ *   --sk-primary          Brand accent (links, highlights)
+ *   --sk-bg               Page background
+ *   --sk-bg-elevated      Card / elevated surface background
+ *   --sk-text-primary     Main text
+ *   --sk-text-secondary   Subdued text
+ *   --sk-text-tertiary    Faint text / meta
+ *   --sk-surface-border   Subtle border color
+ *
+ * If none are set the defaults produce a clean neutral light-mode look.
+ */
+export declare const articleCss: string;
+export declare const articleListCss: string;

package/dist/press-kit/articles/article-tables.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-rendered table scrolling. Keep the author's table markup intact so
+ * captions, header associations, links and table semantics survive unchanged.
+ */
+/**
+ * Single source of truth for default article table wrappers. Safe to call twice;
+ * already wrapped tables and HTML examples are left alone. This is a layout
+ * transform, not an HTML sanitizer: content still follows the host's trust policy.
+ */
+export declare function wrapArticleTables(html: string): string;
+/** Native overflow only when content needs it; small tables retain their layout. */
+export declare const articleTableCss: string;

package/dist/press-kit/articles/artwork.d.ts

@@ -0,0 +1,16 @@
+import type { CSSProperties } from 'react';
+import type { Article } from './types';
+export interface ArticleArtwork {
+    src: string | undefined;
+    alt: string;
+    composed: boolean;
+}
+type ArtworkSource = Pick<Article, 'title' | 'featured_image' | 'featured_image_alt' | 'editorial_image' | 'editorial_image_alt'>;
+/** Single source of truth for article artwork versus complete promotional cards. */
+export declare function resolveArticleArtwork(post: ArtworkSource, placement?: 'article' | 'card'): ArticleArtwork;
+/** Preserve generated text and graphics across every stock card surface. */
+export declare function articleArtworkImageStyle(artwork: ArticleArtwork): CSSProperties | undefined;
+/** Search/discovery artwork is the representative photograph; social cards stay available separately. */
+export declare function resolveRepresentativeImage(post: Partial<Pick<Article, 'title' | 'representative_image' | 'editorial_image' | 'editorial_image_alt' | 'editorial_image_width' | 'editorial_image_height' | 'featured_image' | 'featured_image_alt' | 'featured_image_width' | 'featured_image_height'>>): import('./types').ArticleImage | undefined;
+export declare function articleImageSchema(post: Partial<Article>): object | string | undefined;
+export {};

package/dist/press-kit/articles/author-schema.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @sonordev/press-kit/articles — Author JSON-LD (pure)
+ *
+ * Split out of `./server-core` on purpose. Everything here is a pure function:
+ * it maps an `ArticleAuthor` to schema objects and touches no env, no config,
+ * and no network. It only ever lived in `server-core` because the other author
+ * helpers there (`getAuthorBySlug`, `getAuthorPosts`) do fetch.
+ *
+ * `AuthorPage` is exported from the client-stamped `@sonordev/press-kit/articles`
+ * barrel (see `./index.ts`), so importing these from `server-core` dragged that
+ * whole server module — its `x-api-key` fetches included — into the browser
+ * bundle. Keeping the pure half here means `AuthorPage` can stay in the barrel
+ * without pulling a single line of server code with it.
+ *
+ * Anything added here must stay pure. If it needs an API key or a fetch, it
+ * belongs in `./server-core`, not in this file.
+ *
+ * Identity model (single source of truth for every author node the kit emits):
+ * - The author page is a `ProfilePage` whose `mainEntity` is the `Person`
+ *   (Google's profile-page markup for author pages).
+ * - The `Person` carries one `@id` everywhere it appears (`authorEntityId`):
+ *   the row's `entity_id` when the person has a cross-site identity (e.g.
+ *   https://example.com/#person), else `<author profile URL>#person`.
+ * - Article bylines (`generateArticleAuthorNode`) reference that same `@id`,
+ *   so an article, its author page and the person's own site describe one
+ *   person, which is what a Knowledge Panel is built from.
+ */
+import type { ArticleAuthor } from './types';
+import { type PublicationRoutingOptions } from './routes';
+export type AuthorSchemaOptions = PublicationRoutingOptions & {
+    siteUrl?: string;
+    siteName?: string;
+};
+/**
+ * Single source of truth for an author's Person `@id`.
+ *
+ * The row's `entity_id` (one id shared by every site that describes the
+ * person) wins. Otherwise the Person lives at `<profile URL>#person`. A
+ * relative profile URL gives no `@id`: an id must be absolute to mean the
+ * same thing on every page.
+ */
+export declare function authorEntityId(author: Pick<ArticleAuthor, 'entity_id'>, profileUrl?: string): string | undefined;
+/**
+ * The bare `Person` for an author, with no `@context`, for embedding in a
+ * larger graph (an Organization's `founder`, an `@graph` array). Author pages
+ * want `generateAuthorSchema`, which wraps this in a `ProfilePage`.
+ */
+export declare function generateAuthorPersonSchema(author: ArticleAuthor, options?: AuthorSchemaOptions): Record<string, unknown>;
+/**
+ * JSON-LD for an author page: a `ProfilePage` whose `mainEntity` is the
+ * author's `Person`. Render it once per author page (`AuthorPage` does, unless
+ * its `jsonLd` prop is false).
+ */
+export declare function generateAuthorSchema(author: ArticleAuthor, options?: AuthorSchemaOptions): object;
+/**
+ * The `author` node for article JSON-LD. Single source of truth for bylines:
+ * generateArticleSchema, generateClusterArticleSchema and stored schema_json
+ * (via withArticleAuthorIdentity) all route through here.
+ *
+ * Links to an author page only when one is known to exist: the row's
+ * `author_page_url`, or the site declaring `authorPages` in its routing. A
+ * bare string byline stays a named Person.
+ */
+export declare function generateArticleAuthorNode(author: ArticleAuthor | string | null | undefined, options?: AuthorSchemaOptions): Record<string, unknown> | undefined;
+/**
+ * Attach the author's identity to an article node from stored schema_json
+ * (built by Signal at publish time, frozen in the row). Adds `@id` and `url`
+ * from generateArticleAuthorNode when the stored byline is a Person with the
+ * same name and lacks them; stored values always win and nothing else in the
+ * node changes. Non-article nodes pass through untouched.
+ */
+export declare function withArticleAuthorIdentity(node: unknown, author: ArticleAuthor | string | null | undefined, options?: AuthorSchemaOptions): unknown;

package/dist/press-kit/articles/author-social.d.ts

@@ -0,0 +1,14 @@
+import type { ArticleAuthor } from './types';
+export interface AuthorSocialLink {
+    label: string;
+    href: string;
+}
+/**
+ * Single source of truth for author social display.
+ *
+ * The real blog_authors columns are linkedin_url / twitter_url / website_url
+ * (E-E-A-T fields); `social_links` / `website` are the legacy shape that no
+ * API response ever carried. Real columns win; legacy handles get their host
+ * prefixed unless they are already full URLs.
+ */
+export declare function getAuthorSocialLinks(author: Pick<ArticleAuthor, 'linkedin_url' | 'twitter_url' | 'website_url' | 'website' | 'social_links'>): AuthorSocialLink[];

package/dist/press-kit/articles/excerpt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Excerpt sanitizing for article metadata, schema and feeds.
+ *
+ * Pure (no `server-only` chain) so it is unit-testable and safe to reuse.
+ * Source of truth for turning a stored excerpt into display-safe prose.
+ */
+/**
+ * Turn a stored excerpt into something safe to put in a meta description,
+ * a schema `description`, or an RSS `<description>`.
+ *
+ * The AI article pipeline stores content as JSON sections
+ * (`{"heading": "## ...", "content": "## ...\n\nIf you're asking **how**..."}`)
+ * and that value can ship verbatim into <meta name="description">, leaving a
+ * SERP snippet of raw JSON with markdown asterisks and literal \n. Parse the
+ * sections out, strip markdown, and cap at a sentence boundary.
+ */
+export declare function sanitizeExcerpt(raw: string | undefined | null, maxLength?: number): string;

package/dist/press-kit/articles/index.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @sonordev/press-kit/articles
+ *
+ * Complete article integration for Sonor-managed content.
+ * Create posts in the Sonor dashboard, automatically embedded in your site.
+ *
+ * Async server components (PublicationLayout, ArticleList, Article, PublicationSidebar,
+ * RelatedPosts, the *Page helpers) come from `articles/server-ui`. This entry is
+ * 'use client'-stamped, so importing them from here hands Next an async
+ * component across a client boundary and the route 500s in production.
+ *
+ * @example
+ * ```tsx
+ * // Publication index page — both from server-ui; this barrel is for client components only
+ * import { ArticleList, PublicationLayout } from '@sonordev/press-kit/articles/server-ui'
+ *
+ * export default function PublicationPage() {
+ *   return (
+ *     <PublicationLayout hero={{ title: 'Blog', subtitle: 'Latest articles' }}>
+ *       <ArticleList showCategoryFilter showPagination />
+ *     </PublicationLayout>
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Single post page: UI from server-ui, data/metadata from server
+ * import { Article } from '@sonordev/press-kit/articles/server-ui'
+ * import { generateArticleMetadata, generateArticleStaticParams } from '@sonordev/press-kit/articles/server'
+ *
+ * export const generateStaticParams = generateArticleStaticParams
+ * export async function generateMetadata({ params }) {
+ *   return generateArticleMetadata(params.slug, { siteName: 'My Site' })
+ * }
+ *
+ * export default function Post({ params }) {
+ *   return <Article slug={params.slug} showRelated showToc />
+ * }
+ * ```
+ */
+export type { PublicationDefinition } from './publication-definition';
+export type { ArticleServerProps, ArticleStyles } from './Article';
+export type { ArticleListServerProps, ArticleListStyles } from './ArticleList';
+export type { PublicationSidebarProps } from './PublicationSidebar';
+export { NewsletterWidget } from './NewsletterWidget';
+export type { NewsletterWidgetProps } from './NewsletterWidget';
+export type { PublicationLayoutProps, PublicationPageProps, ArticlePageProps, CategoryPageProps } from './PublicationLayout';
+export { AuthorCard } from './AuthorCard';
+export { AuthorPage } from './AuthorPage';
+export { TableOfContents } from './TableOfContents';
+export { ServiceCallout, ServiceCallouts } from './ServiceCallout';
+export type { ServiceCalloutProps } from './ServiceCallout';
+export { ArticleFAQ } from './ArticleFAQ';
+export type { ArticleEditorialPhoto } from './types';
+export type { ArticleFAQProps, FaqItem } from './ArticleFAQ';
+export { ClusterNavigation } from './ClusterNavigation';
+export type { ClusterNavigationProps } from './ClusterNavigation';
+/**
+ * `ClusterLandingPage` is deliberately NOT re-exported here — import it from
+ * `@sonordev/press-kit/articles/server-ui`.
+ *
+ * This barrel is stamped `'use client'` at build time (it is listed in
+ * `CLIENT_ENTRIES`, `src/shared/build-entries.ts`), so every module it reaches
+ * is client code by declaration. `ClusterLandingPage` is an async component that
+ * awaits `getTopicCluster` from `./server-core`, so exporting it from here put
+ * that module's `x-api-key` fetch into the browser bundle (confirmed in a real
+ * site's build, in `.next/static/chunks/`). It also could never have
+ * worked as a client component: async components are server-only.
+ *
+ * The type stays — `export type` is erased at build time and reaches no runtime
+ * module, so it keeps `import type { ClusterLandingPageProps }` working for
+ * existing consumers.
+ */
+export type { ClusterLandingPageProps } from './ClusterLandingPage';
+export * from './types';
+export { articleCategorySlug, createPublicationRoutes, resolveArticleUrl, resolvePublicationUrl } from './routes';
+export type { ArticleRoutePost, PublicationRoutingOptions } from './routes';
+export { resolveArticleArtwork } from './artwork';
+export { addExternalLinkTargets, linkClassificationHost, normalizeSiteHost, resolvePublicationSiteUrl, } from './processArticleHtml';

package/dist/press-kit/articles/news-sitemap.d.ts

@@ -0,0 +1,40 @@
+import type { Article } from './types';
+import { type PublicationRoutingOptions, type ArticleRoutePost } from './routes';
+/** Google only reads articles from the last two days in a News sitemap. */
+export declare const NEWS_SITEMAP_WINDOW_MS: number;
+/** Google's cap per News sitemap. */
+export declare const NEWS_SITEMAP_MAX_URLS = 1000;
+/**
+ * Items a feed carries by default. Feeds hold each post's full HTML, so a
+ * 100-post feed ran past half a megabyte, which is where some readers and
+ * aggregators stop fetching. Readers poll often; 20 recent items is the
+ * common convention, and older posts stay in the sitemap.
+ */
+export declare const FEED_DEFAULT_ITEMS = 20;
+export interface NewsSitemapPost extends ArticleRoutePost {
+    title: string;
+    published_at?: string | null;
+    representative_image?: Article['representative_image'];
+    editorial_image?: string;
+    featured_image?: string;
+}
+export interface NewsSitemapOptions extends PublicationRoutingOptions {
+    siteUrl: string;
+    /** The publication name, exactly as it appears on the articles (e.g. "The Journal by Example Co."). */
+    publicationName: string;
+    /** ISO 639 language code. Defaults to "en". */
+    language?: string;
+}
+export declare function escapeXml(text: string): string;
+/**
+ * Wrap HTML in CDATA. A literal `]]>` inside the post would close the section
+ * early and break the whole feed, so it's split across two sections.
+ */
+export declare function cdata(html: string): string;
+/** The posts a News sitemap may list: published in the window, newest first. */
+export declare function recentNewsPosts<T extends NewsSitemapPost>(posts: T[], now?: Date): T[];
+/**
+ * Build a Google News sitemap. With no post in the window it's a valid, empty
+ * urlset, which Google accepts; it fills again on the next publish.
+ */
+export declare function buildNewsSitemapXml(posts: NewsSitemapPost[], options: NewsSitemapOptions, now?: Date): string;

package/dist/press-kit/articles/processArticleHtml.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Post-process Sonor/article HTML for safe, consistent link behavior.
+ * Server-safe string transforms only (no DOM).
+ */
+/**
+ * The host `addExternalLinkTargets` compares links against to decide whether a
+ * link is internal (same tab) or external (`target="_blank"`). Lowercased,
+ * leading `www.` stripped, so `www.example.com` and `example.com` count as the
+ * same site; returns '' for anything unparseable.
+ *
+ * NOT the multi-site host normalizer. That is `normalizeSiteHost` in
+ * `sites/normalize`, which keeps `www.` because `www.example.com` and
+ * `example.com` can be different sub-sites of one Sonor project. This used to
+ * share that name, so the two were easy to swap by accident.
+ */
+export declare function linkClassificationHost(siteUrl: string): string;
+/**
+ * @deprecated Renamed to {@link linkClassificationHost} (same behavior: strips
+ * `www.`). It shared a name with the multi-site `normalizeSiteHost` from
+ * `sites/normalize`, which keeps `www.`. Kept so existing imports from
+ * `@sonordev/press-kit/articles` still work.
+ */
+export declare const normalizeSiteHost: typeof linkClassificationHost;
+/**
+ * Resolve canonical site URL for link classification.
+ * Pass `explicit` from props when env vars are not set (e.g. non-Vercel hosts).
+ */
+export declare function resolvePublicationSiteUrl(explicit?: string): string;
+/**
+ * Add `target="_blank"` and `rel="noopener noreferrer"` to external http(s) links.
+ * Same registrable host (with or without `www`) is treated as internal.
+ * Skips anchors that already set `target`.
+ */
+export declare function addExternalLinkTargets(html: string, siteUrl: string): string;

package/dist/press-kit/articles/public-reads.d.ts

@@ -0,0 +1,42 @@
+import type { ArticleCategory, Article } from './types';
+export interface ArticleReadConfig {
+    apiUrl: string;
+    apiKey: string;
+    /** Sub-site host override. Omit to resolve from NEXT_PUBLIC_SITE_URL. */
+    site?: string;
+}
+/** A failed upstream read must never masquerade as a missing article. */
+export declare class ArticleUnavailableError extends Error {
+    readonly status?: number | undefined;
+    readonly code = "ARTICLE_UNAVAILABLE";
+    constructor(status?: number | undefined);
+}
+export type ArticleReadResult<T> = {
+    state: 'ready';
+    value: T;
+} | {
+    state: 'not_found';
+} | {
+    state: 'unavailable';
+    status?: number;
+};
+export declare function readArticleBySlug({ apiUrl, apiKey, site }: ArticleReadConfig, slug: string): Promise<ArticleReadResult<Article>>;
+/** Returns null only on a confirmed 404; outages propagate to the route error boundary. */
+export declare function fetchArticleBySlug(config: ArticleReadConfig, slug: string): Promise<Article | null>;
+/** GET /public/articles/categories — [] on any failure. */
+export declare function fetchArticleCategories({ apiUrl, apiKey, site }: ArticleReadConfig): Promise<ArticleCategory[]>;
+/**
+ * POST /public/articles/related — [] on any failure.
+ *
+ * `/public/articles/*`, not `/api/public/articles/*`: public-article.controller is one of
+ * only two public controllers whose @Controller() omits the `api/` segment.
+ * The body is snake_case `current_post_id` (the controller looks the post up
+ * by id — there is no slug path), and `site` rides in the body because this is
+ * the one article read that isn't a GET.
+ *
+ * `revalidate` is optional so <RelatedPosts>, which never set a fetch cache
+ * lifetime, keeps rendering exactly as it did.
+ */
+export declare function fetchRelatedArticles({ apiUrl, apiKey, site }: ArticleReadConfig, currentPostId: string, limit: number, cache?: {
+    revalidate?: number;
+}): Promise<Article[]>;

package/dist/press-kit/articles/publication-definition.d.ts

@@ -0,0 +1,41 @@
+/** One portable, tenant-authored launch definition. Contains no credential or content. */
+export interface PublicationDefinition {
+    version: 1;
+    name: string;
+    description: string;
+    siteUrl: string;
+    basePath: string;
+    style: 'newsroom' | 'journal' | 'briefing';
+    sections: Array<{
+        slug: string;
+        title: string;
+    }>;
+    newsletterFormId: string;
+    brand: {
+        primary: string;
+    };
+}
+export declare const PUBLICATION_STARTERS: {
+    readonly newsroom: {
+        readonly label: 'Newsroom';
+        readonly description: 'A strong masthead and a visual grid for frequent reporting.';
+        readonly columns: 3;
+        readonly maxWidth: 1280;
+        readonly serif: false;
+    };
+    readonly journal: {
+        readonly label: 'Journal';
+        readonly description: 'A quieter serif masthead and roomy stories for expert essays.';
+        readonly columns: 2;
+        readonly maxWidth: 1040;
+        readonly serif: true;
+    };
+    readonly briefing: {
+        readonly label: 'Briefing';
+        readonly description: 'A compact single-column reading list for useful updates.';
+        readonly columns: 1;
+        readonly maxWidth: 820;
+        readonly serif: false;
+    };
+};
+export declare function definePublication(input: unknown): PublicationDefinition;

package/dist/press-kit/articles/publication-reads.d.ts

@@ -0,0 +1,54 @@
+import 'server-only';
+import type { Article } from './types';
+import type { ArticleReadResult } from './public-reads';
+export interface PublicationIssue {
+    id: string;
+    title: string;
+    subject: string;
+    sentAt: string;
+    window?: {
+        start?: string;
+        end?: string;
+    };
+    articles: Array<{
+        id: string;
+        title: string;
+        url: string;
+    }>;
+    /** Immutable, public-safe sent snapshot; no recipient tokens or private fields. */
+    html?: string;
+    text?: string;
+}
+export interface PublicationIssueList {
+    issues: PublicationIssue[];
+    nextCursor?: string;
+}
+export declare function getPublicationIssues(options?: {
+    site?: string;
+    limit?: number;
+    cursor?: string;
+}): Promise<ArticleReadResult<PublicationIssueList>>;
+export declare function getPublicationIssue(id: string, options?: {
+    site?: string;
+}): Promise<ArticleReadResult<PublicationIssue>>;
+export interface ArticlePreview {
+    post: Article;
+    revision: string;
+    expiresAt: string;
+    site: string;
+}
+export declare const PUBLICATION_PREVIEW_COOKIE = "_sk_press_preview";
+export declare const PUBLICATION_PREVIEW_HEADERS: {
+    'Cache-Control': string;
+    'X-Robots-Tag': string;
+    'Referrer-Policy': string;
+};
+/** Server-to-server exchange. Never render or log the token; every read rechecks its exact revision. */
+export declare function getArticlePreview(token: string, options: {
+    site: string;
+}): Promise<ArticleReadResult<ArticlePreview>>;
+/** CMS entry: validate once, hide token in a scoped HttpOnly cookie, redirect only to configured local preview. */
+export declare function createPublicationPreviewHandler(options: {
+    siteUrl: string;
+    previewPath: string;
+}): (request: Request) => Promise<Response>;

package/dist/press-kit/articles/reading-time.d.ts

@@ -0,0 +1,9 @@
+import type { Article } from './types';
+/**
+ * Single source of truth for reading-time display.
+ *
+ * The DB/API column is `reading_time` (blog_posts) — `reading_time_minutes`
+ * never existed server-side and exists on the type only for callers that
+ * pre-map their own data. Every "X min read" chip resolves through here.
+ */
+export declare function readingTimeMinutes(post: Pick<Article, 'reading_time' | 'reading_time_minutes'>): number | null;

package/dist/press-kit/articles/routes.d.ts

@@ -0,0 +1,52 @@
+/** Shared, environment-free publication routes for server helpers and article UI. */
+export interface ArticleRoutePost {
+    slug: string;
+    category?: string | {
+        slug?: string;
+        name?: string;
+    } | null;
+    canonical_url?: string | null;
+}
+/**
+ * Where a publication lives when a site doesn't say. A site whose articles
+ * already live at another path (/article, /insights, /theforge) passes basePath;
+ * changing a live URL is an SEO decision, never a default's.
+ */
+export declare const DEFAULT_PUBLICATION_PATH = "/articles";
+export interface PublicationRoutingOptions {
+    /** Publication root, e.g. /theforge or /news. Defaults to DEFAULT_PUBLICATION_PATH (/articles). */
+    basePath?: string;
+    /** Use /publication/category/post instead of /publication/post. */
+    includeCategoryInPath?: boolean;
+    /** Fallback category for partial cluster records. */
+    category?: string;
+    /** A custom local article path. Receives the post's slug and category. */
+    postPath?: (post: ArticleRoutePost) => string;
+    /** A custom category destination, for example /theforge?category=guides. */
+    categoryPath?: (slug: string) => string;
+    /**
+     * Whether this site serves author pages. `true` means they live at the
+     * default `<publication>/author/<slug>`; a function gives a custom path, for
+     * example ``(slug) => `/author/${slug}` `` when author pages sit at the site
+     * root. Article JSON-LD links bylines to author pages ONLY when this is set
+     * (or the author row has `author_page_url`), because most sites have none
+     * and a byline URL that 404s is worse than no URL.
+     */
+    authorPages?: boolean | ((slug: string) => string);
+}
+export declare function articleCategorySlug(category: ArticleRoutePost['category']): string;
+/** Single source of truth for publication paths. Custom routes never change OG artwork. */
+export declare function createPublicationRoutes(options?: PublicationRoutingOptions): {
+    index: string;
+    post(post: ArticleRoutePost): string;
+    category(slug: string): string;
+    cluster: (slug: string) => string;
+    author: (slug: string) => string;
+    rss: string;
+    atom: string;
+};
+export declare function resolvePublicationUrl(path: string, siteUrl?: string): string;
+/** Metadata, feeds, sitemaps and generated schemas agree on a supplied canonical. */
+export declare function resolveArticleUrl(post: ArticleRoutePost, options?: PublicationRoutingOptions & {
+    siteUrl?: string;
+}): string;