@sonordev/site-kit 8.5.2 → 8.6.0

package/dist/contracts/outreach.d.ts

@@ -0,0 +1,267 @@
+/** Bumped when a stored shape here (SegmentGrant, the segment key) changes incompatibly. */
+export declare const OUTREACH_CONTRACT_VERSION = 1;
+/** The badge Signal's outreach writer files and acts under. */
+export declare const OUTREACH_WRITER_BADGE = "signal.outreach.writer";
+/** The ledger kind segments belong to, and its key under settings.autonomy.segments. */
+export declare const OUTREACH_EMAIL_KIND = "outreach_email";
+/**
+ * Signal's one graduation bar: a track record earns sending without a click
+ * per item once at least minMeasured are measured, at least minWinRate of
+ * them won, and none degraded without being undone. Single source of truth
+ * for both APIs: Signal measures a kind or a segment against it, and an
+ * earned segment grant needs minMeasured receipts wherever
+ * grantEvidenceRefusal checks one.
+ */
+export declare const GRADUATION_BAR: {
+    readonly minMeasured: 5;
+    readonly minWinRate: 0.7;
+    readonly maxUnrevertedDegradations: 0;
+};
+/**
+ * A segment's standing, one vocabulary everywhere:
+ *  - ungranted: nobody turned it on (its next email is a first email);
+ *  - granted: a person turned it on and it's sending without a per-email click;
+ *  - paused: it stopped itself (a quality loss or a list signal) until a person resumes it;
+ *  - lapsed: the pitch changed since it was turned on, so its next email is a first email again;
+ *  - revoked: a person stopped it.
+ * "Awaiting first approval" is a drip check's answer, never a stored state.
+ */
+export declare const SEGMENT_STATES: readonly ['ungranted', 'granted', 'paused', 'lapsed', 'revoked'];
+export type SegmentState = (typeof SEGMENT_STATES)[number];
+export type OutreachSegmentSource = 'drip' | 'mcp';
+/** The vertical of a lead with no industry. Never grantable. */
+export declare const UNSPECIFIED_INDUSTRY = "unspecified";
+/**
+ * A prospect's industry as written, in the one order every caller uses: the
+ * target company's vertical, then its industry, then the lead's
+ * company_industry. Null when none is set.
+ */
+export declare function prospectIndustry(prospect: {
+    vertical?: unknown;
+    industry?: unknown;
+    company_industry?: unknown;
+} | null | undefined): string | null;
+/**
+ * An industry as it appears in a segment key: NFKC, accents folded, lowercase,
+ * "&" read as "and", every run of anything that isn't a-z or 0-9 a single
+ * "-", trimmed, at most 48 characters. Empty is 'unspecified'. There's no
+ * synonym table: "Roofing" and "Roofers" are two segments.
+ */
+export declare function normalizeIndustry(value: unknown): string;
+/** The fields of an outreach_narratives row that are its pitch. Its name, its switch and its forbidden phrases aren't. */
+export declare const NARRATIVE_PITCH_FIELDS: readonly ['positioning_statement', 'target_icp_description', 'tone_profile', 'hook_types', 'example_angles', 'value_prop_bullets'];
+/** A narrative row, or any object carrying its pitch fields; every other column (name, enabled, forbidden_phrases, ...) is read past. */
+export type NarrativePitch = {
+    [K in (typeof NARRATIVE_PITCH_FIELDS)[number]]?: unknown;
+} & Record<string, unknown>;
+/**
+ * The narrative's pitch, fingerprinted: FNV-1a of canonical JSON of
+ * NARRATIVE_PITCH_FIELDS only. Rewriting the pitch changes it, and that
+ * lapses a segment's grant. Renaming the narrative, switching it on or off,
+ * or tightening its forbidden phrases or avoid_tone doesn't: those take
+ * effect at once through the checker and the prompt.
+ */
+export declare function narrativeFingerprint(narrative: NarrativePitch | null | undefined): string;
+/** target_ref.segment on an outreach_email row: stamped once, at filing. */
+export interface OutreachSegment {
+    key: string;
+    source: OutreachSegmentSource;
+    narrative_id: string | null;
+    mailbox_id: string | null;
+    vertical: string;
+    label: string;
+    angle_fp: string | null;
+}
+/**
+ * A segment: which pitch, from which mailbox, to which kind of business.
+ *  - drip: `drip:<narrative uuid>@<mailbox uuid>|<vertical>`. Null when either id isn't a UUID.
+ *  - mcp: `mcp:-|<vertical>`. For metrics only; never granted.
+ */
+export declare function outreachSegment(input: {
+    source: OutreachSegmentSource;
+    narrativeId?: string | null;
+    mailboxId?: string | null;
+    industry?: unknown;
+    label?: string | null;
+    angleFp?: string | null;
+}): OutreachSegment | null;
+/** A segment's label: "<narrative name> to <industry as written>, from <mailbox address>". */
+export declare function outreachSegmentLabel(input: {
+    narrativeName?: unknown;
+    industry?: unknown;
+    mailboxAddress?: unknown;
+}): string;
+export type ParsedOutreachSegmentKey = {
+    source: 'drip';
+    narrative_id: string;
+    mailbox_id: string;
+    vertical: string;
+} | {
+    source: 'mcp';
+    vertical: string;
+};
+/**
+ * A segment key, parsed strictly, or null. Nothing else is ever used as a key
+ * in projects.settings, so a caller-chosen key ("__proto__", a long string)
+ * is refused before any read or write.
+ */
+export declare function parseOutreachSegmentKey(key: unknown): ParsedOutreachSegmentKey | null;
+/**
+ * Whether a segment can ever be turned on: a drip segment with a known
+ * industry. An mcp segment, or a lead with no industry, always waits for a
+ * person. (A row whose recipient Sonor already knows waits too; that's the
+ * row's relationship, checked separately.)
+ */
+export declare function isGrantableSegmentKey(key: unknown): boolean;
+/**
+ * A person's standing approval of one segment, at
+ * projects.settings.autonomy.segments.outreach_email[key]. Written only by
+ * Signal's AutonomyPolicyService.setSegmentGrant, refused on every generic
+ * settings writer, and only ever trusted after grantEvidenceRefusal passes.
+ */
+export interface SegmentGrant {
+    state: 'granted' | 'revoked';
+    /** first_email: a person approved the segment's first email unedited with "Send the rest like this". earned: they accepted Signal's offer once the bar was met. */
+    source: 'first_email' | 'earned';
+    /** contacts.id of the person who turned it on. */
+    by: string;
+    /** Where they did it. Never MCP. */
+    via: 'dashboard' | 'drafts';
+    at: string;
+    /** first_email: the ledger id of that email. earned: the offer's dedup key. */
+    ref: string;
+    /** earned: the ledger ids of the wins that earned it. */
+    receipts?: string[];
+    /** The mailbox it sends from. A grant never covers another mailbox. */
+    mailbox_id: string;
+    label: string;
+    /** narrativeFingerprint when it was turned on. A rewritten pitch lapses it. */
+    angle_fp: string;
+    /** Stopped itself. Cleared only by a person's resume. */
+    paused?: {
+        at: string;
+        reason: string;
+        loss_ref: string | null;
+    };
+    resumed?: {
+        by: string;
+        at: string;
+    };
+    revoked?: {
+        by: string;
+        at: string;
+        reason: string;
+    };
+}
+/**
+ * Every well-formed grant, by segment key. Pass projects.settings or its
+ * autonomy document. A key that doesn't parse strictly, or a grant that isn't
+ * the SegmentGrant shape, is left out: an unreadable grant counts as no grant.
+ */
+export declare function readSegmentGrants(source: unknown): Record<string, SegmentGrant>;
+/** The grant for a segment when it's live (granted, not paused, on a grantable key), else null. Evidence is checked separately. */
+export declare function activeSegmentGrant(source: unknown, key: string): SegmentGrant | null;
+export type SegmentGrantCoverage = {
+    covers: true;
+} | {
+    covers: false;
+    code: 'not_granted' | 'revoked' | 'paused' | 'other_person' | 'granted_after' | 'angle_changed' | 'other_mailbox';
+    reason: string;
+};
+/**
+ * Whether a live grant covers one row: refused when there's no grant, it was
+ * revoked or paused, the row names another approver, the row was filed
+ * before the grant, the pitch changed since (a different fingerprint), or the
+ * row sends from another mailbox.
+ */
+export declare function segmentGrantCovers(grant: SegmentGrant | null | undefined, row: {
+    by?: string | null;
+    createdAt: string | null | undefined;
+    angleFp: string | null | undefined;
+    mailboxId: string | null | undefined;
+}): SegmentGrantCoverage;
+/** The columns of a signal_proposals row grantEvidenceRefusal reads. */
+export interface GrantEvidenceRow {
+    id: string;
+    kind: string;
+    status: string;
+    project_id?: string | null;
+    created_by?: string | null;
+    reviewed_by?: string | null;
+    reviewed_at?: string | null;
+    target_ref?: unknown;
+    payload?: unknown;
+}
+export interface GrantEvidenceScope {
+    /** The segment key the grant is stored under. */
+    key: string;
+    /** GRADUATION_BAR.minMeasured: how many receipts an earned grant needs. */
+    minMeasured: number;
+    /** The project the grant is stored on. Rows from another project never count. */
+    projectId?: string | null;
+    /** contacts.id of reviewers known to be people (not agents). When given, every reviewer must be in it. */
+    people?: ReadonlySet<string> | ReadonlyArray<string> | null;
+}
+/**
+ * Why a grant can't be trusted, or null when the ledger rows it cites stand
+ * behind it. A grant that fails counts as no grant, so a grant forged into
+ * settings never sends anything.
+ *
+ * - first_email: grant.ref is an applied outreach_email the writer filed in
+ *   this project and segment, from the grant's mailbox, approved by grant.by
+ *   at or before grant.at, in Sonor (via dashboard or drafts, never MCP),
+ *   unedited, and read back verified.
+ * - earned: at least scope.minMeasured distinct receipts, each an applied
+ *   writer row in this segment and mailbox, for the same pitch, approved by a
+ *   person in Sonor at or before grant.at, unedited and read back verified.
+ */
+export declare function grantEvidenceRefusal(grant: SegmentGrant | null | undefined, refRows: ReadonlyArray<GrantEvidenceRow> | null | undefined, scope: GrantEvidenceScope): string | null;
+/** The live roles of the person asking, read by the caller. */
+export interface SegmentGranterRoles {
+    contact_type?: string | null;
+    is_platform_admin?: boolean | null;
+    /** Their role in the project's org. */
+    org_role?: string | null;
+    /** Their role on the project itself. */
+    project_role?: string | null;
+    /** Their role in the agency that manages the project's org. */
+    managing_org_role?: string | null;
+}
+/**
+ * Whether this person may turn a segment on (or resume it): never an agent
+ * contact; otherwise a platform admin, or an owner or admin of the project,
+ * its org, or the agency that manages that org.
+ */
+export declare function segmentGranterEligible(roles: SegmentGranterRoles | null | undefined): boolean;
+/**
+ * Domains anyone can sign up for. A matching address says nothing about the
+ * company someone works for, so a relationship check never matches on one.
+ */
+export declare const PUBLIC_MAILBOX_DOMAINS: ReadonlyArray<string>;
+/** Whether an address or a domain is a public mailbox provider's. Case and a leading "mailto:" or "@" don't matter. */
+export declare function isPublicMailboxDomain(value: unknown): boolean;
+/**
+ * - live: still waiting on a person or a held send. Leave the lead reserved.
+ * - sent: the email went out. The lead moves on.
+ * - retire: a person said it shouldn't go to this person. Drop the lead.
+ * - declined: a person turned this email down for another reason. The lead goes back in line.
+ * - refile: nothing was decided about the lead (wrong timing, expired,
+ *   superseded, the kind switched off, a send that never went out). It may be
+ *   filed again after its cooldown.
+ */
+export type DripRowDisposition = 'live' | 'sent' | 'retire' | 'declined' | 'refile';
+/** The columns of a signal_proposals row dripRowDisposition reads. */
+export interface DripLedgerRow {
+    status: string;
+    review_reason?: string | null;
+    reviewed_by?: string | null;
+    autonomy_decision?: unknown;
+    payload?: unknown;
+}
+/**
+ * What a drip's ledger row means for its lead. Signal's filing dedup and the
+ * Sonor API's reservation release both read it, so "decided" means one thing.
+ * A status it doesn't know reads as live: a lead stays reserved rather than
+ * being written to twice.
+ */
+export declare function dripRowDisposition(row: DripLedgerRow | null | undefined): DripRowDisposition;

