113 lines
8.3 KiB
Markdown
113 lines
8.3 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## 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<EventsPluginConfig>` consumed by `@suavepl…
|
|
- [plugin](./src/plugin/plugin.md) — Defines `createEventsPlugin`, the factory that returns the `PluginDescriptor<EventsPluginConfig>` 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…
|
|
<!-- end:auto-docs -->
|
|
|
|
## 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.
|
|
|