@classytic/commerce-sdk 0.1.1 → 0.2.1

package/dist/sales/hooks/cart.js

@@ -0,0 +1,161 @@
+"use client";
+
+import { useMutationWithOptimistic } from "../../core/react/mutation.factory.js";
+import { createQueryKeys } from "../../core/react/query.factory.js";
+import { cartApi } from "../api/cart.js";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/sales/hooks/cart.ts
+/**
+* Cart Hooks
+*
+* React hooks for shopping cart operations with optimistic updates.
+*/
+const CART_KEYS = createQueryKeys("cart");
+function calculateItemPrice(item) {
+	if (!item?.product) return 0;
+	const product = item.product;
+	const basePrice = product.currentPrice ?? product.basePrice ?? 0;
+	if (item.variantSku && product.variants && product.variants.length > 0) {
+		const variant = product.variants.find((v) => v.sku === item.variantSku);
+		if (variant) return basePrice + (variant.priceModifier || 0);
+	}
+	return basePrice;
+}
+function calculateItemTotal(item) {
+	return calculateItemPrice(item) * (item.quantity || 1);
+}
+function calculateCartSubtotal(items) {
+	return items?.reduce((total, item) => total + calculateItemTotal(item), 0) || 0;
+}
+function getCartItemCount(items) {
+	return items?.reduce((count, item) => count + (item.quantity || 0), 0) || 0;
+}
+function getCartItemVariant(item) {
+	if (!item?.variantSku || !item?.product?.variants) return null;
+	return item.product.variants.find((v) => v.sku === item.variantSku) || null;
+}
+function formatVariantAttributes(attributes) {
+	if (!attributes || Object.keys(attributes).length === 0) return "";
+	return Object.entries(attributes).map(([key, value]) => `${key.charAt(0).toUpperCase() + key.slice(1)}: ${value}`).join(", ");
+}
+const CART_QUERY_KEY = ["cart"];
+/**
+* Full cart hook with optimistic updates.
+*/
+function useCart(options = {}) {
+	const { enabled = true, staleTime = 120 * 1e3, gcTime = 600 * 1e3 } = options;
+	const queryClient = useQueryClient();
+	const { data: cart, isLoading, error, isFetching, refetch } = useQuery({
+		queryKey: CART_QUERY_KEY,
+		queryFn: () => cartApi.getCart(),
+		enabled,
+		staleTime,
+		gcTime
+	});
+	const addMutation = useMutationWithOptimistic({
+		mutationFn: (data) => cartApi.addItem({ data }),
+		queryKeys: [CART_QUERY_KEY],
+		messages: {
+			success: "Added to cart!",
+			error: "Failed to add item to cart"
+		},
+		onSuccess: (data) => queryClient.setQueryData(CART_QUERY_KEY, data)
+	});
+	const updateMutation = useMutationWithOptimistic({
+		mutationFn: ({ itemId, quantity }) => cartApi.updateItem({
+			itemId,
+			quantity
+		}),
+		queryKeys: [CART_QUERY_KEY],
+		optimisticUpdate: (old, { itemId, quantity }) => {
+			const cart = old;
+			if (!cart) return old;
+			return {
+				...cart,
+				items: cart.items.map((i) => i._id === itemId ? {
+					...i,
+					quantity
+				} : i)
+			};
+		},
+		messages: { error: "Failed to update cart" },
+		onSuccess: (data) => queryClient.setQueryData(CART_QUERY_KEY, data)
+	});
+	const removeMutation = useMutationWithOptimistic({
+		mutationFn: (itemId) => cartApi.removeItem({ itemId }),
+		queryKeys: [CART_QUERY_KEY],
+		optimisticUpdate: (old, itemId) => {
+			const cart = old;
+			if (!cart) return old;
+			return {
+				...cart,
+				items: cart.items.filter((i) => i._id !== itemId)
+			};
+		},
+		messages: {
+			success: "Item removed",
+			error: "Failed to remove item"
+		},
+		onSuccess: (data) => queryClient.setQueryData(CART_QUERY_KEY, data)
+	});
+	const clearMutation = useMutationWithOptimistic({
+		mutationFn: () => cartApi.clear(),
+		queryKeys: [CART_QUERY_KEY],
+		optimisticUpdate: (old) => {
+			const cart = old;
+			if (!cart) return old;
+			return {
+				...cart,
+				items: []
+			};
+		},
+		messages: {
+			success: "Cart cleared",
+			error: "Failed to clear cart"
+		},
+		onSuccess: (data) => queryClient.setQueryData(CART_QUERY_KEY, data)
+	});
+	const items = cart?.items || [];
+	const isUpdating = addMutation.isPending || updateMutation.isPending || removeMutation.isPending || clearMutation.isPending;
+	return {
+		cart,
+		items,
+		itemCount: getCartItemCount(items),
+		subtotal: calculateCartSubtotal(items),
+		isLoading,
+		isFetching,
+		isUpdating,
+		error,
+		addToCart: (data) => addMutation.mutate(data),
+		addToCartAsync: (data) => addMutation.mutateAsync(data),
+		updateCartItem: (data) => updateMutation.mutate(data),
+		updateCartItemAsync: (data) => updateMutation.mutateAsync(data),
+		removeCartItem: (itemId) => removeMutation.mutate(itemId),
+		removeCartItemAsync: (itemId) => removeMutation.mutateAsync(itemId),
+		clearCart: () => clearMutation.mutate(),
+		clearCartAsync: () => clearMutation.mutateAsync(),
+		refetch: () => refetch(),
+		getItemPrice: calculateItemPrice
+	};
+}
+/**
+* Lightweight hook for cart count (header badge).
+*/
+function useCartCount(options = {}) {
+	const { enabled = true, staleTime = 120 * 1e3, gcTime = 600 * 1e3 } = options;
+	const { data: cart, isLoading } = useQuery({
+		queryKey: CART_QUERY_KEY,
+		queryFn: () => cartApi.getCart(),
+		enabled,
+		staleTime,
+		gcTime
+	});
+	return {
+		count: getCartItemCount(cart?.items || []),
+		isLoading
+	};
+}
+
+//#endregion
+export { CART_KEYS, calculateCartSubtotal, calculateItemPrice, calculateItemTotal, formatVariantAttributes, getCartItemCount, getCartItemVariant, useCart, useCartCount };

