@sonordev/contracts 2.16.0 → 2.18.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 2.18.0
+
+A minor release: one new entry, `@sonordev/contracts/decision-roles`. Every other entry is unchanged.
+
+- **What a job title says about a buying decision.** `DECISION_ROLES` is the four parts a person can play (`owner`, `decision_maker`, `influencer`, `gatekeeper`), strongest first, and `decisionRoleForTitle(title)` returns the one a title names, or `null` when it names none. The role comes from the title alone, by eight rules read in order with the first match deciding, so "Vice President of Sales" is a decision maker, "Executive Assistant to the CEO" is a gatekeeper and "Marketing Coordinator" is an influencer. "Principal" is an owner unless it names a job, so "Principal Engineer" has no role. A title is read whole (it isn't split on "&" or "/") and only its first 200 characters count. `DecisionRole` is the type. Anything that finds the people on a company's website can import it, so two scans of the same page can't give one person two roles.
+
+## 2.17.0
+
+A minor release: one new entry, `@sonordev/contracts/crm-disposition`. Every other entry is unchanged.
+
+- **What a rep's call outcome changes.** `SALES_DISPOSITIONS` is the three outcomes a rep taps after a call (`positive`, `negative`, `voicemail`), `NEGATIVE_REASONS` the five reasons a negative one carries (`not_a_fit`, `no_budget`, `has_agency`, `wrong_number`, `do_not_call`) and `SALES_DISPOSITION_LABELS` / `NEGATIVE_REASON_LABELS` what each button says. `dispositionTransitions(disposition, { reason? })` returns what the outcome does to the call (`outcomeType`, `sentiment`), the contact (`contactStage`), the company (`companyStatus`), today's reminder (`reminder`) and outreach (`stopsOutreach`, `suppresses`). A caller makes the moves; the contract only names them, so the API, the dashboard and the sales extension read one map. `dispositionProblem(disposition, { reason? })` says in a sentence why an outcome can't be applied, such as a negative one with no reason. `isSalesDisposition`, `isNegativeReason` and `CRM_DISPOSITION_CONTRACT_VERSION` (1) complete it.
+
 ## 2.16.0
 
 A minor release: `@sonordev/contracts/portfolio` gains the verification, a proof-stage section for builds a Lighthouse run can't honestly score. Every other entry is unchanged. Nothing was removed or renamed, but three things behave differently. `PortfolioSectionType` has a new member, so a `Record<PortfolioSectionType, ...>` you keep needs an entry for `portfolioVerification` before it type-checks. `caseStudyStageStatus` reads each section's `data`. A reported number's date has to be a real day.

package/README.md

@@ -40,6 +40,8 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/public-url-host` | Which literal hosts are refused as public fetch destinations (`isBlockedPublicUrlHost`) | the Sonor API and Signal's URL validators and network fetchers |
 | `@sonordev/contracts/funnels` | Incomplete drafts, launch definitions, command/readiness/receipt schemas, bounded public pages and presentation-only brand overrides | Sites, APIs, UI and agent adapters share the same rules |
 | `@sonordev/contracts/inbox` | Which inbox cards are decisions a bulk action leaves alone (`isDecisionCard`, `DECISION_INSIGHT_TYPES`) | Signal's inbox decides what "Mark all read" and "Dismiss all" may touch, the dashboard previews the same result before the write |
+| `@sonordev/contracts/crm-disposition` | What a rep's call outcome (positive, negative or left voicemail) changes on a prospect: the call's outcome and sentiment, the contact's stage, the company's status, today's reminder and outreach (`dispositionTransitions`), and the reasons a negative outcome carries | the Sonor API applies an outcome, the dashboard's calling screen offers the same three buttons and reasons, the sales extension stops flipping a company on dial |
+| `@sonordev/contracts/decision-roles` | The part a job title says a person plays in a buying decision (`DECISION_ROLES`: owner, decision maker, influencer, gatekeeper), read from the title alone by `decisionRoleForTitle` | the Sonor API's site-people scan and Signal's site-people scout read the same map |
 
 ## Focus closing artwork
 
@@ -90,6 +92,123 @@ list (a database filter that leaves them out of a bulk write, for one).
 key, a JSON `null` and a `null` `data` mean no proposal, and any other value,
 an empty string included, means one.
 
+## Call dispositions
+
+After a sales call a rep taps one of three outcomes. What each one changes on
+the prospect is written here once, so the API that applies it, the calling
+screen that offers it and the browser extension that dials from a list can't
+disagree about what "negative" moves.
+
+```ts
+import { dispositionProblem, dispositionTransitions } from '@sonordev/contracts/crm-disposition'
+
+dispositionProblem('negative', { reason: undefined })
+// 'A negative outcome needs a reason: not_a_fit, no_budget, has_agency, wrong_number, do_not_call.'
+
+dispositionTransitions('negative', { reason: 'do_not_call' })
+// {
+//   outcomeType: 'connected', sentiment: 'negative',
+//   contactStage: 'lost', companyStatus: 'not_a_fit',
+//   reminder: 'complete', stopsOutreach: false, suppresses: true,
+// }
+```
+
+| Outcome | Call | Contact stage | Company status | Today's reminder | Outreach |
+|---|---|---|---|---|---|
+| `positive` | `connected`, positive | `contacted` | `contacted` | `complete` | the drip stops (`stopsOutreach`) |
+| `negative` | `connected`, negative | `lost` | `not_a_fit` | `complete` | nothing, unless the reason is `do_not_call` (`suppresses`) |
+| `voicemail` | `left_voicemail`, no sentiment | unchanged | unchanged | `snooze_next_business_day` | nothing |
+
+- **The contract names the moves; the caller makes them.** `contactStage` is a
+  meaning (`contacted` or `lost`), not a project's stage key. `reminder:
+  'snooze_next_business_day'` leaves the instant to the caller, who knows the
+  project's time zone. A `null` in any field means leave that thing as it is.
+  A stage a rep picks by hand afterwards, such as `qualified`, is a separate
+  move that no outcome makes.
+- **A voicemail isn't a conversation.** It leaves the contact and company
+  alone, and a company only moves to `contacted` when someone answered. Dialing
+  a number moves nothing either; the outcome does.
+- **A negative outcome needs a reason.** `NEGATIVE_REASONS` is the five, in the
+  order a screen offers them: `not_a_fit`, `no_budget`, `has_agency`,
+  `wrong_number` and `do_not_call`. `NEGATIVE_REASON_LABELS` and
+  `SALES_DISPOSITION_LABELS` say what each button reads.
+- **`suppresses` is for `do_not_call` only.** It means write a suppression for
+  the prospect, which blocks every send on its own. It's separate from
+  `stopsOutreach`, which stops a drip the prospect is enrolled in, so a caller
+  that wants both for an "asked not to call" outcome stops the drip as well.
+- **Check an untrusted outcome first.** `dispositionProblem(disposition,
+  { reason })` returns one sentence about why an outcome can't be applied, or
+  `null`: a word that isn't one of the three, a negative outcome with no reason
+  or one that isn't a listed reason, or a reason on an outcome that takes none.
+  `isSalesDisposition` and `isNegativeReason` are the plain guards.
+  `dispositionTransitions` throws a `RangeError` for something that isn't a
+  disposition, and ignores a reason on any outcome but a negative one.
+- **Fresh each time.** `dispositionTransitions` returns a new object per call,
+  so changing one caller's copy never changes the next.
+
+`CRM_DISPOSITION_CONTRACT_VERSION` is bumped when an outcome's transitions
+change incompatibly. The wire values (the three outcomes and five reasons) are
+stored and sent, so they don't change.
+
+## Decision roles
+
+When a company's website lists its people, what each job title says about a
+buying decision has to be read the same way wherever the list is built.
+`decisionRoleForTitle` is that rule, written once, so a person can't be an
+influencer in one scan and an owner in another. The role comes from the title
+the page gives and never from a model's opinion: a model can find the people,
+and code decides the role.
+
+```ts
+import { DECISION_ROLES, decisionRoleForTitle } from '@sonordev/contracts/decision-roles'
+
+DECISION_ROLES                                          // ['owner', 'decision_maker', 'influencer', 'gatekeeper']
+decisionRoleForTitle('Vice President of Sales')         // 'decision_maker'
+decisionRoleForTitle('Executive Assistant to the CEO')  // 'gatekeeper'
+decisionRoleForTitle('Marketing Coordinator')           // 'influencer'
+decisionRoleForTitle('Principal Engineer')              // null
+```
+
+The first rule that matches the title decides, in this order:
+
+| Order | The title says | Role |
+|---|---|---|
+| 1 | an executive, administrative, office or personal assistant, "assistant to", secretary, receptionist, front desk | `gatekeeper` |
+| 2 | vice president (VP, SVP, EVP, AVP) | `decision_maker` |
+| 3 | owner, co-owner, founder, co-founder, proprietor, president, CEO, chief executive, managing, senior, name or equity partner, a lone "Partner", or "Principal" that isn't a job | `owner` |
+| 4 | a chief of something else (COO, CFO, CTO, CMO, "Chief ... Officer") | `decision_maker` |
+| 5 | general manager (or GM), director, operations manager, estimator, estimating manager, project manager, superintendent | `decision_maker` |
+| 6 | office manager, administrator, administrative, admin | `gatekeeper` |
+| 7 | marketing, HR, human resources, recruiting, talent acquisition, sales, business development | `influencer` |
+| 8 | coordinator | `gatekeeper` |
+
+- **Order is the meaning.** "Vice President of Sales" is a decision maker, not
+  an owner because it says president and not an influencer because it says
+  sales. "Marketing Director" is a decision maker, because director comes
+  before marketing. "Marketing Coordinator" is an influencer, because
+  marketing comes before coordinator. "Executive Assistant to the CEO" is a
+  gatekeeper, because the assistant rule comes before the CEO rule.
+- **"Principal" is an owner unless it names a job.** "Principal" alone is an
+  owner. "Principal Engineer", "Principal Architect", "Principal Consultant",
+  "Principal Designer", "Principal Developer" and "Principal Analyst" say
+  nothing about ownership, so they have no role.
+- **A title is read whole.** A title that names two jobs isn't split, and the
+  strongest role doesn't win; the first rule above that matches does. "Owner &
+  Office Manager" is an owner. "Receptionist & Owner" is a gatekeeper.
+- **"Assistant" alone isn't a gatekeeper.** "Assistant Project Manager" and
+  "Assistant General Manager" are decision makers, as the manager rules read
+  them. "Assistant to the Project Manager" is a gatekeeper.
+- **No title or no match is `null`.** "Technician", a bare "Manager",
+  "Accounting Manager", an empty string, whitespace, `null`, `undefined` and
+  anything that isn't a string all say no role. The map doesn't guess.
+- **Case, `&` and periods don't matter.** "C.E.O.", "FOUNDER & CEO" and
+  "Vice-President" read the same as their plain spellings.
+- **Only the start of a title is read.** Titles come off scraped pages, so
+  the first 200 characters decide and the rest is ignored.
+
+The four role values are stored and sent, so they don't change. `DECISION_ROLES`
+lists them strongest first, which is the order a screen should rank them in.
+
 ## Schema placeholders
 
 `schema-placeholders` finds the parts of a JSON-LD value that a template left

package/dist/crm-disposition.d.ts

@@ -0,0 +1,87 @@
+/**
+ * What a rep's three call outcomes do to a prospect. Single source of truth for
+ * the Sales Mode disposition: the Sonor API applies it when a rep taps an
+ * outcome, the dashboard shows the same three buttons and reasons, and the
+ * sales extension stops guessing at 'contacted' when a number is dialed. One
+ * map, so the three can't disagree about what "negative" moves.
+ *
+ *   positive   a connected call that went well. The contact is `contacted`,
+ *              the company is `contacted`, today's reminder is done and the
+ *              prospect's drip stops, since they're now in a conversation.
+ *   negative   a connected call that ended the lead. The contact is `lost`
+ *              (a reason is required), the company is `not_a_fit`, today's
+ *              reminder is done. Only "asked not to call" suppresses outreach.
+ *   voicemail  nobody picked up. Nothing about the contact or company changes,
+ *              because a voicemail isn't a conversation, and today's reminder
+ *              moves to the next business day.
+ *
+ * The contract names the moves; the caller makes them. Which stage key
+ * `contacted` or `lost` is on a given project, which instant "the next business
+ * day" is in the project's time zone, and how a suppression row is written all
+ * stay with the Sonor API. A stage the rep picks by hand afterwards (qualified,
+ * say) is a separate move that no disposition makes.
+ *
+ * Pure data and a few small functions, no dependencies. The wire values (the
+ * three dispositions, the five reasons) are stored and sent, so they never
+ * change; a different map is a new CRM_DISPOSITION_CONTRACT_VERSION.
+ */
+/** Bumped when a disposition's transitions change incompatibly. */
+export declare const CRM_DISPOSITION_CONTRACT_VERSION = 1;
+/** The three words a rep taps after a call, in button order. */
+export declare const SALES_DISPOSITIONS: readonly ['positive', 'negative', 'voicemail'];
+export type SalesDisposition = (typeof SALES_DISPOSITIONS)[number];
+/** What each button says. */
+export declare const SALES_DISPOSITION_LABELS: Record<SalesDisposition, string>;
+/** The one-tap reasons a negative outcome must carry, in the order they're offered. */
+export declare const NEGATIVE_REASONS: readonly ['not_a_fit', 'no_budget', 'has_agency', 'wrong_number', 'do_not_call'];
+export type NegativeReason = (typeof NEGATIVE_REASONS)[number];
+/** What each reason says on its button. `do_not_call` is the one that suppresses outreach. */
+export declare const NEGATIVE_REASON_LABELS: Record<NegativeReason, string>;
+/** Whether a value is one of the three dispositions, spelled exactly. */
+export declare function isSalesDisposition(value: unknown): value is SalesDisposition;
+/** Whether a value is one of the five negative reasons, spelled exactly. */
+export declare function isNegativeReason(value: unknown): value is NegativeReason;
+/** What a disposition changes. A null leaves that thing as it is. */
+export interface DispositionTransitions {
+    /** The call row's `outcome_type`. */
+    outcomeType: 'connected' | 'left_voicemail';
+    /** The call row's `sentiment`. */
+    sentiment: 'positive' | 'negative' | null;
+    /** The contact's stage, by meaning rather than by a project's stage key. */
+    contactStage: 'contacted' | 'lost' | null;
+    /** The target company's `status`. */
+    companyStatus: 'contacted' | 'not_a_fit' | null;
+    /**
+     * What happens to the prospect's reminder due today: finish it, or push it to
+     * 09:00 on the project's next business day. No disposition leaves it alone
+     * today; a caller still handles null so that never has to be a breaking change.
+     */
+    reminder: 'complete' | 'snooze_next_business_day' | null;
+    /** Stop the prospect's enrolled drip or sequence. */
+    stopsOutreach: boolean;
+    /**
+     * Write an outreach suppression for the prospect. That blocks every send on
+     * its own, so it isn't also a `stopsOutreach`. Only a negative outcome whose
+     * reason is `do_not_call` suppresses.
+     */
+    suppresses: boolean;
+}
+export interface DispositionOptions {
+    /** The negative outcome's reason. Read for a negative outcome only. */
+    reason?: NegativeReason | null;
+}
+/**
+ * What a disposition changes. Returns a fresh object each call, so a caller can
+ * adjust its copy without touching the next caller's. Throws a RangeError for a
+ * value that isn't a disposition: check an untrusted one with
+ * `dispositionProblem` first.
+ */
+export declare function dispositionTransitions(disposition: SalesDisposition, opts?: DispositionOptions): DispositionTransitions;
+/**
+ * Why a disposition and its reason can't be applied, in one sentence, or null
+ * when they can. A negative outcome needs a reason and no other outcome takes
+ * one. A null or undefined reason means none was given.
+ */
+export declare function dispositionProblem(disposition: unknown, opts?: {
+    reason?: unknown;
+}): string | null;

package/dist/crm-disposition.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// src/contracts/crm-disposition.ts
+var CRM_DISPOSITION_CONTRACT_VERSION = 1;
+var SALES_DISPOSITIONS = ["positive", "negative", "voicemail"];
+var SALES_DISPOSITION_LABELS = {
+  positive: "Positive",
+  negative: "Negative",
+  voicemail: "Left voicemail"
+};
+var NEGATIVE_REASONS = ["not_a_fit", "no_budget", "has_agency", "wrong_number", "do_not_call"];
+var NEGATIVE_REASON_LABELS = {
+  not_a_fit: "Not a fit",
+  no_budget: "No budget",
+  has_agency: "Has an agency",
+  wrong_number: "Wrong number",
+  do_not_call: "Asked not to call"
+};
+function isSalesDisposition(value) {
+  return typeof value === "string" && SALES_DISPOSITIONS.includes(value);
+}
+function isNegativeReason(value) {
+  return typeof value === "string" && NEGATIVE_REASONS.includes(value);
+}
+var TRANSITIONS = {
+  positive: {
+    outcomeType: "connected",
+    sentiment: "positive",
+    contactStage: "contacted",
+    companyStatus: "contacted",
+    reminder: "complete",
+    stopsOutreach: true
+  },
+  negative: {
+    outcomeType: "connected",
+    sentiment: "negative",
+    contactStage: "lost",
+    companyStatus: "not_a_fit",
+    reminder: "complete",
+    stopsOutreach: false
+  },
+  voicemail: {
+    outcomeType: "left_voicemail",
+    sentiment: null,
+    contactStage: null,
+    companyStatus: null,
+    reminder: "snooze_next_business_day",
+    stopsOutreach: false
+  }
+};
+function dispositionTransitions(disposition, opts = {}) {
+  if (!isSalesDisposition(disposition)) {
+    throw new RangeError(`Not a sales disposition: ${String(disposition)}`);
+  }
+  return { ...TRANSITIONS[disposition], suppresses: disposition === "negative" && opts.reason === "do_not_call" };
+}
+function dispositionProblem(disposition, opts = {}) {
+  if (!isSalesDisposition(disposition)) {
+    return `The outcome has to be one of ${SALES_DISPOSITIONS.join(", ")}.`;
+  }
+  const reason = opts.reason;
+  const given = reason !== null && reason !== void 0;
+  if (disposition === "negative") {
+    if (!given) return `A negative outcome needs a reason: ${NEGATIVE_REASONS.join(", ")}.`;
+    if (!isNegativeReason(reason)) return `The reason has to be one of ${NEGATIVE_REASONS.join(", ")}.`;
+    return null;
+  }
+  return given ? `Only a negative outcome takes a reason, and this one is ${disposition}.` : null;
+}
+
+exports.CRM_DISPOSITION_CONTRACT_VERSION = CRM_DISPOSITION_CONTRACT_VERSION;
+exports.NEGATIVE_REASONS = NEGATIVE_REASONS;
+exports.NEGATIVE_REASON_LABELS = NEGATIVE_REASON_LABELS;
+exports.SALES_DISPOSITIONS = SALES_DISPOSITIONS;
+exports.SALES_DISPOSITION_LABELS = SALES_DISPOSITION_LABELS;
+exports.dispositionProblem = dispositionProblem;
+exports.dispositionTransitions = dispositionTransitions;
+exports.isNegativeReason = isNegativeReason;
+exports.isSalesDisposition = isSalesDisposition;

package/dist/crm-disposition.mjs

@@ -0,0 +1,69 @@
+// src/contracts/crm-disposition.ts
+var CRM_DISPOSITION_CONTRACT_VERSION = 1;
+var SALES_DISPOSITIONS = ["positive", "negative", "voicemail"];
+var SALES_DISPOSITION_LABELS = {
+  positive: "Positive",
+  negative: "Negative",
+  voicemail: "Left voicemail"
+};
+var NEGATIVE_REASONS = ["not_a_fit", "no_budget", "has_agency", "wrong_number", "do_not_call"];
+var NEGATIVE_REASON_LABELS = {
+  not_a_fit: "Not a fit",
+  no_budget: "No budget",
+  has_agency: "Has an agency",
+  wrong_number: "Wrong number",
+  do_not_call: "Asked not to call"
+};
+function isSalesDisposition(value) {
+  return typeof value === "string" && SALES_DISPOSITIONS.includes(value);
+}
+function isNegativeReason(value) {
+  return typeof value === "string" && NEGATIVE_REASONS.includes(value);
+}
+var TRANSITIONS = {
+  positive: {
+    outcomeType: "connected",
+    sentiment: "positive",
+    contactStage: "contacted",
+    companyStatus: "contacted",
+    reminder: "complete",
+    stopsOutreach: true
+  },
+  negative: {
+    outcomeType: "connected",
+    sentiment: "negative",
+    contactStage: "lost",
+    companyStatus: "not_a_fit",
+    reminder: "complete",
+    stopsOutreach: false
+  },
+  voicemail: {
+    outcomeType: "left_voicemail",
+    sentiment: null,
+    contactStage: null,
+    companyStatus: null,
+    reminder: "snooze_next_business_day",
+    stopsOutreach: false
+  }
+};
+function dispositionTransitions(disposition, opts = {}) {
+  if (!isSalesDisposition(disposition)) {
+    throw new RangeError(`Not a sales disposition: ${String(disposition)}`);
+  }
+  return { ...TRANSITIONS[disposition], suppresses: disposition === "negative" && opts.reason === "do_not_call" };
+}
+function dispositionProblem(disposition, opts = {}) {
+  if (!isSalesDisposition(disposition)) {
+    return `The outcome has to be one of ${SALES_DISPOSITIONS.join(", ")}.`;
+  }
+  const reason = opts.reason;
+  const given = reason !== null && reason !== void 0;
+  if (disposition === "negative") {
+    if (!given) return `A negative outcome needs a reason: ${NEGATIVE_REASONS.join(", ")}.`;
+    if (!isNegativeReason(reason)) return `The reason has to be one of ${NEGATIVE_REASONS.join(", ")}.`;
+    return null;
+  }
+  return given ? `Only a negative outcome takes a reason, and this one is ${disposition}.` : null;
+}
+
+export { CRM_DISPOSITION_CONTRACT_VERSION, NEGATIVE_REASONS, NEGATIVE_REASON_LABELS, SALES_DISPOSITIONS, SALES_DISPOSITION_LABELS, dispositionProblem, dispositionTransitions, isNegativeReason, isSalesDisposition };

package/dist/decision-roles.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What a job title says about a person's part in a buying decision. Single
+ * source of truth for the site-people scan: the Sonor API's deterministic scan
+ * (JSON-LD persons) and Signal's site-people scout both read this map, so the
+ * same person can't be an influencer on one side and an owner on the other.
+ *
+ * The role is never a model's opinion. A model finds the people; the title the
+ * page gives them decides the role, by the rules below, in this order (first
+ * match wins):
+ *
+ *   gatekeeper      someone who works for a person, whatever that person's
+ *                   title is: "Executive Assistant to the President",
+ *                   "Receptionist"
+ *   decision_maker  a vice president, matched before the president rule can
+ *                   claim the word
+ *   owner           owner, founder, president, CEO, a managing, senior, name
+ *                   or equity partner, a lone "Partner", and "Principal"
+ *                   unless it names a job ("Principal Engineer")
+ *   decision_maker  a chief of something that isn't the CEO, a general
+ *                   manager (or GM), a director, an operations or project
+ *                   manager, an estimator, a superintendent
+ *   gatekeeper      an office manager, an administrator
+ *   influencer      marketing, HR, recruiting, sales, business development
+ *   gatekeeper      a coordinator, last of all
+ *
+ * So "Vice President of Sales" is a decision maker (not an owner because it
+ * says president, not an influencer because it says sales), "Marketing
+ * Director" is a decision maker (director beats marketing) and "Marketing
+ * Coordinator" is an influencer. A title that names none of these
+ * ("Technician", a bare "Manager") has no role: no guess.
+ *
+ * Pure data and one small function, no dependencies. The four role values are
+ * stored and sent, so they never change.
+ */
+/** The four parts a person can play in a buying decision, strongest first. */
+export declare const DECISION_ROLES: readonly ['owner', 'decision_maker', 'influencer', 'gatekeeper'];
+export type DecisionRole = (typeof DECISION_ROLES)[number];
+/** The buying role a job title says, or null when it says none ("Technician", "Manager", no title). */
+export declare function decisionRoleForTitle(title: string | null | undefined): DecisionRole | null;

package/dist/decision-roles.js

@@ -0,0 +1,31 @@
+'use strict';
+
+// src/contracts/decision-roles.ts
+var DECISION_ROLES = ["owner", "decision_maker", "influencer", "gatekeeper"];
+var MAX_TITLE_LENGTH = 200;
+var RULES = [
+  // Someone who works for a person, whatever that person's title is.
+  [/\b(?:executive|administrative|admin|office|personal)\s+assistant\b|\bassistant to\b|\bsecretary\b|\breceptionist\b|\bfront desk\b/, "gatekeeper"],
+  // A vice president before the president rule below can claim the word.
+  [/\b(?:vice[ -]president|vp|svp|evp|avp)\b/, "decision_maker"],
+  [
+    /\b(?:owner|co-?owner|founder|co-?founder|proprietor|president|ceo|chief executive(?: officer)?|managing partner|senior partner|name partner|equity partner)\b|\bprincipal\b(?!\s+(?:engineer|architect|consultant|designer|developer|analyst))|^partner$/,
+    "owner"
+  ],
+  // Chief of something else (not the CEO, matched above).
+  [/\bchief\b.*\bofficer\b|\b(?:coo|cfo|cto|cmo)\b/, "decision_maker"],
+  [/\b(?:general manager|gm|director|operations manager|estimator|estimating manager|project manager|superintendent)\b/, "decision_maker"],
+  [/\boffice manager\b|\badministrat(?:or|ive)\b|\badmin\b/, "gatekeeper"],
+  [/\b(?:marketing|hr|human resources|recruit(?:er|ing)|talent acquisition|sales|business development)\b/, "influencer"],
+  [/\bcoordinator\b/, "gatekeeper"]
+];
+function decisionRoleForTitle(title) {
+  if (typeof title !== "string") return null;
+  const t = title.slice(0, MAX_TITLE_LENGTH).toLowerCase().replace(/&/g, " and ").replace(/\./g, "").replace(/\s+/g, " ").trim();
+  if (!t) return null;
+  for (const [pattern, role] of RULES) if (pattern.test(t)) return role;
+  return null;
+}
+
+exports.DECISION_ROLES = DECISION_ROLES;
+exports.decisionRoleForTitle = decisionRoleForTitle;

package/dist/decision-roles.mjs

@@ -0,0 +1,28 @@
+// src/contracts/decision-roles.ts
+var DECISION_ROLES = ["owner", "decision_maker", "influencer", "gatekeeper"];
+var MAX_TITLE_LENGTH = 200;
+var RULES = [
+  // Someone who works for a person, whatever that person's title is.
+  [/\b(?:executive|administrative|admin|office|personal)\s+assistant\b|\bassistant to\b|\bsecretary\b|\breceptionist\b|\bfront desk\b/, "gatekeeper"],
+  // A vice president before the president rule below can claim the word.
+  [/\b(?:vice[ -]president|vp|svp|evp|avp)\b/, "decision_maker"],
+  [
+    /\b(?:owner|co-?owner|founder|co-?founder|proprietor|president|ceo|chief executive(?: officer)?|managing partner|senior partner|name partner|equity partner)\b|\bprincipal\b(?!\s+(?:engineer|architect|consultant|designer|developer|analyst))|^partner$/,
+    "owner"
+  ],
+  // Chief of something else (not the CEO, matched above).
+  [/\bchief\b.*\bofficer\b|\b(?:coo|cfo|cto|cmo)\b/, "decision_maker"],
+  [/\b(?:general manager|gm|director|operations manager|estimator|estimating manager|project manager|superintendent)\b/, "decision_maker"],
+  [/\boffice manager\b|\badministrat(?:or|ive)\b|\badmin\b/, "gatekeeper"],
+  [/\b(?:marketing|hr|human resources|recruit(?:er|ing)|talent acquisition|sales|business development)\b/, "influencer"],
+  [/\bcoordinator\b/, "gatekeeper"]
+];
+function decisionRoleForTitle(title) {
+  if (typeof title !== "string") return null;
+  const t = title.slice(0, MAX_TITLE_LENGTH).toLowerCase().replace(/&/g, " and ").replace(/\./g, "").replace(/\s+/g, " ").trim();
+  if (!t) return null;
+  for (const [pattern, role] of RULES) if (pattern.test(t)) return role;
+  return null;
+}
+
+export { DECISION_ROLES, decisionRoleForTitle };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.16.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, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, which literal hosts are refused as public fetch destinations, and which inbox cards are decisions a bulk action leaves alone. Pure functions, no dependencies.",
+  "version": "2.18.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, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, which literal hosts are refused as public fetch destinations, which inbox cards are decisions a bulk action leaves alone, what a rep's call outcome (positive, negative or left voicemail) changes on a prospect, and which buying role a job title says (owner, decision maker, influencer or gatekeeper). Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -155,6 +155,16 @@
       "types": "./dist/funnels.d.ts",
       "import": "./dist/funnels.mjs",
       "require": "./dist/funnels.js"
+    },
+    "./crm-disposition": {
+      "types": "./dist/crm-disposition.d.ts",
+      "import": "./dist/crm-disposition.mjs",
+      "require": "./dist/crm-disposition.js"
+    },
+    "./decision-roles": {
+      "types": "./dist/decision-roles.d.ts",
+      "import": "./dist/decision-roles.mjs",
+      "require": "./dist/decision-roles.js"
     }
   },
   "typesVersions": {