@happyvertical/smrt-products 0.30.0

package/AGENTS.md

@@ -0,0 +1,122 @@
+# @happyvertical/smrt-products
+
+Product catalog — reference template for triple-consumption: npm package library, module federation, and standalone REST API server.
+
+## Models
+
+- **Product**: STI base. Tenant-scoped (`@TenantScoped({ mode: 'optional' })`, nullable `tenantId`). Knowledge base product with specs, tags, and the `productType` discriminator. Consumers subclass this with vertical-specific subtypes (apparel `Style`, automotive `Model`, furniture `Design`, etc.).
+- **Material**: STI subtype. Raw input consumed by manufacturing (fabric, trim, thread, packaging, component). Meta fields: `materialKind`, `uom`, `costPerUnit`. Materials are first-class products in the catalog — the SAP/NetSuite pattern. Bills of materials in `@happyvertical/smrt-manufacturing` reference Materials by id.
+- **ProductVariant**: standalone (NOT a Product STI subtype). Declarative axis definition: `productId`, `axisName` (e.g. `'size'`, `'color'`, `'finish'`), `allowedValues` (JSON-stored array), optional `label` and `sortOrder`. Per-SKU value pins live on `Sku.attributes`. Lives in its own `product_variants` table; `conflictColumns: ['product_id', 'axis_name', 'tenant_id']`.
+- **Sku**: standalone. The smallest sellable / countable unit. `productId` points at a `Product` or any of its STI subtypes; `code` is the human-meaningful identifier; `attributes` JSON pins each axis value (`{ size: 'M', color: 'navy' }`). Lives in its own `product_skus` table; `conflictColumns: ['code', 'tenant_id']`. Stock balance and movement history for a Sku live in `@happyvertical/smrt-inventory`.
+- **ProductAsset**: dedicated owned-asset join in `product_assets` with `relationship` and `sortOrder`. Tenant-scoped to match Product.
+- **Category**: hierarchical (parentId, level, productCount). STI base, tenant-scoped.
+
+## Vertical-specific Product subtypes
+
+This package deliberately ships ONLY the generic primitives. Domain-specific top-level item types live in the consumer's template:
+
+- Apparel: `Style extends Product`, `Makeup extends Product`
+- Furniture: `Design extends Product`, `Configuration extends Product`
+- Automotive: `Model extends Product`, `Trim extends Product`
+- CPG: `Brand extends Product`, `Recipe extends Product`
+
+Each is a small subclass: `@smrt()`, override `productType`, add `@meta()` fields. See `packages/template-apparel-erp` for a worked example.
+
+## Variants — the two concepts
+
+The framework's variant story uses two distinct primitives that look similar but do different jobs:
+
+- **`ProductVariant`** — *axis declaration*. "For product X, axis `size` accepts the values `[XS, S, M, L, XL]`." Drives form/UI choices.
+- **`Sku.attributes`** — *per-unit value pins*. `{ color: 'navy', size: 'M' }` on each concrete sellable SKU.
+
+Both live in this package — all catalog shapes are here. Stock motion (where the SKU is, how many, history) lives in `@happyvertical/smrt-inventory`.
+
+There is deliberately no separate "catalog grouping above SKU" row (a la a "Navy colorway" row sitting between the Product and its Skus). Group SKUs by axis value via `attributes.color = 'navy'` queries; attach per-axis-value assets via `ProductAsset` rows with relationship metadata. Matches how Shopify, Stripe Products, and most e-commerce platforms model the same shape.
+
+## Collections
+
+- **ProductCollection** — base. Polymorphic queries return the correct subclass instance per row.
+- **MaterialCollection** — STI-filtered subclass. Override `_itemClass`; framework auto-filters by `_meta_type`.
+- **ProductVariantCollection** — standalone collection over `product_variants`. Helpers: `findForProduct(productId)`, `findAxis(productId, axisName)`.
+- **SkuCollection** — standalone collection over `product_skus`. Helpers: `findByCode`, `findByBarcode`, `findByProduct`, `findByParent`, `findActive`.
+- **CategoryCollection** — standard Category CRUD with `getRootCategories()`.
+- **ProductAssetCollection** — direct access to `product_assets` rows and product asset helper wrappers.
+
+## Multi-tenancy
+
+Optional. With `withTenant(id, fn)` (from `@happyvertical/smrt-tenancy`), all queries auto-filter and inserts auto-stamp `tenantId`. Without it, models behave globally (`tenantId = null`). This lets the same package serve both shared reference catalogs and per-merchant SaaS catalogs.
+
+## Triple-Consumption Pattern
+
+Same codebase consumed three ways:
+1. **NPM library**: import classes directly
+2. **Module federation**: runtime component sharing (experimental)
+3. **Standalone API**: `startRestServer([Product, Category])`
+
+## Virtual Modules (Vite)
+
+Auto-generated via Vite plugins: `@happyvertical/smrt-client` (TypeScript client), `@happyvertical/smrt-types`, `@happyvertical/smrt-routes` (Express), `@happyvertical/smrt-mcp`, `@happyvertical/smrt-manifest`.
+
+Svelte 5 stores use runes (`$state`, `$derived`, `$effect`). Separate `product-store.server.svelte.ts` vs `product-store.client.svelte.ts` for SSR safety.
+
+## Schema migrations (Phase 1 release)
+
+This package's schema changed shape between the previous release and the Phase 1 apparel-ERP release. Consumers upgrading need to migrate two tables.
+
+### `Sku` rows moved tables
+
+Previously `Sku` shipped in `@happyvertical/smrt-inventory` under table `inventory_skus`. It now lives here under `product_skus`. Cross-package refs (`StockLevel.skuId`, `BomLine.componentSkuId`) carry plain string ids that still resolve.
+
+**Upgrade procedure** (works on SQLite + Postgres; does NOT rely on `CREATE TABLE AS` which strips constraints):
+
+1. **Boot the new version once** so the framework's lazy `syncSchema` creates `product_skus` with the right PRIMARY KEY, NOT NULL, UNIQUE (`code`, `tenant_id`), and indexes derived from the `Sku` model.
+
+2. **Idempotently copy rows**:
+
+   ```sql
+   BEGIN;
+   INSERT INTO product_skus (
+     id, slug, context, created_at, updated_at,
+     tenant_id, product_id, code, barcode, name,
+     attributes, weight_grams, parent_sku_id, active
+   )
+   SELECT
+     id, slug, context, created_at, updated_at,
+     tenant_id, product_id, code, barcode, name,
+     attributes, weight_grams, parent_sku_id, active
+   FROM inventory_skus
+   WHERE NOT EXISTS (
+     SELECT 1 FROM product_skus p WHERE p.id = inventory_skus.id
+   );
+   COMMIT;
+   ```
+
+3. **Drop the legacy table** once row counts match:
+
+   ```sql
+   DROP TABLE IF EXISTS inventory_skus;
+   ```
+
+### `ProductVariant` changed shape entirely
+
+Previously a Product STI subtype carrying `parentProductId` + `axisValues` JSON inside `_meta_data` on the shared `products` table (`_meta_type='@happyvertical/smrt-products:ProductVariant'`). It is now a **standalone model** on its own `product_variants` table, with columns `productId`, `axisName`, `allowedValues`, `label`, `sortOrder`.
+
+**There is no automatic data conversion.** The old "catalog grouping above SKU" concept doesn't map 1:1 to the new "per-axis declaration" concept. Recommended procedure:
+
+1. Inspect the old rows: `SELECT * FROM products WHERE _meta_type = '@happyvertical/smrt-products:ProductVariant';`. Treat them as historical reference.
+2. Re-author axis declarations against the new shape (one `ProductVariant` row per `(productId, axisName)` pair, with `allowedValues` listing the values).
+3. Once the new declarations are populated and verified, remove the legacy rows: `DELETE FROM products WHERE _meta_type = '@happyvertical/smrt-products:ProductVariant';`.
+
+If you had per-colorway / per-variant images attached via `ProductAsset` rows pointing at old ProductVariant ids, repoint those to the parent Product id; group-by-axis-value queries on `Sku.attributes` cover the same use case at the SKU level.
+
+## Gotchas
+
+- **`ProductVariant` and `Sku` are NOT Product STI subtypes** — they each have their own table (`product_variants`, `product_skus`) because their shapes don't fit the Product schema. Don't try to query them via `ProductCollection`.
+- **`npm run build` emits the published library surface directly**: package consumers read model, collection, and helper exports from `dist/lib`. Cross-package imports from this package should target `/models` or `/collections` subpaths (not the main entry) when the consumer isn't a vite app — the main entry pulls in vite virtual modules.
+- **Use `npm run build:all` only when you need standalone or federation bundles** in addition to the library output
+- **Constructor must explicitly assign all properties**: `Object.assign` doesn't work reliably with decorators
+- **STI subtype-specific fields use `Meta<T>`** — declare them as `fieldName: Meta<FieldType> = defaultValue`. The AST scanner detects the `Meta<T>` type wrapper at build time and routes the field through `_meta_data` JSON storage instead of materializing it as a column on the parent's table. Do **NOT** use the runtime `@meta()` decorator on STI children — it never reaches the manifest, so the schema generator treats the field as an ordinary column on the parent table and the framework's hydration path can't tell it's meta. Override `productType` on each subclass.
+- **Tenant-scoped STI children must repeat `@TenantScoped`** — `@TenantScoped` registers per concrete className, so `Material extends Product` inheriting from a tenant-scoped `Product` is NOT automatically tenant-scoped itself. `MaterialCollection.list/save` passes `'Material'` to the tenant interceptor, which looks up `'Material'` (not `'Product'`) in the per-class registry. Without an explicit `@TenantScoped({ mode: 'optional' })` on `Material`, material rows skip the tenant auto-filter and auto-populate.
+- **STI children must repeat `@smrt({ api, mcp, cli })` generation config (S5 #1406)** — like `@TenantScoped`, the generation config is registered per concrete className and is NOT inherited from the STI parent. An empty `@smrt()` on a child resolves `getConfig(child).api/.mcp` to `undefined`, which the REST and MCP generators treat as "expose EVERYTHING" — including `delete` and write-capable MCP tools — even when the parent deliberately restricts its surface. The package's `mcp.ts` generator enumerates the whole registry, so an under-configured child ships a wide-open surface silently. Re-declare the parent's `api`/`mcp`/`cli` posture on every subtype (see `Material`). Consumer subtypes (apparel `Style`/`Makeup`, automotive `Model`/`Trim`, …) must do the same.
+- **Two-tenant same-slug is currently a hard error** for tenant-scoped STI bases (`Product`, `Category`). The core schema generator hardcodes the STI unique index as `(slug, context, _meta_type)` and does NOT include `tenant_id` even for `@TenantScoped` classes. Two tenants saving a row with the same slug + context + meta_type collide at the SQL layer. Workaround: namespace slugs per tenant on the application side (e.g. `${tenantId}-widget`) until the upstream framework fix lands.
+- **Module Federation marked experimental**: may change

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright <2025> <Happy Vertical Corporation>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,115 @@
+# @happyvertical/smrt-products
+
+Product catalog reference template demonstrating triple-consumption: npm package library, module federation, and standalone REST API server.
+
+## Installation
+
+```bash
+pnpm add @happyvertical/smrt-products
+```
+
+## Usage
+
+### Import as npm library
+
+```typescript
+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` | SMRT 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 |

package/dist/lib/__smrt-register__.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__smrt-register__.d.ts.map

package/dist/lib/__smrt-register__.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"__smrt-register__.d.ts","sourceRoot":"","sources":["../../src/__smrt-register__.ts"],"names":[],"mappings":""}

