@getvitops/utils 3.0.0 → 4.1.0

package/dist/onboarding/index.mjs

@@ -0,0 +1,359 @@
+import { n as googleAccessToken } from "../token-BV7tPHh2.mjs";
+import { n as findZoneId, r as listApexTxt, t as createApexTxt } from "../cloudflare-BW-Iyi-B.mjs";
+
+//#region src/onboarding/plan.ts
+/** The `sc-domain:` property identifier for a bare domain. */
+const siteUrlFor = (domain) => `sc-domain:${domain}`;
+/**
+* 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.
+*/
+function backoffSchedule(maxAttempts = 5) {
+	const out = [];
+	for (let i = 1; i <= maxAttempts; i++) out.push(2 ** i * 1e3);
+	return out;
+}
+/** Decide the four steps for one domain from its desired config and live state. */
+function planDomain(setup, state) {
+	const reminders = [];
+	if (setup.fullUserGroup) reminders.push(`add ${setup.fullUserGroup} as a Full User in Search Console — no API exists for this, do it in the UI`);
+	const txt = state.txtPresent ? {
+		action: "skip",
+		detail: "apex TXT already present"
+	} : {
+		action: "create",
+		detail: "create apex TXT verification record"
+	};
+	const verify = state.verified ? {
+		action: "skip",
+		detail: "ownership already verified"
+	} : {
+		action: "create",
+		detail: "verify ownership (DNS_TXT)"
+	};
+	const property = state.propertyExists ? {
+		action: "skip",
+		detail: "property already exists"
+	} : {
+		action: "create",
+		detail: `add property ${siteUrlFor(setup.domain)}`
+	};
+	const desired = setup.delegatedOwners ?? [];
+	const present = new Set(state.currentOwners.map((o) => o.toLowerCase()));
+	const ownersToAdd = desired.filter((o) => !present.has(o.toLowerCase()));
+	const owners = desired.length === 0 ? {
+		action: "skip",
+		detail: "no delegated owners"
+	} : ownersToAdd.length === 0 ? {
+		action: "skip",
+		detail: "all delegated owners already present"
+	} : {
+		action: "update",
+		detail: `add ${ownersToAdd.length} owner(s): ${ownersToAdd.join(", ")}`
+	};
+	return {
+		domain: setup.domain,
+		siteUrl: siteUrlFor(setup.domain),
+		txt,
+		verify,
+		property,
+		owners,
+		ownersToAdd,
+		reminders
+	};
+}
+/**
+* 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.
+*/
+function ownerUnion(current, toAdd) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const o of [...current, ...toAdd]) {
+		const key = o.toLowerCase();
+		if (seen.has(key)) continue;
+		seen.add(key);
+		out.push(o);
+	}
+	return out;
+}
+/** Plan every domain. */
+function plan(config, states) {
+	const notes = [];
+	return {
+		domains: config.domains.map((setup) => {
+			const state = states.get(setup.domain);
+			if (!state) notes.push(`${setup.domain}: no observed state; treating everything as pending`);
+			return planDomain(setup, state ?? {
+				txtPresent: false,
+				verified: false,
+				currentOwners: [],
+				propertyExists: false
+			});
+		}),
+		notes
+	};
+}
+/** Any step on any domain is a mutation — i.e. the live state has drifted. */
+function hasDrift(p) {
+	return p.domains.some((d) => d.txt.action !== "skip" || d.verify.action !== "skip" || d.property.action !== "skip" || d.owners.action !== "skip");
+}
+/** Render a plan as the block `--dry` and `--check` print. */
+function formatPlan(p) {
+	const lines = [];
+	const glyph = (s) => s.action === "skip" ? "·" : "+";
+	for (const d of p.domains) {
+		lines.push(d.domain);
+		lines.push(`  ${glyph(d.txt)} TXT       ${d.txt.detail}`);
+		lines.push(`  ${glyph(d.verify)} verify    ${d.verify.detail}`);
+		lines.push(`  ${glyph(d.property)} property  ${d.property.detail}`);
+		lines.push(`  ${glyph(d.owners)} owners    ${d.owners.detail}`);
+		for (const r of d.reminders) lines.push(`  ! ${r}`);
+	}
+	for (const n of p.notes) lines.push(`! ${n}`);
+	return lines.join("\n");
+}
+const pad = (s, n) => s.padEnd(n);
+/** Render the end-of-run summary: one row per domain, plus any reminders. */
+function formatSummary(results) {
+	const headers = [
+		"DOMAIN",
+		"TXT",
+		"VERIFIED",
+		"PROPERTY"
+	];
+	const rows = results.map((r) => [
+		r.domain,
+		r.txt,
+		r.verified,
+		r.property
+	]);
+	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i]?.length ?? 0)));
+	const line = (cells) => cells.map((c, i) => pad(c, widths[i] ?? 0)).join("  ").trimEnd();
+	const out = [line(headers), widths.map((w) => "─".repeat(w)).join("  ")];
+	for (const row of rows) out.push(line(row));
+	const reminders = results.flatMap((r) => r.reminders.map((m) => `  ! ${r.domain}: ${m}`));
+	if (reminders.length) out.push("", "Reminders (manual — no API):", ...reminders);
+	return out.join("\n");
+}
+
+//#endregion
+//#region src/onboarding/google.ts
+/**
+* Google — the two APIs onboarding drives, and the user-OAuth token behind both.
+*
+* Auth here is a **user OAuth refresh token**, not a service account: verifying a
+* site and adding a Search Console property act *as a person* who can own them, not
+* as a project robot. That makes the token exchange simpler than the indexing
+* module's — a `refresh_token` grant, no JWT and no `node:crypto` — but it needs
+* broader scope, granted when the refresh token is minted:
+*   - `https://www.googleapis.com/auth/siteverification`  (Site Verification API)
+*   - `https://www.googleapis.com/auth/webmasters`        (Search Console API)
+*
+* The exchange itself lives in `../google/token.ts`, shared with `indexing/gsc.ts`
+* — the grants differ, everything after building the form body did not. It throws
+* (nothing downstream can run without a token) while every API call below returns
+* a structured result and lets the caller decide per domain. `googleapis` is
+* deliberately not a dependency — these are a handful of REST endpoints in a CLI
+* that installs into every consumer.
+*/
+const SITEVERIFICATION = "https://www.googleapis.com/siteVerification/v1";
+const WEBMASTERS = "https://www.googleapis.com/webmasters/v3";
+/** Exchange a user OAuth refresh token for a short-lived access token. */
+function refreshTokenGrant(oauth, fetchImpl = fetch) {
+	return googleAccessToken({
+		kind: "oauth",
+		oauth
+	}, fetchImpl);
+}
+const inetSite = (domain) => ({
+	type: "INET_DOMAIN",
+	identifier: domain
+});
+/**
+* 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.
+*/
+async function getVerificationToken(token, domain, fetchImpl = fetch) {
+	const res = await fetchImpl(`${SITEVERIFICATION}/token`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			verificationMethod: "DNS_TXT",
+			site: inetSite(domain)
+		})
+	});
+	if (!res.ok) return {
+		ok: false,
+		status: res.status,
+		message: await res.text()
+	};
+	const body = await res.json();
+	if (!body.token) return {
+		ok: false,
+		status: res.status,
+		message: "no token in response"
+	};
+	return {
+		ok: true,
+		status: res.status,
+		token: body.token
+	};
+}
+/**
+* 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.
+*/
+async function getWebResource(token, domain, fetchImpl = fetch) {
+	const res = await fetchImpl(`${SITEVERIFICATION}/webResource`, { headers: { authorization: `Bearer ${token}` } });
+	if (!res.ok) return {
+		ok: false,
+		status: res.status,
+		exists: false,
+		owners: [],
+		message: await res.text()
+	};
+	const match = (await res.json()).items?.find((it) => it.site?.type === "INET_DOMAIN" && it.site?.identifier === domain);
+	if (!match) return {
+		ok: true,
+		status: res.status,
+		exists: false,
+		owners: []
+	};
+	return {
+		ok: true,
+		status: res.status,
+		exists: true,
+		...match.id ? { id: match.id } : {},
+		owners: match.owners ?? []
+	};
+}
+/** Verify ownership (DNS_TXT). Succeeds only once the TXT record has propagated. */
+async function verifyWebResource(token, domain, fetchImpl = fetch) {
+	const res = await fetchImpl(`${SITEVERIFICATION}/webResource?verificationMethod=DNS_TXT`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			site: inetSite(domain),
+			verificationMethod: "DNS_TXT"
+		})
+	});
+	if (!res.ok) return {
+		ok: false,
+		status: res.status,
+		owners: [],
+		message: await res.text()
+	};
+	const body = await res.json();
+	return {
+		ok: true,
+		status: res.status,
+		...body.id ? { id: body.id } : {},
+		owners: body.owners ?? []
+	};
+}
+/**
+* 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.
+*/
+async function updateOwners(token, id, domain, owners, fetchImpl = fetch) {
+	const res = await fetchImpl(`${SITEVERIFICATION}/webResource/${encodeURIComponent(id)}`, {
+		method: "PUT",
+		headers: {
+			authorization: `Bearer ${token}`,
+			"content-type": "application/json"
+		},
+		body: JSON.stringify({
+			id,
+			site: inetSite(domain),
+			owners
+		})
+	});
+	if (!res.ok) return {
+		ok: false,
+		status: res.status,
+		message: await res.text()
+	};
+	return {
+		ok: true,
+		status: res.status
+	};
+}
+const encodeSite = (siteUrl) => encodeURIComponent(siteUrl);
+/** Whether a Search Console property already exists (`GET sites/{siteUrl}`). */
+async function getSite(token, siteUrl, fetchImpl = fetch) {
+	const res = await fetchImpl(`${WEBMASTERS}/sites/${encodeSite(siteUrl)}`, { headers: { authorization: `Bearer ${token}` } });
+	if (res.ok) return {
+		ok: true,
+		status: res.status,
+		exists: true
+	};
+	if (res.status === 404) return {
+		ok: true,
+		status: res.status,
+		exists: false
+	};
+	return {
+		ok: false,
+		status: res.status,
+		exists: false,
+		message: await res.text()
+	};
+}
+/**
+* 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.
+*/
+async function addSite(token, siteUrl, fetchImpl = fetch) {
+	const res = await fetchImpl(`${WEBMASTERS}/sites/${encodeSite(siteUrl)}`, {
+		method: "PUT",
+		headers: { authorization: `Bearer ${token}` }
+	});
+	if (res.ok) return {
+		ok: true,
+		status: res.status
+	};
+	const detail = res.status === 403 ? `403 — "${siteUrl}" is not verified for this account yet, or the OAuth token lacks the webmasters scope` : `${res.status}: ${await res.text()}`;
+	return {
+		ok: false,
+		status: res.status,
+		message: detail
+	};
+}
+
+//#endregion
+export { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan, planDomain, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource };
+//# sourceMappingURL=index.mjs.map

