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

/**
 * Unit tests for @sh-mcp/payments tools.
 *
 * All tests use:
 *   - A mock AuthContext with finance:read scope (unless testing scope rejection).
 *   - A mock PaymentsClient — no real DynamoDB or AWS calls.
 *
 * Coverage targets:
 *   - Happy path for each tool
 *   - Empty result set
 *   - Client error propagation
 *   - Throttle / retry simulation (transient error then success)
 *   - Scope enforcement: missing scope throws ScopeError
 *   - Redaction: bank account, routing, card numbers are masked; vendor names are not
 */

import { describe, it, expect, vi, beforeEach } from 'vitest';
import type { AuthContext } from '@sh-mcp/shared';
import { requireScope } from '@sh-mcp/shared';
import type { PaymentsClient, Payment } from '../src/client.js';
import {
  makeLookupByVendorTool,
  makeLookupByInvoiceTool,
  makeLookupByCheckTool,
} from '../src/tools.js';

// ---------------------------------------------------------------------------
// Shared test fixtures
// ---------------------------------------------------------------------------

/** A fully-scoped finance context — happy-path default. */
const financeCtx: AuthContext = {
  sub: 'adam@seahavenind.com',
  scopes: ['finance:read'],
  aud: 'sh-mcp-finance',
};

/** A context that lacks finance:read — for scope-rejection tests. */
const opsOnlyCtx: AuthContext = {
  sub: 'staff@seahavenind.com',
  scopes: ['ops:read'],
  aud: 'sh-mcp-ops',
};

const samplePayment: Payment = {
  paymentId: 'pmt-001',
  vendor: 'Acme Electrical Supply',
  vendorContact: 'billing@acme.example.com',
  amount: 4250.0,
  currency: 'USD',
  invoiceNumber: 'INV-2026-0042',
  checkNumber: '10412',
  paymentDate: '2026-05-15',
  status: 'cleared',
  bankAccountNumber: '123456789',
  bankRoutingNumber: '021000021',
  cardNumber: '4111111111111111',
  memo: 'Electrical supplies for Ronkonkoma site',
};

// ---------------------------------------------------------------------------
// Mock client builder
// ---------------------------------------------------------------------------

function makeMockClient(overrides?: Partial<PaymentsClient>): PaymentsClient {
  return {
    getByVendor: vi.fn().mockResolvedValue([samplePayment]),
    getByInvoice: vi.fn().mockResolvedValue([samplePayment]),
    getByCheck: vi.fn().mockResolvedValue([samplePayment]),
    ...overrides,
  };
}

// ---------------------------------------------------------------------------
// lookup_payment_by_vendor
// ---------------------------------------------------------------------------

