@getvitops/generator 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # @getvitops/generator
 
+## 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.
+
+- e764090: Separate where a processor stores information from whose law can reach it.
+
+  A processor carried one optional `country`, and the privacy policy flat-deduped it into a single
+  sentence. That conflated two facts a disclosure has to keep apart — **where the data rests** and
+  **which jurisdiction can compel access** — and privacy law turns on the second: the OPC's concern
+  is foreign _access_, not merely foreign storage.
+
+  Ordinary arrangements were inexpressible. Azure is data-resident in Canada and US-controlled;
+  Zoho can serve mail from a Canadian datacentre and telemetry from the US while being headquartered
+  in India; a Microsoft 365 tenant can be Canadian with its identity data in the US. For all of
+  them every available option was wrong: `country: "Canada"` rendered the incoherent _"outside of
+  Canada, including Canada"_, naming the operator's country asserted storage that wasn't happening,
+  and omitting it dropped the processor from the disclosure **silently**.
+
+  **New on a processor:**
+
+  ```jsonc
+  {
+    "name": "Zoho",
+    "purpose": "receiving and storing email sent to us",
+    "storage": [
+      { "country": "Canada", "scope": "mail and productivity data" },
+      { "country": "the United States", "scope": "analytics and telemetry" },
+    ],
+    "operatorCountry": "India",
+  }
+  ```
+
+  - `storage[]` — where information rests, each entry optionally `scope`d to a category. The scope
+    is what makes "Canadian tenant, identity data in the US" sayable.
+  - `operatorCountry` — the jurisdiction that can compel the provider to produce it. Gets its own
+    sentence: _"…established in, or controlled from, jurisdictions outside of Canada, including
+    India. Personal information those providers handle on our behalf may be subject to the laws of
+    those jurisdictions even when it is stored in Canada."_
+  - `country` still works, as shorthand asserting **both** facts — which is what it always
+    asserted, since the sentence it fed claimed storage and legal reach in one breath.
+
+  **Combining `country` with either explicit field is rejected** by `vitops validate`. Whether the
+  shorthand narrows the explicit fact or adds to it are two readings that make contradictory legal
+  claims, so neither is guessed.
+
+  A country in the policy's own jurisdiction is no longer treated as a transfer, which is the
+  `country: "Canada"` fix. Comparison ignores case and a leading "the".
+
+  ### This changes text you have already published
+
+  **Cloudflare, Cloudflare Turnstile, Vercel and Netlify now assert operator jurisdiction and no
+  storage.** They previously claimed `the United States` into a sentence saying "stored or processed
+  in" — a claim about the wrong fact. Cloudflare is anycast: a request from Toronto is answered from
+  a Toronto PoP, and Workers/R2 have residency controls the config cannot see.
+
+  So a site whose only foreign element is its host or Turnstile **stops claiming foreign storage**
+  and instead discloses foreign legal reach. That is a retraction in the direction of accuracy, and
+  it deserves a re-read. **If you pin a US region, say so** — declare a processor with
+  `storage: [{ country: "the United States" }]`. This generalises the rule the provider table
+  already applied to Matomo: "we don't know" is a fact.
+
+  **Everything else renders identically.** Google Analytics, Tag Manager, Clarity, Plausible,
+  Matomo Cloud and any processor you declared with `country` produce the same words as before,
+  because the shorthand expands to both facts and the operator sentence is suppressed when it would
+  only restate a country already disclosed as storage. The one cosmetic change: the closing
+  "subject to access requests…" sentence is now its own paragraph, since it is shared by both
+  clauses.
+
+  **A processor with no location at all is now reported** on stderr by `vitops legal`, naming the
+  document it will be missing from. It cannot appear in a transfer disclosure — there is nothing
+  true to say — but it used to vanish in silence, which is the failure that looks tidy. It is not a
+  validation error: a bare `{ name, purpose }` is still valid.
+
+  New exports from `@getvitops/generator`: `processorsMissingLocation`, `JURISDICTION_COUNTRIES`,
+  and the `ProcessorStorage` type. `PolicyVars` gains `jurisdictionCountry`, `storageCountries`,
+  `scopedStorage` and `operatorCountries`; `countries` is **deprecated but retained**, and still
+  names every country it ever named, so a custom template keeps rendering what it rendered.
+
+### Patch Changes
+
+- Updated dependencies [2c890c0]
+  - @getvitops/utils@4.1.0
+
 ## 4.0.0
 
 ### Major Changes

