@sonordev/contracts 2.15.0 → 2.17.0

package/dist/portfolio.d.ts

@@ -16,14 +16,7 @@
  * must carry, and which numbers may headline. The Sonor API applies the same
  * rules.
  */
-/** 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;
+export { FRAME_READY_MESSAGE, isFrameReadyMessage, type FrameReadyMessage } from './frame-ready';
 /** Bump on breaking changes to the collapse policy. */
 export declare const PORTFOLIO_CONTRACT_VERSION: 1;
 /** The four beats, in reading order. */
@@ -57,7 +50,7 @@ export declare function stageName(names: CaseStudyStageNames | null | undefined,
  * sections of the story (SEO metadata, the closing CTA). This is THE list;
  * the Sonor API and agency-site-kit import it rather than keeping their own.
  */
-export declare const PORTFOLIO_SECTION_TYPES: readonly ['portfolioHero', 'portfolioChallenges', 'portfolioBeforeAfter', 'portfolioStrategy', 'portfolioSiteArchitecture', 'portfolioDesignSystem', 'portfolioFeatureSpotlight', 'portfolioGallery', 'portfolioVideo', 'portfolioTechStack', 'portfolioPerformance', 'portfolioSpeedComparison', 'portfolioResults', 'portfolioMetricsTimeline', 'portfolioConversionFunnel', 'portfolioServices', 'portfolioTeam', 'portfolioTestimonial', 'portfolioDetails', 'portfolioSeo', 'portfolioCTA'];
+export declare const PORTFOLIO_SECTION_TYPES: readonly ['portfolioHero', 'portfolioChallenges', 'portfolioBeforeAfter', 'portfolioStrategy', 'portfolioSiteArchitecture', 'portfolioDesignSystem', 'portfolioFeatureSpotlight', 'portfolioGallery', 'portfolioVideo', 'portfolioTechStack', 'portfolioPerformance', 'portfolioSpeedComparison', 'portfolioVerification', 'portfolioResults', 'portfolioMetricsTimeline', 'portfolioConversionFunnel', 'portfolioServices', 'portfolioTeam', 'portfolioTestimonial', 'portfolioDetails', 'portfolioSeo', 'portfolioCTA'];
 export type PortfolioSectionType = (typeof PORTFOLIO_SECTION_TYPES)[number];
 export declare function isPortfolioSectionType(value: unknown): value is PortfolioSectionType;
 /**
@@ -70,20 +63,42 @@ export declare const SECTION_STAGE: Record<PortfolioSectionType, CaseStudyStage
 /** The stage a section type belongs to, or null when it sits outside the story. Unknown types are null. */
 export declare function sectionStage(type: string): CaseStudyStage | null;
 /**
- * The one section each stage can't do without. A stage with other sections
- * but not this one is told so by {@link caseStudyStageStatus}: a proof stage
- * that's only a speed comparison has no measurement of the finished build.
+ * The one section each stage can't do without, and the one an editor offers
+ * to add when the stage has nothing. A stage with other sections but not its
+ * core (or a stand-in, {@link STAGE_CORE_ALTERNATES}) is told so by
+ * {@link caseStudyStageStatus}: a proof stage that's only a speed comparison
+ * has no measurement of the finished build.
  */
 export declare const STAGE_CORE_SECTION: Record<CaseStudyStage, PortfolioSectionType>;
+/**
+ * Sections that stand in for a stage's core. A Lighthouse run can only score
+ * what a browser can reach without signing in, so an app whose screens sit
+ * behind a login has no honest Performance section; its proof is a
+ * verification: checks that each say what they cover and what they don't.
+ * Either one completes the proof stage. This is deliberately not gated on
+ * the kind of project: the status below only sees section types, and the
+ * rule for "is this an app" lives with each caller's own data. A verification
+ * is a measurement of the finished build with its limits stated, which is
+ * what the stage asks for. Single source of truth for what completes a stage.
+ */
+export declare const STAGE_CORE_ALTERNATES: Partial<Record<CaseStudyStage, readonly PortfolioSectionType[]>>;
+/** Every section type that completes a stage: its core first, then its stand-ins. */
+export declare function stageCoreSections(stage: CaseStudyStage): PortfolioSectionType[];
 /**
  * Canonical display order, derived from the list above so it can't disagree
  * with the stages. Renderers sort by this when nobody has reordered; the
  * dashboard's stored order only ever moves a section within its stage.
  */
 export declare const PORTFOLIO_SECTION_ORDER: Record<PortfolioSectionType, number>;
-/** The least a section needs for the ordering helpers: its type. Anything else rides along. */
+/**
+ * The least a section needs for the ordering helpers: its type. Anything else
+ * rides along. `data` is optional for them and needed by
+ * {@link caseStudyStageStatus}, which won't count a stand-in section for a
+ * stage's core (a verification) unless its data shows something.
+ */
 export interface SectionLike {
     sectionType: string;
+    data?: unknown;
 }
 /**
  * The sections in the order the case study reads.
@@ -120,7 +135,11 @@ export interface CaseStudyStageStatus {
     stage: CaseStudyStage;
     /** The section types present, in reading order. */
     present: PortfolioSectionType[];
-    /** True when the stage's core section ({@link STAGE_CORE_SECTION}) is present. */
+    /**
+     * True when the stage's core section ({@link STAGE_CORE_SECTION}) is present, or a stand-in for it
+     * ({@link STAGE_CORE_ALTERNATES}) is present with something a page can show. Pass each section's `data`:
+     * a stand-in without it doesn't count.
+     */
     complete: boolean;
     /** Null when complete; otherwise one sentence on what the stage is missing. */
     missing: string | null;
@@ -129,6 +148,10 @@ export interface CaseStudyStageStatus {
  * Each stage's status, all four, in order, whether or not the case study has
  * sections in it. The dashboard shows these beside the editor so an empty
  * proof stage is seen before the case study is published, not after.
+ *
+ * A stage's core section completes it by type. A stand-in for the core (a
+ * verification) completes it only when its `data` holds something a page can
+ * show, so pass `data`; without it a stand-in reads as empty, never as done.
  */
 export declare function caseStudyStageStatus(sections: readonly SectionLike[] | null | undefined): CaseStudyStageStatus[];
 export interface CaseStudyNarrative {
@@ -196,6 +219,166 @@ export declare function caseStudyFlowProblems(input: {
     phases?: readonly PhaseLike[] | null;
     results?: readonly ResultLike[] | null;
 }): string[];
+/**
+ * True for a real calendar day written YYYY-MM-DD. "2026-02-31" is not (Date.parse
+ * rolls it into March), and neither is a year under 100 (Date.UTC maps those into
+ * the 1900s). Single source of truth for what counts as a day.
+ */
+export declare function isRealDay(value: string): boolean;
+/** The most checks one verification lists. It's a short list; the case study isn't an audit report. */
+export declare const VERIFICATION_MAX_CHECKS = 8;
+/** Every field of a check, in the order a renderer reads them. */
+export declare const VERIFICATION_CHECK_FIELDS: readonly ['label', 'result', 'measured', 'where', 'method', 'date', 'scope'];
+export type VerificationCheckField = (typeof VERIFICATION_CHECK_FIELDS)[number];
+/** The longest each text field may run. Each is a line, not a paragraph. `date` is a day, not text. */
+export declare const VERIFICATION_FIELD_MAX_CHARS: {
+    readonly label: 80;
+    readonly result: 120;
+    readonly measured: 200;
+    readonly where: 200;
+    readonly method: 240;
+    readonly scope: 240;
+};
+/** One thing we checked on the finished build. Every field is required. */
+export interface VerificationCheck {
+    /** What the check is called: "Sign-in page, mobile speed". */
+    label: string;
+    /** What came out: "Performance 89", "42 of 42 tables have row-level security". */
+    result: string;
+    /** What was measured: "Lighthouse performance score of the page a visitor sees before signing in". */
+    measured: string;
+    /** Where: a URL, or the screen or file. "https://example.com/login", "the migrations in the repository". */
+    where: string;
+    /** The tool and settings: "Lighthouse 13, mobile preset, median of 3 runs". */
+    method: string;
+    /** The day it was checked, YYYY-MM-DD. */
+    date: string;
+    /** What the check does NOT cover, as a limit: "The sign-in page only; the screens behind it weren't measured." */
+    scope: string;
+}
+/** The `data` of a `portfolioVerification` section. */
+export interface PortfolioVerificationData {
+    checks: VerificationCheck[];
+}
+/** The earliest day a check may carry. An earlier date is a typo, not a check of this build. */
+export declare const VERIFICATION_EARLIEST_DAY = "2000-01-01";
+/**
+ * The latest day a check may carry: tomorrow in UTC. A check run today anywhere
+ * on earth is dated no later than that (the furthest-ahead zone is UTC+14), so a
+ * server's clock can't drop a check dated "today" where the person ran it, and a
+ * date further out is a check that hasn't happened. Single source of truth for
+ * the allowance: writers and readers both use it, so no one keeps a second one.
+ * `now` is for tests and for callers with a clock of their own.
+ */
+export declare function latestVerificationDay(now?: Date): string;
+export interface VerificationOptions {
+    /**
+     * The latest day a check may carry, YYYY-MM-DD; a later one is a problem. Leave it out to use
+     * {@link latestVerificationDay}, which is what a page and a write path both want. Pass one for a fixed clock.
+     */
+    latestDay?: string;
+}
+/**
+ * True when a line says nothing: it has no words, or every word is a
+ * placeholder or filler ("N/A", "n/a n/a", "TBD", "see above", "none at all").
+ */
+export declare function isPlaceholderText(text: string): boolean;
+/**
+ * True when a scope line doesn't state a limit. A scope is "what this check
+ * does NOT cover", so it has to be a sentence that uses a word marking where
+ * coverage stops ("only", "not", "except", "without", "n't") and says
+ * something beyond that word. A coverage claim ("All screens", "Fully
+ * tested"), a placeholder ("N/A", "None at all", "Not applicable") and a
+ * denied limit ("No restrictions", "Nothing excluded") fail. "Desktop only",
+ * "Counted, not exercised" and "No queries ran as a signed-in user" pass.
+ *
+ * It reads English. It can't judge whether a limit is true or useful, only
+ * that one was written; a person still reads the scope.
+ */
+export declare function isVacuousScope(scope: string): boolean;
+/**
+ * What's wrong with a verification section's data, or an empty list. The
+ * section needs between one and {@link VERIFICATION_MAX_CHECKS} checks, and
+ * every field of every check is required, the scope most of all. Whatever
+ * stores a verification should run this first. The contract can't make it:
+ * until a write path calls it, stored data can hold anything, and
+ * {@link readVerificationChecks} is what keeps a bad check off the page.
+ */
+export declare function verificationProblems(data: unknown, options?: VerificationOptions): string[];
+/**
+ * The checks a renderer may show: the ones with every field present, within
+ * the limits, with a real day and a scope that states a limit, trimmed, in their
+ * stored order and no more than {@link VERIFICATION_MAX_CHECKS}. A check that
+ * fails is left out, so one with no scope line (or a placeholder for one) never
+ * prints. That's all it can promise: whether a scope is true is a person's call.
+ * Empty when the data is anything else. Single source of truth for what a case
+ * study prints from this section.
+ */
+export declare function readVerificationChecks(data: unknown, options?: VerificationOptions): VerificationCheck[];
+/**
+ * The link for a check's `where`: the address when it is exactly one http or
+ * https URL with no credentials in it and a public host, else null. A screen
+ * name or a file path is printed as text; nothing else is ever made into a link.
+ */
+export declare function verificationLink(where: string): string | null;
+/** Agent-native contract: JSON Schema for {@link PortfolioVerificationData}. What a scope or a where says, and whether a date is a real day in range, are checked by {@link verificationProblems}. */
+export declare const PORTFOLIO_VERIFICATION_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/portfolio-verification.v1.json';
+    readonly title: 'PortfolioVerificationData';
+    readonly description: 'A short list of checks on the finished build. Each says what was checked, where, how, when, what came out, and what it does not cover.';
+    readonly type: 'object';
+    readonly required: readonly ['checks'];
+    readonly properties: {
+        readonly checks: {
+            readonly type: 'array';
+            readonly minItems: 1;
+            readonly maxItems: 8;
+            readonly items: {
+                readonly type: 'object';
+                readonly required: readonly ["label", "result", "measured", "where", "method", "date", "scope"];
+                readonly properties: {
+                    readonly label: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 80;
+                    };
+                    readonly result: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 120;
+                    };
+                    readonly measured: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly where: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 200;
+                    };
+                    readonly method: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 240;
+                    };
+                    readonly date: {
+                        readonly type: 'string';
+                        readonly pattern: '^\\d{4}-\\d{2}-\\d{2}$';
+                    };
+                    readonly scope: {
+                        readonly type: 'string';
+                        readonly minLength: 1;
+                        readonly maxLength: 240;
+                    };
+                };
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly additionalProperties: false;
+};
 /** Minimal KPI shape the policy reads — callers pass their own richer tiles. */
 export interface KpiLike {
     label: string;