package/dist/contracts/page-titles.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Page-titles contract: what a page is called when a list, a sitemap or a
+ * case study needs its own name and not its whole <title>. The Sonor APIs and
+ * the agency site kit import it as `@sonordev/contracts/page-titles`.
+ *
+ * Why it exists: three places each turned a stored title or a URL slug into a
+ * label with their own logic, and they disagreed. "ac-replacement" became "Ac
+ * Replacement", "faq" became "Faq", "smith-and-smith" became "Smith And
+ * Smith", and a title with a stray second pipe shipped as "Loans | | Brand".
+ * There's one rule now:
+ *
+ *  - `titleHead` is the page's own name: the title without its trailing
+ *    " | Brand" segment. Prefer it. A page's title is the label it was
+ *    written with, so it beats anything guessed from a URL.
+ *  - `slugLabel` is for the rare case a label has to come from a slug, a file
+ *    name or a path, because the page has no title at all.
+ *  - `isRoutePlaceholder` says whether a value is a framework route
+ *    placeholder (":slug", "[slug]", "[...rest]") and not a page's name.
+ *  - `isPageAddress` says whether a value is a page's address (a path, a
+ *    URL, a route pattern, or the page's own path without its slashes) and
+ *    not its name. It's the one "is this title really a path" rule, so the
+ *    writer of a page list and the reader that prints it can't disagree.
+ *  - `isPageName` says whether a stored title is a name: something is left
+ *    once the pipes are set aside, and no piece between them is an address.
+ *    It's the one rule for a title that gets printed whole, so the writer
+ *    that stores a name and the reader that prints it can't disagree about
+ *    a path, a URL or a placeholder behind a pipe.
+ *
+ * Pure string logic: no I/O, no Node built-ins. The brand split is
+ * seo-meta's `stripTitleSuffix`, imported, never copied: only the LAST
+ * " | " segment of a title is its brand.
+ */
+/**
+ * The page's own name: the title without its trailing " | Brand" segment.
+ *
+ * Whitespace is collapsed first. Stray pipes are repaired before the brand is
+ * cut, so "Loans | | Brand" reads as "Loans | Brand" (a run of pipes with
+ * only whitespace between them is one separator) and a leading or trailing
+ * pipe is dropped ("Pricing |" is "Pricing"). Then the last " | " segment is
+ * the brand and goes; anything before it stays, pipes and all:
+ * "1 Bedroom | 1BR 1BA | Example Apartments" is "1 Bedroom | 1BR 1BA".
+ *
+ * Apply it once to a stored title. A title with two or more separators
+ * loses one segment per call, so its own output isn't a fixed point.
+ *
+ * A title with no separator comes back as written (trimmed): this can't tell
+ * a brand from a name, so a title that's only a brand stays that brand.
+ * Empty, whitespace-only, non-string, null and undefined input give "".
+ */
+export declare function titleHead(title: string | null | undefined): string;
+/**
+ * A readable label for a slug, a file name or a path: "ac-replacement" is
+ * "AC Replacement", "/services/hvac-repair/" is "HVAC Repair".
+ *
+ * Reach for it only when the page has no title (`titleHead` is the page's own
+ * name). It reads the last non-empty path segment of the input, after
+ * dropping a "https://host" origin, a query or a hash, and decodes %-escapes
+ * without ever throwing. A trailing .html, .htm, .php or .aspx is dropped. The
+ * words split on "-", "_", "+" and whitespace.
+ *
+ * Each word is cased by the first rule that fits:
+ *  - an acronym is upper case ("ac", "ai", "cms", "faq", "hvac", "seo",
+ *    "llc", "mls", ...), and "faqs" is "FAQs";
+ *  - a two-letter US state or DC code is upper case ("ky" is "KY"), apart
+ *    from the codes that are ordinary words as often as not ("in", "or",
+ *    "me", "hi", "id", "la", "ma", "pa", "al", "de", "co"). "mt" goes by its
+ *    position: last, it's Montana ("billings-mt" is "Billings MT"); with a
+ *    word after it, it's Mount ("mt-adams" is "Mt Adams"). "us" isn't a
+ *    state: "about-us" is "About Us";
+ *  - a word with a digit keeps its case and only gains a leading capital
+ *    when it starts with a letter ("c1" is "C1", "075ct" stays);
+ *  - a small word ("a", "an", "and", "at", "by", "for", "in", "of", "on",
+ *    "or", "the", "to", "vs", "with") is lower case, unless it's first;
+ *  - anything else is capitalized with the rest lower case.
+ *
+ * Nothing left to label ("", "/", "?x=1") gives "". The home page is the
+ * caller's to name. A label isn't a title: "index" isn't special-cased,
+ * and a brand's own capitalization ("DeWalt") isn't recoverable from a slug.
+ */
+export declare function slugLabel(input: string): string;
+/**
+ * True when the value, or any "/"-separated segment of it, is a framework
+ * route placeholder: a page's pattern leaked into its name ("/floor-plans/:slug",
+ * ":Slug", "[...rest]"). A placeholder is one token with no spaces, so
+ * ordinary text that contains a colon or a bracket isn't one ("Update: new
+ * hours", "FAQ / [draft] notes"). Nullish, empty and non-string values are
+ * false.
+ */
+export declare function isRoutePlaceholder(value: string | null | undefined): boolean;
+/**
+ * Whether `value` is a page's address and not its name: what a page's title
+ * becomes when nothing better was stored (the old sitemap writers saved the
+ * path there), or a pattern that leaked out of the router. True for:
+ *
+ *  - a path, or anything starting with a slash ("/services/ac-repair",
+ *    "//example.com/services");
+ *  - an absolute URL ("https://example.com/services");
+ *  - a host and a path with no scheme ("example.com/services");
+ *  - a route placeholder, as `isRoutePlaceholder` reads it ("/floor-plans/:slug",
+ *    ":Slug", "[slug]");
+ *  - the page's own path written without its slashes. Given `path`, the
+ *    comparison drops leading and trailing slashes from both sides, so for
+ *    "/services/ac-repair" the values "services/ac-repair" and
+ *    "services/ac-repair/" are the address, and for "/faq" the value "faq" is.
+ *    It compares the whole path and it's case-sensitive: "ac-repair" isn't
+ *    the address of "/services/ac-repair", and "Pricing" for "/pricing" is a
+ *    name where "pricing" is the path.
+ *
+ * The value is trimmed first. Empty, whitespace-only, nullish and non-string
+ * values give false: they aren't an address, they're nothing, and the caller
+ * decides what an empty title means. `path` is optional; without it only the
+ * checks that don't need the page's own path run.
+ *
+ * It judges one string. A title with a " | Brand" tail is `titleHead`'s to
+ * cut, and the caller asks about the head: `isPageAddress(titleHead(title), path)`.
+ * Pure string logic, linear in the length of the input.
+ */
+export declare function isPageAddress(value: string | null | undefined, path?: string | null): boolean;
+/**
+ * Whether a stored title is a real name for the page at `path`: something is
+ * left once the pipes are set aside, and none of its pieces is a page's
+ * address (`isPageAddress`, given the page's path). It's the one rule for a
+ * title that gets printed whole, so whoever stores a name and whoever prints
+ * it can't disagree.
+ *
+ * Every piece is judged, the first and the last included, because a title
+ * with a pipe in it prints with its pipes: ":slug | Example Apartments" (a
+ * placeholder in front of a brand tail) and "Floor Plans | /floor-plans/x" (a
+ * path behind the name) are both refused, and so is the unspaced
+ * "Floor Plans|/floor-plans/x". A name with a pipe in it stays a name while
+ * every piece is text ("1 Bedroom | 1BR 1BA"). A title that's only pipes has
+ * no piece and isn't a name. Empty, whitespace-only, nullish and non-string
+ * values aren't names either.
+ *
+ * It judges the title it is given, brand tail and all. A writer cuts the tail
+ * first and asks about what it stores: `isPageName(titleHead(title), path)`.
+ * `path` is optional, as it is for `isPageAddress`. Pure string logic, linear
+ * in the length of the input.
+ */
+export declare function isPageName(title: string | null | undefined, path?: string | null): boolean;

