@hed-hog/catalog 0.0.293 → 0.0.294

package/hedhog/table/catalog_similarity_rule.yaml

@@ -1,21 +1,32 @@
-columns:
-  - type: pk
-  - name: category_id
-    type: fk
-    references:
-      table: category
-      column: id
-      onDelete: CASCADE
-  - name: rule_type
-    type: enum
-    values: [same_category, compatible_category, shared_attribute, manual]
-    default: same_category
-  - name: rule_json
-    type: json
-    isNullable: true
-  - name: min_similarity_score
-    type: decimal
-    precision: 5
+columns:
+  - type: pk
+  - name: catalog_category_id
+    type: fk
+    references:
+      table: catalog_category
+      column: id
+      onDelete: CASCADE
+  - name: related_catalog_category_id
+    type: fk
+    isNullable: true
+    references:
+      table: catalog_category
+      column: id
+      onDelete: SET NULL
+  - name: shared_attribute_id
+    type: fk
+    isNullable: true
+    references:
+      table: catalog_attribute
+      column: id
+      onDelete: SET NULL
+  - name: rule_type
+    type: enum
+    values: [same_category, compatible_category, shared_attribute, manual]
+    default: same_category
+  - name: min_similarity_score
+    type: decimal
+    precision: 5
     scale: 2
     default: 0
   - name: status
@@ -24,5 +35,7 @@ columns:
     default: active
   - type: created_at
   - type: updated_at
-indices:
-  - columns: [category_id, status]
+indices:
+  - columns: [catalog_category_id, status]
+  - columns: [related_catalog_category_id, status]
+  - columns: [shared_attribute_id, status]

package/hedhog/table/catalog_site.yaml

@@ -17,15 +17,22 @@ columns:
     type: enum
     values: [portal, niche, tenant]
     default: portal
-  - name: default_locale_id
-    type: fk
-    references:
-      table: locale
-      column: id
-      onDelete: RESTRICT
-  - name: theme_settings_json
-    type: json
-    isNullable: true
+  - name: default_locale_id
+    type: fk
+    references:
+      table: locale
+      column: id
+      onDelete: RESTRICT
+  - name: logo_file_id
+    type: fk
+    isNullable: true
+    references:
+      table: file
+      column: id
+      onDelete: SET NULL
+  - name: theme_settings_json
+    type: json
+    isNullable: true
   - name: seo_defaults_json
     type: json
     isNullable: true
@@ -34,7 +41,8 @@ columns:
 indices:
   - columns: [slug]
     isUnique: true
-  - columns: [domain]
-    isUnique: true
-  - columns: [status]
-  - columns: [default_locale_id]
+  - columns: [domain]
+    isUnique: true
+  - columns: [status]
+  - columns: [default_locale_id]
+  - columns: [logo_file_id]

package/hedhog/table/catalog_site_category.yaml

@@ -1,17 +1,17 @@
-columns:
-  - type: pk
-  - name: site_id
+columns:
+  - type: pk
+  - name: site_id
     type: fk
     references:
       table: catalog_site
       column: id
       onDelete: CASCADE
-  - name: category_id
-    type: fk
-    references:
-      table: category
-      column: id
-      onDelete: CASCADE
+  - name: catalog_category_id
+    type: fk
+    references:
+      table: catalog_category
+      column: id
+      onDelete: CASCADE
   - name: is_primary
     type: boolean
     default: false
@@ -21,6 +21,6 @@ columns:
     default: visible
   - type: created_at
   - type: updated_at
-indices:
-  - columns: [site_id, category_id]
-    isUnique: true
+indices:
+  - columns: [site_id, catalog_category_id]
+    isUnique: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/catalog",
-  "version": "0.0.293",
+  "version": "0.0.294",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -10,13 +10,13 @@
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
     "@hed-hog/api": "0.0.4",
-    "@hed-hog/core": "0.0.293",
-    "@hed-hog/api-locale": "0.0.13",
     "@hed-hog/api-pagination": "0.0.6",
     "@hed-hog/api-prisma": "0.0.5",
