@classytic/crm 0.9.0 → 1.1.0

package/LICENSE

@@ -1,21 +1,75 @@
-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.
+Classytic Source-Available License (Community & Commercial), Version 1.0
+
+Copyright (c) 2026 Classytic LLC. All rights reserved.
+
+This software is source-available, not open source. Please read this License
+before using it.
+
+1. DEFINITIONS
+   "Software" means the contents of this package and any accompanying source
+   code, object code, or documentation, in any form.
+   "Licensor" means Classytic LLC, a limited liability company organized in the
+   United States.
+   "You" means the individual or legal entity exercising rights under this
+   License.
+   "Evaluation Use" means use for evaluation, development, testing,
+   experimentation, or internal non-commercial purposes only.
+   "Production Use" means any use of the Software that is live, commercial,
+   revenue-generating, or customer-facing, or any use other than Evaluation Use.
+   "Commercial License" means a separate written agreement executed with
+   Licensor that grants Production Use rights.
+
+2. OWNERSHIP
+   The Software is licensed, not sold. Licensor retains all right, title, and
+   interest in and to the Software, including all intellectual property rights.
+   All rights not expressly granted in this License are reserved by Licensor.
+
+3. EVALUATION GRANT
+   Subject to Your compliance with this License, Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable, revocable license
+   to download, install, run, and modify the Software solely for Evaluation Use.
+
+4. PRODUCTION USE REQUIRES A COMMERCIAL LICENSE
+   Production Use of the Software is NOT permitted under this License and
+   requires a Commercial License from Licensor. A Commercial License may be
+   granted at Licensor's discretion, with or without a fee, and may confer
+   perpetual, irrevocable, and transferable Production Use rights as set out in
+   that agreement. Contact licensing@classytic.com to obtain one.
+
+5. RESTRICTIONS
+   You may not:
+   (a) make any Production Use of the Software without a Commercial License;
+   (b) redistribute, resell, rent, sublicense, or otherwise make the Software
+       (in whole or in part, original or modified) available to third parties as
+       a stand-alone product, framework, library, or hosted/managed service that
+       competes with the Software or with Licensor;
+   (c) remove, obscure, or alter any copyright, license, or attribution notice.
+
+6. FEEDBACK AND CONTRIBUTIONS
+   Any feedback, suggestions, or contributions You provide relating to the
+   Software may be used by Licensor for any purpose without obligation to You.
+
+7. TERMINATION
+   This License and the Evaluation Grant terminate automatically if You breach
+   any term. Upon termination You must cease all use of the Software and destroy
+   all copies in Your possession. Rights under a Commercial License are governed
+   by that agreement's own terms and survive termination of this License to the
+   extent stated there.
+
+8. DISCLAIMER OF WARRANTY
+   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.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR 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.
+
+10. GOVERNING LAW
+   This License is governed by the laws of the State of Delaware, United States,
+   without regard to its conflict-of-laws principles. (Adjust to Your LLC's state
+   of formation.)
+
+For commercial licensing, contact: licensing@classytic.com

package/README.md

