feat(gtm,ga): consent.default() + strict GCMv2 validation (#772)

Author: harlan-zw

docs/content/docs/1.guides/3.consent.md

@@ -89,7 +89,7 @@ const consent = useScriptTriggerConsent({
 
 ## Per-script consent API
 
-Every consent-aware `useScriptX()`{lang="ts"} returns a `consent` object typed to the vendor's native API. Combine it with `defaultConsent` for the initial policy (applied in `clientInit` before the vendor fires its first call) and call `consent.*` from your cookie banner to update.
+Every consent-aware `useScriptX()`{lang="ts"} returns a `consent` object typed to the vendor's native API. Combine it with `defaultConsent` for the initial policy (applied in `clientInit` before the vendor fires its first call) and call `consent.*` from your cookie banner to update. For GCMv2 scripts (Google Analytics, Google Tag Manager), `consent.default(state)`{lang="ts"} is also available for runtime-derived defaults; both methods validate input against the canonical GCMv2 schema and warn via `consola` on unknown keys or non-`granted`/`denied` values.
 
 ```ts
 const { consent } =useScriptGoogleAnalytics({
@@ -111,8 +111,8 @@ function onAcceptAll() {
 
 | Script |`defaultConsent`| Runtime `consent.*`|
 |---|---|---|
-| Google Analytics |`Partial<ConsentState>`{lang="html"} (GCMv2) |`consent.update(state)`{lang="ts"} |
-| Google Tag Manager |`Partial<ConsentState>`{lang="html"} (GCMv2) |`consent.update(state)`{lang="ts"} |
+| Google Analytics |`Partial<ConsentState>`{lang="html"} (GCMv2) |`consent.default(state)`{lang="ts"} / `consent.update(state)`{lang="ts"} |
+| Google Tag Manager |`Partial<ConsentState>`{lang="html"} (GCMv2) |`consent.default(state)`{lang="ts"} / `consent.update(state)`{lang="ts"} |
 | Bing UET |`{ ad_storage }`|`consent.update({ ad_storage })`{lang="ts"} |
 | Meta Pixel |`'granted' \| 'denied'`|`consent.grant()`{lang="ts"} / `consent.revoke()`{lang="ts"} |
 | TikTok Pixel |`'granted' \| 'denied' \| 'hold'`|`consent.grant()`{lang="ts"} / `consent.revoke()`{lang="ts"} / `consent.hold()`{lang="ts"} |

docs/content/scripts/google-analytics.md

@@ -32,7 +32,7 @@ The proxy exposes the `gtag` and `dataLayer` properties, and you should use them
 
 ## Consent Mode
 
-Google Analytics natively consumes [GCMv2 consent state](https://developers.google.com/tag-platform/security/guides/consent). Set the default with `defaultConsent` (fires `gtag('consent', 'default', state)`{lang="ts"} before `gtag('js', ...)`{lang="ts"}) and call `consent.update()`{lang="ts"} at runtime to flip categories.
+Google Analytics natively consumes [GCMv2 consent state](https://developers.google.com/tag-platform/security/guides/consent). Set the default with `defaultConsent` (fires `gtag('consent', 'default', state)`{lang="ts"} before `gtag('js', ...)`{lang="ts"}) and call `consent.update()`{lang="ts"} at runtime to flip categories. For runtime-derived defaults (waiting for region/CMS to resolve before firing), call `consent.default()`{lang="ts"} from the client.
 
 ::callout{icon="i-heroicons-play"to="https://stackblitz.com/github/nuxt/scripts/tree/main/examples/regional-consent"target="_blank"}
 Try the live [Regional Consent Example](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/regional-consent) on [StackBlitz](https://stackblitz.com).
@@ -70,7 +70,7 @@ function savePreferences(choices: { analytics: boolean, marketing: boolean }) {
 </script>
 ```
 
-`consent.update()`{lang="ts"} accepts any `Partial<ConsentState>`{lang="ts"}; missing categories stay at their current value. For pre-`gtag('js')`{lang="ts"} setup beyond consent defaults, `onBeforeGtagStart` remains available as a general escape hatch.
+`consent.update()`{lang="ts"} and `consent.default()`{lang="ts"} both accept any `Partial<ConsentState>`{lang="ts"}; missing categories stay at their current value. Both methods validate input against the canonical GCMv2 schema and warn via `consola` on unknown keys or non-`granted`/`denied` values. For pre-`gtag('js')`{lang="ts"} setup beyond consent defaults, `onBeforeGtagStart` remains available as a general escape hatch.
 
 ### Per-region defaults
 

docs/content/scripts/google-tag-manager.md

@@ -48,7 +48,7 @@ useScriptEventPage(({ title, path }) => {
 
 ## Consent Mode
 
-Google Tag Manager natively consumes [GCMv2 consent state](https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic). Set the default with `defaultConsent` (pushes `['consent','default', state]` onto the dataLayer before the `gtm.js` event) and call `consent.update()`{lang="ts"} at runtime. Pass an **array** to `defaultConsent` to fire multiple defaults, for example [region-specific defaults](https://developers.google.com/tag-platform/security/guides/consent?consentmode=advanced#region-specific-behavior) where each entry targets different countries via `region`.
+Google Tag Manager natively consumes [GCMv2 consent state](https://developers.google.com/tag-platform/security/guides/consent?consentmode=basic). Set the default with `defaultConsent` (pushes `['consent','default', state]` onto the dataLayer before the `gtm.js` event) and call `consent.update()`{lang="ts"} at runtime. Pass an **array** to `defaultConsent` to fire multiple defaults, for example [region-specific defaults](https://developers.google.com/tag-platform/security/guides/consent?consentmode=advanced#region-specific-behavior) where each entry targets different countries via `region`. For runtime-derived defaults (waiting for region/CMS to resolve before queueing), call `consent.default()`{lang="ts"} from the client.
 
 ::callout{icon="i-heroicons-play"to="https://stackblitz.com/github/nuxt/scripts/tree/main/examples/cookie-consent"target="_blank"}
 Try the live [Cookie Consent Example](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/cookie-consent), [Granular Consent Example](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/granular-consent), or [Regional Consent Example](https://stackblitz.com/github/nuxt/scripts/tree/main/examples/regional-consent) on [StackBlitz](https://stackblitz.com).
@@ -133,7 +133,7 @@ useScriptGoogleTagManager({
 
 The module forwards each entry verbatim, in input order. Precedence between region-scoped and unscoped defaults is enforced by gtag at runtime, not by ordering.
 
-`consent.update()`{lang="ts"} accepts any `Partial<ConsentState>`{lang="ts"}; missing categories stay at their current value. `onBeforeGtmStart` remains available as a general escape hatch for any other pre-`gtm.start` setup (only when the GTM ID is passed directly to the composable, not via `nuxt.config`).
+`consent.update()`{lang="ts"} and `consent.default()`{lang="ts"} both accept any `Partial<ConsentState>`{lang="ts"}; missing categories stay at their current value. Both methods validate input against the canonical GCMv2 schema and warn via `consola` on unknown keys or non-`granted`/`denied` values. `onBeforeGtmStart` remains available as a general escape hatch for any other pre-`gtm.start` setup (only when the GTM ID is passed directly to the composable, not via `nuxt.config`).
 
 ::script-types
 ::

packages/script/src/runtime/registry/_gcm-consent.ts

@@ -0,0 +1,47 @@
+importtype{ConsentState,GcmConsentApi,UseScriptContext}from'../types'
+import{safeParse,strictObject}from'valibot'
+import{logger}from'../logger'
+import{gcmConsentState}from'./schemas'
+
+exporttype{GcmConsentApi}
+
+// Strict variant rebuilt from the lenient schema's entries — same shape, but
+// unknown keys produce issues so we can warn on typos without breaking the
+// lenient `defaultConsent` schema parse used at build time.
+constgcmConsentStateStrict=strictObject(gcmConsentState.entries)
+
+/**
+ * GCMv2 consent contract returned by registry scripts (GA, GTM, future Google Ads, …).
+ * `useRegistryScript` wires the `consent.default/update` API when present.
+ */
+exportinterfaceGcmConsentContract{
+/** Forward a `consent`,`<action>`, `<state>` call to the script's transport (dataLayer or gtag). */
+push: (proxy: any,action: 'default'|'update',state: ConsentState)=>void
+}
+
+/** Validate a partial GCMv2 consent state. Logs each issue via the registry-scoped logger. */
+exportfunctionvalidateConsentState(log: typeoflogger,state: ConsentState,source: string){
+constresult=safeParse(gcmConsentStateStrict,state)
+if(result.success)
+return
+for(constissueofresult.issues)
+log.warn(`${source}: ${issue.message} (path: ${issue.path?.map(p=>p.key).join('.')||'<root>'})`)
+}
+
+exportfunctionattachGcmConsent(
+instance: UseScriptContext<any,GcmConsentApi>,
+contract: GcmConsentContract,
+registryKey: string,
+){
+if(instance.consent)
+return
+constlog=logger.withTag(registryKey)
+constpush=(action: 'default'|'update',state: ConsentState)=>{
+validateConsentState(log,state,`consent.${action}()`)
+contract.push(instance.proxy,action,state)
+}
+instance.consent={
+default: (state: ConsentState)=>push('default',state),
+update: (state: ConsentState)=>push('update',state),
+}
+}

packages/script/src/runtime/registry/google-analytics.ts

@@ -1,4 +1,5 @@
 importtype{ConsentState,RegistryScriptInput,UseScriptContext}from'#nuxt-scripts/types'
+importtype{GcmConsentApi}from'./_gcm-consent'
 import{withQuery}from'ufo'
 import{useRegistryScript}from'#nuxt-scripts/utils'
 import{GoogleAnalyticsOptions}from'./schemas'
@@ -111,13 +112,11 @@ export { GoogleAnalyticsOptions }
 
 exporttypeGoogleAnalyticsInput=RegistryScriptInput<typeofGoogleAnalyticsOptions>
 
-exportinterfaceGoogleAnalyticsConsent{
-/** Send `gtag('consent','update', state)` with GCMv2 partial state. */
-update: (state: ConsentState)=>void
-}
+/** @deprecated Use {@link GcmConsentApi} from `#nuxt-scripts/types` instead. */
+exporttypeGoogleAnalyticsConsent=GcmConsentApi
 
-exportfunctionuseScriptGoogleAnalytics<TextendsGoogleAnalyticsApi>(_options?: GoogleAnalyticsInput&{onBeforeGtagStart?: (gtag: GTag)=>void}): UseScriptContext<T,GoogleAnalyticsConsent>{
-constinstance=useRegistryScript<T,typeofGoogleAnalyticsOptions>(_options?.key||'googleAnalytics',(options)=>{
+exportfunctionuseScriptGoogleAnalytics<TextendsGoogleAnalyticsApi>(_options?: GoogleAnalyticsInput&{onBeforeGtagStart?: (gtag: GTag)=>void}): UseScriptContext<T,GcmConsentApi>{
+returnuseRegistryScript<T,typeofGoogleAnalyticsOptions>(_options?.key||'googleAnalytics',(options)=>{
 constdataLayerName=options?.l??'dataLayer'
 constw=import.meta.client ? windowasany : {}
 return{
@@ -133,6 +132,9 @@ export function useScriptGoogleAnalytics<T extends GoogleAnalyticsApi>(_options?
 }
 },
 },
+gcmConsent: {
+push: (proxy: any,action: 'default'|'update',state: ConsentState)=>(proxyasGoogleAnalyticsApi).gtag('consent',action,stateasConsentOptions),
+},
 clientInit: import.meta.server
  ? undefined
  : ()=>{
@@ -157,14 +159,5 @@ export function useScriptGoogleAnalytics<T extends GoogleAnalyticsApi>(_options?
 }
 },
 }
-},_options)asUseScriptContext<T,GoogleAnalyticsConsent>
-
-if(import.meta.client&&!instance.consent){
-instance.consent={
-update: (state: ConsentState)=>{
-;(instance.proxyasunknownasGoogleAnalyticsApi).gtag('consent','update',stateasConsentOptions)
-},
-}
-}
-returninstance
+},_options)asUseScriptContext<T,GcmConsentApi>
 }

packages/script/src/runtime/registry/google-tag-manager.ts

@@ -1,4 +1,5 @@
 importtype{ConsentState,NuxtUseScriptOptions,RegistryScriptInput,UseFunctionType,UseScriptContext}from'#nuxt-scripts/types'
+importtype{GcmConsentApi}from'./_gcm-consent'
 importtype{GTag}from'./google-analytics'
 import{withQuery}from'ufo'
 import{useRegistryScript}from'#nuxt-scripts/utils'
@@ -80,10 +81,8 @@ export { GoogleTagManagerOptions }
 
 exporttypeGoogleTagManagerInput=RegistryScriptInput<typeofGoogleTagManagerOptions>
 
-exportinterfaceGoogleTagManagerConsent{
-/** Send `gtag('consent','update', state)` so the dataLayer receives consent command (GCMv2 partial state). */
-update: (state: ConsentState)=>void
-}
+/** @deprecated Use {@link GcmConsentApi} from `#nuxt-scripts/types` instead. */
+exporttypeGoogleTagManagerConsent=GcmConsentApi
 
 /**
  * Hook to use Google Tag Manager in Nuxt applications
@@ -96,10 +95,8 @@ export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(
  */
 onBeforeGtmStart?: (gtag: DataLayerPush)=>void
 },
-): UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>,T>,GoogleTagManagerConsent>{
-constconsentDataLayerName=options?.l??options?.dataLayer??'dataLayer'
-
-constinstance=useRegistryScript<T,typeofGoogleTagManagerOptions>(
+): UseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>,T>,GcmConsentApi>{
+returnuseRegistryScript<T,typeofGoogleTagManagerOptions>(
 options?.key||'googleTagManager',
 (opts)=>{
 constdataLayerName=opts?.l??opts?.dataLayer??'dataLayer'
@@ -128,6 +125,17 @@ export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(
 }
 },
 },
+gcmConsent: {
+// Match the gtag.js contract: enqueue an `Arguments` object, not a plain Array,
+// so GTM/Tag Assistant/Analytics Debugger recognise the consent command. See #770/#771.
+push: (_proxy: any,action: 'default'|'update',state: ConsentState)=>{
+constdl=(windowasany)[dataLayerName]=(windowasany)[dataLayerName]||[]
+;(function(..._args: any[]){
+// eslint-disable-next-line prefer-rest-params
+dl.push(arguments)
+})('consent',action,state)
+},
+},
 clientInit: import.meta.server
  ? undefined
  : ()=>{
@@ -168,30 +176,5 @@ export function useScriptGoogleTagManager<T extends GoogleTagManagerApi>(
 }
 },
 options,
-)
-
-// Handle callback for cached/pre-initialized scripts (e.g., when ID is in nuxt.config)
-if(import.meta.client&&options?.onBeforeGtmStart){
-constgtag=(windowasany).gtag
-if(gtag)
-options.onBeforeGtmStart(gtag)
-}
-
-consttyped=instanceasUseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>,T>,GoogleTagManagerConsent>
-if(import.meta.client&&!typed.consent){
-typed.consent={
-update: (state: ConsentState)=>{
-constdl=(windowasany)[consentDataLayerName]=(windowasany)[consentDataLayerName]||[]
-// Must push the real `arguments` object — not a
-// spread array — so GTM processes consent and
-// other commands like the official snippet
-;(function(..._args: any[]){
-// Rest params satisfy TypeScript call sites; gtm expects `arguments` on the queue.
-// eslint-disable-next-line prefer-rest-params
-dl.push(arguments)
-})('consent','update',state)
-},
-}
-}
-returntyped
+)asUseScriptContext<UseFunctionType<NuxtUseScriptOptions<T>,T>,GcmConsentApi>
 }

packages/script/src/runtime/registry/schemas.ts

@@ -3,8 +3,11 @@ import { any, array, boolean, custom, literal, minLength, number, object, option
 // Shared GCMv2 consent category value.
 constconsentCategoryValue=union([literal('granted'),literal('denied')])
 
-// Shared GCMv2 consent state (+ GA-only control fields).
-constgcmConsentState=object({
+// Shared GCMv2 consent state (+ GA-only control fields). Lenient at schema-parse
+// time (extra keys pass through); the runtime `consent.*` API rebuilds a strict
+// variant from these entries so typos surface as a `consola` warning without
+// breaking the dev schema check.
+exportconstgcmConsentState=object({
 ad_storage: optional(consentCategoryValue),
 ad_user_data: optional(consentCategoryValue),
 ad_personalization: optional(consentCategoryValue),

packages/script/src/runtime/types.ts

@@ -80,6 +80,17 @@ export interface ConsentState {
 wait_for_update?: number
 }
 
+/**
+ * Auto-attached `consent` API on scripts that adhere to the GCMv2 Consent Mode
+ * contract (Google Analytics, Google Tag Manager, …).
+ */
+exportinterfaceGcmConsentApi{
+/** Push `['consent','default', state]` (or equivalent gtag call) with GCMv2 partial state. */
+default: (state: ConsentState)=>void
+/** Push `['consent','update', state]` (or equivalent gtag call) with GCMv2 partial state. */
+update: (state: ConsentState)=>void
+}
+
 exporttypeUseScriptContext<TextendsRecord<symbol|string,any>,C=unknown>=VueScriptInstance<T>&{
 /**
  * Remove and reload the script. Useful for scripts that need to re-execute

packages/script/src/runtime/utils.ts

@@ -9,12 +9,14 @@ import type {
 UseFunctionType,
 UseScriptContext,
 }from'#nuxt-scripts/types'
+importtype{GcmConsentContract}from'./registry/_gcm-consent'
 import{defu}from'defu'
 import{createError,useRuntimeConfig}from'nuxt/app'
 import{parseQuery,parseURL,withQuery}from'ufo'
 import{parse}from'valibot'
 import{useScript}from'./composables/useScript'
 import{createNpmScriptStub}from'./npm-script-stub'
+import{attachGcmConsent}from'./registry/_gcm-consent'
 
 // Dev-only: stack trace parsing for component location detection (only referenced inside import.meta.dev)
 constURL_MATCH_RE=/https?:\/\/[^/]+\/_nuxt\/(.+\.vue)(?:\?[^)]*)?:(\d+):(\d+)/
@@ -42,6 +44,11 @@ type OptionsFn<O> = (options: InferIfSchema<O>, ctx: { scriptInput?: UseScriptIn
 schema?: OextendsObjectSchema<any,any>|UnionSchema<any,any> ? O : undefined
 clientInit?: ()=>void|Promise<any>
 scriptMode?: 'external'|'npm'// NEW: external = CDN script (default), npm = NPM package only
+/**
+ * Opt-in: this script consumes GCMv2 Consent Mode. `useRegistryScript` auto-attaches
+ * a `consent: { default, update }` API + dev validation against the canonical schema.
+ */
+gcmConsent?: GcmConsentContract
 })
 
 exportfunctionscriptRuntimeConfig<TextendskeyofScriptRegistry>(key: T){
@@ -173,5 +180,10 @@ export function useRegistryScript<T extends Record<string | symbol, any>, O = Em
 options.clientInit?.()
 }
 }
-returnuseScript<T>(scriptInput,scriptOptionsasNuxtUseScriptOptions<T>)
+constinstance=useScript<T>(scriptInput,scriptOptionsasNuxtUseScriptOptions<T>)
+
+if(import.meta.client&&options.gcmConsent)
+attachGcmConsent(instanceasany,options.gcmConsent,String(registryKey))
+
+returninstance
 }