@doswiftly/storefront-sdk 4.1.0 → 4.2.0

package/README.md

@@ -7,8 +7,8 @@ Layered runtime SDK for DoSwiftly Commerce storefronts. Hydrogen-aligned archite
 ```
 @doswiftly/storefront-sdk
 ├── core (.)              — Framework-agnostic: transport, middleware, CartClient, AuthClient,
-│                           cache, format utilities, sanitizeHtml, normalizeConnection,
-│                           auth cookie config/handlers/token client, route matching
+│                           cache, format utilities, image loader, sanitizeHtml,
+│                           normalizeConnection, auth cookie config/handlers/token client, route matching
 ├── react (./react)       — React adapter: providers, Zustand stores (Context-based), hooks,
 │                           useHydrated, useDebouncedValue, createStoreContext
 ├── react/server          — Server-side client factory
@@ -93,7 +93,7 @@ const { currency, setCurrency } = useCurrencyStore();
 
 | Path | Description | Dependencies |
 |------|-------------|-------------|
-| `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, errors, format, sanitize, auth handlers, route matching | **0** |
+| `@doswiftly/storefront-sdk` | Core: transport, middleware, clients, errors, format, image loader, sanitize, auth handlers, route matching | **0** |
 | `@doswiftly/storefront-sdk/react` | Providers, hooks, store hooks, useHydrated, useDebouncedValue, createStoreContext | react, zustand |
 | `@doswiftly/storefront-sdk/react/server` | Server-side client factory | react |
 | `@doswiftly/storefront-sdk/cache` | Cache strategy functions | **0** |
@@ -213,6 +213,20 @@ formatDate(new Date());                                // "Dec 9, 2025"
 formatPercentage(0.15);                                // "15%"
 ```
 
+### Image Loader (CDN)
+
+Template ships with global `loaderFile` in `next.config.ts` — ALL `<Image>` components are optimized automatically. No per-component configuration needed.
+
+```typescript
+// For custom frameworks (Svelte, Astro, etc.) — import the loader function directly:
+import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+
+const url = storefrontImageLoader({ src: image.url, width: 800, quality: 85 });
+// → image.url + "?width=800&quality=85&format=webp"
+```
+
+Width quantized to Next.js-aligned breakpoints for CDN cache efficiency. `ImageData` type matches GraphQL `Image` fragment: `{ url, altText?, width?, height?, id? }`.
+
 ### HTML Sanitizer
 
 ```typescript
@@ -442,6 +456,7 @@ SDK provides:                    Template owns:
 ├── Providers + Zustand stores   ├── lib/graphql/fragments/
 ├── Format utilities             ├── hooks/use-cart-di.ts (CartActions DI impl)
 ├── sanitizeHtml                 ├── hooks/use-cart-actions.ts (UX wrapper)
+├── createImageLoader (CDN)      ├── components/product/product-image.tsx
 ├── normalizeConnection          ├── stores/ (checkout, wishlist via createStoreContext)
 ├── Auth handlers + token client ├── lib/auth/routes.ts (route config)
 ├── useHydrated + useDebouncedValue

package/dist/core/image.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Image utilities for DoSwiftly storefronts.
+ *
+ * Zero configuration — GraphQL API returns ready-to-use CDN URLs.
+ * The loader just appends resize query params. No keys, no env vars.
+ *
+ * @example
+ * ```typescript
+ * import { storefrontImageLoader, type ImageData } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={product.featuredImage.url} width={800} alt="..." />
+ * ```
+ */
+/**
+ * Image data from GraphQL API (matches Image type in storefront schema).
+ */
+export interface ImageData {
+    /** Image URL from GraphQL (ready-to-use CDN URL) */
+    url: string;
+    /** Alt text for accessibility + SEO */
+    altText?: string | null;
+    /** Original image width in pixels */
+    width?: number | null;
+    /** Original image height in pixels */
+    height?: number | null;
+    /** Image ID */
+    id?: string | null;
+}
+/**
+ * Next.js Image loader function signature.
+ */
+export interface ImageLoaderParams {
+    src: string;
+    width: number;
+    quality?: number;
+}
+/**
+ * Next.js image loader for DoSwiftly storefronts.
+ *
+ * Zero configuration — works out of the box with GraphQL image URLs.
+ * Appends resize query params (?width=&quality=&format=) to the URL
+ * that backend already returned via GraphQL.
+ *
+ * Width is quantized to preset breakpoints for optimal CDN cache.
+ * No HMAC, no env vars, no setup — like Shopify Hydrogen's image loader.
+ *
+ * @example
+ * ```tsx
+ * import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={image.url} width={800} alt="..." />
+ * ```
+ */
+export declare function storefrontImageLoader({ src, width, quality }: ImageLoaderParams): string;
+//# sourceMappingURL=image.d.ts.map

package/dist/core/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../src/core/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,eAAe;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,MAAM,CAKxF"}

package/dist/core/image.js

