@open-mercato/channel-ses 0.7.1-develop.7151.1.00d0391847

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@open-mercato/channel-ses",
+  "version": "0.7.1-develop.7151.1.00d0391847",
+  "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"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts",
+        "./src/*.tsx"
+      ],
+      "default": "./dist/*.js"
+    },
+    "./*/*": {
+      "types": [
+        "./src/*/*.ts",
+        "./src/*/*.tsx"
+      ],
+      "default": "./dist/*/*.js"
+    },
+    "./*/*/*": {
+      "types": [
+        "./src/*/*/*.ts",
+        "./src/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*.js"
+    },
+    "./*/*/*/*": {
+      "types": [
+        "./src/*/*/*/*.ts",
+        "./src/*/*/*/*.tsx"
+      ],
+      "default": "./dist/*/*/*/*.js"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-sesv2": "^3.946.0",
+    "@open-mercato/core": "0.7.1-develop.7151.1.00d0391847",
+    "@types/nodemailer": "^8.0.0",
+    "nodemailer": "^9.0.0"
+  },
+  "peerDependencies": {
+    "@mikro-orm/postgresql": "^7.0.14",
+    "@open-mercato/ai-assistant": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/shared": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/ui": "0.7.1-develop.7151.1.00d0391847",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@open-mercato/ai-assistant": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/shared": "0.7.1-develop.7151.1.00d0391847",
+    "@open-mercato/ui": "0.7.1-develop.7151.1.00d0391847",
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "ts-jest": "^29.4.11",
+    "typescript": "7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/channel-ses"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/index.ts

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

package/src/modules/channel_ses/__tests__/contracts.test.ts

@@ -0,0 +1,27 @@
+import { features } from '../acl'
+import { sesCapabilities } from '../capabilities'
+import { integration } from '../integration'
+import { metadata } from '../index'
+
+describe('channel_ses contracts', () => {
+  it('declares supported module metadata and coordinated versions', () => {
+    expect(metadata).toEqual(expect.objectContaining({
+      id: 'channel_ses',
+      version: '0.1.0',
+      requires: ['communication_channels', 'integrations'],
+    }))
+    expect(integration).toEqual(expect.objectContaining({
+      version: '0.1.0',
+      healthCheck: { service: 'channelSesHealthCheck' },
+    }))
+    expect(metadata).not.toHaveProperty('dependencies')
+  })
+
+  it('exports catalog-compatible ACL features and honest capabilities', () => {
+    expect(features).toEqual([
+      { id: 'channel_ses.view', title: expect.any(String), module: 'channel_ses' },
+      { id: 'channel_ses.configure', title: expect.any(String), module: 'channel_ses' },
+    ])
+    expect(sesCapabilities.fileSharing).toBe(false)
+  })
+})

package/src/modules/channel_ses/acl.ts

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

package/src/modules/channel_ses/capabilities.ts

@@ -0,0 +1,8 @@
+import { baseEmailCapabilities } from '@open-mercato/core/modules/communication_channels/lib/email-capabilities'
+import type { ChannelCapabilities } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+export const sesCapabilities: ChannelCapabilities = {
+  ...baseEmailCapabilities,
+  fileSharing: false,
+  conversationHistory: false,
+}

package/src/modules/channel_ses/di.ts

@@ -0,0 +1,20 @@
+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 { getSesChannelAdapter } from './lib/adapter'
+import { registerSesSystemEmailConfigResolver } from './lib/system-email-config'
+import { channelSesHealthCheck } from './lib/health'
+
+export function register(container: AppContainer): void {
+  registerSesSystemEmailConfigResolver()
+  if (!hasChannelAdapter('ses')) {
+    registerChannelAdapter(getSesChannelAdapter())
+  }
+  container.register({
+    channelSesAdapter: asValue(getSesChannelAdapter()),
+    channelSesHealthCheck: asValue(channelSesHealthCheck),
+  })
+}

package/src/modules/channel_ses/index.ts

@@ -0,0 +1,9 @@
+export const metadata = {
+  id: 'channel_ses',
+  name: 'Amazon SES Email Channel',
+  description: 'Outbound Amazon SES email channel provider for the Communications Hub.',
+  version: '0.1.0',
+  requires: ['communication_channels', 'integrations'],
+}
+
+export default metadata

package/src/modules/channel_ses/integration.ts

@@ -0,0 +1,64 @@
+import { buildIntegrationDetailWidgetSpotId, type IntegrationBundle, type IntegrationDefinition } from '@open-mercato/shared/modules/integrations/types'
+
+export const channelSesDetailWidgetSpotId = buildIntegrationDetailWidgetSpotId('channel_ses')
+
+export const integration: IntegrationDefinition = {
+  id: 'channel_ses',
+  title: 'Amazon SES',
+  description: 'Send transactional email through Amazon SES using the Communications Hub.',
+  category: 'communication',
+  hub: 'communication_channels',
+  providerKey: 'ses',
+  icon: 'mail',
+  docsUrl: 'https://docs.aws.amazon.com/ses/',
+  package: '@open-mercato/channel-ses',
+  version: '0.1.0',
+  author: 'Open Mercato Team',
+  company: 'Open Mercato',
+  license: 'MIT',
+  tags: ['email', 'aws', 'ses', 'transactional', 'communication'],
+  detailPage: {
+    widgetSpotId: channelSesDetailWidgetSpotId,
+  },
+  apiVersions: [
+    {
+      id: 'sesv2',
+      label: 'Amazon SES v2',
+      status: 'stable',
+      default: true,
+      changelog: 'Initial outbound transactional email adapter.',
+    },
+  ],
+  healthCheck: { service: 'channelSesHealthCheck' },
+  credentials: {
+    fields: [
+      {
+        key: 'region',
+        label: 'AWS region',
+        type: 'text',
+        required: true,
+        placeholder: 'eu-west-2',
+        helpText: 'SES region used for this tenant connection.',
+      },
+      {
+        key: 'fromAddress',
+        label: 'From address',
+        type: 'text',
+        required: true,
+        placeholder: 'no-reply@example.com',
+        helpText: 'Verified SES sender address or domain identity.',
+      },
+      {
+        key: 'configurationSetName',
+        label: 'Configuration set',
+        type: 'text',
+        required: false,
+        helpText: 'Optional SES configuration set name.',
+      },
+    ],
+  },
+}
+
+export const integrations: IntegrationDefinition[] = [integration]
+export const bundles: IntegrationBundle[] = []
+export const bundle: IntegrationBundle | undefined = undefined

package/src/modules/channel_ses/lib/__tests__/adapter.test.ts

@@ -0,0 +1,94 @@
+import { getSesChannelAdapter } from '../adapter'
+
+var sendMailMock: jest.Mock
+var createTransportMock: jest.Mock
+var SESv2ClientMock: jest.Mock
+var SendEmailCommandMock: jest.Mock
+
+jest.mock('nodemailer', () => {
+  sendMailMock = jest.fn().mockResolvedValue({ messageId: 'ses-1', response: 'ok' })
+  createTransportMock = jest.fn().mockReturnValue({ sendMail: sendMailMock })
+  return { __esModule: true, default: { createTransport: createTransportMock } }
+})
+
+jest.mock('@aws-sdk/client-sesv2', () => {
+  SESv2ClientMock = jest.fn()
+  SendEmailCommandMock = jest.fn()
+  return {
+    SESv2Client: SESv2ClientMock,
+    SendEmailCommand: SendEmailCommandMock,
+  }
+})
+
+describe('SesChannelAdapter', () => {
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    process.env = { ...originalEnv }
+    sendMailMock.mockClear()
+    createTransportMock.mockClear()
+    SESv2ClientMock.mockClear()
+    SendEmailCommandMock.mockClear()
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+  })
+
+  it('sends html email through Nodemailer SES transport', async () => {
+    const adapter = getSesChannelAdapter()
+    const converted = await adapter.convertOutbound({
+      body: '<p>Hello</p>',
+      bodyFormat: 'html',
+      channelMetadata: {
+        to: 'user@example.com',
+        subject: 'Hello',
+        from: 'from@example.com',
+        replyTo: 'reply@example.com',
+        attachments: [{ filename: 'a.txt', content: 'dGVzdA==', contentType: 'text/plain' }],
+      },
+    })
+
+    const result = await adapter.sendMessage({
+      content: converted.content,
+      credentials: {
+        region: 'eu-west-2',
+        fromAddress: 'fallback@example.com',
+        configurationSetName: 'default',
+      },
+      scope: { tenantId: 'tenant', organizationId: 'org' },
+      metadata: converted.metadata,
+    })
+
+    expect(result).toEqual(expect.objectContaining({ status: 'sent', externalMessageId: 'ses-1' }))
+    expect(SESv2ClientMock).toHaveBeenCalledWith({ region: 'eu-west-2' })
+    expect(createTransportMock).toHaveBeenCalledWith(expect.objectContaining({ SES: expect.any(Object) }))
+    expect(sendMailMock).toHaveBeenCalledWith(expect.objectContaining({
+      from: 'from@example.com',
+      to: ['user@example.com'],
+      subject: 'Hello',
+      html: '<p>Hello</p>',
+      text: 'Hello',
+      replyTo: 'reply@example.com',
+      attachments: [{ filename: 'a.txt', content: 'dGVzdA==', encoding: 'base64', contentType: 'text/plain' }],
+      ses: { ConfigurationSetName: 'default' },
+    }))
+  })
+
+  it('returns a failed result when the SES transport rejects', async () => {
+    sendMailMock.mockRejectedValueOnce(new Error('temporary outage'))
+    const adapter = getSesChannelAdapter()
+
+    const result = await adapter.sendMessage({
+      content: { text: 'Hello' },
+      credentials: { region: 'eu-west-2', fromAddress: 'from@example.com' },
+      scope: { tenantId: 'tenant', organizationId: 'org' },
+      metadata: { to: ['user@example.com'], subject: 'Hello' },
+    })
+
+    expect(result).toEqual(expect.objectContaining({
+      status: 'failed',
+      error: 'SES_SEND_FAILED: temporary outage',
+    }))
+  })
+})

