@sazito/checkout 0.1.0

package/dist/next/index.d.cts

@@ -0,0 +1,427 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode, ButtonHTMLAttributes, InputHTMLAttributes } from 'react';
+import { Cart, Invoice, ApplicableShippingMethods, InvoiceItem, ShippingRate, PaymentMethod, Order } from '@sazito/client-sdk';
+
+/**
+ * Checkout domain types.
+ *
+ * The package re-exports the SDK data models (camelCase) and layers
+ * checkout-specific state, config, events and effects on top.
+ */
+
+/** How a discount code changes the order. */
+type DiscountKind = 'percentage' | 'fixed_amount' | 'free_shipping' | 'unknown';
+/**
+ * A successfully applied discount code with its detected type. The API only
+ * reports discount codes as totals on the invoice, so the type is inferred by
+ * `classifyAppliedDiscount` (selectors) — `unknown` when nothing measurable
+ * changed yet (e.g. a free-shipping code applied before a rate is selected).
+ */
+interface AppliedDiscount {
+    code: string;
+    kind: DiscountKind;
+    /** Amount taken off the items total by this code. */
+    amount: number;
+    /** Percentage discounts only: the detected integer percent. */
+    percent?: number;
+    /** Shipping cost removed by the code. */
+    shippingSaved?: number;
+}
+/** Regions are not re-exported by the SDK top level; mirror the shape here. */
+interface CheckoutCity {
+    id: number;
+    name: string;
+    latitude: number;
+    longitude: number;
+}
+interface CheckoutRegion {
+    id: number;
+    name: string;
+    cities: CheckoutCity[];
+}
+type CheckoutLocale = 'fa' | 'en';
+type CheckoutDirection = 'rtl' | 'ltr';
+/** Interactive steps in order. `result` is the terminal post-payment screen. */
+type CheckoutStep = 'cart' | 'shipping' | 'payment' | 'result';
+/** Coarse engine status used to drive spinners / disabled states. */
+type CheckoutStatus = 'idle' | 'bootstrapping' | 'working' | 'redirecting' | 'polling' | 'error';
+type CheckoutResultStatus = 'success' | 'failed' | 'pending' | 'stock_violated';
+interface CheckoutTheme {
+    /** Primary accent (buttons, active states). CSS color. */
+    accent?: string;
+    /** Foreground used on top of the accent. CSS color. */
+    accentForeground?: string;
+    /** Soft accent surface used for selected rows and focus-adjacent states. */
+    accentSoft?: string;
+    /** Checkout page background. */
+    background?: string;
+    /** Primary text color. */
+    foreground?: string;
+    /** Muted surface background. */
+    muted?: string;
+    /** Secondary text color. */
+    mutedForeground?: string;
+    /** Borders and dividers. */
+    border?: string;
+    /** Form, product, and shipping card background. */
+    card?: string;
+    /** Order-summary sidebar background. */
+    summaryBackground?: string;
+    /** Error and destructive-state color. */
+    danger?: string;
+    /** Success and completed-state color. */
+    success?: string;
+    /** Base corner radius in px. */
+    radius?: number;
+    /** Font family. Defaults to `inherit` so the host font flows through. */
+    fontFamily?: string;
+}
+/** Seed credentials so checkout can attach to an already-built cart. */
+interface CheckoutCredentials {
+    cart?: {
+        id?: number;
+        identifier: string;
+    };
+    invoice?: {
+        id: number;
+        identifier: string;
+    };
+}
+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. */
+    returnUrl?: string;
+    /** Pending-payment poll interval in ms (default 15000). */
+    pollIntervalMs?: number;
+    /** Currency label override (defaults per-locale). */
+    currencyLabel?: string;
+    onEvent?: (event: CheckoutEvent) => void;
+}
+/** The guest contact + address form. */
+interface AddressFormValues {
+    firstName: string;
+    lastName: string;
+    mobilePhone: string;
+    email: string;
+    phoneNumber: string;
+    regionId: number | null;
+    cityId: number | null;
+    postalCode: string;
+    address: string;
+    description: string;
+}
+/**
+ * A shippable group: a set of invoice items shipped together, with the rates
+ * the customer can switch between and the currently selected rate.
+ */
+interface ShippingGroup {
+    key: string;
+    title: string;
+    itemIds: Array<number | string>;
+    items: InvoiceItem[];
+    rates: ShippingRate[];
+    selectedRateId: number | null;
+}
+interface CheckoutResult {
+    status: CheckoutResultStatus;
+    order?: Order;
+    message?: string;
+}
+interface CheckoutError {
+    message: string;
+    code?: CheckoutErrorCode;
+    status?: number;
+    step?: CheckoutStep;
+}
+type CheckoutErrorCode = 'no_cart' | 'no_invoice' | 'min_basket' | 'rate_limited' | 'cart_invalid' | 'invoice_locked' | 'stock_violated' | 'shipping_required' | 'address_required' | 'payment_failed' | 'network' | 'validation' | 'unknown';
+/** Per-region async flags so the UI can show targeted spinners. */
+interface CheckoutFlags {
+    bootstrapping: boolean;
+    updatingCart: boolean;
+    savingAddress: boolean;
+    loadingShipping: boolean;
+    selectingRate: boolean;
+    applyingDiscount: boolean;
+    loadingPayments: boolean;
+    placingOrder: boolean;
+}
+interface CheckoutState {
+    step: CheckoutStep;
+    status: CheckoutStatus;
+    locale: CheckoutLocale;
+    direction: CheckoutDirection;
+    cart: Cart | null;
+    invoice: Invoice | null;
+    regions: CheckoutRegion[];
+    addressForm: AddressFormValues;
+    /** Shop-level requirement loaded from the checkout configuration. */
+    postalCodeMandatory: boolean;
+    /** Shop-level requirement loaded from the checkout configuration. */
+    emailMandatory: boolean;
+    /** Whether the saved address on the invoice matches the current form. */
+    addressDirty: boolean;
+    applicable: ApplicableShippingMethods | null;
+    shippingGroups: ShippingGroup[];
+    paymentMethods: PaymentMethod[];
+    selectedPaymentMethodId: number | null;
+    discountCode: string;
+    appliedDiscountCode: string | null;
+    /** Type + saved amounts of the applied code; null when no code is applied. */
+    appliedDiscount: AppliedDiscount | null;
+    /** Inline error for the discount field; not shown in the global banner. */
+    discountError: string | null;
+    result: CheckoutResult | null;
+    error: CheckoutError | null;
+    flags: CheckoutFlags;
+}
+type CheckoutEventName = 'checkout_viewed' | 'step_viewed' | 'address_submitted' | 'shipping_rate_selected' | 'discount_applied' | 'discount_removed' | 'payment_method_selected' | 'payment_initiated' | 'payment_succeeded' | 'payment_failed' | 'payment_pending';
+interface CheckoutEvent {
+    name: CheckoutEventName;
+    step?: CheckoutStep;
+    value?: number;
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+}
+/** Public command surface exposed to UI bindings. */
+interface CheckoutActions {
+    /** Load cart + invoice and derive initial state. */
+    start(): Promise<void>;
+    goToStep(step: CheckoutStep): void;
+    next(): Promise<void>;
+    back(): void;
+    /** Cart review edits — update a line quantity or remove a line. */
+    updateItemQuantity(cartProductId: number | string, variantId: number, quantity: number): Promise<void>;
+    removeItem(cartProductId: number | string, variantId: number): Promise<void>;
+    setAddressField<K extends keyof AddressFormValues>(key: K, value: AddressFormValues[K]): void;
+    submitAddress(): Promise<boolean>;
+    selectShippingRate(groupKey: string, rateId: number): Promise<void>;
+    setDiscountCode(code: string): void;
+    applyDiscount(): Promise<void>;
+    removeDiscount(): Promise<void>;
+    selectPaymentMethod(id: number): void;
+    placeOrder(): Promise<void>;
+    /** Resolve a return from the payment gateway (query params from the URL). */
+    resolvePaymentReturn(params: Record<string, string>): Promise<void>;
+    reset(): void;
+}
+
+/**
+ * UI strings (fa/en) and domain label helpers (payment gateways, shipping).
+ */
+
+interface Strings {
+    stepCart: string;
+    stepShipping: string;
+    stepPayment: string;
+    stepReview: string;
+    stepResult: string;
+    /** Mobile header title for the shipping step. */
+    stepShippingInfo: string;
+    /** Mobile header progress, e.g. "مرحله ۲ از ۳" / "Step 2 of 3". */
+    stepOf: (current: string, total: string) => string;
+    next: string;
+    placeOrder: string;
+    saveShippingDetails: string;
+    continueToPayment: string;
+    finalizeOrder: string;
+    finishPurchase: string;
+    back: string;
+    continueShopping: string;
+    orderSummary: string;
+    subtotal: string;
+    shipping: string;
+    discount: string;
+    credit: string;
+    vat: string;
+    total: string;
+    totalAmount: string;
+    free: string;
+    quantity: string;
+    optional: string;
+    cartTitle: string;
+    cartEmpty: string;
+    cartEmptyHint: string;
+    remove: string;
+    itemDiscount: (amount: string) => string;
+    yourSavings: string;
+    contactInfo: string;
+    firstName: string;
+    lastName: string;
+    mobilePhone: string;
+    email: string;
+    phoneNumber: string;
+    region: string;
+    city: string;
+    postalCode: string;
+    addressLine: string;
+    description: string;
+    selectRegion: string;
+    selectCity: string;
+    shippingMethod: string;
+    shippingMethods: string;
+    shippingMethodsHint: string;
+    digitalNoShipping: string;
+    errorRequired: string;
+    errorMobilePhone: string;
+    errorEmail: string;
+    changeTo: string;
+    productCount: (n: string) => string;
+    paymentMethod: string;
+    discountCode: string;
+    discountPlaceholder: string;
+    apply: string;
+    applied: string;
+    discountPercentOff: (percent: string) => string;
+    discountAmountOff: (amount: string) => string;
+    discountFreeShipping: string;
+    reviewTitle: string;
+    reviewContact: string;
+    reviewAddress: string;
+    reviewShipping: string;
+    reviewPayment: string;
+    payNow: string;
+    edit: string;
+    paymentSuccess: string;
+    paymentFailed: string;
+    paymentPending: string;
+    paymentPendingHint: string;
+    orderNumber: string;
+    tryAgain: string;
+    loading: string;
+    processing: string;
+    redirecting: string;
+}
+
+/**
+ * Pure derivations over invoice / shipping data: shipping groups, summary
+ * lines, address form mapping and validation. No SDK calls, no side-effects.
+ */
+
+type SummaryLineKey = 'subtotal' | 'discount' | 'shipping' | 'credit' | 'vat';
+interface SummaryLine {
+    key: SummaryLineKey;
+    amount: number;
+    negative?: boolean;
+    free?: boolean;
+    /** Discount line only: amount as a percentage of subtotal (rounded). */
+    percent?: number;
+}
+interface CheckoutSummary {
+    lines: SummaryLine[];
+    total: number;
+}
+
+/** Props passed to renderNextButton / renderBackButton. */
+interface RenderButtonProps {
+    /** Whether the action is in-flight (show a loading indicator). */
+    loading: boolean;
+    /** Whether the button should be inert (validation not met). */
+    disabled: boolean;
+    /** Trigger the checkout action for this button. */
+    onClick: () => void;
+    /** Localised label for the current step. */
+    children: ReactNode;
+}
+interface RenderEmptyCartProps$1 {
+    continueShoppingUrl?: string;
+}
+interface SazitoCheckoutProps {
+    theme?: CheckoutTheme;
+    continueShoppingUrl?: string;
+    className?: string;
+    renderNextButton?: (props: RenderButtonProps) => ReactNode;
+    renderBackButton?: (props: RenderButtonProps) => ReactNode;
+    renderEmptyCart?: (props: RenderEmptyCartProps$1) => ReactNode;
+}
+declare function SazitoCheckout({ theme, continueShoppingUrl, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutProps): react_jsx_runtime.JSX.Element;
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: 'primary' | 'outline' | 'ghost';
+    block?: boolean;
+    loading?: boolean;
+    asChild?: boolean;
+}
+declare function Button({ variant, block, loading, asChild, className, children, disabled, ...rest }: ButtonProps): react_jsx_runtime.JSX.Element;
+interface SpinnerProps {
+    asChild?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+declare function Spinner({ asChild, className, children }?: SpinnerProps): react_jsx_runtime.JSX.Element;
+interface ProductPlaceholderProps {
+    asChild?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+declare function ProductPlaceholder({ asChild, className, children }?: ProductPlaceholderProps): react_jsx_runtime.JSX.Element;
+interface FieldProps extends InputHTMLAttributes<HTMLInputElement> {
+    label: string;
+    error?: string;
+    optionalLabel?: string;
+    asChild?: boolean;
+}
+declare function Field({ label, id, className, error, required, optionalLabel, asChild, children, ...rest }: FieldProps): react_jsx_runtime.JSX.Element;
+interface SectionTitleProps {
+    children: ReactNode;
+    asChild?: boolean;
+    className?: string;
+}
+declare function SectionTitle({ children, asChild, className }: SectionTitleProps): react_jsx_runtime.JSX.Element;
+interface ErrorBannerProps {
+    message: string;
+    asChild?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+declare function ErrorBanner({ message, asChild, children, className }: ErrorBannerProps): react_jsx_runtime.JSX.Element;
+
+interface RenderEmptyCartProps {
+    continueShoppingUrl?: string;
+}
+interface SazitoCheckoutPageProps {
+    credentials?: CheckoutCredentials;
+    config?: CheckoutConfig;
+    paymentReturnParams?: Record<string, string>;
+    className?: string;
+    renderNextButton?: (props: RenderButtonProps) => React.ReactNode;
+    renderBackButton?: (props: RenderButtonProps) => React.ReactNode;
+    renderEmptyCart?: (props: RenderEmptyCartProps) => React.ReactNode;
+}
+declare function SazitoCheckoutPage({ credentials, config, paymentReturnParams, className, renderNextButton, renderBackButton, renderEmptyCart, }: SazitoCheckoutPageProps): react_jsx_runtime.JSX.Element;
+
+interface CheckoutProviderProps {
+    /** Override the SazitoProvider client for this checkout instance only. */
+    client?: unknown;
+    credentials?: CheckoutCredentials;
+    config?: CheckoutConfig;
+    autoStart?: boolean;
+    children: ReactNode;
+}
+declare function CheckoutProvider({ client: clientProp, credentials, config, autoStart, children }: CheckoutProviderProps): react_jsx_runtime.JSX.Element;
+
+interface UseCheckout {
+    state: CheckoutState;
+    actions: CheckoutActions;
+    /** Localized UI strings. */
+    t: Strings;
+    /** Format an amount with the currency label for the active locale. */
+    money(value: number): string;
+    /** Like `money`, but renders 0 as "Free". */
+    price(value: number): string;
+    summary: CheckoutSummary;
+    digitalItems: InvoiceItem[];
+}
+declare function useCheckout(): UseCheckout;
+
+interface SazitoProviderProps {
+    client: unknown;
+    children: ReactNode;
+}
+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 };