perspectapi-ts-sdk 6.5.7 → 7.0.0

package/dist/v2/index.mjs

@@ -0,0 +1,40 @@
+import {
+  ApiKeysV2Client,
+  BaseV2Client,
+  CategoriesV2Client,
+  CollectionsV2Client,
+  ContactsV2Client,
+  ContentV2Client,
+  CreditsV2Client,
+  NewsletterV2Client,
+  OrdersV2Client,
+  OrganizationsV2Client,
+  PerspectApiV2Client,
+  PerspectV2Error,
+  ProductsV2Client,
+  SiteUsersV2Client,
+  SitesV2Client,
+  SubscriptionsV2Client,
+  WebhooksV2Client,
+  createPerspectApiV2Client
+} from "../chunk-K3T2AFYA.mjs";
+export {
+  ApiKeysV2Client,
+  BaseV2Client,
+  CategoriesV2Client,
+  CollectionsV2Client,
+  ContactsV2Client,
+  ContentV2Client,
+  CreditsV2Client,
+  NewsletterV2Client,
+  OrdersV2Client,
+  OrganizationsV2Client,
+  PerspectApiV2Client,
+  PerspectV2Error,
+  ProductsV2Client,
+  SiteUsersV2Client,
+  SitesV2Client,
+  SubscriptionsV2Client,
+  WebhooksV2Client,
+  createPerspectApiV2Client
+};

package/docs/README.md

@@ -0,0 +1,15 @@
+# PerspectAPI SDK Docs
+
+The current SDK and REST API surface is v2.
+
+Use:
+
+```typescript
+import { createPerspectApiV2Client } from 'perspectapi-ts-sdk/v2';
+```
+
+Do not use `/api/v1`, `PerspectApiClient`, `createPerspectApiClient`, or
+`src/client/*` for new code. v1 sunsets on **2026-06-01**.
+
+Historical v1 material lives under [v1-deprecated](./v1-deprecated/) for
+migration reference only.

package/docs/v1-deprecated/README.md

@@ -0,0 +1,9 @@
+# Deprecated v1 Material
+
+This directory contains historical v1 SDK docs, examples, and migration notes.
+
+Do not copy these examples into new code. v1 (`/api/v1`, `PerspectApiClient`,
+`createPerspectApiClient`, and `src/client/*`) sunsets on **2026-06-01**.
+
+Use `createPerspectApiV2Client` from `perspectapi-ts-sdk/v2` and `/api/v2`
+for all new integrations.

package/docs/v1-deprecated/examples/README.md

