@proxima-io/storefront-core 0.3.0 → 0.8.2

package/dist/seo/json-ld.d.ts

@@ -0,0 +1,57 @@
+import type { BreadcrumbItem, JsonLdLocalBusinessMeta, JsonLdProductMeta, JsonLdWebsiteMeta } from '../types/seo.js';
+/**
+ * Build a `WebSite` JSON-LD object.
+ * Enables Google's Search Action box in SERPs.
+ *
+ * @example
+ * <script type="application/ld+json" set:html={JSON.stringify(buildWebSiteJsonLd(website))} />
+ */
+export declare function buildWebSiteJsonLd(website: JsonLdWebsiteMeta): Record<string, any>;
+/**
+ * Build an `Organization` JSON-LD object.
+ * Returns `null` when `website.logo_url` is absent (Google ignores logo-less org markup).
+ *
+ * @example
+ * {orgJsonLd && <script type="application/ld+json" set:html={JSON.stringify(orgJsonLd)} />}
+ */
+export declare function buildOrganizationJsonLd(website: JsonLdWebsiteMeta): Record<string, any> | null;
+/**
+ * Build a `Product` JSON-LD object for a product detail page.
+ * Includes `Offer` with pricing, currency, and availability.
+ *
+ * @example
+ * <script type="application/ld+json" set:html={JSON.stringify(buildProductJsonLd(product, website))} />
+ */
+export declare function buildProductJsonLd(product: JsonLdProductMeta, website: {
+    domain: string;
+    currency: string;
+}, options?: {
+    productUrl?: string;
+    locale?: string;
+    localizedPaths?: Record<string, string>;
+    defaultLocale?: string;
+}): Record<string, any>;
+/**
+ * Build a `BreadcrumbList` JSON-LD object.
+ *
+ * @param items  Array of breadcrumb steps.  The last item typically has no `href`.
+ * @param siteUrl  Absolute site URL, e.g. `https://example.com`
+ *
+ * @example
+ * const crumbs = buildBreadcrumbJsonLd(
+ *   [{ label: "Inicio", href: "/" }, { label: "Zapatos", href: "/categoria/zapatos" }, { label: "Nike Air Max" }],
+ *   `https://${website.domain}`
+ * );
+ * <script type="application/ld+json" set:html={JSON.stringify(crumbs)} />
+ */
+export declare function buildBreadcrumbJsonLd(items: BreadcrumbItem[], siteUrl: string): Record<string, any>;
+/**
+ * Build a `LocalBusiness` JSON-LD object for brick-and-mortar stores.
+ * Returns `null` when `seo` is falsy so callers can gate rendering easily.
+ *
+ * @example
+ * const schema = buildLocalBusinessJsonLd(seo);
+ * {schema && <script type="application/ld+json" set:html={JSON.stringify(schema)} />}
+ */
+export declare function buildLocalBusinessJsonLd(seo: JsonLdLocalBusinessMeta | null | undefined): Record<string, unknown> | null;
+//# sourceMappingURL=json-ld.d.ts.map

package/dist/seo/json-ld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-ld.d.ts","sourceRoot":"","sources":["../../src/seo/json-ld.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGrH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAgBlF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,iBAAiB,GACzB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAU5B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,iBAAiB,EAC1B,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC7C,OAAO,CAAC,EAAE;IACR,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GACA,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAqDrB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,cAAc,EAAE,EACvB,OAAO,EAAE,MAAM,GACd,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAarB;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CA6ChC"}

package/dist/seo/json-ld.js

