@open-mercato/core 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3043.1a796c3920

package/src/modules/catalog/ai-tools/categories-pack.ts

@@ -0,0 +1,192 @@
+/**
+ * `catalog.list_categories` + `catalog.get_category` (Phase 1 WS-C, Step 3.10).
+ *
+ * Read-only category tools scoped by tenant + organization. `parentId: null`
+ * returns root nodes; any concrete UUID restricts to direct children.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { loadCustomFieldValues } from '@open-mercato/shared/lib/crud/custom-fields'
+import { E } from '#generated/entities.ids.generated'
+import { CatalogProductCategory } from '../data/entities'
+import { assertTenantScope, type CatalogAiToolDefinition, type CatalogToolContext } from './types'
+
+function resolveEm(ctx: CatalogToolContext): EntityManager {
+  return ctx.container.resolve<EntityManager>('em')
+}
+
+function buildScope(ctx: CatalogToolContext, tenantId: string) {
+  return { tenantId, organizationId: ctx.organizationId }
+}
+
+const listCategoriesInput = z
+  .object({
+    parentId: z
+      .union([z.string().uuid(), z.null()])
+      .optional()
+      .describe('Parent category id; pass `null` to list root nodes. Omit to list every category in scope.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max rows (default 50, max 100).'),
+    offset: z.number().int().min(0).optional().describe('Rows to skip (default 0).'),
+    includeArchived: z
+      .boolean()
+      .optional()
+      .describe('When true, include soft-deleted categories. Defaults to active-only.'),
+  })
+  .passthrough()
+
+const listCategoriesTool: CatalogAiToolDefinition = {
+  name: 'catalog.list_categories',
+  displayName: 'List categories',
+  description:
+    'List catalog categories scoped to tenant + organization. Use `parentId: null` to list roots or a specific uuid to fetch direct children.',
+  inputSchema: listCategoriesInput,
+  requiredFeatures: ['catalog.categories.view'],
+  tags: ['read', 'catalog'],
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = listCategoriesInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const where: Record<string, unknown> = { tenantId }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    if (!input.includeArchived) where.deletedAt = null
+    if ('parentId' in input) {
+      where.parentId = input.parentId ?? null
+    }
+    const [rows, total] = await Promise.all([
+      findWithDecryption<CatalogProductCategory>(
+        em,
+        CatalogProductCategory,
+        where as any,
+        { limit, offset, orderBy: { depth: 'asc', name: 'asc' } as any } as any,
+        buildScope(ctx, tenantId),
+      ),
+      em.count(CatalogProductCategory, where as any),
+    ])
+    const filtered = rows.filter((row) => row.tenantId === tenantId)
+    return {
+      items: filtered.map((row) => ({
+        id: row.id,
+        name: row.name,
+        slug: row.slug ?? null,
+        description: row.description ?? null,
+        parentId: row.parentId ?? null,
+        rootId: row.rootId ?? null,
+        treePath: row.treePath ?? null,
+        depth: row.depth,
+        childIds: Array.isArray(row.childIds) ? row.childIds : [],
+        isActive: !!row.isActive,
+        organizationId: row.organizationId ?? null,
+        tenantId: row.tenantId ?? null,
+        createdAt: row.createdAt ? new Date(row.createdAt).toISOString() : null,
+      })),
+      total,
+      limit,
+      offset,
+    }
+  },
+}
+
+const getCategoryInput = z.object({
+  categoryId: z.string().uuid().describe('Category id (UUID).'),
+  includeRelated: z
+    .boolean()
+    .optional()
+    .describe(
+      'When true, include direct children (capped at 100) and inherited ancestor refs. Custom fields are always included.',
+    ),
+})
+
+const getCategoryTool: CatalogAiToolDefinition = {
+  name: 'catalog.get_category',
+  displayName: 'Get category',
+  description:
+    'Fetch a catalog category by id with core fields and (optionally) children + ancestor inheritance + custom fields. Returns { found: false } when missing or cross-tenant.',
+  inputSchema: getCategoryInput,
+  requiredFeatures: ['catalog.categories.view'],
+  tags: ['read', 'catalog'],
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = getCategoryInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const where: Record<string, unknown> = {
+      id: input.categoryId,
+      tenantId,
+      deletedAt: null,
+    }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const category = await findOneWithDecryption<CatalogProductCategory>(
+      em,
+      CatalogProductCategory,
+      where as any,
+      undefined,
+      buildScope(ctx, tenantId),
+    )
+    if (!category || category.tenantId !== tenantId) {
+      return { found: false as const, categoryId: input.categoryId }
+    }
+    const customFieldValues = await loadCustomFieldValues({
+      em,
+      entityId: E.catalog.catalog_product_category,
+      recordIds: [category.id],
+      tenantIdByRecord: { [category.id]: category.tenantId ?? null },
+      organizationIdByRecord: { [category.id]: category.organizationId ?? null },
+      tenantFallbacks: [category.tenantId ?? tenantId].filter((value): value is string => !!value),
+    })
+    const customFields = customFieldValues[category.id] ?? {}
+    let related: Record<string, unknown> | null = null
+    if (input.includeRelated) {
+      const scope = buildScope(ctx, tenantId)
+      const children = await findWithDecryption<CatalogProductCategory>(
+        em,
+        CatalogProductCategory,
+        { tenantId, parentId: category.id, deletedAt: null } as any,
+        { limit: 100, orderBy: { name: 'asc' } as any } as any,
+        scope,
+      )
+      related = {
+        children: children
+          .filter((row) => row.tenantId === tenantId)
+          .map((row) => ({
+            id: row.id,
+            name: row.name,
+            slug: row.slug ?? null,
+            depth: row.depth,
+            isActive: !!row.isActive,
+          })),
+        ancestorIds: Array.isArray(category.ancestorIds) ? [...category.ancestorIds] : [],
+        descendantIds: Array.isArray(category.descendantIds) ? [...category.descendantIds] : [],
+      }
+    }
+    return {
+      found: true as const,
+      category: {
+        id: category.id,
+        name: category.name,
+        slug: category.slug ?? null,
+        description: category.description ?? null,
+        parentId: category.parentId ?? null,
+        rootId: category.rootId ?? null,
+        treePath: category.treePath ?? null,
+        depth: category.depth,
+        childIds: Array.isArray(category.childIds) ? [...category.childIds] : [],
+        ancestorIds: Array.isArray(category.ancestorIds) ? [...category.ancestorIds] : [],
+        descendantIds: Array.isArray(category.descendantIds) ? [...category.descendantIds] : [],
+        metadata: category.metadata ?? null,
+        isActive: !!category.isActive,
+        organizationId: category.organizationId ?? null,
+        tenantId: category.tenantId ?? null,
+        createdAt: category.createdAt ? new Date(category.createdAt).toISOString() : null,
+        updatedAt: category.updatedAt ? new Date(category.updatedAt).toISOString() : null,
+      },
+      customFields,
+      related,
+    }
+  },
+}
+
+export const categoriesAiTools: CatalogAiToolDefinition[] = [listCategoriesTool, getCategoryTool]
+
+export default categoriesAiTools

package/src/modules/catalog/ai-tools/configuration-pack.ts

@@ -0,0 +1,218 @@
+/**
+ * `catalog.list_option_schemas` + `catalog.list_unit_conversions` (Phase 1
+ * WS-C, Step 3.10).
+ *
+ * Product-configuration surface: option schemas (variant axes) and unit
+ * conversions (UoM factors).
+ *
+ * Phase 3c of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * both tools are now API-backed wrappers over the documented CRUD list
+ * routes (`GET /api/catalog/option-schemas` and
+ * `GET /api/catalog/product-unit-conversions`). Tool names, schemas,
+ * requiredFeatures, and output shapes are unchanged.
+ */
+import { z } from 'zod'
+import { defineApiBackedAiTool } from '@open-mercato/ai-assistant/modules/ai_assistant/lib/api-backed-tool'
+import type {
+  AiApiOperationRequest,
+  AiToolExecutionContext,
+} from '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-api-operation-runner'
+import { assertTenantScope, type CatalogAiToolDefinition, type CatalogToolContext } from './types'
+
+const listOptionSchemasInput = z
+  .object({
+    limit: z.number().int().min(1).max(100).optional().describe('Max rows (default 50, max 100).'),
+    offset: z.number().int().min(0).optional().describe('Rows to skip (default 0).'),
+  })
+  .passthrough()
+
+type ListOptionSchemasInput = z.infer<typeof listOptionSchemasInput>
+
+type ListOptionSchemasApiItem = {
+  id?: string
+  code?: string | null
+  name?: string | null
+  description?: string | null
+  schema?: unknown
+  metadata?: unknown
+  is_active?: boolean | null
+  isActive?: boolean | null
+  organization_id?: string | null
+  organizationId?: string | null
+  tenant_id?: string | null
+  tenantId?: string | null
+  created_at?: string | null
+  createdAt?: string | null
+}
+
+type ListOptionSchemasApiResponse = {
+  items?: ListOptionSchemasApiItem[]
+  total?: number
+}
+
+type ListOptionSchemasOutput = {
+  items: Array<Record<string, unknown>>
+  total: number
+  limit: number
+  offset: number
+}
+
+const listOptionSchemasTool = defineApiBackedAiTool<
+  ListOptionSchemasInput,
+  ListOptionSchemasApiResponse,
+  ListOptionSchemasOutput
+>({
+  name: 'catalog.list_option_schemas',
+  displayName: 'List option schemas',
+  description:
+    'List product option schemas (variant axes, e.g. size/color definitions) for the caller tenant + organization.',
+  inputSchema: listOptionSchemasInput,
+  requiredFeatures: ['catalog.products.view'],
+  toOperation: (input, ctx) => {
+    assertTenantScope(ctx as unknown as CatalogToolContext)
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const page = Math.floor(offset / limit) + 1
+    const operation: AiApiOperationRequest = {
+      method: 'GET',
+      path: '/catalog/option-schemas',
+      query: { page, pageSize: limit },
+    }
+    return operation
+  },
+  mapResponse: (response, input) => {
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const data = (response.data ?? {}) as ListOptionSchemasApiResponse
+    const rawItems: ListOptionSchemasApiItem[] = Array.isArray(data.items) ? data.items : []
+    return {
+      items: rawItems.map((row) => {
+        const createdAtRaw = row.created_at ?? row.createdAt ?? null
+        const createdAt = createdAtRaw ? new Date(String(createdAtRaw)).toISOString() : null
+        return {
+          id: row.id,
+          code: row.code,
+          name: row.name,
+          description: row.description ?? null,
+          schema: row.schema,
+          metadata: row.metadata ?? null,
+          isActive: !!(row.is_active ?? row.isActive),
+          organizationId: row.organization_id ?? row.organizationId ?? null,
+          tenantId: row.tenant_id ?? row.tenantId ?? null,
+          createdAt,
+        }
+      }),
+      total: typeof data.total === 'number' ? data.total : 0,
+      limit,
+      offset,
+    }
+  },
+}) as unknown as CatalogAiToolDefinition
+
+const listUnitConversionsInput = z
+  .object({
+    productId: z.string().uuid().optional().describe('Restrict to unit conversions for this product.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max rows (default 50, max 100).'),
+    offset: z.number().int().min(0).optional().describe('Rows to skip (default 0).'),
+  })
+  .passthrough()
+
+type ListUnitConversionsInput = z.infer<typeof listUnitConversionsInput>
+
+type ListUnitConversionsApiItem = {
+  id?: string
+  product_id?: string | null
+  productId?: string | null
+  unit_code?: string | null
+  unitCode?: string | null
+  to_base_factor?: string | number | null
+  toBaseFactor?: string | number | null
+  sort_order?: number | null
+  sortOrder?: number | null
+  is_active?: boolean | null
+  isActive?: boolean | null
+  metadata?: unknown
+  organization_id?: string | null
+  organizationId?: string | null
+  tenant_id?: string | null
+  tenantId?: string | null
+  created_at?: string | null
+  createdAt?: string | null
+}
+
+type ListUnitConversionsApiResponse = {
+  items?: ListUnitConversionsApiItem[]
+  total?: number
+}
+
+type ListUnitConversionsOutput = {
+  items: Array<Record<string, unknown>>
+  total: number
+  limit: number
+  offset: number
+}
+
+const listUnitConversionsTool = defineApiBackedAiTool<
+  ListUnitConversionsInput,
+  ListUnitConversionsApiResponse,
+  ListUnitConversionsOutput
+>({
+  name: 'catalog.list_unit_conversions',
+  displayName: 'List unit conversions',
+  description:
+    'List product unit conversions (alternate units with `toBaseFactor`) for the caller tenant + organization. Optionally narrow by product.',
+  inputSchema: listUnitConversionsInput,
+  requiredFeatures: ['catalog.products.view'],
+  toOperation: (input, ctx) => {
+    assertTenantScope(ctx as unknown as CatalogToolContext)
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const page = Math.floor(offset / limit) + 1
+    const query: Record<string, string | number | boolean | null | undefined> = {
+      page,
+      pageSize: limit,
+    }
+    if (input.productId) query.productId = input.productId
+    const operation: AiApiOperationRequest = {
+      method: 'GET',
+      path: '/catalog/product-unit-conversions',
+      query,
+    }
+    return operation
+  },
+  mapResponse: (response, input) => {
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const data = (response.data ?? {}) as ListUnitConversionsApiResponse
+    const rawItems: ListUnitConversionsApiItem[] = Array.isArray(data.items) ? data.items : []
+    return {
+      items: rawItems.map((row) => {
+        const createdAtRaw = row.created_at ?? row.createdAt ?? null
+        const createdAt = createdAtRaw ? new Date(String(createdAtRaw)).toISOString() : null
+        const toBaseFactor = row.to_base_factor ?? row.toBaseFactor ?? null
+        return {
+          id: row.id,
+          unitCode: row.unit_code ?? row.unitCode ?? null,
+          toBaseFactor: toBaseFactor === null ? null : String(toBaseFactor),
+          sortOrder: row.sort_order ?? row.sortOrder ?? 0,
+          isActive: !!(row.is_active ?? row.isActive),
+          productId: row.product_id ?? row.productId ?? null,
+          metadata: row.metadata ?? null,
+          organizationId: row.organization_id ?? row.organizationId ?? null,
+          tenantId: row.tenant_id ?? row.tenantId ?? null,
+          createdAt,
+        }
+      }),
+      total: typeof data.total === 'number' ? data.total : 0,
+      limit,
+      offset,
+    }
+  },
+}) as unknown as CatalogAiToolDefinition
+
+export const configurationAiTools: CatalogAiToolDefinition[] = [
+  listOptionSchemasTool,
+  listUnitConversionsTool,
+]
+
+export default configurationAiTools