package/dist/onboarding/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/onboarding/plan.ts","../../src/onboarding/google.ts"],"sourcesContent":["/**\n * Every decision `vitops search setup` makes, as one pure function.\n *\n * Pure in the load-bearing sense: no `fetch`, no `fs`, no clock. The executors\n * beside this one gather each domain's live state and apply what they are told;\n * this module decides, from that state, what is left to do. That split is what\n * makes `--dry` a complete account of a run and `--check` an honest drift report —\n * the same arrangement the indexing planner makes against `gsc.ts`/`indexnow.ts`.\n *\n * Idempotency lives here too: a step whose desired state already holds resolves to\n * `skip`, so a re-run of a fully-onboarded domain is all skips — a no-op, by\n * construction rather than by the executors checking twice.\n */\nimport type { DomainSetup, DomainState, OnboardingConfig } from './types.ts';\n\n/** A step's decision: do it, or skip it because it already holds. */\nexport type StepAction = 'create' | 'update' | 'skip';\n\nexport interface StepPlan {\n  action: StepAction;\n  /** Why it's a skip, or what the mutation will do. */\n  detail: string;\n}\n\n/** The four onboarding steps for one domain, decided against its live state. */\nexport interface DomainPlan {\n  domain: string;\n  /** `sc-domain:` property identifier this domain maps to. */\n  siteUrl: string;\n  /** Ensure the apex TXT verification record. */\n  txt: StepPlan;\n  /** Verify ownership via the Site Verification API (DNS_TXT). */\n  verify: StepPlan;\n  /** Add the Search Console domain property. */\n  property: StepPlan;\n  /** Add delegated owners to the verified web resource. */\n  owners: StepPlan;\n  /** Owners not yet present that the run should add. */\n  ownersToAdd: string[];\n  /** Manual follow-ups (e.g. a Full-User group). */\n  reminders: string[];\n}\n\nexport interface OnboardingPlan {\n  domains: DomainPlan[];\n  /** Operator-facing warnings that span the whole run. */\n  notes: string[];\n}\n\n/** The `sc-domain:` property identifier for a bare domain. */\nexport const siteUrlFor = (domain: string): string => `sc-domain:${domain}`;\n\n/**\n * Backoff ladder for the verification retry, in milliseconds.\n *\n * DNS_TXT verification fails until the record has propagated, which is a matter of\n * seconds-to-minutes, not a real error — so the schedule is a *policy*, decided\n * here and asserted in the tests, while the actual sleeping is the CLI's job.\n * Capped at `maxAttempts`; a domain still unverified after the last attempt is\n * reported PENDING, never failed.\n */\nexport function backoffSchedule(maxAttempts = 5): number[] {\n  const out: number[] = [];\n  for (let i = 1; i <= maxAttempts; i++) out.push(2 ** i * 1000);\n  return out;\n}\n\n/** Decide the four steps for one domain from its desired config and live state. */\nexport function planDomain(setup: DomainSetup, state: DomainState): DomainPlan {\n  const reminders: string[] = [];\n  if (setup.fullUserGroup)\n    reminders.push(\n      `add ${setup.fullUserGroup} as a Full User in Search Console — no API exists for this, do it in the UI`,\n    );\n\n  const txt: StepPlan = state.txtPresent\n    ? { action: 'skip', detail: 'apex TXT already present' }\n    : { action: 'create', detail: 'create apex TXT verification record' };\n\n  const verify: StepPlan = state.verified\n    ? { action: 'skip', detail: 'ownership already verified' }\n    : { action: 'create', detail: 'verify ownership (DNS_TXT)' };\n\n  const property: StepPlan = state.propertyExists\n    ? { action: 'skip', detail: 'property already exists' }\n    : { action: 'create', detail: `add property ${siteUrlFor(setup.domain)}` };\n\n  // Owners can only be read once verified; before that, treat every delegated\n  // owner as still-to-add so --check reports the drift rather than hiding it.\n  const desired = setup.delegatedOwners ?? [];\n  const present = new Set(state.currentOwners.map((o) => o.toLowerCase()));\n  const ownersToAdd = desired.filter((o) => !present.has(o.toLowerCase()));\n  const owners: StepPlan =\n    desired.length === 0\n      ? { action: 'skip', detail: 'no delegated owners' }\n      : ownersToAdd.length === 0\n        ? { action: 'skip', detail: 'all delegated owners already present' }\n        : {\n            action: 'update',\n            detail: `add ${ownersToAdd.length} owner(s): ${ownersToAdd.join(', ')}`,\n          };\n\n  return {\n    domain: setup.domain,\n    siteUrl: siteUrlFor(setup.domain),\n    txt,\n    verify,\n    property,\n    owners,\n    ownersToAdd,\n    reminders,\n  };\n}\n\n/**\n * The owner set to PUT: everyone already there, plus everyone being added.\n *\n * `updateOwners` REPLACES the owner list, so this is the one computation standing\n * between a delegation and locking yourself out — pass a bare `ownersToAdd` and\n * the account that just verified the domain is removed from it. It belongs here\n * rather than at the call site for exactly that reason: it is a decision, it is\n * the dangerous one, and the executor is not allowed to make it.\n *\n * `current` comes FIRST so the API's own casing survives dedupe; matching is\n * case-insensitive, mirroring `planDomain`'s `present` check, because Google\n * echoes back addresses in whatever case the account uses and a case-sensitive\n * `Set` would re-add an owner who is already there.\n */\nexport function ownerUnion(current: string[], toAdd: string[]): string[] {\n  const out: string[] = [];\n  const seen = new Set<string>();\n  for (const o of [...current, ...toAdd]) {\n    const key = o.toLowerCase();\n    if (seen.has(key)) continue;\n    seen.add(key);\n    out.push(o);\n  }\n  return out;\n}\n\n/** Plan every domain. */\nexport function plan(config: OnboardingConfig, states: Map<string, DomainState>): OnboardingPlan {\n  const notes: string[] = [];\n  const domains = config.domains.map((setup) => {\n    const state = states.get(setup.domain);\n    if (!state)\n      // Should not happen — the CLI observes every domain before planning — but a\n      // missing observation must not silently read as \"nothing to do\".\n      notes.push(`${setup.domain}: no observed state; treating everything as pending`);\n    return planDomain(\n      setup,\n      state ?? { txtPresent: false, verified: false, currentOwners: [], propertyExists: false },\n    );\n  });\n  return { domains, notes };\n}\n\n/** Any step on any domain is a mutation — i.e. the live state has drifted. */\nexport function hasDrift(p: OnboardingPlan): boolean {\n  return p.domains.some(\n    (d) =>\n      d.txt.action !== 'skip' ||\n      d.verify.action !== 'skip' ||\n      d.property.action !== 'skip' ||\n      d.owners.action !== 'skip',\n  );\n}\n\n/** Render a plan as the block `--dry` and `--check` print. */\nexport function formatPlan(p: OnboardingPlan): string {\n  const lines: string[] = [];\n  const glyph = (s: StepPlan) => (s.action === 'skip' ? '·' : '+');\n  for (const d of p.domains) {\n    lines.push(d.domain);\n    lines.push(`  ${glyph(d.txt)} TXT       ${d.txt.detail}`);\n    lines.push(`  ${glyph(d.verify)} verify    ${d.verify.detail}`);\n    lines.push(`  ${glyph(d.property)} property  ${d.property.detail}`);\n    lines.push(`  ${glyph(d.owners)} owners    ${d.owners.detail}`);\n    for (const r of d.reminders) lines.push(`  ! ${r}`);\n  }\n  for (const n of p.notes) lines.push(`! ${n}`);\n  return lines.join('\\n');\n}\n\n/** The outcome of one domain's run, for the summary table. */\nexport interface DomainResult {\n  domain: string;\n  txt: 'created' | 'present' | 'failed' | '—';\n  verified: 'yes' | 'pending' | 'failed' | '—';\n  property: 'added' | 'present' | 'failed' | '—';\n  reminders: string[];\n}\n\nconst pad = (s: string, n: number) => s.padEnd(n);\n\n/** Render the end-of-run summary: one row per domain, plus any reminders. */\nexport function formatSummary(results: DomainResult[]): string {\n  const headers = ['DOMAIN', 'TXT', 'VERIFIED', 'PROPERTY'];\n  const rows = results.map((r) => [r.domain, r.txt, r.verified, r.property]);\n  const widths = headers.map((h, i) =>\n    Math.max(h.length, ...rows.map((row) => row[i]?.length ?? 0)),\n  );\n  const line = (cells: string[]) =>\n    cells\n      .map((c, i) => pad(c, widths[i] ?? 0))\n      .join('  ')\n      .trimEnd();\n\n  const out = [line(headers), widths.map((w) => '─'.repeat(w)).join('  ')];\n  for (const row of rows) out.push(line(row));\n\n  const reminders = results.flatMap((r) => r.reminders.map((m) => `  ! ${r.domain}: ${m}`));\n  if (reminders.length) {\n    out.push('', 'Reminders (manual — no API):', ...reminders);\n  }\n  return out.join('\\n');\n}\n","/**\n * Google — the two APIs onboarding drives, and the user-OAuth token behind both.\n *\n * Auth here is a **user OAuth refresh token**, not a service account: verifying a\n * site and adding a Search Console property act *as a person* who can own them, not\n * as a project robot. That makes the token exchange simpler than the indexing\n * module's — a `refresh_token` grant, no JWT and no `node:crypto` — but it needs\n * broader scope, granted when the refresh token is minted:\n *   - `https://www.googleapis.com/auth/siteverification`  (Site Verification API)\n *   - `https://www.googleapis.com/auth/webmasters`        (Search Console API)\n *\n * The exchange itself lives in `../google/token.ts`, shared with `indexing/gsc.ts`\n * — the grants differ, everything after building the form body did not. It throws\n * (nothing downstream can run without a token) while every API call below returns\n * a structured result and lets the caller decide per domain. `googleapis` is\n * deliberately not a dependency — these are a handful of REST endpoints in a CLI\n * that installs into every consumer.\n */\nimport { googleAccessToken, type GoogleOAuth } from '../google/token.ts';\n\nconst SITEVERIFICATION = 'https://www.googleapis.com/siteVerification/v1';\nconst WEBMASTERS = 'https://www.googleapis.com/webmasters/v3';\n\n/** Exchange a user OAuth refresh token for a short-lived access token. */\nexport function refreshTokenGrant(\n  oauth: GoogleOAuth,\n  fetchImpl: typeof fetch = fetch,\n): Promise<string> {\n  return googleAccessToken({ kind: 'oauth', oauth }, fetchImpl);\n}\n\nconst inetSite = (domain: string) => ({ type: 'INET_DOMAIN', identifier: domain });\n\n/**\n * Ask the Site Verification API for the DNS_TXT token for a domain.\n *\n * Returns the full `google-site-verification=…` value that goes in the apex TXT\n * record. It is deterministic per (user, domain), so re-fetching it and comparing\n * against DNS is what makes the TXT step idempotent.\n */\nexport async function getVerificationToken(\n  token: string,\n  domain: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; status: number; token?: string; message?: string }> {\n  const res = await fetchImpl(`${SITEVERIFICATION}/token`, {\n    method: 'POST',\n    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },\n    body: JSON.stringify({ verificationMethod: 'DNS_TXT', site: inetSite(domain) }),\n  });\n  if (!res.ok) return { ok: false, status: res.status, message: await res.text() };\n  const body = (await res.json()) as { token?: string };\n  if (!body.token) return { ok: false, status: res.status, message: 'no token in response' };\n  return { ok: true, status: res.status, token: body.token };\n}\n\n/**\n * Look up the verified web resource for a domain, if any.\n *\n * Uses `webResource.list` rather than a `get` by id, because the id format for an\n * INET_DOMAIN resource is awkward to construct by hand and the list only ever\n * contains resources the user already owns — so a hit *is* the verified state, and\n * carries the id and owners the later steps need.\n */\nexport async function getWebResource(\n  token: string,\n  domain: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{\n  ok: boolean;\n  status: number;\n  exists: boolean;\n  id?: string;\n  owners: string[];\n  message?: string;\n}> {\n  const res = await fetchImpl(`${SITEVERIFICATION}/webResource`, {\n    headers: { authorization: `Bearer ${token}` },\n  });\n  if (!res.ok)\n    return { ok: false, status: res.status, exists: false, owners: [], message: await res.text() };\n  const body = (await res.json()) as {\n    items?: { id?: string; site?: { type?: string; identifier?: string }; owners?: string[] }[];\n  };\n  const match = body.items?.find(\n    (it) => it.site?.type === 'INET_DOMAIN' && it.site?.identifier === domain,\n  );\n  if (!match) return { ok: true, status: res.status, exists: false, owners: [] };\n  return {\n    ok: true,\n    status: res.status,\n    exists: true,\n    ...(match.id ? { id: match.id } : {}),\n    owners: match.owners ?? [],\n  };\n}\n\n/** Verify ownership (DNS_TXT). Succeeds only once the TXT record has propagated. */\nexport async function verifyWebResource(\n  token: string,\n  domain: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; status: number; id?: string; owners: string[]; message?: string }> {\n  const res = await fetchImpl(`${SITEVERIFICATION}/webResource?verificationMethod=DNS_TXT`, {\n    method: 'POST',\n    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },\n    body: JSON.stringify({ site: inetSite(domain), verificationMethod: 'DNS_TXT' }),\n  });\n  if (!res.ok) return { ok: false, status: res.status, owners: [], message: await res.text() };\n  const body = (await res.json()) as { id?: string; owners?: string[] };\n  return {\n    ok: true,\n    status: res.status,\n    ...(body.id ? { id: body.id } : {}),\n    owners: body.owners ?? [],\n  };\n}\n\n/**\n * Set the owners of a verified web resource to a given list.\n *\n * The API replaces the owner set, so the caller passes the **union** of the\n * current owners and the ones to add — never a bare list of new owners, which\n * would drop everyone already there.\n */\nexport async function updateOwners(\n  token: string,\n  id: string,\n  domain: string,\n  owners: string[],\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; status: number; message?: string }> {\n  const res = await fetchImpl(`${SITEVERIFICATION}/webResource/${encodeURIComponent(id)}`, {\n    method: 'PUT',\n    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },\n    body: JSON.stringify({ id, site: inetSite(domain), owners }),\n  });\n  if (!res.ok) return { ok: false, status: res.status, message: await res.text() };\n  return { ok: true, status: res.status };\n}\n\nconst encodeSite = (siteUrl: string) => encodeURIComponent(siteUrl);\n\n/** Whether a Search Console property already exists (`GET sites/{siteUrl}`). */\nexport async function getSite(\n  token: string,\n  siteUrl: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; status: number; exists: boolean; message?: string }> {\n  const res = await fetchImpl(`${WEBMASTERS}/sites/${encodeSite(siteUrl)}`, {\n    headers: { authorization: `Bearer ${token}` },\n  });\n  if (res.ok) return { ok: true, status: res.status, exists: true };\n  if (res.status === 404) return { ok: true, status: res.status, exists: false };\n  return { ok: false, status: res.status, exists: false, message: await res.text() };\n}\n\n/**\n * Add a Search Console property (`PUT sites/{siteUrl}`).\n *\n * A `403` here almost always means the domain is not yet verified for this user\n * rather than a transient error — property creation is gated on ownership.\n */\nexport async function addSite(\n  token: string,\n  siteUrl: string,\n  fetchImpl: typeof fetch = fetch,\n): Promise<{ ok: boolean; status: number; message?: string }> {\n  const res = await fetchImpl(`${WEBMASTERS}/sites/${encodeSite(siteUrl)}`, {\n    method: 'PUT',\n    headers: { authorization: `Bearer ${token}` },\n  });\n  if (res.ok) return { ok: true, status: res.status };\n  const detail =\n    res.status === 403\n      ? `403 — \"${siteUrl}\" is not verified for this account yet, or the OAuth token lacks the webmasters scope`\n      : `${res.status}: ${await res.text()}`;\n  return { ok: false, status: res.status, message: detail };\n}\n"],"mappings":"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"}

package/dist/platform-0nlOIy8h.mjs

@@ -0,0 +1,96 @@
+//#region src/tracking/params.ts
+/**
+* The ad-platform vocabulary — the one place that says which URL parameters mean
+* "this visit came from an ad", and which platform each belongs to.
+*
+* Single source of truth on purpose: the capture script reads it to know what to
+* pull off the URL, and the notification renderer reads it to name the platform.
+* Two lists would drift into a cookie holding a click ID nothing can attribute.
+*/
+/**
+* Click-ID parameters, in identification precedence.
+*
+* Order matters: `identifyPlatform` and `getPrimaryClickId` return the first
+* match, and a URL can legitimately carry more than one (a Google Ads link
+* retargeted through Meta arrives with both `gclid` and `fbclid`). Google first
+* because its click IDs are the ones that survive redirects intact.
+*
+* This table must cover every `clickIdParams` entry in `ads/providers.ts`, and
+* `ads/providers.test.ts` asserts it does. A configured ad property whose click ID
+* is not captured here means every conversion from that platform arrives
+* unattributed — silently, since an unattributed conversion looks exactly like an
+* organic one. `li_fat_id` and `epik` were missing for precisely that reason.
+*/
+const PLATFORM_PARAMS = {
+	gclid: "Google Ads",
+	gbraid: "Google Ads",
+	wbraid: "Google Ads",
+	fbclid: "Meta",
+	ttclid: "TikTok",
+	rdt_cid: "Reddit",
+	ScCid: "Snapchat",
+	msclkid: "Microsoft Ads",
+	li_fat_id: "LinkedIn",
+	epik: "Pinterest"
+};
+/** Just the parameter names, in the same precedence order. */
+const CLICK_ID_PARAMS = Object.keys(PLATFORM_PARAMS);
+const UTM_PARAMS = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_content",
+	"utm_term"
+];
+/** Everything the capture script pulls off the landing URL. */
+const TRACKED_PARAMS = [...CLICK_ID_PARAMS, ...UTM_PARAMS];
+/**
+* The attribution cookie.
+*
+* First-party and same-site: it is read by this site's own conversion handler and
+* never sent anywhere. It is still a persistent identifier, which is why writing
+* it waits on consent.
+*/
+const TRACKING_COOKIE = "_ac";
+/** 90 days — an ad click and the conversion it produces are rarely further apart. */
+const TRACKING_COOKIE_DAYS = 90;
+/** The A/B variant cookie, assigned by the router when a site runs experiments. */
+const AB_COOKIE = "_ab";
+
+//#endregion
+//#region src/tracking/platform.ts
+/**
+* Naming the source of a visit.
+*
+* Both functions return the **first** match in `PLATFORM_PARAMS` order rather
+* than collecting every one, because a notification needs an answer, not a list.
+* A URL carrying two click IDs is a real case — a Google Ads link retargeted
+* through Meta — and the precedence in the table is the tiebreak.
+*/
+/**
+* Which platform sent this visitor.
+*
+* Falls back to `utm_source` when no click ID is present: a UTM-tagged link from
+* a newsletter or a partner site is still attribution, just self-declared rather
+* than platform-issued. Returns null when there is nothing to go on.
+*/
+function identifyPlatform(data) {
+	for (const param of CLICK_ID_PARAMS) if (data[param]) return PLATFORM_PARAMS[param] ?? null;
+	const source = data["utm_source"];
+	return typeof source === "string" && source ? source : null;
+}
+/** The click ID to quote, with the parameter it came from. */
+function getPrimaryClickId(data) {
+	for (const param of CLICK_ID_PARAMS) {
+		const value = data[param];
+		if (value) return {
+			param,
+			value: String(value)
+		};
+	}
+	return null;
+}
+
+//#endregion
+export { PLATFORM_PARAMS as a, TRACKING_COOKIE_DAYS as c, CLICK_ID_PARAMS as i, UTM_PARAMS as l, identifyPlatform as n, TRACKED_PARAMS as o, AB_COOKIE as r, TRACKING_COOKIE as s, getPrimaryClickId as t };
+//# sourceMappingURL=platform-0nlOIy8h.mjs.map

