@classytic/commerce-sdk 0.1.1 → 0.2.1

package/dist/catalog/hooks/product.js

@@ -0,0 +1,267 @@
+"use client";
+
+import { getToastHandler } from "../../core/react/mutation.factory.js";
+import { createCrudHooks } from "../../core/react/crud.factory.js";
+import { productApi } from "../api/product.js";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+//#region src/catalog/hooks/product.ts
+/**
+* Product Hooks
+*
+* Pre-built hooks for product CRUD operations with:
+* - Optimistic updates
+* - Smart caching
+* - Type safety
+*/
+/**
+* Product CRUD hooks with optimistic updates
+*/
+const productHooks = createCrudHooks({
+	api: productApi,
+	entityKey: "products",
+	singular: "Product",
+	plural: "Products",
+	defaults: { staleTime: 300 * 1e3 }
+});
+const { KEYS: PRODUCT_KEYS, useList: useProducts, useDetail: useProductDetail, useActions: useProductActions, useNavigation: useProductNavigation } = productHooks;
+/**
+* Hook to get product by slug
+*
+* @param token - Auth token (optional for public access)
+* @param slug - Product slug
+* @param options - React Query options
+* @returns Query result with product data
+*
+* @example
+* ```tsx
+* function ProductPage({ slug }) {
+*   const { data, isLoading } = useProductBySlug(null, slug);
+*
+*   if (isLoading) return <Spinner />;
+*
+*   return <h1>{data?.data?.name}</h1>;
+* }
+* ```
+*/
+function useProductBySlug(token, slug, options = {}) {
+	return useQuery({
+		queryKey: [
+			...PRODUCT_KEYS.all,
+			"slug",
+			slug
+		],
+		queryFn: () => productApi.getBySlug({
+			token,
+			slug
+		}),
+		enabled: !!slug,
+		staleTime: 300 * 1e3,
+		...options
+	});
+}
+/**
+* Hook to get product recommendations
+*
+* @param productId - Product ID to get recommendations for
+* @param options - React Query options
+* @returns Object with recommendations array, isLoading, and error
+*
+* @example
+* ```tsx
+* function ProductRecommendations({ productId }) {
+*   const { recommendations, isLoading } = useProductRecommendations(productId);
+*
+*   if (isLoading) return <Spinner />;
+*
+*   return (
+*     <div>
+*       {recommendations.map(product => (
+*         <ProductCard key={product._id} product={product} />
+*       ))}
+*     </div>
+*   );
+* }
+* ```
+*/
+function useProductRecommendations(productId, options = {}) {
+	const { data, isLoading, error } = useQuery({
+		queryKey: [
+			...PRODUCT_KEYS.all,
+			"recommendations",
+			productId
+		],
+		queryFn: () => productApi.getRecommendations({
+			token: null,
+			productId
+		}),
+		enabled: !!productId,
+		staleTime: 600 * 1e3,
+		...options
+	});
+	return {
+		recommendations: data?.data ?? [],
+		isLoading,
+		error
+	};
+}
+/**
+* Hook to get soft-deleted products (Recycle Bin)
+*
+* @param token - Auth token (required, admin only)
+* @param params - Query parameters for pagination/filtering
+* @param options - React Query options
+* @returns Query result with deleted products
+*
+* @example
+* ```tsx
+* function RecycleBin() {
+*   const { data, isLoading } = useDeletedProducts(token, { page: 1, limit: 20 });
+*
+*   if (isLoading) return <Spinner />;
+*
+*   return (
+*     <div>
+*       {data?.docs?.map(product => (
+*         <DeletedProductRow key={product._id} product={product} />
+*       ))}
+*     </div>
+*   );
+* }
+* ```
+*/
+function useDeletedProducts(token, params = {}, options = {}) {
+	return useQuery({
+		queryKey: [
+			...PRODUCT_KEYS.all,
+			"deleted",
+			params
+		],
+		queryFn: () => productApi.getDeleted({
+			token,
+			params
+		}),
+		enabled: !!token,
+		staleTime: 120 * 1e3,
+		...options
+	});
+}
+/**
+* Hook to restore a soft-deleted product
+*
+* @param token - Auth token (required, admin only)
+* @returns Mutation result with restore function
+*
+* @example
+* ```tsx
+* function RestoreButton({ productId }) {
+*   const { mutate: restore, isPending } = useRestoreProduct(token);
+*
+*   return (
+*     <Button onClick={() => restore(productId)} disabled={isPending}>
+*       Restore Product
+*     </Button>
+*   );
+* }
+* ```
+*/
+function useRestoreProduct(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	return useMutation({
+		mutationFn: (id) => productApi.restore({
+			token,
+			id
+		}),
+		onSuccess: () => {
+			toast.success("Product restored successfully");
+			queryClient.invalidateQueries({ queryKey: [...PRODUCT_KEYS.all, "deleted"] });
+			queryClient.invalidateQueries({ queryKey: PRODUCT_KEYS.lists() });
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to restore product");
+		}
+	});
+}
+/**
+* Hook to permanently delete a product (Hard delete)
+*
+* @param token - Auth token (required, admin only)
+* @returns Mutation result with hard delete function
+*
+* @example
+* ```tsx
+* function PermanentDeleteButton({ productId }) {
+*   const { mutate: hardDelete, isPending } = useHardDeleteProduct(token);
+*
+*   return (
+*     <Button
+*       variant="destructive"
+*       onClick={() => hardDelete(productId)}
+*       disabled={isPending}
+*     >
+*       Permanently Delete
+*     </Button>
+*   );
+* }
+* ```
+*/
+function useHardDeleteProduct(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	return useMutation({
+		mutationFn: (id) => productApi.hardDelete({
+			token,
+			id
+		}),
+		onSuccess: () => {
+			toast.success("Product permanently deleted");
+			queryClient.invalidateQueries({ queryKey: [...PRODUCT_KEYS.all, "deleted"] });
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to permanently delete product");
+		}
+	});
+}
+/**
+* Hook to sync product stock quantity
+*
+* Recomputes product.quantity by summing all StockEntry quantities across branches.
+*
+* @param token - Auth token (requires: admin, warehouse-admin, warehouse-staff, or store-manager role)
+* @returns Mutation result with sync function
+*
+* @example
+* ```tsx
+* function SyncStockButton({ productId }) {
+*   const { mutate: syncStock, isPending } = useSyncProductStock(token);
+*
+*   return (
+*     <Button onClick={() => syncStock(productId)} disabled={isPending}>
+*       Sync Stock
+*     </Button>
+*   );
+* }
+* ```
+*/
+function useSyncProductStock(token) {
+	const queryClient = useQueryClient();
+	const toast = getToastHandler();
+	return useMutation({
+		mutationFn: (id) => productApi.syncStock({
+			token,
+			id
+		}),
+		onSuccess: (result, id) => {
+			toast.success(`Stock synced: ${result.totalQuantity} units`);
+			queryClient.invalidateQueries({ queryKey: PRODUCT_KEYS.detail(id) });
+			queryClient.invalidateQueries({ queryKey: PRODUCT_KEYS.lists() });
+		},
+		onError: (error) => {
+			toast.error(error.message || "Failed to sync stock");
+		}
+	});
+}
+
+//#endregion
+export { PRODUCT_KEYS, productHooks, useDeletedProducts, useHardDeleteProduct, useProductActions, useProductBySlug, useProductDetail, useProductNavigation, useProductRecommendations, useProducts, useRestoreProduct, useSyncProductStock };

