@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7000.1.0ae682bad1

package/src/modules/inbox_ops/api/extract/route.ts

@@ -70,6 +70,10 @@ export async function POST(req: Request) {
         organizationId: ctx.organizationId,
         forwardedByAddress: submitterEmail,
         subject: title || 'Text extraction',
+      }, {
+        persistent: true,
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId,
       })
     } catch (eventError) {
       logger.error('Failed to emit email.received event', { err: eventError })

package/src/modules/inbox_ops/api/webhook/inbound.ts

@@ -396,6 +396,10 @@ export async function POST(req: Request) {
       organizationId: settings.organizationId,
       forwardedByAddress: parsed.from.email,
       subject: parsed.subject,
+    }, {
+      persistent: true,
+      tenantId: settings.tenantId,
+      organizationId: settings.organizationId,
     })
   } catch (eventError) {
     logger.error('Failed to emit email.received event', { err: eventError })

package/src/modules/sales/commands/documents.ts

@@ -2112,8 +2112,8 @@ async function loadCreditMemoSnapshot(
       organizationId: creditMemo.organizationId,
       tenantId: creditMemo.tenantId,
       creditMemoNumber: creditMemo.creditMemoNumber,
-      orderId: creditMemo.orderId ?? null,
-      invoiceId: creditMemo.invoiceId ?? null,
+      orderId: creditMemo.order?.id ?? null,
+      invoiceId: creditMemo.invoice?.id ?? null,
       statusEntryId: creditMemo.statusEntryId ?? null,
       status: creditMemo.status ?? null,
       reason: creditMemo.reason ?? null,
@@ -9471,8 +9471,8 @@ const createCreditMemoCommand: CommandHandler<
       organizationId: parsed.organizationId,
       tenantId: parsed.tenantId,
       creditMemoNumber: ensuredCreditMemoNumber,
-      orderId: parsed.orderId ?? null,
-      invoiceId: parsed.invoiceId ?? null,
+      order: parsed.orderId ? em.getReference(SalesOrder, parsed.orderId) : null,
+      invoice: parsed.invoiceId ? em.getReference(SalesInvoice, parsed.invoiceId) : null,
       statusEntryId: parsed.statusEntryId ?? null,
       status,
       reason: parsed.reason ?? null,
@@ -9722,8 +9722,12 @@ const updateCreditMemoCommand: CommandHandler<
     ensureOrganizationScope(ctx, creditMemo.organizationId);
     ensureTenantScope(ctx, creditMemo.tenantId);
     creditMemo.creditMemoNumber = before.creditMemo.creditMemoNumber;
-    creditMemo.orderId = before.creditMemo.orderId;
-    creditMemo.invoiceId = before.creditMemo.invoiceId;
+    creditMemo.order = before.creditMemo.orderId
+      ? em.getReference(SalesOrder, before.creditMemo.orderId)
+      : null;
+    creditMemo.invoice = before.creditMemo.invoiceId
+      ? em.getReference(SalesInvoice, before.creditMemo.invoiceId)
+      : null;
     creditMemo.statusEntryId = before.creditMemo.statusEntryId;
     creditMemo.status = before.creditMemo.status;
     creditMemo.reason = before.creditMemo.reason;
@@ -9826,8 +9830,12 @@ const deleteCreditMemoCommand: CommandHandler<
       organizationId: before.creditMemo.organizationId,
       tenantId: before.creditMemo.tenantId,
       creditMemoNumber: before.creditMemo.creditMemoNumber,
-      orderId: before.creditMemo.orderId,
-      invoiceId: before.creditMemo.invoiceId,
+      order: before.creditMemo.orderId
+        ? em.getReference(SalesOrder, before.creditMemo.orderId)
+        : null,
+      invoice: before.creditMemo.invoiceId
+        ? em.getReference(SalesInvoice, before.creditMemo.invoiceId)
+        : null,
       statusEntryId: before.creditMemo.statusEntryId,
       status: before.creditMemo.status,
       reason: before.creditMemo.reason,

package/src/modules/warranty_claims/AGENTS.md

@@ -0,0 +1,49 @@
+# Warranty Claims Module — Agent Guidelines
+
+`warranty_claims` is the B2B warranty, RMA, core-return, and vendor-recovery claims desk. It owns the claim aggregate, line-level partials, customer-visible timeline, staff notifications, portal intake, SLA settings, risk signals, and sales-order tab injection while coupling to other modules only through IDs, snapshots, events, QueryEngine lookups, and widgets.
+
+Covers claim lifecycle + line dispositions, receiving & grading, SLA pause/escalation, risk signals & adjudication, registrations & vendor recovery, portal + API-key intake, and resolution-execution bridges into `sales`. Design of record: [`.ai/specs/2026-07-03-warranty-rma-claims-desk.md`](../../../../../.ai/specs/2026-07-03-warranty-rma-claims-desk.md); unimplemented candidates: [`.ai/specs/2026-07-16-warranty-rma-roadmap.md`](../../../../../.ai/specs/2026-07-16-warranty-rma-roadmap.md).
+
+## Always
+
+1. MUST keep claim lifecycle transitions in `lib/stateMachine.ts` and `data/constants.ts`; the status enum is FROZEN and lifecycle moves MUST go through `warranty_claims.claim.transition`, never generic `PUT`.
+2. MUST preserve legal transitions: `closed -> in_review` is the reopen path, `cancelled` is terminal, and direct status writes through CRUD update are forbidden.
+3. MUST treat claim lines as first-class partials with dispositions; line create/update/delete MUST recompute header money rollups inside the same atomic flush.
+4. MUST keep SLA behavior settings-driven from `lib/settings.ts` and `/api/warranty_claims/settings-general`: due dates come from settings/defaults, `info_requested` pauses when configured, and resume shifts the due date instead of shortening the SLA window.
+5. MUST keep auto-adjudication default OFF, risk-gated by `lib/risk.ts`, executed only inside the submit command path, and limited to auto-approval; never auto-deny.
+6. MUST keep risk signals deterministic, tenant/org scoped, and based on code constants in `lib/risk.ts`; do not make thresholds tenant data without a spec.
+7. MUST preserve the event split: `warranty_claims.claim.status_changed` is the staff/client broadcast and MUST NOT pin `recipientUserIds`; `warranty_claims.claim.portal_status_changed` is the portal broadcast and MUST pin customer-user recipient ids, skipping emit when there are no recipients.
+8. MUST use FK-id plus snapshot coupling for sales, customers, catalog, and auth data; use QueryEngine or scoped decrypted lookups wrapped in `try/catch` for optional peer lookups.
+9. MUST carry `tenantId` and `organizationId` in every ORM `where` clause. The scope argument to `findOneWithDecryption` / `findWithDecryption` is decryption scope only and does not add SQL filters.
+10. MUST pin portal reads and writes to the server-resolved customer id; portal mutation guards use the customer-user id with an empty feature list.
+11. MUST keep optimistic locking on by default for CRUD and settings; action endpoints use `enforceCommandOptimisticLock`, and UI line mutations send each line's own `updatedAt` header.
+12. MUST keep free-text/correspondence fields in `encryption.ts` encrypted and excluded from search sources in `search.ts`.
+
+## Ask First
+
+- Ask before adding, renaming, or removing claim statuses, line statuses, dispositions, event ids, notification ids, API paths, widget spot ids, ACL ids, DI keys, or search entity ids.
+- Ask before changing lifecycle semantics, reopen behavior, cancellation rules, SLA pause/resume math, risk thresholds, auto-adjudication policy, or vendor-recovery reconciliation.
+- Ask before importing another module's ORM entity, writing to sales/customers/auth aggregates, or replacing FK-id plus snapshot coupling with direct relations.
+- Ask before changing portal ownership rules, customer-user recipient selection, attachment ownership, or customer-visible timeline visibility.
+
+## Never
+
+- Never change `claimType` or `status` through generic CRUD update.
+- Never import sales, customers, catalog, or auth ORM entities into this module.
+- Never emit a portal-broadcast event without pinned customer-user recipients.
+- Never rely on `findOneWithDecryption` scope to tenant-filter data; missing tenant/org in `where` is a data isolation bug.
+- Never bypass mutation guards, command optimistic locks, encrypted field helpers, or atomic flush for claim/line writes.
+- Never put encrypted text fields such as notes, resolution summary, fault description, inspection notes, or event body into search source text.
+- Never edit `i18n/*.json` in packet work; record new keys and English fallbacks in the packet notes file.
+
+## Validation Commands
+
+```bash
+cd packages/core
+npx jest src/modules/warranty_claims/__tests__
+cd ../..
+yarn generate
+yarn i18n:check-sync
+```
+
+Integration coverage lives under `packages/core/src/modules/warranty_claims/__integration__/TC-WC-*.spec.ts`; run the relevant `TC-WC-*` scenario when changing API or portal behavior.

package/src/modules/warranty_claims/acl.ts

@@ -0,0 +1,71 @@
+export const features = [
+  { id: 'warranty_claims.claim.view', title: 'View warranty claims', module: 'warranty_claims' },
+  {
+    id: 'warranty_claims.claim.create',
+    title: 'Create warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.claim.manage',
+    title: 'Manage warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.claim.delete',
+    title: 'Delete warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.settings.manage',
+    title: 'Manage warranty claim settings',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.external.submit',
+    title: 'Submit external warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.create'],
+  },
+  {
+    id: 'warranty_claims.external.view',
+    title: 'View external warranty claims',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.registration.view',
+    title: 'View warranty registrations',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.view'],
+  },
+  {
+    id: 'warranty_claims.registration.manage',
+    title: 'Manage warranty registrations',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.registration.view'],
+  },
+  {
+    id: 'warranty_claims.vendor_policy.manage',
+    title: 'Manage warranty vendor policies',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+  {
+    id: 'warranty_claims.troubleshooting.manage',
+    title: 'Manage warranty troubleshooting guides',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.settings.manage'],
+  },
+  {
+    id: 'warranty_claims.receiving.manage',
+    title: 'Manage warranty receiving and grading',
+    module: 'warranty_claims',
+    dependsOn: ['warranty_claims.claim.manage'],
+  },
+]
+
+export default features

package/src/modules/warranty_claims/ai-agents.ts

@@ -0,0 +1,189 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type {
+  AiAgentDefinition,
+  AiAgentPageContextInput,
+} from '@open-mercato/ai-assistant/modules/ai_assistant/lib/ai-agent-definition'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { WarrantyClaim } from './data/entities'
+
+type PromptSectionName =
+  | 'role'
+  | 'scope'
+  | 'lifecycle'
+  | 'linePartials'
+  | 'vendorRecovery'
+  | 'hardRules'
+  | 'responseStyle'
+
+type PromptSection = {
+  name: PromptSectionName
+  order: number
+  content: string
+}
+
+const CLAIMS_ASSISTANT_ID = 'warranty_claims.claims_assistant'
+const MODULE_ID = 'warranty_claims'
+
+const CLAIMS_ASSISTANT_ALLOWED_TOOLS: readonly string[] = [
+  'warranty_claims.list_claims',
+  'warranty_claims.get_claim',
+  'warranty_claims.suggest_triage',
+  'warranty_claims.transition_claim',
+  'warranty_claims.draft_customer_reply',
+  'warranty_claims.summarize_claim',
+  'warranty_claims.assess_damage_photo',
+  'warranty_claims.extract_proof_of_purchase',
+]
+
+const PROMPT_SECTIONS: PromptSection[] = [
+  {
+    name: 'role',
+    order: 1,
+    content: [
+      'ROLE',
+      'You are the Claims Assistant inside Open Mercato. You help warranty and RMA desk operators triage claims, check entitlement facts, summarize history, and draft customer replies for operator review.',
+      'Stay inside the warranty_claims module and respect tenant and organization isolation through the authorized tool pack.',
+    ].join('\n'),
+  },
+  {
+    name: 'scope',
+    order: 2,
+    content: [
+      'SCOPE',
+      'Use list_claims and get_claim to inspect tenant-scoped claim data. Use suggest_triage for deterministic entitlement, disposition, and priority guidance before proposing a lifecycle move.',
+      'Use draft_customer_reply only to prepare suggestion text; the operator sends or edits the message manually.',
+      'Use summarize_claim when the operator needs a compact history or open-question list.',
+      'Use assess_damage_photo and extract_proof_of_purchase only for attached claim evidence; these tools return assessment facts and never change money fields.',
+    ].join('\n'),
+  },
+  {
+    name: 'lifecycle',
+    order: 3,
+    content: [
+      'CLAIM LIFECYCLE',
+      'The primary path is draft -> submitted -> in_review -> approved -> awaiting_return -> received -> inspecting -> resolved -> closed.',
+      'Branches: info_requested pauses for customer input and returns to in_review when the customer replies; rejected and cancelled are non-happy-path outcomes; cancelled is terminal.',
+      'Closed claims can reopen to in_review only through the documented transition path.',
+    ].join('\n'),
+  },
+  {
+    name: 'linePartials',
+    order: 4,
+    content: [
+      'LINE PARTIALS AND DISPOSITIONS',
+      'A claim can be partially approved line by line. Read lineStatus, disposition, qtyClaimed, qtyApproved, warrantyStatus, SKU, serial number, and product name before recommending a path.',
+      'Dispositions include restock, repair, replace, credit, refund, field_destroy, scrap, return_to_vendor, and deny. Do not collapse line-level differences into a single header recommendation.',
+    ].join('\n'),
+  },
+  {
+    name: 'vendorRecovery',
+    order: 5,
+    content: [
+      'VENDOR RECOVERY',
+      'Vendor recovery claims are linked follow-up claims for supplier-recoverable value. Treat vendorName, vendorRef, sourceClaimId, recovered totals, and return_to_vendor dispositions as recovery facts.',
+      'Do not promise supplier reimbursement or customer credit unless the facts already show approved amounts or resolved recovery outcomes.',
+    ].join('\n'),
+  },
+  {
+    name: 'hardRules',
+    order: 6,
+    content: [
+      'HARD RULES',
+      'Never claim to have transitioned a claim unless an approved transition_claim call has completed. If a transition is pending approval, say the operator still needs to approve it.',
+      'Customer reply drafts are suggestions for operator review, not sent messages.',
+      'Always cite claim numbers when discussing a specific claim.',
+      'Never invent refund amounts, credit amounts, replacement dates, shipping dates, SLA dates, or vendor commitments that are not present in tool results.',
+      'Never expose internal-only timeline notes in customer-facing reply text.',
+    ].join('\n'),
+  },
+  {
+    name: 'responseStyle',
+    order: 7,
+    content: [
+      'RESPONSE STYLE',
+      'Lead with the practical answer. Keep operator-facing summaries concise, factual, and grounded in tool results.',
+      'For customer-facing draft content, preserve the customer language when the facts expose a latest customer message, avoid markdown headers, and keep the wording suitable for manual review by the merchant.',
+    ].join('\n'),
+  },
+]
+
+function compilePrompt(sections: PromptSection[]): string {
+  return sections
+    .slice()
+    .sort((a, b) => a.order - b.order)
+    .map((section) => section.content.trim())
+    .join('\n\n')
+}
+
+const CLAIM_ENTITY_TYPE = 'warranty_claims.claim'
+
+async function resolveClaimPageContext(input: AiAgentPageContextInput): Promise<string | null> {
+  if (input.entityType !== CLAIM_ENTITY_TYPE) return null
+  if (!input.tenantId || !input.organizationId) return null
+  try {
+    const em = input.container.resolve<EntityManager>('em')
+    const scope = { tenantId: input.tenantId, organizationId: input.organizationId }
+    const claim = await findOneWithDecryption(
+      em,
+      WarrantyClaim,
+      { id: input.recordId, tenantId: scope.tenantId, organizationId: scope.organizationId, deletedAt: null },
+      {},
+      scope,
+    )
+    if (!claim) return null
+    return [
+      'CURRENT CLAIM CONTEXT',
+      `The operator is viewing claim ${claim.claimNumber} (status: ${claim.status}, type: ${claim.claimType}).`,
+      `When the operator refers to "this claim", call the warranty_claims tools with claimId "${claim.claimNumber}" without asking for the identifier, and always refer to the claim by its claim number in replies.`,
+      `Machine hint: tools whose claimId input requires a UUID accept "${claim.id}" for claim ${claim.claimNumber}; do not quote this UUID to the operator.`,
+    ].join('\n')
+  } catch {
+    return null
+  }
+}
+
+const claimsAssistant: AiAgentDefinition = {
+  id: CLAIMS_ASSISTANT_ID,
+  moduleId: MODULE_ID,
+  label: 'Claims Assistant',
+  description: 'Warranty & RMA desk copilot: triages claims, checks entitlement, summarizes history, and drafts customer replies for operator review.',
+  systemPrompt: compilePrompt(PROMPT_SECTIONS),
+  allowedTools: [...CLAIMS_ASSISTANT_ALLOWED_TOOLS],
+  acceptedMediaTypes: ['image', 'pdf'],
+  executionMode: 'chat',
+  executionEngine: 'stream-text',
+  allowRuntimeOverride: true,
+  readOnly: false,
+  mutationPolicy: 'confirm-required',
+  requiredFeatures: ['warranty_claims.claim.view'],
+  keywords: ['warranty', 'claim', 'rma', 'return', 'triage', 'sla'],
+  domain: 'warranty_claims',
+  resolvePageContext: resolveClaimPageContext,
+  loop: {
+    maxSteps: 10,
+    budget: { maxToolCalls: 10, maxWallClockMs: 60_000 },
+    allowRuntimeOverride: true,
+  },
+  dataCapabilities: {
+    entities: ['warranty_claims.claim'],
+    operations: ['read', 'search'],
+  },
+  suggestions: [
+    {
+      label: 'Triage this claim',
+      prompt: 'Suggest triage for this claim: eligibility, dispositions, and priority.',
+    },
+    {
+      label: 'Draft a reply',
+      prompt: 'Draft a customer reply summarizing the current claim status.',
+    },
+    {
+      label: 'Summarize history',
+      prompt: 'Summarize this claim history and list open questions.',
+    },
+  ],
+}
+
+export const aiAgents: AiAgentDefinition[] = [claimsAssistant]
+
+export default aiAgents