@classytic/crm 0.9.0 → 1.0.0

package/package.json

@@ -1,73 +1,79 @@
-{
-  "name": "@classytic/crm",
-  "version": "0.9.0",
-  "description": "Engine-factory CRM package \u2014 leads, accounts, contacts, opportunities, pipelines, campaigns, subscriptions, activities, notes, email engagement. PACKAGE_RULES compliant; built on Mongoose + mongokit + arc primitives.",
-  "author": "Classytic",
-  "license": "MIT",
-  "type": "module",
-  "sideEffects": false,
-  "engines": {
-    "node": ">=22"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./events": {
-      "types": "./dist/events.d.ts",
-      "default": "./dist/events.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "files": [
-    "dist",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/classytic/crm.git"
-  },
-  "bugs": {
-    "url": "https://github.com/classytic/crm/issues"
-  },
-  "homepage": "https://github.com/classytic/crm#readme",
-  "scripts": {
-    "build": "tsdown",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run --project unit --project integration",
-    "test:unit": "vitest run --project unit",
-    "test:integration": "vitest run --project integration",
-    "test:e2e": "vitest run --project e2e",
-    "test:all": "vitest run",
-    "test:watch": "vitest --project unit --project integration",
-    "push": "classytic-push"
-  },
-  "peerDependencies": {
-    "@classytic/mongokit": ">=3.22.0",
-    "@classytic/primitives": ">=0.11.0",
-    "@classytic/repo-core": ">=0.13.0",
-    "mongoose": ">=9.4.1",
-    "zod": ">=4.0.0"
-  },
-  "devDependencies": {
-    "@classytic/dev-tools": "^0.2.0",
-    "@classytic/mongokit": "^3.22.0",
-    "@classytic/primitives": "^0.11.0",
-    "@classytic/repo-core": "^0.13.0",
-    "@types/node": "^25.5.0",
-    "mongodb-memory-server": "^10.1.4",
-    "mongoose": "^9.4.1",
-    "tsdown": "^0.21.10",
-    "typescript": "^5.8.2",
-    "vitest": "^3.2.4",
-    "zod": "^4.3.6"
-  }
-}
+{
+  "name": "@classytic/crm",
+  "version": "1.0.0",
+  "description": "Engine-factory CRM package — leads, accounts, contacts, opportunities, pipelines, campaigns, subscriptions, activities, notes, email engagement. PACKAGE_RULES compliant; built on Mongoose + mongokit + arc primitives.",
+  "author": "Classytic",
+  "license": "SEE LICENSE IN LICENSE",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./events": {
+      "types": "./dist/events.d.ts",
+      "default": "./dist/events.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "scripts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/classytic/crm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/classytic/crm/issues"
+  },
+  "homepage": "https://github.com/classytic/crm#readme",
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --project unit --project integration",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:e2e": "vitest run --project e2e",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit --project integration",
+    "drift:suppression": "node scripts/suppression-key-drift.mjs",
+    "drift:email-keys": "node scripts/lead-contact-email-key-drift.mjs",
+    "push": "classytic-push"
+  },
+  "peerDependencies": {
+    "@classytic/contact": ">=0.1.0",
+    "@classytic/mongokit": ">=3.32.0",
+    "@classytic/primitives": ">=0.14.0",
+    "@classytic/repo-core": ">=0.13.0",
+    "mongoose": ">=9.4.1",
+    "zod": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@classytic/contact": ">=0.1.0",
+    "@classytic/dev-tools": "^0.2.0",
+    "@classytic/mongokit": "^3.25.0",
+    "@classytic/primitives": ">=0.20.0",
+    "@classytic/repo-core": ">=0.20.0",
+    "@types/node": "^25.5.0",
+    "mongodb-memory-server": "^10.1.4",
+    "mongoose": "^9.4.1",
+    "publint": "^0.3.23",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4",
+    "zod": "^4.3.6"
+  }
+}

