@sazito/client-sdk 1.2.2 → 1.2.3

package/README.md

@@ -2,6 +2,8 @@
 
 Official JavaScript/TypeScript SDK for Sazito storefronts.
 
+Read the full developer documentation at [developers.sazito.com](https://developers.sazito.com).
+
 This SDK is built for application developers who want a typed, framework-agnostic client with:
 - automatic request/response key transformation
 - unified response objects (`{ data, error }`)
@@ -56,6 +58,54 @@ if (res.error) {
 }
 ```
 
+## Checkout component
+
+For a ready-made React/Next.js checkout UI, install the companion package:
+
+```bash
+pnpm add @sazito/client-sdk @sazito/checkout
+```
+
+Create one SDK client, provide it to the checkout, and import the checkout
+stylesheet once:
+
+```tsx
+'use client';
+
+import '@sazito/checkout/styles.css';
+import { createSazitoClient } from '@sazito/client-sdk';
+import { SazitoCheckoutPage, SazitoProvider } from '@sazito/checkout/next';
+
+const sazito = createSazitoClient({ domain: 'mystore.sazito.com' });
+
+export default function CheckoutPage() {
+  return (
+    <SazitoProvider client={sazito}>
+      <SazitoCheckoutPage
+        credentials={{ cart: { identifier: 'cart-identifier' } }}
+        config={{
+          locale: 'fa',
+          continueShoppingUrl: '/',
+          theme: {
+            accent: '#4f46e5',
+            accentForeground: '#ffffff',
+            radius: 16
+          }
+        }}
+      />
+    </SazitoProvider>
+  );
+}
+```
+
+The component provides a typed, RTL-first flow for `cart → shipping → payment → result`,
+including cart editing, address and shipping-rate selection, discounts, payment
+gateway redirects, and pending-payment polling. It reuses the credentials stored
+by the SDK client, so credentials created through `sazito.cart` and
+`sazito.invoices` can be used by the component. For theming, custom buttons,
+analytics, payment returns, and a fully custom layout, see the
+[checkout guide](https://developers.sazito.com/docs/guides/checkout).
+
 ## Core Response Model
 
 All SDK methods return a `SazitoResponse<T>`:
@@ -198,6 +248,8 @@ The client instance exposes:
 - `entityRoutes`
 - `menu`
 - `general`
+- `dynamicForms`
+- `regions`
 
 ### Methods by Module
 
@@ -205,14 +257,14 @@ The client instance exposes:
 |---|---|
 | `products` | `get`, `list`, `search` |
 | `categories` | `get`, `list` |
-| `cart` | `get`, `create`, `addItem`, `updateItem`, `removeItem`, `clearCart` |
+| `cart` | `get`, `create`, `addItem`, `addItemWithAttributes`, `updateItem`, `updateItemWithAttributes`, `removeItem`, `clearCart` |
 | `orders` | `list`, `get` |
-| `invoices` | `get`, `create`, `refresh`, `addShippingAddress`, `addDiscountCode`, `assignShippingMethod`, `addDetails`, `getApplicableShippingMethods`, `clearInvoice` |
-| `shipping` | `createAddress`, `updateAddress`, `getAddress`, `getMethods`, `clearAddress` |
-| `payments` | `getMethods`, `create`, `initialize`, `processStep`, `clearPayment` |
+| `invoices` | `get`, `create`, `refresh`, `addShippingAddress`, `addDiscountCode`, `assignShippingMethod`, `addDetails`, `addForm`, `addCredit`, `removeCredit`, `toggleCredit`, `getApplicableShippingMethods`, `clearInvoice` |
+| `shipping` | `createAddress`, `updateAddress` (legacy), `listAddresses`, `getAddress`, `getMethods`, `clearAddress` |
+| `payments` | `getMethods`, `create`, `initialize`, `verify`, `processStep`, `processStepForm`, `pollUntilSettled`, `clearPayment` |
 | `users` | `login`, `requestMobileOTP`, `verifyMobileOTP`, `requestEmailLogin`, `register`, `getCurrentUser`, `updateProfile`, `requestMobilePhoneUpdate`, `verifyMobilePhoneUpdate`, `forgotPassword`, `revivePassword`, `mergeUser` |
-| `search` | `search` |
-| `feedbacks` | `list`, `create`, `get` |
+| `search` | `query` |
+| `feedbacks` | `getSeed`, `createOrderRating`, `submitProductReview`, `getProductStatistics`, `getProductReviews`, `uploadReviewImages`, `list`, `create`, `get` |
 | `wallet` | `getBalance`, `applyCredit`, `removeCredit`, `listTransactions` |
 | `cms` | `getPage`, `listPages`, `getBlogPost`, `listBlogPosts`, `listAll` |
 | `images` | `upload`, `delete` |
@@ -221,6 +273,8 @@ The client instance exposes:
 | `entityRoutes` | `resolve` |
 | `menu` | `getHeaderMenu` |
 | `general` | `getInfo`, `getFeatures`, `getCheckoutConfig`, `getWalletConfig`, `getTajrobeConfig` |
+| `dynamicForms` | `getForm`, `uploadProductFormFile` |
+| `regions` | `list` |
 
 ## Usage Examples
 

package/dist/index.d.ts

@@ -68,6 +68,7 @@ interface RequestOptions {
     cache?: boolean;
     headers?: Record<string, string>;
     signal?: AbortSignal;
+    skipTransform?: boolean;
 }
 /**
  * Cookie options for token storage
@@ -96,9 +97,19 @@ interface Image {
 /**
  * Product attribute (e.g., color, size)
  */
+/**
+ * Rich attribute value for typed fields like color swatches.
+ * `value` is the human-readable label; `extra` carries the payload
+ * (e.g. a hex color when `fieldType` is `'color'`).
+ */
+interface ProductAttributeValueObject {
+    value: string;
+    extra?: string;
+    fieldType?: string;
+}
 interface ProductAttribute {
     name: string;
-    value: string;
+    value: string | ProductAttributeValueObject;
 }
 /**
  * Normalized product snapshot embedded in checkout entities
@@ -247,7 +258,6 @@ interface Cart {
     deleteCoupon?: boolean;
 }
 interface CartCredentials {
-    id: number;
     identifier: string;
 }
 interface AddToCartInput {
@@ -330,6 +340,7 @@ interface ShippingAddress {
     city: ShippingAddressCity;
     address: string;
     postalCode?: string;
+    description?: string;
     latitude?: number;
     longitude?: number;
     userSetCoordinatesBefore?: boolean;
@@ -347,6 +358,7 @@ interface InvoiceShippingAddress {
     region?: InvoiceShippingAddressRegion;
     address: string;
     postalCode?: string;
+    description?: string;
     latitude?: number;
     longitude?: number;
     userSetCoordinatesBefore?: boolean;
@@ -396,11 +408,9 @@ interface InvoiceCredentials {
     identifier: string;
 }
 interface CreateInvoiceInput {
-    cartId: number;
     cartIdentifier: string;
 }
 interface RefreshInvoiceInput {
-    cartId: number;
     cartIdentifier: string;
     identifier: string;
 }
@@ -417,6 +427,7 @@ interface ShippingRate {
     id: number;
     name: string;
     price: number;
+    description?: string;
     icon?: string;
     color?: string;
     type?: string;
@@ -440,6 +451,7 @@ interface ShippingAddressInput {
     cityId?: number;
     address: string;
     postalCode?: string;
+    description?: string;
     latitude?: number;
     longitude?: number;
     showMap?: boolean;
@@ -492,6 +504,16 @@ type PaymentStatus = 'PENDING' | 'PROCESSING' | 'PAID' | 'FAILED' | 'CANCELLED'
 interface PaymentMethod {
     id: number;
     code: PaymentGateway;
+    /** Backend display title (English). */
+    title: string;
+    /** Backend display title (Persian). */
+    titleFa: string;
+    /** Backend description; often null. */
+    description: string | null;
+    /** Backend payment sub-type id; null when not provided. */
+    paymentSubType: number | null;
+    /** Display order from backend. */
+    order: number;
     isDefault: boolean;
 }
 interface Payment {
@@ -708,6 +730,73 @@ interface MenuNode {
     children: MenuNode[];
 }
 
+/**
+ * Credentials Manager for guest users
+ * Manages cart, invoice, shipping, and payment credentials.
+ * Accepts an optional StorageAdapter — defaults to localStorage in browsers,
+ * in-memory otherwise (SSR / server actions).
+ */
+
+interface StorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare class MemoryStorage implements StorageAdapter {
+    private data;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+declare class CredentialsManager {
+    private readonly CART_KEY;
+    private readonly INVOICE_KEY;
+    private readonly SHIPPING_KEY;
+    private readonly PAYMENT_KEY;
+    private readonly DISCOUNT_KEY;
+    private storage;
+    constructor(storage?: StorageAdapter);
+    /**
+     * Cart Credentials
+     */
+    getCartCredentials(): CartCredentials | null;
+    setCartCredentials(credentials: CartCredentials & {
+        id?: number;
+    }): void;
+    clearCartCredentials(): void;
+    /**
+     * Invoice Credentials
+     */
+    getInvoiceCredentials(): InvoiceCredentials | null;
+    setInvoiceCredentials(credentials: InvoiceCredentials): void;
+    clearInvoiceCredentials(): void;
+    /**
+     * Shipping Address Credentials
+     */
+    getShippingCredentials(): ShippingAddressCredentials | null;
+    setShippingCredentials(credentials: ShippingAddressCredentials): void;
+    clearShippingCredentials(): void;
+    /**
+     * Payment Credentials
+     */
+    getPaymentCredentials(): PaymentCredentials | null;
+    setPaymentCredentials(credentials: PaymentCredentials): void;
+    clearPaymentCredentials(): void;
+    /**
+     * Discount Code
+     */
+    getDiscountCode(): string | null;
+    setDiscountCode(code: string): void;
+    clearDiscountCode(): void;
+    /**
+     * Clear all credentials
+     */
+    clearAll(): void;
+    private getItem;
+    private setItem;
+    private removeItem;
+}
+
 /**
  * Token storage for auth token persistence
  * Primary storage: localStorage (user_id_token), with cookie fallback.
@@ -892,65 +981,6 @@ declare class CategoriesAPI {
     list(filters?: CategoryFilters, options?: RequestOptions): Promise<SazitoResponse<CategoryListResponse>>;
 }
 
-/**
- * Credentials Manager for guest users
- * Manages cart, invoice, shipping, and payment credentials in localStorage
- */
-
-declare class CredentialsManager {
-    private readonly CART_KEY;
-    private readonly INVOICE_KEY;
-    private readonly SHIPPING_KEY;
-    private readonly PAYMENT_KEY;
-    private readonly DISCOUNT_KEY;
-    /**
-     * Cart Credentials
-     */
-    getCartCredentials(): CartCredentials | null;
-    setCartCredentials(credentials: CartCredentials): void;
-    clearCartCredentials(): void;
-    /**
-     * Invoice Credentials
-     */
-    getInvoiceCredentials(): InvoiceCredentials | null;
-    setInvoiceCredentials(credentials: InvoiceCredentials): void;
-    clearInvoiceCredentials(): void;
-    /**
-     * Shipping Address Credentials
-     */
-    getShippingCredentials(): ShippingAddressCredentials | null;
-    setShippingCredentials(credentials: ShippingAddressCredentials): void;
-    clearShippingCredentials(): void;
-    /**
-     * Payment Credentials
-     */
-    getPaymentCredentials(): PaymentCredentials | null;
-    setPaymentCredentials(credentials: PaymentCredentials): void;
-    clearPaymentCredentials(): void;
-    /**
-     * Discount Code
-     */
-    getDiscountCode(): string | null;
-    setDiscountCode(code: string): void;
-    clearDiscountCode(): void;
-    /**
-     * Clear all credentials
-     */
-    clearAll(): void;
-    /**
-     * Get item from localStorage
-     */
-    private getItem;
-    /**
-     * Set item in localStorage
-     */
-    private setItem;
-    /**
-     * Remove item from localStorage
-     */
-    private removeItem;
-}
-
 /**
  * Cart API
  * Supports both authenticated and guest users via credentials
@@ -1100,14 +1130,25 @@ declare class ShippingAPI {
     private credentials;
     constructor(http: HttpClient, credentials: CredentialsManager);
     private sanitizeAddressInput;
+    private unwrapAddressPayload;
+    private extractAddressList;
     /**
      * Create shipping address
      */
     createAddress(address: ShippingAddressInput, options?: RequestOptions): Promise<SazitoResponse<ShippingAddress>>;
     /**
-     * Update shipping address
+     * Update the address referenced by the currently stored credentials.
+     * @deprecated Do not use during checkout. Existing invoices can reference
+     * this row, so mutation can rewrite address data shown on previous orders.
+     * Create a new address snapshot with createAddress instead.
      */
     updateAddress(address: ShippingAddressInput, options?: RequestOptions): Promise<SazitoResponse<ShippingAddress>>;
+    /**
+     * Get the authenticated user's shipping addresses, newest first.
+     * This endpoint is intentionally not cached: checkout must see an address
+     * created by the user's most recent order immediately.
+     */
+    listAddresses(options?: RequestOptions): Promise<SazitoResponse<ShippingAddress[]>>;
     /**
      * Get shipping address
      */
@@ -1140,13 +1181,30 @@ declare class PaymentsAPI {
      */
     create(paymentTypeId: number, options?: RequestOptions): Promise<SazitoResponse<Payment>>;
     /**
-     * Initialize payment (get payment action)
+     * Initialize payment: start the payment step before redirecting the user to
+     * the gateway. Returns the next {@link PaymentAction} (typically REDIRECT or
+     * POST for hosted gateways, or showOrder for zero-amount/instant payments).
      */
     initialize(options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
     /**
-     * Process payment step (for card-to-card or multi-step payments)
+     * Verify payment after the user returns from the gateway. Forwards the
+     * gateway callback parameters (e.g. `tatoken`, `trackingData`, `isFailed`,
+     * `code`) to the same payment-step endpoint and returns the settled
+     * {@link PaymentAction} (showOrder on success, FAIL/StockViolated otherwise,
+     * or pending if the gateway has not reported back yet).
+     */
+    verify(input?: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /**
+     * Process payment step (for card-to-card or multi-step payments).
+     *
+     * @deprecated Prefer {@link verify} for gateway-return verification.
      */
     processStep(input: PaymentStepInput, options?: RequestOptions): Promise<SazitoResponse<PaymentAction>>;
+    /**
+     * Shared core for the `process_payment_step` endpoint used by
+     * {@link initialize}, {@link verify} and {@link processStep}.
+     */
+    private submitPaymentStep;
     /**
      * Process payment step in form mode (non-JSON content-type).
      */
@@ -1162,7 +1220,12 @@ declare class PaymentsAPI {
     private withExactJsonHeader;
     private buildProcessStepFormData;
     private appendFormValue;
-    private normalizePayment;
+    /**
+     * Post-process a `process_payment_step` response. The exact-JSON endpoint
+     * returns an envelope `{ result: PaymentAction, error, error_code, status }`;
+     * unwrap `result`, surface envelope-level errors, and run the pinch hook.
+     */
+    private finalizeStepResponse;
     private normalizeAction;
     private callPinchAfterSuccessfulPayment;
 }
@@ -2078,7 +2141,7 @@ declare class SazitoClient {
     readonly general: GeneralAPI;
     readonly dynamicForms: DynamicFormsAPI;
     readonly regions: RegionsAPI;
-    constructor(config: SazitoConfig);
+    constructor(config: SazitoConfig, credentialsManager?: CredentialsManager);
     /**
      * Set authentication token (stored in localStorage with cookie fallback)
      */
@@ -2103,6 +2166,12 @@ declare class SazitoClient {
      * Clear all guest credentials
      */
     clearCredentials(): void;
+    /**
+     * Access the guest credential store used by checkout-related modules.
+     * Useful for integrations that receive an SDK client from the host app and
+     * need to restore cart/invoice/payment credentials on that same instance.
+     */
+    getCredentialsManager(): CredentialsManager;
     /**
      * Clear everything (auth + cache + credentials)
      */
@@ -2115,7 +2184,7 @@ declare class SazitoClient {
 /**
  * Create a new Sazito SDK client instance
  */
-declare function createSazitoClient(config: SazitoConfig): SazitoClient;
+declare function createSazitoClient(config: SazitoConfig, credentialsManager?: CredentialsManager): SazitoClient;
 
 interface ModuleContext {
     http: HttpClient;
@@ -2172,6 +2241,8 @@ interface ApiResponseEnvelope {
         result?: TransformObject;
     };
 }
+/** Convert Persian and Arabic-Indic numerals to ASCII digits. */
+declare function toEnglishDigits(input: string): string;
 /**
  * Transform object keys from snake_case to camelCase with field name beautification
  * @param obj - Object to transform
@@ -2213,5 +2284,5 @@ declare function transformAddToCartInput(variantId: number, quantity: number, fo
  */
 declare function transformCreateCartInput(input: TransformValue): TransformObject;
 
-export { CredentialsManager, HttpClient, SazitoClient, TokenStorage, createBookingAPI as booking, createCartAPI as cart, createCategoriesAPI as categories, createCMSAPI as cms, createBookingAPI, createCMSAPI, createCartAPI, createCategoriesAPI, createDynamicFormsAPI, createEntityRoutesAPI, createFeedbacksAPI, createGeneralAPI, createImagesAPI, createInvoicesAPI, createMenuAPI, createOrdersAPI, createPaymentsAPI, createProductsAPI, createRegionsAPI, createSazitoClient, createSearchAPI, createShippingAPI, createUsersAPI, createVisitsAPI, createWalletAPI, createDynamicFormsAPI as dynamicForms, createEntityRoutesAPI as entityRoutes, createFeedbacksAPI as feedbacks, createGeneralAPI as general, createImagesAPI as images, createInvoicesAPI as invoices, createMenuAPI as menu, createOrdersAPI as orders, createPaymentsAPI as payments, createProductsAPI as products, createRegionsAPI as regions, createSearchAPI as search, createShippingAPI as shipping, transformAddToCartInput, transformApiResponse, transformCartResponse, transformCreateCartInput, transformInvoiceResponse, transformProductListResponse, transformRequestKeys, transformResponseKeys, transformShippingAddressInput, createUsersAPI as users, createVisitsAPI as visits, createWalletAPI as wallet };
-export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutProductSnapshot, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User };
+export { CredentialsManager, HttpClient, MemoryStorage, SazitoClient, TokenStorage, createBookingAPI as booking, createCartAPI as cart, createCategoriesAPI as categories, createCMSAPI as cms, createBookingAPI, createCMSAPI, createCartAPI, createCategoriesAPI, createDynamicFormsAPI, createEntityRoutesAPI, createFeedbacksAPI, createGeneralAPI, createImagesAPI, createInvoicesAPI, createMenuAPI, createOrdersAPI, createPaymentsAPI, createProductsAPI, createRegionsAPI, createSazitoClient, createSearchAPI, createShippingAPI, createUsersAPI, createVisitsAPI, createWalletAPI, createDynamicFormsAPI as dynamicForms, createEntityRoutesAPI as entityRoutes, createFeedbacksAPI as feedbacks, createGeneralAPI as general, createImagesAPI as images, createInvoicesAPI as invoices, createMenuAPI as menu, createOrdersAPI as orders, createPaymentsAPI as payments, createProductsAPI as products, createRegionsAPI as regions, createSearchAPI as search, createShippingAPI as shipping, toEnglishDigits, transformAddToCartInput, transformApiResponse, transformCartResponse, transformCreateCartInput, transformInvoiceResponse, transformProductListResponse, transformRequestKeys, transformResponseKeys, transformShippingAddressInput, createUsersAPI as users, createVisitsAPI as visits, createWalletAPI as wallet };
+export type { AddToCartInput, ApplicableShippingMethods, BlogPage, BlogPageEntityRoute, CMSPageEntityRoute, CMSPageType, CacheConfig, Cart, CartCredentials, CartProduct, CheckoutProductSnapshot, City$1 as City, CmsPage, CookieOptions, CreateCartInput, CreateInvoiceInput, CreatePaymentInput, EntityRoute, EntityRouteResponse, EntityType, FormAttributeValue, Image, Invoice, InvoiceCredentials, InvoiceItem, InvoiceItemFormAttributes, InvoiceShippingAddress, InvoiceShippingAddressRegion, ItemShippingRate, JsonArray, JsonObject, JsonPrimitive, JsonValue, MenuItem, MenuNode, MenuTree, Order, OrderFilters, OrdersListResponse, PaginatedResponse, Payment, PaymentAction, PaymentCredentials, PaymentGateway, PaymentMethod, PaymentStatus, PaymentStepFormFields, PaymentStepFormValue, PaymentStepInput, Product, ProductAttribute, ProductAttributeValueObject, ProductCategory, ProductCategoryEntityRoute, ProductEntityRoute, ProductFilters, ProductSort, ProductVariant, RefreshInvoiceInput, Region$1 as Region, RequestOptions, RetryConfig, SazitoConfig, SazitoResponse, SchedulerBookingAttributes, SearchFilters, SearchResponse, ShippingAddress, ShippingAddressCity, ShippingAddressCredentials, ShippingAddressInput, ShippingAddressRegion, ShippingAssignment, ShippingItem, ShippingMethod, ShippingRate, StorageAdapter, Tag, UnknownEntityRoute, UploadedFormFileAttribute, User };