@classytic/commerce-sdk

Modular API client and React hooks for the Classytic commerce platform.

Installation

npm install @classytic/commerce-sdk

Requirements

• React 19+
• @tanstack/react-query 5+
• Optional: Next.js 15+ for app/router usage

Quick Start

import { initCommerceSDK } from '@classytic/commerce-sdk';

// Initialize once at app startup
initCommerceSDK({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });

Modules

Import what you need from domain-specific subpath exports:

// Catalog (products, categories, reviews, size guides)
import { productApi, useProducts, useProductDetail } from '@classytic/commerce-sdk/catalog';

// Sales (orders, customers, cart, POS, loyalty)
import { orderApi, useOrders, useCart, usePosProducts } from '@classytic/commerce-sdk/sales';

// Inventory (stock, purchases, transfers, warehouse, Flow WMS)
import { purchaseApi, useTransfers, useMovements } from '@classytic/commerce-sdk/inventory';

// Platform (branches, users, config, permissions, promo engine)
import { branchApi, useBranches, usePlatformConfig } from '@classytic/commerce-sdk/platform';

// Accounting (chart of accounts, journal entries, reports, budgets)
import { useAccounts, useJournalEntries, useTrialBalance } from '@classytic/commerce-sdk/accounting';

// Auth / User queries
import { authApi, UserRole, verifyManagerAuth } from '@classytic/commerce-sdk/auth';

// Finance, Logistics, Content, Payments, Analytics, Notifications
import { useFinanceSummary } from '@classytic/commerce-sdk/finance';
import { useDeliveryCharge } from '@classytic/commerce-sdk/logistics';
import { mediaApi, useCMSPage } from '@classytic/commerce-sdk/content';
import { usePaymentActions } from '@classytic/commerce-sdk/payments';
import { useAnalyticsDashboard } from '@classytic/commerce-sdk/analytics';
import { useNotifications, useUnreadCount } from '@classytic/commerce-sdk/notifications';

Module Reference

Catalog

Products, categories, reviews, size guides.

import type { Product, Category, SizeGuide } from '@classytic/commerce-sdk/catalog';

| Hook | Purpose | |------|---------| | useProducts(params) | Paginated product list | | useProductDetail(id) | Single product | | useProductActions() | Create, update, delete | | useCategoryTree() | Nested category tree | | useReviews(productId) | Product reviews |

Sales

Orders, customers, cart, POS, loyalty.

import type { Order, Customer, PosProduct, LoyaltyMember } from '@classytic/commerce-sdk/sales';

| Hook | Purpose | |------|---------| | useOrders(params) | Paginated order list | | useOrderDetail(id) | Single order with shipping | | useCart() | Cart CRUD | | useGuestCheckout() | Unauthenticated checkout | | usePosProducts(token, params) | POS product search with stock | | useCustomers(params) | Customer list | | useLoyaltyMember(token, id) | Loyalty member lookup |

Order types include: promoApplied (promo discounts), membershipApplied (loyalty tier/points), full shipping with charges, cashCollection, pickup, and providerOrderId.

Typed errors: InsufficientStockError, FulfillmentOverCoverageError. Use <Class>.fromUnknown(err) in onError to extract structured details (orderLineId, requested, coverageRemaining, etc.) for tailored toasts.

Inventory

Stock, purchases, transfers, requests, adjustments, suppliers, and full WMS.

import type {
  Purchase, Transfer, StockRequest, StockMovement,
  FlowOperationType, FlowMoveStatus,
  WarehouseNode, WarehouseLocation,
  ReplenishmentRule, ProcurementOrder, StockLot,
} from '@classytic/commerce-sdk/inventory';

| Hook | Purpose | |------|---------| | usePurchases(token) | Purchase invoices | | useTransfers(token) | Inter-branch challans | | useStockRequests(token) | Sub-branch stock requests | | useMovements(token, params) | Stock movement audit trail | | useInventory(token, params) | Stock levels by product | | useWarehouses(token) | Warehouse nodes | | useLocations(token, nodeId) | Locations within a node | | useAudits(token) | Physical count sessions | | useReplenishmentRules(token) | Auto-reorder rules (Standard+) | | useProcurementOrders(token) | Flow procurement (Standard+) | | useLots(token) | Lot/serial tracking (Standard+) | | useCostLayers(token) | FIFO/LIFO cost layers (Standard+) | | useStockHealth(token) | Stock health metrics (Enterprise) | | useLotTrace(token, id) | Full traceability (Enterprise) |

