@getvitops/utils 3.0.0 → 4.0.0

package/dist/notify/index.mjs

@@ -0,0 +1,320 @@
+import { n as identifyPlatform, t as getPrimaryClickId } from "../platform-CIdwwI_Z.mjs";
+
+//#region src/notify/email.ts
+/**
+* Provider errors worth retrying.
+*
+* Everything else is a configuration fault — an unverified sender, a malformed
+* payload, a suppressed recipient — where a retry is pure latency and the send
+* will fail identically. Retrying those also burns the daily quota.
+*/
+const RETRYABLE = new Set([
+	"E_RATE_LIMIT_EXCEEDED",
+	"E_DELIVERY_FAILED",
+	"E_INTERNAL_SERVER_ERROR"
+]);
+function codeOf(error) {
+	const code = error?.code;
+	return typeof code === "string" ? code : void 0;
+}
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* Send one rendered message according to a plan.
+*
+* Never throws: a failed notification must not take down the request that
+* produced it. The visitor has already submitted their form, and failing their
+* response because our mail didn't go out would turn a lost notification into a
+* lost conversion. The failure is returned instead, for the caller to log.
+*/
+async function sendEmail(plan, message, binding, options = {}) {
+	if (!plan.enabled || !plan.to || !plan.from) return {
+		channel: "email",
+		sent: false,
+		reason: plan.skip ?? "Channel not enabled."
+	};
+	const attempts = Math.max(1, options.attempts ?? 3);
+	const sleep = options.sleep ?? wait;
+	for (let attempt = 1; attempt <= attempts; attempt++) try {
+		await binding.send({
+			to: plan.to,
+			from: plan.fromName ? {
+				email: plan.from,
+				name: plan.fromName
+			} : { email: plan.from },
+			subject: message.subject,
+			text: message.text,
+			html: message.html,
+			...plan.replyTo ? { replyTo: plan.replyTo } : {}
+		});
+		return {
+			channel: "email",
+			sent: true
+		};
+	} catch (error) {
+		const code = codeOf(error);
+		if (attempt === attempts || !code || !RETRYABLE.has(code)) return {
+			channel: "email",
+			sent: false,
+			reason: messageOf(error),
+			...code ? { code } : {}
+		};
+		await sleep(2 ** (attempt - 1) * 250);
+	}
+	/* c8 ignore next -- the loop always returns; this satisfies the type checker. */
+	return {
+		channel: "email",
+		sent: false,
+		reason: "Exhausted attempts."
+	};
+}
+/**
+* Print the message instead of sending it.
+*
+* The dev path, for a machine with no binding. Explicit rather than a silent
+* no-op, because "I never saw the notification" is the symptom of both a broken
+* integration and a working one nobody could observe.
+*/
+function logEmail(plan, message, log = console.log) {
+	log([
+		"\n========== NOTIFICATION EMAIL (not sent — no binding) ==========",
+		`To: ${plan.to ?? "(unresolved)"}`,
+		`From: ${plan.from ?? "(unresolved)"}`,
+		`Subject: ${message.subject}`,
+		"---",
+		message.text,
+		"================================================================\n"
+	].join("\n"));
+	return {
+		channel: "email",
+		sent: false,
+		reason: "No binding — logged to the console."
+	};
+}
+
+//#endregion
+//#region src/notify/plan.ts
+/** Default Workers binding name for Cloudflare Email Sending. */
+const DEFAULT_EMAIL_BINDING = "EMAIL";
+/** Normalise the `email` shorthand: a bare address means a Cloudflare send to it. */
+function normalizeEmailChannel(input) {
+	if (input === void 0) return void 0;
+	return typeof input === "string" ? {
+		provider: "cloudflare",
+		to: input
+	} : input;
+}
+/**
+* Who the notification reaches.
+*
+* An explicit recipient wins; otherwise it falls to the site's own contact
+* addresses, primary first. This cascade is why a site that has already said
+* where it receives mail doesn't have to say it twice.
+*/
+function resolveRecipient(channel, ctx) {
+	if (channel.to) return channel.to;
+	return ctx.locationEmails?.find((e) => !!e);
+}
+/**
+* The From address.
+*
+* `noreply@<canonical>` by default, because the sending domain has to be one the
+* site controls — Cloudflare rejects anything else with `E_SENDER_NOT_VERIFIED`,
+* and guessing from the recipient's domain would send that failure every time.
+*/
+function resolveSender(channel, ctx) {
+	if (channel.from) return channel.from;
+	if (!ctx.canonical) return void 0;
+	let host;
+	try {
+		host = new URL(ctx.canonical).hostname;
+	} catch {
+		host = ctx.canonical.replace(/^https?:\/\//, "").replace(/\/.*$/, "");
+	}
+	return host ? `noreply@${host}` : void 0;
+}
+/**
+* Decide what will be sent, and say why anything won't be.
+*
+* Every "off" carries a reason rather than being an absence, so a caller can
+* report the misconfiguration instead of reporting success over a no-op.
+*/
+function planNotifications(ctx) {
+	const email = planEmail(ctx);
+	return {
+		email,
+		empty: !email.enabled
+	};
+}
+function planEmail(ctx) {
+	const channel = normalizeEmailChannel(ctx.notifications?.email);
+	const binding = channel?.binding ?? "EMAIL";
+	if (!channel) return {
+		provider: "cloudflare",
+		binding,
+		enabled: false,
+		skip: "No `notifications.email` configured."
+	};
+	const to = resolveRecipient(channel, ctx);
+	if (!to) return {
+		provider: "cloudflare",
+		binding,
+		enabled: false,
+		skip: "No recipient: set `notifications.email.to`, or give a location an `email` so the notification has somewhere to go."
+	};
+	const from = resolveSender(channel, ctx);
+	if (!from) return {
+		provider: "cloudflare",
+		binding,
+		to,
+		enabled: false,
+		skip: "No sender: set `notifications.email.from`, or `domains.canonical` so `noreply@<host>` can be derived. Cloudflare only sends from a domain you have onboarded."
+	};
+	return {
+		provider: "cloudflare",
+		binding,
+		to,
+		from,
+		fromName: channel.fromName ?? ctx.organizationName,
+		replyTo: channel.replyTo,
+		enabled: true
+	};
+}
+
+//#endregion
+//#region src/notify/render.ts
+/**
+* Turning a `ConversionEvent` into something a person reads.
+*
+* Pure, and separate from both the plan and the sender, because rendering is the
+* part that differs per channel: an SMS channel will render the same event in 160
+* characters, a portal log as a row. The event stays the fact; only this file has
+* an opinion about prose.
+*
+* The layout is three sections — who got in touch, which ad sent them, and what
+* the request looked like — because that is the order the reader needs them in.
+* The contact details are the point; attribution is why it matters; the visitor
+* context is for when something looks wrong.
+*/
+/**
+* Fields never worth putting in a notification.
+*
+* A honeypot is not visitor-supplied — it is bait, and reporting it as something
+* they submitted is untrue. The same rule `legal/derive.ts` applies when deriving
+* `piiCollected`, and for the same reason. Callers may strip more.
+*/
+const OMIT_FIELDS = new Set([
+	"website",
+	"_honeypot",
+	"honeypot",
+	"cf-turnstile-response"
+]);
+function label(key) {
+	return key.charAt(0).toUpperCase() + key.slice(1).replace(/[_-]/g, " ");
+}
+function escapeHtml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+/**
+* The event as sections — the shared structure behind both renderings.
+*
+* Extracted so the text and HTML versions cannot disagree about content. They
+* differ only in markup; a field added here appears in both.
+*/
+function describeEvent(event) {
+	const t = event.tracking;
+	const platform = t ? identifyPlatform(t) : null;
+	const clickId = t ? getPrimaryClickId(t) : null;
+	const contact = [];
+	let subject;
+	if (event.type === "form" && event.formData) {
+		subject = `[Contact Form] New submission from ${event.formData["name"] ?? "Unknown"}`;
+		for (const [key, value] of Object.entries(event.formData)) if (!OMIT_FIELDS.has(key) && value) contact.push([label(key), value]);
+	} else {
+		const phone = event.phone ?? "unknown";
+		subject = `[Phone Call] Visitor calling ${phone}`;
+		contact.push(["Phone", phone]);
+	}
+	const attribution = [];
+	if (t) {
+		if (platform) attribution.push(["Platform", platform]);
+		if (clickId) attribution.push([`Click ID (${clickId.param})`, clickId.value]);
+		for (const key of [
+			"utm_campaign",
+			"utm_source",
+			"utm_medium",
+			"utm_content",
+			"utm_term"
+		]) {
+			const value = t[key];
+			if (value) attribution.push([label(key.replace("utm_", "")), String(value)]);
+		}
+		if (t.ab_variant) attribution.push(["A/B variant", t.ab_variant]);
+	}
+	const context = [];
+	if (t?.landingPage) context.push(["Landing page", t.landingPage]);
+	if (t?.referrer) context.push(["Referrer", t.referrer]);
+	if (t?.ts) context.push(["First visit", new Date(t.ts).toISOString()]);
+	context.push(["Received", new Date(event.at).toISOString()]);
+	if (event.userAgent) context.push(["User agent", event.userAgent]);
+	if (event.ip) context.push(["IP", event.ip]);
+	const sections = [
+		{
+			heading: "Contact details",
+			lines: contact
+		},
+		{
+			heading: "Ad attribution",
+			lines: attribution.length ? attribution : [["Source", "None — visitor arrived without ad tracking"]]
+		},
+		{
+			heading: "Visitor context",
+			lines: context
+		}
+	];
+	return {
+		subject,
+		sections: sections.filter((s) => s.lines.length)
+	};
+}
+/** Render for e-mail. Both halves, always — see `RenderedMessage`. */
+function renderEmail(event) {
+	const { subject, sections } = describeEvent(event);
+	return {
+		subject,
+		text: sections.map((s) => [`--- ${s.heading} ---`, ...s.lines.map(([k, v]) => `${k}: ${v}`)].join("\n")).join("\n\n"),
+		html: sections.map((s) => `<h2 style="font:600 14px system-ui;margin:24px 0 8px">${escapeHtml(s.heading)}</h2><table style="font:14px system-ui;border-collapse:collapse">${s.lines.map(([k, v]) => `<tr><td style="padding:2px 12px 2px 0;color:#666;vertical-align:top">${escapeHtml(k)}</td><td style="padding:2px 0">${escapeHtml(v)}</td></tr>`).join("")}</table>`).join("")
+	};
+}
+
+//#endregion
+//#region src/notify/index.ts
+/**
+* Notify every configured channel about a conversion.
+*
+* Channels are independent: one failing must not stop the others, and none of
+* them may throw into the request that produced the event. Every outcome —
+* delivered, skipped, failed — comes back as data for the caller to log.
+*/
+async function notify(event, ctx, deps = {}) {
+	const plan = planNotifications(ctx);
+	const results = [];
+	if (plan.email.enabled) {
+		const message = renderEmail(event);
+		results.push(deps.email ? await sendEmail(plan.email, message, deps.email) : logEmail(plan.email, message));
+	} else results.push({
+		channel: "email",
+		sent: false,
+		reason: plan.email.skip ?? "Not configured."
+	});
+	return {
+		results,
+		delivered: results.some((r) => r.sent)
+	};
+}
+
+//#endregion
+export { DEFAULT_EMAIL_BINDING, describeEvent, logEmail, normalizeEmailChannel, notify, planNotifications, renderEmail, resolveRecipient, resolveSender, sendEmail };
+//# sourceMappingURL=index.mjs.map

package/dist/notify/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/notify/email.ts","../../src/notify/plan.ts","../../src/notify/render.ts","../../src/notify/index.ts"],"sourcesContent":["/**\n * The e-mail channel — Cloudflare Email Sending.\n *\n * I/O only: it executes an `EmailPlan` and decides nothing. Whether to send, to\n * whom, and from where were all settled in `plan.ts`.\n *\n * **The binding is passed in, never imported.** `@getvitops/utils` does not depend\n * on `cloudflare:workers`, so this module runs in Node and in a test with a stub,\n * and the Astro package gains no Cloudflare coupling. The consumer's route hands\n * over `env.EMAIL`.\n *\n * Uses the current Email Sending binding — a structured `send({ to, from,\n * subject, html, text })` — not the legacy `EmailMessage` + hand-built MIME path.\n * The domain in `from` must have been onboarded (`wrangler email sending enable\n * <domain>`); nothing here can check that, which is why `E_SENDER_NOT_VERIFIED`\n * is surfaced verbatim rather than collapsed into \"send failed\".\n */\nimport type { RenderedMessage } from './types.ts';\nimport type { ChannelResult, EmailBinding, EmailPlan } from './types.ts';\n\n/**\n * Provider errors worth retrying.\n *\n * Everything else is a configuration fault — an unverified sender, a malformed\n * payload, a suppressed recipient — where a retry is pure latency and the send\n * will fail identically. Retrying those also burns the daily quota.\n */\nconst RETRYABLE = new Set([\n  'E_RATE_LIMIT_EXCEEDED',\n  'E_DELIVERY_FAILED',\n  'E_INTERNAL_SERVER_ERROR',\n]);\n\nfunction codeOf(error: unknown): string | undefined {\n  const code = (error as { code?: unknown } | null)?.code;\n  return typeof code === 'string' ? code : undefined;\n}\n\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nexport interface SendEmailOptions {\n  /** Attempts for a retryable failure (default 3). */\n  attempts?: number;\n  /** Injected for tests; real callers let it default to a real delay. */\n  sleep?: (ms: number) => Promise<void>;\n}\n\nconst wait = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/**\n * Send one rendered message according to a plan.\n *\n * Never throws: a failed notification must not take down the request that\n * produced it. The visitor has already submitted their form, and failing their\n * response because our mail didn't go out would turn a lost notification into a\n * lost conversion. The failure is returned instead, for the caller to log.\n */\nexport async function sendEmail(\n  plan: EmailPlan,\n  message: RenderedMessage,\n  binding: EmailBinding,\n  options: SendEmailOptions = {},\n): Promise<ChannelResult> {\n  if (!plan.enabled || !plan.to || !plan.from) {\n    return { channel: 'email', sent: false, reason: plan.skip ?? 'Channel not enabled.' };\n  }\n\n  const attempts = Math.max(1, options.attempts ?? 3);\n  const sleep = options.sleep ?? wait;\n\n  for (let attempt = 1; attempt <= attempts; attempt++) {\n    try {\n      await binding.send({\n        to: plan.to,\n        from: plan.fromName ? { email: plan.from, name: plan.fromName } : { email: plan.from },\n        subject: message.subject,\n        text: message.text,\n        html: message.html,\n        ...(plan.replyTo ? { replyTo: plan.replyTo } : {}),\n      });\n      return { channel: 'email', sent: true };\n    } catch (error) {\n      const code = codeOf(error);\n      if (attempt === attempts || !code || !RETRYABLE.has(code)) {\n        return {\n          channel: 'email',\n          sent: false,\n          reason: messageOf(error),\n          ...(code ? { code } : {}),\n        };\n      }\n      // Exponential backoff. Cloudflare's rate limit is per-account, so a burst\n      // of conversions retrying in lockstep would keep colliding.\n      await sleep(2 ** (attempt - 1) * 250);\n    }\n  }\n\n  /* c8 ignore next -- the loop always returns; this satisfies the type checker. */\n  return { channel: 'email', sent: false, reason: 'Exhausted attempts.' };\n}\n\n/**\n * Print the message instead of sending it.\n *\n * The dev path, for a machine with no binding. Explicit rather than a silent\n * no-op, because \"I never saw the notification\" is the symptom of both a broken\n * integration and a working one nobody could observe.\n */\nexport function logEmail(\n  plan: EmailPlan,\n  message: RenderedMessage,\n  log: (line: string) => void = console.log,\n): ChannelResult {\n  log(\n    [\n      '\\n========== NOTIFICATION EMAIL (not sent — no binding) ==========',\n      `To: ${plan.to ?? '(unresolved)'}`,\n      `From: ${plan.from ?? '(unresolved)'}`,\n      `Subject: ${message.subject}`,\n      '---',\n      message.text,\n      '================================================================\\n',\n    ].join('\\n'),\n  );\n  return { channel: 'email', sent: false, reason: 'No binding — logged to the console.' };\n}\n","/**\n * Every decision a notification makes, as one pure function.\n *\n * Pure in the load-bearing sense: no `fetch`, no binding, no clock. Whether a\n * channel fires, who it reaches, and *why* it was skipped are all decided here and\n * asserted in `plan.test.ts`; the senders beside this file do what they are told\n * and decide nothing. That is the same split `indexing/plan.ts` makes against\n * `gsc.ts`, and `@getvitops/core`'s consent store makes against its DOM wiring,\n * for the same reason: the consequential logic has to be testable without the\n * environment it runs in.\n *\n * The practical payoff is that a misconfigured site can be told exactly what will\n * and won't happen without sending anything — a silently unsent conversion\n * notification is indistinguishable from no conversion.\n */\nimport type { EmailChannelConfig, EmailPlan, NotificationPlan, NotifyContext } from './types.ts';\n\n/** Default Workers binding name for Cloudflare Email Sending. */\nexport const DEFAULT_EMAIL_BINDING = 'EMAIL';\n\n/** Normalise the `email` shorthand: a bare address means a Cloudflare send to it. */\nexport function normalizeEmailChannel(\n  input: string | EmailChannelConfig | undefined,\n): EmailChannelConfig | undefined {\n  if (input === undefined) return undefined;\n  return typeof input === 'string' ? { provider: 'cloudflare', to: input } : input;\n}\n\n/**\n * Who the notification reaches.\n *\n * An explicit recipient wins; otherwise it falls to the site's own contact\n * addresses, primary first. This cascade is why a site that has already said\n * where it receives mail doesn't have to say it twice.\n */\nexport function resolveRecipient(\n  channel: EmailChannelConfig,\n  ctx: NotifyContext,\n): string | undefined {\n  if (channel.to) return channel.to;\n  return ctx.locationEmails?.find((e) => !!e);\n}\n\n/**\n * The From address.\n *\n * `noreply@<canonical>` by default, because the sending domain has to be one the\n * site controls — Cloudflare rejects anything else with `E_SENDER_NOT_VERIFIED`,\n * and guessing from the recipient's domain would send that failure every time.\n */\nexport function resolveSender(channel: EmailChannelConfig, ctx: NotifyContext): string | undefined {\n  if (channel.from) return channel.from;\n  if (!ctx.canonical) return undefined;\n  let host: string;\n  try {\n    host = new URL(ctx.canonical).hostname;\n  } catch {\n    // A bare hostname is a legitimate way to write `domains.canonical`.\n    host = ctx.canonical.replace(/^https?:\\/\\//, '').replace(/\\/.*$/, '');\n  }\n  return host ? `noreply@${host}` : undefined;\n}\n\n/**\n * Decide what will be sent, and say why anything won't be.\n *\n * Every \"off\" carries a reason rather than being an absence, so a caller can\n * report the misconfiguration instead of reporting success over a no-op.\n */\nexport function planNotifications(ctx: NotifyContext): NotificationPlan {\n  const email = planEmail(ctx);\n  return { email, empty: !email.enabled };\n}\n\nfunction planEmail(ctx: NotifyContext): EmailPlan {\n  const channel = normalizeEmailChannel(ctx.notifications?.email);\n  const binding = channel?.binding ?? DEFAULT_EMAIL_BINDING;\n\n  if (!channel) {\n    return {\n      provider: 'cloudflare',\n      binding,\n      enabled: false,\n      skip: 'No `notifications.email` configured.',\n    };\n  }\n\n  const to = resolveRecipient(channel, ctx);\n  if (!to) {\n    return {\n      provider: 'cloudflare',\n      binding,\n      enabled: false,\n      skip:\n        'No recipient: set `notifications.email.to`, or give a location an `email` ' +\n        'so the notification has somewhere to go.',\n    };\n  }\n\n  const from = resolveSender(channel, ctx);\n  if (!from) {\n    return {\n      provider: 'cloudflare',\n      binding,\n      to,\n      enabled: false,\n      skip:\n        'No sender: set `notifications.email.from`, or `domains.canonical` so ' +\n        '`noreply@<host>` can be derived. Cloudflare only sends from a domain you have onboarded.',\n    };\n  }\n\n  return {\n    provider: 'cloudflare',\n    binding,\n    to,\n    from,\n    fromName: channel.fromName ?? ctx.organizationName,\n    replyTo: channel.replyTo,\n    enabled: true,\n  };\n}\n","/**\n * Turning a `ConversionEvent` into something a person reads.\n *\n * Pure, and separate from both the plan and the sender, because rendering is the\n * part that differs per channel: an SMS channel will render the same event in 160\n * characters, a portal log as a row. The event stays the fact; only this file has\n * an opinion about prose.\n *\n * The layout is three sections — who got in touch, which ad sent them, and what\n * the request looked like — because that is the order the reader needs them in.\n * The contact details are the point; attribution is why it matters; the visitor\n * context is for when something looks wrong.\n */\nimport { getPrimaryClickId, identifyPlatform } from '../tracking/platform.ts';\nimport type { ConversionEvent } from '../tracking/types.ts';\nimport type { RenderedMessage } from './types.ts';\n\n/**\n * Fields never worth putting in a notification.\n *\n * A honeypot is not visitor-supplied — it is bait, and reporting it as something\n * they submitted is untrue. The same rule `legal/derive.ts` applies when deriving\n * `piiCollected`, and for the same reason. Callers may strip more.\n */\nconst OMIT_FIELDS = new Set(['website', '_honeypot', 'honeypot', 'cf-turnstile-response']);\n\nfunction label(key: string): string {\n  return key.charAt(0).toUpperCase() + key.slice(1).replace(/[_-]/g, ' ');\n}\n\nfunction escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\n/** One section: a heading and its lines. Empty sections are dropped by the caller. */\ninterface Section {\n  heading: string;\n  lines: [string, string][];\n}\n\n/**\n * The event as sections — the shared structure behind both renderings.\n *\n * Extracted so the text and HTML versions cannot disagree about content. They\n * differ only in markup; a field added here appears in both.\n */\nexport function describeEvent(event: ConversionEvent): { subject: string; sections: Section[] } {\n  const t = event.tracking;\n  const platform = t ? identifyPlatform(t) : null;\n  const clickId = t ? getPrimaryClickId(t) : null;\n\n  const contact: [string, string][] = [];\n  let subject: string;\n\n  if (event.type === 'form' && event.formData) {\n    const name = event.formData['name'] ?? 'Unknown';\n    subject = `[Contact Form] New submission from ${name}`;\n    for (const [key, value] of Object.entries(event.formData)) {\n      if (!OMIT_FIELDS.has(key) && value) contact.push([label(key), value]);\n    }\n  } else {\n    const phone = event.phone ?? 'unknown';\n    subject = `[Phone Call] Visitor calling ${phone}`;\n    contact.push(['Phone', phone]);\n  }\n\n  const attribution: [string, string][] = [];\n  if (t) {\n    if (platform) attribution.push(['Platform', platform]);\n    if (clickId) attribution.push([`Click ID (${clickId.param})`, clickId.value]);\n    for (const key of ['utm_campaign', 'utm_source', 'utm_medium', 'utm_content', 'utm_term']) {\n      const value = t[key];\n      if (value) attribution.push([label(key.replace('utm_', '')), String(value)]);\n    }\n    if (t.ab_variant) attribution.push(['A/B variant', t.ab_variant]);\n  }\n\n  const context: [string, string][] = [];\n  if (t?.landingPage) context.push(['Landing page', t.landingPage]);\n  if (t?.referrer) context.push(['Referrer', t.referrer]);\n  if (t?.ts) context.push(['First visit', new Date(t.ts).toISOString()]);\n  context.push(['Received', new Date(event.at).toISOString()]);\n  if (event.userAgent) context.push(['User agent', event.userAgent]);\n  if (event.ip) context.push(['IP', event.ip]);\n\n  const sections: Section[] = [\n    { heading: 'Contact details', lines: contact },\n    // Stated rather than omitted: \"we don't know where this came from\" is a\n    // useful answer, and a silently missing section reads as a bug in the tool.\n    {\n      heading: 'Ad attribution',\n      lines: attribution.length\n        ? attribution\n        : [['Source', 'None — visitor arrived without ad tracking']],\n    },\n    { heading: 'Visitor context', lines: context },\n  ];\n\n  return { subject, sections: sections.filter((s) => s.lines.length) };\n}\n\n/** Render for e-mail. Both halves, always — see `RenderedMessage`. */\nexport function renderEmail(event: ConversionEvent): RenderedMessage {\n  const { subject, sections } = describeEvent(event);\n\n  const text = sections\n    .map((s) => [`--- ${s.heading} ---`, ...s.lines.map(([k, v]) => `${k}: ${v}`)].join('\\n'))\n    .join('\\n\\n');\n\n  const html = sections\n    .map(\n      (s) =>\n        `<h2 style=\"font:600 14px system-ui;margin:24px 0 8px\">${escapeHtml(s.heading)}</h2>` +\n        `<table style=\"font:14px system-ui;border-collapse:collapse\">${s.lines\n          .map(\n            ([k, v]) =>\n              `<tr><td style=\"padding:2px 12px 2px 0;color:#666;vertical-align:top\">${escapeHtml(k)}</td>` +\n              `<td style=\"padding:2px 0\">${escapeHtml(v)}</td></tr>`,\n          )\n          .join('')}</table>`,\n    )\n    .join('');\n\n  return { subject, text, html };\n}\n","/**\n * Conversion notifications — plan, render, dispatch.\n *\n * The seam between \"a conversion happened\" and \"someone found out about it\".\n * A `ConversionEvent` from `@getvitops/utils/tracking` goes in; where it goes and\n * how it reads are config, not code at the call site.\n *\n * Three files, three jobs, matching `indexing/`:\n *   - `plan.ts`    decides everything, purely — which channels, which recipients,\n *                  and why anything is off.\n *   - `render.ts`  turns the event into prose, purely.\n *   - `email.ts`   executes, and decides nothing.\n *\n * ---\n *\n * **TODO — further channels.** Only `email` is implemented. The seam is\n * `NotificationsConfig` + a sender with `sendEmail`'s signature `(plan, message,\n * transport) => ChannelResult`; adding one should mean a new sender file, a new\n * branch in `planNotifications`, and a schema variant — touching neither\n * `ConversionEvent` nor the recipient cascade. Planned:\n *   - `sms`      — the same event rendered short. `render.ts` already separates\n *                  `describeEvent` from `renderEmail` for exactly this.\n *   - `persist`  — append to a store (D1, a portal log) the client reviews.\n * The generic `email`/`text`/`persist` helpers taking content + provider config\n * belong at that point, not before: one implemented channel is not enough to know\n * what the abstraction should be.\n */\nimport type { ConversionEvent } from '../tracking/types.ts';\nimport { logEmail, sendEmail } from './email.ts';\nimport { planNotifications } from './plan.ts';\nimport { renderEmail } from './render.ts';\nimport type { ChannelResult, EmailBinding, NotifyContext } from './types.ts';\n\nexport interface NotifyDeps {\n  /**\n   * The Workers `send_email` binding (`env.EMAIL`). Omit it and the notification\n   * is printed instead — the dev path.\n   */\n  email?: EmailBinding | undefined;\n}\n\nexport interface NotifyResult {\n  results: ChannelResult[];\n  /** True when at least one channel delivered. */\n  delivered: boolean;\n}\n\n/**\n * Notify every configured channel about a conversion.\n *\n * Channels are independent: one failing must not stop the others, and none of\n * them may throw into the request that produced the event. Every outcome —\n * delivered, skipped, failed — comes back as data for the caller to log.\n */\nexport async function notify(\n  event: ConversionEvent,\n  ctx: NotifyContext,\n  deps: NotifyDeps = {},\n): Promise<NotifyResult> {\n  const plan = planNotifications(ctx);\n  const results: ChannelResult[] = [];\n\n  if (plan.email.enabled) {\n    const message = renderEmail(event);\n    results.push(\n      deps.email ? await sendEmail(plan.email, message, deps.email) : logEmail(plan.email, message),\n    );\n  } else {\n    results.push({ channel: 'email', sent: false, reason: plan.email.skip ?? 'Not configured.' });\n  }\n\n  return { results, delivered: results.some((r) => r.sent) };\n}\n\nexport {\n  DEFAULT_EMAIL_BINDING,\n  normalizeEmailChannel,\n  planNotifications,\n  resolveRecipient,\n  resolveSender,\n} from './plan.ts';\nexport { describeEvent, renderEmail } from './render.ts';\nexport { logEmail, sendEmail } from './email.ts';\nexport type {\n  ChannelPlan,\n  ChannelResult,\n  EmailBinding,\n  EmailChannelConfig,\n  EmailPlan,\n  NotificationPlan,\n  NotificationsConfig,\n  NotifyContext,\n  RenderedMessage,\n} from './types.ts';\n"],"mappings":"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"}

package/dist/onboarding/index.d.mts

@@ -0,0 +1,231 @@
+import { n as GoogleOAuth } from "../token--18wN9UR.mjs";
+
+//#region src/onboarding/types.d.ts
+/**
+ * The onboarding module's own option surface.
+ *
+ * Deliberately structural rather than `Config['site']['searchConsole']` imported
+ * from `@getvitops/generator`: the generator already depends on this package, so
+ * importing back would be a cycle. The vocabulary mirrors that block field for
+ * field, so the CLI's adapter is a flat map — the same arrangement, and for the
+ * same reason, as `IndexingConfig` beside it.
+ *
+ * Optional fields are written `?: T | undefined` throughout: `exactOptionalPropertyTypes`
+ * is on, and these types describe a *parsed JSON config* where an absent key and an
+ * explicit `undefined` are the same thing.
+ */
+/** One domain to onboard, as the config declares it. */
+interface DomainSetup {
+  /** The domain, bare (`acme.ca`). Becomes the `sc-domain:` property and the DNS zone name. */
+  domain: string;
+  /**
+   * Emails added as verification owners on the Site Verification web resource.
+   * Additive: existing owners are never removed.
+   */
+  delegatedOwners?: string[] | undefined;
+  /**
+   * A Google Group to grant Full-User access in Search Console. Surfaced as a
+   * reminder only — Search Console has no user/permission API.
+   */
+  fullUserGroup?: string | undefined;
+}
+/** Everything `plan()` needs, once the CLI has read the config and creds. */
+interface OnboardingConfig {
+  /** The domains to onboard. Already filtered to `--domain` if that was passed. */
+  domains: DomainSetup[];
+}
+/**
+ * One domain's observed live state, gathered by the executors before planning.
+ *
+ * `plan()` compares this against the desired `DomainSetup` to decide each step —
+ * the same shape the indexing planner takes its sitemap snapshot in, for the same
+ * reason: the decision is pure, the observation is not.
+ */
+interface DomainState {
+  /** The Cloudflare zone id for the domain, if one was found. */
+  zoneId?: string | undefined;
+  /** An apex TXT record already carrying the verification token exists. */
+  txtPresent: boolean;
+  /** The Site Verification web resource reports this domain as verified. */
+  verified: boolean;
+  /** Owners currently on the web resource (empty when not yet verified). */
+  currentOwners: string[];
+  /** A `sc-domain:` property already exists in Search Console. */
+  propertyExists: boolean;
+}
+//#endregion
+//#region src/onboarding/plan.d.ts
+/** A step's decision: do it, or skip it because it already holds. */
+type StepAction = 'create' | 'update' | 'skip';
+interface StepPlan {
+  action: StepAction;
+  /** Why it's a skip, or what the mutation will do. */
+  detail: string;
+}
+/** The four onboarding steps for one domain, decided against its live state. */
+interface DomainPlan {
+  domain: string;
+  /** `sc-domain:` property identifier this domain maps to. */
+  siteUrl: string;
+  /** Ensure the apex TXT verification record. */
+  txt: StepPlan;
+  /** Verify ownership via the Site Verification API (DNS_TXT). */
+  verify: StepPlan;
+  /** Add the Search Console domain property. */
+  property: StepPlan;
+  /** Add delegated owners to the verified web resource. */
+  owners: StepPlan;
+  /** Owners not yet present that the run should add. */
+  ownersToAdd: string[];
+  /** Manual follow-ups (e.g. a Full-User group). */
+  reminders: string[];
+}
+interface OnboardingPlan {
+  domains: DomainPlan[];
+  /** Operator-facing warnings that span the whole run. */
+  notes: string[];
+}
+/** The `sc-domain:` property identifier for a bare domain. */
+declare const siteUrlFor: (domain: string) => string;
+/**
+ * Backoff ladder for the verification retry, in milliseconds.
+ *
+ * DNS_TXT verification fails until the record has propagated, which is a matter of
+ * seconds-to-minutes, not a real error — so the schedule is a *policy*, decided
+ * here and asserted in the tests, while the actual sleeping is the CLI's job.
+ * Capped at `maxAttempts`; a domain still unverified after the last attempt is
+ * reported PENDING, never failed.
+ */
+declare function backoffSchedule(maxAttempts?: number): number[];
+/** Decide the four steps for one domain from its desired config and live state. */
+declare function planDomain(setup: DomainSetup, state: DomainState): DomainPlan;
+/**
+ * The owner set to PUT: everyone already there, plus everyone being added.
+ *
+ * `updateOwners` REPLACES the owner list, so this is the one computation standing
+ * between a delegation and locking yourself out — pass a bare `ownersToAdd` and
+ * the account that just verified the domain is removed from it. It belongs here
+ * rather than at the call site for exactly that reason: it is a decision, it is
+ * the dangerous one, and the executor is not allowed to make it.
+ *
+ * `current` comes FIRST so the API's own casing survives dedupe; matching is
+ * case-insensitive, mirroring `planDomain`'s `present` check, because Google
+ * echoes back addresses in whatever case the account uses and a case-sensitive
+ * `Set` would re-add an owner who is already there.
+ */
+declare function ownerUnion(current: string[], toAdd: string[]): string[];
+/** Plan every domain. */
+declare function plan(config: OnboardingConfig, states: Map<string, DomainState>): OnboardingPlan;
+/** Any step on any domain is a mutation — i.e. the live state has drifted. */
+declare function hasDrift(p: OnboardingPlan): boolean;
+/** Render a plan as the block `--dry` and `--check` print. */
+declare function formatPlan(p: OnboardingPlan): string;
+/** The outcome of one domain's run, for the summary table. */
+interface DomainResult {
+  domain: string;
+  txt: 'created' | 'present' | 'failed' | '—';
+  verified: 'yes' | 'pending' | 'failed' | '—';
+  property: 'added' | 'present' | 'failed' | '—';
+  reminders: string[];
+}
+/** Render the end-of-run summary: one row per domain, plus any reminders. */
+declare function formatSummary(results: DomainResult[]): string;
+//#endregion
+//#region src/onboarding/cloudflare.d.ts
+/** Find the zone id for a domain (`GET /zones?name=`). */
+declare function findZoneId(token: string, domain: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  zoneId?: string;
+  message?: string;
+}>;
+/** List the apex TXT record contents for a zone. */
+declare function listApexTxt(token: string, zoneId: string, domain: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  contents: string[];
+  message?: string;
+}>;
+/**
+ * Create an apex TXT record. **Create only** — never called when one already
+ * exists (the planner decides that), and there is no sibling that edits or removes.
+ */
+declare function createApexTxt(token: string, zoneId: string, domain: string, content: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  message?: string;
+}>;
+//#endregion
+//#region src/onboarding/google.d.ts
+/** Exchange a user OAuth refresh token for a short-lived access token. */
+declare function refreshTokenGrant(oauth: GoogleOAuth, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * Ask the Site Verification API for the DNS_TXT token for a domain.
+ *
+ * Returns the full `google-site-verification=…` value that goes in the apex TXT
+ * record. It is deterministic per (user, domain), so re-fetching it and comparing
+ * against DNS is what makes the TXT step idempotent.
+ */
+declare function getVerificationToken(token: string, domain: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  token?: string;
+  message?: string;
+}>;
+/**
+ * Look up the verified web resource for a domain, if any.
+ *
+ * Uses `webResource.list` rather than a `get` by id, because the id format for an
+ * INET_DOMAIN resource is awkward to construct by hand and the list only ever
+ * contains resources the user already owns — so a hit *is* the verified state, and
+ * carries the id and owners the later steps need.
+ */
+declare function getWebResource(token: string, domain: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  exists: boolean;
+  id?: string;
+  owners: string[];
+  message?: string;
+}>;
+/** Verify ownership (DNS_TXT). Succeeds only once the TXT record has propagated. */
+declare function verifyWebResource(token: string, domain: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  id?: string;
+  owners: string[];
+  message?: string;
+}>;
+/**
+ * Set the owners of a verified web resource to a given list.
+ *
+ * The API replaces the owner set, so the caller passes the **union** of the
+ * current owners and the ones to add — never a bare list of new owners, which
+ * would drop everyone already there.
+ */
+declare function updateOwners(token: string, id: string, domain: string, owners: string[], fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  message?: string;
+}>;
+/** Whether a Search Console property already exists (`GET sites/{siteUrl}`). */
+declare function getSite(token: string, siteUrl: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  exists: boolean;
+  message?: string;
+}>;
+/**
+ * Add a Search Console property (`PUT sites/{siteUrl}`).
+ *
+ * A `403` here almost always means the domain is not yet verified for this user
+ * rather than a transient error — property creation is gated on ownership.
+ */
+declare function addSite(token: string, siteUrl: string, fetchImpl?: typeof fetch): Promise<{
+  ok: boolean;
+  status: number;
+  message?: string;
+}>;
+//#endregion
+export { type DomainPlan, type DomainResult, type DomainSetup, type DomainState, type GoogleOAuth, type OnboardingConfig, type OnboardingPlan, type StepAction, type StepPlan, addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan, planDomain, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource };
+//# sourceMappingURL=index.d.mts.map

package/dist/onboarding/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/onboarding/types.ts","../../src/onboarding/plan.ts","../../src/onboarding/cloudflare.ts","../../src/onboarding/google.ts"],"mappings":"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"}