@fullstackdatasolutions/articles 0.7.1 → 0.8.0

package/dist/server.d.cts

@@ -37,6 +37,7 @@ interface Article {
     canonicalUrl?: string;
     articleType?: string;
     series?: string;
+    aiCrawl?: boolean;
 }
 interface CategoryInfo {
     name: string;
@@ -45,19 +46,6 @@ interface CategoryInfo {
     featuredImage: string;
 }
 
-declare function sanitizeImagePath(rawPath: string, articleSlug: string): string | null;
-declare function getAvailableArticleSlugs(): string[];
-declare const getArticleMetadata: (slug: string) => Promise<Article | null>;
-declare const getAllArticles: () => Promise<Article[]>;
-declare function getAdjacentArticles(currentSlug: string): Promise<{
-    previous: Article | null;
-    next: Article | null;
-}>;
-declare function searchArticles(query: string): Promise<Article[]>;
-declare function categoryToSlug(category: string): string;
-declare function getAllCategories(): Promise<CategoryInfo[]>;
-declare function getArticlesByCategory(categorySlug: string): Promise<Article[]>;
-
 /** Keys for each renderable section of the articles listing page. */
 type ArticlesSection = 'hero' | 'search' | 'featured' | 'latest' | 'categories' | 'newsletter';
 /**
@@ -149,8 +137,28 @@ interface ArticlesConfig {
     showToc?: boolean;
     /** Set to false to hide the "Back to Articles" navigation link on article detail pages. Default: true. */
     showBackToArticles?: boolean;
+    /** Set to false to hide author names from UI and metadata. Default: true. */
+    showAuthor?: boolean;
 }
 
+declare function sanitizeImagePath(rawPath: string, articleSlug: string): string | null;
+declare function getAvailableArticleSlugs(): string[];
+declare const getArticleMetadata: (slug: string) => Promise<Article | null>;
+declare const getAllArticles: () => Promise<Article[]>;
+declare function getAdjacentArticles(currentSlug: string): Promise<{
+    previous: Article | null;
+    next: Article | null;
+}>;
+declare function getArticleMarkdown(slug: string): Promise<string | null>;
+declare function getArticleMarkdownResponse(slug: string, config: ArticlesConfig): Promise<Response>;
+declare function getArticleMarkdownUrl(article: Pick<Article, 'slug' | 'aiCrawl'>, config?: Pick<ArticlesConfig, 'siteUrl'>): string | undefined;
+declare function getArticleAiHeaders(article: Pick<Article, 'slug' | 'aiCrawl'>, config?: Pick<ArticlesConfig, 'siteUrl'>): Record<string, string>;
+declare function getAiRobotsTxtRules(): Promise<string>;
+declare function searchArticles(query: string, config?: ArticlesConfig): Promise<Article[]>;
+declare function categoryToSlug(category: string): string;
+declare function getAllCategories(): Promise<CategoryInfo[]>;
+declare function getArticlesByCategory(categorySlug: string): Promise<Article[]>;
+
 declare function generateArticleStaticParams(): {
     slug: string;
 }[];
