@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/features/consent/cookieScript.ts

@@ -0,0 +1,53 @@
+import { deniedConsentState, type ConsentAdapter, type ConsentState } from '../contracts/consent'
+
+/** Provider state is authoritative; neither event names nor an action alone grant categories. */
+export function normalizeCookieScript(input: unknown): ConsentState {
+  if (!input || typeof input !== 'object') return deniedConsentState()
+  const state = input as { action?: unknown; categories?: unknown }
+  if ((state.action !== 'accept' && state.action !== 'reject') || !Array.isArray(state.categories) ||
+    !state.categories.every((category) => typeof category === 'string')) return deniedConsentState()
+  const accepted = state.action === 'accept' ? state.categories : []
+  return {
+    version: 1, necessary: true, ready: true,
+    preferences: accepted.includes('functionality'), analytics: accepted.includes('performance'),
+    marketing: accepted.includes('targeting'),
+  }
+}
+
+type CookieScriptWindow = Window & { CookieScript?: { instance?: { currentState?: () => unknown; show?: () => void } } }
+const EVENTS = ['CookieScriptLoaded', 'CookieScriptAccept', 'CookieScriptAcceptAll', 'CookieScriptReject', 'CookieScriptClose'] as const
+
+/** Construct without side effects; the root subscribes before installing its owned CMP. */
+export function cookieScriptAdapter(window: Window): ConsentAdapter {
+  const target = window as CookieScriptWindow
+  const listeners = new Set<(state: ConsentState) => void>()
+  let reopenFailed = false
+  const read = (): ConsentState => {
+    try {
+      const instance = target.CookieScript?.instance
+      if (reopenFailed || typeof instance?.currentState !== 'function' || typeof instance.show !== 'function') return deniedConsentState()
+      return normalizeCookieScript(instance.currentState())
+    } catch { return deniedConsentState() }
+  }
+  const publish = () => { const state = read(); for (const listener of listeners) listener({ ...state }) }
+  const change = () => { reopenFailed = false; publish() }
+  return {
+    read,
+    subscribe(listener) {
+      if (listeners.size === 0) for (const event of EVENTS) window.addEventListener(event, change)
+      listeners.add(listener)
+      let subscribed = true
+      return () => {
+        if (!subscribed) return
+        subscribed = false
+        listeners.delete(listener)
+        if (listeners.size === 0) for (const event of EVENTS) window.removeEventListener(event, change)
+      }
+    },
+    openPreferences() {
+      if (!read().ready) { publish(); return }
+      try { target.CookieScript!.instance!.show!() }
+      catch { reopenFailed = true; publish() }
+    },
+  }
+}

package/src/features/consent/custom.ts

