Merge pull request #8 from foundersandcoders/feature/ap-16-event-service-module

feat: add Event service module (Airtable CRUD)

Author: AlexVOiceover

README.md

@@ -120,7 +120,18 @@ const records = await table
 const value = record.get('fldXXXXXXXXXXXXXX'); // field ID
 ```
 
-**Limitation:** `filterByFormula` still requires field **names**, not IDs. This is an Airtable API limitation. Document any field names used in formulas to track potential breaking changes.
+**Limitation:** `filterByFormula` still requires field **names**, not IDs. This is an Airtable API limitation.
+
+### Field Names Used in Formulas
+
+The following field names are used in `filterByFormula` queries. **Renaming these fields in Airtable will break the app:**
+
+| Table | Field Name | Used In |
+|-------|------------|---------|
+| Apprentices | `Learner email` | `findApprenticeByEmail()` |
+| Cohorts | `FAC Cohort` | `getApprenticesByFacCohort()` |
+| Events | `FAC Cohort` | `listEvents()` cohort filter |
+| Events | `Date Time` | `listEvents()` date range filter |
 
 ### Fetching Schema IDs
 
@@ -138,3 +149,13 @@ This script:
 **Always use this script** to get IDs rather than copying them manually from the Airtable UI. This ensures accuracy and provides documentation of the schema at that point in time.
 
 The generated schema file can be used to update `src/lib/airtable/config.ts` with new field IDs.
+
+### Event Types
+
+Event types are defined in `src/lib/types/event.ts`. The `EventType` union currently includes:
+
+- `Regular class`
+- `Workshop`
+- `Hackathon`
+
+If new event types are added in Airtable's "Select" field, update this type definition to match.

scripts/test-events.ts

@@ -0,0 +1,61 @@
+/**
+ * Manual test script for Events CRUD operations.
+ * Run with: npx tsx scripts/test-events.ts
+ */
+
+import { createEventsClient } from '../src/lib/airtable/events.ts';
+import { config } from 'dotenv';
+config({ path: '.env.local' });
+
+const apiKey = process.env.AIRTABLE_API_KEY!;
+const baseId = process.env.AIRTABLE_BASE_ID_LEARNERS!;
+
+if (!apiKey || !baseId) {
+	console.error('Missing AIRTABLE_API_KEY or AIRTABLE_BASE_ID_LEARNERS');
+	process.exit(1);
+}
+
+const client = createEventsClient(apiKey, baseId);
+
+async function main() {
+	console.log('=== Testing Events CRUD ===\n');
+
+	// List events
+	console.log('1. Listing events...');
+	const events = await client.listEvents();
+	console.log(`   Found ${events.length} events`);
+	if (events.length > 0) {
+		console.log('   First event:', events[0]);
+	}
+
+	// Get single event (if any exist)
+	if (events.length > 0) {
+		console.log('\n2. Getting single event...');
+		const event = await client.getEvent(events[0].id);
+		console.log('   Event:', event);
+	}
+
+	// Uncomment below to test create/update/delete (will modify Airtable!)
+	/*
+	console.log('\n3. Creating event...');
+	const newEvent = await client.createEvent({
+		name: 'Test Event',
+		dateTime: new Date().toISOString(),
+		cohortId: 'YOUR_COHORT_RECORD_ID',
+		eventType: 'Workshop',
+	});
+	console.log('   Created:', newEvent);
+
+	console.log('\n4. Updating event...');
+	const updated = await client.updateEvent(newEvent.id, { name: 'Updated Test Event' });
+	console.log('   Updated:', updated);
+
+	console.log('\n5. Deleting event...');
+	await client.deleteEvent(newEvent.id);
+	console.log('   Deleted');
+	*/
+
+	console.log('\n=== Done ===');
+}
+
+main().catch(console.error);

src/lib/airtable/events.spec.ts

@@ -0,0 +1,174 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createEventsClient } from './events';
+
+// Mock Airtable
+vi.mock('airtable', () => {
+	const mockSelect = vi.fn();
+	const mockFind = vi.fn();
+	const mockCreate = vi.fn();
+	const mockUpdate = vi.fn();
+	const mockDestroy = vi.fn();
+
+	return {
+		default: {
+			configure: vi.fn(),
+			base: vi.fn(() => () => ({
+				select: mockSelect,
+				find: mockFind,
+				create: mockCreate,
+				update: mockUpdate,
+				destroy: mockDestroy,
+			})),
+		},
+	};
+});
+
+import Airtable from 'airtable';
+
+describe('events', () => {
+	let client: ReturnType<typeof createEventsClient>;
+	let mockTable: {
+		select: ReturnType<typeof vi.fn>;
+		find: ReturnType<typeof vi.fn>;
+		create: ReturnType<typeof vi.fn>;
+		update: ReturnType<typeof vi.fn>;
+		destroy: ReturnType<typeof vi.fn>;
+	};
+
+	beforeEach(() => {
+		vi.clearAllMocks();
+		client = createEventsClient('test-api-key', 'test-base-id');
+		// Get reference to mock table
+		mockTable = (Airtable.base('test-base-id') as unknown as () => typeof mockTable)();
+	});
+
+	describe('listEvents', () => {
+		it('should return mapped events', async () => {
+			const mockRecords = [
+				{
+					id: 'rec123',
+					get: vi.fn((field: string) => {
+						const data: Record<string, unknown> = {
+							fldMCZijN6TJeUdFR: 'Week 1 Monday',
+							fld8AkM3EanzZa5QX: '2025-01-06T10:00:00.000Z',
+							fldcXDEDkeHvWTnxE: ['recCohort1'],
+							fldo7fwAsFhkA1icC: 'Regular class',
+							fld9XBHnCWBtZiZah: 'https://survey.example.com',
+						};
+						return data[field];
+					}),
+				},
+			];
+
+			mockTable.select.mockReturnValue({ all: vi.fn().mockResolvedValue(mockRecords) });
+
+			const events = await client.listEvents();
+
+			expect(events).toHaveLength(1);
+			expect(events[0]).toEqual({
+				id: 'rec123',
+				name: 'Week 1 Monday',
+				dateTime: '2025-01-06T10:00:00.000Z',
+				cohortId: 'recCohort1',
+				eventType: 'Regular class',
+				surveyUrl: 'https://survey.example.com',
+			});
+		});
+	});
+
+	describe('getEvent', () => {
+		it('should return event when found', async () => {
+			const mockRecord = {
+				id: 'rec123',
+				get: vi.fn((field: string) => {
+					const data: Record<string, unknown> = {
+						fldMCZijN6TJeUdFR: 'Workshop',
+						fld8AkM3EanzZa5QX: '2025-01-07T14:00:00.000Z',
+						fldcXDEDkeHvWTnxE: ['recCohort2'],
+						fldo7fwAsFhkA1icC: 'Workshop',
+						fld9XBHnCWBtZiZah: undefined,
+					};
+					return data[field];
+				}),
+			};
+
+			mockTable.find.mockResolvedValue(mockRecord);
+
+			const event = await client.getEvent('rec123');
+
+			expect(event).toEqual({
+				id: 'rec123',
+				name: 'Workshop',
+				dateTime: '2025-01-07T14:00:00.000Z',
+				cohortId: 'recCohort2',
+				eventType: 'Workshop',
+				surveyUrl: undefined,
+			});
+		});
+
+		it('should return null when not found', async () => {
+			mockTable.find.mockRejectedValue(new Error('Record not found'));
+
+			const event = await client.getEvent('nonexistent');
+
+			expect(event).toBeNull();
+		});
+	});
+
+	describe('createEvent', () => {
+		it('should create and return new event', async () => {
+			const mockRecord = { id: 'recNew123' };
+			mockTable.create.mockResolvedValue(mockRecord);
+
+			const input = {
+				name: 'New Event',
+				dateTime: '2025-01-08T09:00:00.000Z',
+				cohortId: 'recCohort1',
+				eventType: 'Workshop' as const,
+				surveyUrl: 'https://survey.example.com',
+			};
+
+			const event = await client.createEvent(input);
+
+			expect(event).toEqual({
+				id: 'recNew123',
+				...input,
+			});
+			expect(mockTable.create).toHaveBeenCalled();
+		});
+	});
+
+	describe('updateEvent', () => {
+		it('should update and return event', async () => {
+			const mockRecord = {
+				id: 'rec123',
+				get: vi.fn((field: string) => {
+					const data: Record<string, unknown> = {
+						fldMCZijN6TJeUdFR: 'Updated Name',
+						fld8AkM3EanzZa5QX: '2025-01-06T10:00:00.000Z',
+						fldcXDEDkeHvWTnxE: ['recCohort1'],
+						fldo7fwAsFhkA1icC: 'Regular class',
+						fld9XBHnCWBtZiZah: undefined,
+					};
+					return data[field];
+				}),
+			};
+			mockTable.update.mockResolvedValue(mockRecord);
+
+			const event = await client.updateEvent('rec123', { name: 'Updated Name' });
+
+			expect(event.name).toBe('Updated Name');
+			expect(mockTable.update).toHaveBeenCalledWith('rec123', expect.any(Object));
+		});
+	});
+
+	describe('deleteEvent', () => {
+		it('should delete event', async () => {
+			mockTable.destroy.mockResolvedValue({});
+
+			await client.deleteEvent('rec123');
+
+			expect(mockTable.destroy).toHaveBeenCalledWith('rec123');
+		});
+	});
+});