@open-mercato/core 0.7.1-develop.7173.1.a901520d0f → 0.7.1-develop.7176.1.d229567a50

package/dist/modules/phone_calls/setup.js

@@ -0,0 +1,16 @@
+const setup = {
+  defaultRoleFeatures: {
+    admin: [
+      "phone_calls.*"
+    ],
+    employee: [
+      "phone_calls.view"
+    ]
+  }
+};
+var setup_default = setup;
+export {
+  setup_default as default,
+  setup
+};
+//# sourceMappingURL=setup.js.map

package/dist/modules/phone_calls/setup.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/modules/phone_calls/setup.ts"],
+  "sourcesContent": ["import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'\n\nexport const setup: ModuleSetupConfig = {\n  defaultRoleFeatures: {\n    admin: [\n      'phone_calls.*',\n    ],\n    employee: [\n      'phone_calls.view',\n    ],\n  },\n}\n\nexport default setup\n"],
+  "mappings": "AAEO,MAAM,QAA2B;AAAA,EACtC,qBAAqB;AAAA,IACnB,OAAO;AAAA,MACL;AAAA,IACF;AAAA,IACA,UAAU;AAAA,MACR;AAAA,IACF;AAAA,EACF;AACF;AAEA,IAAO,gBAAQ;",
+  "names": []
+}

package/generated/entities/phone_call/index.ts

@@ -0,0 +1,25 @@
+export const id = "id";
+export const organization_id = "organization_id";
+export const tenant_id = "tenant_id";
+export const provider_key = "provider_key";
+export const integration_id = "integration_id";
+export const external_call_id = "external_call_id";
+export const external_conversation_id = "external_conversation_id";
+export const direction = "direction";
+export const status = "status";
+export const started_at = "started_at";
+export const answered_at = "answered_at";
+export const ended_at = "ended_at";
+export const duration_seconds = "duration_seconds";
+export const recording_url = "recording_url";
+export const recording_attachment_id = "recording_attachment_id";
+export const active_transcript_version_id = "active_transcript_version_id";
+export const active_summary_version_id = "active_summary_version_id";
+export const communication_projection_id = "communication_projection_id";
+export const provider_facts = "provider_facts";
+export const raw_snapshot = "raw_snapshot";
+export const ingest_status = "ingest_status";
+export const last_ingested_at = "last_ingested_at";
+export const created_at = "created_at";
+export const updated_at = "updated_at";
+export const deleted_at = "deleted_at";

package/generated/entities/phone_call_participant/index.ts

@@ -0,0 +1,12 @@
+export const id = "id";
+export const organization_id = "organization_id";
+export const tenant_id = "tenant_id";
+export const phone_call_id = "phone_call_id";
+export const provider_participant_id = "provider_participant_id";
+export const role = "role";
+export const phone_number = "phone_number";
+export const display_name = "display_name";
+export const email = "email";
+export const metadata = "metadata";
+export const created_at = "created_at";
+export const updated_at = "updated_at";

package/generated/entities.ids.generated.ts

