@getvitops/utils 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # @getvitops/utils
 
+## 4.1.0
+
+### Minor Changes
+
+- 2c890c0: Link a site to its ad properties: `site.ads`, `vitops ads`, and `<Ads />`.
+
+  `vitops search` covers the whole Search Console relationship. Nothing covered the equivalent one
+  with ad platforms, and a site's ad accounts had nowhere to live — so a Meta pixel pasted into a
+  template was invisible to the rest of the toolchain. It set `_fbp` on a site whose generated cookie
+  notice never mentioned it, whose consent gate never cleared it on revoke, and — for LinkedIn and
+  Pinterest — whose attribution never captured the click ID at all, so every conversion from those
+  platforms arrived indistinguishable from organic traffic.
+
+  **New `site.ads` block**, keyed by platform (`google`, `meta`, `linkedin`, `reddit`, `tiktok`,
+  `microsoft`, `pinterest`, `snapchat`):
+
+  ```jsonc
+  {
+    "site": {
+      "ads": {
+        "meta": { "pixelId": "123456789", "domainVerification": "abc123" },
+        "google": {
+          "accountId": "123-456-7890",
+          "pixelId": "AW-987654321",
+          "conversionLabel": "xyz",
+        },
+      },
+    },
+  }
+  ```
+
+  **`vitops ads setup`** ensures each platform's domain-verification DNS record. Only four platforms
+  verify a domain at all — Meta, TikTok, Pinterest and Snapchat, by apex DNS TXT — and that record is
+  the one thing created for you (in Cloudflare, via `CLOUDFLARE_API_TOKEN`; created only, never edited
+  or deleted). Google Ads, LinkedIn, Reddit and Microsoft Ads have no domain verification: linking
+  there is the tag and the account id, and the run says so rather than skipping in silence. No
+  platform Marketing API is called — Meta's needs a system-user token and Google's an approved
+  developer token with your own account on the line — so the final "Verify" click is surfaced as a
+  reminder. `--dry` prints the plan, `--check` reports drift and exits non-zero.
+
+  **It asks for what the config is missing.** A verification token does not exist until someone
+  fetches it from the platform UI, so a first run prompts for it, naming the exact UI path, folds the
+  answer into the plan and writes it to your config. The token is not a secret — it is published in
+  DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key.
+  Prompting requires a TTY: with `--dry`, `--check`, `--no-prompt`, or in CI, you get a named error
+  instead and the run never hangs. `--no-write` keeps the answer out of the config.
+
+  **`vitops ads tags`** prints each pixel as an inert, consent-gated `<script>` — `type="text/plain"`
+  with the library URL on `data-src`, so an undecided visitor's page issues no third-party request.
+  For Bricks, WordPress, Eleventy: any stack without the Astro integration.
+
+  **`vitops ads lint`** reports the gaps that are invisible at runtime: a click ID the platform stamps
+  that attribution does not capture, a pixel while `site.tracking` is off, a property with no tag id.
+
+  **`<Ads />` in `@getvitops/astro`**, a sibling of `<Analytics />` rather than part of it — ad
+  properties come from the site config, state their own consent category (`marketing` by default,
+  rather than being derived), and switch per environment on their own
+  (`environments.<env>.ads`, defaulting to `analytics`, then true, so a preview deployment can send
+  pageviews without firing conversion pixels). Both components now render through one `<GatedTags />`,
+  so the inert markup has a single implementation.
+
+  **Your cookie notice now discloses every configured pixel** — name, cookies and opt-out — from the
+  same table that writes `data-consent-cookies`, so the notice and the revoke cannot disagree. If you
+  add `site.ads` to a config whose privacy policy or cookie notice you have already published,
+  re-generate and re-read them.
+
+  `li_fat_id` (LinkedIn) and `epik` (Pinterest) join the click-ID capture vocabulary; a site running
+  either platform starts attributing conversions it previously recorded as organic.
+
 ## 4.0.0
 
 ### Major Changes

