@sonordev/contracts 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0
+
+First release. The rules site-kit 6.x published as `@sonordev/site-kit/*/contract`
+(website, color, sites, seo-pages, seo-meta, llms, forms, fleet, slots,
+portfolio), as a dependency-free package, so sonor-api, signal-api and the
+dashboard import them instead of keeping mirrors.

package/README.md

@@ -0,0 +1,44 @@
+# @sonordev/contracts
+
+The rules Sonor's sites, APIs and dashboard have to agree on, as one package.
+Pure functions and types: no dependencies, no DOM, no network.
+
+```bash
+pnpm add @sonordev/contracts
+```
+
+| Entry | What it decides | Who reads it |
+|---|---|---|
+| `@sonordev/contracts/website` | A site's design tokens and what a popup is made of (blocks, limits, the text sanitizer) | site-kit renders them, sonor-api validates every write, the dashboard previews them, Signal's agents send them |
+| `@sonordev/contracts/color` | Reading a CSS color, WCAG luminance and contrast | `website`, site-kit's brand extraction |
+| `@sonordev/contracts/sites` | The canonical shape of a site host (the multi-site `site` dimension) | every ingest and read that filters by site |
+| `@sonordev/contracts/seo-pages` | Which `seo_pages` row a path resolves to on a multi-site project | sonor-api, Signal, site-kit's sitemap sync |
+| `@sonordev/contracts/seo-meta` | Whether a title or description is fit to ship | site-kit, Signal's SEO gate |
+| `@sonordev/contracts/llms` | llms.txt sanitizers and contract version | site-kit, sonor-api, Signal's schema validation |
+| `@sonordev/contracts/forms` | The honeypot policy | site-kit forms, sonor-api intake |
+| `@sonordev/contracts/fleet` | The fleet heartbeat's wire shape | site-kit, sonor-api |
+| `@sonordev/contracts/slots` | Slot payload signing (HMAC; Node only) | sonor-api, site-kit on the server |
+| `@sonordev/contracts/portfolio` | Where a portfolio number comes from and which may headline; the live-frame message | sonor-api, Signal, agency-site-kit |
+
+## Why it exists
+
+Before this package, each API kept a byte-identical copy of the rules it
+shared with site-kit, plus a drift test to catch the copies diverging. Ten
+parallel copies of a rule is how two of them end up disagreeing. Now there's
+one: the source is `src/contracts/` in the site-kit repo, site-kit bundles it
+into its own `*/contract` entries, and this package publishes the same files
+for everyone else.
+
+## Loading it
+
+CommonJS and ESM both. `require('@sonordev/contracts/website')` works in a
+CommonJS Nest API (including `moduleResolution: "node"`, through
+`typesVersions`); `import` works everywhere else. `slots` imports Node's
+`crypto`, so keep it out of browser code.
+
+## Changing a rule
+
+Edit `src/contracts/<entry>.ts` in the site-kit repo, run
+`pnpm test:contracts`, and bump this package's version. A breaking change to
+a shape bumps the major and that contract's own `*_VERSION` constant.
+`pnpm build:contracts` builds it and checks every entry loads both ways.

