suaveplan/openspec/archive/2026-05-19-add-api-plugin-events/proposal.md

add-api-plugin-events

Package: @suaveplan/api-plugin-events Status: PROPOSED Type: new-package Design: (none — straightforward migration; see this proposal + spec delta) Spec delta: ./specs/api-plugin-events/spec.md

Why

Genesis ships the foundational pieces of @suaveplan/api (database, search, auth, etc.) but is missing the event-management plugin (calendar-style entity: schedule events, RSVP, invite users). Without this plugin, downstream apps that need meetup / RSVP / attendee flows have to hand-roll the surface — there is no other @suaveplan/* capability that covers it. Upstream enterprise/api-plugin-events.md documents the audit (3 *.test.ts files, parity-only migration target). This change brings the package across at full functional parity, adapted to the genesis @suaveplan/api plugin shape (PluginDescriptor, ctx.getService("app"), ctx.getService("db")) and genesis DatabaseAdapter positional-param surface, with the named-emitter wart replaced by the shared ctx.eventBus so other plugins can subscribe.

The event-management plugin is distinct from @suaveplan/events (the typed event-bus, already shipped on genesis) and from @suaveplan/api-plugin-event-bus (the API-side adapter for the event-bus, also shipped). The name collision is unfortunate but the plugin's defineCodes namespace is EVENTS_PLUGIN (not EVENTS) precisely to avoid the registry clash with @suaveplan/events.

What changes

• ADDED: createEventsPlugin(options?) — factory returning a PluginDescriptor<EventsPluginConfig> for @suaveplan/api.
• ADDED: EventsPluginOptionsSchema / EventsPluginConfig / EventsPluginConfigInput — Zod-validated config (basePath, enableNotifications, maxInvitesPerRequest).
• ADDED: EventRepository + IEventRepository — SurrealDB-backed event CRUD repository over the genesis SurrealAdapter service slot.
• ADDED: RsvpRepository + IRsvpRepository — SurrealDB-backed RSVP / invitation / attendee-counting repository.
• ADDED: createEventRoutes — Hono OpenAPI route module with 9 endpoints (list / get / create / update / delete / rsvp / cancel-rsvp / my-rsvp / attendees / invite).
• ADDED: EVENTS_PLUGIN_CODES registry + EventsPluginError class — 12 stable codes spanning configuration, lifecycle, repository, and route paths.
• ADDED: OTel instruments — 5 counters / histograms emitted from repository + route code (events created, events updated, events deleted, rsvps written, invitations sent).
• ADDED: ServiceRegistry augmentation — eventRepository and rsvpRepository slots become available to downstream plugins via typed ctx.getService(...).
• ADDED: Local Zod schemas (EventSchema, CreateEventSchema, UpdateEventSchema, EventQuerySchema, EventIdParamSchema, EventLocationSchema, EventStatusSchema, AttendeeCountSchema, EventListResponseSchema, RsvpSchema, RsvpStatusSchema, CreateRsvpSchema, RsvpResponseSchema, AttendeeSchema, AttendeeQuerySchema, AttendeeListResponseSchema, InviteUsersSchema, InviteResponseSchema) — @suaveplan/api-schemas on genesis only ships event-bus envelope schemas, not event-entity schemas, so the plugin owns its boundary schemas.
• ADDED: surql/tables/event.surql migration — event and event_rsvp SCHEMAFULL tables plus the two indexes the repositories rely on (event_start_idx, event_rsvp_unique_idx). See ## Out of scope for the deferred upstream permission rules / helper functions / event_update table.
• ADDED: EventsPluginEvents event-map keys — events:initialized, events:ready, event:created, event:updated, event:cancelled, rsvp:created, rsvp:cancelled, event:invitations:sent.

Out of scope

Items from enterprise/api-plugin-events.md "Required enterprise-quality improvements" and "Feature-rich enhancements" are deferred to follow-up changes because they each require new cross-package dependencies that don't exist yet on genesis (or are migrated under their own change):

• ICS / iCalendar export — requires a @suaveplan/templates ICS builder or a hand-rolled module; deferred to add-api-plugin-events-ics-export.
• Recurring events (RRULE / RFC-5545) — requires @suaveplan/datetime RRULE expansion which is not yet wired; deferred to add-api-plugin-events-recurrence.
• Notification fan-out via @suaveplan/notification-channel — enableNotifications is wired through the plugin config and accepted at construction, but the actual channel binding lands when @suaveplan/notification-channel migrates (see STATUS.md). The config flag is non-load-bearing in this change but reserved by Zod so consumers configuring it today won't fail validation later.
• Rate-limiter on /events/:id/invite — depends on @suaveplan/api-plugin-rate-limit which is migrating concurrently; will be composed at the host level once both land.
• Audit-log on create / cancel / RSVP — depends on @suaveplan/api-plugin-audit (concurrent migration).
• Auth gating via @suaveplan/api-plugin-auth — this plugin reads c.get("user") (set by the host's auth middleware) and raises UNAUTHENTICATED when missing; explicit requireAuth() composition is a host-level concern.
• Calendar sync (Google / Outlook / iCloud), waitlist / capacity, invite tokens, reminders, geo, check-in QR, ticketing, SSE live updates — each is a feature-rich enhancement called out in the upstream enterprise audit, none of which are present in the upstream code itself; they belong in follow-up changes that don't ride on this parity migration.
• Upstream surql/tables/event.surql ships row-level PERMISSIONS rules and stored helper functions (fn::event::can_view, fn::event::can_moderate, fn::event::create, fn::event::update_rsvp, fn::event::invite, fn::event::post_update, fn::event::get_upcoming) plus an event_update table — all of which transitively depend on fn::bitwise::*, fn::notification::*, fn::group::*, and record<site> / record<group> references from sibling plugins (api-plugin-site, api-plugin-notifications, api-plugin-groups, api-plugin-bitwise). None of those plugins exist on genesis yet, and the upstream test harness papers over the gap with a loadCrossPluginStubs helper that is itself absent from genesis's @suaveplan/surrealdb. To avoid hand-rolling four downstream plugins as a side-quest, the migration ships a slimmer surql/tables/event.surql covering only the event and event_rsvp tables that the repositories actually read / write; permissions enforcement moves to the route layer (auth guard + creator check) and the event_update table + helper functions migrate when their dependent plugins land.

Source mapping

This change derives from ../suaveplan/enterprise/api-plugin-events.md and the upstream source at ../suaveplan/packages/server/api-plugin-events/.

Requirement	Source lines	Notes
Plugin factory createEventsPlugin(config?)	enterprise.md L18-L23; src/index.ts L35-L101	reworded — genesis uses PluginDescriptor not Plugin<EventsConfig>
Config schema (basePath, enableNotifications, maxInvitesPerRequest)	enterprise.md L12; src/index.ts L23-L29	verbatim
Plugin dependencies: ["database"]	enterprise.md L16; src/index.ts L46	verbatim
migrationsPath: "./surql"	enterprise.md L16; src/index.ts L58	verbatim — surql payload migrated unchanged
EventRepository: findAll/findById/create/update/delete/isCreator/updateAttendeeCount	src/repositories/event.repository/index.ts	verbatim — semantics preserved, query helper rewritten for genesis adapter
RsvpRepository: findByEventAndUser/findAttendees/upsert/delete/createInvitations/countByStatus	src/repositories/rsvp.repository/index.ts	verbatim
createEventRoutes (9 endpoints)	src/routes/events/index.ts	verbatim — ctx.eventBus replaces local EventEmitter
event / event_rsvp / event_update tables + indexes	surql/tables/event.surql	verbatim
Public re-export of repositories + routes + types	src/index.ts L103-L106	reworded — explicit named exports per genesis rule 10

Requirements with no source line

Requirement	Justification
100% test / branch / function / line coverage	Genesis-wide policy (CLAUDE.md "Quality", AGENTS.md §7).
defineCodes("EVENTS_PLUGIN", [...]) namespace	Genesis convention; EVENTS collides with the @suaveplan/events event-bus registry.
OTel instruments via metrics.getMeter("@suaveplan/api-plugin-events")	Genesis-wide observability policy; emitted from production paths and asserted with a real in-memory MeterProvider (AGENTS.md §13).
Use ctx.eventBus from @suaveplan/api-plugin context, not a local EventEmitter	Fixes the smell flagged in enterprise/api-plugin-events.md "Notable smells" L41 (local emitter not visible to other plugins).
Subpath exports per feature module	AGENTS.md §6 — required so consumers can tree-shake.
Schemas owned locally	@suaveplan/api-schemas on genesis ships only event-bus envelope schemas, not event-entity schemas (verified by inspection: packages/api/api-schemas/src/events/ contains domain-event.ts, envelope.ts, metadata.ts only). Migrating the entity schemas into @suaveplan/api-schemas is out of scope for a plugin migration.
Positional $p0-style params instead of named $title	Genesis DatabaseAdapter.query(sql, params: readonly unknown[]) wraps params as {p0: ..., p1: ...} via paramsToRecord. Upstream uses named placeholders that don't survive the canonical surface (Path-A escape valve documented in CLAUDE.md).

Verification approach

• src/repositories/event.repository/event.repository.test.ts — covers EventRepository requirements (CRUD, normalisation, isCreator branches, attendee count).
• src/repositories/rsvp.repository/rsvp.repository.test.ts — covers RsvpRepository requirements (find / upsert / delete / invitations / countByStatus).
• src/routes/events-routes/events-routes.test.ts — covers route surface, status codes, auth guard, event emission.
• src/plugin/plugin.test.ts — covers plugin lifecycle (onInit / onReady / onClose), service registration, route mounting.
• src/error-codes/error-codes.test.ts — pins every code is reachable from a real call site.
• src/otel/instruments.test.ts — real MeterProvider, asserts instrument shape and emission.
• src/schemas/event-schemas.test.ts + src/schemas/rsvp-schemas.test.ts + src/schemas/options.test.ts — Zod boundary tests.
• surql/surql-validation.test.ts — discovers and loads the surql migration against a real SurrealDB testcontainer (isSurrealDBAvailable skip-aware).
• tests/integration/full-boot.test.ts — full plugin boot + CRUD roundtrip against a real SurrealDB container.
• src/api-plugin-events.spec-conformance.test.ts — pins every public symbol re-exported by the package root.

Migration impact

None — additive only. This is a brand-new package on genesis. Consumers will opt-in via createEventsPlugin() once they need event-management routes.

Impact

Affected dependents

None on genesis today — package is additive. Downstream apps that previously had no event-management capability gain access.