@open-mercato/core 0.4.5-develop-636d33c995 → 0.4.5-develop-3d8e759e45

package/src/modules/inbox_ops/lib/executionHelpers.ts

@@ -0,0 +1,527 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { EntityClass } from '@mikro-orm/core'
+import type { AwilixContainer } from 'awilix'
+import type { EventBus } from '@open-mercato/events/types'
+import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
+import type { CommandBus, CommandRuntimeContext } from '@open-mercato/shared/lib/commands'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import type { InboxActionExecutionContext } from '@open-mercato/shared/modules/inbox-actions'
+import type { CrossModuleEntities } from './executionEngine'
+export { formatZodErrors } from './validation'
+
+// ---------------------------------------------------------------------------
+// Context type used by helper functions (concrete types for ORM/DI access)
+// ---------------------------------------------------------------------------
+
+export interface ExecutionHelperContext {
+  em: EntityManager
+  userId: string
+  tenantId: string
+  organizationId: string
+  eventBus?: EventBus | null
+  container: AwilixContainer
+  auth?: AuthContext
+  entities?: CrossModuleEntities
+}
+
+/**
+ * Cast InboxActionExecutionContext (from shared) to the concrete helper context.
+ * The inbox-actions.ts handlers receive InboxActionExecutionContext but helpers
+ * need concrete EntityManager / AwilixContainer types.
+ */
+export function asHelperContext(ctx: InboxActionExecutionContext): ExecutionHelperContext {
+  return ctx as unknown as ExecutionHelperContext
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class ExecutionError extends Error {
+  statusCode: number
+
+  constructor(message: string, statusCode = 400) {
+    super(message)
+    this.statusCode = statusCode
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Command execution
+// ---------------------------------------------------------------------------
+
+export async function executeCommand<TInput, TResult>(
+  ctx: ExecutionHelperContext,
+  commandId: string,
+  input: TInput,
+): Promise<TResult> {
+  const commandBus = ctx.container.resolve('commandBus') as CommandBus
+  if (!commandBus || typeof commandBus.execute !== 'function') {
+    throw new ExecutionError('Command bus is not available', 503)
+  }
+
+  const auth =
+    ctx.auth ??
+    ({
+      sub: ctx.userId,
+      userId: ctx.userId,
+      tenantId: ctx.tenantId,
+      orgId: ctx.organizationId,
+      isSuperAdmin: false,
+    } satisfies Exclude<AuthContext, null>)
+
+  const commandContext: CommandRuntimeContext = {
+    container: ctx.container,
+    auth,
+    organizationScope: null,
+    selectedOrganizationId: ctx.organizationId,
+    organizationIds: [ctx.organizationId],
+  }
+
+  const { result } = await commandBus.execute<TInput, TResult>(commandId, {
+    input,
+    ctx: commandContext,
+  })
+
+  return result
+}
+
+// ---------------------------------------------------------------------------
+// Entity resolution
+// ---------------------------------------------------------------------------
+
+export function resolveEntityClass<K extends keyof CrossModuleEntities>(
+  ctx: ExecutionHelperContext,
+  key: K,
+): CrossModuleEntities[K] | null {
+  const fromEntities = ctx.entities?.[key]
+  if (fromEntities) return fromEntities
+  try { return ctx.container.resolve(key) } catch { return null }
+}
+
+// ---------------------------------------------------------------------------
+// Source metadata
+// ---------------------------------------------------------------------------
+
+export function buildSourceMetadata(actionId: string, proposalId: string): Record<string, unknown> {
+  return {
+    source: 'inbox_ops',
+    inboxOpsActionId: actionId,
+    inboxOpsProposalId: proposalId,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Order resolution
+// ---------------------------------------------------------------------------
+
+export async function resolveOrderByReference(
+  ctx: ExecutionHelperContext,
+  orderId?: string,
+  orderNumber?: string,
+): Promise<{ id: string; orderNumber: string; currencyCode: string; comments?: string | null }> {
+  const SalesOrderClass = resolveEntityClass(ctx, 'SalesOrder')
+  if (!SalesOrderClass) {
+    throw new ExecutionError('Sales module entities not available', 503)
+  }
+
+  const where: Record<string, unknown> = {
+    tenantId: ctx.tenantId,
+    organizationId: ctx.organizationId,
+    deletedAt: null,
+  }
+  if (orderId) {
+    where.id = orderId
+  } else if (orderNumber && orderNumber.trim().length > 0) {
+    where.orderNumber = orderNumber.trim()
+  } else {
+    throw new ExecutionError('Order reference is required', 400)
+  }
+
+  const order = await findOneWithDecryption(
+    ctx.em,
+    SalesOrderClass,
+    where,
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  if (!order) {
+    throw new ExecutionError('Referenced order not found', 404)
+  }
+  return order
+}
+
+// ---------------------------------------------------------------------------
+// Channel resolution
+// ---------------------------------------------------------------------------
+
+export async function resolveFirstChannelId(ctx: ExecutionHelperContext): Promise<string | null> {
+  const SalesChannelClass = resolveEntityClass(ctx, 'SalesChannel')
+  if (!SalesChannelClass) return null
+
+  try {
+    const channel = await findOneWithDecryption(
+      ctx.em,
+      SalesChannelClass,
+      {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
+        deletedAt: null,
+      },
+      { orderBy: { name: 'ASC' } },
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+    return channel?.id ?? null
+  } catch {
+    return null
+  }
+}
+
+export async function resolveChannelCurrency(
+  ctx: ExecutionHelperContext,
+  channelId: string | null,
+): Promise<string | null> {
+  const SalesChannelClass = resolveEntityClass(ctx, 'SalesChannel')
+  if (!SalesChannelClass) return null
+
+  try {
+    const where: Record<string, unknown> = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    }
+    if (channelId) where.id = channelId
+    const channel = await findOneWithDecryption(
+      ctx.em,
+      SalesChannelClass,
+      where,
+      channelId ? undefined : { orderBy: { name: 'ASC' } },
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+    return channel?.currencyCode ?? null
+  } catch {
+    return null
+  }
+}
+
+export async function resolveEffectiveDocumentKind(
+  ctx: ExecutionHelperContext,
+  channelId: string,
+): Promise<'order' | 'quote'> {
+  const SalesChannelClass = resolveEntityClass(ctx, 'SalesChannel')
+  if (!SalesChannelClass) return 'order'
+
+  const channel = await findOneWithDecryption(
+    ctx.em,
+    SalesChannelClass,
+    {
+      id: channelId,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  if (!channel) return 'order'
+
+  const metadata = channel.metadata as Record<string, unknown> | null
+  if (metadata?.quotesRequired === true) {
+    return 'quote'
+  }
+  return 'order'
+}
+
+// ---------------------------------------------------------------------------
+// Shipment status resolution
+// ---------------------------------------------------------------------------
+
+const SALES_SHIPMENT_STATUS_DICTIONARY_KEY = 'sales.shipment_status'
+
+export async function resolveShipmentStatusEntryId(
+  ctx: ExecutionHelperContext,
+  statusLabel: string,
+): Promise<string | null> {
+  const DictionaryClass = resolveEntityClass(ctx, 'Dictionary')
+  const DictionaryEntryClass = resolveEntityClass(ctx, 'DictionaryEntry')
+  if (!DictionaryClass || !DictionaryEntryClass) return null
+
+  const encryptionScope = { tenantId: ctx.tenantId, organizationId: ctx.organizationId }
+
+  const dictionary = await findOneWithDecryption(
+    ctx.em,
+    DictionaryClass,
+    {
+      key: SALES_SHIPMENT_STATUS_DICTIONARY_KEY,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    encryptionScope,
+  )
+  if (!dictionary) return null
+
+  const entries = await findWithDecryption(
+    ctx.em,
+    DictionaryEntryClass,
+    {
+      dictionary: dictionary.id,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+    },
+    undefined,
+    encryptionScope,
+  )
+  if (!entries.length) return null
+
+  const normalizedTarget = normalizeDictionaryToken(statusLabel)
+  const loweredTarget = statusLabel.trim().toLowerCase()
+
+  const match = entries.find((entry) => {
+    const label = entry.label.trim().toLowerCase()
+    const value = entry.value.trim().toLowerCase()
+    return (
+      entry.normalizedValue === normalizedTarget ||
+      label === loweredTarget ||
+      value === loweredTarget
+    )
+  })
+
+  return match?.id ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Customer / contact resolution
+// ---------------------------------------------------------------------------
+
+export async function resolveCustomerEntityIdByEmail(
+  ctx: ExecutionHelperContext,
+  email: string,
+): Promise<string | null> {
+  const normalized = email.trim().toLowerCase()
+  if (!normalized) return null
+
+  const CustomerEntityClass = resolveEntityClass(ctx, 'CustomerEntity')
+  if (!CustomerEntityClass) return null
+
+  const entity = await findOneWithDecryption(
+    ctx.em,
+    CustomerEntityClass,
+    {
+      primaryEmail: normalized,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  if (entity) return entity.id
+
+  const candidates = await findWithDecryption(
+    ctx.em,
+    CustomerEntityClass,
+    {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    { limit: 100, orderBy: { createdAt: 'DESC' } },
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  const match = candidates.find(
+    (e) => e.primaryEmail && e.primaryEmail.toLowerCase() === normalized,
+  )
+  return match?.id ?? null
+}
+
+export async function resolveContactIdByNameAndType(
+  ctx: ExecutionHelperContext,
+  contactName: string,
+  contactType: string,
+): Promise<string | null> {
+  const CustomerEntityClass = resolveEntityClass(ctx, 'CustomerEntity')
+  if (!CustomerEntityClass) return null
+
+  const normalized = contactName.trim()
+  if (!normalized) return null
+
+  const entity = await findOneWithDecryption(
+    ctx.em,
+    CustomerEntityClass,
+    {
+      displayName: normalized,
+      kind: contactType,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+
+  return entity?.id ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Order line items
+// ---------------------------------------------------------------------------
+
+export interface OrderLineItem {
+  id: string
+  name?: string | null
+}
+
+export async function loadOrderLineItems(
+  ctx: ExecutionHelperContext,
+  orderId: string,
+): Promise<OrderLineItem[]> {
+  try {
+    const result = await executeCommand<Record<string, unknown>, { lines?: OrderLineItem[] }>(
+      ctx,
+      'sales.orders.lines.list',
+      { orderId, organizationId: ctx.organizationId, tenantId: ctx.tenantId },
+    )
+    return result.lines ?? []
+  } catch {
+    return []
+  }
+}
+
+export function matchLineItemByName(
+  orderLines: OrderLineItem[],
+  lineItemName: string,
+): string | null {
+  const target = lineItemName.trim().toLowerCase()
+  if (!target) return null
+
+  const exact = orderLines.find((l) => (l.name || '').trim().toLowerCase() === target)
+  if (exact) return exact.id
+
+  const partial = orderLines.find((l) => {
+    const name = (l.name || '').trim().toLowerCase()
+    return name.includes(target) || target.includes(name)
+  })
+  return partial?.id ?? null
+}
+
+// ---------------------------------------------------------------------------
+// Data normalization utilities
+// ---------------------------------------------------------------------------
+
+export function normalizeAddressSnapshot(
+  address: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    addressLine1: address.line1 ?? address.addressLine1 ?? '',
+    addressLine2: address.line2 ?? address.addressLine2 ?? null,
+    companyName: address.company ?? address.companyName ?? null,
+    name: address.contactName ?? address.name ?? null,
+    city: address.city ?? null,
+    region: address.state ?? address.region ?? null,
+    postalCode: address.postalCode ?? null,
+    country: address.country ?? null,
+  }
+}
+
+export function parseDateToken(value?: string | null): Date | undefined {
+  if (!value) return undefined
+  const parsed = new Date(value)
+  if (Number.isNaN(parsed.getTime())) return undefined
+  return parsed
+}
+
+export function parseNumberToken(value: string, fieldName: string): number {
+  const parsed = Number(value)
+  if (!Number.isFinite(parsed)) {
+    throw new ExecutionError(`Invalid numeric value for ${fieldName}`, 400)
+  }
+  return parsed
+}
+
+export function normalizeDictionaryToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[\s-]+/g, '_')
+}
+
+// ---------------------------------------------------------------------------
+// Product discrepancy resolution (used by catalog inbox action handler)
+// ---------------------------------------------------------------------------
+
+export async function resolveProductDiscrepanciesInProposal(
+  em: EntityManager,
+  proposalId: string,
+  productTitle: string,
+  productId: string,
+  scope: { tenantId: string; organizationId: string },
+): Promise<void> {
+  const { InboxDiscrepancy, InboxProposalAction } = await import('../data/entities')
+
+  const discrepancies = await findWithDecryption(
+    em,
+    InboxDiscrepancy,
+    {
+      proposalId,
+      type: 'product_not_found',
+      resolved: false,
+      tenantId: scope.tenantId,
+      organizationId: scope.organizationId,
+    },
+    undefined,
+    scope,
+  )
+
+  const normalizedTitle = productTitle.toLowerCase().trim()
+  const matchingDiscrepancies = discrepancies.filter((d) => {
+    const foundValue = (d.foundValue || '').toLowerCase().trim()
+    return foundValue === normalizedTitle
+  })
+
+  if (matchingDiscrepancies.length === 0) return
+
+  // Phase 1: flush scalar mutations before any queries to avoid UoW tracking loss (SPEC-018)
+  for (const discrepancy of matchingDiscrepancies) {
+    discrepancy.resolved = true
+  }
+  await em.flush()
+
+  // Phase 2: update line item product IDs (involves findOneWithDecryption queries)
+  const actionIds = matchingDiscrepancies
+    .map((d) => d.actionId)
+    .filter((id): id is string => !!id)
+
+  for (const actionId of actionIds) {
+    const action = await findOneWithDecryption(
+      em,
+      InboxProposalAction,
+      { id: actionId, deletedAt: null },
+      undefined,
+      scope,
+    )
+    if (!action) continue
+
+    const payload = action.payload as Record<string, unknown>
+    const lineItems = Array.isArray(payload?.lineItems)
+      ? (payload.lineItems as Record<string, unknown>[])
+      : []
+
+    let updated = false
+    for (const item of lineItems) {
+      if (item.productId) continue
+      const itemName = (typeof item.productName === 'string' ? item.productName : '').toLowerCase().trim()
+      if (itemName === normalizedTitle) {
+        item.productId = productId
+        updated = true
+        break
+      }
+    }
+
+    if (updated) {
+      action.payload = { ...payload, lineItems }
+    }
+  }
+
+  if (actionIds.length > 0) {
+    await em.flush()
+  }
+}

package/src/modules/inbox_ops/lib/extractionPrompt.ts

@@ -1,14 +1,52 @@
 import type { ContactMatchResult } from './contactMatcher'
-import { REQUIRED_FEATURES_MAP } from './constants'
+import type { InboxActionDefinition } from '@open-mercato/shared/modules/inbox-actions'
 
 const LANGUAGE_NAMES: Record<string, string> = { en: 'English', de: 'German', es: 'Spanish', pl: 'Polish' }
 
-export function buildExtractionSystemPrompt(
+/**
+ * Lazily load registered inbox action definitions from the generated registry.
+ * Uses dynamic import to avoid circular dependencies at module load time.
+ */
+async function loadRegisteredActions(): Promise<InboxActionDefinition[]> {
+  try {
+    const registry = await import('@/.mercato/generated/inbox-actions.generated')
+    return registry.inboxActions ?? []
+  } catch {
+    return []
+  }
+}
+
+function buildFeaturesSection(actions: InboxActionDefinition[]): string {
+  return actions
+    .map((a) => `- ${a.type} (requires: ${a.requiredFeature})`)
+    .join('\n')
+}
+
+function buildPayloadSchemasSection(actions: InboxActionDefinition[]): string {
+  return actions
+    .filter((a) => a.promptSchema && a.promptSchema !== '(shared with create_order)' && a.promptSchema !== '(shared with create_order above)')
+    .map((a) => a.promptSchema)
+    .join('\n\n')
+}
+
+function buildActionRulesSection(actions: InboxActionDefinition[]): string {
+  const rules = actions.flatMap((a) => a.promptRules ?? [])
+  return rules.map((r) => `- ${r}`).join('\n')
+}
+
+export async function buildExtractionSystemPrompt(
   matchedContacts: ContactMatchResult[],
   catalogProducts: { id: string; name: string; sku?: string; price?: string }[],
   channelId?: string,
   workingLanguage?: string,
-): string {
+  registeredActions?: InboxActionDefinition[],
+): Promise<string> {
+  const actions = registeredActions ?? await loadRegisteredActions()
+
+  const featuresSection = buildFeaturesSection(actions)
+  const payloadSchemasSection = buildPayloadSchemasSection(actions)
+  const actionRulesSection = buildActionRulesSection(actions)
+
   const contactsSection = matchedContacts.length > 0
     ? `\nPre-matched contacts from CRM:\n${JSON.stringify(
         matchedContacts.map((match) => ({
@@ -36,7 +74,7 @@ You are an email-to-ERP extraction agent.
 </role>
 
 <required_features>
-${Object.entries(REQUIRED_FEATURES_MAP).map(([actionType, feature]) => `- ${actionType} (requires: ${feature})`).join('\n')}
+${featuresSection}
 </required_features>
 
 <safety>
@@ -46,41 +84,13 @@ ${Object.entries(REQUIRED_FEATURES_MAP).map(([actionType, feature]) => `- ${acti
 </safety>
 
 <payload_schemas>
-create_order / create_quote payload:
-{ customerName: string, customerEmail?: string, customerEntityId?: uuid, channelId?: uuid, currencyCode: string (3-letter ISO), taxRateId?: uuid, lineItems: [{ productName: string (REQUIRED), productId?: uuid, variantId?: uuid, sku?: string, quantity: string, unitPrice?: string, kind?: "product"|"service", description?: string }], requestedDeliveryDate?: string, notes?: string, customerReference?: string (customer's own PO number or reference code — only set if explicitly stated in the email, do NOT use the email subject), shippingAddress?: { line1?: string, line2?: string, city?: string, state?: string, postalCode?: string, country?: string, company?: string, contactName?: string }, billingAddress?: { line1?: string, line2?: string, city?: string, state?: string, postalCode?: string, country?: string, company?: string, contactName?: string } }
-
-create_contact payload:
-{ type: "person"|"company", name: string, email?: string, phone?: string, companyName?: string, role?: string, source: "inbox_ops" }
-
-create_product payload:
-{ title: string, sku?: string, unitPrice?: string, currencyCode?: string (3-letter ISO), kind?: "product"|"service", description?: string }
-
-link_contact payload:
-{ emailAddress: string (email), contactId: uuid, contactType: "person"|"company", contactName: string }
-
-update_order payload:
-{ orderId?: uuid, orderNumber?: string, quantityChanges?: [{ lineItemName: string, lineItemId?: uuid, oldQuantity?: string, newQuantity: string }], deliveryDateChange?: { oldDate?: string, newDate: string }, noteAdditions?: string[] }
-
-update_shipment payload:
-{ orderId?: uuid, orderNumber?: string, trackingNumbers?: string[], carrierName?: string, statusLabel: string, shippedAt?: string, deliveredAt?: string, estimatedDelivery?: string, notes?: string }
-
-log_activity payload:
-{ contactId?: uuid, contactType: "person"|"company", contactName: string, activityType: "email"|"call"|"meeting"|"note", subject: string, body: string }
-
-draft_reply payload:
-{ to: string (email), toName?: string, subject: string, body: string, context?: string }
+${payloadSchemasSection}
 </payload_schemas>
 
 <rules>
 - Extract only details explicitly stated or strongly implied in the thread.
 - Do not fabricate values; omit values that are not present.
-- ALWAYS propose a create_order or create_quote action when the customer expresses interest in buying, even if some product names are uncertain or not in the catalog. Use the best product name available; the system will flag unmatched products as discrepancies. Do NOT replace an order with a draft_reply asking for clarification — propose both if needed.
-- Use create_order when the customer has clearly confirmed they want to proceed (e.g., "let's go ahead", "please process", "confirmed"). Use create_quote when the customer is still inquiring, requesting pricing, asking for a proposal, or negotiating (e.g., "could you send a quote", "what would it cost", "we're interested in", "can you offer"). When in doubt, prefer create_quote.
-- For create_order / create_quote: each line item MUST have "productName" (the product name goes here, NOT in "description"). Include currencyCode and customerName.
-- For update_shipment: use statusLabel text only.
-- For create_order / create_quote: extract shippingAddress and billingAddress as structured objects when addresses are mentioned. Parse street, city, postal code, country from the text. Do NOT put address data in notes.
-- For create_contact: always include email when available from the thread. Set source to "inbox_ops", type must be lowercase "person" or "company".
-- For draft_reply: include ERP context when available.
+${actionRulesSection}
 - Set requiredFeature on each action from the mapping above.
 - Set confidence in [0.0, 1.0].
 - Write summary and all action descriptions in ${LANGUAGE_NAMES[workingLanguage || 'en'] || 'English'} even if the original thread is in another language.
@@ -110,4 +120,5 @@ ${cleanedText}
 </output_requirements>`
 }
 
+/** @deprecated Use the generated inbox action registry instead */
 export { REQUIRED_FEATURES_MAP } from './constants'

package/src/modules/inbox_ops/lib/inbox-actions-generated.d.ts

@@ -0,0 +1,11 @@
+declare module '@/.mercato/generated/inbox-actions.generated' {
+  import type { InboxActionDefinition } from '@open-mercato/shared/modules/inbox-actions'
+
+  export const inboxActionConfigEntries: Array<{
+    moduleId: string
+    actions: InboxActionDefinition[]
+  }>
+  export const inboxActions: InboxActionDefinition[]
+  export function getInboxAction(type: string): InboxActionDefinition | undefined
+  export function getRegisteredActionTypes(): string[]
+}