package/scripts/lead-contact-email-key-drift.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * DRY RUN — which Lead / Contact rows are forked or unreachable under canonical
+ * email keys?
+ *
+ * Lead `email` and Contact `contact.email` used to be folded by mongoose
+ * `lowercase: true` alone. That does not IDNA-fold, so `ada@bücher.de` and
+ * `ada@xn--bcher-kva.de` — one host in two encodings — were two distinct keys and
+ * the partial-unique `(organizationId, <email>)` index admitted both. One mailbox,
+ * two rows, no error. Both fields now key through `normalizeEmail` from
+ * `@classytic/contact/email` on every write and every query filter.
+ *
+ * Rows written under the old rule are NOT migrated automatically, and must not be.
+ * These are live customer records: a rekey can hit the unique index outright, and
+ * deciding which of two forked rows survives (and what happens to the
+ * opportunities, activities and subscriptions pointing at the loser) is a human
+ * call. This script only READS. It never writes, never drops, never creates an
+ * index, never merges.
+ *
+ * Four outcomes per row:
+ *
+ *   unchanged        the stored value already IS its canonical key. No action.
+ *   rekey            canonicalises to a DIFFERENT string, and nothing else in the
+ *                    org holds that key. A `$set` would succeed — but see the
+ *                    closing note: it is still not this script's call.
+ *   collision        rekeying it would land on a key another row in the same org
+ *                    already holds. The unique index means a naive `updateOne`
+ *                    FAILS. These are the forks: two rows, one mailbox. Merging
+ *                    them — and re-pointing every FK off the loser — is a human
+ *                    decision, not a script's.
+ *   uncanonicalisable  not an address the canonical grammar admits. It could never
+ *                    have matched a real send or a real dedup either. The write
+ *                    verbs now refuse these outright, so no NEW ones appear; what
+ *                    to do with the existing ones is a data-quality decision.
+ *
+ * Usage:
+ *   node scripts/lead-contact-email-key-drift.mjs <mongodb-uri> [options]
+ *
+ * Options:
+ *   --leads=NAME       lead collection      (default: leads)
+ *   --contacts=NAME    contact collection   (default: contacts)
+ *   --json             machine-readable output
+ *
+ * Collections default to mongoose's pluralisation of the `Lead` / `Contact` model
+ * names. Pass the flags when the host set a `modelPrefix`.
+ */
+
+import { MongoClient } from 'mongodb';
+import { normalizeEmail } from '@classytic/contact/email';
+
+const args = process.argv.slice(2);
+const uri = args.find((a) => !a.startsWith('--'));
+const asJson = args.includes('--json');
+const flag = (name, fallback) =>
+  (args.find((a) => a.startsWith(`--${name}=`)) ?? '').split('=')[1] || fallback;
+
+if (!uri) {
+  console.error(
+    'usage: node scripts/lead-contact-email-key-drift.mjs <mongodb-uri> ' +
+      '[--leads=NAME] [--contacts=NAME] [--json]',
+  );
+  process.exit(2);
+}
+
+/** The schema's key rule, without importing mongoose. */
+function key(email) {
+  try {
+    return { ok: true, key: normalizeEmail(email) };
+  } catch (err) {
+    return { ok: false, reason: err?.code ?? 'invalid' };
+  }
+}
+
+/** Read a dotted path off a plain document (`contact.email`). */
+function at(doc, path) {
+  return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), doc);
+}
+
+/**
+ * Classify one collection. `emailPath` is the dotted field the unique index is
+ * built on, so the projection, the classification and the collision scope all
+ * derive from ONE declaration — a report that classified a different field from
+ * the one the index enforces would be confidently wrong.
+ */
+async function scan(db, { collectionName, emailPath }) {
+  const coll = db.collection(collectionName);
+  const total = await coll.countDocuments({});
+  const rows = await coll
+    .find({}, { projection: { _id: 1, organizationId: 1, [emailPath]: 1 } })
+    .toArray();
+
+  // Canonical keys ALREADY claimed per org. A rekey landing on one of these
+  // collides with the unique index whether or not both source rows move.
+  const occupied = new Map(); // org -> Map<canonicalKey, count>
+  for (const row of rows) {
+    const stored = at(row, emailPath);
+    if (typeof stored !== 'string') continue;
+    const org = String(row.organizationId ?? '');
+    if (!occupied.has(org)) occupied.set(org, new Map());
+    const k = key(stored);
+    if (!k.ok) continue;
+    const bucket = occupied.get(org);
+    bucket.set(k.key, (bucket.get(k.key) ?? 0) + 1);
+  }
+
+  const buckets = { unchanged: [], rekey: [], collision: [], uncanonicalisable: [] };
+  let withEmail = 0;
+  for (const row of rows) {
+    const stored = at(row, emailPath);
+    // The index is PARTIAL on `$type: 'string'` — a row with no email is not in
+    // it and cannot fork. Counting it as `unchanged` would inflate the clean
+    // number with rows the question does not apply to.
+    if (typeof stored !== 'string') continue;
+    withEmail += 1;
+
+    const org = String(row.organizationId ?? '');
+    const k = key(stored);
+    if (!k.ok) {
+      buckets.uncanonicalisable.push({ _id: String(row._id), organizationId: org, stored, reason: k.reason });
+      continue;
+    }
+    if (k.key === stored) {
+      buckets.unchanged.push({ _id: String(row._id), organizationId: org, stored });
+      continue;
+    }
+    const contenders = occupied.get(org)?.get(k.key) ?? 0;
+    (contenders > 1 ? buckets.collision : buckets.rekey).push({
+      _id: String(row._id),
+      organizationId: org,
+      stored,
+      canonical: k.key,
+    });
+  }
+
+  return {
+    summary: {
+      collection: collectionName,
+      field: emailPath,
+      totalRows: total,
+      rowsWithEmail: withEmail,
+      unchanged: buckets.unchanged.length,
+      rekey: buckets.rekey.length,
+      collision: buckets.collision.length,
+      uncanonicalisable: buckets.uncanonicalisable.length,
+      unmatchableToday:
+        buckets.rekey.length + buckets.collision.length + buckets.uncanonicalisable.length,
+    },
+    buckets,
+  };
+}
+
+function report(result) {
+  const s = result.summary;
+  console.log(`\ncollection            ${s.collection}  (${s.field})`);
+  console.log(`rows                  ${s.totalRows}`);
+  console.log(`  with an email       ${s.rowsWithEmail}`);
+  console.log(`    unchanged         ${s.unchanged}`);
+  console.log(`    rekey             ${s.rekey}`);
+  console.log(`    collision         ${s.collision}`);
+  console.log(`    uncanonicalisable ${s.uncanonicalisable}`);
+  console.log(`UNMATCHABLE TODAY     ${s.unmatchableToday}`);
+
+  for (const name of ['collision', 'rekey', 'uncanonicalisable']) {
+    const rows = result.buckets[name];
+    if (rows.length === 0) continue;
+    console.log(`\n── ${name} — ${s.collection} ──`);
+    for (const r of rows) {
+      console.log(
+        `  ${r.organizationId}  ${JSON.stringify(r.stored)}  ->  ${r.canonical ?? `(none: ${r.reason})`}`,
+      );
+    }
+  }
+
+  // "Zero rows" and "collection absent" are DIFFERENT answers, and both print a
+  // clean-looking report. Say which one this was.
+  if (s.totalRows === 0) {
+    console.log(
+      `\nSCANNED NOTHING — collection '${s.collection}' is empty or absent in this database.\n` +
+        'That is NOT the same answer as "clean". Confirm the collection name (a host with a\n' +
+        '`modelPrefix` stores it elsewhere) and the database in the URI before concluding\n' +
+        'there is no drift.',
+    );
+  } else if (s.rowsWithEmail === 0) {
+    console.log(
+      `\nNO ROW IN '${s.collection}' CARRIES AN EMAIL — ${s.totalRows} row(s) scanned, none in the\n` +
+        'partial-unique index. Nothing here can fork; nothing here is evidence that the rest is clean.',
+    );
+  }
+}
+
+const client = new MongoClient(uri);
+try {
+  await client.connect();
+  const db = client.db();
+
+  const results = [
+    await scan(db, { collectionName: flag('leads', 'leads'), emailPath: 'email' }),
+    await scan(db, { collectionName: flag('contacts', 'contacts'), emailPath: 'contact.email' }),
+  ];
+
+  if (asJson) {
+    console.log(JSON.stringify(results, null, 2));
+  } else {
+    for (const r of results) report(r);
+    const collisions = results.reduce((n, r) => n + r.summary.collision, 0);
+    if (collisions > 0) {
+      console.log(
+        `\n${collisions} COLLISION(S). Each is one mailbox living as two rows. A naive \`$set\` to the\n` +
+          'canonical key hits the unique index and fails — the two rows must be MERGED, and which\n' +
+          "reason/owner/history survives, plus where the loser's opportunities, activities, notes\n" +
+          'and subscriptions re-point, is a decision this script will not make for you.',
+      );
+    }
+    console.log('\nNOTHING WAS WRITTEN. This is a report, not a migration.');
+  }
+} finally {
+  await client.close();
+}