@@ -0,0 +1,180 @@
+import { buildEnginePageUrl } from './engine-url.js';
+/**
+ * Build a `WebSite` JSON-LD object.
+ * Enables Google's Search Action box in SERPs.
+ *
+ * @example
+ * <script type="application/ld+json" set:html={JSON.stringify(buildWebSiteJsonLd(website))} />
+ */
+export function buildWebSiteJsonLd(website) {
+    const siteUrl = `https://${website.domain}`;
+    return {
+        "@context": "https://schema.org",
+        "@type": "WebSite",
+        "name": website.name,
+        "url": `${siteUrl}/`,
+        "potentialAction": {
+            "@type": "SearchAction",
+            "target": {
+                "@type": "EntryPoint",
+                "urlTemplate": `${siteUrl}/buscar?q={search_term_string}`,
+            },
+            "query-input": "required name=search_term_string",
+        },
+    };
+}
+/**
+ * Build an `Organization` JSON-LD object.
+ * Returns `null` when `website.logo_url` is absent (Google ignores logo-less org markup).
+ *
+ * @example
+ * {orgJsonLd && <script type="application/ld+json" set:html={JSON.stringify(orgJsonLd)} />}
+ */
+export function buildOrganizationJsonLd(website) {
+    if (!website.logo_url)
+        return null;
+    const siteUrl = `https://${website.domain}`;
+    return {
+        "@context": "https://schema.org",
+        "@type": "Organization",
+        "name": website.name,
+        "url": `${siteUrl}/`,
+        "logo": { "@type": "ImageObject", "url": website.logo_url },
+    };
+}
+/**
+ * Build a `Product` JSON-LD object for a product detail page.
+ * Includes `Offer` with pricing, currency, and availability.
+ *
+ * @example
+ * <script type="application/ld+json" set:html={JSON.stringify(buildProductJsonLd(product, website))} />
+ */
+export function buildProductJsonLd(product, website, options) {
+    const siteUrl = `https://${website.domain}`;
+    const defaultLocale = options?.defaultLocale ?? 'es';
+    const productUrl = options?.productUrl ??
+        (options?.localizedPaths && options.locale
+            ? buildEnginePageUrl(website.domain, options.locale, options.localizedPaths, { slug: product.slug }, defaultLocale)
+            : `${siteUrl}/producto/${product.slug}`);
+    // Deduplicated image list: primary first, then extras
+    const images = [
+        product.image,
+        ...(product.images?.filter((img) => img && img !== product.image) ?? []),
+    ].filter(Boolean);
+    const result = {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        "name": product.name,
+        "image": images.length === 1 ? images[0] : images,
+        "offers": {
+            "@type": "Offer",
+            "url": productUrl,
+            "price": product.priceRaw,
+            "priceCurrency": website.currency,
+            "availability": product.inStock === false
+                ? "https://schema.org/OutOfStock"
+                : "https://schema.org/InStock",
+        },
+    };
+    if (product.description)
+        result["description"] = product.description;
+    if (product.sku)
+        result["sku"] = product.sku;
+    if (product.productId != null)
+        result["identifier"] = String(product.productId);
+    if (product.brand)
+        result["brand"] = { "@type": "Brand", "name": product.brand };
+    // Strikethrough price — only when compare-at is higher than current
+    if (product.compareAtPrice && product.compareAtPrice > product.priceRaw) {
+        result["offers"]["priceSpecification"] = {
+            "@type": "PriceSpecification",
+            "price": product.compareAtPrice,
+            "priceCurrency": website.currency,
+        };
+    }
+    return result;
+}
+/**
+ * Build a `BreadcrumbList` JSON-LD object.
+ *
+ * @param items  Array of breadcrumb steps.  The last item typically has no `href`.
+ * @param siteUrl  Absolute site URL, e.g. `https://example.com`
+ *
+ * @example
+ * const crumbs = buildBreadcrumbJsonLd(
+ *   [{ label: "Inicio", href: "/" }, { label: "Zapatos", href: "/categoria/zapatos" }, { label: "Nike Air Max" }],
+ *   `https://${website.domain}`
+ * );
+ * <script type="application/ld+json" set:html={JSON.stringify(crumbs)} />
+ */
+export function buildBreadcrumbJsonLd(items, siteUrl) {
+    return {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        "itemListElement": items.map((item, i) => ({
+            "@type": "ListItem",
+            "position": i + 1,
+            "name": item.label,
+            ...(item.href
+                ? { "item": item.href.startsWith("http") ? item.href : `${siteUrl}${item.href}` }
+                : {}),
+        })),
+    };
+}
+/**
+ * Build a `LocalBusiness` JSON-LD object for brick-and-mortar stores.
+ * Returns `null` when `seo` is falsy so callers can gate rendering easily.
+ *
+ * @example
+ * const schema = buildLocalBusinessJsonLd(seo);
+ * {schema && <script type="application/ld+json" set:html={JSON.stringify(schema)} />}
+ */
+export function buildLocalBusinessJsonLd(seo) {
+    if (!seo)
+        return null;
+    const result = {
+        "@context": "https://schema.org",
+        "@type": "LocalBusiness",
+        "name": seo.name,
+        "url": seo.url,
+        "@id": `${seo.url}#localbusiness`,
+    };
+    if (seo.image)
+        result["image"] = seo.image;
+    if (seo.telephone)
+        result["telephone"] = seo.telephone;
+    const hasAddress = seo.street_address || seo.address_locality || seo.address_country;
+    if (hasAddress) {
+        const address = { "@type": "PostalAddress" };
+        if (seo.street_address)
+            address["streetAddress"] = seo.street_address;
+        if (seo.address_locality)
+            address["addressLocality"] = seo.address_locality;
+        if (seo.address_region)
+            address["addressRegion"] = seo.address_region;
+        if (seo.postal_code)
+            address["postalCode"] = seo.postal_code;
+        if (seo.address_country)
+            address["addressCountry"] = seo.address_country;
+        result["address"] = address;
+    }
+    if (seo.latitude != null && seo.longitude != null) {
+        result["geo"] = {
+            "@type": "GeoCoordinates",
+            "latitude": seo.latitude,
+            "longitude": seo.longitude,
+        };
+    }
+    if (seo.opening_hours?.length || seo.opens || seo.closes) {
+        result["openingHoursSpecification"] = [{
+                "@type": "OpeningHoursSpecification",
+                ...(seo.opening_hours?.length ? { "dayOfWeek": seo.opening_hours } : {}),
+                ...(seo.opens ? { "opens": seo.opens } : {}),
+                ...(seo.closes ? { "closes": seo.closes } : {}),
+            }];
+    }
+    if (seo.social_links?.length)
+        result["sameAs"] = seo.social_links;
+    return result;
+}
+//# sourceMappingURL=json-ld.js.map

