@fullstackdatasolutions/articles 1.2.3 → 1.3.1

package/dist/nextjs.d.cts

@@ -1,6 +1,16 @@
 import { NextRequest } from 'next/server';
 import { ComponentType } from 'react';
 
+/**
+ * A real-world thing an article is about, emitted as schema.org `about`.
+ * `sameAs` should point at an authoritative identifier for the entity
+ * (Wikipedia, Wikidata, an official site) - that URL is what lets a consumer
+ * resolve "Pathfinder" the game system rather than guessing from the string.
+ */
+interface EntityReference {
+    name: string;
+    sameAs?: string;
+}
 /**
  * A "start here" curated reader journey that can cross series/categories -
  * a distinct primitive from the label-only `series` field/`seriesSlug`
@@ -67,6 +77,13 @@ interface AuthorProfile {
     promise?: string;
     /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
     originStory?: RichText;
+    /**
+     * Topics this author writes about, emitted as Person `knowsAbout`. Omit to
+     * derive it from the categories of their own published articles - unlike
+     * `credentials`/`proof`, subject matter is verifiable from the corpus
+     * itself, so it does belong in structured data.
+     */
+    knowsAbout?: string[];
     /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
     servesWho?: string[];
     /** Core beliefs/approach statements. */
@@ -79,6 +96,27 @@ interface AuthorProfile {
     credentials?: string[];
     /** Concrete, sourceable proof points. */
     proof?: ProofItem[];
+    /**
+     * The one canonical URL identifying this person across every site they
+     * publish on. Used *only* to derive the Person `@id`, so the same author
+     * resolves to a single entity everywhere instead of one entity per site.
+     *
+     * Deliberately separate from `url`: that field also drives byline link
+     * targets, the author page's Open Graph URL, and its `CollectionPage` URL,
+     * so pointing it at another domain would send readers off-site and hand
+     * this site's author page a canonical belonging to a different one.
+     * `identityUrl` changes nothing a reader sees.
+     *
+     * Set the same value on every site. Falls back to `url`, then to this
+     * site's own author page.
+     */
+    identityUrl?: string;
+    /**
+     * Additional profile URLs identifying this same person elsewhere, merged
+     * into the Person schema's `sameAs` alongside the derived social links.
+     * List the author's pages on the other sites here.
+     */
+    sameAs?: string[];
     /** Primary call-to-action rendered on the author's page. */
     primaryCta?: {
         label: string;
@@ -249,6 +287,54 @@ interface BreadcrumbsConfig {
     /** Optional label overrides for built-in breadcrumb items. */
     labels?: BreadcrumbLabels;
 }
+/** Payload passed to `ArticlesConfig.onAiCrawl`. */
+interface AiCrawlEvent {
+    /** Article slug whose markdown twin was fetched. */
+    slug: string;
+    /** Matched crawler name (e.g. `'GPTBot'`), or `'unknown'` when the agent is not recognized. */
+    crawler: string;
+    /** Raw `User-Agent` header, or an empty string when absent. */
+    userAgent: string;
+}
+/**
+ * The publishing entity behind the site. Drives `OrganizationSchema`,
+ * `WebSiteSchema`, and the `publisher` reference on every article - so all
+ * three point at one `@id` instead of repeating an inline, unlinked
+ * `Organization` stub per page.
+ */
+interface OrganizationConfig {
+    /** schema.org type. Use `'Person'` for a personal brand. Default: `'Organization'`. */
+    type?: 'Organization' | 'Person';
+    /** Entity name. Falls back to `siteName`. */
+    name?: string;
+    /** Entity homepage. Falls back to `siteUrl`. */
+    url?: string;
+    /** Logo URL. Site-relative paths are resolved against `siteUrl`. */
+    logo?: string;
+    /** Entity description. Falls back to `ArticlesConfig.description`. */
+    description?: string;
+    /** Profile URLs that identify the same entity elsewhere (social, Crunchbase, Wikidata). */
+    sameAs?: string[];
+    /**
+     * The umbrella entity this site belongs to, for a network of sites run by
+     * one publisher. Emitted as `parentOrganization` - the link that lets
+     * authority earned by the network attach to each site in it, instead of
+     * each site standing alone.
+     */
+    parentOrganization?: {
+        name: string;
+        url: string;
+    };
+    /**
+     * Search URL template for the `WebSite` `SearchAction`, e.g.
+     * `'/search?q={search_term_string}'`. Omitted by default - the library's
+     * own search is client-side with no crawlable results URL, so declaring one
+     * that does not exist would be a false claim. Only set this if the app
+     * actually serves search results at that URL. Must contain the literal
+     * `{search_term_string}` placeholder.
+     */
+    searchUrlTemplate?: string;
+}
 /** Top-level configuration object. Pass one instance to every library component. */
 interface ArticlesConfig {
     /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
@@ -311,6 +397,94 @@ interface ArticlesConfig {
      * step rather than a build-time failure otherwise.
      */
     paths?: Record<string, PathDefinition>;
+    /**
+     * Template for the `<title>` tag on article, category, series, and author
+     * pages. Supports `{title}` and `{siteName}` placeholders.
+     * Default: `'{title} | {siteName}'`.
+     *
+     * Google truncates a result title around 60 characters, and a site name
+     * suffix spends that budget on every page. Set `'{title}'` to drop it when
+     * your titles are already long and your brand draws little search volume -
+     * the suffix is only earning its characters if people search for the brand.
+     */
+    titleTemplate?: string;
+    /**
+     * BCP 47 language tag for the site's content. Emitted as the Article
+     * schema's `inLanguage` and the RSS channel `<language>`. Default: `'en'`.
+     */
+    language?: string;
+    /**
+     * Set to `false` when articles sit behind a paywall or registration wall.
+     * Default: `true`, emitted as the Article schema's `isAccessibleForFree` -
+     * an explicit "this is readable" signal, since consumers that cannot tell
+     * tend to skip suspected-paywalled sources.
+     */
+    isAccessibleForFree?: boolean;
+    /**
+     * CSS selectors marking the parts of an article suitable for text-to-speech,
+     * emitted as the Article schema's `speakable`. Omitted by default - the
+     * correct selectors depend on the consuming app's own markup, and guessing
+     * them would point at elements that may not exist.
+     */
+    speakableSelectors?: string[];
+    /**
+     * Set to `true` to derive `FAQPage` entries from question-shaped `##`
+     * headings and the paragraph that follows each one. Default: `false` -
+     * turning prose into structured data without the author's intent can
+     * promote a rhetorical heading into a published Q&A pair, so this is
+     * opt-in. Explicit `faq` frontmatter always wins over derived entries.
+     */
+    deriveFaqFromHeadings?: boolean;
+    /**
+     * Shared entity vocabulary, keyed by an app-chosen slug. Article `about`
+     * entries may reference a key here instead of repeating a name/`sameAs`
+     * pair - the point of `about` is that a consumer can resolve one entity
+     * across a corpus, which free-text names spelled three different ways
+     * defeat. `validateArticles` warns on `about` keys with no registry entry.
+     */
+    entities?: Record<string, EntityReference>;
+    /**
+     * Where `lastmod` comes from when frontmatter omits it.
+     * - `'published'` (default): reuse the publish date, as before 1.3.0.
+     * - `'none'`: leave `lastmod` unset, so `dateModified` is omitted rather
+     *   than repeating a stale publish date.
+     * - `'fileMtime'`: read the article file's modification time. Accurate
+     *   locally; on a CI runner that clones fresh, every file's mtime is the
+     *   checkout time, which would report the whole corpus as updated today.
+     *   Only use it where the build preserves mtimes.
+     */
+    lastmodFallback?: 'published' | 'none' | 'fileMtime';
+    /**
+     * Called when an AI crawler fetches an article's markdown twin. The one
+     * choke point where those requests land, so it is the only place a site
+     * can measure whether any of its AI-readable content is being read, and
+     * by which bot. No PII: the payload carries the slug, the matched crawler
+     * name, and the raw user agent string only.
+     */
+    onAiCrawl?: (event: AiCrawlEvent) => void;
+    /**
+     * The publishing entity behind the site. Omit to keep the pre-1.3.0 inline
+     * `{'@type':'Organization', name: siteName}` publisher stub on articles.
+     * Set it to emit `OrganizationSchema`/`WebSiteSchema` in the root layout and
+     * have every article, author, and collection page reference the same `@id`.
+     */
+    organization?: OrganizationConfig;
+    /**
+     * Default `aiCrawl` value for articles whose frontmatter omits the key.
+     * Default: `false` (every article stays opted out unless it sets
+     * `aiCrawl: true`). Set to `true` on a site whose goal is being cited by
+     * answer engines to opt the whole corpus in at once; per-article
+     * `aiCrawl: false` still wins and keeps that article blocked.
+     */
+    aiCrawlDefault?: boolean;
+    /**
+     * Set to `false` to serve article markdown twins as the bare body, with no
+     * attribution header. Default: `true` - the twin is prefixed with the
+     * title, excerpt, canonical source URL, dates, author, and site name so a
+     * model reading `/articles/[slug].md` can attribute it. Only applies when
+     * a config is available (i.e. via `getArticleMarkdownResponse`).
+     */
+    markdownTwinHeader?: boolean;
     /**
      * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
      * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
@@ -321,7 +495,10 @@ interface ArticlesConfig {
 }
 
 /**
- * Returns a Next.js App Router GET handler for serving article markdown.
+ * Returns a Next.js App Router GET handler for serving markdown twins -
+ * articles plus category/author/series listings, dispatched by slug prefix.
+ * The request is passed through so `ArticlesConfig.onAiCrawl` can see the
+ * user agent.
  *
  * Usage in app/api/articles-markdown/[...slug]/route.ts:
  *   import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
@@ -329,7 +506,7 @@ interface ArticlesConfig {
  *   export const { GET } = createArticleMarkdownHandler(siteConfig)
  */
 declare function createArticleMarkdownHandler(config: ArticlesConfig): {
-    GET: (_request: NextRequest, context: {
+    GET: (request: NextRequest, context: {
         params: Promise<Record<string, string | string[]>>;
     }) => Promise<Response>;
 };

package/dist/nextjs.d.ts

@@ -1,6 +1,16 @@
 import { NextRequest } from 'next/server';
 import { ComponentType } from 'react';
 
+/**
+ * A real-world thing an article is about, emitted as schema.org `about`.
+ * `sameAs` should point at an authoritative identifier for the entity
+ * (Wikipedia, Wikidata, an official site) - that URL is what lets a consumer
+ * resolve "Pathfinder" the game system rather than guessing from the string.
+ */
+interface EntityReference {
+    name: string;
+    sameAs?: string;
+}
 /**
  * A "start here" curated reader journey that can cross series/categories -
  * a distinct primitive from the label-only `series` field/`seriesSlug`
@@ -67,6 +77,13 @@ interface AuthorProfile {
     promise?: string;
     /** Structured long-form origin story - see `RichText`/`RichTextSection`. */
     originStory?: RichText;
+    /**
+     * Topics this author writes about, emitted as Person `knowsAbout`. Omit to
+     * derive it from the categories of their own published articles - unlike
+     * `credentials`/`proof`, subject matter is verifiable from the corpus
+     * itself, so it does belong in structured data.
+     */
+    knowsAbout?: string[];
     /** Who this author's content/work is for, e.g. "New game masters", "Streaming DMs". */
     servesWho?: string[];
     /** Core beliefs/approach statements. */
@@ -79,6 +96,27 @@ interface AuthorProfile {
     credentials?: string[];
     /** Concrete, sourceable proof points. */
     proof?: ProofItem[];
+    /**
+     * The one canonical URL identifying this person across every site they
+     * publish on. Used *only* to derive the Person `@id`, so the same author
+     * resolves to a single entity everywhere instead of one entity per site.
+     *
+     * Deliberately separate from `url`: that field also drives byline link
+     * targets, the author page's Open Graph URL, and its `CollectionPage` URL,
+     * so pointing it at another domain would send readers off-site and hand
+     * this site's author page a canonical belonging to a different one.
+     * `identityUrl` changes nothing a reader sees.
+     *
+     * Set the same value on every site. Falls back to `url`, then to this
+     * site's own author page.
+     */
+    identityUrl?: string;
+    /**
+     * Additional profile URLs identifying this same person elsewhere, merged
+     * into the Person schema's `sameAs` alongside the derived social links.
+     * List the author's pages on the other sites here.
+     */
+    sameAs?: string[];
     /** Primary call-to-action rendered on the author's page. */
     primaryCta?: {
         label: string;
@@ -249,6 +287,54 @@ interface BreadcrumbsConfig {
     /** Optional label overrides for built-in breadcrumb items. */
     labels?: BreadcrumbLabels;
 }
+/** Payload passed to `ArticlesConfig.onAiCrawl`. */
+interface AiCrawlEvent {
+    /** Article slug whose markdown twin was fetched. */
+    slug: string;
+    /** Matched crawler name (e.g. `'GPTBot'`), or `'unknown'` when the agent is not recognized. */
+    crawler: string;
+    /** Raw `User-Agent` header, or an empty string when absent. */
+    userAgent: string;
+}
+/**
+ * The publishing entity behind the site. Drives `OrganizationSchema`,
+ * `WebSiteSchema`, and the `publisher` reference on every article - so all
+ * three point at one `@id` instead of repeating an inline, unlinked
+ * `Organization` stub per page.
+ */
+interface OrganizationConfig {
+    /** schema.org type. Use `'Person'` for a personal brand. Default: `'Organization'`. */
+    type?: 'Organization' | 'Person';
+    /** Entity name. Falls back to `siteName`. */
+    name?: string;
+    /** Entity homepage. Falls back to `siteUrl`. */
+    url?: string;
+    /** Logo URL. Site-relative paths are resolved against `siteUrl`. */
+    logo?: string;
+    /** Entity description. Falls back to `ArticlesConfig.description`. */
+    description?: string;
+    /** Profile URLs that identify the same entity elsewhere (social, Crunchbase, Wikidata). */
+    sameAs?: string[];
+    /**
+     * The umbrella entity this site belongs to, for a network of sites run by
+     * one publisher. Emitted as `parentOrganization` - the link that lets
+     * authority earned by the network attach to each site in it, instead of
+     * each site standing alone.
+     */
+    parentOrganization?: {
+        name: string;
+        url: string;
+    };
+    /**
+     * Search URL template for the `WebSite` `SearchAction`, e.g.
+     * `'/search?q={search_term_string}'`. Omitted by default - the library's
+     * own search is client-side with no crawlable results URL, so declaring one
+     * that does not exist would be a false claim. Only set this if the app
+     * actually serves search results at that URL. Must contain the literal
+     * `{search_term_string}` placeholder.
+     */
+    searchUrlTemplate?: string;
+}
 /** Top-level configuration object. Pass one instance to every library component. */
 interface ArticlesConfig {
     /** Canonical base URL of the site, used in metadata and JSON-LD. Example: `'https://yoursite.com'` */
@@ -311,6 +397,94 @@ interface ArticlesConfig {
      * step rather than a build-time failure otherwise.
      */
     paths?: Record<string, PathDefinition>;
+    /**
+     * Template for the `<title>` tag on article, category, series, and author
+     * pages. Supports `{title}` and `{siteName}` placeholders.
+     * Default: `'{title} | {siteName}'`.
+     *
+     * Google truncates a result title around 60 characters, and a site name
+     * suffix spends that budget on every page. Set `'{title}'` to drop it when
+     * your titles are already long and your brand draws little search volume -
+     * the suffix is only earning its characters if people search for the brand.
+     */
+    titleTemplate?: string;
+    /**
+     * BCP 47 language tag for the site's content. Emitted as the Article
+     * schema's `inLanguage` and the RSS channel `<language>`. Default: `'en'`.
+     */
+    language?: string;
+    /**
+     * Set to `false` when articles sit behind a paywall or registration wall.
+     * Default: `true`, emitted as the Article schema's `isAccessibleForFree` -
+     * an explicit "this is readable" signal, since consumers that cannot tell
+     * tend to skip suspected-paywalled sources.
+     */
+    isAccessibleForFree?: boolean;
+    /**
+     * CSS selectors marking the parts of an article suitable for text-to-speech,
+     * emitted as the Article schema's `speakable`. Omitted by default - the
+     * correct selectors depend on the consuming app's own markup, and guessing
+     * them would point at elements that may not exist.
+     */
+    speakableSelectors?: string[];
+    /**
+     * Set to `true` to derive `FAQPage` entries from question-shaped `##`
+     * headings and the paragraph that follows each one. Default: `false` -
+     * turning prose into structured data without the author's intent can
+     * promote a rhetorical heading into a published Q&A pair, so this is
+     * opt-in. Explicit `faq` frontmatter always wins over derived entries.
+     */
+    deriveFaqFromHeadings?: boolean;
+    /**
+     * Shared entity vocabulary, keyed by an app-chosen slug. Article `about`
+     * entries may reference a key here instead of repeating a name/`sameAs`
+     * pair - the point of `about` is that a consumer can resolve one entity
+     * across a corpus, which free-text names spelled three different ways
+     * defeat. `validateArticles` warns on `about` keys with no registry entry.
+     */
+    entities?: Record<string, EntityReference>;
+    /**
+     * Where `lastmod` comes from when frontmatter omits it.
+     * - `'published'` (default): reuse the publish date, as before 1.3.0.
+     * - `'none'`: leave `lastmod` unset, so `dateModified` is omitted rather
+     *   than repeating a stale publish date.
+     * - `'fileMtime'`: read the article file's modification time. Accurate
+     *   locally; on a CI runner that clones fresh, every file's mtime is the
+     *   checkout time, which would report the whole corpus as updated today.
+     *   Only use it where the build preserves mtimes.
+     */
+    lastmodFallback?: 'published' | 'none' | 'fileMtime';
+    /**
+     * Called when an AI crawler fetches an article's markdown twin. The one
+     * choke point where those requests land, so it is the only place a site
+     * can measure whether any of its AI-readable content is being read, and
+     * by which bot. No PII: the payload carries the slug, the matched crawler
+     * name, and the raw user agent string only.
+     */
+    onAiCrawl?: (event: AiCrawlEvent) => void;
+    /**
+     * The publishing entity behind the site. Omit to keep the pre-1.3.0 inline
+     * `{'@type':'Organization', name: siteName}` publisher stub on articles.
+     * Set it to emit `OrganizationSchema`/`WebSiteSchema` in the root layout and
+     * have every article, author, and collection page reference the same `@id`.
+     */
+    organization?: OrganizationConfig;
+    /**
+     * Default `aiCrawl` value for articles whose frontmatter omits the key.
+     * Default: `false` (every article stays opted out unless it sets
+     * `aiCrawl: true`). Set to `true` on a site whose goal is being cited by
+     * answer engines to opt the whole corpus in at once; per-article
+     * `aiCrawl: false` still wins and keeps that article blocked.
+     */
+    aiCrawlDefault?: boolean;
+    /**
+     * Set to `false` to serve article markdown twins as the bare body, with no
+     * attribution header. Default: `true` - the twin is prefixed with the
+     * title, excerpt, canonical source URL, dates, author, and site name so a
+     * model reading `/articles/[slug].md` can attribute it. Only applies when
+     * a config is available (i.e. via `getArticleMarkdownResponse`).
+     */
+    markdownTwinHeader?: boolean;
     /**
      * Vendor-neutral event callback (Phase 27F). Fired by components/hooks at
      * meaningful reader-journey moments (see `ArticleEvent` in `events.ts`).
@@ -321,7 +495,10 @@ interface ArticlesConfig {
 }
 
 /**
- * Returns a Next.js App Router GET handler for serving article markdown.
+ * Returns a Next.js App Router GET handler for serving markdown twins -
+ * articles plus category/author/series listings, dispatched by slug prefix.
+ * The request is passed through so `ArticlesConfig.onAiCrawl` can see the
+ * user agent.
  *
  * Usage in app/api/articles-markdown/[...slug]/route.ts:
  *   import { createArticleMarkdownHandler } from '@fullstackdatasolutions/articles/nextjs'
@@ -329,7 +506,7 @@ interface ArticlesConfig {
  *   export const { GET } = createArticleMarkdownHandler(siteConfig)
  */
 declare function createArticleMarkdownHandler(config: ArticlesConfig): {
-    GET: (_request: NextRequest, context: {
+    GET: (request: NextRequest, context: {
         params: Promise<Record<string, string | string[]>>;
     }) => Promise<Response>;
 };