Move statuses (from @classytic/flow): draft → planned → waiting → ready → partially_done → done | cancelled

Operation types: receipt, transfer, shipment, return, adjustment, count

Accounting

Double-entry bookkeeping, journal entries, reports, budgets, day-close.

import type {
  Account, JournalEntry, FiscalPeriod, Budget,
  TrialBalanceReport, BalanceSheetReport, IncomeStatementReport,
} from '@classytic/commerce-sdk/accounting';

| Hook | Purpose | |------|---------| | useAccounts() | Chart of accounts | | useAccountTypes() | Static account type lookup | | useJournalEntries(params) | Journal entry list | | useJournalEntryActions() | Create, post, reverse, duplicate | | useFiscalPeriods() | Fiscal period management | | usePostingStatus() | Today/yesterday posting status | | useCloseDay() | Close a day (create journal entries) | | useBackfill() | Recover missed days | | useTrialBalance(params) | Trial balance report | | useBalanceSheet(params) | Balance sheet report | | useIncomeStatement(params) | Income statement report | | useGeneralLedger(params) | General ledger by account | | useCashFlow(params) | Cash flow statement | | useBudgets(params) | Budget list with approval workflow | | useBudgetVsActual(params) | Budget vs actual variance report |

Platform

Branches, users, platform config, promo engine, permissions.

import type { Branch, PlatformConfig, MembershipConfig } from '@classytic/commerce-sdk/platform';

| Hook | Purpose | |------|---------| | useBranches() | Branch list | | usePlatformConfig() | Platform configuration | | useMembershipConfig() | Membership/loyalty config | | usePaymentMethods() | Enabled payment methods | | useDeliveryZones() | Delivery zone pricing | | useFeatures() | Feature tier gating |

Logistics

Delivery charge calculation, shipment management, provider tracking.

import type { DeliveryOption, TrackingResult, ShipmentStatus } from '@classytic/commerce-sdk/logistics';

Content

Media library and CMS pages.

import type { Media, CMSPage, HomePageContent } from '@classytic/commerce-sdk/content';

Notifications

In-app notifications with SSE real-time updates.

import type { InAppNotification } from '@classytic/commerce-sdk/notifications';

| Hook | Purpose | |------|---------| | useNotifications(params) | Paginated notification list | | useUnreadCount() | Unread notification count | | useNotificationActions() | Mark read, mark all read |

Usage Patterns

Server Components / API Routes

import { productApi } from '@classytic/commerce-sdk/catalog';

const products = await productApi.getAll({ params: { page: 1 } });
const product = await productApi.getBySlug({ slug: 'my-product' });

Client Components (React Query hooks)

import { useProducts, useProductActions } from '@classytic/commerce-sdk/catalog';

function ProductList() {
  // Token auto-injected via configureSDK({ getToken })
  const { items, isLoading } = useProducts({ page: 1 });
  const { create, update, remove } = useProductActions();
}

Guest Checkout

import { useGuestCheckout } from '@classytic/commerce-sdk/sales';

function GuestCheckoutButton({ cartItems }) {
  const { guestCheckout, isCheckingOut } = useGuestCheckout();

  const handleCheckout = async () => {
    const order = await guestCheckout({
      items: cartItems.map(item => ({
        productId: item.productId,
        variantSku: item.variantSku,
        quantity: item.quantity,
      })),
      guest: { name: 'John Doe', phone: '01712345678' },
      deliveryAddress: { recipientName: 'John', addressLine1: '...', areaId: 1 },
      delivery: { method: 'standard', price: 80 },
      paymentData: { type: 'bkash', reference: 'TRX123' },
      idempotencyKey: `guest_01712345678_${Date.now()}`,
    });
  };
}

Core Utilities

import { handleApiRequest, BaseApi } from '@classytic/commerce-sdk/core';

// Custom API calls (token auto-injected from configureSDK)
const data = await handleApiRequest('POST', '/api/v1/custom', { body: { ... } });

Types

All types are co-located with their modules:

import type { Product, Category } from '@classytic/commerce-sdk/catalog';
import type { Order, Customer, PromoApplied } from '@classytic/commerce-sdk/sales';
import type { StockEntry, Transfer, FlowMoveStatus } from '@classytic/commerce-sdk/inventory';
import type { Account, JournalEntry, Budget } from '@classytic/commerce-sdk/accounting';
import type { User, UserRoleType } from '@classytic/commerce-sdk/auth';

License

Proprietary - see LICENSE