package/dist/seo/json-ld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-ld.js","sourceRoot":"","sources":["../../src/seo/json-ld.ts"],"names":[],"mappings":"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"}

package/dist/seo/page-seo.d.ts

@@ -0,0 +1,21 @@
+import type { PageSeoMeta, PageSeoWebsiteMeta } from '../types/seo.js';
+/**
+ * Build fully resolved SEO metadata for a page.
+ *
+ * Data priority:
+ *   1. Admin-set `PageSEO` fields in `composition.seo` (explicit overrides)
+ *   2. Entity-derived data in `composition.seo.entity_name` / `entity_image` (auto-populated by API)
+ *   3. Website-level defaults (`website.og_image_url`, etc.)
+ *   4. Hard fallbacks (empty strings)
+ *
+ * @param seoData   The `seo` object from `ProximaCompositionResponse` (may be null)
+ * @param website   Website-level SEO fields
+ * @param locale    Locale code for resolving localized strings (e.g. "es")
+ * @param currentUrl  Absolute URL of the current page — used as canonical fallback
+ *
+ * @example
+ * const seo = buildPageSeo(composition.seo, website, website.locale, canonicalUrl);
+ * // → pass to <SiteLayout seo={seo} />
+ */
+export declare function buildPageSeo(seoData: Record<string, any> | null | undefined, website: PageSeoWebsiteMeta, locale: string, currentUrl: string): PageSeoMeta;
+//# sourceMappingURL=page-seo.d.ts.map

package/dist/seo/page-seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-seo.d.ts","sourceRoot":"","sources":["../../src/seo/page-seo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEvE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,EAC/C,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,WAAW,CAwDb"}

package/dist/seo/page-seo.js

