@sonordev/contracts 2.18.0 → 2.20.0

package/dist/signal-experiments.mjs

@@ -0,0 +1,260 @@
+// src/contracts/wire-schema.ts
+function createWireSchema(fail2, isValidationError) {
+  const own = (v, k) => Object.prototype.hasOwnProperty.call(v, k);
+  const field2 = (schema, read) => ({ schema, read });
+  const text2 = (max = 200, pattern, min = 1) => field2({ type: "string", minLength: min, maxLength: max, ...pattern ? { pattern: pattern.source } : {} }, (v, p) => typeof v === "string" && v.length >= min && v.length <= max && (!pattern || pattern.test(v)) ? v : fail2(p, "invalid string"));
+  const choice2 = (...values) => field2({ type: "string", enum: values }, (v, p) => typeof v === "string" && values.includes(v) ? v : fail2(p, "unsupported value"));
+  const literal2 = (value) => field2({ const: value }, (v, p) => v === value ? value : fail2(p, "unexpected value"));
+  const integer2 = (min = 0, max = Number.MAX_SAFE_INTEGER) => field2({ type: "integer", minimum: min, maximum: max }, (v, p) => typeof v === "number" && Number.isSafeInteger(v) && v >= min && v <= max ? v : fail2(p, "invalid integer"));
+  const bool = field2({ type: "boolean" }, (v, p) => typeof v === "boolean" ? v : fail2(p, "must be boolean"));
+  const optional2 = (f) => ({ ...f, optional: true });
+  const nullable2 = (f) => field2({ anyOf: [f.schema, { type: "null" }] }, (v, p) => v === null ? null : f.read(v, p));
+  const list2 = (f, max = 100, min = 0) => field2({ type: "array", items: f.schema, minItems: min, maxItems: max }, (v, p) => {
+    if (!Array.isArray(v) || v.length < min || v.length > max) fail2(p, "invalid array");
+    return v.map((x, i) => f.read(x, `${p}[${i}]`));
+  });
+  const object2 = (fields2) => field2({ type: "object", additionalProperties: false, properties: Object.fromEntries(Object.entries(fields2).map(([k, f]) => [k, f.schema])), required: Object.keys(fields2).filter((k) => !("optional" in fields2[k])) }, (v, p) => {
+    if (!v || typeof v !== "object" || Array.isArray(v) || ![Object.prototype, null].includes(Object.getPrototypeOf(v))) fail2(p, "must be a plain object");
+    const source = v, result = {};
+    for (const key of Reflect.ownKeys(source)) if (typeof key !== "string" || !own(fields2, key)) fail2(p, "unknown field");
+    for (const [key, f] of Object.entries(fields2)) {
+      if (!own(source, key)) {
+        if ("optional" in f) continue;
+        fail2(`${p}.${key}`, "required");
+      }
+      const descriptor = Object.getOwnPropertyDescriptor(source, key);
+      if (!own(descriptor, "value")) fail2(`${p}.${key}`, "accessors are not wire data");
+      result[key] = f.read(descriptor.value, `${p}.${key}`);
+    }
+    return result;
+  });
+  const union2 = (...fields2) => field2({ oneOf: fields2.map((f) => f.schema) }, (v, p) => {
+    const found = [];
+    for (const f of fields2) {
+      try {
+        found.push(f.read(v, p));
+      } catch (e) {
+        if (!isValidationError(e)) throw e;
+      }
+    }
+    return found.length === 1 ? found[0] : fail2(p, "must match exactly one supported shape");
+  });
+  const refine2 = (f, check) => field2(f.schema, (v, p) => {
+    const result = f.read(v, p);
+    check(result, p);
+    return result;
+  });
+  return { field: field2, text: text2, choice: choice2, literal: literal2, integer: integer2, bool, optional: optional2, nullable: nullable2, list: list2, object: object2, union: union2, refine: refine2 };
+}
+
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site) {
+  if (!site || typeof site !== "string") return null;
+  let s = site.trim().toLowerCase();
+  if (!s) return null;
+  s = s.replace(/^https?:\/\//, "");
+  const slash = s.indexOf("/");
+  if (slash >= 0) s = s.slice(0, slash);
+  const colon = s.indexOf(":");
+  if (colon >= 0) s = s.slice(0, colon);
+  s = s.replace(/\.+$/, "");
+  return s || null;
+}
+
+// src/contracts/sites.ts
+function isNormalizedSiteHost(value) {
+  return typeof value === "string" && value.length > 0 && normalizeSiteHost(value) === value;
+}
+
+// src/contracts/public-url-host.ts
+function isPrivateIpv4(a, b) {
+  return a === 127 || a === 10 || a === 0 || a === 192 && b === 168 || a === 172 && b >= 16 && b <= 31 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a >= 224;
+}
+function ipv6Words(host) {
+  if (!host.includes(":") || !/^[a-f\d:.]+$/.test(host)) return null;
+  let canonical;
+  try {
+    canonical = new URL(`http://[${host}]/`).hostname.slice(1, -1);
+  } catch {
+    return null;
+  }
+  const sides = canonical.split("::");
+  const left = sides[0] ? sides[0].split(":") : [];
+  const right = sides.length > 1 && sides[1] ? sides[1].split(":") : [];
+  return [...left, ...Array(sides.length > 1 ? 8 - left.length - right.length : 0).fill("0"), ...right].map((word) => parseInt(word, 16));
+}
+function isBlockedPublicUrlHost(rawHost) {
+  const host = rawHost.toLowerCase().replace(/^\[|\]$/g, "");
+  const blockedName = host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal");
+  if (host.includes(":") && host.includes("%")) return true;
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  const blockedIp = !!ipv4 && isPrivateIpv4(Number(ipv4[1]), Number(ipv4[2]));
+  const words = ipv6Words(host);
+  const blockedIpv6 = !!words && // Unspecified/loopback, unique-local, link-local, deprecated site-local
+  // and multicast destinations aren't public logo/webhook endpoints.
+  (words.every((word) => word === 0) || words.slice(0, 7).every((word) => word === 0) && words[7] === 1 || (words[0] & 65024) === 64512 || (words[0] & 65472) === 65152 || (words[0] & 65472) === 65216 || (words[0] & 65280) === 65280 || // IPv4-mapped and older IPv4-compatible forms carry an IPv4 destination.
+  words.slice(0, 5).every((word) => word === 0) && [0, 65535].includes(words[5]) && isPrivateIpv4(words[6] >> 8, words[6] & 255));
+  return blockedName || blockedIp || blockedIpv6;
+}
+
+// src/contracts/signal-experiments.ts
+var SignalExperimentValidationError = class extends Error {
+  constructor(path, reason) {
+    super(`${path}: ${reason}`);
+    this.path = path;
+    this.name = "SignalExperimentValidationError";
+  }
+};
+var fail = (path, reason) => {
+  throw new SignalExperimentValidationError(path, reason);
+};
+var { field, text, choice, literal, integer, optional, nullable, list, object, union, refine } = createWireSchema(fail, (error) => error instanceof SignalExperimentValidationError);
+var percent = field({ type: "number", minimum: 0, maximum: 100 }, (v, p) => typeof v === "number" && Number.isFinite(v) && v >= 0 && v <= 100 ? v : fail(p, "must be a finite percentage from 0 to 100"));
+var page = refine(text(2048, /^\/(?!\/)[^?#\s\\]*$/), (v, p) => {
+  const parsed = new URL(v, "https://example.com");
+  if (parsed.pathname !== v) fail(p, "must be a canonical page path");
+});
+var variant = object({ key: text(80), name: text(160), weight: percent, description: optional(text(1e3, void 0, 0)) });
+var variants = refine(list(variant, 50, 2), (v, p) => {
+  if (new Set(v.map((x) => x.key)).size !== v.length) fail(p, "variant keys must be unique");
+  if (Math.abs(v.reduce((sum, x) => sum + x.weight, 0) - 100) > 0.01) fail(p, "variant weights must sum to 100");
+});
+var targeting = object({ pages: optional(list(page, 100)), segments: optional(list(text(160), 100)), devices: optional(list(choice("desktop", "mobile", "tablet"), 3)), geo: optional(list(text(160), 100)) });
+var fields = { name: text(160), description: text(1e4, void 0, 0), variants, traffic_allocation: percent, targeting_rules: targeting };
+var create = object({ ...fields, description: optional(fields.description), traffic_allocation: optional(fields.traffic_allocation), targeting_rules: optional(fields.targeting_rules) });
+var update = object({ name: optional(fields.name), description: optional(fields.description), variants: optional(fields.variants), traffic_allocation: optional(fields.traffic_allocation), targeting_rules: optional(fields.targeting_rules) });
+var parseSignalExperimentCreate = (v) => create.read(v, "experimentCreate");
+var parseSignalExperimentUpdate = (v) => update.read(v, "experimentUpdate");
+var SIGNAL_EXPERIMENT_CREATE_JSON_SCHEMA = create.schema;
+var SIGNAL_EXPERIMENT_UPDATE_JSON_SCHEMA = update.schema;
+var measurementUuid = text(36, /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+var measurementRevision = text(128, /^[a-zA-Z0-9._:-]+$/);
+var measurementInstant = refine(text(30, /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/), (v, p) => {
+  if (!Number.isFinite(Date.parse(v)) || new Date(v).toISOString().replace(".000Z", "Z") !== v.replace(".000Z", "Z")) fail(p, "invalid UTC instant");
+});
+var measurementSite = refine(text(253), (v, p) => {
+  if (!isNormalizedSiteHost(v) || isBlockedPublicUrlHost(v)) fail(p, "must be a normalized public site host");
+});
+var measurementCount = text(30, /^(?:0|[1-9][0-9]*)$/);
+var measurementScope = object({
+  projectId: measurementUuid,
+  experimentId: measurementUuid,
+  site: measurementSite,
+  experimentRevision: integer(1),
+  goalRevision: measurementRevision,
+  campaignId: measurementUuid,
+  campaignVersionId: measurementUuid,
+  assignedFrom: measurementInstant,
+  assignedTo: measurementInstant
+});
+var assignmentCounts = {
+  variantKey: text(80),
+  assignedUnits: measurementCount,
+  exposureEvents: measurementCount,
+  exposedUnits: measurementCount,
+  matureAssignedUnits: measurementCount,
+  immatureAssignedUnits: measurementCount,
+  assignmentsWithoutExposure: measurementCount
+};
+var availableVariant = object({ ...assignmentCounts, acceptedFormEvents: measurementCount, acceptedFormUnits: measurementCount, matureAcceptedFormUnits: measurementCount });
+var unsupportedVariant = object({ ...assignmentCounts, acceptedFormEvents: literal(null), acceptedFormUnits: literal(null), matureAcceptedFormUnits: literal(null) });
+var businessMetrics = object({
+  uniqueQualifiedContacts: object({ state: literal("unavailable"), reasonCode: literal("original_qualified_lineage_not_bound") }),
+  wonValue: object({ state: literal("unavailable"), reasonCode: literal("original_deal_lineage_not_bound") }),
+  paidRevenue: object({ state: literal("unavailable"), reasonCode: literal("original_paid_source_lineage_not_bound") })
+});
+var goalCountingUnit = choice("unique_source", "unique_qualified_contact", "net_order");
+var originalGoalFields = { sourceId: measurementUuid, sourceRevision: measurementRevision, countingUnit: goalCountingUnit };
+var formSourceKind = choice("accepted_form", "qualified_lead");
+var unsupportedSourceKind = choice("completed_booking", "net_paid_order", "approved_application");
+var observedFields = {
+  schemaVersion: literal(1),
+  mode: literal("trusted_source"),
+  state: literal("observed"),
+  observedAt: measurementInstant,
+  scope: measurementScope,
+  countingUnit: literal("consent_subject"),
+  coverage: literal("assigned_population_only"),
+  semanticRole: literal("accepted_form_diagnostic"),
+  businessMetrics
+};
+var observedMeasurement = refine(union(
+  object({
+    ...observedFields,
+    originalGoal: object({ ...originalGoalFields, sourceKind: formSourceKind }),
+    diagnosticType: literal("accepted_form"),
+    diagnosticState: literal("available"),
+    variants: list(availableVariant, 50)
+  }),
+  object({
+    ...observedFields,
+    originalGoal: object({ ...originalGoalFields, sourceKind: unsupportedSourceKind }),
+    diagnosticType: literal(null),
+    diagnosticState: literal("unsupported_original_source"),
+    variants: list(unsupportedVariant, 50)
+  })
+), (value, p) => {
+  if (Date.parse(value.scope.assignedFrom) >= Date.parse(value.scope.assignedTo) || Date.parse(value.scope.assignedTo) > Date.parse(value.observedAt))
+    fail(p + ".scope", "requires an increasing assignment cohort ending by the native observation");
+  if (new Set(value.variants.map((v) => v.variantKey)).size !== value.variants.length) fail(p + ".variants", "variant keys must be unique");
+  for (const [index, v] of value.variants.entries()) {
+    const assigned = BigInt(v.assignedUnits), exposed = BigInt(v.exposedUnits), mature = BigInt(v.matureAssignedUnits);
+    const at = `${p}.variants[${index}]`;
+    if (exposed > assigned || BigInt(v.exposureEvents) < exposed || BigInt(v.assignmentsWithoutExposure) !== assigned - exposed || mature + BigInt(v.immatureAssignedUnits) !== assigned)
+      fail(at, "assignment, exposure and maturity counts are inconsistent");
+    if (v.acceptedFormUnits !== null && v.acceptedFormEvents !== null && v.matureAcceptedFormUnits !== null) {
+      const accepted = BigInt(v.acceptedFormUnits), matureAccepted = BigInt(v.matureAcceptedFormUnits);
+      if (accepted > exposed || accepted > BigInt(v.acceptedFormEvents) || matureAccepted > mature || matureAccepted > accepted)
+        fail(at, "accepted form units must remain within their exposed, event and mature cohorts");
+    }
+  }
+});
+var measurement = union(
+  object({ schemaVersion: literal(1), mode: literal("legacy"), state: literal("unavailable"), reasonCode: literal("legacy_assignment_outcome_events_only") }),
+  object({ schemaVersion: literal(1), mode: literal("trusted_source"), state: literal("unavailable"), reasonCode: literal("measurement_scope_required") }),
+  observedMeasurement
+);
+var parseSignalExperimentMeasurement = (v) => measurement.read(v, "experimentMeasurement");
+var SIGNAL_EXPERIMENT_MEASUREMENT_JSON_SCHEMA = measurement.schema;
+var scopeOption = object({
+  campaignId: measurementUuid,
+  campaignVersionId: measurementUuid,
+  campaignDefinitionRevision: integer(1),
+  acceptedAt: measurementInstant,
+  site: measurementSite,
+  experimentId: measurementUuid,
+  experimentRevision: integer(1),
+  goalRevision: measurementRevision,
+  goalLabel: nullable(text(200)),
+  assignmentExtent: nullable(object({ firstAssignedAt: measurementInstant, lastAssignedAt: measurementInstant })),
+  suggestedCohort: nullable(object({ assignedFrom: measurementInstant, assignedTo: measurementInstant }))
+});
+var scopeOptions = refine(object({ observedAt: measurementInstant, items: list(scopeOption, 100), nextCursor: nullable(text(4096)) }), (value, p) => {
+  const observed = Date.parse(value.observedAt), tuples = /* @__PURE__ */ new Set();
+  for (const [index, item] of value.items.entries()) {
+    const at = `${p}.items[${index}]`, accepted = Date.parse(item.acceptedAt);
+    const tuple = JSON.stringify([
+      item.campaignId.toLowerCase(),
+      item.campaignVersionId.toLowerCase(),
+      item.site,
+      item.experimentId.toLowerCase(),
+      item.experimentRevision,
+      item.goalRevision
+    ]);
+    if (tuples.has(tuple)) fail(at, "original scope tuples must be unique");
+    tuples.add(tuple);
+    if (accepted > observed) fail(at + ".acceptedAt", "must not follow the native observation");
+    if (item.assignmentExtent) {
+      const first = Date.parse(item.assignmentExtent.firstAssignedAt), last = Date.parse(item.assignmentExtent.lastAssignedAt);
+      if (first > last || last > observed) fail(at + ".assignmentExtent", "requires first <= last <= native observation");
+    }
+    if (item.suggestedCohort) {
+      const from = Date.parse(item.suggestedCohort.assignedFrom), to = Date.parse(item.suggestedCohort.assignedTo);
+      if (from !== accepted || from >= to || to > observed) fail(at + ".suggestedCohort", "requires original acceptance start and increasing cohort ending by native observation");
+    }
+  }
+});
+var parseSignalExperimentScopeOptions = (v) => scopeOptions.read(v, "experimentScopeOptions");
+var SIGNAL_EXPERIMENT_SCOPE_OPTIONS_JSON_SCHEMA = scopeOptions.schema;
+
+export { SIGNAL_EXPERIMENT_CREATE_JSON_SCHEMA, SIGNAL_EXPERIMENT_MEASUREMENT_JSON_SCHEMA, SIGNAL_EXPERIMENT_SCOPE_OPTIONS_JSON_SCHEMA, SIGNAL_EXPERIMENT_UPDATE_JSON_SCHEMA, SignalExperimentValidationError, parseSignalExperimentCreate, parseSignalExperimentMeasurement, parseSignalExperimentScopeOptions, parseSignalExperimentUpdate };

package/dist/wire-schema.d.ts

@@ -0,0 +1,36 @@
+/** Internal shared wire-schema primitives. Parser and JSON Schema share one field definition. */
+export type JsonSchema = {
+    [key: string]: unknown;
+};
+export interface Field<T> {
+    schema: JsonSchema;
+    read(value: unknown, path: string): T;
+}
+export type Value<F> = F extends Field<infer T> ? T : never;
+type Fields = Record<string, Field<unknown>>;
+type ObjectValue<S extends Fields> = {
+    [K in keyof S as S[K] extends {
+        optional: true;
+    } ? never : K]: Value<S[K]>;
+} & {
+    [K in keyof S as S[K] extends {
+        optional: true;
+    } ? K : never]?: Value<S[K]>;
+};
+export declare function createWireSchema(fail: (path: string, reason: string) => never, isValidationError: (error: unknown) => boolean): {
+    field: <T>(schema: JsonSchema, read: Field<T>['read']) => Field<T>;
+    text: (max?: number, pattern?: RegExp, min?: number) => Field<string>;
+    choice: <const T extends readonly string[]>(...values: T) => Field<T[number]>;
+    literal: <T extends string | number | boolean | null>(value: T) => Field<T>;
+    integer: (min?: number, max?: number) => Field<number>;
+    bool: Field<boolean>;
+    optional: <T>(f: Field<T>) => Field<T> & {
+        optional: true;
+    };
+    nullable: <T>(f: Field<T>) => Field<T | null>;
+    list: <T>(f: Field<T>, max?: number, min?: number) => Field<T[]>;
+    object: <S extends Fields>(fields: S) => Field<ObjectValue<S>>;
+    union: <const F extends readonly Field<unknown>[]>(...fields: F) => Field<Value<F[number]>>;
+    refine: <T>(f: Field<T>, check: (v: T, p: string) => void) => Field<T>;
+};
+export {};

package/docs.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": 1,
+  "title": "contracts",
+  "summary": "Shared validation rules, wire types and JSON schemas for Sonor applications.",
+  "groups": [
+    {
+      "title": "Start here",
+      "pages": [
+        {
+          "slug": "",
+          "title": "Overview and contracts",
+          "file": "README.md"
+        }
+      ]
+    }
+  ],
+  "changelog": {
+    "file": "CHANGELOG.md",
+    "since": "2.18.0"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sonordev/contracts",
-  "version": "2.18.0",
-  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, the forms honeypot, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, which literal hosts are refused as public fetch destinations, which inbox cards are decisions a bulk action leaves alone, what a rep's call outcome (positive, negative or left voicemail) changes on a prospect, and which buying role a job title says (owner, decision maker, influencer or gatekeeper). Pure functions, no dependencies.",
+  "version": "2.20.0",
+  "description": "The rules Sonor's sites, APIs and dashboard share: popup blocks and site design tokens, site hosts, SEO page identity, title quality, llms.txt sanitizers, shared form validation, fleet heartbeats, slot content and signing, site cache tags, portfolio metrics, the house voice's contraction rule, how a proposal's site plan counts its pages, what separates an error page from a page's content, which stored JSON-LD is a template's unfilled placeholder, where prose splits into sentences, which Sonor records Signal reads into a project's knowledge and the address each one is stored under, what outbound email and text may claim about a business and whether a sent email arrived intact, what a segment of outreach is and who may turn one on, a page's own name taken from its title or its slug, which Broadcast card layouts and review compositions are drawn and what a retired one draws as, what a publication's branding may hold, which literal hosts are refused as public fetch destinations, which inbox cards are decisions a bulk action leaves alone, what a rep's call outcome (positive, negative or left voicemail) changes on a prospect, and which buying role a job title says (owner, decision maker, influencer or gatekeeper). Pure functions, no dependencies.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -165,6 +165,21 @@
       "types": "./dist/decision-roles.d.ts",
       "import": "./dist/decision-roles.mjs",
       "require": "./dist/decision-roles.js"
+    },
+    "./resonance": {
+      "types": "./dist/resonance.d.ts",
+      "import": "./dist/resonance.mjs",
+      "require": "./dist/resonance.js"
+    },
+    "./resonance-constants": {
+      "types": "./dist/resonance-constants.d.ts",
+      "import": "./dist/resonance-constants.mjs",
+      "require": "./dist/resonance-constants.js"
+    },
+    "./signal-experiments": {
+      "types": "./dist/signal-experiments.d.ts",
+      "import": "./dist/signal-experiments.mjs",
+      "require": "./dist/signal-experiments.js"
     }
   },
   "typesVersions": {
@@ -177,7 +192,8 @@
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs.json"
   ],
   "engines": {
     "node": ">=20"