perspectapi-ts-sdk 2.1.0 → 2.2.1

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

@@ -729,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) {
@@ -740,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)
     );
   }
   /**
@@ -1107,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;
@@ -2322,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 });
@@ -2336,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
     };
@@ -2396,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) {
@@ -2422,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) {
@@ -2488,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");
@@ -2499,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(
@@ -2519,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,
@@ -2530,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

@@ -668,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) {
@@ -679,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)
     );
   }
   /**
@@ -1046,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;
@@ -2261,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 });
@@ -2275,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
     };
@@ -2335,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) {
@@ -2361,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) {
@@ -2427,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");
@@ -2438,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(
@@ -2458,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,
@@ -2469,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.1.0",
+  "version": "2.2.1",
   "description": "TypeScript SDK for PerspectAPI - Cloudflare Workers compatible",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

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(
+      ', ',
+    )}.`,
+  );
+}
+