@proxima-io/storefront-core 0.3.0 → 0.8.1

package/dist/index.js

@@ -1,1577 +1,41 @@
-// ---------------------------------------------------------------------------
-// Proxima Storefront Core SDK
-// ---------------------------------------------------------------------------
-// Single-file client for the Proxima API.  Import what you need:
-//   import { loginBuyer, fetchRegistrationForm, addToWishlist } from '@proxima-io/storefront-core';
-// ---------------------------------------------------------------------------
-/**
- * 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,
-    };
-}
-/**
- * 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) {
-    const siteUrl = `https://${website.domain}`;
-    const productUrl = `${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;
-}
-/** 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, "&amp;")
-        .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 entries = [];
-    // 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" && page.path) {
-            const priority = page.path === "/" ? "1.0" : "0.8";
-            const changefreq = page.path === "/" ? "daily" : "weekly";
-            entries.push(_urlEntry(`${siteUrl}${page.path}`, priority, changefreq, TODAY));
-        }
-    }
-    // 2. Category pages (recursive nav tree)
-    try {
-        // Lazy import to avoid circular dependency — fetchCategoryNavTree is defined below
-        const tree = await fetchCategoryNavTree({ baseUrl: apiUrl }, website);
-        function collectHrefs(nodes) {
-            for (const node of nodes) {
-                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) {
-            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) {
-                entries.push(_urlEntry(`${siteUrl}/producto/${product.slug}`, "0.9", "weekly", TODAY));
-            }
-            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");
-}
-/**
- * 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");
-}
-// ---------------------------------------------------------------------------
-// IndexNow — real-time URL change notifications
-// ---------------------------------------------------------------------------
-/**
- * Submit a list of changed URLs to the IndexNow API.
- *
- * IndexNow notifies Bing, Yandex, and (increasingly) Google about new or
- * updated pages so they are re-crawled within seconds instead of waiting for
- * the next sitemap crawl.
- *
- * **Setup (one-time per storefront):**
- * 1. Generate or reuse the key from `PROXIMA_INDEXNOW_KEY` env var.
- * 2. Serve `GET /{key}.txt` returning the key as plain text — see the scaffold
- *    template at `src/pages/[indexnow_key].txt.ts`.
- * 3. That's it — IndexNow verifies the key automatically on first submission.
- *
- * @param apiKey   Your IndexNow key (platform-level; served at `/{apiKey}.txt`)
- * @param siteUrl  Absolute origin of the site, e.g. `https://example.com`
- * @param urls     Absolute URLs that changed (max 10 000 per call)
- *
- * @example
- * await notifyIndexNow("my-secret-key", "https://214store.com", [
- *   "https://214store.com/producto/laptop-gamer",
- * ]);
- */
-export async function notifyIndexNow(apiKey, siteUrl, urls) {
-    if (!apiKey || urls.length === 0)
-        return;
-    const host = new URL(siteUrl).hostname;
-    const payload = {
-        host,
-        key: apiKey,
-        keyLocation: `${siteUrl}/${apiKey}.txt`,
-        urlList: urls,
-    };
-    try {
-        const resp = await fetch("https://api.indexnow.org/indexnow", {
-            method: "POST",
-            headers: { "Content-Type": "application/json; charset=utf-8" },
-            body: JSON.stringify(payload),
-        });
-        if (!resp.ok && resp.status !== 202) {
-            console.warn(`[IndexNow] Submission returned ${resp.status} for ${host}`);
-        }
-    }
-    catch (err) {
-        console.warn(`[IndexNow] Submission failed for ${host}:`, err);
-    }
-}
-/** List all websites for a service-key authenticated caller. Useful for build-time scripts. */
-export async function fetchProximaWebsiteList(config) {
-    const url = new URL("/api/v1/storefront/cms/websites", config.baseUrl);
-    const headers = {};
-    if (config.serviceKey)
-        headers["Authorization"] = `Bearer ${config.serviceKey}`;
-    const response = await fetch(url, { headers });
-    if (!response.ok)
-        throw new Error(`Website list failed: ${response.status}`);
-    return response.json();
-}
-/**
- * Resolve a website by domain/host. Call this once per request and cache the result.
- * Pass `host` if the incoming request host differs from `config.domain` (e.g. in middleware).
- *
- * @example
- * const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: Astro.url.hostname });
- */
-export async function fetchProximaWebsite(config) {
-    const url = new URL("/api/v1/storefront/cms/websites/resolve", config.baseUrl);
-    url.searchParams.set("host", config.host || config.domain);
-    const headers = {};
-    if (config.serviceKey)
-        headers["Authorization"] = `Bearer ${config.serviceKey}`;
-    const response = await fetch(url, { headers });
-    if (!response.ok)
-        throw new Error(`Website resolve failed: ${response.status}`);
-    return response.json();
-}
-/**
- * Build a synthetic `ProximaWebsiteResponse` for the visual builder preview.
- * Use this when the builder passes `websiteId` and `businessId` via query params
- * instead of resolving by domain.
- */
-export function makeBuilderPreviewWebsite(config) {
-    if (!config.websiteId || !config.businessId) {
-        throw new Error("Builder preview requires websiteId and businessId");
-    }
-    return {
-        id: config.websiteId,
-        business_id: config.businessId,
-        name: "Builder preview",
-        domain: config.domain,
-        delivery_mode: "custom_managed",
-        website_kind: "ecommerce",
-        template_key: null,
-        code_profile: null,
-        locale: "es",
-        currency: "PEN",
-        capabilities: {},
-        theme_tokens: {},
-        animation_config: {},
-        pages: [],
-    };
-}
-/**
- * Fetch the fully resolved page composition for the given path.
- * This is the main data-fetching call for every SSR page render.
- * The response embeds all section data (via smart collections) and, for detail pages,
- * the primary entity in `resolved_data` (product, category, brand, blog post).
- * No additional catalog API calls are needed for the initial render.
- *
- * @example
- * // src/pages/[...path].astro
- * const composition = await fetchProximaComposition(
- *   { ...config, path: Astro.url.pathname },
- *   website
- * );
- */
-export async function fetchProximaComposition(config, website) {
-    const locale = website.locale ?? "es";
-    const currency = website.currency ?? "PEN";
-    const url = new URL(`/api/v1/storefront/cms/websites/${website.id}/pages/composition`, config.baseUrl);
-    url.searchParams.set("path", config.path);
-    url.searchParams.set("locale", locale);
-    url.searchParams.set("business_id", website.business_id);
-    if (config.variantId)
-        url.searchParams.set("variant_id", config.variantId);
-    if (config.previewToken)
-        url.searchParams.set("preview_token", config.previewToken);
-    const headers = {
-        "X-Business-ID": website.business_id,
-        "Accept-Language": locale,
-        "X-Currency": currency,
-    };
-    if (config.serviceKey)
-        headers["Authorization"] = `Bearer ${config.serviceKey}`;
-    const response = await fetch(url, { headers });
-    if (!response.ok)
-        throw new Error(`Composition failed: ${response.status}`);
-    return response.json();
-}
-/**
- * @deprecated Use `fetchStorefrontProducts` instead. This function calls the raw
- * catalog endpoint (`/api/v1/products`) which is not enriched for storefront use
- * (no price_formatted, no badge, no default_variant_id). It will be removed in a future version.
- */
-export async function fetchProximaProducts(config, website) {
-    const url = new URL("/api/v1/products", config.baseUrl);
-    url.searchParams.set("size", "12");
-    const headers = {
-        "X-Business-ID": website.business_id,
-        "Accept-Language": website.locale ?? "es",
-        "X-Currency": website.currency ?? "PEN",
-    };
-    if (config.serviceKey)
-        headers["Authorization"] = `Bearer ${config.serviceKey}`;
-    const response = await fetch(url, { headers });
-    if (!response.ok)
-        throw new Error(`Products failed: ${response.status}`);
-    return response.json();
-}
-// ---------------------------------------------------------------------------
-// Error constants
-// ---------------------------------------------------------------------------
-/** Well-known error detail strings returned by the API. Use these for comparison
- *  instead of hardcoding strings in your storefront.
- *
- * @example
- * try { await resetPassword(...) } catch (e: any) {
- *   if (e.data?.detail === BUYER_AUTH_ERRORS.RESET_TOKEN_INVALID) { ... }
- * }
- */
-export const BUYER_AUTH_ERRORS = {
-    RESET_TOKEN_INVALID: "RESET_TOKEN_INVALID",
-    VERIFY_TOKEN_INVALID: "VERIFY_TOKEN_INVALID",
-    EMAIL_ALREADY_VERIFIED: "EMAIL_ALREADY_VERIFIED",
-    EMAIL_TAKEN: "Email already registered in this store",
-    MISSING_REQUIRED_FIELDS: "MISSING_REQUIRED_FIELDS",
-};
-/**
- * Thrown when the API returns 422 MISSING_REQUIRED_FIELDS.
- * Use `error.missingFields` to mark exactly which fields are invalid in the UI.
- *
- * @example
- * try {
- *   await registerBuyer(config, website, params);
- * } catch (e) {
- *   if (e instanceof MissingFieldsError) {
- *     for (const { field } of e.missingFields) markFieldError(field);
- *   }
- * }
- */
-export class MissingFieldsError extends Error {
-    status = 422;
-    missingFields;
-    constructor(missingFields) {
-        super("MISSING_REQUIRED_FIELDS");
-        this.name = "MissingFieldsError";
-        this.missingFields = missingFields;
-    }
-}
-/** Recommended options for the buyer session cookie. Apply to both `buyer_token` and `buyer_refresh_token`. */
-export const BUYER_COOKIE_OPTIONS = {
-    path: "/",
-    httpOnly: true,
-    sameSite: "lax",
-    maxAge: 60 * 60 * 24 * 7,
-};
-export const BUYER_COOKIE_NAME = "buyer_token";
-export const BUYER_REFRESH_COOKIE_NAME = "buyer_refresh_token";
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-function apiError(status, data) {
-    return Object.assign(new Error(`Request failed: ${status}`), { status, data });
-}
-function authHeaders(businessId, token) {
-    const h = { "X-Business-ID": businessId };
-    if (token)
-        h["Authorization"] = `Bearer ${token}`;
-    return h;
-}
-// ---------------------------------------------------------------------------
-// Registration Form
-// ---------------------------------------------------------------------------
-/**
- * Fetch the merchant-configured registration form schema.
- * Call this server-side in your /register page to know which fields to render
- * and which are required. `email` and `password` are always prepended by the API.
- *
- * @example
- * // src/pages/register.astro
- * const form = await fetchRegistrationForm({ baseUrl: env.apiUrl }, website);
- * // Pass `form` as a prop to a client component that renders the dynamic form
- */
-export async function fetchRegistrationForm(config, website) {
-    const url = new URL("/api/v1/store/auth/registration-form", config.baseUrl);
-    const res = await fetch(url, {
-        headers: { "X-Business-ID": website.business_id },
-    });
-    if (!res.ok) {
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    }
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Buyer Auth — client-side functions
-// ---------------------------------------------------------------------------
-/**
- * Register a new customer. The merchant decides which fields are required —
- * call fetchRegistrationForm() first to know what to collect.
- *
- * Throws MissingFieldsError when the merchant marked fields as required but
- * they were omitted, so you can mark exactly which inputs are invalid.
- *
- * @example
- * try {
- *   const session = await registerBuyer(config, website, { email, password, fullName });
- * } catch (e) {
- *   if (e instanceof MissingFieldsError) {
- *     e.missingFields.forEach(({ field }) => markError(field));
- *   }
- * }
- */
-export async function registerBuyer(config, website, params) {
-    const url = new URL("/api/v1/store/auth/register", config.baseUrl);
-    const body = {
-        email: params.email,
-        password: params.password,
-    };
-    if (params.fullName !== undefined)
-        body.full_name = params.fullName;
-    if (params.phone !== undefined)
-        body.phone = params.phone;
-    if (params.docType !== undefined)
-        body.doc_type = params.docType;
-    if (params.docNumber !== undefined)
-        body.doc_number = params.docNumber;
-    if (params.birthDate !== undefined)
-        body.birth_date = params.birthDate;
-    if (params.newsletterSubscribed !== undefined)
-        body.newsletter_subscribed = params.newsletterSubscribed;
-    if (params.registrationSource !== undefined)
-        body.registration_source = params.registrationSource;
-    if (params.metadata !== undefined)
-        body.metadata = params.metadata;
-    if (params.address !== undefined)
-        body.address = params.address;
-    if (params.captchaToken)
-        body.captcha_token = params.captchaToken;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-Business-ID": website.business_id },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok) {
-        const data = await res.json().catch(() => ({}));
-        // Parse MISSING_REQUIRED_FIELDS into structured MissingFieldsError
-        if (res.status === 422 && typeof data.detail === "string" && data.detail.startsWith("MISSING_REQUIRED_FIELDS:")) {
-            try {
-                const raw = data.detail.replace("MISSING_REQUIRED_FIELDS:", "").trim();
-                // API returns Python repr: [{'field': 'phone', 'msg': 'FIELD_REQUIRED'}, ...]
-                // Safe to JSON.parse after normalizing Python single-quotes
-                const normalized = raw.replace(/'/g, '"');
-                const missingFields = JSON.parse(normalized);
-                throw new MissingFieldsError(missingFields);
-            }
-            catch (e) {
-                if (e instanceof MissingFieldsError)
-                    throw e;
-                // If parsing failed, fall through to generic error
-            }
-        }
-        throw apiError(res.status, data);
-    }
-    return res.json();
-}
-/**
- * Authenticate a customer with email and password.
- * Returns a BuyerSession with access_token and refresh_token.
- * Throws { status: 401 } on wrong credentials.
- */
-export async function loginBuyer(config, website, params) {
-    const url = new URL("/api/v1/store/auth/login", config.baseUrl);
-    const body = { email: params.email, password: params.password };
-    if (params.captchaToken)
-        body.captcha_token = params.captchaToken;
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-Business-ID": website.business_id },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Invalidate the current session server-side. Best-effort — always clear the cookie too. */
-export async function logoutBuyer(config, website, params) {
-    const url = new URL("/api/v1/store/auth/logout", config.baseUrl);
-    await fetch(url, {
-        method: "POST",
-        headers: {
-            "Authorization": `Bearer ${params.token}`,
-            "X-Business-ID": website.business_id,
-        },
-    });
-}
-/**
- * Exchange a refresh token for a new access token.
- * Call this when you get a 401 on any authenticated request.
- * Throws { status: 401 } if the refresh token is expired or revoked.
- *
- * @example
- * // In Astro middleware:
- * try {
- *   const session = await refreshBuyerToken(config, website, { refreshToken });
- *   // Set new access_token cookie
- * } catch {
- *   // Clear both cookies, redirect to login
- * }
- */
-export async function refreshBuyerToken(config, website, params) {
-    const url = new URL("/api/v1/store/auth/refresh", config.baseUrl);
-    url.searchParams.set("refresh_token", params.refreshToken);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "X-Business-ID": website.business_id },
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Fetch the authenticated customer's full profile. */
-export async function fetchBuyerProfile(config, website, params) {
-    const url = new URL("/api/v1/store/me", config.baseUrl);
-    const res = await fetch(url, {
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Update the authenticated customer's profile. Only the fields you include
- * in `params` are changed — it's a partial update.
- */
-export async function updateBuyerProfile(config, website, params) {
-    const url = new URL("/api/v1/store/me/profile", config.baseUrl);
-    const body = {};
-    if (params.fullName !== undefined)
-        body.full_name = params.fullName;
-    if (params.phone !== undefined)
-        body.phone = params.phone;
-    if (params.docType !== undefined)
-        body.doc_type = params.docType;
-    if (params.docNumber !== undefined)
-        body.doc_number = params.docNumber;
-    if (params.birthDate !== undefined)
-        body.birth_date = params.birthDate;
-    if (params.newsletterSubscribed !== undefined)
-        body.newsletter_subscribed = params.newsletterSubscribed;
-    if (params.avatarUrl !== undefined)
-        body.avatar_url = params.avatarUrl;
-    if (params.password !== undefined)
-        body.password = params.password;
-    const res = await fetch(url, {
-        method: "PATCH",
-        headers: { "Content-Type": "application/json", ...authHeaders(website.business_id, params.token) },
-        body: JSON.stringify(body),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Password recovery & email verification
-// ---------------------------------------------------------------------------
-/**
- * Send a password reset email. Always resolves — even if the email doesn't exist.
- * Always show: "Si el email existe, recibirás un enlace para restablecer tu contraseña."
- */
-export async function forgotPassword(config, website, params) {
-    const url = new URL("/api/v1/store/auth/forgot-password", config.baseUrl);
-    const body = { email: params.email };
-    if (params.captchaToken)
-        body.captcha_token = params.captchaToken;
-    await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", "X-Business-ID": website.business_id },
-        body: JSON.stringify(body),
-    });
-}
-/**
- * Reset the customer's password using the token from the reset email link.
- * The token is the `?token=` query param in the reset URL.
- * On success, all active sessions are revoked — redirect to login.
- * Throws { status: 400, data.detail: BUYER_AUTH_ERRORS.RESET_TOKEN_INVALID } on bad token.
- */
-export async function resetPassword(config, params) {
-    const url = new URL("/api/v1/store/auth/reset-password", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ token: params.token, new_password: params.newPassword }),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-}
-/**
- * Verify the customer's email using the token from the verification email link.
- * Throws { status: 400, data.detail: BUYER_AUTH_ERRORS.VERIFY_TOKEN_INVALID } on bad token.
- */
-export async function verifyEmail(config, params) {
-    const url = new URL("/api/v1/store/auth/verify-email", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ token: params.token }),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-}
-/**
- * Re-send the email verification link. Requires the customer to be authenticated.
- * Throws { status: 400, data.detail: BUYER_AUTH_ERRORS.EMAIL_ALREADY_VERIFIED } if already verified.
- */
-export async function resendVerification(config, website, params) {
-    const url = new URL("/api/v1/store/auth/resend-verification", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-}
-// ---------------------------------------------------------------------------
-// Storefront catalog — search & listings (client-side interactions)
-// ---------------------------------------------------------------------------
-// Internal helper: builds the Accept-Language + X-Currency + X-Business-ID headers
-function storefrontHeaders(businessId, locale, currency) {
-    const h = { "X-Business-ID": businessId };
-    if (locale)
-        h["Accept-Language"] = locale;
-    if (currency)
-        h["X-Currency"] = currency;
-    return h;
-}
-/**
- * Search products by query string. Use this for the search bar, autocomplete,
- * and search results pages — `resolved_data` for a `search` page is intentionally
- * null; query results must be fetched directly.
- *
- * @example
- * const results = await searchStorefront(config, website, { q: 'zapatillas', limit: 10 });
- */
-export async function searchStorefront(config, website, params) {
-    const url = new URL("/api/v1/storefront/search", config.baseUrl);
-    url.searchParams.set("q", params.q);
-    if (params.limit !== undefined)
-        url.searchParams.set("limit", String(params.limit));
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale, params.currency ?? website.currency),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch the general product listing with optional filters and pagination.
- * Use this for client-side filter/sort/paginate interactions on the all-products page.
- * The initial page render is handled by the composition — call this for subsequent
- * filter changes and page turns.
- */
-export async function fetchStorefrontProducts(config, website, params = {}) {
-    const url = new URL("/api/v1/storefront/products", config.baseUrl);
-    if (params.page)
-        url.searchParams.set("page", String(params.page));
-    if (params.pageSize)
-        url.searchParams.set("page_size", String(params.pageSize));
-    if (params.sort)
-        url.searchParams.set("sort", params.sort);
-    if (params.brand)
-        url.searchParams.set("brand", params.brand);
-    if (params.category)
-        url.searchParams.set("category", params.category);
-    if (params.q)
-        url.searchParams.set("q", params.q);
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale, params.currency ?? website.currency),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch paginated + filtered products for a category page (CLP).
- * Use this for client-side filter/sort/paginate after the initial SSR render
- * (which arrives in `resolved_data` from `fetchProximaComposition`).
- */
-export async function fetchCategoryProducts(config, website, params) {
-    const url = new URL(`/api/v1/storefront/categories/${encodeURIComponent(params.slug)}/products`, config.baseUrl);
-    if (params.page)
-        url.searchParams.set("page", String(params.page));
-    if (params.pageSize)
-        url.searchParams.set("page_size", String(params.pageSize));
-    if (params.sort)
-        url.searchParams.set("sort", params.sort);
-    if (params.brand)
-        url.searchParams.set("brand", params.brand);
-    if (params.q)
-        url.searchParams.set("q", params.q);
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale, params.currency ?? website.currency),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch paginated + filtered products for a brand page (BLP).
- * Use this for client-side filter/sort/paginate after the initial SSR render
- * (which arrives in `resolved_data` from `fetchProximaComposition`).
- */
-export async function fetchBrandProducts(config, website, params) {
-    const url = new URL(`/api/v1/storefront/brands/${encodeURIComponent(params.slug)}/products`, config.baseUrl);
-    if (params.page)
-        url.searchParams.set("page", String(params.page));
-    if (params.pageSize)
-        url.searchParams.set("page_size", String(params.pageSize));
-    if (params.sort)
-        url.searchParams.set("sort", params.sort);
-    if (params.category)
-        url.searchParams.set("category", params.category);
-    if (params.q)
-        url.searchParams.set("q", params.q);
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale, params.currency ?? website.currency),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch the full category directory (all categories with product counts).
- * Useful for navigation menus and sitemap generation.
- * For section-level category carousels, use smart collections via composition instead.
- */
-export async function fetchCategoriesDirectory(config, website, params = {}) {
-    const url = new URL("/api/v1/storefront/categories", config.baseUrl);
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch the full category hierarchy as a recursive tree.
- * Use this for data-driven mega menus — it returns nested `children[]`
- * with `/categoria/{slug}` hrefs ready to render.
- *
- * @param maxDepth - Maximum tree depth (1–5, default 3)
- */
-export async function fetchCategoryNavTree(config, website, params = {}) {
-    const url = new URL("/api/v1/storefront/categories/tree", config.baseUrl);
-    if (params.maxDepth !== undefined)
-        url.searchParams.set("max_depth", String(params.maxDepth));
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Fetch the full brand directory (all brands with product counts).
- * Useful for navigation menus and sitemap generation.
- */
-export async function fetchBrandsDirectory(config, website, params = {}) {
-    const url = new URL("/api/v1/storefront/brands", config.baseUrl);
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, params.locale ?? website.locale),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Cart
-// ---------------------------------------------------------------------------
-function cartHeaders(businessId, token, sessionId) {
-    const h = { "X-Business-ID": businessId };
-    if (token)
-        h["Authorization"] = `Bearer ${token}`;
-    if (sessionId && !token)
-        h["X-Session-ID"] = sessionId;
-    return h;
-}
-/** Fetch the current cart. Works for both guest sessions and authenticated customers. */
-export async function fetchCart(config, website, params) {
-    const url = new URL("/api/v1/cart", config.baseUrl);
-    const res = await fetch(url, { headers: cartHeaders(website.business_id, params.token, params.sessionId) });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Add a product variant to the cart. Use `StorefrontProductSummary.default_variant_id`
- * as `variantId` when adding from a listing card.
- */
-export async function addToCart(config, website, params) {
-    const url = new URL("/api/v1/cart/items", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...cartHeaders(website.business_id, params.token, params.sessionId) },
-        body: JSON.stringify({ product_variant_id: params.variantId, quantity: params.quantity }),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Update the quantity of an existing cart item. Set `quantity` to 0 to remove it. */
-export async function updateCartItem(config, website, params) {
-    const url = new URL(`/api/v1/cart/items/${params.variantId}`, config.baseUrl);
-    const res = await fetch(url, {
-        method: "PATCH",
-        headers: { "Content-Type": "application/json", ...cartHeaders(website.business_id, params.token, params.sessionId) },
-        body: JSON.stringify({ quantity: params.quantity }),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Remove a product variant from the cart entirely. */
-export async function removeCartItem(config, website, params) {
-    const url = new URL(`/api/v1/cart/items/${params.variantId}`, config.baseUrl);
-    const res = await fetch(url, {
-        method: "DELETE",
-        headers: cartHeaders(website.business_id, params.token, params.sessionId),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Merge a guest cart (identified by session ID) into the authenticated customer's cart.
- * Call this immediately after a successful login if there is an active guest session.
- *
- * @example
- * const sessionId = localStorage.getItem('proxima_session_id');
- * if (sessionId) await mergeGuestCart(config, website, { token, sessionId });
- */
-export async function mergeGuestCart(config, website, params) {
-    const url = new URL("/api/v1/cart/merge", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: {
-            "X-Business-ID": website.business_id,
-            "X-Session-ID": params.sessionId,
-            "Authorization": `Bearer ${params.token}`,
-        },
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Validate a coupon code before checkout. Always resolves — check `result.valid`.
- * Use the `discount_amount` from the result to preview the discount in the UI.
- *
- * @example
- * const result = await validateCoupon(config, website, { code: 'PROMO10', amount: 150.00 });
- * if (result.valid) showDiscount(result.discount_amount);
- * else showError(result.error);
- */
-export async function validateCoupon(config, website, params) {
-    const url = new URL("/api/v1/commerce/coupons/validate", config.baseUrl);
-    url.searchParams.set("code", params.code);
-    url.searchParams.set("amount", String(params.amount));
-    const res = await fetch(url, {
-        headers: { "X-Business-ID": website.business_id },
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Orders
-// ---------------------------------------------------------------------------
-/**
- * Submit the current cart as an order (checkout). The cart must be non-empty.
- * On success the cart is cleared. Throws 400 on validation errors (e.g. out of stock).
- */
-export async function createOrder(config, website, params) {
-    const url = new URL("/api/v1/checkout", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...cartHeaders(website.business_id, params.token) },
-        body: JSON.stringify(params.checkout),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Fetch the authenticated customer's order history, paginated. */
-export async function fetchOrders(config, website, params) {
-    const url = new URL("/api/v1/store/me/orders", config.baseUrl);
-    if (params.page)
-        url.searchParams.set("page", String(params.page));
-    if (params.size)
-        url.searchParams.set("size", String(params.size));
-    const res = await fetch(url, {
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/** Fetch a single order by ID. Works for authenticated customers and guests with the receipt token. */
-export async function fetchOrder(config, website, params) {
-    const url = new URL(`/api/v1/orders/${params.orderId}`, config.baseUrl);
-    const res = await fetch(url, {
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Address Book
-// ---------------------------------------------------------------------------
-/** Fetch all saved addresses for the authenticated customer. */
-export async function fetchCustomerAddresses(config, website, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/store/me/addresses/`, {
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw new Error(`fetchCustomerAddresses failed: ${res.status}`);
-    return res.json();
-}
-/** Save a new address to the customer's address book. */
-export async function createCustomerAddress(config, website, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/store/me/addresses/`, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...authHeaders(website.business_id, params.token) },
-        body: JSON.stringify(params.address),
-    });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw Object.assign(new Error("createCustomerAddress failed"), { status: res.status, detail: err.detail });
-    }
-    return res.json();
-}
-/** Partially update a saved address. Only the fields included in `address` are changed. */
-export async function updateCustomerAddress(config, website, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/store/me/addresses/${params.addressId}`, {
-        method: "PATCH",
-        headers: { "Content-Type": "application/json", ...authHeaders(website.business_id, params.token) },
-        body: JSON.stringify(params.address),
-    });
-    if (!res.ok) {
-        const err = await res.json().catch(() => ({}));
-        throw Object.assign(new Error("updateCustomerAddress failed"), { status: res.status, detail: err.detail });
-    }
-    return res.json();
-}
-/** Delete a saved address. Throws if the address does not exist. */
-export async function deleteCustomerAddress(config, website, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/store/me/addresses/${params.addressId}`, {
-        method: "DELETE",
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok && res.status !== 204)
-        throw new Error(`deleteCustomerAddress failed: ${res.status}`);
-}
-/** Mark an address as the customer's default. The previous default is unset automatically. */
-export async function setDefaultAddress(config, website, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/store/me/addresses/${params.addressId}/default`, {
-        method: "POST",
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw new Error(`setDefaultAddress failed: ${res.status}`);
-    return res.json();
-}
-/**
- * Search Peruvian ubigeo codes (department/province/district) by name.
- * Use this to power the address form's location selector.
- * Returns an empty array on error instead of throwing.
- */
-export async function searchUbigeo(config, params) {
-    const res = await fetch(`${config.baseUrl}/api/v1/catalog/locations/ubigeos?q=${encodeURIComponent(params.q)}`);
-    if (!res.ok)
-        return [];
-    return res.json();
-}
-// ---------------------------------------------------------------------------
-// Wishlist
-// ---------------------------------------------------------------------------
-/**
- * Fetch all wishlist items for the authenticated customer.
- * Returns an empty array if the wishlist is empty.
- */
-export async function fetchWishlist(config, website, params) {
-    const url = new URL("/api/v1/store/me/wishlist", config.baseUrl);
-    const res = await fetch(url, {
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Add a product to the wishlist. Idempotent — if the product is already
- * in the wishlist, returns the existing item without creating a duplicate.
- */
-export async function addToWishlist(config, website, params) {
-    const url = new URL("/api/v1/store/me/wishlist", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...authHeaders(website.business_id, params.token) },
-        body: JSON.stringify({
-            product_id: params.productId,
-            variant_id: params.variantId ?? null,
-            notes: params.notes ?? null,
-        }),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-/**
- * Remove a product from the wishlist.
- * Throws { status: 404 } if the product was not in the wishlist.
- */
-export async function removeFromWishlist(config, website, params) {
-    const url = new URL(`/api/v1/store/me/wishlist/${params.productId}`, config.baseUrl);
-    const res = await fetch(url, {
-        method: "DELETE",
-        headers: authHeaders(website.business_id, params.token),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-}
-// ---------------------------------------------------------------------------
-// Server-side Handler Helpers (for Astro API routes)
-//
-// These orchestrators combine fetchProximaWebsite + SDK calls so that Astro
-// API routes become thin wrappers (~10 lines) that only deal with cookies
-// and redirects. Use them in `src/pages/api/buyer/**` files.
-// ---------------------------------------------------------------------------
-/**
- * Resolve the website then call loginBuyer.
- * Returns { access_token, refresh_token, next } on success, throws on failure.
- */
-export async function processBuyerLogin(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    const session = await loginBuyer({ baseUrl: env.apiUrl }, website, { email: params.email, password: params.password, captchaToken: params.captchaToken });
-    return { access_token: session.access_token, refresh_token: session.refresh_token ?? null, next: params.next || "/" };
-}
-/**
- * Resolve the website then call registerBuyer.
- * Returns { access_token, refresh_token, next } on success, throws on failure.
- * Propagates MissingFieldsError so the API route can return structured 422 errors.
- */
-export async function processBuyerRegister(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    const { next, ...registerParams } = params;
-    const session = await registerBuyer({ baseUrl: env.apiUrl }, website, registerParams);
-    return { access_token: session.access_token, refresh_token: session.refresh_token ?? null, next: next || "/" };
-}
-/**
- * Call logoutBuyer (best-effort — never throws).
- * Always clear the session cookie regardless of the result.
- */
-export async function processBuyerLogout(env, params) {
-    try {
-        const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-        await logoutBuyer({ baseUrl: env.apiUrl }, website, { token: params.token });
-    }
-    catch {
-        // Best-effort — caller must always clear the cookie regardless
-    }
-}
-/**
- * Resolve the website then exchange a refresh token for a new access token.
- * Use this in Astro middleware to silently refresh expired sessions.
- * Throws { status: 401 } if the refresh token is expired — clear cookies and redirect to login.
- */
-export async function processRefreshToken(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    const session = await refreshBuyerToken({ baseUrl: env.apiUrl }, website, { refreshToken: params.refreshToken });
-    return { access_token: session.access_token, refresh_token: session.refresh_token ?? null };
-}
-/**
- * Resolve the website then send a password reset email.
- * Never throws — always show a generic confirmation message.
- */
-export async function processForgotPassword(env, params) {
-    try {
-        const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-        await forgotPassword({ baseUrl: env.apiUrl }, website, { email: params.email, captchaToken: params.captchaToken });
-    }
-    catch {
-        // Never expose whether the email exists
-    }
-}
-/**
- * Reset the customer's password with the token from the email link.
- * Throws { status: 400, data.detail: BUYER_AUTH_ERRORS.RESET_TOKEN_INVALID } on bad token.
- */
-export async function processResetPassword(env, params) {
-    await resetPassword({ baseUrl: env.apiUrl }, params);
-}
-/**
- * Verify the customer's email with the token from the email link.
- * Throws { status: 400, data.detail: BUYER_AUTH_ERRORS.VERIFY_TOKEN_INVALID } on bad token.
- */
-export async function processVerifyEmail(env, params) {
-    await verifyEmail({ baseUrl: env.apiUrl }, params);
-}
-/**
- * Resolve the website then add a variant to the cart.
- * Token is optional (guest cart supported).
- */
-export async function processAddToCart(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return addToCart({ baseUrl: env.apiUrl }, website, { token: params.token, sessionId: params.sessionId, variantId: params.variantId, quantity: params.quantity });
-}
-/**
- * Resolve the website then remove a variant from the cart.
- * Token is optional (guest cart supported).
- */
-export async function processRemoveCartItem(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return removeCartItem({ baseUrl: env.apiUrl }, website, { token: params.token, sessionId: params.sessionId, variantId: params.variantId });
-}
-/**
- * Resolve the website then update the quantity of a variant in the cart.
- * Token is optional (guest cart supported).
- */
-export async function processUpdateCartItem(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return updateCartItem({ baseUrl: env.apiUrl }, website, { token: params.token, sessionId: params.sessionId, variantId: params.variantId, quantity: params.quantity });
-}
-/**
- * Resolve the website then fetch the current cart.
- * Token is optional (guest cart supported).
- */
-export async function processGetCart(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return fetchCart({ baseUrl: env.apiUrl }, website, { token: params.token, sessionId: params.sessionId });
-}
-/**
- * Resolve the website then call POST /checkout.
- * Returns { orderId } on success, throws on failure.
- */
-export async function processBuyerCheckout(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    const order = await createOrder({ baseUrl: env.apiUrl }, website, { token: params.token, checkout: params.checkout });
-    return { orderId: order.id };
-}
-/** Resolve website then set the customer's default address. */
-export async function processSetDefaultAddress(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return setDefaultAddress({ baseUrl: env.apiUrl }, website, params);
-}
-/** Resolve website then delete a saved address. */
-export async function processDeleteAddress(env, params) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return deleteCustomerAddress({ baseUrl: env.apiUrl }, website, params);
-}
-/**
- * Fetch a filtered, sorted, paginated product listing.
- * Extends fetchStorefrontProducts with price range and stock filters.
- */
-export async function fetchProductListing(config, website, params = {}) {
-    const url = new URL("/api/v1/storefront/products", config.baseUrl);
-    if (params.filters?.brand)
-        url.searchParams.set("brand", params.filters.brand);
-    if (params.filters?.category)
-        url.searchParams.set("category", params.filters.category);
-    if (params.filters?.price_min != null)
-        url.searchParams.set("price_min", String(params.filters.price_min));
-    if (params.filters?.price_max != null)
-        url.searchParams.set("price_max", String(params.filters.price_max));
-    if (params.filters?.in_stock)
-        url.searchParams.set("in_stock", "true");
-    if (params.sort)
-        url.searchParams.set("sort", params.sort);
-    if (params.page)
-        url.searchParams.set("page", String(params.page));
-    if (params.page_size)
-        url.searchParams.set("page_size", String(params.page_size));
-    const res = await fetch(url, {
-        headers: storefrontHeaders(website.business_id, website.locale, website.currency),
-    });
-    if (!res.ok)
-        throw apiError(res.status, await res.json().catch(() => ({})));
-    return res.json();
-}
-export class GuestOrderError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.code = code;
-        this.name = "GuestOrderError";
-    }
-}
-/**
- * Create an order without buyer authentication.
- * The cart is identified by `session_id` (from the storefront session cookie).
- * Throws `GuestOrderError` for typed error cases.
- */
-export async function initiateGuestOrder(config, website, payload) {
-    const { session_id, ...checkout } = payload;
-    const url = new URL("/api/v1/checkout", config.baseUrl);
-    const res = await fetch(url, {
-        method: "POST",
-        headers: {
-            "Content-Type": "application/json",
-            "X-Business-ID": website.business_id,
-            "X-Session-ID": session_id,
-        },
-        body: JSON.stringify(checkout),
-    });
-    if (!res.ok) {
-        const body = await res.json().catch(() => ({}));
-        const detail = body?.detail ?? "";
-        if (detail === "Cart is empty" || detail === "Cart not found") {
-            throw new GuestOrderError("CART_NOT_FOUND", detail);
-        }
-        if (typeof detail === "object" && detail?.code === "OUT_OF_STOCK") {
-            throw new GuestOrderError("OUT_OF_STOCK", "Some items are out of stock");
-        }
-        throw new GuestOrderError("SERVER_ERROR", String(detail || res.status));
-    }
-    const order = await res.json();
-    return { orderId: order.id };
-}
-/**
- * Resolve website then call initiateGuestOrder.
- * Server-side helper for Astro API routes.
- */
-export async function processGuestCheckout(env, payload) {
-    const website = await fetchProximaWebsite({ baseUrl: env.apiUrl, domain: env.domain, serviceKey: env.serviceKey });
-    return initiateGuestOrder({ baseUrl: env.apiUrl }, website, payload);
-}
-class ProximaAnalytics {
-    config = null;
-    queue = [];
-    preInitQueue = [];
-    timer = null;
-    initialized = false;
-    init(config) {
-        if (typeof window === 'undefined')
-            return;
-        this.config = config;
-        if (this.initialized)
-            return;
-        this.initialized = true;
-        for (const [type, payload] of this.preInitQueue.splice(0)) {
-            this.track(type, payload);
-        }
-        const firePageView = () => this.track('page_view');
-        firePageView();
-        document.addEventListener('astro:page-load', firePageView);
-        const interval = config.flushInterval ?? 3000;
-        this.timer = setInterval(() => this.flush(), interval);
-        document.addEventListener('visibilitychange', () => {
-            if (document.visibilityState === 'hidden')
-                this.flush(true);
-        });
-    }
-    track(type, payload = {}) {
-        if (typeof window === 'undefined')
-            return;
-        if (!this.config) {
-            this.preInitQueue.push([type, payload]);
-            return;
-        }
-        const event = {
-            event_type: type,
-            occurred_at: new Date().toISOString(),
-            website_id: this.config.websiteId,
-            path: window.location.pathname,
-            referrer: document.referrer || undefined,
-            locale: this.config.locale,
-            payload,
-        };
-        this.queue.push(event);
-        if (this.config.debug)
-            console.debug('[proxima:analytics] queued', event);
-    }
-    flush(beacon = false) {
-        if (!this.config || this.queue.length === 0)
-            return;
-        const batch = this.queue.splice(0);
-        const url = `${this.config.apiUrl}/api/v1/store/events`;
-        const body = JSON.stringify({ events: batch });
-        const headers = { 'Content-Type': 'application/json', 'X-Business-ID': this.config.businessId };
-        if (this.config.debug)
-            console.debug(`[proxima:analytics] flushing ${batch.length} event(s)`);
-        if (beacon && typeof navigator !== 'undefined' && navigator.sendBeacon) {
-            const blob = new Blob([body], { type: 'application/json' });
-            const sent = navigator.sendBeacon(url, blob);
-            if (!sent)
-                this.queue.unshift(...batch);
-            return;
-        }
-        fetch(url, { method: 'POST', headers, body, keepalive: true }).catch(() => { });
-    }
-    destroy() {
-        if (this.timer !== null)
-            clearInterval(this.timer);
-        this.timer = null;
-        this.initialized = false;
-        this.config = null;
-        this.queue = [];
-        this.preInitQueue = [];
-    }
-}
-/** Singleton analytics client. Call `analytics.init()` once from SiteLayout. */
-export const analytics = new ProximaAnalytics();
-export { createFixtureBundle, createStorefrontDataSource, validateFixtureBundle, resolveStorefrontDataSourceForRequest, FixtureGuestOrderError, } from "./fixtures-commerce.js";
+// Proxima Storefront Core SDK — barrel re-exports
+export * from './types/cms.js';
+export * from './types/seo.js';
+export * from './types/business.js';
+export * from './types/buyer.js';
+export * from './types/catalog.js';
+export * from './types/cart.js';
+export * from './types/order.js';
+export * from './types/address.js';
+export * from './types/wishlist.js';
+export * from './types/server-env.js';
+export * from './types/listing.js';
+export * from './types/guest-order.js';
+export * from './types/campaign.js';
+export * from './types/analytics.js';
+export * from './types/cookie-consent.js';
+export * from './api/index.js';
+export * from './seo/page-seo.js';
+export * from './seo/json-ld.js';
+export * from './seo/sitemap.js';
+export * from './seo/robots.js';
+export * from './seo/indexnow.js';
+export * from './cms/website.js';
+export * from './cms/payment-methods.js';
+export * from './buyer/auth.js';
+export * from './catalog/listings.js';
+export * from './cart/cart.js';
+export * from './orders/orders.js';
+export * from './orders/guest.js';
+export * from './addresses/address-book.js';
+export * from './wishlist/wishlist.js';
+export * from './server/process.js';
+export * from './campaign/countdown.js';
+export { analytics } from './analytics/analytics.js';
+export { resolveAnalyticsSessionId, ANALYTICS_SESSION_STORAGE_KEY } from './analytics/session.js';
+export { captureSessionAttribution, getSessionAttribution, clearSessionAttribution, inferAttributionFromReferrer, ATTRIBUTION_STORAGE_KEY, } from './analytics/attribution.js';
+export { createStorefrontAnalyticsTrackers } from './analytics/trackers.js';
+export * from './cookie-consent/consent.js';
+export * from './cache/cache.js';
+export { createFixtureBundle, createStorefrontDataSource, validateFixtureBundle, resolveStorefrontDataSourceForRequest, FixtureGuestOrderError, } from './fixtures-commerce.js';
 //# sourceMappingURL=index.js.map