@sonordev/contracts 2.16.0 → 2.17.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 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,7 @@ 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 |
 
 ## Focus closing artwork
 
@@ -90,6 +91,64 @@ 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.
+
 ## 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/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.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.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -155,6 +155,11 @@
       "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"
     }
   },
   "typesVersions": {