@wocart/storefront 0.0.0-stage → 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,418 @@
+import { z } from "zod";
+import { ProductSchema, ProductListSchema, CategorySchema, ProductImageSchema, ProductVariantSchema, OfferSchema, PageDocumentPayloadSchema } from "./schemas.js";
+export type Product = z.infer<typeof ProductSchema>;
+export type ProductList = z.infer<typeof ProductListSchema>;
+/** Compact catalog projection used in grids, cards and search results. */
+export type ProductListItem = ProductList;
+/** Complete catalog projection used on a product detail surface. */
+export type ProductDetail = Product;
+export type Category = z.infer<typeof CategorySchema>;
+export type ProductImage = z.infer<typeof ProductImageSchema>;
+export type ProductVariant = z.infer<typeof ProductVariantSchema>;
+export type Offer = z.infer<typeof OfferSchema>;
+/**
+ * One store's saved composition document for one surface. Transport shape
+ * only — `sections` items are `unknown`; the theme
+ * SDK's `parsePageData` validates what they mean.
+ */
+export type PageDocumentPayload = z.infer<typeof PageDocumentPayloadSchema>;
+/**
+ * The merchant's order-form configuration, as the server resolves it.
+ *
+ * A plain type, not a schema: the server has already applied the defaults and
+ * validated every value by the time this arrives, and it enforces all of it
+ * again on POST /store/orders. The theme's job is to render what it is told —
+ * a theme that decided anything about form rules would be engine logic in a
+ * swappable layer, and the two copies would drift.
+ *
+ * `address` may be "hidden" (some merchants take it by phone after the order).
+ * A hidden field ships no markup at all; whether a HOME parcel may then leave
+ * without an address is a platform decision, enforced at dispatch — not here.
+ */
+export interface CheckoutFormPolicy {
+    address: "required" | "optional" | "hidden";
+    notes: "optional" | "hidden";
+    email: "required" | "optional" | "hidden";
+    deliveryOptions: {
+        home: boolean;
+        stopDesk: boolean;
+    };
+    customFields: CheckoutFormCustomField[];
+}
+export interface CheckoutFormCustomField {
+    /** Server-minted. Answers are keyed by it, so it outlives label edits. */
+    id: string;
+    /** Merchant-authored text. Render as a text node — never as markup. */
+    label: string;
+    type: "text" | "textarea" | "number" | "select";
+    required: boolean;
+    /** `select` only. */
+    options?: string[] | undefined;
+}
+/** A language the store serves (`StoreConfig.locales`). */
+export interface StorefrontLanguage {
+    /** BCP 47 code, e.g. `ar`, `fr`. */
+    code: string;
+    /** The language's name in itself, for a language switcher. */
+    nativeName: string;
+    /** `<html dir>` for this language. */
+    direction: "rtl" | "ltr";
+}
+export interface StoreConfig {
+    id: string;
+    name: string;
+    domain: string | null;
+    logoUrl: string | null;
+    themeId: string;
+    primaryColor: string;
+    accentColor: string;
+    bgColor: string;
+    fontFamily: string;
+    fontUrl: string | null;
+    /** The store's primary language: a BCP 47 code such as `ar`. */
+    lang: string;
+    /**
+     * The language this config was served in: the client's `locale` when the
+     * store publishes it, `lang` otherwise.
+     */
+    locale: string;
+    /** The published languages, primary first (always includes `lang`). */
+    locales: StorefrontLanguage[];
+    /**
+     * The store's edits to this theme's text, one map per published language:
+     * `{ ar: { heroTitle: "…" } }`. Sent only to a client created with `theme`.
+     * A theme merges `contentOverrides[locale]` over its own pack for that
+     * language — never another language's map.
+     */
+    contentOverrides: Record<string, Record<string, string>>;
+    currency: string;
+    currencySymbol: string;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    ogImage: string | null;
+    announcementBar: string | null;
+    reviewsEnabled: boolean;
+    /** When true the storefront renders the cart alongside the direct order form. */
+    cartEnabled: boolean;
+    /** Subtotal (DZD) at or above which delivery is free. null = no threshold. */
+    freeShippingThreshold: number | null;
+    cartShippingMode: "highest" | "default_profile";
+    otpEnabled: boolean;
+    /** Cloudflare Turnstile — true only when a store_turnstile_config row exists AND is enabled. */
+    turnstileEnabled: boolean;
+    /** Public widget site key; null when Turnstile is disabled. The secret never leaves the server. */
+    turnstileSiteKey: string | null;
+    status: "active" | "inactive";
+    createdAt: string;
+    updatedAt: string;
+    checkoutForm: CheckoutFormPolicy;
+    pixelId: string | null;
+    conversionEvent: "Purchase" | "Purchase_Confirmed" | "Purchase_Delivered" | "Lead";
+    /**
+     * Published pages that opt into the footer, titled in the store's own
+     * language, ordered for display. The checkout consent line resolves Terms/
+     * Refund from here by `kind` — never a hardcoded slug, since a merchant may
+     * rename any page's slug freely.
+     */
+    pages: StorePageLink[];
+    /**
+     * The public subset of the store's legal profile. Null until the merchant
+     * saves one from the dashboard (Settings → Store Pages) — RC/NIF are never
+     * exposed here, only inside the legal documents themselves.
+     */
+    legalContact: StoreLegalContact | null;
+    /** The WhatsApp contact widget, already resolved, or null when disabled. */
+    whatsapp: StoreWhatsAppWidget | null;
+}
+/** The merchant's per-surface switches for the WhatsApp contact widget. */
+export type WidgetSurfaces = StoreWhatsAppWidget["surfaces"];
+export interface StoreWhatsAppWidget {
+    href: string;
+    agentName: string | null;
+    caption: string | null;
+    avatarUrl: string | null;
+    welcomeMessage: string | null;
+    launcherLabel: string | null;
+    ctaLabel: string | null;
+    prefillGeneral: string | null;
+    prefillProduct: string | null;
+    /** Button label for the thank-you surface's WhatsApp CTA. */
+    thankYouButtonLabel: string | null;
+    /** Message prefill for the thank-you surface's WhatsApp CTA; supports `{order}`. */
+    prefillThankYou: string | null;
+    accent: "whatsapp" | "primary";
+    position: "right" | "left";
+    attention: boolean;
+    surfaces: {
+        home: boolean;
+        catalog: boolean;
+        product: boolean;
+        pages: boolean;
+        thankYou: boolean;
+        checkout: boolean;
+        landing: boolean;
+    };
+}
+export interface StorePageLink {
+    id: string;
+    kind: "terms" | "privacy" | "refund" | "shipping" | "custom";
+    slug: string;
+    title: string;
+    position: number;
+}
+export interface StoreLegalContact {
+    contactEmail: string | null;
+    contactPhone: string | null;
+    deliveryMinDays: number;
+    deliveryMaxDays: number;
+}
+/** A resolved store page — GET /store/pages/{slug}. */
+export interface StorePagePublic {
+    id: string;
+    kind: "terms" | "privacy" | "refund" | "shipping" | "custom";
+    slug: string;
+    locale: string;
+    title: string;
+    /** Sanitised HTML. Render with set:html and never re-sanitise. */
+    bodyHtml: string;
+    metaTitle: string | null;
+    metaDescription: string | null;
+}
+export interface ShippingRates {
+    [wilayaId: string]: WilayaRates;
+}
+/** Delivery pricing for one wilaya. */
+export interface WilayaRates {
+    home: number;
+    stopDesk: number;
+}
+/** One image in a landing page's ordered stack. */
+export interface LandingPageImage {
+    id: string;
+    src: string;
+    altText: string | null;
+    position: number;
+    /** Intrinsic dimensions (px), captured at upload — the page reserves the box. */
+    width: number | null;
+    height: number | null;
+}
+/**
+ * A published landing page — GET /store/landing-pages/{slug}.
+ *
+ * The ordered image stack,
+ * spacing, and the linked product in full store-product shape so the order
+ * form works unmodified. Draft/archived/unknown slugs resolve to null —
+ * the theme redirects to the store home, never a dead end.
+ */
+export interface LandingPage {
+    id: string;
+    slug: string;
+    name: string;
+    status: "draft" | "published" | "archived";
+    /** Pixels between stacked images. */
+    imageGap: number;
+    metaTitle: string | null;
+    metaDescription: string | null;
+    publishedAt: string | null;
+    /** The image stack, ordered by position (1 = top). */
+    images: LandingPageImage[];
+    /** Null when the product is no longer publicly visible. */
+    product: Product | null;
+    /**
+     * Which Meta pixel THIS page loads and fires at, already resolved
+     * server-side — the browser never works this out for itself, so it cannot
+     * disagree with the Conversions API mirror.
+     */
+    tracking: {
+        pixelId: string | null;
+        conversionEvent: "Lead" | "Purchase" | "Purchase_Confirmed" | "Purchase_Delivered";
+    };
+}
+export interface Wilaya {
+    id: number;
+    name: string;
+    nameAr: string;
+}
+export interface Commune {
+    id: string;
+    name: string;
+    nameAr: string;
+}
+/** One re-priced basket line from POST /store/cart/validate. */
+export interface CartValidationLine {
+    productId: string;
+    variantId: string | null;
+    variantLabel: string | null;
+    productName: string;
+    quantity: number;
+    /** CURRENT catalog price — the cart's optimistic price is display-only. */
+    unitPrice: number;
+    lineTotal: number;
+    /** Units still available; null when the product is not stock-tracked. */
+    maxQuantity: number | null;
+    /**
+     * Why the line cannot be ordered as requested. Blocked lines are excluded
+     * from subtotal, offers and free-delivery math server-side.
+     */
+    blocker: "missing" | "unlisted" | "out_of_stock" | null;
+}
+/** A satisfied Buy-X-Get-Y reward, appended server-side at order time. */
+export interface CartReward {
+    offerId: string;
+    productId: string | null;
+    productName: string | null;
+    quantity: number;
+}
+/** The catalog's truth about a basket, right now. Read-only — nothing is written. */
+export interface CartValidation {
+    lines: CartValidationLine[];
+    subtotal: number;
+    rewards: CartReward[];
+    /** Subtotal-based, so answerable before the shopper types an address. */
+    freeDelivery: {
+        fromOffer: boolean;
+        threshold: number | null;
+        qualified: boolean;
+        remaining: number;
+    };
+}
+/** What POST /store/orders returns on 201. */
+export interface CreatedOrder {
+    orderId: string;
+    orderNumber: string;
+    price: number;
+    deliveryFee: number;
+    /** price + deliveryFee, after any offer. */
+    total: number;
+}
+/** One basket line in a create-order body. */
+export interface CreateOrderItemInput {
+    productId: string;
+    productName: string;
+    variantId?: string | undefined;
+    variantLabel?: string | undefined;
+    quantity: number;
+    /**
+     * Display-only continuity value. The server re-prices every line from the
+     * catalog row; a price sent from the browser is never charged.
+     */
+    pricePerUnit?: number | undefined;
+    /** Explicit offer tier the shopper selected. */
+    offerId?: string | undefined;
+}
+/** One per-unit variant selection, for multi-unit orders. */
+export interface CreateOrderVariantSelection {
+    variantId: string;
+    variantLabel?: string | undefined;
+}
+/**
+ * The create-order body the server accepts.
+ *
+ * An order is either a basket or a single product, never neither: `items[]`
+ * supersedes the flat `productId`/`productName`/`pricePerUnit`, and without
+ * `items[]` all three are required. The server re-checks every rule (bounds,
+ * sellability, OTP/Turnstile proof, checkout-form policy) — this type states
+ * what may travel, not what will be accepted.
+ *
+ * `phone` may be any shape a shopper types; the server normalises it to the
+ * canonical local `05XXXXXXXX` form before deduplicating customers.
+ */
+export interface CreateOrderInput {
+    customerName: string;
+    phone: string;
+    wilayaId: number;
+    communeId: string;
+    address?: string | undefined;
+    deliveryType?: "home" | "stop_desk" | undefined;
+    /** The one product a direct order form was rendered for. */
+    productId?: string | undefined;
+    productName?: string | undefined;
+    variantId?: string | undefined;
+    variantLabel?: string | undefined;
+    quantity?: number | undefined;
+    /** Display-only, like the basket line's. */
+    pricePerUnit?: number | undefined;
+    notes?: string | undefined;
+    email?: string | undefined;
+    /** Answers to the merchant's custom checkout fields, keyed by field id. */
+    customFieldResponses?: string | unknown[] | undefined;
+    offerId?: string | undefined;
+    /** Meta click/browser cookies captured at placement time. */
+    fbc?: string | undefined;
+    fbp?: string | undefined;
+    /** WhatsApp OTP proof — required only while the store has OTP enabled. */
+    otpToken?: string | undefined;
+    /** Cloudflare Turnstile proof — required only while Turnstile is enabled. */
+    turnstileToken?: string | undefined;
+    variantSelections?: CreateOrderVariantSelection[] | undefined;
+    items?: CreateOrderItemInput[] | undefined;
+    /** Landing-page attribution — best-effort; an unknown slug never blocks. */
+    landingPageSlug?: string | undefined;
+}
+/**
+ * The order's tracking destination — which Meta pixel it belongs to and
+ * which browser event the thank-you page may fire. `event` is null when no
+ * browser event should fire (tracking off, or the merchant's conversion
+ * fires server-side further down the funnel).
+ */
+export interface OrderTracking {
+    pixelId: string | null;
+    event: "Purchase" | "Lead" | null;
+}
+/** POST /store/otp/send success payload. */
+export type OtpSendResult = {
+    status: "sent";
+    requestId: string;
+    /** Unix milliseconds. */
+    expiresAt: number;
+    maxAttempts: number;
+} | {
+    /** Fail-open: checkout proceeds unverified with the bypass token. */
+    status: "unavailable";
+    reason: string;
+    bypassToken: string;
+};
+/** POST /store/otp/verify success payload. */
+export type OtpVerifyResult = {
+    status: "verified";
+    /** Signed, 15-min TTL, bound to the phone. Travels with the order. */
+    otpToken: string;
+};
+export interface Review {
+    id: string;
+    customerName: string;
+    rating: number;
+    title: string | null;
+    body: string;
+    createdAt: string;
+}
+/**
+ * Filters `products.list()` accepts — named so a theme can type its own
+ * wrappers and route query parsing without re-declaring the shape.
+ */
+export interface ProductListFilters {
+    categoryId?: string;
+    featured?: boolean;
+    /** Server-side cap; the server clamps anything larger. */
+    limit?: number;
+    /** Products to skip — with `limit`, pages through the whole catalog. */
+    offset?: number;
+}
+/** `products.reviews.list()` paging — named for the same reason. */
+export interface ReviewListPagination {
+    limit?: number;
+    offset?: number;
+}
+/**
+ * The body `products.reviews.submit()` accepts: the order number is the proof
+ * of purchase, and the server owns every other rule (moderation, one-review
+ * per order line).
+ */
+export interface ReviewInput {
+    orderNumber: string;
+    productId: string;
+    /** 1–5, the server validates the range. */
+    rating: number;
+    title?: string;
+    body: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/image.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Cloudflare Image Resizing Utility
+ *
+ * Generates optimized image URLs using Cloudflare's Image Resizing service.
+ * Automatically resizes images to exact dimensions and converts to WebP format.
+ *
+ * Deep module: hides Cloudflare CDN-CGI URL construction, fit modes, format
+ * negotiation, and no-op fallback logic behind a simple interface.
+ */
+export interface ImageResizeOptions {
+    width: number;
+    height: number;
+    quality?: number;
+    format?: "webp" | "avif" | "auto";
+    fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
+}
+/**
+ * Generate an optimized image URL using Cloudflare Image Resizing
+ *
+ * @param originalUrl - The original image URL from R2
+ * @param options - Resize and optimization options
+ * @param mediaDomain - Media domain (e.g., "media.example.com" or "https://media.example.com")
+ * @returns Optimized image URL
+ *
+ * @example
+ * ```ts
+ * const url = optimizeImage(
+ *   'https://media.example.com/products/image.jpg',
+ *   { width: 400, height: 400 },
+ *   'media.example.com'
+ * );
+ * // Returns: https://media.example.com/cdn-cgi/image/width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
+ * ```
+ */
+export declare function optimizeImage(originalUrl: string, options: ImageResizeOptions, mediaDomain?: string): string;
+/**
+ * Predefined image sizes for common use cases
+ */
+export declare const IMAGE_SIZES: {
+    readonly CARD: {
+        readonly width: 400;
+        readonly height: 400;
+        readonly quality: 85;
+    };
+    readonly GALLERY_MAIN: {
+        readonly width: 800;
+        readonly height: 800;
+        readonly quality: 90;
+    };
+    readonly GALLERY_THUMB: {
+        readonly width: 80;
+        readonly height: 80;
+        readonly quality: 80;
+    };
+    readonly HERO: {
+        readonly width: 1200;
+        readonly height: 600;
+        readonly quality: 90;
+    };
+    readonly CATEGORY: {
+        readonly width: 300;
+        readonly height: 200;
+        readonly quality: 85;
+    };
+    readonly LOGO: {
+        readonly width: 200;
+        readonly height: 80;
+        readonly quality: 90;
+        readonly fit: "contain";
+    };
+};
+/**
+ * Quick helper functions for common image sizes
+ *
+ * These take the media domain per call. Theme code usually binds it once with
+ * `createImageHelpers(mediaDomain)` and uses the returned helpers, so a call
+ * site can never forget the domain and silently ship an unoptimized image.
+ */
+export declare const getCardImage: (url: string, mediaDomain?: string) => string;
+export declare const getGalleryImage: (url: string, mediaDomain?: string) => string;
+export declare const getThumbnailImage: (url: string, mediaDomain?: string) => string;
+export declare const getHeroImage: (url: string, mediaDomain?: string) => string;
+export declare const getCategoryImage: (url: string, mediaDomain?: string) => string;
+export declare const getLogoImage: (url: string, mediaDomain?: string) => string;
+/**
+ * Generate responsive image srcset for different screen sizes
+ *
+ * @param originalUrl - The original image URL
+ * @param baseWidth - Base width for 1x display
+ * @param baseHeight - Base height for 1x display
+ * @param mediaDomain - Media domain
+ * @returns srcset string for responsive images
+ *
+ * @example
+ * ```ts
+ * const srcset = generateSrcSet(
+ *   'https://media.example.com/products/image.jpg',
+ *   400,
+ *   400,
+ *   'media.example.com'
+ * );
+ * // Returns: "url 1x, url 1.5x, url 2x"
+ * ```
+ */
+export declare function generateSrcSet(originalUrl: string, baseWidth: number, baseHeight: number, mediaDomain?: string): string;
+/**
+ * Bind a media domain once and get the whole image toolkit back.
+ *
+ * The single binding point for theme code: a media domain is configured once
+ * (an env var, a store setting), and every helper then takes only the URL. A
+ * per-call domain still wins, so a theme with two media hosts can override.
+ *
+ * With no domain bound every helper is a pass-through — the correct behavior
+ * for a store that has no media domain configured (original R2 URLs).
+ *
+ * @param mediaDomain - Media domain (e.g., "media.example.com" or "https://media.example.com")
+ *
+ * @example
+ * ```ts
+ * const images = createImageHelpers(env.MEDIA_DOMAIN);
+ * images.getThumbnailImage(product.coverImage.src);
+ * images.getCardImage(url);
+ * images.generateSrcSet(url, 400, 400);
+ * ```
+ */
+export interface ImageHelpers {
+    /** `optimizeImage` with the media domain bound. */
+    optimizeImage: (originalUrl: string, options: ImageResizeOptions, mediaDomain?: string) => string;
+    /** `generateSrcSet` with the media domain bound. */
+    generateSrcSet: (originalUrl: string, baseWidth: number, baseHeight: number, mediaDomain?: string) => string;
+    /** The shared size presets, for callers that want the raw dimensions. */
+    IMAGE_SIZES: typeof IMAGE_SIZES;
+    getCardImage: (url: string) => string;
+    getGalleryImage: (url: string) => string;
+    getThumbnailImage: (url: string) => string;
+    getHeroImage: (url: string) => string;
+    getCategoryImage: (url: string) => string;
+    getLogoImage: (url: string) => string;
+}
+export declare function createImageHelpers(mediaDomain?: string): ImageHelpers;

package/dist/utils/image.js

@@ -0,0 +1,131 @@
+/**
+ * Cloudflare Image Resizing Utility
+ *
+ * Generates optimized image URLs using Cloudflare's Image Resizing service.
+ * Automatically resizes images to exact dimensions and converts to WebP format.
+ *
+ * Deep module: hides Cloudflare CDN-CGI URL construction, fit modes, format
+ * negotiation, and no-op fallback logic behind a simple interface.
+ */
+/**
+ * Generate an optimized image URL using Cloudflare Image Resizing
+ *
+ * @param originalUrl - The original image URL from R2
+ * @param options - Resize and optimization options
+ * @param mediaDomain - Media domain (e.g., "media.example.com" or "https://media.example.com")
+ * @returns Optimized image URL
+ *
+ * @example
+ * ```ts
+ * const url = optimizeImage(
+ *   'https://media.example.com/products/image.jpg',
+ *   { width: 400, height: 400 },
+ *   'media.example.com'
+ * );
+ * // Returns: https://media.example.com/cdn-cgi/image/width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
+ * ```
+ */
+export function optimizeImage(originalUrl, options, mediaDomain) {
+    // No-op when mediaDomain is empty or URL doesn't match
+    if (!mediaDomain || !originalUrl) {
+        return originalUrl;
+    }
+    const normalizedDomain = `https://${mediaDomain.replace(/^https?:\/\//, "")}`;
+    let mediaOrigin;
+    let original;
+    try {
+        mediaOrigin = new URL(normalizedDomain).origin;
+        original = new URL(originalUrl);
+    }
+    catch {
+        return originalUrl;
+    }
+    // Only optimize a URL from the configured media origin
+    if (original.origin !== mediaOrigin) {
+        return originalUrl;
+    }
+    const { width, height, quality = 85, format = "webp", fit = "cover" } = options;
+    const imagePath = `${original.pathname.replace(/^\/+/, "")}${original.search}${original.hash}`;
+    // Build the Cloudflare Image Resizing URL
+    const resizeParams = [
+        `width=${width}`,
+        `height=${height}`,
+        `format=${format}`,
+        `quality=${quality}`,
+        `fit=${fit}`,
+    ].join(",");
+    return `${mediaOrigin}/cdn-cgi/image/${resizeParams}/${imagePath}`;
+}
+/**
+ * Predefined image sizes for common use cases
+ */
+export const IMAGE_SIZES = {
+    // Product cards (grid view)
+    CARD: { width: 400, height: 400, quality: 85 },
+    // Product gallery main image
+    GALLERY_MAIN: { width: 800, height: 800, quality: 90 },
+    // Product gallery thumbnails
+    GALLERY_THUMB: { width: 80, height: 80, quality: 80 },
+    // Hero/banner images
+    HERO: { width: 1200, height: 600, quality: 90 },
+    // Category images
+    CATEGORY: { width: 300, height: 200, quality: 85 },
+    // Logo/brand images
+    LOGO: { width: 200, height: 80, quality: 90, fit: "contain" },
+};
+/**
+ * Quick helper functions for common image sizes
+ *
+ * These take the media domain per call. Theme code usually binds it once with
+ * `createImageHelpers(mediaDomain)` and uses the returned helpers, so a call
+ * site can never forget the domain and silently ship an unoptimized image.
+ */
+export const getCardImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.CARD, mediaDomain);
+export const getGalleryImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.GALLERY_MAIN, mediaDomain);
+export const getThumbnailImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.GALLERY_THUMB, mediaDomain);
+export const getHeroImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.HERO, mediaDomain);
+export const getCategoryImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.CATEGORY, mediaDomain);
+export const getLogoImage = (url, mediaDomain) => optimizeImage(url, IMAGE_SIZES.LOGO, mediaDomain);
+/**
+ * Generate responsive image srcset for different screen sizes
+ *
+ * @param originalUrl - The original image URL
+ * @param baseWidth - Base width for 1x display
+ * @param baseHeight - Base height for 1x display
+ * @param mediaDomain - Media domain
+ * @returns srcset string for responsive images
+ *
+ * @example
+ * ```ts
+ * const srcset = generateSrcSet(
+ *   'https://media.example.com/products/image.jpg',
+ *   400,
+ *   400,
+ *   'media.example.com'
+ * );
+ * // Returns: "url 1x, url 1.5x, url 2x"
+ * ```
+ */
+export function generateSrcSet(originalUrl, baseWidth, baseHeight, mediaDomain) {
+    const sizes = [
+        { width: baseWidth, height: baseHeight, density: "1x" },
+        { width: Math.round(baseWidth * 1.5), height: Math.round(baseHeight * 1.5), density: "1.5x" },
+        { width: baseWidth * 2, height: baseHeight * 2, density: "2x" },
+    ];
+    return sizes
+        .map((size) => `${optimizeImage(originalUrl, size, mediaDomain)} ${size.density}`)
+        .join(", ");
+}
+export function createImageHelpers(mediaDomain) {
+    return {
+        optimizeImage: (originalUrl, options, domain = mediaDomain) => optimizeImage(originalUrl, options, domain),
+        generateSrcSet: (originalUrl, baseWidth, baseHeight, domain = mediaDomain) => generateSrcSet(originalUrl, baseWidth, baseHeight, domain),
+        IMAGE_SIZES,
+        getCardImage: (url) => getCardImage(url, mediaDomain),
+        getGalleryImage: (url) => getGalleryImage(url, mediaDomain),
+        getThumbnailImage: (url) => getThumbnailImage(url, mediaDomain),
+        getHeroImage: (url) => getHeroImage(url, mediaDomain),
+        getCategoryImage: (url) => getCategoryImage(url, mediaDomain),
+        getLogoImage: (url) => getLogoImage(url, mediaDomain),
+    };
+}