package/scripts/suppression-key-drift.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * DRY RUN — which suppression rows are unreachable under canonical keys?
+ *
+ * `SuppressionRepository` used to key rows with `email.trim().toLowerCase()`. It
+ * now keys them with `normalizeEmail` from `@classytic/contact/email`, which also
+ * IDNA-folds the domain to punycode and REFUSES what it cannot canonicalise.
+ *
+ * Rows written under the old rule are not migrated automatically, and must not be:
+ * a suppression list is a do-not-contact record with legal weight, so a bad rewrite
+ * is worse than a stale row. This script only READS. It never writes, never drops,
+ * never creates an index. Run it, read the numbers, and decide.
+ *
+ * Four outcomes per row:
+ *
+ *   unchanged        the stored value already IS its canonical key. No action.
+ *   rekey            canonicalises to a DIFFERENT string — today this row can
+ *                    never match a lookup. It is a suppression that suppresses
+ *                    nothing.
+ *   collision        rekeying it would land on a key another row in the same org
+ *                    already holds. The (organizationId, email) index is unique,
+ *                    so a naive `updateOne` here FAILS — the two rows must be
+ *                    merged, and which `reason`/`suppressedAt` survives is a
+ *                    human decision, not a script's.
+ *   uncanonicalisable  not an address the canonical grammar admits. It could never
+ *                    have matched a real send either; deleting it is probably
+ *                    right, but "probably" is why this script does not.
+ *
+ * Usage:
+ *   node scripts/suppression-key-drift.mjs <mongodb-uri> [--collection=suppressions] [--json]
+ *
+ * The collection defaults to `suppressions` (mongoose's pluralisation of the
+ * `Suppression` model). Pass `--collection` when the host set a `modelPrefix`.
+ */
+
+import { MongoClient } from 'mongodb';
+import { normalizeEmail } from '@classytic/contact/email';
+
+const args = process.argv.slice(2);
+const uri = args.find((a) => !a.startsWith('--'));
+const collectionName = (args.find((a) => a.startsWith('--collection=')) ?? '').split('=')[1] || 'suppressions';
+const asJson = args.includes('--json');
+
+if (!uri) {
+  console.error('usage: node scripts/suppression-key-drift.mjs <mongodb-uri> [--collection=NAME] [--json]');
+  process.exit(2);
+}
+
+/** The repository's key rule, without importing the repository (no mongoose here). */
+function key(email) {
+  try {
+    return { ok: true, key: normalizeEmail(email) };
+  } catch (err) {
+    return { ok: false, reason: err?.code ?? 'invalid' };
+  }
+}
+
+const client = new MongoClient(uri);
+try {
+  await client.connect();
+  const coll = client.db().collection(collectionName);
+
+  const total = await coll.countDocuments({});
+  const rows = await coll
+    .find({}, { projection: { _id: 1, organizationId: 1, email: 1, reason: 1, suppressedAt: 1 } })
+    .toArray();
+
+  // Canonical keys ALREADY present per org — a rekey landing on one of these
+  // collides with the unique index whether or not the source rows both move.
+  const occupied = new Map(); // `${org}` -> Map<canonicalKey, count>
+  for (const row of rows) {
+    const org = String(row.organizationId ?? '');
+    if (!occupied.has(org)) occupied.set(org, new Map());
+    const k = key(String(row.email ?? ''));
+    if (!k.ok) continue;
+    const bucket = occupied.get(org);
+    bucket.set(k.key, (bucket.get(k.key) ?? 0) + 1);
+  }
+
+  const buckets = { unchanged: [], rekey: [], collision: [], uncanonicalisable: [] };
+  for (const row of rows) {
+    const stored = String(row.email ?? '');
+    const org = String(row.organizationId ?? '');
+    const k = key(stored);
+    if (!k.ok) {
+      buckets.uncanonicalisable.push({ _id: String(row._id), organizationId: org, stored, reason: k.reason });
+      continue;
+    }
+    if (k.key === stored) {
+      buckets.unchanged.push({ _id: String(row._id), organizationId: org, stored });
+      continue;
+    }
+    const contenders = occupied.get(org)?.get(k.key) ?? 0;
+    const target = contenders > 1;
+    (target ? buckets.collision : buckets.rekey).push({
+      _id: String(row._id),
+      organizationId: org,
+      stored,
+      canonical: k.key,
+      reason: row.reason,
+    });
+  }
+
+  const summary = {
+    collection: collectionName,
+    totalRows: total,
+    unchanged: buckets.unchanged.length,
+    rekey: buckets.rekey.length,
+    collision: buckets.collision.length,
+    uncanonicalisable: buckets.uncanonicalisable.length,
+    unmatchableToday: buckets.rekey.length + buckets.collision.length + buckets.uncanonicalisable.length,
+  };
+
+  if (asJson) {
+    console.log(JSON.stringify({ summary, rekey: buckets.rekey, collision: buckets.collision, uncanonicalisable: buckets.uncanonicalisable }, null, 2));
+  } else {
+    console.log(`collection            ${summary.collection}`);
+    console.log(`rows                  ${summary.totalRows}`);
+    console.log(`  unchanged           ${summary.unchanged}`);
+    console.log(`  rekey               ${summary.rekey}`);
+    console.log(`  collision           ${summary.collision}`);
+    console.log(`  uncanonicalisable   ${summary.uncanonicalisable}`);
+    console.log(`UNMATCHABLE TODAY     ${summary.unmatchableToday}`);
+    for (const name of ['rekey', 'collision', 'uncanonicalisable']) {
+      if (buckets[name].length === 0) continue;
+      console.log(`\n── ${name} ──`);
+      for (const r of buckets[name]) {
+        console.log(`  ${r.organizationId}  ${JSON.stringify(r.stored)}  ->  ${r.canonical ?? `(none: ${r.reason})`}`);
+      }
+    }
+    if (summary.totalRows === 0) {
+      console.log(
+        `\nSCANNED NOTHING — collection '${collectionName}' is empty or absent in this database.\n` +
+          'That is NOT the same answer as "clean". Confirm the collection name (a host with a\n' +
+          '`modelPrefix` stores it elsewhere) and the database in the URI before concluding\n' +
+          'there is no drift.',
+      );
+    }
+    console.log('\nNOTHING WAS WRITTEN. This is a report, not a migration.');
+  }
+} finally {
+  await client.close();
+}