package/config.schema.json

@@ -1382,6 +1382,10 @@
                 "description": "Whether analytics fire in this environment.",
                 "type": "boolean"
               },
+              "ads": {
+                "description": "Whether `site.ads` pixels fire in this environment. Defaults to `analytics`, then true — a preview deployment sending pageviews is survivable, one firing conversion pixels is not, so this can be turned off on its own.",
+                "type": "boolean"
+              },
               "robots": {
                 "description": "Robots policy (e.g. \"noindex,nofollow\" for dev).",
                 "type": "string"
@@ -2452,6 +2456,61 @@
           },
           "additionalProperties": false
         },
+        "ads": {
+          "description": "Ad properties this site is linked to, keyed by platform. Read by `vitops ads setup` (ensure the DNS verification record), `vitops ads tags` (emit the consent-gated pixel), and the generated cookie notice (disclose what each pixel stores). Credentials never live here — the DNS write uses CLOUDFLARE_API_TOKEN from the environment.",
+          "type": "object",
+          "propertyNames": {
+            "type": "string",
+            "enum": [
+              "google",
+              "meta",
+              "linkedin",
+              "reddit",
+              "tiktok",
+              "microsoft",
+              "pinterest",
+              "snapchat"
+            ]
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "accountId": {
+                "description": "The advertising account as the platform shows it — Google Ads customer ID, Meta ad account, LinkedIn partner ID, Reddit advertiser ID. For LinkedIn this is also the Insight Tag id; everywhere else the tag id is `pixelId`.",
+                "type": "string"
+              },
+              "pixelId": {
+                "description": "The tag/pixel ID the browser snippet initialises — Meta pixel, TikTok pixel, Reddit pixel, Microsoft UET tag ID, Pinterest tag ID, Snap pixel, or the Google Ads conversion ID (`AW-…`, which is NOT the customer ID).",
+                "type": "string"
+              },
+              "conversionLabel": {
+                "description": "Google Ads only: the conversion action label paired with the `AW-…` conversion ID.",
+                "type": "string"
+              },
+              "domain": {
+                "description": "Bare hostname to verify with this platform. Defaults to the host of `domains.canonical` — set it only when the ad account is verified against a different domain.",
+                "type": "string"
+              },
+              "domainVerification": {
+                "description": "The verification token from the platform UI, for the platforms that verify by DNS TXT (Meta, TikTok, Pinterest, Snapchat). `vitops ads setup` prompts for it and writes it here on first run. NOT a secret — it is published in DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key. A value containing `=` is used as the whole record, which is the escape hatch if a platform changes its prefix.",
+                "type": "string"
+              },
+              "category": {
+                "description": "Consent category the tag waits on (default `marketing`). An ad pixel is advertising by default; `analytics` is for a site using one purely for its own measurement.",
+                "type": "string",
+                "enum": [
+                  "marketing",
+                  "analytics"
+                ]
+              },
+              "enabled": {
+                "description": "Set false to keep the property on record without emitting its tag.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          }
+        },
         "security": {
           "description": "Security integrations (bot protection).",
           "type": "object",
@@ -2568,7 +2627,32 @@
                         "description": "Why they receive it, as a noun phrase that reads after \"for\" (e.g. \"payment processing\")."
                       },
                       "country": {
-                        "description": "Where they process it, as it should read in a sentence (e.g. \"the United States\"). Feeds the cross-border-transfer disclosure.",
+                        "description": "Shorthand for the common case where one country is both where they store it and whose laws reach it: asserts BOTH `storage: [{ country }]` AND `operatorCountry`. Reads inside a sentence (e.g. \"the United States\"). When the two differ — a Canadian region operated by a US company — state `storage` and `operatorCountry` instead; setting this alongside either is rejected.",
+                        "type": "string"
+                      },
+                      "storage": {
+                        "description": "Where the information actually rests. Feeds the \"stored or processed outside of <jurisdiction>\" disclosure and nothing else. Several entries are allowed, each optionally scoped to a category of information — which is what makes a Canadian-region tenant holding identity data in the US expressible.",
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "country": {
+                              "type": "string",
+                              "description": "A country or bloc where this provider stores or processes the information, as it should read in a sentence (e.g. \"Canada\", \"the United States\", \"the European Union\"). Naming the jurisdiction the policy is written for is meaningful: it says this information does not leave it."
+                            },
+                            "scope": {
+                              "description": "Which information is held there, as a noun phrase that reads after \"in the case of\" (e.g. \"account and sign-in information\", \"mailbox contents\"). Omit when this location holds everything the provider receives — a scoped entry claims LESS than an unscoped one, so omitting it is the safe default.",
+                              "type": "string"
+                            }
+                          },
+                          "required": [
+                            "country"
+                          ],
+                          "additionalProperties": false
+                        }
+                      },
+                      "operatorCountry": {
+                        "description": "The jurisdiction that can compel this provider to hand the information over — where it is established, or from which it is controlled. Reads after \"the laws of\" (e.g. \"the United States\"); a bloc is acceptable. A SEPARATE fact from `storage`, because privacy law cares about foreign *access*, not only foreign storage: a Canadian-region service run by a US company is `storage: [{ country: \"Canada\" }]` with `operatorCountry: \"the United States\"`.",
                         "type": "string"
                       },
                       "privacyUrl": {

package/dist/index.d.mts

@@ -389,6 +389,41 @@ declare const IndexingSchema: z.ZodMiniObject<{
   }, z.z.core.$strip>>;
   priorityUrls: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniURL>>;
 }, z.z.core.$strip>;
