@open-mercato/channel-imap 0.6.4

package/jest.config.cjs

@@ -0,0 +1,34 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/channel-imap/(.*)$': '<rootDir>/src/$1',
+    '^@open-mercato/core/(.*)$': '<rootDir>/../core/src/$1',
+    '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
+    '^@open-mercato/queue/(.*)$': '<rootDir>/../queue/src/$1',
+    '^@open-mercato/ui/(.*)$': '<rootDir>/../ui/src/$1',
+  },
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      '<rootDir>/../../scripts/jest-mikroorm-transformer.cjs',
+      {
+        tsconfig: {
+          jsx: 'react-jsx',
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  transformIgnorePatterns: [
+    'node_modules/(?!(@mikro-orm|kysely)/)',
+  ],
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@open-mercato/channel-imap",
+  "version": "0.6.4",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*.tsx": {
+      "types": "./src/*.tsx",
+      "default": "./dist/*.js"
+    },
+    "./*.json": "./src/*.json",
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*.json": "./src/*/*.json",
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*.json": "./src/*/*/*.json",
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*.json": "./src/*/*/*/*.json",
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    },
+    "./*/*/*/*/*.json": "./src/*/*/*/*/*.json",
+    "./*/*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*/*.ts",
+        "./src/*/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*/*.js"
+    }
+  },
+  "dependencies": {
+    "@open-mercato/core": "0.6.4",
+    "@open-mercato/queue": "0.6.4",
+    "@open-mercato/ui": "0.6.4",
+    "@types/mailparser": "^3.4.5",
+    "@types/nodemailer": "^8.0.0",
+    "imapflow": "^1.0.171",
+    "mailparser": "^3.7.1",
+    "nodemailer": "^8.0.10"
+  },
+  "peerDependencies": {
+    "@mikro-orm/postgresql": "^7.0.14",
+    "@open-mercato/shared": "0.6.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@open-mercato/shared": "0.6.4",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.0",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "ts-jest": "^29.4.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/channel-imap"
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { metadata } from './modules/channel_imap/index'

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-001.spec.ts

@@ -0,0 +1,80 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+
+/**
+ * TC-CHANNEL-EMAIL-001 — IMAP provider visible to the hub's per-user channel API.
+ *
+ * After Slice 3e registers the `imap` adapter inside `@open-mercato/channel-imap`,
+ * the per-user channel routes must accept `providerKey: 'imap'` as a known provider.
+ * Without a live IMAP test server we exercise the routing-and-validation surface only;
+ * actual credential validation against a real IMAP host is covered by the unit tests
+ * in `lib/__tests__/validate-credentials.test.ts`.
+ *
+ * The route should NOT 404 the provider (proves registration), and should NOT 500
+ * (proves the request reaches the adapter and rejects cleanly when no live server
+ * is reachable).
+ */
+test.describe('TC-CHANNEL-EMAIL-001: IMAP provider registration', () => {
+  test('POST connect/credentials with providerKey=imap reaches the adapter', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/connect/credentials',
+      {
+        token,
+        data: {
+          providerKey: 'imap',
+          displayName: 'IMAP — integration test',
+          credentials: {
+            imapHost: 'invalid.test.example',
+            imapPort: 993,
+            imapTls: 'tls',
+            imapUser: 'fake@example.test',
+            imapPassword: 'wrong-password',
+            smtpHost: 'invalid.test.example',
+            smtpPort: 465,
+            smtpTls: 'tls',
+            smtpUser: 'fake@example.test',
+            smtpPassword: 'wrong-password',
+            fromAddress: 'fake@example.test',
+          },
+        },
+      },
+    )
+    expect(response.status(), 'route should not 5xx').toBeLessThan(500)
+    // 401 (no auth seeded) / 422 (validation failure surfaced via createCrudFormError) /
+    // 502 ish — but never 404, which would indicate the provider isn't registered.
+    expect(response.status(), 'IMAP provider should be registered').not.toBe(404)
+  })
+
+  test('POST connect/credentials with providerKey=imap and malformed credentials returns 422', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/connect/credentials',
+      {
+        token,
+        data: {
+          providerKey: 'imap',
+          displayName: 'IMAP — malformed',
+          credentials: {
+            // Missing required imap/smtp fields entirely.
+            fromAddress: 'not-an-email',
+          },
+        },
+      },
+    )
+    expect(response.status()).toBeLessThan(500)
+    expect([401, 422, 400]).toContain(response.status())
+    if (response.status() === 422) {
+      // The route surfaces credential-validation failures as { error, fieldErrors }
+      // (see api/post/channels/connect/credentials/route.ts).
+      const body = await readJsonSafe<{ error?: string; fieldErrors?: Record<string, string> }>(response)
+      expect(body?.fieldErrors ?? body?.error).toBeTruthy()
+    }
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-002.spec.ts

@@ -0,0 +1,28 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-002 — IMAP webhook endpoint stays disabled.
+ *
+ * IMAP has no webhook flow; the polling worker drives inbound. We still expose
+ * the standard `/api/communication_channels/webhook/[provider]` URL because the
+ * hub's route is generic. The IMAP adapter's `verifyWebhook` returns an
+ * `eventType: 'other'` event so the route MUST respond 2xx (not handled) instead
+ * of 5xx-ing or 404-ing.
+ */
+test.describe('TC-CHANNEL-EMAIL-002: IMAP webhook is a no-op', () => {
+  test('POST /api/communication_channels/webhook/imap does not 5xx', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/webhook/imap',
+      {
+        token,
+        data: { ping: true },
+      },
+    )
+    expect(response.status(), 'webhook route should not 5xx').toBeLessThan(500)
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-003.spec.ts

@@ -0,0 +1,23 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-003 — Profile page renders with the IMAP provider installed.
+ *
+ * Confirms `@open-mercato/channel-imap` does not break the per-user profile page
+ * (`/backend/profile/communication-channels`). Empty-state still renders even
+ * when the IMAP provider is the only one registered.
+ */
+test.describe('TC-CHANNEL-EMAIL-003: profile page with IMAP provider installed', () => {
+  test('GET /backend/profile/communication-channels does not 5xx', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'GET',
+      '/backend/profile/communication-channels',
+      { token },
+    )
+    expect(response.status(), 'profile page should not 5xx').toBeLessThan(500)
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-021.spec.ts

@@ -0,0 +1,40 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-021 — IMAP zero-history bootstrap
+ *
+ * Verifies that the polling worker surface exists and that the
+ * `/poll-now` operator endpoint is reachable. The full happy path —
+ * a freshly-connected channel persists `UIDVALIDITY` + `UIDNEXT` and
+ * fetches ZERO historical messages — is captured in the QA scenario
+ * markdown `TC-CHANNEL-EMAIL-021-imap-bootstrap.md`.
+ *
+ * Unit-level coverage of the bootstrap branch lives in
+ * `packages/channel-imap/.../lib/__tests__/adapter.test.ts`
+ * (`fetchHistory` describe block, "bootstrap" case).
+ */
+test.describe('TC-CHANNEL-EMAIL-021: IMAP bootstrap', () => {
+  test('poll-now endpoint requires authentication', async ({ request }) => {
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/00000000-0000-4000-8000-000000000021/poll-now',
+      // Intentionally empty token — this assertion is the 401 unauth path.
+      { token: '' },
+    )
+    expect(response.status()).toBe(401)
+  })
+
+  test('poll-now endpoint returns 400 for invalid UUID', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/not-a-uuid/poll-now',
+      { token },
+    )
+    expect(response.status()).toBe(400)
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-022.spec.ts

@@ -0,0 +1,38 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-022 — IMAP incremental ingest within 90s
+ *
+ * Verifies the channels-list endpoint is reachable (which proves the
+ * poll-tick scheduler + per-channel polling pipeline is wired). Full
+ * E2E (new mail arrives → polling worker picks it up within 60s tick →
+ * ingest-inbound-message creates a CRM interaction within 90s) is in
+ * the QA scenario markdown `TC-CHANNEL-EMAIL-022-imap-incremental.md`.
+ */
+test.describe('TC-CHANNEL-EMAIL-022: IMAP incremental polling', () => {
+  test('me/channels endpoint requires authentication', async ({ request }) => {
+    // Intentionally empty token — this assertion is the 401 unauth path.
+    const response = await apiRequest(
+      request,
+      'GET',
+      '/api/communication_channels/me/channels',
+      { token: '' },
+    )
+    expect(response.status()).toBe(401)
+  })
+
+  test('me/channels returns items array when authenticated', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'GET',
+      '/api/communication_channels/me/channels',
+      { token },
+    )
+    expect(response.status()).toBe(200)
+    const body = (await response.json()) as { items?: unknown }
+    expect(Array.isArray(body.items)).toBe(true)
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-023.spec.ts

@@ -0,0 +1,31 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-023 — Threading via References token
+ *
+ * Smoke: the layered thread matcher prefers `token-references`
+ * (highest-confidence strategy) when an inbound message carries our
+ * synthetic `<om_TOKEN@open-mercato.invalid>` Message-ID in
+ * `References`. The 5-strategy fallthrough order is unit-tested in
+ * `packages/core/.../lib/__tests__/thread-matcher.test.ts`; the
+ * end-to-end "send → reply preserves References → CRM threads back"
+ * path is in the QA scenario markdown.
+ *
+ * Webhook-less providers have no public endpoint to assert against,
+ * so this smoke test is intentionally minimal — it just confirms the
+ * platform's send-as-user route is reachable (used by the outbound
+ * test setup in the QA scenario).
+ */
+test.describe('TC-CHANNEL-EMAIL-023: References-token threading', () => {
+  test('send-as-user endpoint requires authentication', async ({ request }) => {
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/send-as-user',
+      // Intentionally empty token — this test asserts the 401 unauth path.
+      { token: '', data: { channelId: '00000000-0000-4000-8000-000000000023' } },
+    )
+    expect(response.status()).toBe(401)
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-024.spec.ts

@@ -0,0 +1,27 @@
+import { expect, test } from '@playwright/test'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-024 — Threading via body footer
+ *
+ * When the recipient's MUA strips RFC5322 References on reply, our
+ * hidden body-footer marker (`<span style="display:none">[OM:TOKEN]</span>`
+ * for HTML; `[OM:TOKEN]` bracketed marker for plain text) still
+ * survives quoting and the layered matcher's `token-body` strategy
+ * threads the reply correctly.
+ *
+ * Full E2E in the QA scenario markdown. This smoke test confirms the
+ * send-as-user endpoint exists (same shape as TC-023).
+ */
+test.describe('TC-CHANNEL-EMAIL-024: Body-footer threading', () => {
+  test('send-as-user endpoint exists at the expected path', async ({ request }) => {
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/send-as-user',
+      // Intentionally empty token — the 401 / 400 branch is what we assert.
+      { token: '', data: {} },
+    )
+    expect([400, 401]).toContain(response.status())
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-025.spec.ts

@@ -0,0 +1,23 @@
+import { test } from '@playwright/test'
+
+/**
+ * TC-CHANNEL-EMAIL-025 — JWZ-headers fallback threading
+ *
+ * Verifies the `jwz-headers` strategy (Spec B § thread-matcher,
+ * confidence: medium) — when an inbound reply has no `om_*` token
+ * but carries `In-Reply-To` / `References` pointing at one of our
+ * outbound `Message-Id`s, the matcher walks the conventional JWZ
+ * algorithm against the existing `external_messages` table.
+ *
+ * This path is exercised end-to-end by the QA scenario markdown
+ * `TC-CHANNEL-EMAIL-025-jwz-fallback.md`. The unit-level coverage
+ * lives in `packages/core/.../lib/__tests__/thread-matcher.test.ts`
+ * (Strategy 3 — jwz-headers describe block).
+ *
+ * No additional API surface to assert at the integration layer
+ * beyond the smoke tests already in TC-023/024 — this spec file
+ * documents the existence of the JWZ pathway for QA-tracking purposes.
+ */
+test.describe('TC-CHANNEL-EMAIL-025: JWZ-headers fallback', () => {
+  test.skip('behavioral coverage: thread-matcher.test.ts Strategy 3 (jwz-headers). Playwright E2E is infeasible — provider mock seams are process-local (see TC-CHANNEL-EMAIL-031 / TC-CRM-EMAIL-001).', () => {})
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-026.spec.ts

@@ -0,0 +1,18 @@
+import { test } from '@playwright/test'
+
+/**
+ * TC-CHANNEL-EMAIL-026 — Subject + participants fallback threading
+ *
+ * Last-ditch matcher strategy: when neither `om_*` token nor JWZ
+ * headers are present, the matcher normalises the inbound subject
+ * (`Re:`, `Fwd:`, `[EXTERNAL]` stripped) and checks for an existing
+ * thread whose participants overlap >= 50% with the inbound's
+ * sender/to/cc. Confidence: low.
+ *
+ * Unit-tested in `packages/core/.../lib/__tests__/thread-matcher.test.ts`
+ * (Strategy 4 — subject-participants). End-to-end is the QA scenario
+ * markdown.
+ */
+test.describe('TC-CHANNEL-EMAIL-026: Subject + participants fallback', () => {
+  test.skip('behavioral coverage: thread-matcher.test.ts Strategy 4 (subject + participants). Playwright E2E is infeasible — provider mock seams are process-local (see TC-CHANNEL-EMAIL-031 / TC-CRM-EMAIL-001).', () => {})
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-027.spec.ts

@@ -0,0 +1,18 @@
+import { test } from '@playwright/test'
+
+/**
+ * TC-CHANNEL-EMAIL-027 — Auto-recovery from `status='error'`
+ *
+ * Spec B § Phase B5 — `poll-tick.ts` enumerates two channel pools per
+ * tick: (a) `status='connected'` and due for polling, (b) `status='error'`
+ * whose `lastFailureAt` is older than `OM_CHANNEL_AUTO_RECOVER_MINUTES`
+ * (default 30). A successful poll in pool (b) flips status back to
+ * 'connected' via `poll-channel.ts`.
+ *
+ * Unit-tested in `packages/core/.../workers/__tests__/poll-tick.test.ts`
+ * (auto-recovery describe block). Full E2E (force a transient error →
+ * fast-forward 30 min → next tick recovers) is in the QA scenario.
+ */
+test.describe('TC-CHANNEL-EMAIL-027: Auto-recovery sweep', () => {
+  test.skip('behavioral coverage: workers/__tests__/poll-tick.test.ts (auto-recovery sweep). Playwright E2E is infeasible — provider mock seams are process-local + needs scheduler fast-forward.', () => {})
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-028.spec.ts

@@ -0,0 +1,19 @@
+import { test } from '@playwright/test'
+
+/**
+ * TC-CHANNEL-EMAIL-028 — Malformed MIME → dead-letter, cursor advances
+ *
+ * Spec B § Phase B4 — `poll-channel.ts` classifies per-message ingest
+ * failures: transient failures abort the loop without advancing the
+ * cursor (idempotent retry on next tick), permanent failures write the
+ * raw MIME blob + error metadata to `ChannelIngestDeadLetter`
+ * (encrypted at rest via `defaultEncryptionMaps`) and the cursor
+ * advances anyway so the bad blob never re-stalls the channel.
+ *
+ * Unit-tested via the `ChannelIngestDeadLetter row shape (Spec B § B4)`
+ * describe in `ingest-inbound-message.test.ts` plus the implementation
+ * paths in `poll-channel.test.ts`. Full E2E in the QA scenario.
+ */
+test.describe('TC-CHANNEL-EMAIL-028: Malformed MIME → dead-letter', () => {
+  test.skip('behavioral coverage: workers/__tests__/poll-channel.test.ts (permanent ingest failure → dead-letter + cursor advances; transient → cursor held). Playwright E2E is infeasible — provider mock seams are process-local.', () => {})
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-029.spec.ts

@@ -0,0 +1,72 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+
+/**
+ * TC-CHANNEL-EMAIL-029 — operator-triggered backlog import (Spec B § Phase B6).
+ *
+ * Verifies that the `/api/communication_channels/channels/{id}/import-history`
+ * route is reachable, requires authentication, validates the body, and 404s
+ * for non-existent / not-owned channels (the access-control branch).
+ *
+ * Concurrency guard (429), the ProgressJob lifecycle, and the IMAP SEARCH +
+ * fetch loop are exercised by the unit-test layer:
+ *   - packages/core/src/modules/communication_channels/commands/__tests__/queue-import-history.test.ts
+ *   - packages/core/src/modules/communication_channels/workers/__tests__/channel-import-history.test.ts
+ *   - packages/channel-imap/src/modules/channel_imap/lib/__tests__/adapter.test.ts (importHistory cases)
+ *
+ * The full end-to-end (connect a mailbox → POST /import-history → ProgressJob
+ * completes → imported messages visible on Person timeline) is captured in
+ * `.ai/qa/scenarios/TC-CHANNEL-EMAIL-029-import-history.md` for manual QA.
+ */
+test.describe('TC-CHANNEL-EMAIL-029: import-history route wiring', () => {
+  const FAKE_CHANNEL_ID = '00000000-0000-0000-0000-000000000029'
+
+  test('rejects unauthenticated requests', async ({ request }) => {
+    const response = await apiRequest(
+      request,
+      'POST',
+      `/api/communication_channels/channels/${FAKE_CHANNEL_ID}/import-history`,
+      // Intentionally empty token — this test asserts the 401 unauth path.
+      { token: '', data: { sinceDays: 14 } },
+    )
+    expect(response.status()).toBe(401)
+  })
+
+  test('returns 400 on invalid channel id', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/not-a-uuid/import-history',
+      { token, data: { sinceDays: 14 } },
+    )
+    expect(response.status()).toBe(400)
+  })
+
+  test('returns 400 when body fails Zod validation (sinceDays out of range)', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      `/api/communication_channels/channels/${FAKE_CHANNEL_ID}/import-history`,
+      { token, data: { sinceDays: 9999 } },
+    )
+    expect(response.status()).toBe(400)
+  })
+
+  test('returns 404 for a channel the caller does not own', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      `/api/communication_channels/channels/${FAKE_CHANNEL_ID}/import-history`,
+      { token, data: { sinceDays: 14, maxMessages: 100 } },
+    )
+    // A caller without an organization scope is rejected with 400 ("No
+    // organization scope") before the channel lookup; a scoped caller reaches
+    // the channel-not-found branch (404, same shape as access-denied for parity).
+    expect(response.status(), 'route should not 5xx').toBeLessThan(500)
+    expect([400, 403, 404]).toContain(response.status())
+  })
+})

package/src/modules/channel_imap/__integration__/TC-CHANNEL-EMAIL-030.spec.ts

@@ -0,0 +1,19 @@
+import { test } from '@playwright/test'
+
+/**
+ * TC-CHANNEL-EMAIL-030 — Sent-folder dedup
+ *
+ * Spec B § Phase B3 — `ingest-inbound-message.ts` short-circuits when
+ * the inbound message's `messageId` matches an outbound
+ * `MessageChannelLink.channelMetadata.messageId` we already sent. This
+ * prevents IMAP polls of the Sent folder from creating duplicate
+ * inbound rows for every outbound the user sent.
+ *
+ * Contract unit-tested in `ingest-inbound-message.test.ts` (sent-folder
+ * dedup describe block). Full E2E in the QA scenario markdown — send
+ * an outbound, observe Sent folder surfaces it, confirm no duplicate
+ * `MessageChannelLink` row appears for the inbound direction.
+ */
+test.describe('TC-CHANNEL-EMAIL-030: Sent-folder dedup', () => {
+  test.skip('behavioral coverage: ingest-inbound-message.test.ts (sent-folder dedup contract + dedup → status=duplicate). Playwright E2E is infeasible — provider mock seams are process-local.', () => {})
+})

package/src/modules/channel_imap/acl.ts

@@ -0,0 +1,6 @@
+export const features = [
+  { id: 'channel_imap.view', title: 'View IMAP channel configuration', module: 'channel_imap' },
+  { id: 'channel_imap.configure', title: 'Configure IMAP channel defaults', module: 'channel_imap' },
+]
+
+export default features

package/src/modules/channel_imap/di.ts

@@ -0,0 +1,26 @@
+import { asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  hasChannelAdapter,
+  registerChannelAdapter,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter-registry-singleton'
+import { getImapChannelAdapter } from './lib/adapter'
+import { channelImapHealthCheck } from './lib/health'
+
+/**
+ * Re-register the adapter on container creation as a safety net for runtime
+ * environments that bypass module setup (worker-only nodes, ad-hoc CLI). The
+ * underlying registry is process-wide so the registration is idempotent.
+ */
+export function register(container: AppContainer): void {
+  if (!hasChannelAdapter('imap')) {
+    registerChannelAdapter(getImapChannelAdapter())
+  }
+  container.register({
+    channelImapAdapter: asValue(getImapChannelAdapter()),
+    // Registered under the exact service name declared in `integration.ts`
+    // (`healthCheck.service`). Without this, the hub's `container.resolve(...)`
+    // throws and the channel reports permanently 'unhealthy'.
+    channelImapHealthCheck: asValue(channelImapHealthCheck),
+  })
+}

package/src/modules/channel_imap/index.ts

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: 'channel_imap',
+  title: 'IMAP + SMTP Email Channel',
+  description:
+    'Connect personal mailboxes via IMAP for inbound polling and SMTP for outbound delivery. Pairs with the Communications Hub (SPEC-045d).',
+}