@auriclabs/events 0.1.0

package/src/dispatch-event.test.ts

@@ -0,0 +1,226 @@
+const { mockGetEventService, mockGetHead, mockAppendEvent, mockGetEventContext, mockUlid } =
+  vi.hoisted(() => ({
+    mockGetEventService: vi.fn(),
+    mockGetHead: vi.fn(),
+    mockAppendEvent: vi.fn(),
+    mockGetEventContext: vi.fn(),
+    mockUlid: vi.fn(),
+  }));
+
+vi.mock('./init', () => ({
+  getEventService: mockGetEventService,
+}));
+
+vi.mock('./context', () => ({
+  getEventContext: mockGetEventContext,
+}));
+
+vi.mock('@auriclabs/api-core', () => ({
+  retry: vi.fn((fn: () => unknown) => fn()),
+}));
+
+vi.mock('@auriclabs/logger', () => ({
+  logger: { debug: vi.fn() },
+}));
+
+vi.mock('ulid', () => ({
+  ulid: mockUlid,
+}));
+
+import { dispatchEvent } from './dispatch-event';
+import { retry } from '@auriclabs/api-core';
+
+describe('dispatchEvent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetEventService.mockReturnValue({
+      getHead: mockGetHead,
+      appendEvent: mockAppendEvent,
+    });
+    mockGetEventContext.mockReturnValue({});
+    mockGetHead.mockResolvedValue(undefined);
+    mockAppendEvent.mockResolvedValue({ pk: 'AGG#test#1', sk: 'EVT#000000001', version: 1 });
+    mockUlid.mockReturnValue('01ARZ3NDEKTSV4RRFFQ69G5FAV');
+  });
+
+  it('generates eventId with ulid prefix when not provided', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        eventId: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('uses provided eventId when given', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+      eventId: 'custom-event-id',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        eventId: 'custom-event-id',
+      }),
+    );
+  });
+
+  it('uses provided idempotencyKey when given', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+      idempotencyKey: 'my-idem-key',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        idempotencyKey: 'my-idem-key',
+      }),
+    );
+  });
+
+  it('defaults idempotencyKey to eventId when not provided', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        idempotencyKey: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('reads head version before appending', async () => {
+    mockGetHead.mockResolvedValue({ currentVersion: 5 });
+
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderUpdated',
+    });
+
+    expect(mockGetHead).toHaveBeenCalledWith('order', 'o-1');
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        expectedVersion: 5,
+      }),
+    );
+  });
+
+  it('uses expectedVersion 0 when head does not exist', async () => {
+    mockGetHead.mockResolvedValue(undefined);
+
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        expectedVersion: 0,
+      }),
+    );
+  });
+
+  it('merges event context into append args', async () => {
+    mockGetEventContext.mockReturnValue({
+      correlationId: 'ctx-corr-1',
+      actorId: 'ctx-actor-1',
+    });
+
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'ctx-corr-1',
+        actorId: 'ctx-actor-1',
+      }),
+    );
+  });
+
+  it('event args override event context', async () => {
+    mockGetEventContext.mockReturnValue({
+      correlationId: 'ctx-corr',
+      actorId: 'ctx-actor',
+    });
+
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+      correlationId: 'event-corr',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'event-corr',
+        actorId: 'ctx-actor',
+      }),
+    );
+  });
+
+  it('calls retry wrapper', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(retry).toHaveBeenCalledTimes(1);
+    expect(retry).toHaveBeenCalledWith(expect.any(Function));
+  });
+
+  it('sets schemaVersion to 1', async () => {
+    await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(mockAppendEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        schemaVersion: 1,
+      }),
+    );
+  });
+
+  it('returns the appendEvent result', async () => {
+    const expected = { pk: 'AGG#order#o-1', sk: 'EVT#000000001', version: 1 };
+    mockAppendEvent.mockResolvedValue(expected);
+
+    const result = await dispatchEvent({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+    });
+
+    expect(result).toEqual(expected);
+  });
+});

package/src/dispatch-event.ts

