OpenSpec Change: enterprise-contacts

Change ID: enterprise-contacts
Package: @suaveplan/contacts
Category: universal
Target path: universal/email/contacts
Status: IN PROGRESS
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/contacts.md

Summary

Deliver @suaveplan/contacts on the genesis branch from scratch at enterprise quality. The package provides contact and group management: a typed Contact model with hierarchical group nesting, CRUD operations with optimistic concurrency (ETag-style version fields), deduplication via @suaveplan/dedup, tag-based filtering, CSV/VCard import-export, full-text search across name/email/phone fields, a ContactStore interface with an in-memory reference adapter, and event bus integration for change propagation. Genesis adds structured errors, Zod schemas, OTel instrumentation, and property-based tests.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`ContactError`; `CONTACT.*` error codes
`@suaveplan/types` (`workspace:^`)	`LoggerLike`, `Clock`, `EventBusLike`, `StorageLike`
`@suaveplan/events` (`workspace:^`)	Change event bus
`@suaveplan/dedup` (`workspace:^`)	Email/phone deduplication engine
`@suaveplan/pagination` (`workspace:^`)	Cursor/offset pagination for contact lists
`zod` (`catalog:forms`)	Schema validation
`@opentelemetry/api` (`catalog:observability`)	Spans + counters

Dev deps: vitest, @vitest/coverage-istanbul, fast-check (all catalog:testing).

Public API surface

Core types

interface Contact {
  id: string
  version: number          // optimistic concurrency
  firstName?: string
  lastName?: string
  displayName: string
  email: EmailEntry[]
  phone: PhoneEntry[]
  address: AddressEntry[]
  tags: string[]
  groupIds: string[]
  metadata: Record<string, unknown>
  createdAt: Date
  updatedAt: Date
}

interface EmailEntry {
  value: string
  label?: string           // 'work' | 'personal' | custom
  primary?: boolean
}

interface PhoneEntry {
  value: string
  label?: string
  primary?: boolean
}

interface AddressEntry {
  street?: string
  city?: string
  state?: string
  postalCode?: string
  country?: string
  label?: string
}

interface ContactGroup {
  id: string
  name: string
  parentId?: string        // hierarchical nesting
  contactCount: number
  createdAt: Date
}

`ContactStore`

interface ContactStore {
  create(data: ContactCreateInput): Promise<Contact>
  get(id: string): Promise<Contact | undefined>
  update(id: string, patch: ContactPatch, expectedVersion: number): Promise<Contact>
  delete(id: string): Promise<void>
  search(query: string, options?: SearchOptions): Promise<PaginatedResult<Contact>>
  list(filter?: ContactFilter, options?: ListOptions): Promise<PaginatedResult<Contact>>
  importCsv(csv: string, options?: ImportOptions): Promise<ImportResult>
  importVcard(vcard: string): Promise<ImportResult>
  exportCsv(filter?: ContactFilter): Promise<string>
  deduplicate(options?: DeduplicateOptions): Promise<DeduplicateResult>
}

function createMemoryContactStore(options?: MemoryStoreOptions): ContactStore

Error codes

type ContactErrorCode =
  | 'CONTACT_NOT_FOUND'
  | 'CONTACT_VERSION_CONFLICT'
  | 'CONTACT_DUPLICATE_EMAIL'
  | 'CONTACT_INVALID_EMAIL'
  | 'CONTACT_IMPORT_FAILED'
  | 'CONTACT_GROUP_NOT_FOUND'

Genesis additions

ContactError extends SuaveplanError with six stable codes.
Zod schemas for Contact, ContactGroup, EmailEntry, PhoneEntry, AddressEntry, ContactFilter, SearchOptions.
VCard 3.0/4.0 import — parses BEGIN:VCARD blocks into Contact records; exports contacts as VCard 4.0.
Deduplication — delegates to @suaveplan/dedup; surfaces a deduplicate() method returning merge candidates.
OTel instrumentation — spans on create, update, delete, search; counters contact.create_total, contact.search_total; histogram contact.search_duration_ms.
Property-based tests — CSV import/export round-trip, optimistic concurrency conflict detection.

File layout

universal/email/contacts/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/
      index.ts
    types/
      common.ts
      common.md
    core/
      contact-store/
        contact-store.ts
        contact-store.md
        contact-store.types.ts
        contact-store.test.ts
        index.ts
      memory-store/
        memory-store.ts
        memory-store.md
        memory-store.test.ts
        index.ts
    io/
      csv-import/
        csv-import.ts
        csv-import.md
        csv-import.test.ts
        index.ts
      vcard-import/
        vcard-import.ts
        vcard-import.md
        vcard-import.test.ts
        index.ts
      csv-export/
        csv-export.ts
        csv-export.md
        csv-export.test.ts
        index.ts
    search/
      contact-search/
        contact-search.ts
        contact-search.md
        contact-search.test.ts
        index.ts
    __benchmarks__/
      contacts.bench.ts
  tests/
    integration.test.ts
    property.test.ts

Impact

Downstream consumers: @suaveplan/campaigns, @suaveplan/audience-rules.

Workspace dep prerequisites: @suaveplan/error, @suaveplan/types, @suaveplan/events, @suaveplan/dedup, @suaveplan/pagination.

5.5 KiB Raw Permalink Blame History