@wocart/storefront 1.19.0 → 1.21.0

package/dist/schemas.d.ts

@@ -109,6 +109,8 @@ export declare const ProductListSchema: z.ZodObject<{
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     shippingProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metaTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metaDescription: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     variantOptions: z.ZodNullable<z.ZodString>;
     tags: z.ZodNullable<z.ZodString>;
     coverImage: z.ZodNullable<z.ZodObject<{
@@ -162,6 +164,8 @@ export declare const ProductSchema: z.ZodObject<{
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
     shippingProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metaTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metaDescription: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     variantOptions: z.ZodNullable<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         values: z.ZodArray<z.ZodObject<{
@@ -276,6 +280,16 @@ export declare const StoreCollectionSchema: z.ZodObject<{
     handle: z.ZodString;
     title: z.ZodString;
     description: z.ZodNullable<z.ZodString>;
+    productCount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    image: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        id: z.ZodString;
+        src: z.ZodString;
+        srcSm: z.ZodNullable<z.ZodString>;
+        srcMd: z.ZodNullable<z.ZodString>;
+        srcLg: z.ZodNullable<z.ZodString>;
+        altText: z.ZodNullable<z.ZodString>;
+        position: z.ZodNumber;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const StoreMenuSchema: z.ZodObject<{
     handle: z.ZodString;
@@ -600,6 +614,8 @@ export declare const LandingPageSchema: z.ZodObject<{
         createdAt: z.ZodString;
         updatedAt: z.ZodString;
         shippingProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metaTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metaDescription: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         variantOptions: z.ZodNullable<z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             values: z.ZodArray<z.ZodObject<{
@@ -821,6 +837,88 @@ export declare const OrderTrackingSchema: z.ZodObject<{
         Purchase: "Purchase";
     }>>;
 }, z.core.$strip>;
+/**
+ * Where a shopper's order is — POST /store/orders/status. `stage` is an open
+ * string: a newer server may name a step this release does not know.
+ */
+export declare const ShopperOrderStatusSchema: z.ZodObject<{
+    orderNumber: z.ZodString;
+    placedAt: z.ZodString;
+    stage: z.ZodString;
+    deliveryType: z.ZodEnum<{
+        home: "home";
+        stop_desk: "stop_desk";
+    }>;
+    lines: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        variantLabel: z.ZodNullable<z.ZodString>;
+        quantity: z.ZodNumber;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+    tracking: z.ZodNullable<z.ZodObject<{
+        number: z.ZodString;
+        carrier: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** A page of products with the whole listing's size; `total` is absent from a server that predates it. */
+export declare const ProductPageEnvelopeSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodNullable<z.ZodString>;
+        descriptionFormat: z.ZodEnum<{
+            html: "html";
+            text: "text";
+        }>;
+        descriptionPlain: z.ZodNullable<z.ZodString>;
+        handle: z.ZodString;
+        currency: z.ZodString;
+        price: z.ZodNumber;
+        compareAtPrice: z.ZodNullable<z.ZodNumber>;
+        costPrice: z.ZodNullable<z.ZodNumber>;
+        type: z.ZodEnum<{
+            DIGITAL: "DIGITAL";
+            PHYSICAL: "PHYSICAL";
+        }>;
+        hasVariants: z.ZodBoolean;
+        sku: z.ZodNullable<z.ZodString>;
+        inventory: z.ZodNumber;
+        trackInventory: z.ZodBoolean;
+        lowStockThreshold: z.ZodNumber;
+        categoryId: z.ZodNullable<z.ZodString>;
+        visibility: z.ZodBoolean;
+        status: z.ZodEnum<{
+            ACTIVE: "ACTIVE";
+            ARCHIVED: "ARCHIVED";
+            DRAFT: "DRAFT";
+        }>;
+        showInStore: z.ZodBoolean;
+        storeFeatured: z.ZodBoolean;
+        deletedAt: z.ZodOptional<z.ZodNull>;
+        publishedAt: z.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+        shippingProfileId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metaTitle: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        metaDescription: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        variantOptions: z.ZodNullable<z.ZodString>;
+        tags: z.ZodNullable<z.ZodString>;
+        coverImage: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            src: z.ZodString;
+            srcSm: z.ZodNullable<z.ZodString>;
+            srcMd: z.ZodNullable<z.ZodString>;
+            srcLg: z.ZodNullable<z.ZodString>;
+            altText: z.ZodNullable<z.ZodString>;
+            position: z.ZodNumber;
+        }, z.core.$strip>>;
+        reviewStats: z.ZodNullable<z.ZodObject<{
+            avgRating: z.ZodNumber;
+            reviewCount: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * The `{ id }` success payload of the write endpoints that only mint a row:
  * POST /store/reviews and POST /store/abandoned.

package/dist/schemas.js

@@ -86,6 +86,10 @@ const productBaseFields = {
     currency: z.string(),
     price: z.number(),
     compareAtPrice: z.number().nullable(),
+    /**
+     * @deprecated Always null: what the merchant paid is never served to a
+     * storefront. Older servers sent it; a later major drops it. Do not read it.
+     */
     costPrice: z.number().nullable(),
     type: z.enum(["PHYSICAL", "DIGITAL"]),
     hasVariants: z.boolean(),
@@ -109,6 +113,10 @@ const productBaseFields = {
     createdAt: z.string().datetime(),
     updatedAt: z.string().datetime(),
     shippingProfileId: z.string().nullable().optional(),
+    /** The title search engines and shared links show, in the client's language; null or absent: use `productMeta(product)`, which falls back to the name. */
+    metaTitle: z.string().nullish(),
+    /** The description search engines and shared links show; null or absent: `productMeta(product)` shortens the product's own. */
+    metaDescription: z.string().nullish(),
 };
 const variantOptionSchema = z.object({
     name: z.string(),
@@ -124,6 +132,7 @@ const variantOptionSchema = z.object({
 const rawProductFields = {
     ...productBaseFields,
     variantOptions: z.string().nullable(),
+    /** The tags as stored JSON text; read them with `productTags(product)`, which a product page's list also goes through. */
     tags: z.string().nullable(),
     coverImage: ProductImageSchema.nullable(),
     reviewStats: reviewStatsSchema.nullable(),
@@ -170,6 +179,10 @@ export const StoreCollectionSchema = z.object({
     handle: z.string(),
     title: z.string(),
     description: z.string().nullable(),
+    /** How many products a shopper sees in it; absent from a server that predates it. */
+    productCount: z.number().int().min(0).nullish(),
+    /** Its first listed product's first photo; absent from a server that predates it. */
+    image: ProductImageSchema.nullish(),
 });
 export const StoreMenuSchema = z.object({
     handle: z.string(),
@@ -413,6 +426,24 @@ export const OrderTrackingSchema = z.object({
     pixelId: z.string().nullable(),
     event: z.enum(["Purchase", "Lead"]).nullable(),
 });
+/**
+ * Where a shopper's order is — POST /store/orders/status. `stage` is an open
+ * string: a newer server may name a step this release does not know.
+ */
+export const ShopperOrderStatusSchema = z.object({
+    orderNumber: z.string(),
+    placedAt: z.string(),
+    stage: z.string(),
+    deliveryType: z.enum(["home", "stop_desk"]),
+    lines: z.array(z.object({ name: z.string(), variantLabel: z.string().nullable(), quantity: z.number().int() })),
+    total: z.number(),
+    tracking: z.object({ number: z.string(), carrier: z.string().nullable() }).nullable(),
+});
+/** A page of products with the whole listing's size; `total` is absent from a server that predates it. */
+export const ProductPageEnvelopeSchema = z.object({
+    data: z.array(ProductListSchema),
+    total: z.number().int().min(0).optional(),
+});
 /**
  * The `{ id }` success payload of the write endpoints that only mint a row:
  * POST /store/reviews and POST /store/abandoned.

package/dist/seo.d.ts

@@ -0,0 +1,47 @@
+import type { Product, ProductList } from "./types.js";
+/** The lengths a search-engine title and description may have: about what a search result shows. */
+export declare const SEO_TEXT_LIMITS: {
+    readonly titleMax: 60;
+    readonly descriptionMax: 160;
+};
+/** A page's `<title>` text and `<meta name="description">`; description null when there is nothing to say. */
+export interface PageMeta {
+    title: string;
+    description: string | null;
+}
+type MetaSource = Pick<ProductList, "name" | "description" | "descriptionFormat" | "descriptionPlain"> & {
+    metaTitle?: string | null | undefined;
+    metaDescription?: string | null | undefined;
+};
+/**
+ * A product's title and description for search engines and shared links:
+ * what the merchant wrote for them, else its name and the start of its own
+ * description as plain text — never markup — within `SEO_TEXT_LIMITS`.
+ * The store's name is the theme's to add to the title.
+ */
+export declare function productMeta(product: MetaSource): PageMeta;
+export interface ProductStructuredDataOptions {
+    /** The page's absolute URL. */
+    url: string;
+    /** The store's name, as the brand when the product has no other. */
+    storeName?: string;
+}
+/**
+ * The schema.org `Product` of a product page, for a
+ * `<script type="application/ld+json">` written with `jsonLd()`: name,
+ * description, photos, SKU, its price and stock as an `Offer` — an
+ * `AggregateOffer` with the lowest and highest price when its variants cost
+ * different amounts — and its rating once it has reviews.
+ */
+export declare function productStructuredData(product: Product, options: ProductStructuredDataOptions): Record<string, unknown>;
+/**
+ * Structured data as the text of a `<script type="application/ld+json">`:
+ * JSON with `<`, `>`, `&` and the two line separators escaped, so no value — a
+ * product name holding `</script>` — can end the script or start markup.
+ *
+ * ```astro
+ * <script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url }))} />
+ * ```
+ */
+export declare function jsonLd(value: unknown): string;
+export {};

package/dist/seo.js

@@ -0,0 +1,87 @@
+/**
+ * What a product page tells search engines and shared links: its title and
+ * description, and its structured data — decided once, so every theme ranks
+ * the same products the same way.
+ */
+import { getProductView } from "./product-view.js";
+import { initialVariant } from "./variant-picker.js";
+/** The lengths a search-engine title and description may have: about what a search result shows. */
+export const SEO_TEXT_LIMITS = { titleMax: 60, descriptionMax: 160 };
+const collapse = (text) => text.replace(/\s+/g, " ").trim();
+/** `text` within `max` characters, cut at a word with an ellipsis when it is longer. */
+function shorten(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max - 1);
+    const space = cut.lastIndexOf(" ");
+    return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+/**
+ * A product's title and description for search engines and shared links:
+ * what the merchant wrote for them, else its name and the start of its own
+ * description as plain text — never markup — within `SEO_TEXT_LIMITS`.
+ * The store's name is the theme's to add to the title.
+ */
+export function productMeta(product) {
+    const title = collapse(product.metaTitle ?? "") || collapse(product.name);
+    const written = collapse(product.metaDescription ?? "");
+    if (written)
+        return { title, description: written };
+    const plain = product.descriptionPlain ?? (product.descriptionFormat === "text" ? product.description : null);
+    const text = collapse(plain ?? "");
+    return { title, description: text ? shorten(text, SEO_TEXT_LIMITS.descriptionMax) : null };
+}
+const AVAILABILITY = { inStock: "https://schema.org/InStock", outOfStock: "https://schema.org/OutOfStock" };
+/**
+ * The schema.org `Product` of a product page, for a
+ * `<script type="application/ld+json">` written with `jsonLd()`: name,
+ * description, photos, SKU, its price and stock as an `Offer` — an
+ * `AggregateOffer` with the lowest and highest price when its variants cost
+ * different amounts — and its rating once it has reviews.
+ */
+export function productStructuredData(product, options) {
+    const meta = productMeta(product);
+    const view = getProductView(product);
+    const variants = product.hasVariants ? product.variants.filter((variant) => variant.active) : [];
+    const prices = variants.map((variant) => variant.price);
+    const sellable = product.hasVariants
+        ? variants.some((variant) => !product.trackInventory || variant.inventory > 0)
+        : !view.isOutOfStock;
+    const availability = sellable ? AVAILABILITY.inStock : AVAILABILITY.outOfStock;
+    const ranged = prices.length > 1 && Math.min(...prices) !== Math.max(...prices);
+    const offers = ranged
+        ? { "@type": "AggregateOffer", url: options.url, priceCurrency: product.currency, lowPrice: Math.min(...prices), highPrice: Math.max(...prices), offerCount: prices.length, availability }
+        : { "@type": "Offer", url: options.url, priceCurrency: product.currency, price: view.basePrice, availability, itemCondition: "https://schema.org/NewCondition" };
+    const sku = product.sku ?? (product.hasVariants ? initialVariant(product)?.sku : null) ?? null;
+    const images = [...product.images].sort((a, b) => a.position - b.position).map((image) => image.src);
+    const rating = product.reviewStats && product.reviewStats.reviewCount > 0 ? product.reviewStats : null;
+    return {
+        "@context": "https://schema.org",
+        "@type": "Product",
+        name: collapse(product.name),
+        ...(meta.description ? { description: meta.description } : {}),
+        ...(images.length > 0 ? { image: images } : {}),
+        ...(sku ? { sku } : {}),
+        url: options.url,
+        ...(options.storeName ? { brand: { "@type": "Brand", name: options.storeName } } : {}),
+        offers,
+        ...(rating ? { aggregateRating: { "@type": "AggregateRating", ratingValue: rating.avgRating, reviewCount: rating.reviewCount } } : {}),
+    };
+}
+/**
+ * Structured data as the text of a `<script type="application/ld+json">`:
+ * JSON with `<`, `>`, `&` and the two line separators escaped, so no value — a
+ * product name holding `</script>` — can end the script or start markup.
+ *
+ * ```astro
+ * <script type="application/ld+json" set:html={jsonLd(productStructuredData(product, { url }))} />
+ * ```
+ */
+export function jsonLd(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}

package/dist/server.d.ts

@@ -6,3 +6,4 @@ export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPrevie
 export { REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
 export type { RevalidateClaims, RevalidateRequest, RevalidateRequestOptions } from "./revalidate.js";
 export type { PreviewClaims, PreviewDraft, PreviewRequest, PreviewRequestOptions, PreviewTokenCheck, PreviewTokenOptions, PreviewTokenRefusal, } from "./preview.js";
+export { catalogPaths, sitemapXml } from "./sitemap.js";

package/dist/server.js

@@ -2,3 +2,4 @@ export { createStoreClient } from "./client/index.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
 export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";
 export { REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
+export { catalogPaths, sitemapXml } from "./sitemap.js";

package/dist/sitemap.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The storefront's sitemap: every page a shopper can land on, in every
+ * published language, as search engines read multilingual sites — one
+ * `<url>` per page per language, each naming all its language versions and
+ * `x-default`. Landing pages are left out: they are ad destinations, often
+ * unlisted from the store.
+ */
+import type { StoreClient } from "./client/index.js";
+import { type LocaleRouting } from "./locale-routing.js";
+import type { StoreConfig } from "./types.js";
+/**
+ * The sitemap of `paths` — unprefixed page paths (`/products/robe`) — on
+ * `origin`, in every language `routing` publishes. A path given twice is
+ * listed once.
+ */
+export declare function sitemapXml(paths: readonly string[], routing: LocaleRouting, origin: string): string;
+/**
+ * Every page of the store a sitemap lists, unprefixed: home, the catalog,
+ * each category, each product (the whole catalog, read page by page) and each
+ * published text page.
+ */
+export declare function catalogPaths(client: StoreClient, config: Pick<StoreConfig, "pages">): Promise<string[]>;

package/dist/sitemap.js

@@ -0,0 +1,51 @@
+import { PRODUCT_PAGE_MAX } from "./client/products.js";
+import { alternateLinks, localizeHref } from "./locale-routing.js";
+import { storefrontPath } from "./routes.js";
+/** The most catalog pages `catalogPaths` reads: a sitemap holds 50,000 addresses at most. */
+const MAX_CATALOG_PAGES = 500;
+const escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+/**
+ * The sitemap of `paths` — unprefixed page paths (`/products/robe`) — on
+ * `origin`, in every language `routing` publishes. A path given twice is
+ * listed once.
+ */
+export function sitemapXml(paths, routing, origin) {
+    const base = origin.replace(/\/+$/, "");
+    const multilingual = routing.published.length > 1;
+    const urls = [...new Set(paths)].flatMap((path) => {
+        const alternates = multilingual
+            ? alternateLinks(path, routing, base).map((link) => `    <xhtml:link rel="alternate" hreflang="${escapeXml(link.hreflang)}" href="${escapeXml(link.href)}"/>`)
+            : [];
+        return routing.published.map((locale) => ["  <url>", `    <loc>${escapeXml(`${base}${localizeHref(path, locale, routing)}`)}</loc>`, ...alternates, "  </url>"].join("\n"));
+    });
+    return [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">',
+        ...urls,
+        "</urlset>",
+        "",
+    ].join("\n");
+}
+/**
+ * Every page of the store a sitemap lists, unprefixed: home, the catalog,
+ * each category, each product (the whole catalog, read page by page) and each
+ * published text page.
+ */
+export async function catalogPaths(client, config) {
+    const products = [];
+    const categories = client.categories.list();
+    for (let page = 0, offset = 0; page < MAX_CATALOG_PAGES; page++) {
+        const result = await client.products.page({ limit: PRODUCT_PAGE_MAX, offset });
+        products.push(...result.items.map((product) => storefrontPath("product", { handle: product.handle })));
+        if (!result.hasNext || result.items.length === 0)
+            break;
+        offset += result.items.length;
+    }
+    return [
+        storefrontPath("home"),
+        storefrontPath("catalog"),
+        ...(await categories).map((category) => storefrontPath("category", { slug: category.slug })),
+        ...products,
+        ...config.pages.map((page) => storefrontPath("page", { slug: page.slug })),
+    ];
+}

package/dist/store-request.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Which store a request renders, in which language — the rules every theme's
+ * middleware needs, decided once:
+ *
+ * - A page takes its language from its path (`/fr/products/robe`). The
+ *   primary's own prefix redirects permanently to its one address (`/ar/x` →
+ *   `/x`); a language the store stopped publishing redirects temporarily to the
+ *   primary page, since it may publish it again.
+ * - An endpoint (`/api/…`) or a server island (`/_server-islands/…`) serves part
+ *   of a page in a request with no language in its URL: it takes the language
+ *   of the page that asked, from its same-origin `Referer`, and is never
+ *   redirected or rewritten.
+ * - An editor's preview renders the store as the draft would leave it, in the
+ *   language the draft asks for when the store serves it.
+ *
+ * The theme keeps what is its own: the client it creates (one per request),
+ * the config it falls back to when the store cannot be read, and the context
+ * it builds from what these return.
+ */
+import type { StoreClient } from "./client/index.js";
+import { type LocaleRouting } from "./locale-routing.js";
+import { type PreviewDraft } from "./preview.js";
+import type { StoreConfig } from "./types.js";
+export interface StoreRequestOptions {
+    /** The request's client in `locale`, or in the store's primary language when absent. */
+    client: (locale?: string) => StoreClient;
+    /** What renders when the store's config cannot be read: a shell with the checkout switched off. */
+    fallback: StoreConfig;
+    /** Whether a path serves part of a page rather than a page. Default: `/api/` and `/_server-islands/`. */
+    embedded?: (pathname: string) => boolean;
+}
+/** The store a request renders. */
+export interface ResolvedStore {
+    /** The client in this request's language; every read of the page goes through it. */
+    client: StoreClient;
+    config: StoreConfig;
+    /** The language this request renders in. */
+    locale: string;
+    /** The store's languages, as links need them. */
+    routing: LocaleRouting;
+    /** The path without its language prefix: the route the page renders. */
+    pathname: string;
+}
+export type StoreRequestResolution = ({
+    kind: "page";
+    /** An endpoint or server island: never redirected, never rewritten. */
+    embedded: boolean;
+    /** The path and query to render instead of the request's (`/fr/x` renders `/x`); null to render it as it is. */
+    rewrite: string | null;
+} & ResolvedStore) | {
+    kind: "redirect";
+    /** Where the shopper goes, the request's query kept. */
+    location: string;
+    status: 301 | 302;
+};
+/**
+ * The store a request renders and the language it renders in, or the redirect
+ * it answers:
+ *
+ * ```ts
+ * const request = await resolveStoreRequest(
+ *   { url: context.url, referer: context.request.headers.get("Referer") },
+ *   { client: createStore, fallback: FALLBACK_CONFIG },
+ * );
+ * if (request.kind === "redirect") return context.redirect(request.location, request.status);
+ * context.locals.store = buildContext(request);
+ * return request.rewrite ? next(request.rewrite) : next();
+ * ```
+ */
+export declare function resolveStoreRequest(request: {
+    url: URL;
+    referer: string | null;
+}, options: StoreRequestOptions): Promise<StoreRequestResolution>;
+/**
+ * The store an editor's draft previews: its theme settings and text edits
+ * over the saved ones, conversion tracking off, in the language the draft
+ * asks for when the store serves it — else the primary. `pathname` is the
+ * route the draft previews (`draft.path`), else the home page.
+ */
+export declare function resolvePreviewStore(draft: PreviewDraft, options: Omit<StoreRequestOptions, "embedded">): Promise<ResolvedStore>;
+/** What `notFound` uses of a page's `Astro` global. */
+export interface NotFoundContext {
+    cache?: {
+        set(options: false): void;
+    };
+    response: {
+        status?: number | undefined;
+    };
+    rewrite(path: string): Promise<Response>;
+}
+/**
+ * Answers a page whose resource does not exist — `return notFound(Astro)` —
+ * with the theme's not-found page (`/404`) and status 404, and never caches
+ * it: a product published a minute later must show, not the cached refusal.
+ */
+export declare function notFound(context: NotFoundContext, page?: string): Promise<Response>;

package/dist/store-request.js

@@ -0,0 +1,102 @@
+import { localeRouting, resolveLocalePath } from "./locale-routing.js";
+import { previewConfig } from "./preview.js";
+const defaultEmbedded = (pathname) => pathname.startsWith("/api/") || pathname.startsWith("/_server-islands/");
+async function primaryStore(options) {
+    const client = options.client();
+    const config = (await client.config.get()) ?? options.fallback;
+    return { client, config, routing: localeRouting(config) };
+}
+async function resolvePath(path, primary, options) {
+    const { routing } = primary;
+    const resolved = resolveLocalePath(path, routing);
+    if (resolved.kind === "redirect")
+        return { kind: "redirect", location: resolved.location, status: 301 };
+    if (resolved.locale === routing.primary)
+        return { kind: "page", client: primary.client, config: primary.config, locale: resolved.locale, routing, pathname: resolved.pathname };
+    const client = options.client(resolved.locale);
+    const config = (await client.config.get()) ?? primary.config;
+    if (config.locale !== resolved.locale)
+        return { kind: "redirect", location: resolved.pathname, status: 302 };
+    return { kind: "page", client, config, locale: resolved.locale, routing, pathname: resolved.pathname };
+}
+/** The page an embedded request serves part of: its same-origin `Referer`'s path, else the home page. */
+function askingPage(url, referer) {
+    if (referer === null)
+        return "/";
+    try {
+        const page = new URL(referer);
+        return page.origin === url.origin ? page.pathname : "/";
+    }
+    catch {
+        return "/";
+    }
+}
+/**
+ * The store a request renders and the language it renders in, or the redirect
+ * it answers:
+ *
+ * ```ts
+ * const request = await resolveStoreRequest(
+ *   { url: context.url, referer: context.request.headers.get("Referer") },
+ *   { client: createStore, fallback: FALLBACK_CONFIG },
+ * );
+ * if (request.kind === "redirect") return context.redirect(request.location, request.status);
+ * context.locals.store = buildContext(request);
+ * return request.rewrite ? next(request.rewrite) : next();
+ * ```
+ */
+export async function resolveStoreRequest(request, options) {
+    const { url } = request;
+    const embedded = (options.embedded ?? defaultEmbedded)(url.pathname);
+    const primary = await primaryStore(options);
+    let resolved = await resolvePath(embedded ? askingPage(url, request.referer) : url.pathname, primary, options);
+    if (resolved.kind === "redirect") {
+        if (!embedded)
+            return { kind: "redirect", location: `${resolved.location}${url.search}`, status: resolved.status };
+        // The asking page's own address redirects: serve the part as its target would.
+        for (let hops = 0; resolved.kind === "redirect" && hops < 3; hops++)
+            resolved = await resolvePath(resolved.location, primary, options);
+        if (resolved.kind === "redirect")
+            resolved = { kind: "page", client: primary.client, config: primary.config, locale: primary.routing.primary, routing: primary.routing, pathname: "/" };
+    }
+    const { client, config, locale, routing, pathname } = resolved;
+    return {
+        kind: "page",
+        embedded,
+        rewrite: embedded || pathname === url.pathname ? null : `${pathname}${url.search}`,
+        client,
+        config,
+        locale,
+        routing,
+        pathname,
+    };
+}
+/**
+ * The store an editor's draft previews: its theme settings and text edits
+ * over the saved ones, conversion tracking off, in the language the draft
+ * asks for when the store serves it — else the primary. `pathname` is the
+ * route the draft previews (`draft.path`), else the home page.
+ */
+export async function resolvePreviewStore(draft, options) {
+    const primary = await primaryStore(options);
+    const { routing } = primary;
+    const pathname = draft.path ?? "/";
+    const asked = draft.locale;
+    if (asked !== undefined && asked !== routing.primary && routing.published.includes(asked)) {
+        const client = options.client(asked);
+        const config = await client.config.get();
+        if (config !== null && config.locale === asked)
+            return { client, config: previewConfig(config, draft), locale: asked, routing, pathname };
+    }
+    return { client: primary.client, config: previewConfig(primary.config, draft), locale: routing.primary, routing, pathname };
+}
+/**
+ * Answers a page whose resource does not exist — `return notFound(Astro)` —
+ * with the theme's not-found page (`/404`) and status 404, and never caches
+ * it: a product published a minute later must show, not the cached refusal.
+ */
+export function notFound(context, page = "/404") {
+    context.cache?.set(false);
+    context.response.status = 404;
+    return context.rewrite(page);
+}