@open-mercato/core 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

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

@@ -0,0 +1,387 @@
+/**
+ * `catalog.list_products` + `catalog.get_product` (Phase 1 WS-C, Step 3.10).
+ *
+ * Read-only tools scoped to `ctx.tenantId` + `ctx.organizationId`. Mutation
+ * tools are deferred to Step 5.14 under the pending-action contract.
+ *
+ * Phase 3b of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * `catalog.list_products` is now an API-backed wrapper over
+ * `GET /api/catalog/products`. Tool name, schema, requiredFeatures, and
+ * output shape are unchanged.
+ */
+import type { EntityManager } from '@mikro-orm/postgresql'
+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 { 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 { Attachment } from '@open-mercato/core/modules/attachments/data/entities'
+import {
+  CatalogProduct,
+  CatalogProductCategoryAssignment,
+  CatalogProductTagAssignment,
+  CatalogProductTag,
+  CatalogProductVariant,
+  CatalogProductPrice,
+  CatalogProductUnitConversion,
+} from '../data/entities'
+import { assertTenantScope, type CatalogAiToolDefinition, type CatalogToolContext } from './types'
+
+function resolveEm(ctx: CatalogToolContext | AiToolExecutionContext): EntityManager {
+  return ctx.container.resolve<EntityManager>('em')
+}
+
+function buildScope(ctx: CatalogToolContext | AiToolExecutionContext, tenantId: string) {
+  return { tenantId, organizationId: ctx.organizationId }
+}
+
+const listProductsInput = z
+  .object({
+    q: z.string().trim().min(1).optional().describe('Optional search text matched against title / subtitle / sku / handle.'),
+    limit: z.number().int().min(1).max(100).optional().describe('Maximum rows to return (default 50, max 100).'),
+    offset: z.number().int().min(0).optional().describe('Number of rows to skip (default 0).'),
+    categoryId: z.string().uuid().optional().describe('Restrict to products assigned to this catalog category.'),
+    tagIds: z.array(z.string().uuid()).optional().describe('Restrict to products carrying at least one of these tag ids.'),
+    active: z.boolean().optional().describe('When true, only active (not archived) products are returned.'),
+  })
+  .passthrough()
+
+type ListProductsInput = z.infer<typeof listProductsInput>
+
+type ListProductsApiItem = {
+  id?: string
+  title?: string | null
+  subtitle?: string | null
+  sku?: string | null
+  handle?: string | null
+  product_type?: string | null
+  productType?: string | null
+  status_entry_id?: string | null
+  statusEntryId?: string | null
+  primary_currency_code?: string | null
+  primaryCurrencyCode?: string | null
+  default_media_id?: string | null
+  defaultMediaId?: string | null
+  default_media_url?: string | null
+  defaultMediaUrl?: string | null
+  is_active?: boolean | null
+  isActive?: boolean | null
+  is_configurable?: boolean | null
+  isConfigurable?: boolean | null
+  organization_id?: string | null
+  organizationId?: string | null
+  tenant_id?: string | null
+  tenantId?: string | null
+  created_at?: string | null
+  createdAt?: string | null
+  updated_at?: string | null
+  updatedAt?: string | null
+}
+
+type ListProductsApiResponse = {
+  items?: ListProductsApiItem[]
+  total?: number
+}
+
+type ListProductsOutput = {
+  items: Array<Record<string, unknown>>
+  total: number
+  limit: number
+  offset: number
+}
+
+const listProductsTool = defineApiBackedAiTool<
+  ListProductsInput,
+  ListProductsApiResponse,
+  ListProductsOutput
+>({
+  name: 'catalog.list_products',
+  displayName: 'List products',
+  description:
+    'Search / list catalog products for the caller tenant + organization. Returns { items, total, limit, offset }.',
+  inputSchema: listProductsInput,
+  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.q?.trim()) query.search = input.q.trim()
+    if (input.categoryId) query.categoryIds = input.categoryId
+    if (input.tagIds && input.tagIds.length > 0) query.tagIds = input.tagIds.join(',')
+    if (input.active === true) query.isActive = 'true'
+
+    const operation: AiApiOperationRequest = {
+      method: 'GET',
+      path: '/catalog/products',
+      query,
+    }
+    return operation
+  },
+  mapResponse: (response, input) => {
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const data = (response.data ?? {}) as ListProductsApiResponse
+    const rawItems: ListProductsApiItem[] = 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 updatedAtRaw = row.updated_at ?? row.updatedAt ?? null
+        const updatedAt = updatedAtRaw ? new Date(String(updatedAtRaw)).toISOString() : null
+        return {
+          id: row.id,
+          title: row.title ?? null,
+          subtitle: row.subtitle ?? null,
+          sku: row.sku ?? null,
+          handle: row.handle ?? null,
+          productType: row.product_type ?? row.productType ?? null,
+          statusEntryId: row.status_entry_id ?? row.statusEntryId ?? null,
+          primaryCurrencyCode: row.primary_currency_code ?? row.primaryCurrencyCode ?? null,
+          defaultMediaId: row.default_media_id ?? row.defaultMediaId ?? null,
+          defaultMediaUrl: row.default_media_url ?? row.defaultMediaUrl ?? null,
+          imageUrl: row.default_media_url ?? row.defaultMediaUrl ?? null,
+          isActive: !!(row.is_active ?? row.isActive),
+          isConfigurable: !!(row.is_configurable ?? row.isConfigurable),
+          organizationId: row.organization_id ?? row.organizationId ?? null,
+          tenantId: row.tenant_id ?? row.tenantId ?? null,
+          createdAt,
+          updatedAt,
+        }
+      }),
+      total: typeof data.total === 'number' ? data.total : 0,
+      limit,
+      offset,
+    }
+  },
+}) as unknown as CatalogAiToolDefinition
+
+const getProductInput = z.object({
+  productId: z.string().uuid().describe('Catalog product id (UUID).'),
+  includeRelated: z
+    .boolean()
+    .optional()
+    .describe(
+      'When true, include categories, tags, variants, prices (base + offers), media (metadata only), unit conversions, and custom fields (each related list capped at 100).',
+    ),
+})
+
+const getProductTool: CatalogAiToolDefinition = {
+  name: 'catalog.get_product',
+  displayName: 'Get product',
+  description:
+    'Fetch a catalog product by id with core fields and (optionally) categories, tags, variants, prices, media metadata, unit conversions, and custom fields. Returns { found: false } when the record is outside tenant/org scope or missing.',
+  inputSchema: getProductInput,
+  requiredFeatures: ['catalog.products.view'],
+  tags: ['read', 'catalog'],
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = getProductInput.parse(rawInput)
+    const em = resolveEm(ctx)
+    const where: Record<string, unknown> = {
+      id: input.productId,
+      tenantId,
+      deletedAt: null,
+    }
+    if (ctx.organizationId) where.organizationId = ctx.organizationId
+    const product = await findOneWithDecryption<CatalogProduct>(
+      em,
+      CatalogProduct,
+      where as any,
+      undefined,
+      buildScope(ctx, tenantId),
+    )
+    if (!product || product.tenantId !== tenantId) {
+      return { found: false as const, productId: input.productId }
+    }
+
+    let related: Record<string, unknown> | null = null
+    let customFields: Record<string, unknown> = {}
+    if (input.includeRelated) {
+      const scope = buildScope(ctx, tenantId)
+      const [
+        categoryAssignments,
+        tagAssignments,
+        variants,
+        prices,
+        mediaAttachments,
+        unitConversions,
+        customFieldValues,
+      ] = await Promise.all([
+        findWithDecryption<CatalogProductCategoryAssignment>(
+          em,
+          CatalogProductCategoryAssignment,
+          { tenantId, product: product.id } as any,
+          { limit: 100, populate: ['category'] as any } as any,
+          scope,
+        ),
+        findWithDecryption<CatalogProductTagAssignment>(
+          em,
+          CatalogProductTagAssignment,
+          { tenantId, product: product.id } as any,
+          { limit: 100, populate: ['tag'] as any } as any,
+          scope,
+        ),
+        findWithDecryption<CatalogProductVariant>(
+          em,
+          CatalogProductVariant,
+          { tenantId, product: product.id, deletedAt: null } as any,
+          { limit: 100, orderBy: { createdAt: 'asc' } as any } as any,
+          scope,
+        ),
+        findWithDecryption<CatalogProductPrice>(
+          em,
+          CatalogProductPrice,
+          { tenantId, product: product.id } as any,
+          { limit: 100, orderBy: { createdAt: 'asc' } as any } as any,
+          scope,
+        ),
+        findWithDecryption<Attachment>(
+          em,
+          Attachment,
+          { tenantId, entityId: E.catalog.catalog_product, recordId: product.id } as any,
+          { limit: 100, orderBy: { createdAt: 'asc' } as any } as any,
+          scope,
+        ),
+        findWithDecryption<CatalogProductUnitConversion>(
+          em,
+          CatalogProductUnitConversion,
+          { tenantId, product: product.id, deletedAt: null } as any,
+          { limit: 100, orderBy: { sortOrder: 'asc', createdAt: 'asc' } as any } as any,
+          scope,
+        ),
+        loadCustomFieldValues({
+          em,
+          entityId: E.catalog.catalog_product,
+          recordIds: [product.id],
+          tenantIdByRecord: { [product.id]: product.tenantId ?? null },
+          organizationIdByRecord: { [product.id]: product.organizationId ?? null },
+          tenantFallbacks: [product.tenantId ?? tenantId].filter((value): value is string => !!value),
+        }),
+      ])
+      customFields = customFieldValues[product.id] ?? {}
+      related = {
+        categories: categoryAssignments
+          .map((assignment) => {
+            const category = (assignment as any).category
+            if (!category || typeof category === 'string') {
+              const fallbackId = typeof category === 'string' ? category : null
+              return fallbackId ? { id: fallbackId, name: null, slug: null } : null
+            }
+            return {
+              id: category.id,
+              name: category.name ?? null,
+              slug: category.slug ?? null,
+            }
+          })
+          .filter((value): value is { id: string; name: string | null; slug: string | null } => value !== null),
+        tags: tagAssignments
+          .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),
+        variants: variants.map((variant) => ({
+          id: variant.id,
+          name: variant.name ?? null,
+          sku: variant.sku ?? null,
+          barcode: variant.barcode ?? null,
+          optionValues: variant.optionValues ?? null,
+          defaultMediaId: variant.defaultMediaId ?? null,
+          defaultMediaUrl: variant.defaultMediaUrl ?? null,
+          isDefault: !!variant.isDefault,
+          isActive: !!variant.isActive,
+        })),
+        prices: prices.map((price) => ({
+          id: price.id,
+          priceKindId: (price as any).priceKind && typeof (price as any).priceKind === 'object'
+            ? (price as any).priceKind.id
+            : (price as any).priceKind ?? null,
+          currencyCode: price.currencyCode,
+          kind: price.kind,
+          minQuantity: price.minQuantity,
+          maxQuantity: price.maxQuantity ?? null,
+          unitPriceNet: price.unitPriceNet ?? null,
+          unitPriceGross: price.unitPriceGross ?? null,
+          channelId: price.channelId ?? null,
+          offerId: (price as any).offer && typeof (price as any).offer === 'object'
+            ? (price as any).offer.id
+            : (price as any).offer ?? null,
+          variantId: (price as any).variant && typeof (price as any).variant === 'object'
+            ? (price as any).variant.id
+            : (price as any).variant ?? null,
+          startsAt: price.startsAt ? new Date(price.startsAt).toISOString() : null,
+          endsAt: price.endsAt ? new Date(price.endsAt).toISOString() : null,
+        })),
+        media: mediaAttachments.map((attachment) => ({
+          id: attachment.id,
+          fileName: attachment.fileName,
+          mimeType: attachment.mimeType,
+          fileSize: attachment.fileSize,
+          url: attachment.url,
+        })),
+        unitConversions: unitConversions.map((row) => ({
+          id: row.id,
+          unitCode: row.unitCode,
+          toBaseFactor: row.toBaseFactor,
+          sortOrder: row.sortOrder,
+          isActive: !!row.isActive,
+        })),
+        customFields,
+      }
+    }
+
+    return {
+      found: true as const,
+      product: {
+        id: product.id,
+        title: product.title,
+        subtitle: product.subtitle ?? null,
+        description: product.description ?? null,
+        sku: product.sku ?? null,
+        handle: product.handle ?? null,
+        productType: product.productType,
+        statusEntryId: product.statusEntryId ?? null,
+        primaryCurrencyCode: product.primaryCurrencyCode ?? null,
+        taxRate: product.taxRate ?? null,
+        taxRateId: product.taxRateId ?? null,
+        defaultUnit: product.defaultUnit ?? null,
+        defaultSalesUnit: product.defaultSalesUnit ?? null,
+        defaultSalesUnitQuantity: product.defaultSalesUnitQuantity ?? null,
+        unitPriceEnabled: !!product.unitPriceEnabled,
+        unitPriceReferenceUnit: product.unitPriceReferenceUnit ?? null,
+        unitPriceBaseQuantity: product.unitPriceBaseQuantity ?? null,
+        defaultMediaId: product.defaultMediaId ?? null,
+        defaultMediaUrl: product.defaultMediaUrl ?? null,
+        imageUrl: product.defaultMediaUrl ?? null,
+        weightValue: product.weightValue ?? null,
+        weightUnit: product.weightUnit ?? null,
+        dimensions: product.dimensions ?? null,
+        metadata: product.metadata ?? null,
+        customFieldsetCode: product.customFieldsetCode ?? null,
+        isConfigurable: !!product.isConfigurable,
+        isActive: !!product.isActive,
+        organizationId: product.organizationId ?? null,
+        tenantId: product.tenantId ?? null,
+        createdAt: product.createdAt ? new Date(product.createdAt).toISOString() : null,
+        updatedAt: product.updatedAt ? new Date(product.updatedAt).toISOString() : null,
+      },
+      customFields,
+      related,
+    }
+  },
+}
+
+export const productsAiTools: CatalogAiToolDefinition[] = [listProductsTool, getProductTool]
+
+export default productsAiTools

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