@@ -0,0 +1,89 @@
+import { ConsentStateSchema, deniedConsentState, type ConsentAdapter, type ConsentState } from '../contracts/consent'
+
+/** Code-owned registration: choose one stable adapter or one normalized-event bridge. */
+export type CustomConsentRegistration =
+  | { adapter: ConsentAdapter; openPreferences?: never }
+  | { adapter?: never; openPreferences: () => void }
+
+export function customConsentAdapter(window: Window, registration?: CustomConsentRegistration): ConsentAdapter {
+  const listeners = new Set<(state: ConsentState) => void>()
+  const adapter = registration?.adapter
+  const registered = adapter && registration.openPreferences === undefined &&
+    typeof adapter.read === 'function' && typeof adapter.subscribe === 'function' && typeof adapter.openPreferences === 'function'
+  const reopen = registration?.openPreferences
+  const bridge = adapter === undefined && typeof registration?.openPreferences === 'function'
+  let state = deniedConsentState()
+  let failed = false
+  let subscription = 0
+  const hasReopen = () => registered
+    ? registration?.adapter === adapter && registration.openPreferences === undefined && typeof adapter.openPreferences === 'function'
+    : bridge && registration?.adapter === undefined && typeof reopen === 'function' && registration?.openPreferences === reopen
+  let cleanup: (() => void) | undefined
+  const normalize = (input: unknown): ConsentState => {
+    try {
+      const result = ConsentStateSchema.safeParse(input)
+      return result.success ? result.data : deniedConsentState()
+    } catch { return deniedConsentState() }
+  }
+  const publish = (input: unknown) => {
+    state = normalize(input)
+    for (const listener of listeners) listener({ ...state })
+  }
+  const change = (event: Event) => { failed = false; publish(hasReopen() ? (event as CustomEvent<unknown>).detail : deniedConsentState()) }
+  const read = (): ConsentState => {
+    if (failed || !hasReopen()) return deniedConsentState()
+    if (registered) {
+      try { state = normalize(adapter.read()); return { ...state } }
+      catch { state = deniedConsentState(); return { ...state } }
+    }
+    return bridge && listeners.size > 0 ? { ...state } : deniedConsentState()
+  }
+  return {
+    read,
+    subscribe(listener) {
+      listeners.add(listener)
+      if (listeners.size === 1) {
+        const current = ++subscription
+        state = deniedConsentState()
+        failed = false
+        if (registered) {
+          try {
+            let active = false
+            const off = adapter.subscribe((next) => {
+              if (!active || current !== subscription || !listeners.size) return
+              failed = false
+              publish(hasReopen() ? next : deniedConsentState())
+            })
+            if (typeof off !== 'function') throw new Error('Custom subscription must supply cleanup.')
+            active = true
+            cleanup = off
+            publish(read())
+          } catch { ++subscription; failed = true; publish(deniedConsentState()) }
+        } else if (bridge) {
+          window.addEventListener('u90:consent', change)
+          cleanup = () => window.removeEventListener('u90:consent', change)
+        }
+      }
+      let subscribed = true
+      return () => {
+        if (!subscribed) return
+        subscribed = false
+        listeners.delete(listener)
+        if (listeners.size === 0) {
+          ++subscription
+          try { cleanup?.() } catch { /* Detached listeners cannot restore this authority. */ }
+          cleanup = undefined
+          state = deniedConsentState()
+          failed = true
+        }
+      }
+    },
+    openPreferences() {
+      if (!read().ready) { publish(deniedConsentState()); return }
+      try {
+        if (registered) adapter.openPreferences()
+        else if (bridge) reopen!()
+      } catch { failed = true; publish(deniedConsentState()) }
+    },
+  }
+}

package/src/features/consent/defaults.ts

@@ -0,0 +1,40 @@
+/** Shared server/bootstrap and defensive driver initializer. No tenant/category authority. */
+export type GoogleConsentWindow = Window & {
+  __u90ConsentDefaultsV1?: true
+  dataLayer?: unknown[]
+  gtag?: (...args: unknown[]) => void
+}
+export function initializeConsentDefaults(window: Window): void {
+  const target = window as GoogleConsentWindow
+  if (target.__u90ConsentDefaultsV1 === true) {
+    if (!Array.isArray(target.dataLayer) || typeof target.gtag !== 'function')
+      throw new Error('Consent defaults are unavailable.')
+    return
+  }
+  if (
+    target.gtag !== undefined ||
+    (target.dataLayer !== undefined &&
+      (!Array.isArray(target.dataLayer) || target.dataLayer.length > 0))
+  )
+    throw new Error(
+      'Consent defaults ownership conflicts with unmanaged Google code. Reload after correcting setup.',
+    )
+  target.dataLayer = target.dataLayer || []
+  target.gtag = function () {
+    // Preserve Google's documented gtag queue payload shape.
+    // eslint-disable-next-line prefer-rest-params
+    target.dataLayer!.push(arguments)
+  }
+  target.gtag('consent', 'default', {
+    analytics_storage: 'denied',
+    ad_storage: 'denied',
+    ad_user_data: 'denied',
+    ad_personalization: 'denied',
+    functionality_storage: 'denied',
+    personalization_storage: 'denied',
+    security_storage: 'granted',
+  })
+  target.__u90ConsentDefaultsV1 = true
+}
+export const CONSENT_DEFAULTS_ID = 'u90-consent-defaults-v1'
+export const CONSENT_DEFAULTS_SCRIPT = `(${initializeConsentDefaults.toString()})(window);`

package/src/features/consent/drivers.ts