@@ -165,6 +173,17 @@ declare function getArticleSitemapEntries(baseUrlOrConfig: string | ArticlesConf
 declare function markdownToHtml(markdown: string, articleSlug?: string): Promise<string>;
 declare function extractToc(markdown: string): Promise<TocItem[]>;
 
+type ArticlesErrorCode = 'article-directory-read-failed' | 'article-load-failed' | 'article-markdown-load-failed' | 'markdown-conversion-failed' | 'unsafe-image-path';
+type ArticlesErrorContext = Readonly<Record<string, string | number | boolean | undefined>>;
+type ArticlesErrorReport = Readonly<{
+    code: ArticlesErrorCode;
+    message: string;
+    error?: unknown;
+    context?: ArticlesErrorContext;
+}>;
+type ArticlesErrorHandler = (report: ArticlesErrorReport) => void;
+declare function setArticlesErrorHandler(handler?: ArticlesErrorHandler): void;
+
 type ArticleContentProps = Readonly<{
     article: Article;
     className?: string;
@@ -177,4 +196,4 @@ type ArticleTOCProps = Readonly<{
 }>;
 declare function ArticleTOC({ toc, className }: ArticleTOCProps): react_jsx_runtime.JSX.Element | null;
 
-export { type Article, ArticleContent, ArticleTOC, type ArticlesConfig, type CategoryInfo, type TocItem, categoryToSlug, extractToc, generateArticleMetadata, generateArticleStaticParams, generateArticlesIndexMetadata, generateCategoryMetadata, generateCategoryStaticParams, getAdjacentArticles, getAllArticles, getAllCategories, getArticleMetadata, getArticleSitemapEntries, getArticlesByCategory, getAvailableArticleSlugs, markdownToHtml, sanitizeImagePath, searchArticles };
+export { type Article, ArticleContent, ArticleTOC, type ArticlesConfig, type ArticlesErrorCode, type ArticlesErrorContext, type ArticlesErrorHandler, type ArticlesErrorReport, type CategoryInfo, type TocItem, categoryToSlug, extractToc, generateArticleMetadata, generateArticleStaticParams, generateArticlesIndexMetadata, generateCategoryMetadata, generateCategoryStaticParams, getAdjacentArticles, getAiRobotsTxtRules, getAllArticles, getAllCategories, getArticleAiHeaders, getArticleMarkdown, getArticleMarkdownResponse, getArticleMarkdownUrl, getArticleMetadata, getArticleSitemapEntries, getArticlesByCategory, getAvailableArticleSlugs, markdownToHtml, sanitizeImagePath, searchArticles, setArticlesErrorHandler };

package/dist/server.d.ts

@@ -37,6 +37,7 @@ interface Article {
     canonicalUrl?: string;
     articleType?: string;
     series?: string;
+    aiCrawl?: boolean;
 }
 interface CategoryInfo {
     name: string;
@@ -45,19 +46,6 @@ interface CategoryInfo {
     featuredImage: string;
 }
 
-declare function sanitizeImagePath(rawPath: string, articleSlug: string): string | null;
-declare function getAvailableArticleSlugs(): string[];
-declare const getArticleMetadata: (slug: string) => Promise<Article | null>;
-declare const getAllArticles: () => Promise<Article[]>;
-declare function getAdjacentArticles(currentSlug: string): Promise<{
-    previous: Article | null;
-    next: Article | null;
-}>;
-declare function searchArticles(query: string): Promise<Article[]>;
-declare function categoryToSlug(category: string): string;
-declare function getAllCategories(): Promise<CategoryInfo[]>;
-declare function getArticlesByCategory(categorySlug: string): Promise<Article[]>;
-
 /** Keys for each renderable section of the articles listing page. */
 type ArticlesSection = 'hero' | 'search' | 'featured' | 'latest' | 'categories' | 'newsletter';
 /**
@@ -149,8 +137,28 @@ interface ArticlesConfig {
     showToc?: boolean;
     /** Set to false to hide the "Back to Articles" navigation link on article detail pages. Default: true. */
     showBackToArticles?: boolean;
+    /** Set to false to hide author names from UI and metadata. Default: true. */
+    showAuthor?: boolean;
 }
 
+declare function sanitizeImagePath(rawPath: string, articleSlug: string): string | null;
+declare function getAvailableArticleSlugs(): string[];
+declare const getArticleMetadata: (slug: string) => Promise<Article | null>;
+declare const getAllArticles: () => Promise<Article[]>;
+declare function getAdjacentArticles(currentSlug: string): Promise<{
+    previous: Article | null;
+    next: Article | null;
+}>;
+declare function getArticleMarkdown(slug: string): Promise<string | null>;
+declare function getArticleMarkdownResponse(slug: string, config: ArticlesConfig): Promise<Response>;
+declare function getArticleMarkdownUrl(article: Pick<Article, 'slug' | 'aiCrawl'>, config?: Pick<ArticlesConfig, 'siteUrl'>): string | undefined;
+declare function getArticleAiHeaders(article: Pick<Article, 'slug' | 'aiCrawl'>, config?: Pick<ArticlesConfig, 'siteUrl'>): Record<string, string>;
+declare function getAiRobotsTxtRules(): Promise<string>;
+declare function searchArticles(query: string, config?: ArticlesConfig): Promise<Article[]>;
+declare function categoryToSlug(category: string): string;
+declare function getAllCategories(): Promise<CategoryInfo[]>;
+declare function getArticlesByCategory(categorySlug: string): Promise<Article[]>;
+
 declare function generateArticleStaticParams(): {
     slug: string;
 }[];
@@ -165,6 +173,17 @@ declare function getArticleSitemapEntries(baseUrlOrConfig: string | ArticlesConf
 declare function markdownToHtml(markdown: string, articleSlug?: string): Promise<string>;
 declare function extractToc(markdown: string): Promise<TocItem[]>;
 
+type ArticlesErrorCode = 'article-directory-read-failed' | 'article-load-failed' | 'article-markdown-load-failed' | 'markdown-conversion-failed' | 'unsafe-image-path';
+type ArticlesErrorContext = Readonly<Record<string, string | number | boolean | undefined>>;
+type ArticlesErrorReport = Readonly<{
+    code: ArticlesErrorCode;
+    message: string;
+    error?: unknown;
+    context?: ArticlesErrorContext;
+}>;
+type ArticlesErrorHandler = (report: ArticlesErrorReport) => void;
+declare function setArticlesErrorHandler(handler?: ArticlesErrorHandler): void;
+
 type ArticleContentProps = Readonly<{
     article: Article;
     className?: string;
@@ -177,4 +196,4 @@ type ArticleTOCProps = Readonly<{
 }>;
 declare function ArticleTOC({ toc, className }: ArticleTOCProps): react_jsx_runtime.JSX.Element | null;
 
-export { type Article, ArticleContent, ArticleTOC, type ArticlesConfig, type CategoryInfo, type TocItem, categoryToSlug, extractToc, generateArticleMetadata, generateArticleStaticParams, generateArticlesIndexMetadata, generateCategoryMetadata, generateCategoryStaticParams, getAdjacentArticles, getAllArticles, getAllCategories, getArticleMetadata, getArticleSitemapEntries, getArticlesByCategory, getAvailableArticleSlugs, markdownToHtml, sanitizeImagePath, searchArticles };
+export { type Article, ArticleContent, ArticleTOC, type ArticlesConfig, type ArticlesErrorCode, type ArticlesErrorContext, type ArticlesErrorHandler, type ArticlesErrorReport, type CategoryInfo, type TocItem, categoryToSlug, extractToc, generateArticleMetadata, generateArticleStaticParams, generateArticlesIndexMetadata, generateCategoryMetadata, generateCategoryStaticParams, getAdjacentArticles, getAiRobotsTxtRules, getAllArticles, getAllCategories, getArticleAiHeaders, getArticleMarkdown, getArticleMarkdownResponse, getArticleMarkdownUrl, getArticleMetadata, getArticleSitemapEntries, getArticlesByCategory, getAvailableArticleSlugs, markdownToHtml, sanitizeImagePath, searchArticles, setArticlesErrorHandler };

package/dist/server.js

@@ -68,6 +68,23 @@ import remarkGithubBlockquoteAlert from "remark-github-blockquote-alert";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { visit } from "unist-util-visit";
+
+// src/errorReporting.ts
+function defaultArticlesErrorHandler(report) {
+  if (process.env.NODE_ENV === "production") return;
+  const context = report.context ? ` ${JSON.stringify(report.context)}` : "";
+  const detail = report.error instanceof Error ? `: ${report.error.message}` : "";
+  console.warn(`[articles:${report.code}] ${report.message}${context}${detail}`);
+}
+var articlesErrorHandler = defaultArticlesErrorHandler;
+function setArticlesErrorHandler(handler) {
+  articlesErrorHandler = handler != null ? handler : defaultArticlesErrorHandler;
+}
+function reportArticlesError(report) {
+  articlesErrorHandler(report);
+}
+
+// src/markdown.ts
 function sanitizeImagePath(rawPath, articleSlug) {
   if (!rawPath || typeof rawPath !== "string") {
     return null;
@@ -77,17 +94,29 @@ function sanitizeImagePath(rawPath, articleSlug) {
     return cleanPath;
   }
   if (cleanPath.includes("..") || cleanPath.includes("\\") || cleanPath.startsWith("/")) {
-    console.warn(`Potentially unsafe image path detected: ${cleanPath}`);
+    reportArticlesError({
+      code: "unsafe-image-path",
+      message: "Rejected unsafe markdown image path.",
+      context: { articleSlug, path: cleanPath }
+    });
     return null;
   }
   if (!/^[a-zA-Z0-9._/-]+$/.test(cleanPath)) {
-    console.warn(`Invalid characters in image path: ${cleanPath}`);
+    reportArticlesError({
+      code: "unsafe-image-path",
+      message: "Rejected markdown image path with invalid characters.",
+      context: { articleSlug, path: cleanPath }
+    });
     return null;
   }
   if (cleanPath.includes("/")) {
     const normalizedPath = cleanPath.replaceAll("\\", "/");
     if (normalizedPath.startsWith("..") || normalizedPath.includes("../")) {
-      console.warn(`Path traversal attempt detected: ${cleanPath}`);
+      reportArticlesError({
+        code: "unsafe-image-path",
+        message: "Rejected markdown image path traversal attempt.",
+        context: { articleSlug, path: cleanPath }
+      });
       return null;
     }
     return `/articles/${articleSlug}/${normalizedPath}`;
@@ -262,7 +291,11 @@ var rehypeProcessImages = (options = {}) => {
           if (sanitizedSrc) {
             node.properties.src = sanitizedSrc;
           } else {
-            console.warn(`Using placeholder for unsafe image path: ${src}`);
+            reportArticlesError({
+              code: "unsafe-image-path",
+              message: "Using placeholder for unsafe markdown image path.",
+              context: { articleSlug: options.articleSlug, path: src }
+            });
             node.properties.src = "/placeholder-logo.png";
           }
         }
@@ -286,7 +319,12 @@ function markdownToHtml(markdown, articleSlug) {
       const result = yield processor.use(rehypeStringify).process(markdown);
       return result.toString();
     } catch (error) {
-      console.error("Markdown conversion error:", error);
+      reportArticlesError({
+        code: "markdown-conversion-failed",
+        message: "Unable to convert markdown to HTML.",
+        error,
+        context: { articleSlug }
+      });
       return markdown;
     }
   });
@@ -318,7 +356,11 @@ function extractToc(markdown) {
 }
 
 // src/server-articles.ts
-var articlesDirectory = path.join(process.cwd(), "public/articles");
+var articlesDirectory = path.join(
+  /* turbopackIgnore: true */
+  process.cwd(),
+  "public/articles"
+);
 function getReadingTime(content) {
   return readingTime(content).text;
 }
@@ -345,17 +387,29 @@ function sanitizeImagePath2(rawPath, articleSlug) {
   const cleanPath = rawPath.replaceAll(/[\x00-\x1f\x7f-\x9f]/g, "");
   if (cleanPath.startsWith("http://") || cleanPath.startsWith("https://")) return cleanPath;
   if (cleanPath.includes("..") || cleanPath.includes("\\") || cleanPath.startsWith("/")) {
-    console.warn(`Potentially unsafe image path detected: ${cleanPath}`);
+    reportArticlesError({
+      code: "unsafe-image-path",
+      message: "Rejected unsafe article image path.",
+      context: { articleSlug, path: cleanPath }
+    });
     return null;
   }
   if (!/^[a-zA-Z0-9._/-]+$/.test(cleanPath)) {
-    console.warn(`Invalid characters in image path: ${cleanPath}`);
+    reportArticlesError({
+      code: "unsafe-image-path",
+      message: "Rejected article image path with invalid characters.",
+      context: { articleSlug, path: cleanPath }
+    });
     return null;
   }
   if (cleanPath.includes("/")) {
     const normalizedPath = path.normalize(cleanPath);
     if (normalizedPath.startsWith("..") || normalizedPath.includes("../")) {
-      console.warn(`Path traversal attempt detected: ${cleanPath}`);
+      reportArticlesError({
+        code: "unsafe-image-path",
+        message: "Rejected article image path traversal attempt.",
+        context: { articleSlug, path: cleanPath }
+      });
       return null;
     }
     return `/articles/${articleSlug}/${cleanPath}`;
@@ -374,7 +428,12 @@ function getAvailableArticleSlugs() {
     if (!fs.existsSync(articlesDirectory)) return [];
     return walkArticleDir(articlesDirectory, "");
   } catch (error) {
-    console.error("Error reading articles directory:", error);
+    reportArticlesError({
+      code: "article-directory-read-failed",
+      message: "Unable to read articles directory.",
+      error,
+      context: { directory: articlesDirectory }
+    });
     return [];
   }
 }
@@ -451,10 +510,16 @@ function getArticleSummary(slug) {
         howTo: parseHowToSteps(data.howTo),
         canonicalUrl: typeof data.canonicalUrl === "string" ? data.canonicalUrl : void 0,
         articleType: typeof data.articleType === "string" ? data.articleType : void 0,
-        series: typeof data.series === "string" ? data.series : void 0
+        series: typeof data.series === "string" ? data.series : void 0,
+        aiCrawl: data.aiCrawl === true
       };
     } catch (error) {
-      console.error(`Error loading article ${slug}:`, error);
+      reportArticlesError({
+        code: "article-load-failed",
+        message: "Unable to load article summary.",
+        error,
+        context: { slug }
+      });
       return null;
     }
   });
@@ -477,7 +542,12 @@ var getArticleMetadata = cache((slug) => __async(void 0, null, function* () {
     }
     return __spreadProps(__spreadValues({}, summary), { content: markdownContent, htmlContent, mdxSource, toc });
   } catch (error) {
-    console.error(`Error loading article ${slug}:`, error);
+    reportArticlesError({
+      code: "article-load-failed",
+      message: "Unable to load article metadata.",
+      error,
+      context: { slug }
+    });
     return null;
   }
 }));
@@ -502,16 +572,86 @@ function getAdjacentArticles(currentSlug) {
     return { previous, next };
   });
 }
