@cedros/data-react 0.1.0

package/dist/react/fetch.d.ts

@@ -0,0 +1,11 @@
+import type { ServerFetchOptions } from "./types.js";
+/**
+ * Resolves the cedros-data server URL from options or environment.
+ * Throws if no URL is available.
+ */
+export declare function resolveServerUrl(options?: ServerFetchOptions): string;
+/** Internal fetch wrapper for server-side calls to cedros-data. */
+export declare function fetchJson<T>(serverUrl: string, path: string, init?: {
+    method?: string;
+    body?: unknown;
+}): Promise<T>;

package/dist/react/fetch.js

@@ -0,0 +1,32 @@
+/**
+ * Resolves the cedros-data server URL from options or environment.
+ * Throws if no URL is available.
+ */
+export function resolveServerUrl(options) {
+    const url = options?.serverUrl ??
+        (typeof process !== "undefined"
+            ? process.env.CEDROS_DATA_URL ?? process.env.NEXT_PUBLIC_BACKEND_API_URL
+            : undefined);
+    if (!url) {
+        throw new Error("@cedros/data-react: no serverUrl provided and neither CEDROS_DATA_URL nor " +
+            "NEXT_PUBLIC_BACKEND_API_URL environment variable is set");
+    }
+    return url.replace(/\/+$/, "");
+}
+/** Internal fetch wrapper for server-side calls to cedros-data. */
+export async function fetchJson(serverUrl, path, init) {
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    const response = await fetch(`${serverUrl}${path}`, {
+        method: init?.method ?? "GET",
+        headers,
+        body: init?.body !== undefined ? JSON.stringify(init.body) : undefined,
+    });
+    if (!response.ok) {
+        const text = await response.text();
+        throw new Error(`@cedros/data-react: ${init?.method ?? "GET"} ${path} failed ` +
+            `(${response.status}): ${text}`);
+    }
+    return (await response.json());
+}

package/dist/react/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @cedros/data-react — client-safe exports.
+ *
+ * These exports are safe to use in React Client Components and
+ * do not import any server-only modules.
+ */
+export { CmsContent, type CmsContentProps } from "./CmsContent.js";
+export { getOrCreateVisitorId } from "./visitor.js";
+export { sanitizeCmsHtml, renderCmsMarkdown } from "./sanitize.js";
+export type { CmsPageRecord, SiteDataRecord, SanitizeOptions, ContentType, } from "./types.js";

package/dist/react/index.js

@@ -0,0 +1,9 @@
+/**
+ * @cedros/data-react — client-safe exports.
+ *
+ * These exports are safe to use in React Client Components and
+ * do not import any server-only modules.
+ */
+export { CmsContent } from "./CmsContent.js";
+export { getOrCreateVisitorId } from "./visitor.js";
+export { sanitizeCmsHtml, renderCmsMarkdown } from "./sanitize.js";

package/dist/react/metadata.d.ts

@@ -0,0 +1,44 @@
+import type { BuildPageMetadataOptions, CmsPageRecord, ServerFetchOptions } from "./types.js";
+/**
+ * Metadata object compatible with Next.js `generateMetadata` return type.
+ * Kept as a plain object so this module doesn't import `next` as a dependency.
+ */
+export interface PageMetadata {
+    title?: string;
+    description?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        images?: Array<{
+            url: string;
+        }>;
+        url?: string;
+        type?: string;
+    };
+    twitter?: {
+        card?: string;
+        title?: string;
+        description?: string;
+    };
+    alternates?: {
+        canonical?: string;
+    };
+    other?: Record<string, string>;
+}
+/**
+ * Builds a Next.js-compatible Metadata object from a CMS page record.
+ *
+ * @param page  - CMS page record from the entries API
+ * @param options - Optional site data, origin, path, and mode
+ * @returns Metadata object suitable for Next.js `generateMetadata`
+ */
+export declare function buildPageMetadata(page: CmsPageRecord, options?: BuildPageMetadataOptions): PageMetadata;
+/**
+ * Convenience wrapper that fetches a page by slug, then builds metadata.
+ *
+ * Uses the cedros-data entries API to query the "pages" collection by
+ * entry_key (slug), then delegates to `buildPageMetadata`.
+ */
+export declare function generatePageMetadata(slug: string, options?: BuildPageMetadataOptions & ServerFetchOptions & {
+    collection?: string;
+}): Promise<PageMetadata>;

