@wocart/storefront 2.2.0 → 3.0.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/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);