sh-mcp/packages/gmail/test/gmail.test.ts

/**
 * Unit tests for @sh-mcp/gmail.
 *
 * The GmailClient is fully mocked — no real network calls, no Google SDK
 * imported at test time.  A mock AuthContext is passed to each handler.
 *
 * Coverage:
 *   - Happy path: search returns results / thread returns messages
 *   - Empty result: client returns []
 *   - Scope error: handler called with wrong scope throws ScopeError
 *   - Client error: underlying client rejects with a transient error
 *   - Throttle / retry: client rejects with a 429-style error
 *   - Redaction: sensitive values in snippets/bodies are masked
 *   - maxResults cap: enforced at 50 regardless of caller input
 */

import { describe, it, expect, vi, beforeEach } from 'vitest';
import type { GmailClient, EmailMessage, EmailThread } from '../src/client.js';
import { makeSearchInboxTool, makeGetEmailThreadDetailTool } from '../src/tools.js';
import type { AuthContext } from '@sh-mcp/shared';
import { ScopeError } from '@sh-mcp/shared';

// ---------------------------------------------------------------------------
// Mock helpers
// ---------------------------------------------------------------------------

function mockAuthContext(overrides?: Partial<AuthContext>): AuthContext {
  return {
    sub: 'lauren@seahavenind.com',
    scopes: ['gmail:self', 'ops:read'],
    aud: 'sh-mcp-ops',
    ...overrides,
  };
}

function mockEmailMessage(overrides?: Partial<EmailMessage>): EmailMessage {
  return {
    id: 'msg_001',
    threadId: 'thread_001',
    subject: 'Invoice from ACME Corp',
    from: 'billing@acme.com',
    to: 'lauren@seahavenind.com',
    date: '2026-06-01T10:00:00Z',
    snippet: 'Please find the invoice attached.',
    ...overrides,
  };
}

function mockEmailThread(overrides?: Partial<EmailThread>): EmailThread {
  return {
    threadId: 'thread_001',
    subject: 'Invoice from ACME Corp',
    messages: [
      {
        id: 'msg_001',
        from: 'billing@acme.com',
        to: 'lauren@seahavenind.com',
        date: '2026-06-01T10:00:00Z',
        body: 'Please find the invoice attached. Total due: $1,500.',
      },
      {
        id: 'msg_002',
        from: 'lauren@seahavenind.com',
        to: 'billing@acme.com',
        date: '2026-06-02T09:00:00Z',
        body: 'Thank you, received.',
      },
    ],
    ...overrides,
  };
}

function makeMockClient(): GmailClient {
  return {
    searchInbox: vi.fn(),
    getThreadDetail: vi.fn(),
  };
}

// ---------------------------------------------------------------------------
// search_inbox
// ---------------------------------------------------------------------------

