Add KnightConnect support to event generation

[DVidal1205]

When making an event on Blade, it automatically inserted to:

• Our database
• Our Discord calendar
• Our google Calendar

We want to add compatibility with UCF's KnightConnect. I am not sure if there is a proper API for this, none on admin side. May require a bit of reverse engineering via the network tab :)

If this is impossible, no worries, but it is worth the investigation!

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Warning

A plan generation is already in progress. Please wait for it to complete before requesting a new plan.

[coderabbitai]

Coding Plan

Summary

• Leverage the official Campus Labs Engage REST API with header-based API key authentication, following the same multi-service coordination pattern already established for Discord and Google Calendar
• Extend the existing sequential creation flow (Discord → Google → KnightConnect → Database) with proper rollback cleanup on failures
• Store KnightConnect event IDs in the database as a nullable field to maintain sync state and support graceful degradation when the service is unavailable
• Map Blade event fields to Engage API's required Event structure, using environment variables for static organization identifiers

Design Choices

Design Choice 1: API Access Availability

Options Considered:

1. Use the official Engage REST API with an API key obtained from UCF KnightConnect admin
2. Reverse-engineer the web application by inspecting network requests
3. Mark feature as infeasible if no API access can be obtained

Chosen Option: 1

Rationale: The official Engage API is well-documented with clear endpoints for event creation, updates, and cancellation. This should be the primary approach, with Option 2 as fallback investigation if API access is denied.

Design Choice 2: Required Organization Identifiers

Options Considered:

1. Store organization/submitter IDs as environment variables (static configuration)
2. Fetch organization ID dynamically via API lookup at runtime

Chosen Option: 1

Rationale: Store as environment variables since the Knight Hacks organization ID is static and won't change. This avoids unnecessary API calls and simplifies the implementation.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Infrastructure and Foundation

This phase establishes the groundwork for KnightConnect integration by adding configuration, creating the API client, and extending the database schema to track KnightConnect event IDs.

Task 1: Add KnightConnect Environment Variables

Configure environment variables for KnightConnect API authentication and organization settings.

• Update packages/api/src/env.ts to add Zod validation for new variables: KNIGHTCONNECT_API_KEY, KNIGHTCONNECT_ORG_ID, KNIGHTCONNECT_SUBMITTER_ID, and optionally KNIGHTCONNECT_API_URL (with default to Engage API base URL)
• Update .env.example to document the new KnightConnect environment variables with placeholder values and comments explaining each variable's purpose
• Follow existing naming convention pattern (e.g., DISCORD_BOT_TOKEN, GOOGLE_PRIVATE_KEY_B64)

Task 2: Create KnightConnect API Client Utility

Build a reusable client for interacting with the Campus Labs Engage REST API.

• Add KnightConnect client initialization in packages/api/src/utils.ts following the pattern used for discord and calendar clients
• Implement core API methods: createEvent, updateEvent, cancelEvent that wrap the Engage API endpoints
• Use header-based authentication (X-Engage-Api-Key) for cleaner URLs
• Include proper TypeScript types for Engage API request/response structures based on the documented schema (Event object with name, description, startsOn, endsOn, address, organizationIds, etc.)
• Handle rate limiting by respecting 429 responses with Retry-After header

Task 3: Extend Event Database Schema

Add a field to track KnightConnect event IDs for synchronization.

• Add knightConnectId varchar(255) nullable field to the Event table in packages/db/src/schemas/knight-hacks.ts, following the pattern of existing discordId and googleId fields
• Make the field nullable to support events that may not be synced to KnightConnect (e.g., if API is temporarily unavailable or feature is disabled)
• Run database migration to apply schema changes

🤖 Prompt for AI agents

This phase sets up the infrastructure for KnightConnect integration by adding
environment configuration, creating an API client, and extending the database
schema.

**Environment Variables (`packages/api/src/env.ts` and `.env.example`):**
- Add Zod validation in `packages/api/src/env.ts` for:
  - `KNIGHTCONNECT_API_KEY` (required string)
  - `KNIGHTCONNECT_ORG_ID` (required string)
  - `KNIGHTCONNECT_SUBMITTER_ID` (required string)
- `KNIGHTCONNECT_API_URL` (optional string with default to Engage API base URL)
- Follow the existing naming convention pattern used for `DISCORD_BOT_TOKEN` and
`GOOGLE_PRIVATE_KEY_B64`
- Update `.env.example` with placeholder values and comments explaining each
variable's purpose

**API Client (`packages/api/src/utils.ts`):**
- Initialize KnightConnect client following the existing pattern for `discord`
and `calendar` clients
- Implement three core API methods:
  - `createEvent`: Wraps Engage API event creation endpoint
  - `updateEvent`: Wraps Engage API event update endpoint
  - `cancelEvent`: Wraps Engage API event cancellation endpoint