package/dist/catalog/hooks/review.d.ts

@@ -0,0 +1,18 @@
+import { CreateReviewPayload, Review, ReviewResponse, UpdateReviewPayload } from "../types/review.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import { UseQueryOptions } 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/catalog/hooks/review.d.ts
+declare const reviewHooks: _classytic_arc_next0.CrudHooksReturn<Review, CreateReviewPayload, UpdateReviewPayload>;
+declare const REVIEW_KEYS: _classytic_arc_next_query0.QueryKeys, useReviews: {
+    (params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<Review> | undefined): _classytic_arc_next_query0.ListQueryResult<Review>;
+    (token: string | null, params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<Review> | undefined): _classytic_arc_next_query0.ListQueryResult<Review>;
+  }, useReviewDetail: {
+    (id: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<Review> | undefined): _classytic_arc_next_query0.DetailQueryResult<Review>;
+    (id: string | null, token: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<Review> | undefined): _classytic_arc_next_query0.DetailQueryResult<Review>;
+  }, useReviewActions: () => _classytic_arc_next0.CrudActions<Review, CreateReviewPayload, UpdateReviewPayload>, useReviewNavigation: () => _classytic_arc_next0.NavigateFn<Review>;
+declare function useMyReview(token: string | null | undefined, productId: string | null | undefined, options?: Omit<UseQueryOptions<ReviewResponse>, "queryKey" | "queryFn">): _tanstack_react_query0.UseQueryResult<ReviewResponse, Error>;
+//#endregion
+export { REVIEW_KEYS, reviewHooks, useMyReview, useReviewActions, useReviewDetail, useReviewNavigation, useReviews };