package/dist/react/metadata.js

@@ -0,0 +1,142 @@
+import { fetchJson, resolveServerUrl } from "./fetch.js";
+/**
+ * Builds a Next.js-compatible Metadata object from a CMS page record.
+ *
+ * @param page  - CMS page record from the entries API
+ * @param options - Optional site data, origin, path, and mode
+ * @returns Metadata object suitable for Next.js `generateMetadata`
+ */
+export function buildPageMetadata(page, options) {
+    const p = page.payload;
+    const site = options?.siteData;
+    const origin = options?.origin?.replace(/\/+$/, "") ?? "";
+    const path = options?.path ?? p.route ?? "";
+    const mode = options?.mode ?? "page";
+    const siteName = site?.siteName ?? site?.siteTitle ?? "";
+    const title = p.title ?? siteName ?? undefined;
+    const description = p.description ?? site?.defaultDescription ?? undefined;
+    const ogTitle = p.ogTitle ?? p.title ?? undefined;
+    const ogDescription = p.ogDescription ?? p.description ?? undefined;
+    const ogImages = buildOgImages(p.ogImage, site?.defaultOgImage);
+    const pageUrl = origin ? `${origin}${path}` : undefined;
+    const ogType = mode === "blog" ? "article" : "website";
+    const twitterTitle = p.twitterTitle ?? p.ogTitle ?? p.title ?? undefined;
+    const twitterDescription = p.twitterDescription ?? p.ogDescription ?? p.description ?? undefined;
+    const canonical = resolveCanonical(origin, path, mode, p.slug);
+    const metadata = {
+        title,
+        description,
+        openGraph: {
+            title: ogTitle,
+            description: ogDescription,
+            images: ogImages,
+            url: pageUrl,
+            type: ogType,
+        },
+        twitter: {
+            card: "summary_large_image",
+            title: twitterTitle,
+            description: twitterDescription,
+        },
+    };
+    if (canonical) {
+        metadata.alternates = { canonical };
+    }
+    // For blog posts, add JSON-LD structured data as a serialized string
+    if (mode === "blog") {
+        metadata.other = {
+            "script:ld+json": buildBlogJsonLd(page, origin, path),
+        };
+    }
+    return metadata;
+}
+/**
+ * Convenience wrapper that fetches a page by slug, then builds metadata.
+ *
+ * Uses the cedros-data entries API to query the "pages" collection by
+ * entry_key (slug), then delegates to `buildPageMetadata`.
+ */
+export async function generatePageMetadata(slug, options) {
+    const serverUrl = resolveServerUrl(options);
+    const collection = options?.collection ?? "pages";
+    const entries = await fetchJson(serverUrl, "/entries/query", {
+        method: "POST",
+        body: {
+            collection_name: collection,
+            entry_keys: [slug],
+            limit: 1,
+            offset: 0,
+        },
+    });
+    if (entries.length === 0) {
+        return { title: slug };
+    }
+    let siteData = options?.siteData;
+    if (!siteData) {
+        siteData = await fetchSiteData(serverUrl);
+    }
+    return buildPageMetadata(entries[0], {
+        ...options,
+        siteData,
+        path: options?.path ?? `/${slug}`,
+    });
+}
+async function fetchSiteData(serverUrl) {
+    try {
+        const entries = await fetchJson(serverUrl, "/entries/query", {
+            method: "POST",
+            body: {
+                collection_name: "site_settings",
+                entry_keys: ["global"],
+                limit: 1,
+                offset: 0,
+            },
+        });
+        if (entries.length > 0) {
+            return entries[0].payload;
+        }
+    }
+    catch {
+        // Site settings may not exist; fall through
+    }
+    return undefined;
+}
+function buildOgImages(pageImage, defaultImage) {
+    if (pageImage)
+        return [{ url: pageImage }];
+    if (defaultImage)
+        return [{ url: defaultImage }];
+    return [];
+}
+function resolveCanonical(origin, path, mode, slug) {
+    if (!origin)
+        return undefined;
+    if (mode === "docs" && slug) {
+        return `${origin}/blog/${slug}`;
+    }
+    return `${origin}${path}`;
+}
+function buildBlogJsonLd(page, origin, path) {
+    const p = page.payload;
+    const jsonLd = {
+        "@context": "https://schema.org",
+        "@type": "BlogPosting",
+        headline: p.title,
+        description: p.description,
+        datePublished: p.publishedAt,
+        dateModified: p.updatedAt ?? page.updated_at,
+    };
+    if (origin) {
+        jsonLd.url = `${origin}${path}`;
+    }
+    if (p.author) {
+        jsonLd.author = { "@type": "Person", name: p.author };
+    }
+    if (p.ogImage) {
+        jsonLd.image = p.ogImage;
+    }
+    if (p.wordCount) {
+        jsonLd.wordCount = p.wordCount;
+    }
+    return JSON.stringify(jsonLd);
+}