@@ -0,0 +1,34 @@
+import { retry } from '@auriclabs/api-core';
+import { logger } from '@auriclabs/logger';
+import { ulid } from 'ulid';
+
+import { AppendArgs, AppendEventResult } from './event-service';
+import { getEventService } from './init';
+import { getEventContext } from './context';
+
+export type DispatchEventArgs = Omit<
+  AppendArgs,
+  'eventId' | 'expectedVersion' | 'schemaVersion' | 'occurredAt' | 'idempotencyKey'
+> &
+  Partial<Pick<AppendArgs, 'idempotencyKey' | 'eventId'>>;
+
+export const dispatchEvent = async (event: DispatchEventArgs): Promise<AppendEventResult> => {
+  const eventService = getEventService();
+  const eventId = event.eventId ?? `evt-${ulid()}`;
+  const occurredAt = new Date().toISOString();
+  const idempotencyKey = event.idempotencyKey ?? eventId;
+
+  return retry(async () => {
+    const head = await eventService.getHead(event.aggregateType, event.aggregateId);
+    logger.debug({ event }, 'Dispatching event');
+    return eventService.appendEvent({
+      ...getEventContext(),
+      ...event,
+      eventId,
+      expectedVersion: head?.currentVersion ?? 0,
+      schemaVersion: 1,
+      occurredAt,
+      idempotencyKey,
+    });
+  });
+};

package/src/dispatch-events.test.ts

@@ -0,0 +1,72 @@
+const { mockDispatchEvent } = vi.hoisted(() => ({
+  mockDispatchEvent: vi.fn(),
+}));
+
+vi.mock('./dispatch-event', () => ({
+  dispatchEvent: mockDispatchEvent,
+}));
+
+import { dispatchEvents } from './dispatch-events';
+
+describe('dispatchEvents', () => {
+  beforeEach(() => {
+    mockDispatchEvent.mockReset();
+    mockDispatchEvent.mockResolvedValue({ pk: 'pk', sk: 'sk', version: 1 });
+  });
+
+  it('dispatches events in parallel by default (Promise.all)', async () => {
+    const events = [
+      { aggregateType: 'order', aggregateId: '1', source: 'test', eventType: 'A' },
+      { aggregateType: 'order', aggregateId: '2', source: 'test', eventType: 'B' },
+      { aggregateType: 'order', aggregateId: '3', source: 'test', eventType: 'C' },
+    ];
+
+    await dispatchEvents(events);
+
+    expect(mockDispatchEvent).toHaveBeenCalledTimes(3);
+    expect(mockDispatchEvent).toHaveBeenCalledWith(events[0]);
+    expect(mockDispatchEvent).toHaveBeenCalledWith(events[1]);
+    expect(mockDispatchEvent).toHaveBeenCalledWith(events[2]);
+  });
+
+  it('dispatches events sequentially with inOrder: true', async () => {
+    const callOrder: number[] = [];
+    mockDispatchEvent.mockImplementation(async (event) => {
+      callOrder.push(event.aggregateId);
+      return { pk: 'pk', sk: 'sk', version: 1 };
+    });
+
+    const events = [
+      { aggregateType: 'order', aggregateId: '1', source: 'test', eventType: 'A' },
+      { aggregateType: 'order', aggregateId: '2', source: 'test', eventType: 'B' },
+      { aggregateType: 'order', aggregateId: '3', source: 'test', eventType: 'C' },
+    ];
+
+    await dispatchEvents(events, { inOrder: true });
+
+    expect(mockDispatchEvent).toHaveBeenCalledTimes(3);
+    expect(callOrder).toEqual(['1', '2', '3']);
+  });
+
+  it('handles empty events array', async () => {
+    await dispatchEvents([]);
+
+    expect(mockDispatchEvent).not.toHaveBeenCalled();
+  });
+
+  it('handles empty events array with inOrder: true', async () => {
+    await dispatchEvents([], { inOrder: true });
+
+    expect(mockDispatchEvent).not.toHaveBeenCalled();
+  });
+
+  it('defaults inOrder to false when options not provided', async () => {
+    const events = [
+      { aggregateType: 'order', aggregateId: '1', source: 'test', eventType: 'A' },
+    ];
+
+    await dispatchEvents(events);
+
+    expect(mockDispatchEvent).toHaveBeenCalledTimes(1);
+  });
+});

package/src/dispatch-events.ts

