@classytic/commerce-sdk 0.1.1 → 0.2.1

package/README.md

@@ -11,8 +11,8 @@ npm install @classytic/commerce-sdk
 ## Requirements
 
 - React 19+
-- Optional: Next.js 16+ for app/router usage
-- Optional: @tanstack/react-query 5+ for hooks
+- @tanstack/react-query 5+
+- Optional: Next.js 15+ for app/router usage
 
 ## Quick Start
 
@@ -20,127 +20,244 @@ npm install @classytic/commerce-sdk
 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! }
-});
+initCommerceSDK({ baseUrl: process.env.NEXT_PUBLIC_API_URL! });
 ```
 
 ## Modules
 
-Import what you need from domain-specific modules:
+Import what you need from domain-specific subpath exports:
 
 ```typescript
-// Catalog (products, categories, size guides)
+// Catalog (products, categories, reviews, 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';
+// Sales (orders, customers, cart, POS, loyalty)
+import { orderApi, useOrders, useCart, usePosProducts } from '@classytic/commerce-sdk/sales';
 
-// Inventory (stock, purchases, transfers, suppliers)
-import { stockApi, useInventory, useTransfers } from '@classytic/commerce-sdk/inventory';
+// Inventory (stock, purchases, transfers, warehouse, Flow WMS)
+import { purchaseApi, useTransfers, useMovements } from '@classytic/commerce-sdk/inventory';
 
-// Platform (branches, users, coupons, config)
+// Platform (branches, users, config, permissions, promo engine)
 import { branchApi, useBranches, usePlatformConfig } from '@classytic/commerce-sdk/platform';
 
-// Auth (login, register, password reset)
-import { loginApi, UserRole, verifyManagerAuth } from '@classytic/commerce-sdk/auth';
+// Accounting (chart of accounts, journal entries, reports, budgets)
+import { useAccounts, useJournalEntries, useTrialBalance } from '@classytic/commerce-sdk/accounting';
 
-// Finance, Logistics, Content, Payments, Analytics
+// 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';
 ```
 
-## Usage Patterns
+## Module Reference
 
-### Server Components / API Routes (public routes)
+### Catalog
+
+Products, categories, reviews, size guides.
 
 ```typescript
-import { productApi } from '@classytic/commerce-sdk/catalog';
+import type { Product, Category, SizeGuide } 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' });
+| 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.
+
+```typescript
+import type { Order, Customer, PosProduct, LoyaltyMember } from '@classytic/commerce-sdk/sales';
 ```
 
-### Server Components / API Routes (authenticated)
+| 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`.
+
+### Inventory
+
+Stock, purchases, transfers, requests, adjustments, suppliers, and full WMS.
 
 ```typescript
-import { productApi } from '@classytic/commerce-sdk/catalog';
-import { auth } from '@/auth';
+import type {
+  Purchase, Transfer, StockRequest, StockMovement,
+  FlowOperationType, FlowMoveStatus,
+  WarehouseNode, WarehouseLocation,
+  ReplenishmentRule, ProcurementOrder, StockLot,
+} from '@classytic/commerce-sdk/inventory';
+```
 
-export async function GET() {
-  const session = await auth();
-  const token = session?.token;
+| 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) |
 
-  const products = await productApi.getAll({
-    token,
-    params: { page: 1 }
-  });
+**Move statuses** (from @classytic/flow): `draft` → `planned` → `waiting` → `ready` → `partially_done` → `done` | `cancelled`
 
-  return Response.json(products);
-}
+**Operation types**: `receipt`, `transfer`, `shipment`, `return`, `adjustment`, `count`
+
+### Accounting
+
+Double-entry bookkeeping, journal entries, reports, budgets, day-close.
+
+```typescript
+import type {
+  Account, JournalEntry, FiscalPeriod, Budget,
+  TrialBalanceReport, BalanceSheetReport, IncomeStatementReport,
+} from '@classytic/commerce-sdk/accounting';
 ```
 
-### Client Components (React Query hooks)
+| 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.
 
 ```typescript
-import { useProducts, useProductActions } from '@classytic/commerce-sdk/catalog';
+import type { Branch, PlatformConfig, MembershipConfig } from '@classytic/commerce-sdk/platform';
+```
 
-function ProductList({ token }) {
-  const { items, isLoading } = useProducts(token, { page: 1 });
-  const { create, update, remove } = useProductActions(token);
+| 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.
+
+```typescript
+import type { DeliveryOption, TrackingResult, ShipmentStatus } from '@classytic/commerce-sdk/logistics';
 ```
 
-### Core Utilities
+### Content
+
+Media library and CMS pages.
 
 ```typescript
-import { handleApiRequest, BaseApi } from '@classytic/commerce-sdk/core';
+import type { Media, CMSPage, HomePageContent } from '@classytic/commerce-sdk/content';
+```
 
-// Make custom API calls
-const data = await handleApiRequest('POST', '/api/v1/custom', {
-  token,
-  body: { ... }
-});
+### Notifications
+
+In-app notifications with SSE real-time updates.
+
+```typescript
+import type { InAppNotification } from '@classytic/commerce-sdk/notifications';
 ```
 
-## Authentication Guidance
+| Hook | Purpose |
+|------|---------|
+| `useNotifications(params)` | Paginated notification list |
+| `useUnreadCount()` | Unread notification count |
+| `useNotificationActions()` | Mark read, mark all read |
 
-Recommended pattern: keep SDK config static and pass the user token per request.
+## Usage Patterns
+
+### Server Components / API Routes
 
 ```typescript