package/dist/contracts/public-url-host.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The shared literal-host SSRF policy. Pass URL.hostname (which canonicalizes
+ * numeric IPv4 spellings), or an address returned by a DNS lookup. IPv6 may
+ * have the brackets URL.hostname retains. This isn't a URL validator and
+ * doesn't trim input, resolve DNS, follow redirects or open a connection.
+ * Callers still enforce their protocol/port rules and check or pin the DNS
+ * addresses used by each connection; a false result alone can't prove a
+ * destination is public.
+ */
+export declare function isBlockedPublicUrlHost(rawHost: string): boolean;

package/dist/contracts/publication-branding.d.ts

@@ -0,0 +1,143 @@
+import { type BroadcastStyleId, type PublicationCardLayout } from './broadcast-layouts';
+import { type PublicationCharter } from './publication-charter';
+export { PUBLICATION_CHARTER_FIELDS, parsePublicationCharter, parseSiteCharters, publicationCharterContext, publicationCharterFor, type PublicationCharter, } from './publication-charter';
+/** The stored profile's version. A breaking change to the shape bumps it. */
+export declare const PUBLICATION_BRANDING_VERSION: 1;
+/** Where a publication appears. `social` overrides every social network; each network can override again. */
+export declare const PUBLICATION_PLATFORMS: readonly ['publication', 'email', 'social', 'instagram', 'facebook', 'linkedin', 'gbp'];
+export type PublicationPlatform = (typeof PUBLICATION_PLATFORMS)[number];
+/** The sections of a profile and of each platform override, in the order they're read. */
+export declare const PUBLICATION_BRANDING_SECTIONS: readonly ['identity', 'colors', 'typography', 'editorial', 'newsletter'];
+export type PublicationBrandingSection = (typeof PUBLICATION_BRANDING_SECTIONS)[number];
+export declare const PUBLICATION_IDENTITY_FIELDS: readonly ['publicationName', 'wordmark', 'tagline', 'publisherName', 'publisherUrl', 'publisherLogoUrl', 'logos'];
+export declare const PUBLICATION_LOGO_VARIANTS: readonly ['default', 'light', 'dark'];
+export declare const PUBLICATION_COLOR_FIELDS: readonly ['primary', 'secondary', 'accent', 'background', 'surface', 'text', 'muted', 'border'];
+export declare const PUBLICATION_TYPOGRAPHY_FIELDS: readonly ['heading', 'body', 'mono', 'emailHeadingFallback', 'emailBodyFallback'];
+export declare const PUBLICATION_EDITORIAL_FIELDS: readonly ['articleStyle', 'cardLayout', 'charter', 'siteCharters'];
+export declare const PUBLICATION_NEWSLETTER_FIELDS: readonly ['name', 'tagline', 'layout', 'maxWidth'];
+/** Fonts every email client has, the only families an email fallback may name. Lowercase. */
+export declare const EMAIL_SAFE_FONTS: ReadonlySet<string>;
+/** CSS generic families: written bare and lowercase in a font stack, never quoted. */
+export declare const GENERIC_FONT_FAMILIES: ReadonlySet<string>;
+export interface PublicationIdentity {
+    publicationName?: string;
+    wordmark?: string;
+    tagline?: string;
+    publisherName?: string;
+    publisherUrl?: string;
+    /** The publisher's attribution mark, separate from the publication masthead. */
+    publisherLogoUrl?: string;
+    logos?: {
+        default?: string;
+        light?: string;
+        dark?: string;
+    };
+}
+export interface PublicationColors {
+    primary?: string;
+    secondary?: string;
+    accent?: string;
+    background?: string;
+    surface?: string;
+    text?: string;
+    muted?: string;
+    border?: string;
+}
+export interface PublicationTypography {
+    heading?: string;
+    body?: string;
+    mono?: string;
+    emailHeadingFallback?: string;
+    emailBodyFallback?: string;
+}
+export interface PublicationEditorial {
+    charter?: PublicationCharter;
+    siteCharters?: Record<string, PublicationCharter>;
+    /** Shared Broadcast style for articles, reviews and generated posts; portfolio is excluded. Legacy wire name. */
+    articleStyle?: BroadcastStyleId;
+    cardLayout?: PublicationCardLayout;
+}
+export interface PublicationNewsletter {
+    name?: string;
+    tagline?: string;
+    layout?: 'editorial';
+    maxWidth?: 600 | 640;
+}
+export interface PublicationBrandingSections {
+    identity?: PublicationIdentity;
+    colors?: PublicationColors;
+    typography?: PublicationTypography;
+    editorial?: PublicationEditorial;
+    newsletter?: PublicationNewsletter;
+}
+/** Exactly the object stored in projects.settings.publication_branding. */
+export interface PublicationBranding extends PublicationBrandingSections {
+    version: typeof PUBLICATION_BRANDING_VERSION;
+    platforms?: Partial<Record<PublicationPlatform, PublicationBrandingSections>>;
+}
+export type PublicationBrandingProfile = PublicationBranding;
+type LeafPatch<T> = {
+    [K in keyof T]?: NonNullable<T[K]> extends object ? LeafPatch<NonNullable<T[K]>> : T[K] | null;
+};
+export type PublicationBrandingSectionsPatch = LeafPatch<PublicationBrandingSections>;
+/** A change: any leaf set to a value, or to null to clear that override. */
+export interface PublicationBrandingPatch extends PublicationBrandingSectionsPatch {
+    version?: typeof PUBLICATION_BRANDING_VERSION;
+    platforms?: Partial<Record<PublicationPlatform, PublicationBrandingSectionsPatch>>;
+}
+/**
+ * A refusal, naming the field: `publication_branding.colors.primary: use a
+ * valid opaque color`. One case throws a plain Error instead: a charter set on
+ * a channel override, which belongs to the publication or a site.
+ */
+export declare class PublicationBrandingValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** True for a control character (U+0000-U+001F, U+007F) anywhere in the text. */
+export declare function containsControlCharacters(value: string): boolean;
+/**
+ * A CSS font stack as data, never a stylesheet fragment: quoted family names
+ * and lowercase generic families joined by commas ("'Brand Display',serif"),
+ * or undefined when the value carries rules, variables, url() or anything
+ * that isn't a family name. The theme aliases heading, body and mono drop out.
+ */
+export declare function safeFontStack(value: unknown): string | undefined;
+export interface PublicationBrandingValidatorOptions {
+    /**
+     * True when a URL's hostname must never be stored as a logo or publisher
+     * URL: loopback, private and link-local ranges, `localhost` and the like.
+     * Each API passes the shared `public-url-host` policy. It receives
+     * `new URL(value).hostname`, so IPv6 keeps its brackets.
+     */
+    isBlockedHost: (hostname: string) => boolean;
+}
+export interface PublicationBrandingValidator {
+    /** A whole saved profile. Retired card layouts still read. */
+    validatePublicationBranding(value: unknown): PublicationBranding;
+    /** A change. Leaves may be null (clear that override); a card layout must be one drawn today. */
+    validatePublicationBrandingPatch(value: unknown): PublicationBrandingPatch;
+    /** The sections of a profile or a platform override, at `path`. */
+    validatePublicationBrandingSections(input: unknown, path: string, patch: boolean): PublicationBrandingSections | PublicationBrandingSectionsPatch;
+    /**
+     * The saved profile with the change applied: a null leaf clears just that
+     * override and empty containers are pruned. No profile yet reads as
+     * `{ version: 1 }`; a change that sets nothing returns the profile as it was.
+     */
+    mergePublicationBrandingPatch(current: unknown, patch: unknown): PublicationBranding;
+    /** One text leaf: trimmed, 1 to max characters (0 when empty is allowed), no control characters. */
+    text(value: unknown, path: string, max: number, empty?: boolean): string;
+    /** One URL leaf: a public HTTPS URL without credentials, normalized. */
+    url(value: unknown, path: string): string;
+    /** One font leaf, normalized by safeFontStack; email fallbacks may name only EMAIL_SAFE_FONTS. */
+    font(value: unknown, path: string, emailSafe?: boolean): string;
+}
+/**
+ * Leaf-wise merge of a validated change into a profile layer: a null leaf
+ * deletes that key, an object merges recursively, and a container left empty
+ * is removed. The inputs are never mutated. The Sonor API layers resolved
+ * branding with the same merge.
+ */
+export declare function mergePublicationBrandingLayers(current: Record<string, unknown>, patch: Record<string, unknown>): Record<string, unknown>;
+/** Single source of truth for publication-branding validation, bound to the caller's host guard. */
+export declare function createPublicationBrandingValidator(options: PublicationBrandingValidatorOptions): PublicationBrandingValidator;