- Use header-based authentication with `X-Engage-Api-Key` header
- Define TypeScript types for Engage API structures including Event object with
fields: name, description, startsOn, endsOn, address, organizationIds,
submittedByOrganizationId, submittedById
- Implement rate limiting handling by checking for 429 responses and respecting
`Retry-After` header

**Database Schema (`packages/db/src/schemas/knight-hacks.ts`):**
- Add `knightConnectId` field to Event table:
  - Type: varchar(255)
  - Nullable: true
  - Follow the same pattern as existing `discordId` and `googleId` fields
- Generate and run database migration to apply the schema changes

Phase 2: Event Lifecycle Integration

This phase integrates KnightConnect into the existing event creation, update, and deletion workflows, maintaining the established sequential-with-rollback pattern.

Task 1: Integrate KnightConnect into Event Creation

Extend the createEvent mutation to sync new events to KnightConnect.

• Modify the createEvent procedure in packages/api/src/routers/event.ts to add KnightConnect event creation as a step in the sequential flow (after Google Calendar, before database insert)
• Map Blade event fields to Engage API Event structure:
  • name → formatted name with tag prefix [TAG] Event Name
  • description → event description (include hackathon context if applicable)
  • startsOn/endsOn → ISO datetime strings from start_datetime/end_datetime
  • address → construct EventAddress object from location field
  • submittedByOrganizationId and organizationIds → from environment config
  • submittedById → from environment config
• Store returned KnightConnect event ID in the database record
• Add error handling that rolls back Discord and Google Calendar events if KnightConnect creation fails
• Add audit logging via log() function for successful KnightConnect sync

Task 2: Integrate KnightConnect into Event Updates

Extend the updateEvent mutation to sync changes to KnightConnect.

• Modify the updateEvent procedure in packages/api/src/routers/event.ts to include KnightConnect updates
• Use PATCH endpoint with JSON Patch operations for field updates
• Include submittedById in all update requests as required by the API
• Handle cases where event may not have a knightConnectId (skip KnightConnect update gracefully)
• Add appropriate error handling and logging

Task 3: Integrate KnightConnect into Event Deletion

Extend the deleteEvent mutation to cancel events in KnightConnect.

• Modify the deleteEvent procedure in packages/api/src/routers/event.ts to cancel the KnightConnect event
• Use the cancel endpoint (POST /v3.0/events/event/{id}/cancel) rather than delete, as Engage does not support hard deletion
• Handle cases where event may not have a knightConnectId (skip cancellation gracefully)
• Include in the existing rollback cleanup flow if database deletion fails
• Add audit logging for successful cancellation

Task 4: Add Graceful Degradation

Ensure the system remains functional if KnightConnect integration fails or is unavailable.

• Wrap KnightConnect operations in try-catch blocks that log errors but don't prevent event creation if KnightConnect is the only failing service
• Consider adding a feature flag or environment variable (KNIGHTCONNECT_ENABLED) to easily disable the integration without code changes
• Ensure events can still be created/updated/deleted in Discord, Google Calendar, and the database even if KnightConnect API is unreachable
• Log warnings when KnightConnect operations are skipped or fail, using appropriate color (uhoh_red for failures)

🤖 Prompt for AI agents

This phase integrates KnightConnect into the event lifecycle (create, update,
delete) following the existing sequential-with-rollback pattern.

**Event Creation (`packages/api/src/routers/event.ts` - `createEvent`
procedure):**
- Add KnightConnect event creation step after Google Calendar and before
database insert
- Map Blade event fields to Engage API Event structure:
  - `name`: Format as `[TAG] Event Name`
- `description`: Use event description, include hackathon context if applicable
- `startsOn`/`endsOn`: Convert start_datetime/end_datetime to ISO datetime
strings
  - `address`: Construct EventAddress object from location field
- `submittedByOrganizationId` and `organizationIds`: Use values from environment
config
  - `submittedById`: Use value from environment config
- Store the returned KnightConnect event ID in the database record
- Implement rollback logic: if KnightConnect creation fails, roll back Discord
and Google Calendar events
- Add audit logging using `log()` function for successful KnightConnect sync

**Event Updates (`packages/api/src/routers/event.ts` - `updateEvent`
procedure):**
- Add KnightConnect update step to the procedure
- Use PATCH endpoint with JSON Patch operations for field updates
- Include `submittedById` in all update requests (required by API)
- Check if event has `knightConnectId` before attempting update; skip gracefully
if null
- Add error handling and logging

