@happyvertical/smrt-products

Product catalog reference template demonstrating triple-consumption: npm package library, module federation, and standalone REST API server.

Installation

pnpm add @happyvertical/smrt-products

Usage

Import as npm library

import { Product, ProductCollection, Category } from '@happyvertical/smrt-products';
import { startServer } from '@happyvertical/smrt-products';
import { generateMCPServer } from '@happyvertical/smrt-products';
import { AssetCollection } from '@happyvertical/smrt-assets';

// Start standalone REST API server
const { shutdown } = await startServer();

const products = await ProductCollection.create();
const assets = await AssetCollection.create();
const product = await products.create({
  name: 'Demo Product',
  price: 29.99,
});
const hero = await assets.create({
  name: 'demo-product-hero.jpg',
  sourceUri: 'file:///tmp/demo-product-hero.jpg',
  mimeType: 'image/jpeg',
});

await product.addAsset(hero, 'hero');
await products.addAsset(product.id!, hero, 'gallery', 1);

Three consumption modes

1. NPM library -- import classes, components, and stores directly
2. Module federation -- runtime component sharing (experimental)
3. Standalone API -- startServer() launches Express with auto-generated routes

API

Top-Level Exports

Export	Description
startServer	Launch standalone REST API server
generateMCPServer	Generate MCP server for AI tool integration
demonstrateClient	Demo of auto-generated TypeScript client
startAll	Start all services (REST + MCP)

Models (from lib/models)

Export	Description
Product	STI-enabled product with specs and tags
Category	Hierarchical category (parentId, level, productCount), STI enabled
ProductAsset	Dedicated owned-asset join stored in product_assets with relationship and sortOrder; intentionally not tenant-scoped because Product is not tenant-scoped

Collections (from lib/collections)

Export	Description
ProductCollection	CRUD plus findByManufacturer(), findInStock(), and owned asset wrappers
ProductAssetCollection	Direct access to product_assets rows plus asset helper wrappers

Components (from lib/components)

Export	Description
ProductCard	Svelte 5 product display component
ProductForm	Svelte 5 product edit form

Stores (from lib/stores)

Export	Description
ProductStoreClass	Svelte 5 rune-based state management class
productStore	Singleton store instance

Utilities (from lib/utils)

Export	Description
formatPrice	Format number as USD currency string
formatDate	Format date as human-readable string
slugify	Convert text to URL-friendly slug
generateId	Generate random ID string

Virtual Modules (Vite plugin)

Export	Description
createClient	Auto-generated TypeScript API client
setupRoutes	Auto-generated Express routes
createMCPServer	Auto-generated MCP server
manifest	s-m-r-t object metadata

Owned asset helpers are available on both Product and ProductCollection via getAssets(), addAsset(), and removeAsset(). Common relationships include hero, gallery, attachment, and thumbnail.

Dependencies

Package	Purpose
@happyvertical/smrt-core	SmrtObject/SmrtCollection base classes, REST server, MCP generator
@happyvertical/smrt-assets	Shared Asset / AssetCollection types used by product-owned asset helpers
@happyvertical/sql	Database operations
@happyvertical/ai	AI integration