@sonordev/contracts 2.17.0 → 2.18.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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.

package/README.md

@@ -41,6 +41,7 @@ pnpm add @sonordev/contracts
 | `@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
 
@@ -149,6 +150,65 @@ dispositionTransitions('negative', { reason: 'do_not_call' })
 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/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.17.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, and what a rep's call outcome (positive, negative or left voicemail) changes on a prospect. 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",
@@ -160,6 +160,11 @@
       "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": {