@putiikkipalvelu/storefront-sdk 0.3.0 → 0.4.1

package/dist/index.d.cts

@@ -419,6 +419,10 @@ interface CartResponse {
     /** Cart ID for guest users (undefined for logged-in users) */
     cartId?: string;
 }
+/**
+ * Reason why a discount code was removed during validation
+ */
+type DiscountRemovalReason = "CAMPAIGN_ACTIVE" | "MIN_ORDER_NOT_MET" | "CODE_INVALID";
 /**
  * Changes detected during cart validation
  */
@@ -429,9 +433,16 @@ interface CartValidationChanges {
     quantityAdjusted: number;
     /** Number of items with changed price */
     priceChanged: number;
+    /** Whether discount code was removed */
+    discountCouponRemoved: boolean;
+    /** Reason why discount was removed (only present if discountCouponRemoved is true) */
+    discountRemovalReason?: DiscountRemovalReason;
 }
 /**
  * Response from GET /cart/validate
+ *
+ * Returns validated cart items and change metadata.
+ * No totals or discount data - those are calculated client-side or fetched separately.
  */
 interface CartValidationResponse {
     /** Validated cart items (with auto-fixed quantities/prices) */
@@ -724,7 +735,7 @@ interface Order {
     storeId: string;
     /** Order creation timestamp */
     createdAt: string;
-    /** Total order amount in cents */
+    /** Total order amount in cents (subtotal before discount) */
     totalAmount: number;
     /** Current order status */
     status: OrderStatus;
@@ -736,6 +747,12 @@ interface Order {
     orderCustomerData: ConfirmationOrderCustomerData | null;
     /** Shipment method with tracking info */
     orderShipmentMethod: ConfirmationOrderShipmentMethod | null;
+    /** Discount code string (e.g., "SUMMER20") - null if no discount applied */
+    discountCodeValue: string | null;
+    /** Discount amount in cents - null if no discount applied */
+    discountAmount: number | null;
+    /** VAT rate used for the discount calculation */
+    discountVatRate: number | null;
 }
 
 /**
@@ -1232,6 +1249,104 @@ interface CheckoutErrorDetails {
     [key: string]: unknown;
 }
 
+/**
+ * Discount Code Types
+ *
+ * Types for discount code API endpoints.
+ */
+/**
+ * Type of discount
+ */
+type DiscountType = "PERCENTAGE" | "FIXED_AMOUNT";
+/**
+ * Applied discount code information (stored in cart)
+ */
+interface AppliedDiscount {
+    /** The discount code string */
+    code: string;
+    /** Type of discount */
+    discountType: DiscountType;
+    /** Discount value (percentage 1-100 or cents for fixed amount) */
+    discountValue: number;
+}
+/**
+ * Parameters for applying a discount code
+ */
+interface ApplyDiscountParams {
+    /** The discount code to apply */
+    code: string;
+    /** Cart ID for guest users */
+    cartId?: string;
+    /** Session ID for logged-in users */
+    sessionId?: string;
+    /** Cart items for campaign conflict check (SDK uses this for instant validation) */
+    cartItems?: CartItem[];
+    /** Active campaigns for campaign conflict check (SDK uses this for instant validation) */
+    campaigns?: Campaign[];
+}
+/**
+ * Parameters for removing a discount code
+ */
+interface RemoveDiscountParams {
+    /** Cart ID for guest users */
+    cartId?: string;
+    /** Session ID for logged-in users */
+    sessionId?: string;
+}
+/**
+ * Parameters for getting current discount
+ */
+interface GetDiscountParams {
+    /** Cart ID for guest users */
+    cartId?: string;
+    /** Session ID for logged-in users */
+    sessionId?: string;
+}
+/**
+ * Response from POST /discount-code/apply
+ *
+ * Note: No discountAmount returned - cart can change before checkout.
+ * Calculate locally or get from cart validate if needed.
+ */
+interface ApplyDiscountResponse {
+    /** Whether the discount was applied successfully */
+    success: boolean;
+    /** Applied discount details */
+    discount: {
+        code: string;
+        discountType: DiscountType;
+        discountValue: number;
+        /** Minimum order amount for this code (in cents) - for UI display */
+        minOrderAmount: number | null;
+    };
+}
+/**
+ * Response from GET /discount-code/apply (get current discount)
+ *
+ * Returns stored discount data without re-validation.
+ * Use /cart/validate for full validation.
+ */
+interface GetDiscountResponse {
+    /** Current discount (null if none applied) */
+    discount: AppliedDiscount | null;
+}
+/**
+ * Response from DELETE /discount-code/apply
+ */
+interface RemoveDiscountResponse {
+    /** Whether the discount was removed successfully */
+    success: boolean;
+}
+/**
+ * Error response from discount code endpoints
+ */
+interface DiscountCodeError {
+    /** Error message (Finnish, user-friendly) */
+    error: string;
+    /** Error code for programmatic use */
+    code: "MISSING_CODE" | "MISSING_CART_TOTAL" | "CART_MISSING" | "NOT_FOUND" | "INACTIVE" | "NOT_STARTED" | "EXPIRED" | "MAX_USES_REACHED" | "MIN_ORDER_NOT_MET" | "CAMPAIGN_ACTIVE" | "INTERNAL_ERROR";
+}
+
 /**
  * Putiikkipalvelu Storefront SDK Types
  *
@@ -1658,28 +1773,35 @@ declare function createCartResource(fetcher: Fetcher): {
      * Checks product availability, stock levels, and prices.
      * Auto-fixes issues (removes unavailable items, adjusts quantities).
      *
+     * Campaign conflict detection:
+     * - SDK calculates if BuyXPayY campaigns apply using calculateCartWithCampaigns()
+     * - Sends x-campaigns-apply header to backend
+     * - If campaigns apply AND discount code exists, backend removes it
+     * - Returns changes.discountCouponRemoved = true
+     *
      * @param options - Cart session options
+     * @param cartItems - Current cart items for campaign calculation
+     * @param campaigns - Active campaigns for conflict check
      * @param fetchOptions - Fetch options
      * @returns Validated cart with change metadata
      *
      * @example Validate before checkout
      * ```typescript
-     * const { items, hasChanges, changes } = await client.cart.validate({ cartId });
+     * const result = await client.cart.validate(
+     *   { cartId },
+     *   cartItems,
+     *   storeConfig.campaigns
+     * );
      *
-     * if (hasChanges) {
-     *   if (changes.removedItems > 0) {
-     *     notify('Some items were removed (out of stock)');
-     *   }
-     *   if (changes.quantityAdjusted > 0) {
-     *     notify('Some quantities were adjusted');
-     *   }
-     *   if (changes.priceChanged > 0) {
-     *     notify('Some prices have changed');
+     * if (result.hasChanges) {
+     *   if (result.changes.discountCouponRemoved) {
+     *     notify("Alennuskoodi poistettu - kampanja-alennus aktivoitui");
      *   }
+     *   // Handle other changes...
      * }
      * ```
      */
-    validate(options?: CartSessionOptions, fetchOptions?: FetchOptions): Promise<CartValidationResponse>;
+    validate(options?: CartSessionOptions, cartItems?: CartItem[], campaigns?: Campaign[], fetchOptions?: FetchOptions): Promise<CartValidationResponse>;
 };
 /**
  * Type for the cart resource
@@ -1700,6 +1822,8 @@ interface GetShippingOptionsParams extends FetchOptions {
     cartItems?: CartItem[];
     /** Active campaigns - used to calculate cart total with discounts for free shipping */
     campaigns?: Campaign[];
+    /** Discount amount in cents (from discount code) - subtracted from cart total for free shipping threshold */
+    discountAmount?: number;
     /** Country code (default: "FI") */
     country?: string;
 }
