@asstio-dev/storefront 0.9.2 → 0.12.0

package/README.md

@@ -146,9 +146,11 @@ const html = `<div class="card-image"><div style="${styleToCss(f.box)}">${placeh
 
 `description` is **already sanitized** on the server: render `description.html` as-is — do not sanitize, escape or
 re-parse it — and use `description.text` wherever you need plain text (a meta description, a snippet, an
-`aria-label`). `shortDescription` is plain text. `brand.facet` is set when the brand shares a facet's source, so it
-can link straight to a filtered listing; when it is `null`, render `brand.label` as plain text and never guess a
-filter.
+`aria-label`). `shortDescription` is plain text. `brand` is the product's brand (the main product's); every variant in `variants[]` and on `/variants` carries its own
+`brand` and `responsible` — render the **selected variant's**. `brand.facet` links a filtered listing
+(`filter[facet.key]=facet.valueKey`) when the shop has a brand filter. `brand.url` is the brand page on this market and
+is `null` whenever that page would not exist here (brand pages off, or nothing of the brand sold on this market) — then
+render the label (and `brand.logo`) without a link; never build a brand URL yourself.
 
 `attributes[]` arrives ordered and labelled for display. Branch on `type` (`text` | `html` | `number` | `bool` |
 `list`): a list fills `values`, everything else fills `value`, and `html` fills `html` too — sanitized exactly like
@@ -170,6 +172,77 @@ value has no key of its own: a list is either fully linkable or not linkable at
 `related[]` holds groups of cards already resolved for this market, and `bundle.components[]` the cards a bundle is
 made of; both leave out anything that no longer exists or is not sold here.
 
+### Brands and responsible parties
+
+`responsible` is `{ manufacturer, importer, euResponsiblePerson }`, each a party or `null`. Show the selected variant's
+on the product page (EU GPSR manufacturer and responsible-person contact data). `null` means nothing applies for this
+SKU: do not fall back to the product's or the brand's. `phone` is only present when the shop publishes it.
+
+Brand pages: `GET /v1/brands` lists the brands with a page on this market (paged, by name); `GET /v1/brands/{slugOrId}`
+returns the brand's name, description (sanitized like product descriptions), logo, website, its default parties and
+`facet` — render the listing with `GET /v1/products?filter[<facet.key>]=<facet.valueKey>`. A `redirectTo` means 301 to
+that slug. `GET /v1/sitemap?type=brand` lists them for `sitemap.xml`.
+
+```ts
+const { data: brand } = await storefront.GET("/v1/brands/{slugOrId}", { params: { path: { slugOrId: "hugo-boss" } } });
+if (brand?.redirectTo) redirect(301, `/varumarken/${brand.redirectTo}`);
+const { data: listing } = await storefront.GET("/v1/products", {
+  params: { query: { filter: filterQuery({ [brand!.facet!.key]: [brand!.facet!.valueKey] }) } },
+});
+```
+
+### SEO
+
+Pure helpers that compute schema.org JSON-LD and `<head>` data from the DTOs. They render nothing: your frontend
+writes the markup. No backend call, no DOM, no dependency.
+
+**Product JSON-LD.** `productJsonLd` returns a `Product` (one variant) or a `ProductGroup` with one `Product` and
+`Offer` per variant sold on the market. `variantUrl` is required: Google needs a distinct URL per variant, and opening
+that URL **must preselect the variant** on your page. The format is yours; `?variant=` below is only an example.
+`variesBy` maps your option names to `size`, `color`, `material` or `pattern`; unmapped options still name the
+variants. A product with more than 100 variants arrives with `variants: null`: pass the first `/variants` page as
+`variants`, or the product gets no offer (valid schema.org, but not eligible for product rich results).
+
+```tsx
+const ld = productJsonLd(product, {
+  site, market: "se",
+  variantUrl: (v) => `${product.url}?variant=${v.id}`,
+  variesBy: { Storlek: "size", Färg: "color" },
+});
+<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLdScript(ld) }} />
+```
+
+In a plain template: `<script type="application/ld+json">${jsonLdScript(ld)}</script>`. `jsonLdScript` escapes
+`<`, `>`, `&`, U+2028 and U+2029, so merchant text cannot end the script element; never use plain `JSON.stringify` there.
+
+**Breadcrumbs.** On a collection page, `r.breadcrumb` holds the ancestors only. Add the collection itself as `current`:
+
+```ts
+const crumbs = breadcrumbJsonLd(r.breadcrumb, { home: { name: "Hem", url: "https://moory.se/" }, current: r.collection });
+// null below two items (Google's minimum): render nothing then.
+```
+
+**Head.** `productHead`, `collectionHead` (takes your own `description`; the API has none for collections) and
+`brandHead` return a framework-neutral `SeoHead`: title, description (cut at 160 characters on a word boundary),
+canonical, hreflang alternates (keyed `language-COUNTRY`, `x-default` from the site's default market; override with
+`xDefault: "<market>"` or `false`), and Open Graph / Twitter meta. `titleTemplate: "%s | Moory"` applies to `<title>`
+only, never to the social titles. In Next.js:
+
+```ts
+export async function generateMetadata(): Promise<Metadata> {
+  return toNextMetadata(productHead(product, { site, market: "se", titleTemplate: "%s | Moory" }));
+}
+```
+
+Titles come out as `{ absolute }` on purpose, so a layout's `title.template` does not apply a second time.
+
+**Errors.** `SeoError` means a caller or configuration error: `redirectTo` is set (answer 301 instead), an unknown
+market, a bad `variesBy` value, a `variantUrl` that is not an absolute http(s) URL or repeats for two variants, or
+two markets with the same `language-COUNTRY` and different URLs. Catch it at your SEO boundary and fix the market
+config. Holes in the data never throw: a missing image, description or price only leaves that part out.
+
+hreflang sets are only as reciprocal as the API's `alternateUrls`; the SDK renders what the API gives.
+
 ### Search-as-you-type and search-in-facet
 
 `/v1/search/suggest` answers three short lists for what the shopper has typed so far: up to 5 product cards

package/dist/gtin.d.ts

@@ -0,0 +1,3 @@
+/** Schema.org's GTIN property for a `gtin` value from the API (GTIN spec §13.3): gtin8, gtin12, gtin13 or gtin14 by
+ *  length. The API sends the canonical form, so the length is the format. Spread it into a Product or Offer object. */
+export declare function gtinJsonLd(gtin: string | null | undefined): Record<string, string>;

package/dist/gtin.js

@@ -0,0 +1,13 @@
+/** Schema.org's GTIN property for a `gtin` value from the API (GTIN spec §13.3): gtin8, gtin12, gtin13 or gtin14 by
+ *  length. The API sends the canonical form, so the length is the format. Spread it into a Product or Offer object. */
+export function gtinJsonLd(gtin) {
+    if (!gtin || !/^\d+$/.test(gtin))
+        return {};
+    switch (gtin.length) {
+        case 8: return { gtin8: gtin };
+        case 12: return { gtin12: gtin };
+        case 13: return { gtin13: gtin };
+        case 14: return { gtin14: gtin };
+        default: return {};
+    }
+}

package/dist/index.d.ts

@@ -51,3 +51,9 @@ export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCh
 export { retryAfterSeconds, type CheckoutDto, type CheckoutOrderRefDto, type CheckoutResult, type CheckoutStatusDto, type CheckoutWidgetDto, type OrderDto, type OrderResult, type StatusResult, type StorefrontProblem } from "./checkout/types.js";
 export { mountCheckout, type CheckoutHandle, type MountOptions, type MinimalDocument, type MinimalElement, type MinimalScript } from "./checkout/browser.js";
 export { controllers, type CheckoutController, type ProviderWindow } from "./checkout/controllers.js";
+export { breadcrumbJsonLd } from "./seo/breadcrumb.js";
+export { brandHead, collectionHead, productHead, toNextMetadata } from "./seo/head.js";
+export { gtinJsonLd } from "./gtin.js";
+export { productJsonLd } from "./seo/product.js";
+export { jsonLdScript } from "./seo/serialize.js";
+export { SeoError, type BreadcrumbLink, type CollectionHeadOptions, type HeadOptions, type JsonLd, type NextMetadataLike, type ProductJsonLdOptions, type SchemaProperty, type SeoContext, type SeoHead, type SeoMeta, } from "./seo/types.js";

package/dist/index.js

@@ -40,3 +40,9 @@ export { awaitCompletion, completeCheckout, getCheckoutStatus, getOrder, startCh
 export { retryAfterSeconds } from "./checkout/types.js";
 export { mountCheckout } from "./checkout/browser.js";
 export { controllers } from "./checkout/controllers.js";
+export { breadcrumbJsonLd } from "./seo/breadcrumb.js";
+export { brandHead, collectionHead, productHead, toNextMetadata } from "./seo/head.js";
+export { gtinJsonLd } from "./gtin.js";
+export { productJsonLd } from "./seo/product.js";
+export { jsonLdScript } from "./seo/serialize.js";
+export { SeoError, } from "./seo/types.js";

package/dist/schema.d.ts

@@ -4,6 +4,40 @@
  */
 
 export interface paths {
+    "/v1/brands": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Brands with a page on this market (some product of the brand is sold here), by name. Empty when the site has no brand facet or the market no brand URL pattern. productCount counts product families with a variant of the brand sold here. */
+        get: operations["ListBrands"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/brands/{slugOrId}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** A brand page's data by current slug, historical slug or id: name, description, logo, website, the brand's default responsible parties and the facet link for its listing. redirectTo is set for a historical slug. */
+        get: operations["GetBrand"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/cart": {
         parameters: {
             query?: never;
@@ -325,7 +359,7 @@ export interface paths {
             path?: never;
             cookie?: never;
         };
-        /** Ids, slugs, URLs and lastmod for sitemap.xml and selective revalidation. type=product|collection, ?since= is inclusive. */
+        /** Ids, slugs, URLs and lastmod for sitemap.xml and selective revalidation. type=product|collection|brand, ?since= is inclusive. */
         get: operations["GetSitemap"];
         put?: never;
         post?: never;
@@ -368,9 +402,50 @@ export interface components {
             valueKeys: string[] | null;
             values: string[] | null;
         };
+        BrandDetailDto: {
+            alternateUrls: {
+                [key: string]: string;
+            };
+            description: null | components["schemas"]["DescriptionDto"];
+            facet: null | components["schemas"]["FacetLinkDto"];
+            id: string;
+            logo: null | components["schemas"]["MediaDescriptorDto"];
+            name: string;
+            /** Format: int64 */
+            productCount: number | string;
+            redirectTo: null | string;
+            responsible: components["schemas"]["ResponsibleDto"];
+            slug: string;
+            /** Format: date-time */
+            updatedAt: string;
+            url: string;
+            websiteUrl: null | string;
+        };
         BrandDto: {
             facet: null | components["schemas"]["FacetLinkDto"];
+            id?: null | string;
             label: string;
+            logo?: null | components["schemas"]["MediaDescriptorDto"];
+            slug?: null | string;
+            url?: null | string;
+        };
+        BrandListItemDto: {
+            id: string;
+            logo: null | components["schemas"]["MediaDescriptorDto"];
+            name: string;
+            /** Format: int64 */
+            productCount: number | string;
+            slug: string;
+            url: string;
+        };
+        BrandPageDto: {
+            items: components["schemas"]["BrandListItemDto"][];
+            /** Format: int32 */
+            page: number | string;
+            /** Format: int32 */
+            pageSize: number | string;
+            /** Format: int64 */
+            total: number | string;
         };
         BundleComponentDto: {
             product: components["schemas"]["ProductCardDto"];
@@ -731,6 +806,18 @@ export interface components {
             gross: string;
             vat: components["schemas"]["VatAmountDto"][];
         };
+        PartyDto: {
+            city: null | string;
+            countryCode: string;
+            email: null | string;
+            legalName: string;
+            name: string;
+            phone: null | string;
+            postalCode: null | string;
+            region: null | string;
+            street: null | string;
+            url: null | string;
+        };
         PriceDto: {
             amount: string;
             compareAt: null | string;
@@ -765,6 +852,8 @@ export interface components {
             collections: components["schemas"]["CollectionRefDto"][];
             description: null | components["schemas"]["DescriptionDto"];
             files: components["schemas"]["MediaDescriptorDto"][];
+            gtin: null | string;
+            gtins: string[];
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];
             images: components["schemas"]["MediaDescriptorDto"][];
@@ -773,6 +862,7 @@ export interface components {
             options: components["schemas"]["OptionDto"][];
             redirectTo: null | string;
             related: components["schemas"]["RelatedGroupDto"][];
+            responsible: components["schemas"]["ResponsibleDto"];
             seo: components["schemas"]["SeoDto"];
             shortDescription: null | string;
             sku: string;
@@ -802,6 +892,11 @@ export interface components {
             label: string;
             products: components["schemas"]["ProductCardDto"][];
         };
+        ResponsibleDto: {
+            euResponsiblePerson: null | components["schemas"]["PartyDto"];
+            importer: null | components["schemas"]["PartyDto"];
+            manufacturer: null | components["schemas"]["PartyDto"];
+        };
         SeoDto: {
             description: null | string;
             title: string;
@@ -909,12 +1004,16 @@ export interface components {
             product: string;
         };
         VariantDto: {
+            brand: null | components["schemas"]["BrandDto"];
+            gtin: null | string;
+            gtins: string[];
             hasOwnImages: boolean;
             id: string;
             image: null | components["schemas"]["MediaDescriptorDto"];
             images: components["schemas"]["MediaDescriptorDto"][];
             inStock: boolean;
             price: null | components["schemas"]["PriceDto"];
+            responsible: components["schemas"]["ResponsibleDto"];
             selectedOptions: {
                 [key: string]: string;
             };
@@ -958,6 +1057,175 @@ export interface components {
 }
 export type $defs = Record<string, never>;
 export interface operations {
+    ListBrands: {
+        parameters: {
+            query?: {
+                /** @description 1-based page. page × pageSize must not exceed 10000 (default pageSize 100, max 1000). */
+                page?: number;
+                /** @description Items per page, 1–1000. Out of range is a 400 with code INVALID_PAGE. */
+                pageSize?: number;
+            };
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BrandPageDto"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site) or INVALID_PAGE. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_INACTIVE, or NOT_FOUND for an unrouted path. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
+    GetBrand: {
+        parameters: {
+            query?: never;
+            header: {
+                /** @description Publishable, preview or secret site key. Required on every request; secret keys are server-side only. */
+                "X-Site-Key": string;
+                /** @description Market code (e.g. "se"). Omit for the site's default market. */
+                "X-Market"?: string;
+                /** @description BCP-47 language tag. Omit to use the market's language. */
+                "Accept-Language"?: string;
+            };
+            path: {
+                slugOrId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description OK */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["BrandDetailDto"];
+                };
+            };
+            /** @description problem+json. MARKET_UNKNOWN (no such market on this site) or INVALID_PAGE. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_KEY_MISSING or SITE_KEY_INVALID. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SECRET_KEY_FROM_BROWSER: a secret key was sent from a browser. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. BRAND_NOT_FOUND, or SITE_INACTIVE when the site itself is not live. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. RATE_LIMITED; retryAfterSeconds and the Retry-After header say how long to wait. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+            /** @description problem+json. SITE_REGISTRY_WARMING or INDEX_UNAVAILABLE — retry, the request was not wrong. */
+            503: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/problem+json": components["schemas"]["StorefrontProblem"];
+                };
+            };
+        };
+    };
     GetCart: {
         parameters: {
             query?: never;

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;