perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/legacy-notes/CHANGELOG-CHECKOUT.md

@@ -0,0 +1,143 @@
+# Checkout Client Updates - Breaking Changes
+
+## Summary
+Updated `CheckoutClient.createCheckoutSession()` to use the correct PerspectAPI route pattern with site name parameter.
+
+## Breaking Changes
+
+### Method Signature Change
+
+**Before:**
+```typescript
+async createCheckoutSession(data: CreateCheckoutSessionRequest): Promise<ApiResponse<CheckoutSession>>
+```
+
+**After:**
+```typescript
+async createCheckoutSession(siteName: string, data: CreateCheckoutSessionRequest): Promise<ApiResponse<CheckoutSession>>
+```
+
+### Route Change
+
+**Before:**
+```
+POST /api/v1/checkout/create-session
+```
+
+**After:**
+```
+POST /api/v1/{siteName}/checkout/create-session
+```
+
+This matches the pattern used by other site-specific endpoints like:
+- `/api/v1/{siteName}/products`
+- `/api/v1/{siteName}/content`
+
+## Updated Type Definition
+
+The `CreateCheckoutSessionRequest` interface now supports both single-item and multi-item checkouts:
+
+```typescript
+export interface CreateCheckoutSessionRequest {
+  // Single item checkout (legacy/simple)
+  priceId?: string;
+  quantity?: number;
+  
+  // Multiple items checkout (recommended)
+  line_items?: Array<{
+    price: string;
+    quantity: number;
+  }>;
+  
+  // Common fields
+  success_url?: string;
+  cancel_url?: string;
+  successUrl?: string;  // Alternative naming
+  cancelUrl?: string;   // Alternative naming
+  customer_email?: string;
+  customerEmail?: string;  // Alternative naming
+  metadata?: Record<string, string>;
+  mode?: 'payment' | 'subscription' | 'setup';
+  automatic_tax?: {
+    enabled: boolean;
+  };
+  shipping_address_collection?: {
+    allowed_countries: string[];
+  };
+  billing_address_collection?: 'auto' | 'required';
+}
+```
+
+## Migration Guide
+
+### Old Usage (❌ Deprecated)
+
+```typescript
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.perspect.co',
+  apiKey: 'your-api-key'
+});
+
+// This will no longer work
+const session = await client.checkout.createCheckoutSession({
+  priceId: 'price_xxxxx',
+  successUrl: 'https://example.com/success',
+  cancelUrl: 'https://example.com/cancel'
+});
+```
+
+### New Usage (✅ Required)
+
+```typescript
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.perspect.co',
+  apiKey: 'your-api-key'
+});
+
+// Single item checkout
+const session = await client.checkout.createCheckoutSession('museum-indian-art', {
+  line_items: [{
+    price: 'price_xxxxx',
+    quantity: 1
+  }],
+  success_url: 'https://example.com/success',
+  cancel_url: 'https://example.com/cancel'
+});
+
+// Multiple items checkout
+const session = await client.checkout.createCheckoutSession('museum-indian-art', {
+  line_items: [
+    { price: 'price_xxxxx', quantity: 2 },
+    { price: 'price_yyyyy', quantity: 1 }
+  ],
+  success_url: 'https://example.com/success',
+  cancel_url: 'https://example.com/cancel',
+  customer_email: 'customer@example.com',
+  mode: 'payment',
+  automatic_tax: { enabled: true },
+  shipping_address_collection: {
+    allowed_countries: ['US', 'CA']
+  },
+  billing_address_collection: 'required'
+});
+```
+
+## Benefits
+
+1. **Consistency** - Matches the pattern used by all other site-specific endpoints
+2. **Multi-tenancy** - Properly isolates checkout sessions by site
+3. **Flexibility** - Supports both single and multiple line items
+4. **Full Stripe Support** - Exposes all Stripe checkout session configuration options
+
+## Compatibility
+
+- **Version**: 1.1.0+
+- **PerspectAPI Backend**: Requires backend version that supports `/api/v1/{siteName}/checkout/create-session` route
+- **Node.js**: 16.x or higher
+- **TypeScript**: 4.5 or higher
+
+## Related Changes
+
+- Updated `CreateCheckoutSessionRequest` interface to support multiple line items
+- Added support for snake_case and camelCase field naming for flexibility
+- Enhanced JSDoc documentation with parameter descriptions

