@classytic/commerce-sdk 0.1.2 → 0.2.1

package/dist/catalog/api/category.d.ts

@@ -0,0 +1,97 @@
+import { ApiResponse, BaseApi } from "../../core/api-factory.js";
+import { Category, CategoryTreeResponse, CreateCategoryPayload, UpdateCategoryPayload } from "../types/category.js";
+//#region src/catalog/api/category.d.ts
+type FetchOptions = {
+  cache?: RequestCache;
+  revalidate?: number;
+  tags?: string[];
+};
+/**
+ * Category API Client
+ * Extends BaseApi with category-specific endpoints
+ */
+declare class CategoryApi extends BaseApi<Category, CreateCategoryPayload, UpdateCategoryPayload> {
+  constructor(config?: {});
+  /**
+   * Get category tree (nested structure)
+   * GET /categories/tree
+   *
+   * **This is the main endpoint - FE should cache this and derive everything else from it.**
+   *
+   * Returns nested tree structure with children. Use helper functions to flatten, search, or extract children.
+   *
+   * @param token - Auth token (optional, public endpoint)
+   * @param options - Additional fetch options
+   * @returns Nested category tree
+   *
+   * @example
+   * ```typescript
+   * const { data } = await categoryApi.getTree({ token: null });
+   * // data = [{ slug: "clothing", name: "Clothing", children: [...] }]
+   * ```
+   */
+  getTree({
+    token,
+    options
+  }?: {
+    token?: string | null;
+    options?: FetchOptions;
+  }): Promise<CategoryTreeResponse>;
+  /**
+   * Get category by slug
+   * GET /categories/slug/:slug
+   *
+   * For URL resolution when you need full category details.
+   *
+   * @param token - Auth token (optional, public endpoint)
+   * @param slug - Category slug (e.g., "electronics", "t-shirts")
+   * @param options - Additional fetch options
+   * @returns Category object
+   *
+   * @example
+   * ```typescript
+   * const { data } = await categoryApi.getBySlug({
+   *   token: null,
+   *   slug: 'electronics'
+   * });
+   * ```
+   */
+  getBySlug({
+    token,
+    slug,
+    options
+  }: {
+    token?: string | null;
+    slug: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Category>>;
+  /**
+   * Sync product counts for all categories
+   * POST /categories/sync-product-count
+   *
+   * Recalculates `productCount` for all categories based on current products.
+   * Use when manual data fixes or migrations may have desynced counts.
+   *
+   * @param token - Auth token (admin or inventory staff required)
+   * @param options - Additional fetch options
+   * @returns Number of categories updated
+   *
+   * @example
+   * ```typescript
+   * const { data } = await categoryApi.syncProductCount({ token });
+   * // data = { updated: 42 }
+   * ```
+   */
+  syncProductCount({
+    token,
+    options
+  }: {
+    token: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<{
+    updated: number;
+  }>>;
+}
+declare const categoryApi: CategoryApi;
+//#endregion
+export { CategoryApi, categoryApi };

package/dist/catalog/api/category.js

@@ -0,0 +1,109 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/catalog/api/category.ts
+/**
+* Category API Client
+*
+* **Authentication:**
+* - Public: List, Get, Tree, GetBySlug
+* - Admin: Create, Update, Delete
+*
+* **Base URL:** `/api/v1/categories`
+*
+* **Slug-Based Design:**
+* - Categories use slugs as identifiers (not ObjectIds)
+* - Products store category as slug string for fast queries
+* - Example: `db.products.find({ category: "electronics" })`
+*/
+/**
+* Category API Client
+* Extends BaseApi with category-specific endpoints
+*/
+var CategoryApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("categories", config);
+	}
+	/**
+	* Get category tree (nested structure)
+	* GET /categories/tree
+	*
+	* **This is the main endpoint - FE should cache this and derive everything else from it.**
+	*
+	* Returns nested tree structure with children. Use helper functions to flatten, search, or extract children.
+	*
+	* @param token - Auth token (optional, public endpoint)
+	* @param options - Additional fetch options
+	* @returns Nested category tree
+	*
+	* @example
+	* ```typescript
+	* const { data } = await categoryApi.getTree({ token: null });
+	* // data = [{ slug: "clothing", name: "Clothing", children: [...] }]
+	* ```
+	*/
+	async getTree({ token = null, options = {} } = {}) {
+		return this.request("GET", `${this.baseUrl}/tree`, {
+			token: token || void 0,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+	/**
+	* Get category by slug
+	* GET /categories/slug/:slug
+	*
+	* For URL resolution when you need full category details.
+	*
+	* @param token - Auth token (optional, public endpoint)
+	* @param slug - Category slug (e.g., "electronics", "t-shirts")
+	* @param options - Additional fetch options
+	* @returns Category object
+	*
+	* @example
+	* ```typescript
+	* const { data } = await categoryApi.getBySlug({
+	*   token: null,
+	*   slug: 'electronics'
+	* });
+	* ```
+	*/
+	async getBySlug({ token = null, slug, options = {} }) {
+		if (!slug) throw new Error("Category slug is required");
+		return this.request("GET", `${this.baseUrl}/slug/${slug}`, {
+			token: token || void 0,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+	/**
+	* Sync product counts for all categories
+	* POST /categories/sync-product-count
+	*
+	* Recalculates `productCount` for all categories based on current products.
+	* Use when manual data fixes or migrations may have desynced counts.
+	*
+	* @param token - Auth token (admin or inventory staff required)
+	* @param options - Additional fetch options
+	* @returns Number of categories updated
+	*
+	* @example
+	* ```typescript
+	* const { data } = await categoryApi.syncProductCount({ token });
+	* // data = { updated: 42 }
+	* ```
+	*/
+	async syncProductCount({ token, options = {} }) {
+		return this.request("POST", `${this.baseUrl}/sync-product-count`, {
+			token,
+			options
+		});
+	}
+};
+const categoryApi = new CategoryApi();
+
+//#endregion
+export { CategoryApi, categoryApi };

package/dist/catalog/api/index.d.ts

@@ -0,0 +1,4 @@
+import { ProductApi, productApi } from "./product.js";
+import { CategoryApi, categoryApi } from "./category.js";
+import { SizeGuideApi, sizeGuideApi } from "./size-guide.js";
+import { ReviewApi, reviewApi } from "./review.js";

package/dist/catalog/api/product.d.ts

@@ -0,0 +1,136 @@
+import { ApiResponse, BaseApi, PaginatedResponse } from "../../core/api-factory.js";
+import { CreateProductPayload, Product, ProductSyncStockResponse, UpdateProductPayload } from "../types/product.js";
+//#region src/catalog/api/product.d.ts
+type FetchOptions = {
+  cache?: RequestCache;
+  revalidate?: number;
+  tags?: string[];
+};
+/**
+ * Product API Client
+ * Extends BaseApi with product-specific endpoints
+ */
+declare class ProductApi extends BaseApi<Product, CreateProductPayload, UpdateProductPayload> {
+  constructor(config?: {});
+  /**
+   * Get product by slug
+   * GET /products/slug/:slug
+   * (Public endpoint)
+   *
+   * @param token - Auth token (optional, public endpoint)
+   * @param slug - Product slug
+   * @param options - Additional fetch options
+   * @returns Product object
+   */
+  getBySlug({
+    token,
+    slug,
+    options
+  }: {
+    token?: string | null;
+    slug: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Product>>;
+  /**
+   * Get product recommendations
+   * GET /products/:id/recommendations
+   * (Public endpoint)
+   *
+   * @param token - Auth token (optional)
+   * @param productId - Product ID to get recommendations for
+   * @param options - Additional fetch options
+   * @returns List of recommended products
+   */
+  getRecommendations({
+    token,
+    productId,
+    options
+  }: {
+    token?: string | null;
+    productId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Product[]>>;
+  /**
+   * Get soft-deleted products (Recycle Bin)
+   * GET /products/deleted
+   * (Admin only)
+   *
+   * @param token - Auth token (required)
+   * @param params - Query parameters for pagination/filtering
+   * @param options - Additional fetch options
+   * @returns Paginated list of deleted products
+   */
+  getDeleted({
+    token,
+    params,
+    options
+  }: {
+    token: string;
+    params?: Record<string, unknown>;
+    options?: FetchOptions;
+  }): Promise<PaginatedResponse<Product>>;
+  /**
+   * Restore a soft-deleted product
+   * POST /products/:id/restore
+   * (Admin only)
+   *
+   * @param token - Auth token (required)
+   * @param id - Product ID to restore
+   * @param options - Additional fetch options
+   * @returns Restored product
+   */
+  restore({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Product>>;
+  /**
+   * Permanently delete a product (Hard delete)
+   * DELETE /products/:id?hard=true
+   * (Admin only - use with caution)
+   *
+   * @param token - Auth token (required)
+   * @param id - Product ID to permanently delete
+   * @param options - Additional fetch options
+   * @returns Delete confirmation
+   */
+  hardDelete({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<{
+    deleted: boolean;
+  }>>;
+  /**
+   * Sync product stock quantity
+   * POST /products/:id/sync-stock
+   *
+   * Recomputes product.quantity by summing all StockEntry quantities across branches.
+   * (Requires: admin, warehouse-admin, warehouse-staff, or store-manager role)
+   *
+   * @param token - Auth token (required)
+   * @param id - Product ID to sync stock for
+   * @param options - Additional fetch options
+   * @returns Sync result with new quantity
+   */
+  syncStock({
+    token,
+    id,
+    options
+  }: {
+    token: string;
+    id: string;
+    options?: FetchOptions;
+  }): Promise<ProductSyncStockResponse>;
+}
+declare const productApi: ProductApi;
+//#endregion
+export { ProductApi, productApi };

package/dist/catalog/api/product.js

@@ -0,0 +1,142 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/catalog/api/product.ts
+/**
+* Product API Client
+*
+* **Authentication:**
+* - Public: List, Get, GetBySlug, GetRecommendations
+* - Admin: Create, Update, Delete, GetDeleted, Restore, HardDelete, SyncStock
+*
+* **Base URL:** `/api/v1/products`
+*/
+/**
+* Product API Client
+* Extends BaseApi with product-specific endpoints
+*/
+var ProductApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("products", config);
+	}
+	/**
+	* Get product by slug
+	* GET /products/slug/:slug
+	* (Public endpoint)
+	*
+	* @param token - Auth token (optional, public endpoint)
+	* @param slug - Product slug
+	* @param options - Additional fetch options
+	* @returns Product object
+	*/
+	async getBySlug({ token = null, slug, options = {} }) {
+		if (!slug) throw new Error("Product slug is required");
+		return this.request("GET", `${this.baseUrl}/slug/${slug}`, {
+			token: token || void 0,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+	/**
+	* Get product recommendations
+	* GET /products/:id/recommendations
+	* (Public endpoint)
+	*
+	* @param token - Auth token (optional)
+	* @param productId - Product ID to get recommendations for
+	* @param options - Additional fetch options
+	* @returns List of recommended products
+	*/
+	async getRecommendations({ token = null, productId, options = {} }) {
+		if (!productId) throw new Error("Product ID is required");
+		return this.request("GET", `${this.baseUrl}/${productId}/recommendations`, {
+			token: token || void 0,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+	/**
+	* Get soft-deleted products (Recycle Bin)
+	* GET /products/deleted
+	* (Admin only)
+	*
+	* @param token - Auth token (required)
+	* @param params - Query parameters for pagination/filtering
+	* @param options - Additional fetch options
+	* @returns Paginated list of deleted products
+	*/
+	async getDeleted({ token, params = {}, options = {} }) {
+		return this.request("GET", `${this.baseUrl}/deleted`, {
+			token,
+			params,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+	/**
+	* Restore a soft-deleted product
+	* POST /products/:id/restore
+	* (Admin only)
+	*
+	* @param token - Auth token (required)
+	* @param id - Product ID to restore
+	* @param options - Additional fetch options
+	* @returns Restored product
+	*/
+	async restore({ token, id, options = {} }) {
+		if (!id) throw new Error("Product ID is required");
+		return this.request("POST", `${this.baseUrl}/${id}/restore`, {
+			token,
+			options
+		});
+	}
+	/**
+	* Permanently delete a product (Hard delete)
+	* DELETE /products/:id?hard=true
+	* (Admin only - use with caution)
+	*
+	* @param token - Auth token (required)
+	* @param id - Product ID to permanently delete
+	* @param options - Additional fetch options
+	* @returns Delete confirmation
+	*/
+	async hardDelete({ token, id, options = {} }) {
+		if (!id) throw new Error("Product ID is required");
+		return this.delete({
+			token,
+			id,
+			options: {
+				...options,
+				params: { hard: "true" }
+			}
+		});
+	}
+	/**
+	* Sync product stock quantity
+	* POST /products/:id/sync-stock
+	*
+	* Recomputes product.quantity by summing all StockEntry quantities across branches.
+	* (Requires: admin, warehouse-admin, warehouse-staff, or store-manager role)
+	*
+	* @param token - Auth token (required)
+	* @param id - Product ID to sync stock for
+	* @param options - Additional fetch options
+	* @returns Sync result with new quantity
+	*/
+	async syncStock({ token, id, options = {} }) {
+		if (!id) throw new Error("Product ID is required");
+		return this.request("POST", `${this.baseUrl}/${id}/sync-stock`, {
+			token,
+			options
+		});
+	}
+};
+const productApi = new ProductApi();
+
+//#endregion
+export { ProductApi, productApi };

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

@@ -0,0 +1,32 @@
+import { ApiResponse, BaseApi } from "../../core/api-factory.js";
+import { CreateReviewPayload, Review, UpdateReviewPayload } from "../types/review.js";
+//#region src/catalog/api/review.d.ts
+type FetchOptions = {
+  cache?: RequestCache;
+  revalidate?: number;
+  tags?: string[];
+};
+declare class ReviewApi extends BaseApi<Review, CreateReviewPayload, UpdateReviewPayload> {
+  constructor(config?: {});
+  /**
+   * Get current user's review for a product
+   * GET /reviews/my/:productId
+   *
+   * @param token - Auth token (required)
+   * @param productId - Product ID
+   * @param options - Additional fetch options
+   * @returns Review or null
+   */
+  getMyReview({
+    token,
+    productId,
+    options
+  }: {
+    token: string;
+    productId: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<Review | null>>;
+}
+declare const reviewApi: ReviewApi;
+//#endregion
+export { ReviewApi, reviewApi };

package/dist/catalog/api/review.js

@@ -0,0 +1,41 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/catalog/api/review.ts
+/**
+* Review API Client
+*
+* **Authentication:**
+* - Public: List, Get
+* - User/Admin: Create, Update, Get My Review
+* - Admin: Delete
+*
+* **Base URL:** `/api/v1/reviews`
+*/
+var ReviewApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("reviews", config);
+	}
+	/**
+	* Get current user's review for a product
+	* GET /reviews/my/:productId
+	*
+	* @param token - Auth token (required)
+	* @param productId - Product ID
+	* @param options - Additional fetch options
+	* @returns Review or null
+	*/
+	async getMyReview({ token, productId, options = {} }) {
+		if (!productId) throw new Error("Product ID is required");
+		return this.request("GET", `${this.baseUrl}/my/${productId}`, {
+			token,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+};
+const reviewApi = new ReviewApi();
+
+//#endregion
+export { ReviewApi, reviewApi };

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

@@ -0,0 +1,46 @@
+import { ApiResponse, BaseApi } from "../../core/api-factory.js";
+import { CreateSizeGuidePayload, SizeGuide, UpdateSizeGuidePayload } from "../types/size-guide.js";
+//#region src/catalog/api/size-guide.d.ts
+type FetchOptions = {
+  cache?: RequestCache;
+  revalidate?: number;
+  tags?: string[];
+};
+/**
+ * Size Guide API Client
+ * Extends BaseApi with size-guide-specific endpoints
+ */
+declare class SizeGuideApi extends BaseApi<SizeGuide, CreateSizeGuidePayload, UpdateSizeGuidePayload> {
+  constructor(config?: {});
+  /**
+   * Get size guide by slug
+   * GET /size-guides/slug/:slug
+   *
+   * For product detail pages to fetch the appropriate size guide.
+   *
+   * @param token - Auth token (optional, public endpoint)
+   * @param slug - Size guide slug (e.g., "t-shirts-tops")
+   * @param options - Additional fetch options
+   * @returns Size guide object
+   *
+   * @example
+   * ```typescript
+   * const { data } = await sizeGuideApi.getBySlug({
+   *   token: null,
+   *   slug: 't-shirts-tops'
+   * });
+   * ```
+   */
+  getBySlug({
+    token,
+    slug,
+    options
+  }: {
+    token?: string | null;
+    slug: string;
+    options?: FetchOptions;
+  }): Promise<ApiResponse<SizeGuide>>;
+}
+declare const sizeGuideApi: SizeGuideApi;
+//#endregion
+export { SizeGuideApi, sizeGuideApi };

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

@@ -0,0 +1,58 @@
+import { BaseApi } from "../../core/api-factory.js";
+
+//#region src/catalog/api/size-guide.ts
+/**
+* Size Guide API Client
+*
+* **Authentication:**
+* - Public: List, Get, GetBySlug
+* - Admin: Create, Update, Delete
+*
+* **Base URL:** `/api/v1/size-guides`
+*
+* **Slug-Based Design:**
+* - Size guides use slugs as identifiers
+* - Products store `sizeGuideSlug` to reference a size guide
+*/
+/**
+* Size Guide API Client
+* Extends BaseApi with size-guide-specific endpoints
+*/
+var SizeGuideApi = class extends BaseApi {
+	constructor(config = {}) {
+		super("size-guides", config);
+	}
+	/**
+	* Get size guide by slug
+	* GET /size-guides/slug/:slug
+	*
+	* For product detail pages to fetch the appropriate size guide.
+	*
+	* @param token - Auth token (optional, public endpoint)
+	* @param slug - Size guide slug (e.g., "t-shirts-tops")
+	* @param options - Additional fetch options
+	* @returns Size guide object
+	*
+	* @example
+	* ```typescript
+	* const { data } = await sizeGuideApi.getBySlug({
+	*   token: null,
+	*   slug: 't-shirts-tops'
+	* });
+	* ```
+	*/
+	async getBySlug({ token = null, slug, options = {} }) {
+		if (!slug) throw new Error("Size guide slug is required");
+		return this.request("GET", `${this.baseUrl}/slug/${slug}`, {
+			token: token || void 0,
+			options: {
+				cache: this.config.cache,
+				...options
+			}
+		});
+	}
+};
+const sizeGuideApi = new SizeGuideApi();
+
+//#endregion
+export { SizeGuideApi, sizeGuideApi };