@@ -0,0 +1,48 @@
+/**
+ * Image utilities for DoSwiftly storefronts.
+ *
+ * Zero configuration — GraphQL API returns ready-to-use CDN URLs.
+ * The loader just appends resize query params. No keys, no env vars.
+ *
+ * @example
+ * ```typescript
+ * import { storefrontImageLoader, type ImageData } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={product.featuredImage.url} width={800} alt="..." />
+ * ```
+ */
+/**
+ * Preset widths for CDN cache optimization.
+ * Loader quantizes requested width to the nearest preset — limits cache variants.
+ */
+const PRESET_WIDTHS = [150, 320, 640, 750, 828, 1080, 1200, 1600, 1920, 2048];
+function nearestPresetWidth(requested) {
+    for (const w of PRESET_WIDTHS) {
+        if (w >= requested)
+            return w;
+    }
+    return PRESET_WIDTHS[PRESET_WIDTHS.length - 1];
+}
+/**
+ * Next.js image loader for DoSwiftly storefronts.
+ *
+ * Zero configuration — works out of the box with GraphQL image URLs.
+ * Appends resize query params (?width=&quality=&format=) to the URL
+ * that backend already returned via GraphQL.
+ *
+ * Width is quantized to preset breakpoints for optimal CDN cache.
+ * No HMAC, no env vars, no setup — like Shopify Hydrogen's image loader.
+ *
+ * @example
+ * ```tsx
+ * import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={image.url} width={800} alt="..." />
+ * ```
+ */
+export function storefrontImageLoader({ src, width, quality }) {
+    const w = nearestPresetWidth(width);
+    const q = quality || 85;
+    const separator = src.includes('?') ? '&' : '?';
+    return `${src}${separator}width=${w}&quality=${q}&format=webp`;
+}

package/dist/core/index.d.ts

@@ -61,6 +61,7 @@ export { CART_COOKIE_NAME, CART_COOKIE_MAX_AGE } from './cart/cookie-config';
 export { matchesRoute, type RouteProtectionConfig } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers';
 export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
+export { storefrontImageLoader, type ImageData, type ImageLoaderParams, } from './image';
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"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"}

package/dist/core/index.js

@@ -74,6 +74,8 @@ export { matchesRoute } from './auth/routes';
 export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers';
 // Auth token client (client-side fetch helpers)
 export { createAuthTokenClient } from './auth/token-client';
+// Image utilities
+export { storefrontImageLoader, } from './image';
 // Utilities
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "types": "dist/core/index.d.ts",

package/src/core/image.ts

@@ -0,0 +1,75 @@
+/**
+ * Image utilities for DoSwiftly storefronts.
+ *
+ * Zero configuration — GraphQL API returns ready-to-use CDN URLs.
+ * The loader just appends resize query params. No keys, no env vars.
+ *
+ * @example
+ * ```typescript
+ * import { storefrontImageLoader, type ImageData } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={product.featuredImage.url} width={800} alt="..." />
+ * ```
+ */
+
+/**
+ * Image data from GraphQL API (matches Image type in storefront schema).
+ */
+export interface ImageData {
+  /** Image URL from GraphQL (ready-to-use CDN URL) */
+  url: string;
+  /** Alt text for accessibility + SEO */
+  altText?: string | null;
+  /** Original image width in pixels */
+  width?: number | null;
+  /** Original image height in pixels */
+  height?: number | null;
+  /** Image ID */
+  id?: string | null;
+}
+
+/**
+ * Next.js Image loader function signature.
+ */
+export interface ImageLoaderParams {
+  src: string;
+  width: number;
+  quality?: number;
+}
+
+/**
+ * Preset widths for CDN cache optimization.
+ * Loader quantizes requested width to the nearest preset — limits cache variants.
+ */
+const PRESET_WIDTHS = [150, 320, 640, 750, 828, 1080, 1200, 1600, 1920, 2048] as const;
+
+function nearestPresetWidth(requested: number): number {
+  for (const w of PRESET_WIDTHS) {
+    if (w >= requested) return w;
+  }
+  return PRESET_WIDTHS[PRESET_WIDTHS.length - 1];
+}
+
+/**
+ * Next.js image loader for DoSwiftly storefronts.
+ *
+ * Zero configuration — works out of the box with GraphQL image URLs.
+ * Appends resize query params (?width=&quality=&format=) to the URL
+ * that backend already returned via GraphQL.
+ *
+ * Width is quantized to preset breakpoints for optimal CDN cache.
+ * No HMAC, no env vars, no setup — like Shopify Hydrogen's image loader.
+ *
+ * @example
+ * ```tsx
+ * import { storefrontImageLoader } from '@doswiftly/storefront-sdk';
+ *
+ * <Image loader={storefrontImageLoader} src={image.url} width={800} alt="..." />
+ * ```
+ */
+export function storefrontImageLoader({ src, width, quality }: ImageLoaderParams): string {
+  const w = nearestPresetWidth(width);
+  const q = quality || 85;
+  const separator = src.includes('?') ? '&' : '?';
+  return `${src}${separator}width=${w}&quality=${q}&format=webp`;
+}

package/src/core/index.ts

@@ -166,6 +166,13 @@ export { createSetTokenHandler, createClearTokenHandler } from './auth/handlers'
 // Auth token client (client-side fetch helpers)
 export { createAuthTokenClient, type AuthTokenClient } from './auth/token-client';
 
+// Image utilities
+export {
+  storefrontImageLoader,
+  type ImageData,
+  type ImageLoaderParams,
+} from './image';
+
 // Utilities
 export { getOperationName } from './client/operation-name';
 export { hashQuery } from './client/hash';