package/src/modules/channel_ses/lib/__tests__/health.test.ts

@@ -0,0 +1,51 @@
+import { channelSesHealthCheck } from '../health'
+
+var sendMock: jest.Mock
+var destroyMock: jest.Mock
+var SESv2ClientMock: jest.Mock
+var GetAccountCommandMock: jest.Mock
+
+jest.mock('@aws-sdk/client-sesv2', () => {
+  sendMock = jest.fn().mockResolvedValue({ ProductionAccessEnabled: true, SendingEnabled: true })
+  destroyMock = jest.fn()
+  SESv2ClientMock = jest.fn().mockImplementation(() => ({ send: sendMock, destroy: destroyMock }))
+  GetAccountCommandMock = jest.fn()
+  return { SESv2Client: SESv2ClientMock, GetAccountCommand: GetAccountCommandMock }
+})
+
+describe('channelSesHealthCheck', () => {
+  beforeEach(() => {
+    sendMock.mockClear()
+    destroyMock.mockClear()
+    SESv2ClientMock.mockClear()
+    GetAccountCommandMock.mockClear()
+  })
+
+  it('performs a bounded GetAccount probe and closes the client', async () => {
+    const result = await channelSesHealthCheck.check(
+      { region: 'eu-west-2', fromAddress: 'from@example.com' },
+      { tenantId: 'tenant-1', organizationId: 'organization-1' },
+    )
+
+    expect(result).toEqual(expect.objectContaining({ status: 'healthy' }))
+    expect(SESv2ClientMock).toHaveBeenCalledWith({ region: 'eu-west-2' })
+    expect(sendMock).toHaveBeenCalledWith(expect.anything(), {
+      abortSignal: expect.any(AbortSignal),
+    })
+    expect(destroyMock).toHaveBeenCalledTimes(1)
+  })
+
+  it('reports provider failures as unhealthy', async () => {
+    sendMock.mockRejectedValueOnce(new Error('access denied'))
+
+    const result = await channelSesHealthCheck.check(
+      { region: 'eu-west-2', fromAddress: 'from@example.com' },
+      { tenantId: 'tenant-1', organizationId: 'organization-1' },
+    )
+
+    expect(result).toEqual(expect.objectContaining({
+      status: 'unhealthy',
+      message: expect.stringContaining('access denied'),
+    }))
+  })
+})

