@sazito/checkout 0.2.1 → 0.4.0

package/dist/next/index.d.cts

@@ -94,14 +94,32 @@ interface CheckoutCredentials {
         id: number;
         identifier: string;
     };
+    payment?: {
+        id: number;
+        identifier: string;
+    };
+}
+/** Normalized payment callback data accepted by `SazitoCheckoutPage`. */
+interface CheckoutPaymentReturn {
+    payment: {
+        id: number;
+        identifier: string;
+    };
+    params: Record<string, string>;
 }
+/** Search-param shape exposed by current Next.js App Router pages. */
+type PaymentReturnSearchParams = Record<string, string | string[] | undefined>;
 interface CheckoutConfig {
     locale?: CheckoutLocale;
     direction?: CheckoutDirection;
     theme?: CheckoutTheme;
     /** URL for the "continue shopping" / back-to-store action. */
     continueShoppingUrl?: string;
-    /** URL the gateway returns to after payment. Defaults to current URL. */
+    /**
+     * Reserved for gateways that support a caller-provided return URL.
+     * Current Sazito legacy callbacks use their generated nested result path.
+     * @deprecated Use an optional catch-all route with `parsePaymentReturn`.
+     */
     returnUrl?: string;
     /** Pending-payment poll interval in ms (default 15000). */
     pollIntervalMs?: number;
@@ -335,8 +353,27 @@ interface RenderButtonProps {
     /** Localised label for the current step. */
     children: ReactNode;
 }
-interface RenderEmptyCartProps$1 {
+interface RenderEmptyCartProps {
     continueShoppingUrl?: string;
+    title: ReactNode;
+    description: ReactNode;
+    actionLabel: ReactNode;
+    icon: ReactNode;
+}
+/** Content-level customisation for the built-in empty-cart screen. */
+interface EmptyCartOptions {
+    /** Empty-state heading. Defaults to the active locale. */
+    title?: ReactNode;
+    /** Supporting copy below the heading. Defaults to the active locale. */
+    description?: ReactNode;
+    /** Label for the back-to-store action. Defaults to the active locale. */
+    actionLabel?: ReactNode;
+    /** Replace the built-in cart illustration. */
+    icon?: ReactNode;
+    /** Override config.continueShoppingUrl for this action only. */
+    actionUrl?: string;
+    /** Hide the action even when a continue-shopping URL is configured. */
+    hideAction?: boolean;
 }
 interface SazitoCheckoutProps {
     theme?: CheckoutTheme;
@@ -344,9 +381,10 @@ interface SazitoCheckoutProps {
     className?: string;
     renderNextButton?: (props: RenderButtonProps) => ReactNode;
     renderBackButton?: (props: RenderButtonProps) => ReactNode;
-    renderEmptyCart?: (props: RenderEmptyCartProps$1) => ReactNode;
+    renderEmptyCart?: (props: RenderEmptyCartProps) => ReactNode;
+    emptyCart?: EmptyCartOptions;
 }
-declare function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutProps): react_jsx_runtime.JSX.Element;
+declare function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }: SazitoCheckoutProps): react_jsx_runtime.JSX.Element;
 
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: 'primary' | 'outline' | 'ghost';
@@ -388,19 +426,20 @@ interface ErrorBannerProps {
 }
 declare function ErrorBanner({ message, asChild, children, className }: ErrorBannerProps): react_jsx_runtime.JSX.Element;
 
-interface RenderEmptyCartProps {
-    continueShoppingUrl?: string;
-}
 interface SazitoCheckoutPageProps {
     credentials?: CheckoutCredentials;
     config?: CheckoutConfig;
+    /** Parsed nested gateway callback. Prefer `parsePaymentReturn()` to create it. */
+    paymentReturn?: CheckoutPaymentReturn;
+    /** @deprecated Prefer `paymentReturn`; retained for query-only callbacks. */
     paymentReturnParams?: Record<string, string>;
     className?: string;
     renderNextButton?: (props: RenderButtonProps) => React.ReactNode;
     renderBackButton?: (props: RenderButtonProps) => React.ReactNode;
     renderEmptyCart?: (props: RenderEmptyCartProps) => React.ReactNode;
+    emptyCart?: EmptyCartOptions;
 }