+/**
+ * The ad platforms `vitops ads` can link a site to.
+ *
+ * A closed enum, mirroring `AD_PROVIDER_KEYS` in `@getvitops/utils/ads` — that
+ * module owns what each platform *can do* (whether it verifies a domain, what its
+ * tag is, which click ID it stamps), this owns what a config may *say*. Mirrored
+ * rather than derived because a `z.enum` needs literals to reach the published JSON
+ * Schema; `config.test.ts` asserts the two lists are the same set, so a provider
+ * added to one and not the other fails the build rather than silently getting no
+ * verification step and no tag.
+ */
+declare const AD_PROVIDERS: readonly ["google", "meta", "linkedin", "reddit", "tiktok", "microsoft", "pinterest", "snapchat"];
+type AdProvider = (typeof AD_PROVIDERS)[number];
+/**
+ * One ad property this site is linked to.
+ *
+ * Facts, not prose — the same rule the legal block follows. This records *which*
+ * account and *which* tag id, and the platform capability table decides what can be
+ * done about them. It is also what finally lets the rest of the toolchain see an ad
+ * pixel: the generated cookie notice discloses its cookies, `vitops ads lint`
+ * checks its click ID is captured, and the consent gate is handed the cookie names
+ * to clear on revoke. A pixel pasted into a template is invisible to all three.
+ */
+declare const AdPropertySchema: z.ZodMiniObject<{
+  accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+  category: z.ZodMiniOptional<z.ZodMiniEnum<{
+    analytics: "analytics";
+    marketing: "marketing";
+  }>>;
+  enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+}, z.z.core.$strip>;
 /**
  * Which template set the generated legal documents are written against. This is
  * a closed enum rather than a free string because an unrecognised value would
@@ -398,6 +433,22 @@ declare const IndexingSchema: z.ZodMiniObject<{
  */
 declare const JURISDICTIONS: readonly ["ca"];
 type Jurisdiction = (typeof JURISDICTIONS)[number];
