@sonordev/contracts 2.8.0 → 2.9.0

package/dist/page-titles.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// src/contracts/seo-meta.ts
+var TITLE_SEPARATOR = " | ";
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+
+// src/contracts/page-titles.ts
+var PIPE_RUN = /\|(?:\s*\|)+/g;
+var EDGE_PIPES = /^[\s|]+|[\s|]+$/g;
+function titleHead(title) {
+  if (typeof title !== "string") return "";
+  const tidy = title.replace(/\s+/g, " ").replace(PIPE_RUN, " | ").replace(EDGE_PIPES, "").replace(/\s+/g, " ");
+  return tidy ? stripTitleSuffix(tidy) : "";
+}
+var ACRONYMS = /* @__PURE__ */ new Map([
+  ["ac", "AC"],
+  ["ai", "AI"],
+  ["aeo", "AEO"],
+  ["api", "API"],
+  ["cms", "CMS"],
+  ["crm", "CRM"],
+  ["faq", "FAQ"],
+  ["faqs", "FAQs"],
+  ["fsbo", "FSBO"],
+  ["hvac", "HVAC"],
+  ["jl", "JL"],
+  ["llc", "LLC"],
+  ["llp", "LLP"],
+  ["mls", "MLS"],
+  ["pdf", "PDF"],
+  ["pllc", "PLLC"],
+  ["ppc", "PPC"],
+  ["roi", "ROI"],
+  ["seo", "SEO"],
+  ["ui", "UI"],
+  ["usa", "USA"],
+  ["ux", "UX"]
+]);
+var STATE_CODES = new Set(
+  "al ak az ar ca co ct de dc fl ga hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd oh ok or pa ri sc sd tn tx ut vt va wa wv wi wy".split(" ")
+);
+var WORD_STATE_CODES = /* @__PURE__ */ new Set([
+  "in",
+  "or",
+  "me",
+  "hi",
+  "id",
+  "la",
+  "ma",
+  "pa",
+  "al",
+  "de",
+  "co"
+]);
+var TRAILING_STATE_CODES = /* @__PURE__ */ new Set(["mt"]);
+function isStateCode(lower, isLast) {
+  if (!STATE_CODES.has(lower) || WORD_STATE_CODES.has(lower)) return false;
+  return TRAILING_STATE_CODES.has(lower) ? isLast : true;
+}
+var SMALL_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "at",
+  "by",
+  "for",
+  "in",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "vs",
+  "with"
+]);
+var PAGE_EXTENSION = /\.(?:html?|php|aspx)$/i;
+var URL_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/\\]*/i;
+var PERCENT_RUN = /(?:%[0-9a-f]{2})+/gi;
+function decodeEscapes(value) {
+  return value.replace(PERCENT_RUN, (run) => {
+    try {
+      return decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+  });
+}
+function capitalizeFirst(word) {
+  const code = word.codePointAt(0);
+  if (code === void 0) return word;
+  const first = String.fromCodePoint(code);
+  return first.toUpperCase() + word.slice(first.length);
+}
+function labelWord(token, isFirst, isLast) {
+  const lower = token.toLowerCase();
+  const acronym = ACRONYMS.get(lower);
+  if (acronym) return acronym;
+  if (isStateCode(lower, isLast)) return lower.toUpperCase();
+  if (/\p{N}/u.test(token)) return /^\p{L}/u.test(token) ? capitalizeFirst(token) : token;
+  if (!isFirst && SMALL_WORDS.has(lower)) return lower;
+  return capitalizeFirst(lower);
+}
+function slugLabel(input) {
+  if (typeof input !== "string") return "";
+  const path = input.split(/[?#]/, 1)[0].replace(URL_ORIGIN, "");
+  const segment = path.split(/[/\\]/).filter((s) => s.trim() !== "").pop();
+  if (!segment) return "";
+  const name = decodeEscapes(segment).replace(PAGE_EXTENSION, "");
+  const tokens = name.split(/[-_+\s]+/).filter(Boolean);
+  return tokens.map((token, i) => labelWord(token, i === 0, i === tokens.length - 1)).join(" ");
+}
+var PLACEHOLDER_TOKEN = /^(?::[A-Za-z_][\w-]*[?*+]?|\[\[\.\.\.[A-Za-z_][\w-]*\]\]|\[(?:\.\.\.)?[A-Za-z_][\w-]*\])$/;
+function isRoutePlaceholder(value) {
+  if (typeof value !== "string") return false;
+  return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
+}
+
+exports.isRoutePlaceholder = isRoutePlaceholder;
+exports.slugLabel = slugLabel;
+exports.titleHead = titleHead;

package/dist/page-titles.mjs

@@ -0,0 +1,120 @@
+// src/contracts/seo-meta.ts
+var TITLE_SEPARATOR = " | ";
+function stripTitleSuffix(title) {
+  const t = title.trim();
+  const i = t.lastIndexOf(TITLE_SEPARATOR);
+  return i > 0 ? t.slice(0, i).trim() : t;
+}
+
+// src/contracts/page-titles.ts
+var PIPE_RUN = /\|(?:\s*\|)+/g;
+var EDGE_PIPES = /^[\s|]+|[\s|]+$/g;
+function titleHead(title) {
+  if (typeof title !== "string") return "";
+  const tidy = title.replace(/\s+/g, " ").replace(PIPE_RUN, " | ").replace(EDGE_PIPES, "").replace(/\s+/g, " ");
+  return tidy ? stripTitleSuffix(tidy) : "";
+}
+var ACRONYMS = /* @__PURE__ */ new Map([
+  ["ac", "AC"],
+  ["ai", "AI"],
+  ["aeo", "AEO"],
+  ["api", "API"],
+  ["cms", "CMS"],
+  ["crm", "CRM"],
+  ["faq", "FAQ"],
+  ["faqs", "FAQs"],
+  ["fsbo", "FSBO"],
+  ["hvac", "HVAC"],
+  ["jl", "JL"],
+  ["llc", "LLC"],
+  ["llp", "LLP"],
+  ["mls", "MLS"],
+  ["pdf", "PDF"],
+  ["pllc", "PLLC"],
+  ["ppc", "PPC"],
+  ["roi", "ROI"],
+  ["seo", "SEO"],
+  ["ui", "UI"],
+  ["usa", "USA"],
+  ["ux", "UX"]
+]);
+var STATE_CODES = new Set(
+  "al ak az ar ca co ct de dc fl ga hi id il in ia ks ky la me md ma mi mn ms mo mt ne nv nh nj nm ny nc nd oh ok or pa ri sc sd tn tx ut vt va wa wv wi wy".split(" ")
+);
+var WORD_STATE_CODES = /* @__PURE__ */ new Set([
+  "in",
+  "or",
+  "me",
+  "hi",
+  "id",
+  "la",
+  "ma",
+  "pa",
+  "al",
+  "de",
+  "co"
+]);
+var TRAILING_STATE_CODES = /* @__PURE__ */ new Set(["mt"]);
+function isStateCode(lower, isLast) {
+  if (!STATE_CODES.has(lower) || WORD_STATE_CODES.has(lower)) return false;
+  return TRAILING_STATE_CODES.has(lower) ? isLast : true;
+}
+var SMALL_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "at",
+  "by",
+  "for",
+  "in",
+  "of",
+  "on",
+  "or",
+  "the",
+  "to",
+  "vs",
+  "with"
+]);
+var PAGE_EXTENSION = /\.(?:html?|php|aspx)$/i;
+var URL_ORIGIN = /^[a-z][a-z0-9+.-]*:\/\/[^/\\]*/i;
+var PERCENT_RUN = /(?:%[0-9a-f]{2})+/gi;
+function decodeEscapes(value) {
+  return value.replace(PERCENT_RUN, (run) => {
+    try {
+      return decodeURIComponent(run);
+    } catch {
+      return run;
+    }
+  });
+}
+function capitalizeFirst(word) {
+  const code = word.codePointAt(0);
+  if (code === void 0) return word;
+  const first = String.fromCodePoint(code);
+  return first.toUpperCase() + word.slice(first.length);
+}
+function labelWord(token, isFirst, isLast) {
+  const lower = token.toLowerCase();
+  const acronym = ACRONYMS.get(lower);
+  if (acronym) return acronym;
+  if (isStateCode(lower, isLast)) return lower.toUpperCase();
+  if (/\p{N}/u.test(token)) return /^\p{L}/u.test(token) ? capitalizeFirst(token) : token;
+  if (!isFirst && SMALL_WORDS.has(lower)) return lower;
+  return capitalizeFirst(lower);
+}
+function slugLabel(input) {
+  if (typeof input !== "string") return "";
+  const path = input.split(/[?#]/, 1)[0].replace(URL_ORIGIN, "");
+  const segment = path.split(/[/\\]/).filter((s) => s.trim() !== "").pop();
+  if (!segment) return "";
+  const name = decodeEscapes(segment).replace(PAGE_EXTENSION, "");
+  const tokens = name.split(/[-_+\s]+/).filter(Boolean);
+  return tokens.map((token, i) => labelWord(token, i === 0, i === tokens.length - 1)).join(" ");
+}
+var PLACEHOLDER_TOKEN = /^(?::[A-Za-z_][\w-]*[?*+]?|\[\[\.\.\.[A-Za-z_][\w-]*\]\]|\[(?:\.\.\.)?[A-Za-z_][\w-]*\])$/;
+function isRoutePlaceholder(value) {
+  if (typeof value !== "string") return false;
+  return value.split("/").some((segment) => PLACEHOLDER_TOKEN.test(segment.trim()));
+}
+
+export { isRoutePlaceholder, slugLabel, titleHead };

package/dist/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 its own server-side SSRF host guard. 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;