@putiikkipalvelu/storefront-sdk 0.11.2 → 0.14.0

package/dist/index.d.cts

@@ -1,8 +1,180 @@
+/**
+ * Product Types
+ *
+ * Types for product-related API endpoints.
+ */
+
+/**
+ * Product variation option (e.g., Size: Large)
+ */
+interface VariationOption {
+    /** Option value (e.g., "Large", "Red") */
+    value: string;
+    /** Option type information */
+    optionType: {
+        /** Option type name (e.g., "Size", "Color") */
+        name: string;
+    };
+}
+/**
+ * Product variation for listings (minimal fields)
+ */
+interface ProductVariationListing {
+    /** Unique variation identifier */
+    id: string;
+    /** Variation price in cents */
+    price: number;
+    /** Sale price in cents (null if not on sale) */
+    salePrice: number | null;
+    /** Sale discount percentage as string (null if not on sale) */
+    salePercent: string | null;
+    /** Sale start date (ISO 8601), null = immediate */
+    saleStartDate: string | null;
+    /** Sale end date (ISO 8601), null = no end */
+    saleEndDate: string | null;
+}
+/**
+ * Full product variation (for product detail page)
+ */
+interface ProductVariation extends ProductVariationListing {
+    /** Variation weight in kg (null = use product weight) */
+    weight: number | null;
+    /** Available quantity (null = unlimited) */
+    quantity: number | null;
+    /** Stock keeping unit */
+    sku: string | null;
+    /** Variation-specific images */
+    images: string[];
+    /** Variation-specific description */
+    description: string | null;
+    /** Whether variation is visible on store */
+    showOnStore: boolean;
+    /** Variation options (size, color, etc.) */
+    options: VariationOption[];
+}
+/**
+ * Product for listing (cards, grids)
+ * Used by: /latest-products, /sorted-products
+ */
+interface Product {
+    /** Unique product identifier */
+    id: string;
+    /** Product display name */
+    name: string;
+    /** URL-friendly slug */
+    slug: string;
+    /** Product description */
+    description: string;
+    /** Base price in cents */
+    price: number;
+    /** Product images (URLs) */
+    images: string[];
+    /** Available quantity (null = unlimited) */
+    quantity: number | null;
+    /** Sale price in cents (null if not on sale) */
+    salePrice: number | null;
+    /** Sale discount percentage as string (null if not on sale) */
+    salePercent: string | null;
+    /** Sale start date (ISO 8601), null = immediate */
+    saleStartDate: string | null;
+    /** Sale end date (ISO 8601), null = no end */
+    saleEndDate: string | null;
+    /** True if this product is delivered as a digital download (no shipping) */
+    isDigital?: boolean;
+    /** Product variations (minimal fields for listing) */
+    variations: ProductVariationListing[];
+}
+/**
+ * Full product detail (single product page)
+ * Used by: /product/{slug}
+ */
+/**
+ * Ticket info attached to a ticket product
+ */
+interface ProductTicketInfo {
+    /** Ticket info ID */
+    id: string;
+    /** Whether holder name is required per ticket at checkout */
+    requiresHolder: boolean;
+    /** Maximum uses per ticket (0 = unlimited) */
+    maxUses: number;
+    /** Ticket sales start (ISO 8601), null = sales open immediately */
+    salesStart: string | null;
+    /** Ticket sales end (ISO 8601), null = sales never end */
+    salesEnd: string | null;
+}
+interface ProductDetail extends Omit<Product, "variations"> {
+    /** Product weight in kg (for shipping calculations) */
+    weight: number;
+    /** Stock keeping unit */
+    sku: string | null;
+    /** SEO meta title */
+    metaTitle: string | null;
+    /** SEO meta description */
+    metaDescription: string | null;
+    /** Product categories */
+    categories: CategoryReference[];
+    /** Full product variations */
+    variations: ProductVariation[];
+    /** Ticket info (present if product is a ticket, null otherwise) */
+    ticketInfo: ProductTicketInfo | null;
+    /**
+     * HTML instructions shown to the buyer after a digital purchase.
+     * Only populated when isDigital=true; null otherwise.
+     */
+    digitalContent?: string | null;
+    /** Average rating across approved reviews (null when there are none) */
+    averageRating: number | null;
+    /** Number of approved reviews */
+    reviewCount: number;
+}
+/**
+ * Response from /sorted-products
+ */
+interface ProductListResponse {
+    /** Category/collection name */
+    name: string;
+    /** Products in the list */
+    products: Product[];
+    /** Total count for pagination (only in sorted-products) */
+    totalCount?: number;
+}
+/**
+ * Response from /products-count
+ */
+interface ProductCountResponse {
+    /** Number of products */
+    count: number;
+}
+/**
+ * Sort options for product listing
+ */
+type ProductSortOption = "newest" | "price_asc" | "price_desc" | "popularity" | "relevance"
+/** The merchant's manual per-category order (set in the dashboard). Only
+ *  meaningful within a category; falls back to "newest" on all-products. */
+ | "featured";
+/**
+ * Parameters for sorted products
+ */
+interface ProductListParams {
+    /** Category slugs to filter by (omit for all products) */
+    slugs?: string[];
+    /** Page number (1-based, default: 1) */
+    page?: number;
+    /** Products per page (default: 12, max: 100) */
+    pageSize?: number;
+    /** Sort order */
+    sort?: ProductSortOption;
+    /** Full-text search query */
+    query?: string;
+}
+
 /**
  * Store Configuration Types
  *
  * Types for the store config endpoint response.
  */