+/**
+ * The country each template set frames cross-border transfers as *leaving*.
+ *
+ * A jurisdiction's own country is not a transfer, so this is what filters the
+ * disclosure lists — without it, `country: "Canada"` renders the incoherent
+ * "outside of Canada, including Canada".
+ *
+ * It belongs to the **jurisdiction**, not to `organization.address`: a `ca` policy
+ * says "outside of Canada" even for a business incorporated elsewhere. (The
+ * address drives a different sentence — the terms' governing-law clause, via
+ * `governingCountry`.) `satisfies` makes a new jurisdiction unable to forget it,
+ * the same guard style as `TEMPLATES`.
+ */
+declare const JURISDICTION_COUNTRIES: {
+  ca: string;
+};
 declare const SiteSectionSchema: z.ZodMiniObject<{
   defaultLocale: z.ZodMiniString<string>;
   locales: z.ZodMiniRecord<z.ZodMiniString<string>, z.ZodMiniObject<{
@@ -445,6 +496,7 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
     url: z.ZodMiniURL;
     api: z.ZodMiniOptional<z.ZodMiniURL>;
     analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
     robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
     variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
   }, z.z.core.$strip>>;
@@ -667,6 +719,27 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
     }>>;
     platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
   }, z.z.core.$strip>>;
+  ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+    google: "google";
+    meta: "meta";
+    linkedin: "linkedin";
+    reddit: "reddit";
+    tiktok: "tiktok";
+    microsoft: "microsoft";
+    pinterest: "pinterest";
+    snapchat: "snapchat";
+  }> & z.z.core.$partial, z.ZodMiniObject<{
+    accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+    category: z.ZodMiniOptional<z.ZodMiniEnum<{
+      analytics: "analytics";
+      marketing: "marketing";
+    }>>;
+    enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+  }, z.z.core.$strip>>>;
   security: z.ZodMiniOptional<z.ZodMiniObject<{
     turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
       siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -697,6 +770,11 @@ declare const SiteSectionSchema: z.ZodMiniObject<{
         name: z.ZodMiniString<string>;
         purpose: z.ZodMiniString<string>;
         country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+          country: z.ZodMiniString<string>;
+          scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        }, z.z.core.$strip>>>;
+        operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
         privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
       }, z.z.core.$strip>>>;
     }, z.z.core.$strip>>;
@@ -1121,6 +1199,7 @@ declare const ConfigSchema: z.ZodMiniObject<{
       url: z.ZodMiniURL;
       api: z.ZodMiniOptional<z.ZodMiniURL>;
       analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+      ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
       robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
       variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
     }, z.z.core.$strip>>;
@@ -1343,6 +1422,27 @@ declare const ConfigSchema: z.ZodMiniObject<{
       }>>;
       platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
     }, z.z.core.$strip>>;
+    ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+      google: "google";
+      meta: "meta";
+      linkedin: "linkedin";
+      reddit: "reddit";
+      tiktok: "tiktok";
+      microsoft: "microsoft";
+      pinterest: "pinterest";
+      snapchat: "snapchat";
+    }> & z.z.core.$partial, z.ZodMiniObject<{
+      accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+      category: z.ZodMiniOptional<z.ZodMiniEnum<{
+        analytics: "analytics";
+        marketing: "marketing";
+      }>>;
+      enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+    }, z.z.core.$strip>>>;
     security: z.ZodMiniOptional<z.ZodMiniObject<{
       turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
         siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -1373,6 +1473,11 @@ declare const ConfigSchema: z.ZodMiniObject<{
           name: z.ZodMiniString<string>;
           purpose: z.ZodMiniString<string>;
           country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+            country: z.ZodMiniString<string>;
+            scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+          }, z.z.core.$strip>>>;
+          operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
           privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
         }, z.z.core.$strip>>>;
       }, z.z.core.$strip>>;
@@ -1441,6 +1546,8 @@ type SiteIndexing = z.infer<typeof IndexingSchema>;
 type SiteIndexNow = z.infer<typeof IndexNowSchema>;
 /** Google Search Console property settings. The credential is never in the config. */
 type SiteSearchConsole = z.infer<typeof SearchConsoleSchema>;