package/dist/lib/app/main.d.ts

@@ -0,0 +1,6 @@
+declare const app: {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<Record<string, any>>): void;
+} & Record<string, any>;
+export default app;
+//# sourceMappingURL=main.d.ts.map

package/dist/lib/app/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/app/main.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,WAAW,CAAC;AAInB,QAAA,MAAM,GAAG;;;uBAEP,CAAC;AAEH,eAAe,GAAG,CAAC"}

package/dist/lib/chunks/ProductAssetCollection-DFPXN43q.js

@@ -0,0 +1,64 @@
+import { getOwnedAssetsFromCollection, addOwnedAssetFromCollection, removeOwnedAssetFromCollection } from "@happyvertical/smrt-assets";
+import { smrt, SmrtJunction } from "@happyvertical/smrt-core";
+import { a as ProductAsset } from "./Sku-DUKtbYWT.js";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = decorator(result) || result;
+  return result;
+};
+var __publicField = (obj, key, value) => __defNormalProp(obj, key + "", value);
+let ProductAssetCollection = class extends SmrtJunction {
+  leftField = "productId";
+  rightField = "assetId";
+  productCollectionPromise = null;
+  async getProductCollection() {
+    if (!this.productCollectionPromise) {
+      const { ProductCollection } = await import("./SkuCollection-C0tdkEdL.js").then((n) => n.b);
+      this.productCollectionPromise = ProductCollection.create({ db: this.db });
+    }
+    return this.productCollectionPromise;
+  }
+  async getAssets(productId, relationship) {
+    return getOwnedAssetsFromCollection(
+      await this.getProductCollection(),
+      productId,
+      relationship
+    );
+  }
+  async addAsset(productId, asset, relationship = "attachment", sortOrder = 0) {
+    await addOwnedAssetFromCollection(
+      await this.getProductCollection(),
+      "Product",
+      productId,
+      asset,
+      relationship,
+      sortOrder
+    );
+  }
+  async removeAsset(productId, assetId, relationship) {
+    await removeOwnedAssetFromCollection(
+      await this.getProductCollection(),
+      "Product",
+      productId,
+      assetId,
+      relationship
+    );
+  }
+};
+__publicField(ProductAssetCollection, "_itemClass", ProductAsset);
+ProductAssetCollection = __decorateClass([
+  smrt({
+    api: false,
+    mcp: false,
+    cli: false
+  })
+], ProductAssetCollection);
+export {
+  ProductAssetCollection
+};
+//# sourceMappingURL=ProductAssetCollection-DFPXN43q.js.map

