@sonordev/contracts 2.12.0 → 2.15.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## Unreleased
+
+- `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.
+
+## 2.15.0
+
+- 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.
+
+## 2.14.0
+
+- Publication branding adds optional `identity.squareLogoUrl` and `identity.fullLogoUrl` for a square publication mark and its full/display logo. Both use the existing URL validation and support `null` in patches to clear an override. Theme variants in `identity.logos`, the text `identity.wordmark`, and publisher attribution remain separate. Existing saved profiles keep their shape and version.
+- Add `@sonordev/contracts/inbox`: the one rule for which inbox cards are decisions that "Mark all read" and "Dismiss all" leave alone. `isDecisionCard(card)` counts an approval, the ledger's unconfirmed-action card and any card carrying a proposal; `DECISION_INSIGHT_TYPES`, `APPROVAL_NEEDED_INSIGHT_TYPE` and `LEDGER_UNCONFIRMED_INSIGHT_TYPE` are the types behind it. The Signal API and the dashboard read the same rule, so a bulk action's preview matches what it writes.
+
+## 2.13.0
+
+- Publication branding adds `editorial.focusClosingBackground`, with `planned_photo` and `article_atmosphere` choices. The setting inherits through publication and platform layers, and supports clearing an override. Article atmosphere closing frames reuse saved artwork and the real author portrait; other publications retain their existing behavior.
+
 ## 2.12.0
 
 A minor release: `@sonordev/contracts/portfolio` now holds the structure of a case study's story. Every other entry is unchanged, and nothing already exported from `portfolio` changed.
@@ -7,7 +26,7 @@ A minor release: `@sonordev/contracts/portfolio` now holds the structure of a ca
 - **The case study arc.** `CASE_STUDY_STAGES` names the four beats every case study reads in (`problem`, `build`, `proof`, `outcome`), `CASE_STUDY_STAGE_COPY` gives each a generic name and the question it answers, `PORTFOLIO_SECTION_TYPES` is every section type in canonical reading order, and `SECTION_STAGE` / `sectionStage` say which stage each belongs to. The section list used to be kept separately by the Sonor API and agency-site-kit; this is now the one copy.
 - **Reading order.** `orderSections` always keeps the arc (hero, problem, build, proof, outcome, CTA) and keeps an agency's stored order only within a stage, so a reordered case study can no longer put its results above its challenges. `groupSectionsByStage` returns the beats a case study actually has, numbered in order. `PORTFOLIO_SECTION_ORDER` is derived from the list. Performance now reads before Results: the proof comes before the outcome.
 - **Stage status.** `caseStudyStageStatus` reports all four stages, complete only with the stage's core section (`STAGE_CORE_SECTION`), with one sentence on what's missing.
-- **Stage names.** An agency can call the four stages what it likes ("Heat", "Shape", "Temper", "Finish"); `CaseStudyStageNames` is that map, `stageName(names, stage)` reads it with the generic name as the fallback, `stageNamesProblems` validates it and `STAGE_NAME_MAX_CHARS` is the length limit. The ids never change; only what people see does.
+- **Stage names.** A site can call the four stages what it likes ("Heat", "Shape", "Temper", "Finish"); `CaseStudyStageNames` is that map, `stageName(names, stage)` reads it with the generic name as the fallback, `stageNamesProblems` validates it and `STAGE_NAME_MAX_CHARS` is the length limit. The ids never change; only what people see does.
 - **The narrative.** `CaseStudyNarrative` is a case study's thesis and one lede per stage, written for the project rather than borrowed from the house. `narrativeProblems` validates one, `NARRATIVE_MAX_CHARS` is the length limit and `CASE_STUDY_NARRATIVE_JSON_SCHEMA` the same rule as a schema. An absent narrative passes.
 - **The thread.** A challenge carries an `id` (`challengeId(n)`), a phase `resolves` challenges and a result `proves` them; `caseStudyFlowProblems` names every challenge nothing resolves or proves and every dangling reference, and passes content written before the thread existed.
 

package/README.md

@@ -18,7 +18,7 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
 | `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | the Sonor API, Signal, site-kit's sitemap sync |
 | `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
-| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), and the contract version | site-kit, the Sonor API, Signal's schema validation |
+| `@sonordev/contracts/llms` | llms.txt sanitizers, the word-safe cut they use (`clipAtWordBoundary`), what each page line says (`pickLlmsPageDescription`: summary, curated meta, served meta, schema description, then a cleaned scrape; `llmsPageTitle`, `isLlmsListablePage`, `groupLlmsPages`, `selectLlmsPages`) and the contract version | site-kit, the Sonor API, Signal's schema validation |
 | `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, the Sonor API's form intake |
 | `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, the Sonor API |
 | `@sonordev/contracts/slots` | Slot payload signing, contract v2 (HMAC; Node only). Signs and verifies v1 for older site-kit releases | the Sonor API, site-kit on the server |
@@ -38,6 +38,17 @@ pnpm add @sonordev/contracts
 | `@sonordev/contracts/broadcast-layouts` | Which Broadcast card layouts are drawn (centered `headline`, low `anchor`), which retired IDs still read and what each draws as (`normalizeArticleCoverLayout`), the Broadcast styles, and the review compositions with the frozen draw that gives each review its own (`reviewCardVariationFromDigest`) | the Sonor API's card renderers and settings, Signal's agent tools, the dashboard's pickers |
 | `@sonordev/contracts/publication-branding` | What a publication's branding may hold and what a change may set (`createPublicationBrandingValidator`), how a change merges, the editorial charter, and safe font stacks | the Sonor API stores and resolves it, Signal checks an agent's change before filing it, the dashboard edits it |
 | `@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 |
