@putiikkipalvelu/storefront-sdk 0.7.4 → 0.10.0

package/dist/index.d.cts

@@ -345,6 +345,8 @@ interface Product {
     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[];
 }
@@ -382,6 +384,11 @@ interface ProductDetail extends Omit<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
@@ -476,6 +483,8 @@ interface CartItem {
     variation?: ProductVariation;
     /** Whether this item is a ticket product (no shipping required) */
     isTicket?: boolean;
+    /** Whether this item is a digital product (no shipping required) */
+    isDigital?: boolean;
 }
 /**
  * Response from GET /cart, POST /cart, PATCH /cart, DELETE /cart
@@ -743,6 +752,11 @@ interface ConfirmationOrderLineItem {
     vatRate: number;
     /** Product images array */
     images: string[];
+    /**
+     * Snapshot of the product's digital instructions at purchase time.
+     * Populated for digital products; null otherwise.
+     */
+    digitalContent?: string | null;
 }
 /**
  * Customer delivery information attached to an order
@@ -1704,6 +1718,157 @@ interface TicketUseResponse {
     ticket: PurchasedTicket;
 }
 
+/**
+ * Digital Downloads Types
+ *
+ * Types for digital product downloads (instructions + downloadable files).
+ */
+/**
+ * A single downloadable file within an order line item.
+ * Snapshotted at purchase time — persists even if the merchant deletes the
+ * original product or file.
+ */
+interface OrderDownload {
+    /** Unique download record ID (pass this to getDownloadUrl) */
+    id: string;
+    /** Merchant-editable file name shown to the customer */
+    displayName: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** MIME type, e.g. "application/pdf" */
+    mimeType: string;
+    /** How many times this file has been downloaded on this order */
+    downloadCount: number;
+    /** Max downloads allowed on this order (null = unlimited) */
+    maxDownloads: number | null;
+    /** Downloads remaining (null = unlimited) */
+    remaining: number | null;
+}
+/**
+ * A line item in an order with digital content and/or downloadable files.
+ * Only line items that either have instructions or files are returned by
+ * the downloads list endpoint.
+ */
+interface OrderDownloadLineItem {
+    /** Order line item ID */
+    id: string;
+    /** Product/variation display name */
+    name: string;
+    /** Quantity ordered */
+    quantity: number;
+    /** Sanitized HTML instructions (from merchant's TipTap field). May be null. */
+    digitalContent: string | null;
+    /** Downloadable files attached to this line item. May be empty. */
+    downloads: OrderDownload[];
+}
+/**
+ * Response from GET /order/:id/downloads
+ */
+interface OrderDownloadsResponse {
+    /** Order ID the downloads belong to */
+    orderId: string;
+    /** Line items with digital content and/or downloads */
+    items: OrderDownloadLineItem[];
+}
+/**
+ * Response from POST /order/:id/downloads/:downloadId
+ * Short-lived presigned URL for downloading the file directly from R2.
+ */
+interface DownloadUrlResponse {
+    /** Presigned download URL (typically valid ~5 minutes) */
+    url: string;
+    /** How long the URL stays valid, in seconds */
+    expiresIn: number;
+}
+/**
+ * Options for calling the downloads endpoints.
+ * Authentication is granted via EITHER a token (from order confirmation email)
+ * OR a valid customer session (logged-in customer who owns the order).
+ */
+interface DownloadsAuthOptions {
+    /** Download token from the confirmation email URL. Use this for guest access. */
+    token?: string;
+    /** Customer session token. Use this for logged-in customer access. */
+    sessionId?: string;
+}
+
+/**
+ * Withdrawal Notice Types
+ *
+ * Types for the KKV peruutustoiminto / EU CRD Article 11a mandatory
+ * withdrawal function (effective 19.6.2026).
+ */
+/**
+ * A single item being withdrawn (partial withdrawal).
+ * Omit the items array entirely to indicate "whole order".
+ */
+interface WithdrawalItem {
+    /** Optional reference to a known line item id (matched orders only). */
+    lineItemId?: string;
+    /** Product name as the consumer sees it. */
+    productName: string;
+    /** Number of units being withdrawn. */
+    quantity: number;
+}
+/**
+ * Parameters for submitting a withdrawal notice.
+ *
+ * The function must accept the notice regardless of whether the order
+ * can be resolved server-side (KKV requires the function to record any
+ * submission as a legal record of intent).
+ */
+interface WithdrawalNoticeParams {
+    /** Consumer's name (KKV mandate). */
+    name: string;
+    /** Email where the confirmation will be sent (KKV mandate — consumer chooses). */
+    email: string;
+    /** Order number as the consumer types it. Optional — best-effort matched server-side. */
+    orderNumber?: string;
+    /**
+     * Items being withdrawn for a partial withdrawal.
+     * Omit / empty array = whole order.
+     */
+    items?: WithdrawalItem[];
+    /** Optional free-text message from the consumer (max 2000 chars). */
+    message?: string;
+    /**
+     * Pre-submit confirmation flag — MUST be `true`.
+     * This represents the two-step UX step legally required by § 356a BGB
+     * (and implied by KKV "selkeästi merkitty vahvistustoiminto").
+     */
+    confirmRead: true;
+    /**
+     * Honeypot field — leave empty. Submissions with a non-empty value are
+     * silently dropped server-side as bot traffic.
+     */
+    honeypot?: string;
+}
+/**
+ * Response from a successful withdrawal submission.
+ */
+interface WithdrawalSubmitResponse {
+    /** Human-readable per-store sequence (e.g. "PER-0042"). */
+    noticeNumber: string;
+    /** ISO timestamp of submission — printed on the confirmation email. */
+    createdAt: string;
+}
+/**
+ * Order details resolved from a withdrawal token (the signed link in the
+ * order confirmation email). Used to pre-fill the withdrawal form.
+ */
+interface WithdrawalResolveTokenResponse {
+    /** Order number as a string ready to display. */
+    orderNumber: string;
+    /** Customer's full name from the order. */
+    customerName: string;
+    /** Customer's email from the order. */
+    customerEmail: string;
+    /** Line items eligible for partial withdrawal (excludes shipping rows). */
+    items: WithdrawalItem[];
+    /** ISO timestamp when the token expires. */
+    expiresAt: string;
+}
+
 /**
  * Putiikkipalvelu Storefront SDK Types
  *
@@ -2573,7 +2738,7 @@ declare function createCustomerResource(fetcher: Fetcher): {
 type CustomerResource = ReturnType<typeof createCustomerResource>;
 
 /**
- * Order resource for fetching order details
+ * Order resource for fetching order details and digital downloads
  *
  * Used for order confirmation pages and viewing order details.
  * For customer order history, use the customer.getOrders() method instead.
@@ -2596,36 +2761,54 @@ declare function createOrderResource(fetcher: Fetcher): {
      * console.log(`Order #${order.orderNumber} - ${order.status}`);
      * console.log(`Total: ${order.totalAmount / 100} EUR`);
      * ```
+     */
+    get(orderId: string, options?: FetchOptions): Promise<Order>;
+    /**
+     * List downloadable files for a paid order.
      *
-     * @example Next.js - with caching
+     * Requires EITHER a download token (from the order confirmation email)
+     * OR a valid customer session (for logged-in customers viewing their own
+     * order history).
+     *
+     * Returns only line items that have digital content or downloadable files.
+     * The order must be paid (status !== PENDING or FAILED).
+     *
+     * @param orderId - The order ID
+     * @param auth - Token (guest) or sessionId (logged-in customer)
+     * @param options - Fetch options
+     *
+     * @example Guest access via email token
      * ```typescript
-     * const order = await client.order.get(orderId, {
-     *   next: { revalidate: 60, tags: ['order', orderId] }
-     * });
+     * const token = new URLSearchParams(location.search).get("token");
+     * const { items } = await client.order.listDownloads(orderId, { token });
      * ```
      *
-     * @example Display line items
+     * @example Logged-in customer
      * ```typescript
-     * const order = await client.order.get(orderId);
-     * order.OrderLineItems.forEach(item => {
-     *   if (item.itemType !== 'SHIPPING') {
-     *     console.log(`${item.name} x${item.quantity} = ${item.totalAmount / 100} EUR`);
-     *   }
-     * });
+     * const { items } = await client.order.listDownloads(orderId, { sessionId });
      * ```
+     */
+    listDownloads(orderId: string, auth?: DownloadsAuthOptions, options?: FetchOptions): Promise<OrderDownloadsResponse>;
+    /**
+     * Issue a short-lived presigned URL to download a specific file from a
+     * paid order. Increments the download counter and records a download
+     * event (IP, user agent) on the server.
+     *
+     * The returned URL is typically valid for ~5 minutes — redirect the
+     * browser to it or trigger a download immediately.
+     *
+     * @param orderId - The order ID
+     * @param downloadId - The OrderDownload.id
+     * @param auth - Token (guest) or sessionId (logged-in customer)
+     * @param options - Fetch options
      *
-     * @example Show tracking info
+     * @example
      * ```typescript
-     * const order = await client.order.get(orderId);
-     * if (order.orderShipmentMethod?.trackingNumber) {
-     *   console.log(`Tracking: ${order.orderShipmentMethod.trackingNumber}`);
-     *   order.orderShipmentMethod.trackingUrls?.forEach(url => {
-     *     console.log(`Track at: ${url}`);
-     *   });
-     * }
+     * const { url } = await client.order.getDownloadUrl(orderId, downloadId, { token });
+     * window.location.href = url;
      * ```
      */