package/dist/sales/hooks/customer.d.ts

@@ -0,0 +1,100 @@
+import { Customer, CustomerPayload } from "../types/customer.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import * as _classytic_arc_next_query0 from "@classytic/arc-next/query";
+import * as _classytic_arc_next0 from "@classytic/arc-next";
+
+//#region src/sales/hooks/customer.d.ts
+interface QueryOptions {
+  enabled?: boolean;
+  staleTime?: number;
+}
+type MembershipAction = "enroll" | "deactivate" | "reactivate" | "adjust";
+type PointsType = "bonus" | "correction" | "manual_redemption" | "redemption" | "expiry";
+interface MembershipActionParams {
+  id: string;
+  action: MembershipAction;
+  points?: number;
+  reason?: string;
+  type?: PointsType;
+}
+interface UseCustomerMembershipReturn {
+  membershipAction: (params: MembershipActionParams) => Promise<Customer>;
+  isPending: boolean;
+}
+/**
+ * Customer hooks using createCrudHooks factory
+ *
+ * Provides:
+ * - useCustomers: List customers with filtering/pagination
+ * - useCustomerDetail: Get single customer
+ * - useCustomerActions: Create, update, delete mutations
+ * - useCustomerNavigation: Navigation between customers
+ */
+declare const customerHooks: _classytic_arc_next0.CrudHooksReturn<Customer, CustomerPayload, CustomerPayload>;
+declare const CUSTOMER_KEYS: _classytic_arc_next_query0.QueryKeys, useCustomers: {
+    (params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<Customer> | undefined): _classytic_arc_next_query0.ListQueryResult<Customer>;
+    (token: string | null, params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<Customer> | undefined): _classytic_arc_next_query0.ListQueryResult<Customer>;
+  }, useCustomerDetail: {
+    (id: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<Customer> | undefined): _classytic_arc_next_query0.DetailQueryResult<Customer>;
+    (id: string | null, token: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<Customer> | undefined): _classytic_arc_next_query0.DetailQueryResult<Customer>;
+  }, useCustomerActions: () => _classytic_arc_next0.CrudActions<Customer, CustomerPayload, CustomerPayload>, useCustomerNavigation: () => _classytic_arc_next0.NavigateFn<Customer>;
+/**
+ * Get current user's customer profile
+ *
+ * @param token - Auth token
+ * @param options - Query options
+ *
+ * @example
+ * ```tsx
+ * function ProfilePage() {
+ *   const { data: customer, isLoading } = useCurrentCustomer(token);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   return (
+ *     <div>
+ *       <h1>{customer?.name}</h1>
+ *       <p>Points: {customer?.membership?.points || 0}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useCurrentCustomer(token: string, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<Customer, Error>;
+/**
+ * Customer membership actions (enroll, deactivate, reactivate, adjust points)
+ *
+ * @param token - Admin auth token
+ *
+ * @example
+ * ```tsx
+ * function MembershipManager({ customer }) {
+ *   const { membershipAction, isPending } = useCustomerMembership(token);
+ *
+ *   const handleEnroll = async () => {
+ *     await membershipAction({
+ *       id: customer._id,
+ *       action: 'enroll',
+ *     });
+ *   };
+ *
+ *   const handleAdjustPoints = async (points: number) => {
+ *     await membershipAction({
+ *       id: customer._id,
+ *       action: 'adjust',
+ *       points,
+ *       type: 'bonus',
+ *       reason: 'Birthday bonus',
+ *     });
+ *   };
+ *
+ *   return (
+ *     <Button onClick={handleEnroll} disabled={isPending}>
+ *       Enroll in Membership
+ *     </Button>
+ *   );
+ * }
+ * ```
+ */
+declare function useCustomerMembership(token: string): UseCustomerMembershipReturn;
+//#endregion
+export { CUSTOMER_KEYS, MembershipActionParams, UseCustomerMembershipReturn, customerHooks, useCurrentCustomer, useCustomerActions, useCustomerDetail, useCustomerMembership, useCustomerNavigation, useCustomers };