@@ -0,0 +1,233 @@
+import {
+  classifyManagedIntegration,
+  deniedConsentState,
+  ManagedIntegrationSchema,
+  type ConsentState,
+  type IntegrationDriver,
+  type ManagedIntegration,
+} from '../contracts/consent'
+import { ConsentReloadRequiredError, executableFingerprint } from './loader'
+import { initializeConsentDefaults, type GoogleConsentWindow } from './defaults'
+
+type BrowserWindow = GoogleConsentWindow & {
+  _uxa?: unknown[][]
+  [key: `ga-disable-${string}`]: boolean
+}
+type Execution = {
+  integration: ManagedIntegration
+  kind: ReturnType<typeof classifyManagedIntegration>
+  attempted: boolean
+  loaded: boolean
+  running: boolean
+  allowed: boolean
+  configured: boolean
+  uncertain: boolean
+  element?: HTMLScriptElement
+  loading?: Promise<void>
+  lastPage?: string
+}
+export const CONSENT_LOAD_TIMEOUT_MS = 10000
+/** Private built-in driver. Its synchronous veto is independent of async loader completion. */
+export function createBrowserConsentDriver(window: Window): IntegrationDriver & {
+  configure(integrations: ManagedIntegration[]): void
+  setPermission(state: ConsentState, mode: 'basic' | 'advanced'): void
+  suspend(value: boolean): void
+  page(path: string): void
+  attempted(): boolean
+  googleAttempted(): boolean
+} {
+  const target = window as BrowserWindow
+  const records = new Map<string, Execution>()
+  let state = deniedConsentState()
+  let mode: 'basic' | 'advanced' = 'basic'
+  let suspended = false
+  let path = window.location.pathname
+  const permitted = (record: Execution) =>
+    !suspended &&
+    state.ready &&
+    state[record.integration.category] &&
+    record.allowed &&
+    (record.kind.kind !== 'ga4' || state.analytics)
+  const signal = () => {
+    if (target.__u90ConsentDefaultsV1 !== true) return
+    target.gtag?.('consent', 'update', {
+      analytics_storage: state.ready && state.analytics ? 'granted' : 'denied',
+      ad_storage: state.ready && state.marketing ? 'granted' : 'denied',
+      ad_user_data: state.ready && state.marketing ? 'granted' : 'denied',
+      ad_personalization: state.ready && state.marketing ? 'granted' : 'denied',
+      functionality_storage: state.ready && state.preferences ? 'granted' : 'denied',
+      personalization_storage: state.ready && state.preferences ? 'granted' : 'denied',
+      security_storage: 'granted',
+    })
+  }
+  const veto = (record: Execution) => {
+    if (record.kind.kind === 'ga4')
+      target[`ga-disable-${record.kind.measurementId}`] = !permitted(record)
+  }
+  const pageview = (record: Execution) => {
+    if (
+      record.kind.kind !== 'ga4' ||
+      !record.loaded ||
+      !permitted(record) ||
+      record.lastPage === path
+    )
+      return
+    record.lastPage = path
+    target.gtag!('event', 'page_view', {
+      send_to: record.kind.measurementId,
+      page_path: path,
+      page_location: new URL(path, window.location.origin).href,
+      page_title: window.document.title,
+    })
+  }
+  const optout = () => {
+    target._uxa = target._uxa || []
+    target._uxa.push(['optout'])
+  }
+  const driver = {
+    // Preserve proven teardown for executed code; policy edits never promote catalogue authority.
+    configure(integrations: ManagedIntegration[]) {
+      for (const record of records.values()) {
+        const next = integrations.find((row) => row.id === record.integration.id)
+        if (next && executableFingerprint(next) === executableFingerprint(record.integration))
+          record.integration = next
+        else {
+          record.running = false
+          record.allowed = false
+        }
+        veto(record)
+      }
+    },
+    setPermission(next: ConsentState, nextMode: 'basic' | 'advanced') {
+      const changed = JSON.stringify(state) !== JSON.stringify(next)
+      state = { ...next }
+      mode = nextMode
+      for (const record of records.values()) {
+        record.allowed = record.running && state.ready && state[record.integration.category]
+        if (!permitted(record)) record.lastPage = undefined
+        veto(record)
+      }
+      if (changed) signal()
+      for (const record of records.values()) pageview(record)
+    },
+    suspend(value: boolean) {
+      suspended = value
+      for (const record of records.values()) veto(record)
+    },
+    page(next: string) {
+      path = next
+      for (const record of records.values()) pageview(record)
+    },
+    attempted: () => [...records.values()].some((record) => record.attempted),
+    googleAttempted: () =>
+      [...records.values()].some((record) => record.attempted && record.kind.kind === 'ga4'),
+    async start(input: ManagedIntegration) {
+      const integration = ManagedIntegrationSchema.parse(input)
+      let record = records.get(integration.id)
+      if (!record) {
+        record = {
+          integration,
+          kind: classifyManagedIntegration(integration),
+          attempted: false,
+          loaded: false,
+          running: false,
+          allowed: false,
+          configured: false,
+          uncertain: false,
+        }
+        records.set(integration.id, record)
+      }
+      if (record.uncertain)
+        throw new ConsentReloadRequiredError(
+          'Reload required after uncertain integration initialization.',
+        )
+      const current = record
+      current.running = true
+      current.integration = integration
+      current.allowed = !suspended && state.ready && state[integration.category]
+      if (
+        !current.allowed &&
+        !(current.kind.kind === 'ga4' && mode === 'advanced' && state.ready && !suspended)
+      )
+        return
+      if (current.kind.kind === 'ga4') {
+        initializeConsentDefaults(window)
+        signal()
+        veto(current)
+        if (!current.configured) {
+          target.gtag!('js', new Date())
+          target.gtag!('config', current.kind.measurementId, { send_page_view: false })
+          current.configured = true
+        }
+      }
+      if (current.loaded) {
+        veto(current)
+        pageview(current)
+        return
+      }
+      if (!current.loading) {
+        current.loading = new Promise<void>((resolve, reject) => {
+          const script = window.document.createElement('script')
+          script.async = true
+          for (const [key, value] of Object.entries(integration.attributes ?? {}))
+            script.setAttribute(key, value)
+          if (script.id && window.document.getElementById(script.id)) {
+            reject(Error('Integration element ID is already owned.'))
+            return
+          }
+          script.src = integration.src
+          script.dataset.u90Integration = integration.id
+          current.element = script
+          const finish = () => {
+            window.clearTimeout(timer)
+            script.onload = null
+            script.onerror = null
+          }
+          const timer = window.setTimeout(() => {
+            finish()
+            current.uncertain = true
+            reject(new ConsentReloadRequiredError('Integration load timed out; reload required.'))
+          }, CONSENT_LOAD_TIMEOUT_MS)
+          script.onload = () => {
+            finish()
+            current.loaded = true
+            resolve()
+          }
+          script.onerror = () => {
+            finish()
+            script.remove()
+            current.element = undefined
+            reject(Error('Integration failed to load. Retry consent setup.'))
+          }
+          current.attempted = true
+          window.document.head.appendChild(script)
+        }).finally(() => {
+          current.loading = undefined
+        })
+      }
+      await current.loading
+      veto(current)
+      if (current.kind.kind === 'contentsquare' && !permitted(current)) optout()
+      pageview(current)
+    },
+    async stop(id: string): Promise<'stopped' | 'reload-required'> {
+      const record = records.get(id)
+      if (!record) return 'stopped'
+      record.running = false
+      record.allowed = false
+      record.lastPage = undefined
+      veto(record)
+      if (!record.attempted) return 'stopped'
+      if (record.kind.kind === 'contentsquare') optout()
+      if (
+        record.kind.kind === 'ga4' &&
+        !record.uncertain &&
+        record.integration.revocation === 'stop'
+      )
+        return 'stopped'
+      // Removing a node cannot undo downloaded or executing third-party code.
+      return 'reload-required'
+    },
+  }
+  return driver
+}