-function searchArticles(query) {
+function getArticleMarkdown(slug) {
+  return __async(this, null, function* () {
+    try {
+      const summary = yield getArticleSummary(slug);
+      if (!(summary == null ? void 0 : summary.aiCrawl)) return null;
+      const found = findArticleFile(slug);
+      if (!found) return null;
+      const fileContent = fs.readFileSync(found.filePath, "utf8");
+      const { content: markdownContent } = matter(fileContent);
+      return markdownContent;
+    } catch (error) {
+      reportArticlesError({
+        code: "article-markdown-load-failed",
+        message: "Unable to load article markdown.",
+        error,
+        context: { slug }
+      });
+      return null;
+    }
+  });
+}
+function getArticleMarkdownResponse(slug, config) {
+  return __async(this, null, function* () {
+    const markdown = yield getArticleMarkdown(slug);
+    if (markdown === null) return new Response("Not Found", { status: 404 });
+    const article = yield getArticleMetadata(slug);
+    return new Response(markdown, {
+      headers: __spreadValues({
+        "Content-Type": "text/markdown; charset=utf-8",
+        "Cache-Control": "public, max-age=3600, s-maxage=3600"
+      }, article ? getArticleAiHeaders(article, config) : {})
+    });
+  });
+}
+function getArticleMarkdownUrl(article, config) {
+  if (article.aiCrawl !== true) return void 0;
+  const pathname = `/articles/${article.slug}.md`;
+  if (!config) return pathname;
+  return `${config.siteUrl.replace(/\/$/, "")}${pathname}`;
+}
+function getArticleAiHeaders(article, config) {
+  const markdownUrl = getArticleMarkdownUrl(article, config);
+  if (markdownUrl) {
+    return {
+      Link: `<${markdownUrl}>; rel="alternate"; type="text/markdown"`
+    };
+  }
+  return {
+    "X-Robots-Tag": "noai, noimageai"
+  };
+}
+function getAiRobotsTxtRules() {
+  return __async(this, null, function* () {
+    const articles = yield getAllArticles();
+    const blockedArticles = articles.filter((article) => article.aiCrawl !== true);
+    if (blockedArticles.length === 0) return "";
+    const aiCrawlers = [
+      "GPTBot",
+      "ChatGPT-User",
+      "CCBot",
+      "ClaudeBot",
+      "Claude-User",
+      "PerplexityBot",
+      "Google-Extended"
+    ];
+    const disallowRules = blockedArticles.map((article) => `Disallow: /articles/${article.slug}`).join("\n");
+    return aiCrawlers.map((crawler) => [`User-agent: ${crawler}`, disallowRules].join("\n")).join("\n\n");
+  });
+}
+function searchArticles(query, config) {
   return __async(this, null, function* () {
     if (!(query == null ? void 0 : query.trim())) return getAllArticles();
     const articles = yield getAllArticles();
     const searchTerm = query.toLowerCase().trim();
+    const includeAuthor = (config == null ? void 0 : config.showAuthor) !== false;
     return articles.filter((article) => {
       var _a;
       const matchesTitle = article.title.toLowerCase().includes(searchTerm);
       const matchesExcerpt = article.excerpt.toLowerCase().includes(searchTerm);
-      const matchesAuthor = article.author.toLowerCase().includes(searchTerm);
+      const matchesAuthor = includeAuthor && article.author.toLowerCase().includes(searchTerm);
       const matchesCategory = article.categories.some((cat) => cat.toLowerCase().includes(searchTerm));
       const matchesTags = (_a = article.tags) == null ? void 0 : _a.some((tag) => tag.toLowerCase().includes(searchTerm));
       return matchesTitle || matchesExcerpt || matchesAuthor || matchesCategory || Boolean(matchesTags);
@@ -582,11 +722,13 @@ function generateArticleMetadata(slug, config) {
     const canonicalUrl = (_a = article.canonicalUrl) != null ? _a : articleUrl;
     const imageUrl = article.featuredImage ? resolveImageUrl(article.featuredImage, siteUrl) : `${siteUrl}/placeholder-logo.png`;
     const description = (_b = article.excerpt) != null ? _b : `Read ${article.title} on ${config.siteName}.`;
+    const showAuthor = config.showAuthor !== false;
+    const markdownUrl = getArticleMarkdownUrl(article, config);
     return {
       title: `${article.title} | ${config.siteName}`,
       description,
       keywords: [...((_c = article.tags) != null ? _c : []).map((tag) => tag.toLowerCase())].join(", "),
-      openGraph: __spreadProps(__spreadValues(__spreadValues({
+      openGraph: __spreadProps(__spreadValues(__spreadValues(__spreadValues({
         title: article.title,
         description,
         url: articleUrl,
@@ -594,8 +736,7 @@ function generateArticleMetadata(slug, config) {
         images: [{ url: imageUrl, width: 1200, height: 630, alt: article.title }],
         locale: "en_US",
         type: "article"
-      }, article.date && { publishedTime: article.date }), article.lastmod && { modifiedTime: new Date(article.lastmod).toISOString() }), {
-        authors: [article.author],
+      }, article.date && { publishedTime: article.date }), article.lastmod && { modifiedTime: new Date(article.lastmod).toISOString() }), showAuthor && { authors: [article.author] }), {
         tags: (_d = article.tags) != null ? _d : []
       }),
       twitter: {
@@ -604,9 +745,13 @@ function generateArticleMetadata(slug, config) {
         description,
         images: [imageUrl]
       },
-      alternates: {
+      alternates: __spreadValues({
         canonical: canonicalUrl
-      },
+      }, markdownUrl && {
+        types: {
+          "text/markdown": markdownUrl
+        }
+      }),
       robots: {
         index: true,
         follow: true,
@@ -618,9 +763,7 @@ function generateArticleMetadata(slug, config) {
           "max-snippet": -1
         }
       },
-      other: __spreadProps(__spreadValues(__spreadValues({
-        "article:author": article.author
-      }, article.date && {
+      other: __spreadProps(__spreadValues(__spreadValues(__spreadValues({}, showAuthor && { "article:author": article.author }), article.date && {
         "article:published_time": new Date(article.date).toISOString()
       }), article.lastmod && {
         "article:modified_time": new Date(article.lastmod).toISOString()
@@ -830,14 +973,20 @@ export {
   generateCategoryMetadata,
   generateCategoryStaticParams,
   getAdjacentArticles,
+  getAiRobotsTxtRules,
   getAllArticles,
   getAllCategories,
+  getArticleAiHeaders,
+  getArticleMarkdown,
+  getArticleMarkdownResponse,
+  getArticleMarkdownUrl,
   getArticleMetadata,
   getArticleSitemapEntries,
   getArticlesByCategory,
   getAvailableArticleSlugs,
   markdownToHtml,
   sanitizeImagePath2 as sanitizeImagePath,
-  searchArticles
+  searchArticles,
+  setArticlesErrorHandler
 };
 //# sourceMappingURL=server.js.map