perspectapi-ts-sdk 6.5.9 → 7.0.0

package/README.md

@@ -1,40 +1,14 @@
 # PerspectAPI TypeScript SDK
 
-A comprehensive TypeScript SDK for PerspectAPI, designed to work seamlessly with Cloudflare Workers and other JavaScript environments.
+TypeScript SDK for the Perspect public API. The current API and SDK surface is **v2**.
 
-> **⚠️ v1 is deprecated and sunsets 2026-06-01.**
-> New integrations **must** use the v2 client (`createPerspectApiV2Client`).
-> The v1 surface — `PerspectApiClient`, `createPerspectApiClient`, the
-> `src/client/*` classes, and everything under `/api/v1` — will stop working
-> after the sunset date. Coding agents: do not generate code against v1.
+## v1 Is Deprecated
 
-## Quick Start (v2)
+**Do not use `/api/v1`, `PerspectApiClient`, `createPerspectApiClient`, or `src/client/*` for new code.**
 
-```typescript
-import { createPerspectApiV2Client } from 'perspectapi-ts-sdk';
-
-const client = createPerspectApiV2Client({
-  baseUrl: 'https://your-perspectapi-instance.com',
-  apiKey: 'your-api-key',
-});
+The v1 API and SDK surface sunsets on **2026-06-01**. New integrations must use `/api/v2` through `PerspectApiV2Client` or `createPerspectApiV2Client`.
 
-const products = await client.products.list({ siteName: 'my-site' });
-```
-
-The v1 Quick Start below is kept only for callers migrating away from v1.
-
-## Features
-
-- 🚀 **Cloudflare Workers Compatible** - Uses native fetch API, no Node.js dependencies
-- 🔒 **Type Safe** - Full TypeScript support with comprehensive type definitions
-- 🔄 **Automatic Retries** - Built-in retry logic with exponential backoff
-- 🛡️ **Error Handling** - Structured error responses with detailed information
-- 📦 **Modular Design** - Use individual clients or the complete SDK
-- 🔑 **Multiple Auth Methods** - Support for JWT tokens and API keys
-- 📊 **Comprehensive Coverage** - All PerspectAPI endpoints supported
-- 🧩 **High-Level Loaders** - Drop-in helpers for products, content, and checkout flows with fallbacks
-- 📧 **Newsletter Management** - Complete newsletter subscription system with double opt-in, preferences, and lists
-- 👥 **Site Users** - OTP-based customer accounts with metadata, profiles, orders, and subscriptions
+Historical v1 examples have been moved to [docs/v1-deprecated/sdk-readme.md](docs/v1-deprecated/sdk-readme.md) for migration reference only.
 
 ## Installation
 
@@ -44,1023 +18,84 @@ npm install perspectapi-ts-sdk
 
 ## Quick Start
 
-```typescript
-import { createPerspectApiClient } from 'perspectapi-ts-sdk';
-
-// Initialize with API key
-const client = createPerspectApiClient({
-  baseUrl: 'https://your-perspectapi-instance.com',
-  apiKey: 'your-api-key'
-});
-
-// Or initialize with JWT token
-const client = createPerspectApiClient({
-  baseUrl: 'https://your-perspectapi-instance.com',
-  jwt: 'your-jwt-token'
-});
-
-// Use the client
-async function example() {
-  const siteName = 'your-site-name';
-
-  // Get all content
-  const content = await client.content.getContent(siteName);
-  console.log(content.data);
-
-  // Create new content
-  const newContent = await client.content.createContent({
-    page_title: 'Hello World',
-    page_content: 'This is my first post!',
-    page_status: 'publish',
-    page_type: 'post'
-  });
-  
-  console.log(newContent.data);
-}
-
-### High-Level Loaders (Quick Example)
+Use the v2 subpath when you want the import itself to make the version explicit:
 
 ```typescript
