@wocart/storefront 1.23.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@ follows [semantic versioning](https://semver.org/): breaking changes ship only
 in a new major version, and an export is marked `@deprecated` for at least one
 minor release before a major removes it.
 
+## 2.1.0 — 2026-10-31
+
+### Added
+
+- `LandingPage.document`: the page's own composition for the client's
+  `theme`, or null — a landing page and its document in one request. Null
+  from a server that predates it, and a malformed document reads as null.
+- `pages.landing(slug, { preview: true })` answers a draft page too and
+  counts no visit, for an editor's preview.
+- `countdownTarget`, `countdownEnd` and `timeLeft`: an offer countdown's end
+  — every midnight, or a day the merchant names, at its end or at a time —
+  in Algiers time, the same in the server's render and the browser.
+
+### Fixed
+
+- `pages.landing` sends the client's language, like every read that carries
+  merchant text: the page's product reaches a shopper in their language.
+
+## 2.0.0 — 2026-10-30
+
+A store's images can live on any media host. The server answers every image
+as a `MediaImage` and the store's config says how its images are delivered;
+the image helpers take that delivery instead of a media domain. Requires a
+store server that answers this shape.
+
+### Changed (breaking)
+
+- Every image is a `MediaImage`, `{ key, url, width, height }`: a product
+  image (`ProductImageSchema`) and a landing image carry `key` and `url`
+  (`src`, `srcSm`, `srcMd`, `srcLg` are gone); a category has `image` (was
+  `imageUrl`); `StoreConfig` has `logo` (was `logoUrl`) and `ogImage` as
+  images.
+- `StoreConfig.media` (`MediaDelivery`, `{ kind, origin }`): where every key is
+  served from, and how it is resized — `imagekit`, `cloudflare`, or `direct`.
+- `mediaUrl(key, delivery)`, `mediaImageUrl(url, params, delivery)`,
+  `mediaImageSrcset(url, widths, { delivery })` and `pictureOf(image,
+  delivery)` take the store's delivery (was a media domain). `mediaImageUrl`
+  builds ImageKit's `?tr=` or Cloudflare's `/cdn-cgi/image/`, and answers
+  `null` for a `direct` delivery.
+- `productImageSource` reads `url`.
+
+### Removed
+
+- `optimizeImage`, `generateSrcSet`, `IMAGE_SIZES`, `getCardImage`,
+  `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`,
+  `getLogoImage`, `createImageHelpers` and their types: each took a media
+  domain, which no longer exists. Use `mediaImageUrl` and `mediaImageSrcset`
+  with the size a page shows. They are removed without a deprecating minor
+  because no media domain is left for them to take.
+
+### Added
+
+- `isMediaKey`, `MediaImage`, `MediaDelivery`, `MediaDeliveryKind`,
+  `MediaImageSchema` and `MediaDeliverySchema`.
+
+### Changed
+
+- The README is short and points to the documentation at docs.wocart.store.
+
 ## 1.23.0 — 2026-10-25
 
 One checkout, one order: a double click, a refreshed submission or a retry

package/README.md

@@ -1,20 +1,13 @@
 # @wocart/storefront
 
 The storefront SDK for [Wocart](https://github.com/bighadj22/codflow), the
-cash-on-delivery commerce platform for Algeria. It gives a storefront theme
-typed, validated access to a store's catalog, delivery prices, basket,
-checkout, OTP and order tracking — and keeps prices, rules and secrets on the
-server.
+cash-on-delivery commerce platform for Algeria. It gives a storefront typed,
+validated access to a store's catalog, delivery prices, basket, checkout, OTP,
+order tracking and images — and keeps prices, rules and secrets on the server.
 
-- **Typed and validated.** Every server response is parsed against a schema
-  before your code sees it.
-- **Predictable failures.** Reads never throw: they resolve to `null`, `[]` or
-  `{}` and report through `onError`. Writes return a result whose failure always
-  carries a structured `DomainError`.
-- **Browser-safe by construction.** The root entry exports no client and no
-  secret; the store API key lives behind `@wocart/storefront/server`.
-- **Framework-neutral core, Astro adapters.** Proxy routes, form actions and
-  the POST/Redirect/GET middleware decision for Astro, with no Astro import.
+**Documentation: [docs.wocart.store/sdk/storefront](https://docs.wocart.store/sdk/storefront)**
+— also in [French](https://docs.wocart.store/fr/sdk/storefront) and
+[Arabic](https://docs.wocart.store/ar/sdk/storefront).
 
 ## Install
 
@@ -22,123 +15,35 @@ server.
 npm install @wocart/storefront zod
 ```
 
-`zod` (4.x) is a peer dependency: the SDK's schemas are part of its API — you
-can validate with them, and you pass your own schemas to `createProxyEndpoint` —
-so your app and the SDK share one copy. npm 7 and later install it
-automatically. ESM only. Runs in browsers, Cloudflare Workers, Node and Astro server
-runtimes; tooling needs Node 22.12 or newer.
+`zod` 4 is a peer dependency. ESM only; Node 22.12 or newer for tooling.
 
 ## Quick start
 
 ```ts
 import { createStoreClient } from "@wocart/storefront/server";
+import { mediaImageUrl } from "@wocart/storefront";
 
-// Server-side only: a page frontmatter, endpoint, action or middleware.
-const store = createStoreClient({
-  serverUrl: env.COD_SERVER_URL, // your store's API origin
-  apiKey: env.STORE_API_KEY,     // server-only secret
-  onError: (error) => console.warn(error.operation, error.code, error.requestId),
-});
+const store = createStoreClient({ serverUrl: env.COD_SERVER_URL, apiKey: env.STORE_API_KEY });
 
-// Reads: typed, validated, safe to render straight away.
-const [config, products] = await Promise.all([
-  store.config.get(),                                // StoreConfig | null
-  store.products.list({ featured: true, limit: 8 }), // ProductList[]
-]);
-const product = await store.products.get("blue-t-shirt"); // Product | null
-
-// Writes: a discriminated result, never a thrown HTTP error.
-const result = await store.orders.create({
-  customerName: "أمين",
-  phone: "0555123456",
-  wilayaId: 16,
-  communeId: "c-16-001",
-  items: [{ productId: "p-1", productName: "Blue T-Shirt", quantity: 1 }],
-});
-
-if (result.success) {
-  console.log(result.data.orderNumber, result.data.total);
-} else {
-  console.error(result.domainError.category, result.domainError.message);
-}
-```
-
-## Entry points
-
-| Import | Runs in | What it holds |
-| --- | --- | --- |
-| `@wocart/storefront` | browser and server | read-model types and schemas, reference data (58 wilayas, 1,551 communes), money and image helpers, the basket and OTP state machines, language routing, Meta pixel payloads |
-| `@wocart/storefront/server` | server only | `createStoreClient`, `StoreClient`, `ClientResult`, `StorefrontError` — the API key lives here — the preview checks (`readPreviewRequest`, `verifyPreviewToken`, `previewResponseHeaders`, `previewConfig`) and revalidation (`readRevalidateRequest`) |
-| `@wocart/storefront/astro` | server only | `createStorefrontRoutes`, `createProxyEndpoint`, `placeOrderInput`, `executePlaceOrder`, `collectForwardedHeaders`, `runFormAction` |
-
-Browser code never receives the key. It calls your own same-origin routes
-(for example `src/pages/api/cart.ts`), which call the SDK on the server:
-
-```ts
-// In the browser: no client, no key.
-import { createBasketStore, formatMoney } from "@wocart/storefront";
+const config = await store.config.get();
+const product = await store.products.get("blue-t-shirt");
+const photo = product?.images[0];
+const src = photo && config ? mediaImageUrl(photo.url, { width: 480, fit: "cover", format: "auto" }, config.media) ?? photo.url : null;
 ```
 
-## What the client covers
-
-| Namespace | Use it for |
-| --- | --- |
-| `config` | store identity, branding, languages, checkout policy, feature flags |
-| `products` | catalog lists, product detail, reviews |
-| `categories` | catalog navigation |
-| `pages` | legal and CMS pages, landing pages |
-| `pageData` | the store's saved page document for a surface (render it with [`@wocart/theme`](https://www.npmjs.com/package/@wocart/theme)) |
-| `shipping` | home and stop-desk delivery prices per wilaya |
-| `geo` | wilayas and communes |
-| `cart` | server re-pricing and validation of a browser basket |
-| `orders` | order creation, OTP, abandoned checkout, conversion tracking |
-
-## How errors work
+Reads never throw: they resolve to `null`, `[]` or `{}` and report through
+`onError`. Writes return `{ success, data }` or a structured `domainError`.
 
-- **Reads** resolve to the empty value (`null`, `[]`, `{}`) so a page still
-  renders, and report the cause to `onError` as a `DomainError` with
-  `category`, `code`, `retryable`, `sideEffect`, `operation` and `requestId`.
-- **Writes** return `ClientResult<T>`: `{ success: true, data }` or
-  `{ success: false, error, domainError }`. Branch on
-  `result.domainError.category` — `validation`, `authentication`, `business`,
-  `system`, `transport` — instead of status codes.
-- **Setup errors are loud.** An empty `serverUrl` or `apiKey` throws
-  `MISSING_CONFIGURATION` when the client is created, instead of quietly
-  turning every read into an empty store.
-
-## Configuration
+## Entry points
 
-| Option | Required | Notes |
+| Import | Runs in | Holds |
 | --- | --- | --- |
-| `serverUrl` | yes | your store's API origin |
-| `apiKey` | yes | the store API key, sent as `X-Store-API-Key`; server-only |
-| `locale` | no | read merchant text in a published store language (`"fr"`); one client per language |
-| `theme` | no | your theme's key (`defineTheme({ key })`), to receive the merchant's edits to your theme's text |
-| `onError` | no | observability hook for degraded reads |
-| `readTimeoutMs` | no | how long one read may take, retries included, before it degrades (default 10 000; `0` for no limit) |
-
-A storefront deployed by Wocart receives its origin and key as the
-`COD_SERVER_URL` and `STORE_API_KEY` environment variables. The SDK reads no
-environment variables itself; pass the values in. In Astro, declare the key as
-a server secret (`envField.string({ context: "server", access: "secret" })`)
-and never expose it as a public variable.
-
-## Documentation
-
-- [USAGE.md](./USAGE.md) — the full guide: every namespace and the UI decisions
-  it implies, checkout and OTP, Astro actions and proxy routes, languages,
-  images, and a definition of done for a new theme.
-- [CHANGELOG.md](./CHANGELOG.md) — what changed in each release.
-
-## Compatibility
+| `@wocart/storefront` | browser and server | types and schemas, reference data, money and image helpers, basket and OTP state |
+| `@wocart/storefront/server` | server only | `createStoreClient` — the store API key lives here — preview and revalidation checks |
+| `@wocart/storefront/astro` | server only | proxy routes, form actions, `placeOrderInput` |
 
-- Follows [semantic versioning](https://semver.org/). Breaking changes ship
-  only in a new major version and are listed in the changelog.
-- Response schemas ignore fields they do not know, so a newer server never
-  breaks an older SDK; a response missing a required field degrades the read
-  and reports it.
-- Astro 7 is verified. The Astro adapters are structural and import nothing
-  from Astro.
+[USAGE.md](./USAGE.md) ships with the package for offline reading;
+[CHANGELOG.md](./CHANGELOG.md) lists every release.
 
 ## License
 

package/USAGE.md

@@ -214,10 +214,11 @@ server directly.
 
 | Export | Use it for |
 | --- | --- |
-| `formatMoney`, `optimizeImage`, `generateSrcSet` | Money text and image URLs |
-| `mediaImageUrl` | The Cloudflare resizing URL of a media-domain image, served by the media domain itself (any storefront host); `null` for any other image — the builder behind every image helper and `@wocart/theme/image-service` |
-| `mediaUrl(key, mediaDomain)` | The public URL of a stored media key — what a theme's `image` field holds (`{ key: "products/…" }`): `mediaUrl(image.key, MEDIA_DOMAIN)`; `null` with no media domain or a key that cannot name an object. The key is the identity; the URL is derived at render |
-| `createImageHelpers(mediaDomain)`, `getCardImage`, `getGalleryImage`, `getThumbnailImage`, `getHeroImage`, `getCategoryImage`, `getLogoImage` | The bound image toolkit (`IMAGE_SIZES` holds the presets) |
+| `formatMoney` | Money text |
+| `mediaImageUrl(url, params, config.media)` | A store image at the size and format a page shows it, from the store's delivery (ImageKit `?tr=` or Cloudflare `/cdn-cgi/image/`); `null` for an image the delivery does not serve, or a `direct` delivery — the builder behind `@wocart/theme/image-service` |
+| `mediaImageSrcset(url, widths, { delivery })` | The same image at several widths, for `srcset` |
+| `mediaUrl(key, config.media)`, `isMediaKey` | The URL of a Media Key — what a theme's `image` field holds (`{ key: "products/…" }`); `null` without a delivery or for a value that is not a key |
+| `pictureOf(image, config.media)` | A picked image ready for an `<img>`: URL, alt, size, focal point |
 | `WILAYAS`, `ALGERIA_COMMUNES`, `communesForWilaya` | Reference data: 58 wilayas, 1,551 communes, one wilaya's rows |
 | `isWilayaId` | Whether a value is a wilaya id — the range `WilayaIdSchema` checks on the server, without a schema in the browser |
 | `readShippingRates`, `readCouponOutcome` | Read in the browser what the server handed it — the rates a page carries, a quote's coupon outcome — accepting exactly what `ShippingRatesSchema` / `CouponOutcomeSchema` accept, without Zod |
@@ -290,7 +291,6 @@ storefront deployed by Wocart receives these:
 | --- | --- | --- |
 | `COD_SERVER_URL` | server variable | the store's API origin, e.g. `https://api.your-store.com` |
 | `STORE_API_KEY` | server secret | the store API key |
-| `MEDIA_DOMAIN` | server variable (optional) | media domain for `createImageHelpers(mediaDomain)`; unset → image URLs pass through unchanged |
 
 Never put `STORE_API_KEY` in a browser-exposed variable (no `PUBLIC_*`, no
 `import.meta.env` in client code, no HTML attribute). In Astro, declare it in
@@ -518,11 +518,13 @@ const currencySymbol = config?.currencySymbol ?? "دج";
 StoreConfig contains the current store identity and presentation fields,
 including:
 
-- name, domain, logoUrl and themeId (the colors, fontFamily and fontUrl
+- name, domain, logo (a MediaImage) and themeId (the colors, fontFamily and fontUrl
   fields are deprecated: colors and fonts are theme settings, read from
   themeSettings);
 - lang (the primary language), locales, contentOverrides, themeSettings,
-  currency, currencySymbol, metaTitle, metaDescription, and ogImage;
+  currency, currencySymbol, metaTitle, metaDescription, and ogImage (a
+  MediaImage);
+- media, the store's MediaDelivery, which every image helper takes;
 - reviewsEnabled (announcementBar is deprecated and always null: an
   announcement is a theme's own setting);
 - cartEnabled, freeShippingThreshold, and cartShippingMode;
@@ -996,7 +998,19 @@ const landing = await store.pages.landing("summer-sale");
 
 A landing page can contain its own name, SEO metadata, image gap, images,
 product, publishedAt, and tracking information. The product may be null.
-Draft, archived, or unknown landing pages resolve to null.
+Draft, archived, or unknown landing pages resolve to null. Its product
+arrives in the client's language.
+
+A client created with `theme` also receives the page's own composition,
+`landing.document` (the page document `lp:<id>`), or null when it has none:
+render it with `@wocart/theme` against the theme's `landing` surface, which
+gives every landing page its starting document. An editor's preview reads a
+draft page too, and counts no visit, with `{ preview: true }` — never on a
+shopper's page:
+
+~~~ts
+const landing = await store.pages.landing(slug, { preview: true });
+~~~
 
 Landing tracking is already resolved by the server:
 
@@ -1008,6 +1022,21 @@ if (landing?.tracking.pixelId) {
 
 Do not invent tracking events from a landing-page slug.
 
+### An offer's countdown
+
+~~~ts
+import { countdownEnd, countdownTarget, timeLeft } from "@wocart/storefront";
+
+const ends = countdownTarget(settings.mode, settings.endsOn, settings.endsAt); // "midnight", "2026-11-30", "2026-11-30T18:30"
+const end = countdownEnd(ends);           // null: ended, or no real moment — show nothing
+const left = end === null ? null : timeLeft(end);
+~~~
+
+A countdown ends every day at midnight, or on a day the merchant names, at
+its end or at the time they give, in Algiers time. The server writes the time
+left; the browser keeps it running with the same functions. A countdown that
+has ended shows nothing, never zeros.
+
 ### The saved page document (theme composition)
 
 ~~~ts
@@ -1827,53 +1856,46 @@ price presentation does not drift between cards, product pages, and checkout.
 
 ### Images
 
+Every image the store's server answers is a `MediaImage` — `{ key, url,
+width, height }` — and the store's config carries `media`, its
+`MediaDelivery`: the origin every key is served from and how that origin
+resizes (`imagekit`, `cloudflare`, or `direct` for files served as stored).
+Pass `config.media` to the image helpers; one theme then works on every host a
+store can use.
+
 ~~~ts
-import {
-  generateSrcSet,
-  getCardImage,
-  optimizeImage,
-} from "@wocart/storefront";
+import { mediaImageUrl } from "@wocart/storefront";
 
-const mediaDomain = env.MEDIA_DOMAIN;
-const originalImage = product.images[0]?.src ?? "";
-const cardImage = getCardImage(originalImage, mediaDomain);
-const src = optimizeImage(originalImage, {
-  width: 480,
-  height: 480,
-  quality: 82,
-  format: "auto",
-  fit: "cover",
-}, mediaDomain);
-const srcSet = generateSrcSet(originalImage, 480, 480, mediaDomain);
+const photo = product.images[0];
+const card = photo ? mediaImageUrl(photo.url, { width: 480, height: 480, fit: "cover", format: "auto", quality: 82 }, config.media) ?? photo.url : null;
 ~~~
 
-The image utility accepts the original media URL and can target a media
-domain. Use it to produce appropriately sized URLs rather than downloading
-original assets into every card.
+`mediaImageUrl` answers `null` for an image its delivery does not serve and
+for a `direct` delivery, which does not resize: show the original then.
 
 For an image whose width changes with the screen, give the browser widths and
 let `sizes` choose — a phone then downloads a phone-sized file.
-`mediaImageSrcset(src, widths, { mediaDomain, ratio, quality })` gives one
-size per width with width descriptors, cropped to `ratio` (height ÷ width)
-when given; null off the media domain:
+`mediaImageSrcset(src, widths, { delivery, ratio, quality })` gives one size
+per width with width descriptors, cropped to `ratio` (height ÷ width) when
+given and never enlarged past the original otherwise:
 
 ~~~astro
 <img
-  src={mediaImageUrl(src, { width: 720, format: "auto" }, mediaDomain) ?? src}
-  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { mediaDomain, ratio: 1.25 }) ?? undefined}
+  src={mediaImageUrl(src, { width: 720, fit: "scale-down", format: "auto" }, config.media) ?? src}
+  srcset={mediaImageSrcset(src, [360, 540, 720, 1080], { delivery: config.media, ratio: 1.25 }) ?? undefined}
   sizes="(min-width: 1024px) 25vw, 50vw"
   alt="" loading="lazy" />
 ~~~
 
-A photo a merchant picks for a section is stored as a media key with its alt
-text, size and focal point. `pictureOf(image, mediaDomain)` turns it into what
+A photo a merchant picks for a section is stored as a Media Key with its alt
+text, size and focal point. `pictureOf(image, config.media)` turns it into what
 an `<img>` needs — `src`, `alt` (empty when none was written), `width`,
 `height` and `position`, the focal point as CSS `object-position` — or null
 when none is picked:
 
 ~~~astro
 ---
-const picture = pictureOf(props.image, mediaDomain);
+const picture = pictureOf(props.image, config.media);
 ---
 {picture && <img src={picture.src} alt={picture.alt} width={picture.width} height={picture.height} style={{ objectPosition: picture.position }} />}
 ~~~
@@ -1886,10 +1908,10 @@ thumbnail. `productImageSource` answers which image represents the product, so
 a cart drawer, a checkout summary and a product card cannot disagree:
 
 ~~~ts
-import { getThumbnailImage, productImageSource } from "@wocart/storefront";
+import { mediaImageUrl, productImageSource } from "@wocart/storefront";
 
 const src = productImageSource(product); // Product | ProductList
-const thumbnail = src ? getThumbnailImage(src) : null;
+const thumbnail = src ? mediaImageUrl(src, { width: 160, height: 160, fit: "cover", format: "auto" }, config.media) ?? src : null;
 ~~~
 
 It prefers the merchant's cover and falls back to the first usable gallery
@@ -1897,40 +1919,6 @@ image; `null` means the product genuinely has no photograph, so that is the
 moment to render a placeholder. The list model carries no gallery at all, so a
 card gets the cover or `null`.
 
-Available semantic helpers include:
-
-- getCardImage;
-- getGalleryImage;
-- getThumbnailImage;
-- getHeroImage;
-- getCategoryImage;
-- getLogoImage.
-
-The helper chooses the appropriate image role. The theme still owns layout,
-aspect ratio, alt text, lazy loading, placeholders, and art direction.
-
-#### Bind the media domain once
-
-Do not thread the media domain through every call site — a missed argument
-silently ships an unoptimized image. Bind it once and use the URL-only helper
-set:
-
-~~~ts
-import { createImageHelpers } from "@wocart/storefront";
-
-const images = createImageHelpers(env.MEDIA_DOMAIN);
-
-const thumbnail = images.getThumbnailImage(product.images[0].src);
-const preview = images.getCardImage(product.images[0].src);
-const srcSet = images.generateSrcSet(product.images[0].src, 480, 480);
-~~~
-
-The returned toolkit exposes the same helpers plus `optimizeImage`,
-`generateSrcSet`, and `IMAGE_SIZES`. With no domain bound, every helper returns
-the original URL unchanged, so a store without a media domain needs no branch —
-and `optimizeImage` / `generateSrcSet` still take a per-call domain that
-overrides the bound one.
-
 ## WhatsApp prefill messages
 
 The storefront's WhatsApp launcher hands the shopper to WhatsApp with a message

package/dist/client/pages.d.ts

@@ -9,7 +9,8 @@
  * - `get(slug)` → null means "not published" — the theme 404s, never a
  *   soft 200 with empty content.
  * - `landing(slug)` → null means draft/archived/unknown — the theme
- *   redirects to the store home instead of a dead end.
+ *   redirects to the store home instead of a dead end. `{ preview: true }`
+ *   also answers a draft page and counts no visit: an editor's preview.
  */
 import { type ClientCore } from "./core.js";
 import type { LandingPage, StorePagePublic } from "../types.js";
@@ -22,10 +23,15 @@ export interface PagesNamespace {
     get(slug: string): Promise<StorePagePublic | null>;
     /**
      * Get a published landing page by its public slug: the ordered image
-     * stack, spacing settings, and the linked product in full store-product
-     * shape. Resolves to `null` for draft/archived/unknown slugs or failure.
+     * stack, spacing settings, the linked product in full store-product
+     * shape, and the page's own document for the client's `theme`. Resolves to
+     * `null` for draft/archived/unknown slugs or failure. With
+     * `{ preview: true }` a draft page answers too and no visit is counted —
+     * for an editor's preview only, never a shopper's page.
      */
-    landing(slug: string): Promise<LandingPage | null>;
+    landing(slug: string, options?: {
+        preview?: boolean;
+    }): Promise<LandingPage | null>;
 }
 /**
  * Create pages namespace

package/dist/client/pages.js

@@ -9,7 +9,8 @@
  * - `get(slug)` → null means "not published" — the theme 404s, never a
  *   soft 200 with empty content.
  * - `landing(slug)` → null means draft/archived/unknown — the theme
- *   redirects to the store home instead of a dead end.
+ *   redirects to the store home instead of a dead end. `{ preview: true }`
+ *   also answers a draft page and counts no visit: an editor's preview.
  */
 import { LandingPageSchema, StorePagePublicSchema } from "../schemas.js";
 import { STOREFRONT_OPERATIONS } from "../operations.js";
@@ -31,9 +32,12 @@ export function createPagesNamespace(core) {
                 return null;
             }
         },
-        async landing(slug) {
+        async landing(slug, options = {}) {
             try {
-                const landingPage = await core.get(`/store/landing-pages/${encodeURIComponent(slug)}`, LandingPageSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesLanding });
+                const landingPage = await core.get(localizedPath(core.config, `/store/landing-pages/${encodeURIComponent(slug)}`, {
+                    theme: core.config.theme,
+                    preview: options.preview === true ? "1" : undefined,
+                }), LandingPageSchema.nullable(), { operation: STOREFRONT_OPERATIONS.pagesLanding });
                 return landingPage ?? null;
             }
             catch (error) {

package/dist/countdown.d.ts

@@ -0,0 +1,28 @@
+/**
+ * An offer countdown's end, as the store sets it: every day at midnight, or
+ * a day the merchant names — at its end or at the time they give — in
+ * Algiers time (UTC+1 all year). An end already past, or a day or time that
+ * does not exist, is no countdown at all: a shopper never sees zeros. Runs
+ * the same on the server, which writes the time left, and in the browser,
+ * which keeps it running.
+ */
+/** What a countdown counts to: `midnight`, a day (`YYYY-MM-DD`) or a day at a time (`YYYY-MM-DDTHH:MM`). */
+export type CountdownEnd = "midnight" | string;
+/** The time left, in whole units. */
+export interface TimeLeft {
+    days: number;
+    hours: number;
+    minutes: number;
+    seconds: number;
+}
+/**
+ * What a countdown's settings count to: `mode` `midnight` or `date`, the
+ * day the merchant typed (`YYYY-MM-DD`) and, optionally, the time
+ * (`HH:MM`). Undefined when they count to nothing — no day for `date`, or
+ * any other mode.
+ */
+export declare function countdownTarget(mode: string | undefined, endsOn: string | undefined, endsAt: string | undefined): CountdownEnd | undefined;
+/** When a countdown ends, as an instant (ms since the epoch); null when it has ended or names no real moment. */
+export declare function countdownEnd(ends: CountdownEnd | undefined, now?: number): number | null;
+/** The time left until `end`, in whole days, hours, minutes and seconds; zero once it has passed. */
+export declare function timeLeft(end: number, now?: number): TimeLeft;

package/dist/countdown.js

@@ -0,0 +1,55 @@
+/**
+ * An offer countdown's end, as the store sets it: every day at midnight, or
+ * a day the merchant names — at its end or at the time they give — in
+ * Algiers time (UTC+1 all year). An end already past, or a day or time that
+ * does not exist, is no countdown at all: a shopper never sees zeros. Runs
+ * the same on the server, which writes the time left, and in the browser,
+ * which keeps it running.
+ */
+const ALGERIA_OFFSET_MS = 60 * 60 * 1000;
+const MOMENT = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?$/;
+const TIME = /^(\d{1,2}):(\d{2})$/;
+/**
+ * What a countdown's settings count to: `mode` `midnight` or `date`, the
+ * day the merchant typed (`YYYY-MM-DD`) and, optionally, the time
+ * (`HH:MM`). Undefined when they count to nothing — no day for `date`, or
+ * any other mode.
+ */
+export function countdownTarget(mode, endsOn, endsAt) {
+    if (mode === "midnight")
+        return "midnight";
+    const day = endsOn?.trim() ?? "";
+    if (mode !== "date" || day === "")
+        return undefined;
+    const time = TIME.exec(endsAt?.trim() ?? "");
+    return time ? `${day}T${time[1].padStart(2, "0")}:${time[2]}` : day;
+}
+/** When a countdown ends, as an instant (ms since the epoch); null when it has ended or names no real moment. */
+export function countdownEnd(ends, now = Date.now()) {
+    if (ends === undefined || ends === "")
+        return null;
+    if (ends === "midnight") {
+        const local = new Date(now + ALGERIA_OFFSET_MS);
+        return Date.UTC(local.getUTCFullYear(), local.getUTCMonth(), local.getUTCDate() + 1) - ALGERIA_OFFSET_MS;
+    }
+    const match = MOMENT.exec(ends.trim());
+    if (!match)
+        return null;
+    const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+    const check = new Date(Date.UTC(year, month - 1, day));
+    if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day)
+        return null;
+    let end = Date.UTC(year, month - 1, day + 1) - ALGERIA_OFFSET_MS;
+    if (match[4] !== undefined) {
+        const [hours, minutes] = [Number(match[4]), Number(match[5])];
+        if (hours > 23 || minutes > 59)
+            return null;
+        end = Date.UTC(year, month - 1, day, hours, minutes) - ALGERIA_OFFSET_MS;
+    }
+    return end > now ? end : null;
+}
+/** The time left until `end`, in whole days, hours, minutes and seconds; zero once it has passed. */
+export function timeLeft(end, now = Date.now()) {
+    const total = Math.max(0, Math.floor((end - now) / 1000));
+    return { days: Math.floor(total / 86400), hours: Math.floor((total % 86400) / 3600), minutes: Math.floor((total % 3600) / 60), seconds: total % 60 };
+}

package/dist/index.d.ts

@@ -11,8 +11,8 @@
  */
 export { formatMoney } from "./utils/money.js";
 export type { MoneyFormatOptions } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, mediaImageSrcset, mediaUrl, pictureOf, } from "./utils/image.js";
-export type { ImageHelpers, ImageResizeOptions, MediaImageParams, MediaImageSrcsetOptions, PickedImage, Picture } from "./utils/image.js";
+export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from "./utils/image.js";
+export type { MediaDelivery, MediaDeliveryKind, MediaImage, MediaImageParams, MediaImageSrcsetOptions, PickedImage, Picture } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export type { ProductImageSourceInput } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
@@ -49,6 +49,8 @@ export * from "./domain.js";
 export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { countdownEnd, countdownTarget, timeLeft } from "./countdown.js";
+export type { CountdownEnd, TimeLeft } from "./countdown.js";
 export { COUPON_HINT_REASONS, COUPON_NOT_APPLICABLE, COUPON_REFUSAL_REASONS, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf, couponRefusalTone, } from "./coupon.js";
 export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
 export type { OptionSelection, OptionState, PickerVariant } from "./variant-picker.js";

package/dist/index.js

@@ -10,7 +10,7 @@
  * Internal modules stay reachable only through their intentional entry points.
  */
 export { formatMoney } from "./utils/money.js";
-export { optimizeImage, generateSrcSet, IMAGE_SIZES, getCardImage, getGalleryImage, getThumbnailImage, getHeroImage, getCategoryImage, getLogoImage, createImageHelpers, mediaImageUrl, mediaImageSrcset, mediaUrl, pictureOf, } from "./utils/image.js";
+export { isMediaKey, mediaImageSrcset, mediaImageUrl, mediaUrl, pictureOf } from "./utils/image.js";
 export { productImageSource } from "./utils/product-image.js";
 export { MAX_RESOLVED_PREFILL_LENGTH, PREFILL_TOKENS, stripTrackingParams, truncateAtWordBoundary, resolvePrefillText, buildWhatsAppHref, } from "./whatsapp.js";
 export { STOREFRONT_PAGE_PATHS, STOREFRONT_ROUTES, matchStorefrontPath, showsWidgetOn, storefrontPath } from "./routes.js";
@@ -36,6 +36,7 @@ export * from "./domain.js";
 export * from "./operations.js";
 export * from "./product-view.js";
 export { getOfferTierView, getQuantityTierViews } from "./offer-view.js";
+export { countdownEnd, countdownTarget, timeLeft } from "./countdown.js";
 export { COUPON_HINT_REASONS, COUPON_NOT_APPLICABLE, COUPON_REFUSAL_REASONS, COUPON_URL_PARAM, couponFromUrl, couponRefusalOf, couponRefusalTone, } from "./coupon.js";
 export { initialVariant, optionStates, pickOption, variantFor } from "./variant-picker.js";
 export { ABANDONED_CHECKOUT_SESSION_KEY, convertAbandonedCheckout, createAbandonedCheckoutTracker, createBrowserAbandonedCheckoutTracker, } from "./abandoned-checkout.js";