-    get(orderId: string, options?: FetchOptions): Promise<Order>;
+    getDownloadUrl(orderId: string, downloadId: string, auth?: DownloadsAuthOptions, options?: FetchOptions): Promise<DownloadUrlResponse>;
 };
 /**
  * Type for the order resource
@@ -2931,6 +3114,59 @@ declare function createTicketsResource(fetcher: Fetcher): {
  */
 type TicketsResource = ReturnType<typeof createTicketsResource>;
 
+/**
+ * Withdrawal Resource
+ *
+ * Submits consumer withdrawal notices (KKV peruutustoiminto / EU CRD Art. 11a).
+ */
+
+/**
+ * Creates the withdrawal resource.
+ */
+declare function createWithdrawalResource(fetcher: Fetcher): {
+    /**
+     * Submit a withdrawal notice (peruutusilmoitus).
+     *
+     * The notice is a legal record of intent. The server records it regardless
+     * of whether the order number can be resolved, and the consumer receives a
+     * confirmation email containing what was withdrawn plus exact submission
+     * date/time.
+     *
+     * Refunds are handled separately by the merchant via the dashboard — this
+     * endpoint never issues a refund.
+     *
+     * @param params - Notice payload (name, email, optional orderNumber + items + message)
+     * @returns Notice number and creation timestamp
+     *
+     * @example
+     * ```typescript
+     * const { noticeNumber } = await client.withdrawal.submit({
+     *   name: "Matti Meikäläinen",
+     *   email: "matti@example.com",
+     *   orderNumber: "1024",
+     *   items: [{ productName: "Tuote A", quantity: 1 }],
+     *   message: "Haluan peruuttaa.",
+     *   confirmRead: true,
+     * });
+     * ```
+     */
+    submit(params: WithdrawalNoticeParams): Promise<WithdrawalSubmitResponse>;
+    /**
+     * Resolve a withdrawal token (from the order confirmation email link)
+     * to the matching order's details. Used to pre-fill the withdrawal form.
+     *
+     * Throws `StorefrontError` with code `EXPIRED` / `INVALID` / `STORE_MISMATCH`
+     * / `ORDER_NOT_FOUND` as appropriate.
+     *
+     * @param token - The signed token from the `?token=…` query param
+     */
+    resolveToken(token: string): Promise<WithdrawalResolveTokenResponse>;
+};
+/**
+ * Type for the withdrawal resource.
+ */
+type WithdrawalResource = ReturnType<typeof createWithdrawalResource>;
+
 /**
  * The Storefront API client
  */
@@ -2983,6 +3219,10 @@ interface StorefrontClient {
      * Tickets resource for ticket scanning and validation
      */
     readonly tickets: TicketsResource;
+    /**
+     * Withdrawal resource for consumer withdrawal notices (KKV peruutustoiminto)
+     */
+    readonly withdrawal: WithdrawalResource;
 }
 /**
  * Create a new Storefront API client
@@ -3230,4 +3470,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 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 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, 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 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 };