@@ -34,6 +34,7 @@ export const M = {
     "messages": "messages",
     "communication_channels": "communication_channels",
     "push_notifications": "push_notifications",
+    "phone_calls": "phone_calls",
     "translations": "translations",
     "inbox_ops": "inbox_ops",
     "payment_gateways": "payment_gateways",
@@ -293,6 +294,10 @@ export const M = {
     "push_notifications": {
       "push_notification_delivery": "push_notifications:push_notification_delivery"
     },
+    "phone_calls": {
+      "phone_call": "phone_calls:phone_call",
+      "phone_call_participant": "phone_calls:phone_call_participant"
+    },
     "translations": {
       "entity_translation": "translations:entity_translation"
     },

package/generated/entity-fields-registry.ts

@@ -1872,6 +1872,47 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "updated_at": "updated_at",
       "deleted_at": "deleted_at"
     },
+    "phone_call": {
+      "id": "id",
+      "organization_id": "organization_id",
+      "tenant_id": "tenant_id",
+      "provider_key": "provider_key",
+      "integration_id": "integration_id",
+      "external_call_id": "external_call_id",
+      "external_conversation_id": "external_conversation_id",
+      "direction": "direction",
+      "status": "status",
+      "started_at": "started_at",
+      "answered_at": "answered_at",
+      "ended_at": "ended_at",
+      "duration_seconds": "duration_seconds",
+      "recording_url": "recording_url",
+      "recording_attachment_id": "recording_attachment_id",
+      "active_transcript_version_id": "active_transcript_version_id",
+      "active_summary_version_id": "active_summary_version_id",
+      "communication_projection_id": "communication_projection_id",
+      "provider_facts": "provider_facts",
+      "raw_snapshot": "raw_snapshot",
+      "ingest_status": "ingest_status",
+      "last_ingested_at": "last_ingested_at",
+      "created_at": "created_at",
+      "updated_at": "updated_at",
+      "deleted_at": "deleted_at"
+    },
+    "phone_call_participant": {
+      "id": "id",
+      "organization_id": "organization_id",
+      "tenant_id": "tenant_id",
+      "phone_call_id": "phone_call_id",
+      "provider_participant_id": "provider_participant_id",
+      "role": "role",
+      "phone_number": "phone_number",
+      "display_name": "display_name",
+      "email": "email",
+      "metadata": "metadata",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
     "planner_availability_rule": {
       "id": "id",
       "tenant_id": "tenant_id",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.7.1-develop.7173.1.a901520d0f",
+  "version": "0.7.1-develop.7176.1.d229567a50",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -252,16 +252,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7173.1.a901520d0f",
-    "@open-mercato/shared": "0.7.1-develop.7173.1.a901520d0f",
-    "@open-mercato/ui": "0.7.1-develop.7173.1.a901520d0f",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/shared": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/ui": "0.7.1-develop.7176.1.d229567a50",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.7.1-develop.7173.1.a901520d0f",
-    "@open-mercato/shared": "0.7.1-develop.7173.1.a901520d0f",
-    "@open-mercato/ui": "0.7.1-develop.7173.1.a901520d0f",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/shared": "0.7.1-develop.7176.1.d229567a50",
+    "@open-mercato/ui": "0.7.1-develop.7176.1.d229567a50",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",

package/src/modules/auth/i18n/de.json

@@ -203,6 +203,8 @@
   "auth.acl.features.payment_gateways.view": "View payment gateway transactions",
   "auth.acl.features.perspectives.role_defaults": "Manage role default perspectives",
   "auth.acl.features.perspectives.use": "Use table perspectives",
+  "auth.acl.features.phone_calls.manage": "Telefonanrufe verwalten (Abruf, Rohdaten)",
+  "auth.acl.features.phone_calls.view": "Telefonanrufe anzeigen",
   "auth.acl.features.planner.manage_availability": "Manage availability",
   "auth.acl.features.planner.view": "View schedules",
   "auth.acl.features.progress.cancel": "Cancel progress jobs",
@@ -280,6 +282,7 @@
   "auth.acl.features.storage_providers.manage": "Manage storage providers",
   "auth.acl.features.sync_excel.run": "Upload CSV files and prepare imports",
   "auth.acl.features.sync_excel.view": "View sync_excel uploads and previews",
+  "auth.acl.features.tillio.manage": "Tillio-Integration verwalten",
   "auth.acl.features.translations.manage": "Manage entity translations",
   "auth.acl.features.translations.manage_locales": "Configure supported locales",
   "auth.acl.features.translations.view": "View translations",

package/src/modules/auth/i18n/en.json

@@ -203,6 +203,8 @@
   "auth.acl.features.payment_gateways.view": "View payment gateway transactions",
   "auth.acl.features.perspectives.role_defaults": "Manage role default perspectives",
   "auth.acl.features.perspectives.use": "Use table perspectives",
+  "auth.acl.features.phone_calls.manage": "Manage phone calls (pull, raw payload)",
+  "auth.acl.features.phone_calls.view": "View phone calls",
   "auth.acl.features.planner.manage_availability": "Manage availability",
   "auth.acl.features.planner.view": "View schedules",
   "auth.acl.features.progress.cancel": "Cancel progress jobs",
@@ -280,6 +282,7 @@
   "auth.acl.features.storage_providers.manage": "Manage storage providers",
   "auth.acl.features.sync_excel.run": "Upload CSV files and prepare imports",
   "auth.acl.features.sync_excel.view": "View sync_excel uploads and previews",
+  "auth.acl.features.tillio.manage": "Manage Tillio integration",
   "auth.acl.features.translations.manage": "Manage entity translations",
   "auth.acl.features.translations.manage_locales": "Configure supported locales",
   "auth.acl.features.translations.view": "View translations",

package/src/modules/auth/i18n/es.json

@@ -203,6 +203,8 @@
   "auth.acl.features.payment_gateways.view": "View payment gateway transactions",
   "auth.acl.features.perspectives.role_defaults": "Manage role default perspectives",
   "auth.acl.features.perspectives.use": "Use table perspectives",
+  "auth.acl.features.phone_calls.manage": "Gestionar llamadas telefónicas (importación, datos sin procesar)",
+  "auth.acl.features.phone_calls.view": "Ver llamadas telefónicas",
   "auth.acl.features.planner.manage_availability": "Manage availability",
   "auth.acl.features.planner.view": "View schedules",
   "auth.acl.features.progress.cancel": "Cancel progress jobs",
@@ -280,6 +282,7 @@
   "auth.acl.features.storage_providers.manage": "Manage storage providers",
   "auth.acl.features.sync_excel.run": "Upload CSV files and prepare imports",
   "auth.acl.features.sync_excel.view": "View sync_excel uploads and previews",
+  "auth.acl.features.tillio.manage": "Gestionar la integración con Tillio",
   "auth.acl.features.translations.manage": "Manage entity translations",
   "auth.acl.features.translations.manage_locales": "Configure supported locales",
   "auth.acl.features.translations.view": "View translations",

package/src/modules/auth/i18n/ko.json

@@ -203,6 +203,8 @@
   "auth.acl.features.payment_gateways.view": "View payment gateway transactions",
   "auth.acl.features.perspectives.role_defaults": "Manage role default perspectives",
   "auth.acl.features.perspectives.use": "Use table perspectives",
+  "auth.acl.features.phone_calls.manage": "전화 통화 관리(가져오기, 원시 페이로드)",
+  "auth.acl.features.phone_calls.view": "전화 통화 보기",
   "auth.acl.features.planner.manage_availability": "Manage availability",
   "auth.acl.features.planner.view": "View schedules",
   "auth.acl.features.progress.cancel": "Cancel progress jobs",
@@ -280,6 +282,7 @@
   "auth.acl.features.storage_providers.manage": "Manage storage providers",
   "auth.acl.features.sync_excel.run": "Upload CSV files and prepare imports",
   "auth.acl.features.sync_excel.view": "View sync_excel uploads and previews",
+  "auth.acl.features.tillio.manage": "Tillio 통합 관리",
   "auth.acl.features.translations.manage": "Manage entity translations",
   "auth.acl.features.translations.manage_locales": "Configure supported locales",
   "auth.acl.features.translations.view": "View translations",

package/src/modules/auth/i18n/pl.json

@@ -203,6 +203,8 @@
   "auth.acl.features.payment_gateways.view": "Wyświetl transakcje bramek płatniczych",
   "auth.acl.features.perspectives.role_defaults": "Zarządzaj domyślnymi perspektywami ról",
   "auth.acl.features.perspectives.use": "Używaj perspektyw tabel",
+  "auth.acl.features.phone_calls.manage": "Zarządzaj połączeniami telefonicznymi (pobieranie, surowe dane)",
+  "auth.acl.features.phone_calls.view": "Wyświetl połączenia telefoniczne",
   "auth.acl.features.planner.manage_availability": "Zarządzaj dostępnością",
   "auth.acl.features.planner.view": "Wyświetl harmonogramy",
   "auth.acl.features.progress.cancel": "Anuluj zadania postępu",
@@ -280,6 +282,7 @@
   "auth.acl.features.storage_providers.manage": "Zarządzaj dostawcami pamięci masowej",
   "auth.acl.features.sync_excel.run": "Przesyłaj pliki CSV i przygotowuj importy",
   "auth.acl.features.sync_excel.view": "Wyświetl przesłane pliki i podglądy importu Excel / CSV",
+  "auth.acl.features.tillio.manage": "Zarządzaj integracją Tillio",
   "auth.acl.features.translations.manage": "Zarządzaj tłumaczeniami encji",
   "auth.acl.features.translations.manage_locales": "Konfiguruj obsługiwane ustawienia regionalne",
   "auth.acl.features.translations.view": "Wyświetl tłumaczenia",

package/src/modules/configs/lib/upgrade-actions.ts

@@ -126,6 +126,26 @@ export const upgradeActions: UpgradeActionDefinition[] = [
       await registerSessionInitializationPruneSchedule(container, { tenantId, organizationId })
     },
   },
+  {
+    id: 'phone_calls.seed-call-encryption-maps',
+    version: '0.7.1',
+    messageKey: 'phone_calls.config.upgradeActions.encryptionMaps.message',
+    ctaKey: 'phone_calls.config.upgradeActions.encryptionMaps.cta',
+    successKey: 'phone_calls.config.upgradeActions.encryptionMaps.success',
+    loadingKey: 'phone_calls.config.upgradeActions.encryptionMaps.loading',
+    // `Migration20260822120000` backfills these maps, but only for scopes that had active maps when
+    // it ran. A tenant that upgraded with encryption disabled and turned it on afterwards is left
+    // without a map, so ingest writes call PII as plaintext with nothing to signal it. This is the
+    // heal for that case, and the same re-assert path devices exposes for its own map.
+    // Lazy-imported so configs stays decoupled from phone_calls/entities (mirrors the devices action).
+    run: async ({ em, tenantId, organizationId }) => {
+      const [{ default: phoneCallsEncryptionMaps }, { upsertEncryptionMapSpecs }] = await Promise.all([
+        import('@open-mercato/core/modules/phone_calls/encryption'),
+        import('@open-mercato/core/modules/entities/cli'),
+      ])
+      await upsertEncryptionMapSpecs(em, tenantId, organizationId ?? null, phoneCallsEncryptionMaps)
+    },
+  },
 ]
 
 export function actionsUpToVersion(version: string): UpgradeActionDefinition[] {

package/src/modules/entities/cli.ts

@@ -22,6 +22,7 @@ import {
 import {
   TenantDataEncryptionService,
   parseDecryptedFieldValue,
+  resolveEncryptionKeyId,
 } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
 import { resolveEntityIdFromMetadata } from '@open-mercato/shared/lib/encryption/entityIds'
 import { listEntityMetadata } from '@open-mercato/shared/lib/db/entityMetadata'
@@ -549,6 +550,27 @@ const rotateEncryptionKey: ModuleCli = {
     }
 
     const oldDekCache = new Map<string, TenantDek | null>()
+    // A dry run must not provision key material. `encryptEntityPayload` creates and
+    // persists a tenant DEK in KMS/Vault the first time it runs for a tenant, so a
+    // read-only preview would silently mutate KMS state (#5950). Probe read-only
+    // once per tenant instead, and report what a real run would rewrite.
+    //
+    // The tenant id IS the key id here: this command skips every system-scoped
+    // entity above, and its service is built without `defaultEncryptionMaps`, so
+    // no map it sees can resolve to a `system:<entityId>` key.
+    const dekAvailability = new Map<string, boolean>()
+    const hasExistingDek = async (tenantId: string): Promise<boolean> => {
+      const cached = dekAvailability.get(tenantId)
+      if (cached !== undefined) return cached
+      const available = Boolean(await encryptionService.getDek(tenantId))
+      dekAvailability.set(tenantId, available)
+      if (!available) {
+        console.warn(
+          `[dry-run] Tenant ${tenantId} has no data-encryption key yet. Reporting the rows a real run would encrypt; no key material was provisioned.`,
+        )
+      }
+      return available
+    }
     const processScope = async (
       entityId: string,
       meta: any,
@@ -576,6 +598,7 @@ const rotateEncryptionKey: ModuleCli = {
       const rows = await conn.execute(selectSql, [scope.tenantId, scope.organizationId])
       const list = Array.isArray(rows) ? rows : []
       if (!list.length) return 0
+      const dekAvailable = dryRun ? await hasExistingDek(scope.tenantId) : true
       let updated = 0
       for (const row of list) {
         const payload: Record<string, unknown> = {}
@@ -611,11 +634,26 @@ const rotateEncryptionKey: ModuleCli = {
             payload[rule.field] = parseDecryptedFieldValue(decrypted)
           }
         }
+        if (!dekAvailable) {
+          // Nothing was encrypted because no key exists and this run refuses to
+          // create one. Count the rows a real run would rewrite by applying the
+          // same plaintext/ciphertext filters the update path uses below.
+          const wouldChange = fields.some((rule) => {
+            const col = resolveProperty(meta, rule.field)?.columnName
+            if (!col) return false
+            const value = row[col]
+            if (value === null || value === undefined) return false
+            return rotate ? isEncryptedPayload(value) : !isEncryptedPayload(value)
+          })
+          if (wouldChange) updated += 1
+          continue
+        }
         const encrypted = await encryptionService.encryptEntityPayload(
           entityId,
           payload,
           scope.tenantId,
           scope.organizationId,
+          { createMissingDek: !dryRun },
         )
         const updates: Record<string, unknown> = {}
         for (const rule of fields) {
@@ -1129,6 +1167,17 @@ const backfillSystemEncryption: ModuleCli = {
       const columnList = Array.from(columns)
       const selectList = columnList.map((column) => `"${column}"`).join(', ')
 
+      // Same dry-run guarantee as rotate-encryption-key: previewing must not make
+      // the KMS provision this entity's system DEK as a side effect (#5950).
+      const systemDekAvailable = dryRun
+        ? Boolean(await encryptionService.getDek(resolveEncryptionKeyId(entityId, 'system', null)))
+        : true
+      if (!systemDekAvailable) {
+        console.warn(
+          `[dry-run] ${entityId} has no system data-encryption key yet. Reporting the rows a real run would encrypt; no key material was provisioned.`,
+        )
+      }
+
       let cursor: unknown = null
       let entityRowsScanned = 0
       let entityRowsUpdated = 0
@@ -1160,8 +1209,19 @@ const backfillSystemEncryption: ModuleCli = {
             }
           }
           if (!hasPlaintext) continue
+          if (!systemDekAvailable) {
+            // `hasPlaintext` already means a real run would rewrite this row.
+            entityRowsUpdated += 1
+            continue
+          }
 
-          const encrypted = await encryptionService.encryptEntityPayload(entityId, payload, null, null)
+          const encrypted = await encryptionService.encryptEntityPayload(
+            entityId,
+            payload,
+            null,
+            null,
+            { createMissingDek: !dryRun },
+          )
           const updates: Record<string, unknown> = {}
           for (const rule of map.fields) {
             const resolved = resolveProperty(meta, rule.field)

package/src/modules/entities/migrations/Migration20260822120000.ts

@@ -0,0 +1,56 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// Backfill the phone_calls encryption maps for every pre-existing (tenant, org) scope that already
+// has active encryption maps. Encryption maps are seeded only at tenant creation (`entities
+// seed-encryption`), so a tenant that predates the phone_calls module has no map for either of its
+// entities, `encryptEntityPayload` no-ops, and caller/destination numbers plus the untouched Tillio
+// payload are written as PLAINTEXT, both in the base tables and in the query index doc. Restricting
+// the insert to scopes that ALREADY have maps mirrors what seed-encryption does and correctly skips
+// tenants with encryption disabled (which have no maps at all). Idempotent via the NOT EXISTS guard,
+// so re-runs are a no-op and it stays consistent with the runtime `upsertEncryptionMapSpecs` helper.
+// Same shape as the `devices:user_device` backfill in Migration20260722120000.
+export class Migration20260822120000 extends Migration {
+
+  override async up(): Promise<void> {
+    this.addSql(`
+      insert into "encryption_maps" ("id", "entity_id", "tenant_id", "organization_id", "fields_json", "is_active", "created_at", "updated_at")
+      select gen_random_uuid(), 'phone_calls:phone_call', src."tenant_id", src."organization_id", '[{"field":"raw_snapshot"},{"field":"provider_facts"},{"field":"recording_url"}]'::jsonb, true, now(), now()
+      from (
+        select distinct "tenant_id", "organization_id"
+        from "encryption_maps"
+        where "is_active" = true and "deleted_at" is null
+      ) src
+      where not exists (
+        select 1 from "encryption_maps" existing
+        where existing."entity_id" = 'phone_calls:phone_call'
+          and existing."tenant_id" is not distinct from src."tenant_id"
+          and existing."organization_id" is not distinct from src."organization_id"
+          and existing."deleted_at" is null
+      );
+    `);
+
+    this.addSql(`
+      insert into "encryption_maps" ("id", "entity_id", "tenant_id", "organization_id", "fields_json", "is_active", "created_at", "updated_at")
+      select gen_random_uuid(), 'phone_calls:phone_call_participant', src."tenant_id", src."organization_id", '[{"field":"phone_number"},{"field":"display_name"},{"field":"email"}]'::jsonb, true, now(), now()
+      from (
+        select distinct "tenant_id", "organization_id"
+        from "encryption_maps"
+        where "is_active" = true and "deleted_at" is null
+      ) src
+      where not exists (
+        select 1 from "encryption_maps" existing
+        where existing."entity_id" = 'phone_calls:phone_call_participant'
+          and existing."tenant_id" is not distinct from src."tenant_id"
+          and existing."organization_id" is not distinct from src."organization_id"
+          and existing."deleted_at" is null
+      );
+    `);
+  }
+
+  override async down(): Promise<void> {
+    // Reverts the feature's encryption maps. phone_calls maps have no source other than this module,
+    // so deleting them all returns the schema to its pre-feature state.
+    this.addSql(`delete from "encryption_maps" where "entity_id" in ('phone_calls:phone_call', 'phone_calls:phone_call_participant');`);
+  }
+
+}

package/src/modules/phone_calls/acl.ts

@@ -0,0 +1,11 @@
+export const features = [
+  { id: 'phone_calls.view', title: 'View phone calls', module: 'phone_calls' },
+  {
+    id: 'phone_calls.manage',
+    title: 'Manage phone calls (pull, raw payload)',
+    module: 'phone_calls',
+    dependsOn: ['phone_calls.view'],
+  },
+]
+
+export default features

package/src/modules/phone_calls/api/calls/route.ts

@@ -0,0 +1,150 @@
+import { z } from 'zod'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import type { Where } from '@open-mercato/shared/lib/query/types'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
+import { E } from '#generated/entities.ids.generated'
+import { PhoneCall } from '../../data/entities'
+import { createPhoneCallsCrudOpenApi, createPagedListResponseSchema } from '../openapi'
+
+const filterDateSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .refine((value) => !Number.isNaN(new Date(value).getTime()), { message: 'Expected a parsable date' })
+
+const listSchema = z
+  .object({
+    page: z.coerce.number().min(1).default(1),
+    pageSize: z.coerce.number().min(1).max(100).default(50),
+    q: z.string().optional(),
+    providerKey: z.string().optional(),
+    status: z.string().optional(),
+    direction: z.string().optional(),
+    // Validated rather than parsed later: an unparsable value used to be dropped, so a typo in a
+    // filter silently returned the unfiltered page.
+    startedFrom: filterDateSchema.optional(),
+    startedTo: filterDateSchema.optional(),
+    sortField: z.string().optional(),
+    sortDir: z.enum(['asc', 'desc']).optional(),
+    id: z.string().uuid().optional(),
+  })
+  .passthrough()
+
+const dayOnlySchema = z.iso.date()
+
+// A day is a range, not an instant. `new Date('2026-08-20')` is midnight UTC, so using it as
+// the upper bound drops every call on the day the user picked. The filter bar sends bare
+// `yyyy-MM-dd` for both ends, so each is widened to the day it names; a caller that sends a
+// full timestamp keeps the instant it asked for.
+function rangeBoundary(value: string, edge: 'start' | 'end'): Date {
+  if (!dayOnlySchema.safeParse(value).success) return new Date(value)
+  return new Date(`${value}T${edge === 'start' ? '00:00:00.000' : '23:59:59.999'}Z`)
+}
+
+const routeMetadata = {
+  GET: { requireAuth: true, requireFeatures: ['phone_calls.view'] },
+}
+
+export const metadata = routeMetadata
+
+// No `recording_url`: provider recording links carry their own access token, and this route
+// is gated on `phone_calls.view`. The key still ships as null so the response shape holds.
+const listFields = [
+  'id',
+  'organization_id',
+  'tenant_id',
+  'provider_key',
+  'integration_id',
+  'external_call_id',
+  'external_conversation_id',
+  'direction',
+  'status',
+  'started_at',
+  'answered_at',
+  'ended_at',
+  'duration_seconds',
+  'ingest_status',
+  'last_ingested_at',
+  'created_at',
+  'updated_at',
+]
+
+const crud = makeCrudRoute({
+  metadata: routeMetadata,
+  orm: {
+    entity: PhoneCall,
+    idField: 'id',
+    orgField: 'organizationId',
+    tenantField: 'tenantId',
+    softDeleteField: 'deletedAt',
+  },
+  indexer: { entityType: E.phone_calls.phone_call },
+  list: {
+    schema: listSchema,
+    entityId: E.phone_calls.phone_call,
+    fields: listFields,
+    transformItem: (item: Record<string, unknown>) => ({ ...item, recording_url: null }),
+    sortFieldMap: {
+      externalCallId: 'external_call_id',
+      startedAt: 'started_at',
+      endedAt: 'ended_at',
+      durationSeconds: 'duration_seconds',
+      status: 'status',
+      direction: 'direction',
+      providerKey: 'provider_key',
+      ingestStatus: 'ingest_status',
+      createdAt: 'created_at',
+      updatedAt: 'updated_at',
+    },
+    buildFilters: (query): Where<Record<string, unknown>> => {
+      const filters: Record<string, unknown> = {}
+      if (query.id) filters.id = { $eq: query.id }
+      if (query.providerKey) filters.provider_key = { $eq: query.providerKey }
+      if (query.status) filters.status = { $eq: query.status }
+      if (query.direction) filters.direction = { $eq: query.direction }
+      if (query.q) {
+        const term = buildIlikeTerm(query.q)
+        filters.$or = [
+          { external_call_id: { $ilike: term } },
+          { external_conversation_id: { $ilike: term } },
+          { provider_key: { $ilike: term } },
+        ]
+      }
+      const startedRange: Record<string, Date> = {}
+      if (query.startedFrom) startedRange.$gte = rangeBoundary(query.startedFrom, 'start')
+      if (query.startedTo) startedRange.$lte = rangeBoundary(query.startedTo, 'end')
+      if (Object.keys(startedRange).length) filters.started_at = startedRange
+      return filters
+    },
+  },
+})
+
+export const GET = crud.GET
+
+const phoneCallListItemSchema = z.object({
+  id: z.string().uuid(),
+  organization_id: z.string().uuid().nullable().optional(),
+  tenant_id: z.string().uuid().nullable().optional(),
+  provider_key: z.string().nullable().optional(),
+  integration_id: z.string().nullable().optional(),
+  external_call_id: z.string().nullable().optional(),
+  external_conversation_id: z.string().nullable().optional(),
+  direction: z.string().nullable().optional(),
+  status: z.string().nullable().optional(),
+  started_at: z.string().nullable().optional(),
+  answered_at: z.string().nullable().optional(),
+  ended_at: z.string().nullable().optional(),
+  duration_seconds: z.number().nullable().optional(),
+  recording_url: z.string().nullable().optional(),
+  ingest_status: z.string().nullable().optional(),
+  last_ingested_at: z.string().nullable().optional(),
+  created_at: z.string().nullable().optional(),
+  updated_at: z.string().nullable().optional(),
+})
+
+export const openApi = createPhoneCallsCrudOpenApi({
+  resourceName: 'PhoneCall',
+  pluralName: 'PhoneCalls',
+  querySchema: listSchema,
+  listResponseSchema: createPagedListResponseSchema(phoneCallListItemSchema),
+})

package/src/modules/phone_calls/api/openapi.ts

@@ -0,0 +1,25 @@
+import { type ZodTypeAny } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import {
+  createCrudOpenApiFactory,
+  createPagedListResponseSchema as createSharedPagedListResponseSchema,
+  defaultOkResponseSchema as sharedDefaultOkResponseSchema,
+  type CrudOpenApiOptions,
+} from '@open-mercato/shared/lib/openapi/crud'
+
+export const defaultOkResponseSchema = sharedDefaultOkResponseSchema
+
+export function createPagedListResponseSchema(itemSchema: ZodTypeAny) {
+  return createSharedPagedListResponseSchema(itemSchema, { paginationMetaOptional: true })
+}
+
+const buildPhoneCallsCrudOpenApi = createCrudOpenApiFactory({
+  defaultTag: 'PhoneCalls',
+  defaultOkResponseSchema,
+  makeListDescription: ({ pluralLower }) =>
+    `Returns a paginated collection of ${pluralLower} scoped to the authenticated organization.`,
+})
+
+export function createPhoneCallsCrudOpenApi(options: CrudOpenApiOptions): OpenApiRouteDoc {
+  return buildPhoneCallsCrudOpenApi(options)
+}

package/src/modules/phone_calls/backend/page.meta.ts

@@ -0,0 +1,12 @@
+export const metadata = {
+  requireAuth: true,
+  requireFeatures: ['phone_calls.view'],
+  pageTitle: 'Phone Calls',
+  pageTitleKey: 'phone_calls.nav.calls',
+  pageGroup: 'Communication',
+  pageGroupKey: 'phone_calls.nav.group',
+  pagePriority: 10,
+  pageOrder: 100,
+  icon: 'phone-call',
+  breadcrumb: [{ label: 'Phone Calls', labelKey: 'phone_calls.nav.calls' }],
+}