@sonordev/contracts 2.15.0 → 2.17.0

package/CHANGELOG.md

@@ -1,12 +1,26 @@
 # Changelog
 
-## Unreleased
+## 2.17.0
 
-- `llms` holds the rules for what llms.txt says about each page, so the Sonor API and site-kit's local generator build page lines the same way. New: `pickLlmsPageDescription` and `resolveLlmsPageDescription` (summary, curated meta, served meta, schema description, then a cleaned scrape), `llmsPageListNote`, `llmsPageTitle`, `isLlmsListablePage`, `selectLlmsPages`, `groupLlmsPages`, `llmsBlockquoteSummary`, `llmsContactLines`, `llmsAbsoluteUrl`, `cleanScrapedPageText`, `stripContactDetails`, `stripPageFiller` and `LLMS_DESCRIPTION_MAX_LENGTH`.
-- `sanitizeLlmsPublicSummary` removes a phone number or email address, with the "call" or "email us at" in front of it, and a "This page covers" lead-in, and keeps the rest. It used to return `null` for any summary that mentioned a phone or email, and a page with no summary is described by its scrape.
+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.
+
+- **A new section type, `portfolioVerification`.** An app behind a sign-in has a public door and little else a browser can reach, and a Lighthouse score for the door reads as a score for the app. A verification is a short list of checks instead (one to eight). Each says what it's called (`label`), what came out (`result`), what was measured (`measured`), where (`where`: a URL, a screen or a file), with which tool and settings (`method`), on what day (`date`, YYYY-MM-DD) and, required, what it doesn't cover (`scope`). A check that can't state its limits isn't a check. Every check is something you ran yourself; a figure a client gave you stays a reported number in Results.
+- **It sits in the proof stage**, after `portfolioPerformance` and `portfolioSpeedComparison`. `PORTFOLIO_SECTION_TYPES` grows by one entry, so the `PORTFOLIO_SECTION_ORDER` value of each outcome section and the CTA rises by one. The reading order itself is unchanged.
+- **It completes the proof stage on its own, once it has something to show.** `caseStudyStageStatus` counts a verification toward the proof stage only when its `data` holds at least one check a page may show (`readVerificationChecks`). An empty verification, which is what an editor's Add button creates, leaves the stage incomplete and says so, instead of reading as a finished proof stage over an empty one. `SectionLike` gains an optional `data`; pass each section's `data`, because a caller that passes only `sectionType` sees a verification as empty. `STAGE_CORE_SECTION` still names Performance as the section to offer when a stage is empty; `STAGE_CORE_ALTERNATES` lists the sections that stand in for a stage's core and `stageCoreSections(stage)` returns the core and its stand-ins together. Nothing is gated on the kind of project, because the status doesn't know it. An empty proof stage now says a verification is the other way to fill it.
+- **One rule for what a day is.** `isRealDay(value)` says whether a string is a real calendar day written YYYY-MM-DD. A verification's `date` and a reported number's `reportedBy.date` both ask it. The reported number's date used to go through `Date.parse`, which rolls `2026-02-31` into March and let it pass; it's now refused, so a number can't be attributed to a day that doesn't exist.
+- **Validating and reading one.** `PortfolioVerificationData` and `VerificationCheck` are the shapes. `verificationProblems(data, { latestDay? })` lists what's wrong, one sentence each, with the check's position: a missing field, a field over its limit (`VERIFICATION_FIELD_MAX_CHARS`) or not one line of plain text (a control character, a zero-width or direction mark), more than `VERIFICATION_MAX_CHECKS` checks, a day that doesn't exist, a day before `VERIFICATION_EARLIEST_DAY` or after `latestVerificationDay()` (tomorrow in UTC, so a check run today in any time zone passes and one that hasn't happened doesn't; `readVerificationChecks` applies the same bound), a `where` that says nothing ("n/a", one plain word), carries a username or password, or names localhost or a private network, a field the check doesn't have, and a scope that doesn't state a limit (`isVacuousScope`): it has to be a sentence with a word that marks where coverage stops, such as "only", "not" or "without", so placeholders ("N/A", "None at all"), coverage claims ("All screens") and denied limits ("No restrictions") are refused. It reads English, and it can see that a limit was written, not that it's true, so a person still reads the scope. `isPlaceholderText(text)` is the test for a line with nothing in it ("n/a", "see above"), shared by `where` and `scope`. `readVerificationChecks(data)` returns the checks that can be shown, trimmed and in order, and leaves out any that fail, so a check with no scope line, or a placeholder for one, doesn't print. `verificationLink(where)` returns a plain `http` or `https` address with a public host as a link and everything else, localhost included, as null. `PORTFOLIO_VERIFICATION_JSON_SCHEMA` is the same shape as a schema.
 
 ## 2.15.0
 