describe('lookup_payment_by_vendor', () => {
  let client: PaymentsClient;

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

  it('returns payments and redacts sensitive fields on the happy path', async () => {
    const tool = makeLookupByVendorTool(client);
    const result = await tool.handler({ vendor: 'Acme' }, financeCtx);

    expect(result.count).toBe(1);
    expect(result.payments).toHaveLength(1);

    const p = result.payments[0]!;
    // Vendor name and contact must be intact.
    expect(p.vendor).toBe('Acme Electrical Supply');
    expect(p.vendorContact).toBe('billing@acme.example.com');

    // Sensitive fields must be redacted (not equal to the originals).
    expect(p.bankAccountNumber).not.toBe(samplePayment.bankAccountNumber);
    expect(p.bankRoutingNumber).not.toBe(samplePayment.bankRoutingNumber);
    expect(p.cardNumber).not.toBe(samplePayment.cardNumber);

    // Non-sensitive fields must be preserved.
    expect(p.amount).toBe(4250.0);
    expect(p.status).toBe('cleared');
    expect(p.paymentDate).toBe('2026-05-15');
  });

  it('forwards the vendor string and limit to the client', async () => {
    const tool = makeLookupByVendorTool(client);
    await tool.handler({ vendor: 'Acme', limit: 5 }, financeCtx);

    expect(client.getByVendor).toHaveBeenCalledWith('Acme', { limit: 5 });
  });

  it('caps limit at 100', async () => {
    const tool = makeLookupByVendorTool(client);
    await tool.handler({ vendor: 'Acme', limit: 9999 }, financeCtx);

    expect(client.getByVendor).toHaveBeenCalledWith('Acme', { limit: 100 });
  });

  it('returns empty result when the client returns no payments', async () => {
    client = makeMockClient({
      getByVendor: vi.fn().mockResolvedValue([]),
    });
    const tool = makeLookupByVendorTool(client);
    const result = await tool.handler({ vendor: 'Unknown Vendor' }, financeCtx);

    expect(result.count).toBe(0);
    expect(result.payments).toEqual([]);
  });

  it('propagates a client error', async () => {
    client = makeMockClient({
      getByVendor: vi.fn().mockRejectedValue(new Error('DynamoDB unavailable')),
    });
    const tool = makeLookupByVendorTool(client);

    await expect(tool.handler({ vendor: 'Acme' }, financeCtx)).rejects.toThrow(
      'DynamoDB unavailable',
    );
  });

  it('retries and succeeds after a transient throttle error', async () => {
    // Simulate a throttle on the first call, success on the second.
    const throttleError = Object.assign(new Error('ProvisionedThroughputExceededException'), {
      name: 'ProvisionedThroughputExceededException',
    });
    const getByVendor = vi
      .fn()
      .mockRejectedValueOnce(throttleError)
      .mockResolvedValueOnce([samplePayment]);

    client = makeMockClient({ getByVendor });

    // The tool itself does not implement retry logic — that is the
    // responsibility of the client implementation.  We verify here that
    // when the client internally retries and succeeds, the tool returns
    // the correct result.  We simulate this by wrapping the tool call
    // in a simple retry loop (as a client-layer retry would do).
    const tool = makeLookupByVendorTool(client);
    let result;
    for (let attempt = 0; attempt < 2; attempt++) {
      try {
        result = await tool.handler({ vendor: 'Acme' }, financeCtx);
        break;
      } catch {
        if (attempt === 1) throw new Error('Max retries exceeded');
      }
    }

    expect(result?.count).toBe(1);
    expect(getByVendor).toHaveBeenCalledTimes(2);
  });

  it('throws ScopeError when the caller lacks finance:read', async () => {
    const tool = makeLookupByVendorTool(client);

    await expect(tool.handler({ vendor: 'Acme' }, opsOnlyCtx)).rejects.toThrow();

    // Verify that the error comes from requireScope, not from the client.
    expect(client.getByVendor).not.toHaveBeenCalled();
  });

  it('has the correct tool metadata', () => {
    const tool = makeLookupByVendorTool(client);

    expect(tool.name).toBe('lookup_payment_by_vendor');
    expect(tool.tier).toBe('finance');
    expect(tool.requiredScope).toBe('finance:read');
  });
});

// ---------------------------------------------------------------------------
// lookup_payment_by_invoice
// ---------------------------------------------------------------------------

