perspectapi-ts-sdk 2.0.0 → 2.2.1

package/README.md

@@ -148,6 +148,88 @@ export default {
 ```
 
 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>`, 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}`,
+  ],
+};
+
+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.
 ```
 
 ## Image Transformations

package/dist/index.d.mts

@@ -424,6 +424,34 @@ type CheckoutMetadataValue = string | number | boolean | null | CheckoutMetadata
     [key: string]: CheckoutMetadataValue;
 };
 type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
+type CheckoutTaxStrategy = 'disabled' | 'gateway_auto' | 'manual_rates' | 'external_service';
+type CheckoutTaxExemptionStatus = 'none' | 'exempt' | 'reverse_charge';
+interface CheckoutTaxCustomerExemptionRequest {
+    status?: CheckoutTaxExemptionStatus;
+    reason?: string;
+    tax_id?: string;
+    tax_id_type?: string;
+    certificate_url?: string;
+    metadata?: Record<string, any>;
+    expires_at?: string;
+}
+interface CheckoutTaxRequest {
+    strategy?: CheckoutTaxStrategy;
+    customer_identifier?: string;
+    customer_profile_id?: string;
+    customer_display_name?: string;
+    allow_exemption?: boolean;
+    require_tax_id?: boolean;
+    save_profile?: boolean;
+    customer_exemption?: CheckoutTaxCustomerExemptionRequest;
+    manual_rate_percent?: number;
+    manual_rate_map?: Record<string, number>;
+    external_service?: {
+        provider: string;
+        config?: Record<string, any>;
+    };
+    metadata?: Record<string, any>;
+}
 interface CreateCheckoutSessionRequest {
     priceId?: string;
     quantity?: number;
@@ -455,6 +483,7 @@ interface CreateCheckoutSessionRequest {
         allowed_countries: string[];
     };
     billing_address_collection?: 'auto' | 'required';
+    tax?: CheckoutTaxRequest;
 }
 interface CheckoutSession {
     id: string;
@@ -2322,6 +2351,10 @@ interface CheckoutSessionOptions {
      * Optional resolver to convert a product record into a Stripe price ID.
      */
     priceIdResolver?: (product: Product, mode: 'live' | 'test') => string | undefined;
+    /**
+     * Optional tax configuration that will be forwarded to the checkout API.
+     */
+    tax?: CheckoutTaxRequest;
 }
 /**
  * Convenience helper that creates a checkout session by looking up Stripe price IDs
@@ -2331,4 +2364,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.d.ts

@@ -424,6 +424,34 @@ type CheckoutMetadataValue = string | number | boolean | null | CheckoutMetadata
     [key: string]: CheckoutMetadataValue;
 };
 type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
+type CheckoutTaxStrategy = 'disabled' | 'gateway_auto' | 'manual_rates' | 'external_service';
+type CheckoutTaxExemptionStatus = 'none' | 'exempt' | 'reverse_charge';
+interface CheckoutTaxCustomerExemptionRequest {
+    status?: CheckoutTaxExemptionStatus;
+    reason?: string;
+    tax_id?: string;
+    tax_id_type?: string;
+    certificate_url?: string;
+    metadata?: Record<string, any>;
+    expires_at?: string;
+}
+interface CheckoutTaxRequest {
+    strategy?: CheckoutTaxStrategy;
+    customer_identifier?: string;
+    customer_profile_id?: string;
+    customer_display_name?: string;
+    allow_exemption?: boolean;
+    require_tax_id?: boolean;
+    save_profile?: boolean;
+    customer_exemption?: CheckoutTaxCustomerExemptionRequest;
+    manual_rate_percent?: number;
+    manual_rate_map?: Record<string, number>;
+    external_service?: {
+        provider: string;
+        config?: Record<string, any>;
+    };
+    metadata?: Record<string, any>;
+}
 interface CreateCheckoutSessionRequest {
     priceId?: string;
     quantity?: number;
@@ -455,6 +483,7 @@ interface CreateCheckoutSessionRequest {
         allowed_countries: string[];
     };
     billing_address_collection?: 'auto' | 'required';
+    tax?: CheckoutTaxRequest;
 }
 interface CheckoutSession {
     id: string;
@@ -2322,6 +2351,10 @@ interface CheckoutSessionOptions {
      * Optional resolver to convert a product record into a Stripe price ID.
      */
     priceIdResolver?: (product: Product, mode: 'live' | 'test') => string | undefined;
+    /**
+     * Optional tax configuration that will be forwarded to the checkout API.
+     */
+    tax?: CheckoutTaxRequest;
 }
 /**
  * Convenience helper that creates a checkout session by looking up Stripe price IDs
@@ -2331,4 +2364,4 @@ declare function createCheckoutSession(options: CheckoutSessionOptions): Promise
     error: string;
 }>;
 
-export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutTaxCustomerExemptionRequest, type CheckoutTaxExemptionStatus, type CheckoutTaxRequest, type CheckoutTaxStrategy, ContactClient, type ContactStatusResponse, type ContactSubmission, type ContactSubmitResponse, type Content, ContentClient, type ContentQueryParams, type ContentStatus, type ContentType, type CreateApiKeyRequest, type CreateCategoryRequest, type CreateCheckoutSessionRequest, type CreateContactRequest, type CreateContentRequest, type CreateNewsletterSubscriptionRequest, type CreateOrganizationRequest, type CreatePaymentGatewayRequest, type CreateProductRequest, type CreateSiteRequest, type CreateWebhookRequest, DEFAULT_IMAGE_SIZES, HttpClient, type HttpMethod, type ImageTransformOptions, InMemoryCacheAdapter, type LoadContentBySlugOptions, type LoadContentOptions, type LoadProductBySlugOptions, type LoadProductsOptions, type LoaderLogger, type LoaderOptions, type MediaItem, NewsletterClient, type NewsletterConfirmResponse, type NewsletterList, type NewsletterPreferences, type NewsletterStatusResponse, type NewsletterSubscribeResponse, type NewsletterSubscription, type NewsletterUnsubscribeRequest, type NewsletterUnsubscribeResponse, NoopCacheAdapter, type Organization, OrganizationsClient, type PaginatedResponse, type PaginationParams, type PaymentGateway, PerspectApiClient, type PerspectApiConfig, type Product, type ProductQueryParams, ProductsClient, type RequestOptions, type ResponsiveImageSizes, type SignInRequest, type SignUpRequest, type Site, SitesClient, type UpdateApiKeyRequest, type UpdateContentRequest, type User, type Webhook, WebhooksClient, buildImageUrl, createApiError, createCheckoutSession, createPerspectApiClient, PerspectApiClient as default, generateResponsiveImageHtml, generateResponsiveUrls, generateSizesAttribute, generateSrcSet, loadAllContent, loadContentBySlug, loadPages, loadPosts, loadProductBySlug, loadProducts, transformContent, transformMediaItem, transformProduct };

package/dist/index.js

@@ -354,6 +354,7 @@ var CacheManager = class {
   }
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
+      console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
       const value2 = await resolveValue();
       if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
         await this.set(key, value2, policy);
@@ -365,12 +366,16 @@ var CacheManager = class {
     if (cachedRaw) {
       const entry = this.deserialize(cachedRaw);
       if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log("[Cache] \u2713 HIT", { key, tags: entry.tags });
         return entry.value;
       }
+      console.log("[Cache] \u2717 EXPIRED", { key, expiresAt: new Date(entry.expiresAt) });
       await this.adapter.delete(namespacedKey);
       if (entry.tags?.length) {
         await this.removeKeyFromTags(namespacedKey, entry.tags);
       }
+    } else {
+      console.log("[Cache] \u2717 MISS", { key });
     }
     const value = await resolveValue();
     await this.set(key, value, policy);
@@ -388,6 +393,7 @@ var CacheManager = class {
       tags: options?.tags,
       metadata: options?.metadata
     };
+    console.log("[Cache] SET", { key, ttlSeconds, tags: options?.tags });
     await this.adapter.set(namespacedKey, this.serialize(entry), {
       ttlSeconds: ttlSeconds > 0 ? ttlSeconds : void 0
     });
@@ -406,34 +412,42 @@ var CacheManager = class {
     if (!this.enabled) {
       return;
     }
+    let totalInvalidated = 0;
     if (options.keys?.length) {
       const namespacedKeys = options.keys.map((key) => this.namespacedKey(key));
+      console.log("[Cache] INVALIDATE by keys", { count: options.keys.length, keys: options.keys });
       if (this.adapter.deleteMany) {
         await this.adapter.deleteMany(namespacedKeys);
       } else {
         await Promise.all(namespacedKeys.map((key) => this.adapter.delete(key)));
       }
+      totalInvalidated += options.keys.length;
     }
     if (options.tags?.length) {
+      console.log("[Cache] INVALIDATE by tags", { tags: options.tags });
       await Promise.all(
         options.tags.map(async (tag) => {
           const tagKey = this.tagKey(tag);
           const payload = await this.adapter.get(tagKey);
           if (!payload) {
+            console.log("[Cache] No entries for tag", { tag });
             return;
           }
           const keys = this.deserializeTagSet(payload);
           if (keys.length) {
+            console.log("[Cache] Invalidating entries for tag", { tag, count: keys.length });
             if (this.adapter.deleteMany) {
               await this.adapter.deleteMany(keys);
             } else {
               await Promise.all(keys.map((key) => this.adapter.delete(key)));
             }
+            totalInvalidated += keys.length;
           }
           await this.adapter.delete(tagKey);
         })
       );
     }
+    console.log("[Cache] \u2713 INVALIDATED", { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
   }
   namespacedKey(key) {
     return `${this.keyPrefix}:${key}`;
@@ -715,6 +729,43 @@ var AuthClient = class extends BaseClient {
   }
 };
 
+// src/utils/validators.ts
+var MAX_API_QUERY_LIMIT = 100;
+var ALLOWED_CONTENT_TYPES = ["post", "page"];
+function validateLimit(limit, context) {
+  if (typeof limit !== "number" || Number.isNaN(limit) || !Number.isFinite(limit)) {
+    throw new Error(`[PerspectAPI] ${context} limit must be a finite number.`);
+  }
+  if (limit < 1) {
+    throw new Error(`[PerspectAPI] ${context} limit must be at least 1.`);
+  }
+  if (limit > MAX_API_QUERY_LIMIT) {
+    throw new Error(
+      `[PerspectAPI] ${context} limit ${limit} exceeds the maximum allowed value of ${MAX_API_QUERY_LIMIT}.`
+    );
+  }
+  return limit;
+}
+function validateOptionalLimit(limit, context) {
+  if (limit === void 0 || limit === null) {
+    return void 0;
+  }
+  return validateLimit(limit, context);
+}
+function validateOptionalContentType(pageType, context) {
+  if (pageType === void 0 || pageType === null) {
+    return void 0;
+  }
+  if (ALLOWED_CONTENT_TYPES.includes(pageType)) {
+    return pageType;
+  }
+  throw new Error(
+    `[PerspectAPI] ${context} received unsupported page_type "${pageType}". Allowed values are ${ALLOWED_CONTENT_TYPES.join(
+      ", "
+    )}.`
+  );
+}
+
 // src/client/content-client.ts
 var ContentClient = class extends BaseClient {
   constructor(http, cache) {
@@ -726,12 +777,33 @@ var ContentClient = class extends BaseClient {
   async getContent(siteName, params, cachePolicy) {
     const endpoint = this.siteScopedEndpoint(siteName);
     const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : void 0;
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "content query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        "content query"
+      );
+      if (validatedPageType !== void 0) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
     return this.fetchWithCache(
       endpoint,
-      params,
+      normalizedParams,
       this.buildContentTags(siteName),
       cachePolicy,
-      () => this.http.get(path, params)
+      () => this.http.get(path, normalizedParams)
     );
   }
   /**
@@ -1093,6 +1165,15 @@ var ProductsClient = class extends BaseClient {
     };
     const normalizedParams = params ? { ...params } : void 0;
     if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "products query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
       const normalizedCategories = normalizeList(normalizedParams.category);
       if (normalizedCategories !== void 0) {
         normalizedParams.category = normalizedCategories;
@@ -2308,12 +2389,16 @@ async function loadProducts(options) {
     siteName,
     logger = noopLogger,
     fallbackProducts,
-    limit = 100,
+    limit: requestedLimit,
     offset,
     search,
     category,
     categoryIds
   } = options;
+  const resolvedLimit = validateLimit(
+    requestedLimit ?? MAX_API_QUERY_LIMIT,
+    "products query"
+  );
   if (!client) {
     log(logger, "warn", "[PerspectAPI] No client configured, using fallback products");
     return resolveFallbackProducts({ siteName, fallbackProducts });
@@ -2322,7 +2407,7 @@ async function loadProducts(options) {
     log(logger, "info", `[PerspectAPI] Loading products for site "${siteName}"`);
     const queryParams = {
       isActive: true,
-      limit,
+      limit: resolvedLimit,
       offset,
       search
     };
@@ -2382,13 +2467,20 @@ async function loadPages(options) {
   }
   try {
     log(logger, "info", `[PerspectAPI] Loading pages for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "pages query"
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType = validateOptionalContentType(requestedPageType, "pages query") ?? "page";
     const response = await client.content.getContent(
       siteName,
       {
         ...params,
         page_status: params?.page_status ?? "publish",
-        page_type: params?.page_type ?? "page",
-        limit: options.limit ?? params?.limit ?? 100
+        page_type: validatedPageType,
+        limit: resolvedLimit
       }
     );
     if (!response.data) {
@@ -2408,13 +2500,20 @@ async function loadPosts(options) {
   }
   try {
     log(logger, "info", `[PerspectAPI] Loading posts for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "posts query"
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType = validateOptionalContentType(requestedPageType, "posts query") ?? "post";
     const response = await client.content.getContent(
       siteName,
       {
         ...params,
         page_status: params?.page_status ?? "publish",
-        page_type: params?.page_type ?? "post",
-        limit: options.limit ?? params?.limit ?? 100
+        page_type: validatedPageType,
+        limit: resolvedLimit
       }
     );
     if (!response.data) {
@@ -2474,7 +2573,8 @@ async function createCheckoutSession(options) {
     logger = noopLogger,
     fallbackProducts,
     metadata,
-    priceIdResolver
+    priceIdResolver,
+    tax
   } = options;
   if (!client) {
     log(logger, "error", "[PerspectAPI] Cannot create checkout session without SDK client");
@@ -2485,7 +2585,7 @@ async function createCheckoutSession(options) {
       client,
       siteName,
       logger,
-      limit: 200,
+      limit: Math.min(Math.max(items.length, 1), MAX_API_QUERY_LIMIT),
       fallbackProducts
     });
     const productMap = new Map(
@@ -2505,6 +2605,18 @@ async function createCheckoutSession(options) {
         quantity: item.quantity
       };
     });
+    const resolvedTax = (() => {
+      if (!tax && !customerEmail) {
+        return void 0;
+      }
+      if (!tax) {
+        return { customer_identifier: customerEmail };
+      }
+      return {
+        ...tax,
+        customer_identifier: tax.customer_identifier ?? customerEmail ?? void 0
+      };
+    })();
     const checkoutData = {
       line_items,
       successUrl,
@@ -2516,6 +2628,9 @@ async function createCheckoutSession(options) {
       mode: mode === "test" ? "payment" : "payment",
       metadata
     };
+    if (resolvedTax) {
+      checkoutData.tax = resolvedTax;
+    }
     log(logger, "info", "[PerspectAPI] Creating checkout session");
     return client.checkout.createCheckoutSession(siteName, checkoutData);
   } catch (error) {

package/dist/index.mjs

@@ -293,6 +293,7 @@ var CacheManager = class {
   }
   async getOrSet(key, resolveValue, policy) {
     if (!this.enabled || policy?.skipCache) {
+      console.log("[Cache] Cache disabled or skipped", { key, enabled: this.enabled, skipCache: policy?.skipCache });
       const value2 = await resolveValue();
       if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
         await this.set(key, value2, policy);
@@ -304,12 +305,16 @@ var CacheManager = class {
     if (cachedRaw) {
       const entry = this.deserialize(cachedRaw);
       if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log("[Cache] \u2713 HIT", { key, tags: entry.tags });
         return entry.value;
       }
+      console.log("[Cache] \u2717 EXPIRED", { key, expiresAt: new Date(entry.expiresAt) });
       await this.adapter.delete(namespacedKey);
       if (entry.tags?.length) {
         await this.removeKeyFromTags(namespacedKey, entry.tags);
       }
+    } else {
+      console.log("[Cache] \u2717 MISS", { key });
     }
     const value = await resolveValue();
     await this.set(key, value, policy);
@@ -327,6 +332,7 @@ var CacheManager = class {
       tags: options?.tags,
       metadata: options?.metadata
     };
+    console.log("[Cache] SET", { key, ttlSeconds, tags: options?.tags });
     await this.adapter.set(namespacedKey, this.serialize(entry), {
       ttlSeconds: ttlSeconds > 0 ? ttlSeconds : void 0
     });
@@ -345,34 +351,42 @@ var CacheManager = class {
     if (!this.enabled) {
       return;
     }
+    let totalInvalidated = 0;
     if (options.keys?.length) {
       const namespacedKeys = options.keys.map((key) => this.namespacedKey(key));
+      console.log("[Cache] INVALIDATE by keys", { count: options.keys.length, keys: options.keys });
       if (this.adapter.deleteMany) {
         await this.adapter.deleteMany(namespacedKeys);
       } else {
         await Promise.all(namespacedKeys.map((key) => this.adapter.delete(key)));
       }
+      totalInvalidated += options.keys.length;
     }
     if (options.tags?.length) {
+      console.log("[Cache] INVALIDATE by tags", { tags: options.tags });
       await Promise.all(
         options.tags.map(async (tag) => {
           const tagKey = this.tagKey(tag);
           const payload = await this.adapter.get(tagKey);
           if (!payload) {
+            console.log("[Cache] No entries for tag", { tag });
             return;
           }
           const keys = this.deserializeTagSet(payload);
           if (keys.length) {
+            console.log("[Cache] Invalidating entries for tag", { tag, count: keys.length });
             if (this.adapter.deleteMany) {
               await this.adapter.deleteMany(keys);
             } else {
               await Promise.all(keys.map((key) => this.adapter.delete(key)));
             }
+            totalInvalidated += keys.length;
           }
           await this.adapter.delete(tagKey);
         })
       );
     }
+    console.log("[Cache] \u2713 INVALIDATED", { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
   }
   namespacedKey(key) {
     return `${this.keyPrefix}:${key}`;
@@ -654,6 +668,43 @@ var AuthClient = class extends BaseClient {
   }
 };
 
+// src/utils/validators.ts
+var MAX_API_QUERY_LIMIT = 100;
+var ALLOWED_CONTENT_TYPES = ["post", "page"];
+function validateLimit(limit, context) {
+  if (typeof limit !== "number" || Number.isNaN(limit) || !Number.isFinite(limit)) {
+    throw new Error(`[PerspectAPI] ${context} limit must be a finite number.`);
+  }
+  if (limit < 1) {
+    throw new Error(`[PerspectAPI] ${context} limit must be at least 1.`);
+  }
+  if (limit > MAX_API_QUERY_LIMIT) {
+    throw new Error(
+      `[PerspectAPI] ${context} limit ${limit} exceeds the maximum allowed value of ${MAX_API_QUERY_LIMIT}.`
+    );
+  }
+  return limit;
+}
+function validateOptionalLimit(limit, context) {
+  if (limit === void 0 || limit === null) {
+    return void 0;
+  }
+  return validateLimit(limit, context);
+}
+function validateOptionalContentType(pageType, context) {
+  if (pageType === void 0 || pageType === null) {
+    return void 0;
+  }
+  if (ALLOWED_CONTENT_TYPES.includes(pageType)) {
+    return pageType;
+  }
+  throw new Error(
+    `[PerspectAPI] ${context} received unsupported page_type "${pageType}". Allowed values are ${ALLOWED_CONTENT_TYPES.join(
+      ", "
+    )}.`
+  );
+}
+
 // src/client/content-client.ts
 var ContentClient = class extends BaseClient {
   constructor(http, cache) {
@@ -665,12 +716,33 @@ var ContentClient = class extends BaseClient {
   async getContent(siteName, params, cachePolicy) {
     const endpoint = this.siteScopedEndpoint(siteName);
     const path = this.buildPath(endpoint);
+    const normalizedParams = params ? { ...params } : void 0;
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "content query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        "content query"
+      );
+      if (validatedPageType !== void 0) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
     return this.fetchWithCache(
       endpoint,
-      params,
+      normalizedParams,
       this.buildContentTags(siteName),
       cachePolicy,
-      () => this.http.get(path, params)
+      () => this.http.get(path, normalizedParams)
     );
   }
   /**
@@ -1032,6 +1104,15 @@ var ProductsClient = class extends BaseClient {
     };
     const normalizedParams = params ? { ...params } : void 0;
     if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        "products query"
+      );
+      if (validatedLimit !== void 0) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
       const normalizedCategories = normalizeList(normalizedParams.category);
       if (normalizedCategories !== void 0) {
         normalizedParams.category = normalizedCategories;
@@ -2247,12 +2328,16 @@ async function loadProducts(options) {
     siteName,
     logger = noopLogger,
     fallbackProducts,
-    limit = 100,
+    limit: requestedLimit,
     offset,
     search,
     category,
     categoryIds
   } = options;
+  const resolvedLimit = validateLimit(
+    requestedLimit ?? MAX_API_QUERY_LIMIT,
+    "products query"
+  );
   if (!client) {
     log(logger, "warn", "[PerspectAPI] No client configured, using fallback products");
     return resolveFallbackProducts({ siteName, fallbackProducts });
@@ -2261,7 +2346,7 @@ async function loadProducts(options) {
     log(logger, "info", `[PerspectAPI] Loading products for site "${siteName}"`);
     const queryParams = {
       isActive: true,
-      limit,
+      limit: resolvedLimit,
       offset,
       search
     };
@@ -2321,13 +2406,20 @@ async function loadPages(options) {
   }
   try {
     log(logger, "info", `[PerspectAPI] Loading pages for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "pages query"
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType = validateOptionalContentType(requestedPageType, "pages query") ?? "page";
     const response = await client.content.getContent(
       siteName,
       {
         ...params,
         page_status: params?.page_status ?? "publish",
-        page_type: params?.page_type ?? "page",
-        limit: options.limit ?? params?.limit ?? 100
+        page_type: validatedPageType,
+        limit: resolvedLimit
       }
     );
     if (!response.data) {
@@ -2347,13 +2439,20 @@ async function loadPosts(options) {
   }
   try {
     log(logger, "info", `[PerspectAPI] Loading posts for site "${siteName}"`);
+    const requestedLimit = options.limit !== void 0 ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      "posts query"
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType = validateOptionalContentType(requestedPageType, "posts query") ?? "post";
     const response = await client.content.getContent(
       siteName,
       {
         ...params,
         page_status: params?.page_status ?? "publish",
-        page_type: params?.page_type ?? "post",
-        limit: options.limit ?? params?.limit ?? 100
+        page_type: validatedPageType,
+        limit: resolvedLimit
       }
     );
     if (!response.data) {
@@ -2413,7 +2512,8 @@ async function createCheckoutSession(options) {
     logger = noopLogger,
     fallbackProducts,
     metadata,
-    priceIdResolver
+    priceIdResolver,
+    tax
   } = options;
   if (!client) {
     log(logger, "error", "[PerspectAPI] Cannot create checkout session without SDK client");
@@ -2424,7 +2524,7 @@ async function createCheckoutSession(options) {
       client,
       siteName,
       logger,
-      limit: 200,
+      limit: Math.min(Math.max(items.length, 1), MAX_API_QUERY_LIMIT),
       fallbackProducts
     });
     const productMap = new Map(
@@ -2444,6 +2544,18 @@ async function createCheckoutSession(options) {
         quantity: item.quantity
       };
     });
+    const resolvedTax = (() => {
+      if (!tax && !customerEmail) {
+        return void 0;
+      }
+      if (!tax) {
+        return { customer_identifier: customerEmail };
+      }
+      return {
+        ...tax,
+        customer_identifier: tax.customer_identifier ?? customerEmail ?? void 0
+      };
+    })();
     const checkoutData = {
       line_items,
       successUrl,
@@ -2455,6 +2567,9 @@ async function createCheckoutSession(options) {
       mode: mode === "test" ? "payment" : "payment",
       metadata
     };
+    if (resolvedTax) {
+      checkoutData.tax = resolvedTax;
+    }
     log(logger, "info", "[PerspectAPI] Creating checkout session");
     return client.checkout.createCheckoutSession(siteName, checkoutData);
   } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perspectapi-ts-sdk",
-  "version": "2.0.0",
+  "version": "2.2.1",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/cache/cache-manager.ts

@@ -75,6 +75,7 @@ export class CacheManager {
     policy?: CachePolicy
   ): Promise<T> {
     if (!this.enabled || policy?.skipCache) {
+      console.log('[Cache] Cache disabled or skipped', { key, enabled: this.enabled, skipCache: policy?.skipCache });
       const value = await resolveValue();
 
       if (this.enabled && !policy?.skipCache && policy?.ttlSeconds !== 0) {
@@ -91,14 +92,18 @@ export class CacheManager {
       const entry = this.deserialize<T>(cachedRaw);
 
       if (!entry.expiresAt || entry.expiresAt > Date.now()) {
+        console.log('[Cache] ✓ HIT', { key, tags: entry.tags });
         return entry.value;
       }
 
       // Expired entry
+      console.log('[Cache] ✗ EXPIRED', { key, expiresAt: new Date(entry.expiresAt) });
       await this.adapter.delete(namespacedKey);
       if (entry.tags?.length) {
         await this.removeKeyFromTags(namespacedKey, entry.tags);
       }
+    } else {
+      console.log('[Cache] ✗ MISS', { key });
     }
 
     const value = await resolveValue();
@@ -122,6 +127,8 @@ export class CacheManager {
       metadata: options?.metadata,
     };
 
+    console.log('[Cache] SET', { key, ttlSeconds, tags: options?.tags });
+
     await this.adapter.set(namespacedKey, this.serialize(entry), {
       ttlSeconds: ttlSeconds > 0 ? ttlSeconds : undefined,
     });
@@ -144,37 +151,47 @@ export class CacheManager {
       return;
     }
 
+    let totalInvalidated = 0;
+
     if (options.keys?.length) {
       const namespacedKeys = options.keys.map(key => this.namespacedKey(key));
+      console.log('[Cache] INVALIDATE by keys', { count: options.keys.length, keys: options.keys });
       if (this.adapter.deleteMany) {
         await this.adapter.deleteMany(namespacedKeys);
       } else {
         await Promise.all(namespacedKeys.map(key => this.adapter.delete(key)));
       }
+      totalInvalidated += options.keys.length;
     }
 
     if (options.tags?.length) {
+      console.log('[Cache] INVALIDATE by tags', { tags: options.tags });
       await Promise.all(
         options.tags.map(async tag => {
           const tagKey = this.tagKey(tag);
           const payload = await this.adapter.get(tagKey);
           if (!payload) {
+            console.log('[Cache] No entries for tag', { tag });
             return;
           }
 
           const keys = this.deserializeTagSet(payload);
           if (keys.length) {
+            console.log('[Cache] Invalidating entries for tag', { tag, count: keys.length });
             if (this.adapter.deleteMany) {
               await this.adapter.deleteMany(keys);
             } else {
               await Promise.all(keys.map(key => this.adapter.delete(key)));
             }
+            totalInvalidated += keys.length;
           }
 
           await this.adapter.delete(tagKey);
         })
       );
     }
+
+    console.log('[Cache] ✓ INVALIDATED', { totalEntries: totalInvalidated, keys: options.keys?.length || 0, tags: options.tags?.length || 0 });
   }
 
   private namespacedKey(key: string): string {

package/src/client/content-client.ts

@@ -13,6 +13,7 @@ import type {
   PaginatedResponse,
   ApiResponse,
 } from '../types';
+import { validateOptionalContentType, validateOptionalLimit } from '../utils/validators';
 
 export class ContentClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
@@ -29,13 +30,38 @@ export class ContentClient extends BaseClient {
   ): Promise<PaginatedResponse<Content>> {
     const endpoint = this.siteScopedEndpoint(siteName);
     const path = this.buildPath(endpoint);
+    const normalizedParams: ContentQueryParams | undefined = params
+      ? { ...params }
+      : undefined;
+
+    if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        'content query',
+      );
+      if (validatedLimit !== undefined) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+
+      const validatedPageType = validateOptionalContentType(
+        normalizedParams.page_type,
+        'content query',
+      );
+      if (validatedPageType !== undefined) {
+        normalizedParams.page_type = validatedPageType;
+      } else {
+        delete normalizedParams.page_type;
+      }
+    }
 
     return this.fetchWithCache<PaginatedResponse<Content>>(
       endpoint,
-      params,
+      normalizedParams,
       this.buildContentTags(siteName),
       cachePolicy,
-      () => this.http.get(path, params) as Promise<PaginatedResponse<Content>>
+      () => this.http.get(path, normalizedParams) as Promise<PaginatedResponse<Content>>
     );
   }
 

package/src/client/products-client.ts

@@ -12,6 +12,7 @@ import type {
   ApiResponse,
   ProductQueryParams,
 } from '../types';
+import { validateOptionalLimit } from '../utils/validators';
 
 export class ProductsClient extends BaseClient {
   constructor(http: any, cache?: CacheManager) {
@@ -41,6 +42,16 @@ export class ProductsClient extends BaseClient {
     const normalizedParams: ProductQueryParams | undefined = params ? { ...params } : undefined;
 
     if (normalizedParams) {
+      const validatedLimit = validateOptionalLimit(
+        normalizedParams.limit,
+        'products query',
+      );
+      if (validatedLimit !== undefined) {
+        normalizedParams.limit = validatedLimit;
+      } else {
+        delete normalizedParams.limit;
+      }
+
       const normalizedCategories = normalizeList(normalizedParams.category as any);
       if (normalizedCategories !== undefined) {
         normalizedParams.category = normalizedCategories;

package/src/loaders.ts

@@ -17,8 +17,14 @@ import type {
   BlogPost,
   CreateCheckoutSessionRequest,
   CheckoutSession,
-  CheckoutMetadata
+  CheckoutMetadata,
+  CheckoutTaxRequest
 } from './types';
+import {
+  MAX_API_QUERY_LIMIT,
+  validateLimit,
+  validateOptionalContentType
+} from './utils/validators';
 
 /**
  * Logger interface so consumers can supply custom logging behaviour (or noop).
@@ -311,13 +317,18 @@ export async function loadProducts(options: LoadProductsOptions): Promise<Produc
     siteName,
     logger = noopLogger,
     fallbackProducts,
-    limit = 100,
+    limit: requestedLimit,
     offset,
     search,
     category,
     categoryIds
   } = options;
 
+  const resolvedLimit = validateLimit(
+    requestedLimit ?? MAX_API_QUERY_LIMIT,
+    'products query',
+  );
+
   if (!client) {
     log(logger, 'warn', '[PerspectAPI] No client configured, using fallback products');
     return resolveFallbackProducts({ siteName, fallbackProducts });
@@ -327,7 +338,7 @@ export async function loadProducts(options: LoadProductsOptions): Promise<Produc
     log(logger, 'info', `[PerspectAPI] Loading products for site "${siteName}"`);
     const queryParams: ProductQueryParams = {
       isActive: true,
-      limit,
+      limit: resolvedLimit,
       offset,
       search
     };
@@ -427,13 +438,23 @@ export async function loadPages(
 
   try {
     log(logger, 'info', `[PerspectAPI] Loading pages for site "${siteName}"`);
+    const requestedLimit =
+      options.limit !== undefined ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      'pages query',
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType =
+      validateOptionalContentType(requestedPageType, 'pages query') ?? 'page';
+
     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
+        page_type: validatedPageType as ContentType,
+        limit: resolvedLimit
       }
     );
 
@@ -463,13 +484,23 @@ export async function loadPosts(
 
   try {
     log(logger, 'info', `[PerspectAPI] Loading posts for site "${siteName}"`);
+    const requestedLimit =
+      options.limit !== undefined ? options.limit : params?.limit;
+    const resolvedLimit = validateLimit(
+      requestedLimit ?? MAX_API_QUERY_LIMIT,
+      'posts query',
+    );
+    const requestedPageType = params?.page_type;
+    const validatedPageType =
+      validateOptionalContentType(requestedPageType, 'posts query') ?? 'post';
+
     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
+        page_type: validatedPageType as ContentType,
+        limit: resolvedLimit
       }
     );
 
@@ -558,6 +589,10 @@ export interface CheckoutSessionOptions {
    * Optional resolver to convert a product record into a Stripe price ID.
    */
   priceIdResolver?: (product: Product, mode: 'live' | 'test') => string | undefined;