-import {
-  loadProducts,
-  loadPosts,
-  createCheckoutSession
-} from 'perspectapi-ts-sdk';
-
-const loaders = {
-  client: createPerspectApiClient({ baseUrl, apiKey }),
-  siteName: 'my-museum-site'
-};
-
-const products = await loadProducts(loaders);
-const posts = await loadPosts(loaders);
-
-const checkout = await createCheckoutSession({
-  ...loaders,
-  items: [{ productId: products[0].id, quantity: 1 }],
-  successUrl: 'https://example.com/success',
-  cancelUrl: 'https://example.com/cancel'
-});
-```
-
-> 📚 See [docs/loaders.md](docs/loaders.md) for full walkthroughs, including fallback data, custom logging, and Stripe price resolution.
-
-## Configuring Caching
-
-Pass a `cache` block when you create the client to enable caching. The SDK falls back to an in-memory store in development; in production you can supply any adapter that satisfies the `CacheAdapter` interface.
-
-```ts
-import { PerspectApiClient } from 'perspectapi-ts-sdk';
-import { myCacheAdapter } from './cache-adapter';
-
-const perspect = new PerspectApiClient({
-  baseUrl: 'https://api.perspect.comm',
-  apiKey: env.PERSPECT_API_KEY,
-  cache: {
-    adapter: myCacheAdapter,
-    defaultTtlSeconds: 300,
-    keyPrefix: 'storefront', // optional namespace
-  },
-});
-```
-
-### Cloudflare Workers KV example
-
-KV namespaces make a great globally distributed cache. Bind a namespace (e.g. `PERSPECT_CACHE`) in your Worker and wrap it with a small adapter:
-
-```ts
-// worker.ts
-import { PerspectApiClient, type CacheAdapter } from 'perspectapi-ts-sdk';
-
-const kvAdapter = (kv: KVNamespace): CacheAdapter => ({
-  async get(key) {
-    const value = await kv.get(key);
-    return value ?? undefined;
-  },
-  async set(key, value, options) {
-    const ttl = options?.ttlSeconds;
-    await kv.put(key, value, ttl ? { expirationTtl: ttl } : undefined);
-  },
-  async delete(key) {
-    await kv.delete(key);
-  },
-  async deleteMany(keys) {
-    await Promise.all(keys.map(key => kv.delete(key)));
-  },
-});
-
-export default {
-  async fetch(request: Request, env: Env) {
-    const perspect = new PerspectApiClient({
-      baseUrl: env.PERSPECT_API_URL,
-      apiKey: env.PERSPECT_API_KEY,
-      cache: {
-        adapter: kvAdapter(env.PERSPECT_CACHE),
-        defaultTtlSeconds: 300,
-        keyPrefix: 'storefront',
-      },
-    });
-
-    const products = await perspect.products.getProducts('museum-indian-art');
-    return new Response(JSON.stringify(products.data), {
-      headers: { 'Content-Type': 'application/json' },
-    });
-  },
-};
-```
-
-When PerspectAPI sends a webhook—or when your Worker mutates data directly—call `perspect.cache.invalidate({ tags: [...] })` using the tags emitted by the SDK (`products:site:<site>`, `content:slug:<site>:<slug>`, `newsletter:campaigns:slug:<site>:<slug>`, etc.) so stale entries are purged immediately.
-
-### Webhook-driven cache invalidation
-
-Most deployments rely on PerspectAPI webhooks to bust cache entries whenever content changes. Your app needs an HTTP endpoint that:
-
-1. Verifies the webhook signature (or shared secret).
-2. Maps the webhook payload to the cache tags that were used when reading data.
-3. Calls `client.cache.invalidate({ tags })`.
-
-Below is a minimal Cloudflare Worker handler; the same flow works in Express, Fastify, etc.—just swap the request parsing.
-
-```ts
-// worker.ts
-import { PerspectApiClient } from 'perspectapi-ts-sdk';
-
-const kvAdapter = (kv: KVNamespace) => ({
-  get: (key: string) => kv.get(key),
-  set: (key: string, value: string, options?: { ttlSeconds?: number }) =>
-    options?.ttlSeconds
-      ? kv.put(key, value, { expirationTtl: options.ttlSeconds })
-      : kv.put(key, value),
-  delete: (key: string) => kv.delete(key),
-});
-
-const perspect = new PerspectApiClient({
-  baseUrl: env.PERSPECT_API_URL,
-  apiKey: env.PERSPECT_API_KEY,
-  cache: { adapter: kvAdapter(env.PERSPECT_CACHE), defaultTtlSeconds: 300 },
-});
-
-type WebhookEvent =
-  | { type: 'product.updated'; site: string; slug?: string; id?: number }
-  | { type: 'content.published'; site: string; slug: string; id: number }
-  | { type: 'category.updated'; site: string; slug: string };
-
-const tagMap: Record<string, (e: WebhookEvent) => string[]> = {
-  'product.updated': event => [
-    `products`,
-    `products:site:${event.site}`,
-    event.slug ? `products:slug:${event.site}:${event.slug}` : '',
-    event.id ? `products:id:${event.id}` : '',
-  ],
-  'content.published': event => [
-    `content`,
-    `content:site:${event.site}`,
-    `content:slug:${event.site}:${event.slug}`,
-    `content:id:${event.id}`,
-  ],
-  'category.updated': event => [
-    `categories`,
-    `categories:site:${event.site}`,
-    `categories:product:${event.site}:${event.slug}`,
-    `products:category:${event.site}:${event.slug}`,
-    `content:category:${event.site}:${event.slug}`,
-  ],
-};
-
-export default {
-  async fetch(request: Request, env: Env) {
-    const url = new URL(request.url);
-
-    if (url.pathname === '/webhooks/perspect' && request.method === 'POST') {
-      const event = (await request.json()) as WebhookEvent;
-
-      // TODO: validate shared secret / signature before proceeding
-
-      const buildTags = tagMap[event.type];
-      if (buildTags) {
-        const tags = buildTags(event).filter(Boolean);
-        if (tags.length) {
-          await perspect.cache.invalidate({ tags });
-        }
-      }
-
-      return new Response(null, { status: 202 });
-    }
-
-    // ...rest of your app
-    return new Response('ok');
-  },
-};
-```
-
-> 🔁 Adjust the `WebhookEvent` union and `tagMap` to match the actual payloads you receive. PerspectAPI webhooks also carry version IDs and environment metadata that you can use for more granular targeting if needed.
-
-### Newsletter Publish Invalidation
-
-Newsletter list and campaign reads are cache-aware:
-
-```ts
-const campaigns = await perspect.newsletter.getPublishedCampaigns('museum-indian-art', {
-  page: 1,
-  limit: 20,
-});
-const campaign = await perspect.newsletter.getPublishedCampaignBySlug(
-  'museum-indian-art',
-  'spring-launch',
-  { slugPrefix: 'updates' }
-);
-```
+import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';
 
-For webhook handling, use the newsletter helper so invalidation happens only when campaigns are published (not when drafts are created):
-
-```ts
-const result = await perspect.newsletter.invalidatePublishedCampaignCacheFromWebhook(
-  webhookPayload,
-  'museum-indian-art'
-);
-
-if (result.invalidated) {
-  console.log(result.tags);
-}
-```
-
-## 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.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
-}
-
-// Or build custom transformations
-const customUrl = buildImageUrl(
-  'https://api.perspect.comm',
-  '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:
-
-- normalise products (including nested media arrays and Stripe IDs)
-- search products server-side with limit/offset support and filter by category names or IDs (no hard-coded IDs)
-- fetch published posts/pages with sensible defaults
-- fall back to sample data when PerspectAPI is not configured (useful for local previews)
-- create Stripe checkout sessions by automatically resolving price IDs
-
-All loaders accept a shared `LoaderOptions` object:
-
-```typescript
-import {
-  loadProducts,
-  loadProductBySlug,
-  loadPosts,
-  createCheckoutSession,
-  type LoaderOptions
-} from 'perspectapi-ts-sdk';
-
-const options: LoaderOptions = {
-  client: createPerspectApiClient({ baseUrl, apiKey }),
-  siteName: 'museum-indian-art',
-  logger: console,              // optional
-  fallbackProducts: [],         // optional
-  fallbackPosts: []             // optional
-};
-
-const products = await loadProducts(options);
-const single = await loadProductBySlug({ ...options, slug: 'sunset-painting' });
-const posts = await loadPosts(options);
-
-await createCheckoutSession({
-  ...options,
-  items: [{ productId: products[0].id, quantity: 1 }],
-  successUrl: 'https://example.com/success',
-  cancelUrl: 'https://example.com/cancel'
-});
-
-// Filter products by multiple category names/IDs while combining search
-const decorPillows = await loadProducts({
-  ...options,
-  category: ['Home Decor', 'Seasonal Sale'],
-  categoryIds: [12],
-  search: 'pillow',
-  offset: 24,
-  limit: 12
+const client = createPerspectApiV2Client({
+  baseUrl: 'https://api.perspect.com',
+  apiKey: process.env.PERSPECTAPI_API_KEY!,
 });
-```
-
-> More real-world scenarios—including Cloudflare Workers, Remix/Next.js loaders, custom logger implementations, and checkout price resolution—are documented in [docs/loaders.md](docs/loaders.md).
-
-## Authentication
-
-### API Key Authentication
 
-```typescript
-const client = createPerspectApiClient({
-  baseUrl: 'https://api.example.com',
-  apiKey: 'pk_your_api_key_here'
-});
+const site = await client.sites.get('my-site');
+console.log(site.id, site.name);
 ```
 
-### JWT Token Authentication
+The top-level package also exports v2:
 
 ```typescript
-const client = createPerspectApiClient({
-  baseUrl: 'https://api.example.com',
-  jwt: 'your.jwt.token'
-});
-
-// Or authenticate after initialization
-await client.auth.signIn({
-  email: 'user@example.com',
-  password: 'password'
-});
+import { createPerspectApiV2Client } from 'perspectapi-ts-sdk';
 ```
 
-### Dynamic Authentication
+## Common Resources
 
 ```typescript
-const client = createPerspectApiClient({
-  baseUrl: 'https://api.example.com'
+const content = await client.content.list('my-site', {
+  type: 'post',
+  status: 'publish',
+  limit: 10,
 });
 
-// Set authentication later
-client.setApiKey('pk_your_api_key');
-// or
-client.setAuth('your.jwt.token');
-
-// Clear authentication
-client.clearAuth();
-```
-
-## API Reference
-
-### Content Management
-
-```typescript
-// Get all content with pagination
-const content = await client.content.getContent('your-site-name', {
-  page: 1,
+const products = await client.products.list('my-site', {
+  published: true,
   limit: 20,
-  page_status: 'publish',
-  page_type: 'post',
-  slug_prefix: 'blog'  // Optional: filter by slug prefix
 });
 
-// Get content by ID
-const post = await client.content.getContentById(123);
-
-// Get content by slug
-const page = await client.content.getContentBySlug('your-site-name', 'about-us');
-
-// Get content by category slug
-const categoryContent = await client.content.getContentByCategorySlug(
-  'your-site-name',
-  'news',
-  {
-    page: 1,
-    limit: 20,
-    page_type: 'post'
-  }
-);
-
-// Create new content
-const newPost = await client.content.createContent({
-  page_title: 'My New Post',
-  page_content: '<p>Content goes here</p>',
-  content_markdown: '# My New Post\n\nContent goes here',
-  page_status: 'draft',
-  page_type: 'post',
-  slug: 'my-new-post'
-});
-
-// Update content
-const updated = await client.content.updateContent(123, {
-  page_title: 'Updated Title',
-  page_status: 'publish'
-});
-
-// Delete content
-await client.content.deleteContent(123);
-
-// Publish/unpublish content
-await client.content.publishContent(123);
-await client.content.unpublishContent(123);
-```
-
-### Products & E-commerce
-
-```typescript
-// Get all products
-const products = await client.products.getProducts('my-site', {
-  page: 1,
+const contacts = await client.contacts.list('my-site', {
   limit: 20,
-  isActive: true,
-  slug_prefix: 'shop'  // Optional: filter by slug prefix
-});
-
-// Create new product
-const product = await client.products.createProduct({
-  name: 'Amazing Product',
-  description: 'Product description',
-  price: 29.99,
-  currency: 'USD',
-  sku: 'PROD-001'
 });
-
-// Update product inventory
-await client.products.updateProductInventory(123, {
-  quantity: 10,
-  operation: 'add',
-  reason: 'Restocked'
-});
-
-// Get product by slug and site name (NEW!)
-const productBySlug = await client.products.getProductBySlug('my-site', 'awesome-laptop');
-console.log('Product:', productBySlug.data?.name);
-console.log('Variants:', productBySlug.data?.variants);
-
-// Get products by category slug (NEW!)
-const categoryProducts = await client.products.getProductsByCategorySlug(
-  'my-site',
-  'electronics',
-  {
-    page: 1,
-    limit: 20,
-    published: true,
-    search: 'phone'
-  }
-);
-console.log('Products:', categoryProducts.data?.data);
-console.log('Category info:', categoryProducts.data?.category);
-```
-
-### Organizations & Sites
-
-```typescript
-// Get organizations
-const orgs = await client.organizations.getOrganizations();
-
-// Create new organization
-const org = await client.organizations.createOrganization({
-  name: 'My Company',
-  description: 'Company description'
-});
-
-// Get sites
-const sites = await client.sites.getSites({
-  organizationId: 1
-});
-
-// Create new site
-const site = await client.sites.createSite({
-  name: 'My Website',
-  domain: 'example.com',
-  organizationId: 1
-});
-```
-
-### API Key Management
-
-```typescript
-// Get all API keys
-const apiKeys = await client.apiKeys.getApiKeys();
-
-// Create new API key
-const newKey = await client.apiKeys.createApiKey({
-  name: 'Frontend App Key',
-  description: 'API key for frontend application',
-  permissions: ['content:read', 'products:read'],
-  expiresAt: '2024-12-31T23:59:59Z'
-});
-
-console.log('New API key:', newKey.data.key);
-
-// Test API key validity
-const testResult = await client.apiKeys.testApiKey('pk_test_key');
-console.log('Key valid:', testResult.data.valid);
-```
-
-### Webhooks
-
-```typescript
-// Get all webhooks
-const webhooks = await client.webhooks.getWebhooks();
-
-// Create new webhook
-const webhook = await client.webhooks.createWebhook({
-  name: 'Order Notifications',
-  url: 'https://myapp.com/webhooks/orders',
-  provider: 'stripe',
-  events: ['payment_intent.succeeded', 'payment_intent.payment_failed'],
-  isActive: true
-});
-
-// Test webhook
-const testResult = await client.webhooks.testWebhook(webhook.data.id);
-console.log('Webhook test:', testResult.data);
-```
-
-### Checkout & Payments
-
-```typescript
-// Create Stripe checkout session
-const session = await client.checkout.createCheckoutSession({
-  priceId: 'price_1234567890',
-  successUrl: 'https://myapp.com/success',
-  cancelUrl: 'https://myapp.com/cancel',
-  customerEmail: 'customer@example.com',
-  currency: 'usd',
-  shipping_amount: 500,
-  shipping_address: {
-    country: 'US',
-    state: 'CA',
-    postal_code: '94110'
-  },
-  billing_address: {
-    country: 'US',
-    state: 'CA',
-    postal_code: '94110'
-  },
-  tax: {
-    strategy: 'manual_rates',
-    customer_identifier: 'acct-123',
-    customer_display_name: 'Acme Corp',
-    customer_exemption: {
-      status: 'exempt',
-      tax_id: '99-1234567',
-      tax_id_type: 'ein'
-    }
-  }
-});
-
-// Redirect user to checkout
-window.location.href = session.data.url;
-
-// Get checkout session status
-const sessionStatus = await client.checkout.getCheckoutSession('cs_test_123');
-console.log(sessionStatus.data.tax?.amount); // Display assessed tax (if calculated)
-```
-
-### Contact Forms
-
-```typescript
-const siteName = 'your-site-name';
-
-// Submit contact form
-const submission = await client.contact.submitContact(siteName, {
-  name: 'John Doe',
-  email: 'john@example.com',
-  subject: 'Question about pricing',
-  message: 'I have a question about your pricing plans.',
-  turnstileToken: 'turnstile-response-token'
-});
-
-// Get contact submissions (admin only)
-const submissions = await client.contact.getContactSubmissions(siteName, {
-  status: 'unread',
-  page: 1,
-  limit: 50
-});
-
-// Update submission status
-await client.contact.updateContactStatus(siteName, submission.data.id, 'read');
-```
-
-### Newsletter Subscriptions
-
-```typescript
-const siteName = 'your-site-name';
-
-// Subscribe to newsletter (with double opt-in)
-const subscription = await client.newsletter.subscribe(siteName, {
-  email: 'subscriber@example.com',
-  name: 'Jane Doe',
-  list_ids: ['list_default'],  // Optional: subscribe to specific lists
-  frequency: 'weekly',          // instant, daily, weekly, monthly
-  topics: ['news', 'updates'],  // Optional: topic preferences
-  double_opt_in: true,          // Default: true for GDPR compliance
-  turnstile_token: 'token'      // Optional: Turnstile verification
-});
-
-// Confirm subscription via email token
-const confirmed = await client.newsletter.confirmSubscription(
-  siteName,
-  'confirmation-token-from-email'
-);
-
-// Unsubscribe
-const unsubscribed = await client.newsletter.unsubscribe(siteName, {
-  email: 'subscriber@example.com',
-  reason: 'Too many emails'  // Optional feedback
-});
-
-// One-click unsubscribe (from email link)
-await client.newsletter.unsubscribeByToken(siteName, 'unsubscribe-token');
-
-// Update preferences
-await client.newsletter.updatePreferences(siteName, 'subscriber@example.com', {
-  frequency: 'monthly',
-  topics: ['product-updates'],
-  email_format: 'html',  // html, text, or both
-  timezone: 'America/New_York',
-  track_opens: false,
-  track_clicks: false
-});
-
-// Check subscription status
-const status = await client.newsletter.getStatus(siteName, 'subscriber@example.com');
-console.log('Subscribed:', status.data.subscribed);
-console.log('Status:', status.data.status); // pending, confirmed, unsubscribed
-
-// Get available newsletter lists
-const lists = await client.newsletter.getLists(siteName);
-console.log('Available lists:', lists.data.lists);
-```
-
-#### Newsletter Management APIs
-
-`client.newsletter` is now public-only (subscribe/confirm/unsubscribe/preferences/public lists/published campaigns).
-For management operations, use `client.newsletterManagement`.
-
-```typescript
-// Sync subscriber by email (canonical create/update path)
-const sync = await client.newsletterManagement.syncSubscription(siteName, {
-  email: 'user@example.com',
-  name: 'User Name',
-  list_ids: ['list_default'],
-  resubscribe_override: false
-});
-console.log(sync.data.code); // CREATED, UPDATED, RESUBSCRIBED, ALREADY_UNSUBSCRIBED
-
-// List subscribers
-const subscriptions = await client.newsletterManagement.listSubscriptions(siteName, {
-  page: 1,
-  limit: 100,
-  status: 'confirmed'
-});
-
-// Import with override controls (row-level override wins)
-await client.newsletterManagement.importSubscriptions(siteName, {
-  resubscribe_override: false,
-  rows: [
-    { email: 'user1@example.com', list_ids: ['list_default'] },
-    { email: 'user2@example.com', resubscribe_override: true }
-  ]
-});
-
-// List + campaign management
-await client.newsletterManagement.createList(siteName, {
-  list_name: 'VIP Customers',
-  slug: 'vip-customers',
-  is_public: false
-});
-
-await client.newsletterManagement.createCampaign(siteName, {
-  campaign_name: 'Spring Update',
-  subject: 'Spring Update',
-  markdown_content: '# Hello',
-  status: 'draft'
-});
-
-// Exports (csv/json only; xlsx returns UNSUPPORTED_FORMAT)
-const exportData = await client.newsletterManagement.createExport(siteName, {
-  format: 'csv'
-});
-console.log(exportData.data.downloadUrl);
-```
-
-> 📚 **For complete newsletter documentation**, see [docs/newsletter.md](docs/newsletter.md)
-
-### Site Users (Customer Accounts)
-
-Site users are per-site customer accounts with OTP-based authentication, separate from admin users.
-
-```typescript
-const siteName = 'your-site-name';
-
-// Request OTP for login/signup (with optional metadata)
-await client.siteUsers.requestOtp(
-  siteName,
-  {
-    email: 'user@example.com',
-    waitlist: true,  // Optional: mark as waitlist signup
-    metadata: {      // Optional: set metadata at signup time
-      signupSource: 'landing-page',
-      referralCode: 'FRIEND123',
-      interests: ['product-updates']
-    }
-  },
-  csrfToken
-);
-
-// Verify OTP and get JWT token
-const response = await client.siteUsers.verifyOtp(
-  siteName,
-  { email: 'user@example.com', code: '123456' },
-  csrfToken
-);
-
-const { token, user } = response.data;
-client.setAuth(token);  // Set auth for subsequent requests
-
-// Get current user profile
-const { data } = await client.siteUsers.getMe(siteName);
-console.log(data.user);      // Basic user fields + metadata
-console.log(data.profile);   // Key-value profile data
-
-// Update user profile and metadata
-await client.siteUsers.updateMe(
-  siteName,
-  {
-    first_name: 'John',
-    last_name: 'Doe',
-    metadata: {
-      preferences: { theme: 'dark' },
-      tags: ['premium'],
-      customField: 'value'
-    }
-  },
-  csrfToken
-);
-
-// Set profile key-values (phone, addresses, etc.)
-await client.siteUsers.setProfileValue(
-  siteName,
-  'phone',
-  '+1-555-0123',
-  csrfToken
-);
-
-await client.siteUsers.setProfileValue(
-  siteName,
-  'address_shipping',
-  JSON.stringify({
-    line1: '123 Main St',
-    city: 'San Francisco',
-    state: 'CA',
-    postal_code: '94102',
-    country: 'US'
-  }),
-  csrfToken
-);
-
-// Get order history
-const orders = await client.siteUsers.getOrders(siteName, {
-  limit: 50,
-  offset: 0
-});
-
-// Get subscriptions
-const subscriptions = await client.siteUsers.getSubscriptions(siteName);
-
-// Cancel at end of billing period (default)
-await client.siteUsers.cancelSubscription(siteName, 'sub_123', csrfToken);
-
-// Cancel immediately
-await client.siteUsers.cancelSubscription(
-  siteName,
-  'sub_123',
-  csrfToken,
-  { mode: 'immediate' }
-);
-
-// Cancel at a scheduled time (absolute)
-await client.siteUsers.cancelSubscription(
-  siteName,
-  'sub_123',
-  csrfToken,
-  { mode: 'scheduled', cancel_at: '2026-05-01T15:30:00Z' }
-);
-
-// Cancel after a configured delay (days/hours/minutes)
-await client.siteUsers.cancelSubscription(
-  siteName,
-  'sub_123',
-  csrfToken,
-  { mode: 'scheduled', delay_days: 7, delay_hours: 2 }
-);
-
-// Logout
-await client.siteUsers.logout(siteName);
-client.setAuth(null);
-```
-
-> 📚 **For complete site users documentation** including waitlist management, metadata patterns, cross-domain authentication, and complete examples, see [docs/site-users.md](docs/site-users.md)
-
-## Configuration Options
-
-```typescript
-interface PerspectApiConfig {
-  baseUrl: string;           // Required: API base URL
-  apiKey?: string;          // Optional: API key for authentication
-  jwt?: string;             // Optional: JWT token for authentication
-  timeout?: number;         // Optional: Request timeout in ms (default: 30000)
-  retries?: number;         // Optional: Number of retries (default: 3)
-  headers?: Record<string, string>; // Optional: Additional headers
-}
 ```
 
 ## Error Handling
 
-The SDK provides structured error handling:
-
 ```typescript
-import { createApiError } from 'perspectapi-ts-sdk';
+import { PerspectV2Error } from 'perspectapi-ts-sdk/v2';
 
 try {
-  const content = await client.content.getContentById(999);
+  await client.products.get('my-site', 'prod_missing');
 } catch (error) {
-  const apiError = createApiError(error);
-  
-  console.log('Error message:', apiError.message);
-  console.log('Status code:', apiError.status);
-  console.log('Error code:', apiError.code);
-  console.log('Details:', apiError.details);
-}
-```
-
-## Cloudflare Workers Usage
-
-The SDK is fully compatible with Cloudflare Workers:
-
-```typescript
-// worker.ts
-import { createPerspectApiClient } from 'perspectapi-ts-sdk';
-
-export default {
-  async fetch(request: Request, env: any): Promise<Response> {
-    const client = createPerspectApiClient({
-      baseUrl: env.PERSPECT_API_URL,
-      apiKey: env.PERSPECT_API_KEY
-    });
-
-    try {
-      const content = await client.content.getContent(env.PERSPECT_SITE_NAME, { limit: 10 });
-      
-      return new Response(JSON.stringify(content.data), {
-        headers: { 'Content-Type': 'application/json' }
-      });
-    } catch (error) {
-      return new Response('Error fetching content', { status: 500 });
-    }
+  if (error instanceof PerspectV2Error) {
+    console.error(error.type, error.code, error.message);
   }
-};
-```
-
-## Advanced Usage
-
-### Using Individual Clients
-
-```typescript
-import { HttpClient, ContentClient } from 'perspectapi-ts-sdk';
-
-// Create HTTP client
-const http = new HttpClient({
-  baseUrl: 'https://api.example.com',
-  apiKey: 'your-api-key'
-});
-
-// Use individual client
-const contentClient = new ContentClient(http);
-const content = await contentClient.getContent('your-site-name');
-```
-
-### Custom Headers
-
-```typescript
-const client = createPerspectApiClient({
-  baseUrl: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  headers: {
-    'X-Custom-Header': 'custom-value',
-    'User-Agent': 'MyApp/1.0.0'
-  }
-});
-```
-
-### Timeout and Retries
-
-```typescript
-const client = createPerspectApiClient({
-  baseUrl: 'https://api.example.com',
-  apiKey: 'your-api-key',
-  timeout: 60000,  // 60 seconds
-  retries: 5       // Retry up to 5 times
-});
-```
-
-## 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:
+## Caching
 
 ```typescript
-import type { 
-  Content, 
-  Product, 
-  ApiResponse, 
-  PaginatedResponse 
+import {
+  createPerspectApiV2Client,
+  InMemoryCacheAdapter,
 } from 'perspectapi-ts-sdk';
 
-// Fully typed responses
-const content: ApiResponse<Content> = await client.content.getContentById(123);
-const products: PaginatedResponse<Product> = await client.products.getProducts('your-site-name');
+const client = createPerspectApiV2Client({
+  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
+  apiKey: process.env.PERSPECTAPI_API_KEY!,
+  cache: {
+    adapter: new InMemoryCacheAdapter(),
+    defaultTtlSeconds: 300,
+  },
+});
 ```
 
-## Contributing
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## License
+## API Reference
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+- Current SDK entry point: `perspectapi-ts-sdk/v2`
+- Current REST base path: `/api/v2`
+- Public docs: `https://perspect.com/docs/sdk/typescript/v2-client`
+- LLM docs: `https://perspect.com/llms.txt`
 
-## Support
+## Migration
 
-- 📖 [Documentation](https://docs.perspectapi.com)
-- 🐛 [Issue Tracker](https://github.com/perspectapi/perspectapi-ts-sdk/issues)
-- 💬 [Discussions](https://github.com/perspectapi/perspectapi-ts-sdk/discussions)
-- 📧 [Email Support](mailto:support@perspectapi.com)
+If you are maintaining existing v1 code, migrate it before **2026-06-01**. v1 runtime responses include `Deprecation`, `Sunset`, `Warning`, `Link`, and `X-Perspect-Deprecation-Notice` headers, and v1 SDK constructors emit a warning.