package/src/features/consent/loader.ts

@@ -0,0 +1,248 @@
+import {
+  ConsentStateSchema,
+  type ConsentState,
+  type IntegrationDriver,
+  type ManagedIntegration,
+} from '../contracts/consent'
+
+export class ConsentReloadRequiredError extends Error {}
+const OPERATION_TIMEOUT_MS = 10000
+function bounded<T>(operation: Promise<T>, timeout: () => void): Promise<T> {
+  let timer: ReturnType<typeof setTimeout>
+  return Promise.race([
+    operation,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => {
+        timeout()
+        reject(new ConsentReloadRequiredError('Consent operation timed out; reload required.'))
+      }, OPERATION_TIMEOUT_MS)
+    }),
+  ]).finally(() => clearTimeout(timer))
+}
+
+type RecordState = {
+  integration: ManagedIntegration
+  fingerprint: string
+  desired: boolean
+  attempted: boolean
+  active: boolean
+  revoked: boolean
+  start?: Promise<void>
+  stop?: Promise<void>
+  error?: string
+}
+type Store = {
+  records: Map<string, RecordState>
+  reloadRequired: boolean
+  error: string | null
+  listeners: Set<() => void>
+}
+const stores = new WeakMap<IntegrationDriver, Store>()
+function storeFor(driver: IntegrationDriver): Store {
+  let store = stores.get(driver)
+  if (!store) {
+    store = { records: new Map(), reloadRequired: false, error: null, listeners: new Set() }
+    stores.set(driver, store)
+  }
+  return store
+}
+export function executableFingerprint(integration: ManagedIntegration): string {
+  return JSON.stringify([
+    integration.src,
+    Object.entries(integration.attributes ?? {}).sort(([a], [b]) => a.localeCompare(b)),
+  ])
+}
+/** Internal diagnostics; only the fixed loader contract is exposed by the package. */
+export function consentLoaderStatus(driver: IntegrationDriver) {
+  const { reloadRequired, error } = storeFor(driver)
+  return { reloadRequired, error }
+}
+export function observeConsentLoader(driver: IntegrationDriver, listener: () => void) {
+  const listeners = storeFor(driver).listeners
+  listeners.add(listener)
+  return () => {
+    listeners.delete(listener)
+  }
+}
+function publish(store: Store) {
+  for (const listener of store.listeners) listener()
+}
+export function requireConsentReload(driver: IntegrationDriver, reason: string) {
+  const store = storeFor(driver)
+  store.reloadRequired = true
+  store.error = reason
+  for (const record of store.records.values()) {
+    record.desired = false
+    void stopRecord(driver, store, record).catch(() => {})
+  }
+  publish(store)
+}
+function stopRecord(
+  driver: IntegrationDriver,
+  store: Store,
+  record: RecordState,
+  finalize = false,
+): Promise<void> {
+  if (!record.attempted || (record.revoked && !finalize)) return record.stop ?? Promise.resolve()
+  record.revoked = true
+  record.active = false
+  // Invoke before constructing/awaiting any queue: drivers synchronously latch their veto.
+  let operation: Promise<'stopped' | 'reload-required'>
+  try {
+    operation = driver.stop(record.integration.id)
+  } catch (cause) {
+    operation = Promise.reject(cause)
+  }
+  const stop = bounded(operation, () =>
+    requireConsentReload(driver, 'Reload to apply consent changes. Integration stop timed out.'),
+  )
+    .then(
+      (result) => {
+        if (result === 'reload-required' || record.integration.revocation === 'reload')
+          requireConsentReload(
+            driver,
+            'Reload to apply consent changes. Previously started code requires a fresh document.',
+          )
+      },
+      (cause) => {
+        requireConsentReload(
+          driver,
+          `Reload to apply consent changes. Integration stop failed: ${cause instanceof Error ? cause.message : 'unavailable'}`,
+        )
+        throw cause
+      },
+    )
+    .finally(() => {
+      if (record.stop === stop) record.stop = undefined
+      publish(store)
+    })
+  record.stop = stop
+  return stop
+}
+function startRecord(driver: IntegrationDriver, store: Store, record: RecordState): Promise<void> {
+  if (record.start) return record.start
+  if (!record.desired || store.reloadRequired || record.active)
+    return record.stop ?? Promise.resolve()
+  const begin = async () => {
+    if (record.stop) await record.stop
+    if (!record.desired || store.reloadRequired || record.active) return
+    record.attempted = true
+    record.revoked = false
+    record.error = undefined
+    try {
+      let expired = false
+      const operation = driver.start(record.integration)
+      void operation.then(
+        () => {
+          if (expired) void stopRecord(driver, store, record, true).catch(() => {})
+        },
+        () => {},
+      )
+      await bounded(operation, () => {
+        expired = true
+        requireConsentReload(
+          driver,
+          'Reload to apply consent changes. Integration initialization timed out.',
+        )
+      })
+      if (!record.desired || record.revoked || store.reloadRequired) {
+        await stopRecord(driver, store, record, true)
+      } else record.active = true
+    } catch (cause) {
+      if (cause instanceof ConsentReloadRequiredError) requireConsentReload(driver, cause.message)
+      record.error = cause instanceof Error ? cause.message : 'Integration initialization failed'
+      store.error = record.error
+      publish(store)
+      throw cause
+    }
+  }
+  // begin invokes start synchronously until its first await.
+  const starting = begin().finally(() => {
+    if (record.start === starting) record.start = undefined
+    publish(store)
+  })
+  record.start = starting
+  return starting
+}
+export function createConsentLoader(driver: IntegrationDriver): {
+  apply(state: ConsentState, integrations: ManagedIntegration[]): Promise<void>
+  dispose(): void
+} {
+  const store = storeFor(driver)
+  let disposed = false
+  return {
+    async apply(input, integrations) {
+      if (disposed) return
+      const parsed = ConsentStateSchema.safeParse(input)
+      const state = parsed.success ? parsed.data : null
+      const incoming = new Map(integrations.map((row) => [row.id, row]))
+      const operations: Promise<void>[] = []
+      // Record *all* restrictions first, independently of asynchronous failures.
+      for (const [id, record] of store.records) {
+        const next = incoming.get(id)
+        if (next && executableFingerprint(next) !== record.fingerprint && record.attempted)
+          requireConsentReload(
+            driver,
+            'Reload to apply consent changes. An executed integration was replaced.',
+          )
+        record.desired = !store.reloadRequired && !!next && !!state?.ready && state[next.category]
+        if (next && executableFingerprint(next) === record.fingerprint) record.integration = next
+        if (!record.desired) operations.push(stopRecord(driver, store, record))
+      }
+      // A different ID must not slip past a stop that may latch document reload.
+      const pendingStops = [...store.records.values()].flatMap((record) =>
+        record.stop ? [record.stop] : [],
+      )
+      const stopped = pendingStops.length ? Promise.allSettled(pendingStops) : undefined
+      for (const integration of integrations) {
+        let record = store.records.get(integration.id)
+        if (
+          !record ||
+          (!record.attempted && executableFingerprint(integration) !== record.fingerprint)
+        ) {
+          record = {
+            integration,
+            fingerprint: executableFingerprint(integration),
+            desired: false,
+            attempted: false,
+            active: false,
+            revoked: false,
+          }
+          store.records.set(integration.id, record)
+        }
+        record.desired = !store.reloadRequired && !!state?.ready && state[integration.category]
+        if (record.desired) {
+          const current = record
+          operations.push(
+            (stopped
+              ? stopped.then(() => {
+                  if (!disposed) return startRecord(driver, store, current)
+                })
+              : startRecord(driver, store, current)
+            ).then(async () => {
+              // A regrant during an unresolved start/stop resumes only once both settled.
+              if (!disposed && current.desired && !current.active && !store.reloadRequired)
+                await startRecord(driver, store, current)
+            }),
+          )
+        }
+      }
+      const results = await Promise.allSettled(operations)
+      const failure = results.find(
+        (result): result is PromiseRejectedResult => result.status === 'rejected',
+      )
+      if (failure) throw failure.reason
+      if (!store.reloadRequired && ![...store.records.values()].some((record) => record.error))
+        store.error = null
+      publish(store)
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      for (const record of store.records.values()) {
+        record.desired = false
+        void stopRecord(driver, store, record).catch(() => {})
+      }
+    },
+  }
+}