@classytic/commerce-sdk 0.1.1 → 0.2.1

package/dist/inventory/hooks/inventory.js

@@ -0,0 +1,267 @@
+"use client";
+
+import { getToastHandler } from "../../core/react/mutation.factory.js";
+import posApi from "../../sales/api/pos.js";
+import { adjustmentApi } from "../api/adjustment.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/inventory/hooks/inventory.ts
+/**
+* Inventory Hooks
+*
+* React hooks for inventory management with branch-specific stock.
+* These hooks use the POS API internally for product/stock data.
+*/
+const INVENTORY_KEYS = {
+	all: ["inventory"],
+	products: (branchId) => [
+		...INVENTORY_KEYS.all,
+		"products",
+		branchId
+	],
+	productsList: (branchId, params) => [...INVENTORY_KEYS.products(branchId), params],
+	lookup: (code, branchId) => [
+		...INVENTORY_KEYS.all,
+		"lookup",
+		code,
+		branchId
+	]
+};
+/**
+* Hook to fetch inventory products with branch stock
+* Uses POS API: GET /pos/products
+*
+* @param token - Auth token
+* @param branchId - Branch to get stock for
+* @param filters - Product filters
+* @param options - Query options
+*
+* @example
+* ```tsx
+* function InventoryTable({ branchId }) {
+*   const { items, summary, isLoading } = useInventory(token, branchId, {
+*     category: 'electronics',
+*     lowStockOnly: true,
+*   });
+*
+*   return (
+*     <Table data={items} />
+*   );
+* }
+* ```
+*/
+const EMPTY_PAGINATION = {
+	page: 1,
+	limit: 15,
+	total: 0,
+	pages: 0,
+	hasNext: false,
+	hasPrev: false
+};
+function useInventory(token, branchId, filters = {}, options = {}) {
+	const { data, isLoading, isFetching, error, refetch } = useQuery({
+		queryKey: INVENTORY_KEYS.productsList(branchId, filters),
+		queryFn: () => posApi.getProducts({
+			token,
+			branchId,
+			category: filters.category,
+			search: filters.search,
+			inStockOnly: filters.inStockOnly,
+			lowStockOnly: filters.lowStockOnly,
+			page: filters.page || 1,
+			limit: filters.limit || 15,
+			sort: filters.sort || "name"
+		}),
+		enabled: !!token && options.enabled !== false,
+		staleTime: 30 * 1e3,
+		refetchOnWindowFocus: true,
+		placeholderData: (prev) => prev
+	});
+	const raw = data;
+	return {
+		items: raw?.docs || [],
+		summary: raw?.summary || {
+			totalItems: 0,
+			totalQuantity: 0,
+			lowStockCount: 0,
+			outOfStockCount: 0
+		},
+		branch: raw?.branch || {
+			_id: "",
+			code: "",
+			name: ""
+		},
+		pagination: raw ? {
+			page: raw.page || 1,
+			limit: raw.limit || 15,
+			total: raw.total || 0,
+			pages: raw.pages || 0,
+			hasNext: raw.hasNext || false,
+			hasPrev: raw.hasPrev || false
+		} : EMPTY_PAGINATION,
+		isLoading,
+		isFetching,
+		error,
+		refetch
+	};
+}
+/**
+* Hook for barcode/SKU lookup
+*
+* @param token - Auth token
+* @param code - Barcode or SKU to lookup
+* @param branchId - Branch for stock info
+* @param options - Query options
+*
+* @example
+* ```tsx
+* function BarcodeScanner({ branchId }) {
+*   const [code, setCode] = useState('');
+*   const { data, isFetching } = useInventoryLookup(token, code, branchId, {
+*     enabled: code.length >= 2,
+*   });
+*
+*   return <Input value={code} onChange={e => setCode(e.target.value)} />;
+* }
+* ```
+*/
+function useInventoryLookup(token, code, branchId, options = {}) {
+	return useQuery({
+		queryKey: INVENTORY_KEYS.lookup(code, branchId),
+		queryFn: () => posApi.lookup({
+			token,
+			code,
+			branchId
+		}),
+		enabled: !!token && !!code && code.length >= 2 && options.enabled !== false,
+		staleTime: 10 * 1e3,
+		retry: false
+	});
+}
+/**
+* Hook for stock adjustment actions
+*
+* @param token - Auth token
+*
+* @example
+* ```tsx
+* function StockAdjuster({ product, branchId }) {
+*   const { adjust, isAdjusting } = useStockActions(token);
+*
+*   const handleAdjust = async (quantity: number) => {
+*     await adjust({
+*       productId: product._id,
+*       quantity,
+*       mode: 'set',
+*       branchId,
+*     });
+*   };
+*
+*   return <Button onClick={() => handleAdjust(10)} disabled={isAdjusting}>Set Stock</Button>;
+* }
+* ```
+*/
+function useStockActions(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	/**
+	* Invalidate all queries affected by stock adjustments.
+	*/
+	const invalidateStockQueries = (branchId) => {
+		queryClient.invalidateQueries({ queryKey: INVENTORY_KEYS.products(branchId) });
+		queryClient.invalidateQueries({ queryKey: [
+			"pos",
+			"products",
+			branchId
+		] });
+	};
+	const adjustMutation = useMutation({
+		mutationFn: (data) => adjustmentApi.create({
+			token,
+			data
+		}),
+		onSuccess: (_, variables) => {
+			invalidateStockQueries(variables.branchId);
+			toast.success("Stock adjusted successfully");
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to adjust stock");
+		}
+	});
+	const setStockMutation = useMutation({
+		mutationFn: ({ productId, quantity, branchId, variantSku, notes }) => adjustmentApi.create({
+			token,
+			data: {
+				productId,
+				quantity,
+				branchId,
+				variantSku,
+				mode: "set",
+				notes
+			}
+		}),
+		onSuccess: (_, variables) => {
+			invalidateStockQueries(variables.branchId);
+			toast.success("Stock level updated");
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to update stock");
+		}
+	});
+	const bulkAdjustMutation = useMutation({
+		mutationFn: (data) => adjustmentApi.create({
+			token,
+			data: {
+				adjustments: data.adjustments,
+				branchId: data.branchId,
+				reason: data.reason
+			}
+		}),
+		onSuccess: (_, variables) => {
+			invalidateStockQueries(variables.branchId);
+			toast.success("Bulk adjustment completed");
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to bulk adjust stock");
+		}
+	});
+	return {
+		adjust: adjustMutation.mutateAsync,
+		isAdjusting: adjustMutation.isPending,
+		setStock: setStockMutation.mutateAsync,
+		isSettingStock: setStockMutation.isPending,
+		bulkAdjust: bulkAdjustMutation.mutateAsync,
+		isBulkAdjusting: bulkAdjustMutation.isPending,
+		isLoading: adjustMutation.isPending || setStockMutation.isPending || bulkAdjustMutation.isPending
+	};
+}
+/**
+* Helper to determine stock status
+*/
+function getStockStatus(quantity, lowThreshold = 10) {
+	if (quantity === 0) return "out";
+	if (quantity <= lowThreshold) return "low";
+	return "ok";
+}
+/**
+* Helper to format stock status badge props
+*/
+function getStockStatusBadge(status) {
+	switch (status) {
+		case "out": return {
+			variant: "destructive",
+			label: "Out of Stock"
+		};
+		case "low": return {
+			variant: "warning",
+			label: "Low Stock"
+		};
+		case "ok": return {
+			variant: "success",
+			label: "In Stock"
+		};
+	}
+}
+
+//#endregion
+export { INVENTORY_KEYS, getStockStatus, getStockStatusBadge, useInventory, useInventoryLookup, useStockActions };

