@wocart/storefront 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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

package/USAGE.md

@@ -998,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:
 
@@ -1010,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

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

@@ -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

@@ -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";

package/dist/schemas.d.ts

@@ -746,6 +746,11 @@ export declare const LandingPageSchema: z.ZodObject<{
             rewardUnitPrice: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    document: z.ZodDefault<z.ZodCatch<z.ZodNullable<z.ZodObject<{
+        version: z.ZodNumber;
+        surface: z.ZodString;
+        sections: z.ZodArray<z.ZodUnknown>;
+    }, z.core.$loose>>>>;
     tracking: z.ZodObject<{
         pixelId: z.ZodNullable<z.ZodString>;
         conversionEvent: z.ZodEnum<{

package/dist/schemas.js

@@ -341,6 +341,7 @@ export const LandingPageSchema = z.object({
     publishedAt: z.string().nullable(),
     images: z.array(LandingPageImageSchema),
     product: ProductSchema.nullable(),
+    document: PageDocumentPayloadSchema.nullable().catch(null).default(null),
     tracking: z.object({
         pixelId: z.string().nullable(),
         conversionEvent: z.enum([

package/dist/types.d.ts

@@ -296,6 +296,12 @@ export interface LandingPage {
         pixelId: string | null;
         conversionEvent: "Lead" | "Purchase" | "Purchase_Confirmed" | "Purchase_Delivered";
     };
+    /**
+     * The page's own composition for the client's `theme` (its `lp:<id>`
+     * document), or null when it has none, the client names no theme, or the
+     * server predates it: the theme then renders its `landing` default.
+     */
+    document: PageDocumentPayload | null;
 }
 export interface Wilaya {
     id: number;

package/package.json

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