@@ -39,8 +39,57 @@ and conversation/message threads. Built on **Mongoose + @classytic/mongokit
 npm install @classytic/crm
 ```
 
-Peers: `@classytic/mongokit >=3.16.0`, `@classytic/repo-core >=0.6.0`,
-`@classytic/primitives >=0.7.1`, `mongoose >=9.4.1`, `zod >=4.0.0`.
+Peers: `@classytic/contact >=0.1.0`, `@classytic/mongokit >=3.30.0`,
+`@classytic/repo-core >=0.13.0`, `@classytic/primitives >=0.14.0`,
+`mongoose >=9.4.1`, `zod >=4.0.0`.
+
+`@classytic/contact` is the email/phone identity kernel. It is a **peer**, not a
+dependency, so npm cannot nest a second copy and break `instanceof` across the
+boundary — the same reason `@classytic/party` declares it that way. This package
+imports `@classytic/contact/email` directly at one place, the suppression list.
+
+## The suppression list is keyed CANONICALLY
+
+`SuppressionRepository` is the org-wide do-not-contact list a host consults before
+every outbound email. Its key is whatever `normalizeEmail` from
+`@classytic/contact/email` returns: trimmed, both sides lowercased, **and the
+domain IDNA-folded to punycode**. `ada@bücher.de` is stored, matched and returned
+as `ada@xn--bcher-kva.de`.
+
+Two consequences for a host:
+
+```ts
+import { suppressionEmailKey } from '@classytic/crm';
+
+// filterSuppressed() returns CANONICAL keys — canonicalise your own recipient
+// before testing membership. Matching on the raw spelling is the original bug.
+const blocked = await crm.repositories.suppression.filterSuppressed(recipients, ctx);
+const sendable = recipients.filter((e) => !blocked.has(suppressionEmailKey(e) ?? e));
+```
+
+- **Writes refuse what they cannot canonicalise.** `suppress()` and `unsuppress()`
+  throw `SuppressionEmailFormatError` (400). A malformed address stored verbatim is
+  a do-not-contact record that can never match a send — it suppresses nothing while
+  reporting success.
+- **Reads fail closed.** `isSuppressed()` answers `true`, and `filterSuppressed()`
+  reports as blocked, for an address with no canonical form. The permissive answer
+  would send mail to an address we could not parse; the conservative answer costs
+  one undeliverable message. They do not throw, because one malformed recipient must
+  not abort a fanout to thousands of valid ones. `suppressionEmailKey()` returns
+  `null` for such an address if you need to tell it apart from a real suppression.
+
+**Upgrading from a version before this rule:** rows written under the old
+`trim().toLowerCase()` key may no longer be reachable. Report — do not migrate —
+with the read-only script:
+
+```bash
+node node_modules/@classytic/crm/scripts/suppression-key-drift.mjs "$MONGO_URI"
+```
+
+It classifies every row as `unchanged` / `rekey` / `collision` / `uncanonicalisable`
+and writes nothing. `collision` rows cannot be moved by an `updateOne` at all — the
+`(organizationId, email)` index is unique and another row already holds the target
+key, so which `reason` and `suppressedAt` survive is a human decision.
 
 ## Quick start
 
@@ -50,7 +99,7 @@ import { createCrm, LeadService } from '@classytic/crm';
 
 const crm = await createCrm({
   connection: mongoose.connection,
-  tenantFieldType: 'objectId', // matches Better Auth orgs; 'string' for UUID hosts
+  tenant: { fieldType: 'objectId' }, // matches Better Auth orgs; 'string' for UUID hosts
 });
 
 const ctx = { organizationId: orgId };

package/dist/events.d.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
-import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
-import * as _$mongoose from "mongoose";
+import { DomainEvent, EventMeta } from "@classytic/primitives/events";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
+import "mongoose";
+import "@classytic/mongokit";
 import { OperationContext } from "@classytic/primitives/context";
+import "@classytic/primitives/outbox";
+import "@classytic/repo-core/tenant";
 //#region src/events/event-constants.d.ts
 /** PACKAGE_RULES rule 12: `package:resource.verb`. */
 declare const CRM_EVENTS: {
@@ -54,9 +58,11 @@ declare const CRM_EVENTS: {
   readonly EMAIL_EVENT_UNSUBSCRIBED: "crm:email_event.unsubscribed";
   readonly LEAD_ENRICHED: "crm:lead.enriched";
   readonly LEAD_ASSIGNED: "crm:lead.assigned";
+  readonly LEAD_ANONYMIZED: "crm:lead.anonymized";
   readonly CONTACT_ENRICHED: "crm:contact.enriched";
   readonly CONTACT_ASSIGNED: "crm:contact.assigned";
   readonly CONTACT_MERGED: "crm:contact.merged";
+  readonly CONTACT_ANONYMIZED: "crm:contact.anonymized";
   readonly ACCOUNT_ENRICHED: "crm:account.enriched";
   readonly ACCOUNT_ASSIGNED: "crm:account.assigned";
   readonly ACCOUNT_MERGED: "crm:account.merged";
@@ -122,6 +128,10 @@ declare const LeadAssigned: CrmEventDefinition<z.ZodObject<{
   ownerId: z.ZodString;
   previousOwnerId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>>;
+declare const LeadAnonymized: CrmEventDefinition<z.ZodObject<{
+  leadId: z.ZodString;
+  fields: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
 declare const AccountCreated: CrmEventDefinition<z.ZodObject<{
   accountId: z.ZodString;
   name: z.ZodString;
@@ -172,6 +182,10 @@ declare const ContactMerged: CrmEventDefinition<z.ZodObject<{
     preferSecondary: "preferSecondary";
   }>;
 }, z.core.$strip>>;
+declare const ContactAnonymized: CrmEventDefinition<z.ZodObject<{
+  contactId: z.ZodString;
+  fields: z.ZodArray<z.ZodString>;
+}, z.core.$strip>>;
 declare const OpportunityCreated: CrmEventDefinition<z.ZodObject<{
   opportunityId: z.ZodString;
   pipelineId: z.ZodString;
@@ -450,8 +464,8 @@ interface CrmLogger {
  * `metadata?` field — keep the typed surface tight.
  */
 interface CrmContext extends OperationContext {
-  organizationId?: string | _$mongoose.Types.ObjectId;
-  actorId?: string | _$mongoose.Types.ObjectId;
+  organizationId?: string | import('mongoose').Types.ObjectId;
+  actorId?: string | import('mongoose').Types.ObjectId;
   /** Mongo transaction session (passed through to mongokit). */
   session?: unknown;
 }
@@ -460,16 +474,10 @@ interface CrmContext extends OperationContext {
 declare function createEvent<T>(type: string, payload: T, ctx?: CrmContext, meta?: Partial<EventMeta>): DomainEvent<T>;
 //#endregion
 //#region src/events/in-process-bus.d.ts
-declare class InProcessCrmBus implements EventTransport {
-  readonly name = "in-process-crm";
-  private subs;
-  private logger?;
+declare class InProcessCrmBus extends InProcessEventBus {
   constructor(options?: {
     logger?: CrmLogger;
   });
-  publish(event: DomainEvent): Promise<void>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
 }
 //#endregion
-export { AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRescheduled, CRM_EVENTS, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignResumed, ContactAssigned, ContactCreated, ContactEnriched, ContactMerged, ContactUpdated, ConversationAssigned, ConversationCreated, ConversationReopened, ConversationResolved, CrmEventDefinition, CrmEventName, CrmEventSchema, EmailEventBounced, EmailEventClicked, EmailEventComplained, EmailEventOpened, EmailEventUnsubscribed, EnrollmentCompleted, EnrollmentCreated, EnrollmentExited, EnrollmentPaused, EnrollmentResumed, EnrollmentStepSent, InProcessCrmBus, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEnriched, LeadScored, LeadStatusChanged, MessageReceived, MessageSent, NoteAdded, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityLost, OpportunityStageAdvanced, OpportunityStageRegressed, OpportunityWon, PipelineArchived, PipelineCreated, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionUnsubscribed, SuppressionAdded, SuppressionRemoved, createEvent, crmEventDefinitions };
+export { AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRescheduled, CRM_EVENTS, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignResumed, ContactAnonymized, ContactAssigned, ContactCreated, ContactEnriched, ContactMerged, ContactUpdated, ConversationAssigned, ConversationCreated, ConversationReopened, ConversationResolved, CrmEventDefinition, CrmEventName, CrmEventSchema, EmailEventBounced, EmailEventClicked, EmailEventComplained, EmailEventOpened, EmailEventUnsubscribed, EnrollmentCompleted, EnrollmentCreated, EnrollmentExited, EnrollmentPaused, EnrollmentResumed, EnrollmentStepSent, InProcessCrmBus, LeadAnonymized, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEnriched, LeadScored, LeadStatusChanged, MessageReceived, MessageSent, NoteAdded, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityLost, OpportunityStageAdvanced, OpportunityStageRegressed, OpportunityWon, PipelineArchived, PipelineCreated, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionUnsubscribed, SuppressionAdded, SuppressionRemoved, createEvent, crmEventDefinitions };

package/dist/events.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { createEvent as createEvent$1, matchEventPattern } from "@classytic/primitives/events";
+import { createEvent as createEvent$1 } from "@classytic/primitives/events";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
 //#region src/events/event-constants.ts
 /** PACKAGE_RULES rule 12: `package:resource.verb`. */
 const CRM_EVENTS = {
@@ -52,9 +53,11 @@ const CRM_EVENTS = {
 	EMAIL_EVENT_UNSUBSCRIBED: "crm:email_event.unsubscribed",
 	LEAD_ENRICHED: "crm:lead.enriched",
 	LEAD_ASSIGNED: "crm:lead.assigned",
+	LEAD_ANONYMIZED: "crm:lead.anonymized",
 	CONTACT_ENRICHED: "crm:contact.enriched",
 	CONTACT_ASSIGNED: "crm:contact.assigned",
 	CONTACT_MERGED: "crm:contact.merged",
+	CONTACT_ANONYMIZED: "crm:contact.anonymized",
 	ACCOUNT_ENRICHED: "crm:account.enriched",
 	ACCOUNT_ASSIGNED: "crm:account.assigned",
 	ACCOUNT_MERGED: "crm:account.merged",
@@ -194,6 +197,15 @@ const LeadAssigned = defineCrmEvent({
 	description: "assign() (re)assigned the lead owner.",
 	zodSchema: z.object({ leadId: z.string() }).extend(ownerChangeSchema.shape)
 });
+const LeadAnonymized = defineCrmEvent({
+	name: CRM_EVENTS.LEAD_ANONYMIZED,
+	resource: "lead",
+	description: "anonymize() scrubbed a lead's PII (name/email/phone) in place — GDPR right-to-erasure. Non-PII aggregates (score/status/engagement) and the id are preserved; `anonymizedAt` tombstones the row.",
+	zodSchema: z.object({
+		leadId: z.string(),
+		fields: z.array(z.string())
+	})
+});
 const AccountCreated = defineCrmEvent({
 	name: CRM_EVENTS.ACCOUNT_CREATED,
 	resource: "account",
@@ -260,6 +272,15 @@ const ContactMerged = defineCrmEvent({
 	description: "merge() folded a secondary contact into the primary; secondary deleted.",
 	zodSchema: mergeSchema
 });
+const ContactAnonymized = defineCrmEvent({
+	name: CRM_EVENTS.CONTACT_ANONYMIZED,
+	resource: "contact",
+	description: "anonymize() scrubbed a contact's PII (name + every contact channel) in place — GDPR right-to-erasure. Non-PII aggregates (accountId, ownerId, tags) and the id are preserved; `anonymizedAt` tombstones the row.",
+	zodSchema: z.object({
+		contactId: z.string(),
+		fields: z.array(z.string())
+	})
+});
 const OpportunityCreated = defineCrmEvent({
 	name: CRM_EVENTS.OPPORTUNITY_CREATED,
 	resource: "opportunity",
@@ -715,6 +736,7 @@ const crmEventDefinitions = [
 	LeadDisqualified,
 	LeadEnriched,
 	LeadAssigned,
+	LeadAnonymized,
 	AccountCreated,
 	AccountUpdated,
 	AccountEnriched,
@@ -725,6 +747,7 @@ const crmEventDefinitions = [
 	ContactEnriched,
 	ContactAssigned,
 	ContactMerged,
+	ContactAnonymized,
 	OpportunityCreated,
 	OpportunityStageAdvanced,
 	OpportunityStageRegressed,
@@ -800,38 +823,25 @@ function createEvent(type, payload, ctx, meta) {
 //#region src/events/in-process-bus.ts
 /**
 * In-process event bus — default fallback when no `eventTransport` is
-* provided to `createCrm`. Structurally identical to arc's
-* `MemoryEventTransport`; pattern matching is delegated to primitives.
-* Handler errors are swallowed — event emission never blocks writes.
+* provided to `blueprint.bind(connection, runtime)`.
+*
+* A thin subclass of `@classytic/primitives/event-infra`'s shared
+* `InProcessEventBus`. Prior semantics preserved: glob matching via
+* `matchEventPattern`, per-handler error isolation, idempotent `close()`.
+* CRM historically SWALLOWED handler errors when no logger was supplied —
+* that default is preserved by passing `logger: null` unless the host
+* injects a `CrmLogger`, whose structured `error(msg, meta)` slot is
+* bridged onto the shared error-logger contract.
 */
-var InProcessCrmBus = class {
-	name = "in-process-crm";
-	subs = [];
-	logger;
+var InProcessCrmBus = class extends InProcessEventBus {
 	constructor(options) {
-		if (options?.logger) this.logger = options.logger;
-	}
-	async publish(event) {
-		const matching = this.subs.filter((s) => matchEventPattern(s.pattern, event.type));
-		for (const sub of matching) try {
-			await sub.handler(event);
-		} catch (err) {
-			this.logger?.error?.(`[crm] event handler error [${event.type}]`, { error: err instanceof Error ? err.message : String(err) });
-		}
-	}
-	async subscribe(pattern, handler) {
-		const sub = {
-			pattern,
-			handler
-		};
-		this.subs.push(sub);
-		return () => {
-			this.subs = this.subs.filter((s) => s !== sub);
-		};
-	}
-	async close() {
-		this.subs = [];
+		const crmLogger = options?.logger;
+		super({
+			name: "in-process-crm",
+			logLabel: "crm",
+			logger: crmLogger?.error ? { error: (message, ...args) => crmLogger.error?.(message, { args }) } : null
+		});
 	}
 };
 //#endregion
-export { AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRescheduled, CRM_EVENTS, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignResumed, ContactAssigned, ContactCreated, ContactEnriched, ContactMerged, ContactUpdated, ConversationAssigned, ConversationCreated, ConversationReopened, ConversationResolved, EmailEventBounced, EmailEventClicked, EmailEventComplained, EmailEventOpened, EmailEventUnsubscribed, EnrollmentCompleted, EnrollmentCreated, EnrollmentExited, EnrollmentPaused, EnrollmentResumed, EnrollmentStepSent, InProcessCrmBus, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEnriched, LeadScored, LeadStatusChanged, MessageReceived, MessageSent, NoteAdded, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityLost, OpportunityStageAdvanced, OpportunityStageRegressed, OpportunityWon, PipelineArchived, PipelineCreated, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionUnsubscribed, SuppressionAdded, SuppressionRemoved, createEvent, crmEventDefinitions };
+export { AccountAssigned, AccountCreated, AccountEnriched, AccountMerged, AccountUpdated, ActivityCancelled, ActivityCompleted, ActivityOutcomeRecorded, ActivityPlanned, ActivityRescheduled, CRM_EVENTS, CampaignActivated, CampaignArchived, CampaignCompleted, CampaignCreated, CampaignPaused, CampaignResumed, ContactAnonymized, ContactAssigned, ContactCreated, ContactEnriched, ContactMerged, ContactUpdated, ConversationAssigned, ConversationCreated, ConversationReopened, ConversationResolved, EmailEventBounced, EmailEventClicked, EmailEventComplained, EmailEventOpened, EmailEventUnsubscribed, EnrollmentCompleted, EnrollmentCreated, EnrollmentExited, EnrollmentPaused, EnrollmentResumed, EnrollmentStepSent, InProcessCrmBus, LeadAnonymized, LeadAssigned, LeadConverted, LeadCreated, LeadDisqualified, LeadEnriched, LeadScored, LeadStatusChanged, MessageReceived, MessageSent, NoteAdded, OpportunityAbandoned, OpportunityAmountChanged, OpportunityAssigned, OpportunityCreated, OpportunityExtended, OpportunityLost, OpportunityStageAdvanced, OpportunityStageRegressed, OpportunityWon, PipelineArchived, PipelineCreated, SequenceActivated, SequenceArchived, SequenceCreated, SequencePaused, SubscriptionBounced, SubscriptionComplained, SubscriptionConfirmed, SubscriptionCreated, SubscriptionUnsubscribed, SuppressionAdded, SuppressionRemoved, createEvent, crmEventDefinitions };