Initial Commit

openspec/changes/enterprise-contacts/proposal.md

@@ -0,0 +1,198 @@
+# 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
+
+```ts
+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`
+
+```ts
+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
+
+```ts
+type ContactErrorCode =
+  | 'CONTACT_NOT_FOUND'
+  | 'CONTACT_VERSION_CONFLICT'
+  | 'CONTACT_DUPLICATE_EMAIL'
+  | 'CONTACT_INVALID_EMAIL'
+  | 'CONTACT_IMPORT_FAILED'
+  | 'CONTACT_GROUP_NOT_FOUND'
+```
+
+---
+
+## Genesis additions
+
+1. **`ContactError`** extends `SuaveplanError` with six stable codes.
+2. **Zod schemas** for `Contact`, `ContactGroup`, `EmailEntry`, `PhoneEntry`, `AddressEntry`, `ContactFilter`, `SearchOptions`.
+3. **VCard 3.0/4.0 import** — parses `BEGIN:VCARD` blocks into `Contact` records; exports contacts as VCard 4.0.
+4. **Deduplication** — delegates to `@suaveplan/dedup`; surfaces a `deduplicate()` method returning merge candidates.
+5. **OTel instrumentation** — spans on `create`, `update`, `delete`, `search`; counters `contact.create_total`, `contact.search_total`; histogram `contact.search_duration_ms`.
+6. **Property-based tests** — CSV import/export round-trip, optimistic concurrency conflict detection.
+
+---
+
+## File layout
+
+```text
+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`.