@wocart/storefront 1.19.0 → 1.20.0

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;
+    };
+    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);
+}

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
  */