@open-mercato/core 0.7.1-develop.7175.1.d49ab48ee2 → 0.7.1-develop.7176.1.d229567a50

package/src/modules/phone_calls/backend/page.tsx

@@ -0,0 +1,303 @@
+"use client"
+
+import * as React from 'react'
+import type { SortingState } from '@tanstack/react-table'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { StatusBadge, type StatusMap } from '@open-mercato/ui/primitives/status-badge'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useAppEvent } from '@open-mercato/ui/backend/injection/useAppEvent'
+import { useProgressPoll } from '@open-mercato/ui/backend/progress/useProgressPoll'
+import { formatDateTime } from '@open-mercato/shared/lib/time'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { PHONE_CALL_RESOURCE_KIND } from '@open-mercato/shared/modules/phone_calls/types'
+
+type PhoneCallRow = {
+  id: string
+  provider_key: string | null
+  external_call_id: string | null
+  direction: string | null
+  status: string | null
+  started_at: string | null
+  duration_seconds: number | null
+  ingest_status: string | null
+}
+
+type PhoneCallListResponse = {
+  items?: PhoneCallRow[]
+  total?: number
+  page?: number
+  totalPages?: number
+  totalIsCapped?: boolean
+}
+
+const DIRECTION_VALUES = ['inbound', 'outbound', 'internal', 'unknown'] as const
+const STATUS_VALUES = ['new', 'ringing', 'answered', 'missed', 'failed', 'completed', 'unknown'] as const
+
+type PhoneCallStatusValue = typeof STATUS_VALUES[number]
+
+function isPhoneCallStatus(value: string): value is PhoneCallStatusValue {
+  return (STATUS_VALUES as readonly string[]).includes(value)
+}
+
+// Column id (snake_case accessorKey) -> API sortField key (camelCase, matches
+// the route's sortFieldMap). Columns absent from this map are not sortable.
+const SORT_FIELDS: Record<string, string> = {
+  external_call_id: 'externalCallId',
+  direction: 'direction',
+  status: 'status',
+  provider_key: 'providerKey',
+  started_at: 'startedAt',
+  duration_seconds: 'durationSeconds',
+  ingest_status: 'ingestStatus',
+}
+
+const STATUS_TONE: StatusMap<PhoneCallStatusValue> = {
+  completed: 'success',
+  answered: 'success',
+  ringing: 'warning',
+  new: 'neutral',
+  missed: 'error',
+  failed: 'error',
+  unknown: 'neutral',
+}
+
+function formatDuration(seconds: number | null): string {
+  if (seconds == null || Number.isNaN(seconds)) return '—'
+  const total = Math.max(0, Math.floor(seconds))
+  const mins = Math.floor(total / 60)
+  const secs = total % 60
+  return `${mins}:${String(secs).padStart(2, '0')}`
+}
+
+export default function PhoneCallsPage() {
+  const t = useT()
+  const [rows, setRows] = React.useState<PhoneCallRow[]>([])
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [totalIsCapped, setTotalIsCapped] = React.useState(false)
+  const [page, setPage] = React.useState(1)
+  const [pageSize, setPageSize] = React.useState(50)
+  const [search, setSearch] = React.useState('')
+  const [sorting, setSorting] = React.useState<SortingState>([{ id: 'started_at', desc: true }])
+  const [filterValues, setFilterValues] = React.useState<FilterValues>({})
+
+  const handleSortingChange = React.useCallback((next: SortingState) => {
+    setSorting(next)
+    setPage(1)
+  }, [])
+  const [isLoading, setIsLoading] = React.useState(true)
+  const [error, setError] = React.useState<string | null>(null)
+  const [reloadToken, setReloadToken] = React.useState(0)
+
+  // Ingest runs in a provider worker, so the rows land after the page did. Any job that
+  // declares this resource kind wrote calls, whichever provider queued it.
+  useAppEvent('progress.job.completed', (event) => {
+    const meta = (event.payload as { meta?: Record<string, unknown> | null } | undefined)?.meta
+    if (meta?.resourceKind !== PHONE_CALL_RESOURCE_KIND) return
+    setReloadToken((token) => token + 1)
+  }, [])
+
+  // The event above is a live subscription with no replay: one emitted while the stream is
+  // reconnecting is gone, and the grid keeps showing a range the ingest already filled. Polling
+  // asks for state instead of waiting to be told, keyed by job id so nothing reloads twice.
+  const { recentlyCompleted } = useProgressPoll()
+  const seenJobIds = React.useRef<Set<string> | null>(null)
+  React.useEffect(() => {
+    const ingestJobs = recentlyCompleted.filter(
+      (job) => (job.meta as { resourceKind?: string } | null | undefined)?.resourceKind === PHONE_CALL_RESOURCE_KIND,
+    )
+    // Jobs that finished before this page mounted are recorded without a reload; the initial
+    // load already covers them.
+    if (seenJobIds.current === null) {
+      seenJobIds.current = new Set(ingestJobs.map((job) => job.id))
+      return
+    }
+    const unseen = ingestJobs.filter((job) => !seenJobIds.current!.has(job.id))
+    if (!unseen.length) return
+    for (const job of unseen) seenJobIds.current.add(job.id)
+    setReloadToken((token) => token + 1)
+  }, [recentlyCompleted])
+
+  const queryString = React.useMemo(() => {
+    const params = new URLSearchParams()
+    params.set('page', String(page))
+    params.set('pageSize', String(pageSize))
+    if (search.trim()) params.set('q', search.trim())
+    if (typeof filterValues.direction === 'string' && filterValues.direction) params.set('direction', filterValues.direction)
+    if (typeof filterValues.status === 'string' && filterValues.status) params.set('status', filterValues.status)
+    if (typeof filterValues.providerKey === 'string' && filterValues.providerKey.trim()) params.set('providerKey', filterValues.providerKey.trim())
+    const started = filterValues.started as { from?: string; to?: string } | undefined
+    if (started?.from) params.set('startedFrom', started.from)
+    if (started?.to) params.set('startedTo', started.to)
+    const activeSort = sorting[0]
+    if (activeSort) {
+      const sortField = SORT_FIELDS[activeSort.id]
+      if (sortField) {
+        params.set('sortField', sortField)
+        params.set('sortDir', activeSort.desc ? 'desc' : 'asc')
+      }
+    }
+    return params.toString()
+  }, [page, pageSize, search, filterValues, sorting])
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function load() {
+      setIsLoading(true)
+      setError(null)
+      const response = await apiCall<PhoneCallListResponse>(`/api/phone_calls/calls?${queryString}`).catch((err: unknown) => ({
+        ok: false as const,
+        result: { error: err instanceof Error ? err.message : undefined },
+      }))
+      if (cancelled) return
+      if (!response.ok) {
+        const errBody = response.result as { error?: string } | undefined
+        setError(errBody?.error ?? t('phone_calls.calls.list.error', 'Failed to load phone calls'))
+        setRows([])
+        setTotal(0)
+        setTotalPages(1)
+        setTotalIsCapped(false)
+      } else {
+        const data = (response.result ?? {}) as PhoneCallListResponse
+        setRows(Array.isArray(data.items) ? data.items : [])
+        setTotal(typeof data.total === 'number' ? data.total : 0)
+        setTotalPages(typeof data.totalPages === 'number' ? data.totalPages : 1)
+        setTotalIsCapped(data.totalIsCapped === true)
+      }
+      setIsLoading(false)
+    }
+    void load()
+    return () => { cancelled = true }
+  }, [queryString, reloadToken, t])
+
+  const filters = React.useMemo<FilterDef[]>(() => [
+    {
+      id: 'direction',
+      label: t('phone_calls.calls.filters.direction', 'Direction'),
+      type: 'select',
+      options: DIRECTION_VALUES.map((value) => ({
+        value,
+        label: t(`phone_calls.calls.direction.${value}`, value),
+      })),
+    },
+    {
+      id: 'status',
+      label: t('phone_calls.calls.filters.status', 'Status'),
+      type: 'select',
+      options: STATUS_VALUES.map((value) => ({
+        value,
+        label: t(`phone_calls.calls.status.${value}`, value),
+      })),
+    },
+    {
+      id: 'providerKey',
+      label: t('phone_calls.calls.filters.provider', 'Provider'),
+      type: 'text',
+      placeholder: t('phone_calls.calls.filters.providerPlaceholder', 'Provider key'),
+    },
+    {
+      id: 'started',
+      label: t('phone_calls.calls.filters.started', 'Started'),
+      type: 'dateRange',
+    },
+  ], [t])
+
+  const columns = React.useMemo<ColumnDef<PhoneCallRow>[]>(() => [
+    {
+      accessorKey: 'external_call_id',
+      header: t('phone_calls.calls.columns.callId', 'Call ID'),
+      meta: { truncate: true, maxWidth: '240px' },
+      cell: ({ row }) => (
+        <span className="text-sm font-medium">{row.original.external_call_id || '—'}</span>
+      ),
+    },
+    {
+      accessorKey: 'direction',
+      header: t('phone_calls.calls.columns.direction', 'Direction'),
+      cell: ({ row }) => {
+        const value = row.original.direction
+        return <span className="text-sm">{value ? t(`phone_calls.calls.direction.${value}`, value) : '—'}</span>
+      },
+    },
+    {
+      accessorKey: 'status',
+      header: t('phone_calls.calls.columns.status', 'Status'),
+      cell: ({ row }) => {
+        const value = row.original.status
+        if (!value) return <span className="text-sm text-muted-foreground">—</span>
+        return (
+          <StatusBadge variant={STATUS_TONE[isPhoneCallStatus(value) ? value : 'unknown']} dot>
+            {t(`phone_calls.calls.status.${value}`, value)}
+          </StatusBadge>
+        )
+      },
+    },
+    {
+      accessorKey: 'provider_key',
+      header: t('phone_calls.calls.columns.provider', 'Provider'),
+      cell: ({ row }) => <span className="text-sm">{row.original.provider_key || '—'}</span>,
+    },
+    {
+      accessorKey: 'started_at',
+      header: t('phone_calls.calls.columns.started', 'Started'),
+      cell: ({ row }) => <span className="text-sm text-muted-foreground">{formatDateTime(row.original.started_at) ?? '—'}</span>,
+    },
+    {
+      accessorKey: 'duration_seconds',
+      header: t('phone_calls.calls.columns.duration', 'Duration'),
+      cell: ({ row }) => <span className="text-sm tabular-nums">{formatDuration(row.original.duration_seconds)}</span>,
+    },
+    {
+      accessorKey: 'ingest_status',
+      header: t('phone_calls.calls.columns.ingestStatus', 'Ingest'),
+      cell: ({ row }) => {
+        const value = row.original.ingest_status
+        return (
+          <span className="text-sm text-muted-foreground">
+            {value ? t(`phone_calls.calls.ingestStatus.${value}`, value) : '—'}
+          </span>
+        )
+      },
+    },
+  ], [t])
+
+  return (
+    <Page>
+      <PageBody>
+        <DataTable<PhoneCallRow>
+          title={t('phone_calls.calls.list.title', 'Phone Calls')}
+          extensionTableId="phone_calls.calls"
+          columns={columns}
+          data={rows}
+          isLoading={isLoading}
+          error={error}
+          sortable
+          manualSorting
+          sorting={sorting}
+          onSortingChange={handleSortingChange}
+          searchValue={search}
+          onSearchChange={(value) => { setSearch(value); setPage(1) }}
+          searchPlaceholder={t('phone_calls.calls.list.searchPlaceholder', 'Search by call, conversation or provider')}
+          filters={filters}
+          filterValues={filterValues}
+          onFiltersApply={(values) => { setFilterValues(values); setPage(1) }}
+          onFiltersClear={() => { setFilterValues({}); setPage(1) }}
+          emptyState={t('phone_calls.calls.list.empty', 'No phone calls yet. Calls appear here once they are ingested from a provider.')}
+          pagination={{
+            page,
+            pageSize,
+            total,
+            totalPages,
+            totalIsCapped,
+            onPageChange: setPage,
+            pageSizeOptions: [10, 25, 50, 100],
+            onPageSizeChange: (size) => { setPageSize(size); setPage(1) },
+          }}
+        />
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/phone_calls/commands/calls.ts

@@ -0,0 +1,156 @@
+import { registerCommand } from '@open-mercato/shared/lib/commands'
+import type { CommandHandler } from '@open-mercato/shared/lib/commands'
+import { emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+import { ensureOrganizationScope, ensureTenantScope } from '@open-mercato/shared/lib/commands/scope'
+import type { CrudIndexerConfig } from '@open-mercato/shared/lib/crud/types'
+import type { DataEngine } from '@open-mercato/shared/lib/data/engine'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import { PHONE_CALL_RESOURCE_KIND } from '@open-mercato/shared/modules/phone_calls/types'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { E } from '#generated/entities.ids.generated'
+import { PhoneCall, PhoneCallParticipant } from '../data/entities'
+import {
+  ingestPhoneCallSchema,
+  type IngestPhoneCallInput,
+} from '../data/validators'
+import { emitPhoneCallsEvent } from '../events'
+
+export const PHONE_CALLS_CALL_INGEST_COMMAND_ID = 'phone_calls.call.ingest'
+export { PHONE_CALL_RESOURCE_KIND }
+
+const phoneCallCrudIndexer: CrudIndexerConfig<PhoneCall> = {
+  entityType: E.phone_calls.phone_call,
+}
+
+// The list route derives its cache tag from the entity class name, and the tag the bus
+// derives from this command id is a different one, so without the alias the cached list
+// pages survive an ingest.
+const PHONE_CALL_CACHE_ALIASES = [PhoneCall.name]
+
+export type IngestPhoneCallResult = { phoneCallId: string; created: boolean }
+
+function applyScalarFields(call: PhoneCall, input: IngestPhoneCallInput, ingestedAt: Date): void {
+  call.integrationId = input.integrationId ?? null
+  call.externalConversationId = input.externalConversationId ?? null
+  call.direction = input.direction
+  call.status = input.status
+  call.startedAt = input.startedAt ?? null
+  call.answeredAt = input.answeredAt ?? null
+  call.endedAt = input.endedAt ?? null
+  call.durationSeconds = input.durationSeconds ?? null
+  call.recordingUrl = input.recording?.url ?? null
+  call.providerFacts = input.providerFacts ?? null
+  call.rawSnapshot = input.rawPayload
+  call.ingestStatus = 'complete'
+  call.lastIngestedAt = ingestedAt
+}
+
+async function syncParticipants(
+  em: EntityManager,
+  call: PhoneCall,
+  input: IngestPhoneCallInput,
+): Promise<void> {
+  // Replace the whole participant set on every ingest: participants have no reliable
+  // natural key (providerParticipantId/phoneNumber are often null), so a diff/upsert would
+  // be guesswork. Delete-all + insert stays deterministic and idempotent. Revisit this if
+  // anything starts referencing participant.id externally (re-pull rotates these ids).
+  await em.nativeDelete(PhoneCallParticipant, { phoneCallId: call.id })
+  for (const participant of input.participants) {
+    em.persist(em.create(PhoneCallParticipant, {
+      organizationId: call.organizationId,
+      tenantId: call.tenantId,
+      phoneCallId: call.id,
+      providerParticipantId: participant.providerParticipantId ?? null,
+      role: participant.role,
+      phoneNumber: participant.phoneNumber ?? null,
+      displayName: participant.displayName ?? null,
+      email: participant.email ?? null,
+      metadata: participant.metadata ?? null,
+    }))
+  }
+}
+
+const ingestPhoneCallCommand: CommandHandler<IngestPhoneCallInput, IngestPhoneCallResult> = {
+  id: PHONE_CALLS_CALL_INGEST_COMMAND_ID,
+  async execute(rawInput, ctx) {
+    const input = ingestPhoneCallSchema.parse(rawInput)
+    ensureTenantScope(ctx, input.tenantId)
+    ensureOrganizationScope(ctx, input.organizationId)
+
+    const em = (ctx.container.resolve('em') as EntityManager).fork()
+    const existing = await findOneWithDecryption(
+      em,
+      PhoneCall,
+      {
+        providerKey: input.providerKey,
+        externalCallId: input.externalCallId,
+        tenantId: input.tenantId,
+        organizationId: input.organizationId,
+      },
+      undefined,
+      { tenantId: input.tenantId, organizationId: input.organizationId },
+    )
+    const created = !existing
+    const call = existing ?? em.create(PhoneCall, {
+      organizationId: input.organizationId,
+      tenantId: input.tenantId,
+      providerKey: input.providerKey,
+      externalCallId: input.externalCallId,
+      direction: input.direction,
+      status: input.status,
+    })
+    if (created) em.persist(call)
+    const ingestedAt = new Date()
+
+    await withAtomicFlush(
+      em,
+      [
+        () => applyScalarFields(call, input, ingestedAt),
+        () => syncParticipants(em, call, input),
+      ],
+      { transaction: true, label: PHONE_CALLS_CALL_INGEST_COMMAND_ID },
+    )
+
+    // The module emits its own declared events, so only the indexer is handed to the
+    // shared side effects: the query index and the read caches have to see the write.
+    await emitCrudSideEffects({
+      dataEngine: ctx.container.resolve('dataEngine') as DataEngine,
+      action: created ? 'created' : 'updated',
+      entity: call,
+      identifiers: {
+        id: call.id,
+        organizationId: call.organizationId,
+        tenantId: call.tenantId,
+      },
+      indexer: phoneCallCrudIndexer,
+    })
+
+    await emitPhoneCallsEvent(
+      created ? 'phone_calls.call.ingested' : 'phone_calls.call.updated',
+      { id: call.id, organizationId: call.organizationId, tenantId: call.tenantId },
+    ).catch(() => undefined)
+
+    return { phoneCallId: call.id, created }
+  },
+  // Calls carry PII (numbers, names, recordings), so the audit entry stays at identifiers
+  // and the ingest outcome. No snapshot, and the command is not undoable.
+  buildLog: async ({ input, result }) => {
+    const { translate } = await resolveTranslations()
+    return {
+      actionLabel: result.created
+        ? translate('phone_calls.audit.calls.ingested', 'Ingest phone call')
+        : translate('phone_calls.audit.calls.updated', 'Update ingested phone call'),
+      resourceKind: PHONE_CALL_RESOURCE_KIND,
+      resourceId: result.phoneCallId,
+      tenantId: input.tenantId,
+      organizationId: input.organizationId,
+      context: { cacheAliases: PHONE_CALL_CACHE_ALIASES },
+    }
+  },
+}
+
+registerCommand(ingestPhoneCallCommand)
+
+export { ingestPhoneCallCommand }

package/src/modules/phone_calls/commands/index.ts

@@ -0,0 +1 @@
+import './calls'

package/src/modules/phone_calls/data/entities.ts

@@ -0,0 +1,144 @@
+import { OptionalProps } from '@mikro-orm/core'
+import { Entity, Index, ManyToOne, PrimaryKey, Property, Unique } from '@mikro-orm/decorators/legacy'
+import type {
+  PhoneCallDirection,
+  PhoneCallStatus,
+  PhoneCallParticipantRole,
+} from '@open-mercato/shared/modules/phone_calls/types'
+
+export type PhoneCallIngestStatus = 'pending' | 'complete' | 'failed'
+
+@Entity({ tableName: 'phone_calls' })
+@Index({ name: 'phone_calls_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+@Unique({
+  name: 'phone_calls_provider_external_scope_uq',
+  properties: ['providerKey', 'externalCallId', 'tenantId', 'organizationId'],
+})
+@Index({ name: 'phone_calls_org_started_at_idx', properties: ['organizationId', 'startedAt'] })
+@Index({ name: 'phone_calls_org_status_idx', properties: ['organizationId', 'status'] })
+@Index({
+  name: 'phone_calls_communication_projection_id_idx',
+  expression:
+    'create index "phone_calls_communication_projection_id_idx" on "phone_calls" ("communication_projection_id") where "communication_projection_id" is not null',
+})
+export class PhoneCall {
+  [OptionalProps]?: 'ingestStatus' | 'createdAt' | 'updatedAt' | 'deletedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @Property({ name: 'provider_key', type: 'text' })
+  providerKey!: string
+
+  @Property({ name: 'integration_id', type: 'text', nullable: true })
+  integrationId?: string | null
+
+  @Property({ name: 'external_call_id', type: 'text' })
+  externalCallId!: string
+
+  @Property({ name: 'external_conversation_id', type: 'text', nullable: true })
+  externalConversationId?: string | null
+
+  @Property({ name: 'direction', type: 'text' })
+  direction!: PhoneCallDirection
+
+  @Property({ name: 'status', type: 'text' })
+  status!: PhoneCallStatus
+
+  @Property({ name: 'started_at', type: Date, nullable: true })
+  startedAt?: Date | null
+
+  @Property({ name: 'answered_at', type: Date, nullable: true })
+  answeredAt?: Date | null
+
+  @Property({ name: 'ended_at', type: Date, nullable: true })
+  endedAt?: Date | null
+
+  @Property({ name: 'duration_seconds', type: 'integer', nullable: true })
+  durationSeconds?: number | null
+
+  @Property({ name: 'recording_url', type: 'text', nullable: true })
+  recordingUrl?: string | null
+
+  @Property({ name: 'recording_attachment_id', type: 'uuid', nullable: true })
+  recordingAttachmentId?: string | null
+
+  @Property({ name: 'active_transcript_version_id', type: 'uuid', nullable: true })
+  activeTranscriptVersionId?: string | null
+
+  @Property({ name: 'active_summary_version_id', type: 'uuid', nullable: true })
+  activeSummaryVersionId?: string | null
+
+  @Property({ name: 'communication_projection_id', type: 'uuid', nullable: true })
+  communicationProjectionId?: string | null
+
+  @Property({ name: 'provider_facts', type: 'jsonb', nullable: true })
+  providerFacts?: Record<string, unknown> | null
+
+  @Property({ name: 'raw_snapshot', type: 'jsonb', nullable: true })
+  rawSnapshot?: Record<string, unknown> | null
+
+  @Property({ name: 'ingest_status', type: 'text', default: 'pending' })
+  ingestStatus: PhoneCallIngestStatus = 'pending'
+
+  @Property({ name: 'last_ingested_at', type: Date, nullable: true })
+  lastIngestedAt?: Date | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+
+  @Property({ name: 'deleted_at', type: Date, nullable: true })
+  deletedAt?: Date | null
+}
+
+@Entity({ tableName: 'phone_call_participants' })
+@Index({ name: 'phone_call_participants_call_idx', properties: ['phoneCallId'] })
+@Index({ name: 'phone_call_participants_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
+export class PhoneCallParticipant {
+  [OptionalProps]?: 'createdAt' | 'updatedAt'
+
+  @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
+  id!: string
+
+  @Property({ name: 'organization_id', type: 'uuid' })
+  organizationId!: string
+
+  @Property({ name: 'tenant_id', type: 'uuid' })
+  tenantId!: string
+
+  @ManyToOne(() => PhoneCall, { fieldName: 'phone_call_id', deleteRule: 'cascade', mapToPk: true })
+  phoneCallId!: string
+
+  @Property({ name: 'provider_participant_id', type: 'text', nullable: true })
+  providerParticipantId?: string | null
+
+  @Property({ name: 'role', type: 'text' })
+  role!: PhoneCallParticipantRole
+
+  @Property({ name: 'phone_number', type: 'text', nullable: true })
+  phoneNumber?: string | null
+
+  @Property({ name: 'display_name', type: 'text', nullable: true })
+  displayName?: string | null
+
+  @Property({ name: 'email', type: 'text', nullable: true })
+  email?: string | null
+
+  @Property({ name: 'metadata', type: 'jsonb', nullable: true })
+  metadata?: Record<string, unknown> | null
+
+  @Property({ name: 'created_at', type: Date, onCreate: () => new Date() })
+  createdAt: Date = new Date()
+
+  @Property({ name: 'updated_at', type: Date, onUpdate: () => new Date() })
+  updatedAt: Date = new Date()
+}

package/src/modules/phone_calls/data/validators.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod'
+
+const uuid = () => z.string().uuid()
+
+export const scopedSchema = z.object({
+  organizationId: uuid(),
+  tenantId: uuid(),
+})
+
+export const phoneCallDirectionSchema = z.enum([
+  'inbound',
+  'outbound',
+  'internal',
+  'unknown',
+])
+
+export const phoneCallStatusSchema = z.enum([
+  'new',
+  'ringing',
+  'answered',
+  'missed',
+  'failed',
+  'completed',
+  'unknown',
+])
+
+export const phoneCallParticipantRoleSchema = z.enum([
+  'caller',
+  'callee',
+  'agent',
+  'unknown',
+])
+
+export const ingestParticipantSchema = z.object({
+  role: phoneCallParticipantRoleSchema,
+  providerParticipantId: z.string().nullish(),
+  phoneNumber: z.string().nullish(),
+  displayName: z.string().nullish(),
+  email: z.string().nullish(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const ingestRecordingSchema = z.object({
+  url: z.string().nullish(),
+  providerRecordingId: z.string().nullish(),
+  mimeType: z.string().nullish(),
+  durationSeconds: z.number().int().nullish(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+})
+
+export const ingestPhoneCallSchema = scopedSchema.extend({
+  providerKey: z.string().min(1),
+  integrationId: z.string().nullish(),
+  externalCallId: z.string().min(1),
+  externalConversationId: z.string().nullish(),
+  direction: phoneCallDirectionSchema,
+  status: phoneCallStatusSchema,
+  participants: z.array(ingestParticipantSchema).default([]),
+  recording: ingestRecordingSchema.nullish(),
+  startedAt: z.coerce.date().nullish(),
+  answeredAt: z.coerce.date().nullish(),
+  endedAt: z.coerce.date().nullish(),
+  durationSeconds: z.number().int().nullish(),
+  providerFacts: z.record(z.string(), z.unknown()).optional(),
+  rawPayload: z.record(z.string(), z.unknown()),
+})
+
+export type IngestPhoneCallInput = z.infer<typeof ingestPhoneCallSchema>
+export type IngestParticipantInput = z.infer<typeof ingestParticipantSchema>

package/src/modules/phone_calls/di.ts

@@ -0,0 +1,10 @@
+import { asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import { PhoneCall, PhoneCallParticipant } from './data/entities'
+
+export function register(container: AppContainer) {
+  container.register({
+    PhoneCall: asValue(PhoneCall),
+    PhoneCallParticipant: asValue(PhoneCallParticipant),
+  })
+}