package/docs/v1-deprecated/legacy-notes/CSRF-CHECKOUT.md

@@ -0,0 +1,271 @@
+# CSRF-Protected Checkout Implementation
+
+## Overview
+
+The PerspectAPI SDK now includes automatic CSRF token handling for secure checkout operations. This follows the double-submit CSRF token pattern required by PerspectAPI.
+
+## SDK Updates
+
+### 1. CheckoutClient Enhancements
+
+**New Method: `getCsrfToken(siteName)`**
+```typescript
+// Get CSRF token for a specific site
+const csrfResponse = await client.checkout.getCsrfToken('museum-indian-art');
+// Returns: { csrf_token: "...", site_id: "...", site_name: "..." }
+```
+
+**Enhanced: `createCheckoutSession(siteName, data, csrfToken?)`**
+```typescript
+// Automatic CSRF handling (recommended)
+const session = await client.checkout.createCheckoutSession(
+  'museum-indian-art',
+  {
+    line_items: [
+      {
+        price: 'price_xxx',  // Existing Stripe price ID
+        quantity: 1
+      }
+    ],
+    success_url: 'https://yoursite.com/success',
+    cancel_url: 'https://yoursite.com/cancel'
+  }
+);
+
+// Manual CSRF token (advanced)
+const csrfToken = await client.checkout.getCsrfToken('museum-indian-art');
+const session = await client.checkout.createCheckoutSession(
+  'museum-indian-art',
+  data,
+  csrfToken.data.csrf_token
+);
+```
+
+### 2. Main Client CSRF Methods
+
+**Site-Specific Token (Recommended for Development)**
+```typescript
+// Works from localhost, no Host header needed
+const token = await client.getCsrfToken('museum-indian-art');
+```
+
+**Host-Based Token (Production)**
+```typescript
+// Requires correct Host header
+const token = await client.getCsrfToken();
+```
+
+### 3. Enhanced Type Definitions
+
+**Line Items Support:**
+```typescript
+interface CreateCheckoutSessionRequest {
+  line_items?: Array<{
+    // Option 1: Use existing Stripe price ID
+    price?: string;
+    quantity: number;
+    
+    // Option 2: Define price inline
+    price_data?: {
+      currency: string;
+      product_data: {
+        name: string;
+        description?: string;
+        images?: string[];
+      };
+      unit_amount: number;  // Amount in cents
+    };
+  }>;
+  
+  // Required fields
+  success_url: string;
+  cancel_url: string;
+  
+  // Optional fields
+  customer_email?: string;
+  metadata?: Record<string, string>;
+  mode?: 'payment' | 'subscription' | 'setup';
+  automatic_tax?: { enabled: boolean };
+  shipping_address_collection?: { allowed_countries: string[] };
+  billing_address_collection?: 'auto' | 'required';
+}
+```
+
+## API Endpoints
+
+### 1. Get CSRF Token
+
+**Site-Specific (Development-Friendly)**
+```bash
+GET /api/v1/csrf/token/{siteName}
+
+# Example
+curl -X GET "https://api.perspect.co/api/v1/csrf/token/museum-indian-art" \
+  -H "X-API-Key: your_api_key"
+
+# Response
+{
+  "csrf_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "site_id": "site_xxx",
+  "site_name": "museum-indian-art"
+}
+```
+
+**Host-Based (Production)**
+```bash
+GET /api/v1/csrf/token
+
+curl -X GET "https://api.perspect.co/api/v1/csrf/token" \
+  -H "X-API-Key: your_api_key" \
+  -H "Host: indianart.perspect.com"
+```
+
+### 2. Create Checkout Session
+
+```bash
+POST /api/v1/{siteName}/checkout/create-session
+
+curl -X POST "https://api.perspect.co/api/v1/museum-indian-art/checkout/create-session" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your_api_key" \
+  -H "X-CSRF-Token: csrf_token_from_step_1" \
+  -d '{
+    "line_items": [
+      {
+        "price": "price_xxx",
+        "quantity": 1
+      }
+    ],
+    "success_url": "https://yoursite.com/success",
+    "cancel_url": "https://yoursite.com/cancel"
+  }'
+
+# Response
+{
+  "id": "cs_test_...",
+  "url": "https://checkout.stripe.com/pay/cs_test_..."
+}
+```
+
+## How It Works
+
+### Automatic CSRF Flow (SDK)
+
+1. **Client calls** `createCheckoutSession(siteName, data)`
+2. **SDK checks** if CSRF token provided
+3. **If not**, SDK calls `GET /api/v1/csrf/token/{siteName}`
+4. **SDK extracts** `csrf_token` from response
+5. **SDK makes** checkout request with `X-CSRF-Token` header
+6. **API validates** CSRF token and creates session
+7. **SDK returns** checkout session with ID and URL
+
+### Manual CSRF Flow (Direct API)
+
+1. **Client calls** `GET /api/v1/csrf/token/{siteName}`
+2. **API returns** CSRF token
+3. **Client calls** `POST /api/v1/{siteName}/checkout/create-session` with `X-CSRF-Token` header
+4. **API validates** token and creates session
+5. **API returns** checkout session
+
+## Benefits
+
+### Security
+- ✅ Double-submit CSRF protection
+- ✅ Site-specific token signing
+- ✅ JWT-based tokens with expiration
+- ✅ Prevents cross-site request forgery attacks
+
+### Developer Experience
+- ✅ Automatic token handling in SDK
+- ✅ Works from localhost without configuration
+- ✅ No Host header manipulation needed
+- ✅ Explicit site specification
+
+### Portability
+- ✅ Works across all environments (Cloudflare Workers, Node.js, etc.)
+- ✅ No vendor lock-in
+- ✅ Standard HTTP headers
+- ✅ Compatible with any HTTP client
+
+## Migration Guide
+
+### Before (Direct Fetch)
+```typescript
+const response = await fetch(`${baseUrl}/api/v1/${siteName}/checkout/create-session`, {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-API-Key': apiKey
+  },
+  body: JSON.stringify(data)
+});
+// ❌ Missing CSRF token - will fail with 401
+```
+
+### After (SDK with Auto CSRF)
+```typescript
+const response = await client.checkout.createCheckoutSession(siteName, data);
+// ✅ CSRF token automatically handled
+```
+
+## Example: Remix Integration
+
+```typescript
+// app/utils/perspectapi-loaders.server.ts
+export async function createCheckoutSession(params: {
+  products: Array<{ stripe_product_id: string; quantity: number }>;
+  successUrl: string;
+  cancelUrl: string;
+  customerEmail?: string;
+}) {
+  const siteName = getSiteName();
+  
+  // SDK handles CSRF automatically
+  const response = await perspectClient.checkout.createCheckoutSession(
+    siteName,
+    {
+      line_items: params.products.map(p => ({
+        price: p.stripe_product_id,
+        quantity: p.quantity
+      })),
+      success_url: params.successUrl,
+      cancel_url: params.cancelUrl,
+      customer_email: params.customerEmail,
+      mode: 'payment',
+      automatic_tax: { enabled: true },
+      shipping_address_collection: {
+        allowed_countries: ['US', 'CA']
+      },
+      billing_address_collection: 'required'
+    }
+  );
+
+  return {
+    id: response.data?.id,
+    url: response.data?.url
+  };
+}
+```
+
+## Troubleshooting
+
+### "CSRF token required" (401)
+- Ensure you're using the SDK's `createCheckoutSession()` method
+- Or manually fetch CSRF token and include in `X-CSRF-Token` header
+- Verify API key has proper permissions
+
+### "Failed to obtain CSRF token"
+- Check that site name is correct
+- Verify API key is valid
+- Ensure CSRF endpoint is accessible
+
+### CSRF token format issues
+- SDK handles multiple response formats: `data.token`, `token`, `csrf_token`
+- Response may vary based on API version
+- SDK automatically extracts the correct field
+
+## Related Documentation
+
+- [Checkout Integration Guide](../museumof-remix/CHECKOUT-INTEGRATION.md)
+- [PerspectAPI CSRF Implementation](https://github.com/perspectapiworkers)
+- [Stripe Checkout Documentation](https://stripe.com/docs/payments/checkout)

package/docs/v1-deprecated/legacy-notes/IMAGE_TRANSFORMS_PORT.md

@@ -0,0 +1,298 @@
+# Image Transformation Utilities - Port Complete
+
+Successfully ported Cloudflare Image Resizing utilities from `perspectapiworkers` to `perspectapi-ts-sdk`.
+
+## What Was Ported
+
+### 1. Core Utilities (`src/utils/image-transform.ts`)
+
+**Functions:**
+- ✅ `buildImageUrl()` - Build single transformed URL with custom options
+- ✅ `generateResponsiveUrls()` - Generate multiple sizes at once
+- ✅ `generateSrcSet()` - Generate srcset for responsive images
+- ✅ `generateSizesAttribute()` - Generate sizes attribute
+- ✅ `generateResponsiveImageHtml()` - Complete HTML generation
+- ✅ `transformMediaItem()` - **NEW** - Convenience function for MediaItem objects
+
+**Types:**
+- ✅ `ImageTransformOptions` - All transformation options
+- ✅ `ResponsiveImageSizes` - Size presets interface
+- ✅ `DEFAULT_IMAGE_SIZES` - Default responsive sizes
+
+**Transform Options Supported:**
+- `width`, `height` - Dimensions
+- `fit` - Resize mode (scale-down, contain, cover, crop, pad)
+- `gravity` - Crop focus (auto, left, right, top, bottom, center)
+- `quality` - 1-100
+- `format` - auto, avif, webp, jpeg, png
+- `dpr` - Device pixel ratio (1, 2, 3)
+- `sharpen`, `blur`, `rotate` - Effects
+- `metadata`, `background`, `trim` - Advanced options
+
+### 2. Documentation (`docs/image-transforms.md`)
+
+**Comprehensive guide covering:**
+- ✅ Quick start examples
+- ✅ All function documentation with examples
+- ✅ Common use cases (e-commerce, blog, avatars)
+- ✅ Framework examples (Next.js, Remix, Cloudflare Workers)
+- ✅ React component examples
+- ✅ Best practices
+- ✅ Performance benefits
+- ✅ Troubleshooting
+- ✅ Requirements and setup
+
+### 3. Examples (`examples/image-transforms.ts`)
+
+**Demonstrates:**
+- ✅ Product image transformation
+- ✅ Custom transformations
+- ✅ Responsive images
+- ✅ High DPR (Retina) support
+- ✅ React component patterns
+- ✅ Common use cases
+
+### 4. SDK Integration
+
+**Exports added to `src/index.ts`:**
+```typescript
+export {
+  buildImageUrl,
+  generateResponsiveUrls,
+  generateSrcSet,
+  generateSizesAttribute,
+  generateResponsiveImageHtml,
+  transformMediaItem,
+  DEFAULT_IMAGE_SIZES
+} from './utils/image-transform';
+
+export type {
+  ImageTransformOptions,
+  ResponsiveImageSizes
+} from './utils/image-transform';
+```
+
+**README updated:**
+- ✅ Added Image Transformations section
+- ✅ Quick start example
+- ✅ Feature list
+- ✅ Link to full documentation
+
+## Key Improvements Over Original
+
+### 1. `transformMediaItem()` Function
+
+**New convenience function** specifically for working with SDK's `MediaItem` type:
+
+```typescript
+const product = await client.products.getProduct('mysite', 123);
+const media = product.data.media?.[0];
+
+if (media) {
+  const urls = transformMediaItem('https://api.perspect.co', media);
+  // Automatically handles both 'link' and 'r2_key' formats
+}
+```
+
+This makes it trivial for SDK users to transform images from API responses.
+
+### 2. Better Type Safety
+
+All functions have proper TypeScript types and JSDoc documentation with examples.
+
+### 3. SDK-Specific Examples
+
+Documentation includes examples using the SDK's client methods, not just raw URLs.
+
+## Usage Examples
+
+### Basic Usage
+
+```typescript
+import { createPerspectApiClient, transformMediaItem } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.perspect.co',
+  apiKey: 'your-api-key'
+});
+
+// Get products
+const products = await client.products.getProducts('mysite', { limit: 10 });
+
+// Transform images
+products.data.forEach(product => {
+  const media = product.media?.[0];
+  if (media && !Array.isArray(media)) {
+    const urls = transformMediaItem('https://api.perspect.co', media);
+    console.log('Thumbnail:', urls.thumbnail);
+    console.log('Large:', urls.large);
+  }
+});
+```
+
+### React Component
+
+```tsx
+import { transformMediaItem, type MediaItem } from 'perspectapi-ts-sdk';
+
+interface ProductImageProps {
+  media: MediaItem;
+  alt: string;
+}
+
+export function ProductImage({ media, alt }: ProductImageProps) {
+  const urls = transformMediaItem('https://api.perspect.co', 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}
+      loading="lazy"
+      className="rounded-lg"
+    />
+  );
+}
+```
+
+### Custom Transformations
+
+```typescript
+import { buildImageUrl } from 'perspectapi-ts-sdk';
+
+// E-commerce thumbnail
+const thumbnail = buildImageUrl(
+  'https://api.perspect.co',
+  'media/mysite/product.jpg',
+  {
+    width: 300,
+    height: 300,
+    fit: 'cover',
+    format: 'auto',
+    quality: 85
+  }
+);
+
+// Blog featured image
+const featured = buildImageUrl(
+  'https://api.perspect.co',
+  'media/mysite/blog.jpg',
+  {
+    width: 800,
+    fit: 'scale-down',
+    format: 'auto',
+    quality: 85
+  }
+);
+
+// Retina display
+const retina = buildImageUrl(
+  'https://api.perspect.co',
+  'media/mysite/icon.jpg',
+  {
+    width: 400,
+    dpr: 2,
+    format: 'auto'
+  }
+);
+```
+
+## Benefits for SDK Users
+
+### 1. Zero Configuration
+No setup needed - just import and use. Works with any MediaItem from the API.
+
+### 2. Type Safe
+Full TypeScript support with autocomplete and type checking.
+
+### 3. Framework Agnostic
+Works in Next.js, Remix, Cloudflare Workers, vanilla JS, etc.
+
+### 4. Performance
+- On-the-fly resizing (no pre-generated thumbnails)
+- Automatic format optimization (WebP/AVIF)
+- CDN caching at the edge
+- Bandwidth savings
+
+### 5. Easy Migration
+If you're already using the API, just add image transformations with one function call.
+
+## 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
+
+## Testing
+
+**Comprehensive test suite** (`tests/utils/image-transform.test.ts`):
+
+✅ **100+ test cases** covering:
+- `buildImageUrl()` - All transform options, edge cases
+- `generateResponsiveUrls()` - Default and custom sizes
+- `generateSrcSet()` - Default and custom widths
+- `generateSizesAttribute()` - Default and custom breakpoints
+- `generateResponsiveImageHtml()` - All options and attributes
+- `transformMediaItem()` - Both link and r2_key formats
+- `DEFAULT_IMAGE_SIZES` - All presets
+- Edge cases - Empty paths, query params, zero values
+
+**Run tests:**
+```bash
+npm test tests/utils/image-transform.test.ts
+```
+
+**Test coverage includes:**
+- URL format validation
+- Cloudflare Image Resizing URL structure
+- All transformation options (width, height, fit, gravity, quality, format, dpr, etc.)
+- Responsive image generation
+- MediaItem object handling
+- Edge cases and error conditions
+
+## Files Added/Modified
+
+**New Files:**
+- `src/utils/image-transform.ts` - Core utilities (256 lines)
+- `docs/image-transforms.md` - Complete documentation (600+ lines)
+- `examples/image-transforms.ts` - Working examples (200+ lines)
+- `tests/utils/image-transform.test.ts` - Comprehensive tests (400+ lines)
+- `IMAGE_TRANSFORMS_PORT.md` - This summary
+
+**Modified Files:**
+- `src/index.ts` - Added exports
+- `README.md` - Added Image Transformations section
+- `examples/README.md` - Added image transforms example
+
+## Testing
+
+Run the example:
+```bash
+export API_URL=https://api.perspect.co
+export API_KEY=your-api-key
+export SITE_NAME=your-site
+
+npx tsx examples/image-transforms.ts
+```
+
+## Next Steps
+
+SDK users can now:
+1. Import image transformation utilities
+2. Transform MediaItem objects from API responses
+3. Build custom transformation URLs
+4. Generate responsive images with srcset
+5. Use in any framework (React, Vue, Svelte, etc.)
+
+## Documentation
+
+- **Quick Start**: See README.md
+- **Full Guide**: See docs/image-transforms.md
+- **Examples**: See examples/image-transforms.ts
+- **API Reference**: TypeScript types in src/utils/image-transform.ts