@wocart/storefront 1.23.0 → 2.0.0

package/dist/schemas.js

@@ -1,10 +1,17 @@
 import { z } from "zod";
-export const ProductImageSchema = z.object({
+import { MEDIA_DELIVERY_KINDS } from "./utils/image.js";
+export const MediaImageSchema = z.object({
+    key: z.string(),
+    url: z.string().url(),
+    width: z.number().int().nullable(),
+    height: z.number().int().nullable(),
+});
+export const MediaDeliverySchema = z.object({
+    kind: z.enum(MEDIA_DELIVERY_KINDS),
+    origin: z.string().url(),
+});
+export const ProductImageSchema = MediaImageSchema.extend({
     id: z.string(),
-    src: z.string().url(),
-    srcSm: z.string().url().nullable(),
-    srcMd: z.string().url().nullable(),
-    srcLg: z.string().url().nullable(),
     altText: z.string().nullable(),
     position: z.number().int().min(0),
 });
@@ -63,7 +70,7 @@ const productCategorySchema = z.object({
     slug: z.string(),
     description: z.string().nullable(),
     parentId: z.string().nullable(),
-    imageUrl: z.string().url().nullable(),
+    image: MediaImageSchema.nullable(),
     metaTitle: z.string().nullable(),
     metaDescription: z.string().nullable(),
     metaKeywords: z.string().nullable(),
@@ -265,7 +272,7 @@ export const StoreConfigSchema = z.object({
     id: z.string(),
     name: z.string(),
     domain: z.string().nullable(),
-    logoUrl: z.string().nullable(),
+    logo: MediaImageSchema.nullable(),
     themeId: z.string(),
     primaryColor: z.string(),
     accentColor: z.string(),
@@ -290,7 +297,8 @@ export const StoreConfigSchema = z.object({
     currencySymbol: z.string(),
     metaTitle: z.string().nullable(),
     metaDescription: z.string().nullable(),
-    ogImage: z.string().nullable(),
+    ogImage: MediaImageSchema.nullable(),
+    media: MediaDeliverySchema,
     announcementBar: z.string().nullable(),
     reviewsEnabled: z.boolean(),
     cartEnabled: z.boolean(),
@@ -317,13 +325,10 @@ export const StoreConfigSchema = z.object({
     legalContact: StoreLegalContactSchema.nullable().default(null),
     whatsapp: StoreWhatsAppWidgetSchema.nullable().default(null),
 });
-export const LandingPageImageSchema = z.object({
+export const LandingPageImageSchema = MediaImageSchema.extend({
     id: z.string(),
-    src: z.string(),
     altText: z.string().nullable(),
     position: z.number().int(),
-    width: z.number().int().nullable().default(null),
-    height: z.number().int().nullable().default(null),
 });
 export const LandingPageSchema = z.object({
     id: z.string(),

package/dist/seo.js

@@ -55,7 +55,7 @@ export function productStructuredData(product, options) {
         ? { "@type": "AggregateOffer", url: options.url, priceCurrency: product.currency, lowPrice: Math.min(...prices), highPrice: Math.max(...prices), offerCount: prices.length, availability }
         : { "@type": "Offer", url: options.url, priceCurrency: product.currency, price: view.basePrice, availability, itemCondition: "https://schema.org/NewCondition" };
     const sku = product.sku ?? (product.hasVariants ? initialVariant(product)?.sku : null) ?? null;
-    const images = [...product.images].sort((a, b) => a.position - b.position).map((image) => image.src);
+    const images = [...product.images].sort((a, b) => a.position - b.position).map((image) => image.url);
     const rating = product.reviewStats && product.reviewStats.reviewCount > 0 ? product.reviewStats : null;
     return {
         "@context": "https://schema.org",

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { COUPON_REFUSAL_REASONS } from "./coupon.js";
 import type { PRODUCT_SORTS, SHOPPER_ORDER_STAGES } from "./catalog.js";
 import { z } from "zod";
+import type { MediaDelivery, MediaImage } from "./utils/image.js";
 import { ProductSchema, ProductListSchema, CategorySchema, ProductImageSchema, ProductVariantSchema, OfferSchema, QuantityPricingSchema, PageDocumentPayloadSchema } from "./schemas.js";
 export type Product = z.infer<typeof ProductSchema>;
 export type ProductList = z.infer<typeof ProductListSchema>;
@@ -67,7 +68,7 @@ export interface StoreConfig {
     id: string;
     name: string;
     domain: string | null;
-    logoUrl: string | null;
+    logo: MediaImage | null;
     themeId: string;
     /**
      * @deprecated A store's colors and font are its theme's settings: declare
@@ -124,7 +125,10 @@ export interface StoreConfig {
     currencySymbol: string;
     metaTitle: string | null;
     metaDescription: string | null;
-    ogImage: string | null;
+    /** The image links to the store show when shared. */
+    ogImage: MediaImage | null;
+    /** Where every image key is served from, and how it is resized: pass it to `mediaUrl`, `mediaImageUrl` and `pictureOf`. */
+    media: MediaDelivery;
     /**
      * @deprecated Always null. An announcement is a theme's own content: declare
      * it as a theme setting and read `themeSettings`. Removed in 2.0.
@@ -256,14 +260,10 @@ export interface WilayaRates {
     stopDesk: number;
 }
 /** One image in a landing page's ordered stack. */
-export interface LandingPageImage {
+export interface LandingPageImage extends MediaImage {
     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}.

package/dist/utils/image.d.ts

@@ -1,88 +1,74 @@
 /**
- * Cloudflare Image Resizing Utility
+ * The store's images: where a key is served, and how a photo is asked for at
+ * the size a page shows it.
  *
- * 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.
+ * Every image the store's server answers is a `MediaImage` — its key and its
+ * URL — and the store's config carries its `MediaDelivery`: the origin every
+ * key is served from and how that origin resizes. These helpers take that
+ * delivery, so one theme works on every host a store can use.
  */
-export interface ImageResizeOptions {
-    width: number;
-    height: number;
-    quality?: number;
-    format?: "webp" | "avif" | "auto";
-    fit?: "scale-down" | "contain" | "cover" | "crop" | "pad";
+export declare const MEDIA_DELIVERY_KINDS: readonly ["imagekit", "cloudflare", "direct"];
+/** How a store's images are resized: `imagekit` (`?tr=`), `cloudflare` (`/cdn-cgi/image/`), or `direct` (served as stored). */
+export type MediaDeliveryKind = (typeof MEDIA_DELIVERY_KINDS)[number];
+/** Where a store's images are served from: a key's URL is `origin`, a slash, and the key. */
+export interface MediaDelivery {
+    kind: MediaDeliveryKind;
+    origin: string;
 }
-/**
- * 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/onerror=redirect,width=400,height=400,format=webp,quality=85,fit=cover/products/image.jpg
- * ```
- */
-export declare function optimizeImage(originalUrl: string, options: ImageResizeOptions, mediaDomain?: string): string;
-/** What `mediaImageUrl` can ask Cloudflare for; an omitted value is left to Cloudflare's default. */
+/** An image as the store's server answers it. */
+export interface MediaImage {
+    key: string;
+    url: string;
+    width: number | null;
+    height: number | null;
+}
+/** How to show a photo; an omitted value is left to the host's default. */
 export interface MediaImageParams {
     width?: number;
     height?: number;
+    /** Encoder quality, 1–100. */
     quality?: number;
+    /** `auto` lets the host pick the best format the browser takes. */
     format?: string;
+    /** CSS `object-fit` words: `cover` and `crop` fill the box, `contain` and `scale-down` fit inside it (`scale-down` never enlarges), `squeeze` stretches, `pad` letterboxes. */
     fit?: "scale-down" | "contain" | "cover" | "crop" | "pad" | "squeeze";
 }
+/** Whether `value` can be a Media Key: a store folder, then segments of letters, digits, `.`, `_` and `-` that start with a letter or digit. */
+export declare function isMediaKey(value: unknown): value is string;
 /**
- * The Cloudflare Image Resizing URL of an image on the media domain, served
- * by the media domain itself (`https://<media>/cdn-cgi/image/<options>/<path>`)
- * — so it works wherever the storefront is hosted, as long as the media
- * domain's zone has Image Transformations on.
+ * The URL of a key in the store's media — what a theme's `image` field
+ * stores (`products/3f2a9c.webp`). The key is the image's identity; its URL
+ * depends on the store's delivery, so it is derived at render, never stored.
  *
- * `onerror=redirect` comes first: when a resize fails, Cloudflare redirects to
- * the original image instead of answering with an error.
- *
- * @returns `null` when there is no media domain, or the URL is not on it.
+ * @returns `null` without a delivery, or for a value that is not a Media Key.
  */
-export declare function mediaImageUrl(originalUrl: string, params: MediaImageParams, mediaDomain?: string): string | null;
+export declare function mediaUrl(key: string, delivery: MediaDelivery | null | undefined): string | null;
 /**
- * The public URL of an object in the store's media bucket, from its key —
- * what a theme's `image` field stores (`products/3f2a9c.webp`). The key is
- * the image's identity; the URL depends on where the store serves its media,
- * so it is derived here, at render, never stored. Pass the result to
- * `mediaImageUrl` or Astro's `<Image>` to resize it.
+ * A photo of the store's media at the size and format a page shows it, from
+ * the delivery's own resizer: ImageKit's `?tr=` or Cloudflare's
+ * `/cdn-cgi/image/` (which falls back to the original when a resize fails).
  *
- * @returns `null` when there is no media domain, or the key cannot name an
- * object: empty, too long, an empty, `.` or `..` segment (a leading slash
- * makes an empty one), whitespace, control characters, a backslash, `?` or `#`.
+ * @returns `null` without a delivery, for a URL not served by it, or for a
+ * `direct` delivery, which does not resize — show the original then.
  */
-export declare function mediaUrl(key: string, mediaDomain?: string): string | null;
+export declare function mediaImageUrl(url: string, params: MediaImageParams, delivery: MediaDelivery | null | undefined): string | null;
 export interface MediaImageSrcsetOptions {
-    /** The store's media domain; without one there is no srcset. */
-    mediaDomain?: string;
-    /** Height ÷ width: given, each size is cropped to it (`fit=cover`); absent, the photo keeps its shape (`fit=scale-down`). */
+    /** The store's delivery; without one there is no srcset. */
+    delivery: MediaDelivery | null | undefined;
+    /** Height ÷ width: given, each size is cropped to it (`cover`); absent, the photo keeps its shape and is never enlarged (`scale-down`). */
     ratio?: number;
-    /** Encoder quality, 1–100; Cloudflare's default when absent. */
+    /** Encoder quality, 1–100; the host's default when absent. */
     quality?: number;
 }
 /**
  * The same photo at several widths, with width descriptors
  * (`… 360w, … 720w`), for an `<img>` whose `sizes` says how wide it shows —
- * a phone then downloads a phone-sized file. Each size is converted to the
- * best format the browser takes (`format=auto`).
+ * a phone then downloads a phone-sized file, in the best format it takes.
  *
- * @returns `null` when there is no media domain, the URL is not on it, or no
+ * @returns `null` when the photo cannot be resized (see `mediaImageUrl`) or no
  * width is a positive whole number.
  */
-export declare function mediaImageSrcset(src: string, widths: readonly number[], options?: MediaImageSrcsetOptions): string | null;
+export declare function mediaImageSrcset(src: string, widths: readonly number[], options: MediaImageSrcsetOptions): string | null;
 /** An image a merchant picked, by its media key — what a theme's `image` field resolves to. */
 export interface PickedImage {
     key: string;
@@ -105,116 +91,11 @@ export interface Picture {
     position: string | undefined;
 }
 /**
- * A picked image as a theme draws it: its URL on the store's media domain,
- * its alt text (empty when the merchant wrote none), its size, and its focal
- * point as `object-position`, so a cropped photo keeps what matters in view.
+ * A picked image as a theme draws it: its URL in the store's media, its alt
+ * text (empty when the merchant wrote none), its size, and its focal point as
+ * `object-position`, so a cropped photo keeps what matters in view.
  *
- * @returns `null` when no image is picked, the key cannot name an object, or
- * the store has no media domain.
- */
-export declare function pictureOf(image: PickedImage | null | undefined, mediaDomain?: string): Picture | null;
-/**
- * Predefined image sizes for common use cases
+ * @returns `null` when no image is picked, the key is not a Media Key, or there
+ * is no delivery.
  */
-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;
+export declare function pictureOf(image: PickedImage | null | undefined, delivery: MediaDelivery | null | undefined): Picture | null;