@wocart/storefront 1.19.0 → 1.20.0

package/dist/operations.js

@@ -9,6 +9,7 @@ export const STOREFRONT_OPERATIONS = {
     categoriesList: "categories.list",
     productsGet: "products.get",
     productsList: "products.list",
+    productsSearch: "products.search",
     productsReviewsList: "products.reviews.list",
     productsReviewsSubmit: "products.reviews.submit",
     productsReviewsEligibility: "products.reviews.eligibility",
@@ -24,6 +25,7 @@ export const STOREFRONT_OPERATIONS = {
     pageDataGet: "pageData.get",
     ordersCreate: "orders.create",
     ordersTracking: "orders.tracking",
+    ordersStatus: "orders.status",
     ordersAbandonedUpsert: "orders.abandoned.upsert",
     ordersAbandonedConvert: "orders.abandoned.convert",
     ordersOtpSend: "orders.otp.send",
@@ -50,6 +52,7 @@ export const STOREFRONT_RETRY_POLICIES = {
     [STOREFRONT_OPERATIONS.ordersOtpSend]: "never",
     [STOREFRONT_OPERATIONS.ordersOtpVerify]: "never",
     [STOREFRONT_OPERATIONS.ordersTracking]: "safe-read",
+    [STOREFRONT_OPERATIONS.ordersStatus]: "never",
     [STOREFRONT_OPERATIONS.pageDataGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesGet]: "safe-read",
     [STOREFRONT_OPERATIONS.pagesLanding]: "safe-read",
@@ -57,6 +60,7 @@ export const STOREFRONT_RETRY_POLICIES = {
     [STOREFRONT_OPERATIONS.collectionsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsGet]: "safe-read",
     [STOREFRONT_OPERATIONS.productsList]: "safe-read",
+    [STOREFRONT_OPERATIONS.productsSearch]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsList]: "safe-read",
     [STOREFRONT_OPERATIONS.productsReviewsSubmit]: "never",
     [STOREFRONT_OPERATIONS.productsReviewsEligibility]: "never",

package/dist/order-number.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The order number a shopper is given (`ORD-20261023-0042`) and types back to
+ * review what they bought or follow their order. The server refuses any other
+ * shape with `VALIDATION_FAILED`; a form can say so before asking.
+ */
+/** `ORD-`, the day the order was placed (`YYYYMMDD`), a dash and its digits; any case. */
+export declare const ORDER_NUMBER_PATTERN: RegExp;
+/** Whether `value`, without the spaces around it, has the shape of an order number. */
+export declare function isOrderNumber(value: string): boolean;

package/dist/order-number.js

@@ -0,0 +1,11 @@
+/**
+ * The order number a shopper is given (`ORD-20261023-0042`) and types back to
+ * review what they bought or follow their order. The server refuses any other
+ * shape with `VALIDATION_FAILED`; a form can say so before asking.
+ */
+/** `ORD-`, the day the order was placed (`YYYYMMDD`), a dash and its digits; any case. */
+export const ORDER_NUMBER_PATTERN = /^ORD-\d{8}-\d+$/i;
+/** Whether `value`, without the spaces around it, has the shape of an order number. */
+export function isOrderNumber(value) {
+    return typeof value === "string" && ORDER_NUMBER_PATTERN.test(value.trim());
+}

package/dist/product-view.d.ts

@@ -10,3 +10,11 @@ export interface ProductView {
 }
 export declare function getProductView(product: ProductDetail): ProductView;
 export declare function getProductListView(product: ProductList): ProductView;
+/**
+ * A product's tags as a list, whichever read it came from: a product page's
+ * `tags` is already a list, a listing's is the stored JSON text. Anything
+ * that is not a list of text reads as no tags.
+ */
+export declare function productTags(product: {
+    tags: string | null | readonly string[];
+}): string[];

package/dist/product-view.js

@@ -8,13 +8,18 @@ function discountOf(basePrice, comparePrice) {
         discountPct: Math.round((1 - basePrice / comparePrice) * 100),
     };
 }
-function stockOf(product) {
+/**
+ * Whether what the page opens on can be sold, and is nearly gone: the default
+ * variant's stock for a product with variants, the product's own otherwise.
+ * The product decides whether stock is tracked at all.
+ */
+function stockOf(product, stock = product) {
     if (!product.trackInventory) {
         return { isOutOfStock: false, isLowStock: false };
     }
     return {
-        isOutOfStock: product.inventory === 0,
-        isLowStock: product.inventory > 0 && product.inventory <= product.lowStockThreshold,
+        isOutOfStock: stock.inventory === 0,
+        isLowStock: stock.inventory > 0 && stock.inventory <= stock.lowStockThreshold,
     };
 }
 export function getProductView(product) {
@@ -26,7 +31,7 @@ export function getProductView(product) {
         basePrice,
         comparePrice,
         ...discountOf(basePrice, comparePrice),
-        ...stockOf(product),
+        ...stockOf(product, defaultVariant ?? product),
     };
 }
 export function getProductListView(product) {
@@ -39,3 +44,20 @@ export function getProductListView(product) {
         ...stockOf(product),
     };
 }
+/**
+ * A product's tags as a list, whichever read it came from: a product page's
+ * `tags` is already a list, a listing's is the stored JSON text. Anything
+ * that is not a list of text reads as no tags.
+ */
+export function productTags(product) {
+    let tags = product.tags;
+    if (typeof tags === "string") {
+        try {
+            tags = JSON.parse(tags);
+        }
+        catch {
+            return [];
+        }
+    }
+    return Array.isArray(tags) ? tags.filter((tag) => typeof tag === "string") : [];
+}

package/dist/quote.d.ts

@@ -0,0 +1,27 @@
+import type { CartQuoteOptions } from "./client/cart.js";
+import type { CartQuoteLines } from "./domain.js";
+import type { CartValidation } from "./types.js";
+/**
+ * `fresh`: the answer to the latest question, to show. `stale`: a newer
+ * question was asked meanwhile; keep what is shown. `failed`: the latest
+ * question got no usable answer; the shopper can be told.
+ */
+export type QuoteResult = {
+    status: "fresh";
+    quote: CartValidation;
+} | {
+    status: "stale";
+} | {
+    status: "failed";
+};
+export interface QuoterOptions {
+    /** The theme's cart-validate route (`createStorefrontRoutes().cartValidate`), e.g. `/api/cart/validate`. */
+    endpoint: string;
+    /** The `fetch` to send with; the page's own by default. */
+    fetch?: typeof fetch;
+}
+export interface Quoter {
+    /** Ask what `lines` would cost, with the destination, code and phone the shopper gave so far. */
+    quote(lines: CartQuoteLines, asks?: CartQuoteOptions): Promise<QuoteResult>;
+}
+export declare function createQuoter(options: QuoterOptions): Quoter;

package/dist/quote.js

@@ -0,0 +1,43 @@
+/**
+ * Asking the theme's cart-validate route what an order would cost, from the
+ * browser: a product page as its order form posts it, or the basket.
+ *
+ * Every answer is the server's — lines re-priced from the catalog, offers,
+ * the coupon, the delivery fee — and a form asks again whenever the shopper
+ * changes something. Only the latest question counts: a slower answer to an
+ * earlier one is `stale`, so it never replaces what a newer answer shows.
+ */
+import { readCartQuote } from "./answer-readers.js";
+export function createQuoter(options) {
+    let latest = 0;
+    return {
+        async quote(lines, asks = {}) {
+            const id = ++latest;
+            const send = options.fetch ?? globalThis.fetch;
+            const body = {
+                ...lines,
+                ...(asks.destination ? { destination: asks.destination } : {}),
+                ...(asks.couponCode ? { couponCode: asks.couponCode } : {}),
+                ...(asks.phone ? { phone: asks.phone } : {}),
+            };
+            let quote = null;
+            try {
+                const response = await send(options.endpoint, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(body),
+                });
+                if (response.ok) {
+                    const payload = await response.json();
+                    quote = typeof payload === "object" && payload !== null ? readCartQuote(payload.data) : null;
+                }
+            }
+            catch {
+                quote = null;
+            }
+            if (id !== latest)
+                return { status: "stale" };
+            return quote === null ? { status: "failed" } : { status: "fresh", quote };
+        },
+    };
+}

package/dist/review-capture.d.ts

@@ -0,0 +1,77 @@
+/**
+ * What a review form does in the browser before a photo or a voice note is
+ * sent, so it arrives small on a slow mobile connection: a photo shrunk and
+ * re-encoded without its EXIF, a voice note recorded at a low bitrate that
+ * stops at the store's limit. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+export interface PhotoOptions {
+    /** Longest edge in pixels. Default 1600 (what the server keeps). */
+    maxEdge?: number;
+    /** Encoder quality, 0–1. Default 0.82. */
+    quality?: number;
+}
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export declare function photoTargetSize(width: number, height: number, maxEdge: number): {
+    width: number;
+    height: number;
+};
+export interface PhotoDeps {
+    createImageBitmap: (image: Blob, options?: ImageBitmapOptions) => Promise<ImageBitmap>;
+    /** A canvas of the given size that can encode itself. */
+    createCanvas: (width: number, height: number) => {
+        getContext(type: "2d"): Pick<CanvasRenderingContext2D, "drawImage"> | null;
+        toBlob(type: string, quality: number): Promise<Blob | null>;
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export declare function prepareReviewPhoto(photo: Blob, options?: PhotoOptions, deps?: PhotoDeps | null): Promise<Blob>;
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export declare const VOICE_MIME_TYPES: readonly ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export declare function pickVoiceMimeType(isTypeSupported: (type: string) => boolean): string | null;
+export interface RecordedVoice {
+    blob: Blob;
+    /** As measured while recording; send it with the upload. */
+    durationMs: number;
+    mimeType: string;
+}
+export interface VoiceRecorderOptions {
+    /** Stops by itself after this many seconds (the store's limit). */
+    maxSeconds: number;
+    /** About every 250 ms while recording, with the time recorded so far. */
+    onTick?: (elapsedMs: number) => void;
+    /** When it stopped by itself at the limit. */
+    onLimit?: (voice: RecordedVoice) => void;
+}
+export interface VoiceRecorder {
+    /** Asks for the microphone and starts. Rejects when it is refused or unavailable. */
+    start(): Promise<void>;
+    /** Stops and gives the recording. */
+    stop(): Promise<RecordedVoice>;
+    /** Stops and throws the recording away. */
+    cancel(): void;
+    readonly state: "idle" | "recording" | "stopped";
+}
+export interface VoiceDeps {
+    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
+    MediaRecorder: {
+        new (stream: MediaStream, options?: MediaRecorderOptions): MediaRecorder;
+        isTypeSupported(type: string): boolean;
+    };
+    now: () => number;
+    setInterval: (fn: () => void, ms: number) => unknown;
+    clearInterval: (id: unknown) => void;
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export declare function canRecordVoice(deps?: VoiceDeps | null): boolean;
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export declare function createVoiceRecorder(options: VoiceRecorderOptions, deps?: VoiceDeps | null): VoiceRecorder;

package/dist/review-capture.js

@@ -0,0 +1,172 @@
+/**
+ * What a review form does in the browser before a photo or a voice note is
+ * sent, so it arrives small on a slow mobile connection: a photo shrunk and
+ * re-encoded without its EXIF, a voice note recorded at a low bitrate that
+ * stops at the store's limit. Each takes its browser dependencies as an
+ * optional last argument, for tests and unusual hosts.
+ */
+/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
+export function photoTargetSize(width, height, maxEdge) {
+    const longest = Math.max(width, height);
+    if (longest <= maxEdge || longest === 0)
+        return { width, height };
+    const scale = maxEdge / longest;
+    return { width: Math.max(1, Math.round(width * scale)), height: Math.max(1, Math.round(height * scale)) };
+}
+function browserPhotoDeps() {
+    if (typeof createImageBitmap !== "function" || typeof document === "undefined")
+        return null;
+    return {
+        createImageBitmap: (image, options) => createImageBitmap(image, options),
+        createCanvas: (width, height) => {
+            const canvas = document.createElement("canvas");
+            canvas.width = width;
+            canvas.height = height;
+            return {
+                getContext: () => canvas.getContext("2d"),
+                toBlob: (type, quality) => new Promise((resolve) => canvas.toBlob(resolve, type, quality)),
+            };
+        },
+    };
+}
+/**
+ * A photo ready to send: drawn upright (the camera's orientation applied),
+ * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
+ * written). When the browser cannot do it, the photo is sent as it is — the
+ * server still converts it and drops its EXIF.
+ */
+export async function prepareReviewPhoto(photo, options = {}, deps = browserPhotoDeps()) {
+    if (!deps)
+        return photo;
+    const maxEdge = options.maxEdge ?? 1600;
+    const quality = options.quality ?? 0.82;
+    let bitmap;
+    try {
+        bitmap = await deps.createImageBitmap(photo, { imageOrientation: "from-image" });
+    }
+    catch {
+        return photo;
+    }
+    try {
+        const size = photoTargetSize(bitmap.width, bitmap.height, maxEdge);
+        const canvas = deps.createCanvas(size.width, size.height);
+        const context = canvas.getContext("2d");
+        if (!context)
+            return photo;
+        context.drawImage(bitmap, 0, 0, size.width, size.height);
+        for (const type of ["image/webp", "image/jpeg"]) {
+            const blob = await canvas.toBlob(type, quality);
+            if (blob && blob.type === type && blob.size > 0)
+                return blob;
+        }
+        return photo;
+    }
+    catch {
+        return photo;
+    }
+    finally {
+        bitmap.close?.();
+    }
+}
+/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
+export const VOICE_MIME_TYPES = ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
+/** The first format this browser can record, or null when it cannot record voice. */
+export function pickVoiceMimeType(isTypeSupported) {
+    return VOICE_MIME_TYPES.find((type) => {
+        try {
+            return isTypeSupported(type);
+        }
+        catch {
+            return false;
+        }
+    }) ?? null;
+}
+function browserVoiceDeps() {
+    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getUserMedia || typeof MediaRecorder === "undefined")
+        return null;
+    return {
+        getUserMedia: (constraints) => navigator.mediaDevices.getUserMedia(constraints),
+        MediaRecorder,
+        now: () => performance.now(),
+        setInterval: (fn, ms) => setInterval(fn, ms),
+        clearInterval: (id) => clearInterval(id),
+    };
+}
+/** Whether this browser can record a voice note at all (hide the record button when not). */
+export function canRecordVoice(deps = browserVoiceDeps()) {
+    return Boolean(deps && pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type)));
+}
+/**
+ * A recorder for one voice note: speech at about 32 kb/s, mono, with the
+ * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
+ */
+export function createVoiceRecorder(options, deps = browserVoiceDeps()) {
+    let state = "idle";
+    let recorder = null;
+    let stream = null;
+    let chunks = [];
+    let startedAt = 0;
+    let ticker = null;
+    let finished = null;
+    const release = () => {
+        if (ticker !== null)
+            deps?.clearInterval(ticker);
+        ticker = null;
+        stream?.getTracks().forEach((track) => track.stop());
+        stream = null;
+    };
+    return {
+        get state() {
+            return state;
+        },
+        async start() {
+            if (!deps)
+                throw new Error("This browser cannot record voice notes");
+            if (state === "recording")
+                return;
+            const mimeType = pickVoiceMimeType((type) => deps.MediaRecorder.isTypeSupported(type));
+            if (!mimeType)
+                throw new Error("This browser cannot record voice notes");
+            stream = await deps.getUserMedia({ audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true } });
+            chunks = [];
+            recorder = new deps.MediaRecorder(stream, { mimeType, audioBitsPerSecond: 32_000 });
+            const active = recorder;
+            finished = new Promise((resolve) => {
+                active.ondataavailable = (event) => {
+                    if (event.data.size > 0)
+                        chunks.push(event.data);
+                };
+                active.onstop = () => {
+                    const type = (active.mimeType || mimeType).split(";")[0];
+                    resolve({ blob: new Blob(chunks, { type }), durationMs: Math.round(deps.now() - startedAt), mimeType: type });
+                };
+            });
+            startedAt = deps.now();
+            recorder.start(1000);
+            state = "recording";
+            ticker = deps.setInterval(() => {
+                const elapsed = deps.now() - startedAt;
+                options.onTick?.(elapsed);
+                if (elapsed >= options.maxSeconds * 1000 && state === "recording") {
+                    void this.stop().then((voice) => options.onLimit?.(voice));
+                }
+            }, 250);
+        },
+        async stop() {
+            if (state !== "recording" || !recorder || !finished)
+                throw new Error("Not recording");
+            state = "stopped";
+            recorder.stop();
+            const voice = await finished;
+            release();
+            return voice;
+        },
+        cancel() {
+            if (recorder && state === "recording")
+                recorder.stop();
+            state = "stopped";
+            chunks = [];
+            release();
+        },
+    };
+}

