OpenSpec Change: enterprise-api-plugin-contacts

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

Summary

Deliver @suaveplan/api-plugin-contacts on the genesis branch from scratch at enterprise quality. Contact book plugin: contact CRUD, custom fields (arbitrary key/value), tags, lists, import/export (CSV via @suaveplan/password-formats CSV pattern), deduplication via @suaveplan/dedup, domain normalization via @suaveplan/domain-normalizer, GDPR consent tracking, and per-contact suppression status. Routes under /contacts. Per-table SurrealQL. Typed bus events: contacts:created, contacts:merged, contacts:deleted.

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/dedup` (`workspace:^`)	Duplicate detection + merge
`@suaveplan/domain-normalizer` (`workspace:^`)	Email domain normalization
`@suaveplan/suppression` (`workspace:^`)	Per-contact suppression
`@suaveplan/data-masking` (`workspace:^`)	PII masking on export
`@suaveplan/events` (`workspace:^`)	Event bus
`@suaveplan/error` (`workspace:^`)	`ContactsError` hierarchy
`@suaveplan/rate-limiter` (`workspace:^`)	Rate limits
`hono` + `@hono/zod-openapi` + `zod`	Routes
`@opentelemetry/api`	OTel

Public API surface

function createContactsPlugin(config?: ContactsPluginConfig): PluginDescriptor
// Services: ContactService, ListService, ImportService, ExportService, DeduplicationService
// Routes: /contacts, /contacts/:id, /contacts/import, /contacts/export,
//         /contacts/lists, /contacts/lists/:id, /contacts/:id/suppress

Error codes

type ContactsErrorCode =
  | "CONTACTS_NOT_FOUND"
  | "CONTACTS_DUPLICATE"
  | "CONTACTS_LIST_NOT_FOUND"
  | "CONTACTS_IMPORT_FAILED"
  | "CONTACTS_EXPORT_FAILED"

File layout

api/comms/api-plugin-contacts/
  package.json  tsconfig.json  vitest.config.ts
  surql/ (contact, contact_custom_field, contact_tag, contact_list, contact_list_member, gdpr_consent tables)
  src/
    index.ts  events.ts  types/  errors/
    services/contact/  services/list/  services/import/  services/export/  services/deduplication/
    routes/contacts/  routes/lists/
  tests/integration.test.ts

Impact

Prerequisites: @suaveplan/api, @suaveplan/api-plugin-auth, @suaveplan/api-plugin-database, @suaveplan/dedup, @suaveplan/domain-normalizer, @suaveplan/suppression, @suaveplan/data-masking.

2.9 KiB Raw Blame History