OpenSpec Change: enterprise-api-plugin-messaging

Change ID: enterprise-api-plugin-messaging
Package: @suaveplan/api-plugin-messaging
Category: api/comms
Target path: api/comms/api-plugin-messaging
Status: PROPOSED
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/api-plugin-messaging.md

Summary

Deliver @suaveplan/api-plugin-messaging on the genesis branch from scratch at enterprise quality. In-app messaging plugin: threads (1:1 and group), messages with rich content (text, attachments, reactions), read receipts, typing indicators via SSE or WebSocket bridge, message search, and moderation (flag/delete). Routes under /messaging. Per-table SurrealQL. Typed bus events: messaging:message:sent, messaging:thread:created, messaging:message:deleted. Integrates with @suaveplan/api-plugin-notifications to emit push/email notifications on new messages.

Available workspace deps on genesis

Package	Role
`@suaveplan/api` (`workspace:^`)	`definePlugin`
`@suaveplan/api-shared` (`workspace:^`)	Helpers
`@suaveplan/api-plugin-auth` (`workspace:^`)	`requireAuth`
`@suaveplan/api-plugin-database` (`workspace:^`)	SurrealDB
`@suaveplan/api-plugin-file-upload` (`workspace:^`)	Attachment uploads
`@suaveplan/api-plugin-notifications` (`workspace:^`)	Push/email on new message
`@suaveplan/suppression` (`workspace:^`)	Message suppression list
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`MessagingError` hierarchy
`@suaveplan/rate-limiter` (`workspace:^`)	Send rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createMessagingPlugin(config?: MessagingPluginConfig): PluginDescriptor
// Services: ThreadService, MessageService, ReactionService, ModerationService
// Routes: /messaging/threads, /messaging/threads/:id/messages,
//         /messaging/threads/:id/read, /messaging/threads/:id/typing

Error codes

type MessagingErrorCode =
  | "MESSAGING_THREAD_NOT_FOUND"
  | "MESSAGING_MESSAGE_NOT_FOUND"
  | "MESSAGING_NOT_PARTICIPANT"
  | "MESSAGING_SUPPRESSED"
  | "MESSAGING_ATTACHMENT_TOO_LARGE"
  | "MESSAGING_RATE_LIMITED"

File layout

api/comms/api-plugin-messaging/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (thread, thread_participant, message, reaction, read_receipt tables)
  src/
    index.ts  events.ts  types/  errors/
    services/thread/  services/message/  services/reaction/  services/moderation/
    routes/threads/  routes/messages/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/api-plugin-file-upload, @suaveplan/api-plugin-notifications, @suaveplan/suppression.

2.9 KiB Raw Blame History