+- `llms` holds the rules for what llms.txt says about each page, so the Sonor API and site-kit's local generator build page lines the same way. New: `pickLlmsPageDescription` and `resolveLlmsPageDescription` (summary, curated meta, served meta, schema description, then a cleaned scrape), `llmsPageListNote`, `llmsPageTitle`, `isLlmsListablePage`, `selectLlmsPages`, `groupLlmsPages`, `llmsBlockquoteSummary`, `llmsContactLines`, `llmsAbsoluteUrl`, `cleanScrapedPageText`, `stripContactDetails`, `stripPageFiller` and `LLMS_DESCRIPTION_MAX_LENGTH`.
+- `sanitizeLlmsPublicSummary` removes a phone number or email address, with the "call" or "email us at" in front of it, and a "This page covers" lead-in, and keeps the rest. It used to return `null` for any summary that mentioned a phone or email, and a page with no summary is described by its scrape.
+
 - Add `@sonordev/contracts/funnels` with bounded incomplete drafts, launch-ready definitions, command envelopes, brand presentation overrides, readiness and public page validation. Runtime parsers and JSON schemas share the same shapes.
 - Add the canonical funnel content cache tag and campaign normalization used by managed landing pages. Existing publication logo roles and inbox behavior remain available.
 

package/README.md

@@ -25,7 +25,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/slot-content` | What a slot of each kind may hold (`normalizeSlotValue`), safe links, the rich-text parser. No `crypto`, so browsers can import it | the Sonor API, site-kit, the dashboard editor |
 | `@sonordev/contracts/site-cache` | The cache tags a site's Sonor fetches carry and the revalidation route's path, payload and ping | site-kit tags and serves the route, the Sonor API calls it |
 | `@sonordev/contracts/site-edit` | Edit on page: the messages between a framed site and the dashboard, trusted origins, how a slot is found on the page | site-kit's overlay, the dashboard's visual editor |
-| `@sonordev/contracts/portfolio` | The case study arc: every section type, the stage each belongs to, the reading order, the narrative that opens each stage and the thread from a challenge to the phase that cleared it and the result that proves it. Also where a portfolio number comes from and which may headline, and the live-frame message | the Sonor API, Signal's case-study writer, the dashboard's editor, agency-site-kit |
+| `@sonordev/contracts/portfolio` | The case study arc: every section type, the stage each belongs to, the reading order, the narrative that opens each stage and the thread from a challenge to the phase that cleared it and the result that proves it. The verification, the proof for a build a Lighthouse run can't score: checks that each state what they don't cover. Also where a portfolio number comes from and which may headline, and the live-frame message | the Sonor API, Signal's case-study writer, the dashboard's editor, agency-site-kit |
 | `@sonordev/contracts/proposal-sitemap` | How a proposal's site plan counts its pages, when its before-and-after comparison may show, and whether the page counts stated elsewhere in the proposal add up | the Sonor API, Signal's proposal writer, the dashboard's proposal pages |
 | `@sonordev/contracts/voice` | The house voice's contraction rule. `findUncontracted` and `contractText` find and apply full forms that should be contractions; `findContracted` finds the contractions a question-form heading should expand | anything that checks or rewrites copy: Sonor's APIs and dashboard |
 | `@sonordev/contracts/error-page` | Whether stored text is a rendered error page rather than a page's content, and whether generated copy says the page itself is missing | anything that stores page text or writes page copy from it: the Sonor API's page-view and sitemap writers, Signal's metadata generators |
@@ -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
@@ -871,8 +930,12 @@ the dashboard that edits it and every site that renders it.
   with its sections; a stage with nothing in it is left out.
 - **`caseStudyStageStatus(sections)`** reports all four stages, complete
   only when the stage's core section (`STAGE_CORE_SECTION`: challenges,
-  strategy, performance, results) is present, with one sentence on what's
-  missing. The dashboard shows it beside the editor.
+  strategy, performance, results) or a stand-in for it
+  (`STAGE_CORE_ALTERNATES`: a verification completes the proof stage) is
+  present, with one sentence on what's missing. A stand-in counts only when
+  its `data` holds something a page can show, so pass each section's `data`
+  along with its `sectionType`. `stageCoreSections(stage)` lists the core and
+  its stand-ins. The dashboard shows the status beside the editor.
 - **Stage names.** The ids are fixed; what people see isn't. A site names
   the four stages in the dashboard ("Heat", "Shape", "Temper", "Finish"),
   per project like the rest of its branding, and `CaseStudyStageNames`
@@ -891,6 +954,100 @@ the dashboard that edits it and every site that renders it.
   phases, results })` names every challenge nothing resolves or proves and
   every dangling reference. It judges links only where ids were written, so
   content from before the thread passes.