@@ -0,0 +1,18 @@
+import { dispatchEvent, DispatchEventArgs } from './dispatch-event';
+
+export interface DispatchEventsArgs {
+  inOrder?: boolean;
+}
+
+export const dispatchEvents = async (
+  events: DispatchEventArgs[],
+  { inOrder = false }: DispatchEventsArgs = {},
+) => {
+  if (inOrder) {
+    for (const event of events) {
+      await dispatchEvent(event);
+    }
+  } else {
+    await Promise.all(events.map((event) => dispatchEvent(event)));
+  }
+};

package/src/event-service.test.ts

@@ -0,0 +1,357 @@
+const { mockSend } = vi.hoisted(() => ({
+  mockSend: vi.fn(),
+}));
+
+vi.mock('@aws-sdk/client-dynamodb', () => ({
+  DynamoDBClient: vi.fn(),
+  ConditionalCheckFailedException: class ConditionalCheckFailedException extends Error {
+    constructor() {
+      super();
+      this.name = 'ConditionalCheckFailedException';
+    }
+  },
+}));
+
+vi.mock('@aws-sdk/lib-dynamodb', () => ({
+  DynamoDBDocumentClient: { from: () => ({ send: mockSend }) },
+  TransactWriteCommand: vi.fn((input: unknown) => ({ input, _type: 'TransactWrite' })),
+  GetCommand: vi.fn((input: unknown) => ({ input, _type: 'Get' })),
+  QueryCommand: vi.fn((input: unknown) => ({ input, _type: 'Query' })),
+}));
+
+vi.mock('@auriclabs/pagination', () => ({
+  normalizePaginationResponse: vi.fn((input: unknown) => input),
+}));
+
+import { createEventService } from './event-service';
+import { TransactWriteCommand, GetCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
+
+describe('event-service', () => {
+  const TABLE_NAME = 'test-events';
+
+  beforeEach(() => {
+    mockSend.mockReset();
+    vi.mocked(TransactWriteCommand).mockClear();
+    vi.mocked(GetCommand).mockClear();
+    vi.mocked(QueryCommand).mockClear();
+  });
+
+  describe('createEventService', () => {
+    it('returns an object with all expected methods', () => {
+      const service = createEventService(TABLE_NAME);
+      expect(service).toHaveProperty('appendEvent');
+      expect(service).toHaveProperty('getHead');
+      expect(service).toHaveProperty('getEvent');
+      expect(service).toHaveProperty('listEvents');
+    });
+  });
+
+  describe('appendEvent', () => {
+    it('sends TransactWriteCommand with correct table name and pk format', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({});
+
+      await service.appendEvent({
+        aggregateType: 'order',
+        aggregateId: 'order-123',
+        source: 'order-service',
+        expectedVersion: 0,
+        idempotencyKey: 'idem-key-1',
+        eventId: 'evt-abc',
+        eventType: 'OrderCreated',
+        payload: { total: 100 },
+      });
+
+      expect(TransactWriteCommand).toHaveBeenCalledTimes(1);
+      const cmdInput = vi.mocked(TransactWriteCommand).mock.calls[0][0];
+
+      // Check Update item (HEAD)
+      const updateItem = cmdInput.TransactItems![0].Update!;
+      expect(updateItem.TableName).toBe(TABLE_NAME);
+      expect(updateItem.Key).toEqual({ pk: 'AGG#order#order-123', sk: 'HEAD' });
+
+      // Check Put item (event)
+      const putItem = cmdInput.TransactItems![1].Put!;
+      expect(putItem.TableName).toBe(TABLE_NAME);
+      expect(putItem.Item!.pk).toBe('AGG#order#order-123');
+      expect(putItem.Item!.sk).toBe('EVT#000000001');
+      expect(putItem.Item!.itemType).toBe('event');
+      expect(putItem.Item!.eventType).toBe('OrderCreated');
+      expect(putItem.Item!.payload).toEqual({ total: 100 });
+      expect(putItem.Item!.version).toBe(1);
+      expect(putItem.Item!.source).toBe('order-service');
+      expect(putItem.Item!.schemaVersion).toBe(1);
+    });
+
+    it('pads version number to 9 digits', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({});
+
+      await service.appendEvent({
+        aggregateType: 'order',
+        aggregateId: '1',
+        source: 'test',
+        expectedVersion: 41,
+        idempotencyKey: 'k',
+        eventId: 'e',
+        eventType: 'T',
+      });
+
+      const cmdInput = vi.mocked(TransactWriteCommand).mock.calls[0][0];
+      const putItem = cmdInput.TransactItems![1].Put!;
+      expect(putItem.Item!.sk).toBe('EVT#000000042');
+      expect(putItem.Item!.version).toBe(42);
+    });
+
+    it('returns pk, sk, and version', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({});
+
+      const result = await service.appendEvent({
+        aggregateType: 'wallet',
+        aggregateId: 'w-1',
+        source: 'billing',
+        expectedVersion: 5,
+        idempotencyKey: 'key',
+        eventId: 'evt-1',
+        eventType: 'CreditAdded',
+      });
+
+      expect(result).toEqual({
+        pk: 'AGG#wallet#w-1',
+        sk: 'EVT#000000006',
+        version: 6,
+      });
+    });
+
+    it('uses provided occurredAt instead of generating one', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({});
+
+      await service.appendEvent({
+        aggregateType: 'order',
+        aggregateId: '1',
+        source: 'test',
+        expectedVersion: 0,
+        idempotencyKey: 'k',
+        eventId: 'e',
+        eventType: 'T',
+        occurredAt: '2025-01-01T00:00:00.000Z',
+      });
+
+      const cmdInput = vi.mocked(TransactWriteCommand).mock.calls[0][0];
+      const putItem = cmdInput.TransactItems![1].Put!;
+      expect(putItem.Item!.occurredAt).toBe('2025-01-01T00:00:00.000Z');
+    });
+
+    it('includes optional metadata fields', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({});
+
+      await service.appendEvent({
+        aggregateType: 'order',
+        aggregateId: '1',
+        source: 'test',
+        expectedVersion: 0,
+        idempotencyKey: 'k',
+        eventId: 'e',
+        eventType: 'T',
+        correlationId: 'corr-1',
+        causationId: 'cause-1',
+        actorId: 'user-1',
+        schemaVersion: 2,
+      });
+
+      const cmdInput = vi.mocked(TransactWriteCommand).mock.calls[0][0];
+      const putItem = cmdInput.TransactItems![1].Put!;
+      expect(putItem.Item!.correlationId).toBe('corr-1');
+      expect(putItem.Item!.causationId).toBe('cause-1');
+      expect(putItem.Item!.actorId).toBe('user-1');
+      expect(putItem.Item!.schemaVersion).toBe(2);
+    });
+
+    it('throws OCC error on ConditionalCheckFailedException', async () => {
+      const service = createEventService(TABLE_NAME);
+      const { ConditionalCheckFailedException } = await import('@aws-sdk/client-dynamodb');
+      mockSend.mockRejectedValue(new ConditionalCheckFailedException());
+
+      await expect(
+        service.appendEvent({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          expectedVersion: 3,
+          idempotencyKey: 'k',
+          eventId: 'e',
+          eventType: 'T',
+        }),
+      ).rejects.toThrow('OCC failed for aggregate order/o-1: expectedVersion=3');
+    });
+
+    it('re-throws non-OCC errors', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockRejectedValue(new Error('Network error'));
+
+      await expect(
+        service.appendEvent({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          expectedVersion: 0,
+          idempotencyKey: 'k',
+          eventId: 'e',
+          eventType: 'T',
+        }),
+      ).rejects.toThrow('Network error');
+    });
+  });
+
+  describe('getHead', () => {
+    it('sends GetCommand with correct pk and sk=HEAD', async () => {
+      const service = createEventService(TABLE_NAME);
+      const head = { pk: 'AGG#order#o-1', sk: 'HEAD', currentVersion: 5 };
+      mockSend.mockResolvedValue({ Item: head });
+
+      const result = await service.getHead('order', 'o-1');
+
+      expect(GetCommand).toHaveBeenCalledWith({
+        TableName: TABLE_NAME,
+        Key: { pk: 'AGG#order#o-1', sk: 'HEAD' },
+      });
+      expect(result).toEqual(head);
+    });
+
+    it('returns undefined when no head exists', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Item: undefined });
+
+      const result = await service.getHead('order', 'nonexistent');
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('getEvent', () => {
+    it('sends GetCommand with correct pk and padded version sk', async () => {
+      const service = createEventService(TABLE_NAME);
+      const event = { pk: 'AGG#order#o-1', sk: 'EVT#000000003', eventType: 'OrderCreated' };
+      mockSend.mockResolvedValue({ Item: event });
+
+      const result = await service.getEvent('order', 'o-1', 3);
+
+      expect(GetCommand).toHaveBeenCalledWith({
+        TableName: TABLE_NAME,
+        Key: { pk: 'AGG#order#o-1', sk: 'EVT#000000003' },
+      });
+      expect(result).toEqual(event);
+    });
+
+    it('returns undefined when event does not exist', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Item: undefined });
+
+      const result = await service.getEvent('order', 'o-1', 999);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('listEvents', () => {
+    it('sends QueryCommand with default range when no bounds specified', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Items: [], LastEvaluatedKey: undefined });
+
+      await service.listEvents({ aggregateType: 'order', aggregateId: 'o-1' });
+
+      expect(QueryCommand).toHaveBeenCalledWith({
+        TableName: TABLE_NAME,
+        KeyConditionExpression: 'pk = :pk AND sk BETWEEN :from AND :to',
+        ExpressionAttributeValues: {
+          ':pk': 'AGG#order#o-1',
+          ':from': 'EVT#000000000',
+          ':to': 'EVT#999999999',
+        },
+        ScanIndexForward: true,
+        Limit: undefined,
+      });
+    });
+
+    it('respects fromVersionExclusive', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Items: [], LastEvaluatedKey: undefined });
+
+      await service.listEvents({
+        aggregateType: 'order',
+        aggregateId: 'o-1',
+        fromVersionExclusive: 5,
+      });
+
+      const cmdInput = vi.mocked(QueryCommand).mock.calls[0][0];
+      // fromVersionExclusive=5 means start from version 6
+      expect(cmdInput.ExpressionAttributeValues![':from']).toBe('EVT#000000006');
+    });
+
+    it('respects toVersionInclusive', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Items: [], LastEvaluatedKey: undefined });
+
+      await service.listEvents({
+        aggregateType: 'order',
+        aggregateId: 'o-1',
+        toVersionInclusive: 10,
+      });
+
+      const cmdInput = vi.mocked(QueryCommand).mock.calls[0][0];
+      expect(cmdInput.ExpressionAttributeValues![':to']).toBe('EVT#000000010');
+    });
+
+    it('respects limit parameter', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Items: [], LastEvaluatedKey: undefined });
+
+      await service.listEvents({
+        aggregateType: 'order',
+        aggregateId: 'o-1',
+        limit: 25,
+      });
+
+      const cmdInput = vi.mocked(QueryCommand).mock.calls[0][0];
+      expect(cmdInput.Limit).toBe(25);
+    });
+
+    it('returns items from query result', async () => {
+      const service = createEventService(TABLE_NAME);
+      const events = [
+        { pk: 'AGG#order#o-1', sk: 'EVT#000000001', eventType: 'OrderCreated' },
+        { pk: 'AGG#order#o-1', sk: 'EVT#000000002', eventType: 'OrderUpdated' },
+      ];
+      mockSend.mockResolvedValue({ Items: events, LastEvaluatedKey: undefined });
+
+      const result = await service.listEvents({ aggregateType: 'order', aggregateId: 'o-1' });
+
+      expect(result).toEqual({ data: events, cursor: undefined });
+    });
+
+    it('extracts cursor from LastEvaluatedKey sk', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({
+        Items: [{ pk: 'AGG#order#o-1', sk: 'EVT#000000001' }],
+        LastEvaluatedKey: { pk: 'AGG#order#o-1', sk: 'EVT#000000001' },
+      });
+
+      const result = await service.listEvents({ aggregateType: 'order', aggregateId: 'o-1' });
+
+      expect(result).toEqual({
+        data: [{ pk: 'AGG#order#o-1', sk: 'EVT#000000001' }],
+        cursor: 'EVT#000000001',
+      });
+    });
+
+    it('returns empty data array when Items is undefined', async () => {
+      const service = createEventService(TABLE_NAME);
+      mockSend.mockResolvedValue({ Items: undefined, LastEvaluatedKey: undefined });
+
+      const result = await service.listEvents({ aggregateType: 'order', aggregateId: 'o-1' });
+
+      expect(result).toEqual({ data: [], cursor: undefined });
+    });
+  });
+});