+
 /**
  * Complete store configuration returned by the API.
  * Includes business info, SEO settings, payments, campaigns, and feature flags.
@@ -70,6 +242,10 @@ interface StoreInfo {
     logoUrl: string | null;
     /** Product image aspect ratio: SQUARE (1:1) or PORTRAIT (3:4) */
     imageAspectRatio: ImageAspectRatio;
+    /** Default product sort for storefront category pages before the shopper
+     *  picks a sort. "featured" = the merchant's manual per-category order.
+     *  Optional for backward compatibility with older backends. */
+    defaultProductSort?: ProductSortOption;
 }
 /**
  * Store SEO and social media configuration
@@ -276,170 +452,6 @@ interface CategoryReference {
     parentId: string | null;
 }
 
-/**
- * Product Types
- *
- * Types for product-related API endpoints.
- */
-
-/**
- * Product variation option (e.g., Size: Large)
- */
-interface VariationOption {
-    /** Option value (e.g., "Large", "Red") */
-    value: string;
-    /** Option type information */
-    optionType: {
-        /** Option type name (e.g., "Size", "Color") */
-        name: string;
-    };
-}
-/**
- * Product variation for listings (minimal fields)
- */
-interface ProductVariationListing {
-    /** Unique variation identifier */
-    id: string;
-    /** Variation price in cents */
-    price: number;
-    /** Sale price in cents (null if not on sale) */
-    salePrice: number | null;
-    /** Sale discount percentage as string (null if not on sale) */
-    salePercent: string | null;
-    /** Sale start date (ISO 8601), null = immediate */
-    saleStartDate: string | null;
-    /** Sale end date (ISO 8601), null = no end */
-    saleEndDate: string | null;
-}
-/**
- * Full product variation (for product detail page)
- */
-interface ProductVariation extends ProductVariationListing {
-    /** Variation weight in kg (null = use product weight) */
-    weight: number | null;
-    /** Available quantity (null = unlimited) */
-    quantity: number | null;
-    /** Stock keeping unit */
-    sku: string | null;
-    /** Variation-specific images */
-    images: string[];
-    /** Variation-specific description */
-    description: string | null;
-    /** Whether variation is visible on store */
-    showOnStore: boolean;
-    /** Variation options (size, color, etc.) */
-    options: VariationOption[];
-}
-/**
- * Product for listing (cards, grids)
- * Used by: /latest-products, /sorted-products
- */
-interface Product {
-    /** Unique product identifier */
-    id: string;
-    /** Product display name */
-    name: string;
-    /** URL-friendly slug */
-    slug: string;
-    /** Product description */
-    description: string;
-    /** Base price in cents */
-    price: number;
-    /** Product images (URLs) */
-    images: string[];
-    /** Available quantity (null = unlimited) */
-    quantity: number | null;
-    /** Sale price in cents (null if not on sale) */
-    salePrice: number | null;
-    /** Sale discount percentage as string (null if not on sale) */
-    salePercent: string | null;
-    /** Sale start date (ISO 8601), null = immediate */
-    saleStartDate: string | null;
-    /** Sale end date (ISO 8601), null = no end */
-    saleEndDate: string | null;
-    /** True if this product is delivered as a digital download (no shipping) */
-    isDigital?: boolean;
-    /** Product variations (minimal fields for listing) */
-    variations: ProductVariationListing[];
-}
-/**
- * Full product detail (single product page)
- * Used by: /product/{slug}
- */
-/**
- * Ticket info attached to a ticket product
- */
-interface ProductTicketInfo {
-    /** Ticket info ID */
-    id: string;
-    /** Whether holder name is required per ticket at checkout */
-    requiresHolder: boolean;
-    /** Maximum uses per ticket (0 = unlimited) */
-    maxUses: number;
-    /** Ticket sales start (ISO 8601), null = sales open immediately */
-    salesStart: string | null;
-    /** Ticket sales end (ISO 8601), null = sales never end */
-    salesEnd: string | null;
-}
-interface ProductDetail extends Omit<Product, "variations"> {
-    /** Product weight in kg (for shipping calculations) */
-    weight: number;
-    /** Stock keeping unit */
-    sku: string | null;
-    /** SEO meta title */
-    metaTitle: string | null;
-    /** SEO meta description */
-    metaDescription: string | null;
-    /** Product categories */
-    categories: CategoryReference[];
-    /** Full product variations */
-    variations: ProductVariation[];
-    /** Ticket info (present if product is a ticket, null otherwise) */
-    ticketInfo: ProductTicketInfo | null;
-    /**
-     * HTML instructions shown to the buyer after a digital purchase.
-     * Only populated when isDigital=true; null otherwise.
-     */
-    digitalContent?: string | null;
-}
-/**
- * Response from /sorted-products
- */
-interface ProductListResponse {
-    /** Category/collection name */
-    name: string;
-    /** Products in the list */
-    products: Product[];
-    /** Total count for pagination (only in sorted-products) */
-    totalCount?: number;
-}
-/**
- * Response from /products-count
- */
-interface ProductCountResponse {
-    /** Number of products */
-    count: number;
-}
-/**
- * Sort options for product listing
- */
-type ProductSortOption = "newest" | "price_asc" | "price_desc" | "popularity" | "relevance";
-/**
- * Parameters for sorted products
- */
-interface ProductListParams {
-    /** Category slugs to filter by (omit for all products) */
-    slugs?: string[];
-    /** Page number (1-based, default: 1) */
-    page?: number;
-    /** Products per page (default: 12, max: 100) */
-    pageSize?: number;
-    /** Sort order */
-    sort?: ProductSortOption;
-    /** Full-text search query */
-    query?: string;
-}
-
 /**
  * Category Types
  *
@@ -1887,6 +1899,90 @@ interface WithdrawalResolveTokenResponse {
     expiresAt: string;
 }
 
+/**
+ * Review Types
+ *
+ * Types for the product reviews & ratings endpoints.
+ */
+/** Moderation status of a review */
+type ReviewStatus = "PENDING" | "APPROVED" | "REJECTED";
+/**
+ * A single approved review as returned by the public list endpoint.
+ */
+interface Review {
+    /** Unique review identifier */
+    id: string;
+    /** Star rating 1–5 */
+    rating: number;
+    /** Optional short title (null if omitted) */
+    title: string | null;
+    /** Review body (plain text). Empty when the moderator hid the content. */
+    body: string;
+    /** True when the moderator redacted the text — show a placeholder, keep stars */
+    contentHidden: boolean;
+    /** True when tied to a verified purchase (and the store shows the badge) */
+    verifiedPurchase: boolean;
+    /** Store owner's reply (null if none) */
+    merchantReply: string | null;
+    /** Creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Display name (logged-in first name → anonymous name → fallback) */
+    reviewerName: string;
+}
+/**
+ * Response from GET /reviews/{slug} — approved reviews for a product.
+ */
+interface ReviewListResponse {
+    /** Average rating across approved reviews (null when none) */
+    averageRating: number | null;
+    /** Number of approved reviews */
+    reviewCount: number;
+    /** Count of approved reviews per star, keyed "1".."5" */
+    distribution: Record<string, number>;
+    /** Most recent approved reviews */
+    reviews: Review[];
+}
+/**
+ * Parameters for submitting a review.
+ * Pass a sessionId to {@link ReviewsResource.submit} for logged-in reviews
+ * (enables the verified-purchase check + reward code); omit it for anonymous.
+ */
+interface SubmitReviewParams {
+    /** Slug of the product being reviewed */
+    slug: string;
+    /** Star rating 1–5 */
+    rating: number;
+    /** Review body text */
+    body: string;
+    /** Optional short title */
+    title?: string;
+    /** Display name for anonymous reviews (ignored when a sessionId is passed) */
+    authorName?: string;
+}
+/** Reward discount code revealed to a logged-in reviewer (if enabled). */
+interface SubmitReviewReward {
+    /** The discount code, e.g. "KIITOS10" */
+    code: string;
+    /** "PERCENTAGE" | "FIXED_AMOUNT" */
+    discountType: string;
+    /** Percentage (e.g. 10) or fixed amount in cents, per discountType */
+    discountValue: number;
+}
+/**
+ * Response from POST /reviews. The created review is always PENDING (the store
+ * owner moderates it). `reward` is non-null only for logged-in reviewers when
+ * the store has enabled a (still-live) reward code.
+ */
+interface SubmitReviewResponse {
+    success: boolean;
+    review: {
+        id: string;
+        status: ReviewStatus;
+        verifiedPurchase: boolean;
+    };
+    reward: SubmitReviewReward | null;
+}
+
 /**
  * Putiikkipalvelu Storefront SDK Types
  *
@@ -3185,6 +3281,69 @@ declare function createWithdrawalResource(fetcher: Fetcher): {
  */
 type WithdrawalResource = ReturnType<typeof createWithdrawalResource>;
 