package/dist/contracts/publication-charter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A publication's editorial charter: data-only direction (who it's for, what
+ * they're deciding, the proof it holds itself to), never evidence of
+ * expertise or permission to publish private material. Part of
+ * `@sonordev/contracts/publication-branding`, which re-exports it; Signal's
+ * writers read it into their prompts and the Sonor API stores it in a
+ * publication's branding. Pure: no I/O, no Node built-ins.
+ */
+export declare const PUBLICATION_CHARTER_FIELDS: readonly ['audience', 'readerDecisions', 'perspective', 'expertise', 'proofStandards', 'tone', 'recurringSeries', 'nonAuthority'];
+export type PublicationCharter = Partial<Record<typeof PUBLICATION_CHARTER_FIELDS[number], string>>;
+export declare function parsePublicationCharter(value: unknown, patch?: boolean): PublicationCharter;
+export declare function parseSiteCharters(value: unknown, patch?: boolean): Record<string, PublicationCharter>;
+export declare function publicationCharterFor(editorial: unknown, site?: string | null): PublicationCharter;
+export declare function publicationCharterContext(charter?: PublicationCharter): string;

package/dist/fleet/index.js

@@ -1,11 +1,11 @@
 'use client';
-export { FLEET_HEARTBEAT_PATH, FleetHeartbeat, detectNextVersion, sendFleetHeartbeat } from '../chunk-ZDUTXHM6.js';
+export { FLEET_HEARTBEAT_PATH, FleetHeartbeat, detectNextVersion, sendFleetHeartbeat } from '../chunk-U34O6I7W.js';
 export { FLEET_CONTRACT_VERSION, FLEET_MODULES, FLEET_MODULES_MAX, FLEET_SITE_MAX_LENGTH, FLEET_VERSION_MAX_LENGTH, FLEET_VERSION_PATTERN, buildFleetHeartbeatPayload, isFleetModule, normalizeFleetModules, normalizeFleetSite, sanitizeFleetVersion } from '../chunk-ZTZQPYP6.js';
 import '../chunk-YC7ELZS3.js';
 import '../chunk-DLM4FFNH.js';
 import '../chunk-EKBEOXTH.js';