package/dist/lib/chunks/ProductAssetCollection-DFPXN43q.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProductAssetCollection-DFPXN43q.js","sources":["../../../src/lib/collections/ProductAssetCollection.ts"],"sourcesContent":["import type { Asset } from '@happyvertical/smrt-assets';\nimport {\n  addOwnedAssetFromCollection,\n  getOwnedAssetsFromCollection,\n  removeOwnedAssetFromCollection,\n} from '@happyvertical/smrt-assets';\nimport type { SmrtCollectionOptions } from '@happyvertical/smrt-core';\nimport { SmrtJunction, smrt } from '@happyvertical/smrt-core';\nimport { ProductAsset } from '../models/ProductAsset';\nimport type { ProductCollection } from './ProductCollection';\n\nexport interface ProductAssetCollectionOptions extends SmrtCollectionOptions {}\n\n@smrt({\n  api: false,\n  mcp: false,\n  cli: false,\n})\nexport class ProductAssetCollection extends SmrtJunction<ProductAsset> {\n  static readonly _itemClass = ProductAsset;\n  protected leftField = 'productId';\n  protected rightField = 'assetId';\n\n  private productCollectionPromise: Promise<ProductCollection> | null = null;\n\n  private async getProductCollection(): Promise<ProductCollection> {\n    if (!this.productCollectionPromise) {\n      const { ProductCollection } = await import('./ProductCollection');\n      this.productCollectionPromise = ProductCollection.create({ db: this.db });\n    }\n\n    return this.productCollectionPromise;\n  }\n\n  async getAssets(productId: string, relationship?: string): Promise<Asset[]> {\n    return getOwnedAssetsFromCollection(\n      await this.getProductCollection(),\n      productId,\n      relationship,\n    );\n  }\n\n  async addAsset(\n    productId: string,\n    asset: Asset,\n    relationship = 'attachment',\n    sortOrder = 0,\n  ): Promise<void> {\n    await addOwnedAssetFromCollection(\n      await this.getProductCollection(),\n      'Product',\n      productId,\n      asset,\n      relationship,\n      sortOrder,\n    );\n  }\n\n  async removeAsset(\n    productId: string,\n    assetId: string,\n    relationship?: string,\n  ): Promise<void> {\n    await removeOwnedAssetFromCollection(\n      await this.getProductCollection(),\n      'Product',\n      productId,\n      assetId,\n      relationship,\n    );\n  }\n}\n"],"names":[],"mappings":";;;;;;;;;;;;;;AAkBO,IAAM,yBAAN,cAAqC,aAA2B;AAAA,EAE3D,YAAY;AAAA,EACZ,aAAa;AAAA,EAEf,2BAA8D;AAAA,EAEtE,MAAc,uBAAmD;AAC/D,QAAI,CAAC,KAAK,0BAA0B;AAClC,YAAM,EAAE,kBAAA,IAAsB,MAAM,OAAO,6BAAqB,EAAA,KAAA,OAAA,EAAA,CAAA;AAChE,WAAK,2BAA2B,kBAAkB,OAAO,EAAE,IAAI,KAAK,IAAI;AAAA,IAC1E;AAEA,WAAO,KAAK;AAAA,EACd;AAAA,EAEA,MAAM,UAAU,WAAmB,cAAyC;AAC1E,WAAO;AAAA,MACL,MAAM,KAAK,qBAAA;AAAA,MACX;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEA,MAAM,SACJ,WACA,OACA,eAAe,cACf,YAAY,GACG;AACf,UAAM;AAAA,MACJ,MAAM,KAAK,qBAAA;AAAA,MACX;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEA,MAAM,YACJ,WACA,SACA,cACe;AACf,UAAM;AAAA,MACJ,MAAM,KAAK,qBAAA;AAAA,MACX;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AACF;AApDE,cADW,wBACK,cAAa,YAAA;AADlB,yBAAN,gBAAA;AAAA,EALN,KAAK;AAAA,IACJ,KAAK;AAAA,IACL,KAAK;AAAA,IACL,KAAK;AAAA,EAAA,CACN;AAAA,GACY,sBAAA;"}