skills/plugins/document-navigator/docs/api-stack/api/api-plugin-events/README.md

@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 — Defines the stable error-code registry and concrete error class for @suaveplan/api-plugin-events. Every failure path…
  • error-codes — Defines the stable error-code registry and concrete error class for @suaveplan/api-plugin-events. Every failure path…
• ics-builder — The ics-builder module emits a complete RFC 5545 VCALENDAR document for a single event document loaded from `EventR…
  • ics-builder — The ics-builder module emits a complete RFC 5545 VCALENDAR document for a single event document loaded from `EventR…
• otel — Bundles the seven OpenTelemetry counters emitted by @suaveplan/api-plugin-events. Every counter is lazily built on th…
  • instruments — Bundles the seven OpenTelemetry counters emitted by @suaveplan/api-plugin-events. Every counter is lazily built on th…
• plugin — Defines createEventsPlugin, the factory that returns the PluginDescriptor<EventsPluginConfig> consumed by `@suavepl…
  • plugin — Defines createEventsPlugin, the factory that returns the PluginDescriptor<EventsPluginConfig> consumed by `@suavepl…
• event-repository — SurrealDB-backed implementation of the IEventRepository contract. The repository owns event-entity CRUD: list / get /…
  • event-repository — SurrealDB-backed implementation of the IEventRepository contract. The repository owns event-entity CRUD: list / get /…
• rsvp-repository — SurrealDB-backed implementation of the IRsvpRepository contract. The repository owns RSVP / invitation persistence: p…
  • rsvp-repository — SurrealDB-backed implementation of the IRsvpRepository contract. The repository owns RSVP / invitation persistence: p…
• events-routes — Builds the nine-route OpenAPI Hono module mounted by createEventsPlugin. Each route is wrapped by @hono/zod-openapi…
  • events-routes — Builds the nine-route OpenAPI Hono module mounted by createEventsPlugin. Each route is wrapped by @hono/zod-openapi…
• ics-export — The ics-export route module exposes GET /:id/ics on top of the shared events OpenAPIHono mount, returning an RFC…
  • ics-export — The ics-export route module exposes GET /:id/ics on top of the shared events OpenAPIHono mount, returning an RFC…
• event-schemas — The package-local Zod schemas for the event entity surface. Owns every input / output shape touching the events route…
• options — The Zod schema for createEventsPlugin's options bundle. Three fields: basePath (mount prefix, default /events), `…
• rsvp-schemas — Local Zod schemas for the RSVP / invitation surface. Owns the persisted RsvpSchema, the CreateRsvpSchema request bo…
• services — Module-augmentation file that adds the eventRepository and rsvpRepository slots to `@suaveplan/api-plugin/service-r…
  • registry-augmentation — Module-augmentation file that adds the eventRepository and rsvpRepository slots to `@suaveplan/api-plugin/service-r…
• types — Public type definitions that don't live alongside their schemas or implementations: the cross-plugin `EventsPluginEvent…
  • types — Public type definitions that don't live alongside their schemas or implementations: the cross-plugin `EventsPluginEvent…

Install

bun add @suaveplan/api-plugin-events

Quick start

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 — 12-code registry + EventsPluginError.
• otel/instruments — 5 OTel counters.
• plugin/plugin — createEventsPlugin factory + lifecycle.
• repositories/event-repository/event-repository — EventRepository.
• repositories/rsvp-repository/rsvp-repository — RsvpRepository.
• routes/events-routes/events-routes — createEventRoutes (9 endpoints).
• routes/ics-export/ics-export — createIcsExportRoutes (RFC 5545 ICS export).
• ics/ics-builder/ics-builder — hand-rolled VCALENDAR builder.
• schemas/event-schemas — local Zod schemas for events.
• schemas/rsvp-schemas — local Zod schemas for RSVPs.
• schemas/options — EventsPluginOptionsSchema.
• services/registry-augmentation — ServiceRegistry slots.
• types/types — 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.