wpheadless-lib 1.0.0

package/dist/utils/i18n.js

@@ -0,0 +1,161 @@
+const defaultMessages = {
+    en: {
+        paginator: {
+            prev: "Previous",
+            next: "Next",
+            aria: "Pagination",
+        },
+        header: {
+            navAria: "Main navigation",
+        },
+        site: {
+            title: "Site title",
+            description: "Site description",
+            paginationTitle: "Site title",
+            paginationDescription: "Site pagination description",
+        },
+        errors: {
+            generic: "Unknown error",
+            fetchPosts: "Error fetching posts:",
+            fetchCategories: "Error fetching categories:",
+            fetchCategory: "Error fetching category:",
+            fetchCategoryPosts: "Error fetching category posts:",
+            fetchPost: "Error fetching post:",
+            fetchStaticRoutes: "Error generating static routes:",
+            fetchLegalPages: "Error generating legal static routes:",
+            fetchLegalPage: "Error fetching legal page:",
+        },
+        home: {
+            title: "Latest articles",
+            error: "Error",
+            errorHint: "Make sure your WordPress site URL is configured.",
+            empty: "No posts found.",
+            loadError: "Error loading posts: {error}",
+            pageLabel: "Page {page}",
+        },
+        post: {
+            authorPrefix: "By {name}",
+            featuredAlt: "Featured image: {title}",
+            articleAlt: "Article image: {title}",
+            aboutAuthor: "About the author",
+        },
+        category: {
+            empty: "No posts in this category.",
+            emptyPage: "No posts on this page.",
+            pageLabel: "Page {page}",
+            countOne: "{count} article",
+            countMany: "{count} articles",
+        },
+        footer: {
+            tagline: "Default footer tagline",
+            navTitle: "Links",
+            navAria: "Footer navigation",
+            noCookies: "Cookie-free site.",
+        },
+    },
+    es: {
+        paginator: {
+            prev: "Anterior",
+            next: "Siguiente",
+            aria: "Paginación",
+        },
+        header: {
+            navAria: "Navegación principal",
+        },
+        site: {
+            title: "Título del sitio",
+            description: "Descripción del sitio",
+            paginationTitle: "Título del sitio",
+            paginationDescription: "Descripción de paginación del sitio",
+        },
+        errors: {
+            generic: "Error desconocido",
+            fetchPosts: "Error obteniendo posts:",
+            fetchCategories: "Error obteniendo categorías:",
+            fetchCategory: "Error obteniendo categoría:",
+            fetchCategoryPosts: "Error obteniendo posts de la categoría:",
+            fetchPost: "Error obteniendo post:",
+            fetchStaticRoutes: "Error generando rutas estáticas:",
+            fetchLegalPages: "Error generando rutas estáticas de páginas:",
+            fetchLegalPage: "Error obteniendo página:",
+        },
+        home: {
+            title: "Últimos artículos",
+            error: "Error",
+            errorHint: "Asegúrate de configurar la URL de tu sitio WordPress.",
+            empty: "No se encontraron posts.",
+            loadError: "Error cargando posts: {error}",
+            pageLabel: "Página {page}",
+        },
+        post: {
+            authorPrefix: "Por {name}",
+            featuredAlt: "Imagen destacada: {title}",
+            articleAlt: "Imagen del artículo: {title}",
+            aboutAuthor: "Sobre el autor",
+        },
+        category: {
+            empty: "No hay posts en esta categoría.",
+            emptyPage: "No hay posts en esta página.",
+            pageLabel: "Página {page}",
+            countOne: "{count} artículo",
+            countMany: "{count} artículos",
+        },
+        footer: {
+            tagline: "Tagline por defecto del pie de página",
+            navTitle: "Enlaces",
+            navAria: "Navegación del pie de página",
+            noCookies: "Sitio sin cookies ni trackers.",
+        },
+    },
+};
+let messages = JSON.parse(JSON.stringify(defaultMessages));
+function deepMerge(target, source) {
+    const output = { ...target };
+    for (const [key, value] of Object.entries(source)) {
+        if (value &&
+            typeof value === "object" &&
+            !Array.isArray(value) &&
+            typeof target[key] === "object") {
+            output[key] = deepMerge(target[key], value);
+        }
+        else {
+            output[key] = value;
+        }
+    }
+    return output;
+}
+/**
+ * Allow projects to override/extend default translations.
+ * Call once during app bootstrap with per-locale overrides.
+ */
+export function extendTranslations(overrides) {
+    messages = deepMerge(messages, overrides);
+}
+const fallbackLocale = "en";
+function getMessage(locale, key) {
+    const parts = key.split(".");
+    let current = messages[locale];
+    for (const part of parts) {
+        if (typeof current !== "object" || current === null) {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return typeof current === "string" ? current : undefined;
+}
+function interpolate(template, vars) {
+    if (!vars)
+        return template;
+    return Object.entries(vars).reduce((acc, [token, value]) => acc.replaceAll(`{${token}}`, String(value)), template);
+}
+export function getTranslator(locale) {
+    const normalizedLocale = locale || fallbackLocale;
+    return (key, vars) => {
+        const value = getMessage(normalizedLocale, key) ??
+            getMessage(fallbackLocale, key) ??
+            key;
+        if (typeof value !== "string")
+            return key;
+        return interpolate(value, vars);
+    };
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./i18n";
+export * from "./routing";
+export * from "./seo";
+export * from "./html";
+export * from "./hreflang";
+export * from "./sitemap";

package/dist/utils/index.js

@@ -0,0 +1,6 @@
+export * from "./i18n";
+export * from "./routing";
+export * from "./seo";
+export * from "./html";
+export * from "./hreflang";
+export * from "./sitemap";

package/dist/utils/routing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Helpers to build localized URLs and pagination links.
+ */
+export declare function getLangPrefix(isDefaultLang: boolean, lang: string): string;
+export declare function ensureTrailingSlash(path: string): string;
+/**
+ * Get the base site URL.
+ * Prefer passing from the app layer; falls back to localhost.
+ */
+export declare function getSiteUrl(siteUrl?: string): string;
+/**
+ * Build an absolute site URL.
+ * @param path - Relative route (e.g. "/category/post")
+ * @param siteUrl - Base site URL from the app layer
+ * @returns Full URL (e.g. "http://localhost:3000/category/post")
+ */
+export declare function getAbsoluteUrl(path: string, siteUrl?: string): string;
+/**
+ * Convert WordPress URLs to local/production URLs.
+ * Replaces the WordPress domain with the current site domain.
+ * @param wpUrl - WordPress URL (e.g. "https://api.example.com/category/post")
+ * @param wpApiBaseUrl - WordPress API base URL from the app layer
+ * @returns Relative or current-site URL (e.g. "/category/post")
+ */
+export declare function convertWpUrl(wpUrl: string, wpApiBaseUrl?: string): string;
+type PrevNext = {
+    prev?: string;
+    next: string;
+};
+export declare function buildPrevNextUrls(opts: {
+    currentPage: number;
+    lang: string;
+    isDefaultLang: boolean;
+    siteUrl?: string;
+}): PrevNext;
+export declare function buildPrevNextFromBase({ baseUrl, currentPage, }: {
+    baseUrl: string;
+    currentPage: number;
+}): PrevNext;
+export {};

package/dist/utils/routing.js

@@ -0,0 +1,84 @@
+/**
+ * Helpers to build localized URLs and pagination links.
+ */
+export function getLangPrefix(isDefaultLang, lang) {
+    return isDefaultLang ? "/" : `/${lang}/`;
+}
+export function ensureTrailingSlash(path) {
+    if (!path)
+        return "/";
+    return path.endsWith("/") ? path : `${path}/`;
+}
+/**
+ * Get the base site URL.
+ * Prefer passing from the app layer; falls back to localhost.
+ */
+export function getSiteUrl(siteUrl) {
+    if (!siteUrl)
+        return "http://localhost:3000";
+    try {
+        const url = new URL(siteUrl);
+        return url.origin;
+    }
+    catch {
+        return siteUrl;
+    }
+}
+/**
+ * Build an absolute site URL.
+ * @param path - Relative route (e.g. "/category/post")
+ * @param siteUrl - Base site URL from the app layer
+ * @returns Full URL (e.g. "http://localhost:3000/category/post")
+ */
+export function getAbsoluteUrl(path, siteUrl) {
+    const baseUrl = getSiteUrl(siteUrl);
+    // Ensure the path starts with /
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const withSlash = ensureTrailingSlash(normalizedPath);
+    return `${baseUrl}${withSlash}`;
+}
+/**
+ * Convert WordPress URLs to local/production URLs.
+ * Replaces the WordPress domain with the current site domain.
+ * @param wpUrl - WordPress URL (e.g. "https://api.example.com/category/post")
+ * @param wpApiBaseUrl - WordPress API base URL from the app layer
+ * @returns Relative or current-site URL (e.g. "/category/post")
+ */
+export function convertWpUrl(wpUrl, wpApiBaseUrl) {
+    try {
+        const wpDomain = (wpApiBaseUrl || "").replace("/wp-json", "");
+        // If the URL contains the WordPress domain, extract only the path
+        if (wpDomain && wpUrl.includes(wpDomain)) {
+            const url = new URL(wpUrl);
+            return url.pathname;
+        }
+        // If it's already a relative URL, return as-is
+        if (wpUrl.startsWith("/")) {
+            return wpUrl;
+        }
+        // If it's an external URL, return as-is
+        return wpUrl;
+    }
+    catch {
+        // If parsing fails, return as-is
+        return wpUrl;
+    }
+}
+export function buildPrevNextUrls(opts) {
+    const { currentPage, lang, isDefaultLang, siteUrl } = opts;
+    const canonicalBase = getLangPrefix(isDefaultLang, lang);
+    return buildPrevNextFromBase({
+        baseUrl: getAbsoluteUrl(canonicalBase, siteUrl),
+        currentPage,
+    });
+}
+export function buildPrevNextFromBase({ baseUrl, currentPage, }) {
+    const normalizedBase = baseUrl.replace(/\/+$/, "");
+    const prev = currentPage > 2
+        ? `${normalizedBase}/page/${currentPage - 1}`
+        : currentPage === 2
+            ? `${normalizedBase}/`
+            : undefined;
+    const next = `${normalizedBase}/page/${currentPage + 1}`;
+    return { prev, next };
+}

package/dist/utils/seo.d.ts

@@ -0,0 +1,75 @@
+import type { WPYoastHeadJson } from "wpjsapi-lib";
+type OgImage = {
+    url?: string;
+    [key: string]: unknown;
+};
+type OgLike = {
+    yoast_head_json?: {
+        og_image?: OgImage[];
+    };
+};
+type FeaturedMedia = {
+    source_url?: string;
+    alt_text?: string;
+    media_details?: {
+        width?: number;
+        height?: number;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+};
+type FeaturedMediaLike = Pick<FeaturedMedia, "source_url">;
+type YoastSchemaHolder = {
+    yoast_head_json?: {
+        schema?: unknown;
+    };
+};
+type YoastHolder = {
+    yoast_head_json?: WPYoastHeadJson;
+};
+type WithEmbeddedMedia = {
+    _embedded?: {
+        "wp:featuredmedia"?: Array<FeaturedMedia>;
+    };
+};
+export declare function getOgImageUrl(entity?: OgLike, featuredMedia?: FeaturedMediaLike): string | undefined;
+type RewriteOpts = {
+    siteUrl?: string;
+    wpApiUrl?: string;
+};
+/**
+ * Replace Yoast URLs so they match the frontend domain instead of the WP API domain.
+ * It stringifies the object to replace origins and keeps structure intact.
+ */
+export declare function rewriteYoastUrls<T extends WPYoastHeadJson | undefined>(yoast: T, opts?: RewriteOpts): T;
+export declare function getYoastHead(entity?: YoastHolder, opts?: RewriteOpts): WPYoastHeadJson | undefined;
+export declare function getYoastSchema(entity?: YoastSchemaHolder, opts?: RewriteOpts): import("wpjsapi-lib").WPYoastSchema;
+export declare function stripBreadcrumbsFromSchema(schema: unknown): unknown;
+export declare function getFeaturedMedia(entity?: WithEmbeddedMedia): FeaturedMedia | undefined;
+export declare function getPlainTextExcerpt(html?: string, maxLength?: number): string | undefined;
+type BreadcrumbItem = {
+    name: string;
+    item?: string;
+};
+export declare function buildBreadcrumbSchema(items: BreadcrumbItem[]): {
+    "@context": string;
+    "@type": string;
+    itemListElement: {
+        item?: string;
+        "@type": string;
+        position: number;
+        name: string;
+    }[];
+};
+export declare function buildCollectionPageSchema({ name, description, url, }: {
+    name: string;
+    description?: string;
+    url: string;
+}): {
+    "@context": string;
+    "@type": string;
+    name: string;
+    description: string;
+    url: string;
+};
+export {};

package/dist/utils/seo.js

@@ -0,0 +1,97 @@
+import { stripTags } from "./html";
+export function getOgImageUrl(entity, featuredMedia) {
+    const ogUrl = entity?.yoast_head_json?.og_image?.[0]?.url;
+    return ogUrl || featuredMedia?.source_url;
+}
+const getOrigin = (url) => {
+    if (!url)
+        return null;
+    try {
+        return new URL(url).origin;
+    }
+    catch {
+        return null;
+    }
+};
+const normalizeWpApiOrigin = (wpApiUrl) => {
+    if (!wpApiUrl)
+        return null;
+    const cleaned = wpApiUrl.replace(/\/wp-json\/?$/, "");
+    return getOrigin(cleaned);
+};
+/**
+ * Replace Yoast URLs so they match the frontend domain instead of the WP API domain.
+ * It stringifies the object to replace origins and keeps structure intact.
+ */
+export function rewriteYoastUrls(yoast, opts = {}) {
+    if (!yoast)
+        return yoast;
+    const targetOrigin = getOrigin(opts.siteUrl);
+    const sourceOrigin = normalizeWpApiOrigin(opts.wpApiUrl) || getOrigin(yoast.canonical);
+    if (!targetOrigin || !sourceOrigin || targetOrigin === sourceOrigin) {
+        return yoast;
+    }
+    try {
+        const serialized = JSON.stringify(yoast);
+        const replaced = serialized.split(sourceOrigin).join(targetOrigin);
+        return JSON.parse(replaced);
+    }
+    catch {
+        return yoast;
+    }
+}
+export function getYoastHead(entity, opts) {
+    const yoast = entity?.yoast_head_json;
+    return rewriteYoastUrls(yoast, opts);
+}
+export function getYoastSchema(entity, opts) {
+    const yoast = getYoastHead(entity, opts);
+    return yoast?.schema || null;
+}
+export function stripBreadcrumbsFromSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return schema;
+    const graph = schema["@graph"];
+    if (!Array.isArray(graph))
+        return schema;
+    const filtered = graph.filter((node) => {
+        const type = node["@type"];
+        if (!type)
+            return true;
+        if (Array.isArray(type)) {
+            return !type.includes("BreadcrumbList");
+        }
+        return type !== "BreadcrumbList";
+    });
+    return { ...schema, "@graph": filtered };
+}
+export function getFeaturedMedia(entity) {
+    return entity?._embedded?.["wp:featuredmedia"]?.[0];
+}
+export function getPlainTextExcerpt(html, maxLength = 160) {
+    if (!html)
+        return undefined;
+    const text = html.replace(/<[^>]*>/g, "");
+    return maxLength > 0 ? text.slice(0, maxLength) : text;
+}
+export function buildBreadcrumbSchema(items) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        itemListElement: items.map((it, idx) => ({
+            "@type": "ListItem",
+            position: idx + 1,
+            name: stripTags(it.name) || it.name,
+            ...(it.item ? { item: it.item } : {}),
+        })),
+    };
+}
+export function buildCollectionPageSchema({ name, description, url, }) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "CollectionPage",
+        name,
+        description,
+        url,
+    };
+}

