@sonordev/contracts 2.13.0 → 2.16.0

package/dist/funnels.mjs

@@ -0,0 +1,560 @@
+// src/contracts/sites-normalize.ts
+function normalizeSiteHost(site2) {
+  if (!site2 || typeof site2 !== "string") return null;
+  let s = site2.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/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/publication-branding.ts
+var PUBLICATION_COLOR_FIELDS = ["primary", "secondary", "accent", "background", "surface", "text", "muted", "border"];
+var GENERIC_FONT_FAMILIES = /* @__PURE__ */ new Set(["serif", "sans-serif", "monospace", "system-ui", "cursive", "fantasy", "ui-serif", "ui-sans-serif", "ui-monospace"]);
+function containsControlCharacters(value) {
+  for (const character of value) {
+    const code = character.charCodeAt(0);
+    if (code <= 31 || code === 127) return true;
+  }
+  return false;
+}
+function safeFontStack(value) {
+  if (typeof value !== "string" || value.length > 512 || containsControlCharacters(value) || /[;{}<>\\]|(?:var|url|expression)\s*\(/i.test(value)) return void 0;
+  const names = value.split(",").map((v) => v.trim().replace(/^(['"])(.*)\1$/, "$2")).filter(Boolean).filter((v) => !/^(?:heading|body|mono)$/i.test(v));
+  if (!names.length || names.some((v) => !/^[\p{L}\p{N} _.-]+$/u.test(v))) return void 0;
+  return names.map((v) => GENERIC_FONT_FAMILIES.has(v.toLowerCase()) ? v.toLowerCase() : `'${v}'`).join(",");
+}
+
+// src/contracts/campaign-normalize.ts
+function normalizeCampaignSlug(input) {
+  if (!input || typeof input !== "string") return null;
+  const slug2 = input.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/[^a-z0-9-]/g, "").replace(/-{2,}/g, "-").replace(/^-+|-+$/g, "").slice(0, 80);
+  return slug2 || null;
+}
+
+// src/contracts/funnels.ts
+var FUNNEL_SCHEMA_VERSION = 1;
+var MANAGED_FUNNEL_PATH_PREFIX = "/f";
+var FUNNEL_TEMPLATES = ["newsletter", "requested_guide", "inquiry"];
+var string = (maxLength, minLength = 1) => ({ type: "string", minLength, maxLength });
+var literal = (value) => ({ const: value });
+var enumeration = (...values) => ({ type: "string", enum: values });
+var object = (properties, required = Object.keys(properties)) => ({ type: "object", properties, required, additionalProperties: false });
+var array = (items, maxItems, minItems = 0) => ({ type: "array", items, maxItems, minItems });
+var integer = (minimum, maximum = Number.MAX_SAFE_INTEGER) => ({ type: "integer", minimum, maximum });
+var nullable = (shape) => ({ oneOf: [shape, { type: "null" }] });
+var isoDate = { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$" };
+var uuid = { type: "string", pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$" };
+var slug = { ...string(80), pattern: "^[a-z0-9]+(?:-[a-z0-9]+)*$" };
+var fieldSlug = { ...string(80), pattern: "^[a-zA-Z0-9_-]+$" };
+var path = { ...string(512), pattern: "^/(?!/)[a-zA-Z0-9/_-]*$" };
+var site = { ...string(253), pattern: "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)+$" };
+var color = { ...string(9), pattern: "^#[a-fA-F0-9]{6}$" };
+var colors = object(Object.fromEntries(PUBLICATION_COLOR_FIELDS.map((key) => [key, color])));
+var typography = object({ headingFamily: string(200), bodyFamily: string(200) });
+var override = object({
+  displayName: nullable(string(120)),
+  tagline: nullable(string(300, 0)),
+  fullLogoAssetId: nullable(uuid),
+  squareLogoAssetId: nullable(uuid),
+  colors: object(Object.fromEntries(PUBLICATION_COLOR_FIELDS.map((key) => [key, nullable(color)])), []),
+  typography: object({ headingFamily: nullable(string(200)), bodyFamily: nullable(string(200)) }, [])
+}, []);
+var bodyBlock = { oneOf: [object({ type: literal("paragraph"), text: string(2e3) }), object({ type: literal("bullets"), items: array(string(500), 8, 1) })] };
+var body = array(bodyBlock, 12);
+var publicBrand = object({ displayName: string(120), tagline: string(300, 0), fullLogoUrl: nullable(string(2048)), squareLogoUrl: nullable(string(2048)), colors, typography, scheme: enumeration("light", "dark") });
+var step = { oneOf: [
+  object({ id: uuid, type: literal("wait"), durationSeconds: integer(60, 2592e3) }),
+  object({ id: uuid, type: literal("send_email"), templateId: uuid, purpose: enumeration("requested_fulfillment", "marketing"), guideAssetId: nullable(uuid) }, ["id", "type", "templateId", "purpose"]),
+  object({ id: uuid, type: literal("add_tag"), target: literal("subscriber"), tag: string(80) }),
+  object({ id: uuid, type: literal("create_task"), ownerContactId: uuid, title: string(160), dueAfterSeconds: integer(0, 2592e3) })
+] };
+var definitionShape = object({
+  schemaVersion: literal(1),
+  name: string(120),
+  template: enumeration(...FUNNEL_TEMPLATES),
+  site,
+  entry: object({ formId: uuid, mode: literal("future_accepted_form_only") }),
+  goal: object({ type: enumeration("newsletter_confirmed", "guide_requested", "inquiry_received", "booking_confirmed"), bookingTypeId: nullable(uuid) }, ["type"]),
+  page: object({ mode: enumeration("existing", "managed"), path, slug: nullable(slug), headline: string(160, 0), body, formId: uuid, offerAssetId: nullable(uuid) }, ["mode", "path", "headline", "body", "formId"]),
+  permission: object({ mode: enumeration("requested_only", "marketing_opt_in"), optInFieldSlug: nullable(fieldSlug) }, ["mode"]),
+  brandOverride: override,
+  steps: array(step, 8),
+  exits: object({ unsubscribe: literal(true), manualStop: literal(true), confirmedBooking: object({ enabled: { type: "boolean" }, bookingTypeId: nullable(uuid) }) }, ["unsubscribe", "manualStop"])
+}, ["schemaVersion", "name", "template", "site", "entry", "goal", "page", "permission", "steps", "exits"]);
+var draftDefinitionShape = JSON.parse(JSON.stringify(definitionShape));
+var draftProps = draftDefinitionShape.properties;
+draftProps.name = string(120, 0);
+draftProps.site = nullable(site);
+draftProps.entry.properties.formId = nullable(uuid);
+draftProps.page.properties.path = nullable(path);
+draftProps.page.properties.formId = nullable(uuid);
+draftProps.permission.properties.optInFieldSlug = nullable(fieldSlug);
+draftProps.steps.items.oneOf = draftProps.steps.items.oneOf.map((item) => {
+  const fields = item.properties;
+  if (fields.templateId) fields.templateId = nullable(uuid);
+  if (fields.guideAssetId) fields.guideAssetId = nullable(uuid);
+  if (fields.ownerContactId) fields.ownerContactId = nullable(uuid);
+  if (fields.title) fields.title = string(160, 0);
+  if (fields.tag) fields.tag = string(80, 0);
+  return item;
+});
+draftProps.page.properties.body = array({ oneOf: [object({ type: literal("paragraph"), text: string(2e3, 0) }), object({ type: literal("bullets"), items: array(string(500, 0), 8, 1) })] }, 12);
+var FUNNEL_DRAFT_DEFINITION_JSON_SCHEMA = { $schema: "http://json-schema.org/draft-07/schema#", ...draftDefinitionShape };
+function parseFunnelDraftDefinition(value) {
+  var _a, _b, _c, _d, _e;
+  check(value, draftDefinitionShape, "draft");
+  const result = JSON.parse(JSON.stringify(value));
+  (_a = result.goal).bookingTypeId ?? (_a.bookingTypeId = null);
+  (_b = result.page).slug ?? (_b.slug = null);
+  (_c = result.page).offerAssetId ?? (_c.offerAssetId = null);
+  (_d = result.permission).optInFieldSlug ?? (_d.optInFieldSlug = null);
+  result.brandOverride ?? (result.brandOverride = {});
+  (_e = result.exits).confirmedBooking ?? (_e.confirmedBooking = { enabled: false, bookingTypeId: null });
+  for (const item of result.steps) if (item.type === "send_email") item.guideAssetId ?? (item.guideAssetId = null);
+  checkBody(result.page.body, "draft.page.body");
+  if (result.brandOverride) checkFonts(result.brandOverride, "draft.brandOverride");
+  if (result.page.mode === "existing" && result.page.slug !== null) fail("draft.page.slug", "only managed pages have slugs");
+  return result;
+}
+function createFunnelDraft(template) {
+  if (!FUNNEL_TEMPLATES.includes(template)) fail("template", "unsupported template");
+  return parseFunnelDraftDefinition({
+    schemaVersion: 1,
+    name: { newsletter: "Newsletter signup", requested_guide: "Requested guide", inquiry: "Inquiry or consultation" }[template],
+    template,
+    site: null,
+    entry: { formId: null, mode: "future_accepted_form_only" },
+    goal: { type: { newsletter: "newsletter_confirmed", requested_guide: "guide_requested", inquiry: "inquiry_received" }[template], bookingTypeId: null },
+    page: { mode: "existing", path: null, slug: null, headline: "", body: [], formId: null, offerAssetId: null },
+    permission: { mode: template === "newsletter" ? "marketing_opt_in" : "requested_only", optInFieldSlug: null },
+    brandOverride: {},
+    steps: [],
+    exits: { unsubscribe: true, manualStop: true, confirmedBooking: { enabled: false, bookingTypeId: null } }
+  });
+}
+var FUNNEL_DEFINITION_JSON_SCHEMA = { $schema: "http://json-schema.org/draft-07/schema#", ...definitionShape };
+var publishedShape = object({
+  schemaVersion: literal(1),
+  id: uuid,
+  versionId: uuid,
+  revision: integer(1),
+  site,
+  path,
+  content: object({ headline: string(160), body, offer: object({ label: string(120), href: string(2048) }) }, ["headline", "body"]),
+  brand: publicBrand,
+  conversion: object({ formSlug: fieldSlug }),
+  tracking: object({ campaignSlug: slug })
+});
+var PUBLISHED_FUNNEL_PAGE_JSON_SCHEMA = { $schema: "http://json-schema.org/draft-07/schema#", ...publishedShape };
+var FUNNEL_LAUNCH_JSON_SCHEMA = object({ expectedRevision: integer(1), previewId: uuid, idempotencyKey: string(200), confirm: literal(true) });
+var FUNNEL_LIFECYCLE_JSON_SCHEMA = object({ expectedActiveVersionId: uuid, idempotencyKey: string(200), confirm: literal(true) });
+var FUNNEL_ROLLBACK_JSON_SCHEMA = object({ expectedActiveVersionId: uuid, targetVersionId: uuid, idempotencyKey: string(200), confirm: literal(true) });
+var FunnelValidationError = class extends Error {
+  constructor(path2, reason) {
+    super(`${path2}: ${reason}`);
+    this.path = path2;
+    this.name = "FunnelValidationError";
+  }
+};
+function fail(path2, reason) {
+  throw new FunnelValidationError(path2, reason);
+}
+function check(value, shape, at) {
+  if (shape.oneOf) {
+    let matches = 0;
+    for (const candidate of shape.oneOf) {
+      try {
+        check(value, candidate, at);
+        matches++;
+      } catch (error) {
+        if (!(error instanceof FunnelValidationError)) throw error;
+      }
+    }
+    if (matches !== 1) fail(at, "must match one supported shape");
+    return;
+  }
+  if ("const" in shape && value !== shape.const) fail(at, "unexpected value");
+  if (shape.enum && !shape.enum.includes(value)) fail(at, "unsupported value");
+  if (shape.type === "null" && value !== null) fail(at, "must be null");
+  if (shape.type === "boolean" && typeof value !== "boolean") fail(at, "must be boolean");
+  if (shape.type === "string") {
+    if (typeof value !== "string") fail(at, "must be a string");
+    if (value.length < (shape.minLength ?? 0) || value.length > (shape.maxLength ?? Infinity) || (shape.minLength ?? 0) > 0 && !value.trim() || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) fail(at, "invalid string length or control character");
+    if (shape.pattern) {
+      const match = new RegExp(shape.pattern).exec(value);
+      if (!match || match[0] !== value) fail(at, "invalid format");
+    }
+  }
+  if (shape.type === "integer" && (typeof value !== "number" || !Number.isSafeInteger(value) || value < (shape.minimum ?? -Infinity) || value > (shape.maximum ?? Infinity))) fail(at, "invalid integer");
+  if (shape.type === "array") {
+    if (!Array.isArray(value) || value.length < (shape.minItems ?? 0) || value.length > (shape.maxItems ?? Infinity)) fail(at, "invalid array length");
+    value.forEach((item, i) => check(item, shape.items, `${at}[${i}]`));
+  }
+  if (shape.type === "object") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) fail(at, "must be an object");
+    const row = value;
+    if (![Object.prototype, null].includes(Object.getPrototypeOf(row))) fail(at, "must be plain JSON");
+    for (const key of shape.required ?? []) if (!Object.prototype.hasOwnProperty.call(row, key)) fail(`${at}.${key}`, "required");
+    for (const key of Object.keys(row)) {
+      if (!Object.prototype.hasOwnProperty.call(shape.properties, key)) fail(`${at}.${key}`, "unknown field");
+      check(row[key], shape.properties[key], `${at}.${key}`);
+    }
+  }
+}
+function isSafeFunnelPublicUrl(value) {
+  try {
+    const url = new URL(value);
+    return value.startsWith("https://") && url.protocol === "https:" && !url.username && !url.password && (!url.port || url.port === "443") && !isBlockedPublicUrlHost(url.hostname) && !/[\s\x00-\x1f\\]/.test(value);
+  } catch {
+    return false;
+  }
+}
+function managedFunnelPath(value) {
+  check(value, slug, "slug");
+  if (normalizeCampaignSlug(value) !== value) fail("slug", "must be canonical");
+  return `${MANAGED_FUNNEL_PATH_PREFIX}/${value}`;
+}
+function checkFonts(value, at) {
+  for (const [key, font] of Object.entries(value.typography ?? {})) if (font !== null && safeFontStack(font) === void 0) fail(`${at}.typography.${key}`, "unsafe font stack");
+}
+function checkBody(blocks, at) {
+  if (blocks.reduce((total, block) => total + (block.type === "paragraph" ? block.text.length : block.items.join("").length), 0) > 12e3) fail(at, "total text exceeds 12000 characters");
+}
+function parseFunnelDefinition(value) {
+  check(value, definitionShape, "definition");
+  const result = JSON.parse(JSON.stringify(value));
+  if (normalizeSiteHost(result.site) !== result.site) fail("definition.site", "must be canonical");
+  if (result.page.formId !== result.entry.formId) fail("definition.page.formId", "must match the entry form");
+  if (result.page.mode === "managed") {
+    if (!result.page.slug || managedFunnelPath(result.page.slug) !== result.page.path) fail("definition.page.path", "must match the managed slug");
+  } else if (result.page.slug != null) fail("definition.page.slug", "only managed pages have slugs");
+  if (result.page.mode === "managed" && !result.page.headline.trim()) fail("definition.page.headline", "required for a managed page");
+  if (result.exits.confirmedBooking?.enabled && !result.exits.confirmedBooking.bookingTypeId) fail("definition.exits.confirmedBooking.bookingTypeId", "required when booking exit is enabled");
+  if (result.goal.type === "booking_confirmed" && !result.goal.bookingTypeId) fail("definition.goal.bookingTypeId", "required for a booking goal");
+  if (result.permission.mode === "marketing_opt_in" && !result.permission.optInFieldSlug) fail("definition.permission.optInFieldSlug", "explicit checkbox required");
+  if (result.steps.some((item) => item.type === "send_email" && item.purpose === "marketing") && result.permission.mode !== "marketing_opt_in") fail("definition.permission", "marketing requires explicit opt-in");
+  if (new Set(result.steps.map((item) => item.id)).size !== result.steps.length) fail("definition.steps", "step identities must be unique");
+  checkBody(result.page.body, "definition.page.body");
+  if (result.brandOverride) checkFonts(result.brandOverride, "definition.brandOverride");
+  return result;
+}
+function parsePublishedFunnelPage(value) {
+  check(value, publishedShape, "page");
+  const result = JSON.parse(JSON.stringify(value));
+  const suffix = result.path.slice(MANAGED_FUNNEL_PATH_PREFIX.length + 1);
+  if (managedFunnelPath(suffix) !== result.path) fail("page.path", "invalid managed route");
+  for (const key of ["fullLogoUrl", "squareLogoUrl"]) if (result.brand[key] && !isSafeFunnelPublicUrl(result.brand[key])) fail(`page.brand.${key}`, "unsafe public URL");
+  checkFonts(result.brand, "page.brand");
+  checkBody(result.content.body, "page.content.body");
+  if (result.content.offer && !isSafeFunnelPublicUrl(result.content.offer.href)) fail("page.content.offer.href", "unsafe public URL");
+  return result;
+}
+function parseFunnelLaunchArgs(value) {
+  check(value, FUNNEL_LAUNCH_JSON_SCHEMA, "launch");
+  return JSON.parse(JSON.stringify(value));
+}
+function parseFunnelLifecycleArgs(value, operation = "pause") {
+  check(value, operation === "rollback" ? FUNNEL_ROLLBACK_JSON_SCHEMA : FUNNEL_LIFECYCLE_JSON_SCHEMA, "lifecycle");
+  return JSON.parse(JSON.stringify(value));
+}
+function applyFunnelBrandOverride(inherited, patch = {}, resolvedAssets = {}) {
+  check(inherited, publicBrand, "brand");
+  check(patch, override, "brandOverride");
+  checkFonts(inherited, "brand");
+  checkFonts(patch, "brandOverride");
+  const brand = JSON.parse(JSON.stringify(inherited));
+  const overridePaths = [];
+  const assetRefs = [];
+  for (const key of ["displayName", "tagline"]) if (patch[key] != null) {
+    brand[key] = patch[key];
+    overridePaths.push(key);
+  }
+  for (const section of ["colors", "typography"]) {
+    for (const [key, value] of Object.entries(patch[section] ?? {})) if (value != null) {
+      Object.assign(brand[section], { [key]: value });
+      overridePaths.push(`${section}.${key}`);
+    }
+  }
+  for (const [idKey, urlKey] of [["fullLogoAssetId", "fullLogoUrl"], ["squareLogoAssetId", "squareLogoUrl"]]) {
+    const id = patch[idKey];
+    if (!id) continue;
+    const asset = Object.prototype.hasOwnProperty.call(resolvedAssets, id) ? resolvedAssets[id] : void 0;
+    if (!asset || !isSafeFunnelPublicUrl(asset.url)) fail(`brandOverride.${idKey}`, "authorized resolved asset required");
+    brand[urlKey] = asset.url;
+    overridePaths.push(urlKey);
+    assetRefs.push({ id, version: asset.version ?? null });
+  }
+  for (const key of ["fullLogoUrl", "squareLogoUrl"]) if (brand[key] && !isSafeFunnelPublicUrl(brand[key])) fail(`brand.${key}`, "unsafe public URL");
+  return { brand, overridePaths, assetRefs };
+}
+var FUNNEL_CREATE_JSON_SCHEMA = object({ idempotencyKey: string(200), definition: draftDefinitionShape });
+var FUNNEL_UPDATE_JSON_SCHEMA = object({ expectedRevision: integer(1), idempotencyKey: string(200), definition: draftDefinitionShape });
+function parseFunnelCreateArgs(value) {
+  check(value, FUNNEL_CREATE_JSON_SCHEMA, "create");
+  const args = value;
+  return { idempotencyKey: args.idempotencyKey, definition: parseFunnelDraftDefinition(args.definition) };
+}
+function parseFunnelUpdateArgs(value) {
+  check(value, FUNNEL_UPDATE_JSON_SCHEMA, "update");
+  const args = value;
+  return { expectedRevision: args.expectedRevision, idempotencyKey: args.idempotencyKey, definition: parseFunnelDraftDefinition(args.definition) };
+}
+function parseFunnelDraftArgs(value, mode) {
+  return mode === "update" ? parseFunnelUpdateArgs(value) : parseFunnelCreateArgs(value);
+}
+var FUNNEL_REVISION_JSON_SCHEMA = object({ expectedRevision: integer(1) });
+var FUNNEL_RETRY_JSON_SCHEMA = object({ expectedAttempt: integer(0, 100), idempotencyKey: string(200), confirm: literal(true) });
+var FUNNEL_DRAFT_JSON_SCHEMAS = { create: FUNNEL_CREATE_JSON_SCHEMA, update: FUNNEL_UPDATE_JSON_SCHEMA };
+function parseFunnelRevisionArgs(value) {
+  check(value, FUNNEL_REVISION_JSON_SCHEMA, "revision");
+  return JSON.parse(JSON.stringify(value));
+}
+function parseFunnelRetryArgs(value) {
+  check(value, FUNNEL_RETRY_JSON_SCHEMA, "retry");
+  return JSON.parse(JSON.stringify(value));
+}
+var fingerprint = { type: "string", pattern: "^[a-f0-9]{64}$" };
+var issue = object({ code: { ...string(80), pattern: "^[A-Z][A-Z0-9_]*$" }, path: string(300), message: string(500), fixRef: object({ section: string(80), field: string(80), resourceId: uuid }, ["section"]) }, ["code", "path", "message"]);
+var FUNNEL_READINESS_JSON_SCHEMA = object({ definitionRevision: integer(1), brandFingerprint: fingerprint, resourceFingerprint: fingerprint, ready: { type: "boolean" }, blockers: array(issue, 50), warnings: array(issue, 50), capabilities: object({ managedPage: { type: "boolean" } }) });
+function parseFunnelReadiness(value) {
+  check(value, FUNNEL_READINESS_JSON_SCHEMA, "readiness");
+  const result = JSON.parse(JSON.stringify(value));
+  if (result.ready !== (result.blockers.length === 0)) fail("readiness.ready", "must agree with blockers");
+  return result;
+}
+var funnelDetailShape = object({ id: uuid, revision: integer(1), definition: draftDefinitionShape, activeVersionId: nullable(uuid), lifecycle: enumeration("draft", "active", "paused"), health: enumeration("healthy", "waiting", "needs_attention", "unknown"), hasDraftChanges: { type: "boolean" }, readiness: FUNNEL_READINESS_JSON_SCHEMA });
+var FUNNEL_DETAIL_JSON_SCHEMA = funnelDetailShape;
+function parseFunnelDetail(value) {
+  check(value, funnelDetailShape, "funnel");
+  const detail = JSON.parse(JSON.stringify(value));
+  detail.definition = parseFunnelDraftDefinition(detail.definition);
+  detail.readiness = parseFunnelReadiness(detail.readiness);
+  return detail;
+}
+var FUNNEL_OPERATION_RECEIPT_JSON_SCHEMA = object({
+  operationId: uuid,
+  projectId: uuid,
+  orgId: uuid,
+  funnelId: uuid,
+  operation: enumeration("create", "update", "launch", "pause", "resume", "retry", "rollback"),
+  idempotencyKey: string(200),
+  requestDigest: fingerprint,
+  versionId: nullable(uuid),
+  lifecycle: enumeration("draft", "active", "paused"),
+  replayed: { type: "boolean" },
+  armedFutureEntrantsOnly: literal(true),
+  enrolledExisting: literal(0),
+  messagesSent: literal(0),
+  pagePublication: enumeration("not_requested", "published", "revalidation_pending"),
+  health: enumeration("healthy", "waiting", "needs_attention", "unknown"),
+  revision: integer(1),
+  commandState: literal("committed"),
+  funnel: nullable(funnelDetailShape),
+  actor: string(200),
+  armedAt: nullable(isoDate),
+  effectScope: enumeration("configuration_only", "safe_retry_armed"),
+  target: object({ funnelId: nullable(uuid), enrollmentId: nullable(uuid), executionId: nullable(uuid), targetVersionId: nullable(uuid) }),
+  ledgerProposalId: uuid
+});
+function parseFunnelOperationReceipt(value) {
+  check(value, FUNNEL_OPERATION_RECEIPT_JSON_SCHEMA, "receipt");
+  const receipt = JSON.parse(JSON.stringify(value));
+  if (receipt.target.funnelId !== (receipt.operation === "create" ? null : receipt.funnelId)) fail("receipt.target.funnelId", "must match operation scope");
+  for (const key of ["enrollmentId", "executionId"]) if (receipt.target[key] !== null !== (receipt.operation === "retry")) fail(`receipt.target.${key}`, "must match retry scope");
+  if (receipt.target.targetVersionId !== null !== (receipt.operation === "rollback")) fail("receipt.target.targetVersionId", "must match rollback scope");
+  if (receipt.funnel !== null !== ["create", "update"].includes(receipt.operation)) fail("receipt.funnel", "detail belongs only to create and update");
+  if (receipt.funnel) {
+    receipt.funnel = parseFunnelDetail(receipt.funnel);
+    if (receipt.funnel.id !== receipt.funnelId || receipt.funnel.revision !== receipt.revision || receipt.funnel.lifecycle !== receipt.lifecycle) fail("receipt.funnel", "must match receipt identity and revision");
+  }
+  if (!["create", "update"].includes(receipt.operation) && receipt.versionId === null) fail("receipt.versionId", "an active or historical version is required");
+  if (receipt.effectScope !== (receipt.operation === "retry" ? "safe_retry_armed" : "configuration_only")) fail("receipt.effectScope", "must match the operation");
+  return receipt;
+}
+var provenancePaths = ["displayName", "tagline", "fullLogoUrl", "squareLogoUrl", "scheme", ...PUBLICATION_COLOR_FIELDS.map((key) => `colors.${key}`), "typography.headingFamily", "typography.bodyFamily"];
+var brandSnapshotShape = object({
+  page: publicBrand,
+  email: publicBrand,
+  provenance: object(Object.fromEntries(["page", "email"].flatMap((channel) => provenancePaths.map((key) => [`${channel}.${key}`, enumeration("project", "brand_profile", "site_design", "publication_branding", "platforms.publication", "platforms.email", "funnel_override", "default")]))), []),
+  assetRefs: array(object({ id: nullable(uuid), version: nullable(string(128)) }), 32),
+  capturedAt: isoDate,
+  fingerprint
+});
+var FUNNEL_BRAND_SNAPSHOT_JSON_SCHEMA = brandSnapshotShape;
+function parseFunnelBrandSnapshot(value) {
+  check(value, brandSnapshotShape, "brandSnapshot");
+  const result = JSON.parse(JSON.stringify(value));
+  applyFunnelBrandOverride(result.page);
+  applyFunnelBrandOverride(result.email);
+  return result;
+}
+var choicePage = (item) => object({ items: array(item, 100), nextCursor: nullable(string(500)) });
+var choiceFields = { id: uuid, label: string(120) };
+var catalogShape = object({
+  templates: array(object({ id: enumeration(...FUNNEL_TEMPLATES), label: string(120), defaults: draftDefinitionShape }), 3),
+  sites: array(object({ host: site, label: string(200) }), 200),
+  brand: nullable(brandSnapshotShape),
+  choices: object({
+    forms: choicePage(object({ ...choiceFields, slug: string(120), site: nullable(site), formType: enumeration("prospect", "contact", "support", "feedback", "newsletter", "custom"), active: { type: "boolean" }, newsletterListIds: array(uuid, 20), fields: array(object({ slug: fieldSlug, type: string(80), label: string(120), required: { type: "boolean" } }), 100) })),
+    lists: choicePage(object({ ...choiceFields, active: { type: "boolean" }, doubleOptIn: { type: "boolean" } })),
+    emailTemplates: choicePage(object({ ...choiceFields, subject: string(998, 0), updatedAt: nullable(isoDate) })),
+    assets: choicePage(object({ ...choiceFields, label: string(160), mimeType: string(100), sizeBytes: integer(0, 52428800), visibility: literal("public"), publicUrl: string(2048), version: nullable(string(200)) })),
+    owners: choicePage(object({ ...choiceFields, active: literal(true) })),
+    bookingTypes: choicePage(object({ ...choiceFields, site: nullable(site), active: literal(true), requiresConfirmation: { type: "boolean" } }))
+  }, []),
+  capabilities: object({ managedPage: { type: "boolean" } })
+});
+var FUNNEL_CATALOG_JSON_SCHEMA = catalogShape;
+function parseFunnelCatalog(value) {
+  check(value, catalogShape, "catalog");
+  const result = JSON.parse(JSON.stringify(value));
+  for (const template of result.templates) template.defaults = parseFunnelDraftDefinition(template.defaults);
+  if (result.brand) result.brand = parseFunnelBrandSnapshot(result.brand);
+  for (const asset of result.choices.assets?.items ?? []) if (!isSafeFunnelPublicUrl(asset.publicUrl)) fail("catalog.choices.assets", "unsafe public asset URL");
+  return result;
+}
+var launchEvidenceShape = object({ projectId: uuid, orgId: uuid, funnelId: uuid, previewId: uuid, versionId: uuid, definitionRevision: integer(1), definitionDigest: fingerprint, brandFingerprint: fingerprint, resourceFingerprint: fingerprint, entryDigest: fingerprint, permissionDigest: fingerprint, expiresAt: isoDate });
+var FUNNEL_LAUNCH_EVIDENCE_JSON_SCHEMA = launchEvidenceShape;
+function parseFunnelLaunchEvidence(value) {
+  check(value, launchEvidenceShape, "launchEvidence");
+  return JSON.parse(JSON.stringify(value));
+}
+var FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA = object({ orgId: uuid, projectId: uuid, funnelId: uuid, targetVersionId: uuid, definitionRevision: integer(1), definitionDigest: fingerprint, brandFingerprint: fingerprint, resourceFingerprint: fingerprint });
+function parseFunnelRollbackEvidence(value) {
+  check(value, FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA, "rollbackEvidence");
+  return JSON.parse(JSON.stringify(value));
+}
+var FUNNEL_PREVIEW_JSON_SCHEMA = object({
+  previewId: uuid,
+  versionId: uuid,
+  expiresAt: isoDate,
+  definitionRevision: integer(1),
+  brand: brandSnapshotShape,
+  readiness: FUNNEL_READINESS_JSON_SCHEMA,
+  page: nullable(publishedShape),
+  launchEvidence: launchEvidenceShape,
+  emailPreviews: array(object({ stepId: uuid, ready: { type: "boolean" }, subject: nullable(string(998, 0)), contentHtml: nullable(string(2e5, 0)), issues: array(issue, 50) }), 8)
+});
+function parseFunnelPreview(value) {
+  check(value, FUNNEL_PREVIEW_JSON_SCHEMA, "preview");
+  const result = JSON.parse(JSON.stringify(value));
+  result.brand = parseFunnelBrandSnapshot(result.brand);
+  result.readiness = parseFunnelReadiness(result.readiness);
+  if (result.page) {
+    result.page = parsePublishedFunnelPage(result.page);
+    if (result.page.id !== result.launchEvidence.funnelId || result.page.versionId !== result.versionId || result.page.revision !== result.definitionRevision) fail("preview.page", "must match the exact preview version");
+    const pageBrand = result.page.brand;
+    const snapshotBrand = result.brand.page;
+    if (["displayName", "tagline", "fullLogoUrl", "squareLogoUrl", "scheme"].some((key) => pageBrand[key] !== snapshotBrand[key]) || PUBLICATION_COLOR_FIELDS.some((key) => pageBrand.colors[key] !== snapshotBrand.colors[key]) || pageBrand.typography.headingFamily !== snapshotBrand.typography.headingFamily || pageBrand.typography.bodyFamily !== snapshotBrand.typography.bodyFamily) fail("preview.page.brand", "must match the captured brand");
+  }
+  const evidence = result.launchEvidence;
+  if (evidence.previewId !== result.previewId || evidence.versionId !== result.versionId || evidence.definitionRevision !== result.definitionRevision || evidence.brandFingerprint !== result.readiness.brandFingerprint || evidence.resourceFingerprint !== result.readiness.resourceFingerprint || evidence.expiresAt !== result.expiresAt) fail("preview.launchEvidence", "must match the exact preview");
+  if (result.definitionRevision !== result.readiness.definitionRevision) fail("preview.definitionRevision", "must match readiness");
+  if (result.brand.fingerprint !== result.readiness.brandFingerprint) fail("preview.brand", "must match readiness fingerprint");
+  return result;
+}
+var summaryShape = object({
+  id: uuid,
+  name: string(120, 0),
+  template: enumeration(...FUNNEL_TEMPLATES),
+  site: nullable(site),
+  revision: integer(1),
+  activeVersionId: nullable(uuid),
+  lifecycle: enumeration("draft", "active", "paused"),
+  health: enumeration("healthy", "waiting", "needs_attention", "unknown"),
+  hasDraftChanges: { type: "boolean" },
+  counts: object({ entered: integer(0), waiting: integer(0), running: integer(0), completed: integer(0), exited: integer(0), needsAttention: integer(0) }),
+  countsBasis: literal("all_versions_all_time"),
+  lastEventAt: nullable(isoDate)
+});
+var FUNNEL_SUMMARY_JSON_SCHEMA = summaryShape;
+function parseFunnelSummary(value) {
+  check(value, summaryShape, "summary");
+  return JSON.parse(JSON.stringify(value));
+}
+var FUNNEL_ENROLLMENT_JSON_SCHEMA = object({
+  id: uuid,
+  versionId: uuid,
+  state: enumeration("waiting", "running", "completed", "exited", "needs_attention"),
+  effectiveStatus: enumeration("paused", "waiting", "running", "completed", "exited", "needs_attention"),
+  source: object({ submissionId: uuid, acceptedAt: isoDate }),
+  subject: object({ kind: enumeration("subscriber", "contact", "submission"), id: uuid, displayLabel: string(200) }),
+  enteredAt: isoDate,
+  nextRunAt: nullable(isoDate),
+  exitCode: nullable(string(80)),
+  stepsCompleted: integer(0, 8),
+  stepsTotal: integer(0, 8),
+  lastReceiptAt: nullable(isoDate)
+});
+function parseFunnelEnrollmentSummary(value) {
+  check(value, FUNNEL_ENROLLMENT_JSON_SCHEMA, "enrollment");
+  const result = JSON.parse(JSON.stringify(value));
+  if (result.stepsCompleted > result.stepsTotal) fail("enrollment.stepsCompleted", "cannot exceed total");
+  return result;
+}
+var FUNNEL_TIMELINE_JSON_SCHEMA = object({
+  items: array(object({ executionId: uuid, stepId: uuid, type: enumeration("wait", "send_email", "add_tag", "create_task"), state: enumeration("pending", "claimed", "queued", "admitted", "succeeded", "skipped", "uncertain", "failed"), dueAt: nullable(isoDate), occurredAt: nullable(isoDate), attempt: integer(0, 100), reasonCode: nullable(string(80)), message: string(500, 0), receipt: nullable(object({ domain: enumeration("campaign_send", "subscriber_tag", "crm_task", "wait"), id: nullable(uuid), state: string(80) })), canRetry: { type: "boolean" } }), 100),
+  nextCursor: nullable(string(500)),
+  exit: nullable(object({ code: string(80), sourceType: string(80), sourceId: nullable(uuid), occurredAt: isoDate }))
+});
+function parseFunnelTimeline(value) {
+  check(value, FUNNEL_TIMELINE_JSON_SCHEMA, "timeline");
+  return JSON.parse(JSON.stringify(value));
+}
+function freezeSchema(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return;
+  for (const child of Object.values(value)) freezeSchema(child);
+  Object.freeze(value);
+}
+for (const schema of [FUNNEL_DEFINITION_JSON_SCHEMA, FUNNEL_DRAFT_DEFINITION_JSON_SCHEMA, PUBLISHED_FUNNEL_PAGE_JSON_SCHEMA, FUNNEL_LAUNCH_JSON_SCHEMA, FUNNEL_LIFECYCLE_JSON_SCHEMA, FUNNEL_ROLLBACK_JSON_SCHEMA, FUNNEL_CREATE_JSON_SCHEMA, FUNNEL_UPDATE_JSON_SCHEMA, FUNNEL_REVISION_JSON_SCHEMA, FUNNEL_RETRY_JSON_SCHEMA, FUNNEL_DRAFT_JSON_SCHEMAS, FUNNEL_READINESS_JSON_SCHEMA, FUNNEL_DETAIL_JSON_SCHEMA, FUNNEL_OPERATION_RECEIPT_JSON_SCHEMA, FUNNEL_BRAND_SNAPSHOT_JSON_SCHEMA, FUNNEL_CATALOG_JSON_SCHEMA, FUNNEL_PREVIEW_JSON_SCHEMA, FUNNEL_SUMMARY_JSON_SCHEMA, FUNNEL_ENROLLMENT_JSON_SCHEMA, FUNNEL_TIMELINE_JSON_SCHEMA]) freezeSchema(schema);
+var FUNNEL_VERSION_JSON_SCHEMA = object({ versionId: uuid, definitionRevision: integer(1), publishedAt: isoDate, brandFingerprint: fingerprint, resourceFingerprint: fingerprint, active: { type: "boolean" } });
+var FUNNEL_VERSION_DETAIL_JSON_SCHEMA = object({ ...FUNNEL_VERSION_JSON_SCHEMA.properties, rollbackEvidence: FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA });
+function parseFunnelPublishedVersion(value) {
+  check(value, FUNNEL_VERSION_JSON_SCHEMA, "version");
+  return JSON.parse(JSON.stringify(value));
+}
+function parseFunnelPublishedVersionDetail(value) {
+  check(value, FUNNEL_VERSION_DETAIL_JSON_SCHEMA, "versionDetail");
+  const result = JSON.parse(JSON.stringify(value));
+  if (result.versionId !== result.rollbackEvidence.targetVersionId || result.definitionRevision !== result.rollbackEvidence.definitionRevision || result.brandFingerprint !== result.rollbackEvidence.brandFingerprint) fail("versionDetail.rollbackEvidence", "must match the published target");
+  return result;
+}
+for (const schema of [FUNNEL_LAUNCH_EVIDENCE_JSON_SCHEMA, FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA, FUNNEL_VERSION_JSON_SCHEMA, FUNNEL_VERSION_DETAIL_JSON_SCHEMA]) freezeSchema(schema);
+
+export { FUNNEL_BRAND_SNAPSHOT_JSON_SCHEMA, FUNNEL_CATALOG_JSON_SCHEMA, FUNNEL_CREATE_JSON_SCHEMA, FUNNEL_DEFINITION_JSON_SCHEMA, FUNNEL_DETAIL_JSON_SCHEMA, FUNNEL_DRAFT_DEFINITION_JSON_SCHEMA, FUNNEL_DRAFT_JSON_SCHEMAS, FUNNEL_ENROLLMENT_JSON_SCHEMA, FUNNEL_LAUNCH_EVIDENCE_JSON_SCHEMA, FUNNEL_LAUNCH_JSON_SCHEMA, FUNNEL_LIFECYCLE_JSON_SCHEMA, FUNNEL_OPERATION_RECEIPT_JSON_SCHEMA, FUNNEL_PREVIEW_JSON_SCHEMA, FUNNEL_READINESS_JSON_SCHEMA, FUNNEL_RETRY_JSON_SCHEMA, FUNNEL_REVISION_JSON_SCHEMA, FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA, FUNNEL_ROLLBACK_JSON_SCHEMA, FUNNEL_SCHEMA_VERSION, FUNNEL_SUMMARY_JSON_SCHEMA, FUNNEL_TEMPLATES, FUNNEL_TIMELINE_JSON_SCHEMA, FUNNEL_UPDATE_JSON_SCHEMA, FUNNEL_VERSION_DETAIL_JSON_SCHEMA, FUNNEL_VERSION_JSON_SCHEMA, FunnelValidationError, MANAGED_FUNNEL_PATH_PREFIX, PUBLISHED_FUNNEL_PAGE_JSON_SCHEMA, applyFunnelBrandOverride, createFunnelDraft, isSafeFunnelPublicUrl, managedFunnelPath, normalizeCampaignSlug, parseFunnelBrandSnapshot, parseFunnelCatalog, parseFunnelCreateArgs, parseFunnelDefinition, parseFunnelDetail, parseFunnelDraftArgs, parseFunnelDraftDefinition, parseFunnelEnrollmentSummary, parseFunnelLaunchArgs, parseFunnelLaunchEvidence, parseFunnelLifecycleArgs, parseFunnelOperationReceipt, parseFunnelPreview, parseFunnelPublishedVersion, parseFunnelPublishedVersionDetail, parseFunnelReadiness, parseFunnelRetryArgs, parseFunnelRevisionArgs, parseFunnelRollbackEvidence, parseFunnelSummary, parseFunnelTimeline, parseFunnelUpdateArgs, parsePublishedFunnelPage };

package/dist/inbox.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Which inbox cards are decisions. Single source of truth for the rule the
+ * Signal API follows when it writes ("Mark all read" and "Dismiss all" leave a
+ * decision alone) and the dashboard follows when it previews that write.
+ *
+ * A decision is a card still waiting on its person:
+ *   - an approval (insight type `approval_needed`);
+ *   - any card carrying a ledger proposal (`data.proposal_id`), which the Inbox
+ *     turns into Approve / Reject;
+ *   - the ledger's unconfirmed-action card (`ledger_unconfirmed_action`):
+ *     Signal started something it never saw finish and won't run again, so a
+ *     person has to check it. It's raised once per claim, ever, so a bulk
+ *     dismissal that took it would leave nobody told. It isn't an approval: the
+ *     claim was approved already, so it has no `proposal_id` and the Inbox
+ *     offers no Approve / Reject on it.
+ *
+ * The Signal API states the same rule once more as a database filter. It
+ * builds that filter from DECISION_INSIGHT_TYPES, so the list is written here
+ * and nowhere else.
+ */
+/** The insight type of an approval waiting on a yes. */
+export declare const APPROVAL_NEEDED_INSIGHT_TYPE = "approval_needed";
+/**
+ * The insight type of the card a ledger claim nobody can account for raises.
+ * The producer writes it, the delivery policy matches it and the decision rule
+ * below counts it.
+ */
+export declare const LEDGER_UNCONFIRMED_INSIGHT_TYPE = "ledger_unconfirmed_action";
+/** Insight types that are a decision whatever their data. */
+export declare const DECISION_INSIGHT_TYPES: readonly string[];
+/** The card fields the rule reads. A stored row or the dashboard's inbox item both fit. */
+export interface DecisionCardFields {
+    insight_type: string;
+    data?: Record<string, unknown> | null;
+}
+/**
+ * Whether a card is a decision still waiting on its person. `proposal_id` set
+ * is what counts, so it's read the way the database reads `data->>proposal_id`:
+ * a JSON null, a missing key and a null `data` all mean no proposal; any other
+ * value, an empty string included, means one.
+ */
+export declare function isDecisionCard(card: DecisionCardFields): boolean;

package/dist/inbox.js

@@ -0,0 +1,14 @@
+'use strict';
+
+// src/contracts/inbox.ts
+var APPROVAL_NEEDED_INSIGHT_TYPE = "approval_needed";
+var LEDGER_UNCONFIRMED_INSIGHT_TYPE = "ledger_unconfirmed_action";
+var DECISION_INSIGHT_TYPES = [APPROVAL_NEEDED_INSIGHT_TYPE, LEDGER_UNCONFIRMED_INSIGHT_TYPE];
+function isDecisionCard(card) {
+  return DECISION_INSIGHT_TYPES.includes(card.insight_type) || card.data?.proposal_id != null;
+}
+
+exports.APPROVAL_NEEDED_INSIGHT_TYPE = APPROVAL_NEEDED_INSIGHT_TYPE;
+exports.DECISION_INSIGHT_TYPES = DECISION_INSIGHT_TYPES;
+exports.LEDGER_UNCONFIRMED_INSIGHT_TYPE = LEDGER_UNCONFIRMED_INSIGHT_TYPE;
+exports.isDecisionCard = isDecisionCard;

package/dist/inbox.mjs

@@ -0,0 +1,9 @@
+// src/contracts/inbox.ts
+var APPROVAL_NEEDED_INSIGHT_TYPE = "approval_needed";
+var LEDGER_UNCONFIRMED_INSIGHT_TYPE = "ledger_unconfirmed_action";
+var DECISION_INSIGHT_TYPES = [APPROVAL_NEEDED_INSIGHT_TYPE, LEDGER_UNCONFIRMED_INSIGHT_TYPE];
+function isDecisionCard(card) {
+  return DECISION_INSIGHT_TYPES.includes(card.insight_type) || card.data?.proposal_id != null;
+}
+
+export { APPROVAL_NEEDED_INSIGHT_TYPE, DECISION_INSIGHT_TYPES, LEDGER_UNCONFIRMED_INSIGHT_TYPE, isDecisionCard };