-    "@hed-hog/category": "0.0.293",
-    "@hed-hog/tag": "0.0.293",
-    "@hed-hog/content": "0.0.293"
+    "@hed-hog/core": "0.0.294",
+    "@hed-hog/category": "0.0.294",
+    "@hed-hog/api-locale": "0.0.13",
+    "@hed-hog/tag": "0.0.294",
+    "@hed-hog/content": "0.0.294"
   },
   "exports": {
     ".": {

package/src/catalog-resource.config.ts

@@ -1,52 +1,64 @@
-export type CatalogResourceConfig = {
-  resource: string;
-  model: string;
-  searchFields: string[];
+export type CatalogResourceConfig = {
+  resource: string;
+  model: string;
+  searchFields: string[];
   filterFields?: string[];
   fields: string[];
   defaultOrderBy?: Record<string, 'asc' | 'desc'>;
   statusField?: string;
   activeStatusValue?: string;
-};
-
-export const catalogResources: CatalogResourceConfig[] = [
-  {
-    resource: 'brands',
-    model: 'catalog_brand',
-    searchFields: ['slug', 'name', 'normalized_name'],
+};
+
+export const catalogResources: CatalogResourceConfig[] = [
+  {
+    resource: 'categories',
+    model: 'catalog_category',
+    searchFields: ['slug', 'name', 'normalized_name', 'description'],
+    filterFields: ['status', 'parent_category_id'],
+    fields: ['parent_category_id', 'slug', 'name', 'normalized_name', 'description', 'comparison_enabled', 'status', 'sort_order'],
+    defaultOrderBy: { sort_order: 'asc' },
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
+  {
+    resource: 'brands',
+    model: 'catalog_brand',
+    searchFields: ['slug', 'name', 'normalized_name'],
     filterFields: ['status', 'logo_file_id'],
     fields: ['slug', 'name', 'normalized_name', 'logo_file_id', 'status', 'website_url'],
     statusField: 'status',
     activeStatusValue: 'active',
   },
   {
-    resource: 'sites',
-    model: 'catalog_site',
-    searchFields: ['slug', 'name', 'domain'],
-    filterFields: ['status', 'site_type', 'default_locale_id'],
-    fields: ['slug', 'name', 'domain', 'status', 'site_type', 'default_locale_id', 'theme_settings_json', 'seo_defaults_json'],
-    statusField: 'status',
-    activeStatusValue: 'active',
-  },
-  {
-    resource: 'products',
-    model: 'catalog_product',
-    searchFields: ['slug', 'name', 'model_name', 'sku', 'gtin'],
-    filterFields: ['status', 'comparison_status', 'brand_id', 'category_id', 'primary_content_id', 'is_active'],
-    fields: ['brand_id', 'category_id', 'primary_content_id', 'slug', 'name', 'short_description', 'description', 'model_name', 'sku', 'gtin', 'status', 'comparison_status', 'release_date', 'spec_snapshot_json', 'comparison_snapshot_json', 'is_active'],
-    statusField: 'status',
-    activeStatusValue: 'published',
-  },
-  {
-    resource: 'product-categories',
-    model: 'catalog_product_category',
-    searchFields: [],
-    filterFields: ['product_id', 'category_id', 'is_primary'],
-    fields: ['product_id', 'category_id', 'is_primary', 'sort_order'],
-  },
-  {
-    resource: 'product-images',
-    model: 'catalog_product_image',
+    resource: 'sites',
+    model: 'catalog_site',
+    searchFields: ['slug', 'name', 'domain'],
+    filterFields: ['status', 'site_type', 'default_locale_id', 'logo_file_id'],
+    fields: ['slug', 'name', 'domain', 'status', 'site_type', 'default_locale_id', 'logo_file_id', 'theme_settings_json', 'seo_defaults_json'],
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
+  {
+    resource: 'products',
+    model: 'catalog_product',
+    searchFields: ['slug', 'name', 'model_name', 'sku', 'gtin'],
+    filterFields: ['status', 'comparison_status', 'brand_id', 'catalog_category_id', 'primary_content_id', 'is_active'],
+    // Snapshot JSON fields remain available for backward-compatible reads,
+    // but attribute values are now the primary source of truth.
+    fields: ['brand_id', 'catalog_category_id', 'primary_content_id', 'slug', 'name', 'short_description', 'description', 'model_name', 'sku', 'gtin', 'status', 'comparison_status', 'release_date', 'spec_snapshot_json', 'comparison_snapshot_json', 'is_active'],
+    statusField: 'status',
+    activeStatusValue: 'published',
+  },
+  {
+    resource: 'product-categories',
+    model: 'catalog_product_category',
+    searchFields: [],
+    filterFields: ['product_id', 'catalog_category_id', 'is_primary'],
+    fields: ['product_id', 'catalog_category_id', 'is_primary', 'sort_order'],
+  },
+  {
+    resource: 'product-images',
+    model: 'catalog_product_image',
     searchFields: ['alt_text', 'role'],
     filterFields: ['product_id', 'file_id', 'role', 'is_primary'],
     fields: ['product_id', 'file_id', 'role', 'sort_order', 'is_primary', 'alt_text'],
@@ -60,45 +72,60 @@ export const catalogResources: CatalogResourceConfig[] = [
     statusField: 'publication_status',
     activeStatusValue: 'published',
   },
-  {
-    resource: 'attribute-groups',
-    model: 'catalog_attribute_group',
+  {
+    resource: 'attribute-groups',
+    model: 'catalog_attribute_group',
     searchFields: ['slug', 'name'],
     filterFields: ['status'],
     fields: ['slug', 'name', 'status'],
     statusField: 'status',
     activeStatusValue: 'active',
   },
-  {
-    resource: 'attributes',
-    model: 'catalog_attribute',
-    searchFields: ['slug', 'label', 'description', 'unit'],
-    filterFields: ['group_id', 'data_type', 'comparison_mode', 'is_filterable', 'is_sortable', 'is_required_for_comparison'],
-    fields: ['group_id', 'slug', 'label', 'description', 'data_type', 'unit', 'comparison_mode', 'is_filterable', 'is_sortable', 'is_required_for_comparison', 'normalization_rule_json', 'display_order'],
-  },
-  {
-    resource: 'category-attributes',
-    model: 'catalog_category_attribute',
-    searchFields: [],
-    filterFields: ['category_id', 'attribute_id', 'is_required', 'is_highlighted', 'facet_mode'],
-    fields: ['category_id', 'attribute_id', 'is_required', 'is_highlighted', 'display_order', 'weight', 'facet_mode'],
-  },
-  {
-    resource: 'product-attributes',
-    model: 'catalog_product_attribute_value',
-    searchFields: ['value_text', 'normalized_text', 'source_type'],
-    filterFields: ['product_id', 'attribute_id', 'is_verified'],
-    fields: ['product_id', 'attribute_id', 'value_text', 'value_number', 'value_boolean', 'value_json', 'value_unit', 'normalized_text', 'normalized_number', 'source_type', 'confidence_score', 'is_verified'],
-  },
-  {
-    resource: 'score-criteria',
-    model: 'catalog_score_criterion',
-    searchFields: ['slug', 'name'],
-    filterFields: ['category_id', 'status', 'score_type'],
-    fields: ['category_id', 'slug', 'name', 'weight', 'score_type', 'formula_json', 'display_order', 'status'],
-    statusField: 'status',
-    activeStatusValue: 'active',
-  },
+  {
+    resource: 'attributes',
+    model: 'catalog_attribute',
+    searchFields: ['slug', 'code', 'name', 'description', 'unit', 'group_name'],
+    filterFields: ['group_id', 'group_name', 'status', 'data_type', 'comparison_mode', 'is_filterable', 'is_sortable', 'is_comparable', 'is_required_default'],
+    fields: ['code', 'group_id', 'group_name', 'slug', 'name', 'description', 'data_type', 'unit', 'comparison_mode', 'is_filterable', 'is_sortable', 'is_comparable', 'is_required_default', 'status', 'display_order'],
+    defaultOrderBy: { display_order: 'asc' },
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
+  {
+    resource: 'attribute-options',
+    model: 'catalog_attribute_option',
+    searchFields: ['slug', 'label', 'option_value', 'normalized_value'],
+    filterFields: ['attribute_id', 'status', 'is_default'],
+    fields: ['attribute_id', 'slug', 'label', 'option_value', 'normalized_value', 'sort_order', 'status', 'is_default'],
+    defaultOrderBy: { sort_order: 'asc' },
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
+  {
+    resource: 'category-attributes',
+    model: 'catalog_category_attribute',
+    searchFields: [],
+    filterFields: ['catalog_category_id', 'attribute_id', 'is_required', 'is_highlight', 'is_filter_visible', 'is_comparison_visible', 'facet_mode'],
+    fields: ['catalog_category_id', 'attribute_id', 'is_required', 'is_highlight', 'is_filter_visible', 'is_comparison_visible', 'sort_order', 'weight', 'facet_mode'],
+    defaultOrderBy: { sort_order: 'asc' },
+  },
+  {
+    resource: 'product-attributes',
+    model: 'catalog_product_attribute_value',
+    searchFields: ['raw_value', 'value_text', 'normalized_value', 'normalized_text', 'source_type'],
+    filterFields: ['product_id', 'attribute_id', 'attribute_option_id', 'is_verified'],
+    fields: ['product_id', 'attribute_id', 'attribute_option_id', 'value_text', 'value_number', 'value_boolean', 'raw_value', 'value_unit', 'normalized_value', 'normalized_text', 'normalized_number', 'source_type', 'confidence_score', 'is_verified'],
+  },
+  {
+    resource: 'score-criteria',
+    model: 'catalog_score_criterion',
+    searchFields: ['slug', 'name'],
+    filterFields: ['catalog_category_id', 'attribute_id', 'target_option_id', 'status', 'score_type'],
+    fields: ['catalog_category_id', 'attribute_id', 'target_option_id', 'slug', 'name', 'weight', 'score_type', 'max_score', 'display_order', 'status'],
+    defaultOrderBy: { display_order: 'asc' },
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
   {
     resource: 'product-scores',
     model: 'catalog_product_score',
@@ -106,15 +133,15 @@ export const catalogResources: CatalogResourceConfig[] = [
     filterFields: ['product_id', 'criterion_id', 'is_manual_override'],
     fields: ['product_id', 'criterion_id', 'score_value', 'score_label', 'summary', 'calculation_source', 'is_manual_override'],
   },
-  {
-    resource: 'comparisons',
-    model: 'catalog_comparison',
-    searchFields: ['slug', 'title', 'summary', 'verdict', 'eligibility_hash'],
-    filterFields: ['category_id', 'site_id', 'primary_content_id', 'comparison_type', 'generation_mode', 'status'],
-    fields: ['category_id', 'site_id', 'primary_content_id', 'slug', 'comparison_type', 'generation_mode', 'status', 'title', 'summary', 'intro', 'verdict', 'spec_snapshot_json', 'eligibility_hash', 'published_at'],
-    statusField: 'status',
-    activeStatusValue: 'published',
-  },
+  {
+    resource: 'comparisons',
+    model: 'catalog_comparison',
+    searchFields: ['slug', 'title', 'summary', 'verdict', 'eligibility_hash'],
+    filterFields: ['catalog_category_id', 'site_id', 'primary_content_id', 'comparison_type', 'generation_mode', 'status'],
+    fields: ['catalog_category_id', 'site_id', 'primary_content_id', 'slug', 'comparison_type', 'generation_mode', 'status', 'title', 'summary', 'intro', 'verdict', 'eligibility_hash', 'published_at'],
+    statusField: 'status',
+    activeStatusValue: 'published',
+  },
   {
     resource: 'comparison-items',
     model: 'catalog_comparison_item',
@@ -129,15 +156,15 @@ export const catalogResources: CatalogResourceConfig[] = [
     filterFields: ['comparison_id', 'product_id', 'attribute_id', 'highlight_type'],
     fields: ['comparison_id', 'product_id', 'attribute_id', 'highlight_type', 'title', 'body', 'sort_order'],
   },
-  {
-    resource: 'similarity-rules',
-    model: 'catalog_similarity_rule',
-    searchFields: ['rule_type'],
-    filterFields: ['category_id', 'status'],
-    fields: ['category_id', 'rule_type', 'rule_json', 'min_similarity_score', 'status'],
-    statusField: 'status',
-    activeStatusValue: 'active',
-  },
+  {
+    resource: 'similarity-rules',
+    model: 'catalog_similarity_rule',
+    searchFields: ['rule_type'],
+    filterFields: ['catalog_category_id', 'related_catalog_category_id', 'shared_attribute_id', 'status'],
+    fields: ['catalog_category_id', 'related_catalog_category_id', 'shared_attribute_id', 'rule_type', 'min_similarity_score', 'status'],
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
   {
     resource: 'merchants',
     model: 'catalog_merchant',
@@ -177,13 +204,13 @@ export const catalogResources: CatalogResourceConfig[] = [
     filterFields: ['offer_id', 'product_id', 'site_id', 'comparison_id'],
     fields: ['offer_id', 'product_id', 'site_id', 'comparison_id', 'clicked_at', 'placement', 'utm_json', 'session_hash', 'referrer_host'],
   },
-  {
-    resource: 'site-categories',
-    model: 'catalog_site_category',
-    searchFields: ['visibility_status'],
-    filterFields: ['site_id', 'category_id', 'is_primary', 'visibility_status'],
-    fields: ['site_id', 'category_id', 'is_primary', 'visibility_status'],
-  },
+  {
+    resource: 'site-categories',
+    model: 'catalog_site_category',
+    searchFields: ['visibility_status'],
+    filterFields: ['site_id', 'catalog_category_id', 'is_primary', 'visibility_status'],
+    fields: ['site_id', 'catalog_category_id', 'is_primary', 'visibility_status'],
+  },
   {
     resource: 'content-relations',
     model: 'catalog_content_relation',
@@ -191,15 +218,15 @@ export const catalogResources: CatalogResourceConfig[] = [
     filterFields: ['site_id', 'content_id', 'product_id', 'comparison_id', 'relation_type'],
     fields: ['site_id', 'content_id', 'product_id', 'comparison_id', 'relation_type', 'sort_order'],
   },
-  {
-    resource: 'seo-rules',
-    model: 'catalog_seo_page_rule',
-    searchFields: ['page_type', 'rule_slug', 'canonical_strategy'],
-    filterFields: ['site_id', 'category_id', 'status', 'page_type'],
-    fields: ['site_id', 'category_id', 'page_type', 'rule_slug', 'status', 'generation_query_json', 'min_product_count', 'min_attribute_coverage', 'canonical_strategy', 'priority', 'template_json'],
-    statusField: 'status',
-    activeStatusValue: 'active',
-  },
+  {
+    resource: 'seo-rules',
+    model: 'catalog_seo_page_rule',
+    searchFields: ['page_type', 'rule_slug', 'canonical_strategy'],
+    filterFields: ['site_id', 'catalog_category_id', 'status', 'page_type'],
+    fields: ['site_id', 'catalog_category_id', 'page_type', 'rule_slug', 'status', 'generation_query_json', 'min_product_count', 'min_attribute_coverage', 'canonical_strategy', 'priority', 'template_json'],
+    statusField: 'status',
+    activeStatusValue: 'active',
+  },
   {
     resource: 'import-sources',
     model: 'catalog_import_source',

package/src/catalog.controller.ts

@@ -1,18 +1,20 @@
 import { Role } from '@hed-hog/api';
 import { Locale } from '@hed-hog/api-locale';
 import { Pagination } from '@hed-hog/api-pagination';
-import {
-  Body,
-  Controller,
-  Delete,
-  Get,
-  Param,
-  ParseIntPipe,
-  Patch,
-  Post,
-  Query,
-} from '@nestjs/common';
-import { CatalogService } from './catalog.service';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  BadRequestException,
+  Param,
+  ParseIntPipe,
+  Patch,
+  Post,
+  Put,
+  Query,
+} from '@nestjs/common';
+import { CatalogService } from './catalog.service';
 
 @Role()
 @Controller('catalog')
@@ -20,18 +22,83 @@ export class CatalogController {
   constructor(private readonly catalogService: CatalogService) {}
 
   @Get('products/:id/images')
-  async listProductImages(
-    @Param('id', ParseIntPipe) id: number,
-    @Pagination() paginationParams,
-    @Locale() locale: string,
-  ) {
-    return this.catalogService.listProductImages(id, locale, paginationParams);
-  }
-
-  @Get(':resource/stats')
-  async stats(@Param('resource') resource: string, @Locale() locale: string) {
-    return this.catalogService.stats(resource, locale);
-  }
+  async listProductImages(
+    @Param('id', ParseIntPipe) id: number,
+    @Pagination() paginationParams,
+    @Locale() locale: string,
+  ) {
+    return this.catalogService.listProductImages(id, locale, paginationParams);
+  }
+
+  @Get('categories/tree')
+  async categoriesTree() {
+    return this.catalogService.getCategoriesTree();
+  }
+
+  @Get('categories/:id/attributes')
+  async listCategoryAttributes(@Param('id', ParseIntPipe) id: number) {
+    return this.catalogService.listCategoryAttributes(id);
+  }
+
+  @Get('products/:id/attributes')
+  async listProductAttributes(@Param('id', ParseIntPipe) id: number) {
+    return this.catalogService.listProductAttributes(id);
+  }
+
+  @Get('products/:id/structured')
+  async structuredProduct(@Param('id', ParseIntPipe) id: number) {
+    return this.catalogService.getProductStructuredPayload(id);
+  }
+
+  @Get('products/:id/comparison-payload')
+  async comparisonPayload(@Param('id', ParseIntPipe) id: number) {
+    return this.catalogService.getProductComparisonPayload(id);
+  }
+
+  @Post('forms/:resource/ai-assist')
+  async generateFormAssistSuggestion(
+    @Param('resource') resource: string,
+    @Body() body: Record<string, unknown>,
+    @Locale() locale: string,
+  ) {
+    const prompt = String(body.prompt ?? '').trim();
+
+    if (!prompt) {
+      throw new BadRequestException('Prompt is required');
+    }
+
+    return this.catalogService.generateFormAssistSuggestion(resource, {
+      prompt,
+      current_values:
+        body.current_values && typeof body.current_values === 'object'
+          ? (body.current_values as Record<string, unknown>)
+          : {},
+      fields: Array.isArray(body.fields)
+        ? (body.fields as Record<string, unknown>[])
+        : [],
+      current_attribute_values: Array.isArray(body.current_attribute_values)
+        ? (body.current_attribute_values as Record<string, unknown>[])
+        : [],
+    }, locale);
+  }
+
+  @Put('products/:id/attributes')
+  async updateProductAttributes(
+    @Param('id', ParseIntPipe) id: number,
+    @Body('values') values: Record<string, unknown>[],
+  ) {
+    return this.catalogService.updateProductAttributes(id, values ?? []);
+  }
+
+  @Post('products/:id/materialize-snapshots')
+  async materializeProductSnapshots(@Param('id', ParseIntPipe) id: number) {
+    return this.catalogService.materializeProductSnapshots(id);
+  }
+
+  @Get(':resource/stats')
+  async stats(@Param('resource') resource: string, @Locale() locale: string) {
+    return this.catalogService.stats(resource, locale);
+  }
 
   @Get(':resource/:id')
   async getById(

package/src/catalog.module.ts

@@ -1,12 +1,16 @@
-import { PaginationModule } from '@hed-hog/api-pagination';
-import { Module, forwardRef } from '@nestjs/common';
-import { CatalogController } from './catalog.controller';
-import { CatalogService } from './catalog.service';
-
-@Module({
-  imports: [forwardRef(() => PaginationModule)],
-  controllers: [CatalogController],
-  providers: [CatalogService],
-  exports: [CatalogService],
-})
-export class CatalogModule {}
+import { PaginationModule } from '@hed-hog/api-pagination';
+import { AiModule } from '@hed-hog/core';
+import { Module, forwardRef } from '@nestjs/common';
+import { CatalogController } from './catalog.controller';
+import { CatalogService } from './catalog.service';
+
+@Module({
+  imports: [
+    forwardRef(() => PaginationModule),
+    forwardRef(() => AiModule),
+  ],
+  controllers: [CatalogController],
+  providers: [CatalogService],
+  exports: [CatalogService],
+})
+export class CatalogModule {}