package/dist/inventory/hooks/lot.d.ts

@@ -0,0 +1,26 @@
+import { CreateLotPayload, StockLot, UpdateLotPayload } from "../api/lot.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import * as _classytic_arc_next_api0 from "@classytic/arc-next/api";
+
+//#region src/inventory/hooks/lot.d.ts
+declare const LOT_KEYS: {
+  all: readonly ["lots"];
+  list: (skuRef?: string) => readonly ["lots", "list", string | undefined];
+  detail: (id: string) => readonly ["lots", string];
+};
+declare function useLots(token: string, skuRef?: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<StockLot[], Error>;
+declare function useLotDetail(token: string, id: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<StockLot, Error>;
+declare function useLotActions(token: string): {
+  create: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<StockLot>, Error, CreateLotPayload, unknown>;
+  update: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<StockLot>, Error, {
+    id: string;
+    data: UpdateLotPayload;
+  }, unknown>;
+  isLoading: boolean;
+};
+//#endregion
+export { LOT_KEYS, useLotActions, useLotDetail, useLots };

package/dist/inventory/hooks/lot.js

@@ -0,0 +1,67 @@
+"use client";
+
+import { lotApi } from "../api/lot.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/inventory/hooks/lot.ts
+/**
+* Lot/Serial Tracking Hooks (Standard+)
+*/
+const LOT_KEYS = {
+	all: ["lots"],
+	list: (skuRef) => [
+		...LOT_KEYS.all,
+		"list",
+		skuRef
+	],
+	detail: (id) => [...LOT_KEYS.all, id]
+};
+function useLots(token, skuRef, options = {}) {
+	return useQuery({
+		queryKey: LOT_KEYS.list(skuRef),
+		queryFn: () => lotApi.list({
+			token,
+			skuRef
+		}),
+		enabled: options.enabled !== false && !!token,
+		select: (res) => res.data
+	});
+}
+function useLotDetail(token, id, options = {}) {
+	return useQuery({
+		queryKey: LOT_KEYS.detail(id),
+		queryFn: () => lotApi.getById({
+			token,
+			id
+		}),
+		enabled: options.enabled !== false && !!token && !!id,
+		select: (res) => res.data
+	});
+}
+function useLotActions(token) {
+	const qc = useQueryClient();
+	const invalidate = () => qc.invalidateQueries({ queryKey: LOT_KEYS.all });
+	const create = useMutation({
+		mutationFn: (data) => lotApi.create({
+			token,
+			data
+		}),
+		onSuccess: invalidate
+	});
+	const update = useMutation({
+		mutationFn: ({ id, data }) => lotApi.update({
+			token,
+			id,
+			data
+		}),
+		onSuccess: invalidate
+	});
+	return {
+		create,
+		update,
+		isLoading: create.isPending || update.isPending
+	};
+}
+
+//#endregion
+export { LOT_KEYS, useLotActions, useLotDetail, useLots };

package/dist/inventory/hooks/movement.d.ts

@@ -0,0 +1,68 @@
+import { ApiResponse } from "../../core/api-factory.js";
+import { LowStockItem, MovementQueryParams, StockMovement } from "../types/inventory.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+
+//#region src/inventory/hooks/movement.d.ts
+declare const MOVEMENT_KEYS: {
+  all: readonly ["inventory", "movements"];
+  list: (params?: Record<string, unknown>) => readonly ["inventory", "movements", "list", Record<string, unknown> | undefined];
+  lowStock: (params?: Record<string, unknown>) => readonly ["inventory", "movements", "low-stock", Record<string, unknown> | undefined];
+};
+interface QueryOptions {
+  enabled?: boolean;
+  staleTime?: number;
+}
+interface PaginationData {
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+interface UseMovementsReturn {
+  movements: StockMovement[];
+  pagination: PaginationData | null;
+  isLoading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => void;
+}
+/**
+ * Fetch stock movements (audit trail)
+ *
+ * @param token - Auth token
+ * @param params - Query parameters (productId, branchId, type, dates, etc.)
+ * @param options - Query options
+ *
+ * @example
+ * ```tsx
+ * function MovementHistory({ productId }) {
+ *   const { movements, isLoading } = useMovements(token, {
+ *     productId,
+ *     limit: 50,
+ *   });
+ *
+ *   return <Timeline events={movements} />;
+ * }
+ * ```
+ */
+declare function useMovements(token: string, params?: MovementQueryParams, options?: QueryOptions): UseMovementsReturn;
+/**
+ * Fetch low stock items
+ *
+ * @param token - Auth token
+ * @param params - Query parameters (branchId, threshold)
+ * @param options - Query options
+ */
+declare function useLowStock(token: string, params?: {
+  branchId?: string;
+  threshold?: number;
+}, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<ApiResponse<LowStockItem[]>, Error>;
+/**
+ * Get all keys that should be invalidated when stock quantities change.
+ * Use for: receive transfer, dispatch, adjustments, purchases.
+ */
+declare function getStockChangeInvalidationKeys(): (readonly ["inventory"] | readonly ["inventory", "movements"])[];
+//#endregion
+export { MOVEMENT_KEYS, UseMovementsReturn, getStockChangeInvalidationKeys, useLowStock, useMovements };

package/dist/inventory/hooks/movement.js

@@ -0,0 +1,106 @@
+"use client";
+
+import { movementApi } from "../api/movement.js";
+import { useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+
+//#region src/inventory/hooks/movement.ts
+/**
+* Movement Hooks
+*
+* React hooks for stock movement (audit trail) queries.
+*/
+const MOVEMENT_KEYS = {
+	all: ["inventory", "movements"],
+	list: (params) => [
+		...MOVEMENT_KEYS.all,
+		"list",
+		params
+	],
+	lowStock: (params) => [
+		...MOVEMENT_KEYS.all,
+		"low-stock",
+		params
+	]
+};
+/**
+* Fetch stock movements (audit trail)
+*
+* @param token - Auth token
+* @param params - Query parameters (productId, branchId, type, dates, etc.)
+* @param options - Query options
+*
+* @example
+* ```tsx
+* function MovementHistory({ productId }) {
+*   const { movements, isLoading } = useMovements(token, {
+*     productId,
+*     limit: 50,
+*   });
+*
+*   return <Timeline events={movements} />;
+* }
+* ```
+*/
+function useMovements(token, params, options = {}) {
+	const { data, isLoading, isFetching, error, refetch } = useQuery({
+		queryKey: MOVEMENT_KEYS.list(params),
+		queryFn: () => movementApi.list({
+			token,
+			params
+		}),
+		enabled: !!token && options.enabled !== false,
+		staleTime: options.staleTime ?? 15 * 1e3
+	});
+	return {
+		movements: useMemo(() => {
+			if (!data) return [];
+			return data.docs || data.data || [];
+		}, [data]),
+		pagination: useMemo(() => {
+			if (!data) return null;
+			const d = data;
+			if (d.page === void 0) return null;
+			return {
+				page: d.page || 1,
+				limit: d.limit || 20,
+				total: d.total || 0,
+				pages: d.pages || 1,
+				hasNext: d.hasNext || false,
+				hasPrev: d.hasPrev || false
+			};
+		}, [data]),
+		isLoading,
+		isFetching,
+		error,
+		refetch
+	};
+}
+/**
+* Fetch low stock items
+*
+* @param token - Auth token
+* @param params - Query parameters (branchId, threshold)
+* @param options - Query options
+*/
+function useLowStock(token, params, options = {}) {
+	return useQuery({
+		queryKey: MOVEMENT_KEYS.lowStock(params),
+		queryFn: () => movementApi.lowStock({
+			token,
+			params
+		}),
+		enabled: !!token && options.enabled !== false,
+		staleTime: options.staleTime ?? 60 * 1e3
+	});
+}
+/**
+* Get all keys that should be invalidated when stock quantities change.
+* Use for: receive transfer, dispatch, adjustments, purchases.
+*/
+function getStockChangeInvalidationKeys() {
+	return [["inventory"], MOVEMENT_KEYS.all];
+}
+
+//#endregion
+export { MOVEMENT_KEYS, getStockChangeInvalidationKeys, useLowStock, useMovements };

package/dist/inventory/hooks/package.d.ts

@@ -0,0 +1,32 @@
+import { CreatePackagePayload, PackageContents, StockPackage } from "../api/package.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import * as _classytic_arc_next_api0 from "@classytic/arc-next/api";
+
+//#region src/inventory/hooks/package.d.ts
+declare const PACKAGE_KEYS: {
+  all: readonly ["packages"];
+  list: (locationId?: string) => readonly ["packages", "list", string | undefined];
+  detail: (id: string) => readonly ["packages", string];
+  contents: (id: string) => readonly ["packages", string, "contents"];
+};
+declare function usePackages(token: string, locationId?: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<StockPackage[], Error>;
+declare function usePackageContents(token: string, id: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<PackageContents, Error>;
+declare function usePackageActions(token: string): {
+  create: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<StockPackage>, Error, CreatePackagePayload, unknown>;
+  nest: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<{
+    nested: boolean;
+  }>, Error, {
+    id: string;
+    childPackageId: string;
+  }, unknown>;
+  unnest: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<{
+    unnested: boolean;
+  }>, Error, string, unknown>;
+  isLoading: boolean;
+};
+//#endregion
+export { PACKAGE_KEYS, usePackageActions, usePackageContents, usePackages };

package/dist/inventory/hooks/package.js

@@ -0,0 +1,80 @@
+"use client";
+
+import { packageApi } from "../api/package.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/inventory/hooks/package.ts
+/**
+* Package Management Hooks (Standard+)
+*/
+const PACKAGE_KEYS = {
+	all: ["packages"],
+	list: (locationId) => [
+		...PACKAGE_KEYS.all,
+		"list",
+		locationId
+	],
+	detail: (id) => [...PACKAGE_KEYS.all, id],
+	contents: (id) => [
+		...PACKAGE_KEYS.all,
+		id,
+		"contents"
+	]
+};
+function usePackages(token, locationId, options = {}) {
+	return useQuery({
+		queryKey: PACKAGE_KEYS.list(locationId),
+		queryFn: () => packageApi.list({
+			token,
+			locationId
+		}),
+		enabled: options.enabled !== false && !!token,
+		select: (res) => res.data
+	});
+}
+function usePackageContents(token, id, options = {}) {
+	return useQuery({
+		queryKey: PACKAGE_KEYS.contents(id),
+		queryFn: () => packageApi.getContents({
+			token,
+			id
+		}),
+		enabled: options.enabled !== false && !!token && !!id,
+		select: (res) => res.data
+	});
+}
+function usePackageActions(token) {
+	const qc = useQueryClient();
+	const invalidate = () => qc.invalidateQueries({ queryKey: PACKAGE_KEYS.all });
+	const create = useMutation({
+		mutationFn: (data) => packageApi.create({
+			token,
+			data
+		}),
+		onSuccess: invalidate
+	});
+	const nest = useMutation({
+		mutationFn: ({ id, childPackageId }) => packageApi.nest({
+			token,
+			id,
+			childPackageId
+		}),
+		onSuccess: invalidate
+	});
+	const unnest = useMutation({
+		mutationFn: (id) => packageApi.unnest({
+			token,
+			id
+		}),
+		onSuccess: invalidate
+	});
+	return {
+		create,
+		nest,
+		unnest,
+		isLoading: create.isPending || nest.isPending || unnest.isPending
+	};
+}
+
+//#endregion
+export { PACKAGE_KEYS, usePackageActions, usePackageContents, usePackages };

package/dist/inventory/hooks/procurement.d.ts

@@ -0,0 +1,28 @@
+import { CreateProcurementPayload, ProcurementOrder, ReceiveProcurementPayload } from "../api/procurement.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import * as _classytic_arc_next_api0 from "@classytic/arc-next/api";
+
+//#region src/inventory/hooks/procurement.d.ts
+declare const PROCUREMENT_KEYS: {
+  all: readonly ["procurement"];
+  list: (status?: string) => readonly ["procurement", "list", string | undefined];
+  detail: (id: string) => readonly ["procurement", string];
+};
+declare function useProcurementOrders(token: string, status?: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<ProcurementOrder[], Error>;
+declare function useProcurementDetail(token: string, id: string, options?: {
+  enabled?: boolean;
+}): _tanstack_react_query0.UseQueryResult<ProcurementOrder, Error>;
+declare function useProcurementActions(token: string): {
+  create: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<ProcurementOrder>, Error, CreateProcurementPayload, unknown>;
+  approve: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<ProcurementOrder>, Error, string, unknown>;
+  receive: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<ProcurementOrder>, Error, {
+    id: string;
+    data: ReceiveProcurementPayload;
+  }, unknown>;
+  cancel: _tanstack_react_query0.UseMutationResult<_classytic_arc_next_api0.ApiResponse<ProcurementOrder>, Error, string, unknown>;
+  isLoading: boolean;
+};
+//#endregion
+export { PROCUREMENT_KEYS, useProcurementActions, useProcurementDetail, useProcurementOrders };