@@ -2303,6 +2427,70 @@ declare function createCheckoutResource(fetcher: Fetcher): {
  */
 type CheckoutResource = ReturnType<typeof createCheckoutResource>;
 
+/**
+ * Discount Code Resource
+ *
+ * Provides methods for managing discount codes in the cart.
+ */
+
+/**
+ * Creates the discount code resource with methods for managing discount codes.
+ */
+declare function createDiscountCodeResource(fetcher: Fetcher): {
+    /**
+     * Apply a discount code to the cart
+     *
+     * Checks for BuyXPayY campaign conflict before calling API.
+     * Discount codes cannot be used when a campaign discount is active.
+     *
+     * @param params - Parameters including code, session info, and cart/campaign data for conflict check
+     * @returns Applied discount details
+     * @throws {StorefrontError} With code "CAMPAIGN_ACTIVE" if a BuyXPayY campaign is active
+     *
+     * @example
+     * ```typescript
+     * const result = await client.discountCode.apply({
+     *   code: "SUMMER20",
+     *   cartId: cartId,
+     *   cartItems: cart.items,
+     *   campaigns: storeConfig.campaigns,
+     * });
+     * ```
+     */
+    apply(params: ApplyDiscountParams): Promise<ApplyDiscountResponse>;
+    /**
+     * Get the currently applied discount code
+     *
+     * @param params - Session info (cartId or sessionId)
+     * @returns Current discount or null if none applied
+     *
+     * @example
+     * ```typescript
+     * const { discount } = await client.discountCode.get({ cartId });
+     * if (discount) {
+     *   console.log(`Code ${discount.code}: ${discount.discountValue}${discount.discountType === 'PERCENTAGE' ? '%' : '¢'} off`);
+     * }
+     * ```
+     */
+    get(params?: GetDiscountParams): Promise<GetDiscountResponse>;
+    /**
+     * Remove the currently applied discount code
+     *
+     * @param params - Session info (cartId or sessionId)
+     * @returns Success status
+     *
+     * @example
+     * ```typescript
+     * await client.discountCode.remove({ cartId });
+     * ```
+     */
+    remove(params?: RemoveDiscountParams): Promise<RemoveDiscountResponse>;
+};
+/**
+ * Type for the discount code resource
+ */
+type DiscountCodeResource = ReturnType<typeof createDiscountCodeResource>;
+
 /**
  * The Storefront API client
  */
@@ -2343,6 +2531,10 @@ interface StorefrontClient {
      * Checkout resource for payment processing
      */
     readonly checkout: CheckoutResource;
+    /**
+     * Discount code resource for applying/removing discount codes
+     */
+    readonly discountCode: DiscountCodeResource;
 }
 /**
  * Create a new Storefront API client
@@ -2427,6 +2619,126 @@ declare function getPriceInfo(product: ProductDetail, variation?: ProductVariati
  */
 declare function calculateCartWithCampaigns(items: CartItem[], campaigns: Campaign[]): CartCalculationResult;
 
+/**
+ * Discount Code Utilities
+ *
+ * Helper functions for working with discount codes.
+ */
+
+/**
+ * Options for formatting discount values
+ */
+interface FormatDiscountOptions {
+    /**
+     * Currency symbol to use for fixed amount discounts
+     * @default "€"
+     */
+    currencySymbol?: string;
+    /**
+     * Whether to show the currency symbol before or after the value
+     * @default "after"
+     */
+    currencyPosition?: "before" | "after";
+    /**
+     * Number of decimal places for fixed amount
+     * @default 2
+     */
+    decimals?: number;
+    /**
+     * Whether to include the minus sign prefix
+     * @default true
+     */
+    showMinus?: boolean;
+}
+/**
+ * Format a discount value for display.
+ *
+ * @param discount - The applied discount (or just type and value)
+ * @param options - Formatting options
+ * @returns Formatted discount string (e.g., "-20%" or "-5,00 €")
+ *
+ * @example
+ * ```typescript
+ * // Percentage discount
+ * formatDiscountValue({ discountType: "PERCENTAGE", discountValue: 20 });
+ * // Returns: "-20%"
+ *
+ * // Fixed amount discount (value in cents)
+ * formatDiscountValue({ discountType: "FIXED_AMOUNT", discountValue: 500 });
+ * // Returns: "-5,00 €"
+ *
+ * // Custom currency
+ * formatDiscountValue(
+ *   { discountType: "FIXED_AMOUNT", discountValue: 1000 },
+ *   { currencySymbol: "$", currencyPosition: "before" }
+ * );
+ * // Returns: "-$10.00"
+ * ```
+ */
+declare function formatDiscountValue(discount: Pick<AppliedDiscount, "discountType" | "discountValue">, options?: FormatDiscountOptions): string;
+/**
+ * Calculate the discount amount in cents.
+ *
+ * @param subtotal - Cart subtotal in cents (before discount)
+ * @param discount - The applied discount
+ * @returns Discount amount in cents (always positive)
+ *
+ * @example
+ * ```typescript
+ * // 20% off 100€ subtotal
+ * calculateDiscountAmount(10000, { discountType: "PERCENTAGE", discountValue: 20 });
+ * // Returns: 2000 (20€ in cents)
+ *
+ * // Fixed 5€ discount
+ * calculateDiscountAmount(10000, { discountType: "FIXED_AMOUNT", discountValue: 500 });
+ * // Returns: 500 (5€ in cents)
+ *
+ * // Fixed discount larger than subtotal (capped)
+ * calculateDiscountAmount(300, { discountType: "FIXED_AMOUNT", discountValue: 500 });
+ * // Returns: 300 (capped to subtotal)
+ * ```
+ */
+declare function calculateDiscountAmount(subtotal: number, discount: Pick<AppliedDiscount, "discountType" | "discountValue">): number;
+/**
+ * Supported locales for error messages
+ */
+type DiscountMessageLocale = "fi" | "en";
+/**
+ * Get a user-friendly message for discount removal reason.
+ *
+ * @param reason - The removal reason from cart validation
+ * @param locale - Locale for the message (fi or en)
+ * @returns Localized user-friendly message
+ *
+ * @example
+ * ```typescript
+ * getDiscountRemovalMessage("CAMPAIGN_ACTIVE", "fi");
+ * // Returns: "Alennuskoodi poistettu - kampanja-alennus aktivoitui"
+ *
+ * getDiscountRemovalMessage("MIN_ORDER_NOT_MET", "en");
+ * // Returns: "Discount code removed - cart total below minimum order"
+ * ```
+ */
+declare function getDiscountRemovalMessage(reason: DiscountRemovalReason | undefined, locale?: DiscountMessageLocale): string;
+/**
+ * Error codes from discount code apply endpoint
+ */
+type DiscountApplyErrorCode = "NOT_FOUND" | "INACTIVE" | "NOT_STARTED" | "EXPIRED" | "MAX_USES_REACHED" | "MIN_ORDER_NOT_MET" | "CAMPAIGN_ACTIVE";
+/**
+ * Get a user-friendly message for discount apply error.
+ *
+ * @param errorCode - The error code from apply endpoint
+ * @param locale - Locale for the message (fi or en)
+ * @returns Localized user-friendly message
+ *
+ * @example
+ * ```typescript
+ * getDiscountApplyErrorMessage("EXPIRED", "fi");
+ * // Returns: "Alennuskoodi on vanhentunut"
+ * ```
+ */
+declare function getDiscountApplyErrorMessage(errorCode: DiscountApplyErrorCode | string | undefined, locale?: DiscountMessageLocale): string;
+
 /**
  * Base error class for all Storefront API errors
  */
@@ -2470,4 +2782,4 @@ declare class VerificationRequiredError extends StorefrontError {
     constructor(message: string, customerId: string);
 }
 
-export { type AddToCartParams, type AddToWishlistResponse, AuthError, type BuyXPayYCampaign, type CalculatedCartItem, type Campaign, type CampaignType, type CartCalculationResult, type CartItem, type CartResponse, type CartSessionOptions, type CartValidationChanges, type CartValidationResponse, type Category, type CategoryReference, type CategoryResponse, type CheckoutCustomerData, type CheckoutErrorCode, type CheckoutErrorDetails, type CheckoutOptions, type CheckoutParams, type CheckoutShipmentMethod, type ConfirmationItemType, type ConfirmationOrderCustomerData, type ConfirmationOrderLineItem, type ConfirmationOrderShipmentMethod, type Customer, type CustomerOrder, type DeleteAccountResponse, type FeatureFlags, type FetchOptions, type ForgotPasswordResponse, type GetOrdersResponse, type GetUserResponse, type HomeDeliveryOption, type LoginOptions, type LoginResponse, type LoginVerificationRequiredResponse, type LogoutResponse, NotFoundError, type OpeningHours, type Order, type OrderLineItem, type OrderProductInfo, type OrderShipmentMethod, type OrderStatus, type PaymentConfig, type PaytrailCheckoutResponse, type PaytrailGroup, type PaytrailProvider, type PickupPointOption, type PriceInfo, type Product, type ProductCountResponse, type ProductDetail, type ProductListParams, type ProductListResponse, type ProductSortOption, type ProductVariation, type ProductVariationListing, RateLimitError, type RegisterData, type RegisterResponse, type RemoveFromCartParams, type RemoveFromWishlistResponse, type ResendVerificationResponse, type ResetPasswordResponse, type ShipitShippingMethod, type ShipmentMethod, type ShipmentMethodsResponse, type StoreConfig, type StoreInfo, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, type StripeCheckoutResponse, type UpdateCartQuantityParams, type UpdateProfileData, type UpdateProfileResponse, ValidationError, type VariationOption, VerificationRequiredError, type VerifyEmailResponse, type WishlistItem, type WishlistProduct, type WishlistResponse, type WishlistVariation, type WishlistVariationOption, calculateCartWithCampaigns, createStorefrontClient, getPriceInfo, isSaleActive };
+export { type AddToCartParams, type AddToWishlistResponse, type AppliedDiscount, type ApplyDiscountParams, type ApplyDiscountResponse, AuthError, type BuyXPayYCampaign, type CalculatedCartItem, type Campaign, type CampaignType, type CartCalculationResult, type CartItem, type CartResponse, type CartSessionOptions, type CartValidationChanges, type CartValidationResponse, type Category, type CategoryReference, type CategoryResponse, type CheckoutCustomerData, type CheckoutErrorCode, type CheckoutErrorDetails, type CheckoutOptions, type CheckoutParams, type CheckoutShipmentMethod, type ConfirmationItemType, type ConfirmationOrderCustomerData, type ConfirmationOrderLineItem, type ConfirmationOrderShipmentMethod, type Customer, type CustomerOrder, type DeleteAccountResponse, type DiscountApplyErrorCode, type DiscountCodeError, type DiscountMessageLocale, type DiscountRemovalReason, type DiscountType, type FeatureFlags, type FetchOptions, type ForgotPasswordResponse, type FormatDiscountOptions, type GetDiscountParams, type GetDiscountResponse, type GetOrdersResponse, type GetUserResponse, type HomeDeliveryOption, type LoginOptions, type LoginResponse, type LoginVerificationRequiredResponse, type LogoutResponse, NotFoundError, type OpeningHours, type Order, type OrderLineItem, type OrderProductInfo, type OrderShipmentMethod, type OrderStatus, type PaymentConfig, type PaytrailCheckoutResponse, type PaytrailGroup, type PaytrailProvider, type PickupPointOption, type PriceInfo, type Product, type ProductCountResponse, type ProductDetail, type ProductListParams, type ProductListResponse, type ProductSortOption, type ProductVariation, type ProductVariationListing, RateLimitError, type RegisterData, type RegisterResponse, type RemoveDiscountParams, type RemoveDiscountResponse, type RemoveFromCartParams, type RemoveFromWishlistResponse, type ResendVerificationResponse, type ResetPasswordResponse, type ShipitShippingMethod, type ShipmentMethod, type ShipmentMethodsResponse, type StoreConfig, type StoreInfo, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, type StripeCheckoutResponse, type UpdateCartQuantityParams, type UpdateProfileData, type UpdateProfileResponse, ValidationError, type VariationOption, VerificationRequiredError, type VerifyEmailResponse, type WishlistItem, type WishlistProduct, type WishlistResponse, type WishlistVariation, type WishlistVariationOption, calculateCartWithCampaigns, calculateDiscountAmount, createStorefrontClient, formatDiscountValue, getDiscountApplyErrorMessage, getDiscountRemovalMessage, getPriceInfo, isSaleActive };