@sazito/checkout 0.1.0

package/dist/core/index.d.cts

@@ -0,0 +1,482 @@
+import { Cart, Invoice, ApplicableShippingMethods, InvoiceItem, ShippingRate, PaymentMethod, Order, SazitoClient, CredentialsManager, SazitoResponse, PaymentGateway, ShippingAssignment } from '@sazito/client-sdk';
+export { ApplicableShippingMethods, Cart, CartProduct, Invoice, InvoiceItem, InvoiceShippingAddress, ItemShippingRate, Order, PaymentAction, PaymentGateway, PaymentMethod, ShippingAddress, ShippingAddressInput, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate } 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;
+}
+/**
+ * Side-effects the pure engine asks the host to perform. The default browser
+ * executor handles all of these; a host may override (SSR / native / tests).
+ */
+type CheckoutEffect = {
+    type: 'redirect';
+    url: string;
+} | {
+    type: 'post-form';
+    url: string;
+    fields: Record<string, string>;
+} | {
+    type: 'emit';
+    event: CheckoutEvent;
+};
+type CheckoutEffectExecutor = (effect: CheckoutEffect) => void;
+/** Options for constructing the engine. */
+interface CheckoutEngineOptions {
+    client?: unknown;
+    credentials?: CheckoutCredentials;
+    config?: CheckoutConfig;
+}
+/** 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;
+}
+
+interface CheckoutEngine {
+    getState(): CheckoutState;
+    subscribe(listener: () => void): () => void;
+    actions: CheckoutActions;
+    setEffectExecutor(executor: CheckoutEffectExecutor): void;
+    destroy(): void;
+}
+declare function createCheckoutEngine(options: CheckoutEngineOptions): CheckoutEngine;
+
+/**
+ * Minimal zero-dependency observable store.
+ *
+ * `getState` returns the current immutable snapshot; `setState` shallow-merges
+ * a partial (or applies an updater) and notifies subscribers. Designed to plug
+ * straight into React's `useSyncExternalStore`.
+ */
+interface Store<T> {
+    getState(): T;
+    setState(partial: Partial<T> | ((prev: T) => Partial<T>)): void;
+    subscribe(listener: () => void): () => void;
+}
+declare function createStore<T extends object>(initialState: T): Store<T>;
+
+interface CheckoutSdkBinding {
+    client: SazitoClient;
+    credentials: CredentialsManager;
+    hasCart(): boolean;
+    hasInvoice(): boolean;
+}
+declare function createSdkBinding(options: CheckoutEngineOptions): CheckoutSdkBinding;
+
+/**
+ * Side-effect types + the default browser executor.
+ *
+ * The engine never touches the DOM directly; it emits effects and a host-
+ * provided executor performs them. This keeps the engine SSR-safe and testable.
+ */
+
+/**
+ * Build the default browser executor. `onEvent` (from config) receives `emit`
+ * effects so analytics adapters can subscribe.
+ */
+declare function createBrowserEffectExecutor(config?: CheckoutConfig): CheckoutEffectExecutor;
+/** A no-op executor for SSR / tests. */
+declare const noopEffectExecutor: CheckoutEffectExecutor;
+
+/**
+ * Typed event bus helpers.
+ */
+
+declare function makeEvent(name: CheckoutEventName, data?: {
+    step?: CheckoutStep;
+    value?: number;
+    metadata?: Record<string, unknown>;
+}): CheckoutEvent;
+
+/**
+ * Error taxonomy + mapping from SDK responses to typed checkout errors.
+ */
+
+type SdkError = NonNullable<SazitoResponse<unknown>['error']>;
+declare function messageForCode(code: CheckoutErrorCode, locale: CheckoutLocale): string;
+declare function fromSdkError(error: SdkError, locale: CheckoutLocale, step?: CheckoutStep): CheckoutError;
+declare function makeError(code: CheckoutErrorCode, locale: CheckoutLocale, step?: CheckoutStep): CheckoutError;
+
+/**
+ * Locale-aware number / currency formatting.
+ * Amounts are integer Toman values from the Sazito API.
+ */
+
+declare function toPersianDigits(input: string): string;
+declare function toEnglishDigits(input: string): string;
+declare function formatNumber(value: number, locale: CheckoutLocale): string;
+/**
+ * Format a percentage with up to `maxDecimals` digits, trimming trailing zeros.
+ * Keeps small fractions visible (e.g. 0.02%) where `formatNumber` would round to 0.
+ */
+declare function formatPercent(value: number, locale: CheckoutLocale, maxDecimals?: number): string;
+declare function defaultCurrencyLabel(locale: CheckoutLocale): string;
+declare function formatMoney(value: number, locale: CheckoutLocale, currencyLabel?: string): string;
+/**
+ * Normalize an Iranian phone number to the 11-digit 0XXXXXXXXXX format.
+ * Accepts: 09..., +989..., 00989..., 989..., 9... (10 digits without leading 0)
+ */
+declare function normalizeIranianPhone(raw: string): string;
+declare function isValidIranianPhone(s: string): boolean;
+declare function isValidIranianMobile(s: string): boolean;
+/** Free price shown when a rate / delivery costs nothing. */
+declare function formatPrice(value: number, locale: CheckoutLocale, currencyLabel?: string): string;
+
+/**
+ * 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;
+}
+declare function strings(locale: CheckoutLocale): Strings;
+/** Visual family of a payment method — drives the icon shown in the UI. */
+type PaymentMethodKind = 'card' | 'cod' | 'bnpl' | 'wallet' | 'gateway' | 'free';
+interface PaymentMethodInfo {
+    title: string;
+    description: string;
+    kind: PaymentMethodKind;
+}
+/** Human label for a payment gateway code. Online gateways fall back generically. */
+declare function paymentMethodLabel(code: PaymentGateway, locale: CheckoutLocale): string;
+/** Title + description + visual family for a payment gateway code. */
+declare function paymentMethodInfo(code: PaymentGateway, locale: CheckoutLocale): PaymentMethodInfo;
+
+/**
+ * Pure derivations over invoice / shipping data: shipping groups, summary
+ * lines, address form mapping and validation. No SDK calls, no side-effects.
+ */
+
+declare function emptyAddressForm(): AddressFormValues;
+declare function addressFormFromInvoice(invoice: Invoice | null): AddressFormValues;
+declare function isAddressComplete(form: AddressFormValues, needsShipping: boolean, postalCodeMandatory?: boolean, emailMandatory?: boolean): boolean;
+/** Has the form diverged from what's saved on the invoice? */
+declare function isAddressDirty(form: AddressFormValues, invoice: Invoice | null): boolean;
+/**
+ * Group invoice items into shippable bundles with their switchable rates and
+ * the currently selected rate. Digital-only invoices yield an empty list.
+ *
+ * The Sazito API returns:
+ *   groupedShippingRates  — all applicable rates per "bundle" (keyed by group ID)
+ *   itemsShippingRate     — one entry per item with its DEFAULT/current rate
+ *
+ * The default rate ID in itemsShippingRate may NOT match any rate in
+ * groupedShippingRates (different IDs for the same method type). We therefore
+ * assign items by the currently ASSIGNED rate from invoice.shippingItems first,
+ * then fall back to the default rate, and finally use positional assignment
+ * (all physical items in the single group when there is only one group).
+ */
+declare function deriveShippingGroups(invoice: Invoice | null, applicable: ApplicableShippingMethods | null): ShippingGroup[];
+/** Build the API payload from the current group selections. */
+declare function buildShippingAssignments(groups: ShippingGroup[]): ShippingAssignment[];
+/** True once every shippable group has a selected rate. */
+declare function isShippingComplete(invoice: Invoice | null, groups: ShippingGroup[]): boolean;
+/**
+ * The documented API contract has no discount "type" field — codes only show
+ * up as totals on the invoice. Classify by comparing the invoice before/after
+ * the code was applied:
+ *   - shipping got cheaper, items total unchanged → free shipping
+ *   - items total dropped by a near-integer %     → percentage
+ *   - items total dropped by anything else        → fixed amount
+ * If the backend ever sends an explicit type on the discount usage
+ * (`discount_type` / `amount_type`), trust it over the heuristics.
+ * `before` is null when the code was restored from a saved invoice; deltas
+ * then fall back to the absolute totals and free shipping is undetectable.
+ */
+declare function classifyAppliedDiscount(before: Invoice | null, after: Invoice, code: string): AppliedDiscount;
+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;
+}
+declare function selectSummary(invoice: Invoice | null): CheckoutSummary;
+/** Items that don't require shipping (digital), for display in the shipping step. */
+declare function selectDigitalItems(invoice: Invoice | null, groups: ShippingGroup[], applicable: ApplicableShippingMethods | null): InvoiceItem[];
+
+export { addressFormFromInvoice, buildShippingAssignments, classifyAppliedDiscount, createBrowserEffectExecutor, createCheckoutEngine, createSdkBinding, createStore, defaultCurrencyLabel, deriveShippingGroups, emptyAddressForm, formatMoney, formatNumber, formatPercent, formatPrice, fromSdkError, isAddressComplete, isAddressDirty, isShippingComplete, isValidIranianMobile, isValidIranianPhone, makeError, makeEvent, messageForCode, noopEffectExecutor, normalizeIranianPhone, paymentMethodInfo, paymentMethodLabel, selectDigitalItems, selectSummary, strings, toEnglishDigits, toPersianDigits };
+export type { AddressFormValues, AppliedDiscount, CheckoutActions, CheckoutCity, CheckoutConfig, CheckoutCredentials, CheckoutDirection, CheckoutEffect, CheckoutEffectExecutor, CheckoutEngine, CheckoutEngineOptions, CheckoutError, CheckoutErrorCode, CheckoutEvent, CheckoutEventName, CheckoutFlags, CheckoutLocale, CheckoutRegion, CheckoutResult, CheckoutResultStatus, CheckoutSdkBinding, CheckoutState, CheckoutStatus, CheckoutStep, CheckoutSummary, CheckoutTheme, DiscountKind, PaymentMethodInfo, PaymentMethodKind, ShippingGroup, Store, Strings, SummaryLine, SummaryLineKey };