perspectapi-ts-sdk 1.4.0 → 1.5.0

package/README.md

@@ -84,6 +84,51 @@ const checkout = await createCheckoutSession({
 > 📚 See [docs/loaders.md](docs/loaders.md) for full walkthroughs, including fallback data, custom logging, and Stripe price resolution.
 ```
 
+## Image Transformations
+
+The SDK includes utilities for transforming images using Cloudflare's Image Resizing service:
+
+```typescript
+import { transformMediaItem, buildImageUrl } from 'perspectapi-ts-sdk';
+
+// Get a product with media
+const product = await client.products.getProduct('mysite', 123);
+const media = product.data.media?.[0];
+
+if (media) {
+  // Generate all responsive sizes automatically
+  const urls = transformMediaItem('https://api.perspect.co', media);
+  
+  console.log(urls.thumbnail);  // 150x150 cover crop
+  console.log(urls.small);      // 400px wide
+  console.log(urls.medium);     // 800px wide
+  console.log(urls.large);      // 1200px wide
+  console.log(urls.original);   // Original with auto format
+}
+
+// Or build custom transformations
+const customUrl = buildImageUrl(
+  'https://api.perspect.co',
+  'media/mysite/photo.jpg',
+  {
+    width: 400,
+    height: 300,
+    fit: 'cover',
+    format: 'webp',
+    quality: 85
+  }
+);
+```
+
+**Features:**
+- ✅ On-the-fly image resizing (no pre-generated thumbnails)
+- ✅ Automatic format optimization (WebP/AVIF)
+- ✅ Responsive image support with srcset
+- ✅ CDN caching at the edge
+- ✅ Bandwidth savings
+
+> 📚 See [docs/image-transforms.md](docs/image-transforms.md) for complete documentation, examples, and best practices.
+
 ## High-Level Data Loaders
 
 The SDK now ships with convenience loaders that wrap the lower-level REST clients. They help you:

package/dist/index.d.mts

@@ -1925,6 +1925,145 @@ declare class PerspectApiClient {
  */
 declare function createPerspectApiClient(config: PerspectApiConfig): PerspectApiClient;
 
+/**
+ * Cloudflare Image Resizing Integration
+ * Transforms images on-the-fly using Cloudflare's Image Resizing service
+ * https://developers.cloudflare.com/images/transform-images/transform-via-url/
+ */
+interface ImageTransformOptions {
+    width?: number;
+    height?: number;
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center';
+    quality?: number;
+    format?: 'auto' | 'avif' | 'webp' | 'json' | 'jpeg' | 'png';
+    sharpen?: number;
+    blur?: number;
+    rotate?: 0 | 90 | 180 | 270;
+    dpr?: number;
+    metadata?: 'keep' | 'copyright' | 'none';
+    background?: string;
+    trim?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+}
+interface ResponsiveImageSizes {
+    thumbnail: ImageTransformOptions;
+    small: ImageTransformOptions;
+    medium: ImageTransformOptions;
+    large: ImageTransformOptions;
+    original: ImageTransformOptions;
+}
+/**
+ * Default responsive image sizes
+ */
+declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
+/**
+ * Build Cloudflare Image Resizing URL
+ *
+ * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.co")
+ * @param mediaPath - The path to the media file (e.g., "media/site/image.jpg")
+ * @param options - Transform options
+ * @returns Cloudflare Image Resizing URL
+ *
+ * @example
+ * ```typescript
+ * const url = buildImageUrl(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   { width: 400, format: 'webp', quality: 85 }
+ * );
+ * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.co/media/mysite/photo.jpg'
+ * ```
+ */
+declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: ImageTransformOptions): string;
+/**
+ * Generate responsive image URLs for different sizes
+ *
+ * @example
+ * ```typescript
+ * const urls = generateResponsiveUrls(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg'
+ * );
+ * // Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }
+ * ```
+ */
+declare function generateResponsiveUrls(baseUrl: string, mediaPath: string, sizes?: ResponsiveImageSizes): Record<keyof ResponsiveImageSizes, string>;
+/**
+ * Generate srcset for responsive images
+ *
+ * @example
+ * ```typescript
+ * const srcset = generateSrcSet(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   [400, 800, 1200]
+ * );
+ * // Returns: "...?width=400 400w, ...?width=800 800w, ...?width=1200 1200w"
+ * ```
+ */
+declare function generateSrcSet(baseUrl: string, mediaPath: string, widths?: number[]): string;
+/**
+ * Generate sizes attribute for responsive images
+ *
+ * @example
+ * ```typescript
+ * const sizes = generateSizesAttribute();
+ * // Returns: "(max-width: 640px) 100vw, (max-width: 768px) 80vw, ..."
+ * ```
+ */
+declare function generateSizesAttribute(breakpoints?: Array<{
+    maxWidth: string;
+    size: string;
+}>): string;
+/**
+ * Helper to generate complete responsive image HTML
+ *
+ * @example
+ * ```typescript
+ * const html = generateResponsiveImageHtml(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   'My photo',
+ *   { className: 'rounded-lg', loading: 'lazy' }
+ * );
+ * ```
+ */
+declare function generateResponsiveImageHtml(baseUrl: string, mediaPath: string, alt: string, options?: {
+    className?: string;
+    loading?: 'lazy' | 'eager';
+    decoding?: 'async' | 'sync' | 'auto';
+    sizes?: string;
+    widths?: number[];
+}): string;
+/**
+ * Transform a MediaItem into responsive URLs
+ * Convenience function for working with MediaItem objects from the API
+ *
+ * @example
+ * ```typescript
+ * import { transformMediaItem } from 'perspectapi-ts-sdk';
+ *
+ * const product = await client.products.getProduct('mysite', 123);
+ * const media = product.data.media?.[0];
+ *
+ * if (media) {
+ *   const urls = transformMediaItem('https://api.perspect.co', media);
+ *   console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
+ * }
+ * ```
+ */
+declare function transformMediaItem(baseUrl: string, media: {
+    link: string;
+} | {
+    r2_key: string;
+    site_name: string;
+}, sizes?: ResponsiveImageSizes): Record<keyof ResponsiveImageSizes, string>;
+
 /**
  * High-level data loading helpers that wrap the PerspectAPI SDK clients.
  * These helpers provide convenient product and content loading utilities with
@@ -2057,4 +2196,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, HttpClient, type HttpMethod, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.d.ts

@@ -1925,6 +1925,145 @@ declare class PerspectApiClient {
  */
 declare function createPerspectApiClient(config: PerspectApiConfig): PerspectApiClient;
 
+/**
+ * Cloudflare Image Resizing Integration
+ * Transforms images on-the-fly using Cloudflare's Image Resizing service
+ * https://developers.cloudflare.com/images/transform-images/transform-via-url/
+ */
+interface ImageTransformOptions {
+    width?: number;
+    height?: number;
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center';
+    quality?: number;
+    format?: 'auto' | 'avif' | 'webp' | 'json' | 'jpeg' | 'png';
+    sharpen?: number;
+    blur?: number;
+    rotate?: 0 | 90 | 180 | 270;
+    dpr?: number;
+    metadata?: 'keep' | 'copyright' | 'none';
+    background?: string;
+    trim?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+}
+interface ResponsiveImageSizes {
+    thumbnail: ImageTransformOptions;
+    small: ImageTransformOptions;
+    medium: ImageTransformOptions;
+    large: ImageTransformOptions;
+    original: ImageTransformOptions;
+}
+/**
+ * Default responsive image sizes
+ */
+declare const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes;
+/**
+ * Build Cloudflare Image Resizing URL
+ *
+ * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.co")
+ * @param mediaPath - The path to the media file (e.g., "media/site/image.jpg")
+ * @param options - Transform options
+ * @returns Cloudflare Image Resizing URL
+ *
+ * @example
+ * ```typescript
+ * const url = buildImageUrl(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   { width: 400, format: 'webp', quality: 85 }
+ * );
+ * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.co/media/mysite/photo.jpg'
+ * ```
+ */
+declare function buildImageUrl(baseUrl: string, mediaPath: string, options?: ImageTransformOptions): string;
+/**
+ * Generate responsive image URLs for different sizes
+ *
+ * @example
+ * ```typescript
+ * const urls = generateResponsiveUrls(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg'
+ * );
+ * // Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }
+ * ```
+ */
+declare function generateResponsiveUrls(baseUrl: string, mediaPath: string, sizes?: ResponsiveImageSizes): Record<keyof ResponsiveImageSizes, string>;
+/**
+ * Generate srcset for responsive images
+ *
+ * @example
+ * ```typescript
+ * const srcset = generateSrcSet(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   [400, 800, 1200]
+ * );
+ * // Returns: "...?width=400 400w, ...?width=800 800w, ...?width=1200 1200w"
+ * ```
+ */
+declare function generateSrcSet(baseUrl: string, mediaPath: string, widths?: number[]): string;
+/**
+ * Generate sizes attribute for responsive images
+ *
+ * @example
+ * ```typescript
+ * const sizes = generateSizesAttribute();
+ * // Returns: "(max-width: 640px) 100vw, (max-width: 768px) 80vw, ..."
+ * ```
+ */
+declare function generateSizesAttribute(breakpoints?: Array<{
+    maxWidth: string;
+    size: string;
+}>): string;
+/**
+ * Helper to generate complete responsive image HTML
+ *
+ * @example
+ * ```typescript
+ * const html = generateResponsiveImageHtml(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   'My photo',
+ *   { className: 'rounded-lg', loading: 'lazy' }
+ * );
+ * ```
+ */
+declare function generateResponsiveImageHtml(baseUrl: string, mediaPath: string, alt: string, options?: {
+    className?: string;
+    loading?: 'lazy' | 'eager';
+    decoding?: 'async' | 'sync' | 'auto';
+    sizes?: string;
+    widths?: number[];
+}): string;
+/**
+ * Transform a MediaItem into responsive URLs
+ * Convenience function for working with MediaItem objects from the API
+ *
+ * @example
+ * ```typescript
+ * import { transformMediaItem } from 'perspectapi-ts-sdk';
+ *
+ * const product = await client.products.getProduct('mysite', 123);
+ * const media = product.data.media?.[0];
+ *
+ * if (media) {
+ *   const urls = transformMediaItem('https://api.perspect.co', media);
+ *   console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
+ * }
+ * ```
+ */
+declare function transformMediaItem(baseUrl: string, media: {
+    link: string;
+} | {
+    r2_key: string;
+    site_name: string;
+}, sizes?: ResponsiveImageSizes): Record<keyof ResponsiveImageSizes, string>;
+
 /**
  * High-level data loading helpers that wrap the PerspectAPI SDK clients.
  * These helpers provide convenient product and content loading utilities with
@@ -2057,4 +2196,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, HttpClient, type HttpMethod, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CheckoutClient: () => CheckoutClient,
   ContactClient: () => ContactClient,
   ContentClient: () => ContentClient,
+  DEFAULT_IMAGE_SIZES: () => DEFAULT_IMAGE_SIZES,
   HttpClient: () => HttpClient,
   NewsletterClient: () => NewsletterClient,
   OrganizationsClient: () => OrganizationsClient,
@@ -34,10 +35,15 @@ __export(index_exports, {
   ProductsClient: () => ProductsClient,
   SitesClient: () => SitesClient,
   WebhooksClient: () => WebhooksClient,
+  buildImageUrl: () => buildImageUrl,
   createApiError: () => createApiError,
   createCheckoutSession: () => createCheckoutSession,
   createPerspectApiClient: () => createPerspectApiClient,
   default: () => perspect_api_client_default,
+  generateResponsiveImageHtml: () => generateResponsiveImageHtml,
+  generateResponsiveUrls: () => generateResponsiveUrls,
+  generateSizesAttribute: () => generateSizesAttribute,
+  generateSrcSet: () => generateSrcSet,
   loadAllContent: () => loadAllContent,
   loadContentBySlug: () => loadContentBySlug,
   loadPages: () => loadPages,
@@ -45,6 +51,7 @@ __export(index_exports, {
   loadProductBySlug: () => loadProductBySlug,
   loadProducts: () => loadProducts,
   transformContent: () => transformContent,
+  transformMediaItem: () => transformMediaItem,
   transformProduct: () => transformProduct
 });
 module.exports = __toCommonJS(index_exports);
@@ -1572,6 +1579,129 @@ function createPerspectApiClient(config) {
 }
 var perspect_api_client_default = PerspectApiClient;
 
+// src/utils/image-transform.ts
+var DEFAULT_IMAGE_SIZES = {
+  thumbnail: {
+    width: 150,
+    height: 150,
+    fit: "cover",
+    quality: 85,
+    format: "auto"
+  },
+  small: {
+    width: 400,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  medium: {
+    width: 800,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  large: {
+    width: 1200,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  original: {
+    format: "auto"
+  }
+};
+function buildImageUrl(baseUrl, mediaPath, options) {
+  const sourceUrl = `${baseUrl}/${mediaPath.replace(/^\//, "")}`;
+  if (!options || Object.keys(options).length === 0) {
+    return sourceUrl;
+  }
+  const params = [];
+  if (options.width) params.push(`width=${options.width}`);
+  if (options.height) params.push(`height=${options.height}`);
+  if (options.fit) params.push(`fit=${options.fit}`);
+  if (options.gravity) params.push(`gravity=${options.gravity}`);
+  if (options.quality) params.push(`quality=${options.quality}`);
+  if (options.format) params.push(`format=${options.format}`);
+  if (options.sharpen) params.push(`sharpen=${options.sharpen}`);
+  if (options.blur) params.push(`blur=${options.blur}`);
+  if (options.rotate) params.push(`rotate=${options.rotate}`);
+  if (options.dpr) params.push(`dpr=${options.dpr}`);
+  if (options.metadata) params.push(`metadata=${options.metadata}`);
+  if (options.background) params.push(`background=${options.background}`);
+  if (options.trim) {
+    const trimParts = [];
+    if (options.trim.top) trimParts.push(`${options.trim.top}`);
+    if (options.trim.right) trimParts.push(`${options.trim.right}`);
+    if (options.trim.bottom) trimParts.push(`${options.trim.bottom}`);
+    if (options.trim.left) trimParts.push(`${options.trim.left}`);
+    if (trimParts.length > 0) {
+      params.push(`trim=${trimParts.join(";")}`);
+    }
+  }
+  const queryString = params.join(",");
+  return `/cdn-cgi/image/${queryString}/${sourceUrl}`;
+}
+function generateResponsiveUrls(baseUrl, mediaPath, sizes = DEFAULT_IMAGE_SIZES) {
+  return {
+    thumbnail: buildImageUrl(baseUrl, mediaPath, sizes.thumbnail),
+    small: buildImageUrl(baseUrl, mediaPath, sizes.small),
+    medium: buildImageUrl(baseUrl, mediaPath, sizes.medium),
+    large: buildImageUrl(baseUrl, mediaPath, sizes.large),
+    original: buildImageUrl(baseUrl, mediaPath, sizes.original)
+  };
+}
+function generateSrcSet(baseUrl, mediaPath, widths = [400, 800, 1200, 1600]) {
+  return widths.map((width) => {
+    const url = buildImageUrl(baseUrl, mediaPath, {
+      width,
+      fit: "scale-down",
+      quality: 85,
+      format: "auto"
+    });
+    return `${url} ${width}w`;
+  }).join(", ");
+}
+function generateSizesAttribute(breakpoints = [
+  { maxWidth: "640px", size: "100vw" },
+  { maxWidth: "768px", size: "80vw" },
+  { maxWidth: "1024px", size: "60vw" },
+  { maxWidth: "1280px", size: "50vw" }
+]) {
+  const mediaQueries = breakpoints.map(
+    (bp) => `(max-width: ${bp.maxWidth}) ${bp.size}`
+  );
+  mediaQueries.push("40vw");
+  return mediaQueries.join(", ");
+}
+function generateResponsiveImageHtml(baseUrl, mediaPath, alt, options) {
+  const srcset = generateSrcSet(baseUrl, mediaPath, options?.widths);
+  const sizes = options?.sizes || generateSizesAttribute();
+  const src = buildImageUrl(baseUrl, mediaPath, {
+    width: 800,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  });
+  return `<img
+    src="${src}"
+    srcset="${srcset}"
+    sizes="${sizes}"
+    alt="${alt}"
+    ${options?.className ? `class="${options.className}"` : ""}
+    ${options?.loading ? `loading="${options.loading}"` : 'loading="lazy"'}
+    ${options?.decoding ? `decoding="${options.decoding}"` : 'decoding="async"'}
+  />`;
+}
+function transformMediaItem(baseUrl, media, sizes) {
+  let mediaPath;
+  if ("link" in media) {
+    mediaPath = media.link.replace(/^https?:\/\/[^/]+\//, "");
+  } else {
+    mediaPath = `media/${media.site_name}/${media.r2_key.split("/").pop()}`;
+  }
+  return generateResponsiveUrls(baseUrl, mediaPath, sizes);
+}
+
 // src/loaders.ts
 var noopLogger = {};
 var log = (logger, level, ...args) => {
@@ -1968,6 +2098,7 @@ async function createCheckoutSession(options) {
   CheckoutClient,
   ContactClient,
   ContentClient,
+  DEFAULT_IMAGE_SIZES,
   HttpClient,
   NewsletterClient,
   OrganizationsClient,
@@ -1975,9 +2106,14 @@ async function createCheckoutSession(options) {
   ProductsClient,
   SitesClient,
   WebhooksClient,
+  buildImageUrl,
   createApiError,
   createCheckoutSession,
   createPerspectApiClient,
+  generateResponsiveImageHtml,
+  generateResponsiveUrls,
+  generateSizesAttribute,
+  generateSrcSet,
   loadAllContent,
   loadContentBySlug,
   loadPages,
@@ -1985,5 +2121,6 @@ async function createCheckoutSession(options) {
   loadProductBySlug,
   loadProducts,
   transformContent,
+  transformMediaItem,
   transformProduct
 });

package/dist/index.mjs

@@ -1521,6 +1521,129 @@ function createPerspectApiClient(config) {
 }
 var perspect_api_client_default = PerspectApiClient;
 
+// src/utils/image-transform.ts
+var DEFAULT_IMAGE_SIZES = {
+  thumbnail: {
+    width: 150,
+    height: 150,
+    fit: "cover",
+    quality: 85,
+    format: "auto"
+  },
+  small: {
+    width: 400,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  medium: {
+    width: 800,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  large: {
+    width: 1200,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  },
+  original: {
+    format: "auto"
+  }
+};
+function buildImageUrl(baseUrl, mediaPath, options) {
+  const sourceUrl = `${baseUrl}/${mediaPath.replace(/^\//, "")}`;
+  if (!options || Object.keys(options).length === 0) {
+    return sourceUrl;
+  }
+  const params = [];
+  if (options.width) params.push(`width=${options.width}`);
+  if (options.height) params.push(`height=${options.height}`);
+  if (options.fit) params.push(`fit=${options.fit}`);
+  if (options.gravity) params.push(`gravity=${options.gravity}`);
+  if (options.quality) params.push(`quality=${options.quality}`);
+  if (options.format) params.push(`format=${options.format}`);
+  if (options.sharpen) params.push(`sharpen=${options.sharpen}`);
+  if (options.blur) params.push(`blur=${options.blur}`);
+  if (options.rotate) params.push(`rotate=${options.rotate}`);
+  if (options.dpr) params.push(`dpr=${options.dpr}`);
+  if (options.metadata) params.push(`metadata=${options.metadata}`);
+  if (options.background) params.push(`background=${options.background}`);
+  if (options.trim) {
+    const trimParts = [];
+    if (options.trim.top) trimParts.push(`${options.trim.top}`);
+    if (options.trim.right) trimParts.push(`${options.trim.right}`);
+    if (options.trim.bottom) trimParts.push(`${options.trim.bottom}`);
+    if (options.trim.left) trimParts.push(`${options.trim.left}`);
+    if (trimParts.length > 0) {
+      params.push(`trim=${trimParts.join(";")}`);
+    }
+  }
+  const queryString = params.join(",");
+  return `/cdn-cgi/image/${queryString}/${sourceUrl}`;
+}
+function generateResponsiveUrls(baseUrl, mediaPath, sizes = DEFAULT_IMAGE_SIZES) {
+  return {
+    thumbnail: buildImageUrl(baseUrl, mediaPath, sizes.thumbnail),
+    small: buildImageUrl(baseUrl, mediaPath, sizes.small),
+    medium: buildImageUrl(baseUrl, mediaPath, sizes.medium),
+    large: buildImageUrl(baseUrl, mediaPath, sizes.large),
+    original: buildImageUrl(baseUrl, mediaPath, sizes.original)
+  };
+}
+function generateSrcSet(baseUrl, mediaPath, widths = [400, 800, 1200, 1600]) {
+  return widths.map((width) => {
+    const url = buildImageUrl(baseUrl, mediaPath, {
+      width,
+      fit: "scale-down",
+      quality: 85,
+      format: "auto"
+    });
+    return `${url} ${width}w`;
+  }).join(", ");
+}
+function generateSizesAttribute(breakpoints = [
+  { maxWidth: "640px", size: "100vw" },
+  { maxWidth: "768px", size: "80vw" },
+  { maxWidth: "1024px", size: "60vw" },
+  { maxWidth: "1280px", size: "50vw" }
+]) {
+  const mediaQueries = breakpoints.map(
+    (bp) => `(max-width: ${bp.maxWidth}) ${bp.size}`
+  );
+  mediaQueries.push("40vw");
+  return mediaQueries.join(", ");
+}
+function generateResponsiveImageHtml(baseUrl, mediaPath, alt, options) {
+  const srcset = generateSrcSet(baseUrl, mediaPath, options?.widths);
+  const sizes = options?.sizes || generateSizesAttribute();
+  const src = buildImageUrl(baseUrl, mediaPath, {
+    width: 800,
+    fit: "scale-down",
+    quality: 85,
+    format: "auto"
+  });
+  return `<img
+    src="${src}"
+    srcset="${srcset}"
+    sizes="${sizes}"
+    alt="${alt}"
+    ${options?.className ? `class="${options.className}"` : ""}
+    ${options?.loading ? `loading="${options.loading}"` : 'loading="lazy"'}
+    ${options?.decoding ? `decoding="${options.decoding}"` : 'decoding="async"'}
+  />`;
+}
+function transformMediaItem(baseUrl, media, sizes) {
+  let mediaPath;
+  if ("link" in media) {
+    mediaPath = media.link.replace(/^https?:\/\/[^/]+\//, "");
+  } else {
+    mediaPath = `media/${media.site_name}/${media.r2_key.split("/").pop()}`;
+  }
+  return generateResponsiveUrls(baseUrl, mediaPath, sizes);
+}
+
 // src/loaders.ts
 var noopLogger = {};
 var log = (logger, level, ...args) => {
@@ -1916,6 +2039,7 @@ export {
   CheckoutClient,
   ContactClient,
   ContentClient,
+  DEFAULT_IMAGE_SIZES,
   HttpClient,
   NewsletterClient,
   OrganizationsClient,
@@ -1923,10 +2047,15 @@ export {
   ProductsClient,
   SitesClient,
   WebhooksClient,
+  buildImageUrl,
   createApiError,
   createCheckoutSession,
   createPerspectApiClient,
   perspect_api_client_default as default,
+  generateResponsiveImageHtml,
+  generateResponsiveUrls,
+  generateSizesAttribute,
+  generateSrcSet,
   loadAllContent,
   loadContentBySlug,
   loadPages,
@@ -1934,5 +2063,6 @@ export {
   loadProductBySlug,
   loadProducts,
   transformContent,
+  transformMediaItem,
   transformProduct
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/index.ts

@@ -26,6 +26,22 @@ export { BaseClient } from './client/base-client';
 // Utilities
 export { HttpClient, createApiError } from './utils/http-client';
 
+// Image transformation utilities
+export {
+  buildImageUrl,
+  generateResponsiveUrls,
+  generateSrcSet,
+  generateSizesAttribute,
+  generateResponsiveImageHtml,
+  transformMediaItem,
+  DEFAULT_IMAGE_SIZES
+} from './utils/image-transform';
+
+export type {
+  ImageTransformOptions,
+  ResponsiveImageSizes
+} from './utils/image-transform';
+
 // High-level data loaders
 export {
   loadProducts,

package/src/utils/image-transform.ts

@@ -0,0 +1,296 @@
+/**
+ * Cloudflare Image Resizing Integration
+ * Transforms images on-the-fly using Cloudflare's Image Resizing service
+ * https://developers.cloudflare.com/images/transform-images/transform-via-url/
+ */
+
+export interface ImageTransformOptions {
+  width?: number;
+  height?: number;
+  fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+  gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center';
+  quality?: number; // 1-100
+  format?: 'auto' | 'avif' | 'webp' | 'json' | 'jpeg' | 'png';
+  sharpen?: number; // 0-10
+  blur?: number; // 0-250
+  rotate?: 0 | 90 | 180 | 270;
+  dpr?: number; // Device Pixel Ratio: 1, 2, or 3
+  metadata?: 'keep' | 'copyright' | 'none';
+  background?: string; // hex color for padding
+  trim?: {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+  };
+}
+
+export interface ResponsiveImageSizes {
+  thumbnail: ImageTransformOptions;
+  small: ImageTransformOptions;
+  medium: ImageTransformOptions;
+  large: ImageTransformOptions;
+  original: ImageTransformOptions;
+}
+
+/**
+ * Default responsive image sizes
+ */
+export const DEFAULT_IMAGE_SIZES: ResponsiveImageSizes = {
+  thumbnail: {
+    width: 150,
+    height: 150,
+    fit: 'cover',
+    quality: 85,
+    format: 'auto'
+  },
+  small: {
+    width: 400,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  medium: {
+    width: 800,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  large: {
+    width: 1200,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  original: {
+    format: 'auto'
+  }
+};
+
+/**
+ * Build Cloudflare Image Resizing URL
+ *
+ * @param baseUrl - The base URL of your API (e.g., "https://api.perspect.co")
+ * @param mediaPath - The path to the media file (e.g., "media/site/image.jpg")
+ * @param options - Transform options
+ * @returns Cloudflare Image Resizing URL
+ *
+ * @example
+ * ```typescript
+ * const url = buildImageUrl(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   { width: 400, format: 'webp', quality: 85 }
+ * );
+ * // Returns: '/cdn-cgi/image/width=400,format=webp,quality=85/https://api.perspect.co/media/mysite/photo.jpg'
+ * ```
+ */
+export function buildImageUrl(
+  baseUrl: string,
+  mediaPath: string,
+  options?: ImageTransformOptions
+): string {
+  // Construct the full source URL
+  const sourceUrl = `${baseUrl}/${mediaPath.replace(/^\//, '')}`;
+
+  if (!options || Object.keys(options).length === 0) {
+    // Return original image URL
+    return sourceUrl;
+  }
+
+  // Build transform options string
+  const params: string[] = [];
+
+  if (options.width) params.push(`width=${options.width}`);
+  if (options.height) params.push(`height=${options.height}`);
+  if (options.fit) params.push(`fit=${options.fit}`);
+  if (options.gravity) params.push(`gravity=${options.gravity}`);
+  if (options.quality) params.push(`quality=${options.quality}`);
+  if (options.format) params.push(`format=${options.format}`);
+  if (options.sharpen) params.push(`sharpen=${options.sharpen}`);
+  if (options.blur) params.push(`blur=${options.blur}`);
+  if (options.rotate) params.push(`rotate=${options.rotate}`);
+  if (options.dpr) params.push(`dpr=${options.dpr}`);
+  if (options.metadata) params.push(`metadata=${options.metadata}`);
+  if (options.background) params.push(`background=${options.background}`);
+
+  if (options.trim) {
+    const trimParts: string[] = [];
+    if (options.trim.top) trimParts.push(`${options.trim.top}`);
+    if (options.trim.right) trimParts.push(`${options.trim.right}`);
+    if (options.trim.bottom) trimParts.push(`${options.trim.bottom}`);
+    if (options.trim.left) trimParts.push(`${options.trim.left}`);
+    if (trimParts.length > 0) {
+      params.push(`trim=${trimParts.join(';')}`);
+    }
+  }
+
+  const queryString = params.join(',');
+
+  // Cloudflare Image Resizing URL format:
+  // /cdn-cgi/image/{options}/{source-image-url}
+  // Note: This only works on Cloudflare zones with Image Resizing enabled
+  return `/cdn-cgi/image/${queryString}/${sourceUrl}`;
+}
+
+/**
+ * Generate responsive image URLs for different sizes
+ *
+ * @example
+ * ```typescript
+ * const urls = generateResponsiveUrls(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg'
+ * );
+ * // Returns: { thumbnail: '...', small: '...', medium: '...', large: '...', original: '...' }
+ * ```
+ */
+export function generateResponsiveUrls(
+  baseUrl: string,
+  mediaPath: string,
+  sizes: ResponsiveImageSizes = DEFAULT_IMAGE_SIZES
+): Record<keyof ResponsiveImageSizes, string> {
+  return {
+    thumbnail: buildImageUrl(baseUrl, mediaPath, sizes.thumbnail),
+    small: buildImageUrl(baseUrl, mediaPath, sizes.small),
+    medium: buildImageUrl(baseUrl, mediaPath, sizes.medium),
+    large: buildImageUrl(baseUrl, mediaPath, sizes.large),
+    original: buildImageUrl(baseUrl, mediaPath, sizes.original)
+  };
+}
+
+/**
+ * Generate srcset for responsive images
+ *
+ * @example
+ * ```typescript
+ * const srcset = generateSrcSet(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   [400, 800, 1200]
+ * );
+ * // Returns: "...?width=400 400w, ...?width=800 800w, ...?width=1200 1200w"
+ * ```
+ */
+export function generateSrcSet(
+  baseUrl: string,
+  mediaPath: string,
+  widths: number[] = [400, 800, 1200, 1600]
+): string {
+  return widths
+    .map((width) => {
+      const url = buildImageUrl(baseUrl, mediaPath, {
+        width,
+        fit: 'scale-down',
+        quality: 85,
+        format: 'auto'
+      });
+      return `${url} ${width}w`;
+    })
+    .join(', ');
+}
+
+/**
+ * Generate sizes attribute for responsive images
+ *
+ * @example
+ * ```typescript
+ * const sizes = generateSizesAttribute();
+ * // Returns: "(max-width: 640px) 100vw, (max-width: 768px) 80vw, ..."
+ * ```
+ */
+export function generateSizesAttribute(
+  breakpoints: Array<{ maxWidth: string; size: string }> = [
+    { maxWidth: '640px', size: '100vw' },
+    { maxWidth: '768px', size: '80vw' },
+    { maxWidth: '1024px', size: '60vw' },
+    { maxWidth: '1280px', size: '50vw' }
+  ]
+): string {
+  const mediaQueries = breakpoints.map(
+    (bp) => `(max-width: ${bp.maxWidth}) ${bp.size}`
+  );
+  mediaQueries.push('40vw'); // default size
+  return mediaQueries.join(', ');
+}
+
+/**
+ * Helper to generate complete responsive image HTML
+ *
+ * @example
+ * ```typescript
+ * const html = generateResponsiveImageHtml(
+ *   'https://api.perspect.co',
+ *   'media/mysite/photo.jpg',
+ *   'My photo',
+ *   { className: 'rounded-lg', loading: 'lazy' }
+ * );
+ * ```
+ */
+export function generateResponsiveImageHtml(
+  baseUrl: string,
+  mediaPath: string,
+  alt: string,
+  options?: {
+    className?: string;
+    loading?: 'lazy' | 'eager';
+    decoding?: 'async' | 'sync' | 'auto';
+    sizes?: string;
+    widths?: number[];
+  }
+): string {
+  const srcset = generateSrcSet(baseUrl, mediaPath, options?.widths);
+  const sizes = options?.sizes || generateSizesAttribute();
+  const src = buildImageUrl(baseUrl, mediaPath, {
+    width: 800,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  });
+
+  return `<img
+    src="${src}"
+    srcset="${srcset}"
+    sizes="${sizes}"
+    alt="${alt}"
+    ${options?.className ? `class="${options.className}"` : ''}
+    ${options?.loading ? `loading="${options.loading}"` : 'loading="lazy"'}
+    ${options?.decoding ? `decoding="${options.decoding}"` : 'decoding="async"'}
+  />`;
+}
+
+/**
+ * Transform a MediaItem into responsive URLs
+ * Convenience function for working with MediaItem objects from the API
+ *
+ * @example
+ * ```typescript
+ * import { transformMediaItem } from 'perspectapi-ts-sdk';
+ * 
+ * const product = await client.products.getProduct('mysite', 123);
+ * const media = product.data.media?.[0];
+ * 
+ * if (media) {
+ *   const urls = transformMediaItem('https://api.perspect.co', media);
+ *   console.log(urls.thumbnail); // Cloudflare-transformed thumbnail URL
+ * }
+ * ```
+ */
+export function transformMediaItem(
+  baseUrl: string,
+  media: { link: string } | { r2_key: string; site_name: string },
+  sizes?: ResponsiveImageSizes
+): Record<keyof ResponsiveImageSizes, string> {
+  // Determine the media path
+  let mediaPath: string;
+  
+  if ('link' in media) {
+    // Extract path from full URL
+    mediaPath = media.link.replace(/^https?:\/\/[^/]+\//, '');
+  } else {
+    // Construct from r2_key
+    mediaPath = `media/${media.site_name}/${media.r2_key.split('/').pop()}`;
+  }
+
+  return generateResponsiveUrls(baseUrl, mediaPath, sizes);
+}