@@ -0,0 +1,324 @@
+# PerspectAPI SDK Examples
+
+These are historical v1 examples kept for migration reference only.
+
+Do not copy these examples into new code. v1 (`/api/v1`, `PerspectApiClient`,
+`createPerspectApiClient`, and `src/client/*`) sunsets on **2026-06-01**. New
+integrations must use `createPerspectApiV2Client` from `perspectapi-ts-sdk/v2`
+and `/api/v2`.
+
+This directory contains practical examples of how the deprecated v1 PerspectAPI
+TypeScript SDK was used in different environments and scenarios.
+
+## Examples
+
+### 1. Image Transformations (`image-transforms.ts`)
+
+Demonstrates how to transform images using Cloudflare Image Resizing:
+- Transform product images to multiple sizes
+- Custom transformations (resize, crop, format)
+- Generate responsive images with srcset
+- High DPR (Retina) support
+- React component examples
+
+**Run:**
+```bash
+npx tsx docs/v1-deprecated/examples/image-transforms.ts
+```
+
+**Key features:**
+- `transformMediaItem()` - Transform MediaItem objects
+- `buildImageUrl()` - Custom transformations
+- `generateResponsiveUrls()` - Multiple sizes at once
+- `generateSrcSet()` - For responsive images
+- `generateResponsiveImageHtml()` - Complete HTML generation
+
+### 2. Basic Usage (`basic-usage.ts`)
+
+Comprehensive example showing all major SDK features:
+- Authentication and user management
+- Content management (CRUD operations)
+- Product management
+- Organization and site management
+- API key management
+- Categories
+- Contact forms
+- Webhooks
+
+**Run the example:**
+```bash
+# Install dependencies
+npm install
+
+# Set environment variables
+export PERSPECT_API_URL="https://your-api-instance.com"
+export PERSPECT_API_KEY="your-api-key"
+
+# Run the deprecated v1 example
+npx tsx docs/v1-deprecated/examples/basic-usage.ts
+```
+
+### 2. Cloudflare Worker (`cloudflare-worker.ts`)
+
+Complete Cloudflare Worker implementation demonstrating:
+- SDK initialization in Workers environment
+- Request routing and handling
+- Error handling for edge environments
+- Optimized timeout and retry settings
+- JSON API responses
+
+**Deploy to Cloudflare Workers:**
+```bash
+# Install Wrangler CLI
+npm install -g wrangler
+
+# Create wrangler.toml
+cat > wrangler.toml << EOF
+name = "perspectapi-sdk-demo"
+main = "docs/v1-deprecated/examples/cloudflare-worker.ts"
+compatibility_date = "2024-01-01"
+
+[vars]
+PERSPECT_API_URL = "https://your-api-instance.com"
+
+[[env.production.vars]]
+PERSPECT_API_KEY = "your-production-api-key"
+EOF
+
+# Deploy
+wrangler deploy
+```
+
+## Environment Variables
+
+All examples require these environment variables:
+
+```bash
+# Required
+PERSPECT_API_URL="https://your-perspectapi-instance.com"
+PERSPECT_SITE_NAME="your-site-name"
+
+# Authentication (choose one)
+PERSPECT_API_KEY="pk_your_api_key_here"
+# OR
+PERSPECT_JWT_TOKEN="your.jwt.token"
+
+# Optional
+PERSPECT_TIMEOUT="30000"  # Request timeout in milliseconds
+PERSPECT_RETRIES="3"      # Number of retry attempts
+```
+
+> **Note:** Site-scoped endpoints (content, products, contact) require a site name. In the snippets below, assume `const siteName = process.env.PERSPECT_SITE_NAME || 'your-site-name';`.
+
+## Common Patterns
+
+### Error Handling
+
+```typescript
+import { createApiError } from 'perspectapi-ts-sdk';
+
+try {
+  const content = await client.content.getContent();
+  console.log(content.data);
+} catch (error) {
+  const apiError = createApiError(error);
+  
+  if (apiError.status === 401) {
+    console.log('Authentication required');
+  } else if (apiError.status === 429) {
+    console.log('Rate limited, retry later');
+  } else {
+    console.error('API Error:', apiError.message);
+  }
+}
+```
+
+### Pagination
+
+```typescript
+// Get all content with pagination
+let page = 1;
+const allContent = [];
+
+while (true) {
+  const response = await client.content.getContent({
+    page,
+    limit: 50,
+    page_status: 'publish'
+  });
+  
+  if (!response.data || response.data.length === 0) {
+    break;
+  }
+  
+  allContent.push(...response.data);
+  page++;
+  
+  // Check if we've reached the last page
+  if (response.pagination && page > response.pagination.totalPages) {
+    break;
+  }
+}
+
+console.log(`Total content items: ${allContent.length}`);
+```
+
+### Batch Operations
+
+```typescript
+// Create multiple products
+const products = [
+  { name: 'Product 1', price: 29.99, currency: 'USD' },
+  { name: 'Product 2', price: 39.99, currency: 'USD' },
+  { name: 'Product 3', price: 49.99, currency: 'USD' }
+];
+
+const createdProducts = await Promise.all(
+  products.map(product => client.products.createProduct(product))
+);
+
+console.log(`Created ${createdProducts.length} products`);
+```
+
+### Dynamic Authentication
+
+```typescript
+// Initialize without auth
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com'
+});
+
+// Authenticate user
+const authResult = await client.auth.signIn({
+  email: 'user@example.com',
+  password: 'password'
+});
+
+// SDK automatically updates auth headers
+console.log('Authenticated as:', authResult.data?.user?.email);
+
+// Or manually set auth
+client.setAuth('your-jwt-token');
+client.setApiKey('your-api-key');
+
+// Clear auth when done
+client.clearAuth();
+```
+
+### Webhook Processing
+
+```typescript
+// Create webhook for Stripe events
+const webhook = await client.webhooks.createWebhook({
+  name: 'Stripe Payment Events',
+  url: 'https://myapp.com/webhooks/stripe',
+  provider: 'stripe',
+  events: [
+    'payment_intent.succeeded',
+    'payment_intent.payment_failed',
+    'customer.subscription.created'
+  ],
+  isActive: true
+});
+
+console.log('Webhook created:', webhook.data.id);
+
+// Test the webhook
+const testResult = await client.webhooks.testWebhook(webhook.data.id);
+console.log('Test result:', testResult.data);
+
+// Get webhook events
+const events = await client.webhooks.getWebhookEvents(webhook.data.id, {
+  status: 'failed',
+  limit: 10
+});
+
+console.log('Failed events:', events.data);
+```
+
+## Best Practices
+
+### 1. Environment-Specific Configuration
+
+```typescript
+const config = {
+  baseUrl: process.env.PERSPECT_API_URL!,
+  apiKey: process.env.PERSPECT_API_KEY,
+  timeout: process.env.NODE_ENV === 'production' ? 30000 : 60000,
+  retries: process.env.NODE_ENV === 'production' ? 3 : 1
+};
+
+const client = createPerspectApiClient(config);
+```
+
+### 2. Graceful Degradation
+
+```typescript
+async function getContentSafely() {
+  try {
+    const content = await client.content.getContent({ limit: 10 });
+    return content.data || [];
+  } catch (error) {
+    console.warn('Failed to fetch content, using fallback');
+    return []; // Return empty array as fallback
+  }
+}
+```
+
+### 3. Caching Responses
+
+```typescript
+const cache = new Map();
+
+async function getCachedContent(cacheKey: string) {
+  if (cache.has(cacheKey)) {
+    return cache.get(cacheKey);
+  }
+  
+  const content = await client.content.getContent();
+  cache.set(cacheKey, content.data);
+  
+  // Clear cache after 5 minutes
+  setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000);
+  
+  return content.data;
+}
+```
+
+### 4. Rate Limit Handling
+
+```typescript
+async function withRateLimit<T>(operation: () => Promise<T>): Promise<T> {
+  try {
+    return await operation();
+  } catch (error) {
+    const apiError = createApiError(error);
+    
+    if (apiError.status === 429) {
+      // Wait and retry after rate limit
+      const retryAfter = parseInt(apiError.details?.headers?.['retry-after'] || '60');
+      console.log(`Rate limited, waiting ${retryAfter} seconds...`);
+      
+      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
+      return await operation();
+    }
+    
+    throw error;
+  }
+}
+
+// Usage
+const content = await withRateLimit(() => 
+  client.content.getContent({ limit: 100 })
+);
+```
+
+## Testing
+
+Each example includes basic error handling and logging to help you understand the SDK behavior. For production use, implement proper error handling, logging, and monitoring based on your application's requirements.
+
+## Need Help?
+
+- 📖 [Main Documentation](../README.md)
+- 🐛 [Report Issues](https://github.com/perspectapi/perspectapi-ts-sdk/issues)
+- 💬 [Discussions](https://github.com/perspectapi/perspectapi-ts-sdk/discussions)

package/docs/v1-deprecated/examples/basic-usage.ts

@@ -0,0 +1,258 @@
+/**
+ * Basic usage examples for PerspectAPI TypeScript SDK
+ *
+ * @deprecated Historical v1 example. Do not copy into new code. v1 sunsets on
+ * 2026-06-01; use createPerspectApiV2Client from perspectapi-ts-sdk/v2.
+ */
+
+import { createPerspectApiClient } from '../../../src';
+
+// Initialize client
+const client = createPerspectApiClient({
+  baseUrl: 'https://your-perspectapi-instance.com',
+  apiKey: 'your-api-key'
+});
+
+async function basicExamples() {
+  try {
+    // 1. Health check
+    console.log('=== Health Check ===');
+    const health = await client.health();
+    console.log('API Status:', health.data);
+    const siteName = 'your-site-name';
+
+    // 2. Admin authentication (OTP-based, see site-user-checkout.ts for site user auth)
+    console.log('\n=== Authentication ===');
+    const csrfToken = await client.getCsrfToken();
+    console.log('CSRF token:', csrfToken.data);
+
+    // After OTP verification, set the JWT token:
+    // client.setAuth(jwtToken);
+
+    // 3. Get admin user profile (requires JWT)
+    // const profile = await client.auth.getUserProfile();
+    // console.log('User profile:', profile.data);
+
+    // 4. Content management
+    console.log('\n=== Content Management ===');
+    
+    // Get all content
+    const content = await client.content.getContent(siteName, {
+      page: 1,
+      limit: 5,
+      page_status: 'publish'
+    });
+    console.log('Published content:', content.data?.length, 'items');
+
+    // Create new content
+    const newContent = await client.content.createContent({
+      page_title: 'SDK Test Post',
+      page_content: '<p>This post was created using the TypeScript SDK!</p>',
+      content_markdown: '# SDK Test Post\n\nThis post was created using the TypeScript SDK!',
+      page_status: 'draft',
+      page_type: 'post',
+      slug: 'sdk-test-post'
+    });
+    console.log('Created content:', newContent.data?.id);
+
+    // Update content
+    if (newContent.data?.id) {
+      const updated = await client.content.updateContent(newContent.data.id, {
+        page_status: 'publish'
+      });
+      console.log('Published content:', updated.data?.pageTitle);
+    }
+
+    // Get individual content by slug (SEO-friendly)
+    try {
+      const blogPost = await client.content.getContentBySlug(siteName, 'sdk-test-post');
+      console.log('Retrieved by slug:', blogPost.data?.pageTitle);
+      console.log('Post type:', blogPost.data?.pageType);
+      console.log('Status:', blogPost.data?.pageStatus);
+    } catch (error) {
+      console.log('Content slug not found');
+    }
+
+    // Get content by ID
+    try {
+      const pageById = await client.content.getContentById(1);
+      console.log('Retrieved by ID:', pageById.data?.pageTitle);
+    } catch (error) {
+      console.log('Content ID not found');
+    }
+
+    // 5. Products
+    console.log('\n=== Products ===');
+    
+    // Get products
+    const products = await client.products.getProducts(siteName, {
+      page: 1,
+      limit: 5,
+      isActive: true
+    });
+    console.log('Active products:', products.data?.length, 'items');
+
+    // Create new product
+    const newProduct = await client.products.createProduct({
+      name: 'SDK Test Product',
+      description: 'A product created via the TypeScript SDK',
+      price: 29.99,
+      currency: 'USD',
+      sku: 'SDK-TEST-001',
+      isActive: true
+    });
+    console.log('Created product:', newProduct.data?.name);
+
+    // Get individual product by ID
+    try {
+      const singleProduct = await client.products.getProductById(123);
+      console.log('Product details:', singleProduct.data?.name);
+      console.log('Price:', singleProduct.data?.price);
+    } catch (error) {
+      console.log('Product not found');
+    }
+
+    // Get product by SKU
+    try {
+      const productBySku = await client.products.getProductBySku('PROD-001');
+      console.log('Product by SKU:', productBySku.data?.name);
+    } catch (error) {
+      console.log('Product SKU not found');
+    }
+
+    // Get product by slug and site name (NEW!)
+    try {
+      const productBySlug = await client.products.getProductBySlug(siteName, 'awesome-product');
+      console.log('Product by slug:', productBySlug.data?.name);
+      console.log('Product variants:', productBySlug.data?.variants?.length);
+    } catch (error) {
+      console.log('Product slug not found');
+    }
+
+    // Get products by category slug (new feature)
+    try {
+      const categoryProducts = await client.products.getProductsByCategorySlug(
+        siteName,
+        'electronics',
+        {
+          page: 1,
+          limit: 10,
+          published: true
+        }
+      );
+      console.log('Products in electronics category:', categoryProducts.data?.data.length);
+      console.log('Category info:', categoryProducts.data?.category);
+    } catch (error) {
+      console.log('No electronics category found or no products in category');
+    }
+
+    // 6. Organizations and Sites
+    console.log('\n=== Organizations & Sites ===');
+    
+    // Get organizations
+    const orgs = await client.organizations.getOrganizations();
+    console.log('Organizations:', orgs.data?.length, 'found');
+
+    // Get sites
+    const sites = await client.sites.getSites();
+    console.log('Sites:', sites.data?.length, 'found');
+
+    // 7. API Keys
+    console.log('\n=== API Keys ===');
+    
+    // Get API keys
+    const apiKeys = await client.apiKeys.getApiKeys();
+    console.log('API Keys:', apiKeys.data?.length, 'found');
+
+    // Create new API key
+    const newApiKey = await client.apiKeys.createApiKey({
+      name: 'SDK Test Key',
+      description: 'API key created via TypeScript SDK',
+      permissions: ['content:read', 'products:read']
+    });
+    console.log('Created API key:', newApiKey.data?.name);
+    console.log('Key value:', newApiKey.data?.key);
+
+    // 8. Categories
+    console.log('\n=== Categories ===');
+    
+    // Get categories
+    const categories = await client.categories.getCategories();
+    console.log('Categories:', categories.data?.length, 'found');
+
+    // Create new category
+    const newCategory = await client.categories.createCategory({
+      name: 'SDK Test Category',
+      slug: 'sdk-test-category',
+      description: 'A category created via the TypeScript SDK'
+    });
+    console.log('Created category:', newCategory.data?.name);
+
+    // Get product category by slug (NEW!)
+    try {
+      const productCategory = await client.categories.getProductCategoryBySlug(siteName, 'electronics');
+      console.log('Product category by slug:', productCategory.data?.name);
+    } catch (error) {
+      console.log('Product category slug not found');
+    }
+
+    // 9. Contact form submission
+    console.log('\n=== Contact Form ===');
+    
+    const contactSubmission = await client.contact.submitContact(siteName, {
+      name: 'SDK Test User',
+      email: 'test@example.com',
+      subject: 'SDK Test Message',
+      message: 'This is a test message submitted via the TypeScript SDK.'
+    });
+    console.log('Contact submitted:', contactSubmission.data?.id);
+
+    // 10. Webhooks
+    console.log('\n=== Webhooks ===');
+    
+    // Get webhooks
+    const webhooks = await client.webhooks.getWebhooks();
+    console.log('Webhooks:', webhooks.data?.length, 'found');
+
+    // Get supported providers
+    const providers = await client.webhooks.getWebhookProviders();
+    console.log('Supported providers:', providers.data?.map(p => p.name).join(', '));
+
+    // 11. Checkout & Payments
+    console.log('\n=== Checkout & Payments ===');
+    
+    // Create checkout session
+    try {
+      const checkoutSession = await client.checkout.createCheckoutSession({
+        priceId: 'price_test_123',
+        successUrl: 'https://example.com/success',
+        cancelUrl: 'https://example.com/cancel',
+        customerEmail: 'customer@example.com'
+      });
+      console.log('Checkout session created:', checkoutSession.data?.id);
+      console.log('Checkout URL:', checkoutSession.data?.url);
+    } catch (error) {
+      console.log('Failed to create checkout session');
+    }
+
+    // Get Stripe configuration
+    try {
+      const stripeConfig = await client.checkout.getStripePublishableKey();
+      console.log('Stripe mode:', stripeConfig.data?.mode);
+    } catch (error) {
+      console.log('Stripe not configured');
+    }
+
+    console.log('\n=== All examples completed successfully! ===');
+
+  } catch (error) {
+    console.error('Error in examples:', error);
+  }
+}
+
+// Run examples
+if (require.main === module) {
+  basicExamples();
+}
+
+export { basicExamples };