package/dist/review-media.d.ts

@@ -1,8 +1,9 @@
 /**
- * `@wocart/storefront/review-media` — what a theme's review form does in the
- * browser before a photo or a voice note is sent, so it arrives small on a
- * slow mobile connection:
+ * `@wocart/storefront/review-media` — a review form in the browser.
  *
+ *   createReviewSession  proves the purchase, sends each photo or voice note
+ *                        as it is added (progress, retries), and submits the
+ *                        review; every refusal comes back as a code
  *   prepareReviewPhoto   shrinks a photo to 1600 px at most and re-encodes it
  *                        (WebP, else JPEG) — a phone photo of several MB
  *                        becomes a few hundred KB, and its EXIF (the phone's
@@ -12,76 +13,8 @@
  *                        itself at the store's limit
  *
  * Browser-only, and kept off the main entry point: a theme that takes no
- * media pays nothing for it. Each takes its browser dependencies as an
- * optional last argument, for tests and unusual hosts.
+ * reviews pays nothing for it.
  */
-export interface PhotoOptions {
-    /** Longest edge in pixels. Default 1600 (what the server keeps). */
-    maxEdge?: number;
-    /** Encoder quality, 0–1. Default 0.82. */
-    quality?: number;
-}
-/** The size a photo is drawn at: its own, or scaled so its longest edge is `maxEdge`. */
-export declare function photoTargetSize(width: number, height: number, maxEdge: number): {
-    width: number;
-    height: number;
-};
-export interface PhotoDeps {
-    createImageBitmap: (image: Blob, options?: ImageBitmapOptions) => Promise<ImageBitmap>;
-    /** A canvas of the given size that can encode itself. */
-    createCanvas: (width: number, height: number) => {
-        getContext(type: "2d"): Pick<CanvasRenderingContext2D, "drawImage"> | null;
-        toBlob(type: string, quality: number): Promise<Blob | null>;
-    };
-}
-/**
- * A photo ready to send: drawn upright (the camera's orientation applied),
- * no larger than `maxEdge`, re-encoded as WebP (JPEG where WebP cannot be
- * written). When the browser cannot do it, the photo is sent as it is — the
- * server still converts it and drops its EXIF.
- */
-export declare function prepareReviewPhoto(photo: Blob, options?: PhotoOptions, deps?: PhotoDeps | null): Promise<Blob>;
-/** Formats in the order a recorder is tried: Opus where it can be written, AAC on iPhone. */
-export declare const VOICE_MIME_TYPES: readonly ["audio/webm;codecs=opus", "audio/ogg;codecs=opus", "audio/mp4;codecs=mp4a.40.2", "audio/mp4", "audio/webm"];
-/** The first format this browser can record, or null when it cannot record voice. */
-export declare function pickVoiceMimeType(isTypeSupported: (type: string) => boolean): string | null;
-export interface RecordedVoice {
-    blob: Blob;
-    /** As measured while recording; send it with the upload. */
-    durationMs: number;
-    mimeType: string;
-}
-export interface VoiceRecorderOptions {
-    /** Stops by itself after this many seconds (the store's limit). */
-    maxSeconds: number;
-    /** About every 250 ms while recording, with the time recorded so far. */
-    onTick?: (elapsedMs: number) => void;
-    /** When it stopped by itself at the limit. */
-    onLimit?: (voice: RecordedVoice) => void;
-}
-export interface VoiceRecorder {
-    /** Asks for the microphone and starts. Rejects when it is refused or unavailable. */
-    start(): Promise<void>;
-    /** Stops and gives the recording. */
-    stop(): Promise<RecordedVoice>;
-    /** Stops and throws the recording away. */
-    cancel(): void;
-    readonly state: "idle" | "recording" | "stopped";
-}
-export interface VoiceDeps {
-    getUserMedia: (constraints: MediaStreamConstraints) => Promise<MediaStream>;
-    MediaRecorder: {
-        new (stream: MediaStream, options?: MediaRecorderOptions): MediaRecorder;
-        isTypeSupported(type: string): boolean;
-    };
-    now: () => number;
-    setInterval: (fn: () => void, ms: number) => unknown;
-    clearInterval: (id: unknown) => void;
-}
-/** Whether this browser can record a voice note at all (hide the record button when not). */
-export declare function canRecordVoice(deps?: VoiceDeps | null): boolean;
-/**
- * A recorder for one voice note: speech at about 32 kb/s, mono, with the
- * phone's echo cancellation and noise suppression — 60 s is about 240 KB.
- */
-export declare function createVoiceRecorder(options: VoiceRecorderOptions, deps?: VoiceDeps | null): VoiceRecorder;
+export * from "./review-capture.js";
+export { createReviewSession } from "./review-session.js";
+export type { ReviewDraft, ReviewFindResult, ReviewRefusal, ReviewSession, ReviewSessionDeps, ReviewSessionOptions, ReviewSessionRoutes, ReviewSubmission, ReviewUpload, ReviewUploadOptions, ReviewUploadRequest, ReviewUploadResult, } from "./review-session.js";