package/dist/react/sanitize.d.ts

@@ -0,0 +1,17 @@
+import type { SanitizeOptions } from "./types.js";
+/**
+ * Sanitizes CMS HTML by stripping dangerous tags, attributes, and protocols.
+ *
+ * Uses a regex-based approach that processes tags iteratively. This is not a
+ * full HTML parser, but is sufficient for CMS content where the input is
+ * author-controlled (not arbitrary user input from the public internet).
+ */
+export declare function sanitizeCmsHtml(html: string, options?: SanitizeOptions): string;
+/**
+ * Converts a basic markdown string to HTML.
+ *
+ * Handles headings, bold, italic, links, images, code blocks, inline code,
+ * unordered/ordered lists, blockquotes, horizontal rules, and paragraphs.
+ * For rich markdown processing, use a full library like react-markdown.
+ */
+export declare function renderCmsMarkdown(markdown: string): string;

package/dist/react/sanitize.js

@@ -0,0 +1,326 @@
+/** Safe HTML tags for CMS prose content. */
+const DEFAULT_ALLOWED_TAGS = new Set([
+    "a",
+    "abbr",
+    "address",
+    "article",
+    "aside",
+    "b",
+    "bdi",
+    "bdo",
+    "blockquote",
+    "br",
+    "caption",
+    "cite",
+    "code",
+    "col",
+    "colgroup",
+    "dd",
+    "del",
+    "details",
+    "dfn",
+    "div",
+    "dl",
+    "dt",
+    "em",
+    "figcaption",
+    "figure",
+    "footer",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "header",
+    "hr",
+    "i",
+    "img",
+    "ins",
+    "kbd",
+    "li",
+    "main",
+    "mark",
+    "nav",
+    "ol",
+    "p",
+    "picture",
+    "pre",
+    "q",
+    "rp",
+    "rt",
+    "ruby",
+    "s",
+    "samp",
+    "section",
+    "small",
+    "source",
+    "span",
+    "strong",
+    "sub",
+    "summary",
+    "sup",
+    "table",
+    "tbody",
+    "td",
+    "tfoot",
+    "th",
+    "thead",
+    "time",
+    "tr",
+    "u",
+    "ul",
+    "var",
+    "wbr",
+]);
+const DEFAULT_ALLOWED_ATTRIBUTES = {
+    a: new Set(["href", "title", "target", "rel", "id"]),
+    img: new Set(["src", "alt", "title", "width", "height", "loading"]),
+    source: new Set(["src", "srcset", "type", "media"]),
+    td: new Set(["colspan", "rowspan"]),
+    th: new Set(["colspan", "rowspan", "scope"]),
+    ol: new Set(["start", "type"]),
+    time: new Set(["datetime"]),
+    blockquote: new Set(["cite"]),
+    q: new Set(["cite"]),
+    col: new Set(["span"]),
+    colgroup: new Set(["span"]),
+    details: new Set(["open"]),
+    "*": new Set(["class", "id", "lang", "dir"]),
+};
+const DEFAULT_ALLOWED_PROTOCOLS = new Set(["http:", "https:", "mailto:"]);
+const EVENT_HANDLER_PATTERN = /^on/i;
+/**
+ * Sanitizes CMS HTML by stripping dangerous tags, attributes, and protocols.
+ *
+ * Uses a regex-based approach that processes tags iteratively. This is not a
+ * full HTML parser, but is sufficient for CMS content where the input is
+ * author-controlled (not arbitrary user input from the public internet).
+ */
+export function sanitizeCmsHtml(html, options) {
+    if (!html)
+        return "";
+    const allowedTags = options?.allowedTags
+        ? new Set(options.allowedTags)
+        : DEFAULT_ALLOWED_TAGS;
+    const allowedAttributes = options?.allowedAttributes
+        ? toAttributeSets(options.allowedAttributes)
+        : DEFAULT_ALLOWED_ATTRIBUTES;
+    const allowedProtocols = options?.allowedProtocols
+        ? new Set(options.allowedProtocols)
+        : DEFAULT_ALLOWED_PROTOCOLS;
+    const linkTarget = options?.linkTarget;
+    let result = html;
+    // Strip dangerous tags and their content entirely
+    result = result.replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, "");
+    result = result.replace(/<style\b[^>]*>[\s\S]*?<\/style\s*>/gi, "");
+    result = result.replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript\s*>/gi, "");
+    // Strip comments
+    result = result.replace(/<!--[\s\S]*?-->/g, "");
+    // Process tags
+    result = result.replace(/<\/?([a-zA-Z][a-zA-Z0-9]*)\b([^>]*)?\/?>/g, (match, tagName, attrs) => {
+        const tag = tagName.toLowerCase();
+        if (!allowedTags.has(tag)) {
+            return "";
+        }
+        const isClosing = match.startsWith("</");
+        if (isClosing) {
+            return `</${tag}>`;
+        }
+        const isSelfClosing = match.endsWith("/>");
+        const sanitizedAttrs = sanitizeAttributes(tag, attrs ?? "", allowedAttributes, allowedProtocols, linkTarget);
+        const attrStr = sanitizedAttrs ? ` ${sanitizedAttrs}` : "";
+        return isSelfClosing ? `<${tag}${attrStr} />` : `<${tag}${attrStr}>`;
+    });
+    return result;
+}
+function sanitizeAttributes(tag, attrString, allowedAttributes, allowedProtocols, linkTarget) {
+    const tagAttrs = allowedAttributes[tag];
+    const globalAttrs = allowedAttributes["*"];
+    const attrs = [];
+    const attrRegex = /([a-zA-Z][a-zA-Z0-9_-]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|(\S+)))?/g;
+    let match;
+    let hasRel = false;
+    let hasTarget = false;
+    while ((match = attrRegex.exec(attrString)) !== null) {
+        const name = match[1].toLowerCase();
+        const value = match[2] ?? match[3] ?? match[4] ?? "";
+        // Block event handlers
+        if (EVENT_HANDLER_PATTERN.test(name))
+            continue;
+        // Check if attribute is allowed
+        if (!tagAttrs?.has(name) && !globalAttrs?.has(name))
+            continue;
+        // Validate URL attributes
+        if ((name === "href" || name === "src" || name === "srcset") && value) {
+            if (!isAllowedUrl(value, allowedProtocols))
+                continue;
+        }
+        attrs.push(`${name}="${escapeAttrValue(value)}"`);
+        if (name === "rel")
+            hasRel = true;
+        if (name === "target")
+            hasTarget = true;
+    }
+    // For <a> tags: add rel="noopener noreferrer" to external links
+    if (tag === "a") {
+        const hrefAttr = attrs.find((a) => a.startsWith("href="));
+        const href = hrefAttr
+            ? hrefAttr.slice(6, -1)
+            : "";
+        const isExternal = href.startsWith("http://") || href.startsWith("https://");
+        if (isExternal) {
+            if (!hasRel) {
+                attrs.push('rel="noopener noreferrer"');
+            }
+            if (!hasTarget && linkTarget) {
+                attrs.push(`target="${escapeAttrValue(linkTarget)}"`);
+            }
+        }
+    }
+    return attrs.join(" ");
+}
+function isAllowedUrl(url, allowedProtocols) {
+    const trimmed = url.trim();
+    if (!trimmed)
+        return true;
+    // Relative URLs are always OK
+    if (trimmed.startsWith("/") || trimmed.startsWith("#") || trimmed.startsWith("?")) {
+        return true;
+    }
+    // Check protocol
+    const protocolMatch = trimmed.match(/^([a-zA-Z][a-zA-Z0-9+.-]*:)/);
+    if (!protocolMatch)
+        return true; // No protocol = relative
+    return allowedProtocols.has(protocolMatch[1].toLowerCase());
+}
+function escapeAttrValue(value) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/"/g, "&quot;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+function toAttributeSets(input) {
+    const result = {};
+    for (const [key, values] of Object.entries(input)) {
+        result[key] = new Set(values);
+    }
+    return result;
+}
+/**
+ * Converts a basic markdown string to HTML.
+ *
+ * Handles headings, bold, italic, links, images, code blocks, inline code,
+ * unordered/ordered lists, blockquotes, horizontal rules, and paragraphs.
+ * For rich markdown processing, use a full library like react-markdown.
+ */
+export function renderCmsMarkdown(markdown) {
+    if (!markdown)
+        return "";
+    let html = markdown;
+    // Fenced code blocks (before other processing)
+    html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, _lang, code) => `<pre><code>${escapeHtml(code.trimEnd())}</code></pre>`);
+    // Process line-by-line for block elements
+    const lines = html.split("\n");
+    const output = [];
+    let inList = null;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        // Skip lines inside code blocks (already processed)
+        if (line.startsWith("<pre><code>") || line.endsWith("</code></pre>")) {
+            output.push(line);
+            continue;
+        }
+        // Headings
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            if (inList) {
+                output.push(`</${inList}>`);
+                inList = null;
+            }
+            const level = headingMatch[1].length;
+            output.push(`<h${level}>${processInline(headingMatch[2])}</h${level}>`);
+            continue;
+        }
+        // Horizontal rule
+        if (/^---+$/.test(line.trim())) {
+            if (inList) {
+                output.push(`</${inList}>`);
+                inList = null;
+            }
+            output.push("<hr />");
+            continue;
+        }
+        // Blockquote
+        if (line.startsWith("> ")) {
+            if (inList) {
+                output.push(`</${inList}>`);
+                inList = null;
+            }
+            output.push(`<blockquote><p>${processInline(line.slice(2))}</p></blockquote>`);
+            continue;
+        }
+        // Unordered list
+        const ulMatch = line.match(/^[-*+]\s+(.+)$/);
+        if (ulMatch) {
+            if (inList !== "ul") {
+                if (inList)
+                    output.push(`</${inList}>`);
+                output.push("<ul>");
+                inList = "ul";
+            }
+            output.push(`<li>${processInline(ulMatch[1])}</li>`);
+            continue;
+        }
+        // Ordered list
+        const olMatch = line.match(/^\d+\.\s+(.+)$/);
+        if (olMatch) {
+            if (inList !== "ol") {
+                if (inList)
+                    output.push(`</${inList}>`);
+                output.push("<ol>");
+                inList = "ol";
+            }
+            output.push(`<li>${processInline(olMatch[1])}</li>`);
+            continue;
+        }
+        // Close list if we hit a non-list line
+        if (inList) {
+            output.push(`</${inList}>`);
+            inList = null;
+        }
+        // Empty line
+        if (!line.trim()) {
+            continue;
+        }
+        // Paragraph
+        output.push(`<p>${processInline(line)}</p>`);
+    }
+    if (inList) {
+        output.push(`</${inList}>`);
+    }
+    return output.join("\n");
+}
+function processInline(text) {
+    let result = escapeHtml(text);
+    // Images: ![alt](src)
+    result = result.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '<img src="$2" alt="$1" />');
+    // Links: [text](href)
+    result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+    // Bold: **text** or __text__
+    result = result.replace(/\*\*(.+?)\*\*/g, "<strong>$1</strong>");
+    result = result.replace(/__(.+?)__/g, "<strong>$1</strong>");
+    // Italic: *text* or _text_
+    result = result.replace(/\*(.+?)\*/g, "<em>$1</em>");
+    result = result.replace(/(?<!\w)_(.+?)_(?!\w)/g, "<em>$1</em>");
+    // Inline code: `code`
+    result = result.replace(/`([^`]+)`/g, "<code>$1</code>");
+    return result;
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}

package/dist/react/server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @cedros/data-react/server — server-only exports.
+ *
+ * These functions call the cedros-data backend directly and should
+ * only be used in React Server Components, route handlers, or
+ * Next.js data-fetching functions (generateMetadata, generateStaticParams).
+ *
+ * Do not import this module in client components.
+ */
+export { buildPageMetadata, generatePageMetadata, type PageMetadata, } from "./metadata.js";
+export { loadSitemapEntries } from "./sitemap.js";
+export { fetchBlogPost } from "./entries.js";
+export { listBlogSlugs, listContentSlugs, listLearnPathIds, } from "./slugs.js";
+export type { BuildPageMetadataOptions, CmsPageRecord, MeteredReadsInfo, SiteDataRecord, SitemapEntry, ServerFetchOptions, ContentType, } from "./types.js";

package/dist/react/server.js

@@ -0,0 +1,13 @@
+/**
+ * @cedros/data-react/server — server-only exports.
+ *
+ * These functions call the cedros-data backend directly and should
+ * only be used in React Server Components, route handlers, or
+ * Next.js data-fetching functions (generateMetadata, generateStaticParams).
+ *
+ * Do not import this module in client components.
+ */
+export { buildPageMetadata, generatePageMetadata, } from "./metadata.js";
+export { loadSitemapEntries } from "./sitemap.js";
+export { fetchBlogPost } from "./entries.js";
+export { listBlogSlugs, listContentSlugs, listLearnPathIds, } from "./slugs.js";

package/dist/react/sitemap.d.ts

@@ -0,0 +1,28 @@
+import type { ContentType, ServerFetchOptions, SitemapEntry } from "./types.js";
+/**
+ * Loads all routable content slugs from cedros-data for sitemap generation.
+ *
+ * Queries each content type collection and returns a flat list of sitemap
+ * entries with slug, lastModified, changeFrequency, and priority.
+ *
+ * @example
+ * ```ts
+ * // app/sitemap.ts
+ * import { loadSitemapEntries } from '@cedros/data-react/server';
+ *
+ * export default async function sitemap() {
+ *   const entries = await loadSitemapEntries({
+ *     serverUrl: process.env.NEXT_PUBLIC_BACKEND_API_URL,
+ *   });
+ *   return entries.map((e) => ({
+ *     url: `${process.env.NEXT_PUBLIC_ORIGIN}/${e.slug}`,
+ *     lastModified: e.lastModified,
+ *     changeFrequency: e.changeFrequency,
+ *     priority: e.priority,
+ *   }));
+ * }
+ * ```
+ */
+export declare function loadSitemapEntries(options?: ServerFetchOptions & {
+    contentTypes?: ContentType[];
+}): Promise<SitemapEntry[]>;