@asstio-dev/storefront 0.7.0 → 0.11.0

package/dist/seo/breadcrumb.d.ts

@@ -0,0 +1,9 @@
+import type { BreadcrumbLink, CollectionCrumbDto, JsonLd } from "./types.js";
+/**
+ * schema.org `BreadcrumbList` (spec §4.18): optional `home`, the API's ancestor crumbs root first, optional `current`
+ * (on a collection page `{ name: r.collection.name, url: r.collection.url }`). `null` below two items (Google's minimum).
+ */
+export declare function breadcrumbJsonLd(crumbs: CollectionCrumbDto[], opts?: {
+    home?: BreadcrumbLink;
+    current?: BreadcrumbLink;
+}): JsonLd | null;

package/dist/seo/breadcrumb.js

@@ -0,0 +1,18 @@
+/**
+ * schema.org `BreadcrumbList` (spec §4.18): optional `home`, the API's ancestor crumbs root first, optional `current`
+ * (on a collection page `{ name: r.collection.name, url: r.collection.url }`). `null` below two items (Google's minimum).
+ */
+export function breadcrumbJsonLd(crumbs, opts = {}) {
+    const trail = [
+        ...(opts.home ? [opts.home] : []),
+        ...crumbs.map((c) => ({ name: c.name, url: c.url })),
+        ...(opts.current ? [opts.current] : []),
+    ];
+    if (trail.length < 2)
+        return null;
+    return {
+        "@context": "https://schema.org",
+        "@type": "BreadcrumbList",
+        itemListElement: trail.map((t, i) => ({ "@type": "ListItem", position: i + 1, name: t.name, item: t.url })),
+    };
+}

package/dist/seo/head.d.ts

@@ -0,0 +1,10 @@
+import type { BrandDetailDto, CollectionHeadOptions, CollectionListingResponse, HeadOptions, NextMetadataLike, ProductDto, SeoHead } from "./types.js";
+export declare function productHead(p: ProductDto, ctx: HeadOptions): SeoHead;
+/** A collection has no description or image in the API; pass `description` yourself if the page has one. */
+export declare function collectionHead(r: CollectionListingResponse, ctx: CollectionHeadOptions): SeoHead;
+export declare function brandHead(b: BrandDetailDto, ctx: HeadOptions): SeoHead;
+/**
+ * `SeoHead` → the Next.js `Metadata` shape (spec §6.5), built from the head alone so the two never disagree. Titles are
+ * `{ absolute }` so a parent layout's `title.template` does not apply twice (review #17). Missing values are omitted.
+ */
+export declare function toNextMetadata(h: SeoHead): NextMetadataLike;

package/dist/seo/head.js