package/dist/sales/hooks/customer.js

@@ -0,0 +1,130 @@
+"use client";
+
+import { getToastHandler } from "../../core/react/mutation.factory.js";
+import { createCrudHooks } from "../../core/react/crud.factory.js";
+import { customerApi } from "../api/customer.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/sales/hooks/customer.ts
+/**
+* Customer Hooks
+*
+* React hooks for customer CRUD operations using the factory pattern.
+* Includes customer profile and membership management.
+*/
+/**
+* Customer hooks using createCrudHooks factory
+*
+* Provides:
+* - useCustomers: List customers with filtering/pagination
+* - useCustomerDetail: Get single customer
+* - useCustomerActions: Create, update, delete mutations
+* - useCustomerNavigation: Navigation between customers
+*/
+const customerHooks = createCrudHooks({
+	api: customerApi,
+	entityKey: "customers",
+	singular: "Customer",
+	plural: "Customers",
+	defaults: { staleTime: 300 * 1e3 }
+});
+const { KEYS: CUSTOMER_KEYS, useList: useCustomers, useDetail: useCustomerDetail, useActions: useCustomerActions, useNavigation: useCustomerNavigation } = customerHooks;
+/**
+* Get current user's customer profile
+*
+* @param token - Auth token
+* @param options - Query options
+*
+* @example
+* ```tsx
+* function ProfilePage() {
+*   const { data: customer, isLoading } = useCurrentCustomer(token);
+*
+*   if (isLoading) return <Skeleton />;
+*   return (
+*     <div>
+*       <h1>{customer?.name}</h1>
+*       <p>Points: {customer?.membership?.points || 0}</p>
+*     </div>
+*   );
+* }
+* ```
+*/
+function useCurrentCustomer(token, options = {}) {
+	return useQuery({
+		queryKey: [...CUSTOMER_KEYS.all, "me"],
+		queryFn: async () => {
+			return (await customerApi.getMe({ token })).data;
+		},
+		enabled: !!token && options.enabled !== false,
+		staleTime: options.staleTime ?? 300 * 1e3
+	});
+}
+/**
+* Customer membership actions (enroll, deactivate, reactivate, adjust points)
+*
+* @param token - Admin auth token
+*
+* @example
+* ```tsx
+* function MembershipManager({ customer }) {
+*   const { membershipAction, isPending } = useCustomerMembership(token);
+*
+*   const handleEnroll = async () => {
+*     await membershipAction({
+*       id: customer._id,
+*       action: 'enroll',
+*     });
+*   };
+*
+*   const handleAdjustPoints = async (points: number) => {
+*     await membershipAction({
+*       id: customer._id,
+*       action: 'adjust',
+*       points,
+*       type: 'bonus',
+*       reason: 'Birthday bonus',
+*     });
+*   };
+*
+*   return (
+*     <Button onClick={handleEnroll} disabled={isPending}>
+*       Enroll in Membership
+*     </Button>
+*   );
+* }
+* ```
+*/
+function useCustomerMembership(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	const mutation = useMutation({
+		mutationFn: async ({ id, action, points, reason, type }) => {
+			return (await customerApi.membershipAction({
+				token,
+				id,
+				data: {
+					action,
+					points,
+					reason,
+					type
+				}
+			})).data;
+		},
+		onSuccess: () => {
+			queryClient.invalidateQueries({ queryKey: CUSTOMER_KEYS.lists() });
+			queryClient.invalidateQueries({ queryKey: CUSTOMER_KEYS.details() });
+			toast.success("Membership updated successfully");
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to update membership");
+		}
+	});
+	return {
+		membershipAction: mutation.mutateAsync,
+		isPending: mutation.isPending
+	};
+}
+
+//#endregion
+export { CUSTOMER_KEYS, customerHooks, useCurrentCustomer, useCustomerActions, useCustomerDetail, useCustomerMembership, useCustomerNavigation, useCustomers };