-import '../chunk-GDQKDL3E.js';
-import '../chunk-OEA7U4HJ.js';
+import '../chunk-IYCSDFPN.js';
+import '../chunk-QQT2T6JQ.js';
 import '../chunk-W7OPEMGJ.js';
-import '../chunk-CFSIGEUW.js';
+import '../chunk-BUE3Z32O.js';
 import '../chunk-PKBMQBKP.js';

package/dist/forms/FileField.d.ts

@@ -24,5 +24,7 @@ export interface FileFieldProps {
     classPrefix: string;
     baseInputStyle: React.CSSProperties;
     onChange: (value: unknown) => void;
+    ariaInvalid?: boolean;
+    describedBy?: string;
 }
-export declare function FileField({ field, inputId, classPrefix, baseInputStyle, onChange, }: FileFieldProps): React.JSX.Element;
+export declare function FileField({ field, inputId, classPrefix, baseInputStyle, onChange, ariaInvalid, describedBy, }: FileFieldProps): React.JSX.Element;

package/dist/forms/PrivateFileField.d.ts

@@ -0,0 +1,3 @@
+import React from 'react';
+import type { FileFieldProps } from './FileField';
+export declare function PrivateFileField({ field, inputId, onChange, ariaInvalid, describedBy }: Pick<FileFieldProps, 'field' | 'inputId' | 'onChange' | 'ariaInvalid' | 'describedBy'>): React.JSX.Element;