package/dist/catalog/hooks/review.js

@@ -0,0 +1,38 @@
+"use client";
+
+import { createCrudHooks } from "../../core/react/crud.factory.js";
+import { reviewApi } from "../api/review.js";
+import { useQuery } from "@tanstack/react-query";
+
+//#region src/catalog/hooks/review.ts
+/**
+* Review Hooks
+*
+* CRUD hooks + current user's review helper.
+*/
+const reviewHooks = createCrudHooks({
+	api: reviewApi,
+	entityKey: "reviews",
+	singular: "Review",
+	plural: "Reviews",
+	defaults: { staleTime: 300 * 1e3 }
+});
+const { KEYS: REVIEW_KEYS, useList: useReviews, useDetail: useReviewDetail, useActions: useReviewActions, useNavigation: useReviewNavigation } = reviewHooks;
+function useMyReview(token, productId, options = {}) {
+	return useQuery({
+		queryKey: [
+			...REVIEW_KEYS.all,
+			"my",
+			productId
+		],
+		queryFn: () => reviewApi.getMyReview({
+			token,
+			productId
+		}),
+		enabled: Boolean(token && productId),
+		...options
+	});
+}
+
+//#endregion
+export { REVIEW_KEYS, reviewHooks, useMyReview, useReviewActions, useReviewDetail, useReviewNavigation, useReviews };

package/dist/catalog/hooks/size-guide.d.ts