@@ -0,0 +1,68 @@
+/**
+ * Build fully resolved SEO metadata for a page.
+ *
+ * Data priority:
+ *   1. Admin-set `PageSEO` fields in `composition.seo` (explicit overrides)
+ *   2. Entity-derived data in `composition.seo.entity_name` / `entity_image` (auto-populated by API)
+ *   3. Website-level defaults (`website.og_image_url`, etc.)
+ *   4. Hard fallbacks (empty strings)
+ *
+ * @param seoData   The `seo` object from `ProximaCompositionResponse` (may be null)
+ * @param website   Website-level SEO fields
+ * @param locale    Locale code for resolving localized strings (e.g. "es")
+ * @param currentUrl  Absolute URL of the current page — used as canonical fallback
+ *
+ * @example
+ * const seo = buildPageSeo(composition.seo, website, website.locale, canonicalUrl);
+ * // → pass to <SiteLayout seo={seo} />
+ */
+export function buildPageSeo(seoData, website, locale, currentUrl) {
+    /** Resolve a value that may be a localized dict `{ es: "...", en: "..." }` or a plain string */
+    function resolveLocalized(value) {
+        if (!value)
+            return null;
+        if (typeof value === "string")
+            return value || null;
+        if (typeof value === "object") {
+            const map = value;
+            return map[locale] ?? map["es"] ?? Object.values(map).find(Boolean) ?? null;
+        }
+        return null;
+    }
+    const entityName = seoData?.entity_name ?? null;
+    const entityImage = seoData?.entity_image ?? null;
+    // Title: admin-set > entity name + site name > site name
+    const adminTitle = resolveLocalized(seoData?.meta_title);
+    const title = adminTitle ?? (entityName ? `${entityName} | ${website.name}` : website.name);
+    // Description: admin-set > entity-based fallback > site name
+    const adminDescription = resolveLocalized(seoData?.meta_description);
+    const description = adminDescription ??
+        (entityName ? `${entityName} en ${website.name}` : website.name);
+    // OG image: admin-set > entity image > website og_image_url
+    const ogImage = seoData?.og_image ??
+        entityImage ??
+        (website.og_image_url ?? null);
+    const ogType = seoData?.og_type ?? "website";
+    const canonicalUrl = seoData?.canonical_url ?? currentUrl;
+    const robots = seoData?.robots === "noindex"
+        ? "noindex, nofollow"
+        : "index, follow";
+    const rawHandle = website.twitter_handle ?? null;
+    const twitterSite = rawHandle ? `@${rawHandle.replace(/^@/, "")}` : null;
+    return {
+        title,
+        description,
+        ogTitle: title,
+        ogDescription: description,
+        ogImage,
+        ogType,
+        ogSiteName: website.name,
+        canonicalUrl,
+        robots,
+        twitterCard: "summary_large_image",
+        twitterSite,
+        twitterImage: ogImage,
+        faviconUrl: website.favicon_url ?? null,
+    };
+}
+//# sourceMappingURL=page-seo.js.map

package/dist/seo/page-seo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-seo.js","sourceRoot":"","sources":["../../src/seo/page-seo.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,YAAY,CAC1B,OAA+C,EAC/C,OAA2B,EAC3B,MAAc,EACd,UAAkB;IAElB,gGAAgG;IAChG,SAAS,gBAAgB,CAAC,KAAc;QACtC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,IAAI,IAAI,CAAC;QACpD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,MAAM,GAAG,GAAG,KAA+B,CAAC;YAC5C,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;QAC9E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAI,OAAO,EAAE,WAAyC,IAAI,IAAI,CAAC;IAC/E,MAAM,WAAW,GAAI,OAAO,EAAE,YAA0C,IAAI,IAAI,CAAC;IAEjF,yDAAyD;IACzD,MAAM,UAAU,GAAG,gBAAgB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;IACzD,MAAM,KAAK,GAAG,UAAU,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,MAAM,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5F,6DAA6D;IAC7D,MAAM,gBAAgB,GAAG,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACrE,MAAM,WAAW,GACf,gBAAgB;QAChB,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAEnE,4DAA4D;IAC5D,MAAM,OAAO,GACV,OAAO,EAAE,QAAsC;QAChD,WAAW;QACX,CAAC,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;IAEjC,MAAM,MAAM,GAAI,OAAO,EAAE,OAAqC,IAAI,SAAS,CAAC;IAC5E,MAAM,YAAY,GAAI,OAAO,EAAE,aAA2C,IAAI,UAAU,CAAC;IACzF,MAAM,MAAM,GACT,OAAO,EAAE,MAAoC,KAAK,SAAS;QAC1D,CAAC,CAAC,mBAAmB;QACrB,CAAC,CAAC,eAAe,CAAC;IAEtB,MAAM,SAAS,GAAG,OAAO,CAAC,cAAc,IAAI,IAAI,CAAC;IACjD,MAAM,WAAW,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzE,OAAO;QACL,KAAK;QACL,WAAW;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,WAAW;QAC1B,OAAO;QACP,MAAM;QACN,UAAU,EAAE,OAAO,CAAC,IAAI;QACxB,YAAY;QACZ,MAAM;QACN,WAAW,EAAE,qBAAqB;QAClC,WAAW;QACX,YAAY,EAAE,OAAO;QACrB,UAAU,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;KACxC,CAAC;AACJ,CAAC"}