+  /**
+   * Optional tax configuration that will be forwarded to the checkout API.
+   */
+  tax?: CheckoutTaxRequest;
 }
 
 /**
@@ -578,7 +613,8 @@ export async function createCheckoutSession(
     logger = noopLogger,
     fallbackProducts,
     metadata,
-    priceIdResolver
+    priceIdResolver,
+    tax
   } = options;
 
   if (!client) {
@@ -592,7 +628,7 @@ export async function createCheckoutSession(
       client,
       siteName,
       logger,
-      limit: 200,
+      limit: Math.min(Math.max(items.length, 1), MAX_API_QUERY_LIMIT),
       fallbackProducts
     });
 
@@ -623,6 +659,21 @@ export async function createCheckoutSession(
       };
     });
 
+    const resolvedTax: CheckoutTaxRequest | undefined = (() => {
+      if (!tax && !customerEmail) {
+        return undefined;
+      }
+
+      if (!tax) {
+        return { customer_identifier: customerEmail };
+      }
+
+      return {
+        ...tax,
+        customer_identifier: tax.customer_identifier ?? customerEmail ?? undefined,
+      };
+    })();
+
     const checkoutData: CreateCheckoutSessionRequest = {
       line_items,
       successUrl,
@@ -632,9 +683,13 @@ export async function createCheckoutSession(
       customerEmail,
       customer_email: customerEmail,
       mode: mode === 'test' ? 'payment' : 'payment',
-      metadata
+      metadata,
     };
 
+    if (resolvedTax) {
+      checkoutData.tax = resolvedTax;
+    }
+
     log(logger, 'info', '[PerspectAPI] Creating checkout session');
     return client.checkout.createCheckoutSession(siteName, checkoutData);
   } catch (error) {

package/src/types/index.ts

@@ -399,6 +399,45 @@ export type CheckoutMetadataValue =
 
 export type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
 
+export type CheckoutTaxStrategy =
+  | 'disabled'
+  | 'gateway_auto'
+  | 'manual_rates'
+  | 'external_service';
+
+export type CheckoutTaxExemptionStatus =
+  | 'none'
+  | 'exempt'
+  | 'reverse_charge';
+
+export interface CheckoutTaxCustomerExemptionRequest {
+  status?: CheckoutTaxExemptionStatus;
+  reason?: string;
+  tax_id?: string;
+  tax_id_type?: string;
+  certificate_url?: string;
+  metadata?: Record<string, any>;
+  expires_at?: string;
+}
+
+export interface CheckoutTaxRequest {
+  strategy?: CheckoutTaxStrategy;
+  customer_identifier?: string;
+  customer_profile_id?: string;
+  customer_display_name?: string;
+  allow_exemption?: boolean;
+  require_tax_id?: boolean;
+  save_profile?: boolean;
+  customer_exemption?: CheckoutTaxCustomerExemptionRequest;
+  manual_rate_percent?: number;
+  manual_rate_map?: Record<string, number>;
+  external_service?: {
+    provider: string;
+    config?: Record<string, any>;
+  };
+  metadata?: Record<string, any>;
+}
+
 export interface CreateCheckoutSessionRequest {
   // Single item checkout (legacy/simple)
   priceId?: string;
@@ -437,6 +476,7 @@ export interface CreateCheckoutSessionRequest {
     allowed_countries: string[];
   };
   billing_address_collection?: 'auto' | 'required';
+  tax?: CheckoutTaxRequest;
 }
 
 export interface CheckoutSession {

package/src/utils/validators.ts

@@ -0,0 +1,53 @@
+import type { ContentType } from '../types';
+
+export const MAX_API_QUERY_LIMIT = 100;
+const ALLOWED_CONTENT_TYPES: ReadonlyArray<ContentType> = ['post', 'page'];
+
+export function validateLimit(limit: number, context: string): number {
+  if (typeof limit !== 'number' || Number.isNaN(limit) || !Number.isFinite(limit)) {
+    throw new Error(`[PerspectAPI] ${context} limit must be a finite number.`);
+  }
+
+  if (limit < 1) {
+    throw new Error(`[PerspectAPI] ${context} limit must be at least 1.`);
+  }
+
+  if (limit > MAX_API_QUERY_LIMIT) {
+    throw new Error(
+      `[PerspectAPI] ${context} limit ${limit} exceeds the maximum allowed value of ${MAX_API_QUERY_LIMIT}.`,
+    );
+  }
+
+  return limit;
+}
+
+export function validateOptionalLimit(
+  limit: number | undefined,
+  context: string,
+): number | undefined {
+  if (limit === undefined || limit === null) {
+    return undefined;
+  }
+
+  return validateLimit(limit, context);
+}
+
+export function validateOptionalContentType(
+  pageType: string | undefined,
+  context: string,
+): ContentType | undefined {
+  if (pageType === undefined || pageType === null) {
+    return undefined;
+  }
+
+  if (ALLOWED_CONTENT_TYPES.includes(pageType as ContentType)) {
+    return pageType as ContentType;
+  }
+
+  throw new Error(
+    `[PerspectAPI] ${context} received unsupported page_type "${pageType}". Allowed values are ${ALLOWED_CONTENT_TYPES.join(
+      ', ',
+    )}.`,
+  );
+}
+