suaveplan/openspec/changes/enterprise-api-plugin-social/proposal.md

OpenSpec Change: enterprise-api-plugin-social

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

---

Summary

Deliver @suaveplan/api-plugin-social on the genesis branch from scratch at enterprise quality. Social graph plugin: follow/unfollow, follower/following lists, activity feed (fan-out on write with configurable fanout limit), likes, comments, shares, content reporting, and a blocking/muting system. Routes under /social. Per-table SurrealQL. Typed bus events: social:followed, social:post:liked, social:comment:created, social:user:blocked.

---

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-notifications (workspace:^)	Notify on follow/like/comment
@suaveplan/events (workspace:^)	Event bus
@suaveplan/error (workspace:^)	SocialError hierarchy
@suaveplan/rate-limiter (workspace:^)	Rate limits
hono + @hono/zod-openapi + zod	Routes
@opentelemetry/api	OTel

---

Public API surface

function createSocialPlugin(config?: SocialPluginConfig): PluginDescriptor
// Services: FollowService, FeedService, LikeService, CommentService, ReportService, BlockService
// Routes: /social/follow, /social/followers, /social/following,
//         /social/feed, /social/posts/:id/like, /social/posts/:id/comments,
//         /social/block, /social/report

Error codes

type SocialErrorCode =
  | "SOCIAL_USER_NOT_FOUND"
  | "SOCIAL_ALREADY_FOLLOWING"
  | "SOCIAL_NOT_FOLLOWING"
  | "SOCIAL_BLOCKED"
  | "SOCIAL_POST_NOT_FOUND"
  | "SOCIAL_COMMENT_NOT_FOUND"

---

File layout

api/comms/api-plugin-social/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (follow, feed_item, like, comment, block, report tables)
  src/
    index.ts  events.ts  types/  errors/
    services/follow/  services/feed/  services/like/  services/comment/
    services/block/  services/report/
    routes/social/
  tests/integration.test.ts

---

Impact

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