package/dist/forms/index.js

@@ -1,25 +1,25 @@
 'use client';
-export { configureFormsApi, defineForm, field, formsApi, initializeForms } from '../chunk-2QFIYYMP.js';
-export { FormClient, ManagedForm } from '../chunk-3PT6SO65.js';
-import '../chunk-DLTLXYOV.js';
+export { configureFormsApi, defineForm, field, formsApi, initializeForms } from '../chunk-L6QTERSH.js';
+export { FormClient, ManagedForm } from '../chunk-7R2STOVD.js';
+import '../chunk-NI6ZTP3D.js';
 export { DatePicker } from '../chunk-SOD2F6C2.js';
 export { FormCelebration } from '../chunk-YGGDU6C3.js';
-export { useForm, useFormTracking } from '../chunk-27LYZVPP.js';
+export { useForm, useFormTracking } from '../chunk-HMTPRBYJ.js';
 import '../chunk-Q6E4OPGG.js';
 import '../chunk-5ROTTMBL.js';
-export { FormEnhancer } from '../chunk-GLLFIE2R.js';
+export { FormEnhancer } from '../chunk-OWO3RFEX.js';
 import '../chunk-C2FZBUSS.js';
 import '../chunk-YC7ELZS3.js';
 import '../chunk-DXO6SBMD.js';