+/**
+ * Reviews Resource
+ *
+ * Read approved product reviews and submit new ones. Submitting works both
+ * anonymously and for logged-in customers — pass a sessionId to run the
+ * verified-purchase check and (if the store enabled it) reveal a reward code.
+ */
+
+/**
+ * Reviews resource for listing and submitting product reviews
+ */
+declare function createReviewsResource(fetcher: Fetcher): {
+    /**
+     * List approved reviews for a product, with the aggregate rating and a
+     * 1–5 star distribution.
+     *
+     * @param slug - Product URL slug
+     * @param options - Fetch options (caching, headers, etc.)
+     * @returns Approved reviews, average rating, count, and distribution
+     *
+     * @example
+     * ```typescript
+     * const { reviews, averageRating, reviewCount } =
+     *   await client.reviews.list('my-product');
+     * ```
+     */
+    list(slug: string, options?: FetchOptions): Promise<ReviewListResponse>;
+    /**
+     * Submit a product review. Anonymous by default; pass a sessionId to submit
+     * as a logged-in customer (enables the verified-purchase check + reward code).
+     * The review is created as PENDING and appears once the store owner approves it.
+     *
+     * @param params - Review data (slug, rating 1–5, body, optional title/authorName)
+     * @param sessionId - Optional customer session id (logged-in submit)
+     * @param options - Fetch options
+     * @returns The created review (PENDING) and a reward code if revealed
+     *
+     * @example Anonymous
+     * ```typescript
+     * await client.reviews.submit({
+     *   slug: 'my-product',
+     *   rating: 5,
+     *   body: 'Loistava tuote!',
+     *   authorName: 'Matti',
+     * });
+     * ```
+     *
+     * @example Logged-in (may return a reward code)
+     * ```typescript
+     * const { reward } = await client.reviews.submit(
+     *   { slug: 'my-product', rating: 5, body: 'Loistava tuote!' },
+     *   sessionId
+     * );
+     * if (reward) console.log(`Käytä koodia ${reward.code}`);
+     * ```
+     */
+    submit(params: SubmitReviewParams, sessionId?: string, options?: FetchOptions): Promise<SubmitReviewResponse>;
+};
+/**
+ * Type for the reviews resource
+ */
+type ReviewsResource = ReturnType<typeof createReviewsResource>;
+
 /**
  * The Storefront API client
  */