@@ -0,0 +1,136 @@
+import { ApiResponse } from "../../core/api-factory.js";
+import { CreateSizeGuidePayload, SizeGuide, UpdateSizeGuidePayload } from "../types/size-guide.js";
+import * as _tanstack_react_query0 from "@tanstack/react-query";
+import { UseQueryOptions } 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/catalog/hooks/size-guide.d.ts
+/**
+ * Size Guide CRUD hooks
+ */
+declare const sizeGuideHooks: _classytic_arc_next0.CrudHooksReturn<SizeGuide, CreateSizeGuidePayload, UpdateSizeGuidePayload>;
+declare const SIZE_GUIDE_KEYS: _classytic_arc_next_query0.QueryKeys, useSizeGuides: {
+    (params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<SizeGuide> | undefined): _classytic_arc_next_query0.ListQueryResult<SizeGuide>;
+    (token: string | null, params?: Record<string, unknown>, options?: _classytic_arc_next_query0.ListQueryOptions<SizeGuide> | undefined): _classytic_arc_next_query0.ListQueryResult<SizeGuide>;
+  }, useSizeGuideDetail: {
+    (id: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<SizeGuide> | undefined): _classytic_arc_next_query0.DetailQueryResult<SizeGuide>;
+    (id: string | null, token: string | null, options?: _classytic_arc_next_query0.DetailQueryOptions<SizeGuide> | undefined): _classytic_arc_next_query0.DetailQueryResult<SizeGuide>;
+  }, useSizeGuideActions: () => _classytic_arc_next0.CrudActions<SizeGuide, CreateSizeGuidePayload, UpdateSizeGuidePayload>, useSizeGuideNavigation: () => _classytic_arc_next0.NavigateFn<SizeGuide>;
+/**
+ * Hook to get size guide by slug
+ *
+ * @param token - Auth token (optional for public access)
+ * @param slug - Size guide slug
+ * @param options - React Query options
+ * @returns Query result with size guide data
+ *
+ * @example
+ * ```tsx
+ * function SizeGuideDisplay({ slug }) {
+ *   const { data, isLoading } = useSizeGuideBySlug(null, slug);
+ *
+ *   if (isLoading) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       <h2>{data?.data?.name}</h2>
+ *       <SizeTable guide={data?.data} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useSizeGuideBySlug(token: string | null | undefined, slug: string, options?: Omit<UseQueryOptions<ApiResponse<SizeGuide>>, "queryKey" | "queryFn">): _tanstack_react_query0.UseQueryResult<ApiResponse<SizeGuide>, Error>;
+/**
+ * Format size guide as select options
+ *
+ * @param sizeGuides - Array of size guides
+ * @returns Options array with value/label for select inputs
+ *
+ * @example
+ * ```tsx
+ * function SizeGuideSelect() {
+ *   const { data } = useSizeGuides(token);
+ *   const options = getSizeGuideOptions(data?.docs);
+ *
+ *   return (
+ *     <Select>
+ *       {options.map(opt => (
+ *         <SelectItem key={opt.value} value={opt.value}>
+ *           {opt.label}
+ *         </SelectItem>
+ *       ))}
+ *     </Select>
+ *   );
+ * }
+ * ```
+ */
+declare function getSizeGuideOptions(sizeGuides: SizeGuide[] | undefined): {
+  value: string;
+  label: string;
+}[];
+/**
+ * Get size guide by ID from a list
+ *
+ * @param sizeGuides - Array of size guides
+ * @param id - Size guide ID
+ * @returns Size guide or undefined
+ */
+declare function findSizeGuideById(sizeGuides: SizeGuide[] | undefined, id: string): SizeGuide | undefined;
+/**
+ * Get size guide by slug from a list
+ *
+ * @param sizeGuides - Array of size guides
+ * @param slug - Size guide slug
+ * @returns Size guide or undefined
+ */
+declare function findSizeGuideBySlug(sizeGuides: SizeGuide[] | undefined, slug: string): SizeGuide | undefined;
+/**
+ * Format measurement value with unit
+ *
+ * @param value - Measurement value
+ * @param unit - Measurement unit ('inches' or 'cm')
+ * @returns Formatted measurement string
+ *
+ * @example
+ * ```typescript
+ * formatMeasurement("34-36", "inches") // "34-36 in"
+ * formatMeasurement("88", "cm") // "88 cm"
+ * ```
+ */
+declare function formatMeasurement(value: string, unit: 'inches' | 'cm'): string;
+/**
+ * Get measurement labels as table headers
+ *
+ * @param guide - Size guide object
+ * @returns Array of header labels including "Size" as first column
+ *
+ * @example
+ * ```typescript
+ * const headers = getSizeTableHeaders(sizeGuide);
+ * // ["Size", "Chest", "Length", "Shoulder"]
+ * ```
+ */
+declare function getSizeTableHeaders(guide: SizeGuide | undefined): string[];
+/**
+ * Get size table rows
+ *
+ * @param guide - Size guide object
+ * @returns Array of row data with size name and measurements
+ *
+ * @example
+ * ```typescript
+ * const rows = getSizeTableRows(sizeGuide);
+ * // [
+ * //   { name: "S", measurements: { chest: "34-36", length: "28" } },
+ * //   { name: "M", measurements: { chest: "38-40", length: "29" } },
+ * // ]
+ * ```
+ */
+declare function getSizeTableRows(guide: SizeGuide | undefined): Array<{
+  name: string;
+  measurements: Record<string, string>;
+}>;
+//#endregion
+export { SIZE_GUIDE_KEYS, findSizeGuideById, findSizeGuideBySlug, formatMeasurement, getSizeGuideOptions, getSizeTableHeaders, getSizeTableRows, sizeGuideHooks, useSizeGuideActions, useSizeGuideBySlug, useSizeGuideDetail, useSizeGuideNavigation, useSizeGuides };

package/dist/catalog/hooks/size-guide.js

