perspectapi-ts-sdk 2.2.1 → 2.3.0

package/README.md

@@ -537,7 +537,29 @@ const session = await client.checkout.createCheckoutSession({
   priceId: 'price_1234567890',
   successUrl: 'https://myapp.com/success',
   cancelUrl: 'https://myapp.com/cancel',
-  customerEmail: 'customer@example.com'
+  customerEmail: 'customer@example.com',
+  currency: 'usd',
+  shipping_amount: 500,
+  shipping_address: {
+    country: 'US',
+    state: 'CA',
+    postal_code: '94110'
+  },
+  billing_address: {
+    country: 'US',
+    state: 'CA',
+    postal_code: '94110'
+  },
+  tax: {
+    strategy: 'manual_rates',
+    customer_identifier: 'acct-123',
+    customer_display_name: 'Acme Corp',
+    customer_exemption: {
+      status: 'exempt',
+      tax_id: '99-1234567',
+      tax_id_type: 'ein'
+    }
+  }
 });
 
 // Redirect user to checkout
@@ -545,6 +567,7 @@ window.location.href = session.data.url;
 
 // Get checkout session status
 const sessionStatus = await client.checkout.getCheckoutSession('cs_test_123');
+console.log(sessionStatus.data.tax?.amount); // Display assessed tax (if calculated)
 ```
 
 ### Contact Forms

package/dist/index.d.mts

@@ -426,6 +426,14 @@ type CheckoutMetadataValue = string | number | boolean | null | CheckoutMetadata
 type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
 type CheckoutTaxStrategy = 'disabled' | 'gateway_auto' | 'manual_rates' | 'external_service';
 type CheckoutTaxExemptionStatus = 'none' | 'exempt' | 'reverse_charge';
+interface CheckoutAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postal_code?: string;
+    country?: string;
+}
 interface CheckoutTaxCustomerExemptionRequest {
     status?: CheckoutTaxExemptionStatus;
     reason?: string;
@@ -474,6 +482,7 @@ interface CreateCheckoutSessionRequest {
     cancelUrl?: string;
     customer_email?: string;
     customerEmail?: string;
+    currency?: string;
     metadata?: CheckoutMetadata;
     mode?: 'payment' | 'subscription' | 'setup';
     automatic_tax?: {
@@ -483,12 +492,35 @@ interface CreateCheckoutSessionRequest {
         allowed_countries: string[];
     };
     billing_address_collection?: 'auto' | 'required';
+    shipping_amount?: number;
+    shippingAmount?: number;
+    shipping_address?: CheckoutAddress;
+    shippingAddress?: CheckoutAddress;
+    billing_address?: CheckoutAddress;
+    billingAddress?: CheckoutAddress;
     tax?: CheckoutTaxRequest;
 }
+interface CheckoutTaxBreakdownItem {
+    jurisdiction: string;
+    rate_percent: number;
+    tax_amount: number;
+    taxable_amount: number;
+    source: 'manual_map' | 'manual_percent' | 'gateway' | 'external';
+}
+interface CheckoutSessionTax {
+    amount: number;
+    currency: string;
+    strategy: CheckoutTaxStrategy;
+    exemption_applied: boolean;
+    exemption_status: CheckoutTaxExemptionStatus;
+    breakdown?: CheckoutTaxBreakdownItem[] | null;
+}
 interface CheckoutSession {
     id: string;
     url: string;
     status: string;
+    payment_status?: string;
+    tax?: CheckoutSessionTax | null;
 }
 interface ContactSubmission {
     id: string;
@@ -2347,6 +2379,22 @@ interface CheckoutSessionOptions {
     logger?: LoaderLogger;
     fallbackProducts?: Product[];
     metadata?: CheckoutMetadata;
+    /**
+     * Optional currency override; defaults to the currency defined on each Stripe price.
+     */
+    currency?: string;
+    /**
+     * Optional shipping amount (in the smallest currency unit).
+     */
+    shippingAmount?: number;
+    /**
+     * Shipping address forwarded to the checkout API for tax estimation.
+     */
+    shippingAddress?: CheckoutAddress;
+    /**
+     * Billing address forwarded to the checkout API for tax estimation.
+     */
+    billingAddress?: CheckoutAddress;
     /**
      * Optional resolver to convert a product record into a Stripe price ID.
      */
@@ -2364,4 +2412,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, 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 };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, 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

@@ -426,6 +426,14 @@ type CheckoutMetadataValue = string | number | boolean | null | CheckoutMetadata
 type CheckoutMetadata = Record<string, CheckoutMetadataValue>;
 type CheckoutTaxStrategy = 'disabled' | 'gateway_auto' | 'manual_rates' | 'external_service';
 type CheckoutTaxExemptionStatus = 'none' | 'exempt' | 'reverse_charge';
+interface CheckoutAddress {
+    line1?: string;
+    line2?: string;
+    city?: string;
+    state?: string;
+    postal_code?: string;
+    country?: string;
+}
 interface CheckoutTaxCustomerExemptionRequest {
     status?: CheckoutTaxExemptionStatus;
     reason?: string;
@@ -474,6 +482,7 @@ interface CreateCheckoutSessionRequest {
     cancelUrl?: string;
     customer_email?: string;
     customerEmail?: string;
+    currency?: string;
     metadata?: CheckoutMetadata;
     mode?: 'payment' | 'subscription' | 'setup';
     automatic_tax?: {
@@ -483,12 +492,35 @@ interface CreateCheckoutSessionRequest {
         allowed_countries: string[];
     };
     billing_address_collection?: 'auto' | 'required';
+    shipping_amount?: number;
+    shippingAmount?: number;
+    shipping_address?: CheckoutAddress;
+    shippingAddress?: CheckoutAddress;
+    billing_address?: CheckoutAddress;
+    billingAddress?: CheckoutAddress;
     tax?: CheckoutTaxRequest;
 }
+interface CheckoutTaxBreakdownItem {
+    jurisdiction: string;
+    rate_percent: number;
+    tax_amount: number;
+    taxable_amount: number;
+    source: 'manual_map' | 'manual_percent' | 'gateway' | 'external';
+}
+interface CheckoutSessionTax {
+    amount: number;
+    currency: string;
+    strategy: CheckoutTaxStrategy;
+    exemption_applied: boolean;
+    exemption_status: CheckoutTaxExemptionStatus;
+    breakdown?: CheckoutTaxBreakdownItem[] | null;
+}
 interface CheckoutSession {
     id: string;
     url: string;
     status: string;
+    payment_status?: string;
+    tax?: CheckoutSessionTax | null;
 }
 interface ContactSubmission {
     id: string;
@@ -2347,6 +2379,22 @@ interface CheckoutSessionOptions {
     logger?: LoaderLogger;
     fallbackProducts?: Product[];
     metadata?: CheckoutMetadata;
+    /**
+     * Optional currency override; defaults to the currency defined on each Stripe price.
+     */
+    currency?: string;
+    /**
+     * Optional shipping amount (in the smallest currency unit).
+     */
+    shippingAmount?: number;
+    /**
+     * Shipping address forwarded to the checkout API for tax estimation.
+     */
+    shippingAddress?: CheckoutAddress;
+    /**
+     * Billing address forwarded to the checkout API for tax estimation.
+     */
+    billingAddress?: CheckoutAddress;
     /**
      * Optional resolver to convert a product record into a Stripe price ID.
      */
@@ -2364,4 +2412,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, 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 };
+export { type ApiError, type ApiKey, ApiKeysClient, type ApiResponse, AuthClient, type AuthResponse, BaseClient, type BlogPost, type CacheConfig, CacheManager, CategoriesClient, type Category, type CheckoutAddress, CheckoutClient, type CheckoutMetadata, type CheckoutMetadataValue, type CheckoutSession, type CheckoutSessionOptions, type CheckoutSessionTax, type CheckoutTaxBreakdownItem, 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

@@ -2573,6 +2573,10 @@ async function createCheckoutSession(options) {
     logger = noopLogger,
     fallbackProducts,
     metadata,
+    currency,
+    shippingAmount,
+    shippingAddress,
+    billingAddress,
     priceIdResolver,
     tax
   } = options;
@@ -2628,6 +2632,21 @@ async function createCheckoutSession(options) {
       mode: mode === "test" ? "payment" : "payment",
       metadata
     };
+    if (currency) {
+      checkoutData.currency = currency;
+    }
+    if (typeof shippingAmount === "number") {
+      checkoutData.shipping_amount = shippingAmount;
+      checkoutData.shippingAmount = shippingAmount;
+    }
+    if (shippingAddress) {
+      checkoutData.shipping_address = shippingAddress;
+      checkoutData.shippingAddress = shippingAddress;
+    }
+    if (billingAddress) {
+      checkoutData.billing_address = billingAddress;
+      checkoutData.billingAddress = billingAddress;
+    }
     if (resolvedTax) {
       checkoutData.tax = resolvedTax;
     }

package/dist/index.mjs

@@ -2512,6 +2512,10 @@ async function createCheckoutSession(options) {
     logger = noopLogger,
     fallbackProducts,
     metadata,
+    currency,
+    shippingAmount,
+    shippingAddress,
+    billingAddress,
     priceIdResolver,
     tax
   } = options;
@@ -2567,6 +2571,21 @@ async function createCheckoutSession(options) {
       mode: mode === "test" ? "payment" : "payment",
       metadata
     };
+    if (currency) {
+      checkoutData.currency = currency;
+    }
+    if (typeof shippingAmount === "number") {
+      checkoutData.shipping_amount = shippingAmount;
+      checkoutData.shippingAmount = shippingAmount;
+    }
+    if (shippingAddress) {
+      checkoutData.shipping_address = shippingAddress;
+      checkoutData.shippingAddress = shippingAddress;
+    }
+    if (billingAddress) {
+      checkoutData.billing_address = billingAddress;
+      checkoutData.billingAddress = billingAddress;
+    }
     if (resolvedTax) {
       checkoutData.tax = resolvedTax;
     }

package/package.json

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

package/src/loaders.ts

@@ -18,7 +18,8 @@ import type {
   CreateCheckoutSessionRequest,
   CheckoutSession,
   CheckoutMetadata,
-  CheckoutTaxRequest
+  CheckoutTaxRequest,
+  CheckoutAddress
 } from './types';
 import {
   MAX_API_QUERY_LIMIT,
@@ -585,6 +586,22 @@ export interface CheckoutSessionOptions {
   logger?: LoaderLogger;
   fallbackProducts?: Product[];
   metadata?: CheckoutMetadata;
+  /**
+   * Optional currency override; defaults to the currency defined on each Stripe price.
+   */
+  currency?: string;
+  /**
+   * Optional shipping amount (in the smallest currency unit).
+   */
+  shippingAmount?: number;
+  /**
+   * Shipping address forwarded to the checkout API for tax estimation.
+   */
+  shippingAddress?: CheckoutAddress;
+  /**
+   * Billing address forwarded to the checkout API for tax estimation.
+   */
+  billingAddress?: CheckoutAddress;
   /**
    * Optional resolver to convert a product record into a Stripe price ID.
    */
@@ -613,6 +630,10 @@ export async function createCheckoutSession(
     logger = noopLogger,
     fallbackProducts,
     metadata,
+    currency,
+    shippingAmount,
+    shippingAddress,
+    billingAddress,
     priceIdResolver,
     tax
   } = options;
@@ -686,6 +707,25 @@ export async function createCheckoutSession(
       metadata,
     };
 
+    if (currency) {
+      checkoutData.currency = currency;
+    }
+
+    if (typeof shippingAmount === 'number') {
+      checkoutData.shipping_amount = shippingAmount;
+      checkoutData.shippingAmount = shippingAmount;
+    }
+
+    if (shippingAddress) {
+      checkoutData.shipping_address = shippingAddress;
+      checkoutData.shippingAddress = shippingAddress;
+    }
+
+    if (billingAddress) {
+      checkoutData.billing_address = billingAddress;
+      checkoutData.billingAddress = billingAddress;
+    }
+
     if (resolvedTax) {
       checkoutData.tax = resolvedTax;
     }

package/src/types/index.ts

@@ -410,6 +410,15 @@ export type CheckoutTaxExemptionStatus =
   | 'exempt'
   | 'reverse_charge';
 
+export interface CheckoutAddress {
+  line1?: string;
+  line2?: string;
+  city?: string;
+  state?: string;
+  postal_code?: string;
+  country?: string;
+}
+
 export interface CheckoutTaxCustomerExemptionRequest {
   status?: CheckoutTaxExemptionStatus;
   reason?: string;
@@ -467,6 +476,7 @@ export interface CreateCheckoutSessionRequest {
   cancelUrl?: string;   // Alternative naming
   customer_email?: string;
   customerEmail?: string;  // Alternative naming
+  currency?: string;
   metadata?: CheckoutMetadata;
   mode?: 'payment' | 'subscription' | 'setup';
   automatic_tax?: {
@@ -476,13 +486,38 @@ export interface CreateCheckoutSessionRequest {
     allowed_countries: string[];
   };
   billing_address_collection?: 'auto' | 'required';
+  shipping_amount?: number;
+  shippingAmount?: number;
+  shipping_address?: CheckoutAddress;
+  shippingAddress?: CheckoutAddress;
+  billing_address?: CheckoutAddress;
+  billingAddress?: CheckoutAddress;
   tax?: CheckoutTaxRequest;
 }
 
+export interface CheckoutTaxBreakdownItem {
+  jurisdiction: string;
+  rate_percent: number;
+  tax_amount: number;
+  taxable_amount: number;
+  source: 'manual_map' | 'manual_percent' | 'gateway' | 'external';
+}
+
+export interface CheckoutSessionTax {
+  amount: number;
+  currency: string;
+  strategy: CheckoutTaxStrategy;
+  exemption_applied: boolean;
+  exemption_status: CheckoutTaxExemptionStatus;
+  breakdown?: CheckoutTaxBreakdownItem[] | null;
+}
+
 export interface CheckoutSession {
   id: string;
   url: string;
   status: string;
+  payment_status?: string;
+  tax?: CheckoutSessionTax | null;
 }
 
 // Contact Forms