@classytic/crm 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to `@classytic/crm` are documented here.
+
+## [0.1.0] — 2026-04-18
+
+Initial release.
+
+### Added
+
+- **Eight domain entities.** `Contact`, `Account`, `Lead`, `Opportunity`, `Pipeline` (+ nested `Stage`), `Activity`, `Note`, `LossReason`.
+- **Three state machines.** Lead (`new` → `contacted` → `qualified` → `converted`, + `disqualified` / `nurturing` branches), Opportunity (`open` → `won` / `lost` / `abandoned` with in-pipeline Stage movement), Activity (`planned` → `in_progress` → `completed` / `cancelled`). All transitions CAS-guarded with explicit `*_TRANSITIONS` maps and `canTransition*` guards.
+- **Six services.**
+  - `ContactService` — CRUD + tag filtering + email lookup.
+  - `AccountService` — CRUD + domain lookup.
+  - `PipelineService` — create, archive, stage helpers (`getStage`, `getFirstStage`, `getNextStage`).
+  - `OpportunityService` — create at first stage (or specified), `moveToStage` with advance/regress event disambiguation, `win` / `lose` (with `lostReasonId`) / `abandon`.
+  - `LeadService` — CRUD + full lifecycle (`markContacted`, `qualify`, `disqualify`, `nurture`) + `convert()` — the crown-jewel verb that atomically creates Contact + Account + Opportunity and transitions the lead to `converted`.
+  - `ActivityService` — polymorphic activities (`plan`, `start`, `complete`, `cancel`) + notes (`addNote`, `listNotesBySubject`).
+- **Pure calculators.**
+  - `defaultLeadScorer` + `composeScorers(...rules)` — host injects whatever rubric (firmographics, in-app signals, ML prediction, enrichment) via a `(lead: Lead) => number` function.
+  - `forecast(opportunities, options?)` — committed + weighted pipeline by bucket (default ISO month), with custom bucket function support. Currency-mismatch detection.
+  - `pipelineConversion(opportunities, stageIds)` — where do deals die? returns per-stage current count + won/lost counts + conversion rate.
+- **Nine repository ports** — one per entity (plus `EventTransport`, `IdGenerator`, `Clock`, optional `OutreachPort`). Full in-memory reference implementations shipped.
+- **Typed error hierarchy** rooted at `CrmError`: `NotFoundError`, `InvalidLeadTransitionError`, `InvalidOpportunityTransitionError`, `InvalidActivityTransitionError`, `StageNotInPipelineError`, `LeadAlreadyConvertedError`, `DuplicateLeadError`, `EmptyPipelineError`.
+- **Nineteen lifecycle events** (`CRM_EVENTS`): covering lead/account/contact/opportunity/pipeline/activity/note verbs, all following `crm:<resource>.<verb>` per PACKAGE_RULES rule 12.
+- **Optional `OutreachPort`** — one-method (`send`) + `NullOutreachPort` + `InMemoryOutreachPort` (recording). Host subscribes to `crm:activity.*` events and drives the port from their automation layer (keeps pacing / retry / bounce handling out of the core).
+- **Testing.** `vitest.config.ts` projects split `unit` + `integration` per [testing-infrastructure.md](../../testing-infrastructure.md). 48 tests (7 files) — all green in <1.5s.
+
+### Design choices
+
+- Pure-TS port-based pattern — consistent with `@classytic/manufacturing`, `@classytic/assets`, `@classytic/fleet`, `@classytic/carrier-*`.
+- Separate Lead + Opportunity models (erpnext style) rather than unified (odoo style) — cleaner semantics for pre-qualification vs in-pipeline data and enables distinct analytics.
+- Polymorphic Activity / Note via `subjectKind` + `subjectId` so hosts can extend without schema changes.
+- `LeadService.convert()` is atomic in intent and sequenced for auditability — it creates Account, then Contact, then Opportunity, then transitions the lead. If a downstream repo fails, the ones that succeeded persist (hosts using Mongoose sessions get atomicity at their layer).
+- Campaigns, appointment booking, competitors, contracts, team routing, RBAC, custom-field validation, email-thread parsing deferred to v0.2+ to keep the surface focused.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Classytic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# @classytic/crm
+
+Framework-agnostic CRM primitive for Node.js + Bun — the base to build
+the next Pipedrive, HubSpot, Salesforce, or Buffer-style outreach
+automation on top of.
+
+- **Pure TypeScript.** No Mongo, no HTTP, no framework dep.
+- **Event-driven.** 19 lifecycle events out of the box — any
+  subscribing automation layer plugs in without modifying the core.
+- **Port-based storage.** Plug in Mongoose / Prisma / your existing
+  data store per entity (8 repo interfaces, 1 optional outreach
+  bridge). In-memory reference implementations shipped for tests +
+  standalone use.
+- **Atomic state transitions.** Every lead / opportunity / activity
+  status change goes through a CAS against the expected status.
+- **Pluggable lead scoring.** `defaultLeadScorer` is replaceable with
+  `composeScorers(...rules)` or any `(lead: Lead) => number`.
+- **Forecast + pipeline-conversion analytics.** Pure functions over
+  opportunity lists — safe to run in any context.
+- **Polymorphic activities + notes.** Attach to Lead, Opportunity,
+  Contact, or Account. Automation subscribes to `crm:activity.*` and
+  does its thing — email, SMS, calendar booking, Slack ping, LLM
+  summary.
+
+## Why this matters for the Node / Bun community
+
+Most CRMs ship as monolithic apps. This package is the **headless
+engine** — it owns the entities, state machines, events, and
+analytics, and gets out of your way on everything else. Want a
+Buffer-style scheduled-outreach app? Subscribe to `crm:activity.planned`
+with `type: 'email'`, queue the send. Want an AI-written follow-up
+layer? Subscribe to `crm:opportunity.stage_advanced`, call an LLM,
+`activities.plan(...)` the generated task. None of that lives in this
+package; all of it is unblocked by it.
+
+## Install
+
+```bash
+npm install @classytic/crm
+```
+
+`@classytic/primitives` is the only peer (for `Money`).
+
+## Full lead-to-customer flow
+
+```ts
+import {
+  AccountService,
+  ActivityService,
+  ContactService,
+  LeadService,
+  OpportunityService,
+  PipelineService,
+  InMemoryAccountRepository,
+  InMemoryActivityRepository,
+  InMemoryContactRepository,
+  InMemoryLeadRepository,
+  InMemoryNoteRepository,
+  InMemoryOpportunityRepository,
+  InMemoryPipelineRepository,
+  InMemoryEventTransport,
+} from '@classytic/crm';
+
+const events = new InMemoryEventTransport();
+
+const accounts = new AccountService({ repo: new InMemoryAccountRepository(), events });
+const contacts = new ContactService({ repo: new InMemoryContactRepository(), events });
+const pipelines = new PipelineService({ repo: new InMemoryPipelineRepository(), events });
+const opportunities = new OpportunityService({
+  repo: new InMemoryOpportunityRepository(),
+  pipelines,
+  events,
+});
+const leads = new LeadService({
+  repo: new InMemoryLeadRepository(),
+  contacts,
+  accounts,
+  opportunities,
+  events,
+});
+const activities = new ActivityService({
+  repo: new InMemoryActivityRepository(),
+  notes: new InMemoryNoteRepository(),
+  events,
+});
+
+// Pipeline setup.
+const pipeline = await pipelines.create({
+  name: 'New Business',
+  stages: [
+    { name: 'Prospecting', sequence: 1, defaultProbability: 0.1 },
+    { name: 'Discovery',   sequence: 2, defaultProbability: 0.3 },
+    { name: 'Proposal',    sequence: 3, defaultProbability: 0.6 },
+    { name: 'Negotiation', sequence: 4, defaultProbability: 0.8 },
+  ],
+});
+
+// Inbound lead.
+const lead = await leads.create({
+  email: 'alex@acme.co',
+  firstName: 'Alex',
+  lastName: 'Rivera',
+  companyName: 'Acme',
+  jobTitle: 'Director',
+  source: 'web-form',
+});
+
+// Qualify + convert — spawns Contact + Account + Opportunity atomically.
+await leads.markContacted(lead.id);
+await leads.qualify(lead.id);
+const { opportunityId } = await leads.convert(lead.id, {
+  pipelineId: pipeline.id,
+  amount: { amount: 120_000, currency: 'USD' },
+  expectedCloseAt: new Date('2026-06-30'),
+});
+
+// Move through pipeline.
+await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[1]!.id });
+await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[2]!.id });
+await opportunities.moveToStage(opportunityId, { stageId: pipeline.stages[3]!.id });
+
+// Close as won.
+await opportunities.win(opportunityId, { amount: { amount: 125_000, currency: 'USD' } });
+```
+
+## State machines
+
+```
+Lead:         new → contacted → qualified → converted
+                ↘        ↘           ↘
+                 disqualified / nurturing ←──────┐
+                                                  │
+                                                  (nurturing → contacted/qualified)
+
+Opportunity:  open → won | lost | abandoned  (terminal)
+              (stage movement happens while open)
+
+Activity:     planned → in_progress → completed
+                ↘            ↘
+                 cancelled (from any non-terminal)
+```
+
+Each transition is CAS-guarded and appends to the record's
+`statusHistory`. Invalid transitions throw typed errors.
+
+## Lead scoring
+
+`LeadService` runs the scorer on `create` and on-demand via
+`recomputeScore(id)`. Replace the default with your own:
+
+```ts
+import { LeadService, composeScorers } from '@classytic/crm';
+
+const scorer = composeScorers(
+  (l) => (l.email ? 20 : 0),
+  (l) => (l.source === 'referral' ? 30 : 0),
+  (l) => (l.tags?.includes('enterprise') ? 50 : 0),
+  (l) => (/ceo|cto|founder/i.test(l.jobTitle ?? '') ? 40 : 0),
+  // Plug in ML / enrichment predictions:
+  (l) => myEnricher.scoreFor(l),
+);
+
+new LeadService({ repo, contacts, accounts, opportunities, scorer });
+```
+
+## Forecast + pipeline conversion
+
+```ts
+import { forecast, pipelineConversion } from '@classytic/crm';
+
+const open = await opportunities.list({ status: 'open' });
+const rows = forecast(open); // default: ISO-month buckets
+// [{ bucket: '2026-06', committed: 120_000, weighted: 96_000, count: 1, currency: 'USD' }]
+
+// Custom buckets (quarters, fiscal years, per-team, …):
+forecast(open, { bucket: (o) => quarterOf(o.expectedCloseAt!) });
+
+// Funnel analysis: where do deals die?
+const all = await opportunities.list();
+const conv = pipelineConversion(all, pipeline.stages.map((s) => s.id));
+```
+
+## Activities + notes (polymorphic)
+
+Attach to any entity via `subjectKind` + `subjectId`:
+
+```ts
+await activities.plan({
+  type: 'email',
+  subjectKind: 'lead',
+  subjectId: lead.id,
+  subject: 'Follow-up on demo',
+  scheduledAt: new Date('2026-04-20T15:00:00Z'),
+  ownerId: 'ae_1',
+});
+
+// Quick note on an opportunity:
+await activities.addNote({
+  subjectKind: 'opportunity',
+  subjectId: opp.id,
+  body: 'Champion confirmed — legal review starts Monday.',
+  authorId: 'ae_1',
+});
+
+// Pull everything for an entity:
+const allActivities = await activities.listBySubject('opportunity', opp.id);
+const allNotes = await activities.listNotesBySubject('opportunity', opp.id);
+```
+
+## Events catalog
+
+Subscribe via `EventTransport` from `@classytic/primitives/events`
+(the same contract mirrored from Arc) — Arc's bus, Redis, in-memory,
+Kafka, or any transport implementing that shape works.
+
+| Event | When |
+|---|---|
+| `crm:lead.created` | new lead |
+| `crm:lead.status_changed` | any transition |
+| `crm:lead.scored` | score recomputed |
+| `crm:lead.converted` | spawns Contact + Account + Opportunity |
+| `crm:lead.disqualified` | with reason |
+| `crm:account.created` / `updated` | |
+| `crm:contact.created` / `updated` | |
+| `crm:opportunity.created` | |
+| `crm:opportunity.stage_advanced` | forward motion |
+| `crm:opportunity.stage_regressed` | backward motion (slip) |
+| `crm:opportunity.won` / `lost` / `abandoned` | |
+| `crm:pipeline.created` / `archived` | |
+| `crm:activity.planned` / `completed` / `cancelled` | |
+| `crm:note.added` | |
+
+This event surface is the extension plane — automation tools
+subscribe with globs (`crm:*`, `crm:lead.*`) and do their thing
+without touching the core package.
+
+## Optional outreach bridge
+
+`OutreachPort` is a one-method interface for sending email / SMS /
+social. The package doesn't call it automatically — wire it in your
+automation layer:
+
+```ts
+import { CRM_EVENTS } from '@classytic/crm';
+
+events.subscribe(CRM_EVENTS.ACTIVITY_PLANNED, async (event) => {
+  const { activityId } = event.payload as { activityId: string };
+  const activity = await activities.findById(activityId);
+  if (activity?.type !== 'email' || !activity.metadata?.toAddress) return;
+  await outreach.send({
+    channel: 'email',
+    toAddress: activity.metadata.toAddress,
+    subject: activity.subject,
+    body: activity.body!,
+    activityId: activity.id,
+  });
+  await activities.complete(activity.id);
+});
+```
+
+`InMemoryOutreachPort` records sends for tests; `NullOutreachPort` is
+a no-op; real integrations wrap SendGrid, Postmark, Twilio, or an
+in-house provider.
+
+## What v0.1 does NOT include
+
+Kept off v0.1 to ship a focused surface — each is small to bolt on
+via the event system:
+
+- Campaigns / sequences (build via activity templates + cron).
+- Territory / team routing (ownership fields are there — use them).
+- Appointment booking (host integrates calendar).
+- Email thread parsing (host integrates inbox).
+- Custom-field schema validation (host owns the `metadata` map).
+- Role-based access control (host owns auth).
+- Audit log (host subscribes to events + persists).
+- Competitor tracking (free-form metadata for now).
+- Contract management (out of scope — use an invoicing package).
+
+## Architecture
+
+```
+src/
+├── index.ts                          ← main barrel
+├── domain/
+│   ├── entities/                     ← Account, Contact, Lead, Opportunity, Pipeline,
+│   │                                    Activity, Note, LossReason
+│   ├── enums/                        ← lead-status, opportunity-status, activity (+ subject-kinds)
+│   ├── ports/                        ← 8 repo ports + OutreachPort + Clock + Ids
+│   └── errors.ts
+├── adapters/in-memory/               ← reference repos + null/recording outreach + events + ids
+├── services/
+│   ├── account.service.ts
+│   ├── activity.service.ts           ← activities + notes
+│   ├── contact.service.ts
+│   ├── lead.service.ts               ← includes convert() — crown-jewel verb
+│   ├── opportunity.service.ts        ← stage movement + win/lose/abandon
+│   ├── pipeline.service.ts
+│   ├── scoring.ts                    ← pure lead scorer + composeScorers
+│   └── forecast.ts                   ← pure forecast() + pipelineConversion()
+└── events/
+    └── event-constants.ts            ← CRM_EVENTS
+```
+
+## Tests
+
+48 tests across unit + integration:
+
+```bash
+npm test                    # unit + integration (default)
+npm run test:unit
+npm run test:integration
+```
+
+The integration scenario in [tests/integration/lead-to-customer.test.ts](tests/integration/lead-to-customer.test.ts)
+is the MOVEMENTS.md §7 gate: **lead → opportunity → customer end-to-end** —
+walks the full happy path, the lost-path, and the nurture-then-requalify
+path, asserting cross-entity links, event order, and forecast roll-up.
+
+## License
+
+MIT