describe('lookup_payment_by_invoice', () => {
  let client: PaymentsClient;

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

  it('returns the matching payment with sensitive fields redacted', async () => {
    const tool = makeLookupByInvoiceTool(client);
    const result = await tool.handler({ invoiceNumber: 'INV-2026-0042' }, financeCtx);

    expect(result.count).toBe(1);
    const p = result.payments[0]!;
    expect(p.vendor).toBe('Acme Electrical Supply');
    expect(p.bankAccountNumber).not.toBe(samplePayment.bankAccountNumber);
    expect(p.bankRoutingNumber).not.toBe(samplePayment.bankRoutingNumber);
    expect(p.cardNumber).not.toBe(samplePayment.cardNumber);
  });

  it('forwards the invoice number to the client', async () => {
    const tool = makeLookupByInvoiceTool(client);
    await tool.handler({ invoiceNumber: 'INV-2026-0042' }, financeCtx);

    expect(client.getByInvoice).toHaveBeenCalledWith('INV-2026-0042');
  });

  it('returns empty result when invoice is not found', async () => {
    client = makeMockClient({
      getByInvoice: vi.fn().mockResolvedValue([]),
    });
    const tool = makeLookupByInvoiceTool(client);
    const result = await tool.handler({ invoiceNumber: 'INV-NOTFOUND' }, financeCtx);

    expect(result.count).toBe(0);
    expect(result.payments).toEqual([]);
  });

  it('propagates a client error', async () => {
    client = makeMockClient({
      getByInvoice: vi.fn().mockRejectedValue(new Error('Internal service error')),
    });
    const tool = makeLookupByInvoiceTool(client);

    await expect(tool.handler({ invoiceNumber: 'INV-2026-0042' }, financeCtx)).rejects.toThrow(
      'Internal service error',
    );
  });

  it('retries and succeeds after a transient throttle error', async () => {
    const throttleError = Object.assign(new Error('ProvisionedThroughputExceededException'), {
      name: 'ProvisionedThroughputExceededException',
    });
    const getByInvoice = vi
      .fn()
      .mockRejectedValueOnce(throttleError)
      .mockResolvedValueOnce([samplePayment]);

    client = makeMockClient({ getByInvoice });
    const tool = makeLookupByInvoiceTool(client);

    let result;
    for (let attempt = 0; attempt < 2; attempt++) {
      try {
        result = await tool.handler({ invoiceNumber: 'INV-2026-0042' }, financeCtx);
        break;
      } catch {
        if (attempt === 1) throw new Error('Max retries exceeded');
      }
    }

    expect(result?.count).toBe(1);
    expect(getByInvoice).toHaveBeenCalledTimes(2);
  });

  it('throws ScopeError when the caller lacks finance:read', async () => {
    const tool = makeLookupByInvoiceTool(client);

    await expect(tool.handler({ invoiceNumber: 'INV-2026-0042' }, opsOnlyCtx)).rejects.toThrow();

    expect(client.getByInvoice).not.toHaveBeenCalled();
  });

  it('has the correct tool metadata', () => {
    const tool = makeLookupByInvoiceTool(client);

    expect(tool.name).toBe('lookup_payment_by_invoice');
    expect(tool.tier).toBe('finance');
    expect(tool.requiredScope).toBe('finance:read');
  });
});

// ---------------------------------------------------------------------------
// lookup_payment_by_check
// ---------------------------------------------------------------------------

