@classytic/commerce-sdk 0.1.1 → 0.2.1

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

@@ -0,0 +1,168 @@
+//#region src/catalog/types/category.d.ts
+/**
+ * Category Types
+ *
+ * Source of truth: modules/commerce/category/category.model.js
+ *
+ * **Slug-Based Design:**
+ * - Products store `category` as slug string (not ObjectId)
+ * - Enables fast queries without $lookup/aggregation
+ * - Example: `db.products.find({ category: "electronics" })`
+ *
+ * **Product Count:**
+ * - Automatically maintained via product repository events
+ * - Increments on product create
+ * - Decrements on product delete
+ * - Updates when product changes category
+ */
+interface CategoryImage {
+  url?: string;
+  alt?: string;
+}
+interface CategorySeo {
+  title?: string;
+  description?: string;
+  keywords?: string[];
+}
+interface Category {
+  _id: string;
+  /** Display name (can be changed without breaking product references) */
+  name: string;
+  /**
+   * URL-safe identifier (auto-generated from name, globally unique).
+   * Products store this value in their `category` field.
+   * IMMUTABLE after creation.
+   */
+  slug: string;
+  /**
+   * Parent category slug (not ObjectId).
+   * null for root categories.
+   */
+  parent: string | null;
+  /** Short description for category listing */
+  description?: string;
+  /** Category image for display */
+  image?: CategoryImage;
+  /** Display order for sorting (lower = first) */
+  displayOrder: number;
+  /**
+   * Category-specific VAT rate override.
+   * null = use platform default rate.
+   */
+  vatRate?: number | null;
+  /** Whether category is visible to customers */
+  isActive: boolean;
+  /**
+   * Cached product count (maintained by product repository events).
+   * Updated automatically on product create/delete/category-change.
+   */
+  productCount: number;
+  /** SEO metadata */
+  seo?: CategorySeo;
+  createdAt: string;
+  updatedAt: string;
+  /** Full path e.g. "clothing/t-shirts" */
+  fullPath?: string;
+  /** Whether this is a root category (no parent) */
+  isRoot?: boolean;
+}
+/**
+ * Category with nested children for tree display
+ * Used for navigation menus and admin selects
+ *
+ * **To flatten for dropdowns:**
+ * ```typescript
+ * function flattenTree(nodes, depth = 0, result = []) {
+ *   for (const n of nodes) {
+ *     result.push({ ...n, depth, displayName: '  '.repeat(depth) + n.name });
+ *     if (n.children) flattenTree(n.children, depth + 1, result);
+ *   }
+ *   return result;
+ * }
+ * ```
+ */
+interface CategoryTreeNode extends Category {
+  /** Child categories (empty array for leaf nodes) */
+  children?: CategoryTreeNode[];
+}
+interface CreateCategoryPayload {
+  /** Required: Display name (slug auto-generated from this) */
+  name: string;
+  /** Parent category slug (not ObjectId) */
+  parent?: string;
+  /** Short description */
+  description?: string;
+  /** Category image */
+  image?: CategoryImage;
+  /** Display order (lower = first, default: 0) */
+  displayOrder?: number;
+  /** VAT rate override (null = use platform default) */
+  vatRate?: number | null;
+  /** Whether visible to customers (default: true) */
+  isActive?: boolean;
+  /** SEO metadata */
+  seo?: CategorySeo;
+}
+interface UpdateCategoryPayload {
+  /** Display name (slug is immutable, cannot be changed) */
+  name?: string;
+  /** Short description */
+  description?: string;
+  /** Category image */
+  image?: CategoryImage;
+  /** Display order */
+  displayOrder?: number;
+  /** VAT rate override */
+  vatRate?: number | null;
+  /** Visibility */
+  isActive?: boolean;
+  /** SEO metadata */
+  seo?: CategorySeo;
+}
+/**
+ * Response from GET /categories (paginated list)
+ */
+interface CategoryListResponse {
+  success: boolean;
+  method: "offset";
+  docs: Category[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Response from GET /categories/tree
+ */
+interface CategoryTreeResponse {
+  success: boolean;
+  data: CategoryTreeNode[];
+}
+/**
+ * Response from GET /categories/:id or /categories/slug/:slug
+ */
+interface CategoryResponse {
+  success: boolean;
+  data: Category;
+}
+/**
+ * Response from DELETE /categories/:id
+ */
+interface CategoryDeleteResponse {
+  success: boolean;
+  deleted: boolean;
+  message?: string;
+}
+/**
+ * Response from POST /categories/sync-product-count
+ */
+interface CategorySyncResponse {
+  success: boolean;
+  data: {
+    updated: number;
+  };
+}
+//#endregion
+export { Category, CategoryDeleteResponse, CategoryImage, CategoryListResponse, CategoryResponse, CategorySeo, CategorySyncResponse, CategoryTreeNode, CategoryTreeResponse, CreateCategoryPayload, UpdateCategoryPayload };

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

@@ -0,0 +1,4 @@
+import { CreateProductPayload, Dimensions, Product, ProductDeleteResponse, ProductDiscount, ProductImage, ProductListResponse, ProductResponse, ProductShipping, ProductStats, ProductSyncStockResponse, ProductVariant, StockProjection, UpdateProductPayload, VariationAttribute } from "./product.js";
+import { Category, CategoryDeleteResponse, CategoryImage, CategoryListResponse, CategoryResponse, CategorySeo, CategorySyncResponse, CategoryTreeNode, CategoryTreeResponse, CreateCategoryPayload, UpdateCategoryPayload } from "./category.js";
+import { CreateSizeGuidePayload, SizeDefinition, SizeGuide, SizeGuideDeleteResponse, SizeGuideListResponse, SizeGuideResponse, UpdateSizeGuidePayload } from "./size-guide.js";
+import { CreateReviewPayload, Review, ReviewListResponse, ReviewReply, ReviewResponse, ReviewStatus, UpdateReviewPayload } from "./review.js";

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

@@ -0,0 +1,261 @@
+//#region src/catalog/types/product.d.ts
+/**
+ * Product Types
+ *
+ * Source of truth: modules/commerce/product/product.model.js
+ */
+/**
+ * Image Schema
+ */
+interface ProductImage {
+  url: string;
+  variants?: {
+    thumbnail?: string;
+    medium?: string;
+  };
+  order?: number;
+  isFeatured?: boolean;
+  alt?: string;
+}
+/**
+ * Dimensions Schema
+ */
+interface Dimensions {
+  length?: number;
+  width?: number;
+  height?: number;
+}
+/**
+ * Shipping Schema
+ */
+interface ProductShipping {
+  weightGrams?: number;
+  dimensionsCm?: Dimensions;
+}
+/**
+ * Variation Attribute (Defines options)
+ * e.g. { name: "Size", values: ["S", "M", "L"] }
+ */
+interface VariationAttribute {
+  name: string;
+  values: string[];
+}
+/**
+ * Variant (Sellable SKU)
+ */
+interface ProductVariant {
+  sku: string;
+  barcode?: string;
+  attributes: Record<string, string>;
+  priceModifier: number;
+  /**
+   * System calculated field (Read-only for frontend)
+   * COGS for this specific variant
+   */
+  costPrice?: number;
+  /**
+   * VAT rate override for this specific variant
+   * null = inherit from product/category/platform
+   */
+  vatRate?: number | null;
+  images?: ProductImage[];
+  shipping?: ProductShipping;
+  isActive?: boolean;
+}
+/**
+ * Discount Schema
+ */
+interface ProductDiscount {
+  type: 'percentage' | 'fixed';
+  value: number;
+  startDate?: string;
+  endDate?: string;
+  description?: string;
+}
+/**
+ * Product Stats (System Generated)
+ */
+interface ProductStats {
+  totalSales: number;
+  totalQuantitySold: number;
+  viewCount: number;
+}
+/**
+ * Stock Projection for Variant Products (Read-Only)
+ * Provides fast storefront availability checks
+ */
+interface StockProjection {
+  variants: Array<{
+    sku: string;
+    quantity: number;
+  }>;
+  syncedAt: string;
+}
+/**
+ * Main Product Interface (Read Model)
+ */
+interface Product {
+  _id: string;
+  name: string;
+  slug: string;
+  shortDescription?: string;
+  description?: string;
+  basePrice: number;
+  /**
+   * System field: Cost of Goods Sold
+   * Not editable by customer. Admin only.
+   * Role-restricted field - only visible to authorized roles
+   */
+  costPrice?: number;
+  /**
+   * VAT rate override for this product
+   * null = inherit from category/platform default
+   */
+  vatRate?: number | null;
+  /**
+   * System field: Total stock quantity across all branches.
+   * Read-only cache. Source of truth is Inventory Service.
+   */
+  quantity: number;
+  /**
+   * Product type: 'simple' for regular products, 'variant' for products with variations
+   * Auto-determined by backend based on presence of variationAttributes
+   */
+  productType: 'simple' | 'variant';
+  sku?: string;
+  barcode?: string;
+  images: ProductImage[];
+  /**
+   * Category slug (references Category.slug, not ObjectId).
+   * Enables direct string queries without $lookup.
+   * @see Category model for metadata (name, image, description)
+   */
+  category: string;
+  /**
+   * Parent category slug (optional, for hierarchical filtering)
+   */
+  parentCategory?: string | null;
+  style?: string[];
+  variationAttributes?: VariationAttribute[];
+  variants?: ProductVariant[];
+  shipping?: ProductShipping;
+  properties?: Record<string, any>;
+  tags?: string[];
+  stats?: ProductStats;
+  averageRating?: number;
+  numReviews?: number;
+  /**
+   * Stock projection for variant products (Read-Only)
+   * Contains aggregated stock quantities per variant across all branches
+   */
+  stockProjection?: StockProjection;
+  discount?: ProductDiscount;
+  /**
+   * Size guide reference (ObjectId of SizeGuide document)
+   * Optional - only for products with sizing information
+   */
+  sizeGuide?: string | null;
+  isActive: boolean;
+  deletedAt?: string | null;
+  createdAt: string;
+  updatedAt: string;
+  isDiscountActive?: boolean;
+  currentPrice?: number;
+  featuredImage?: ProductImage | null;
+  profitMargin?: number | null;
+  profitMarginPercent?: number | null;
+  isDeleted?: boolean;
+}
+/**
+ * Payload for Creating a Product
+ */
+interface CreateProductPayload {
+  name: string;
+  shortDescription?: string;
+  description?: string;
+  basePrice: number;
+  costPrice?: number;
+  vatRate?: number | null;
+  productType?: 'simple' | 'variant';
+  sku?: string;
+  barcode?: string;
+  images?: ProductImage[];
+  category: string;
+  parentCategory?: string;
+  style?: string[];
+  variationAttributes?: VariationAttribute[];
+  variants?: ProductVariant[];
+  shipping?: ProductShipping;
+  properties?: Record<string, any>;
+  tags?: string[];
+  discount?: ProductDiscount;
+  sizeGuide?: string | null;
+  isActive?: boolean;
+}
+/**
+ * Payload for Updating a Product
+ */
+interface UpdateProductPayload {
+  name?: string;
+  shortDescription?: string;
+  description?: string;
+  basePrice?: number;
+  costPrice?: number;
+  vatRate?: number | null;
+  productType?: 'simple' | 'variant';
+  sku?: string;
+  barcode?: string;
+  images?: ProductImage[];
+  category?: string;
+  parentCategory?: string;
+  style?: string[];
+  variationAttributes?: VariationAttribute[];
+  variants?: ProductVariant[];
+  shipping?: ProductShipping;
+  properties?: Record<string, any>;
+  tags?: string[];
+  discount?: ProductDiscount;
+  sizeGuide?: string | null;
+  isActive?: boolean;
+}
+/**
+ * Response from GET /products (paginated list)
+ */
+interface ProductListResponse {
+  success: boolean;
+  method: "offset";
+  docs: Product[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Response from GET /products/:id or /products/slug/:slug
+ */
+interface ProductResponse {
+  success: boolean;
+  data: Product;
+}
+/**
+ * Response from DELETE /products/:id
+ */
+interface ProductDeleteResponse {
+  success: boolean;
+  deleted: boolean;
+  message?: string;
+}
+/**
+ * Response from POST /products/:id/sync-stock
+ */
+interface ProductSyncStockResponse {
+  success: boolean;
+  productId: string;
+  totalQuantity: number;
+  synced: boolean;
+  errors: any[];
+}
+//#endregion
+export { CreateProductPayload, Dimensions, Product, ProductDeleteResponse, ProductDiscount, ProductImage, ProductListResponse, ProductResponse, ProductShipping, ProductStats, ProductSyncStockResponse, ProductVariant, StockProjection, UpdateProductPayload, VariationAttribute };

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

@@ -0,0 +1,48 @@
+import { ApiResponse, PaginatedResponse } from "../../core/api-factory.js";
+import { Product } from "./product.js";
+
+//#region src/catalog/types/review.d.ts
+type ReviewStatus = "pending" | "approved" | "rejected";
+interface ReviewReply {
+  content?: string;
+  repliedBy?: string | {
+    _id: string;
+    name?: string;
+    email?: string;
+  };
+  repliedAt?: string;
+}
+interface Review {
+  _id: string;
+  user: string | {
+    _id: string;
+    name?: string;
+    email?: string;
+  };
+  product: string | Product;
+  order?: string;
+  title?: string;
+  rating: number;
+  comment?: string;
+  helpfulCount: number;
+  isVerifiedPurchase: boolean;
+  status: ReviewStatus;
+  reply?: ReviewReply;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateReviewPayload {
+  product: string;
+  rating: number;
+  title?: string;
+  comment?: string;
+}
+interface UpdateReviewPayload {
+  rating?: number;
+  title?: string;
+  comment?: string;
+}
+type ReviewResponse = ApiResponse<Review | null>;
+type ReviewListResponse = PaginatedResponse<Review>;
+//#endregion
+export { CreateReviewPayload, Review, ReviewListResponse, ReviewReply, ReviewResponse, ReviewStatus, UpdateReviewPayload };

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

@@ -0,0 +1,118 @@
+//#region src/catalog/types/size-guide.d.ts
+/**
+ * Size Guide Types
+ *
+ * Size guides are templates that can be referenced by products to display size information.
+ * Products store `sizeGuideSlug` to reference a size guide.
+ *
+ * **Dynamic Measurements:**
+ * - `measurementLabels` define the columns (e.g., ["Chest", "Length", "Shoulder"])
+ * - Each size has a `measurements` object with key-value pairs
+ * - Keys are lowercase/underscored versions of labels (e.g., "chest", "length")
+ */
+interface SizeDefinition {
+  /** Size name (e.g., "XS", "S", "M", "L", "XL") */
+  name: string;
+  /**
+   * Key-value pairs of measurements.
+   * Keys should match measurementLabels (lowercase, underscored).
+   * Values are strings to support ranges (e.g., "34-36").
+   */
+  measurements: Record<string, string>;
+}
+interface SizeGuide {
+  _id: string;
+  /** Size guide name (e.g., "T-Shirts & Tops") */
+  name: string;
+  /**
+   * URL-safe identifier (auto-generated from name, globally unique).
+   * Products store this value in their `sizeGuideSlug` field.
+   */
+  slug: string;
+  /** Size guide description (max 500 chars) */
+  description?: string;
+  /** Measurement unit: 'inches' or 'cm' */
+  measurementUnit: 'inches' | 'cm';
+  /**
+   * Array of measurement labels (e.g., ["Chest", "Length", "Shoulder", "Sleeve"]).
+   * Used as table column headers. Max 10 labels.
+   */
+  measurementLabels: string[];
+  /** Array of size definitions with measurements */
+  sizes: SizeDefinition[];
+  /** Additional notes for customers (max 1000 chars) */
+  note?: string;
+  /** Whether size guide is visible to customers */
+  isActive: boolean;
+  /** Display order for sorting (lower = first) */
+  displayOrder: number;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateSizeGuidePayload {
+  /** Required: Size guide name (slug auto-generated from this) */
+  name: string;
+  /** Custom slug (optional, auto-generated if not provided) */
+  slug?: string;
+  /** Size guide description */
+  description?: string;
+  /** Measurement unit (default: 'inches') */
+  measurementUnit?: 'inches' | 'cm';
+  /** Measurement labels (max 10) */
+  measurementLabels?: string[];
+  /** Size definitions */
+  sizes?: SizeDefinition[];
+  /** Additional notes */
+  note?: string;
+  /** Whether visible to customers (default: true) */
+  isActive?: boolean;
+  /** Display order (default: 0) */
+  displayOrder?: number;
+}
+interface UpdateSizeGuidePayload {
+  /** Size guide name */
+  name?: string;
+  /** Size guide description */
+  description?: string;
+  /** Measurement unit */
+  measurementUnit?: 'inches' | 'cm';
+  /** Measurement labels (replaces existing) */
+  measurementLabels?: string[];
+  /** Size definitions (replaces existing) */
+  sizes?: SizeDefinition[];
+  /** Additional notes */
+  note?: string;
+  /** Visibility */
+  isActive?: boolean;
+  /** Display order */
+  displayOrder?: number;
+}
+/**
+ * Response from GET /size-guides (paginated list)
+ */
+interface SizeGuideListResponse {
+  success: boolean;
+  docs: SizeGuide[];
+  page: number;
+  limit: number;
+  total: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+/**
+ * Response from GET /size-guides/:id or /size-guides/slug/:slug
+ */
+interface SizeGuideResponse {
+  success: boolean;
+  data: SizeGuide;
+}
+/**
+ * Response from DELETE /size-guides/:id
+ */
+interface SizeGuideDeleteResponse {
+  success: boolean;
+  message?: string;
+}
+//#endregion
+export { CreateSizeGuidePayload, SizeDefinition, SizeGuide, SizeGuideDeleteResponse, SizeGuideListResponse, SizeGuideResponse, UpdateSizeGuidePayload };