Initial Commit
This commit is contained in:
198
openspec/changes/enterprise-contacts/proposal.md
Normal file
198
openspec/changes/enterprise-contacts/proposal.md
Normal file
@@ -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`.
|
||||
72
openspec/changes/enterprise-contacts/tasks.md
Normal file
72
openspec/changes/enterprise-contacts/tasks.md
Normal file
@@ -0,0 +1,72 @@
|
||||
# Tasks: enterprise-contacts
|
||||
|
||||
**Change ID**: enterprise-contacts
|
||||
**Package**: `@suaveplan/contacts`
|
||||
**Target path**: `universal/email/contacts`
|
||||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/dedup`, `@suaveplan/pagination`
|
||||
|
||||
---
|
||||
|
||||
## 0. Pre-flight (non-negotiable)
|
||||
|
||||
- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
|
||||
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
|
||||
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
|
||||
|
||||
## 1. Scaffold
|
||||
|
||||
- [ ] Create `universal/email/contacts/` with `src/`, `tests/`, `src/__benchmarks__/` and all feature subdirectories per the layout in `proposal.md`.
|
||||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, correct `exports` map, `dependencies`, and `devDependencies`.
|
||||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Types + errors
|
||||
|
||||
- [ ] `src/types/common.ts` — `Contact`, `EmailEntry`, `PhoneEntry`, `AddressEntry`, `ContactGroup`, `ContactCreateInput`, `ContactPatch`, `ContactFilter`, `SearchOptions`, `ImportOptions`, `ImportResult`, `DeduplicateOptions`, `DeduplicateResult`.
|
||||
- [ ] `src/types/common.md` (≥200 words, both examples, API reference).
|
||||
- [ ] `src/error-codes.ts` — `ContactErrorCode` (6 codes), metadata, register, eager call.
|
||||
- [ ] `src/types/schemas.ts` + `schemas.md` — Zod schemas.
|
||||
|
||||
---
|
||||
|
||||
## 3. Core modules
|
||||
|
||||
- [ ] **`src/core/memory-store/`** — `createMemoryContactStore(options)`: implements full `ContactStore` interface in memory. Optimistic concurrency: `update` checks `expectedVersion === stored.version`; mismatch throws `CONTACT_VERSION_CONFLICT`. Full-text search across `displayName`, `email[].value`, `phone[].value`. Tests: CRUD, version conflict, tag filtering, group assignment, search across all fields.
|
||||
- [ ] **`src/io/csv-import/`** — `importCsv(csv, options)`: maps CSV columns to `ContactCreateInput` fields; returns `ImportResult` (created, updated, failed counts). Tests: basic CSV, missing required column throws, UTF-8 display names.
|
||||
- [ ] **`src/io/vcard-import/`** — `importVcard(vcard)`: parses `BEGIN:VCARD…END:VCARD` blocks (VCard 3.0 and 4.0). Tests: VCard 3.0, VCard 4.0, multiple contacts in single string, missing FN falls back to N.
|
||||
- [ ] **`src/io/csv-export/`** — `exportCsv(filter)`: exports all matching contacts as RFC 4180 CSV. Round-trip test: export then re-import produces same contacts.
|
||||
- [ ] **`src/search/contact-search/`** — full-text scorer for in-memory search; trigram index for name fields. Tests: prefix match, substring match, multi-word query.
|
||||
|
||||
---
|
||||
|
||||
## 4. OTel instrumentation
|
||||
|
||||
- [ ] `create`, `update`, `delete`: individual spans `contact.create`, `contact.update`, `contact.delete`; counters `contact.create_total`, `contact.update_total`, `contact.delete_total`.
|
||||
- [ ] `search`: span `contact.search`; histogram `contact.search_duration_ms`; counter `contact.search_total`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Property-based tests (`tests/property.test.ts`)
|
||||
|
||||
- [ ] CSV export/import round-trip: for arbitrary arrays of `ContactCreateInput`, `exportCsv(importCsv(csv))` produces contacts with the same displayName and primary email.
|
||||
- [ ] Optimistic concurrency: concurrent updates to the same contact always serialise (one succeeds, others throw `CONTACT_VERSION_CONFLICT`).
|
||||
|
||||
---
|
||||
|
||||
## 6. Benchmarks (`src/__benchmarks__/contacts.bench.ts`)
|
||||
|
||||
- [ ] Full-text search over 10 000 contacts.
|
||||
- [ ] Bulk import of 1 000 contacts from CSV.
|
||||
|
||||
---
|
||||
|
||||
## 7. Docs + verify
|
||||
|
||||
- [ ] One `.md` per implementation file (≥200 words, both examples, API reference). Root `README.md`.
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/contacts` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/contacts` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/contacts`.
|
||||
- [ ] Archive: `openspec/archive/2026-04-24-enterprise-contacts/`.
|
||||
Reference in New Issue
Block a user