@sonordev/contracts 2.7.1 → 2.9.0

package/dist/outreach.mjs

@@ -0,0 +1,328 @@
+// src/contracts/business-claims.ts
+function fnv1a(text) {
+  let hash = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+// src/contracts/outreach.ts
+var OUTREACH_CONTRACT_VERSION = 1;
+var OUTREACH_WRITER_BADGE = "signal.outreach.writer";
+var OUTREACH_EMAIL_KIND = "outreach_email";
+var GRADUATION_BAR = { minMeasured: 5, minWinRate: 0.7, maxUnrevertedDegradations: 0 };
+var SEGMENT_STATES = ["ungranted", "granted", "paused", "lapsed", "revoked"];
+var UNSPECIFIED_INDUSTRY = "unspecified";
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var isUuid = (value) => typeof value === "string" && UUID.test(value);
+var isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+var nonEmpty = (value) => typeof value === "string" && value.trim().length > 0;
+function prospectIndustry(prospect) {
+  for (const value of [prospect?.vertical, prospect?.industry, prospect?.company_industry]) {
+    if (nonEmpty(value)) return value.trim();
+  }
+  return null;
+}
+function normalizeIndustry(value) {
+  if (typeof value !== "string") return UNSPECIFIED_INDUSTRY;
+  const slug = value.normalize("NFKC").normalize("NFD").replace(/\p{M}/gu, "").toLowerCase().replace(/&/g, " and ").replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 48).replace(/-+$/g, "");
+  return slug || UNSPECIFIED_INDUSTRY;
+}
+var NARRATIVE_PITCH_FIELDS = [
+  "positioning_statement",
+  "target_icp_description",
+  "tone_profile",
+  "hook_types",
+  "example_angles",
+  "value_prop_bullets"
+];
+function canonical(value) {
+  if (value === null || value === void 0) return "null";
+  if (typeof value === "string") return JSON.stringify(value.normalize("NFKC").replace(/\s+/g, " ").trim());
+  if (typeof value === "number" || typeof value === "boolean") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`).join(",")}}`;
+  }
+  return "null";
+}
+function narrativeFingerprint(narrative) {
+  const source = isRecord(narrative) ? narrative : {};
+  const pitch = {};
+  for (const field of NARRATIVE_PITCH_FIELDS) pitch[field] = source[field] ?? null;
+  return fnv1a(canonical(pitch));
+}
+function outreachSegment(input) {
+  const vertical = normalizeIndustry(input?.industry);
+  const label = typeof input?.label === "string" ? input.label : "";
+  const angle_fp = typeof input?.angleFp === "string" && input.angleFp ? input.angleFp : null;
+  if (input?.source === "drip") {
+    if (!isUuid(input.narrativeId) || !isUuid(input.mailboxId)) return null;
+    const narrative_id = input.narrativeId.toLowerCase();
+    const mailbox_id = input.mailboxId.toLowerCase();
+    return { key: `drip:${narrative_id}@${mailbox_id}|${vertical}`, source: "drip", narrative_id, mailbox_id, vertical, label, angle_fp };
+  }
+  if (input?.source === "mcp") {
+    const mailbox_id = isUuid(input.mailboxId) ? input.mailboxId.toLowerCase() : null;
+    return { key: `mcp:-|${vertical}`, source: "mcp", narrative_id: null, mailbox_id, vertical, label, angle_fp };
+  }
+  return null;
+}
+function outreachSegmentLabel(input) {
+  const name = nonEmpty(input?.narrativeName) ? input.narrativeName.trim() : "Outreach";
+  const industry = nonEmpty(input?.industry) ? input.industry.trim() : "leads with no industry";
+  const from = nonEmpty(input?.mailboxAddress) ? `, from ${input.mailboxAddress.trim()}` : "";
+  return `${name} to ${industry}${from}`;
+}
+var DRIP_KEY = /^drip:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})@([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\|([a-z0-9-]{1,48})$/;
+var MCP_KEY = /^mcp:-\|([a-z0-9-]{1,48})$/;
+function parseOutreachSegmentKey(key) {
+  if (typeof key !== "string" || key.length > 140) return null;
+  const drip = DRIP_KEY.exec(key);
+  if (drip) return { source: "drip", narrative_id: drip[1], mailbox_id: drip[2], vertical: drip[3] };
+  const mcp = MCP_KEY.exec(key);
+  if (mcp) return { source: "mcp", vertical: mcp[1] };
+  return null;
+}
+function isGrantableSegmentKey(key) {
+  const parsed = parseOutreachSegmentKey(key);
+  return parsed?.source === "drip" && parsed.vertical !== UNSPECIFIED_INDUSTRY;
+}
+var isDate = (value) => typeof value === "string" && !Number.isNaN(Date.parse(value));
+function readGrant(value) {
+  if (!isRecord(value)) return null;
+  const { state, source, by, via, at, ref, receipts, mailbox_id, label, angle_fp, paused, resumed, revoked } = value;
+  if (state !== "granted" && state !== "revoked") return null;
+  if (source !== "first_email" && source !== "earned") return null;
+  if (via !== "dashboard" && via !== "drafts") return null;
+  if (!nonEmpty(by) || !isDate(at) || !nonEmpty(ref) || !nonEmpty(mailbox_id) || !nonEmpty(angle_fp) || typeof label !== "string") return null;
+  const grant = { state, source, by, via, at, ref, mailbox_id, label, angle_fp };
+  if (receipts !== void 0) {
+    if (!Array.isArray(receipts) || !receipts.every(nonEmpty)) return null;
+    grant.receipts = [...receipts];
+  }
+  if (paused !== void 0 && paused !== null) {
+    if (!isRecord(paused) || !isDate(paused.at) || typeof paused.reason !== "string") return null;
+    grant.paused = { at: paused.at, reason: paused.reason, loss_ref: nonEmpty(paused.loss_ref) ? paused.loss_ref : null };
+  }
+  if (resumed !== void 0 && resumed !== null) {
+    if (!isRecord(resumed) || !nonEmpty(resumed.by) || !isDate(resumed.at)) return null;
+    grant.resumed = { by: resumed.by, at: resumed.at };
+  }
+  if (revoked !== void 0 && revoked !== null) {
+    if (!isRecord(revoked) || !nonEmpty(revoked.by) || !isDate(revoked.at) || typeof revoked.reason !== "string") return null;
+    grant.revoked = { by: revoked.by, at: revoked.at, reason: revoked.reason };
+  }
+  return grant;
+}
+function readSegmentGrants(source) {
+  const autonomy = isRecord(source) && isRecord(source.autonomy) ? source.autonomy : source;
+  const segments = isRecord(autonomy) && isRecord(autonomy.segments) ? autonomy.segments[OUTREACH_EMAIL_KIND] : null;
+  const out = {};
+  if (!isRecord(segments)) return out;
+  for (const key of Object.keys(segments)) {
+    if (!parseOutreachSegmentKey(key)) continue;
+    const grant = readGrant(segments[key]);
+    if (grant) out[key] = grant;
+  }
+  return out;
+}
+function activeSegmentGrant(source, key) {
+  if (!isGrantableSegmentKey(key)) return null;
+  const grant = readSegmentGrants(source)[key];
+  return grant && grant.state === "granted" && !grant.paused ? grant : null;
+}
+function segmentGrantCovers(grant, row) {
+  if (!grant) return { covers: false, code: "not_granted", reason: "Nobody's turned this segment on." };
+  if (grant.state === "revoked") return { covers: false, code: "revoked", reason: "Someone stopped this segment." };
+  if (grant.paused) return { covers: false, code: "paused", reason: `This segment stopped itself: ${grant.paused.reason}` };
+  if (grant.state !== "granted") return { covers: false, code: "not_granted", reason: "Nobody's turned this segment on." };
+  if (row.by !== void 0 && row.by !== grant.by) return { covers: false, code: "other_person", reason: "This row names someone other than the person who turned the segment on." };
+  const created = Date.parse(row.createdAt ?? "");
+  const granted = Date.parse(grant.at);
+  if (!Number.isFinite(created) || !Number.isFinite(granted) || created < granted) {
+    return { covers: false, code: "granted_after", reason: "This email was written before the segment was turned on." };
+  }
+  if (!row.angleFp || row.angleFp !== grant.angle_fp) {
+    return { covers: false, code: "angle_changed", reason: "The pitch changed since this segment was turned on, so its next email needs a look." };
+  }
+  if (!row.mailboxId || row.mailboxId.toLowerCase() !== grant.mailbox_id.toLowerCase()) {
+    return { covers: false, code: "other_mailbox", reason: "This email sends from a different mailbox than the one the segment was turned on for." };
+  }
+  return { covers: true };
+}
+function segmentOf(row) {
+  return isRecord(row.target_ref) && isRecord(row.target_ref.segment) ? row.target_ref.segment : null;
+}
+function payloadOf(row) {
+  return isRecord(row.payload) ? row.payload : {};
+}
+function viaOf(row) {
+  const approval = payloadOf(row)._approval;
+  return isRecord(approval) ? approval.via : void 0;
+}
+function wasEdited(row) {
+  const edited = payloadOf(row).edited;
+  return isRecord(edited) && typeof edited.count === "number" && edited.count > 0;
+}
+function readBackStatus(row) {
+  const execution = payloadOf(row)._execution;
+  return isRecord(execution) && isRecord(execution.read_back) ? execution.read_back.status : void 0;
+}
+function evidenceRowRefusal(row, grant, scope, people) {
+  if (!row) return "isn't on record";
+  if (row.kind !== OUTREACH_EMAIL_KIND || row.created_by !== OUTREACH_WRITER_BADGE) return "isn't an email Signal's outreach writer wrote";
+  if (scope.projectId && row.project_id && row.project_id !== scope.projectId) return "belongs to another project";
+  if (row.status !== "applied") return "wasn't approved and sent";
+  const segment = segmentOf(row);
+  if (!segment || segment.key !== scope.key) return "is in a different segment";
+  if (typeof segment.mailbox_id !== "string" || segment.mailbox_id.toLowerCase() !== grant.mailbox_id.toLowerCase()) return "went out from a different mailbox";
+  if (typeof segment.angle_fp === "string" && segment.angle_fp !== grant.angle_fp) return "was written for an earlier version of the pitch";
+  if (!nonEmpty(row.reviewed_by) || row.reviewed_by.startsWith("agent:")) return "wasn't approved by a person";
+  if (people && !people.has(row.reviewed_by)) return "wasn't approved by a person";
+  const reviewed = Date.parse(row.reviewed_at ?? "");
+  if (!Number.isFinite(reviewed) || reviewed > Date.parse(grant.at)) return "was approved after the segment was turned on";
+  const via = viaOf(row);
+  if (via !== "dashboard" && via !== "drafts") return via === "mcp" ? "was approved through MCP, not in Sonor" : "doesn't say where it was approved";
+  if (wasEdited(row)) return "was edited before it was approved";
+  if (readBackStatus(row) !== "verified") return "wasn't confirmed to have arrived intact";
+  return null;
+}
+function grantEvidenceRefusal(grant, refRows, scope) {
+  if (!grant) return "There's no grant.";
+  if (!isGrantableSegmentKey(scope?.key)) return "This segment can't be turned on.";
+  const rows = /* @__PURE__ */ new Map();
+  for (const row of refRows ?? []) if (row && typeof row.id === "string") rows.set(row.id, row);
+  const people = scope.people ? new Set(scope.people) : null;
+  if (grant.source === "first_email") {
+    const row = rows.get(grant.ref);
+    const refusal = evidenceRowRefusal(row, grant, scope, people);
+    if (refusal) return `The email this segment was turned on from ${refusal}.`;
+    if (row.reviewed_by !== grant.by) return "The email this segment was turned on from was approved by someone else.";
+    return null;
+  }
+  const receipts = Array.from(new Set(grant.receipts ?? []));
+  const needed = Math.max(1, Math.ceil(Number(scope.minMeasured) || 0));
+  if (receipts.length < needed) {
+    return `Only ${receipts.length} of the ${needed} approvals this segment needs to earn its own sending are on record.`;
+  }
+  for (const id of receipts) {
+    const refusal = evidenceRowRefusal(rows.get(id), grant, scope, people);
+    if (refusal) return `One of the approvals this segment earned its sending with ${refusal}.`;
+  }
+  return null;
+}
+var GRANTER_ROLES = /* @__PURE__ */ new Set(["owner", "admin"]);
+function segmentGranterEligible(roles) {
+  if (!roles) return false;
+  if (typeof roles.contact_type === "string" && roles.contact_type.trim().toLowerCase() === "agent") return false;
+  if (roles.is_platform_admin === true) return true;
+  return [roles.org_role, roles.project_role, roles.managing_org_role].some(
+    (role) => typeof role === "string" && GRANTER_ROLES.has(role.trim().toLowerCase())
+  );
+}
+var PUBLIC_MAILBOX_DOMAINS = [
+  "gmail.com",
+  "googlemail.com",
+  "yahoo.com",
+  "ymail.com",
+  "rocketmail.com",
+  "hotmail.com",
+  "outlook.com",
+  "live.com",
+  "msn.com",
+  "aol.com",
+  "aim.com",
+  "icloud.com",
+  "me.com",
+  "mac.com",
+  "protonmail.com",
+  "proton.me",
+  "pm.me",
+  "gmx.com",
+  "gmx.net",
+  "mail.com",
+  "zoho.com",
+  "zohomail.com",
+  "yandex.com",
+  "fastmail.com",
+  "hey.com",
+  "tutanota.com",
+  "tuta.io",
+  "att.net",
+  "sbcglobal.net",
+  "bellsouth.net",
+  "comcast.net",
+  "verizon.net",
+  "cox.net",
+  "charter.net",
+  "earthlink.net",
+  "frontier.com",
+  "windstream.net",
+  "centurylink.net",
+  "optonline.net",
+  "juno.com",
+  "netzero.net",
+  "roadrunner.com",
+  "rr.com",
+  "qq.com",
+  "163.com",
+  "126.com",
+  "mail.ru",
+  "web.de",
+  "t-online.de",
+  "orange.fr",
+  "free.fr",
+  "btinternet.com",
+  "sky.com",
+  "rogers.com",
+  "shaw.ca",
+  "sympatico.ca",
+  "bigpond.com"
+];
+var PUBLIC_DOMAIN_SET = new Set(PUBLIC_MAILBOX_DOMAINS);
+var PUBLIC_DOMAIN_FAMILY = /^(?:yahoo|ymail|hotmail|live|outlook|msn|aol|gmx|yandex)\.(?:[a-z]{2,3}|co\.[a-z]{2}|com\.[a-z]{2})$/;
+var PUBLIC_DOMAIN_SUFFIX = [".rr.com"];
+function isPublicMailboxDomain(value) {
+  if (typeof value !== "string") return false;
+  let domain = value.trim().toLowerCase().replace(/^mailto:/, "");
+  const at = domain.lastIndexOf("@");
+  if (at >= 0) domain = domain.slice(at + 1);
+  domain = domain.replace(/\.+$/, "").replace(/^www\./, "");
+  if (!domain) return false;
+  return PUBLIC_DOMAIN_SET.has(domain) || PUBLIC_DOMAIN_FAMILY.test(domain) || PUBLIC_DOMAIN_SUFFIX.some((suffix) => domain.endsWith(suffix));
+}
+function dripRowDisposition(row) {
+  const payload = isRecord(row?.payload) ? row.payload : {};
+  const execution = isRecord(payload._execution) ? payload._execution : {};
+  switch (row?.status) {
+    case "proposed":
+    case "approved":
+      return "live";
+    case "applied":
+    case "auto_applied":
+    case "executed":
+    case "reverted":
+      return "sent";
+    case "failed":
+      return execution.sent === true ? "sent" : "refile";
+    case "rejected": {
+      const decision = isRecord(row?.autonomy_decision) ? row.autonomy_decision : {};
+      if (decision.allowed === "off" && !row?.reviewed_by) return "refile";
+      const reason = row?.review_reason;
+      if (reason === "wrong_recipient") return "retire";
+      if (reason === "wrong_timing" || reason === "withdrawn") return "refile";
+      return "declined";
+    }
+    case "expired":
+    case "superseded":
+    case "discarded":
+      return "refile";
+    default:
+      return "live";
+  }
+}
+
+export { GRADUATION_BAR, NARRATIVE_PITCH_FIELDS, OUTREACH_CONTRACT_VERSION, OUTREACH_EMAIL_KIND, OUTREACH_WRITER_BADGE, PUBLIC_MAILBOX_DOMAINS, SEGMENT_STATES, UNSPECIFIED_INDUSTRY, activeSegmentGrant, dripRowDisposition, grantEvidenceRefusal, isGrantableSegmentKey, isPublicMailboxDomain, narrativeFingerprint, normalizeIndustry, outreachSegment, outreachSegmentLabel, parseOutreachSegmentKey, prospectIndustry, readSegmentGrants, segmentGrantCovers, segmentGranterEligible };

package/dist/page-titles.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ *
+ * 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;

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 };