perspectapi-ts-sdk 7.2.0 → 7.2.3

package/dist/{chunk-OG4UB2MD.mjs → chunk-TFN5IR35.mjs}

@@ -18,10 +18,20 @@ var HttpClient = class {
   defaultHeaders;
   timeout;
   retries;
+  debug;
+  /**
+   * Debug-only logger. Off by default so request URLs, params, headers, and
+   * response bodies (emails, profiles, orders, Stripe identifiers) never
+   * leak into host logs. Opt in explicitly via `config.debug`.
+   */
+  dbg(...args) {
+    if (this.debug) console["log"](...args);
+  }
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.retries = config.retries || 3;
+    this.debug = config.debug ?? false;
     this.defaultHeaders = {
       "Content-Type": "application/json",
       "User-Agent": "perspectapi-ts-sdk/1.0.0",
@@ -66,15 +76,15 @@ var HttpClient = class {
   async request(endpoint, options = {}) {
     const url = this.buildUrl(endpoint, options.params);
     const requestOptions = this.buildRequestOptions(options);
-    console.log(`[HTTP Client] ====== Request Details ======`);
-    console.log(`[HTTP Client] Method: ${options.method || "GET"}`);
-    console.log(`[HTTP Client] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client] Full URL: ${url}`);
+    this.dbg(`[HTTP Client] ====== Request Details ======`);
+    this.dbg(`[HTTP Client] Method: ${options.method || "GET"}`);
+    this.dbg(`[HTTP Client] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client] Full URL: ${url}`);
     if (options.params) {
-      console.log(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
+      this.dbg(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
       if (options.params.slug_prefix) {
-        console.log(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
+        this.dbg(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
       }
     }
     const safeHeaders = { ...requestOptions.headers };
@@ -84,7 +94,7 @@ var HttpClient = class {
     if (safeHeaders["X-API-Key"]) {
       safeHeaders["X-API-Key"] = "[REDACTED]";
     }
-    console.log(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
+    this.dbg(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
     let lastError;
     for (let attempt = 0; attempt <= this.retries; attempt++) {
       try {
@@ -138,25 +148,25 @@ var HttpClient = class {
    */
   buildUrl(endpoint, params) {
     const url = `${this.baseUrl}${endpoint.startsWith("/") ? "" : "/"}${endpoint}`;
-    console.log(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
+    this.dbg(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
     if (!params || Object.keys(params).length === 0) {
-      console.log(`[HTTP Client - URL Builder] No params, returning: ${url}`);
+      this.dbg(`[HTTP Client - URL Builder] No params, returning: ${url}`);
       return url;
     }
-    console.log(`[HTTP Client - URL Builder] Processing params:`, params);
+    this.dbg(`[HTTP Client - URL Builder] Processing params:`, params);
     const searchParams = new URLSearchParams();
     Object.entries(params).forEach(([key, value]) => {
       if (value !== void 0 && value !== null) {
-        console.log(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
+        this.dbg(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
         searchParams.append(key, String(value));
       } else {
-        console.log(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
+        this.dbg(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
       }
     });
     const finalUrl = `${url}?${searchParams.toString()}`;
-    console.log(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
     return finalUrl;
   }
   /**
@@ -205,42 +215,42 @@ var HttpClient = class {
   async handleResponse(response) {
     const contentType = response.headers.get("content-type");
     const isJson = contentType?.includes("application/json");
-    console.log(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
-    console.log(`[HTTP Client - Response] Content-Type: ${contentType}`);
+    this.dbg(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
+    this.dbg(`[HTTP Client - Response] Content-Type: ${contentType}`);
     let data;
     try {
       data = isJson ? await response.json() : await response.text();
     } catch (error) {
-      console.error(`[HTTP Client - Response] Failed to parse response:`, error);
+      this.dbg(`[HTTP Client - Response] Failed to parse response:`, error);
       data = null;
     }
     const dataStr = JSON.stringify(data);
     if (dataStr && dataStr.length > 1e3) {
-      console.log(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
+      this.dbg(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
     } else {
-      console.log(`[HTTP Client - Response] Data:`, data);
+      this.dbg(`[HTTP Client - Response] Data:`, data);
     }
     if (!response.ok) {
-      console.error(`[HTTP Client - Response] Error response received`);
+      this.dbg(`[HTTP Client - Response] Error response received`);
       const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data
       });
-      console.error(`[HTTP Client - Response] Throwing error:`, error);
+      this.dbg(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
     if (isJson && typeof data === "object") {
       if ("data" in data || "message" in data || "error" in data) {
         const apiResponse = data;
-        console.log(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
+        this.dbg(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
         return apiResponse;
       }
-      console.log(`[HTTP Client - Response] Wrapping response in data property`);
+      this.dbg(`[HTTP Client - Response] Wrapping response in data property`);
       return { data, success: true };
     }
-    console.log(`[HTTP Client - Response] Returning text response`);
+    this.dbg(`[HTTP Client - Response] Returning text response`);
     return { data, success: true };
   }
   /**
@@ -945,6 +955,12 @@ var OrdersV2Client = class extends BaseV2Client {
    *
    * Set `notify_customer: true` when moving the order into a terminal
    * fulfillment state to send the customer fulfillment email.
+   *
+   * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+   * `notify_customer: true`, `cancellation_reason` is **required**: the API
+   * responds `400` if it is missing or blank, and the order is not mutated.
+   * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+   * — pass them explicitly if you need them.
    */
   async updateFulfillment(siteName, id, data) {
     const result = await this.patchOne(
@@ -960,6 +976,9 @@ var OrdersV2Client = class extends BaseV2Client {
   /**
    * Send the customer fulfillment template for an external delivery/packing
    * record without mutating a checkout session.
+   *
+   * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+   * is **required**: the API responds `400` if it is missing or blank.
    */
   async sendFulfillmentNotification(siteName, data) {
     return this.post(

package/dist/{index-fBvdMvWa.d.mts → index-hSqTwbPy.d.mts}

@@ -1087,6 +1087,11 @@ interface PerspectApiConfig {
     retries?: number;
     headers?: Record<string, string>;
     cache?: CacheConfig;
+    /**
+     * Opt-in verbose HTTP logging (URLs, params, headers, response bodies).
+     * Off by default so PII never leaks into host logs.
+     */
+    debug?: boolean;
 }
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 interface RequestOptions {
@@ -1108,6 +1113,13 @@ declare class HttpClient {
     private defaultHeaders;
     private timeout;
     private retries;
+    private debug;
+    /**
+     * Debug-only logger. Off by default so request URLs, params, headers, and
+     * response bodies (emails, profiles, orders, Stripe identifiers) never
+     * leak into host logs. Opt in explicitly via `config.debug`.
+     */
+    private dbg;
     constructor(config: PerspectApiConfig);
     /**
      * Update authentication token
@@ -1457,13 +1469,32 @@ interface V2OrderCreateParams {
     currency?: string;
     referral_code?: string;
     referrer_site_user_id?: string;
+    /**
+     * Subscription billing-cycle anchor as a Unix timestamp (seconds). When set
+     * on a `subscription` checkout, no charge is taken at checkout; the first
+     * invoice and the recurring cycle are aligned to this instant via Stripe
+     * `subscription_data.billing_cycle_anchor` with `proration_behavior: none`.
+     */
+    billing_cycle_anchor?: number;
 }
 interface V2OrderFulfillmentUpdate {
     fulfillment_status: string;
     tracking_number?: string;
+    /** Internal operator notes. Never shown to the customer. */
     notes?: string;
     fulfillment_details_text?: string;
     fulfillment_details_html?: string;
+    /**
+     * Customer-visible cancellation reason. **Required** when
+     * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer` is
+     * `true` — the request is rejected with `400` if it is missing or blank.
+     * Not derived from `notes` or `fulfillment_details_*`.
+     */
+    cancellation_reason?: string;
+    /** Customer-visible cancellation detail (plain text). Only used if provided. */
+    cancellation_details_text?: string;
+    /** Customer-visible cancellation detail (HTML). Only used if provided. */
+    cancellation_details_html?: string;
     /** When true, a terminal fulfillment status triggers a customer email. */
     notify_customer?: boolean;
 }
@@ -1481,6 +1512,17 @@ interface V2OrderFulfillmentNotificationParams {
     fulfillment_status?: string;
     fulfillment_details_text?: string;
     fulfillment_details_html?: string;
+    /**
+     * Customer-visible cancellation reason. **Required** when
+     * `fulfillment_status` is `cancelled`/`canceled` — the request is rejected
+     * with `400` if it is missing or blank. Not derived from
+     * `fulfillment_details_*`.
+     */
+    cancellation_reason?: string;
+    /** Customer-visible cancellation detail (plain text). Only used if provided. */
+    cancellation_details_text?: string;
+    /** Customer-visible cancellation detail (HTML). Only used if provided. */
+    cancellation_details_html?: string;
     line_items?: V2OrderFulfillmentNotificationLineItem[];
     amount_total?: number;
     currency?: string;
@@ -2003,11 +2045,20 @@ declare class OrdersV2Client extends BaseV2Client {
      *
      * Set `notify_customer: true` when moving the order into a terminal
      * fulfillment state to send the customer fulfillment email.
+     *
+     * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+     * `notify_customer: true`, `cancellation_reason` is **required**: the API
+     * responds `400` if it is missing or blank, and the order is not mutated.
+     * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+     * — pass them explicitly if you need them.
      */
     updateFulfillment(siteName: string, id: string, data: V2OrderFulfillmentUpdate): Promise<V2Order>;
     /**
      * Send the customer fulfillment template for an external delivery/packing
      * record without mutating a checkout session.
+     *
+     * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+     * is **required**: the API responds `400` if it is missing or blank.
      */
     sendFulfillmentNotification(siteName: string, data: V2OrderFulfillmentNotificationParams): Promise<V2OrderFulfillmentNotificationResult>;
     private withOrderTags;

package/dist/{index-fBvdMvWa.d.ts → index-hSqTwbPy.d.ts}

@@ -1087,6 +1087,11 @@ interface PerspectApiConfig {
     retries?: number;
     headers?: Record<string, string>;
     cache?: CacheConfig;
+    /**
+     * Opt-in verbose HTTP logging (URLs, params, headers, response bodies).
+     * Off by default so PII never leaks into host logs.
+     */
+    debug?: boolean;
 }
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
 interface RequestOptions {
@@ -1108,6 +1113,13 @@ declare class HttpClient {
     private defaultHeaders;
     private timeout;
     private retries;
+    private debug;
+    /**
+     * Debug-only logger. Off by default so request URLs, params, headers, and
+     * response bodies (emails, profiles, orders, Stripe identifiers) never
+     * leak into host logs. Opt in explicitly via `config.debug`.
+     */
+    private dbg;
     constructor(config: PerspectApiConfig);
     /**
      * Update authentication token
@@ -1457,13 +1469,32 @@ interface V2OrderCreateParams {
     currency?: string;
     referral_code?: string;
     referrer_site_user_id?: string;
+    /**
+     * Subscription billing-cycle anchor as a Unix timestamp (seconds). When set
+     * on a `subscription` checkout, no charge is taken at checkout; the first
+     * invoice and the recurring cycle are aligned to this instant via Stripe
+     * `subscription_data.billing_cycle_anchor` with `proration_behavior: none`.
+     */
+    billing_cycle_anchor?: number;
 }
 interface V2OrderFulfillmentUpdate {
     fulfillment_status: string;
     tracking_number?: string;
+    /** Internal operator notes. Never shown to the customer. */
     notes?: string;
     fulfillment_details_text?: string;
     fulfillment_details_html?: string;
+    /**
+     * Customer-visible cancellation reason. **Required** when
+     * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer` is
+     * `true` — the request is rejected with `400` if it is missing or blank.
+     * Not derived from `notes` or `fulfillment_details_*`.
+     */
+    cancellation_reason?: string;
+    /** Customer-visible cancellation detail (plain text). Only used if provided. */
+    cancellation_details_text?: string;
+    /** Customer-visible cancellation detail (HTML). Only used if provided. */
+    cancellation_details_html?: string;
     /** When true, a terminal fulfillment status triggers a customer email. */
     notify_customer?: boolean;
 }
@@ -1481,6 +1512,17 @@ interface V2OrderFulfillmentNotificationParams {
     fulfillment_status?: string;
     fulfillment_details_text?: string;
     fulfillment_details_html?: string;
+    /**
+     * Customer-visible cancellation reason. **Required** when
+     * `fulfillment_status` is `cancelled`/`canceled` — the request is rejected
+     * with `400` if it is missing or blank. Not derived from
+     * `fulfillment_details_*`.
+     */
+    cancellation_reason?: string;
+    /** Customer-visible cancellation detail (plain text). Only used if provided. */
+    cancellation_details_text?: string;
+    /** Customer-visible cancellation detail (HTML). Only used if provided. */
+    cancellation_details_html?: string;
     line_items?: V2OrderFulfillmentNotificationLineItem[];
     amount_total?: number;
     currency?: string;
@@ -2003,11 +2045,20 @@ declare class OrdersV2Client extends BaseV2Client {
      *
      * Set `notify_customer: true` when moving the order into a terminal
      * fulfillment state to send the customer fulfillment email.
+     *
+     * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+     * `notify_customer: true`, `cancellation_reason` is **required**: the API
+     * responds `400` if it is missing or blank, and the order is not mutated.
+     * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+     * — pass them explicitly if you need them.
      */
     updateFulfillment(siteName: string, id: string, data: V2OrderFulfillmentUpdate): Promise<V2Order>;
     /**
      * Send the customer fulfillment template for an external delivery/packing
      * record without mutating a checkout session.
+     *
+     * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+     * is **required**: the API responds `400` if it is missing or blank.
      */
     sendFulfillmentNotification(siteName: string, data: V2OrderFulfillmentNotificationParams): Promise<V2OrderFulfillmentNotificationResult>;
     private withOrderTags;

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { H as HttpClient, C as CacheManager, A as ApiResponse, a as CachePolicy, b as CacheInvalidateOptions, U as User, c as ContentQueryParams, P as PaginatedResponse, d as Content, e as ContentCategoryResponse, f as CreateContentRequest, g as UpdateContentRequest, h as ApiKey, i as CreateApiKeyRequest, j as UpdateApiKeyRequest, O as Organization, k as CreateOrganizationRequest, S as Site, l as CreateSiteRequest, m as ProductQueryParams, n as Product, o as CreateProductRequest, p as ProductSku, q as CreateProductSkuRequest, r as Category, s as CreateCategoryRequest, W as Webhook, t as CreateWebhookRequest, u as CreateCheckoutSessionRequest, v as CheckoutSession, w as CreateContactRequest, x as ContactSubmitResponse, y as ContactStatusResponse, z as ContactSubmission, B as CreateNewsletterSubscriptionRequest, N as NewsletterSubscribeResponse, D as NewsletterConfirmResponse, E as NewsletterUnsubscribeRequest, F as NewsletterUnsubscribeResponse, G as NewsletterPreferences, I as NewsletterList, J as NewsletterCampaignListResponse, K as NewsletterCampaignDetail, L as NewsletterStatusResponse, M as NewsletterManagementSubscriptionsListResponse, Q as NewsletterManagementSubscription, R as NewsletterSubscriptionSyncRequest, T as NewsletterSubscriptionSyncResponse, V as NewsletterSubscriptionsBulkUpdateRequest, X as NewsletterSubscriptionsBulkUpdateResponse, Y as NewsletterSubscriptionMembershipUpdateRequest, Z as NewsletterSubscriptionsImportRequest, _ as NewsletterSubscriptionsImportResponse, $ as NewsletterManagementList, a0 as NewsletterManagementSeries, a1 as NewsletterManagementCampaignListResponse, a2 as NewsletterManagementCampaign, a3 as NewsletterCampaignTestSendRequest, a4 as NewsletterCampaignTestSendResponse, a5 as NewsletterManagementStatsResponse, a6 as NewsletterExportCreateRequest, a7 as NewsletterExportCreateResponse, a8 as RequestOtpRequest, a9 as VerifyOtpRequest, aa as VerifyOtpResponse, ab as SiteUser, ac as SiteUserProfile, ad as UpdateSiteUserRequest, ae as SiteUserOrder, af as SiteUserSubscription, ag as CancelSubscriptionRequest, ah as CancelSubscriptionResponse, ai as CreditBalance, aj as CreditBalanceWithTransactions, ak as GrantCreditRequest, al as ProductBundleGroup, am as CreateBundleGroupRequest, an as BundleCollection, ao as BundleCollectionItemWithProduct, ap as CreateBundleCollectionRequest, aq as AddCollectionItemRequest, ar as BundleCollectionItem, as as PerspectApiConfig, at as CacheAdapter, au as BlogPost, av as CheckoutMetadata, aw as CheckoutAddress, ax as CheckoutTaxRequest } from './index-fBvdMvWa.mjs';
-export { aE as ApiError, aD as CacheConfig, aG as CategorySummary, c4 as CheckoutMetadataValue, c9 as CheckoutSessionTax, c8 as CheckoutTaxBreakdownItem, c7 as CheckoutTaxCustomerExemptionRequest, c6 as CheckoutTaxExemptionStatus, c5 as CheckoutTaxStrategy, b_ as ContentStatus, b$ as ContentType, c2 as CreatePaymentGatewayRequest, cb as CreditTransaction, cc as HttpMethod, aF as MediaItem, aJ as NewsletterCampaignSummary, aK as NewsletterManagementListMembership, aP as NewsletterManagementPagination, aI as NewsletterSubscription, aN as NewsletterSubscriptionImportRowRequest, aL as NewsletterSubscriptionsBulkAction, aM as NewsletterSubscriptionsBulkOutcome, aO as NewsletterSubscriptionsImportRowResult, bZ as PaginationParams, aH as PaymentGateway, aC as PerspectApiError, ay as PerspectApiV2Client, aA as PerspectV2Error, c0 as ProductSkuMediaItem, c1 as ProductSkuOption, cd as RequestOptions, aQ as SetProfileValueRequest, ca as SubscriptionCancellationMode, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, c3 as WebhookEventType, aB as createApiError, az as createPerspectApiV2Client } from './index-fBvdMvWa.mjs';
+import { H as HttpClient, C as CacheManager, A as ApiResponse, a as CachePolicy, b as CacheInvalidateOptions, U as User, c as ContentQueryParams, P as PaginatedResponse, d as Content, e as ContentCategoryResponse, f as CreateContentRequest, g as UpdateContentRequest, h as ApiKey, i as CreateApiKeyRequest, j as UpdateApiKeyRequest, O as Organization, k as CreateOrganizationRequest, S as Site, l as CreateSiteRequest, m as ProductQueryParams, n as Product, o as CreateProductRequest, p as ProductSku, q as CreateProductSkuRequest, r as Category, s as CreateCategoryRequest, W as Webhook, t as CreateWebhookRequest, u as CreateCheckoutSessionRequest, v as CheckoutSession, w as CreateContactRequest, x as ContactSubmitResponse, y as ContactStatusResponse, z as ContactSubmission, B as CreateNewsletterSubscriptionRequest, N as NewsletterSubscribeResponse, D as NewsletterConfirmResponse, E as NewsletterUnsubscribeRequest, F as NewsletterUnsubscribeResponse, G as NewsletterPreferences, I as NewsletterList, J as NewsletterCampaignListResponse, K as NewsletterCampaignDetail, L as NewsletterStatusResponse, M as NewsletterManagementSubscriptionsListResponse, Q as NewsletterManagementSubscription, R as NewsletterSubscriptionSyncRequest, T as NewsletterSubscriptionSyncResponse, V as NewsletterSubscriptionsBulkUpdateRequest, X as NewsletterSubscriptionsBulkUpdateResponse, Y as NewsletterSubscriptionMembershipUpdateRequest, Z as NewsletterSubscriptionsImportRequest, _ as NewsletterSubscriptionsImportResponse, $ as NewsletterManagementList, a0 as NewsletterManagementSeries, a1 as NewsletterManagementCampaignListResponse, a2 as NewsletterManagementCampaign, a3 as NewsletterCampaignTestSendRequest, a4 as NewsletterCampaignTestSendResponse, a5 as NewsletterManagementStatsResponse, a6 as NewsletterExportCreateRequest, a7 as NewsletterExportCreateResponse, a8 as RequestOtpRequest, a9 as VerifyOtpRequest, aa as VerifyOtpResponse, ab as SiteUser, ac as SiteUserProfile, ad as UpdateSiteUserRequest, ae as SiteUserOrder, af as SiteUserSubscription, ag as CancelSubscriptionRequest, ah as CancelSubscriptionResponse, ai as CreditBalance, aj as CreditBalanceWithTransactions, ak as GrantCreditRequest, al as ProductBundleGroup, am as CreateBundleGroupRequest, an as BundleCollection, ao as BundleCollectionItemWithProduct, ap as CreateBundleCollectionRequest, aq as AddCollectionItemRequest, ar as BundleCollectionItem, as as PerspectApiConfig, at as CacheAdapter, au as BlogPost, av as CheckoutMetadata, aw as CheckoutAddress, ax as CheckoutTaxRequest } from './index-hSqTwbPy.mjs';
+export { aE as ApiError, aD as CacheConfig, aG as CategorySummary, c4 as CheckoutMetadataValue, c9 as CheckoutSessionTax, c8 as CheckoutTaxBreakdownItem, c7 as CheckoutTaxCustomerExemptionRequest, c6 as CheckoutTaxExemptionStatus, c5 as CheckoutTaxStrategy, b_ as ContentStatus, b$ as ContentType, c2 as CreatePaymentGatewayRequest, cb as CreditTransaction, cc as HttpMethod, aF as MediaItem, aJ as NewsletterCampaignSummary, aK as NewsletterManagementListMembership, aP as NewsletterManagementPagination, aI as NewsletterSubscription, aN as NewsletterSubscriptionImportRowRequest, aL as NewsletterSubscriptionsBulkAction, aM as NewsletterSubscriptionsBulkOutcome, aO as NewsletterSubscriptionsImportRowResult, bZ as PaginationParams, aH as PaymentGateway, aC as PerspectApiError, ay as PerspectApiV2Client, aA as PerspectV2Error, c0 as ProductSkuMediaItem, c1 as ProductSkuOption, cd as RequestOptions, aQ as SetProfileValueRequest, ca as SubscriptionCancellationMode, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, c3 as WebhookEventType, aB as createApiError, az as createPerspectApiV2Client } from './index-hSqTwbPy.mjs';
 
 /**
  * v1 deprecation constants — kept in sync with the backend's
@@ -1774,9 +1774,21 @@ declare class SiteUsersClient extends BaseClient {
     updateOrderFulfillment(siteName: string, sessionId: string, data: {
         fulfillment_status: string;
         tracking_number?: string;
+        /** Internal operator notes. Never shown to the customer. */
         notes?: string;
         fulfillment_details_text?: string;
         fulfillment_details_html?: string;
+        /**
+         * Customer-visible cancellation reason. Required when
+         * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer`
+         * is `true` — the request is rejected with `400` if missing or blank.
+         * Not derived from `notes` or `fulfillment_details_*`.
+         */
+        cancellation_reason?: string;
+        /** Customer-visible cancellation detail (plain text). Only used if provided. */
+        cancellation_details_text?: string;
+        /** Customer-visible cancellation detail (HTML). Only used if provided. */
+        cancellation_details_html?: string;
         notify_customer?: boolean;
     }): Promise<ApiResponse<{
         success: boolean;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { H as HttpClient, C as CacheManager, A as ApiResponse, a as CachePolicy, b as CacheInvalidateOptions, U as User, c as ContentQueryParams, P as PaginatedResponse, d as Content, e as ContentCategoryResponse, f as CreateContentRequest, g as UpdateContentRequest, h as ApiKey, i as CreateApiKeyRequest, j as UpdateApiKeyRequest, O as Organization, k as CreateOrganizationRequest, S as Site, l as CreateSiteRequest, m as ProductQueryParams, n as Product, o as CreateProductRequest, p as ProductSku, q as CreateProductSkuRequest, r as Category, s as CreateCategoryRequest, W as Webhook, t as CreateWebhookRequest, u as CreateCheckoutSessionRequest, v as CheckoutSession, w as CreateContactRequest, x as ContactSubmitResponse, y as ContactStatusResponse, z as ContactSubmission, B as CreateNewsletterSubscriptionRequest, N as NewsletterSubscribeResponse, D as NewsletterConfirmResponse, E as NewsletterUnsubscribeRequest, F as NewsletterUnsubscribeResponse, G as NewsletterPreferences, I as NewsletterList, J as NewsletterCampaignListResponse, K as NewsletterCampaignDetail, L as NewsletterStatusResponse, M as NewsletterManagementSubscriptionsListResponse, Q as NewsletterManagementSubscription, R as NewsletterSubscriptionSyncRequest, T as NewsletterSubscriptionSyncResponse, V as NewsletterSubscriptionsBulkUpdateRequest, X as NewsletterSubscriptionsBulkUpdateResponse, Y as NewsletterSubscriptionMembershipUpdateRequest, Z as NewsletterSubscriptionsImportRequest, _ as NewsletterSubscriptionsImportResponse, $ as NewsletterManagementList, a0 as NewsletterManagementSeries, a1 as NewsletterManagementCampaignListResponse, a2 as NewsletterManagementCampaign, a3 as NewsletterCampaignTestSendRequest, a4 as NewsletterCampaignTestSendResponse, a5 as NewsletterManagementStatsResponse, a6 as NewsletterExportCreateRequest, a7 as NewsletterExportCreateResponse, a8 as RequestOtpRequest, a9 as VerifyOtpRequest, aa as VerifyOtpResponse, ab as SiteUser, ac as SiteUserProfile, ad as UpdateSiteUserRequest, ae as SiteUserOrder, af as SiteUserSubscription, ag as CancelSubscriptionRequest, ah as CancelSubscriptionResponse, ai as CreditBalance, aj as CreditBalanceWithTransactions, ak as GrantCreditRequest, al as ProductBundleGroup, am as CreateBundleGroupRequest, an as BundleCollection, ao as BundleCollectionItemWithProduct, ap as CreateBundleCollectionRequest, aq as AddCollectionItemRequest, ar as BundleCollectionItem, as as PerspectApiConfig, at as CacheAdapter, au as BlogPost, av as CheckoutMetadata, aw as CheckoutAddress, ax as CheckoutTaxRequest } from './index-fBvdMvWa.js';
-export { aE as ApiError, aD as CacheConfig, aG as CategorySummary, c4 as CheckoutMetadataValue, c9 as CheckoutSessionTax, c8 as CheckoutTaxBreakdownItem, c7 as CheckoutTaxCustomerExemptionRequest, c6 as CheckoutTaxExemptionStatus, c5 as CheckoutTaxStrategy, b_ as ContentStatus, b$ as ContentType, c2 as CreatePaymentGatewayRequest, cb as CreditTransaction, cc as HttpMethod, aF as MediaItem, aJ as NewsletterCampaignSummary, aK as NewsletterManagementListMembership, aP as NewsletterManagementPagination, aI as NewsletterSubscription, aN as NewsletterSubscriptionImportRowRequest, aL as NewsletterSubscriptionsBulkAction, aM as NewsletterSubscriptionsBulkOutcome, aO as NewsletterSubscriptionsImportRowResult, bZ as PaginationParams, aH as PaymentGateway, aC as PerspectApiError, ay as PerspectApiV2Client, aA as PerspectV2Error, c0 as ProductSkuMediaItem, c1 as ProductSkuOption, cd as RequestOptions, aQ as SetProfileValueRequest, ca as SubscriptionCancellationMode, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, c3 as WebhookEventType, aB as createApiError, az as createPerspectApiV2Client } from './index-fBvdMvWa.js';
+import { H as HttpClient, C as CacheManager, A as ApiResponse, a as CachePolicy, b as CacheInvalidateOptions, U as User, c as ContentQueryParams, P as PaginatedResponse, d as Content, e as ContentCategoryResponse, f as CreateContentRequest, g as UpdateContentRequest, h as ApiKey, i as CreateApiKeyRequest, j as UpdateApiKeyRequest, O as Organization, k as CreateOrganizationRequest, S as Site, l as CreateSiteRequest, m as ProductQueryParams, n as Product, o as CreateProductRequest, p as ProductSku, q as CreateProductSkuRequest, r as Category, s as CreateCategoryRequest, W as Webhook, t as CreateWebhookRequest, u as CreateCheckoutSessionRequest, v as CheckoutSession, w as CreateContactRequest, x as ContactSubmitResponse, y as ContactStatusResponse, z as ContactSubmission, B as CreateNewsletterSubscriptionRequest, N as NewsletterSubscribeResponse, D as NewsletterConfirmResponse, E as NewsletterUnsubscribeRequest, F as NewsletterUnsubscribeResponse, G as NewsletterPreferences, I as NewsletterList, J as NewsletterCampaignListResponse, K as NewsletterCampaignDetail, L as NewsletterStatusResponse, M as NewsletterManagementSubscriptionsListResponse, Q as NewsletterManagementSubscription, R as NewsletterSubscriptionSyncRequest, T as NewsletterSubscriptionSyncResponse, V as NewsletterSubscriptionsBulkUpdateRequest, X as NewsletterSubscriptionsBulkUpdateResponse, Y as NewsletterSubscriptionMembershipUpdateRequest, Z as NewsletterSubscriptionsImportRequest, _ as NewsletterSubscriptionsImportResponse, $ as NewsletterManagementList, a0 as NewsletterManagementSeries, a1 as NewsletterManagementCampaignListResponse, a2 as NewsletterManagementCampaign, a3 as NewsletterCampaignTestSendRequest, a4 as NewsletterCampaignTestSendResponse, a5 as NewsletterManagementStatsResponse, a6 as NewsletterExportCreateRequest, a7 as NewsletterExportCreateResponse, a8 as RequestOtpRequest, a9 as VerifyOtpRequest, aa as VerifyOtpResponse, ab as SiteUser, ac as SiteUserProfile, ad as UpdateSiteUserRequest, ae as SiteUserOrder, af as SiteUserSubscription, ag as CancelSubscriptionRequest, ah as CancelSubscriptionResponse, ai as CreditBalance, aj as CreditBalanceWithTransactions, ak as GrantCreditRequest, al as ProductBundleGroup, am as CreateBundleGroupRequest, an as BundleCollection, ao as BundleCollectionItemWithProduct, ap as CreateBundleCollectionRequest, aq as AddCollectionItemRequest, ar as BundleCollectionItem, as as PerspectApiConfig, at as CacheAdapter, au as BlogPost, av as CheckoutMetadata, aw as CheckoutAddress, ax as CheckoutTaxRequest } from './index-hSqTwbPy.js';
+export { aE as ApiError, aD as CacheConfig, aG as CategorySummary, c4 as CheckoutMetadataValue, c9 as CheckoutSessionTax, c8 as CheckoutTaxBreakdownItem, c7 as CheckoutTaxCustomerExemptionRequest, c6 as CheckoutTaxExemptionStatus, c5 as CheckoutTaxStrategy, b_ as ContentStatus, b$ as ContentType, c2 as CreatePaymentGatewayRequest, cb as CreditTransaction, cc as HttpMethod, aF as MediaItem, aJ as NewsletterCampaignSummary, aK as NewsletterManagementListMembership, aP as NewsletterManagementPagination, aI as NewsletterSubscription, aN as NewsletterSubscriptionImportRowRequest, aL as NewsletterSubscriptionsBulkAction, aM as NewsletterSubscriptionsBulkOutcome, aO as NewsletterSubscriptionsImportRowResult, bZ as PaginationParams, aH as PaymentGateway, aC as PerspectApiError, ay as PerspectApiV2Client, aA as PerspectV2Error, c0 as ProductSkuMediaItem, c1 as ProductSkuOption, cd as RequestOptions, aQ as SetProfileValueRequest, ca as SubscriptionCancellationMode, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, c3 as WebhookEventType, aB as createApiError, az as createPerspectApiV2Client } from './index-hSqTwbPy.js';
 
 /**
  * v1 deprecation constants — kept in sync with the backend's
@@ -1774,9 +1774,21 @@ declare class SiteUsersClient extends BaseClient {
     updateOrderFulfillment(siteName: string, sessionId: string, data: {
         fulfillment_status: string;
         tracking_number?: string;
+        /** Internal operator notes. Never shown to the customer. */
         notes?: string;
         fulfillment_details_text?: string;
         fulfillment_details_html?: string;
+        /**
+         * Customer-visible cancellation reason. Required when
+         * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer`
+         * is `true` — the request is rejected with `400` if missing or blank.
+         * Not derived from `notes` or `fulfillment_details_*`.
+         */
+        cancellation_reason?: string;
+        /** Customer-visible cancellation detail (plain text). Only used if provided. */
+        cancellation_details_text?: string;
+        /** Customer-visible cancellation detail (HTML). Only used if provided. */
+        cancellation_details_html?: string;
         notify_customer?: boolean;
     }): Promise<ApiResponse<{
         success: boolean;

package/dist/index.js

@@ -104,10 +104,20 @@ var HttpClient = class {
   defaultHeaders;
   timeout;
   retries;
+  debug;
+  /**
+   * Debug-only logger. Off by default so request URLs, params, headers, and
+   * response bodies (emails, profiles, orders, Stripe identifiers) never
+   * leak into host logs. Opt in explicitly via `config.debug`.
+   */
+  dbg(...args) {
+    if (this.debug) console["log"](...args);
+  }
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.retries = config.retries || 3;
+    this.debug = config.debug ?? false;
     this.defaultHeaders = {
       "Content-Type": "application/json",
       "User-Agent": "perspectapi-ts-sdk/1.0.0",
@@ -152,15 +162,15 @@ var HttpClient = class {
   async request(endpoint, options = {}) {
     const url = this.buildUrl(endpoint, options.params);
     const requestOptions = this.buildRequestOptions(options);
-    console.log(`[HTTP Client] ====== Request Details ======`);
-    console.log(`[HTTP Client] Method: ${options.method || "GET"}`);
-    console.log(`[HTTP Client] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client] Full URL: ${url}`);
+    this.dbg(`[HTTP Client] ====== Request Details ======`);
+    this.dbg(`[HTTP Client] Method: ${options.method || "GET"}`);
+    this.dbg(`[HTTP Client] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client] Full URL: ${url}`);
     if (options.params) {
-      console.log(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
+      this.dbg(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
       if (options.params.slug_prefix) {
-        console.log(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
+        this.dbg(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
       }
     }
     const safeHeaders = { ...requestOptions.headers };
@@ -170,7 +180,7 @@ var HttpClient = class {
     if (safeHeaders["X-API-Key"]) {
       safeHeaders["X-API-Key"] = "[REDACTED]";
     }
-    console.log(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
+    this.dbg(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
     let lastError;
     for (let attempt = 0; attempt <= this.retries; attempt++) {
       try {
@@ -224,25 +234,25 @@ var HttpClient = class {
    */
   buildUrl(endpoint, params) {
     const url = `${this.baseUrl}${endpoint.startsWith("/") ? "" : "/"}${endpoint}`;
-    console.log(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
+    this.dbg(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
     if (!params || Object.keys(params).length === 0) {
-      console.log(`[HTTP Client - URL Builder] No params, returning: ${url}`);
+      this.dbg(`[HTTP Client - URL Builder] No params, returning: ${url}`);
       return url;
     }
-    console.log(`[HTTP Client - URL Builder] Processing params:`, params);
+    this.dbg(`[HTTP Client - URL Builder] Processing params:`, params);
     const searchParams = new URLSearchParams();
     Object.entries(params).forEach(([key, value]) => {
       if (value !== void 0 && value !== null) {
-        console.log(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
+        this.dbg(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
         searchParams.append(key, String(value));
       } else {
-        console.log(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
+        this.dbg(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
       }
     });
     const finalUrl = `${url}?${searchParams.toString()}`;
-    console.log(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
     return finalUrl;
   }
   /**
@@ -291,42 +301,42 @@ var HttpClient = class {
   async handleResponse(response) {
     const contentType = response.headers.get("content-type");
     const isJson = contentType?.includes("application/json");
-    console.log(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
-    console.log(`[HTTP Client - Response] Content-Type: ${contentType}`);
+    this.dbg(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
+    this.dbg(`[HTTP Client - Response] Content-Type: ${contentType}`);
     let data;
     try {
       data = isJson ? await response.json() : await response.text();
     } catch (error) {
-      console.error(`[HTTP Client - Response] Failed to parse response:`, error);
+      this.dbg(`[HTTP Client - Response] Failed to parse response:`, error);
       data = null;
     }
     const dataStr = JSON.stringify(data);
     if (dataStr && dataStr.length > 1e3) {
-      console.log(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
+      this.dbg(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
     } else {
-      console.log(`[HTTP Client - Response] Data:`, data);
+      this.dbg(`[HTTP Client - Response] Data:`, data);
     }
     if (!response.ok) {
-      console.error(`[HTTP Client - Response] Error response received`);
+      this.dbg(`[HTTP Client - Response] Error response received`);
       const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data
       });
-      console.error(`[HTTP Client - Response] Throwing error:`, error);
+      this.dbg(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
     if (isJson && typeof data === "object") {
       if ("data" in data || "message" in data || "error" in data) {
         const apiResponse = data;
-        console.log(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
+        this.dbg(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
         return apiResponse;
       }
-      console.log(`[HTTP Client - Response] Wrapping response in data property`);
+      this.dbg(`[HTTP Client - Response] Wrapping response in data property`);
       return { data, success: true };
     }
-    console.log(`[HTTP Client - Response] Returning text response`);
+    this.dbg(`[HTTP Client - Response] Returning text response`);
     return { data, success: true };
   }
   /**
@@ -1031,6 +1041,12 @@ var OrdersV2Client = class extends BaseV2Client {
    *
    * Set `notify_customer: true` when moving the order into a terminal
    * fulfillment state to send the customer fulfillment email.
+   *
+   * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+   * `notify_customer: true`, `cancellation_reason` is **required**: the API
+   * responds `400` if it is missing or blank, and the order is not mutated.
+   * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+   * — pass them explicitly if you need them.
    */
   async updateFulfillment(siteName, id, data) {
     const result = await this.patchOne(
@@ -1046,6 +1062,9 @@ var OrdersV2Client = class extends BaseV2Client {
   /**
    * Send the customer fulfillment template for an external delivery/packing
    * record without mutating a checkout session.
+   *
+   * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+   * is **required**: the API responds `400` if it is missing or blank.
    */
   async sendFulfillmentNotification(siteName, data) {
     return this.post(

package/dist/index.mjs

@@ -7,7 +7,7 @@ import {
   PerspectV2Error,
   createApiError,
   createPerspectApiV2Client
-} from "./chunk-OG4UB2MD.mjs";
+} from "./chunk-TFN5IR35.mjs";
 
 // src/deprecation.ts
 var V1_SUNSET_DATE = "2026-06-01";

package/dist/v2/index.d.mts

@@ -1 +1 @@
-export { cq as ApiKeysV2Client, cf as BaseV2Client, ci as CategoriesV2Client, cj as CollectionsV2Client, cn as ContactsV2Client, cg as ContentV2Client, ct as CreditsV2Client, cu as EmailV2Client, cm as NewsletterV2Client, ck as OrdersV2Client, co as OrganizationsV2Client, ay as PerspectApiV2Client, ce as PerspectApiV2Config, aA as PerspectV2Error, ch as ProductsV2Client, cl as SiteUsersV2Client, cp as SitesV2Client, cs as SubscriptionsV2Client, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, cr as WebhooksV2Client, az as createPerspectApiV2Client } from '../index-fBvdMvWa.mjs';
+export { cq as ApiKeysV2Client, cf as BaseV2Client, ci as CategoriesV2Client, cj as CollectionsV2Client, cn as ContactsV2Client, cg as ContentV2Client, ct as CreditsV2Client, cu as EmailV2Client, cm as NewsletterV2Client, ck as OrdersV2Client, co as OrganizationsV2Client, ay as PerspectApiV2Client, ce as PerspectApiV2Config, aA as PerspectV2Error, ch as ProductsV2Client, cl as SiteUsersV2Client, cp as SitesV2Client, cs as SubscriptionsV2Client, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, cr as WebhooksV2Client, az as createPerspectApiV2Client } from '../index-hSqTwbPy.mjs';

package/dist/v2/index.d.ts

@@ -1 +1 @@
-export { cq as ApiKeysV2Client, cf as BaseV2Client, ci as CategoriesV2Client, cj as CollectionsV2Client, cn as ContactsV2Client, cg as ContentV2Client, ct as CreditsV2Client, cu as EmailV2Client, cm as NewsletterV2Client, ck as OrdersV2Client, co as OrganizationsV2Client, ay as PerspectApiV2Client, ce as PerspectApiV2Config, aA as PerspectV2Error, ch as ProductsV2Client, cl as SiteUsersV2Client, cp as SitesV2Client, cs as SubscriptionsV2Client, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, cr as WebhooksV2Client, az as createPerspectApiV2Client } from '../index-fBvdMvWa.js';
+export { cq as ApiKeysV2Client, cf as BaseV2Client, ci as CategoriesV2Client, cj as CollectionsV2Client, cn as ContactsV2Client, cg as ContentV2Client, ct as CreditsV2Client, cu as EmailV2Client, cm as NewsletterV2Client, ck as OrdersV2Client, co as OrganizationsV2Client, ay as PerspectApiV2Client, ce as PerspectApiV2Config, aA as PerspectV2Error, ch as ProductsV2Client, cl as SiteUsersV2Client, cp as SitesV2Client, cs as SubscriptionsV2Client, bH as V2ApiKey, bS as V2CancelSubscriptionResult, b4 as V2Category, b5 as V2CategoryCreateParams, b6 as V2CategoryUpdateParams, b7 as V2Collection, b9 as V2CollectionCreateParams, b8 as V2CollectionItem, ba as V2CollectionUpdateParams, bE as V2ContactSubmission, aY as V2Content, aZ as V2ContentCreateParams, a$ as V2ContentListParams, a_ as V2ContentUpdateParams, bU as V2CreditBalance, bT as V2CreditTransaction, aT as V2Deleted, bX as V2EmailSendParams, bY as V2EmailSendResult, aU as V2Error, aV as V2ErrorType, bV as V2GrantCreditParams, bW as V2GrantCreditResult, aS as V2List, aX as V2Media, bv as V2NewsletterCampaign, bC as V2NewsletterImportRequest, bD as V2NewsletterImportResult, bu as V2NewsletterList, bx as V2NewsletterListCreateParams, by as V2NewsletterListUpdateParams, bt as V2NewsletterSubscription, bB as V2NewsletterSubscriptionListMembershipUpdate, bz as V2NewsletterSyncInput, bA as V2NewsletterSyncResult, bw as V2NewsletterTrackingResponse, aR as V2Object, bb as V2Order, bf as V2OrderAddress, bh as V2OrderCreateParams, bm as V2OrderCreateResult, bj as V2OrderFulfillmentNotificationLineItem, bk as V2OrderFulfillmentNotificationParams, bl as V2OrderFulfillmentNotificationResult, bi as V2OrderFulfillmentUpdate, be as V2OrderLineItem, bd as V2OrderLineItemPriceData, bc as V2OrderListParams, bg as V2OrderTaxRequest, bF as V2Organization, aW as V2PaginationParams, b0 as V2Product, b1 as V2ProductCreateParams, b3 as V2ProductListParams, b2 as V2ProductUpdateParams, bG as V2Site, bn as V2SiteUser, bq as V2SiteUserListParams, bp as V2SiteUserMeUpdateParams, bs as V2SiteUserProfile, bM as V2SiteUserSubscription, bo as V2SiteUserUpdateParams, br as V2SiteUserWithProfile, bO as V2SubscriptionCancelParams, bP as V2SubscriptionChangePlanParams, bQ as V2SubscriptionChargeParams, bR as V2SubscriptionChargeResult, bN as V2SubscriptionPauseParams, bJ as V2Webhook, bK as V2WebhookCreateParams, bI as V2WebhookEventType, bL as V2WebhookUpdateParams, cr as WebhooksV2Client, az as createPerspectApiV2Client } from '../index-hSqTwbPy.js';

package/dist/v2/index.js

@@ -62,10 +62,20 @@ var HttpClient = class {
   defaultHeaders;
   timeout;
   retries;
+  debug;
+  /**
+   * Debug-only logger. Off by default so request URLs, params, headers, and
+   * response bodies (emails, profiles, orders, Stripe identifiers) never
+   * leak into host logs. Opt in explicitly via `config.debug`.
+   */
+  dbg(...args) {
+    if (this.debug) console["log"](...args);
+  }
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.timeout = config.timeout || 3e4;
     this.retries = config.retries || 3;
+    this.debug = config.debug ?? false;
     this.defaultHeaders = {
       "Content-Type": "application/json",
       "User-Agent": "perspectapi-ts-sdk/1.0.0",
@@ -110,15 +120,15 @@ var HttpClient = class {
   async request(endpoint, options = {}) {
     const url = this.buildUrl(endpoint, options.params);
     const requestOptions = this.buildRequestOptions(options);
-    console.log(`[HTTP Client] ====== Request Details ======`);
-    console.log(`[HTTP Client] Method: ${options.method || "GET"}`);
-    console.log(`[HTTP Client] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client] Full URL: ${url}`);
+    this.dbg(`[HTTP Client] ====== Request Details ======`);
+    this.dbg(`[HTTP Client] Method: ${options.method || "GET"}`);
+    this.dbg(`[HTTP Client] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client] Full URL: ${url}`);
     if (options.params) {
-      console.log(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
+      this.dbg(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
       if (options.params.slug_prefix) {
-        console.log(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
+        this.dbg(`[HTTP Client] \u26A0\uFE0F slug_prefix detected: "${options.params.slug_prefix}"`);
       }
     }
     const safeHeaders = { ...requestOptions.headers };
@@ -128,7 +138,7 @@ var HttpClient = class {
     if (safeHeaders["X-API-Key"]) {
       safeHeaders["X-API-Key"] = "[REDACTED]";
     }
-    console.log(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
+    this.dbg(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
     let lastError;
     for (let attempt = 0; attempt <= this.retries; attempt++) {
       try {
@@ -182,25 +192,25 @@ var HttpClient = class {
    */
   buildUrl(endpoint, params) {
     const url = `${this.baseUrl}${endpoint.startsWith("/") ? "" : "/"}${endpoint}`;
-    console.log(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
+    this.dbg(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
     if (!params || Object.keys(params).length === 0) {
-      console.log(`[HTTP Client - URL Builder] No params, returning: ${url}`);
+      this.dbg(`[HTTP Client - URL Builder] No params, returning: ${url}`);
       return url;
     }
-    console.log(`[HTTP Client - URL Builder] Processing params:`, params);
+    this.dbg(`[HTTP Client - URL Builder] Processing params:`, params);
     const searchParams = new URLSearchParams();
     Object.entries(params).forEach(([key, value]) => {
       if (value !== void 0 && value !== null) {
-        console.log(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
+        this.dbg(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
         searchParams.append(key, String(value));
       } else {
-        console.log(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
+        this.dbg(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
       }
     });
     const finalUrl = `${url}?${searchParams.toString()}`;
-    console.log(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
     return finalUrl;
   }
   /**
@@ -249,42 +259,42 @@ var HttpClient = class {
   async handleResponse(response) {
     const contentType = response.headers.get("content-type");
     const isJson = contentType?.includes("application/json");
-    console.log(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
-    console.log(`[HTTP Client - Response] Content-Type: ${contentType}`);
+    this.dbg(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
+    this.dbg(`[HTTP Client - Response] Content-Type: ${contentType}`);
     let data;
     try {
       data = isJson ? await response.json() : await response.text();
     } catch (error) {
-      console.error(`[HTTP Client - Response] Failed to parse response:`, error);
+      this.dbg(`[HTTP Client - Response] Failed to parse response:`, error);
       data = null;
     }
     const dataStr = JSON.stringify(data);
     if (dataStr && dataStr.length > 1e3) {
-      console.log(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
+      this.dbg(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1e3) + "...");
     } else {
-      console.log(`[HTTP Client - Response] Data:`, data);
+      this.dbg(`[HTTP Client - Response] Data:`, data);
     }
     if (!response.ok) {
-      console.error(`[HTTP Client - Response] Error response received`);
+      this.dbg(`[HTTP Client - Response] Error response received`);
       const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data
       });
-      console.error(`[HTTP Client - Response] Throwing error:`, error);
+      this.dbg(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
     if (isJson && typeof data === "object") {
       if ("data" in data || "message" in data || "error" in data) {
         const apiResponse = data;
-        console.log(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
+        this.dbg(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : "N/A"}`);
         return apiResponse;
       }
-      console.log(`[HTTP Client - Response] Wrapping response in data property`);
+      this.dbg(`[HTTP Client - Response] Wrapping response in data property`);
       return { data, success: true };
     }
-    console.log(`[HTTP Client - Response] Returning text response`);
+    this.dbg(`[HTTP Client - Response] Returning text response`);
     return { data, success: true };
   }
   /**
@@ -977,6 +987,12 @@ var OrdersV2Client = class extends BaseV2Client {
    *
    * Set `notify_customer: true` when moving the order into a terminal
    * fulfillment state to send the customer fulfillment email.
+   *
+   * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+   * `notify_customer: true`, `cancellation_reason` is **required**: the API
+   * responds `400` if it is missing or blank, and the order is not mutated.
+   * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+   * — pass them explicitly if you need them.
    */
   async updateFulfillment(siteName, id, data) {
     const result = await this.patchOne(
@@ -992,6 +1008,9 @@ var OrdersV2Client = class extends BaseV2Client {
   /**
    * Send the customer fulfillment template for an external delivery/packing
    * record without mutating a checkout session.
+   *
+   * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+   * is **required**: the API responds `400` if it is missing or blank.
    */
   async sendFulfillmentNotification(siteName, data) {
     return this.post(

package/dist/v2/index.mjs

@@ -18,7 +18,7 @@ import {
   SubscriptionsV2Client,
   WebhooksV2Client,
   createPerspectApiV2Client
-} from "../chunk-OG4UB2MD.mjs";
+} from "../chunk-TFN5IR35.mjs";
 export {
   ApiKeysV2Client,
   BaseV2Client,

package/package.json

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

package/src/client/site-users-client.ts

@@ -518,9 +518,21 @@ export class SiteUsersClient extends BaseClient {
     data: {
       fulfillment_status: string;
       tracking_number?: string;
+      /** Internal operator notes. Never shown to the customer. */
       notes?: string;
       fulfillment_details_text?: string;
       fulfillment_details_html?: string;
+      /**
+       * Customer-visible cancellation reason. Required when
+       * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer`
+       * is `true` — the request is rejected with `400` if missing or blank.
+       * Not derived from `notes` or `fulfillment_details_*`.
+       */
+      cancellation_reason?: string;
+      /** Customer-visible cancellation detail (plain text). Only used if provided. */
+      cancellation_details_text?: string;
+      /** Customer-visible cancellation detail (HTML). Only used if provided. */
+      cancellation_details_html?: string;
       notify_customer?: boolean;
     }
   ): Promise<ApiResponse<{ success: boolean }>> {

package/src/types/index.ts

@@ -1192,6 +1192,11 @@ export interface PerspectApiConfig {
   retries?: number;
   headers?: Record<string, string>;
   cache?: CacheConfig;
+  /**
+   * Opt-in verbose HTTP logging (URLs, params, headers, response bodies).
+   * Off by default so PII never leaks into host logs.
+   */
+  debug?: boolean;
 }
 
 // HTTP Methods

package/src/utils/http-client.ts

@@ -16,11 +16,22 @@ export class HttpClient {
   private defaultHeaders: Record<string, string>;
   private timeout: number;
   private retries: number;
+  private debug: boolean;
+
+  /**
+   * Debug-only logger. Off by default so request URLs, params, headers, and
+   * response bodies (emails, profiles, orders, Stripe identifiers) never
+   * leak into host logs. Opt in explicitly via `config.debug`.
+   */
+  private dbg(...args: unknown[]): void {
+    if (this.debug) console["log"](...args);
+  }
 
   constructor(config: PerspectApiConfig) {
     this.baseUrl = config.baseUrl.replace(/\/$/, ''); // Remove trailing slash
     this.timeout = config.timeout || 30000;
     this.retries = config.retries || 3;
+    this.debug = config.debug ?? false;
     
     this.defaultHeaders = {
       'Content-Type': 'application/json',
@@ -78,18 +89,18 @@ export class HttpClient {
     const requestOptions = this.buildRequestOptions(options);
 
     // Enhanced logging for debugging
-    console.log(`[HTTP Client] ====== Request Details ======`);
-    console.log(`[HTTP Client] Method: ${options.method || 'GET'}`);
-    console.log(`[HTTP Client] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client] Full URL: ${url}`);
+    this.dbg(`[HTTP Client] ====== Request Details ======`);
+    this.dbg(`[HTTP Client] Method: ${options.method || 'GET'}`);
+    this.dbg(`[HTTP Client] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client] Full URL: ${url}`);
     
     if (options.params) {
-      console.log(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
+      this.dbg(`[HTTP Client] Query params:`, JSON.stringify(options.params, null, 2));
       
       // Specifically log slug_prefix if present
       if (options.params.slug_prefix) {
-        console.log(`[HTTP Client] ⚠️ slug_prefix detected: "${options.params.slug_prefix}"`);
+        this.dbg(`[HTTP Client] ⚠️ slug_prefix detected: "${options.params.slug_prefix}"`);
       }
     }
     
@@ -101,7 +112,7 @@ export class HttpClient {
     if (safeHeaders['X-API-Key']) {
       safeHeaders['X-API-Key'] = '[REDACTED]';
     }
-    console.log(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
+    this.dbg(`[HTTP Client] Headers:`, JSON.stringify(safeHeaders, null, 2));
 
     let lastError: Error;
     
@@ -172,29 +183,29 @@ export class HttpClient {
   private buildUrl(endpoint: string, params?: Record<string, any>): string {
     const url = `${this.baseUrl}${endpoint.startsWith('/') ? '' : '/'}${endpoint}`;
     
-    console.log(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
-    console.log(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
-    console.log(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
+    this.dbg(`[HTTP Client - URL Builder] Base URL: ${this.baseUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Endpoint: ${endpoint}`);
+    this.dbg(`[HTTP Client - URL Builder] Combined URL (before params): ${url}`);
     
     if (!params || Object.keys(params).length === 0) {
-      console.log(`[HTTP Client - URL Builder] No params, returning: ${url}`);
+      this.dbg(`[HTTP Client - URL Builder] No params, returning: ${url}`);
       return url;
     }
 
-    console.log(`[HTTP Client - URL Builder] Processing params:`, params);
+    this.dbg(`[HTTP Client - URL Builder] Processing params:`, params);
     
     const searchParams = new URLSearchParams();
     Object.entries(params).forEach(([key, value]) => {
       if (value !== undefined && value !== null) {
-        console.log(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
+        this.dbg(`[HTTP Client - URL Builder] Adding param: ${key}=${value}`);
         searchParams.append(key, String(value));
       } else {
-        console.log(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
+        this.dbg(`[HTTP Client - URL Builder] Skipping null/undefined param: ${key}`);
       }
     });
 
     const finalUrl = `${url}?${searchParams.toString()}`;
-    console.log(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
+    this.dbg(`[HTTP Client - URL Builder] Final URL: ${finalUrl}`);
     
     return finalUrl;
   }
@@ -254,34 +265,34 @@ export class HttpClient {
     const contentType = response.headers.get('content-type');
     const isJson = contentType?.includes('application/json');
 
-    console.log(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
-    console.log(`[HTTP Client - Response] Content-Type: ${contentType}`);
+    this.dbg(`[HTTP Client - Response] Status: ${response.status} ${response.statusText}`);
+    this.dbg(`[HTTP Client - Response] Content-Type: ${contentType}`);
 
     let data: any;
     try {
       data = isJson ? await response.json() : await response.text();
     } catch (error) {
-      console.error(`[HTTP Client - Response] Failed to parse response:`, error);
+      this.dbg(`[HTTP Client - Response] Failed to parse response:`, error);
       data = null;
     }
 
     // Log response data (truncate if too large)
     const dataStr = JSON.stringify(data);
     if (dataStr && dataStr.length > 1000) {
-      console.log(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1000) + '...');
+      this.dbg(`[HTTP Client - Response] Data (truncated):`, dataStr.substring(0, 1000) + '...');
     } else {
-      console.log(`[HTTP Client - Response] Data:`, data);
+      this.dbg(`[HTTP Client - Response] Data:`, data);
     }
 
     if (!response.ok) {
-      console.error(`[HTTP Client - Response] Error response received`);
+      this.dbg(`[HTTP Client - Response] Error response received`);
       const error = new PerspectApiError({
         message: data?.error || data?.message || `HTTP ${response.status}: ${response.statusText}`,
         status: response.status,
         code: data?.code,
         details: data,
       });
-      console.error(`[HTTP Client - Response] Throwing error:`, error);
+      this.dbg(`[HTTP Client - Response] Throwing error:`, error);
       throw error;
     }
 
@@ -290,15 +301,15 @@ export class HttpClient {
       // If response has data property, return as-is
       if ('data' in data || 'message' in data || 'error' in data) {
         const apiResponse = data as ApiResponse<T>;
-        console.log(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : 'N/A'}`);
+        this.dbg(`[HTTP Client - Response] Returning API response with success=${apiResponse.success}, data length=${Array.isArray(apiResponse.data) ? apiResponse.data.length : 'N/A'}`);
         return apiResponse;
       }
       // Otherwise wrap in data property
-      console.log(`[HTTP Client - Response] Wrapping response in data property`);
+      this.dbg(`[HTTP Client - Response] Wrapping response in data property`);
       return { data: data as T, success: true };
     }
 
-    console.log(`[HTTP Client - Response] Returning text response`);
+    this.dbg(`[HTTP Client - Response] Returning text response`);
     return { data: data as T, success: true };
   }
 

package/src/v2/client/orders-client.ts

@@ -88,6 +88,12 @@ export class OrdersV2Client extends BaseV2Client {
    *
    * Set `notify_customer: true` when moving the order into a terminal
    * fulfillment state to send the customer fulfillment email.
+   *
+   * When cancelling (`fulfillment_status: 'cancelled'`/`'canceled'`) with
+   * `notify_customer: true`, `cancellation_reason` is **required**: the API
+   * responds `400` if it is missing or blank, and the order is not mutated.
+   * `cancellation_details_*` are no longer derived from `fulfillment_details_*`
+   * — pass them explicitly if you need them.
    */
   async updateFulfillment(
     siteName: string,
@@ -108,6 +114,9 @@ export class OrdersV2Client extends BaseV2Client {
   /**
    * Send the customer fulfillment template for an external delivery/packing
    * record without mutating a checkout session.
+   *
+   * When `fulfillment_status` is `cancelled`/`canceled`, `cancellation_reason`
+   * is **required**: the API responds `400` if it is missing or blank.
    */
   async sendFulfillmentNotification(
     siteName: string,

package/src/v2/types.ts

@@ -322,14 +322,33 @@ export interface V2OrderCreateParams {
   currency?: string;
   referral_code?: string;
   referrer_site_user_id?: string;
+  /**
+   * Subscription billing-cycle anchor as a Unix timestamp (seconds). When set
+   * on a `subscription` checkout, no charge is taken at checkout; the first
+   * invoice and the recurring cycle are aligned to this instant via Stripe
+   * `subscription_data.billing_cycle_anchor` with `proration_behavior: none`.
+   */
+  billing_cycle_anchor?: number;
 }
 
 export interface V2OrderFulfillmentUpdate {
   fulfillment_status: string;
   tracking_number?: string;
+  /** Internal operator notes. Never shown to the customer. */
   notes?: string;
   fulfillment_details_text?: string;
   fulfillment_details_html?: string;
+  /**
+   * Customer-visible cancellation reason. **Required** when
+   * `fulfillment_status` is `cancelled`/`canceled` and `notify_customer` is
+   * `true` — the request is rejected with `400` if it is missing or blank.
+   * Not derived from `notes` or `fulfillment_details_*`.
+   */
+  cancellation_reason?: string;
+  /** Customer-visible cancellation detail (plain text). Only used if provided. */
+  cancellation_details_text?: string;
+  /** Customer-visible cancellation detail (HTML). Only used if provided. */
+  cancellation_details_html?: string;
   /** When true, a terminal fulfillment status triggers a customer email. */
   notify_customer?: boolean;
 }
@@ -349,6 +368,17 @@ export interface V2OrderFulfillmentNotificationParams {
   fulfillment_status?: string;
   fulfillment_details_text?: string;
   fulfillment_details_html?: string;
+  /**
+   * Customer-visible cancellation reason. **Required** when
+   * `fulfillment_status` is `cancelled`/`canceled` — the request is rejected
+   * with `400` if it is missing or blank. Not derived from
+   * `fulfillment_details_*`.
+   */
+  cancellation_reason?: string;
+  /** Customer-visible cancellation detail (plain text). Only used if provided. */
+  cancellation_details_text?: string;
+  /** Customer-visible cancellation detail (HTML). Only used if provided. */
+  cancellation_details_html?: string;
   line_items?: V2OrderFulfillmentNotificationLineItem[];
   amount_total?: number;
   currency?: string;