@classytic/party 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 All notable changes to `@classytic/party` are documented here. Adheres to
 [Keep a Changelog](https://keepachangelog.com/) and [SemVer](https://semver.org/).
 
+## [0.3.0] — 2026-10-11
+
+### Added — marketing consent, per contact channel
+
+- `ContactPoint.consent` (`{ status: 'granted' | 'withdrawn', at, source?, ip? }`) records permission to MARKET to one channel. Absent means "never asked", which a sender must treat as a refusal; `withdrawn` is deliberately not "absent", because only an opt-out has to survive a merge, a re-import or the person booking again.
+- `recordConsent(id, input, ctx)` stores a decision against a channel, matching the channel by its NORMALIZED value (`07700 900000` and `+447700900000` reach the same contact point). A channel the party does not hold is a typed error, not a silent no-op. Emits `party:party.consent_recorded`.
+- Merging two parties **reconciles consent** (`reconcileConsent`, exported): a withdrawal always beats a grant, whichever record is newer, because duplicate rows' clocks record when a row was touched, not when the person spoke. Between two records of the same status the later one wins. A channel one side verified stays verified. Before this, the loser's contact row was dropped wholesale and could discard an opt-out the duplicate alone carried.
+- Contact points are copied field by field on merge: Mongoose subdocuments keep their values behind prototype getters, so spreading one yielded internals and dropped data.
+- `CONSENT_STATUSES` / `ConsentStatus` and the `ChannelConsent` type.
+
+### Added — dated related-party relationships
+
+- `relationships[]` on a party: `shareholder`, `director`, `key_management`, `partner_in_firm`, `member`, `employee`, `lessor`, `associate` (`RELATIONSHIP_KINDS`), each with `from` and an exclusive `to`, an optional `relatedTo` (absent means the reporting company), and `shareClass` / `sharePercent` for shareholders. One party can hold several at once.
+- `addRelationship`, `endRelationship` and `relationshipsOn(id, date, ctx)` (the relationships holding on a date). A bad date range, an overlap or an unknown row throws `PartyRelationshipError` (`party.relationship_invalid`, 422). Emits `party:party.relationship_changed`.
+- A party model index for "every shareholder" / "every lessor" queries.
+
+### Added — `legalForm`
+
+`legalForm` on a party (`@classytic/primitives/legal-form`): what the law treats the party as — a sole trader is an `individual`. Absent means not stated.
+
+### Changed — peer floors raised to current
+
+`@classytic/mongokit` `>=3.33.0` → **`>=3.41.0`**, `@classytic/primitives` `>=0.29.0` → **`>=0.31.1`**, `@classytic/repo-core` `>=0.24.0` → **`>=0.31.0`**, `@classytic/contact` `>=0.1.0` → **`>=0.2.0`**, `mongoose` `>=9.4.1` → **`>=9.11.0`** (mongokit 3.41 requires it). Verified on a fresh install. New parties and merges write the new fields; existing documents read unchanged (`consent` stays absent, `relationships` defaults to `[]`).
+
+## [0.2.0] — 2026-08-17
+
+### Added
+- `defineParty(shape)` / `blueprint.bind(connection, runtime)` — describe/bind construction API replacing `createParty`; describe phase is pure and safe at import time
+- `SubjectRef` / `PARTY_MODEL_NAME` exported from `./domain/subject` — canonical polymorphic subject seam for cross-kernel refs (`@classytic/access`, `@classytic/muster`, etc.)
+- `src/maintenance/phone-identity-repair.ts` — repair utility for phone-identity drift
+
+### Removed
+- `createParty` (replaced by `defineParty`)
+
+## 1.0.0 - 2026-08-07 (unpublished)
+
+### Requirements
+
+- **New peer dependency: `@classytic/contact >=0.1.0`** — install it alongside
+  this package. It owns contact-point canonicalisation (E.164 phones, emails),
+  which `resolveOrCreate` / `syncIdentity` derive their `identityKeys` from.
+  A PEER rather than a regular dependency on purpose: npm may nest a regular one
+  under `party/node_modules`, giving the host a second module instance, and then
+  `err instanceof PhoneFormatError` is `false` at a host catch site that imported
+  its own copy — a guard that compiles, runs, and matches nothing.
+
+### Breaking
+
+- **Contact input that cannot be canonicalised now THROWS** instead of becoming
+  an identity key. A phone that is not a valid, dialable number raises
+  `PartyPhoneFormatError` (400 / `party.phone_invalid`); an unparseable email
+  raises `EmailFormatError`. `0.1.0` degraded both — a rejected phone became
+  `+${digits}`, producing keys like `phone:+01309000993` that are neither a
+  national number nor E.164, so two spellings of one person keyed differently and
+  the identity forked silently. There is no lenient variant.
+- **Phone canonicalisation requires a region for national-format input.**
+  `PartyShape.defaultPhoneRegion` (ISO 3166-1 alpha-2, supplied by the
+  deployment — this kernel names no country). Unset ⇒ E.164-only input is
+  accepted and a national format is refused rather than guessed at. An explicit
+  `+…` number is never re-read through the region.
+- **`ContactPoint.value` stores the canonical E.164**, with the caller's original
+  spelling preserved as `ContactPoint.input` (never keyed, never matched on).
+
+### Changed
+
+- Added `PartyShape.identityContactTypes` (`email | phone`, both by default).
+  A host can exclude shared contact channels from automatic identity resolution
+  while retaining normalized contact points. Tax identifiers and external
+  references remain authoritative. Existing defaults are unchanged.
+- The unique `identityKeys` index now explicitly includes only non-empty arrays.
+  This permits multiple name-only or contact-only parties when contact channels
+  are non-authoritative, without weakening uniqueness for real identity keys.
+- Canonical email output is unchanged for every valid address — trim plus
+  lowercase, and still **no** Gmail-dot or `+tag` folding, since folding a
+  provider's rule merges two distinct inboxes into one identity. No existing key
+  is re-derived.
+- `libphonenumber-js` is no longer a direct dependency.
+
+## 0.1.1 - 2026-07-22 (unpublished)
+
+### Changed
+- Internal: `InProcess*Bus` is now a thin subclass of `@classytic/primitives/event-infra`'s shared `InProcessEventBus` (dedup / error-isolation / close semantics unchanged); `MemoryOutboxStore` re-exported from the shared runtime where applicable. No public API, event-name, or wire-envelope change. Requires `@classytic/primitives >=0.13.0`.
+
 ## [0.1.0] - 2026-07-13
 
 Initial release — the Party / Business-Partner identity kernel.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Classytic
+Copyright (c) 2026 Classytic LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -48,12 +48,12 @@ Peers: `@classytic/mongokit >=3.20`, `@classytic/primitives >=0.9.1`,
 
 ```ts
 import mongoose from 'mongoose';
-import { createParty } from '@classytic/party';
+import { defineParty } from '@classytic/party';
 
-const party = await createParty({
-  connection: mongoose.connection,
+const party = defineParty({
   multiTenant: false, // identity is company-wide here; pass true for per-tenant SaaS
-});
+  defaultPhoneRegion: 'BD',
+}).bind(mongoose.connection);
 
 // Resolve-or-create by ANY identity signal — race-safe, dedup by email/phone/vat.
 const { party: ada, created } = await party.port.resolveOrCreate(
@@ -76,6 +76,27 @@ const snap = await party.port.snapshot(String(ada._id), {});
 await party.repositories.party.merge(dupId, survivorId, {});
 ```
 
+### Contacts are not always proof of identity
+
+Email and phone are authoritative identity keys by default, preserving the
+race-safe behavior existing commerce hosts rely on. Domains where people often
+share contact details can keep those values as contact data without allowing
+them to collapse two parties:
+
+```ts
+const party = defineParty({
+  multiTenant: true,
+  defaultPhoneRegion: 'GB',
+  identityContactTypes: [],
+}).bind(mongoose.connection);
+```
+
+Tax identifiers and explicit external references remain authoritative. A
+domain-specific facet (for example a legal Client) can perform candidate-match
+review and then attach its stable external reference or explicitly merge the
+confirmed duplicate. This setting shapes persisted `identityKeys`; migrate
+existing rows before changing it on a live deployment.
+
 ## The `PartyPort` — the reusable contract
 
 Consuming domains depend on `engine.port` (a `PartyPort`), not the models:
@@ -111,3 +132,7 @@ entities — that's the duplication this kernel exists to remove.
 ## License
 
 MIT
+
+## Trademark
+
+Code is MIT-licensed. "Classytic"/"arc" names + logos are trademarks of Classytic LLC — see [TRADEMARK.md](TRADEMARK.md).

package/dist/events.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { DomainEvent, EventHandler, EventMeta, EventTransport } from "@classytic/primitives/events";
+import { InProcessEventBus } from "@classytic/primitives/event-infra";
 import { Types } from "mongoose";
 import { OperationContext } from "@classytic/primitives/context";
 import "@classytic/primitives/reference";
@@ -14,10 +15,12 @@ declare const PARTY_EVENTS: {
   readonly ROLE_ADDED: 'party:party.role_added';
   readonly ROLE_REMOVED: 'party:party.role_removed';
   readonly USER_LINKED: 'party:party.user_linked';
+  readonly CONSENT_RECORDED: 'party:party.consent_recorded';
   readonly EXTERNAL_REF_ATTACHED: 'party:party.external_ref_attached';
   readonly ARCHIVED: 'party:party.archived';
   readonly RESTORED: 'party:party.restored';
   readonly MERGED: 'party:party.merged';
+  readonly RELATIONSHIP_CHANGED: 'party:party.relationship_changed';
 };
 type PartyEventName = (typeof PARTY_EVENTS)[keyof typeof PARTY_EVENTS];
 //#endregion
@@ -64,6 +67,14 @@ interface PartyUserLinkedPayload {
   partyId: string;
   userId: string;
 }
+interface PartyConsentRecordedPayload {
+  partyId: string;
+  channel: 'email' | 'phone';
+  /** The NORMALIZED channel — what a sender would actually dial or mail. */
+  value: string;
+  status: 'granted' | 'withdrawn';
+  source?: string;
+}
 interface PartyExternalRefAttachedPayload {
   partyId: string;
   sourceModel: string;
@@ -87,6 +98,7 @@ interface PartyEventPayloads {
   [PARTY_EVENTS.ROLE_ADDED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.ROLE_REMOVED]: PartyRoleChangedPayload;
   [PARTY_EVENTS.USER_LINKED]: PartyUserLinkedPayload;
+  [PARTY_EVENTS.CONSENT_RECORDED]: PartyConsentRecordedPayload;
   [PARTY_EVENTS.EXTERNAL_REF_ATTACHED]: PartyExternalRefAttachedPayload;
   [PARTY_EVENTS.ARCHIVED]: PartyLifecyclePayload;
   [PARTY_EVENTS.RESTORED]: PartyLifecyclePayload;
@@ -147,6 +159,19 @@ declare const PartyUserLinked: PartyEventDefinition<z.ZodObject<{
   partyId: z.ZodString;
   userId: z.ZodString;
 }, z.core.$strip>>;
+declare const PartyConsentRecorded: PartyEventDefinition<z.ZodObject<{
+  partyId: z.ZodString;
+  channel: z.ZodEnum<{
+    email: "email";
+    phone: "phone";
+  }>;
+  value: z.ZodString;
+  status: z.ZodEnum<{
+    granted: "granted";
+    withdrawn: "withdrawn";
+  }>;
+  source: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
 declare const PartyExternalRefAttached: PartyEventDefinition<z.ZodObject<{
   partyId: z.ZodString;
   sourceModel: z.ZodString;
@@ -163,6 +188,24 @@ declare const PartyMerged: PartyEventDefinition<z.ZodObject<{
   targetId: z.ZodString;
   absorbedKeys: z.ZodNumber;
 }, z.core.$strip>>;
+declare const PartyRelationshipChanged: PartyEventDefinition<z.ZodObject<{
+  partyId: z.ZodString;
+  relationshipId: z.ZodString;
+  kind: z.ZodEnum<{
+    associate: "associate";
+    director: "director";
+    employee: "employee";
+    key_management: "key_management";
+    lessor: "lessor";
+    member: "member";
+    partner_in_firm: "partner_in_firm";
+    shareholder: "shareholder";
+  }>;
+  change: z.ZodEnum<{
+    added: "added";
+    ended: "ended";
+  }>;
+}, z.core.$strip>>;
 declare const partyEventDefinitions: ReadonlyArray<PartyEventDefinition>;
 //#endregion
 //#region src/domain/ports.d.ts
@@ -192,16 +235,10 @@ interface PartyLogger {
 declare function createEvent<T>(type: string, payload: T, ctx?: PartyContext, meta?: Partial<EventMeta>): DomainEvent<T>;
 //#endregion
 //#region src/events/in-process-bus.d.ts
-declare class InProcessPartyBus implements EventTransport {
-  readonly name = "in-process-party";
-  private subs;
-  private readonly logger;
+declare class InProcessPartyBus extends InProcessEventBus {
   constructor(options?: {
-    logger?: PartyLogger | undefined;
+    logger?: PartyLogger;
   });
-  publish(event: DomainEvent): Promise<void>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
 }
 //#endregion
 //#region src/events/dispatch.d.ts
@@ -235,4 +272,4 @@ declare class PartyEventDispatcher {
  */
 declare function flushPending(dispatcher: PartyEventDispatcher, queue: DomainEvent[], logger?: PartyLogger): Promise<void>;
 //#endregion
-export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyCreated, PartyCreatedPayload, PartyEventDefinition, PartyEventDispatcher, PartyEventDispatcherOptions, PartyEventName, PartyEventPayloads, PartyExternalRefAttached, PartyExternalRefAttachedPayload, PartyLifecyclePayload, PartyMerged, PartyMergedPayload, PartyRestored, PartyRoleAdded, PartyRoleChangedPayload, PartyRoleRemoved, PartyUpdated, PartyUpdatedPayload, PartyUserLinked, PartyUserLinkedPayload, createEvent, flushPending, partyEventDefinitions };
+export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyConsentRecorded, PartyConsentRecordedPayload, PartyCreated, PartyCreatedPayload, PartyEventDefinition, PartyEventDispatcher, PartyEventDispatcherOptions, PartyEventName, PartyEventPayloads, PartyExternalRefAttached, PartyExternalRefAttachedPayload, PartyLifecyclePayload, PartyMerged, PartyMergedPayload, PartyRelationshipChanged, PartyRestored, PartyRoleAdded, PartyRoleChangedPayload, PartyRoleRemoved, PartyUpdated, PartyUpdatedPayload, PartyUserLinked, PartyUserLinkedPayload, createEvent, flushPending, partyEventDefinitions };

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 §12: `package:resource.verb`. Emit ONLY these catalog names. */
 const PARTY_EVENTS = {
@@ -8,10 +9,12 @@ const PARTY_EVENTS = {
 	ROLE_ADDED: "party:party.role_added",
 	ROLE_REMOVED: "party:party.role_removed",
 	USER_LINKED: "party:party.user_linked",
+	CONSENT_RECORDED: "party:party.consent_recorded",
 	EXTERNAL_REF_ATTACHED: "party:party.external_ref_attached",
 	ARCHIVED: "party:party.archived",
 	RESTORED: "party:party.restored",
-	MERGED: "party:party.merged"
+	MERGED: "party:party.merged",
+	RELATIONSHIP_CHANGED: "party:party.relationship_changed"
 };
 //#endregion
 //#region src/events/event-catalog.ts
@@ -70,6 +73,13 @@ const userLinkedSchema = z.object({
 	partyId: z.string(),
 	userId: z.string()
 });
+const consentRecordedSchema = z.object({
+	partyId: z.string(),
+	channel: z.enum(["email", "phone"]),
+	value: z.string(),
+	status: z.enum(["granted", "withdrawn"]),
+	source: z.string().optional()
+});
 const externalRefSchema = z.object({
 	partyId: z.string(),
 	sourceModel: z.string(),
@@ -106,6 +116,11 @@ const PartyUserLinked = definePartyEvent({
 	description: "An auth user was linked to a party (1:many).",
 	zodSchema: userLinkedSchema
 });
+const PartyConsentRecorded = definePartyEvent({
+	name: PARTY_EVENTS.CONSENT_RECORDED,
+	description: "A marketing-consent decision was recorded against one contact channel.",
+	zodSchema: consentRecordedSchema
+});
 const PartyExternalRefAttached = definePartyEvent({
 	name: PARTY_EVENTS.EXTERNAL_REF_ATTACHED,
 	description: "An external-store reference was attached to a party (facet link).",
@@ -126,16 +141,38 @@ const PartyMerged = definePartyEvent({
 	description: "A duplicate party was merged into a survivor; the source becomes a redirect.",
 	zodSchema: mergedSchema
 });
+const relationshipChangedSchema = z.object({
+	partyId: z.string(),
+	relationshipId: z.string(),
+	kind: z.enum([
+		"shareholder",
+		"director",
+		"key_management",
+		"partner_in_firm",
+		"member",
+		"employee",
+		"lessor",
+		"associate"
+	]),
+	change: z.enum(["added", "ended"])
+});
+const PartyRelationshipChanged = definePartyEvent({
+	name: PARTY_EVENTS.RELATIONSHIP_CHANGED,
+	description: "A dated relationship of the party (shareholder, director, lessor, …) was added or ended.",
+	zodSchema: relationshipChangedSchema
+});
 const partyEventDefinitions = [
 	PartyCreated,
 	PartyUpdated,
 	PartyRoleAdded,
 	PartyRoleRemoved,
 	PartyUserLinked,
+	PartyConsentRecorded,
 	PartyExternalRefAttached,
 	PartyArchived,
 	PartyRestored,
-	PartyMerged
+	PartyMerged,
+	PartyRelationshipChanged
 ];
 //#endregion
 //#region src/events/helpers.ts
@@ -158,37 +195,24 @@ function createEvent(type, payload, ctx, meta) {
 //#region src/events/in-process-bus.ts
 /**
 * In-process event bus — default fallback when no `eventTransport` is given to
-* `createParty`. Structurally identical to arc's `MemoryEventTransport`;
-* pattern-matching delegates to primitives' `matchEventPattern` (PACKAGE_RULES
-* §13). Handler errors are swallowed-and-logged — emission never blocks writes.
+* `createParty`.
+*
+* A thin subclass of `@classytic/primitives/event-infra`'s shared
+* `InProcessEventBus`. Prior semantics preserved: glob matching via
+* `matchEventPattern`, per-handler error isolation, idempotent `close()`.
+* Party historically SWALLOWED handler errors when no logger was supplied —
+* that default is preserved by passing `logger: null` unless the host injects
+* a `PartyLogger`, whose structured `error(msg, meta)` slot is bridged onto
+* the shared error-logger contract.
 */
-var InProcessPartyBus = class {
-	name = "in-process-party";
-	subs = [];
-	logger;
+var InProcessPartyBus = class extends InProcessEventBus {
 	constructor(options) {
-		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?.(`[party] 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 partyLogger = options?.logger;
+		super({
+			name: "in-process-party",
+			logLabel: "party",
+			logger: partyLogger?.error ? { error: (message, ...args) => partyLogger.error?.(message, { args }) } : null
+		});
 	}
 };
 //#endregion
@@ -211,7 +235,9 @@ var PartyEventDispatcher = class {
 		return this.transport.publish(event);
 	}
 	subscribe(pattern, handler) {
-		return this.transport.subscribe(pattern, handler);
+		const subscribe = this.transport.subscribe?.bind(this.transport);
+		if (!subscribe) throw new Error("party: configured event transport does not support subscribe");
+		return subscribe(pattern, handler);
 	}
 	/**
 	* Route a domain event with full §P8 discipline. Reads the pending queue and
@@ -252,4 +278,4 @@ async function flushPending(dispatcher, queue, logger) {
 	}
 }
 //#endregion
-export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyCreated, PartyEventDispatcher, PartyExternalRefAttached, PartyMerged, PartyRestored, PartyRoleAdded, PartyRoleRemoved, PartyUpdated, PartyUserLinked, createEvent, flushPending, partyEventDefinitions };
+export { InProcessPartyBus, PARTY_EVENTS, PENDING_EVENTS, PartyArchived, PartyConsentRecorded, PartyCreated, PartyEventDispatcher, PartyExternalRefAttached, PartyMerged, PartyRelationshipChanged, PartyRestored, PartyRoleAdded, PartyRoleRemoved, PartyUpdated, PartyUserLinked, createEvent, flushPending, partyEventDefinitions };