+/** One `site.ads` entry — an ad property to link via `vitops ads setup`. */
+type SiteAdProperty = z.infer<typeof AdPropertySchema>;
 declare const CONFIG_SCHEMA_URL = "https://unpkg.com/@getvitops/generator/config.schema.json";
 /** The published JSON Schema (draft-2020-12), derived from the zod schema. */
 declare const configJsonSchema: {
@@ -1704,6 +1811,7 @@ declare const configJsonSchema: {
         url: z.ZodMiniURL;
         api: z.ZodMiniOptional<z.ZodMiniURL>;
         analytics: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+        ads: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
         robots: z.ZodMiniOptional<z.ZodMiniString<string>>;
         variant: z.ZodMiniOptional<z.ZodMiniString<string>>;
       }, z.z.core.$strip>>;
@@ -1926,6 +2034,27 @@ declare const configJsonSchema: {
         }>>;
         platforms: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniString<string>>>;
       }, z.z.core.$strip>>;
+      ads: z.ZodMiniOptional<z.ZodMiniRecord<z.ZodMiniEnum<{
+        google: "google";
+        meta: "meta";
+        linkedin: "linkedin";
+        reddit: "reddit";
+        tiktok: "tiktok";
+        microsoft: "microsoft";
+        pinterest: "pinterest";
+        snapchat: "snapchat";
+      }> & z.z.core.$partial, z.ZodMiniObject<{
+        accountId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        pixelId: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        conversionLabel: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        domain: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        domainVerification: z.ZodMiniOptional<z.ZodMiniString<string>>;
+        category: z.ZodMiniOptional<z.ZodMiniEnum<{
+          analytics: "analytics";
+          marketing: "marketing";
+        }>>;
+        enabled: z.ZodMiniOptional<z.ZodMiniBoolean<boolean>>;
+      }, z.z.core.$strip>>>;
       security: z.ZodMiniOptional<z.ZodMiniObject<{
         turnstile: z.ZodMiniOptional<z.ZodMiniObject<{
           siteKey: z.ZodMiniOptional<z.ZodMiniString<string>>;
@@ -1956,6 +2085,11 @@ declare const configJsonSchema: {
             name: z.ZodMiniString<string>;
             purpose: z.ZodMiniString<string>;
             country: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            storage: z.ZodMiniOptional<z.ZodMiniArray<z.ZodMiniObject<{
+              country: z.ZodMiniString<string>;
+              scope: z.ZodMiniOptional<z.ZodMiniString<string>>;
+            }, z.z.core.$strip>>>;
+            operatorCountry: z.ZodMiniOptional<z.ZodMiniString<string>>;
             privacyUrl: z.ZodMiniOptional<z.ZodMiniURL>;
           }, z.z.core.$strip>>>;
         }, z.z.core.$strip>>;
@@ -2851,13 +2985,48 @@ declare const BASE_HOOK: Record<string, string>;
 declare const TW_CLASH: ReadonlySet<string>;
 //#endregion
 //#region src/legal/providers.d.ts
+/** One place a provider holds information, and which information if not all of it. */
+interface ProcessorStorage {
+  /** Reads inside a sentence: "…including the United States". */
+  country: string;
+  /**
+   * Reads after "in the case of". Present means this location holds only SOME of
+   * what the provider receives, which is a narrower claim than an unscoped entry —
+   * so the template gives it its own sentence rather than folding it into the list,
+   * where a reader would take it to cover everything.
+   */
+  scope?: string | undefined;
+}
 interface Processor {
   /** The provider as a reader would recognise it. */
   name: string;
   /** Reads after "for": "…to Stripe for payment processing". */
   purpose: string;
-  /** Reads inside a sentence: "…including the United States". */
+  /**
+   * Shorthand asserting BOTH `storage` and `operatorCountry` are this one country.
+   *
+   * Kept for the common case (and because it is public API), but note it is the
+   * field whose *meaning* was never defined — its old doc comment described how it
+   * READ, not what it asserted, which is how one string came to stand for two
+   * different facts. Prefer the explicit pair when they differ.
+   */
   country?: string | undefined;
+  /**
+   * Where the information actually rests. Feeds the "stored or processed outside
+   * of <jurisdiction>" disclosure and nothing else.
+   */
+  storage?: ProcessorStorage[] | undefined;
+  /**
+   * The jurisdiction that can compel this provider to produce the information —
+   * where it is established, or from which it is controlled. Reads after "the laws
+   * of".
+   *
+   * A separate fact from `storage`, and the one privacy law actually turns on: the
+   * OPC's concern is foreign *access*, not foreign storage. Azure in a Canadian
+   * region is `storage: [{ country: 'Canada' }]`, `operatorCountry: 'the United
+   * States'` — the bytes never move and US law still reaches them.
+   */
+  operatorCountry?: string | undefined;
   privacyUrl?: string | undefined;
   /**
    * Cookies this provider sets. An empty array is meaningful and not the same as
@@ -2918,28 +3087,28 @@ declare const KNOWN_PROCESSORS: {
   turnstile: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: string[];
   };
   cloudflare: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
   vercel: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
   netlify: {
     name: string;
     purpose: string;
-    country: string;
+    operatorCountry: string;
     privacyUrl: string;
     cookies: never[];
   };
@@ -2961,6 +3130,19 @@ declare function detectProcessorKeys(cfg: Config): KnownProcessorKey[];
  * an explicit declaration is a statement of fact we have no grounds to drop.
  */
 declare function resolveProcessors(cfg: Config): Processor[];
+/**
+ * Processors the config discloses but places nowhere.
+ *
+ * Such a processor cannot appear in the transfer disclosure — there is nothing true
+ * to say about it — and today it vanishes from that section in silence, which is the
+ * tidy-looking failure. Names only, and deliberately NOT on `PolicyVars`: that type
+ * is the facts a template renders from, and a document must not editorialise about
+ * its own gaps. The CLI reports these on stderr instead.
+ *
+ * Not a `validateConfig` error either: a bare `{ name, purpose }` validates today,
+ * so rejecting it would make this a breaking change.
+ */
+declare function processorsMissingLocation(cfg: Config): string[];
 //#endregion
 //#region src/legal/derive.d.ts
 /**
@@ -3018,7 +3200,42 @@ interface PolicyVars {
     purpose: string;
     retention: string;
   }[];
-  /** Reads after "including": "…the United States and the European Union". */
+  /**
+   * The country this document frames transfers as *leaving*, from the jurisdiction
+   * rather than the org's address — a `ca` policy says "outside of Canada" even for
+   * a business incorporated elsewhere. (`governingCountry` is the address, and
+   * drives a different sentence: the terms' governing-law clause.)
+   */
+  jurisdictionCountry: string;
+  /**
+   * Reads after "including": foreign countries where information rests, with no
+   * category attached — the broad claim.
+   */
+  storageCountries: string | undefined;
+  /**
+   * Foreign storage locations holding only SOME categories. Structured rather than
+   * pre-joined, because the connective ("in the case of") is the template's word,
+   * not a fact. Disjoint from `storageCountries`: a country already claimed
+   * unscoped is never repeated here, since the unscoped claim is the broader one.
+   */
+  scopedStorage: {
+    country: string;
+    scope: string;
+  }[];
+  /**
+   * Reads after "the laws of": foreign jurisdictions that can compel a provider to
+   * produce information, EXCLUDING any already named in `storageCountries` —
+   * saying US law reaches information already disclosed as stored in the US adds a
+   * sentence and no fact.
+   */
+  operatorCountries: string | undefined;
+  /**
+   * Reads after "including": "…the United States and the European Union".
+   *
+   * @deprecated Split into `storageCountries` and `operatorCountries`, which keep
+   * residency and legal reach apart. Retained, and still every country the field
+   * ever named, so a consumer's own template renders what it always rendered.
+   */
   countries: string | undefined;
   consentModel: 'opt-in' | 'opt-out' | 'none';
   cookieCategories: string[];
@@ -3126,5 +3343,5 @@ declare function generateLegal(cfg: Config, opts?: GenerateLegalOptions): Record
  */
 declare function defaultConfig(): DesignSystem;
 //#endregion
-export { BASE_HOOK, type Block, CONFIG_SCHEMA_URL, CONTRAST, type ColorUtility, type Config, ConfigSchema, type ConfigValidationResult, type ContactObject, DARK_SEL, DOC_ORDER, DOC_SLUGS, type DesignSystem, DesignSystemSchema, type DocSet, type ExpandedHue, type Format, type FunctionalRole, type GenerateLegalOptions, type GenerateOptions, type GenerateResult, type IconSpriteOptions, type IconSpriteResult, JURISDICTIONS, type JsonSchemaNode, type Jurisdiction, KNOWN_PROCESSORS, type KnownProcessorKey, type LegalDoc, type LegalOutput, NUMERIC_STEPS, type OrganizationConfig, type PolicyVars, type PostalAddress, type Processor, REQUIRED_ROLES, ROLE_TOKEN_KEYS, type ResolvedInput, type RoleKind, type RoleSpec, SCHEMA_URL, type SchemaTreeNode, type SchemaTreeOptions, type SiteFont, SiteFontSchema, type SiteIndexNow, type SiteIndexing, type SiteSearchConsole, type SiteSection, type Span, type StylesheetFormat, TEMPLATES, TIERS, TIER_NAMES, TW_CLASH, type Tier, type TierAstro, type TierCss, type TierEntry, type TierProjection, type TierWc, type ValidationResult, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, renderInlineMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, schemaTreeNodes, spriteId, stripNulls, tierPatterns, tierTags, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
+export { AD_PROVIDERS, type AdProvider, BASE_HOOK, type Block, CONFIG_SCHEMA_URL, CONTRAST, type ColorUtility, type Config, ConfigSchema, type ConfigValidationResult, type ContactObject, DARK_SEL, DOC_ORDER, DOC_SLUGS, type DesignSystem, DesignSystemSchema, type DocSet, type ExpandedHue, type Format, type FunctionalRole, type GenerateLegalOptions, type GenerateOptions, type GenerateResult, type IconSpriteOptions, type IconSpriteResult, JURISDICTIONS, JURISDICTION_COUNTRIES, type JsonSchemaNode, type Jurisdiction, KNOWN_PROCESSORS, type KnownProcessorKey, type LegalDoc, type LegalOutput, NUMERIC_STEPS, type OrganizationConfig, type PolicyVars, type PostalAddress, type Processor, type ProcessorStorage, REQUIRED_ROLES, ROLE_TOKEN_KEYS, type ResolvedInput, type RoleKind, type RoleSpec, SCHEMA_URL, type SchemaTreeNode, type SchemaTreeOptions, type SiteAdProperty, type SiteFont, SiteFontSchema, type SiteIndexNow, type SiteIndexing, type SiteSearchConsole, type SiteSection, type Span, type StylesheetFormat, TEMPLATES, TIERS, TIER_NAMES, TW_CLASH, type Tier, type TierAstro, type TierCss, type TierEntry, type TierProjection, type TierWc, type ValidationResult, buildIconSprite, configJsonSchema, deepMerge, defaultConfig, derivePolicyVars, detectProcessorKeys, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, jsonSchema, loadIconSvg, parseMarkdown, processorsMissingLocation, renderInlineMarkdown, renderMarkdown, renderNodes, resolveConfig, resolveInput, resolvePrivacyContact, resolveProcessors, resolveTheme, roleColorUtilities, roleHue, roleKind, schemaTreeNodes, spriteId, stripNulls, tierPatterns, tierTags, toContentNodes, toHtmlFragment, toPortableText, tokenClass, tokenVar, validate, validateConfig };
 //# sourceMappingURL=index.d.mts.map