@wocart/storefront 1.19.0 → 1.21.0

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+import type { COUPON_REFUSAL_REASONS } from "./coupon.js";
+import type { PRODUCT_SORTS, SHOPPER_ORDER_STAGES } from "./catalog.js";
 import { z } from "zod";
 import { ProductSchema, ProductListSchema, CategorySchema, ProductImageSchema, ProductVariantSchema, OfferSchema, QuantityPricingSchema, PageDocumentPayloadSchema } from "./schemas.js";
 export type Product = z.infer<typeof ProductSchema>;
@@ -221,6 +223,10 @@ export interface StoreCollection {
     /** In the client's language when the store translated it, else the primary. */
     title: string;
     description: string | null;
+    /** How many products a shopper sees in it; absent from a server that predates it. */
+    productCount?: number | null | undefined;
+    /** Its first listed product's first photo, until a merchant can pick one; absent from a server that predates it. */
+    image?: ProductImage | null | undefined;
 }
 /** A navigation menu — GET /store/menus/{handle}. */
 export interface StoreMenu {
@@ -366,7 +372,7 @@ export interface CartValidation {
  * Why a code does not apply. Open: a server may name a reason this SDK has not
  * seen yet, and a theme then shows its general sentence.
  */
-export type CouponRefusalReason = "not_found" | "not_started" | "expired" | "used_up" | "identify_first" | "not_eligible" | "already_used" | "no_eligible_products" | "offer_applied" | "below_minimum_subtotal" | "below_minimum_quantity" | "delivery_already_free" | (string & {});
+export type CouponRefusalReason = (typeof COUPON_REFUSAL_REASONS)[number] | (string & {});
 export interface CouponRefusal {
     reason: CouponRefusalReason;
     /** The dinars (`below_minimum_subtotal`) or items (`below_minimum_quantity`) still missing. */
@@ -480,6 +486,39 @@ export interface OrderTracking {
     pixelId: string | null;
     event: "Purchase" | "Lead" | null;
 }
+/**
+ * Where an order is, in a shopper's words: `placed` (not confirmed yet),
+ * `confirmed`, `preparing`, `shipped`, `out_for_delivery`, `delivered`,
+ * `returned` (refused at the door) or `cancelled`. Open: a newer server may
+ * name another step, which a theme shows with its general words.
+ */
+export type ShopperOrderStage = (typeof SHOPPER_ORDER_STAGES)[number] | (string & {});
+/** What `orders.status()` answers: what a shopper may know of their order, never its address or notes. */
+export interface ShopperOrderStatus {
+    orderNumber: string;
+    /** When it was placed (ISO 8601). */
+    placedAt: string;
+    stage: ShopperOrderStage;
+    deliveryType: "home" | "stop_desk";
+    /** As sold, in the catalog's language. */
+    lines: {
+        name: string;
+        variantLabel: string | null;
+        quantity: number;
+    }[];
+    /** What the shopper pays on delivery. */
+    total: number;
+    /** The carrier's tracking number once the parcel is with it; null before, or with the store's own driver. */
+    tracking: {
+        number: string;
+        carrier: string | null;
+    } | null;
+}
+/** What `orders.status()` sends: the order's number and the phone it was placed with. */
+export interface ShopperOrderProof {
+    orderNumber: string;
+    phone: string;
+}
 /** POST /store/otp/send success payload. */
 export type OtpSendResult = {
     status: "sent";
@@ -581,16 +620,25 @@ export interface ProductListFilters {
     onSale?: boolean;
     /** @deprecated Use `collection: "featured"`. */
     featured?: boolean;
+    /**
+     * The order. Absent: the listing's own — a collection's, a search's best
+     * match first, else newest. A server that predates sorting ignores it.
+     */
+    sort?: ProductSort;
     /** Server-side cap; the server clamps anything larger. */
     limit?: number;
     /** Products to skip — with `limit`, pages through the whole catalog. */
     offset?: number;
 }
-/** One page of products from `products.page()`. */
+/** How a listing can be ordered: `PRODUCT_SORTS`. */
+export type ProductSort = (typeof PRODUCT_SORTS)[number];
+/** One page of products from `products.page()` or `products.search()`. */
 export interface ProductPage {
     items: ProductList[];
     /** True when another page follows this one. */
     hasNext: boolean;
+    /** How many products the whole listing holds, across its pages; null from a server that predates counts. */
+    total: number | null;
 }
 /** `products.reviews.list()` paging — named for the same reason. */
 export interface ReviewListPagination {

package/dist/utils/image.d.ts

@@ -65,6 +65,54 @@ export declare function mediaImageUrl(originalUrl: string, params: MediaImagePar
  * makes an empty one), whitespace, control characters, a backslash, `?` or `#`.
  */
 export declare function mediaUrl(key: string, mediaDomain?: string): string | null;
+export interface MediaImageSrcsetOptions {
+    /** The store's media domain; without one there is no srcset. */
+    mediaDomain?: string;
+    /** Height ÷ width: given, each size is cropped to it (`fit=cover`); absent, the photo keeps its shape (`fit=scale-down`). */
+    ratio?: number;
+    /** Encoder quality, 1–100; Cloudflare's default when absent. */
+    quality?: number;
+}
+/**
+ * The same photo at several widths, with width descriptors
+ * (`… 360w, … 720w`), for an `<img>` whose `sizes` says how wide it shows —
+ * a phone then downloads a phone-sized file. Each size is converted to the
+ * best format the browser takes (`format=auto`).
+ *
+ * @returns `null` when there is no media domain, the URL is not on it, or no
+ * width is a positive whole number.
+ */
+export declare function mediaImageSrcset(src: string, widths: readonly number[], options?: MediaImageSrcsetOptions): string | null;
+/** An image a merchant picked, by its media key — what a theme's `image` field resolves to. */
+export interface PickedImage {
+    key: string;
+    alt?: string;
+    width?: number;
+    height?: number;
+    /** The point to keep in view when the photo is cropped, each axis 0–1. */
+    focal?: {
+        x: number;
+        y: number;
+    };
+}
+/** A picked image ready for an `<img>`: its URL, its text alternative, its size, and where a crop centres. */
+export interface Picture {
+    src: string;
+    alt: string;
+    width: number | undefined;
+    height: number | undefined;
+    /** CSS `object-position` from the focal point (`30% 70%`); undefined without one. */
+    position: string | undefined;
+}
+/**
+ * A picked image as a theme draws it: its URL on the store's media domain,
+ * its alt text (empty when the merchant wrote none), its size, and its focal
+ * point as `object-position`, so a cropped photo keeps what matters in view.
+ *
+ * @returns `null` when no image is picked, the key cannot name an object, or
+ * the store has no media domain.
+ */
+export declare function pictureOf(image: PickedImage | null | undefined, mediaDomain?: string): Picture | null;
 /**
  * Predefined image sizes for common use cases
  */

package/dist/utils/image.js

@@ -93,6 +93,57 @@ export function mediaUrl(key, mediaDomain) {
     const origin = mediaOriginOf(mediaDomain);
     return origin === null ? null : `${origin}/${segments.map(encodeURIComponent).join("/")}`;
 }
+/**
+ * The same photo at several widths, with width descriptors
+ * (`… 360w, … 720w`), for an `<img>` whose `sizes` says how wide it shows —
+ * a phone then downloads a phone-sized file. Each size is converted to the
+ * best format the browser takes (`format=auto`).
+ *
+ * @returns `null` when there is no media domain, the URL is not on it, or no
+ * width is a positive whole number.
+ */
+export function mediaImageSrcset(src, widths, options = {}) {
+    const sizes = [...new Set(widths.filter((width) => Number.isInteger(width) && width > 0))].sort((a, b) => a - b);
+    if (sizes.length === 0)
+        return null;
+    const { ratio, quality, mediaDomain } = options;
+    const cropped = ratio !== undefined && Number.isFinite(ratio) && ratio > 0;
+    const encoding = quality === undefined ? {} : { quality };
+    const entries = [];
+    for (const width of sizes) {
+        const url = mediaImageUrl(src, cropped
+            ? { width, height: Math.max(1, Math.round(width * ratio)), fit: "cover", format: "auto", ...encoding }
+            : { width, fit: "scale-down", format: "auto", ...encoding }, mediaDomain);
+        if (url === null)
+            return null;
+        entries.push(`${url} ${width}w`);
+    }
+    return entries.join(", ");
+}
+/**
+ * A picked image as a theme draws it: its URL on the store's media domain,
+ * its alt text (empty when the merchant wrote none), its size, and its focal
+ * point as `object-position`, so a cropped photo keeps what matters in view.
+ *
+ * @returns `null` when no image is picked, the key cannot name an object, or
+ * the store has no media domain.
+ */
+export function pictureOf(image, mediaDomain) {
+    if (!image)
+        return null;
+    const src = mediaUrl(image.key, mediaDomain);
+    if (src === null)
+        return null;
+    const percent = (value) => `${Math.round(Math.min(1, Math.max(0, value)) * 100)}%`;
+    const focal = image.focal;
+    return {
+        src,
+        alt: image.alt ?? "",
+        width: image.width,
+        height: image.height,
+        position: focal && Number.isFinite(focal.x) && Number.isFinite(focal.y) ? `${percent(focal.x)} ${percent(focal.y)}` : undefined,
+    };
+}
 /**
  * Predefined image sizes for common use cases
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wocart/storefront",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "Typed, validated SDK for Wocart cash-on-delivery storefronts: catalog reads, basket, checkout, OTP and order tracking, with Astro adapters.",
   "keywords": [
     "wocart",