@classytic/commerce-sdk 0.1.2 → 0.2.1

package/README.md

@@ -1,146 +1,277 @@
-# @classytic/commerce-sdk
-
-Modular API client and React hooks for the Classytic commerce platform.
-
-## Installation
-
-```bash
-npm install @classytic/commerce-sdk
-```
-
-## Requirements
-
-- React 19+
-- Optional: Next.js 14+ for app/router usage
-- Optional: @tanstack/react-query 5+ for hooks
-
-## Quick Start
-
-```typescript
-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 modules:
-
-```typescript
-// 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
-
-```typescript
-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' });
-```
-
-### Client Components (React Query hooks)
-
-```typescript
-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
-
-```typescript
-import { handleApiRequest, BaseApi } from '@classytic/commerce-sdk/core';
-
-// Make custom API calls
-const data = await handleApiRequest('POST', '/api/v1/custom', {
-  token,
-  body: { ... }
-});
-```
-
-### Guest Checkout
-
-Place orders without authentication. The frontend stores cart items in localStorage and sends them directly in the request body along with guest identity.
-
-```typescript
-import { useGuestCheckout } from '@classytic/commerce-sdk/sales';
-import type { GuestCheckoutPayload } 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', email: 'john@example.com' },
-      deliveryAddress: { recipientName: 'John', recipientPhone: '01712345678', addressLine1: '...', areaId: 1 },
-      delivery: { method: 'standard', price: 80 },
-      paymentData: { type: 'bkash', reference: 'TRX123' },
-      idempotencyKey: `guest_01712345678_${Date.now()}`,
-    });
-  };
-
-  return <button onClick={handleCheckout} disabled={isCheckingOut}>Place Order</button>;
-}
-```
-
-Or call the API directly without React:
-
-```typescript
-import { orderApi } from '@classytic/commerce-sdk/sales';
-
-const response = await orderApi.guestCheckout({
-  data: { items, guest, deliveryAddress, delivery, paymentData },
-});
-```
-
-No auth token is required. Product prices are always resolved from the database server-side. Repeat guests are matched by phone number.
-
-## Types
-
-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 { User, UserRoleType } from '@classytic/commerce-sdk/auth';
-```
-
-## License
-
-Proprietary - see `LICENSE`
+# @classytic/commerce-sdk
+
+Modular API client and React hooks for the Classytic commerce platform.
+
+## Installation
+
+```bash
+npm install @classytic/commerce-sdk
+```
+
+## Requirements
+
+- React 19+
+- @tanstack/react-query 5+
+- Optional: Next.js 15+ for app/router usage
+
+## Quick Start
+
+```typescript
+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:
+
+```typescript
+// 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.
+
+```typescript
+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.
+
+```typescript
+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`.
+
+### Inventory
+
+Stock, purchases, transfers, requests, adjustments, suppliers, and full WMS.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+```typescript
+import type { DeliveryOption, TrackingResult, ShipmentStatus } from '@classytic/commerce-sdk/logistics';
+```
+
+### Content
+
+Media library and CMS pages.
+
+```typescript
+import type { Media, CMSPage, HomePageContent } from '@classytic/commerce-sdk/content';
+```
+
+### Notifications
+
+In-app notifications with SSE real-time updates.
+
+```typescript
+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
+
+```typescript
+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)
+
+```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();
+}
+```
+
+### Guest Checkout
+
+```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()}`,
+    });
+  };
+}
+```
+
+### Core Utilities
+
+```typescript
+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:
+
+```typescript
+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`

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 };