package/src/modules/channel_ses/lib/__tests__/preset.test.ts

@@ -0,0 +1,184 @@
+import { findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { applySesEnvPreset, readSesEnvPreset } from '../preset'
+
+jest.mock('@open-mercato/shared/lib/encryption/find', () => ({
+  findOneWithDecryption: jest.fn(),
+}))
+
+const mockedFindOneWithDecryption = findOneWithDecryption as jest.MockedFunction<typeof findOneWithDecryption>
+
+function createContainer(overrides: { save?: jest.Mock; upsert?: jest.Mock } = {}) {
+  const save = overrides.save ?? jest.fn().mockResolvedValue(undefined)
+  const upsert = overrides.upsert ?? jest.fn().mockResolvedValue(undefined)
+  const container = {
+    resolve: (key: string) => (key === 'integrationStateService' ? { upsert } : { save }),
+  } as never
+  return { container, save, upsert }
+}
+
+describe('channel_ses env preset', () => {
+  const originalEnv = process.env
+
+  beforeEach(() => {
+    process.env = {
+      ...originalEnv,
+      SYSTEM_EMAIL_PROVIDER: 'ses',
+      AWS_SES_REGION: 'eu-west-2',
+      EMAIL_FROM: 'from@example.com',
+    }
+    mockedFindOneWithDecryption.mockReset()
+  })
+
+  afterEach(() => {
+    process.env = originalEnv
+  })
+
+  it('creates a tenant-scoped credential row and system channel', async () => {
+    mockedFindOneWithDecryption.mockResolvedValue(null)
+    const channel = { id: 'channel-1' }
+    const flush = jest.fn().mockResolvedValue(undefined)
+    const persist = jest.fn().mockReturnValue({ flush })
+    const em = { create: jest.fn().mockReturnValue(channel), persist }
+    const { container, save } = createContainer()
+
+    await applySesEnvPreset({
+      em: em as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })
+
+    expect(save).toHaveBeenCalledWith(
+      'channel_ses',
+      { region: 'eu-west-2', fromAddress: 'from@example.com' },
+      { tenantId: 'tenant-1', organizationId: 'organization-1', userId: null },
+    )
+    expect(em.create).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+      userId: null,
+      providerKey: 'ses',
+    }))
+    expect(persist).toHaveBeenCalledWith(channel)
+  })
+
+  it('enables the integration state so Integrations does not read Disabled while email is live', async () => {
+    mockedFindOneWithDecryption.mockResolvedValue(null)
+    const flush = jest.fn().mockResolvedValue(undefined)
+    const em = { create: jest.fn().mockReturnValue({ id: 'channel-1' }), persist: jest.fn().mockReturnValue({ flush }) }
+    const { container, upsert } = createContainer()
+
+    await applySesEnvPreset({
+      em: em as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })
+
+    expect(upsert).toHaveBeenCalledWith(
+      'channel_ses',
+      { isEnabled: true },
+      { tenantId: 'tenant-1', organizationId: 'organization-1' },
+    )
+  })
+
+  it('still seeds the system channel when the integration state cannot be written', async () => {
+    mockedFindOneWithDecryption.mockResolvedValue(null)
+    const channel = { id: 'channel-1' }
+    const flush = jest.fn().mockResolvedValue(undefined)
+    const persist = jest.fn().mockReturnValue({ flush })
+    const em = { create: jest.fn().mockReturnValue(channel), persist }
+    const { container } = createContainer({ upsert: jest.fn().mockRejectedValue(new Error('connection terminated')) })
+
+    await expect(applySesEnvPreset({
+      em: em as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })).resolves.toBeUndefined()
+
+    expect(persist).toHaveBeenCalledWith(channel)
+  })
+
+  it('reactivates the exactly scoped existing system channel', async () => {
+    const existing = { isActive: false, status: 'error', lastError: 'failed' }
+    mockedFindOneWithDecryption.mockResolvedValue(existing as never)
+    const flush = jest.fn().mockResolvedValue(undefined)
+    const em = { flush }
+
+    await applySesEnvPreset({
+      em: em as never,
+      container: createContainer().container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })
+
+    expect(mockedFindOneWithDecryption).toHaveBeenCalledWith(
+      em,
+      expect.anything(),
+      expect.objectContaining({ tenantId: 'tenant-1', organizationId: 'organization-1', userId: null }),
+      undefined,
+      { tenantId: 'tenant-1', organizationId: 'organization-1' },
+    )
+    expect(existing).toEqual(expect.objectContaining({ isActive: true, status: 'connected', lastError: null }))
+    expect(flush).toHaveBeenCalledTimes(1)
+  })
+
+  it('still completes tenant seeding when the channel row cannot be written', async () => {
+    mockedFindOneWithDecryption.mockRejectedValue(new Error('connection terminated'))
+    const { container, save } = createContainer()
+
+    await expect(applySesEnvPreset({
+      em: { flush: jest.fn() } as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })).resolves.toBeUndefined()
+
+    expect(save).toHaveBeenCalledTimes(1)
+  })
+
+  it('requires an explicit region and sender address', () => {
+    delete process.env.AWS_SES_REGION
+    delete process.env.AWS_REGION
+    expect(readSesEnvPreset()).toBeNull()
+  })
+
+  it('seeds nothing when another provider is selected, even with AWS_REGION set', async () => {
+    // `AWS_REGION` is set by every AWS runtime and ships uncommented in `.env.example` for vector
+    // search, so without the provider gate a Resend instance would get an Enabled SES integration
+    // and a connected SES channel it never configured.
+    process.env.SYSTEM_EMAIL_PROVIDER = 'resend'
+    delete process.env.AWS_SES_REGION
+    process.env.AWS_REGION = 'eu-central-1'
+    const em = { create: jest.fn(), persist: jest.fn(), flush: jest.fn() }
+    const { container, save, upsert } = createContainer()
+
+    await applySesEnvPreset({
+      em: em as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })
+
+    expect(save).not.toHaveBeenCalled()
+    expect(upsert).not.toHaveBeenCalled()
+    expect(em.create).not.toHaveBeenCalled()
+    expect(mockedFindOneWithDecryption).not.toHaveBeenCalled()
+  })
+
+  it('seeds nothing when no provider is selected, because the default is Resend', async () => {
+    delete process.env.SYSTEM_EMAIL_PROVIDER
+    const em = { create: jest.fn(), persist: jest.fn(), flush: jest.fn() }
+    const { container, save } = createContainer()
+
+    await applySesEnvPreset({
+      em: em as never,
+      container,
+      tenantId: 'tenant-1',
+      organizationId: 'organization-1',
+    })
+
+    expect(save).not.toHaveBeenCalled()
+  })
+})