-declare function SazitoCheckoutPage({ credentials, config, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutPageProps): react_jsx_runtime.JSX.Element;
+declare function SazitoCheckoutPage({ credentials, config, paymentReturn, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }: SazitoCheckoutPageProps): react_jsx_runtime.JSX.Element;
 
 interface CheckoutProviderProps {
     /** Override the SazitoProvider client for this checkout instance only. */
@@ -433,4 +472,4 @@ interface SazitoProviderProps {
 declare function SazitoProvider({ client, children }: SazitoProviderProps): react_jsx_runtime.JSX.Element;
 
 export { Button, CheckoutProvider, ErrorBanner, Field, ProductPlaceholder, SazitoCheckout, SazitoCheckoutPage, SazitoProvider, SectionTitle, Spinner, useCheckout };
-export type { ButtonProps, CheckoutProviderProps, ErrorBannerProps, FieldProps, ProductPlaceholderProps, RenderButtonProps, RenderEmptyCartProps as RenderEmptyCartPageProps, RenderEmptyCartProps$1 as RenderEmptyCartProps, SazitoCheckoutPageProps, SazitoCheckoutProps, SazitoProviderProps, SectionTitleProps, SpinnerProps };
+export type { ButtonProps, CheckoutPaymentReturn, CheckoutProviderProps, EmptyCartOptions, ErrorBannerProps, FieldProps, PaymentReturnSearchParams, ProductPlaceholderProps, RenderButtonProps, RenderEmptyCartProps as RenderEmptyCartPageProps, RenderEmptyCartProps, SazitoCheckoutPageProps, SazitoCheckoutProps, SazitoProviderProps, SectionTitleProps, SpinnerProps };

package/dist/next/index.d.ts

@@ -94,14 +94,32 @@ interface CheckoutCredentials {
         id: number;
         identifier: string;
     };
+    payment?: {
+        id: number;
+        identifier: string;
+    };
+}
+/** Normalized payment callback data accepted by `SazitoCheckoutPage`. */
+interface CheckoutPaymentReturn {
+    payment: {
+        id: number;
+        identifier: string;
+    };
+    params: Record<string, string>;
 }
+/** Search-param shape exposed by current Next.js App Router pages. */
+type PaymentReturnSearchParams = Record<string, string | string[] | undefined>;
 interface CheckoutConfig {
     locale?: CheckoutLocale;
     direction?: CheckoutDirection;
     theme?: CheckoutTheme;
     /** URL for the "continue shopping" / back-to-store action. */
     continueShoppingUrl?: string;
-    /** URL the gateway returns to after payment. Defaults to current URL. */
+    /**
+     * Reserved for gateways that support a caller-provided return URL.
+     * Current Sazito legacy callbacks use their generated nested result path.
+     * @deprecated Use an optional catch-all route with `parsePaymentReturn`.
+     */
     returnUrl?: string;
     /** Pending-payment poll interval in ms (default 15000). */
     pollIntervalMs?: number;
@@ -335,8 +353,27 @@ interface RenderButtonProps {
     /** Localised label for the current step. */
     children: ReactNode;
 }
-interface RenderEmptyCartProps$1 {
+interface RenderEmptyCartProps {
     continueShoppingUrl?: string;
+    title: ReactNode;
+    description: ReactNode;
+    actionLabel: ReactNode;
+    icon: ReactNode;
+}
+/** Content-level customisation for the built-in empty-cart screen. */
+interface EmptyCartOptions {
+    /** Empty-state heading. Defaults to the active locale. */
+    title?: ReactNode;
+    /** Supporting copy below the heading. Defaults to the active locale. */
+    description?: ReactNode;
+    /** Label for the back-to-store action. Defaults to the active locale. */
+    actionLabel?: ReactNode;
+    /** Replace the built-in cart illustration. */
+    icon?: ReactNode;
+    /** Override config.continueShoppingUrl for this action only. */
+    actionUrl?: string;
+    /** Hide the action even when a continue-shopping URL is configured. */
+    hideAction?: boolean;
 }
 interface SazitoCheckoutProps {
     theme?: CheckoutTheme;
@@ -344,9 +381,10 @@ interface SazitoCheckoutProps {
     className?: string;
     renderNextButton?: (props: RenderButtonProps) => ReactNode;
     renderBackButton?: (props: RenderButtonProps) => ReactNode;
-    renderEmptyCart?: (props: RenderEmptyCartProps$1) => ReactNode;
+    renderEmptyCart?: (props: RenderEmptyCartProps) => ReactNode;
+    emptyCart?: EmptyCartOptions;
 }
-declare function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutProps): react_jsx_runtime.JSX.Element;
+declare function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }: SazitoCheckoutProps): react_jsx_runtime.JSX.Element;
 
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: 'primary' | 'outline' | 'ghost';
@@ -388,19 +426,20 @@ interface ErrorBannerProps {
 }
 declare function ErrorBanner({ message, asChild, children, className }: ErrorBannerProps): react_jsx_runtime.JSX.Element;
 
-interface RenderEmptyCartProps {
-    continueShoppingUrl?: string;
-}
 interface SazitoCheckoutPageProps {
     credentials?: CheckoutCredentials;
     config?: CheckoutConfig;
+    /** Parsed nested gateway callback. Prefer `parsePaymentReturn()` to create it. */
+    paymentReturn?: CheckoutPaymentReturn;
+    /** @deprecated Prefer `paymentReturn`; retained for query-only callbacks. */
     paymentReturnParams?: Record<string, string>;
     className?: string;
     renderNextButton?: (props: RenderButtonProps) => React.ReactNode;
     renderBackButton?: (props: RenderButtonProps) => React.ReactNode;
     renderEmptyCart?: (props: RenderEmptyCartProps) => React.ReactNode;
+    emptyCart?: EmptyCartOptions;
 }
-declare function SazitoCheckoutPage({ credentials, config, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutPageProps): react_jsx_runtime.JSX.Element;
+declare function SazitoCheckoutPage({ credentials, config, paymentReturn, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }: SazitoCheckoutPageProps): react_jsx_runtime.JSX.Element;
 
 interface CheckoutProviderProps {
     /** Override the SazitoProvider client for this checkout instance only. */
@@ -433,4 +472,4 @@ interface SazitoProviderProps {
 declare function SazitoProvider({ client, children }: SazitoProviderProps): react_jsx_runtime.JSX.Element;
 
 export { Button, CheckoutProvider, ErrorBanner, Field, ProductPlaceholder, SazitoCheckout, SazitoCheckoutPage, SazitoProvider, SectionTitle, Spinner, useCheckout };
-export type { ButtonProps, CheckoutProviderProps, ErrorBannerProps, FieldProps, ProductPlaceholderProps, RenderButtonProps, RenderEmptyCartProps as RenderEmptyCartPageProps, RenderEmptyCartProps$1 as RenderEmptyCartProps, SazitoCheckoutPageProps, SazitoCheckoutProps, SazitoProviderProps, SectionTitleProps, SpinnerProps };
+export type { ButtonProps, CheckoutPaymentReturn, CheckoutProviderProps, EmptyCartOptions, ErrorBannerProps, FieldProps, PaymentReturnSearchParams, ProductPlaceholderProps, RenderButtonProps, RenderEmptyCartProps as RenderEmptyCartPageProps, RenderEmptyCartProps, SazitoCheckoutPageProps, SazitoCheckoutProps, SazitoProviderProps, SectionTitleProps, SpinnerProps };

package/dist/next/index.js

@@ -1,9 +1,9 @@
 'use client';
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { isValidElement, cloneElement, useMemo, useState, useRef, useEffect, useCallback } from 'react';
-import { u as useCheckout, b as useSazitoClient, C as CheckoutProvider } from '../chunks/use-checkout-DwHd4uFh.js';
-export { S as SazitoProvider } from '../chunks/use-checkout-DwHd4uFh.js';
-import { m as formatPercent, E as sortCartItemsNewestFirst, H as toPersianDigits, r as isDigitalServiceGroup, t as isValidIranianMobile, z as normalizeIranianPhone, A as paymentMethodInfo, l as formatNumber } from '../chunks/labels-CTR6b-KZ.js';
+import { u as useCheckout, b as useSazitoClient, C as CheckoutProvider } from '../chunks/use-checkout-BM810__v.js';
+export { S as SazitoProvider } from '../chunks/use-checkout-BM810__v.js';
+import { m as formatPercent, E as sortCartItemsNewestFirst, H as toPersianDigits, r as isDigitalServiceGroup, t as isValidIranianMobile, z as normalizeIranianPhone, A as paymentMethodInfo, l as formatNumber } from '../chunks/labels-e8w4zRbg.js';
 import '@sazito/client-sdk';
 
 /**
@@ -185,17 +185,29 @@ function attrHexColor(value) {
     }
     return toHexColor(value);
 }
-function CartStep({ continueShoppingUrl, renderEmpty, }) {
+function CartStep({ continueShoppingUrl, emptyCart, renderEmpty, }) {
     const { state, actions, money, t } = useCheckout();
     const cart = state.cart;
     const busy = state.flags.updatingCart;
     const newestCartItems = useMemo(() => sortCartItemsNewestFirst(cart?.items ?? []), [cart?.items]);
     const invoiceItemsByVariant = new Map((state.invoice?.items ?? []).map((item) => [item.productVariantId, item]));
     if (!cart || cart.items.length === 0) {
+        const title = emptyCart?.title ?? t.cartEmpty;
+        const description = emptyCart?.description ?? t.cartEmptyHint;
+        const actionLabel = emptyCart?.actionLabel ?? t.continueShopping;
+        const actionUrl = emptyCart?.actionUrl ?? continueShoppingUrl;
+        const visibleActionUrl = emptyCart?.hideAction ? undefined : actionUrl;
+        const icon = emptyCart?.icon ?? jsx(CartIcon, {});
         if (renderEmpty) {
-            return renderEmpty({ continueShoppingUrl });
+            return renderEmpty({
+                continueShoppingUrl: visibleActionUrl,
+                title,
+                description,
+                actionLabel,
+                icon,
+            });
         }
-        return (jsx("section", { className: "szc-empty", role: "status", "aria-live": "polite", children: jsxs("div", { className: "szc-empty__card", children: [jsx("span", { className: "szc-empty__badge", children: jsx(CartIcon, {}) }), jsxs("div", { className: "szc-empty__copy", children: [jsx("h3", { className: "szc-empty__title", children: t.cartEmpty }), jsx("p", { className: "szc-empty__hint", children: t.cartEmptyHint })] }), continueShoppingUrl ? (jsx(Button, { className: "szc-empty__cta", variant: "primary", onClick: () => { window.location.href = continueShoppingUrl; }, children: t.continueShopping })) : null] }) }));
+        return (jsx("section", { className: "szc-empty", role: "status", "aria-live": "polite", children: jsxs("div", { className: "szc-empty__card", children: [jsx("span", { className: "szc-empty__badge", "aria-hidden": "true", children: icon }), jsxs("div", { className: "szc-empty__copy", children: [jsx("h2", { className: "szc-empty__title", children: title }), jsx("p", { className: "szc-empty__hint", children: description })] }), visibleActionUrl ? (jsx(Button, { className: "szc-empty__cta", variant: "primary", asChild: true, children: jsx("a", { href: visibleActionUrl, children: actionLabel }) })) : null] }) }));
     }
     return (jsx("section", { className: "szc-step-panel", children: jsx("ul", { className: "szc-cart-list", children: newestCartItems.map((item) => {
                 const max = item.product.maxOrderQuantity;
@@ -758,12 +770,13 @@ function themeVars(theme) {
 function CheckoutLoading({ label }) {
     return (jsxs("div", { className: "szc-checkout-loading", role: "status", "aria-live": "polite", children: [jsx(Spinner, { className: "szc-checkout-loading__spinner" }), jsx("span", { children: label })] }));
 }
-function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, }) {
+function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }) {
     const { state, actions, t, summary, money } = useCheckout();
     const { step, direction, flags, error } = state;
     const isResult = step === 'result';
     const bootstrapping = step === 'cart' && !error && (!state.cart || !state.invoice || flags.bootstrapping);
-    const fatal = error && !state.cart && step === 'cart';
+    const emptyCartError = error?.code === 'no_cart';
+    const fatal = error && !state.cart && step === 'cart' && !emptyCartError;
     const cartEmpty = !state.cart || state.cart.items.length === 0;
     const footerVisible = (step === 'cart' && !cartEmpty) || step === 'shipping' || step === 'payment';
     const nextBusy = state.status === 'working' ||
@@ -831,20 +844,28 @@ function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButto
                 ? CardIcon
                 : ClipboardIcon;
     const mobileHead = (jsxs("div", { className: "szc-mobile-head", children: [footerVisible && backVisible ? (jsx("button", { type: "button", className: "szc-mobile-head__back", "aria-label": t.back, onClick: backOnClick, children: jsx("svg", { className: "szc-back-arrow", viewBox: "0 0 16 16", width: "18", height: "18", fill: "none", "aria-hidden": "true", children: jsx("path", { d: "M9.5 3.5 5 8l4.5 4.5", stroke: "currentColor", strokeWidth: "1.8", strokeLinecap: "round", strokeLinejoin: "round" }) }) })) : (jsx("span", {})), jsxs("span", { className: "szc-mobile-head__title", children: [jsx("span", { className: "szc-mobile-head__dot", children: jsx(HeadIcon, {}) }), headTitle] }), flowIndex >= 0 ? (jsx("span", { className: "szc-mobile-head__count", children: t.stepOf(formatNumber(flowIndex + 1, state.locale), formatNumber(flowSteps.length, state.locale)) })) : (jsx("span", {}))] }));
-    return (jsxs("div", { className: `szc-root${className ? ` ${className}` : ''}`, dir: direction, style: themeVars(theme), children: [mobileHead, jsx(Stepper, {}), bootstrapping ? (jsx(CheckoutLoading, { label: t.loading })) : fatal ? (jsx(ErrorBanner, { message: error.message })) : isResult ? (jsx("div", { className: "szc-result-wrap", children: jsx(ResultStep, { continueShoppingUrl: continueShoppingUrl }) })) : (jsx(Fragment, { children: jsxs("div", { className: `szc-layout${cartEmpty ? ' szc-layout--full' : ''}`, children: [jsxs("main", { className: "szc-main", children: [error ? jsx(ErrorBanner, { message: error.message }) : null, step === 'cart' ? jsx(CartStep, { continueShoppingUrl: continueShoppingUrl, renderEmpty: renderEmptyCart }) : null, step === 'shipping' ? jsx(ShippingStep, {}) : null, step === 'payment' ? jsx(PaymentStep, {}) : null, actionsVisible && backButtonNode ? (jsx("div", { className: "szc-back-row", children: backButtonNode })) : null] }), !cartEmpty ? (jsxs("div", { className: "szc-side", children: [jsx(OrderSummary, {}), actionsVisible ? jsx("div", { className: "szc-side__cta", children: nextButtonNode }) : null] })) : null] }) })), actionsVisible ? (jsx("div", { className: "szc-footer-bar", children: jsxs("div", { className: "szc-footer", children: [jsxs("div", { className: "szc-footer__total", children: [jsx("span", { className: "szc-footer__total-label", children: t.total }), jsx("span", { className: "szc-footer__total-value", children: money(summary.total) })] }), jsx("div", { className: "szc-footer__actions", children: nextButtonNode })] }) })) : null] }));
+    return (jsxs("div", { className: `szc-root${className ? ` ${className}` : ''}`, dir: direction, style: themeVars(theme), children: [mobileHead, jsx(Stepper, {}), bootstrapping ? (jsx(CheckoutLoading, { label: t.loading })) : fatal ? (jsx(ErrorBanner, { message: error.message })) : isResult ? (jsx("div", { className: "szc-result-wrap", children: jsx(ResultStep, { continueShoppingUrl: continueShoppingUrl }) })) : (jsx(Fragment, { children: jsxs("div", { className: `szc-layout${cartEmpty ? ' szc-layout--full' : ''}`, children: [jsxs("main", { className: "szc-main", children: [error && !emptyCartError ? jsx(ErrorBanner, { message: error.message }) : null, step === 'cart' ? (jsx(CartStep, { continueShoppingUrl: continueShoppingUrl, emptyCart: emptyCart, renderEmpty: renderEmptyCart })) : null, step === 'shipping' ? jsx(ShippingStep, {}) : null, step === 'payment' ? jsx(PaymentStep, {}) : null, actionsVisible && backButtonNode ? (jsx("div", { className: "szc-back-row", children: backButtonNode })) : null] }), !cartEmpty ? (jsxs("div", { className: "szc-side", children: [jsx(OrderSummary, {}), actionsVisible ? jsx("div", { className: "szc-side__cta", children: nextButtonNode }) : null] })) : null] }) })), actionsVisible ? (jsx("div", { className: "szc-footer-bar", children: jsxs("div", { className: "szc-footer", children: [jsxs("div", { className: "szc-footer__total", children: [jsx("span", { className: "szc-footer__total-label", children: t.total }), jsx("span", { className: "szc-footer__total-value", children: money(summary.total) })] }), jsx("div", { className: "szc-footer__actions", children: nextButtonNode })] }) })) : null] }));
 }
 
-function SazitoCheckoutPage({ credentials, config, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, }) {
-    const isReturn = paymentReturnParams != null;
+function SazitoCheckoutPage({ credentials, config, paymentReturn, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, emptyCart, }) {
+    const returnParams = paymentReturn?.params ?? paymentReturnParams;
+    const isReturn = returnParams != null;
+    const checkoutCredentials = paymentReturn
+        ? { ...credentials, payment: paymentReturn.payment }
+        : credentials;
     const client = useSazitoClient();
-    return (jsxs(CheckoutProvider, { client: client, credentials: credentials, config: config, autoStart: !isReturn, children: [isReturn ? jsx(ResolveReturn, { params: paymentReturnParams }) : null, jsx(SazitoCheckout, { theme: config?.theme, continueShoppingUrl: config?.continueShoppingUrl, className: className, renderNextButton: renderNextButton, renderBackButton: renderBackButton, renderEmptyCart: renderEmptyCart })] }));
+    return (jsxs(CheckoutProvider, { client: client, credentials: checkoutCredentials, config: config, autoStart: !isReturn, children: [returnParams ? jsx(ResolveReturn, { params: returnParams }) : null, jsx(SazitoCheckout, { theme: config?.theme, continueShoppingUrl: config?.continueShoppingUrl, className: className, renderNextButton: renderNextButton, renderBackButton: renderBackButton, renderEmptyCart: renderEmptyCart, emptyCart: emptyCart })] }));
 }
 function ResolveReturn({ params }) {
     const { actions } = useCheckout();
+    const resolvedKey = useRef(null);
+    const paramsKey = JSON.stringify(Object.entries(params).sort(([a], [b]) => a.localeCompare(b)));
     useEffect(() => {
+        if (resolvedKey.current === paramsKey)
+            return;
+        resolvedKey.current = paramsKey;
         void actions.resolvePaymentReturn(params);
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, []);
+    }, [actions, params, paramsKey]);
     return null;
 }