package/dist/seo/robots.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Generate a `robots.txt` for a storefront.
+ *
+ * Blocks all private buyer routes and API paths.
+ * Adds a `Sitemap:` directive pointing to `{siteUrl}/sitemap.xml`.
+ *
+ * @example
+ * // apps/{slug}/src/pages/robots.txt.ts
+ * import type { APIRoute } from "astro";
+ * import { resolveWebsiteOnly } from "@/lib/resolver";
+ * import { generateRobotsTxt } from "@proxima-io/storefront-core";
+ *
+ * export const GET: APIRoute = async () => {
+ *   const website = await resolveWebsiteOnly();
+ *   return new Response(generateRobotsTxt(website), {
+ *     headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "public, max-age=86400" },
+ *   });
+ * };
+ */
+export declare function generateRobotsTxt(website: {
+    domain: string;
+}): string;
+//# sourceMappingURL=robots.d.ts.map

package/dist/seo/robots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"robots.d.ts","sourceRoot":"","sources":["../../src/seo/robots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAcrE"}

package/dist/seo/robots.js

@@ -0,0 +1,35 @@
+/**
+ * Generate a `robots.txt` for a storefront.
+ *
+ * Blocks all private buyer routes and API paths.
+ * Adds a `Sitemap:` directive pointing to `{siteUrl}/sitemap.xml`.
+ *
+ * @example
+ * // apps/{slug}/src/pages/robots.txt.ts
+ * import type { APIRoute } from "astro";
+ * import { resolveWebsiteOnly } from "@/lib/resolver";
+ * import { generateRobotsTxt } from "@proxima-io/storefront-core";
+ *
+ * export const GET: APIRoute = async () => {
+ *   const website = await resolveWebsiteOnly();
+ *   return new Response(generateRobotsTxt(website), {
+ *     headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "public, max-age=86400" },
+ *   });
+ * };
+ */
+export function generateRobotsTxt(website) {
+    const siteUrl = `https://${website.domain}`;
+    return [
+        "User-agent: *",
+        "Allow: /",
+        "",
+        "Disallow: /cuenta",
+        "Disallow: /carrito",
+        "Disallow: /checkout",
+        "Disallow: /api/",
+        "Disallow: /dev/",
+        "",
+        `Sitemap: ${siteUrl}/sitemap.xml`,
+    ].join("\n");
+}
+//# sourceMappingURL=robots.js.map

