Dynamic Commerce

X · LinkedIn

[!WARNING] This project is under active development and is not ready for production use. Please proceed with caution. Use at your own risk.

Products Module

📚 Documentation: 86d.app/docs/modules/products

Product catalog module with variants and hierarchical categories. Full CRUD for the admin panel and read-only browsing with search and filtering for the storefront.

Installation

npm install @86d-app/products

Usage

import products from "@86d-app/products";

const module = products({
  defaultPageSize: 20,
  maxPageSize: 100,
  trackInventory: true,
});

Configuration

Store Endpoints

Query parameters for GET /products:

Admin Endpoints

Service API

A typed service layer is available via createProductController(data) from service-impl.ts:

import { createProductController } from "@86d-app/products/service-impl";

const ctrl = createProductController(dataService);
const product = await ctrl.createProduct({ name: "Widget", slug: "widget", price: 2999 });
const variants = await ctrl.getVariantsByProduct(product.id);
await ctrl.addProductToCollection(collectionId, product.id);
const result = await ctrl.importProducts([{ name: "Gadget", price: 19.99 }]);

Controller API

Controllers are accessed via the runtime context. Five sub-controllers are available: product, variant, category, bulk, collection, and import.

// product controller
context.controllers.product.getById(ctx)        // Product | null
context.controllers.product.getBySlug(ctx)       // Product | null
context.controllers.product.getWithVariants(ctx) // ProductWithVariants | null
context.controllers.product.list(ctx)            // { products: Product[]; total: number }
context.controllers.product.create(ctx)          // Product
context.controllers.product.update(ctx)          // Product | null
context.controllers.product.delete(ctx)          // void

// variant controller
context.controllers.variant.create(ctx)          // ProductVariant
context.controllers.variant.update(ctx)          // ProductVariant | null
context.controllers.variant.delete(ctx)          // void

// category controller
context.controllers.category.getById(ctx)        // Category | null
context.controllers.category.getBySlug(ctx)      // Category | null
context.controllers.category.list(ctx)           // { categories: Category[]; total: number }
context.controllers.category.getTree(ctx)        // Category[]  (hierarchical)
context.controllers.category.create(ctx)         // Category
context.controllers.category.update(ctx)         // Category | null
context.controllers.category.delete(ctx)         // void

Each controller method receives a ctx object:

{
  context: { data: ModuleDataService };
  params: Record<string, string>;
  query: Record<string, string>;
  body: Record<string, unknown>;
}

Types

interface Product {
  id: string;
  name: string;
  slug: string;
  description?: string;
  shortDescription?: string;
  price: number;               // in cents
  compareAtPrice?: number;
  costPrice?: number;
  sku?: string;
  barcode?: string;
  inventory: number;
  trackInventory: boolean;
  allowBackorder: boolean;
  status: "draft" | "active" | "archived";
  categoryId?: string;
  images: string[];
  tags: string[];
  isFeatured: boolean;
  weight?: number;
  weightUnit?: "kg" | "lb" | "oz" | "g";
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

interface ProductVariant {
  id: string;
  productId: string;
  name: string;
  sku?: string;
  price: number;
  compareAtPrice?: number;
  costPrice?: number;
  inventory: number;
  options: Record<string, string>; // e.g. { size: "M", color: "Blue" }
  images: string[];
  position: number;
  weight?: number;
  weightUnit?: "kg" | "lb" | "oz" | "g";
  createdAt: Date;
  updatedAt: Date;
}

interface Category {
  id: string;
  name: string;
  slug: string;
  description?: string;
  parentId?: string;           // Self-referential for nested categories
  image?: string;
  position: number;
  isVisible: boolean;
  metadata?: Record<string, unknown>;
  createdAt: Date;
  updatedAt: Date;
}

interface ProductWithVariants extends Product {
  variants: ProductVariant[];
  category?: Category;
}

Store Components

ProductCard

Displays a single product card with image, name, price, discount badge, and optional "Add to Cart" button.

Props

Usage in MDX

<ProductCard product={product} />

<ProductCard product={product} showAddToCart={false} />

FeaturedProducts

Displays a responsive grid of featured products. Fetches its own data.

Props

Usage in MDX

<FeaturedProducts />

<FeaturedProducts limit={4} title="Staff Picks" />

ProductListing

Full product listing with search, category/price/stock/tag filters, sorting, and pagination. Fetches its own data.

Props

Usage in MDX

<ProductListing />

<ProductListing initialCategory="shoes" pageSize={12} />

ProductDetail

Full product detail page with image gallery, variant selector, pricing, inventory status, reviews, and related products. Fetches its own data.

Props

Usage

Loaded dynamically by the store catch-all route for /products/:slug.

RelatedProducts

Horizontal grid of related products for a given product. Fetches its own data.

Props

Usage in MDX

<RelatedProducts productId={product.id} />

<RelatedProducts productId={product.id} limit={4} title="You may also like" />

CollectionCard

Displays a single collection card with image, name, and description.

Props

Usage in MDX

<CollectionCard collection={collection} />

CollectionGrid

Grid of collections with optional featured-only filtering. Fetches its own data.

Props

Usage in MDX

<CollectionGrid />

<CollectionGrid title="Shop by Category" featured={true} />

CollectionDetail

Full collection page with image, description, product count, and products grid. Fetches its own data.

Props

Usage

Loaded dynamically by the store catch-all route for /collections/:slug.

FilterChip

Small removable tag displaying an active filter. Used internally by ProductListing.

Props

Usage in MDX

<FilterChip label="Shoes" onRemove={handleRemove} />

StarDisplay

Read-only star rating display.

Props

Usage in MDX

<StarDisplay rating={4.5} />

<StarDisplay rating={product.averageRating} size="sm" />

StarPicker

Interactive star rating input for review submission.

Props

Usage in MDX

<StarPicker value={rating} onChange={setRating} />

StockBadge

Inventory status badge. Shows "Out of stock", "Only X left", or "In stock".

Props

Usage in MDX

<StockBadge inventory={product.inventory} />

ProductReviewsSection

Complete review section with rating summary, review list with pagination, and review submission form. Fetches its own data.

Props

Usage in MDX

<ProductReviewsSection productId={product.id} />

Notes

• Store endpoints return only active products; admin endpoints return all statuses (draft, active, archived).
• Product IDs are prefixed: prod_ (UUID in service-impl, timestamp in raw controllers). Variant: var_, Category: cat_, Collection: col_.
• Deleting a category orphans its child categories and products (sets categoryId/parentId to undefined) rather than cascading.
• Deleting a product cascades to all its variants. Deleting a collection cascades to collection-product links.
• getTree() builds a hierarchical category tree from the flat list using parentId references.
• addProductToCollection prevents duplicates — returns existing link if product is already in the collection.
• Import converts dollar prices to cents (price * 100), resolves categories by name (case-insensitive), and deduplicates slugs.
• Inventory decrement has no floor — inventory can go negative (documented behavior).
• Products with trackInventory: false skip all inventory decrement/increment operations.