perspectapi-ts-sdk 1.4.1 → 1.5.1

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:
@@ -189,7 +234,8 @@ const content = await client.content.getContent('your-site-name', {
   page: 1,
   limit: 20,
   page_status: 'publish',
-  page_type: 'post'
+  page_type: 'post',
+  slug_prefix: 'blog'  // Optional: filter by slug prefix
 });
 
 // Get content by ID
@@ -229,7 +275,8 @@ await client.content.unpublishContent(123);
 const products = await client.products.getProducts('my-site', {
   page: 1,
   limit: 20,
-  isActive: true
+  isActive: true,
+  slug_prefix: 'shop'  // Optional: filter by slug prefix
 });
 
 // Create new product
@@ -605,6 +652,54 @@ const client = createPerspectApiClient({
 });
 ```
 
+## Slug Prefix Filtering
+
+The SDK supports filtering content and products by `slug_prefix` to organize your content by URL structure:
+
+```typescript
+// Filter blog posts
+const blogPosts = await client.content.getContent('mysite', {
+  slug_prefix: 'blog',      // /blog/post-1, /blog/post-2
+  page_status: 'publish'
+});
+
+// Filter news articles
+const news = await client.content.getContent('mysite', {
+  slug_prefix: 'news',      // /news/article-1, /news/article-2
+  page_status: 'publish'
+});
+
+// Filter shop products
+const shopProducts = await client.products.getProducts('mysite', {
+  slug_prefix: 'shop',      // /shop/product-1, /shop/product-2
+  isActive: true
+});
+
+// Filter artwork products
+const artwork = await client.products.getProducts('mysite', {
+  slug_prefix: 'artwork',   // /artwork/painting-1, /artwork/sculpture-1
+  isActive: true
+});
+
+// Combine with other filters
+const results = await client.content.getContent('mysite', {
+  slug_prefix: 'blog',
+  page_status: 'publish',
+  page_type: 'post',
+  search: 'javascript',     // Search within blog posts only
+  page: 1,
+  limit: 20
+});
+```
+
+**Use Cases:**
+- Organize blog posts, news, and documentation separately
+- Separate shop products from artwork or digital downloads
+- Create multi-section websites with distinct URL structures
+- Filter content/products by section for navigation
+
+**See `examples/slug-prefix-examples.ts` for 20+ real-world examples!**
+
 ## TypeScript Support
 
 The SDK is written in TypeScript and provides comprehensive type definitions:

package/dist/index.d.mts

@@ -188,6 +188,7 @@ interface Content {
     contentMarkdown?: string;
     custom?: Record<string, any>;
     slug?: string;
+    slug_prefix?: string;
     pageStatus: ContentStatus;
     pageType: ContentType;
     userId?: number;
@@ -211,6 +212,7 @@ interface ContentQueryParams extends PaginationParams {
     page_type?: ContentType;
     search?: string;
     user_id?: number;
+    slug_prefix?: string;
 }
 interface Category {
     id: number;
@@ -277,6 +279,7 @@ interface ProductQueryParams extends PaginationParams {
     search?: string;
     category?: string | string[];
     category_id?: number | string | Array<number | string>;
+    slug_prefix?: string;
 }
 interface BlogPost {
     id: string | number;
@@ -1925,6 +1928,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 +2199,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

@@ -188,6 +188,7 @@ interface Content {
     contentMarkdown?: string;
     custom?: Record<string, any>;
     slug?: string;
+    slug_prefix?: string;
     pageStatus: ContentStatus;
     pageType: ContentType;
     userId?: number;
@@ -211,6 +212,7 @@ interface ContentQueryParams extends PaginationParams {
     page_type?: ContentType;
     search?: string;
     user_id?: number;
+    slug_prefix?: string;
 }
 interface Category {
     id: number;
@@ -277,6 +279,7 @@ interface ProductQueryParams extends PaginationParams {
     search?: string;
     category?: string | string[];
     category_id?: number | string | Array<number | string>;
+    slug_prefix?: string;
 }
 interface BlogPost {
     id: string | number;
@@ -1925,6 +1928,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 +2199,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);
@@ -742,7 +749,10 @@ var ProductsClient = class extends BaseClient {
         delete normalizedParams.category_id;
       }
     }
-    return this.http.get(this.buildPath(this.siteScopedEndpoint(siteName, "/products")), normalizedParams);
+    return this.http.get(
+      this.buildPath(this.siteScopedEndpoint(siteName, "/products", { includeSitesSegment: false })),
+      normalizedParams
+    );
   }
   /**
    * Get product by ID
@@ -761,7 +771,7 @@ var ProductsClient = class extends BaseClient {
    */
   async getProductBySlug(siteName, slug) {
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`)
+      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`, { includeSitesSegment: false })
     ));
   }
   /**
@@ -859,7 +869,11 @@ var ProductsClient = class extends BaseClient {
       search: params.search
     } : void 0;
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/category/${encodeURIComponent(categorySlug)}`)
+      this.siteScopedEndpoint(
+        siteName,
+        `/products/category/${encodeURIComponent(categorySlug)}`,
+        { includeSitesSegment: false }
+      )
     ), queryParams);
   }
 };
