@86d-app/products

The Modern Foundation for Commerce

X · LinkedIn

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

Products Module

New Product and Variant prices are integer minor units. Inventory owns stock, so Product stock mutations are rejected. Collections owns Collection writes; the Products collection routes are compatibility reads only. Direct import is unavailable while its upload, diagnostics, diff, and Review transport remain unfinished. The owner-local immutable revision and presentation projection exist, but import, admin CRUD, and live product-feed generation have not moved to that path yet.

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

Option	Type	Default	Description
defaultPageSize	number	20	Default number of products per page
maxPageSize	number	100	Maximum products per page
trackInventory	boolean	true	Enable inventory tracking by default

Store Endpoints

Method	Path	Description
GET	/products	List active products (paginated, filterable)
GET	/products/featured	Get featured products
GET	/products/:slug	Get a single product by slug (includes variants)
GET	/products/search?q=	Search products by name, description, or tags
GET	/products/store-search	Full-text product search
GET	/products/related/:id	Get related products by category/tag scoring
GET	/categories	List visible categories
GET	/categories/:slug	Get a single category by slug
GET	/collections	List visible collections
GET	/collections/:slug	Get a collection with its active products

Query parameters for GET /products:

Param	Type	Description
page	number	Page number (default 1)
limit	number	Items per page (capped at maxPageSize)
category	string	Filter by category slug
status	string	Product status (storefront always uses active)
featured	boolean	Filter featured products

Admin Endpoints

Method	Path	Description
POST	/admin/products	Create a new product
GET	/admin/products/list	List all products (all statuses)
GET	/admin/products/:id	Get a product by ID
PUT	/admin/products/:id	Update a product
DELETE	/admin/products/:id	Delete a product
POST	/admin/products/:productId/variants	Add a variant to a product
PUT	/admin/variants/:id	Update a variant
DELETE	/admin/variants/:id	Delete a variant
POST	/admin/categories	Create a category
GET	/admin/categories/list	List all categories
PUT	/admin/categories/:id	Update a category
DELETE	/admin/categories/:id	Delete a category
GET	/admin/collections/list	List all collections
POST	/admin/products/bulk-action	Bulk update status or delete
POST	/admin/products/import	Contained; returns PRODUCT_IMPORT_REVIEW_REQUIRED
POST	/admin/catalog/revisions/create	Create an immutable Catalog draft
GET	/admin/catalog/revisions/list	List revision summaries
GET	/admin/catalog/revisions/:id	Read one immutable revision and its content
POST	/admin/catalog/revisions/:id/review	Review the expected content digest
POST	/admin/catalog/revisions/:id/publish	Publish against the recorded base revision

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: 1999 }]);

Catalog revision foundation

applyCatalogRevisionOperation(transaction, input, context) is the narrow, Products-owned interface for future Catalog Commands. It accepts normalized Product, Variant, accepted Category, currency, and integer-minor-unit facts and supports these transitions:

create_draft -> draft -> review -> reviewed -> publish -> published
                    \-> fail -> failed       \-> fail -> failed
published -> superseded (only when its reviewed successor publishes)

Revision content and its SHA-256 digest never change after draft creation. Every operation locks the owner-local Catalog aggregate, records its actor and authority in an audit row, and writes a replay receipt. Publish compares the draft's recorded base revision to the locked published head; a stale base returns stale_base_revision without changing state. The new revision, supersession of the prior revision, audit rows, replay receipt, and catalog.published@1 outbox fact commit in the caller's transaction.

The authenticated Store Admin transport derives its Account actor, Store authority, and Store target from the session. Callers provide a stable operation ID; review and publish also provide the server-issued content digest. All writes return 503 unless the Runtime supplies owner-local locking and transactional durable-event storage. Reads validate stored data and list bounded summaries.

Direct spreadsheet import continues to return PRODUCT_IMPORT_REVIEW_REQUIRED, and product-feed generation continues to fail closed until its projection adapter is connected. Existing Product CRUD is migration state and does not claim to be revision-backed.

Published Catalog presentation

The Products Module registers products.catalog-presentation.v1 as a durable consumer of catalog.published@1. It validates the event against the immutable revision, recomputes the content digest, and replaces one owner-local catalogPresentation row. That row contains three views built from the same revision: active and visible Storefront data, product search documents, and feed-facing product data with explicit minor-unit prices.

An exact replay is a no-op. A publication below the projected revision sequence is ignored, while a conflicting sequence or mismatched revision fails delivery. The runtime runs the handler and its delivery receipt in one transaction, so a failure leaves the last good presentation readable and visible in the durable delivery retry or dead-letter state. Repairing a transient source problem lets the same event replay successfully.

Use readCatalogPresentation(data) to read and validate the current projection. The consumer is fully standalone and makes no 86d.app or Control Plane call. Legacy Storefront endpoints, the Search Module's external index, and generated channel feeds still require explicit adapters before they become revision-backed.

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

Prop	Type	Default	Description
product	Product	—	Product object with id, name, slug, price, images, etc.
showAddToCart	boolean	true	Show the "Add to Cart" button

Usage in MDX

<ProductCard product={product} />

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

FeaturedProducts

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

Props

Prop	Type	Default	Description
limit	number	—	Max number of featured products to display
title	string	—	Section heading

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

Prop	Type	Default	Description
initialCategory	string	—	Pre-select a category filter
initialSearch	string	—	Pre-fill the search query
pageSize	number	—	Products per page

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

Prop	Type	Description
slug	string	Product slug (from URL)
params	Record<string, string>	Route params (params.slug)

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

Prop	Type	Default	Description
productId	string	—	Product ID to find related products for
limit	number	—	Max related products to show
title	string	—	Section heading

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

Prop	Type	Description
collection	CollectionCardData	Collection object with id, name, slug, description, image

Usage in MDX

<CollectionCard collection={collection} />

CollectionGrid

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

Props

Prop	Type	Default	Description
title	string	—	Section heading
featured	boolean	—	Only show featured collections

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

Prop	Type	Description
slug	string	Collection slug (from URL)
params	Record<string, string>	Route params (params.slug)

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

Prop	Type	Description
label	string	Filter display text
onRemove	() => void	Callback when the chip is dismissed

Usage in MDX

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

StarDisplay

Read-only star rating display.

Props

Prop	Type	Default	Description
rating	number	—	Rating value (0–5)
size	"sm" | "md" | "lg"	"md"	Star size

Usage in MDX

<StarDisplay rating={4.5} />

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

StarPicker

Interactive star rating input for review submission.

Props

Prop	Type	Description
value	number	Current rating value
onChange	(n: number) => void	Callback when user selects a rating

Usage in MDX

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

StockBadge

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

Props

Prop	Type	Description
inventory	number	Available inventory count

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

Prop	Type	Description
productId	string	Product ID to show reviews for

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.