package/dist/seo/robots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"robots.js","sourceRoot":"","sources":["../../src/seo/robots.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC3D,MAAM,OAAO,GAAG,WAAW,OAAO,CAAC,MAAM,EAAE,CAAC;IAC5C,OAAO;QACL,eAAe;QACf,UAAU;QACV,EAAE;QACF,mBAAmB;QACnB,oBAAoB;QACpB,qBAAqB;QACrB,iBAAiB;QACjB,iBAAiB;QACjB,EAAE;QACF,YAAY,OAAO,cAAc;KAClC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/seo/sitemap.d.ts

@@ -0,0 +1,35 @@
+import type { SitemapWebsiteMeta } from '../types/seo.js';
+/**
+ * Generate a complete `sitemap.xml` for a storefront.
+ *
+ * Includes:
+ *  1. Content pages from the website manifest (priority 1.0 for home, 0.8 for others)
+ *  2. Category pages from the recursive nav tree (priority 0.8)
+ *  3. Brand pages from the brands directory (priority 0.7)
+ *  4. Product pages — paginated up to `maxProducts` (priority 0.9)
+ *
+ * All entries use today's date as `lastmod`.
+ *
+ * @param website  Resolved website object (domain + pages array)
+ * @param apiUrl   Base URL of the Proxima API (e.g. `http://localhost:8000`)
+ * @param options  Optional overrides: pageSize (default 60), maxProducts (default 3000)
+ *
+ * @example
+ * // apps/{slug}/src/pages/sitemap.xml.ts
+ * import type { APIRoute } from "astro";
+ * import { resolveWebsiteOnly } from "@/lib/resolver";
+ * import { generateSitemapXml } from "@proxima-io/storefront-core";
+ *
+ * export const GET: APIRoute = async () => {
+ *   const website = await resolveWebsiteOnly();
+ *   const xml = await generateSitemapXml(website, import.meta.env.PROXIMA_API_URL ?? "http://localhost:8000");
+ *   return new Response(xml, {
+ *     headers: { "Content-Type": "application/xml; charset=utf-8", "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400" },
+ *   });
+ * };
+ */
+export declare function generateSitemapXml(website: SitemapWebsiteMeta, apiUrl: string, options?: {
+    pageSize?: number;
+    maxProducts?: number;
+}): Promise<string>;
+//# sourceMappingURL=sitemap.d.ts.map

package/dist/seo/sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../../src/seo/sitemap.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAoD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACxD,OAAO,CAAC,MAAM,CAAC,CAqIjB"}

package/dist/seo/sitemap.js

@@ -0,0 +1,186 @@
+import { buildCanonicalUrl } from './hreflang.js';
+import { fillPathTemplate, findWebsitePageByResolver, slugFromCatalogHref, } from './engine-url.js';
+import { fetchBrandsDirectory, fetchCategoryNavTree, fetchStorefrontProducts, } from '../catalog/listings.js';
+/** Private resolver kinds that must never appear in a sitemap */
+const SITEMAP_PRIVATE_KINDS = new Set([
+    "cart",
+    "checkout",
+    "buyer_login",
+    "buyer_account",
+    "buyer_register",
+    "buyer_password_reset",
+    "order_list",
+    "order_detail",
+    "product_compare",
+]);
+function _xmlEscape(str) {
+    return str
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function _urlEntry(loc, priority = "0.7", changefreq = "weekly", lastmod) {
+    const lines = [
+        `  <url>`,
+        `    <loc>${_xmlEscape(loc)}</loc>`,
+        `    <changefreq>${changefreq}</changefreq>`,
+        `    <priority>${priority}</priority>`,
+    ];
+    if (lastmod)
+        lines.push(`    <lastmod>${lastmod}</lastmod>`);
+    lines.push(`  </url>`);
+    return lines.join("\n");
+}
+/**
+ * Generate a complete `sitemap.xml` for a storefront.
+ *
+ * Includes:
+ *  1. Content pages from the website manifest (priority 1.0 for home, 0.8 for others)
+ *  2. Category pages from the recursive nav tree (priority 0.8)
+ *  3. Brand pages from the brands directory (priority 0.7)
+ *  4. Product pages — paginated up to `maxProducts` (priority 0.9)
+ *
+ * All entries use today's date as `lastmod`.
+ *
+ * @param website  Resolved website object (domain + pages array)
+ * @param apiUrl   Base URL of the Proxima API (e.g. `http://localhost:8000`)
+ * @param options  Optional overrides: pageSize (default 60), maxProducts (default 3000)
+ *
+ * @example
+ * // apps/{slug}/src/pages/sitemap.xml.ts
+ * import type { APIRoute } from "astro";
+ * import { resolveWebsiteOnly } from "@/lib/resolver";
+ * import { generateSitemapXml } from "@proxima-io/storefront-core";
+ *
+ * export const GET: APIRoute = async () => {
+ *   const website = await resolveWebsiteOnly();
+ *   const xml = await generateSitemapXml(website, import.meta.env.PROXIMA_API_URL ?? "http://localhost:8000");
+ *   return new Response(xml, {
+ *     headers: { "Content-Type": "application/xml; charset=utf-8", "Cache-Control": "public, s-maxage=3600, stale-while-revalidate=86400" },
+ *   });
+ * };
+ */
+export async function generateSitemapXml(website, apiUrl, options = {}) {
+    const PAGE_SIZE = Math.min(60, options.pageSize ?? 60);
+    const MAX_PRODUCTS = options.maxProducts ?? 3000;
+    const MAX_PAGES = Math.ceil(MAX_PRODUCTS / PAGE_SIZE);
+    const TODAY = new Date().toISOString().split("T")[0];
+    const siteUrl = `https://${website.domain}`;
+    const defaultLocale = website.default_locale ?? "es";
+    const enabledLocales = website.enabled_locales?.length
+        ? website.enabled_locales
+        : [defaultLocale];
+    const entries = [];
+    function localizedTemplatesFor(resolverKind, fallbackTemplate) {
+        const page = findWebsitePageByResolver(website.pages, resolverKind);
+        const localizedPaths = page?.localized_paths ?? {};
+        const hasLocalized = Object.keys(localizedPaths).length > 0;
+        if (!hasLocalized) {
+            return [{ locale: defaultLocale, template: page?.path ?? fallbackTemplate }];
+        }
+        return enabledLocales
+            .map((locale) => ({
+            locale,
+            template: localizedPaths[locale] ?? localizedPaths[defaultLocale] ?? page?.path ?? fallbackTemplate,
+        }))
+            .filter((item) => Boolean(item.template));
+    }
+    function pushEngineUrls(resolverKind, fallbackTemplate, slug, priority, changefreq) {
+        for (const { locale, template } of localizedTemplatesFor(resolverKind, fallbackTemplate)) {
+            const logicalPath = template.includes('{')
+                ? fillPathTemplate(template, { slug })
+                : template;
+            const loc = buildCanonicalUrl(website.domain, locale, logicalPath, defaultLocale);
+            entries.push(_urlEntry(loc, priority, changefreq, TODAY));
+        }
+    }
+    // 1. Content pages from the website manifest
+    for (const page of website.pages ?? []) {
+        if (SITEMAP_PRIVATE_KINDS.has(page.resolver_kind))
+            continue;
+        if (page.resolver_kind !== "content_page")
+            continue;
+        const localizedPaths = page.localized_paths ?? {};
+        const localesToEmit = Object.keys(localizedPaths).length > 0
+            ? enabledLocales.filter((locale) => localizedPaths[locale] || page.path)
+            : [defaultLocale];
+        for (const locale of localesToEmit) {
+            const path = localizedPaths[locale] ?? page.path;
+            if (!path)
+                continue;
+            const priority = path === "/" ? "1.0" : "0.8";
+            const changefreq = path === "/" ? "daily" : "weekly";
+            const loc = buildCanonicalUrl(website.domain, locale, path, defaultLocale);
+            entries.push(_urlEntry(loc, priority, changefreq, TODAY));
+        }
+    }
+    // 2. Category pages (recursive nav tree)
+    try {
+        const tree = await fetchCategoryNavTree({ baseUrl: apiUrl }, website);
+        function collectHrefs(nodes) {
+            for (const node of nodes) {
+                const slug = slugFromCatalogHref(node.href, 'categoria') ??
+                    slugFromCatalogHref(node.href, 'category') ??
+                    node.href.split('/').filter(Boolean).pop();
+                if (slug) {
+                    pushEngineUrls('category_detail', '/categoria/{slug}', slug, '0.8', 'daily');
+                }
+                else {
+                    entries.push(_urlEntry(`${siteUrl}${node.href}`, '0.8', 'daily', TODAY));
+                }
+                if (node.children.length > 0)
+                    collectHrefs(node.children);
+            }
+        }
+        collectHrefs(tree.nodes);
+    }
+    catch {
+        /* API offline — skip category URLs */
+    }
+    // 3. Brand pages
+    try {
+        const brandsResult = await fetchBrandsDirectory({ baseUrl: apiUrl }, website);
+        for (const brand of brandsResult.items) {
+            const slug = slugFromCatalogHref(brand.href, 'marca') ??
+                slugFromCatalogHref(brand.href, 'brand') ??
+                brand.slug;
+            if (slug) {
+                pushEngineUrls('brand_detail', '/marca/{slug}', slug, '0.7', 'weekly');
+            }
+            else {
+                entries.push(_urlEntry(`${siteUrl}${brand.href}`, '0.7', 'weekly', TODAY));
+            }
+        }
+    }
+    catch {
+        /* API offline — skip brand URLs */
+    }
+    // 4. Product pages (paginated)
+    try {
+        let currentPage = 1;
+        let totalPages = 1;
+        while (currentPage <= totalPages && currentPage <= MAX_PAGES) {
+            const result = await fetchStorefrontProducts({ baseUrl: apiUrl }, website, {
+                page: currentPage,
+                pageSize: PAGE_SIZE,
+            });
+            for (const product of result.items) {
+                pushEngineUrls('product_detail', '/producto/{slug}', product.slug, '0.9', 'weekly');
+            }
+            totalPages = result.pagination.total_pages;
+            currentPage++;
+        }
+    }
+    catch {
+        /* API offline — skip product URLs */
+    }
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+        ...entries,
+        "</urlset>",
+    ].join("\n");
+}
+//# sourceMappingURL=sitemap.js.map