package/src/modules/catalog/ai-tools/media-tags-pack.ts

@@ -0,0 +1,127 @@
+/**
+ * `catalog.list_product_media` + `catalog.list_product_tags` (Phase 1 WS-C,
+ * Step 3.10).
+ *
+ * Media tool returns metadata only — bytes flow through the Step 3.7
+ * attachment bridge, not this enumeration. Tags tool mirrors the existing
+ * `/api/catalog/tags` GET surface (feature-gated the same way).
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { E } from '#generated/entities.ids.generated'
+import { Attachment } from '@open-mercato/core/modules/attachments/data/entities'
+import { CatalogProductTag, CatalogProductTagAssignment } from '../data/entities'
+import { assertTenantScope, type CatalogAiToolDefinition, type CatalogToolContext } from './types'
+
+function resolveEm(ctx: CatalogToolContext): EntityManager {
+  return ctx.container.resolve<EntityManager>('em')
+}
+
+function buildScope(ctx: CatalogToolContext, tenantId: string) {
+  return { tenantId, organizationId: ctx.organizationId }
+}
+
+const listProductMediaInput = z
+  .object({
+    productId: z.string().uuid().describe('Catalog product id (UUID).'),
+    limit: z.number().int().min(1).max(100).optional().describe('Max rows (default 50, max 100).'),
+    offset: z.number().int().min(0).optional().describe('Rows to skip (default 0).'),
+  })
+  .passthrough()
+
+const listProductMediaTool: CatalogAiToolDefinition = {
+  name: 'catalog.list_product_media',
+  displayName: 'List product media',
+  description:
+    'Enumerate media attachments (metadata only) associated with a catalog product. Use the attachment bridge (Step 3.7) to fetch bytes.',
+  inputSchema: listProductMediaInput,
+  requiredFeatures: ['catalog.products.view'],
+  tags: ['read', 'catalog'],
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = listProductMediaInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const where: Record<string, unknown> = {
+      tenantId,
+      entityId: E.catalog.catalog_product,
+      recordId: input.productId,
+    }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const [rows, total] = await Promise.all([
+      findWithDecryption<Attachment>(
+        em,
+        Attachment,
+        where as any,
+        { limit, offset, orderBy: { createdAt: 'asc' } as any } as any,
+        buildScope(ctx, tenantId),
+      ),
+      em.count(Attachment, where as any),
+    ])
+    const filtered = rows.filter((row) => (row.tenantId ?? null) === tenantId)
+    return {
+      items: filtered.map((row) => ({
+        id: row.id,
+        fileName: row.fileName,
+        mimeType: row.mimeType,
+        fileSize: row.fileSize,
+        url: row.url,
+        storageDriver: row.storageDriver,
+        partitionCode: row.partitionCode,
+        entityId: row.entityId,
+        recordId: row.recordId,
+        organizationId: row.organizationId ?? null,
+        tenantId: row.tenantId ?? null,
+        createdAt: row.createdAt ? new Date(row.createdAt).toISOString() : null,
+      })),
+      total,
+      limit,
+      offset,
+    }
+  },
+}
+
+const listProductTagsInput = z
+  .object({
+    productId: z.string().uuid().describe('Catalog product id (UUID).'),
+  })
+  .passthrough()
+
+const listProductTagsTool: CatalogAiToolDefinition = {
+  name: 'catalog.list_product_tags',
+  displayName: 'List product tags',
+  description:
+    'Enumerate tags assigned to a catalog product (label + slug). Returns { items, total }.',
+  inputSchema: listProductTagsInput,
+  requiredFeatures: ['catalog.products.view'],
+  tags: ['read', 'catalog'],
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = listProductTagsInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const where: Record<string, unknown> = { tenantId, product: input.productId }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const assignments = await findWithDecryption<CatalogProductTagAssignment>(
+      em,
+      CatalogProductTagAssignment,
+      where as any,
+      { populate: ['tag'] as any } as any,
+      buildScope(ctx, tenantId),
+    )
+    const filtered = assignments.filter((assignment) => assignment.tenantId === tenantId)
+    const items = filtered
+      .map((assignment) => {
+        const tag = (assignment as any).tag as CatalogProductTag | string | null
+        if (!tag || typeof tag === 'string') return null
+        return { id: tag.id, label: tag.label, slug: tag.slug }
+      })
+      .filter((value): value is { id: string; label: string; slug: string } => value !== null)
+    return { items, total: items.length }
+  },
+}
+
+export const mediaTagsAiTools: CatalogAiToolDefinition[] = [listProductMediaTool, listProductTagsTool]
+
+export default mediaTagsAiTools