perspectapi-ts-sdk 6.5.9 → 7.0.0

package/docs/v1-deprecated/legacy-docs/loaders.md

@@ -0,0 +1,304 @@
+# High-Level Loader Helpers
+
+> Deprecated v1 material. Do not copy these examples into new code. v1 sunsets
+> on 2026-06-01; use `createPerspectApiV2Client` from
+> `perspectapi-ts-sdk/v2` and `/api/v2`.
+
+This guide dives into the higher-level helpers exported from `perspectapi-ts-sdk/src/loaders.ts`. They provide a batteries‑included experience for common content and commerce use cases while still working nicely with Remix, Next.js, Cloudflare Workers, or any node/edge runtime.
+
+## Table of Contents
+
+1. [Core Concepts](#core-concepts)
+2. [Basic Usage](#basic-usage)
+3. [Server Framework Examples](#server-framework-examples)
+   - [Remix/Express Route](#remixexpress-route)
+   - [Next.js App Route (Edge)](#nextjs-app-route-edge)
+   - [Cloudflare Worker](#cloudflare-worker)
+4. [Fallback Data Strategies](#fallback-data-strategies)
+5. [Custom Logging](#custom-logging)
+6. [Creating Checkout Sessions](#creating-checkout-sessions)
+7. [Type Reference](#type-reference)
+
+---
+
+## Core Concepts
+
+- **Shared Options** – Every loader accepts a `LoaderOptions` object (`client`, `siteName`, optional `logger`, optional fallbacks, optional `limit`).
+- **Normalised Types** – Returned objects use the SDK’s `Product`, `MediaItem`, and `BlogPost` types, which flatten nested media arrays and expose Stripe/Gateway identifiers when present.
+- **Graceful Fallbacks** – When no PerspectAPI client is provided (or an API call fails), the helpers can emit sample data so your UI keeps rendering during local development.
+- **Checkout Helper** – `createCheckoutSession` converts cart line items into Stripe price IDs (live/test aware) before hitting PerspectAPI’s checkout endpoint.
+
+```typescript
+import {
+  loadProducts,
+  loadProductBySlug,
+  loadPosts,
+  loadPages,
+  loadAllContent,
+  loadContentBySlug,
+  createCheckoutSession,
+  type LoaderOptions
+} from 'perspectapi-ts-sdk';
+```
+
+## Basic Usage
+
+```typescript
+import { createPerspectApiClient, loadProducts } from 'perspectapi-ts-sdk';
+
+const client = createPerspectApiClient({
+  baseUrl: process.env.PERSPECTAPI_BASE_URL!,
+  apiKey: process.env.PERSPECTAPI_API_KEY!
+});
+
+const options: LoaderOptions = {
+  client,
+  siteName: 'museum-indian-art'
+};
+
+const products = await loadProducts(options);
+console.log(products[0].product, products[0].media?.[0]);
+```
+
+## Server Framework Examples
+
+### Remix/Express Route
+
+```typescript
+// app/routes/api/products.ts
+import { json } from '@remix-run/node';
+import {
+  loadProducts,
+  type LoaderOptions
+} from 'perspectapi-ts-sdk';
+
+export async function loader() {
+  const options: LoaderOptions = {
+    client: createPerspectApiClient({
+      baseUrl: process.env.PERSPECTAPI_BASE_URL!,
+      apiKey: process.env.PERSPECTAPI_API_KEY!
+    }),
+    siteName: process.env.PERSPECTAPI_SITE_NAME ?? 'museum-indian-art'
+  };
+
+  const products = await loadProducts(options);
+  return json(products);
+}
+```
+
+### Next.js App Route (Edge)
+
+```typescript
+// app/api/products/route.ts
+import {
+  loadProducts,
+  type LoaderOptions
+} from 'perspectapi-ts-sdk';
+
+export const runtime = 'edge';
+
+export async function GET() {
+  const options: LoaderOptions = {
+    client: createPerspectApiClient({
+      baseUrl: process.env.PERSPECTAPI_BASE_URL!,
+      apiKey: process.env.PERSPECTAPI_API_KEY!
+    }),
+    siteName: process.env.PERSPECTAPI_SITE_NAME ?? 'museum-indian-art'
+  };
+
+  const products = await loadProducts(options);
+  return Response.json(products);
+}
+```
+
+### Cloudflare Worker
+
+```typescript
+import {
+  createPerspectApiClient,
+  loadPosts
+} from 'perspectapi-ts-sdk';
+
+export default {
+  async fetch(_request: Request, env: Env) {
+    const client = createPerspectApiClient({
+      baseUrl: env.PERSPECTAPI_BASE_URL,
+      apiKey: env.PERSPECTAPI_API_KEY
+    });
+
+    const posts = await loadPosts({
+      client,
+      siteName: env.PERSPECTAPI_SITE_NAME ?? 'museum-indian-art',
+      logger: env.ENVIRONMENT === 'dev' ? console : undefined
+    });
+
+    return new Response(JSON.stringify(posts), {
+      headers: { 'content-type': 'application/json' }
+    });
+  }
+};
+```
+
+## Fallback Data Strategies
+
+If PerspectAPI credentials are missing (for example, in Storybook or local prototyping), omitting the `client` will trigger the built-in sample data:
+
+```typescript
+const products = await loadProducts({
+  client: null,
+  siteName: 'Demo Site'
+});
+```
+
+You can also provide your own mock datasets:
+
+```typescript
+const fallbackProducts = [
+  {
+    id: 'demo-1',
+    product: 'Placeholder Canvas',
+    price: 199,
+    slug: 'placeholder-canvas',
+    media: [{ media_id: 'm-1', link: 'https://picsum.photos/800/600', attachment_id: 1 }]
+  }
+];
+
+const products = await loadProducts({
+  client: null,
+  siteName: 'Demo Site',
+  fallbackProducts
+});
+```
+
+## Custom Logging
+
+All loaders accept an optional `logger` implementing `LoaderLogger`. Supplying `console` is enough during development:
+
+```typescript
+const options = {
+  client,
+  siteName: 'museum-indian-art',
+  logger: {
+    info: (...args) => myLogger.info('perspectapi', ...args),
+    warn: (...args) => myLogger.warn('perspectapi', ...args),
+    error: (...args) => myLogger.error('perspectapi', ...args)
+  }
+};
+```
+
+Every helper emits consistent messages (e.g. `[PerspectAPI] Loading products…`, `[PerspectAPI] Error loading posts`) that flow through your custom logger.
+
+## Filtering Products
+
+`loadProducts` accepts optional `search`, `category`, `categoryIds`, and `offset` fields. `category` can be a single display name, a comma-separated string, or an array of names. `categoryIds` accepts one or many numeric/string IDs. PerspectAPI resolves every supplied value before filtering, so callers never need to hard-code IDs. Use `offset` when you want manual pagination instead of the default page-based flow.
+
+```typescript
+const decorPillows = await loadProducts({
+  ...options,
+  category: ['Home Decor', 'Kitchen Essentials'],
+  categoryIds: [12, '18'],
+  offset: 24,
+  search: 'pillow',
+  limit: 12
+});
+```
+
+You can mix categories by name and ID in the same call; the API returns any product that belongs to at least one of the requested categories. If none of the provided names resolve (and no IDs are supplied), the API responds with `success: true` and an empty data array, giving you a clean signal to fall back or show alternative content.
+
+## Creating Checkout Sessions
+
+`createCheckoutSession` accepts cart items keyed by product ID. The helper resolves Stripe price IDs by checking live/test fields on each product:
+
+```typescript
+const checkout = await createCheckoutSession({
+  client,
+  siteName: 'museum-indian-art',
+  items: [
+    { productId: products[0].id, quantity: 1 },
+    { productId: products[1].id, quantity: 2 }
+  ],
+  successUrl: 'https://example.com/success',
+  cancelUrl: 'https://example.com/cancel',
+  customerEmail: 'customer@example.com',
+  currency: 'usd',
+  shippingAmount: 500,
+  shippingAddress: {
+    country: 'US',
+    state: 'CA',
+    postal_code: '94110'
+  },
+  billingAddress: {
+    country: 'US',
+    state: 'CA',
+    postal_code: '94110'
+  },
+  mode: 'test', // optional, defaults to 'live'
+  metadata: {
+    orderRef: 'web-2024-00042',
+    giftWrap: true,
+    shippingOverride: {
+      method: 'courier',
+      window: '5-7pm'
+    }
+  }
+});
+
+if ('error' in checkout) {
+  throw new Error(checkout.error);
+}
+
+console.log(checkout.data?.url); // Stripe-hosted checkout URL
+```
+
+Metadata values can be strings, numbers, booleans, arrays, or nested objects—the SDK forwards them as-is and PerspectAPI handles normalization before sending them to Stripe.
+
+When `shippingAmount`, `shippingAddress`, or `billingAddress` are provided, the helper mirrors them into both camelCase and snake_case fields so the PerspectAPI checkout endpoint receives the correct payload. Optional tax configuration (`CheckoutTaxRequest`) is also forwarded, including customer exemption claims, so the new tax engine can pre-compute totals before redirecting to Stripe.
+
+### Custom Price Resolution
+
+If you store Stripe price IDs elsewhere, supply a resolver:
+
+```typescript
+await createCheckoutSession({
+  ...options,
+  items,
+  priceIdResolver: (product, mode) => {
+    return mode === 'test'
+      ? product.metadata?.test_price_id
+      : product.metadata?.live_price_id;
+  },
+  successUrl,
+  cancelUrl
+});
+```
+
+## Type Reference
+
+- `Product` now includes optional `product`, `name`, `slug`, `slug_prefix`, media arrays, and Stripe/Gateway identifiers.
+- `MediaItem` describes the flattened media structure (ID, link, dimensions, etc.).
+- `BlogPost` normalises PerspectAPI content payloads for blog/page usage.
+- Loader option types:
+  - `LoaderOptions`
+  - `LoadProductsOptions`
+- `LoadProductBySlugOptions`
+- `LoadContentOptions`
+- `LoadContentBySlugOptions`
+- `CheckoutSessionOptions`
+
+They are all exported from the SDK root for convenience:
+
+```typescript
+import type {
+  Product,
+  MediaItem,
+  BlogPost,
+  LoaderOptions,
+  LoadProductsOptions,
+  CheckoutAddress,
+  CheckoutSessionOptions
+} from 'perspectapi-ts-sdk';
+```
+
+---
+
+Need more examples? Open an issue or start a discussion on GitHub—we’d love to add additional recipes tailored to your stack.