package/dist/ads/index.d.mts

@@ -0,0 +1,228 @@
+import { n as findZoneId, r as listApexTxt, t as createApexTxt } from "../cloudflare-BiK61Oq4.mjs";
+
+//#region src/ads/types.d.ts
+/**
+ * The ads module's own option surface.
+ *
+ * Deliberately structural rather than `Config['site']['ads']` 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` and `DomainSetup` beside it.
+ *
+ * Optional fields are written `?: T | undefined` throughout: `exactOptionalPropertyTypes`
+ * is on, and these describe a *parsed JSON config* where an absent key and an explicit
+ * `undefined` are the same thing.
+ */
+/**
+ * The ad platforms this toolchain knows how to link a site to.
+ *
+ * A closed set, mirroring `AD_PROVIDERS` in the generator's `config.ts` — the
+ * capability table in `providers.ts` has one entry per member, and a test in the
+ * generator asserts the two lists agree. An open string would mean a typo'd
+ * provider silently getting no verification step and no tag.
+ */
+type AdProvider = 'google' | 'meta' | 'linkedin' | 'reddit' | 'tiktok' | 'microsoft' | 'pinterest' | 'snapchat';
+/** Which consent category gates a provider's tag. */
+type AdConsentCategory = 'marketing' | 'analytics';
+/** One ad property to link, as the config declares it. */
+interface AdPropertySetup {
+  provider: AdProvider;
+  /**
+   * The account as the platform shows it — Google Ads customer id, Meta ad
+   * account, LinkedIn partner id, Reddit advertiser id.
+   */
+  accountId?: string | undefined;
+  /** The tag/pixel id, when the platform issues one distinct from the account. */
+  pixelId?: string | undefined;
+  /** Google Ads only: the conversion label paired with the conversion id. */
+  conversionLabel?: string | undefined;
+  /** The host to verify, bare (`acme.ca`). The CLI defaults it from the canonical domain. */
+  domain?: string | undefined;
+  /**
+   * The verification token from the platform UI.
+   *
+   * A bare token gets the provider's TXT prefix applied; a value already
+   * containing `=` is used as the whole record content, which is the escape hatch
+   * for a platform changing its prefix without waiting on a toolchain release.
+   */
+  domainVerification?: string | undefined;
+  /** Category the tag waits on. Defaults to `marketing`. */
+  category?: AdConsentCategory | undefined;
+  enabled?: boolean | undefined;
+}
+/** Everything `plan()` needs, once the CLI has read the config. */
+interface AdsConfig {
+  /** The properties to link. Already filtered to `--provider` if that was passed. */
+  properties: AdPropertySetup[];
+}
+/**
+ * One property's observed live state, gathered by the executor before planning.
+ *
+ * Same shape of arrangement as `DomainState`: the decision is pure, the
+ * observation is not. `txtContents` is every apex TXT record on the domain, so
+ * the planner can decide both "our record is present" and "a *different* record
+ * from this provider is present" — the second is a token rotation, which needs
+ * saying rather than silently adding a second record.
+ */
+interface AdDomainState {
+  /** The Cloudflare zone id for the domain, if one was found. */
+  zoneId?: string | undefined;
+  /** Every apex TXT record content, unquoted. */
+  txtContents: string[];
+}
+//#endregion
+//#region src/ads/plan.d.ts
+/** A step's decision. `blocked` means the config is missing something. */
+type StepAction = 'create' | 'skip' | 'blocked';
+/** A config field the operator can supply to unblock a step. */
+type MissingField = 'domainVerification' | 'accountId' | 'pixelId';
+interface StepPlan {
+  action: StepAction;
+  /** Why it's a skip, or what the mutation will do, or what is missing. */
+  detail: string;
+  /** Set only on `blocked`: which config field would unblock it. */
+  needs?: MissingField | undefined;
+}
+/** The steps for one ad property, decided against its live state. */
+interface AdPropertyPlan {
+  provider: AdPropertySetup['provider'];
+  /** The platform name, so a formatter needn't reach back into the table. */
+  name: string;
+  /** The domain being verified, when the platform verifies one. */
+  domain?: string | undefined;
+  /** Ensure the apex verification TXT. */
+  txt: StepPlan;
+  /** Whether the tag can be emitted (`ads tags`). */
+  tag: StepPlan;
+  /** The exact TXT content to create, when `txt.action` is `create`. */
+  txtContent?: string | undefined;
+  /** Manual follow-ups — including *why* a platform has no verification step. */
+  reminders: string[];
+}
+interface AdsPlan {
+  properties: AdPropertyPlan[];
+  /** Operator-facing warnings that span the whole run. */
+  notes: string[];
+}
+/**
+ * Decide one property's steps.
+ *
+ * The `dns-txt` branch has three outcomes, and keeping them distinct is the point:
+ * our record is present (skip), a *different* record from the same platform is
+ * present (create, and say so — a token rotation leaves the old record in place,
+ * since this command never edits or deletes DNS), or no token is configured yet
+ * (blocked, naming the field).
+ */
+declare function planProperty(setup: AdPropertySetup, state: AdDomainState): AdPropertyPlan;
+/** Plan every configured property. */
+declare function plan(config: AdsConfig, states: Map<string, AdDomainState>): AdsPlan;
+/** Any step that isn't a skip — i.e. the live state or the config has drifted. */
+declare function hasDrift(p: AdsPlan): boolean;
+/** Every field a run still needs, per provider — what the CLI asks for. */
+declare function missingFields(p: AdsPlan): {
+  provider: string;
+  needs: MissingField;
+}[];
+/** Render a plan as the block `--dry` and `--check` print. */
+declare function formatPlan(p: AdsPlan): string;
+/** The outcome of one property's run, for the summary table. */
+interface AdPropertyResult {
+  provider: string;
+  domain: string;
+  txt: 'created' | 'present' | 'blocked' | 'failed' | 'n/a';
+  tag: 'ready' | 'blocked';
+  reminders: string[];
+}
+/** Render the end-of-run summary: one row per property, plus any reminders. */
+declare function formatSummary(results: AdPropertyResult[]): string;
+//#endregion
+//#region src/ads/providers.d.ts
+/** How a platform proves you own the domain. */
+interface AdVerificationSpec {
+  method: 'dns-txt' | 'none';
+  /**
+   * Prefix prepended to a bare token to form the record content. Owned here so a
+   * config holds the token the platform shows, not a hand-assembled record — but
+   * see `txtRecord`: a value already containing `=` passes through whole, which is
+   * the escape hatch when a platform changes its spelling.
+   */
+  txtPrefix?: string;
+  /** Where in the platform UI the token is found. Printed when asking for it. */
+  where?: string;
+  /** Why there is nothing to automate. Required when `method` is `none`. */
+  reason?: string;
+}
+/** The tag, and which config field carries its id. */
+interface AdTagSpec {
+  /** Which field the tag id comes from — and therefore what to ask for when absent. */
+  needs: 'pixelId' | 'accountId';
+  /** The remote library. Absent when the platform's own bootstrap loads itself. */
+  src?: (id: string) => string;
+  /** The inline bootstrap, which the gate runs before attaching `src`. */
+  bootstrap: (id: string, entry: AdPropertySetup) => string;
+  /**
+   * Cookies the tag sets, for `data-consent-cookies` (what a revoke clears) and
+   * for the generated cookie notice. A `*` suffix is a prefix match.
+   */
+  cookies: string[];
+  /** The provider's own privacy policy, for the cookie notice. */
+  privacyUrl: string;
+  /** A visitor-facing opt-out, where the platform offers one. */
+  optOut?: string;
+}
+interface AdPlatform {
+  /** The platform as a reader would recognise it. */
+  name: string;
+  /**
+   * The jurisdiction that can compel this platform to produce what it receives —
+   * where the contracting entity is established. Feeds the generated privacy
+   * policy's cross-border transfer disclosure, which is a claim about foreign
+   * *access*, not foreign storage (see `Processor.operatorCountry` in the
+   * generator's `legal/providers.ts`). A consumer whose contracting entity differs
+   * declares their own processor entry instead.
+   */
+  operatorCountry: string;
+  /** Click-ID parameters this platform stamps on an ad landing URL. */
+  clickIdParams: string[];
+  /** Where the operator manages the property. */
+  consoleUrl: string;
+  verification: AdVerificationSpec;
+  tag: AdTagSpec;
+  /** Follow-ups no API covers, given this entry. */
+  manualSteps: (entry: AdPropertySetup) => string[];
+}
+declare const AD_PLATFORMS: Record<AdProvider, AdPlatform>;
+/** Every provider, in table order — the one place iteration order is decided. */
+declare const AD_PROVIDER_KEYS: AdProvider[];
+/** Whether a string names a known provider (for CLI arg validation). */
+declare const isAdProvider: (value: string) => value is AdProvider;
+/**
+ * The DNS TXT record content for a token.
+ *
+ * A value already containing `=` is taken as the whole record and left alone. That
+ * is the same escape hatch an icon name containing `:` gets: a platform can change
+ * its prefix spelling without waiting on a toolchain release, and an operator who
+ * pasted the full record from the UI gets what they meant rather than a
+ * double-prefixed record that verifies against nothing.
+ */
+declare function txtRecord(provider: AdProvider, token: string): string;
+/** The tag id for an entry, or undefined when the field it needs is unset. */
+declare function tagId(entry: AdPropertySetup): string | undefined;
+/** The consent category gating an entry's tag. `marketing` unless stated otherwise. */
+declare const categoryOf: (entry: AdPropertySetup) => AdConsentCategory;
+/**
+ * One provider's tag, rendered as a **consent-gated, inert** `<script>`.
+ *
+ * `type="text/plain"` with the URL on `data-src` is what makes the gate real: the
+ * browser neither parses the body nor fetches the library, so an undecided
+ * visitor's page issues no third-party request. Never give one of these a live
+ * `src` — a gate that instead asks a loaded tracker not to track is a promise.
+ *
+ * Returns null when the entry has no tag id, so a caller can report the gap rather
+ * than emit a snippet that initialises `undefined`.
+ */
+declare function renderTag(entry: AdPropertySetup, strategy?: 'idle' | 'async' | 'interaction'): string | null;
+//#endregion
+export { AD_PLATFORMS, AD_PROVIDER_KEYS, type AdConsentCategory, type AdDomainState, type AdPlatform, type AdPropertyPlan, type AdPropertyResult, type AdPropertySetup, type AdProvider, type AdTagSpec, type AdVerificationSpec, type AdsConfig, type AdsPlan, type MissingField, type StepAction, type StepPlan, categoryOf, createApexTxt, findZoneId, formatPlan, formatSummary, hasDrift, isAdProvider, listApexTxt, missingFields, plan, planProperty, renderTag, tagId, txtRecord };
+//# sourceMappingURL=index.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/ads/types.ts","../../src/ads/plan.ts","../../src/ads/providers.ts"],"mappings":";;;;;;AAsBA;;;;AAAsB;AAWtB;;;;AAA6B;AAG7B;;;;;;;;AAAA,KAdY,UAAA;;KAWA,iBAAA;;UAGK,eAAA;EACf,QAAA,EAAU,UAAA;EAsBH;AAAA;AAIT;;EArBE,SAAA;EAuBA;EArBA,OAAA;EAiCe;EA/Bf,eAAA;;EAEA,MAAA;EAiCW;;;;ACzDb;;;EDgCE,kBAAA;EChCoB;EDkCpB,QAAA,GAAW,iBAAiB;EAC5B,OAAA;AAAA;;UAIe,SAAA;EClCA;EDoCf,UAAA,EAAY,eAAe;AAAA;;;;;;;;AC/BP;AAItB;UDuCiB,aAAA;;EAEf,MAAA;EClCK;EDoCL,WAAW;AAAA;;;;KCzDD,UAAA;ADFZ;AAAA,KCKY,YAAA;AAAA,UAEK,QAAA;EACf,MAAA,EAAQ,UAAA;EDRY;ECUpB,MAAA;EDC2B;ECC3B,KAAA,GAAQ,YAAY;AAAA;ADDO;AAAA,UCKZ,cAAA;EACf,QAAA,EAAU,eAAA;;EAEV,IAAA;EDJA;ECMA,MAAA;EDDA;ECGA,GAAA,EAAK,QAAA;EDCL;ECCA,GAAA,EAAK,QAAA;EDSL;ECPA,UAAA;EDSW;ECPX,SAAA;AAAA;AAAA,UAGe,OAAA;EACf,UAAA,EAAY,cAAc;EDQF;ECNxB,KAAA;AAAA;ADQ2B;AAY7B;;;;AAIa;;;;AAhBgB,iBCIb,YAAA,CAAa,KAAA,EAAO,eAAA,EAAiB,KAAA,EAAO,aAAA,GAAgB,cAAA;;iBAoD5D,IAAA,CAAK,MAAA,EAAQ,SAAA,EAAW,MAAA,EAAQ,GAAA,SAAY,aAAA,IAAiB,OAAA;;iBAe7D,QAAA,CAAS,CAAU,EAAP,OAAO;AA7GnC;AAAA,iBAkHgB,aAAA,CAAc,CAAA,EAAG,OAAA;EAAY,QAAA;EAAkB,KAAA,EAAO,YAAY;AAAA;AAhHlF;AAAA,iBA4HgB,UAAA,CAAW,CAAU,EAAP,OAAO;;UAcpB,gBAAA;EACf,QAAA;EACA,MAAA;EACA,GAAA;EACA,GAAA;EACA,SAAA;AAAA;AA1IoB;AAAA,iBAgJN,aAAA,CAAc,OAA2B,EAAlB,gBAAgB;;;ADjH1B;AAAA,UE9BZ,kBAAA;EACf,MAAA;;;AF6CW;;;;EEtCX,SAAA;EDnBoB;ECqBpB,KAAA;EDrBoB;ECuBpB,MAAA;AAAA;;UAIe,SAAA;EDxBO;EC0BtB,KAAA;EDxBe;EC0Bf,GAAA,IAAO,EAAA;;EAEP,SAAA,GAAY,EAAA,UAAY,KAAA,EAAO,eAAe;ED3B9C;;;;ECgCA,OAAA;ED5BoB;EC8BpB,UAAA;ED1Be;EC4Bf,MAAA;AAAA;AAAA,UAGe,UAAA;EDxBV;EC0BL,IAAA;EDxBa;;;;;;;;ECiCb,eAAA;EDjCK;ECmCL,aAAA;ED/BA;ECiCA,UAAA;EACA,YAAA,EAAc,kBAAA;EACd,GAAA,EAAK,SAAA;EDhCiB;ECkCtB,WAAA,GAAc,KAAA,EAAO,eAAA;AAAA;AAAA,cAaV,YAAA,EAAc,MAAA,CAAO,UAAA,EAAY,UAAA;;cAuMjC,gBAAA,EAAgD,UAAU;;cAG1D,YAAA,GAAgB,KAAA,aAAgB,KAAA,IAAS,UAAmC;AD1OzF;;;;;;;;;AAAA,iBCqPgB,SAAA,CAAU,QAAA,EAAU,UAAU,EAAE,KAAA;;iBAOhC,KAAA,CAAM,KAAsB,EAAf,eAAe;;cAM/B,UAAA,GAAc,KAAA,EAAO,eAAA,KAAkB,iBACrB;ADnQ2D;AAoD1F;;;;;;;;;;AApD0F,iBCmR1E,SAAA,CACd,KAAA,EAAO,eAAe,EACtB,QAAA"}