perspectapi-ts-sdk 1.1.1

package/src/loaders.ts

@@ -0,0 +1,644 @@
+/**
+ * High-level data loading helpers that wrap the PerspectAPI SDK clients.
+ * These helpers provide convenient product and content loading utilities with
+ * graceful fallbacks that can be reused across applications.
+ */
+
+import type { PerspectApiClient } from './perspect-api-client';
+import type {
+  ApiResponse,
+  MediaItem,
+  PaginatedResponse,
+  Product,
+  ProductQueryParams,
+  Content,
+  ContentStatus,
+  ContentType,
+  BlogPost,
+  CreateCheckoutSessionRequest,
+  CheckoutSession,
+  CheckoutMetadata
+} from './types';
+
+/**
+ * Logger interface so consumers can supply custom logging behaviour (or noop).
+ */
+export interface LoaderLogger {
+  debug?(...args: unknown[]): void;
+  info?(...args: unknown[]): void;
+  warn?(...args: unknown[]): void;
+  error?(...args: unknown[]): void;
+}
+
+const noopLogger: LoaderLogger = {};
+
+const log = (
+  logger: LoaderLogger | undefined,
+  level: keyof LoaderLogger,
+  ...args: unknown[]
+) => {
+  const target = logger?.[level];
+  if (typeof target === 'function') {
+    target(...args);
+  }
+};
+
+const isMediaItem = (value: unknown): value is MediaItem => {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  const media = value as Record<string, unknown>;
+  return typeof media.link === 'string' && typeof media.media_id === 'string';
+};
+
+const normalizeMediaList = (rawMedia: unknown): MediaItem[] => {
+  if (!Array.isArray(rawMedia)) {
+    return [];
+  }
+
+  if (rawMedia.length > 0 && Array.isArray(rawMedia[0])) {
+    return (rawMedia as unknown[])
+      .flat()
+      .filter(isMediaItem);
+  }
+
+  return (rawMedia as unknown[]).filter(isMediaItem);
+};
+
+const normalizeQueryParamList = (
+  value: string | number | Array<string | number> | undefined
+): string | undefined => {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const values = Array.isArray(value) ? value : [value];
+  const normalized = values
+    .map(item => String(item).trim())
+    .filter(item => item.length > 0);
+
+  return normalized.length > 0 ? normalized.join(',') : undefined;
+};
+
+/**
+ * Transform a PerspectAPI product payload into a friendlier shape for UI layers.
+ */
+export const transformProduct = (
+  perspectProduct: any,
+  logger?: LoaderLogger
+): Product => {
+  const rawProduct = perspectProduct ?? {};
+
+  const productId =
+    rawProduct.product_id ?? rawProduct.id ?? rawProduct.sku ?? 'unknown';
+  const productName =
+    rawProduct.product ?? rawProduct.name ?? rawProduct.title ?? 'Untitled';
+  const productSlug =
+    rawProduct.slug ??
+    rawProduct.product_slug ??
+    (productId ? `product-${productId}` : 'product');
+  const slugPrefix =
+    rawProduct.slug_prefix ?? rawProduct.slugPrefix ?? rawProduct.category ?? 'artwork';
+
+  const mediaItems = normalizeMediaList(rawProduct.media);
+  const primaryImage =
+    mediaItems[0]?.link ??
+    rawProduct.image ??
+    rawProduct.image_url ??
+    rawProduct.thumbnail ??
+    '';
+
+  log(logger, 'debug', '[PerspectAPI] Transform product', {
+    productId,
+    productSlug,
+    mediaCount: mediaItems.length
+  });
+
+  return {
+    id: typeof productId === 'string' ? productId : String(productId),
+    product: productName,
+    name: productName,
+    slug: productSlug,
+    slug_prefix: slugPrefix,
+    price: typeof rawProduct.price === 'number' ? rawProduct.price : Number(rawProduct.price ?? 0),
+    currency: rawProduct.currency ?? 'USD',
+    description: rawProduct.description ?? '',
+    description_markdown:
+      rawProduct.description_markdown ?? rawProduct.description ?? '',
+    image: primaryImage,
+    media: mediaItems,
+    gateway_product_id_live: rawProduct.gateway_product_id_live,
+    gateway_product_id_test: rawProduct.gateway_product_id_test,
+    stripe_product_id_live: rawProduct.stripe_product_id_live,
+    stripe_product_id_test: rawProduct.stripe_product_id_test,
+    isActive: rawProduct.isActive ?? rawProduct.is_active ?? true,
+    // Preserve original payload for advanced consumers
+    ...rawProduct
+  };
+};
+
+/**
+ * Transform PerspectAPI content payload to a simplified BlogPost structure.
+ */
+export const transformContent = (
+  perspectContent: Content | (Content & Record<string, unknown>)
+): BlogPost => {
+  const raw = perspectContent ?? ({} as Content);
+
+  return {
+    id: typeof raw.id === 'string' ? raw.id : String(raw.id ?? ''),
+    slug: raw.slug ?? `post-${raw.id ?? 'unknown'}`,
+    slug_prefix:
+      (raw as any).slug_prefix ??
+      (raw.pageType === 'post' ? 'blog' : 'page'),
+    page_type: raw.pageType,
+    title: raw.pageTitle,
+    content: raw.pageContent,
+    excerpt:
+      typeof raw.pageContent === 'string'
+        ? `${raw.pageContent.slice(0, 200)}...`
+        : undefined,
+    published: raw.pageStatus === 'publish',
+    created_at: raw.createdAt,
+    updated_at: raw.updatedAt,
+    description: (raw as any).description,
+    published_date: (raw as any).published_date,
+    author: (raw as any).author,
+    tags: (raw as any).tags,
+    image: (raw as any).image
+  };
+};
+
+const getDefaultFallbackProducts = (siteName: string): Product[] => {
+  const safeSite = siteName.replace(/\s+/g, '-').toLowerCase();
+
+  const mediaSamples: MediaItem[] = [
+    {
+      media_id: `${safeSite}-media-1`,
+      attachment_id: 1001,
+      file_name: 'sample-artwork-1.jpg',
+      link: 'https://picsum.photos/1200/800?random=1',
+      content_type: 'image/jpeg',
+      width: 1200,
+      height: 800,
+      filesize: 245760,
+      r2_key: `${safeSite}/artwork-1.jpg`,
+      site_name: siteName
+    },
+    {
+      media_id: `${safeSite}-media-2`,
+      attachment_id: 1002,
+      file_name: 'sample-artwork-2.jpg',
+      link: 'https://picsum.photos/1200/800?random=2',
+      content_type: 'image/jpeg',
+      width: 1200,
+      height: 800,
+      filesize: 312480,
+      r2_key: `${safeSite}/artwork-2.jpg`,
+      site_name: siteName
+    }
+  ];
+
+  return [
+    {
+      id: `${safeSite}-product-1`,
+      product: `${siteName} Sample Artwork 1`,
+      slug: `${safeSite}-sample-artwork-1`,
+      slug_prefix: 'artwork',
+      price: 299,
+      description: `Beautiful artwork from ${siteName}`,
+      description_markdown: `Beautiful artwork from **${siteName}**`,
+      image: 'https://picsum.photos/800/600?random=1',
+      media: mediaSamples
+    },
+    {
+      id: `${safeSite}-product-2`,
+      product: `${siteName} Sample Artwork 2`,
+      slug: `${safeSite}-sample-artwork-2`,
+      slug_prefix: 'artwork',
+      price: 499,
+      description: `Exquisite piece from ${siteName} collection`,
+      description_markdown: `Exquisite piece from **${siteName}** collection`,
+      image: 'https://picsum.photos/800/600?random=2',
+      media: mediaSamples
+    }
+  ];
+};
+
+const getDefaultFallbackPosts = (siteName: string): BlogPost[] => {
+  return [
+    {
+      id: `${siteName}-post-1`,
+      slug: 'welcome-post',
+      slug_prefix: 'blog',
+      page_type: 'post',
+      title: `Welcome to ${siteName}`,
+      content: `<p>Welcome to our ${siteName} blog. Here you'll find articles about art, culture, and our collections.</p>`,
+      excerpt: `Welcome to our ${siteName} blog.`,
+      published: true,
+      created_at: new Date().toISOString()
+    }
+  ];
+};
+
+export interface LoaderOptions {
+  /**
+   * Pre-configured PerspectAPI client. Pass null/undefined to force fallback behaviour.
+   */
+  client?: PerspectApiClient | null;
+  /**
+   * Site name used for API calls and fallback data generation.
+   */
+  siteName: string;
+  /**
+   * Optional logger to capture debug/warn/error output.
+   */
+  logger?: LoaderLogger;
+  /**
+   * Optional fallback datasets.
+   */
+  fallbackProducts?: Product[];
+  fallbackPosts?: BlogPost[];
+  /**
+   * Limit for list fetching (defaults to 100).
+   */
+  limit?: number;
+}
+
+export interface LoadProductsOptions extends LoaderOptions {
+  /**
+   * Optional search term applied server-side.
+   */
+  search?: string;
+  /**
+   * Offset for manual pagination.
+   */
+  offset?: number;
+  /**
+   * Filter products by category name (case-insensitive). Accepts a single name or multiple names.
+   */
+  category?: string | string[];
+  /**
+   * Filter products by category IDs (mixed string/number values supported).
+   */
+  categoryIds?: Array<number | string>;
+}
+
+const resolveFallbackProducts = (
+  { siteName, fallbackProducts }: Pick<LoaderOptions, 'siteName' | 'fallbackProducts'>
+): Product[] => {
+  if (fallbackProducts && fallbackProducts.length > 0) {
+    return fallbackProducts;
+  }
+  return getDefaultFallbackProducts(siteName);
+};
+
+const resolveFallbackPosts = (
+  { siteName, fallbackPosts }: Pick<LoaderOptions, 'siteName' | 'fallbackPosts'>
+): BlogPost[] => {
+  if (fallbackPosts && fallbackPosts.length > 0) {
+    return fallbackPosts;
+  }
+  return getDefaultFallbackPosts(siteName);
+};
+
+/**
+ * Load products for a site with graceful fallbacks.
+ */
+export async function loadProducts(options: LoadProductsOptions): Promise<Product[]> {
+  const {
+    client,
+    siteName,
+    logger = noopLogger,
+    fallbackProducts,
+    limit = 100,
+    offset,
+    search,
+    category,
+    categoryIds
+  } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, using fallback products');
+    return resolveFallbackProducts({ siteName, fallbackProducts });
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading products for site "${siteName}"`);
+    const queryParams: ProductQueryParams = {
+      isActive: true,
+      limit,
+      offset,
+      search
+    };
+
+    const normalizedCategory = normalizeQueryParamList(category as any);
+    if (normalizedCategory) {
+      queryParams.category = normalizedCategory;
+    }
+
+    const normalizedCategoryIds = normalizeQueryParamList(categoryIds);
+    if (normalizedCategoryIds) {
+      queryParams.category_id = normalizedCategoryIds;
+    }
+
+    const response: PaginatedResponse<Product> = await client.products.getProducts(siteName, queryParams);
+
+    if (!response.data) {
+      log(logger, 'warn', '[PerspectAPI] Products response missing data, returning fallback set');
+      return resolveFallbackProducts({ siteName, fallbackProducts });
+    }
+
+    log(logger, 'debug', `[PerspectAPI] Found ${response.data.length} products, transforming...`);
+    return response.data.map(product => transformProduct(product, logger));
+  } catch (error) {
+    log(logger, 'error', '[PerspectAPI] Error loading products', error);
+    return resolveFallbackProducts({ siteName, fallbackProducts });
+  }
+}
+
+export interface LoadProductBySlugOptions extends LoaderOptions {
+  slug: string;
+}
+
+/**
+ * Load single product by slug.
+ */
+export async function loadProductBySlug(
+  options: LoadProductBySlugOptions
+): Promise<Product | null> {
+  const {
+    client,
+    siteName,
+    slug,
+    logger = noopLogger,
+    fallbackProducts
+  } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, searching fallback products');
+    const fallback = resolveFallbackProducts({ siteName, fallbackProducts });
+    return fallback.find(product => product.slug === slug) ?? null;
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading product "${slug}" for site "${siteName}"`);
+    const response: ApiResponse<Product & { variants?: unknown[] }> =
+      await client.products.getProductBySlug(siteName, slug);
+
+    if (!response.data) {
+      log(logger, 'warn', `[PerspectAPI] Product not found for slug "${slug}"`);
+      return null;
+    }
+
+    return transformProduct(response.data, logger);
+  } catch (error) {
+    log(logger, 'error', `[PerspectAPI] Error loading product slug "${slug}"`, error);
+    return null;
+  }
+}
+
+export interface LoadContentOptions extends LoaderOptions {
+  /**
+    * Additional query parameters for content filtering.
+    */
+  params?: Partial<{
+    page_status: string;
+    page_type: string;
+    limit: number;
+    search: string;
+  }>;
+}
+
+/**
+ * Load published pages for a site.
+ */
+export async function loadPages(
+  options: LoadContentOptions
+): Promise<BlogPost[]> {
+  const { client, siteName, logger = noopLogger, params, fallbackPosts } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, using fallback posts for pages');
+    return resolveFallbackPosts({ siteName, fallbackPosts }).filter(
+      post => post.page_type !== 'post'
+    );
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading pages for site "${siteName}"`);
+    const response: PaginatedResponse<Content> = await client.content.getContent(
+      siteName,
+      {
+        ...params,
+        page_status: (params?.page_status ?? 'publish') as ContentStatus,
+        page_type: (params?.page_type ?? 'page') as ContentType,
+        limit: options.limit ?? params?.limit ?? 100
+      }
+    );
+
+    if (!response.data) {
+      return [];
+    }
+
+    return response.data.map(content => transformContent(content));
+  } catch (error) {
+    log(logger, 'error', '[PerspectAPI] Error loading pages', error);
+    return [];
+  }
+}
+
+/**
+ * Load published blog posts for a site.
+ */
+export async function loadPosts(
+  options: LoadContentOptions
+): Promise<BlogPost[]> {
+  const { client, siteName, logger = noopLogger, params, fallbackPosts } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, using fallback posts');
+    return resolveFallbackPosts({ siteName, fallbackPosts });
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading posts for site "${siteName}"`);
+    const response: PaginatedResponse<Content> = await client.content.getContent(
+      siteName,
+      {
+        ...params,
+        page_status: (params?.page_status ?? 'publish') as ContentStatus,
+        page_type: (params?.page_type ?? 'post') as ContentType,
+        limit: options.limit ?? params?.limit ?? 100
+      }
+    );
+
+    if (!response.data) {
+      log(logger, 'warn', '[PerspectAPI] Posts response missing data');
+      return [];
+    }
+
+    return response.data.map(content => transformContent(content));
+  } catch (error) {
+    log(logger, 'error', '[PerspectAPI] Error loading posts', error);
+    return [];
+  }
+}
+
+export interface LoadContentBySlugOptions extends LoaderOptions {
+  slug: string;
+}
+
+/**
+ * Load a single content item (post or page) by slug.
+ */
+export async function loadContentBySlug(
+  options: LoadContentBySlugOptions
+): Promise<BlogPost | null> {
+  const {
+    client,
+    siteName,
+    slug,
+    logger = noopLogger,
+    fallbackPosts
+  } = options;
+
+  if (!client) {
+    log(logger, 'warn', '[PerspectAPI] No client configured, searching fallback posts');
+    const fallback = resolveFallbackPosts({ siteName, fallbackPosts });
+    return fallback.find(post => post.slug === slug) ?? null;
+  }
+
+  try {
+    log(logger, 'info', `[PerspectAPI] Loading content slug "${slug}" for site "${siteName}"`);
+    const response: ApiResponse<Content> =
+      await client.content.getContentBySlug(siteName, slug);
+
+    if (!response.data) {
+      log(logger, 'warn', `[PerspectAPI] Content not found for slug "${slug}"`);
+      return null;
+    }
+
+    return transformContent(response.data);
+  } catch (error) {
+    log(logger, 'error', `[PerspectAPI] Error loading content slug "${slug}"`, error);
+    return null;
+  }
+}
+
+/**
+ * Load all published content (pages + posts).
+ */
+export async function loadAllContent(
+  options: LoaderOptions
+): Promise<BlogPost[]> {
+  const { logger = noopLogger } = options;
+
+  const [pages, posts] = await Promise.all([
+    loadPages(options),
+    loadPosts(options)
+  ]);
+
+  log(logger, 'debug', `[PerspectAPI] Loaded ${pages.length + posts.length} total content items`);
+  return [...pages, ...posts];
+}
+
+export interface CheckoutSessionOptions {
+  client?: PerspectApiClient | null;
+  siteName: string;
+  items: Array<{ productId: string; quantity: number }>;
+  successUrl: string;
+  cancelUrl: string;
+  customerEmail?: string;
+  mode?: 'live' | 'test';
+  logger?: LoaderLogger;
+  fallbackProducts?: Product[];
+  metadata?: CheckoutMetadata;
+  /**
+   * Optional resolver to convert a product record into a Stripe price ID.
+   */
+  priceIdResolver?: (product: Product, mode: 'live' | 'test') => string | undefined;
+}
+
+/**
+ * Convenience helper that creates a checkout session by looking up Stripe price IDs
+ * from product metadata. Falls back to gateway price IDs if Stripe IDs are missing.
+ */
+export async function createCheckoutSession(
+  options: CheckoutSessionOptions
+): Promise<ApiResponse<CheckoutSession> | { error: string }> {
+  const {
+    client,
+    siteName,
+    items,
+    successUrl,
+    cancelUrl,
+    customerEmail,
+    mode = 'live',
+    logger = noopLogger,
+    fallbackProducts,
+    metadata,
+    priceIdResolver
+  } = options;
+
+  if (!client) {
+    log(logger, 'error', '[PerspectAPI] Cannot create checkout session without SDK client');
+    return { error: 'PerspectAPI client not configured' };
+  }
+
+  try {
+    // Fetch active products to build price map
+    const products = await loadProducts({
+      client,
+      siteName,
+      logger,
+      limit: 200,
+      fallbackProducts
+    });
+
+    const productMap = new Map<string, Product>(
+      products.map(product => [String(product.id), product])
+    );
+
+    const line_items = items.map(item => {
+      const product = productMap.get(String(item.productId));
+
+      if (!product) {
+        throw new Error(`Product ${item.productId} not found while building checkout session`);
+      }
+
+      const resolvedPrice =
+        priceIdResolver?.(product, mode) ??
+        (mode === 'test'
+          ? product.stripe_product_id_test ?? (product as any).gateway_product_id_test
+          : product.stripe_product_id_live ?? (product as any).gateway_product_id_live);
+
+      if (!resolvedPrice) {
+        throw new Error(`Missing Stripe price ID for product ${item.productId} (${product.product ?? product.name ?? 'unknown'})`);
+      }
+
+      return {
+        price: resolvedPrice,
+        quantity: item.quantity
+      };
+    });
+
+    const checkoutData: CreateCheckoutSessionRequest = {
+      line_items,
+      successUrl,
+      cancelUrl,
+      success_url: successUrl,
+      cancel_url: cancelUrl,
+      customerEmail,
+      customer_email: customerEmail,
+      mode: mode === 'test' ? 'payment' : 'payment',
+      metadata
+    };
+
+    log(logger, 'info', '[PerspectAPI] Creating checkout session');
+    return client.checkout.createCheckoutSession(siteName, checkoutData);
+  } catch (error) {
+    log(logger, 'error', '[PerspectAPI] Failed to create checkout session', error);
+    return { error: error instanceof Error ? error.message : 'Unknown error creating checkout session' };
+  }
+}