@open-kingdom/shared-backend-feature-email 0.0.2-7

package/src/lib/email.service.spec.ts

@@ -0,0 +1,52 @@
+import { Test } from '@nestjs/testing';
+import { EmailService } from './email.service.js';
+import { EMAIL_PROVIDER } from './email.types.js';
+
+describe('EmailService', () => {
+  let service: EmailService;
+  let mockProvider: { send: jest.Mock };
+
+  beforeEach(async () => {
+    mockProvider = { send: jest.fn() };
+
+    const module = await Test.createTestingModule({
+      providers: [
+        EmailService,
+        { provide: EMAIL_PROVIDER, useValue: mockProvider },
+      ],
+    }).compile();
+
+    service = module.get(EmailService);
+  });
+
+  it('sends email and returns success with message ID', async () => {
+    mockProvider.send.mockResolvedValue({ messageId: 'msg-123' });
+
+    const result = await service.send({
+      to: 'recipient@example.com',
+      subject: 'Test Subject',
+      body: 'Hello, this is a test.',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.messageId).toBe('msg-123');
+    expect(mockProvider.send).toHaveBeenCalledWith({
+      to: ['recipient@example.com'],
+      subject: 'Test Subject',
+      text: 'Hello, this is a test.',
+    });
+  });
+
+  it('returns error when email fails to send', async () => {
+    mockProvider.send.mockRejectedValue(new Error('SMTP connection failed'));
+
+    const result = await service.send({
+      to: 'recipient@example.com',
+      subject: 'Test',
+      body: 'Test body',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('SMTP connection failed');
+  });
+});

package/src/lib/email.service.ts

@@ -0,0 +1,24 @@
+import { Injectable, Inject } from '@nestjs/common';
+import { EMAIL_PROVIDER } from './email.types.js';
+import type { EmailProvider } from './email.types.js';
+import { SendEmailDto, SendEmailResponseDto } from './email.dto.js';
+
+@Injectable()
+export class EmailService {
+  constructor(
+    @Inject(EMAIL_PROVIDER) private readonly emailProvider: EmailProvider
+  ) {}
+
+  async send(dto: SendEmailDto): Promise<SendEmailResponseDto> {
+    try {
+      const result = await this.emailProvider.send({
+        to: [dto.to],
+        subject: dto.subject,
+        text: dto.body,
+      });
+      return { success: true, messageId: result.messageId };
+    } catch (error) {
+      return { success: false, error: (error as Error).message };
+    }
+  }
+}

package/src/lib/email.spec.ts

@@ -0,0 +1,30 @@
+// Mock dependencies before imports to avoid circular dependency issues
+jest.mock('./email.service.js', () => ({ EmailService: jest.fn() }));
+jest.mock('./email.controller.js', () => ({ EmailController: jest.fn() }));
+jest.mock('./providers/gmail.provider.js', () => ({
+  GmailProvider: jest.fn().mockImplementation(() => ({
+    send: jest.fn().mockResolvedValue({ messageId: 'test-123' }),
+  })),
+}));
+
+import { EmailModule } from './email.js';
+
+describe('EmailModule', () => {
+  const gmailConfig = {
+    clientEmail: 'test@example.com',
+    privateKey: '-----BEGIN PRIVATE KEY-----\ntest\n-----END PRIVATE KEY-----',
+    impersonateEmail: 'sender@example.com',
+  };
+
+  it('configures module with gmail provider', () => {
+    const result = EmailModule.forRoot({
+      provider: 'gmail',
+      config: gmailConfig,
+    });
+
+    expect(result.module).toBe(EmailModule);
+    expect(result.controllers).toHaveLength(1);
+    expect(result.providers).toHaveLength(2);
+    expect(result.exports).toHaveLength(1);
+  });
+});

package/src/lib/email.ts

@@ -0,0 +1,45 @@
+import { Module, DynamicModule } from '@nestjs/common';
+import {
+  GmailProvider,
+  GmailProviderConfig,
+} from './providers/gmail.provider.js';
+import { EmailService } from './email.service.js';
+import { EmailController } from './email.controller.js';
+import { EMAIL_PROVIDER } from './email.types.js';
+
+export { EMAIL_PROVIDER } from './email.types.js';
+export type {
+  EmailMessage,
+  EmailResult,
+  EmailProvider,
+} from './email.types.js';
+
+// Extensible for future providers
+export type EmailModuleOptions = {
+  provider: 'gmail';
+  config: GmailProviderConfig;
+};
+
+// Module
+@Module({})
+export class EmailModule {
+  static forRoot(options: EmailModuleOptions): DynamicModule {
+    return {
+      module: EmailModule,
+      controllers: [EmailController],
+      providers: [
+        {
+          provide: EMAIL_PROVIDER,
+          useFactory: () => {
+            switch (options.provider) {
+              case 'gmail':
+                return new GmailProvider(options.config);
+            }
+          },
+        },
+        EmailService,
+      ],
+      exports: [EmailService],
+    };
+  }
+}

package/src/lib/email.types.ts

@@ -0,0 +1,20 @@
+// Types
+export interface EmailMessage {
+  to: string[];
+  from?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+}
+
+export interface EmailResult {
+  messageId?: string;
+}
+
+// Provider interface
+export interface EmailProvider {
+  send(message: EmailMessage): Promise<EmailResult>;
+}
+
+// DI token
+export const EMAIL_PROVIDER = Symbol('EMAIL_PROVIDER');

package/src/lib/providers/gmail.provider.spec.ts

@@ -0,0 +1,142 @@
+import { GmailProvider, GmailProviderConfig } from './gmail.provider.js';
+
+// Mock @googleapis/gmail
+jest.mock('@googleapis/gmail', () => ({
+  gmail: jest.fn().mockReturnValue({
+    users: {
+      messages: {
+        send: jest.fn(),
+      },
+    },
+  }),
+  auth: {
+    JWT: jest.fn().mockImplementation(() => ({})),
+  },
+}));
+
+describe('GmailProvider', () => {
+  const config: GmailProviderConfig = {
+    clientEmail: 'test@project.iam.gserviceaccount.com',
+    privateKey: '-----BEGIN PRIVATE KEY-----\ntest\n-----END PRIVATE KEY-----',
+    impersonateEmail: 'sender@example.com',
+  };
+
+  let provider: GmailProvider;
+  let mockSend: jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    const { gmail } = jest.requireMock('@googleapis/gmail');
+    mockSend = gmail().users.messages.send;
+    provider = new GmailProvider(config);
+  });
+
+  describe('authentication', () => {
+    it('authenticates with gmail send scope', () => {
+      const { auth } = jest.requireMock('@googleapis/gmail');
+      expect(auth.JWT).toHaveBeenCalledWith({
+        email: config.clientEmail,
+        key: config.privateKey,
+        scopes: ['https://www.googleapis.com/auth/gmail.send'],
+        subject: config.impersonateEmail,
+      });
+    });
+
+    it('converts escaped newlines in private key', () => {
+      const escapedConfig: GmailProviderConfig = {
+        ...config,
+        privateKey:
+          '-----BEGIN PRIVATE KEY-----\\ntest\\n-----END PRIVATE KEY-----',
+      };
+      new GmailProvider(escapedConfig);
+
+      const { auth } = jest.requireMock('@googleapis/gmail');
+      expect(auth.JWT).toHaveBeenLastCalledWith(
+        expect.objectContaining({
+          key: '-----BEGIN PRIVATE KEY-----\ntest\n-----END PRIVATE KEY-----',
+        })
+      );
+    });
+  });
+
+  describe('sending emails', () => {
+    it('sends plain text email', async () => {
+      mockSend.mockResolvedValue({ data: { id: 'msg-123' } });
+
+      const result = await provider.send({
+        to: ['recipient@example.com'],
+        subject: 'Test Subject',
+        text: 'Hello World',
+      });
+
+      expect(result).toEqual({ messageId: 'msg-123' });
+    });
+
+    it('sends HTML email', async () => {
+      mockSend.mockResolvedValue({ data: { id: 'msg-456' } });
+
+      const result = await provider.send({
+        to: ['recipient@example.com'],
+        subject: 'Test Subject',
+        html: '<h1>Hello World</h1>',
+      });
+
+      expect(result).toEqual({ messageId: 'msg-456' });
+    });
+
+    it('sends to multiple recipients', async () => {
+      mockSend.mockResolvedValue({ data: { id: 'msg-102' } });
+
+      await provider.send({
+        to: ['first@example.com', 'second@example.com'],
+        subject: 'Test',
+        text: 'Hello',
+      });
+
+      const call = mockSend.mock.calls[0][0];
+      const rawDecoded = Buffer.from(call.requestBody.raw, 'base64').toString();
+      expect(rawDecoded).toContain('To: first@example.com, second@example.com');
+    });
+
+    it('uses impersonate email as default sender', async () => {
+      mockSend.mockResolvedValue({ data: { id: 'msg-789' } });
+
+      await provider.send({
+        to: ['recipient@example.com'],
+        subject: 'Test',
+        text: 'Hello',
+      });
+
+      const call = mockSend.mock.calls[0][0];
+      const rawDecoded = Buffer.from(call.requestBody.raw, 'base64').toString();
+      expect(rawDecoded).toContain(`From: ${config.impersonateEmail}`);
+    });
+
+    it('allows custom sender address', async () => {
+      mockSend.mockResolvedValue({ data: { id: 'msg-101' } });
+
+      await provider.send({
+        to: ['recipient@example.com'],
+        from: 'custom@example.com',
+        subject: 'Test',
+        text: 'Hello',
+      });
+
+      const call = mockSend.mock.calls[0][0];
+      const rawDecoded = Buffer.from(call.requestBody.raw, 'base64').toString();
+      expect(rawDecoded).toContain('From: custom@example.com');
+    });
+
+    it('confirms delivery when Gmail responds without full details', async () => {
+      mockSend.mockResolvedValue({ data: {} });
+
+      const result = await provider.send({
+        to: ['recipient@example.com'],
+        subject: 'Test',
+        text: 'Hello',
+      });
+
+      expect(result).toBeDefined();
+    });
+  });
+});

package/src/lib/providers/gmail.provider.ts

@@ -0,0 +1,63 @@
+import { gmail, auth } from '@googleapis/gmail';
+import { EmailMessage, EmailResult, EmailProvider } from '../email.js';
+
+export interface GmailProviderConfig {
+  clientEmail: string;
+  privateKey: string;
+  impersonateEmail: string;
+}
+
+export class GmailProvider implements EmailProvider {
+  private client: ReturnType<typeof gmail>;
+  private defaultFrom: string;
+
+  constructor(config: GmailProviderConfig) {
+    const jwt = new auth.JWT({
+      email: config.clientEmail,
+      key: config.privateKey.replace(/\\n/g, '\n'),
+      scopes: ['https://www.googleapis.com/auth/gmail.send'],
+      subject: config.impersonateEmail,
+    });
+
+    this.client = gmail({ version: 'v1', auth: jwt });
+    this.defaultFrom = config.impersonateEmail;
+  }
+
+  async send(message: EmailMessage): Promise<EmailResult> {
+    const raw = this.buildRawMessage(message);
+
+    const res = await this.client.users.messages.send({
+      userId: 'me',
+      requestBody: { raw },
+    });
+
+    return { messageId: res.data.id || undefined };
+  }
+
+  private buildRawMessage(message: EmailMessage): string {
+    const from = message.from || this.defaultFrom;
+    const to = message.to.join(', ');
+    const contentType = message.html ? 'text/html' : 'text/plain';
+    const body = message.html || message.text || '';
+
+    const headers = [
+      `From: ${from}`,
+      `To: ${to}`,
+      `Subject: ${message.subject}`,
+      'MIME-Version: 1.0',
+      `Content-Type: ${contentType}; charset=UTF-8`,
+    ].join('\r\n');
+
+    const rawMessage = `${headers}\r\n\r\n${body}`;
+
+    return this.toBase64Url(rawMessage);
+  }
+
+  private toBase64Url(str: string): string {
+    return Buffer.from(str)
+      .toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=+$/, '');
+  }
+}

package/src/lib/providers/index.ts

@@ -0,0 +1,2 @@
+export { GmailProvider } from './gmail.provider.js';
+export type { GmailProviderConfig } from './gmail.provider.js';

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "rootDir": "src",
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": false,
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "forceConsistentCasingInFileNames": true,
+    "types": ["node"],
+    "target": "es2021",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "strictBindCallApply": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src/**/*.ts"],
+  "references": [],
+  "exclude": [
+    "jest.config.ts",
+    "jest.config.cts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.ts"
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,22 @@
+{
+  "extends": "../../../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/jest",
+    "types": ["jest", "node"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "jest.config.ts",
+    "jest.config.cts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}