+
+## Focus closing artwork
+
+`publication-branding` accepts `editorial.focusClosingBackground` at publication
+and platform levels. `planned_photo` keeps the planned closing image;
+`article_atmosphere` reuses the article's saved atmosphere with its real author
+portrait. Omitting the field keeps existing behavior. A patch value of `null`
+clears the override and restores inheritance. The article-atmosphere mode requires
+both saved sources; it doesn't invent a portrait or substitute unrelated artwork.
 
 ## Public URL hosts
 
@@ -54,6 +65,31 @@ isn't proof a destination is public: the fetcher still validates the protocol,
 credentials and port, checks the DNS addresses it connects to, and applies its
 redirect policy on each hop. Those network protections stay in the APIs.
 
+## Inbox decisions
+
+"Mark all read" and "Dismiss all" never touch a decision, so clearing a backlog
+of notices can't bury an approval waiting on a yes. `isDecisionCard(card)` is
+that rule: the Signal API follows it when it writes, and the dashboard follows
+it to show the result before the write, so the two can't drift apart.
+
+A card is a decision when it is:
+
+- an approval (insight type `approval_needed`, `APPROVAL_NEEDED_INSIGHT_TYPE`);
+- the ledger's unconfirmed-action card (`ledger_unconfirmed_action`,
+  `LEDGER_UNCONFIRMED_INSIGHT_TYPE`): Signal started something it never saw
+  finish, so a person has to check it. It's raised once per claim, so a bulk
+  dismissal that took it would leave nobody told. It carries no proposal, so
+  there's nothing to approve or reject on it; or
+- any card carrying a ledger proposal (`data.proposal_id` set).
+
+`DECISION_INSIGHT_TYPES` is the first two, for the callers that need them as a
+list (a database filter that leaves them out of a bulk write, for one).
+`isDecisionCard` takes any object with an `insight_type` string and an optional
+`data` object, so a stored row and the dashboard's inbox item both fit. It reads
+`data.proposal_id` the way the database reads `data->>proposal_id`: a missing
+key, a JSON `null` and a `null` `data` mean no proposal, and any other value,
+an empty string included, means one.
+
 ## Schema placeholders
 
 `schema-placeholders` finds the parts of a JSON-LD value that a template left