-import { initCommerceSDK } from '@classytic/commerce-sdk';
+import { productApi } from '@classytic/commerce-sdk/catalog';
+
+const products = await productApi.getAll({ params: { page: 1 } });
+const product = await productApi.getBySlug({ slug: 'my-product' });
+```
 
-initCommerceSDK({
-  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
-  headers: { 'x-api-key': process.env.NEXT_PUBLIC_API_KEY! }
-});
+### Client Components (React Query hooks)
 
-// Later, per request
-await productApi.getAll({ token, params: { page: 1 } });
+```typescript
+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();
+}
 ```
 
-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.
+### Guest Checkout
 
-## Server Request Scoping (optional)
+```typescript
+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()}`,
+    });
+  };
+}
+```
 
-If you use SSR with concurrent requests and want per-request config safely:
+### Core Utilities
 
 ```typescript
-import { runWithSDKConfig } from '@classytic/commerce-sdk/server';
+import { handleApiRequest, BaseApi } from '@classytic/commerce-sdk/core';
 
-return runWithSDKConfig(
-  { baseUrl: process.env.NEXT_PUBLIC_API_URL!, headers: { 'x-api-key': '...' } },
-  async () => productApi.getAll({ token, params: { page: 1 } })
-);
+// Custom API calls (token auto-injected from configureSDK)
+const data = await handleApiRequest('POST', '/api/v1/custom', { body: { ... } });
 ```
 
 ## Types
@@ -149,16 +266,12 @@ All types are co-located with their modules:
 
 ```typescript
 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 { 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';
 ```
 
-### Local testing: 
-```
-    "@classytic/commerce-sdk": "file:D:/projects/ecom/commerce-bd-sdk/dist"
-```
-
 ## License
 
 Proprietary - see `LICENSE`

package/dist/accounting/api/account.d.ts