@@ -0,0 +1,84 @@
+/**
+ * `catalog.show_stats` — example dynamic UI-part tool.
+ *
+ * Demonstrates the generic UI-part contract: any tool can return a JSON
+ * envelope `{ uiPart: { componentId, payload } }` (or a `uiParts: [...]`
+ * array) and the chat client surfaces it inline. The catalog stats card
+ * is the canonical dynamic example; module authors copy this file +
+ * `components/CatalogStatsCard.tsx` to ship their own cards.
+ *
+ * Read-only — no `prepareMutation` gate, no DB writes.
+ */
+
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { z } from 'zod'
+import { CatalogProduct, CatalogProductCategory, CatalogProductTag } from '../data/entities'
+import { assertTenantScope, type CatalogAiToolDefinition, type CatalogToolContext } from './types'
+
+function resolveEm(ctx: CatalogToolContext): EntityManager {
+  return ctx.container.resolve<EntityManager>('em')
+}
+
+const showStatsInput = z
+  .object({
+    note: z
+      .string()
+      .max(160)
+      .optional()
+      .describe(
+        'Optional one-line note to render below the stats grid (e.g. "as of today" or a quick observation).',
+      ),
+  })
+  .passthrough()
+
+const showStatsTool: CatalogAiToolDefinition = {
+  name: 'catalog.show_stats',
+  displayName: 'Show catalog stats',
+  description:
+    'Displays a compact "Catalog overview" card in the chat with live counts: total products, active products, categories, and tags for the current tenant. Use this when the operator asks for a high-level snapshot of the catalog (e.g. "give me catalog stats", "how many products do we have", "show overview"). Returns a `uiPart` envelope so the registered `catalog.stats-card` component renders inline — no fenced code block needed.',
+  inputSchema: showStatsInput,
+  requiredFeatures: ['catalog.products.view'],
+  tags: ['read', 'catalog', 'stats', 'ui'],
+  isMutation: false,
+  handler: async (rawInput, ctx) => {
+    const { tenantId } = assertTenantScope(ctx)
+    const input = showStatsInput.parse(rawInput)
+    const em = resolveEm(ctx)
+
+    // CatalogProductTag has no soft-delete column, so the `deletedAt: null`
+    // filter (used for products + categories which DO have it) would throw
+    // `Trying to query by not existing property CatalogProductTag.deletedAt`.
+    // Build per-entity scopes that only include the fields that actually exist.
+    const tenantScope: Record<string, unknown> = { tenantId }
+    if (ctx.organizationId) tenantScope.organizationId = ctx.organizationId
+    const softDeleteScope: Record<string, unknown> = { ...tenantScope, deletedAt: null }
+
+    const [products, activeProducts, categories, tags] = await Promise.all([
+      em.count(CatalogProduct, softDeleteScope as never),
+      em.count(CatalogProduct, { ...softDeleteScope, isActive: true } as never),
+      em.count(CatalogProductCategory, softDeleteScope as never),
+      em.count(CatalogProductTag, tenantScope as never),
+    ])
+
+    return {
+      uiPart: {
+        componentId: 'catalog.stats-card',
+        payload: {
+          products,
+          activeProducts,
+          categories,
+          tags,
+          generatedAt: new Date().toISOString(),
+          note: input.note,
+        },
+      },
+      // Plain-text mirror so the model can summarize what it just rendered
+      // without parsing the UI part envelope itself.
+      summary: `Catalog snapshot: ${products} products (${activeProducts} active), ${categories} categories, ${tags} tags.`,
+    }
+  },
+}
+
+export const statsAiTools: CatalogAiToolDefinition[] = [showStatsTool]
+
+export default statsAiTools