@@ -0,0 +1,101 @@
+import { alternateSet, collapse, headDescription, pickImages, productDescription, rejectRedirect, requireMarket } from "./shared.js";
+const applyTemplate = (template, title) => (template === undefined ? title : template.replace("%s", () => title));
+/** Spec §6.4. Meta order is fixed; a tag whose value is null is left out. */
+function buildHead(ctx, input) {
+    const set = alternateSet(ctx.site, ctx.market, input.url, input.alternateUrls, ctx.xDefault);
+    const meta = [];
+    const name = (n, content) => {
+        if (content !== null)
+            meta.push({ name: n, content });
+    };
+    const prop = (p, content) => {
+        if (content !== null)
+            meta.push({ property: p, content });
+    };
+    const img = input.image;
+    name("description", input.description);
+    // Always `website`: Next.js has no `product` Open Graph type and its renderer throws on one (review #2).
+    prop("og:type", "website");
+    prop("og:title", input.title);
+    prop("og:description", input.description);
+    prop("og:url", input.url);
+    prop("og:site_name", ctx.site.name);
+    prop("og:locale", set.locale);
+    for (const l of set.alternateLocales)
+        prop("og:locale:alternate", l);
+    if (img) {
+        prop("og:image", img.url);
+        if (img.height !== undefined) {
+            prop("og:image:width", String(img.width));
+            prop("og:image:height", String(img.height));
+        }
+        prop("og:image:alt", img.alt);
+    }
+    name("twitter:card", img ? "summary_large_image" : "summary");
+    name("twitter:title", input.title);
+    name("twitter:description", input.description);
+    name("twitter:image", img ? img.url : null);
+    return { title: applyTemplate(ctx.titleTemplate, input.title), description: input.description, canonical: input.url, alternates: set.alternates, meta };
+}
+export function productHead(p, ctx) {
+    rejectRedirect(p, `product ${p.sku}`);
+    const market = requireMarket(ctx.site, ctx.market);
+    const [image] = pickImages(ctx.site, p.images, market.language, p.name, 1);
+    return buildHead(ctx, { title: p.seo.title, description: headDescription(productDescription(p)), url: p.url, alternateUrls: p.alternateUrls, image: image ?? null });
+}
+/** A collection has no description or image in the API; pass `description` yourself if the page has one. */
+export function collectionHead(r, ctx) {
+    requireMarket(ctx.site, ctx.market);
+    return buildHead(ctx, { title: r.collection.name, description: headDescription(collapse(ctx.description)), url: r.collection.url, alternateUrls: r.alternateUrls, image: null });
+}
+export function brandHead(b, ctx) {
+    rejectRedirect(b, `brand ${b.slug}`);
+    const market = requireMarket(ctx.site, ctx.market);
+    const [image] = b.logo ? pickImages(ctx.site, [b.logo], market.language, b.name, 1) : [];
+    return buildHead(ctx, { title: b.name, description: headDescription(collapse(b.description?.text)), url: b.url, alternateUrls: b.alternateUrls, image: image ?? null });
+}
+const metaKey = (m) => ("property" in m ? m.property : m.name);
+/** `{ [k]: v }` when `v` is defined, else `{}` — so a missing value is an absent key, never `null`/`undefined`. */
+const opt = (k, v) => (v === undefined ? {} : { [k]: v });
+/**
+ * `SeoHead` → the Next.js `Metadata` shape (spec §6.5), built from the head alone so the two never disagree. Titles are
+ * `{ absolute }` so a parent layout's `title.template` does not apply twice (review #17). Missing values are omitted.
+ */
+export function toNextMetadata(h) {
+    const get = (k) => h.meta.find((m) => metaKey(m) === k)?.content;
+    const all = (k) => h.meta.filter((m) => metaKey(m) === k).map((m) => m.content);
+    const ogImage = get("og:image");
+    const width = get("og:image:width");
+    const height = get("og:image:height");
+    const alternateLocale = all("og:locale:alternate");
+    const twitterImage = get("twitter:image");
+    return {
+        title: { absolute: h.title },
+        ...opt("description", h.description ?? undefined),
+        alternates: {
+            canonical: h.canonical,
+            ...opt("languages", h.alternates.length > 0 ? Object.fromEntries(h.alternates.map((a) => [a.hreflang, a.href])) : undefined),
+        },
+        openGraph: {
+            type: "website",
+            title: { absolute: get("og:title") ?? h.title },
+            ...opt("description", get("og:description")),
+            url: get("og:url") ?? h.canonical,
+            ...opt("siteName", get("og:site_name")),
+            ...opt("locale", get("og:locale")),
+            ...opt("alternateLocale", alternateLocale.length > 0 ? alternateLocale : undefined),
+            ...opt("images", ogImage === undefined ? undefined : [{
+                    url: ogImage,
+                    ...opt("width", width === undefined ? undefined : Number(width)),
+                    ...opt("height", height === undefined ? undefined : Number(height)),
+                    ...opt("alt", get("og:image:alt")),
+                }]),
+        },
+        twitter: {
+            card: get("twitter:card") === "summary_large_image" ? "summary_large_image" : "summary",
+            title: { absolute: get("twitter:title") ?? h.title },
+            ...opt("description", get("twitter:description")),
+            ...opt("images", twitterImage === undefined ? undefined : [twitterImage]),
+        },
+    };
+}