+- **`isRealDay(value)`** is the one rule for whether a string is a day: a real
+  calendar day written YYYY-MM-DD. `2026-02-31` isn't one, and neither is a
+  year under 100. A verification's `date` and a reported number's
+  `reportedBy.date` both ask it, and so can anything else that stores a day.
+
+### The verification
+
+A Lighthouse run can only score what a browser reaches without signing in. For
+an app whose screens sit behind a login, that's the sign-in page, and a score
+for the door reads as a score for the app. The `portfolioVerification` section
+is the proof stage for that build: a short list of checks (one to
+`VERIFICATION_MAX_CHECKS`, eight), each stating what it covers and, required,
+what it doesn't.
+
+```ts
+import {
+  readVerificationChecks,
+  verificationLink,
+  verificationProblems,
+  type PortfolioVerificationData,
+} from '@sonordev/contracts/portfolio'
+
+const data: PortfolioVerificationData = {
+  checks: [
+    {
+      label: 'Sign-in page, mobile speed',
+      result: 'Performance 89',
+      measured: 'The Lighthouse performance score of the page a visitor sees before signing in',
+      where: 'https://example.com/login',
+      method: 'Lighthouse 13, mobile preset, median of 3 runs',
+      date: '2026-10-20',
+      scope: 'The sign-in page only; the screens behind it were not measured.',
+    },
+  ],
+}
+
+verificationProblems(data) // []
+readVerificationChecks(data) // the checks a page may print
+verificationLink(data.checks[0].where) // 'https://example.com/login'
+```
+
+- **Every field is required**, and each is one line of plain text within its
+  limit (`VERIFICATION_FIELD_MAX_CHARS`): no line break, tab or other control
+  character, and no zero-width or direction mark. `date` is a real day, YYYY-MM-DD, no
+  earlier than `VERIFICATION_EARLIEST_DAY` (2000-01-01) and no later than
+  `latestVerificationDay()`, which is tomorrow in UTC. That lets a check run
+  today in a time zone ahead of your server through and refuses one that hasn't
+  happened. `verificationProblems` and `readVerificationChecks` both apply it
+  without being asked; pass `{ latestDay }` to fix the clock.
+- **`where` points somewhere a reader can go or look.** A public web address,
+  or a screen or file named in words ("the migrations in the repository") or as
+  a path. A placeholder ("n/a", "here"; `isPlaceholderText` is the test), one
+  plain word, a username or password
+  in an address, and localhost or a private network are refused. One thing no
+  rule can catch is a view link with a token in its path or query: if the link
+  works for whoever holds it, don't put it here.
+- **`scope` states a limit.** It's what the check does _not_ cover, written as a
+  sentence with a word that marks where coverage stops: "only", "not", "except",
+  "without", or a contraction like "weren't". A placeholder ("N/A", "none",
+  "TBD"), a coverage claim ("All screens", "Fully tested") and a denied limit
+  ("No restrictions") are refused (`isVacuousScope`). "Desktop only" and
+  "Counted, not exercised" pass. Write what the check leaves out: "Counted from
+  the migrations; no query ran as a signed-in user." The test reads English, and
+  it can see that a limit was written, not that it's true, so a person still
+  reads the scope before a case study goes live.
+- **`verificationProblems(data, options)`** names every problem with the check's
+  position (`checks[1].scope is required: say what the check does not cover`),
+  and refuses a field a check doesn't have. Whatever stores a verification
+  should run it first. Nothing calls it for you, and until a write path does,
+  stored data can hold anything, which is why `readVerificationChecks` checks
+  again before a page prints.
+- **`readVerificationChecks(data)`** is what a page prints: the checks that pass,
+  trimmed and in order, up to the limit. A check that fails is left out, so one
+  with no scope line, or a placeholder for one, doesn't print, and a field a
+  newer writer added is ignored.
+- **`verificationLink(where)`** returns the address when `where` is exactly one
+  `http` or `https` URL with no credentials in it and a public host, and null
+  for a screen name, a file path, localhost or anything else, so only a real
+  public address becomes a link.
+- **Every check is something you ran.** There's no `source` on a check. A figure
+  the client gave you stays in Results as a reported number, with the person
+  behind it.
+- **`PORTFOLIO_VERIFICATION_JSON_SCHEMA`** is the same shape for agents. What a
+  `scope` or a `where` says, and whether a `date` is a real day in range, are
+  `verificationProblems`' job; a schema can't express them.
+
+It completes the proof stage on its own (`STAGE_CORE_ALTERNATES`), once it has
+at least one check `readVerificationChecks` would show. An empty verification,
+which is what an editor's Add button creates, leaves the stage incomplete and
+says why; `caseStudyStageStatus` reads that from each section's `data`, and a
+caller that passes only `sectionType` sees a verification as empty. Any project
+can use it. The status doesn't know the kind of project, so nothing is gated on
+it; a site that wants a Lighthouse score for a public site keeps writing a
+Performance section.
 
 ## Why it exists
 

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/frame-ready.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The live-frame handshake, on its own so it stays small.
+ *
+ * A site-kit page framed by another origin posts FRAME_READY_MESSAGE to its
+ * embedder once it has painted (shared/frame.ts, announceFrameReady); a case
+ * study's device frames (the portfolio renderers) are the ones listening.
+ *
+ * This is a leaf module on purpose. shared/frame.ts runs in every page's
+ * analytics and layout graph, and `./portfolio` is a large module of case
+ * study rules: importing the message from there put all of it in every
+ * page's eager bundle. Single source of truth for the message: `./portfolio`
+ * re-exports it (so `@sonordev/contracts/portfolio` and
+ * `@sonordev/site-kit/portfolio/contract` still carry it) and shared/frame.ts
+ * imports it from here. Keep it free of other imports.
+ */
+/** The message a cross-origin-framed site-kit page posts to its embedder once it has painted. */
+export declare const FRAME_READY_MESSAGE: 'sonor:frame-ready';
+export interface FrameReadyMessage {
+    type: typeof FRAME_READY_MESSAGE;
+    v: 1;
+}
+/** True for a {@link FrameReadyMessage}, for the embedder's message handler. */
+export declare function isFrameReadyMessage(data: unknown): data is FrameReadyMessage;