perspectapi-ts-sdk 6.5.9 → 7.0.1

package/docs/v1-deprecated/legacy-docs/image-transforms.md

@@ -0,0 +1,523 @@
+# Image Transformations with Cloudflare Image Resizing
+
+> Deprecated v1 material. Do not copy these examples into new code. v1 sunsets
+> on 2026-06-01; use `createPerspectApiV2Client` from
+> `perspectapi-ts-sdk/v2` and `/api/v2`.
+
+The SDK provides utilities to easily transform images using Cloudflare's Image Resizing service. This allows you to resize, optimize, and transform images on-the-fly without pre-generating thumbnails.
+
+## Overview
+
+**Benefits:**
+- ✅ **No pre-generated thumbnails** - Images are resized on demand
+- ✅ **Automatic format optimization** - Serves WebP/AVIF when supported
+- ✅ **Responsive images** - Browser requests the size it needs
+- ✅ **CDN caching** - Transformed images are cached at the edge
+- ✅ **Bandwidth savings** - Only serve the size needed
+
+## Quick Start
+
+```typescript
+import { 
+  buildImageUrl, 
+  generateResponsiveUrls,
+  transformMediaItem 
+} 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
+  const urls = transformMediaItem('https://api.perspect.comm', 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
+}
+```
+
+## Core Functions
+
+### `buildImageUrl()`
+
+Build a single transformed image URL with custom options.
+
+```typescript
+import { buildImageUrl } from 'perspectapi-ts-sdk';
+
+const url = buildImageUrl(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg',
+  {
+    width: 400,
+    height: 300,
+    fit: 'cover',
+    quality: 85,
+    format: 'webp'
+  }
+);
+```
+
+**Parameters:**
+- `baseUrl` - Your API base URL (e.g., `'https://api.perspect.comm'`)
+- `mediaPath` - Path to the media file (e.g., `'media/mysite/photo.jpg'`)
+- `options` - Transform options (optional)
+
+**Transform Options:**
+
+| Option | Type | Values | Description |
+|--------|------|--------|-------------|
+| `width` | number | 1-9999 | Target width in pixels |
+| `height` | number | 1-9999 | Target height in pixels |
+| `fit` | string | `scale-down`, `contain`, `cover`, `crop`, `pad` | Resize mode |
+| `gravity` | string | `auto`, `left`, `right`, `top`, `bottom`, `center` | Crop focus point |
+| `quality` | number | 1-100 | JPEG/WebP quality (default: 85) |
+| `format` | string | `auto`, `avif`, `webp`, `jpeg`, `png` | Output format |
+| `dpr` | number | 1, 2, 3 | Device pixel ratio |
+| `sharpen` | number | 0-10 | Sharpening amount |
+| `blur` | number | 0-250 | Blur amount |
+| `rotate` | number | 0, 90, 180, 270 | Rotation degrees |
+
+### `generateResponsiveUrls()`
+
+Generate multiple sizes at once for responsive images.
+
+```typescript
+import { generateResponsiveUrls } from 'perspectapi-ts-sdk';
+
+const urls = generateResponsiveUrls(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg'
+);
+
+// Returns:
+// {
+//   thumbnail: '...?width=150&height=150&fit=cover',
+//   small: '...?width=400',
+//   medium: '...?width=800',
+//   large: '...?width=1200',
+//   original: '...'
+// }
+```
+
+### `transformMediaItem()`
+
+Convenience function for working with `MediaItem` objects from the API.
+
+```typescript
+import { transformMediaItem } from 'perspectapi-ts-sdk';
+
+// From a product
+const product = await client.products.getProduct('mysite', 123);
+const media = product.data.media?.[0];
+
+if (media) {
+  const urls = transformMediaItem('https://api.perspect.comm', media);
+  // Use urls.thumbnail, urls.small, etc.
+}
+
+// From content
+const content = await client.content.getContent('mysite', { limit: 10 });
+const firstPost = content.data?.[0];
+// Extract media from content and transform similarly
+```
+
+### `generateSrcSet()`
+
+Generate `srcset` attribute for responsive images.
+
+```typescript
+import { generateSrcSet } from 'perspectapi-ts-sdk';
+
+const srcset = generateSrcSet(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg',
+  [400, 800, 1200, 1600]
+);
+
+// Returns: "/cdn-cgi/image/width=400.../photo.jpg 400w, /cdn-cgi/image/width=800.../photo.jpg 800w, ..."
+```
+
+Use in HTML:
+
+```html
+<img
+  src="/cdn-cgi/image/width=800.../photo.jpg"
+  srcset="..."
+  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 60vw"
+  alt="Photo"
+/>
+```
+
+### `generateResponsiveImageHtml()`
+
+Generate complete responsive image HTML.
+
+```typescript
+import { generateResponsiveImageHtml } from 'perspectapi-ts-sdk';
+
+const html = generateResponsiveImageHtml(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg',
+  'My photo',
+  {
+    className: 'rounded-lg shadow-md',
+    loading: 'lazy',
+    widths: [400, 800, 1200]
+  }
+);
+
+// Returns complete <img> tag with srcset, sizes, etc.
+```
+
+## Common Use Cases
+
+### 1. Product Images (E-commerce)
+
+```typescript
+import { createPerspectApiClient, transformMediaItem } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.perspect.comm',
+  apiKey: 'your-api-key'
+});
+
+// Get products
+const products = await client.products.getProducts('mysite', {
+  limit: 20,
+  published: true
+});
+
+// Transform product images
+const productsWithImages = products.data.map(product => {
+  const media = product.media?.[0];
+  const imageUrls = media 
+    ? transformMediaItem('https://api.perspect.comm', media)
+    : null;
+  
+  return {
+    ...product,
+    imageUrls
+  };
+});
+
+// Use in your UI
+productsWithImages.forEach(product => {
+  console.log(`Thumbnail: ${product.imageUrls?.thumbnail}`);
+  console.log(`Large: ${product.imageUrls?.large}`);
+});
+```
+
+### 2. Blog Post Featured Images
+
+```typescript
+import { loadPosts, buildImageUrl } from 'perspectapi-ts-sdk';
+
+const posts = await loadPosts({
+  client,
+  siteName: 'myblog',
+  limit: 10
+});
+
+posts.forEach(post => {
+  if (post.featured_image) {
+    const featuredImage = buildImageUrl(
+      'https://api.perspect.comm',
+      post.featured_image,
+      {
+        width: 800,
+        fit: 'scale-down',
+        format: 'auto',
+        quality: 85
+      }
+    );
+    console.log(`Featured image: ${featuredImage}`);
+  }
+});
+```
+
+### 3. Responsive Image Component (React)
+
+```tsx
+import { transformMediaItem, type MediaItem } from 'perspectapi-ts-sdk';
+
+interface ResponsiveImageProps {
+  media: MediaItem;
+  alt: string;
+  className?: string;
+}
+
+export function ResponsiveImage({ media, alt, className }: ResponsiveImageProps) {
+  const urls = transformMediaItem('https://api.perspect.comm', media);
+  
+  return (
+    <img
+      src={urls.medium}
+      srcSet={`
+        ${urls.small} 400w,
+        ${urls.medium} 800w,
+        ${urls.large} 1200w
+      `}
+      sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 60vw"
+      alt={alt}
+      className={className}
+      loading="lazy"
+      decoding="async"
+    />
+  );
+}
+
+// Usage
+<ResponsiveImage 
+  media={product.media[0]} 
+  alt={product.name}
+  className="rounded-lg"
+/>
+```
+
+### 4. Custom Sizes
+
+```typescript
+import { generateResponsiveUrls, type ResponsiveImageSizes } from 'perspectapi-ts-sdk';
+
+// Define custom sizes for your use case
+const customSizes: ResponsiveImageSizes = {
+  thumbnail: {
+    width: 100,
+    height: 100,
+    fit: 'cover',
+    quality: 75,
+    format: 'auto'
+  },
+  small: {
+    width: 300,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  medium: {
+    width: 600,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  large: {
+    width: 1000,
+    fit: 'scale-down',
+    quality: 85,
+    format: 'auto'
+  },
+  original: {
+    format: 'auto'
+  }
+};
+
+const urls = generateResponsiveUrls(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg',
+  customSizes
+);
+```
+
+### 5. High DPR (Retina) Displays
+
+```typescript
+import { buildImageUrl } from 'perspectapi-ts-sdk';
+
+// For retina displays
+const retinaUrl = buildImageUrl(
+  'https://api.perspect.comm',
+  'media/mysite/photo.jpg',
+  {
+    width: 400,
+    dpr: 2, // 2x resolution
+    format: 'auto',
+    quality: 85
+  }
+);
+```
+
+## Framework Examples
+
+### Next.js App Router
+
+```tsx
+// app/products/[slug]/page.tsx
+import { createPerspectApiClient, transformMediaItem } from 'perspectapi-ts-sdk';
+import Image from 'next/image';
+
+const client = createPerspectApiClient({
+  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
+  apiKey: process.env.API_KEY!
+});
+
+export default async function ProductPage({ params }: { params: { slug: string } }) {
+  const product = await client.products.getProductBySlug('mysite', params.slug);
+  const media = product.data.media?.[0];
+  
+  if (!media) return <div>No image</div>;
+  
+  const urls = transformMediaItem(process.env.NEXT_PUBLIC_API_URL!, media);
+  
+  return (
+    <div>
+      <Image
+        src={urls.large}
+        alt={product.data.name || ''}
+        width={1200}
+        height={800}
+        className="rounded-lg"
+      />
+    </div>
+  );
+}
+```
+
+### Remix Loader
+
+```typescript
+// app/routes/products.$slug.tsx
+import { json, type LoaderFunctionArgs } from '@remix-run/node';
+import { useLoaderData } from '@remix-run/react';
+import { createPerspectApiClient, transformMediaItem } from 'perspectapi-ts-sdk';
+
+export async function loader({ params }: LoaderFunctionArgs) {
+  const client = createPerspectApiClient({
+    baseUrl: process.env.API_URL!,
+    apiKey: process.env.API_KEY!
+  });
+  
+  const product = await client.products.getProductBySlug('mysite', params.slug!);
+  const media = product.data.media?.[0];
+  
+  const imageUrls = media 
+    ? transformMediaItem(process.env.API_URL!, media)
+    : null;
+  
+  return json({ product: product.data, imageUrls });
+}
+
+export default function ProductPage() {
+  const { product, imageUrls } = useLoaderData<typeof loader>();
+  
+  return (
+    <div>
+      {imageUrls && (
+        <img
+          src={imageUrls.medium}
+          srcSet={`
+            ${imageUrls.small} 400w,
+            ${imageUrls.medium} 800w,
+            ${imageUrls.large} 1200w
+          `}
+          sizes="(max-width: 640px) 100vw, 800px"
+          alt={product.name}
+          loading="lazy"
+        />
+      )}
+    </div>
+  );
+}
+```
+
+### Cloudflare Workers
+
+```typescript
+import { createPerspectApiClient, transformMediaItem } from 'perspectapi-ts-sdk';
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const client = createPerspectApiClient({
+      baseUrl: env.API_URL,
+      apiKey: env.API_KEY
+    });
+    
+    const products = await client.products.getProducts('mysite', {
+      limit: 10,
+      published: true
+    });
+    
+    const productsWithImages = products.data.map(product => {
+      const media = product.media?.[0];
+      const imageUrls = media 
+        ? transformMediaItem(env.API_URL, media)
+        : null;
+      
+      return {
+        id: product.id,
+        name: product.name,
+        price: product.price,
+        thumbnail: imageUrls?.thumbnail,
+        image: imageUrls?.medium
+      };
+    });
+    
+    return Response.json(productsWithImages);
+  }
+};
+```
+
+## Best Practices
+
+1. **Always use `format=auto`** - Let Cloudflare choose the best format (WebP, AVIF, etc.)
+2. **Set appropriate quality** - 85 is a good default, 75 for thumbnails
+3. **Use `fit=scale-down`** - Prevents upscaling small images
+4. **Add `loading=lazy`** - Improves page load performance
+5. **Use srcset for responsive** - Let browser choose appropriate size
+6. **Cache aggressively** - Images rarely change, use long cache times
+
+## Performance Benefits
+
+### Storage Savings
+- **Before**: 5 sizes × file size = 5× storage
+- **After**: 1 original file only
+
+### Upload Time
+- **Before**: Generate all sizes on upload
+- **After**: Store original only
+
+### Flexibility
+- **Before**: Fixed sizes, must regenerate to change
+- **After**: Any size on demand
+
+### Caching
+- First request: Cloudflare resizes and caches
+- Subsequent requests: Served from edge cache (1 year TTL)
+- Global CDN: Fast delivery worldwide
+
+## Requirements
+
+- Cloudflare Image Resizing must be enabled on your zone
+- Images must be served through Cloudflare
+- Free tier: 100,000 images/month
+- Paid: $5 per 100,000 images after free tier
+
+## Troubleshooting
+
+### Images not transforming?
+
+Check that:
+- The URL includes the `/cdn-cgi/image/` prefix
+- The source image is accessible
+- Cloudflare Image Resizing is enabled on your zone
+
+### Images loading slowly?
+
+- First request is slower (resize + cache)
+- Subsequent requests are fast (served from cache)
+- Consider preloading critical images
+
+### Wrong format served?
+
+- Use `format=auto` to let Cloudflare decide
+- Browser must support the format (check Accept header)
+
+## Resources
+
+- [Cloudflare Image Resizing Docs](https://developers.cloudflare.com/images/transform-images/)
+- [Responsive Images Guide](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)
+- [WebP Format](https://developers.google.com/speed/webp)