package/dist/color.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @sonordev/contracts/color — CSS colour reading and WCAG contrast
+ *
+ * Single source of truth for turning a CSS colour string into something the
+ * kit can reason about. Used at build time by the brand-profile extractor
+ * (`src/brand/extract-brand-profile.ts`, theme detection) and in the browser
+ * by Echo (`src/engage/brand-color.ts`, brand text contrast). Pure, no
+ * imports, safe in both.
+ */
+export type Rgb = {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare const HEX_COLOR: RegExp;
+/**
+ * WCAG relative luminance below which a color reads as dark — the point where
+ * it contrasts more with white than with black.
+ */
+export declare const DARK_LUMINANCE = 0.179;
+/** WCAG 2.x relative luminance of an sRGB colour (0 = black, 1 = white). */
+export declare function relativeLuminance({ r, g, b }: Rgb): number;
+/** WCAG 2.x contrast ratio between two relative luminances (1 to 21). */
+export declare function contrastRatio(a: number, b: number): number;
+/**
+ * The sRGB channels (0-255, alpha ignored) of a resolved CSS color, or null
+ * when the value isn't one this can read or paints nothing. Covers hex (3, 4,
+ * 6 and 8 digits), rgb()/rgba() and hsl()/hsla() in comma or space syntax, a
+ * bare shadcn-style HSL triple (`0 0% 100%`), and white/black. oklch(), lab()
+ * and named colours beyond those two return null.
+ */
+export declare function parseColor(value: string): Rgb | null;
+/**
+ * Relative luminance (0 = black, 1 = white) of a resolved CSS color, or null
+ * when the value isn't a color this can read. Everything `parseColor` reads,
+ * plus oklch()/oklab()/lab()/lch() (from their lightness).
+ */
+export declare function colorLuminance(value: string): number | null;

package/dist/color.js

@@ -0,0 +1,101 @@
+'use strict';
+
+// src/contracts/color.ts
+var HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var DARK_LUMINANCE = 0.179;
+function channel(v) {
+  const c = v / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance({ r, g, b }) {
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+function contrastRatio(a, b) {
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+function hexToRgb(hex) {
+  if (!HEX_COLOR.test(hex)) return null;
+  let c = hex.slice(1);
+  if (c.length <= 4) c = c.split("").map((ch) => ch + ch).join("");
+  if (c.length === 8 && c.slice(6) === "00") return null;
+  return {
+    r: parseInt(c.slice(0, 2), 16),
+    g: parseInt(c.slice(2, 4), 16),
+    b: parseInt(c.slice(4, 6), 16)
+  };
+}
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: Math.round(f(0) * 255), g: Math.round(f(8) * 255), b: Math.round(f(4) * 255) };
+}
+function colorArgs(inner) {
+  const [main, alpha] = inner.split("/");
+  const parts = main.split(/[\s,]+/).filter(Boolean);
+  if (alpha === void 0 && parts.length === 4) return { parts: parts.slice(0, 3), alpha: parts[3] };
+  return { parts, alpha: alpha?.trim() };
+}
+function isTransparentAlpha(alpha) {
+  if (!alpha) return false;
+  const n = alpha.endsWith("%") ? parseFloat(alpha) / 100 : parseFloat(alpha);
+  return n === 0;
+}
+function colorFunction(v) {
+  const fn = v.match(/^([a-z]+)\((.*)\)$/);
+  if (!fn) return null;
+  const { parts, alpha } = colorArgs(fn[2]);
+  if (isTransparentAlpha(alpha) || parts.length < 3) return null;
+  return { name: fn[1], parts };
+}
+var num = (p, scale) => p.endsWith("%") ? parseFloat(p) / 100 * scale : parseFloat(p);
+function parseColor(value) {
+  const v = value.trim().toLowerCase();
+  if (!v || v === "transparent") return null;
+  if (v === "white") return { r: 255, g: 255, b: 255 };
+  if (v === "black") return { r: 0, g: 0, b: 0 };
+  if (v.startsWith("#")) return hexToRgb(v);
+  const fn = colorFunction(v);
+  if (fn) {
+    const { name, parts } = fn;
+    if (name === "rgb" || name === "rgba") {
+      const [r, g, b] = parts.map((p) => num(p, 255));
+      return [r, g, b].some(Number.isNaN) ? null : { r, g, b };
+    }
+    if (name === "hsl" || name === "hsla") {
+      const h = parseFloat(parts[0]);
+      const s = num(parts[1], 1);
+      const l = num(parts[2], 1);
+      return [h, s, l].some(Number.isNaN) ? null : hslToRgb(h, s, l);
+    }
+    return null;
+  }
+  const triple = v.match(/^(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (triple) return hslToRgb(parseFloat(triple[1]), parseFloat(triple[2]) / 100, parseFloat(triple[3]) / 100);
+  return null;
+}
+function colorLuminance(value) {
+  const rgb = parseColor(value);
+  if (rgb) return relativeLuminance(rgb);
+  const fn = colorFunction(value.trim().toLowerCase());
+  if (!fn) return null;
+  const { name, parts } = fn;
+  if (name === "oklch" || name === "oklab") {
+    const L = num(parts[0], 1);
+    return Number.isNaN(L) ? null : Math.min(1, Math.max(0, L)) ** 3;
+  }
+  if (name === "lab" || name === "lch") {
+    const L = num(parts[0], 100);
+    if (Number.isNaN(L)) return null;
+    const f = (L + 16) / 116;
+    return Math.min(1, Math.max(0, L > 8 ? f ** 3 : L / 903.3));
+  }
+  return null;
+}
+
+exports.DARK_LUMINANCE = DARK_LUMINANCE;
+exports.HEX_COLOR = HEX_COLOR;
+exports.colorLuminance = colorLuminance;
+exports.contrastRatio = contrastRatio;
+exports.parseColor = parseColor;
+exports.relativeLuminance = relativeLuminance;

package/dist/color.mjs

@@ -0,0 +1,94 @@
+// src/contracts/color.ts
+var HEX_COLOR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var DARK_LUMINANCE = 0.179;
+function channel(v) {
+  const c = v / 255;
+  return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance({ r, g, b }) {
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+function contrastRatio(a, b) {
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+function hexToRgb(hex) {
+  if (!HEX_COLOR.test(hex)) return null;
+  let c = hex.slice(1);
+  if (c.length <= 4) c = c.split("").map((ch) => ch + ch).join("");
+  if (c.length === 8 && c.slice(6) === "00") return null;
+  return {
+    r: parseInt(c.slice(0, 2), 16),
+    g: parseInt(c.slice(2, 4), 16),
+    b: parseInt(c.slice(4, 6), 16)
+  };
+}
+function hslToRgb(h, s, l) {
+  const k = (n) => (n + h / 30) % 12;
+  const a = s * Math.min(l, 1 - l);
+  const f = (n) => l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
+  return { r: Math.round(f(0) * 255), g: Math.round(f(8) * 255), b: Math.round(f(4) * 255) };
+}
+function colorArgs(inner) {
+  const [main, alpha] = inner.split("/");
+  const parts = main.split(/[\s,]+/).filter(Boolean);
+  if (alpha === void 0 && parts.length === 4) return { parts: parts.slice(0, 3), alpha: parts[3] };
+  return { parts, alpha: alpha?.trim() };
+}
+function isTransparentAlpha(alpha) {
+  if (!alpha) return false;
+  const n = alpha.endsWith("%") ? parseFloat(alpha) / 100 : parseFloat(alpha);
+  return n === 0;
+}
+function colorFunction(v) {
+  const fn = v.match(/^([a-z]+)\((.*)\)$/);
+  if (!fn) return null;
+  const { parts, alpha } = colorArgs(fn[2]);
+  if (isTransparentAlpha(alpha) || parts.length < 3) return null;
+  return { name: fn[1], parts };
+}
+var num = (p, scale) => p.endsWith("%") ? parseFloat(p) / 100 * scale : parseFloat(p);
+function parseColor(value) {
+  const v = value.trim().toLowerCase();
+  if (!v || v === "transparent") return null;
+  if (v === "white") return { r: 255, g: 255, b: 255 };
+  if (v === "black") return { r: 0, g: 0, b: 0 };
+  if (v.startsWith("#")) return hexToRgb(v);
+  const fn = colorFunction(v);
+  if (fn) {
+    const { name, parts } = fn;
+    if (name === "rgb" || name === "rgba") {
+      const [r, g, b] = parts.map((p) => num(p, 255));
+      return [r, g, b].some(Number.isNaN) ? null : { r, g, b };
+    }
+    if (name === "hsl" || name === "hsla") {
+      const h = parseFloat(parts[0]);
+      const s = num(parts[1], 1);
+      const l = num(parts[2], 1);
+      return [h, s, l].some(Number.isNaN) ? null : hslToRgb(h, s, l);
+    }
+    return null;
+  }
+  const triple = v.match(/^(-?[\d.]+)(?:deg)?\s+([\d.]+)%\s+([\d.]+)%$/);
+  if (triple) return hslToRgb(parseFloat(triple[1]), parseFloat(triple[2]) / 100, parseFloat(triple[3]) / 100);
+  return null;
+}
+function colorLuminance(value) {
+  const rgb = parseColor(value);
+  if (rgb) return relativeLuminance(rgb);
+  const fn = colorFunction(value.trim().toLowerCase());
+  if (!fn) return null;
+  const { name, parts } = fn;
+  if (name === "oklch" || name === "oklab") {
+    const L = num(parts[0], 1);
+    return Number.isNaN(L) ? null : Math.min(1, Math.max(0, L)) ** 3;
+  }
+  if (name === "lab" || name === "lch") {
+    const L = num(parts[0], 100);
+    if (Number.isNaN(L)) return null;
+    const f = (L + 16) / 116;
+    return Math.min(1, Math.max(0, L > 8 ? f ** 3 : L / 903.3));
+  }
+  return null;
+}
+
+export { DARK_LUMINANCE, HEX_COLOR, colorLuminance, contrastRatio, parseColor, relativeLuminance };

package/dist/fleet.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @sonordev/contracts/fleet — Fleet heartbeat wire contract (v1)
+ *
+ * Single source of truth for the heartbeat payload shape, shared by site-kit
+ * (send side, `@sonordev/site-kit/fleet/contract`) and sonor-api (ingest
+ * side: its DTO is type-checked against FleetHeartbeatPayload).
+ *
+ * Why it exists: ~24+ client sites run site-kit at wildly drifted versions and
+ * the platform could not answer "which version / modules / key state is each
+ * site running" without shelling into every local repo. The heartbeat answers
+ * that from live traffic. It is fire-and-forget, deferred to idle (never in the
+ * hydration path), and carries NO visitor data — only the site's own build
+ * fingerprint. Project identity is resolved server-side from the x-api-key
+ * header, exactly like every other /api/public/* endpoint; sites never send
+ * project IDs.
+ *
+ * The x-sitekit-version header (set by shared/sonorFetch on every request)
+ * already gives the platform a passive "last seen version" for ALL traffic,
+ * including server-only module fetches. The heartbeat adds the things a header
+ * can't carry: the active module set and the host Next.js version.
+ */
+/** Bump on breaking payload changes. Ingest accepts the current version. */
+export declare const FLEET_CONTRACT_VERSION = 1;
+/**
+ * Client-observable site-kit modules — the set a site can honestly self-report
+ * from a client boot, because SiteKitClientProviders actually mounts them.
+ *
+ * Server-only modules (seo, article, images, reputation, redirects, llms) are
+ * intentionally absent: they render on the server and cannot be observed from
+ * the browser. Their usage still surfaces passively through the
+ * x-sitekit-version header on their own server fetches.
+ */
+export type FleetModule = 'analytics' | 'engage' | 'signal' | 'sitemapSync' | 'forms' | 'commerce' | 'sync' | 'maps' | 'slots';
+/** Canonical order — used to serialize equal module sets identically. */
+export declare const FLEET_MODULES: readonly FleetModule[];
+/** Where a heartbeat originated. */
+export type FleetHeartbeatSource = 'client' | 'build';
+/** Hard cap on modules accepted in one payload (junk guard). */
+export declare const FLEET_MODULES_MAX = 32;
+/** Hard cap on the free-form version strings we accept. */
+export declare const FLEET_VERSION_MAX_LENGTH = 40;
+/** Semver-ish shape. Non-matching values are stored as null, never rejected. */
+export declare const FLEET_VERSION_PATTERN: RegExp;
+/** Max host length per RFC 1035. */
+export declare const FLEET_SITE_MAX_LENGTH = 253;
+/**
+ * The heartbeat body a site POSTs to `/api/public/fleet/heartbeat`.
+ * All wire fields are snake_case to match the other contract modules and the
+ * agent-facing read endpoints.
+ */
+export interface FleetHeartbeatPayload {
+    contract_version: number;
+    /** SITE_KIT_VERSION at runtime, e.g. "3.2.0". */
+    kit_version: string;
+    /** Installed Next.js version if detectable, else null. */
+    next_version?: string | null;
+    /** Client-observable active modules — deduped, validated, canonical order. */
+    modules: FleetModule[];
+    /** Normalized lowercase host (multi-site sub-dimension; see CLAUDE.md). */
+    site?: string | null;
+    /** 'client' (runtime boot) or 'build' (CI/build step). Default 'client'. */
+    source?: FleetHeartbeatSource;
+}
+/** The ingest endpoint's response. `received_at` is server-stamped ISO 8601. */
+export interface FleetHeartbeatResponse {
+    ok: boolean;
+    contract_version: number;
+    received_at: string;
+}
+export declare function isFleetModule(x: unknown): x is FleetModule;
+/**
+ * Dedupe + validate a modules array: drop unknowns, cap length, emit in the
+ * canonical FLEET_MODULES order so equal sets always serialize identically.
+ */
+export declare function normalizeFleetModules(input: unknown): FleetModule[];
+/** Coerce a version-ish string to a clean value or null (never throws). */
+export declare function sanitizeFleetVersion(raw: unknown): string | null;
+/**
+ * Light client-side site normalization to the canonical host shape (lowercase,
+ * no protocol/path/port). sonor-api's IngestService.normalizeSite is the
+ * AUTHORITATIVE normalizer and re-runs on ingest — this just avoids sending
+ * obvious noise. Keep the two shapes aligned (see CLAUDE.md "site" convention).
+ */
+export declare function normalizeFleetSite(raw: unknown): string | null;
+/**
+ * Build a validated heartbeat payload from loose inputs. Used by BOTH the
+ * client component and the build-time sender so the wire shape is produced in
+ * exactly one place (single source of truth for the heartbeat body).
+ */
+export declare function buildFleetHeartbeatPayload(input: {
+    kitVersion: string;
+    nextVersion?: string | null;
+    modules?: unknown;
+    site?: string | null;
+    source?: FleetHeartbeatSource;
+}): FleetHeartbeatPayload;

package/dist/fleet.js

@@ -0,0 +1,67 @@
+'use strict';
+
+// src/contracts/fleet.ts
+var FLEET_CONTRACT_VERSION = 1;
+var FLEET_MODULES = [
+  "analytics",
+  "engage",
+  "signal",
+  "sitemapSync",
+  "forms",
+  "commerce",
+  "sync",
+  "maps",
+  "slots"
+];
+var FLEET_MODULES_MAX = 32;
+var FLEET_VERSION_MAX_LENGTH = 40;
+var FLEET_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/;
+var FLEET_SITE_MAX_LENGTH = 253;
+function isFleetModule(x) {
+  return typeof x === "string" && FLEET_MODULES.includes(x);
+}
+function normalizeFleetModules(input) {
+  if (!Array.isArray(input)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of input) {
+    if (isFleetModule(item)) seen.add(item);
+    if (seen.size >= FLEET_MODULES_MAX) break;
+  }
+  return FLEET_MODULES.filter((m) => seen.has(m));
+}
+function sanitizeFleetVersion(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s || s.length > FLEET_VERSION_MAX_LENGTH) return null;
+  return FLEET_VERSION_PATTERN.test(s) ? s : null;
+}
+function normalizeFleetSite(raw) {
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "");
+  if (!s || s.length > FLEET_SITE_MAX_LENGTH) return null;
+  return s;
+}
+function buildFleetHeartbeatPayload(input) {
+  return {
+    contract_version: FLEET_CONTRACT_VERSION,
+    kit_version: input.kitVersion,
+    next_version: sanitizeFleetVersion(input.nextVersion ?? null),
+    modules: normalizeFleetModules(input.modules),
+    site: normalizeFleetSite(input.site ?? null),
+    source: input.source === "build" ? "build" : "client"
+  };
+}
+
+exports.FLEET_CONTRACT_VERSION = FLEET_CONTRACT_VERSION;
+exports.FLEET_MODULES = FLEET_MODULES;
+exports.FLEET_MODULES_MAX = FLEET_MODULES_MAX;
+exports.FLEET_SITE_MAX_LENGTH = FLEET_SITE_MAX_LENGTH;
+exports.FLEET_VERSION_MAX_LENGTH = FLEET_VERSION_MAX_LENGTH;
+exports.FLEET_VERSION_PATTERN = FLEET_VERSION_PATTERN;
+exports.buildFleetHeartbeatPayload = buildFleetHeartbeatPayload;
+exports.isFleetModule = isFleetModule;
+exports.normalizeFleetModules = normalizeFleetModules;
+exports.normalizeFleetSite = normalizeFleetSite;
+exports.sanitizeFleetVersion = sanitizeFleetVersion;

package/dist/fleet.mjs

@@ -0,0 +1,55 @@
+// src/contracts/fleet.ts
+var FLEET_CONTRACT_VERSION = 1;
+var FLEET_MODULES = [
+  "analytics",
+  "engage",
+  "signal",
+  "sitemapSync",
+  "forms",
+  "commerce",
+  "sync",
+  "maps",
+  "slots"
+];
+var FLEET_MODULES_MAX = 32;
+var FLEET_VERSION_MAX_LENGTH = 40;
+var FLEET_VERSION_PATTERN = /^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][0-9A-Za-z.-]+)?$/;
+var FLEET_SITE_MAX_LENGTH = 253;
+function isFleetModule(x) {
+  return typeof x === "string" && FLEET_MODULES.includes(x);
+}
+function normalizeFleetModules(input) {
+  if (!Array.isArray(input)) return [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of input) {
+    if (isFleetModule(item)) seen.add(item);
+    if (seen.size >= FLEET_MODULES_MAX) break;
+  }
+  return FLEET_MODULES.filter((m) => seen.has(m));
+}
+function sanitizeFleetVersion(raw) {
+  if (typeof raw !== "string") return null;
+  const s = raw.trim();
+  if (!s || s.length > FLEET_VERSION_MAX_LENGTH) return null;
+  return FLEET_VERSION_PATTERN.test(s) ? s : null;
+}
+function normalizeFleetSite(raw) {
+  if (typeof raw !== "string") return null;
+  let s = raw.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "");
+  if (!s || s.length > FLEET_SITE_MAX_LENGTH) return null;
+  return s;
+}
+function buildFleetHeartbeatPayload(input) {
+  return {
+    contract_version: FLEET_CONTRACT_VERSION,
+    kit_version: input.kitVersion,
+    next_version: sanitizeFleetVersion(input.nextVersion ?? null),
+    modules: normalizeFleetModules(input.modules),
+    site: normalizeFleetSite(input.site ?? null),
+    source: input.source === "build" ? "build" : "client"
+  };
+}
+
+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 };

package/dist/forms.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @sonordev/contracts/forms — managed-form honeypot policy (v1)
+ *
+ * Single source of truth for the honeypot trap-field naming + server-side
+ * detection policy, shared by the client (site-kit emits the trap field) and
+ * the server (sonor-api names the trap in the form config it returns AND
+ * detects hits on intake). Both import this: site-kit as
+ * `@sonordev/site-kit/forms/contract`, sonor-api through
+ * `src/modules/forms/honeypot-contract.ts`.
+ *
+ * The default field name (`_sk_hp_url`) is deliberately obscure: a common name
+ * like "website" collides with real form fields and flags genuine submissions
+ * as spam, so generic names are only trusted when they DON'T match a real
+ * field of the form (see `resolveHoneypotFieldNames`).
+ */
+/** Bump on breaking changes to the honeypot policy. */
+export declare const FORMS_HONEYPOT_CONTRACT_VERSION: 1;
+/**
+ * Default honeypot field name emitted by site-kit and used by the server as the
+ * fallback trap name when a form has no explicitly configured `honeypot_field`.
+ * Deliberately obscure to avoid colliding with real form fields.
+ */
+export declare const DEFAULT_HONEYPOT_FIELD = "_sk_hp_url";
+/**
+ * Generic trap names the server also watches on intake — the canonical default
+ * plus legacy names still emitted by older deployed forms. Each is only trusted
+ * when it doesn't collide with a real configured field of the form.
+ */
+export declare const GENERIC_HONEYPOT_FIELDS: readonly string[];
+/**
+ * Build the set of field names the server treats as honeypot traps for one form.
+ * Generic names that collide with a real field slug are dropped (or every real
+ * lead using that field would be flagged); the form's dedicated
+ * `honeypot_field` is always honored. Returns an empty set when disabled.
+ */
+export declare function resolveHoneypotFieldNames(opts: {
+    enabled: boolean;
+    formHoneypotField?: string | null;
+    realFieldSlugs?: Iterable<string>;
+}): Set<string>;
+/**
+ * What a tripped trap looked like. Deliberately carries NO value — an
+ * autofilled trap can hold the visitor's real name, URL, or email, and this
+ * rides along into stored spam analysis. The field name is the diagnostic that
+ * matters; type and length are enough to tell autofill from a bot.
+ */
+export interface HoneypotHit {
+    /** Which trap fired. Several are watched per form; only this one tripped. */
+    field: string;
+    valueType: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** Character length for strings, element count for arrays, else null. */
+    length: number | null;
+}
+/**
+ * The first watched trap this submission actually filled, or null.
+ *
+ * Returns the NAME, not a boolean, because "honeypot fired" alone is
+ * unfalsifiable after the fact: the trap values are stripped before storage, so
+ * a bare flag left no way to tell a bot from a browser autofilling a hidden
+ * field. Callers stamp the name into the spam reasons.
+ */
+export declare function findTrippedTrap(data: Record<string, unknown> | null | undefined, fieldNames: Iterable<string>): HoneypotHit | null;
+/**
+ * True when any watched trap field carries a real value — the marker of an
+ * automated submission (real users never see or fill the trap).
+ * Thin view over {@link findTrippedTrap}; one detection rule, two shapes.
+ */
+export declare function isHoneypotTriggered(data: Record<string, unknown> | null | undefined, fieldNames: Iterable<string>): boolean;
+/**
+ * Agent-native contract: JSON Schema for the honeypot slice of the public form
+ * config, so services and agents can validate it mechanically.
+ */
+export declare const HONEYPOT_CONFIG_JSON_SCHEMA: {
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+    readonly $id: 'https://sonor.io/schemas/honeypot-config.v1.json';
+    readonly title: 'HoneypotConfig';
+    readonly description: 'The honeypot slice of a public managed-form config.';
+    readonly type: 'object';
+    readonly properties: {
+        readonly honeypot_enabled: {
+            readonly type: 'boolean';
+        };
+        readonly honeypot_field: {
+            readonly description: "Trap field name; defaults to \"_sk_hp_url\" when unset.";
+            readonly type: 'string';
+        };
+    };
+    readonly additionalProperties: true;
+};

package/dist/forms.js

@@ -0,0 +1,70 @@
+'use strict';
+
+// src/contracts/forms.ts
+var FORMS_HONEYPOT_CONTRACT_VERSION = 1;
+var DEFAULT_HONEYPOT_FIELD = "_sk_hp_url";
+var GENERIC_HONEYPOT_FIELDS = Object.freeze([
+  DEFAULT_HONEYPOT_FIELD,
+  "website",
+  "_hp_field",
+  "bot-field",
+  "bot_field"
+]);
+function resolveHoneypotFieldNames(opts) {
+  const names = /* @__PURE__ */ new Set();
+  if (!opts.enabled) return names;
+  const real = new Set(opts.realFieldSlugs ?? []);
+  for (const generic of GENERIC_HONEYPOT_FIELDS) {
+    if (!real.has(generic)) names.add(generic);
+  }
+  if (opts.formHoneypotField) names.add(opts.formHoneypotField);
+  return names;
+}
+function isTrapFilled(value) {
+  if (value == null) return false;
+  if (typeof value === "string") return value.trim() !== "";
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number") return Number.isFinite(value) && value !== 0;
+  if (Array.isArray(value)) return value.length > 0;
+  return true;
+}
+function findTrippedTrap(data, fieldNames) {
+  for (const field of fieldNames) {
+    const value = data?.[field];
+    if (!isTrapFilled(value)) continue;
+    if (Array.isArray(value)) return { field, valueType: "array", length: value.length };
+    const valueType = typeof value;
+    return {
+      field,
+      valueType: valueType === "string" ? "string" : valueType,
+      length: typeof value === "string" ? value.length : null
+    };
+  }
+  return null;
+}
+function isHoneypotTriggered(data, fieldNames) {
+  return findTrippedTrap(data, fieldNames) !== null;
+}
+var HONEYPOT_CONFIG_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  $id: "https://sonor.io/schemas/honeypot-config.v1.json",
+  title: "HoneypotConfig",
+  description: "The honeypot slice of a public managed-form config.",
+  type: "object",
+  properties: {
+    honeypot_enabled: { type: "boolean" },
+    honeypot_field: {
+      description: `Trap field name; defaults to "${DEFAULT_HONEYPOT_FIELD}" when unset.`,
+      type: "string"
+    }
+  },
+  additionalProperties: true
+};
+
+exports.DEFAULT_HONEYPOT_FIELD = DEFAULT_HONEYPOT_FIELD;
+exports.FORMS_HONEYPOT_CONTRACT_VERSION = FORMS_HONEYPOT_CONTRACT_VERSION;
+exports.GENERIC_HONEYPOT_FIELDS = GENERIC_HONEYPOT_FIELDS;
+exports.HONEYPOT_CONFIG_JSON_SCHEMA = HONEYPOT_CONFIG_JSON_SCHEMA;
+exports.findTrippedTrap = findTrippedTrap;
+exports.isHoneypotTriggered = isHoneypotTriggered;
+exports.resolveHoneypotFieldNames = resolveHoneypotFieldNames;