@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 |