@@ -785,6 +821,14 @@ branding.mergePublicationBrandingPatch(saved, { identity: { logos: { dark: null
   `{ version: 1 }`, and a change that sets nothing returns the profile as it
   was. **`mergePublicationBrandingLayers`** is the same leaf-wise merge for
   resolving layers.
+- **Publication logo roles** are optional `identity.squareLogoUrl` and
+  `identity.fullLogoUrl`. Use the first for a square publication mark and the
+  second for its full/display logo. Both follow the same URL policy as other
+  logo fields. Set either leaf to `null` in a patch to clear that override
+  and restore inheritance. `identity.logos.default/light/dark` remain theme
+  variants, `identity.wordmark` stays text, and `publisherLogoUrl` is publisher
+  attribution. Omitting the new leaves preserves existing profiles; the
+  validator doesn't infer a square mark or select an effective display logo.
 - **Refusals name the field.** A `PublicationBrandingValidationError` carries
   the path (`publication_branding.platforms.email.colors.primary`) and says
   what's allowed. A charter set on a channel override is a plain `Error`: a
@@ -829,10 +873,10 @@ the dashboard that edits it and every site that renders it.
   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.
-- **Stage names.** The ids are fixed; what people see isn't. An agency
-  names the four stages once in the dashboard ("Heat", "Shape", "Temper",
-  "Finish") and `CaseStudyStageNames` carries that map to the editor, the
-  public portfolio config and the agency's site. `stageName(names, stage)`
+- **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`
+  carries that map to the editor, the public portfolio config and the site. `stageName(names, stage)`
   reads it with the generic name as the fallback; `stageNamesProblems`
   validates it and `STAGE_NAME_MAX_CHARS` caps each name.
 - **`CaseStudyNarrative`** is what the story says above its sections: one
@@ -873,3 +917,15 @@ a shape bumps the major and that contract's own `*_VERSION` constant.
 ### Editorial media
 
 `@sonordev/contracts/editorial-media` exports `resolveArticlePhotoPlacements(html, photos)`, returning section targets and a status/offset for each explicit placement. Both the editor and article renderer use this contract; a heading with no eligible prose is reported as `no_paragraph`, and missing/ambiguous anchors never drift to another section. `editorialTextId` creates content identities for explicit takeaway assignments. Source-image format, size and completed-art exclusions are shared by the picker and resolver.
+
+## The funnels contract
+
+Import from `@sonordev/contracts/funnels`. `createFunnelDraft(template)` provides neutral defaults for `newsletter`, `requested_guide` and `inquiry`. `parseFunnelDraftDefinition` accepts bounded incomplete drafts so each setup step can save. `parseFunnelDefinition` requires a launch-ready structural definition. Resource ownership, current permission, route installation and launch authorization remain server checks.
+
+Use `parseFunnelCreateArgs`, `parseFunnelUpdateArgs`, `parseFunnelRevisionArgs`, `parseFunnelLaunchArgs`, `parseFunnelLifecycleArgs` and `parseFunnelRetryArgs` at command boundaries. `parseFunnelDraftArgs(value, mode)` requires an explicit create/update mode. Rollback uses `parseFunnelLifecycleArgs(value, 'rollback')`. Matching exported JSON schemas describe the closed structural shapes; runtime parsers also enforce semantic checks such as matching form references and managed paths.
+
+`applyFunnelBrandOverride` takes an already resolved brand, an allowlisted presentation patch and an API-authorized asset map. Null leaves restore inheritance. It returns the resulting brand, overridden field paths and asset references. It doesn't fetch assets, resolve business precedence or calculate authoritative hashes. `parseFunnelBrandSnapshot` validates the captured presentation and provenance.
+
+`parsePublishedFunnelPage` refuses private definition fields and unsafe asset URLs. It supports bounded text paragraphs and bullet lists, with a managed form slug and canonical campaign identity. `managedFunnelPath` reserves `/f/:slug`; a consuming site must opt in and verify its actual routes.
+
+`parseFunnelReadiness`, `parseFunnelOperationReceipt` and the detail/catalog/preview parsers validate bounded response envelopes. Operation receipts bind the exact command target and approved action, and always report zero messages sent by the configuration command. Preview and published-version detail parsers preserve the exact launch or rollback evidence.

package/dist/campaign-normalize.d.ts

@@ -0,0 +1,2 @@
+/** Single source of truth for campaign identities across sites, APIs and funnels. */
+export declare function normalizeCampaignSlug(input?: string | null): string | null;