@sonordev/contracts 2.7.1 → 2.8.0

package/dist/outreach.mjs

@@ -0,0 +1,328 @@
+// src/contracts/business-claims.ts
+function fnv1a(text) {
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/contracts/outreach.ts
+var OUTREACH_CONTRACT_VERSION = 1;
+var OUTREACH_WRITER_BADGE = "signal.outreach.writer";
+var OUTREACH_EMAIL_KIND = "outreach_email";
+var GRADUATION_BAR = { minMeasured: 5, minWinRate: 0.7, maxUnrevertedDegradations: 0 };
+var SEGMENT_STATES = ["ungranted", "granted", "paused", "lapsed", "revoked"];
+var UNSPECIFIED_INDUSTRY = "unspecified";
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var isUuid = (value) => typeof value === "string" && UUID.test(value);
+var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+var nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+function prospectIndustry(prospect) {
+  for (const value of [prospect?.vertical, prospect?.industry, prospect?.company_industry]) {
+    if (nonEmpty(value)) return value.trim();
+  }
+  return null;
+}
+function normalizeIndustry(value) {
+  if (typeof value !== "string") return UNSPECIFIED_INDUSTRY;
+  const slug = value.normalize("NFKC").normalize("NFD").replace(/\p{M}/gu, "").toLowerCase().replace(/&/g, " and ").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48).replace(/-+$/g, "");
+  return slug || UNSPECIFIED_INDUSTRY;
+}
+var NARRATIVE_PITCH_FIELDS = [
+  "positioning_statement",
+  "target_icp_description",
+  "tone_profile",
+  "hook_types",
+  "example_angles",
+  "value_prop_bullets"
+];
+function canonical(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFKC").replace(/\s+/g, " ").trim());
+  if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return "null";
+}
+function narrativeFingerprint(narrative) {
+  const source = isRecord(narrative) ? narrative : {};
+  const pitch = {};
+  for (const field of NARRATIVE_PITCH_FIELDS) pitch[field] = source[field] ?? null;
+  return fnv1a(canonical(pitch));
+}
+function outreachSegment(input) {
+  const vertical = normalizeIndustry(input?.industry);
+  const label = typeof input?.label === "string" ? input.label : "";
+  const angle_fp = typeof input?.angleFp === "string" && input.angleFp ? input.angleFp : null;
+  if (input?.source === "drip") {
+    if (!isUuid(input.narrativeId) || !isUuid(input.mailboxId)) return null;
+    const narrative_id = input.narrativeId.toLowerCase();
+    const mailbox_id = input.mailboxId.toLowerCase();
+    return { key: `drip:${narrative_id}@${mailbox_id}|${vertical}`, source: "drip", narrative_id, mailbox_id, vertical, label, angle_fp };
+  }
+  if (input?.source === "mcp") {
+    const mailbox_id = isUuid(input.mailboxId) ? input.mailboxId.toLowerCase() : null;
+    return { key: `mcp:-|${vertical}`, source: "mcp", narrative_id: null, mailbox_id, vertical, label, angle_fp };
+  }
+  return null;
+}
+function outreachSegmentLabel(input) {
+  const name = nonEmpty(input?.narrativeName) ? input.narrativeName.trim() : "Outreach";
+  const industry = nonEmpty(input?.industry) ? input.industry.trim() : "leads with no industry";
+  const from = nonEmpty(input?.mailboxAddress) ? `, from ${input.mailboxAddress.trim()}` : "";
+  return `${name} to ${industry}${from}`;
+}
+var DRIP_KEY = /^drip:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})@([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\|([a-z0-9-]{1,48})$/;
+var MCP_KEY = /^mcp:-\|([a-z0-9-]{1,48})$/;
+function parseOutreachSegmentKey(key) {
+  if (typeof key !== "string" || key.length > 140) return null;
+  const drip = DRIP_KEY.exec(key);
+  if (drip) return { source: "drip", narrative_id: drip[1], mailbox_id: drip[2], vertical: drip[3] };
+  const mcp = MCP_KEY.exec(key);
+  if (mcp) return { source: "mcp", vertical: mcp[1] };
+  return null;
+}
+function isGrantableSegmentKey(key) {
+  const parsed = parseOutreachSegmentKey(key);
+  return parsed?.source === "drip" && parsed.vertical !== UNSPECIFIED_INDUSTRY;
+}
+var isDate = (value) => typeof value === "string" && !Number.isNaN(Date.parse(value));
+function readGrant(value) {
+  if (!isRecord(value)) return null;
+  const { state, source, by, via, at, ref, receipts, mailbox_id, label, angle_fp, paused, resumed, revoked } = value;
+  if (state !== "granted" && state !== "revoked") return null;
+  if (source !== "first_email" && source !== "earned") return null;
+  if (via !== "dashboard" && via !== "drafts") return null;
+  if (!nonEmpty(by) || !isDate(at) || !nonEmpty(ref) || !nonEmpty(mailbox_id) || !nonEmpty(angle_fp) || typeof label !== "string") return null;
+  const grant = { state, source, by, via, at, ref, mailbox_id, label, angle_fp };
+  if (receipts !== void 0) {
+    if (!Array.isArray(receipts) || !receipts.every(nonEmpty)) return null;
+    grant.receipts = [...receipts];
+  }
+  if (paused !== void 0 && paused !== null) {
+    if (!isRecord(paused) || !isDate(paused.at) || typeof paused.reason !== "string") return null;
+    grant.paused = { at: paused.at, reason: paused.reason, loss_ref: nonEmpty(paused.loss_ref) ? paused.loss_ref : null };
+  }
+  if (resumed !== void 0 && resumed !== null) {
+    if (!isRecord(resumed) || !nonEmpty(resumed.by) || !isDate(resumed.at)) return null;
+    grant.resumed = { by: resumed.by, at: resumed.at };
+  }
+  if (revoked !== void 0 && revoked !== null) {
+    if (!isRecord(revoked) || !nonEmpty(revoked.by) || !isDate(revoked.at) || typeof revoked.reason !== "string") return null;
+    grant.revoked = { by: revoked.by, at: revoked.at, reason: revoked.reason };
+  }
+  return grant;
+}
+function readSegmentGrants(source) {
+  const autonomy = isRecord(source) && isRecord(source.autonomy) ? source.autonomy : source;
+  const segments = isRecord(autonomy) && isRecord(autonomy.segments) ? autonomy.segments[OUTREACH_EMAIL_KIND] : null;
+  const out = {};
+  if (!isRecord(segments)) return out;
+  for (const key of Object.keys(segments)) {
+    if (!parseOutreachSegmentKey(key)) continue;
+    const grant = readGrant(segments[key]);
+    if (grant) out[key] = grant;
+  }
+  return out;
+}
+function activeSegmentGrant(source, key) {
+  if (!isGrantableSegmentKey(key)) return null;
+  const grant = readSegmentGrants(source)[key];
+  return grant && grant.state === "granted" && !grant.paused ? grant : null;
+}
+function segmentGrantCovers(grant, row) {
+  if (!grant) return { covers: false, code: "not_granted", reason: "Nobody's turned this segment on." };
+  if (grant.state === "revoked") return { covers: false, code: "revoked", reason: "Someone stopped this segment." };
+  if (grant.paused) return { covers: false, code: "paused", reason: `This segment stopped itself: ${grant.paused.reason}` };
+  if (grant.state !== "granted") return { covers: false, code: "not_granted", reason: "Nobody's turned this segment on." };
+  if (row.by !== void 0 && row.by !== grant.by) return { covers: false, code: "other_person", reason: "This row names someone other than the person who turned the segment on." };
+  const created = Date.parse(row.createdAt ?? "");
+  const granted = Date.parse(grant.at);
+  if (!Number.isFinite(created) || !Number.isFinite(granted) || created < granted) {
+    return { covers: false, code: "granted_after", reason: "This email was written before the segment was turned on." };
+  }
+  if (!row.angleFp || row.angleFp !== grant.angle_fp) {
+    return { covers: false, code: "angle_changed", reason: "The pitch changed since this segment was turned on, so its next email needs a look." };
+  }
+  if (!row.mailboxId || row.mailboxId.toLowerCase() !== grant.mailbox_id.toLowerCase()) {
+    return { covers: false, code: "other_mailbox", reason: "This email sends from a different mailbox than the one the segment was turned on for." };
+  }
+  return { covers: true };
+}
+function segmentOf(row) {
+  return isRecord(row.target_ref) && isRecord(row.target_ref.segment) ? row.target_ref.segment : null;
+}
+function payloadOf(row) {
+  return isRecord(row.payload) ? row.payload : {};
+}
+function viaOf(row) {
+  const approval = payloadOf(row)._approval;
+  return isRecord(approval) ? approval.via : void 0;
+}
+function wasEdited(row) {
+  const edited = payloadOf(row).edited;
+  return isRecord(edited) && typeof edited.count === "number" && edited.count > 0;
+}
+function readBackStatus(row) {
+  const execution = payloadOf(row)._execution;
+  return isRecord(execution) && isRecord(execution.read_back) ? execution.read_back.status : void 0;
+}
+function evidenceRowRefusal(row, grant, scope, people) {
+  if (!row) return "isn't on record";
+  if (row.kind !== OUTREACH_EMAIL_KIND || row.created_by !== OUTREACH_WRITER_BADGE) return "isn't an email Signal's outreach writer wrote";
+  if (scope.projectId && row.project_id && row.project_id !== scope.projectId) return "belongs to another project";
+  if (row.status !== "applied") return "wasn't approved and sent";
+  const segment = segmentOf(row);
+  if (!segment || segment.key !== scope.key) return "is in a different segment";
+  if (typeof segment.mailbox_id !== "string" || segment.mailbox_id.toLowerCase() !== grant.mailbox_id.toLowerCase()) return "went out from a different mailbox";
+  if (typeof segment.angle_fp === "string" && segment.angle_fp !== grant.angle_fp) return "was written for an earlier version of the pitch";
+  if (!nonEmpty(row.reviewed_by) || row.reviewed_by.startsWith("agent:")) return "wasn't approved by a person";
+  if (people && !people.has(row.reviewed_by)) return "wasn't approved by a person";
+  const reviewed = Date.parse(row.reviewed_at ?? "");
+  if (!Number.isFinite(reviewed) || reviewed > Date.parse(grant.at)) return "was approved after the segment was turned on";
+  const via = viaOf(row);
+  if (via !== "dashboard" && via !== "drafts") return via === "mcp" ? "was approved through MCP, not in Sonor" : "doesn't say where it was approved";
+  if (wasEdited(row)) return "was edited before it was approved";
+  if (readBackStatus(row) !== "verified") return "wasn't confirmed to have arrived intact";
+  return null;
+}
+function grantEvidenceRefusal(grant, refRows, scope) {
+  if (!grant) return "There's no grant.";
+  if (!isGrantableSegmentKey(scope?.key)) return "This segment can't be turned on.";
+  const rows = /* @__PURE__ */ new Map();
+  for (const row of refRows ?? []) if (row && typeof row.id === "string") rows.set(row.id, row);
+  const people = scope.people ? new Set(scope.people) : null;
+  if (grant.source === "first_email") {
+    const row = rows.get(grant.ref);
+    const refusal = evidenceRowRefusal(row, grant, scope, people);
+    if (refusal) return `The email this segment was turned on from ${refusal}.`;
+    if (row.reviewed_by !== grant.by) return "The email this segment was turned on from was approved by someone else.";
+    return null;
+  }
+  const receipts = Array.from(new Set(grant.receipts ?? []));
+  const needed = Math.max(1, Math.ceil(Number(scope.minMeasured) || 0));
+  if (receipts.length < needed) {
+    return `Only ${receipts.length} of the ${needed} approvals this segment needs to earn its own sending are on record.`;
+  }
+  for (const id of receipts) {
+    const refusal = evidenceRowRefusal(rows.get(id), grant, scope, people);
+    if (refusal) return `One of the approvals this segment earned its sending with ${refusal}.`;
+  }
+  return null;
+}
+var GRANTER_ROLES = /* @__PURE__ */ new Set(["owner", "admin"]);
+function segmentGranterEligible(roles) {
+  if (!roles) return false;
+  if (typeof roles.contact_type === "string" && roles.contact_type.trim().toLowerCase() === "agent") return false;
+  if (roles.is_platform_admin === true) return true;
+  return [roles.org_role, roles.project_role, roles.managing_org_role].some(
+    (role) => typeof role === "string" && GRANTER_ROLES.has(role.trim().toLowerCase())
+  );
+}
+var PUBLIC_MAILBOX_DOMAINS = [
+  "gmail.com",
+  "googlemail.com",
+  "yahoo.com",
+  "ymail.com",
+  "rocketmail.com",
+  "hotmail.com",
+  "outlook.com",
+  "live.com",
+  "msn.com",
+  "aol.com",
+  "aim.com",
+  "icloud.com",
+  "me.com",
+  "mac.com",
+  "protonmail.com",
+  "proton.me",
+  "pm.me",
+  "gmx.com",
+  "gmx.net",
+  "mail.com",
+  "zoho.com",
+  "zohomail.com",
+  "yandex.com",
+  "fastmail.com",
+  "hey.com",
+  "tutanota.com",
+  "tuta.io",
+  "att.net",
+  "sbcglobal.net",
+  "bellsouth.net",
+  "comcast.net",
+  "verizon.net",
+  "cox.net",
+  "charter.net",
+  "earthlink.net",
+  "frontier.com",
+  "windstream.net",
+  "centurylink.net",
+  "optonline.net",
+  "juno.com",
+  "netzero.net",
+  "roadrunner.com",
+  "rr.com",
+  "qq.com",
+  "163.com",
+  "126.com",
+  "mail.ru",
+  "web.de",
+  "t-online.de",
+  "orange.fr",
+  "free.fr",
+  "btinternet.com",
+  "sky.com",
+  "rogers.com",
+  "shaw.ca",
+  "sympatico.ca",
+  "bigpond.com"
+];
+var PUBLIC_DOMAIN_SET = new Set(PUBLIC_MAILBOX_DOMAINS);
+var PUBLIC_DOMAIN_FAMILY = /^(?:yahoo|ymail|hotmail|live|outlook|msn|aol|gmx|yandex)\.(?:[a-z]{2,3}|co\.[a-z]{2}|com\.[a-z]{2})$/;
+var PUBLIC_DOMAIN_SUFFIX = [".rr.com"];
+function isPublicMailboxDomain(value) {
+  if (typeof value !== "string") return false;
+  let domain = value.trim().toLowerCase().replace(/^mailto:/, "");
+  const at = domain.lastIndexOf("@");
+  if (at >= 0) domain = domain.slice(at + 1);
+  domain = domain.replace(/\.+$/, "").replace(/^www\./, "");
+  if (!domain) return false;
+  return PUBLIC_DOMAIN_SET.has(domain) || PUBLIC_DOMAIN_FAMILY.test(domain) || PUBLIC_DOMAIN_SUFFIX.some((suffix) => domain.endsWith(suffix));
+}
+function dripRowDisposition(row) {
+  const payload = isRecord(row?.payload) ? row.payload : {};
+  const execution = isRecord(payload._execution) ? payload._execution : {};
+  switch (row?.status) {
+    case "proposed":
+    case "approved":
+      return "live";
+    case "applied":
+    case "auto_applied":
+    case "executed":
+    case "reverted":
+      return "sent";
+    case "failed":
+      return execution.sent === true ? "sent" : "refile";
+    case "rejected": {
+      const decision = isRecord(row?.autonomy_decision) ? row.autonomy_decision : {};
+      if (decision.allowed === "off" && !row?.reviewed_by) return "refile";
+      const reason = row?.review_reason;
+      if (reason === "wrong_recipient") return "retire";
+      if (reason === "wrong_timing" || reason === "withdrawn") return "refile";
+      return "declined";
+    }
+    case "expired":
+    case "superseded":
+    case "discarded":
+      return "refile";
+    default:
+      return "live";
+  }
+}
+
+export { GRADUATION_BAR, NARRATIVE_PITCH_FIELDS, OUTREACH_CONTRACT_VERSION, OUTREACH_EMAIL_KIND, OUTREACH_WRITER_BADGE, PUBLIC_MAILBOX_DOMAINS, SEGMENT_STATES, UNSPECIFIED_INDUSTRY, activeSegmentGrant, dripRowDisposition, grantEvidenceRefusal, isGrantableSegmentKey, isPublicMailboxDomain, narrativeFingerprint, normalizeIndustry, outreachSegment, outreachSegmentLabel, parseOutreachSegmentKey, prospectIndustry, readSegmentGrants, segmentGrantCovers, segmentGranterEligible };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.7.1",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, and which Sonor records Signal reads into a project's knowledge and the address each one is stored under. Pure functions, no dependencies.",
+  "version": "2.8.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, and what a segment of outreach is and who may turn one on. Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -115,6 +115,16 @@
       "types": "./dist/editorial-media.d.ts",
       "import": "./dist/editorial-media.mjs",
       "require": "./dist/editorial-media.js"
+    },
+    "./business-claims": {
+      "types": "./dist/business-claims.d.ts",
+      "import": "./dist/business-claims.mjs",
+      "require": "./dist/business-claims.js"
+    },
+    "./outreach": {
+      "types": "./dist/outreach.d.ts",
+      "import": "./dist/outreach.mjs",
+      "require": "./dist/outreach.js"
     }
   },
   "typesVersions": {