@classytic/commerce-sdk

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

Installation

npm install @classytic/commerce-sdk

Requirements

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

Quick Start

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

// Initialize once at app startup
initCommerceSDK({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  // Optional: static headers like API key
  headers: { 'x-api-key': process.env.NEXT_PUBLIC_API_KEY! }
});

Modules

Import what you need from domain-specific modules:

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

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

// Inventory (stock, purchases, transfers, suppliers)
import { stockApi, useInventory, useTransfers } from '@classytic/commerce-sdk/inventory';

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

// Auth (login, register, password reset)
import { loginApi, UserRole, verifyManagerAuth } from '@classytic/commerce-sdk/auth';

// Finance, Logistics, Content, Payments, Analytics
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';

Usage Patterns

Server Components / API Routes (public routes)

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

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

Server Components / API Routes (authenticated)

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

export async function GET() {
  const session = await auth();
  const token = session?.token;

  const products = await productApi.getAll({
    token,
    params: { page: 1 }
  });

  return Response.json(products);
}

Client Components (React Query hooks)

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

function ProductList({ token }) {
  const { items, isLoading } = useProducts(token, { page: 1 });
  const { create, update, remove } = useProductActions(token);

  // ...
}

Core Utilities

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

// Make custom API calls
const data = await handleApiRequest('POST', '/api/v1/custom', {
  token,
  body: { ... }
});

Authentication Guidance

Recommended pattern: keep SDK config static and pass the user token per request.

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

initCommerceSDK({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  headers: { 'x-api-key': process.env.NEXT_PUBLIC_API_KEY! }
});

// Later, per request
await productApi.getAll({ token, params: { page: 1 } });

Optional: you can set getToken in config for client-only apps or single-session environments, but avoid it in SSR unless you know it reads per-request state.

Server Request Scoping (optional)

If you use SSR with concurrent requests and want per-request config safely:

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

return runWithSDKConfig(
  { baseUrl: process.env.NEXT_PUBLIC_API_URL!, headers: { 'x-api-key': '...' } },
  async () => productApi.getAll({ token, params: { page: 1 } })
);

Types

All types are co-located with their modules:

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

Local testing:

    "@classytic/commerce-sdk": "file:D:/projects/ecom/commerce-bd-sdk/dist"

License

Proprietary - see LICENSE