@@ -1572,6 +1586,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 +2105,7 @@ async function createCheckoutSession(options) {
   CheckoutClient,
   ContactClient,
   ContentClient,
+  DEFAULT_IMAGE_SIZES,
   HttpClient,
   NewsletterClient,
   OrganizationsClient,
@@ -1975,9 +2113,14 @@ async function createCheckoutSession(options) {
   ProductsClient,
   SitesClient,
   WebhooksClient,
+  buildImageUrl,
   createApiError,
   createCheckoutSession,
   createPerspectApiClient,
+  generateResponsiveImageHtml,
+  generateResponsiveUrls,
+  generateSizesAttribute,
+  generateSrcSet,
   loadAllContent,
   loadContentBySlug,
   loadPages,
@@ -1985,5 +2128,6 @@ async function createCheckoutSession(options) {
   loadProductBySlug,
   loadProducts,
   transformContent,
+  transformMediaItem,
   transformProduct
 });

package/dist/index.mjs

@@ -691,7 +691,10 @@ var ProductsClient = class extends BaseClient {
         delete normalizedParams.category_id;
       }
     }
-    return this.http.get(this.buildPath(this.siteScopedEndpoint(siteName, "/products")), normalizedParams);
+    return this.http.get(
+      this.buildPath(this.siteScopedEndpoint(siteName, "/products", { includeSitesSegment: false })),
+      normalizedParams
+    );
   }
   /**
    * Get product by ID
@@ -710,7 +713,7 @@ var ProductsClient = class extends BaseClient {
    */
   async getProductBySlug(siteName, slug) {
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`)
+      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`, { includeSitesSegment: false })
     ));
   }
   /**
@@ -808,7 +811,11 @@ var ProductsClient = class extends BaseClient {
       search: params.search
     } : void 0;
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/category/${encodeURIComponent(categorySlug)}`)
+      this.siteScopedEndpoint(
+        siteName,
+        `/products/category/${encodeURIComponent(categorySlug)}`,
+        { includeSitesSegment: false }
+      )
     ), queryParams);
   }
 };
@@ -1521,6 +1528,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 +2046,7 @@ export {
   CheckoutClient,
   ContactClient,
   ContentClient,
+  DEFAULT_IMAGE_SIZES,
   HttpClient,
   NewsletterClient,
   OrganizationsClient,
@@ -1923,10 +2054,15 @@ export {
   ProductsClient,
   SitesClient,
   WebhooksClient,
+  buildImageUrl,
   createApiError,
   createCheckoutSession,
   createPerspectApiClient,
   perspect_api_client_default as default,
+  generateResponsiveImageHtml,
+  generateResponsiveUrls,
+  generateSizesAttribute,
+  generateSrcSet,
   loadAllContent,
   loadContentBySlug,
   loadPages,
@@ -1934,5 +2070,6 @@ export {
   loadProductBySlug,
   loadProducts,
   transformContent,
+  transformMediaItem,
   transformProduct
 };

package/package.json

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

package/src/client/products-client.ts

@@ -50,7 +50,10 @@ export class ProductsClient extends BaseClient {
       }
     }
 
-    return this.http.get(this.buildPath(this.siteScopedEndpoint(siteName, '/products')), normalizedParams);
+    return this.http.get(
+      this.buildPath(this.siteScopedEndpoint(siteName, '/products', { includeSitesSegment: false })),
+      normalizedParams
+    );
   }
 
   /**
@@ -72,7 +75,7 @@ export class ProductsClient extends BaseClient {
    */
   async getProductBySlug(siteName: string, slug: string): Promise<ApiResponse<Product & { variants?: any[] }>> {
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`)
+      this.siteScopedEndpoint(siteName, `/products/slug/${encodeURIComponent(slug)}`, { includeSitesSegment: false })
     ));
   }
 
@@ -241,7 +244,11 @@ export class ProductsClient extends BaseClient {
     } : undefined;
 
     return this.http.get(this.buildPath(
-      this.siteScopedEndpoint(siteName, `/products/category/${encodeURIComponent(categorySlug)}`)
+      this.siteScopedEndpoint(
+        siteName,
+        `/products/category/${encodeURIComponent(categorySlug)}`,
+        { includeSitesSegment: false }
+      )
     ), queryParams);
   }
 }

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/types/index.ts

@@ -221,6 +221,7 @@ export interface Content {
   contentMarkdown?: string;
   custom?: Record<string, any>;
   slug?: string;
+  slug_prefix?: string;
   pageStatus: ContentStatus;
   pageType: ContentType;
   userId?: number;
@@ -246,6 +247,7 @@ export interface ContentQueryParams extends PaginationParams {
   page_type?: ContentType;
   search?: string;
   user_id?: number;
+  slug_prefix?: string;
 }
 
 // Categories
@@ -320,6 +322,7 @@ export interface ProductQueryParams extends PaginationParams {
   search?: string;
   category?: string | string[];
   category_id?: number | string | Array<number | string>;
+  slug_prefix?: string;
 }
 
 export interface BlogPost {

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);
+}