@@ -0,0 +1,49 @@
+import { ApiResponse, BaseApi, RequestOptions } from "../../core/api-factory.js";
+import { Account, BulkCreateResult, CreateAccountPayload, SeedAccountsResult, UpdateAccountPayload } from "../types/index.js";
+
+//#region src/accounting/api/account.d.ts
+type FetchOptions = Omit<RequestOptions, "token" | "organizationId">;
+declare class AccountApi extends BaseApi<Account, CreateAccountPayload, UpdateAccountPayload> {
+  constructor(config?: {});
+  /** Seed default BFRS chart of accounts for the branch. */
+  seed({
+    token,
+    options
+  }: {
+    token: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<SeedAccountsResult>>;
+  /** Bulk create accounts. */
+  bulkCreate({
+    token,
+    accounts,
+    options
+  }: {
+    token: string;
+    accounts: CreateAccountPayload[];
+    options?: FetchOptions;
+  }): Promise<ApiResponse<BulkCreateResult>>;
+  /** Enable (activate) an account. */
+  enable({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Account>>;
+  /** Disable (deactivate) an account. */
+  disable({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Account>>;
+}
+declare const accountApi: AccountApi;
+//#endregion
+export { AccountApi, accountApi };

package/dist/accounting/api/account.js

@@ -0,0 +1,45 @@
+import { handleApiRequest } from "../../core/api-handler.js";
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/accounting/api/account.ts
+/**
+* Account API — Chart of Accounts CRUD + Seed/Bulk/Enable/Disable
+*/
+var AccountApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("accounting/accounts", config);
+	}
+	/** Seed default BFRS chart of accounts for the branch. */
+	async seed({ token, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/seed`, {
+			token,
+			...options
+		});
+	}
+	/** Bulk create accounts. */
+	async bulkCreate({ token, accounts, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/bulk`, {
+			token,
+			body: { accounts },
+			...options
+		});
+	}
+	/** Enable (activate) an account. */
+	async enable({ token, id, options = {} }) {
+		return handleApiRequest("PATCH", `${this.baseUrl}/${id}/enable`, {
+			token,
+			...options
+		});
+	}
+	/** Disable (deactivate) an account. */
+	async disable({ token, id, options = {} }) {
+		return handleApiRequest("PATCH", `${this.baseUrl}/${id}/disable`, {
+			token,
+			...options
+		});
+	}
+};
+const accountApi = new AccountApi();
+
+//#endregion
+export { AccountApi, accountApi };

package/dist/accounting/api/budget.d.ts

@@ -0,0 +1,76 @@
+import { ApiResponse, BaseApi, RequestOptions } from "../../core/api-factory.js";
+import { Budget, BudgetSummary, BulkCreateBudgetPayload, CreateBudgetPayload, UpdateBudgetPayload } from "../types/index.js";
+
+//#region src/accounting/api/budget.d.ts
+type FetchOptions = Omit<RequestOptions, "token" | "organizationId">;
+declare class BudgetApi extends BaseApi<Budget, CreateBudgetPayload, UpdateBudgetPayload> {
+  constructor(config?: {});
+  /** Unified action endpoint — Stripe pattern */
+  private action;
+  /** Submit budget for approval (draft/rejected → submitted) */
+  submit({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Budget>>;
+  /** Approve a submitted budget (submitted → approved) */
+  approve({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Budget>>;
+  /** Reject a submitted budget with reason (submitted → rejected) */
+  reject({
+    token,
+    id,
+    reason,
+    options
+  }: {
+    token: string;
+    id: string;
+    reason?: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Budget>>;
+  /** Close an approved budget (approved → closed) */
+  close({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Budget>>;
+  /** Bulk create budget lines for a branch */
+  bulkCreate({
+    token,
+    data,
+    options
+  }: {
+    token: string;
+    data: BulkCreateBudgetPayload;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<{
+    created: number;
+    errors: string[];
+  }>>;
+  /** Budget summary aggregated by status */
+  summary({
+    token,
+    options
+  }: {
+    token: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<BudgetSummary>>;
+}
+declare const budgetApi: BudgetApi;
+//#endregion
+export { BudgetApi, budgetApi };

package/dist/accounting/api/budget.js

@@ -0,0 +1,82 @@
+import { handleApiRequest } from "../../core/api-handler.js";
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/accounting/api/budget.ts
+/**
+* Budget API — CRUD + Stripe Action Pattern (Enterprise Mode)
+*
+* State transitions use Arc's createActionRouter:
+*   POST /accounting/budgets/:id/action { action: "submit" | "approve" | "reject" | "close" }
+*/
+var BudgetApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("accounting/budgets", config);
+	}
+	/** Unified action endpoint — Stripe pattern */
+	async action({ token, id, action, data = {}, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/${id}/action`, {
+			token,
+			body: {
+				action,
+				...data
+			},
+			...options
+		});
+	}
+	/** Submit budget for approval (draft/rejected → submitted) */
+	async submit({ token, id, options = {} }) {
+		return this.action({
+			token,
+			id,
+			action: "submit",
+			options
+		});
+	}
+	/** Approve a submitted budget (submitted → approved) */
+	async approve({ token, id, options = {} }) {
+		return this.action({
+			token,
+			id,
+			action: "approve",
+			options
+		});
+	}
+	/** Reject a submitted budget with reason (submitted → rejected) */
+	async reject({ token, id, reason, options = {} }) {
+		return this.action({
+			token,
+			id,
+			action: "reject",
+			data: { reason },
+			options
+		});
+	}
+	/** Close an approved budget (approved → closed) */
+	async close({ token, id, options = {} }) {
+		return this.action({
+			token,
+			id,
+			action: "close",
+			options
+		});
+	}
+	/** Bulk create budget lines for a branch */
+	async bulkCreate({ token, data, options = {} }) {
+		return handleApiRequest("POST", `${this.baseUrl}/bulk`, {
+			token,
+			body: data,
+			...options
+		});
+	}
+	/** Budget summary aggregated by status */
+	async summary({ token, options = {} }) {
+		return handleApiRequest("GET", `${this.baseUrl}/summary`, {
+			token,
+			...options
+		});
+	}
+};
+const budgetApi = new BudgetApi();
+
+//#endregion
+export { BudgetApi, budgetApi };

package/dist/accounting/api/constants.d.ts

@@ -0,0 +1,58 @@
+import { AccountType, JournalType, TaxCode } from "../types/index.js";
+
+//#region src/accounting/api/constants.d.ts
+/** GET /accounting/account-types */
+declare function getAccountTypes(opts?: {
+  token?: string;
+  search?: string;
+  category?: string;
+}): Promise<{
+  success: boolean;
+  results: number;
+  data: AccountType[];
+}>;
+/** GET /accounting/account-types/:code */
+declare function getAccountType({
+  code
+}: {
+  token?: string;
+  code: string;
+}): Promise<{
+  success: boolean;
+  data: AccountType;
+}>;
+/** GET /accounting/journal-types */
+declare function getJournalTypes(_opts?: {
+  token?: string;
+}): Promise<{
+  success: boolean;
+  results: number;
+  data: JournalType[];
+}>;
+/** GET /accounting/journal-types/:code */
+declare function getJournalType({
+  code
+}: {
+  token?: string;
+  code: string;
+}): Promise<{
+  success: boolean;
+  data: JournalType;
+}>;
+/** GET /accounting/tax-codes */
+declare function getTaxCodes(_opts?: {
+  token?: string;
+}): Promise<{
+  success: boolean;
+  results: number;
+  data: TaxCode[];
+}>;
+/** GET /accounting/tax-codes/divisions */
+declare function getTaxDivisions(_opts?: {
+  token?: string;
+}): Promise<{
+  success: boolean;
+  data: string[];
+}>;
+//#endregion
+export { getAccountType, getAccountTypes, getJournalType, getJournalTypes, getTaxCodes, getTaxDivisions };