describe('search_inbox', () => {
  let client: GmailClient;

  beforeEach(() => {
    client = makeMockClient();
  });

  it('happy path — returns matched messages', async () => {
    const messages = [mockEmailMessage(), mockEmailMessage({ id: 'msg_002', threadId: 'thread_002' })];
    vi.mocked(client.searchInbox).mockResolvedValueOnce(messages);

    const tool = makeSearchInboxTool(client);
    const result = await tool.handler(
      { query: 'from:billing@acme.com subject:invoice' },
      mockAuthContext(),
    );

    expect(result.totalReturned).toBe(2);
    expect(result.messages).toHaveLength(2);
    expect(result.messages[0].id).toBe('msg_001');
    expect(result.messages[0].subject).toBe('Invoice from ACME Corp');
    expect(vi.mocked(client.searchInbox)).toHaveBeenCalledWith({
      query: 'from:billing@acme.com subject:invoice',
      maxResults: 10,
      userSub: 'lauren@seahavenind.com',
    });
  });

  it('respects custom maxResults', async () => {
    vi.mocked(client.searchInbox).mockResolvedValueOnce([]);
    const tool = makeSearchInboxTool(client);
    await tool.handler({ query: 'is:unread', maxResults: 25 }, mockAuthContext());

    expect(vi.mocked(client.searchInbox)).toHaveBeenCalledWith(
      expect.objectContaining({ maxResults: 25 }),
    );
  });

  it('caps maxResults at 50 even when caller requests more', async () => {
    vi.mocked(client.searchInbox).mockResolvedValueOnce([]);
    const tool = makeSearchInboxTool(client);
    await tool.handler({ query: 'is:unread', maxResults: 999 }, mockAuthContext());

    expect(vi.mocked(client.searchInbox)).toHaveBeenCalledWith(
      expect.objectContaining({ maxResults: 50 }),
    );
  });

  it('empty result — returns empty array', async () => {
    vi.mocked(client.searchInbox).mockResolvedValueOnce([]);
    const tool = makeSearchInboxTool(client);
    const result = await tool.handler({ query: 'subject:nonexistent' }, mockAuthContext());

    expect(result.messages).toEqual([]);
    expect(result.totalReturned).toBe(0);
  });

  it('throws ScopeError when gmail:self scope is missing', async () => {
    const tool = makeSearchInboxTool(client);
    const ctx = mockAuthContext({ scopes: ['ops:read'] });

    await expect(tool.handler({ query: 'test' }, ctx)).rejects.toThrow(ScopeError);
    expect(vi.mocked(client.searchInbox)).not.toHaveBeenCalled();
  });

  it('propagates client error', async () => {
    vi.mocked(client.searchInbox).mockRejectedValueOnce(new Error('Gmail API unavailable'));
    const tool = makeSearchInboxTool(client);

    await expect(
      tool.handler({ query: 'test' }, mockAuthContext()),
    ).rejects.toThrow('Gmail API unavailable');
  });

  it('propagates throttle / 429-style error', async () => {
    const throttleError = Object.assign(new Error('Rate limit exceeded'), { code: 429 });
    vi.mocked(client.searchInbox).mockRejectedValueOnce(throttleError);
    const tool = makeSearchInboxTool(client);

    const err = await tool.handler({ query: 'test' }, mockAuthContext()).catch((e: unknown) => e);
    expect(err).toBeInstanceOf(Error);
    expect((err as NodeJS.ErrnoException & { code?: number }).code).toBe(429);
  });

  it('redacts sensitive values in snippets and subjects', async () => {
    const sensitiveMessage = mockEmailMessage({
      subject: 'Wire details: routing 021000021 account 1234567890',
      snippet: 'SSN 123-45-6789 card 4111111111111111',
    });
    vi.mocked(client.searchInbox).mockResolvedValueOnce([sensitiveMessage]);

    const tool = makeSearchInboxTool(client);
    const result = await tool.handler({ query: 'test' }, mockAuthContext());

    // Sensitive patterns must not appear in the output.
    expect(result.messages[0].subject).not.toContain('021000021');
    expect(result.messages[0].snippet).not.toContain('123-45-6789');
    expect(result.messages[0].snippet).not.toContain('4111111111111111');
  });

  it('passes the calling user sub to the client (never reads another mailbox)', async () => {
    vi.mocked(client.searchInbox).mockResolvedValueOnce([]);
    const tool = makeSearchInboxTool(client);
    const ctx = mockAuthContext({ sub: 'adam@seahavenind.com' });
    await tool.handler({ query: 'test' }, ctx);

    expect(vi.mocked(client.searchInbox)).toHaveBeenCalledWith(
      expect.objectContaining({ userSub: 'adam@seahavenind.com' }),
    );
  });
});

// ---------------------------------------------------------------------------
// get_email_thread_detail
// ---------------------------------------------------------------------------

