# @suaveplan/api-plugin-events - Event-management plugin for @suaveplan/api. Ships a SurrealDB-backed EventRepository + RsvpRepository pair, 10 Hono OpenAPI routes (list / get / create / update / delete / rsvp / cancel-rsvp / my-rsvp / attendees / invite / ics export), 13 EVENTS_PLUGIN_* error codes, 7 OTel instruments, and a slimmed-down surql migration for the event / event_rsvp tables. Server-tier — runs in Bun and Node. Event-management plugin for `@suaveplan/api`. Ships a SurrealDB-backed `EventRepository` + `RsvpRepository` pair, ten Hono OpenAPI routes (list / get / create / update / delete / rsvp / cancel-rsvp / my-rsvp / attendees / invite / **ics export**), thirteen `EVENTS_PLUGIN_*` error codes, seven OTel counters, and a slim surql migration covering the `event` and `event_rsvp` tables. The ICS export endpoint emits a hand-rolled RFC 5545 `text/calendar` body — no third-party `ical` dependency — with full §3.3.11 escapes and §3.1 line folding. This plugin is for **event entities** (meetups, invitations, RSVPs, attendee tracking). It is NOT the typed event-bus library — that is `@suaveplan/events`, which this plugin happens to consume. ## Documentation tree - [error-codes](./src/error-codes/error-codes.md) — Defines the stable error-code registry and concrete error class for `@suaveplan/api-plugin-events`. Every failure path… - [error-codes](./src/error-codes/error-codes.md) — Defines the stable error-code registry and concrete error class for `@suaveplan/api-plugin-events`. Every failure path… - [ics-builder](./src/ics/ics-builder/ics-builder.md) — The `ics-builder` module emits a complete RFC 5545 `VCALENDAR` document for a single event document loaded from `EventR… - [ics-builder](./src/ics/ics-builder/ics-builder.md) — The `ics-builder` module emits a complete RFC 5545 `VCALENDAR` document for a single event document loaded from `EventR… - [otel](./src/otel/instruments.md) — Bundles the seven OpenTelemetry counters emitted by `@suaveplan/api-plugin-events`. Every counter is lazily built on th… - [instruments](./src/otel/instruments.md) — Bundles the seven OpenTelemetry counters emitted by `@suaveplan/api-plugin-events`. Every counter is lazily built on th… - [plugin](./src/plugin/plugin.md) — Defines `createEventsPlugin`, the factory that returns the `PluginDescriptor` consumed by `@suavepl… - [plugin](./src/plugin/plugin.md) — Defines `createEventsPlugin`, the factory that returns the `PluginDescriptor` consumed by `@suavepl… - [event-repository](./src/repositories/event-repository/event-repository.md) — SurrealDB-backed implementation of the `IEventRepository` contract. The repository owns event-entity CRUD: list / get /… - [event-repository](./src/repositories/event-repository/event-repository.md) — SurrealDB-backed implementation of the `IEventRepository` contract. The repository owns event-entity CRUD: list / get /… - [rsvp-repository](./src/repositories/rsvp-repository/rsvp-repository.md) — SurrealDB-backed implementation of the `IRsvpRepository` contract. The repository owns RSVP / invitation persistence: p… - [rsvp-repository](./src/repositories/rsvp-repository/rsvp-repository.md) — SurrealDB-backed implementation of the `IRsvpRepository` contract. The repository owns RSVP / invitation persistence: p… - [events-routes](./src/routes/events-routes/events-routes.md) — Builds the nine-route OpenAPI Hono module mounted by `createEventsPlugin`. Each route is wrapped by `@hono/zod-openapi`… - [events-routes](./src/routes/events-routes/events-routes.md) — Builds the nine-route OpenAPI Hono module mounted by `createEventsPlugin`. Each route is wrapped by `@hono/zod-openapi`… - [ics-export](./src/routes/ics-export/ics-export.md) — The `ics-export` route module exposes `GET /:id/ics` on top of the shared events `OpenAPIHono` mount, returning an RFC… - [ics-export](./src/routes/ics-export/ics-export.md) — The `ics-export` route module exposes `GET /:id/ics` on top of the shared events `OpenAPIHono` mount, returning an RFC… - [event-schemas](./src/schemas/event-schemas.md) — The package-local Zod schemas for the `event` entity surface. Owns every input / output shape touching the events route… - [options](./src/schemas/options.md) — The Zod schema for `createEventsPlugin`'s options bundle. Three fields: `basePath` (mount prefix, default `/events`), `… - [rsvp-schemas](./src/schemas/rsvp-schemas.md) — Local Zod schemas for the RSVP / invitation surface. Owns the persisted `RsvpSchema`, the `CreateRsvpSchema` request bo… - [services](./src/services/registry-augmentation.md) — Module-augmentation file that adds the `eventRepository` and `rsvpRepository` slots to `@suaveplan/api-plugin/service-r… - [registry-augmentation](./src/services/registry-augmentation.md) — Module-augmentation file that adds the `eventRepository` and `rsvpRepository` slots to `@suaveplan/api-plugin/service-r… - [types](./src/types/types.md) — Public type definitions that don't live alongside their schemas or implementations: the cross-plugin `EventsPluginEvent… - [types](./src/types/types.md) — Public type definitions that don't live alongside their schemas or implementations: the cross-plugin `EventsPluginEvent… ## Install ```bash bun add @suaveplan/api-plugin-events ``` ## Quick start ```ts import { quickstart } from "@suaveplan/api"; import { createDatabasePlugin } from "@suaveplan/api-plugin-database"; import { createEventsPlugin } from "@suaveplan/api-plugin-events"; const app = await quickstart({ plugins: [ createDatabasePlugin({ url: "ws://localhost:8000/rpc", namespace: "app", database: "main", username: "root", password: "root", }), createEventsPlugin({ basePath: "/events", enableNotifications: false, maxInvitesPerRequest: 50, }), ], }); // Subscribe to domain events on the shared bus app.eventBus.on("event:created", ({ eventId, creatorId }) => { console.log("event", eventId, "created by", creatorId); }); ``` ## Modules - [error-codes/error-codes](./src/error-codes/error-codes.md) — 12-code registry + `EventsPluginError`. - [otel/instruments](./src/otel/instruments.md) — 5 OTel counters. - [plugin/plugin](./src/plugin/plugin.md) — `createEventsPlugin` factory + lifecycle. - [repositories/event-repository/event-repository](./src/repositories/event-repository/event-repository.md) — `EventRepository`. - [repositories/rsvp-repository/rsvp-repository](./src/repositories/rsvp-repository/rsvp-repository.md) — `RsvpRepository`. - [routes/events-routes/events-routes](./src/routes/events-routes/events-routes.md) — `createEventRoutes` (9 endpoints). - [routes/ics-export/ics-export](./src/routes/ics-export/ics-export.md) — `createIcsExportRoutes` (RFC 5545 ICS export). - [ics/ics-builder/ics-builder](./src/ics/ics-builder/ics-builder.md) — hand-rolled VCALENDAR builder. - [schemas/event-schemas](./src/schemas/event-schemas.md) — local Zod schemas for events. - [schemas/rsvp-schemas](./src/schemas/rsvp-schemas.md) — local Zod schemas for RSVPs. - [schemas/options](./src/schemas/options.md) — `EventsPluginOptionsSchema`. - [services/registry-augmentation](./src/services/registry-augmentation.md) — `ServiceRegistry` slots. - [types/types](./src/types/types.md) — `EventsPluginEvents` + `EventsRouteEvent`. ## Out of scope See the design proposal for the full list. Highlights: - ICS / iCalendar export — shipped by `add-events-ics-export` (2026-05-20). - Recurring events (RFC-5545 `RRULE`) — deferred to `add-api-plugin-events-recurrence`. - Notification fan-out — `enableNotifications` is reserved; binding lands when `@suaveplan/notification-channel` migrates. - Rate-limit + audit-log integration — composed at the host level once `api-plugin-rate-limit` and `api-plugin-audit` land. - Upstream surql cross-plugin permission rules, helper functions, and the `event_update` table — scoped out because they depend on plugins (site, group, notifications, bitwise) not yet . ## Status `0.1.0` — feature parity with upstream `@suaveplan/api-plugin-events` modulo the explicit scope-outs above. 100% line / branch / function / statement coverage. Real SurrealDB testcontainer integration.