@wocart/storefront 2.2.0 → 3.1.0

package/dist/schemas.js

@@ -15,24 +15,18 @@ export const ProductImageSchema = MediaImageSchema.extend({
     altText: z.string().nullable(),
     position: z.number().int().min(0),
 });
+/** One active variant of a product, in the merchant's order; its selection in the client's language. */
 export const ProductVariantSchema = z.object({
     id: z.string(),
-    productId: z.string(),
     variations: z.record(z.string(), z.string()),
-    currency: z.string(),
     price: z.number().int().min(0),
     compareAtPrice: z.number().int().min(0).nullable(),
     sku: z.string().nullable(),
-    barcode: z.string().nullable(),
     inventory: z.number().int().min(0),
     lowStockThreshold: z.number().int().min(0),
-    weightKg: z.number().min(0).nullable(),
+    /** The product image this variant shows. */
     imageId: z.string().nullable(),
     isDefault: z.boolean(),
-    active: z.boolean(),
-    position: z.number().int().min(0),
-    createdAt: z.string().datetime(),
-    updatedAt: z.string().datetime(),
 });
 export const OfferSchema = z.object({
     id: z.string(),
@@ -45,9 +39,8 @@ export const OfferSchema = z.object({
     rewardProductName: z.string(),
     rewardVariantId: z.string().nullable(),
     rewardVariantLabel: z.string().nullable(),
-    // What one gift unit is worth at list price. Optional: a server that predates
-    // it omits the field, and the product's own price stands in for the gift.
-    rewardUnitPrice: z.number().nullish(),
+    /** What one gift unit is worth at list price: the reward variant's price, or its product's. */
+    rewardUnitPrice: z.number().nullable(),
 });
 /**
  * Quantity pricing — price tiers by quantity ("2 for 3,500 DA"). The highest
@@ -83,6 +76,18 @@ const reviewStatsSchema = z.object({
     avgRating: z.number(),
     reviewCount: z.number().int(),
 });
+const variantOptionSchema = z.object({
+    name: z.string(),
+    values: z.array(z.object({
+        value: z.string(),
+        // The key may be ABSENT, not just null: rows written before the colour
+        // picker existed never carry it, and a strict `.nullable()` would reject
+        // the whole product, since a failed read degrades to null. Normalising to
+        // null keeps the public shape `string | null` for every consumer.
+        hexColor: z.string().nullable().default(null),
+    })),
+});
+/** A product as a storefront reads it, in the client's language — the fields a listing and a product page share. */
 const productBaseFields = {
     id: z.string(),
     name: z.string(),
@@ -93,71 +98,35 @@ 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(),
+    /** The option axes a shopper picks from; null for a product without variants. */
+    variantOptions: z.array(variantOptionSchema).nullable(),
     sku: z.string().nullable(),
     inventory: z.number().int(),
     trackInventory: z.boolean(),
     lowStockThreshold: z.number().int(),
     categoryId: z.string().nullable(),
-    visibility: z.boolean(),
-    status: z.enum(["DRAFT", "ACTIVE", "ARCHIVED"]),
-    showInStore: z.boolean(),
-    /** @deprecated Whether the product is in the `featured` collection; list it with `collection: "featured"`. Removed in 2.0. */
-    storeFeatured: z.boolean(),
-    /**
-     * @deprecated Always null: the server never serves a removed product. The
-     * server still sends it for older releases; it will stop, and a later major
-     * drops it. Do not read it.
-     */
-    deletedAt: z.null().optional(),
-    publishedAt: z.string().datetime().nullable(),
-    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(),
+    tags: z.array(z.string()),
+    /** The title search engines and shared links show; null: `productMeta(product)` falls back to the name. */
+    metaTitle: z.string().nullable(),
+    /** The description search engines and shared links show; null: `productMeta(product)` shortens the product's own. */
+    metaDescription: z.string().nullable(),
+    reviewStats: reviewStatsSchema.nullable(),
 };
-const variantOptionSchema = z.object({
-    name: z.string(),
-    values: z.array(z.object({
-        value: z.string(),
-        // The key may be ABSENT, not just null: rows written before the colour
-        // picker existed never carry it, and a strict `.nullable()` would reject
-        // the whole product, since a failed read degrades to null. Normalising to
-        // null keeps the public shape `string | null` for every consumer.
-        hexColor: z.string().nullable().default(null),
-    })),
-});
-const rawProductFields = {
+/** A product in a listing: its first photo stands for it. */
+export const ProductListSchema = z.object({
     ...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(),
-};
-export const ProductListSchema = z.object(rawProductFields);
+});
+/** A product's page: every photo, variant and offer, and its category. */
 export const ProductSchema = z.object({
     ...productBaseFields,
-    variantOptions: z.array(variantOptionSchema).nullable(),
-    tags: z.array(z.string()),
     category: productCategorySchema.nullable(),
     variants: z.array(ProductVariantSchema),
     images: z.array(ProductImageSchema),
-    reviewStats: reviewStatsSchema.nullable(),
-    /**
-     * The product's live quantity pricing; null or absent when it has none
-     * (absent from a server that predates it).
-     */
-    quantityPricing: QuantityPricingSchema.nullish(),
+    /** The product's live quantity pricing; null when it has none. */
+    quantityPricing: QuantityPricingSchema.nullable(),
     offers: z.array(OfferSchema),
 });
 export const StorePagePublicSchema = z.object({
@@ -186,10 +155,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(),
+    /** How many products a shopper sees in it. */
+    productCount: z.number().int().min(0),
+    /** Its first listed product's first photo; null while it lists none with one. */
+    image: ProductImageSchema.nullable(),
 });
 export const StoreMenuSchema = z.object({
     handle: z.string(),
@@ -218,11 +187,10 @@ export const StorePageLinkSchema = z.object({
     title: z.string(),
     position: z.number().int(),
 });
-export const StoreLegalContactSchema = z.object({
-    contactEmail: z.string().nullable(),
-    contactPhone: z.string().nullable(),
-    deliveryMinDays: z.number().int(),
-    deliveryMaxDays: z.number().int(),
+export const StoreContactSchema = z.object({
+    phone: z.string().nullable(),
+    email: z.string().nullable(),
+    address: z.string().nullable(),
 });
 export const StoreWhatsAppWidgetSchema = z.object({
     href: z.string(),
@@ -234,8 +202,8 @@ export const StoreWhatsAppWidgetSchema = z.object({
     ctaLabel: z.string().nullable(),
     prefillGeneral: z.string().nullable(),
     prefillProduct: z.string().nullable(),
-    thankYouButtonLabel: z.string().nullable().default(null),
-    prefillThankYou: z.string().nullable().default(null),
+    thankYouButtonLabel: z.string().nullable(),
+    prefillThankYou: z.string().nullable(),
     accent: z.enum(["whatsapp", "primary"]),
     position: z.enum(["right", "left"]),
     attention: z.boolean(),
@@ -273,12 +241,6 @@ export const StoreConfigSchema = z.object({
     name: z.string(),
     domain: z.string().nullable(),
     logo: MediaImageSchema.nullable(),
-    themeId: z.string(),
-    primaryColor: z.string(),
-    accentColor: z.string(),
-    bgColor: z.string(),
-    fontFamily: z.string(),
-    fontUrl: z.string().nullable(),
     lang: z.string().min(1),
     locale: z.string().min(1),
     /**
@@ -286,44 +248,28 @@ export const StoreConfigSchema = z.object({
      * server owns which languages exist, so a new one never fails this parse.
      */
     locales: z.array(StorefrontLanguageSchema),
-    /** The requesting theme's text edits, one map per published language. */
-    contentOverrides: z.record(z.string(), z.record(z.string(), z.string())),
-    /**
-     * The store's values for the requesting theme's settings, as saved. Absent
-     * from a server older than theme settings.
-     */
-    themeSettings: z.record(z.string(), z.unknown()).optional(),
     currency: z.string(),
     currencySymbol: z.string(),
     metaTitle: z.string().nullable(),
     metaDescription: z.string().nullable(),
     ogImage: MediaImageSchema.nullable(),
     media: MediaDeliverySchema,
-    announcementBar: z.string().nullable(),
     reviewsEnabled: z.boolean(),
     cartEnabled: z.boolean(),
     freeShippingThreshold: z.number().int().nullable(),
-    cartShippingMode: z.enum(["highest", "default_profile"]).default("highest"),
+    /** The requesting theme's text edits, one map per published language. */
+    contentOverrides: z.record(z.string(), z.record(z.string(), z.string())),
+    /** The store's values for the requesting theme's settings, as saved. */
+    themeSettings: z.record(z.string(), z.unknown()),
+    checkoutForm: CheckoutFormPolicySchema,
+    whatsapp: StoreWhatsAppWidgetSchema.nullable(),
+    pixelId: z.string().nullable(),
+    conversionEvent: z.enum(["Purchase", "Purchase_Confirmed", "Purchase_Delivered", "Lead"]),
+    pages: z.array(StorePageLinkSchema),
+    contact: StoreContactSchema,
     otpEnabled: z.boolean(),
     turnstileEnabled: z.boolean(),
     turnstileSiteKey: z.string().nullable(),
-    status: z.enum(["active", "inactive"]),
-    createdAt: z.string().optional().default(() => new Date().toISOString()),
-    updatedAt: z.string().optional().default(() => new Date().toISOString()),
-    checkoutForm: CheckoutFormPolicySchema.default({
-        address: "optional",
-        notes: "optional",
-        email: "optional",
-        deliveryOptions: { home: true, stopDesk: true },
-        customFields: [],
-    }),
-    pixelId: z.string().nullable().default(null),
-    conversionEvent: z
-        .enum(["Purchase", "Purchase_Confirmed", "Purchase_Delivered", "Lead"])
-        .default("Purchase"),
-    pages: z.array(StorePageLinkSchema).default([]),
-    legalContact: StoreLegalContactSchema.nullable().default(null),
-    whatsapp: StoreWhatsAppWidgetSchema.nullable().default(null),
 });
 export const LandingPageImageSchema = MediaImageSchema.extend({
     id: z.string(),
@@ -341,7 +287,7 @@ export const LandingPageSchema = z.object({
     publishedAt: z.string().nullable(),
     images: z.array(LandingPageImageSchema),
     product: ProductSchema.nullable(),
-    document: PageDocumentPayloadSchema.nullable().catch(null).default(null),
+    document: PageDocumentPayloadSchema.nullable().catch(null),
     tracking: z.object({
         pixelId: z.string().nullable(),
         conversionEvent: z.enum([
@@ -370,24 +316,24 @@ export const CartValidationLineSchema = z.object({
     quantity: z.number().int(),
     unitPrice: z.number(),
     lineTotal: z.number(),
-    /** The offer applied to the line; absent from a server that predates offers on lines. */
-    offerId: z.string().nullish(),
-    /** That offer's name, in the shopper's language; absent from an older server. */
-    offerName: z.string().nullish(),
-    /** The line's share of the coupon's discount, already out of `lineTotal`; absent from a server that predates coupons. */
-    discount: z.number().nullish(),
+    /** The offer applied to the line. */
+    offerId: z.string().nullable(),
+    /** That offer's name, in the shopper's language. */
+    offerName: z.string().nullable(),
+    /** The line's share of the coupon's discount, already out of `lineTotal`. */
+    discount: z.number(),
     maxQuantity: z.number().nullable(),
     blocker: z.enum(["missing", "unlisted", "out_of_stock"]).nullable(),
 });
 export const CartRewardSchema = z.object({
     offerId: z.string(),
-    /** The offer's name, in the shopper's language; absent from an older server. */
-    offerName: z.string().nullish(),
+    /** The offer's name, in the shopper's language. */
+    offerName: z.string().nullable(),
     productId: z.string().nullable(),
     productName: z.string().nullable(),
-    /** The variant given and its label; absent from an older server. */
-    variantId: z.string().nullish(),
-    variantLabel: z.string().nullish(),
+    /** The variant given and its label; null for a product without variants. */
+    variantId: z.string().nullable(),
+    variantLabel: z.string().nullable(),
     quantity: z.number().int(),
 });
 /**
@@ -409,6 +355,8 @@ export const CartValidationSchema = z.object({
         threshold: z.number().nullable(),
         qualified: z.boolean(),
         remaining: z.number(),
+        /** Why delivery is free: an offer, the coupon or the store's amount; null when it is not. */
+        by: z.enum(["offer", "coupon", "threshold"]).nullable(),
     }),
     delivery: z
         .discriminatedUnion("available", [
@@ -416,8 +364,8 @@ export const CartValidationSchema = z.object({
         z.object({ available: z.literal(false), fee: z.null(), total: z.null() }),
     ])
         .optional(),
-    /** The code's outcome: null without one; absent from a server that predates coupons. */
-    coupon: CouponOutcomeSchema.nullish(),
+    /** The code's outcome: null without one. */
+    coupon: CouponOutcomeSchema.nullable(),
 });
 export const CreatedOrderSchema = z.object({
     orderId: z.string(),
@@ -425,8 +373,8 @@ export const CreatedOrderSchema = z.object({
     price: z.number(),
     deliveryFee: z.number(),
     total: z.number(),
-    /** What the coupon took off; absent from a server that predates coupons. */
-    couponDiscount: z.number().nullish(),
+    /** What the coupon took off. */
+    couponDiscount: z.number(),
 });
 export const OrderTrackingSchema = z.object({
     pixelId: z.string().nullable(),
@@ -445,10 +393,10 @@ export const ShopperOrderStatusSchema = z.object({
     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. */
+/** A page of products with the whole listing's size. */
 export const ProductPageEnvelopeSchema = z.object({
     data: z.array(ProductListSchema),
-    total: z.number().int().min(0).optional(),
+    total: z.number().int().min(0),
 });
 /**
  * The `{ id }` success payload of the write endpoints that only mint a row:
@@ -483,25 +431,17 @@ export const ReviewMediaSchema = z.object({
     height: z.number().int().nullable(),
     durationMs: z.number().int().nullable(),
 });
-export const ReviewSchema = z.preprocess((raw) => {
-    if (typeof raw === "object" && raw !== null) {
-        const obj = raw;
-        return {
-            ...obj,
-            customerName: obj.customerName ?? obj.authorName ?? "Customer",
-        };
-    }
-    return raw;
-}, z.object({
+/** An approved review, newest first: who wrote it, and whether a delivered order proves the purchase. */
+export const ReviewSchema = z.object({
     id: z.string(),
     customerName: z.string(),
     rating: z.number(),
-    title: z.string().nullable().optional().default(null),
+    title: z.string().nullable(),
     body: z.string(),
     createdAt: z.string(),
-    verified: z.boolean().optional().default(false),
-    media: z.array(ReviewMediaSchema).optional().default([]),
-}));
+    verified: z.boolean(),
+    media: z.array(ReviewMediaSchema),
+});
 export const ReviewEligibilitySchema = z.object({
     orderNumber: z.string(),
     customerName: z.string(),
@@ -527,7 +467,7 @@ export const ReviewUploadSchema = z.object({
 });
 export const ReviewSubmitResultSchema = z.object({
     id: z.string(),
-    visibility: z.enum(["published", "after_review"]).optional(),
+    visibility: z.enum(["published", "after_review"]),
 });
 /**
  * GET /store/reviews answers `{ success, data: rows, count, total }` — the

package/dist/seo.js

@@ -44,7 +44,7 @@ const AVAILABILITY = { inStock: "https://schema.org/InStock", outOfStock: "https
 export function productStructuredData(product, options) {
     const meta = productMeta(product);
     const view = getProductView(product);
-    const variants = product.hasVariants ? product.variants.filter((variant) => variant.active) : [];
+    const variants = product.hasVariants ? product.variants : [];
     const prices = variants.map((variant) => variant.price);
     const sellable = product.hasVariants
         ? variants.some((variant) => !product.trackInventory || variant.inventory > 0)
@@ -55,7 +55,7 @@ export function productStructuredData(product, options) {
         ? { "@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.url);
+    const images = product.images.map((image) => image.url);
     const rating = product.reviewStats && product.reviewStats.reviewCount > 0 ? product.reviewStats : null;
     return {
         "@context": "https://schema.org",

package/dist/server.d.ts

@@ -3,7 +3,7 @@ export type { StoreClient } from "./client/index.js";
 export type { ClientResult } from "./client/core.js";
 export { StorefrontError, isStorefrontError } from "./client/errors.js";
 export { previewConfig, previewResponseHeaders, readPreviewRequest, verifyPreviewToken } from "./preview.js";
-export { REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
+export { PAGES_CACHE_TAG, 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

@@ -1,5 +1,5 @@
 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 { PAGES_CACHE_TAG, REVALIDATE_PATH, readRevalidateRequest } from "./revalidate.js";
 export { catalogPaths, sitemapXml } from "./sitemap.js";

package/dist/store-request.d.ts

@@ -14,8 +14,9 @@
  *   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.
+ * the config it falls back to when the store cannot be read
+ * (`unavailableStoreConfig`), and the context it builds from what these
+ * return.
  */
 import type { StoreClient } from "./client/index.js";
 import { type LocaleRouting } from "./locale-routing.js";
@@ -24,7 +25,7 @@ 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. */
+    /** What renders when the store's config cannot be read: `unavailableStoreConfig(…)`. */
     fallback: StoreConfig;
     /** Whether a path serves part of a page rather than a page. Default: `/api/` and `/_server-islands/`. */
     embedded?: (pathname: string) => boolean;
@@ -60,7 +61,7 @@ export type StoreRequestResolution = ({
  * ```ts
  * const request = await resolveStoreRequest(
  *   { url: context.url, referer: context.request.headers.get("Referer") },
- *   { client: createStore, fallback: FALLBACK_CONFIG },
+ *   { client: createStore, fallback: unavailableStoreConfig({ serverUrl: env.COD_SERVER_URL }) },
  * );
  * if (request.kind === "redirect") return context.redirect(request.location, request.status);
  * context.locals.store = buildContext(request);

package/dist/store-request.js

@@ -38,7 +38,7 @@ function askingPage(url, referer) {
  * ```ts
  * const request = await resolveStoreRequest(
  *   { url: context.url, referer: context.request.headers.get("Referer") },
- *   { client: createStore, fallback: FALLBACK_CONFIG },
+ *   { client: createStore, fallback: unavailableStoreConfig({ serverUrl: env.COD_SERVER_URL }) },
  * );
  * if (request.kind === "redirect") return context.redirect(request.location, request.status);
  * context.locals.store = buildContext(request);

package/dist/storefront-middleware.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The request lifecycle every theme's `src/middleware.ts` runs, in one call:
+ *
+ * ```ts
+ * // src/middleware.ts
+ * import { getActionContext } from "astro:actions";
+ * import { createStorefrontMiddleware } from "@wocart/storefront/astro";
+ * import { THEME_PREVIEW_PATH } from "@wocart/theme";
+ *
+ * export const onRequest = createStorefrontMiddleware({
+ *   client: createStore,
+ *   fallback: unavailableStoreConfig({ serverUrl, locale: "ar" }),
+ *   preview: { path: THEME_PREVIEW_PATH, publicKey: () => WOCART_PREVIEW_KEY, theme: THEME_KEY },
+ *   context: (store) => buildStoreContext(store),
+ *   getActionContext,
+ * });
+ * ```
+ *
+ * In order:
+ *
+ * - A prerendered file (the manifest, the theme's styles) and the
+ *   revalidation route (`REVALIDATE_PATH`) need no store.
+ * - A request that already has a store keeps it: a page's `notFound()`
+ *   rewrites to `/404` and Astro runs the middleware again, and the 404 must
+ *   stay in the language the shopper asked for.
+ * - The editor's preview (`preview.path`) renders the store as the draft
+ *   would leave it, after its token is verified; it never runs a form action.
+ * - Any other request resolves its store and language
+ *   (`resolveStoreRequest`), answers its redirect if it has one, builds the
+ *   theme's context, runs a form-called action for the page this POST renders
+ *   (`runFormAction`), then renders the unprefixed route.
+ *
+ * `astro:actions` is an Astro virtual module, so the theme passes
+ * `getActionContext` in. The theme's context becomes `locals.store`; a
+ * verified preview's claims, draft and token become `locals.preview`.
+ */
+import type { StoreClient } from "./client/index.js";
+import { type ActionDescriptor, type ActionHandlerResult } from "./middleware.js";
+import { type PreviewClaims, type PreviewDraft, type PreviewRequestOptions } from "./preview.js";
+import { type ResolvedStore } from "./store-request.js";
+import type { StoreConfig } from "./types.js";
+/** What a verified preview leaves on `locals.preview`. */
+export interface PreviewLocals {
+    claims: PreviewClaims;
+    draft: PreviewDraft;
+    token: string;
+}
+/** What the middleware uses of Astro's `APIContext`. */
+export interface StorefrontMiddlewareContext {
+    isPrerendered: boolean;
+    url: URL;
+    request: Request;
+    /** `App.Locals`: the middleware writes `store` and, on a preview, `preview`. */
+    locals: object;
+    redirect(location: string, status: 301 | 302): Response;
+}
+/** What the middleware uses of `getActionContext(context)`. */
+export interface StorefrontActionContext<TResult extends ActionHandlerResult, TSerialized> {
+    action?: ActionDescriptor<TResult> | undefined;
+    setActionResult: (name: string, serialized: TSerialized) => void;
+    serializeActionResult: (result: TResult) => TSerialized;
+}
+export interface StorefrontMiddlewareOptions<TContext extends StorefrontMiddlewareContext, TStore, TResult extends ActionHandlerResult, TSerialized> {
+    /** The theme's one client factory: 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: `unavailableStoreConfig(…)`. */
+    fallback: StoreConfig;
+    /**
+     * The editor's preview route (`THEME_PREVIEW_PATH`) and how its token is
+     * checked; no `publicKey`: the route answers 404. Pass the key as a
+     * function to read it on each request: a secret from `astro:env/server`
+     * can be set after the module loads.
+     */
+    preview: {
+        path: string;
+        publicKey: PreviewRequestOptions["publicKey"] | (() => PreviewRequestOptions["publicKey"]);
+    } & Pick<PreviewRequestOptions, "theme" | "maxBytes">;
+    /** The theme's context for a resolved store; it becomes `locals.store`. */
+    context: (store: ResolvedStore) => TStore;
+    /** Astro's `getActionContext`, from `astro:actions`. */
+    getActionContext: (context: TContext) => StorefrontActionContext<TResult, TSerialized>;
+    /** Whether a path serves part of a page rather than a page. Default: `/api/` and `/_server-islands/`. */
+    embedded?: (pathname: string) => boolean;
+}
+/** An Astro middleware handler (`onRequest`). */
+export type StorefrontMiddleware<TContext extends StorefrontMiddlewareContext> = (context: TContext, next: (rewrite?: string) => Promise<Response>) => Promise<Response>;
+/** The theme's `onRequest`: store, language, redirects, preview and form actions, as described above. */
+export declare function createStorefrontMiddleware<TContext extends StorefrontMiddlewareContext, TStore, TResult extends ActionHandlerResult, TSerialized>(options: StorefrontMiddlewareOptions<TContext, TStore, TResult, TSerialized>): StorefrontMiddleware<TContext>;

package/dist/storefront-middleware.js

@@ -0,0 +1,37 @@
+import { runFormAction } from "./middleware.js";
+import { readPreviewRequest } from "./preview.js";
+import { REVALIDATE_PATH } from "./revalidate.js";
+import { resolvePreviewStore, resolveStoreRequest } from "./store-request.js";
+/** The theme's `onRequest`: store, language, redirects, preview and form actions, as described above. */
+export function createStorefrontMiddleware(options) {
+    const store = { client: options.client, fallback: options.fallback, ...(options.embedded ? { embedded: options.embedded } : {}) };
+    const { path: previewPath, publicKey, ...previewOptions } = options.preview;
+    return async (context, next) => {
+        const locals = context.locals;
+        if (context.isPrerendered)
+            return next();
+        if (context.url.pathname === REVALIDATE_PATH)
+            return next();
+        if (locals.store !== undefined)
+            return next();
+        if (context.url.pathname === previewPath) {
+            const preview = await readPreviewRequest(context.request, { ...previewOptions, publicKey: typeof publicKey === "function" ? publicKey() : publicKey });
+            if (!preview.ok)
+                return new Response(null, { status: preview.status, headers: { "Cache-Control": "no-store" } });
+            locals.store = options.context(await resolvePreviewStore(preview.draft, store));
+            locals.preview = { claims: preview.claims, draft: preview.draft, token: preview.token };
+            return next();
+        }
+        const request = await resolveStoreRequest({ url: context.url, referer: context.request.headers.get("Referer") }, store);
+        if (request.kind === "redirect")
+            return context.redirect(request.location, request.status);
+        locals.store = options.context(request);
+        const { action, setActionResult, serializeActionResult } = options.getActionContext(context);
+        await runFormAction({
+            ...(action ? { action: { calledFrom: action.calledFrom, name: action.name, handler: action.handler } } : {}),
+            setActionResult,
+            serializeActionResult,
+        });
+        return request.rewrite === null ? next() : next(request.rewrite);
+    };
+}

package/dist/thank-you.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The thank-you page's address for a placed order, and its reading back. The
+ * query carries the order's number, total and id — never the shopper's
+ * details — so the page can thank, show the total and fire a conversion
+ * without reading the order again. One spelling, here: a theme writes it
+ * after `placeOrder`, its thank-you page reads it, and an editor previews
+ * the page with a sample order by building the same address.
+ */
+import { type LocaleRouting } from "./locale-routing.js";
+/** What the thank-you page reads from its address. */
+export interface ThankYouOrder {
+    /** The order number the shopper is given; empty when the address has none. */
+    orderNumber: string;
+    /** The order's id, for a conversion's deduplication; empty when the address has none. */
+    orderId: string;
+    /** The order's total in the store's currency; null when missing or not a number. */
+    total: number | null;
+}
+/**
+ * The thank-you page for a placed order: `/thank-you?order=…&total=…&oid=…`,
+ * in the request's language when `language` is given (`/fr/thank-you?…`).
+ */
+export declare function thankYouHref(order: {
+    orderNumber: string;
+    total: number;
+    orderId?: string | null;
+}, language?: {
+    locale: string;
+    routing: LocaleRouting;
+}): string;
+/** The order a thank-you address names: `thankYouHref`'s query, read back and trimmed. */
+export declare function readThankYou(url: URL | URLSearchParams): ThankYouOrder;

package/dist/thank-you.js

@@ -0,0 +1,33 @@
+/**
+ * The thank-you page's address for a placed order, and its reading back. The
+ * query carries the order's number, total and id — never the shopper's
+ * details — so the page can thank, show the total and fire a conversion
+ * without reading the order again. One spelling, here: a theme writes it
+ * after `placeOrder`, its thank-you page reads it, and an editor previews
+ * the page with a sample order by building the same address.
+ */
+import { localizeHref } from "./locale-routing.js";
+import { storefrontPath } from "./routes.js";
+const ORDER_NUMBER = "order";
+const TOTAL = "total";
+const ORDER_ID = "oid";
+/**
+ * The thank-you page for a placed order: `/thank-you?order=…&total=…&oid=…`,
+ * in the request's language when `language` is given (`/fr/thank-you?…`).
+ */
+export function thankYouHref(order, language) {
+    const query = new URLSearchParams({ [ORDER_NUMBER]: order.orderNumber, [TOTAL]: String(order.total), [ORDER_ID]: order.orderId ?? "" });
+    const path = storefrontPath("thankYou");
+    return `${language ? localizeHref(path, language.locale, language.routing) : path}?${query.toString()}`;
+}
+/** The order a thank-you address names: `thankYouHref`'s query, read back and trimmed. */
+export function readThankYou(url) {
+    const params = url instanceof URLSearchParams ? url : url.searchParams;
+    const raw = params.get(TOTAL)?.trim() ?? "";
+    const total = /^-?\d+$/.test(raw) ? Number.parseInt(raw, 10) : Number.NaN;
+    return {
+        orderNumber: (params.get(ORDER_NUMBER) ?? "").trim(),
+        orderId: (params.get(ORDER_ID) ?? "").trim(),
+        total: Number.isFinite(total) ? total : null,
+    };
+}