describe('get_email_thread_detail', () => {
  let client: GmailClient;

  beforeEach(() => {
    client = makeMockClient();
  });

  it('happy path — returns full thread', async () => {
    const thread = mockEmailThread();
    vi.mocked(client.getThreadDetail).mockResolvedValueOnce(thread);

    const tool = makeGetEmailThreadDetailTool(client);
    const result = await tool.handler({ threadId: 'thread_001' }, mockAuthContext());

    expect(result.threadId).toBe('thread_001');
    expect(result.subject).toBe('Invoice from ACME Corp');
    expect(result.messageCount).toBe(2);
    expect(result.messages).toHaveLength(2);
    expect(result.messages[0].body).toContain('Total due');
    expect(vi.mocked(client.getThreadDetail)).toHaveBeenCalledWith({
      threadId: 'thread_001',
      userSub: 'lauren@seahavenind.com',
    });
  });

  it('empty thread — returns zero messages', async () => {
    vi.mocked(client.getThreadDetail).mockResolvedValueOnce(
      mockEmailThread({ messages: [] }),
    );
    const tool = makeGetEmailThreadDetailTool(client);
    const result = await tool.handler({ threadId: 'thread_empty' }, mockAuthContext());

    expect(result.messages).toEqual([]);
    expect(result.messageCount).toBe(0);
  });

  it('throws ScopeError when gmail:self scope is missing', async () => {
    const tool = makeGetEmailThreadDetailTool(client);
    const ctx = mockAuthContext({ scopes: ['ops:read', 'ops:tasks'] });

    await expect(tool.handler({ threadId: 'thread_001' }, ctx)).rejects.toThrow(ScopeError);
    expect(vi.mocked(client.getThreadDetail)).not.toHaveBeenCalled();
  });

  it('propagates client error', async () => {
    vi.mocked(client.getThreadDetail).mockRejectedValueOnce(new Error('Thread not found'));
    const tool = makeGetEmailThreadDetailTool(client);

    await expect(
      tool.handler({ threadId: 'thread_001' }, mockAuthContext()),
    ).rejects.toThrow('Thread not found');
  });

  it('propagates throttle / 429-style error', async () => {
    const throttleError = Object.assign(new Error('Quota exceeded'), { code: 429, retryAfter: 5 });
    vi.mocked(client.getThreadDetail).mockRejectedValueOnce(throttleError);
    const tool = makeGetEmailThreadDetailTool(client);

    const err = await tool
      .handler({ threadId: 'thread_001' }, mockAuthContext())
      .catch((e: unknown) => e);
    expect(err).toBeInstanceOf(Error);
    expect((err as NodeJS.ErrnoException & { code?: number }).code).toBe(429);
  });

  it('redacts sensitive values in message bodies and subject', async () => {
    const sensitiveThread = mockEmailThread({
      subject: 'ACH routing 021000021',
      messages: [
        {
          id: 'msg_s1',
          from: 'billing@acme.com',
          to: 'lauren@seahavenind.com',
          date: '2026-06-01T10:00:00Z',
          body: 'Account number 9876543210 routing 021000021 SSN 987-65-4321',
        },
      ],
    });
    vi.mocked(client.getThreadDetail).mockResolvedValueOnce(sensitiveThread);

    const tool = makeGetEmailThreadDetailTool(client);
    const result = await tool.handler({ threadId: 'thread_sensitive' }, mockAuthContext());

    expect(result.subject).not.toContain('021000021');
    expect(result.messages[0].body).not.toContain('9876543210');
    expect(result.messages[0].body).not.toContain('021000021');
    expect(result.messages[0].body).not.toContain('987-65-4321');
  });

  it('passes the calling user sub to the client (never reads another mailbox)', async () => {
    vi.mocked(client.getThreadDetail).mockResolvedValueOnce(mockEmailThread());
    const tool = makeGetEmailThreadDetailTool(client);
    const ctx = mockAuthContext({ sub: 'adam@seahavenind.com' });
    await tool.handler({ threadId: 'thread_001' }, ctx);

    expect(vi.mocked(client.getThreadDetail)).toHaveBeenCalledWith(
      expect.objectContaining({ userSub: 'adam@seahavenind.com' }),
    );
  });

  it('tool metadata is correct', () => {
    const tool = makeGetEmailThreadDetailTool(client);
    expect(tool.name).toBe('get_email_thread_detail');
    expect(tool.tier).toBe('ops');
    expect(tool.requiredScope).toBe('gmail:self');
  });

  it('search_inbox tool metadata is correct', () => {
    const tool = makeSearchInboxTool(client);
    expect(tool.name).toBe('search_inbox');
    expect(tool.tier).toBe('ops');
    expect(tool.requiredScope).toBe('gmail:self');
  });
});