@@ -3241,6 +3400,10 @@ interface StorefrontClient {
      * Withdrawal resource for consumer withdrawal notices (KKV peruutustoiminto)
      */
     readonly withdrawal: WithdrawalResource;
+    /**
+     * Reviews resource for listing and submitting product reviews
+     */
+    readonly reviews: ReviewsResource;
 }
 /**
  * Create a new Storefront API client
@@ -3488,4 +3651,4 @@ declare class VerificationRequiredError extends StorefrontError {
     constructor(message: string, customerId: string);
 }
 
-export { type AboutBlock, type AccordionBlock, type AccordionItem, type AddToCartParams, type AddToWishlistResponse, type AnalyticsConfig, type AppliedDiscount, type ApplyDiscountParams, type ApplyDiscountResponse, AuthError, type BuyXPayYCampaign, type CalculatedCartItem, type Campaign, type CampaignType, type CarouselContentBlock, type CarouselContentItem, 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 DownloadUrlResponse, type DownloadsAuthOptions, type FeatureFlags, type FetchOptions, type ForgotPasswordResponse, type FormatDiscountOptions, type GalleryBlock, type GalleryItem, type GetDiscountParams, type GetDiscountResponse, type GetOrdersResponse, type GetUserResponse, type HomeDeliveryOption, type ImageAspectRatio, type ImageGridBlock, type ImageGridItem, type LoginOptions, type LoginResponse, type LoginVerificationRequiredResponse, type LogoutResponse, type MarkdownBlock, type NavPage, NotFoundError, type OpeningHours, type OpeningHoursBlock, type OpeningHoursEntry, type Order, type OrderDownload, type OrderDownloadLineItem, type OrderDownloadsResponse, type OrderLineItem, type OrderProductInfo, type OrderShipmentMethod, type OrderStatus, type PageBlock, type PageSeo, 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 ProductTicketInfo, type ProductVariation, type ProductVariationListing, type PurchasedTicket, RateLimitError, type RegisterData, type RegisterResponse, type RemoveDiscountParams, type RemoveDiscountResponse, type RemoveFromCartParams, type RemoveFromWishlistResponse, type ResendVerificationResponse, type ResetPasswordResponse, type ShipitShippingMethod, type ShipmentMethod, type ShipmentMethodsResponse, type ShowcaseBlock, type ShowcaseItem, type StoreConfig, type StoreInfo, type StorePage, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, type StripeCheckoutResponse, type TableBlock, type TextGridBlock, type TextGridItem, type TicketEvent, type TicketEventsResponse, type TicketGetResponse, type TicketHolderData, type TicketStatus, type TicketUseResponse, type TicketValidatePinResponse, type UpdateCartQuantityParams, type UpdateProfileData, type UpdateProfileResponse, ValidationError, type VariationOption, VerificationRequiredError, type VerifyEmailResponse, type WishlistItem, type WishlistProduct, type WishlistResponse, type WishlistVariation, type WishlistVariationOption, type WithdrawalItem, type WithdrawalNoticeParams, type WithdrawalResolveTokenResponse, type WithdrawalSubmitResponse, calculateCartWithCampaigns, calculateDiscountAmount, createStorefrontClient, formatDiscountValue, getDiscountApplyErrorMessage, getDiscountRemovalMessage, getPriceInfo, isSaleActive };
+export { type AboutBlock, type AccordionBlock, type AccordionItem, type AddToCartParams, type AddToWishlistResponse, type AnalyticsConfig, type AppliedDiscount, type ApplyDiscountParams, type ApplyDiscountResponse, AuthError, type BuyXPayYCampaign, type CalculatedCartItem, type Campaign, type CampaignType, type CarouselContentBlock, type CarouselContentItem, 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 DownloadUrlResponse, type DownloadsAuthOptions, type FeatureFlags, type FetchOptions, type ForgotPasswordResponse, type FormatDiscountOptions, type GalleryBlock, type GalleryItem, type GetDiscountParams, type GetDiscountResponse, type GetOrdersResponse, type GetUserResponse, type HomeDeliveryOption, type ImageAspectRatio, type ImageGridBlock, type ImageGridItem, type LoginOptions, type LoginResponse, type LoginVerificationRequiredResponse, type LogoutResponse, type MarkdownBlock, type NavPage, NotFoundError, type OpeningHours, type OpeningHoursBlock, type OpeningHoursEntry, type Order, type OrderDownload, type OrderDownloadLineItem, type OrderDownloadsResponse, type OrderLineItem, type OrderProductInfo, type OrderShipmentMethod, type OrderStatus, type PageBlock, type PageSeo, 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 ProductTicketInfo, type ProductVariation, type ProductVariationListing, type PurchasedTicket, RateLimitError, type RegisterData, type RegisterResponse, type RemoveDiscountParams, type RemoveDiscountResponse, type RemoveFromCartParams, type RemoveFromWishlistResponse, type ResendVerificationResponse, type ResetPasswordResponse, type Review, type ReviewListResponse, type ReviewStatus, type ShipitShippingMethod, type ShipmentMethod, type ShipmentMethodsResponse, type ShowcaseBlock, type ShowcaseItem, type StoreConfig, type StoreInfo, type StorePage, type StoreSeo, type StorefrontClient, type StorefrontClientConfig, StorefrontError, type StripeCheckoutResponse, type SubmitReviewParams, type SubmitReviewResponse, type SubmitReviewReward, type TableBlock, type TextGridBlock, type TextGridItem, type TicketEvent, type TicketEventsResponse, type TicketGetResponse, type TicketHolderData, type TicketStatus, type TicketUseResponse, type TicketValidatePinResponse, type UpdateCartQuantityParams, type UpdateProfileData, type UpdateProfileResponse, ValidationError, type VariationOption, VerificationRequiredError, type VerifyEmailResponse, type WishlistItem, type WishlistProduct, type WishlistResponse, type WishlistVariation, type WishlistVariationOption, type WithdrawalItem, type WithdrawalNoticeParams, type WithdrawalResolveTokenResponse, type WithdrawalSubmitResponse, calculateCartWithCampaigns, calculateDiscountAmount, createStorefrontClient, formatDiscountValue, getDiscountApplyErrorMessage, getDiscountRemovalMessage, getPriceInfo, isSaleActive };