package/dist/platform-0nlOIy8h.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-0nlOIy8h.mjs","names":[],"sources":["../src/tracking/params.ts","../src/tracking/platform.ts"],"sourcesContent":["/**\n * The ad-platform vocabulary — the one place that says which URL parameters mean\n * \"this visit came from an ad\", and which platform each belongs to.\n *\n * Single source of truth on purpose: the capture script reads it to know what to\n * pull off the URL, and the notification renderer reads it to name the platform.\n * Two lists would drift into a cookie holding a click ID nothing can attribute.\n */\n\n/**\n * Click-ID parameters, in identification precedence.\n *\n * Order matters: `identifyPlatform` and `getPrimaryClickId` return the first\n * match, and a URL can legitimately carry more than one (a Google Ads link\n * retargeted through Meta arrives with both `gclid` and `fbclid`). Google first\n * because its click IDs are the ones that survive redirects intact.\n *\n * This table must cover every `clickIdParams` entry in `ads/providers.ts`, and\n * `ads/providers.test.ts` asserts it does. A configured ad property whose click ID\n * is not captured here means every conversion from that platform arrives\n * unattributed — silently, since an unattributed conversion looks exactly like an\n * organic one. `li_fat_id` and `epik` were missing for precisely that reason.\n */\nexport const PLATFORM_PARAMS: Readonly<Record<string, string>> = {\n  gclid: 'Google Ads',\n  gbraid: 'Google Ads',\n  wbraid: 'Google Ads',\n  fbclid: 'Meta',\n  ttclid: 'TikTok',\n  rdt_cid: 'Reddit',\n  ScCid: 'Snapchat',\n  msclkid: 'Microsoft Ads',\n  li_fat_id: 'LinkedIn',\n  epik: 'Pinterest',\n};\n\n/** Just the parameter names, in the same precedence order. */\nexport const CLICK_ID_PARAMS: readonly string[] = Object.keys(PLATFORM_PARAMS);\n\nexport const UTM_PARAMS = [\n  'utm_source',\n  'utm_medium',\n  'utm_campaign',\n  'utm_content',\n  'utm_term',\n] as const;\n\n/** Everything the capture script pulls off the landing URL. */\nexport const TRACKED_PARAMS: readonly string[] = [...CLICK_ID_PARAMS, ...UTM_PARAMS];\n\n/**\n * The attribution cookie.\n *\n * First-party and same-site: it is read by this site's own conversion handler and\n * never sent anywhere. It is still a persistent identifier, which is why writing\n * it waits on consent.\n */\nexport const TRACKING_COOKIE = '_ac';\n\n/** 90 days — an ad click and the conversion it produces are rarely further apart. */\nexport const TRACKING_COOKIE_DAYS = 90;\n\n/** The A/B variant cookie, assigned by the router when a site runs experiments. */\nexport const AB_COOKIE = '_ab';\n","/**\n * Naming the source of a visit.\n *\n * Both functions return the **first** match in `PLATFORM_PARAMS` order rather\n * than collecting every one, because a notification needs an answer, not a list.\n * A URL carrying two click IDs is a real case — a Google Ads link retargeted\n * through Meta — and the precedence in the table is the tiebreak.\n */\nimport { CLICK_ID_PARAMS, PLATFORM_PARAMS } from './params.ts';\nimport type { TrackingData } from './types.ts';\n\n/**\n * Which platform sent this visitor.\n *\n * Falls back to `utm_source` when no click ID is present: a UTM-tagged link from\n * a newsletter or a partner site is still attribution, just self-declared rather\n * than platform-issued. Returns null when there is nothing to go on.\n */\nexport function identifyPlatform(data: TrackingData): string | null {\n  for (const param of CLICK_ID_PARAMS) {\n    if (data[param]) return PLATFORM_PARAMS[param] ?? null;\n  }\n  const source = data['utm_source'];\n  return typeof source === 'string' && source ? source : null;\n}\n\n/** The click ID to quote, with the parameter it came from. */\nexport function getPrimaryClickId(data: TrackingData): { param: string; value: string } | null {\n  for (const param of CLICK_ID_PARAMS) {\n    const value = data[param];\n    if (value) return { param, value: String(value) };\n  }\n  return null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,kBAAoD;CAC/D,OAAO;CACP,QAAQ;CACR,QAAQ;CACR,QAAQ;CACR,QAAQ;CACR,SAAS;CACT,OAAO;CACP,SAAS;CACT,WAAW;CACX,MAAM;AACR;;AAGA,MAAa,kBAAqC,OAAO,KAAK,eAAe;AAE7E,MAAa,aAAa;CACxB;CACA;CACA;CACA;CACA;AACF;;AAGA,MAAa,iBAAoC,CAAC,GAAG,iBAAiB,GAAG,UAAU;;;;;;;;AASnF,MAAa,kBAAkB;;AAG/B,MAAa,uBAAuB;;AAGpC,MAAa,YAAY;;;;;;;;;;;;;;;;;;;AC7CzB,SAAgB,iBAAiB,MAAmC;CAClE,KAAK,MAAM,SAAS,iBAClB,IAAI,KAAK,QAAQ,OAAO,gBAAgB,UAAU;CAEpD,MAAM,SAAS,KAAK;CACpB,OAAO,OAAO,WAAW,YAAY,SAAS,SAAS;AACzD;;AAGA,SAAgB,kBAAkB,MAA6D;CAC7F,KAAK,MAAM,SAAS,iBAAiB;EACnC,MAAM,QAAQ,KAAK;EACnB,IAAI,OAAO,OAAO;GAAE;GAAO,OAAO,OAAO,KAAK;EAAE;CAClD;CACA,OAAO;AACT"}

package/dist/token--18wN9UR.d.mts

@@ -0,0 +1,46 @@
+//#region src/google/token.d.ts
+/** The fields we need from a service-account JSON key. */
+interface ServiceAccount {
+  client_email: string;
+  private_key: string;
+}
+/** A user OAuth credential (refresh-token flow — never a service account). */
+interface GoogleOAuth {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Which identity to act as.
+ *
+ * `scope` rides on the service-account variant because that grant carries its
+ * scope in the signed assertion. A user OAuth token's scopes are fixed when the
+ * refresh token is minted, so there is nothing to pass at exchange time — the
+ * asymmetry is the protocol's, not ours.
+ */
+type GoogleCredential = {
+  kind: 'service-account';
+  account: ServiceAccount;
+  scope: string;
+} | {
+  kind: 'oauth';
+  oauth: GoogleOAuth;
+};
+/**
+ * Exchange either credential for a short-lived access token.
+ *
+ * Throws rather than returning a result: nothing downstream can run without a
+ * token, so there is no per-item decision for a caller to make. (The API calls
+ * themselves do return structured results — those fail per domain.)
+ *
+ * `now` is a parameter so the assertion is testable without mocking the clock.
+ */
+declare function googleAccessToken(credential: GoogleCredential, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+/** Scopes, named once so a caller never spells one out. */
+declare const SCOPES: {
+  /** Search Console (`sitemaps.submit`, `urlInspection`, `sites`). */readonly webmasters: "https://www.googleapis.com/auth/webmasters"; /** Site Verification API. */
+  readonly siteVerification: "https://www.googleapis.com/auth/siteverification";
+};
+//#endregion
+export { googleAccessToken as a, ServiceAccount as i, GoogleOAuth as n, SCOPES as r, GoogleCredential as t };
+//# sourceMappingURL=token--18wN9UR.d.mts.map

package/dist/token--18wN9UR.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token--18wN9UR.d.mts","names":[],"sources":["../src/google/token.ts"],"mappings":";;UAkCiB,cAAA;EACf,YAAA;EACA,WAAW;AAAA;AAAA;AAAA,UAII,WAAA;EACf,QAAA;EACA,YAAA;EACA,YAAA;AAAA;;;;AAAY;AAWd;;;;KAAY,gBAAA;EACN,IAAA;EAAyB,OAAA,EAAS,cAAA;EAAgB,KAAA;AAAA;EAClD,IAAA;EAAe,KAAA,EAAO,WAAW;AAAA;AAAA;AA8CvC;;;;;;;;AA9CuC,iBA8CvB,iBAAA,CACd,UAAA,EAAY,gBAAA,EACZ,SAAA,UAAkB,KAAA,EAClB,GAAA,YACC,OAAA;;cAiBU,MAAA;EAnBX,6EAwBQ,UAAA,gDAtBP;EAAA,SAsBO,gBAAA;AAAA"}

package/dist/token-BV7tPHh2.mjs

@@ -0,0 +1,96 @@
+import { createSign } from "node:crypto";
+
+//#region src/google/token.ts
+/**
+* Google OAuth2 token exchange — one request, two grants.
+*
+* Both of this package's Google modules need a bearer token, and both used to
+* mint one themselves. The two copies looked different because the *credentials*
+* differ, but everything after building the form body was identical: same
+* endpoint, same content-type, same "surface the response body as the error"
+* rule, same `access_token` extraction. So the seam is precise —
+* **credential → form params differs, params → token does not.**
+*
+* The two grants are kept because they are not accidental duplication; they track
+* how each command is actually run:
+*
+*   - **service account** (RS256 JWT bearer) for `search notify`, which runs on
+*     every deploy in CI. It never expires. A refresh token can be revoked, and
+*     for an OAuth client still in *Testing* publishing status Google expires it
+*     after 7 days — a bad property for a deploy step.
+*   - **user OAuth** (refresh-token grant) for `search setup`, which is a
+*     one-time human operation. Site verification makes the calling identity an
+*     *owner* of the property, and that should be a person, not a project robot.
+*
+* `googleapis` is deliberately not a dependency — this is one REST endpoint in a
+* CLI that installs into every consumer project. See AGENTS.md.
+*
+* Internal: not a published subpath. Both `./indexing` and `./onboarding` import
+* it, so it lands in a shared chunk, which is free for a Node library. (The
+* "don't create a shared chunk" rule in AGENTS.md is about browser bundles and
+* the consent gate.)
+*/
+const TOKEN_URL = "https://oauth2.googleapis.com/token";
+const b64url = (input) => Buffer.from(input).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+/** Sign the RS256 JWT assertion a service-account grant carries. */
+function assertionFor(account, scope, now) {
+	const iat = Math.floor(now / 1e3);
+	const header = b64url(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	}));
+	const claims = b64url(JSON.stringify({
+		iss: account.client_email,
+		scope,
+		aud: TOKEN_URL,
+		iat,
+		exp: iat + 3600
+	}));
+	const signer = createSign("RSA-SHA256");
+	signer.update(`${header}.${claims}`);
+	const pem = account.private_key.replace(/\\n/g, "\n");
+	return `${header}.${claims}.${b64url(signer.sign(pem))}`;
+}
+/** The half that never differs: POST the grant, surface the cause, return the token. */
+async function requestToken(body, fetchImpl) {
+	const res = await fetchImpl(TOKEN_URL, {
+		method: "POST",
+		headers: { "content-type": "application/x-www-form-urlencoded" },
+		body: body.toString()
+	});
+	if (!res.ok) throw new Error(`token exchange failed (${res.status}): ${await res.text()}`);
+	const { access_token } = await res.json();
+	if (!access_token) throw new Error("token exchange returned no access_token");
+	return access_token;
+}
+/**
+* Exchange either credential for a short-lived access token.
+*
+* Throws rather than returning a result: nothing downstream can run without a
+* token, so there is no per-item decision for a caller to make. (The API calls
+* themselves do return structured results — those fail per domain.)
+*
+* `now` is a parameter so the assertion is testable without mocking the clock.
+*/
+function googleAccessToken(credential, fetchImpl = fetch, now = Date.now()) {
+	return requestToken(credential.kind === "oauth" ? new URLSearchParams({
+		grant_type: "refresh_token",
+		client_id: credential.oauth.clientId,
+		client_secret: credential.oauth.clientSecret,
+		refresh_token: credential.oauth.refreshToken
+	}) : new URLSearchParams({
+		grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+		assertion: assertionFor(credential.account, credential.scope, now)
+	}), fetchImpl);
+}
+/** Scopes, named once so a caller never spells one out. */
+const SCOPES = {
+	/** Search Console (`sitemaps.submit`, `urlInspection`, `sites`). */
+	webmasters: "https://www.googleapis.com/auth/webmasters",
+	/** Site Verification API. */
+	siteVerification: "https://www.googleapis.com/auth/siteverification"
+};
+
+//#endregion
+export { googleAccessToken as n, SCOPES as t };
+//# sourceMappingURL=token-BV7tPHh2.mjs.map