-export { FormField as FormFieldComponent, autocompleteFor } from '../chunk-TYAVHRWH.js';
-export { DEFAULT_FORM_SUCCESS_MESSAGE } from '../chunk-5SQK3D53.js';
+export { FormField as FormFieldComponent, autocompleteFor } from '../chunk-CVADNHJ4.js';
+export { DEFAULT_FORM_SUCCESS_MESSAGE } from '../chunk-TYSIAWC3.js';
 import '../chunk-HW7B43E5.js';
 import '../chunk-NJCTQH2P.js';
 import '../chunk-L2V5PUFN.js';
 import '../chunk-GJWI74ZZ.js';
 import '../chunk-5TM3WPCI.js';
-import '../chunk-GDQKDL3E.js';
-import '../chunk-OEA7U4HJ.js';
+import '../chunk-IYCSDFPN.js';
+import '../chunk-QQT2T6JQ.js';
 import '../chunk-W7OPEMGJ.js';
-import '../chunk-CFSIGEUW.js';
+import '../chunk-BUE3Z32O.js';
 import '../chunk-PKBMQBKP.js';

package/dist/forms/private-file-rules.d.ts

@@ -0,0 +1,8 @@
+export declare const PRIVATE_FILE_MAX_BYTES: number;
+export declare const PRIVATE_FILE_TYPES: readonly ['application/pdf', 'image/jpeg', 'image/png', 'image/webp'];
+export declare const PRIVATE_FILE_ACCEPT = ".pdf,.jpg,.jpeg,.png,.webp";
+export declare function validatePrivateFileSelection(files: Array<{
+    name: string;
+    size: number;
+    type: string;
+}>, maxFiles?: number): string | null;