perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/examples/site-user-checkout.ts

@@ -0,0 +1,186 @@
+/**
+ * Site User Profile & Checkout Prefill
+ *
+ * @deprecated Historical v1 example. Do not copy into new code. v1 sunsets on
+ * 2026-06-01; use createPerspectApiV2Client from perspectapi-ts-sdk/v2.
+ *
+ * Shows how to:
+ * 1. Authenticate a site user via OTP
+ * 2. Read and write profile data (shipping address, phone, etc.)
+ * 3. Create a checkout session that prefills Stripe with the user's details
+ */
+
+import { createPerspectApiClient } from '../../../src';
+
+const SITE_NAME = 'my-store';
+
+// The SDK needs both an API key (for checkout) and a site user JWT (for profile).
+// In a real app the API key lives server-side and the JWT is set after OTP login.
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.perspect.commm',
+  apiKey: 'pk_live_xxx',
+});
+
+// ---------------------------------------------------------------------------
+// 1. OTP Authentication
+// ---------------------------------------------------------------------------
+
+async function loginSiteUser(email: string, otpCode: string) {
+  // Request the OTP (sends an email with a 6-digit code)
+  await client.siteUsers.requestOtp(SITE_NAME, { email });
+
+  // Verify the code and set the JWT on the client in one call
+  const { data } = await client.siteUsers.verifyOtpAndSetAuth(SITE_NAME, {
+    email,
+    code: otpCode,
+  });
+
+  // data.user.id is the site_user_id you'll pass to checkout later
+  console.log('Logged in as', data.user.email, '— id:', data.user.id);
+  return data.user;
+}
+
+// ---------------------------------------------------------------------------
+// 2. Profile: Read & Write
+// ---------------------------------------------------------------------------
+
+async function showProfile() {
+  const { data } = await client.siteUsers.getMe(SITE_NAME);
+
+  console.log('Name:', data.user.first_name, data.user.last_name);
+  console.log('Email:', data.user.email);
+  console.log('Profile keys:', Object.keys(data.profile));
+
+  return data;
+}
+
+async function saveShippingAddress(address: {
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  postal_code: string;
+  country: string;
+}) {
+  // Profile values are stored as strings. Serialize objects as JSON.
+  await client.siteUsers.setProfileValue(
+    SITE_NAME,
+    'shipping_address',
+    JSON.stringify(address),
+  );
+}
+
+async function getShippingAddress() {
+  const { data } = await client.siteUsers.getProfile(SITE_NAME);
+  const raw = data.profile['shipping_address'];
+  if (!raw) return null;
+  return JSON.parse(raw.value);
+}
+
+async function savePhone(phone: string) {
+  await client.siteUsers.setProfileValue(SITE_NAME, 'phone', phone);
+}
+
+// ---------------------------------------------------------------------------
+// 3. Checkout with Prefill
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a checkout session for the logged-in site user.
+ *
+ * Passing `site_user_id` tells the backend to create (or reuse) a gateway
+ * customer object. Stripe then prefills the checkout page with the
+ * customer's email, name, saved addresses, and payment methods.
+ *
+ * On the first checkout a new Stripe Customer is created automatically.
+ * Subsequent checkouts reuse the same Customer, so returning buyers see
+ * their saved details without re-entering anything.
+ */
+async function createCheckout(siteUserId: string) {
+  const { data: session } = await client.checkout.createCheckoutSession(
+    SITE_NAME,
+    {
+      line_items: [
+        { price: 'prod_abc123', quantity: 1 },
+      ],
+      success_url: 'https://my-store.com/thank-you',
+      cancel_url: 'https://my-store.com/cart',
+      site_user_id: siteUserId,
+    },
+  );
+
+  console.log('Checkout URL:', session.url);
+  return session;
+}
+
+/**
+ * Checkout with a variant product (SKU).
+ */
+async function createVariantCheckout(siteUserId: string) {
+  const { data: session } = await client.checkout.createCheckoutSession(
+    SITE_NAME,
+    {
+      line_items: [
+        { sku_id: 42, quantity: 2 },
+      ],
+      success_url: 'https://my-store.com/thank-you',
+      cancel_url: 'https://my-store.com/cart',
+      site_user_id: siteUserId,
+    },
+  );
+
+  console.log('Variant checkout URL:', session.url);
+  return session;
+}
+
+// ---------------------------------------------------------------------------
+// 4. Order History
+// ---------------------------------------------------------------------------
+
+async function showOrders() {
+  const { data } = await client.siteUsers.getOrders(SITE_NAME);
+
+  for (const order of data.orders) {
+    console.log(
+      `${order.order_id ?? order.session_id}  ${order.currency.toUpperCase()} ${(order.amount_total / 100).toFixed(2)}  ${order.status}`,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Full flow
+// ---------------------------------------------------------------------------
+
+async function main() {
+  // Step 1 — Log in (in a real app the code comes from the user's email)
+  const user = await loginSiteUser('jane@example.com', '123456');
+
+  // Step 2 — Save profile data (only needed once; persists across sessions)
+  await client.siteUsers.updateMe(SITE_NAME, {
+    first_name: 'Jane',
+    last_name: 'Doe',
+  });
+
+  await saveShippingAddress({
+    line1: '123 Main St',
+    city: 'Portland',
+    state: 'OR',
+    postal_code: '97201',
+    country: 'US',
+  });
+
+  await savePhone('+15035551234');
+
+  // Step 3 — Read it back
+  await showProfile();
+  const address = await getShippingAddress();
+  console.log('Saved shipping address:', address);
+
+  // Step 4 — Create a checkout session (Stripe prefills from the gateway customer)
+  await createCheckout(user.id);
+
+  // Step 5 — After purchase, view order history
+  await showOrders();
+}
+
+main();

package/docs/v1-deprecated/examples/slug-prefix-examples.ts

@@ -0,0 +1,491 @@
+/**
+ * Examples demonstrating slug_prefix filtering with perspectapi-ts-sdk
+ *
+ * @deprecated Historical v1 example. Do not copy into new code. v1 sunsets on
+ * 2026-06-01; use createPerspectApiV2Client from perspectapi-ts-sdk/v2.
+ * 
+ * These examples show how to use the slug_prefix parameter to filter
+ * content and products by their URL prefix.
+ */
+
+import { createPerspectApiClient } from '../../../src';
+
+// Initialize the client
+const client = createPerspectApiClient({
+  baseUrl: 'https://api.example.com',
+  apiKey: 'your-api-key-here'
+});
+
+const siteName = 'mysite';
+
+/**
+ * CONTENT FILTERING EXAMPLES
+ */
+
+// Example 1: Get all blog posts
+async function getBlogPosts() {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    page_status: 'publish',
+    page_type: 'post',
+    page: 1,
+    limit: 20
+  });
+
+  console.log('Blog Posts:', response.data);
+  console.log('Total:', response.pagination?.total);
+  // URLs will be: /blog/post-1, /blog/post-2, etc.
+}
+
+// Example 2: Get all news articles
+async function getNewsArticles() {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'news',
+    page_status: 'publish',
+    page: 1,
+    limit: 10
+  });
+
+  console.log('News Articles:', response.data);
+  // URLs will be: /news/article-1, /news/article-2, etc.
+}
+
+// Example 3: Get documentation pages
+async function getDocumentation() {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'docs',
+    page_type: 'page',
+    page_status: 'publish'
+  });
+
+  console.log('Documentation Pages:', response.data);
+  // URLs will be: /docs/getting-started, /docs/api-reference, etc.
+}
+
+// Example 4: Search within blog posts only
+async function searchBlogPosts(searchTerm: string) {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    search: searchTerm,
+    page_status: 'publish'
+  });
+
+  console.log(`Blog posts matching "${searchTerm}":`, response.data);
+}
+
+// Example 5: Get draft blog posts (for admin)
+async function getDraftBlogPosts() {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    page_status: 'draft',
+    page_type: 'post'
+  });
+
+  console.log('Draft Blog Posts:', response.data);
+}
+
+// Example 6: Get blog posts by specific author
+async function getBlogPostsByAuthor(userId: number) {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    user_id: userId,
+    page_status: 'publish'
+  });
+
+  console.log(`Blog posts by user ${userId}:`, response.data);
+}
+
+/**
+ * PRODUCT FILTERING EXAMPLES
+ */
+
+// Example 7: Get all shop products
+async function getShopProducts() {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'shop',
+    isActive: true,
+    page: 1,
+    limit: 20
+  });
+
+  console.log('Shop Products:', response.data);
+  // URLs will be: /shop/product-1, /shop/product-2, etc.
+}
+
+// Example 8: Get artwork products
+async function getArtworkProducts() {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'artwork',
+    isActive: true
+  });
+
+  console.log('Artwork Products:', response.data);
+  // URLs will be: /artwork/painting-1, /artwork/sculpture-1, etc.
+}
+
+// Example 9: Search within shop products only
+async function searchShopProducts(searchTerm: string) {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'shop',
+    search: searchTerm,
+    isActive: true
+  });
+
+  console.log(`Shop products matching "${searchTerm}":`, response.data);
+}
+
+// Example 10: Get shop products in specific category
+async function getShopProductsByCategory(categorySlug: string) {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'shop',
+    category: categorySlug,
+    isActive: true
+  });
+
+  console.log(`Shop products in ${categorySlug}:`, response.data);
+}
+
+// Example 11: Get shop electronics
+async function getShopElectronics() {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'shop',
+    category: 'electronics',
+    isActive: true,
+    page: 1,
+    limit: 50
+  });
+
+  console.log('Shop Electronics:', response.data);
+}
+
+// Example 12: Get premium products (different prefix)
+async function getPremiumProducts() {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: 'premium',
+    isActive: true
+  });
+
+  console.log('Premium Products:', response.data);
+  // URLs will be: /premium/product-1, /premium/product-2, etc.
+}
+
+/**
+ * ADVANCED FILTERING EXAMPLES
+ */
+
+// Example 13: Multi-section content aggregation
+async function getRecentContentFromAllSections() {
+  // Get recent posts from different sections
+  const [blogPosts, newsArticles, guides] = await Promise.all([
+    client.content.getContent(siteName, {
+      slug_prefix: 'blog',
+      page_status: 'publish',
+      limit: 5
+    }),
+    client.content.getContent(siteName, {
+      slug_prefix: 'news',
+      page_status: 'publish',
+      limit: 5
+    }),
+    client.content.getContent(siteName, {
+      slug_prefix: 'guides',
+      page_status: 'publish',
+      limit: 5
+    })
+  ]);
+
+  return {
+    blog: blogPosts.data || [],
+    news: newsArticles.data || [],
+    guides: guides.data || []
+  };
+}
+
+// Example 14: Product catalog organization
+async function getProductCatalog() {
+  // Get products from different sections
+  const [shopProducts, artworks, services] = await Promise.all([
+    client.products.getProducts(siteName, {
+      slug_prefix: 'shop',
+      isActive: true,
+      limit: 20
+    }),
+    client.products.getProducts(siteName, {
+      slug_prefix: 'artwork',
+      isActive: true,
+      limit: 20
+    }),
+    client.products.getProducts(siteName, {
+      slug_prefix: 'services',
+      isActive: true,
+      limit: 20
+    })
+  ]);
+
+  return {
+    shop: shopProducts.data || [],
+    artwork: artworks.data || [],
+    services: services.data || []
+  };
+}
+
+// Example 15: Paginated blog listing
+async function getPaginatedBlogPosts(page: number = 1, limit: number = 20) {
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    page_status: 'publish',
+    page_type: 'post',
+    page,
+    limit
+  });
+
+  return {
+    posts: response.data,
+    currentPage: page,
+    totalPages: response.pagination?.totalPages || 0,
+    totalPosts: response.pagination?.total || 0,
+    hasNextPage: page < (response.pagination?.totalPages || 0),
+    hasPrevPage: page > 1
+  };
+}
+
+// Example 16: Search across specific product categories with prefix
+async function searchProductsInSection(
+  prefix: string,
+  searchTerm: string,
+  category?: string
+) {
+  const response = await client.products.getProducts(siteName, {
+    slug_prefix: prefix,
+    search: searchTerm,
+    category: category,
+    isActive: true
+  });
+
+  return response.data;
+}
+
+/**
+ * REAL-WORLD USE CASES
+ */
+
+// Example 17: Blog homepage - recent posts
+async function getBlogHomepage() {
+  const recentPosts = await client.content.getContent(siteName, {
+    slug_prefix: 'blog',
+    page_status: 'publish',
+    page_type: 'post',
+    limit: 10
+  });
+
+  return {
+    title: 'Blog',
+    posts: recentPosts.data || [],
+    total: recentPosts.pagination?.total
+  };
+}
+
+// Example 18: Shop homepage - featured products
+async function getShopHomepage() {
+  const products = await client.products.getProducts(siteName, {
+    slug_prefix: 'shop',
+    isActive: true,
+    limit: 12
+  });
+
+  return {
+    title: 'Shop',
+    products: products.data || []
+  };
+}
+
+// Example 19: Documentation site structure
+async function getDocumentationStructure() {
+  const [gettingStarted, apiDocs, guides, tutorials] = await Promise.all([
+    client.content.getContent(siteName, {
+      slug_prefix: 'docs',
+      search: 'getting started',
+      page_status: 'publish'
+    }),
+    client.content.getContent(siteName, {
+      slug_prefix: 'api',
+      page_status: 'publish'
+    }),
+    client.content.getContent(siteName, {
+      slug_prefix: 'guides',
+      page_status: 'publish'
+    }),
+    client.content.getContent(siteName, {
+      slug_prefix: 'tutorials',
+      page_status: 'publish'
+    })
+  ]);
+
+  return {
+    gettingStarted: gettingStarted.data || [],
+    api: apiDocs.data || [],
+    guides: guides.data || [],
+    tutorials: tutorials.data || []
+  };
+}
+
+// Example 20: E-commerce with multiple product types
+async function getEcommerceProducts() {
+  const [physical, digital, services, subscriptions] = await Promise.all([
+    client.products.getProducts(siteName, {
+      slug_prefix: 'shop',
+      isActive: true
+    }),
+    client.products.getProducts(siteName, {
+      slug_prefix: 'downloads',
+      isActive: true
+    }),
+    client.products.getProducts(siteName, {
+      slug_prefix: 'services',
+      isActive: true
+    }),
+    client.products.getProducts(siteName, {
+      slug_prefix: 'subscriptions',
+      isActive: true
+    })
+  ]);
+
+  return {
+    physical: physical.data || [],
+    digital: digital.data || [],
+    services: services.data || [],
+    subscriptions: subscriptions.data || []
+  };
+}
+
+/**
+ * UTILITY FUNCTIONS
+ */
+
+// Example 21: Get all available slug prefixes (for debugging)
+async function getAvailableContentPrefixes() {
+  const allContent = await client.content.getContent(siteName, {
+    limit: 100
+  });
+
+  const prefixes = new Set(
+    (allContent.data || [])
+      .map(item => item.slug_prefix)
+      .filter(prefix => prefix !== null && prefix !== undefined)
+  );
+
+  return Array.from(prefixes);
+}
+
+// Example 22: Get all available product prefixes (for debugging)
+async function getAvailableProductPrefixes() {
+  const allProducts = await client.products.getProducts(siteName, {
+    limit: 100
+  });
+
+  const prefixes = new Set(
+    (allProducts.data || [])
+      .map(item => item.slug_prefix)
+      .filter(prefix => prefix !== null && prefix !== undefined)
+  );
+
+  return Array.from(prefixes);
+}
+
+/**
+ * ERROR HANDLING EXAMPLES
+ */
+
+// Example 23: Handle no results gracefully
+async function safeGetBlogPosts() {
+  try {
+    const response = await client.content.getContent(siteName, {
+      slug_prefix: 'blog',
+      page_status: 'publish'
+    });
+
+    if (!response.data || response.data.length === 0) {
+      console.log('No blog posts found');
+      return [];
+    }
+
+    return response.data;
+  } catch (error) {
+    console.error('Error fetching blog posts:', error);
+    return [];
+  }
+}
+
+// Example 24: Validate prefix exists before querying
+async function getContentByPrefix(prefix: string) {
+  const availablePrefixes = await getAvailableContentPrefixes();
+  
+  if (!availablePrefixes.includes(prefix)) {
+    console.warn(`Prefix "${prefix}" not found. Available: ${availablePrefixes.join(', ')}`);
+    return [];
+  }
+
+  const response = await client.content.getContent(siteName, {
+    slug_prefix: prefix,
+    page_status: 'publish'
+  });
+
+  return response.data;
+}
+
+/**
+ * EXPORT ALL EXAMPLES
+ */
+export {
+  // Content examples
+  getBlogPosts,
+  getNewsArticles,
+  getDocumentation,
+  searchBlogPosts,
+  getDraftBlogPosts,
+  getBlogPostsByAuthor,
+  
+  // Product examples
+  getShopProducts,
+  getArtworkProducts,
+  searchShopProducts,
+  getShopProductsByCategory,
+  getShopElectronics,
+  getPremiumProducts,
+  
+  // Advanced examples
+  getRecentContentFromAllSections,
+  getProductCatalog,
+  getPaginatedBlogPosts,
+  searchProductsInSection,
+  
+  // Real-world use cases
+  getBlogHomepage,
+  getShopHomepage,
+  getDocumentationStructure,
+  getEcommerceProducts,
+  
+  // Utility functions
+  getAvailableContentPrefixes,
+  getAvailableProductPrefixes,
+  
+  // Error handling
+  safeGetBlogPosts,
+  getContentByPrefix
+};
+
+/**
+ * USAGE NOTES:
+ * 
+ * 1. The slug_prefix parameter is optional - omit it to get all content/products
+ * 2. slug_prefix performs exact match (case-sensitive)
+ * 3. Combine slug_prefix with other filters for precise queries
+ * 4. Use consistent naming: 'blog', 'news', 'shop', 'artwork' (lowercase)
+ * 5. Plan your URL structure before setting prefixes
+ * 
+ * URL STRUCTURE EXAMPLES:
+ * - slug_prefix: 'blog', slug: 'my-post' → /blog/my-post
+ * - slug_prefix: 'shop', slug: 'laptop' → /shop/laptop
+ * - slug_prefix: 'artwork', slug: 'painting' → /artwork/painting
+ * - slug_prefix: null, slug: 'about' → /about
+ */