@@ -0,0 +1,173 @@
+"use client";
+
+import { createCrudHooks } from "../../core/react/crud.factory.js";
+import { sizeGuideApi } from "../api/size-guide.js";
+import { useQuery } from "@tanstack/react-query";
+
+//#region src/catalog/hooks/size-guide.ts
+/**
+* Size Guide Hooks
+*
+* Pre-built hooks for size guide CRUD operations with:
+* - Optimistic updates
+* - Smart caching
+* - Type safety
+*/
+/**
+* Size Guide CRUD hooks
+*/
+const sizeGuideHooks = createCrudHooks({
+	api: sizeGuideApi,
+	entityKey: "size-guides",
+	singular: "Size Guide",
+	plural: "Size Guides",
+	defaults: { staleTime: 1800 * 1e3 }
+});
+const { KEYS: SIZE_GUIDE_KEYS, useList: useSizeGuides, useDetail: useSizeGuideDetail, useActions: useSizeGuideActions, useNavigation: useSizeGuideNavigation } = sizeGuideHooks;
+/**
+* Hook to get size guide by slug
+*
+* @param token - Auth token (optional for public access)
+* @param slug - Size guide slug
+* @param options - React Query options
+* @returns Query result with size guide data
+*
+* @example
+* ```tsx
+* function SizeGuideDisplay({ slug }) {
+*   const { data, isLoading } = useSizeGuideBySlug(null, slug);
+*
+*   if (isLoading) return <Spinner />;
+*
+*   return (
+*     <div>
+*       <h2>{data?.data?.name}</h2>
+*       <SizeTable guide={data?.data} />
+*     </div>
+*   );
+* }
+* ```
+*/
+function useSizeGuideBySlug(token, slug, options = {}) {
+	return useQuery({
+		queryKey: [
+			...SIZE_GUIDE_KEYS.all,
+			"slug",
+			slug
+		],
+		queryFn: () => sizeGuideApi.getBySlug({
+			token,
+			slug
+		}),
+		enabled: !!slug,
+		staleTime: 1800 * 1e3,
+		...options
+	});
+}
+/**
+* Format size guide as select options
+*
+* @param sizeGuides - Array of size guides
+* @returns Options array with value/label for select inputs
+*
+* @example
+* ```tsx
+* function SizeGuideSelect() {
+*   const { data } = useSizeGuides(token);
+*   const options = getSizeGuideOptions(data?.docs);
+*
+*   return (
+*     <Select>
+*       {options.map(opt => (
+*         <SelectItem key={opt.value} value={opt.value}>
+*           {opt.label}
+*         </SelectItem>
+*       ))}
+*     </Select>
+*   );
+* }
+* ```
+*/
+function getSizeGuideOptions(sizeGuides) {
+	return (sizeGuides || []).map((guide) => ({
+		value: guide._id,
+		label: guide.name
+	}));
+}
+/**
+* Get size guide by ID from a list
+*
+* @param sizeGuides - Array of size guides
+* @param id - Size guide ID
+* @returns Size guide or undefined
+*/
+function findSizeGuideById(sizeGuides, id) {
+	return sizeGuides?.find((guide) => guide._id === id);
+}
+/**
+* Get size guide by slug from a list
+*
+* @param sizeGuides - Array of size guides
+* @param slug - Size guide slug
+* @returns Size guide or undefined
+*/
+function findSizeGuideBySlug(sizeGuides, slug) {
+	return sizeGuides?.find((guide) => guide.slug === slug);
+}
+/**
+* Format measurement value with unit
+*
+* @param value - Measurement value
+* @param unit - Measurement unit ('inches' or 'cm')
+* @returns Formatted measurement string
+*
+* @example
+* ```typescript
+* formatMeasurement("34-36", "inches") // "34-36 in"
+* formatMeasurement("88", "cm") // "88 cm"
+* ```
+*/
+function formatMeasurement(value, unit) {
+	return `${value} ${unit === "inches" ? "in" : "cm"}`;
+}
+/**
+* Get measurement labels as table headers
+*
+* @param guide - Size guide object
+* @returns Array of header labels including "Size" as first column
+*
+* @example
+* ```typescript
+* const headers = getSizeTableHeaders(sizeGuide);
+* // ["Size", "Chest", "Length", "Shoulder"]
+* ```
+*/
+function getSizeTableHeaders(guide) {
+	if (!guide?.measurementLabels) return ["Size"];
+	return ["Size", ...guide.measurementLabels];
+}
+/**
+* Get size table rows
+*
+* @param guide - Size guide object
+* @returns Array of row data with size name and measurements
+*
+* @example
+* ```typescript
+* const rows = getSizeTableRows(sizeGuide);
+* // [
+* //   { name: "S", measurements: { chest: "34-36", length: "28" } },
+* //   { name: "M", measurements: { chest: "38-40", length: "29" } },
+* // ]
+* ```
+*/
+function getSizeTableRows(guide) {
+	if (!guide?.sizes) return [];
+	return guide.sizes.map((size) => ({
+		name: size.name,
+		measurements: size.measurements
+	}));
+}
+
+//#endregion
+export { SIZE_GUIDE_KEYS, findSizeGuideById, findSizeGuideBySlug, formatMeasurement, getSizeGuideOptions, getSizeTableHeaders, getSizeTableRows, sizeGuideHooks, useSizeGuideActions, useSizeGuideBySlug, useSizeGuideDetail, useSizeGuideNavigation, useSizeGuides };