**Event Deletion (`packages/api/src/routers/event.ts` - `deleteEvent`
procedure):**
- Add KnightConnect cancellation step to the procedure
- Use cancel endpoint: `POST /v3.0/events/event/{id}/cancel` (not delete, as
Engage doesn't support hard deletion)
- Check if event has `knightConnectId` before attempting cancellation; skip
gracefully if null
- Include in existing rollback cleanup flow if database deletion fails
- Add audit logging for successful cancellation

**Graceful Degradation:**
- Wrap all KnightConnect operations in try-catch blocks that log errors but
allow event operations to succeed if KnightConnect is the only failing service
- Consider adding `KNIGHTCONNECT_ENABLED` environment variable as a feature flag
- Ensure Discord, Google Calendar, and database operations continue to work even
if KnightConnect API is unreachable
- Log warnings for skipped or failed KnightConnect operations using `uhoh_red`
color for failures

Research

The project is a Next.js 14 monorepo with a Blade admin dashboard app that manages club and hackathon events. Events are created through tRPC API endpoints in packages/api/src/routers/event.ts, which coordinate multi-service creation across Discord (scheduled events), Google Calendar, and a PostgreSQL database via Drizzle ORM. External service clients are initialized in packages/api/src/utils.ts, environment variables are validated with Zod in packages/api/src/env.ts, and the event schema lives in packages/db/src/schemas/knight-hacks.ts. The existing pattern follows sequential creation with rollback cleanup on failures.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

This phase sets up the infrastructure for KnightConnect integration by adding
environment configuration, creating an API client, and extending the database
schema.

**Environment Variables (`packages/api/src/env.ts` and `.env.example`):**
- Add Zod validation in `packages/api/src/env.ts` for:
  - `KNIGHTCONNECT_API_KEY` (required string)
  - `KNIGHTCONNECT_ORG_ID` (required string)
  - `KNIGHTCONNECT_SUBMITTER_ID` (required string)
- `KNIGHTCONNECT_API_URL` (optional string with default to Engage API base URL)
- Follow the existing naming convention pattern used for `DISCORD_BOT_TOKEN` and
`GOOGLE_PRIVATE_KEY_B64`
- Update `.env.example` with placeholder values and comments explaining each
variable's purpose

**API Client (`packages/api/src/utils.ts`):**
- Initialize KnightConnect client following the existing pattern for `discord`
and `calendar` clients
- Implement three core API methods:
  - `createEvent`: Wraps Engage API event creation endpoint
  - `updateEvent`: Wraps Engage API event update endpoint
  - `cancelEvent`: Wraps Engage API event cancellation endpoint
- Use header-based authentication with `X-Engage-Api-Key` header
- Define TypeScript types for Engage API structures including Event object with
fields: name, description, startsOn, endsOn, address, organizationIds,
submittedByOrganizationId, submittedById
- Implement rate limiting handling by checking for 429 responses and respecting
`Retry-After` header

**Database Schema (`packages/db/src/schemas/knight-hacks.ts`):**
- Add `knightConnectId` field to Event table:
  - Type: varchar(255)
  - Nullable: true
  - Follow the same pattern as existing `discordId` and `googleId` fields
- Generate and run database migration to apply the schema changes
===============================================================================

Task: 2

This phase integrates KnightConnect into the event lifecycle (create, update,
delete) following the existing sequential-with-rollback pattern.

**Event Creation (`packages/api/src/routers/event.ts` - `createEvent`
procedure):**
- Add KnightConnect event creation step after Google Calendar and before
database insert
- Map Blade event fields to Engage API Event structure:
  - `name`: Format as `[TAG] Event Name`
- `description`: Use event description, include hackathon context if applicable
- `startsOn`/`endsOn`: Convert start_datetime/end_datetime to ISO datetime
strings
  - `address`: Construct EventAddress object from location field
- `submittedByOrganizationId` and `organizationIds`: Use values from environment
config
  - `submittedById`: Use value from environment config
- Store the returned KnightConnect event ID in the database record
- Implement rollback logic: if KnightConnect creation fails, roll back Discord
and Google Calendar events
- Add audit logging using `log()` function for successful KnightConnect sync

**Event Updates (`packages/api/src/routers/event.ts` - `updateEvent`
procedure):**
- Add KnightConnect update step to the procedure
- Use PATCH endpoint with JSON Patch operations for field updates
- Include `submittedById` in all update requests (required by API)
- Check if event has `knightConnectId` before attempting update; skip gracefully
if null
- Add error handling and logging

**Event Deletion (`packages/api/src/routers/event.ts` - `deleteEvent`
procedure):**
- Add KnightConnect cancellation step to the procedure
- Use cancel endpoint: `POST /v3.0/events/event/{id}/cancel` (not delete, as
Engage doesn't support hard deletion)
- Check if event has `knightConnectId` before attempting cancellation; skip
gracefully if null
- Include in existing rollback cleanup flow if database deletion fails
- Add audit logging for successful cancellation

**Graceful Degradation:**
- Wrap all KnightConnect operations in try-catch blocks that log errors but
allow event operations to succeed if KnightConnect is the only failing service
- Consider adding `KNIGHTCONNECT_ENABLED` environment variable as a feature flag
- Ensure Discord, Google Calendar, and database operations continue to work even
if KnightConnect API is unreachable
- Log warnings for skipped or failed KnightConnect operations using `uhoh_red`
color for failures

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!