describe('lookup_payment_by_check', () => {
  let client: PaymentsClient;

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

  it('returns the matching payment with sensitive fields redacted', async () => {
    const tool = makeLookupByCheckTool(client);
    const result = await tool.handler({ checkNumber: '10412' }, financeCtx);

    expect(result.count).toBe(1);
    const p = result.payments[0]!;
    expect(p.vendor).toBe('Acme Electrical Supply');
    expect(p.bankAccountNumber).not.toBe(samplePayment.bankAccountNumber);
    expect(p.bankRoutingNumber).not.toBe(samplePayment.bankRoutingNumber);
    expect(p.cardNumber).not.toBe(samplePayment.cardNumber);
  });

  it('forwards the check number to the client', async () => {
    const tool = makeLookupByCheckTool(client);
    await tool.handler({ checkNumber: '10412' }, financeCtx);

    expect(client.getByCheck).toHaveBeenCalledWith('10412');
  });

  it('returns empty result when check number is not found', async () => {
    client = makeMockClient({
      getByCheck: vi.fn().mockResolvedValue([]),
    });
    const tool = makeLookupByCheckTool(client);
    const result = await tool.handler({ checkNumber: '99999' }, financeCtx);

    expect(result.count).toBe(0);
    expect(result.payments).toEqual([]);
  });

  it('propagates a client error', async () => {
    client = makeMockClient({
      getByCheck: vi.fn().mockRejectedValue(new Error('Connection timeout')),
    });
    const tool = makeLookupByCheckTool(client);

    await expect(tool.handler({ checkNumber: '10412' }, financeCtx)).rejects.toThrow(
      'Connection timeout',
    );
  });

  it('retries and succeeds after a transient throttle error', async () => {
    const throttleError = Object.assign(new Error('ProvisionedThroughputExceededException'), {
      name: 'ProvisionedThroughputExceededException',
    });
    const getByCheck = vi
      .fn()
      .mockRejectedValueOnce(throttleError)
      .mockResolvedValueOnce([samplePayment]);

    client = makeMockClient({ getByCheck });
    const tool = makeLookupByCheckTool(client);

    let result;
    for (let attempt = 0; attempt < 2; attempt++) {
      try {
        result = await tool.handler({ checkNumber: '10412' }, financeCtx);
        break;
      } catch {
        if (attempt === 1) throw new Error('Max retries exceeded');
      }
    }

    expect(result?.count).toBe(1);
    expect(getByCheck).toHaveBeenCalledTimes(2);
  });

  it('throws ScopeError when the caller lacks finance:read', async () => {
    const tool = makeLookupByCheckTool(client);

    await expect(tool.handler({ checkNumber: '10412' }, opsOnlyCtx)).rejects.toThrow();

    expect(client.getByCheck).not.toHaveBeenCalled();
  });

  it('has the correct tool metadata', () => {
    const tool = makeLookupByCheckTool(client);

    expect(tool.name).toBe('lookup_payment_by_check');
    expect(tool.tier).toBe('finance');
    expect(tool.requiredScope).toBe('finance:read');
  });
});

// ---------------------------------------------------------------------------
// Redaction contract — cross-cutting
// ---------------------------------------------------------------------------

describe('redaction contract', () => {
  it('does not redact vendor name or vendor contact', async () => {
    const client = makeMockClient();
    const tool = makeLookupByVendorTool(client);
    const result = await tool.handler({ vendor: 'Acme' }, financeCtx);

    const p = result.payments[0]!;
    expect(p.vendor).toBe('Acme Electrical Supply');
    expect(p.vendorContact).toBe('billing@acme.example.com');
  });

  it('redacts all three sensitive fields when present', async () => {
    const client = makeMockClient();
    const tool = makeLookupByVendorTool(client);
    const result = await tool.handler({ vendor: 'Acme' }, financeCtx);

    const p = result.payments[0]!;
    // None of the redacted values should equal the originals.
    expect(p.bankAccountNumber).not.toBe('123456789');
    expect(p.bankRoutingNumber).not.toBe('021000021');
    expect(p.cardNumber).not.toBe('4111111111111111');
  });

  it('omits redacted fields when they were undefined in the source', async () => {
    const minimalPayment: Payment = {
      paymentId: 'pmt-002',
      vendor: 'Generic Vendor',
      amount: 100,
      currency: 'USD',
      paymentDate: '2026-06-01',
      status: 'cleared',
      // No bankAccountNumber, bankRoutingNumber, or cardNumber
    };
    const client = makeMockClient({
      getByVendor: vi.fn().mockResolvedValue([minimalPayment]),
    });
    const tool = makeLookupByVendorTool(client);
    const result = await tool.handler({ vendor: 'Generic' }, financeCtx);

    const p = result.payments[0]!;
    expect(p.bankAccountNumber).toBeUndefined();
    expect(p.bankRoutingNumber).toBeUndefined();
    expect(p.cardNumber).toBeUndefined();
  });
});

// ---------------------------------------------------------------------------
// requireScope integration check
// ---------------------------------------------------------------------------

describe('requireScope integration', () => {
  it('requireScope does not throw when finance:read is present', () => {
    // Smoke-test the shared helper directly to confirm it accepts our fixture.
    expect(() => requireScope(financeCtx, 'finance:read')).not.toThrow();
  });

  it('requireScope throws when finance:read is absent', () => {
    expect(() => requireScope(opsOnlyCtx, 'finance:read')).toThrow();
  });
});