package/dist/utils/sitemap.d.ts

@@ -0,0 +1,26 @@
+import type { LanguageConfig } from "./hreflang";
+export type SitemapRuntimeConfig = {
+    postsPerPagePagination: number;
+};
+export type SitemapConfig = {
+    languages: LanguageConfig[];
+    runtimeConfig: SitemapRuntimeConfig;
+    wpApiUrl?: string;
+    siteUrl?: string;
+};
+export type SitemapEntry = {
+    url: string;
+    lastmod?: string;
+    alternates?: Record<string, string>;
+};
+export declare function renderSitemap(entries: SitemapEntry[]): string;
+export declare function renderSitemapIndex(sitemaps: Array<{
+    url: string;
+    lastmod?: string;
+}>): string;
+export declare function getHomeEntries(cfg: SitemapConfig): Promise<SitemapEntry[]>;
+export declare function getHomePaginationEntries(cfg: SitemapConfig): Promise<SitemapEntry[]>;
+export declare function getCategoryEntries(cfg: SitemapConfig): Promise<SitemapEntry[]>;
+export declare function getCategoryPaginationEntries(cfg: SitemapConfig): Promise<SitemapEntry[]>;
+export declare function getPostEntriesForLang(langCode: string, cfg: SitemapConfig): Promise<SitemapEntry[]>;
+export declare function getLegalEntries(cfg: SitemapConfig): Promise<SitemapEntry[]>;