package/src/modules/catalog/ai-tools/types.ts

@@ -0,0 +1,81 @@
+/**
+ * Local AI tool shape for the catalog module (Phase 1 WS-C, Step 3.10).
+ *
+ * Mirrors the pattern established by the customers pack (Step 3.9): the
+ * catalog module declares its read-only tools as plain objects whose shape
+ * is a strict subset of `AiToolDefinition` from `@open-mercato/ai-assistant`.
+ * Keeping the shape local avoids pulling the ai-assistant package into the
+ * core module graph for jest and sidesteps a cross-package `moduleNameMapper`.
+ * The generator walks every module root for a default / `aiTools` export with
+ * this shape.
+ */
+import type { z } from 'zod'
+import type { AwilixContainer } from 'awilix'
+
+export interface CatalogToolContext {
+  tenantId: string | null
+  organizationId: string | null
+  userId: string | null
+  container: AwilixContainer
+  userFeatures: string[]
+  isSuperAdmin: boolean
+  apiKeySecret?: string
+  sessionId?: string
+}
+
+/**
+ * Shape returned by `loadBeforeRecord` on a single-record mutation tool.
+ * Mirrors `AiToolLoadBeforeSingleRecord` from `@open-mercato/ai-assistant/lib/types`.
+ */
+export interface CatalogToolLoadBeforeSingleRecord {
+  recordId: string
+  entityType: string
+  recordVersion: string | null
+  before: Record<string, unknown>
+}
+
+/**
+ * Shape returned by `loadBeforeRecords` on a bulk mutation tool. Mirrors
+ * `AiToolLoadBeforeRecord` from `@open-mercato/ai-assistant/lib/types` — the
+ * Step 5.6 `prepareMutation` runtime wraps this into the `records[]` array on
+ * the emitted `mutation-preview-card`.
+ */
+export interface CatalogToolLoadBeforeRecord {
+  recordId: string
+  entityType: string
+  label: string
+  recordVersion: string | null
+  before: Record<string, unknown>
+}
+
+export interface CatalogAiToolDefinition<TInput = unknown, TOutput = unknown> {
+  name: string
+  displayName?: string
+  description: string
+  inputSchema: z.ZodType<TInput>
+  requiredFeatures?: string[]
+  tags?: string[]
+  isMutation?: boolean
+  isBulk?: boolean
+  maxCallsPerTurn?: number
+  supportsAttachments?: boolean
+  handler: (input: TInput, context: CatalogToolContext) => Promise<TOutput>
+  loadBeforeRecord?: (
+    input: TInput,
+    context: CatalogToolContext,
+  ) => Promise<CatalogToolLoadBeforeSingleRecord | null>
+  loadBeforeRecords?: (
+    input: TInput,
+    context: CatalogToolContext,
+  ) => Promise<CatalogToolLoadBeforeRecord[]>
+}
+
+export function assertTenantScope(ctx: CatalogToolContext): {
+  tenantId: string
+  organizationId: string | null
+} {
+  if (!ctx.tenantId) {
+    throw new Error('Tenant context is required for catalog.* tools')
+  }
+  return { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+}

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

@@ -0,0 +1,147 @@
+/**
+ * `catalog.list_variants` (Phase 1 WS-C, Step 3.10).
+ *
+ * Enumerate variants for a single product with option values + media refs.
+ *
+ * Phase 3b of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * `catalog.list_variants` is now an API-backed wrapper over
+ * `GET /api/catalog/variants`. Tool name, schema, requiredFeatures, and
+ * output shape 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 listVariantsInput = z
+  .object({
+    productId: z.string().uuid().describe('Parent 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()
+
+type ListVariantsInput = z.infer<typeof listVariantsInput>
+
+type ListVariantsApiItem = {
+  id?: string
+  product_id?: string | null
+  productId?: string | null
+  name?: string | null
+  sku?: string | null
+  barcode?: string | null
+  status_entry_id?: string | null
+  statusEntryId?: string | null
+  option_values?: unknown
+  optionValues?: unknown
+  default_media_id?: string | null
+  defaultMediaId?: string | null
+  default_media_url?: string | null
+  defaultMediaUrl?: string | null
+  weight_value?: string | number | null
+  weightValue?: string | number | null
+  weight_unit?: string | null
+  weightUnit?: string | null
+  dimensions?: unknown
+  tax_rate?: string | number | null
+  taxRate?: string | number | null
+  tax_rate_id?: string | null
+  taxRateId?: string | null
+  is_default?: boolean | null
+  isDefault?: boolean | null
+  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 ListVariantsApiResponse = {
+  items?: ListVariantsApiItem[]
+  total?: number
+}
+
+type ListVariantsOutput = {
+  items: Array<Record<string, unknown>>
+  total: number
+  limit: number
+  offset: number
+}
+
+const listVariantsTool = defineApiBackedAiTool<
+  ListVariantsInput,
+  ListVariantsApiResponse,
+  ListVariantsOutput
+>({
+  name: 'catalog.list_variants',
+  displayName: 'List variants',
+  description:
+    'List the variants of a catalog product (including option values, SKU, barcode, default media ref). Returns { items, total, limit, offset }.',
+  inputSchema: listVariantsInput,
+  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,
+      productId: input.productId,
+    }
+
+    const operation: AiApiOperationRequest = {
+      method: 'GET',
+      path: '/catalog/variants',
+      query,
+    }
+    return operation
+  },
+  mapResponse: (response, input) => {
+    const limit = input.limit ?? 50
+    const offset = input.offset ?? 0
+    const data = (response.data ?? {}) as ListVariantsApiResponse
+    const rawItems: ListVariantsApiItem[] = 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,
+          name: row.name ?? null,
+          sku: row.sku ?? null,
+          barcode: row.barcode ?? null,
+          statusEntryId: row.status_entry_id ?? row.statusEntryId ?? null,
+          optionValues: row.option_values ?? row.optionValues ?? null,
+          defaultMediaId: row.default_media_id ?? row.defaultMediaId ?? null,
+          defaultMediaUrl: row.default_media_url ?? row.defaultMediaUrl ?? null,
+          weightValue: row.weight_value ?? row.weightValue ?? null,
+          weightUnit: row.weight_unit ?? row.weightUnit ?? null,
+          dimensions: row.dimensions ?? null,
+          taxRate: row.tax_rate ?? row.taxRate ?? null,
+          taxRateId: row.tax_rate_id ?? row.taxRateId ?? null,
+          isDefault: !!(row.is_default ?? row.isDefault),
+          isActive: !!(row.is_active ?? row.isActive),
+          productId: row.product_id ?? row.productId ?? 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 variantsAiTools: CatalogAiToolDefinition[] = [listVariantsTool]
+
+export default variantsAiTools