package/dist/seo/locales.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Market → locale for hreflang and Open Graph (spec 2026-10-06 §4.19).
+ *
+ * Embedded tables, read 2026-10-07:
+ * - ISO 639-1: the two-letter column of the ISO 639-2 Registration Authority list (Library of Congress,
+ *   https://www.loc.gov/standards/iso639-2/php/code_list.php), 183 codes; `bh` (withdrawn) and `sh` (deprecated) left out.
+ * - ISO 3166-1 alpha-2: the 249 officially assigned codes (ISO Online Browsing Platform). Reserved codes (UK, EU, AC,
+ *   XK, …) are not assigned and are absent on purpose.
+ */
+export declare const ISO_639_1: ReadonlySet<string>;
+export declare const ISO_3166_1: ReadonlySet<string>;
+export type MarketLocale = {
+    language: string;
+    script?: string;
+    country: string;
+};
+/** `null` = the market has no valid locale and is left out of everything language-dependent. No alias
+ *  canonicalization: `iw`, `in`, `UK` are simply not in the tables. */
+export declare function normalizeLocale(market: {
+    language: string;
+    country: string;
+}): MarketLocale | null;
+/** `language[-Script]-COUNTRY`: `sv-SE`, `zh-Hant-TW`. */
+export declare const hreflang: (l: MarketLocale) => string;
+/** Open Graph `language_TERRITORY`, script dropped: `zh_TW`. Never derived from `hreflang` by separator replacement. */
+export declare const ogLocale: (l: MarketLocale) => string;

package/dist/seo/locales.js

@@ -0,0 +1,95 @@
+/**
+ * Market → locale for hreflang and Open Graph (spec 2026-10-06 §4.19).
+ *
+ * Embedded tables, read 2026-10-07:
+ * - ISO 639-1: the two-letter column of the ISO 639-2 Registration Authority list (Library of Congress,
+ *   https://www.loc.gov/standards/iso639-2/php/code_list.php), 183 codes; `bh` (withdrawn) and `sh` (deprecated) left out.
+ * - ISO 3166-1 alpha-2: the 249 officially assigned codes (ISO Online Browsing Platform). Reserved codes (UK, EU, AC,
+ *   XK, …) are not assigned and are absent on purpose.
+ */
+const codes = (lines) => new Set(lines.join(" ").split(" "));
+export const ISO_639_1 = codes([
+    "aa ab ae af ak am an ar as av ay az",
+    "ba be bg bi bm bn bo br bs",
+    "ca ce ch co cr cs cu cv cy",
+    "da de dv dz",
+    "ee el en eo es et eu",
+    "fa ff fi fj fo fr fy",
+    "ga gd gl gn gu gv",
+    "ha he hi ho hr ht hu hy hz",
+    "ia id ie ig ii ik io is it iu",
+    "ja jv",
+    "ka kg ki kj kk kl km kn ko kr ks ku kv kw ky",
+    "la lb lg li ln lo lt lu lv",
+    "mg mh mi mk ml mn mr ms mt my",
+    "na nb nd ne ng nl nn no nr nv ny",
+    "oc oj om or os",
+    "pa pi pl ps pt",
+    "qu",
+    "rm rn ro ru rw",
+    "sa sc sd se sg si sk sl sm sn so sq sr ss st su sv sw",
+    "ta te tg th ti tk tl tn to tr ts tt tw ty",
+    "ug uk ur uz",
+    "ve vi vo",
+    "wa wo",
+    "xh",
+    "yi yo",
+    "za zh zu",
+]);
+export const ISO_3166_1 = codes([
+    "AD AE AF AG AI AL AM AO AQ AR AS AT AU AW AX AZ",
+    "BA BB BD BE BF BG BH BI BJ BL BM BN BO BQ BR BS BT BV BW BY BZ",
+    "CA CC CD CF CG CH CI CK CL CM CN CO CR CU CV CW CX CY CZ",
+    "DE DJ DK DM DO DZ",
+    "EC EE EG EH ER ES ET",
+    "FI FJ FK FM FO FR",
+    "GA GB GD GE GF GG GH GI GL GM GN GP GQ GR GS GT GU GW GY",
+    "HK HM HN HR HT HU",
+    "ID IE IL IM IN IO IQ IR IS IT",
+    "JE JM JO JP",
+    "KE KG KH KI KM KN KP KR KW KY KZ",
+    "LA LB LC LI LK LR LS LT LU LV LY",
+    "MA MC MD ME MF MG MH MK ML MM MN MO MP MQ MR MS MT MU MV MW MX MY MZ",
+    "NA NC NE NF NG NI NL NO NP NR NU NZ",
+    "OM",
+    "PA PE PF PG PH PK PL PM PN PR PS PT PW PY",
+    "QA",
+    "RE RO RS RU RW",
+    "SA SB SC SD SE SG SH SI SJ SK SL SM SN SO SR SS ST SV SX SY SZ",
+    "TC TD TF TG TH TJ TK TL TM TN TO TR TT TV TW TZ",
+    "UA UG UM US UY UZ",
+    "VA VC VE VG VI VN VU",
+    "WF WS",
+    "YE YT",
+    "ZA ZM ZW",
+]);
+const SCRIPTS = new Set(["Hans", "Hant", "Latn", "Cyrl", "Arab"]);
+/** `null` = the market has no valid locale and is left out of everything language-dependent. No alias
+ *  canonicalization: `iw`, `in`, `UK` are simply not in the tables. */
+export function normalizeLocale(market) {
+    const [primary, ...rest] = market.language.split(/[-_]/);
+    const language = primary.toLowerCase();
+    if (!ISO_639_1.has(language))
+        return null;
+    let i = 0;
+    let script;
+    if (rest[i] !== undefined && /^[a-z]{4}$/i.test(rest[i])) {
+        script = rest[i][0].toUpperCase() + rest[i].slice(1).toLowerCase();
+        if (!SCRIPTS.has(script))
+            return null;
+        i++;
+    }
+    // A region in `language` is dropped: the market's own country is the market (spec §4.19).
+    if (rest[i] !== undefined && /^([a-z]{2}|\d{3})$/i.test(rest[i]))
+        i++;
+    if (i !== rest.length)
+        return null;
+    const country = market.country.toUpperCase();
+    if (!ISO_3166_1.has(country))
+        return null;
+    return script ? { language, script, country } : { language, country };
+}
+/** `language[-Script]-COUNTRY`: `sv-SE`, `zh-Hant-TW`. */
+export const hreflang = (l) => (l.script ? `${l.language}-${l.script}-${l.country}` : `${l.language}-${l.country}`);
+/** Open Graph `language_TERRITORY`, script dropped: `zh_TW`. Never derived from `hreflang` by separator replacement. */
+export const ogLocale = (l) => `${l.language}_${l.country}`;

package/dist/seo/product.d.ts

@@ -0,0 +1,6 @@
+import { type JsonLd, type ProductDto, type ProductJsonLdOptions } from "./types.js";
+/**
+ * schema.org `Product` / `ProductGroup` for a product page (spec §6.2). Decision order: no offer → single (only for a
+ * proven singleton) → group. Never an `AggregateOffer`, never a guessed price.
+ */
+export declare function productJsonLd(p: ProductDto, ctx: ProductJsonLdOptions): JsonLd;

package/dist/seo/product.js

@@ -0,0 +1,128 @@
+import { jsonLdDescription, pickImages, productDescription, rejectRedirect, requireMarket } from "./shared.js";
+import { SeoError } from "./types.js";
+const PROPERTIES = ["size", "color", "material", "pattern"];
+const IN_STOCK = "https://schema.org/InStock";
+const OUT_OF_STOCK = "https://schema.org/OutOfStock";
+const brandNode = (label) => ({ "@type": "Brand", name: label });
+/** Spec §4.12: absolute http(s), distinct per variant; checked for every emitted variant, single path included. */
+function checkVariantUrls(variants, variantUrl) {
+    const seen = new Set();
+    return variants.map((v) => {
+        const u = variantUrl(v);
+        let parsed = null;
+        if (typeof u === "string") {
+            try {
+                parsed = new URL(u);
+            }
+            catch {
+                parsed = null;
+            }
+        }
+        if (parsed === null || (parsed.protocol !== "http:" && parsed.protocol !== "https:"))
+            throw new SeoError(`variantUrl must return an absolute http(s) URL; got ${JSON.stringify(u)} for variant ${v.sku}`);
+        // Crawlers drop the #fragment, so URLs that differ only there are one URL.
+        parsed.hash = "";
+        if (seen.has(parsed.href))
+            throw new SeoError(`variantUrl returns ${parsed.href} for more than one variant (a #fragment does not count); each needs its own URL`);
+        seen.add(parsed.href);
+        return u;
+    });
+}
+const optionValue = (v, name) => Object.hasOwn(v.selectedOptions, name) && v.selectedOptions[name] !== "" ? v.selectedOptions[name] : undefined;
+/** Spec §4.3: the product name, " – ", every option value in `p.options` order; the SKU when there is none. */
+function variantName(p, v) {
+    const values = p.options.map((o) => optionValue(v, o.name)).filter((x) => x !== undefined);
+    return `${p.name} – ${values.length > 0 ? values.join(", ") : v.sku}`;
+}
+function offerExtras(ctx) {
+    const out = {};
+    if (ctx.seller !== undefined)
+        out.seller = ctx.seller;
+    if (ctx.itemCondition !== undefined)
+        out.itemCondition = ctx.itemCondition;
+    if (ctx.shippingDetails !== undefined)
+        out.shippingDetails = ctx.shippingDetails;
+    if (ctx.hasMerchantReturnPolicy !== undefined)
+        out.hasMerchantReturnPolicy = ctx.hasMerchantReturnPolicy;
+    return out;
+}
+/**
+ * schema.org `Product` / `ProductGroup` for a product page (spec §6.2). Decision order: no offer → single (only for a
+ * proven singleton) → group. Never an `AggregateOffer`, never a guessed price.
+ */
+export function productJsonLd(p, ctx) {
+    rejectRedirect(p, `product ${p.sku}`);
+    const market = requireMarket(ctx.site, ctx.market);
+    const variesBy = ctx.variesBy ?? {};
+    for (const [axis, prop] of Object.entries(variesBy))
+        if (!PROPERTIES.includes(prop))
+            throw new SeoError(`variesBy['${axis}'] = '${prop}' is not one of ${PROPERTIES.join(", ")}`);
+    if (typeof ctx.variantUrl !== "function")
+        throw new SeoError("variantUrl is required: Google needs a distinct URL that preselects each variant");
+    const list = p.variants ?? ctx.variants ?? null;
+    const complete = p.variants !== null;
+    const sellable = (list ?? []).filter((v) => v.price !== null);
+    const description = jsonLdDescription(productDescription(p));
+    const images = pickImages(ctx.site, p.images, market.language, p.name).map((i) => i.url);
+    const common = (type) => ({
+        "@context": "https://schema.org",
+        "@type": type,
+        name: p.name,
+        ...(description !== null ? { description } : {}),
+        ...(images.length > 0 ? { image: images } : {}),
+        url: p.url,
+    });
+    const offer = (v, url) => ({
+        "@type": "Offer",
+        price: v.price.amount,
+        priceCurrency: v.price.currency,
+        availability: v.inStock ? IN_STOCK : OUT_OF_STOCK,
+        url,
+        ...offerExtras(ctx),
+    });
+    const gtin = (v) => {
+        const g = ctx.gtin?.(v);
+        return g ? { gtin: g } : {};
+    };
+    if (list === null || sellable.length === 0)
+        return { ...common("Product"), sku: p.sku, ...(p.brand ? { brand: brandNode(p.brand.label) } : {}) };
+    if (list.length === 1 && p.options.length === 0 && sellable.length === 1 && (complete || Number(p.variantCount) === 1)) {
+        const v = sellable[0];
+        const [url] = checkVariantUrls([v], ctx.variantUrl);
+        return { ...common("Product"), sku: v.sku, ...gtin(v), ...(v.brand ? { brand: brandNode(v.brand.label) } : {}), offers: offer(v, url) };
+    }
+    const urls = checkVariantUrls(sellable, ctx.variantUrl);
+    // Spec §4.14: hoist only from the DTO's own list, and only when every emitted variant has the same non-null label.
+    const first = sellable[0].brand?.label;
+    const hoisted = complete && first != null && sellable.every((v) => v.brand?.label === first) ? first : null;
+    const axes = p.options.filter((o) => Object.hasOwn(variesBy, o.name)).map((o) => ({ name: o.name, prop: variesBy[o.name] }));
+    const props = [...new Set(axes.map((a) => a.prop))];
+    return {
+        ...common("ProductGroup"),
+        productGroupID: p.sku,
+        ...(props.length > 0 ? { variesBy: props.map((x) => `https://schema.org/${x}`) } : {}),
+        ...(hoisted !== null ? { brand: brandNode(hoisted) } : {}),
+        hasVariant: sellable.map((v, i) => {
+            const name = variantName(p, v);
+            const own = {};
+            for (const a of axes) {
+                const value = optionValue(v, a.name);
+                if (value !== undefined && !Object.hasOwn(own, a.prop))
+                    own[a.prop] = value;
+            }
+            const vImages = v.hasOwnImages ? pickImages(ctx.site, v.images, market.language, name).map((x) => x.url) : [];
+            return {
+                "@type": "Product",
+                sku: v.sku,
+                ...gtin(v),
+                name,
+                inProductGroupWithID: p.sku,
+                ...own,
+                ...(vImages.length > 0 ? { image: vImages } : {}),
+                ...(hoisted === null && v.brand ? { brand: brandNode(v.brand.label) } : {}),
+                url: urls[i],
+                offers: offer(v, urls[i]),
+            };
+        }),
+    };
+}

package/dist/seo/serialize.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The inner text of a `<script type="application/ld+json">` (spec §4.16): `JSON.stringify` with every `<`, `>`, `&`,
+ * U+2028 and U+2029 written as a six-character backslash-u escape, so merchant text cannot end the script element.
+ * Safe for HTML templates and React's `dangerouslySetInnerHTML`; the frontend writes the element itself.
+ */
+export declare function jsonLdScript(obj: object): string;

package/dist/seo/serialize.js

@@ -0,0 +1,8 @@
+/**
+ * The inner text of a `<script type="application/ld+json">` (spec §4.16): `JSON.stringify` with every `<`, `>`, `&`,
+ * U+2028 and U+2029 written as a six-character backslash-u escape, so merchant text cannot end the script element.
+ * Safe for HTML templates and React's `dangerouslySetInnerHTML`; the frontend writes the element itself.
+ */
+export function jsonLdScript(obj) {
+    return JSON.stringify(obj).replace(/[<>&\u2028\u2029]/g, (c) => "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}

package/dist/seo/shared.d.ts

@@ -0,0 +1,38 @@
+import { type MediaDescriptor } from "../media.js";
+import { type MarketDto, type ProductDto, type SiteDto } from "./types.js";
+export declare function requireMarket(site: SiteDto, code: string): MarketDto;
+/** Spec §4.17: a page with `redirectTo` should answer 301, not render. */
+export declare function rejectRedirect(entity: {
+    redirectTo: string | null;
+}, what: string): void;
+export declare function collapse(s: string | null | undefined): string | null;
+/** Spec §4.9: `seo.description` → `shortDescription` → `description.text`, whitespace collapsed. */
+export declare function productDescription(p: ProductDto): string | null;
+/** At most `max` characters including the `…`; never ends inside a word unless one word is longer than the limit. */
+export declare function truncate(text: string, max: number): string;
+export declare const headDescription: (t: string | null) => string | null;
+export declare const jsonLdDescription: (t: string | null) => string | null;
+export type PickedImage = {
+    url: string;
+    width: number;
+    height?: number;
+    alt: string;
+};
+/** `alt[language] ?? alt[primary subtag] ?? alt.sv ?? fallback` (own, non-empty properties only). */
+export declare function altText(d: MediaDescriptor, language: string, fallback: string): string;
+/** Spec §4.13: images in API order, `kind === "image"` only, at most `limit`; a descriptor that cannot render is skipped. */
+export declare function pickImages(site: SiteDto, descriptors: readonly MediaDescriptor[], language: string, fallbackAlt: string, limit?: number): PickedImage[];
+export type AlternateSet = {
+    alternates: {
+        hreflang: string;
+        href: string;
+    }[];
+    locale: string | null;
+    alternateLocales: string[];
+};
+/**
+ * Spec §6.4, one pass (review #16): candidates = `alternateUrls` entries for the site's markets + the current market
+ * with `url` when missing; markets without a valid locale are skipped; over the final set identical pairs are
+ * deduplicated and the same hreflang with different URLs throws. `x-default` is decided on the original map.
+ */
+export declare function alternateSet(site: SiteDto, market: string, url: string, alternateUrls: Record<string, string>, xDefault?: string | false): AlternateSet;

package/dist/seo/shared.js

@@ -0,0 +1,106 @@
+import { mediaUrl, MediaUrlError, pickWidth } from "../media.js";
+import { hreflang, normalizeLocale, ogLocale } from "./locales.js";
+import { SeoError } from "./types.js";
+export function requireMarket(site, code) {
+    const m = site.markets.find((x) => x.code === code);
+    if (!m)
+        throw new SeoError(`market '${code}' is not one of the site's markets (${site.markets.map((x) => x.code).join(", ")})`);
+    return m;
+}
+/** Spec §4.17: a page with `redirectTo` should answer 301, not render. */
+export function rejectRedirect(entity, what) {
+    if (entity.redirectTo)
+        throw new SeoError(`${what} has redirectTo '${entity.redirectTo}': answer 301 instead of rendering it`);
+}
+export function collapse(s) {
+    if (s == null)
+        return null;
+    const c = s.replace(/\s+/g, " ").trim();
+    return c === "" ? null : c;
+}
+/** Spec §4.9: `seo.description` → `shortDescription` → `description.text`, whitespace collapsed. */
+export function productDescription(p) {
+    return collapse(p.seo.description) ?? collapse(p.shortDescription) ?? collapse(p.description?.text);
+}
+/** At most `max` characters including the `…`; never ends inside a word unless one word is longer than the limit. */
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    const room = text.slice(0, max - 1);
+    const lastSpace = room.lastIndexOf(" ");
+    const cut = text[max - 1] === " " || lastSpace <= 0 ? room : room.slice(0, lastSpace);
+    return cut.trimEnd() + "…";
+}
+export const headDescription = (t) => (t === null ? null : truncate(t, 160));
+export const jsonLdDescription = (t) => (t === null ? null : truncate(t, 5000));
+const IMAGE_WIDTH = 1200;
+/** `alt[language] ?? alt[primary subtag] ?? alt.sv ?? fallback` (own, non-empty properties only). */
+export function altText(d, language, fallback) {
+    const alt = d.alt ?? {};
+    const own = (k) => (Object.hasOwn(alt, k) && alt[k] ? alt[k] : undefined);
+    return own(language) ?? own(language.split(/[-_]/)[0].toLowerCase()) ?? own("sv") ?? fallback;
+}
+/** Spec §4.13: images in API order, `kind === "image"` only, at most `limit`; a descriptor that cannot render is skipped. */
+export function pickImages(site, descriptors, language, fallbackAlt, limit = 10) {
+    const out = [];
+    for (const d of descriptors) {
+        if (out.length >= limit)
+            break;
+        if (d.kind !== "image")
+            continue;
+        let url;
+        let width;
+        try {
+            url = mediaUrl(site.media, d, { width: IMAGE_WIDTH });
+            width = pickWidth(d, IMAGE_WIDTH);
+        }
+        catch (e) {
+            if (e instanceof MediaUrlError)
+                continue;
+            throw e;
+        }
+        const w = d.w == null ? NaN : Number(d.w);
+        const h = d.h == null ? NaN : Number(d.h);
+        const alt = altText(d, language, fallbackAlt);
+        out.push(w > 0 && h > 0 ? { url, width, height: Math.round((width * h) / w), alt } : { url, width, alt });
+    }
+    return out;
+}
+/**
+ * Spec §6.4, one pass (review #16): candidates = `alternateUrls` entries for the site's markets + the current market
+ * with `url` when missing; markets without a valid locale are skipped; over the final set identical pairs are
+ * deduplicated and the same hreflang with different URLs throws. `x-default` is decided on the original map.
+ */
+export function alternateSet(site, market, url, alternateUrls, xDefault) {
+    const byCode = new Map(site.markets.map((m) => [m.code, m]));
+    const candidates = Object.entries(alternateUrls).filter(([code]) => byCode.has(code)).map(([code, href]) => ({ code, href }));
+    if (!Object.hasOwn(alternateUrls, market))
+        candidates.push({ code: market, href: url });
+    const entries = new Map();
+    for (const c of candidates) {
+        const loc = normalizeLocale(byCode.get(c.code));
+        if (!loc)
+            continue;
+        const tag = hreflang(loc);
+        const seen = entries.get(tag);
+        if (seen === undefined)
+            entries.set(tag, { code: c.code, href: c.href, loc });
+        else if (seen.href !== c.href)
+            throw new SeoError(`markets '${seen.code}' and '${c.code}' both give hreflang '${tag}' with different URLs; fix their language/country`);
+    }
+    const sorted = [...entries].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const alternates = sorted.map(([tag, e]) => ({ hreflang: tag, href: e.href }));
+    const target = xDefault === false ? null : (xDefault ?? site.defaultMarket);
+    if (target !== null && Object.hasOwn(alternateUrls, target))
+        alternates.push({ hreflang: "x-default", href: alternateUrls[target] });
+    const self = byCode.get(market);
+    const selfLoc = self ? normalizeLocale(self) : null;
+    const locale = selfLoc ? ogLocale(selfLoc) : null;
+    const alternateLocales = [];
+    for (const [, e] of sorted) {
+        const l = ogLocale(e.loc);
+        if (e.code !== market && l !== locale && !alternateLocales.includes(l))
+            alternateLocales.push(l);
+    }
+    return { alternates, locale, alternateLocales };
+}

package/dist/seo/types.d.ts

@@ -0,0 +1,100 @@
+import type { components } from "../schema";
+type Schemas = components["schemas"];
+export type SiteDto = Schemas["SiteDto"];
+export type MarketDto = Schemas["MarketDto"];
+export type ProductDto = Schemas["ProductDto"];
+export type VariantDto = Schemas["VariantDto"];
+export type CollectionListingResponse = Schemas["CollectionListingResponse"];
+export type CollectionCrumbDto = Schemas["CollectionCrumbDto"];
+export type BrandDetailDto = Schemas["BrandDetailDto"];
+/** Every helper's context. `market` is the code the client sends as X-Market and must be in `site.markets`. */
+export type SeoContext = {
+    site: SiteDto;
+    market: string;
+    /** `x-default` target: a market code, or `false` for none. Default: `site.defaultMarket`. */
+    xDefault?: string | false;
+};
+/** The `variesBy` targets Google accepts as plain strings (spec §4.3, review #5). */
+export type SchemaProperty = "size" | "color" | "material" | "pattern";
+export type SeoMeta = {
+    name: string;
+    content: string;
+} | {
+    property: string;
+    content: string;
+};
+export type SeoHead = {
+    title: string;
+    description: string | null;
+    canonical: string;
+    /** Includes `x-default` (last); otherwise sorted by hreflang. */
+    alternates: {
+        hreflang: string;
+        href: string;
+    }[];
+    meta: SeoMeta[];
+};
+export type ProductJsonLdOptions = SeoContext & {
+    /** Required: a distinct absolute http(s) URL that opens the page with this variant preselected (spec §4.12). */
+    variantUrl: (v: VariantDto) => string;
+    /** Option name (`options[].name`) → schema.org property, e.g. `{ Storlek: "size", Färg: "color" }`. */
+    variesBy?: Record<string, SchemaProperty>;
+    /** Used only when `p.variants` is `null` (more than 100 variants), e.g. the first page of `/variants`. */
+    variants?: VariantDto[];
+    gtin?: (v: VariantDto) => string | undefined;
+    seller?: {
+        name: string;
+    };
+    itemCondition?: string;
+    shippingDetails?: unknown;
+    hasMerchantReturnPolicy?: unknown;
+};
+export type BreadcrumbLink = {
+    name: string;
+    url: string;
+};
+export type HeadOptions = SeoContext & {
+    titleTemplate?: string;
+};
+export type CollectionHeadOptions = HeadOptions & {
+    description?: string;
+};
+export type JsonLd = Record<string, unknown>;
+type AbsoluteTitle = {
+    absolute: string;
+};
+/** The subset of Next.js `Metadata` that `toNextMetadata` fills; assignable to `Metadata` (checked in examples). */
+export type NextMetadataLike = {
+    title: AbsoluteTitle;
+    description?: string;
+    alternates: {
+        canonical: string;
+        languages?: Record<string, string>;
+    };
+    openGraph: {
+        type: "website";
+        title: AbsoluteTitle;
+        description?: string;
+        url: string;
+        siteName?: string;
+        locale?: string;
+        alternateLocale?: string[];
+        images?: {
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        }[];
+    };
+    twitter: {
+        card: "summary" | "summary_large_image";
+        title: AbsoluteTitle;
+        description?: string;
+        images?: string[];
+    };
+};
+/** A caller mistake or a configuration error (spec §7). Holes in the data never throw. */
+export declare class SeoError extends Error {
+    constructor(message: string);
+}
+export {};