package/dist/sales/hooks/earning-rules.d.ts

@@ -0,0 +1,31 @@
+import { CreateEarningRulePayload, EarningRule, EarningRuleListParams, UpdateEarningRulePayload } from "../types/earning-rules.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+
+//#region src/sales/hooks/earning-rules.d.ts
+declare const EARNING_RULE_KEYS: {
+  all: readonly ["loyalty", "earning-rules"];
+  list: (params?: EarningRuleListParams) => readonly ["loyalty", "earning-rules", "list", EarningRuleListParams | undefined];
+  detail: (ruleId: string) => readonly ["loyalty", "earning-rules", string];
+};
+interface QueryOptions {
+  enabled?: boolean;
+  staleTime?: number;
+}
+interface UseEarningRuleActionsReturn {
+  create: (data: CreateEarningRulePayload) => Promise<EarningRule>;
+  update: (ruleId: string, data: UpdateEarningRulePayload) => Promise<EarningRule>;
+  deactivate: (ruleId: string) => Promise<EarningRule>;
+  isPending: boolean;
+}
+declare function useEarningRules(token: string, params?: EarningRuleListParams, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<{
+  docs: EarningRule[];
+  total: number;
+  page: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}, Error>;
+declare function useEarningRuleDetail(token: string, ruleId: string, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<EarningRule, Error>;
+declare function useEarningRuleActions(token: string): UseEarningRuleActionsReturn;
+//#endregion
+export { EARNING_RULE_KEYS, UseEarningRuleActionsReturn, useEarningRuleActions, useEarningRuleDetail, useEarningRules };

package/dist/sales/hooks/earning-rules.js

@@ -0,0 +1,112 @@
+"use client";
+
+import { getToastHandler } from "../../core/react/mutation.factory.js";
+import { earningRulesApi } from "../api/earning-rules.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/sales/hooks/earning-rules.ts
+/**
+* Earning Rules Hooks
+*
+* React hooks for loyalty earning rule management.
+*/
+const EARNING_RULE_KEYS = {
+	all: ["loyalty", "earning-rules"],
+	list: (params) => [
+		...EARNING_RULE_KEYS.all,
+		"list",
+		params
+	],
+	detail: (ruleId) => [...EARNING_RULE_KEYS.all, ruleId]
+};
+function useEarningRules(token, params = {}, options = {}) {
+	return useQuery({
+		queryKey: EARNING_RULE_KEYS.list(params),
+		queryFn: async () => {
+			return (await earningRulesApi.list({
+				token,
+				params
+			})).data;
+		},
+		enabled: !!token && options.enabled !== false,
+		staleTime: options.staleTime ?? 3e4
+	});
+}
+function useEarningRuleDetail(token, ruleId, options = {}) {
+	return useQuery({
+		queryKey: EARNING_RULE_KEYS.detail(ruleId),
+		queryFn: async () => {
+			return (await earningRulesApi.get({
+				token,
+				ruleId
+			})).data;
+		},
+		enabled: !!token && !!ruleId && options.enabled !== false,
+		staleTime: options.staleTime ?? 3e4
+	});
+}
+function useEarningRuleActions(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	const invalidate = () => {
+		queryClient.invalidateQueries({ queryKey: EARNING_RULE_KEYS.all });
+	};
+	const createMutation = useMutation({
+		mutationFn: async (data) => {
+			return (await earningRulesApi.create({
+				token,
+				data
+			})).data;
+		},
+		onSuccess: () => {
+			invalidate();
+			toast.success("Earning rule created");
+		},
+		onError: (err) => {
+			toast.error(err.message || "Failed to create rule");
+		}
+	});
+	const updateMutation = useMutation({
+		mutationFn: async ({ ruleId, data }) => {
+			return (await earningRulesApi.update({
+				token,
+				ruleId,
+				data
+			})).data;
+		},
+		onSuccess: () => {
+			invalidate();
+			toast.success("Earning rule updated");
+		},
+		onError: (err) => {
+			toast.error(err.message || "Failed to update rule");
+		}
+	});
+	const deactivateMutation = useMutation({
+		mutationFn: async (ruleId) => {
+			return (await earningRulesApi.deactivate({
+				token,
+				ruleId
+			})).data;
+		},
+		onSuccess: () => {
+			invalidate();
+			toast.success("Earning rule deactivated");
+		},
+		onError: (err) => {
+			toast.error(err.message || "Failed to deactivate rule");
+		}
+	});
+	return {
+		create: createMutation.mutateAsync,
+		update: (ruleId, data) => updateMutation.mutateAsync({
+			ruleId,
+			data
+		}),
+		deactivate: deactivateMutation.mutateAsync,
+		isPending: createMutation.isPending || updateMutation.isPending || deactivateMutation.isPending
+	};
+}
+
+//#endregion
+export { EARNING_RULE_KEYS, useEarningRuleActions, useEarningRuleDetail, useEarningRules };

package/dist/sales/hooks/index.d.ts

@@ -0,0 +1,8 @@
+import { CART_KEYS, CartOptions, UseCartCountReturn, UseCartReturn, calculateCartSubtotal, calculateItemPrice, calculateItemTotal, formatVariantAttributes, getCartItemCount, getCartItemVariant, useCart, useCartCount } from "./cart.js";
+import { ORDER_KEYS, UseAdminOrderActionsReturn, UseCustomerOrderActionsReturn, UseGuestCheckoutReturn, UseMyOrdersReturn, orderHooks, useAdminOrderActions, useCustomerOrderActions, useGuestCheckout, useMyOrderDetail, useMyOrders, useOrderActions, useOrderDetail, useOrderNavigation, useOrders } from "./order.js";
+import { CUSTOMER_KEYS, MembershipActionParams, UseCustomerMembershipReturn, customerHooks, useCurrentCustomer, useCustomerActions, useCustomerDetail, useCustomerMembership, useCustomerNavigation, useCustomers } from "./customer.js";
+import { POS_KEYS, PosProductFilters, UsePosOrdersReturn, UsePosProductsReturn, UsePosStockActionsReturn, calculateVariantPrice, findVariantBySku, formatVariantLabel, generateIdempotencyKey, getAvailableVariants, getPosProductImage, getVariantStock, isInStock, isVariantProduct, usePosLookup, usePosLookupMutation, usePosOrders, usePosProducts, usePosReceipt, usePosStockActions } from "./pos.js";
+import { LOYALTY_KEYS, UseLoyaltyActionsReturn, useLoyaltyActions, useLoyaltyHistory, useLoyaltyMember, useMyLoyalty, useSelfEnroll } from "./loyalty.js";
+import { EARNING_RULE_KEYS, UseEarningRuleActionsReturn, useEarningRuleActions, useEarningRuleDetail, useEarningRules } from "./earning-rules.js";
+import { TIER_KEYS, UseTierActionsReturn, useLoyaltyTiers, useTierActions } from "./tiers.js";
+import { REFERRAL_KEYS, UseReferralActionsReturn, useMemberReferrals, useReferralActions, useReferralLookup } from "./referrals.js";

package/dist/sales/hooks/loyalty.d.ts

@@ -0,0 +1,51 @@
+import { AdjustPointsPayload, LoyaltyBalanceSummary, LoyaltyHistoryParams, LoyaltyMember, LoyaltyTransaction } from "../types/loyalty.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+
+//#region src/sales/hooks/loyalty.d.ts
+declare const LOYALTY_KEYS: {
+  all: readonly ["loyalty"];
+  members: () => readonly ["loyalty", "members"];
+  member: (customerId: string) => readonly ["loyalty", "members", string];
+  history: (customerId: string) => readonly ["loyalty", "members", string, "history"];
+  me: () => readonly ["loyalty", "me"];
+};
+interface QueryOptions {
+  enabled?: boolean;
+  staleTime?: number;
+}
+interface UseLoyaltyActionsReturn {
+  enroll: (customerId: string) => Promise<unknown>;
+  adjustPoints: (customerId: string, data: AdjustPointsPayload) => Promise<unknown>;
+  deactivate: (customerId: string) => Promise<unknown>;
+  reactivate: (customerId: string) => Promise<unknown>;
+  isPending: boolean;
+}
+/** Get loyalty member details + balance for a customer */
+declare function useLoyaltyMember(customerId: string, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<{
+  member: LoyaltyMember;
+  balance: LoyaltyBalanceSummary;
+}, Error>;
+/** Get points transaction history for a customer */
+declare function useLoyaltyHistory(customerId: string, params?: LoyaltyHistoryParams, options?: QueryOptions): _tanstack_react_query0.UseQueryResult<{
+  docs: LoyaltyTransaction[];
+  total: number;
+  page: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}, Error>;
+/** Loyalty admin actions (enroll, adjust, deactivate, reactivate) */
+declare function useLoyaltyActions(): UseLoyaltyActionsReturn;
+/** Get my loyalty status (customer-facing) */
+declare function useMyLoyalty(options?: QueryOptions): _tanstack_react_query0.UseQueryResult<{
+  enrolled: boolean;
+  member?: LoyaltyMember;
+  balance?: LoyaltyBalanceSummary;
+}, Error>;
+/** Self-enroll in loyalty program */
+declare function useSelfEnroll(): {
+  selfEnroll: _tanstack_react_query0.UseMutateAsyncFunction<unknown, Error, void, unknown>;
+  isPending: boolean;
+};
+//#endregion
+export { LOYALTY_KEYS, UseLoyaltyActionsReturn, useLoyaltyActions, useLoyaltyHistory, useLoyaltyMember, useMyLoyalty, useSelfEnroll };