@sazito/client-sdk 1.2.1 → 1.2.3

package/README.md

@@ -2,12 +2,14 @@
 
 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 }`)
 - configurable retry/timeout/cache behavior
 - guest checkout credential handling
-- modular API access for products, checkout, user, CMS, analytics, and more
+- modular API access for products, cart, invoices, shipping, payments, user, CMS, analytics, and more
 
 ## Package
 
@@ -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
 
@@ -249,11 +303,12 @@ const search = await sazito.search.query('shoes', {
 });
 ```
 
-### Guest Checkout Flow
+### Checkout Modules Flow
 
 ```ts
-// 1) Add product to cart (creates guest cart automatically if needed)
-await sazito.cart.addItem(12345, 2);
+// 1) Add product to cart
+const cartRes = await sazito.cart.addItemWithAttributes(12345, 2);
+if (cartRes.error) throw new Error(cartRes.error.message);
 
 // 2) Create invoice from cart
 const invoiceRes = await sazito.invoices.create();
@@ -272,29 +327,31 @@ const addrRes = await sazito.shipping.createAddress({
 if (addrRes.error) throw new Error(addrRes.error.message);
 
 // 4) Attach shipping address to invoice
-await sazito.invoices.addShippingAddress(addrRes.data.id, addrRes.data.identifier);
+const attachRes = await sazito.invoices.addShippingAddress(addrRes.data.id, addrRes.data.identifier);
+if (attachRes.error) throw new Error(attachRes.error.message);
 
 // 5) Fetch methods and assign shipping
 const methodsRes = await sazito.invoices.getApplicableShippingMethods();
-if (methodsRes.data?.length) {
-  const firstRate = methodsRes.data[0]?.rates?.[0];
-  const currentInvoice = await sazito.invoices.get();
-
-  if (firstRate && currentInvoice.data) {
-    await sazito.invoices.assignShippingMethod([
-      {
-        rateId: firstRate.id,
-        invoiceItemIds: currentInvoice.data.items.map(i => i.id)
-      }
-    ]);
-  }
+if (methodsRes.error) throw new Error(methodsRes.error.message);
+if (methodsRes.data?.itemsShippingRate?.length) {
+  const assignments = methodsRes.data.itemsShippingRate.map((entry) => ({
+    rateId: entry.shippingRate.id,
+    invoiceItemIds: [entry.invoiceItemId],
+  }));
+
+  const assignRes = await sazito.invoices.assignShippingMethod(assignments);
+  if (assignRes.error) throw new Error(assignRes.error.message);
 }
 
 // 6) Payment
 const paymentMethods = await sazito.payments.getMethods();
+if (paymentMethods.error) throw new Error(paymentMethods.error.message);
 if (paymentMethods.data?.length) {
-  await sazito.payments.create(paymentMethods.data[0].id);
+  const paymentCreateRes = await sazito.payments.create(paymentMethods.data[0].id);
+  if (paymentCreateRes.error) throw new Error(paymentCreateRes.error.message);
+
   const action = await sazito.payments.initialize();
+  if (action.error) throw new Error(action.error.message);
   console.log(action.data);
 }
 ```
@@ -357,7 +414,7 @@ Notes:
 Run the local visual playground:
 
 ```bash
-yarn visual:apis
+pnpm visual:apis
 ```
 
 Then open:
@@ -374,11 +431,11 @@ Files:
 Project scripts:
 
 ```bash
-yarn build          # Build dist outputs
-yarn dev            # Rollup watch mode
-yarn typecheck      # TypeScript check (no emit)
-yarn lint           # ESLint on src/
-yarn validate       # typecheck + lint
+pnpm build          # Build dist outputs
+pnpm dev            # Rollup watch mode
+pnpm typecheck      # TypeScript check (no emit)
+pnpm lint           # ESLint on src/
+pnpm validate       # typecheck + lint
 ```
 
 ## Fumadocs Documentation Site
@@ -388,15 +445,15 @@ SDK docs are implemented as a separate Fumadocs app in `docs/`.
 Run docs locally from the repository root:
 
 ```bash
-yarn docs:install
-yarn docs:dev
+pnpm docs:install
+pnpm docs:dev
 ```
 
 Build/start docs:
 
 ```bash
-yarn docs:build
-yarn docs:start
+pnpm docs:build
+pnpm docs:start
 ```
 
 This docs app is tracked in GitHub, but it is not included in the published npm package.