@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/features/consent/registry.ts

@@ -0,0 +1,398 @@
+import {
+  classifyManagedIntegration,
+  ConsentInstallationSchema,
+  ConsentStateSchema,
+  deniedConsentState,
+  type ConsentAdapter,
+  type ConsentInstallation,
+  type ConsentState,
+} from '../contracts/consent'
+import { cookieScriptAdapter } from './cookieScript'
+import { customConsentAdapter, type CustomConsentRegistration } from './custom'
+import { createBrowserConsentDriver, CONSENT_LOAD_TIMEOUT_MS } from './drivers'
+import {
+  consentLoaderStatus,
+  createConsentLoader,
+  observeConsentLoader,
+  requireConsentReload,
+} from './loader'
+
+type Snapshot = {
+  state: ConsentState
+  ready: boolean
+  error: string | null
+  reloadRequired: boolean
+}
+type Identity = {
+  endpoint: string
+  provider: string
+  source: string
+  adapter?: ConsentAdapter
+  owner?: CustomConsentRegistration
+  reopen?: () => void
+}
+const registries = new WeakMap<Document, ReturnType<typeof createRegistry>>()
+export function consentRegistry(window: Window) {
+  let registry = registries.get(window.document)
+  if (!registry) {
+    registry = createRegistry(window)
+    registries.set(window.document, registry)
+  }
+  return registry
+}
+function identity(
+  endpoint: string,
+  installation: ConsentInstallation,
+  registration?: CustomConsentRegistration,
+): Identity {
+  return {
+    endpoint,
+    provider: installation.provider,
+    source: installation.scriptURL ?? '',
+    ...(installation.provider === 'custom'
+      ? registration?.adapter
+        ? { adapter: registration.adapter }
+        : { owner: registration, reopen: registration?.openPreferences }
+      : {}),
+  }
+}
+function same(a: Identity, b: Identity) {
+  return (
+    a.endpoint === b.endpoint &&
+    a.provider === b.provider &&
+    a.source === b.source &&
+    a.adapter === b.adapter &&
+    a.owner === b.owner &&
+    a.reopen === b.reopen
+  )
+}
+function validRegistration(registration?: CustomConsentRegistration) {
+  if (!registration) return false
+  if (registration.adapter !== undefined)
+    return (
+      registration.openPreferences === undefined &&
+      !!registration.adapter &&
+      ['read', 'subscribe', 'openPreferences'].every(
+        (key) => typeof registration.adapter?.[key as keyof ConsentAdapter] === 'function',
+      )
+    )
+  return typeof registration.openPreferences === 'function'
+}
+function createRegistry(window: Window) {
+  const driver = createBrowserConsentDriver(window)
+  const loader = createConsentLoader(driver)
+  const listeners = new Set<() => void>()
+  const owners = new Set<object>()
+  let endpoint: string | undefined
+  let enabled = false
+  let installation: ConsentInstallation | undefined
+  let registration: CustomConsentRegistration | undefined
+  let installed: Identity | undefined
+  let adapter: ConsentAdapter | undefined
+  let unsubscribe: (() => void) | undefined
+  let generation = 0
+  let activated = false
+  let attempted = false
+  let script: HTMLScriptElement | undefined
+  let providerFailed = false
+  let providerError: string | null = null
+  let timer: number | undefined
+  let loadTimer: number | undefined
+  let raw = deniedConsentState()
+  let snapshot: Snapshot = { state: raw, ready: false, error: null, reloadRequired: false }
+  const clearTimer = () => {
+    if (timer !== undefined) window.clearTimeout(timer)
+    timer = undefined
+  }
+  // Embedding a banner does not make it a consent authority for U90-managed scripts.
+  const embedOnly = () => installation?.provider === 'custom' && registration === undefined
+  const registrationComplete = () =>
+    installation?.provider !== 'custom' || validRegistration(registration)
+  const effective = () =>
+    enabled && owners.size === 1 && !!unsubscribe && !providerFailed && registrationComplete()
+      ? raw
+      : deniedConsentState()
+  const publish = () => {
+    const state = effective()
+    const status = consentLoaderStatus(driver)
+    const next = {
+      state: { ...state },
+      ready: state.ready,
+      error: status.reloadRequired
+        ? status.error
+        : !registrationComplete() && !embedOnly() && enabled
+          ? 'Custom consent registration is incomplete. Supply one adapter or a preferences callback.'
+          : (providerError ?? status.error),
+      reloadRequired: status.reloadRequired,
+    }
+    if (JSON.stringify(next) !== JSON.stringify(snapshot)) {
+      snapshot = next
+      for (const listener of listeners) listener()
+    }
+  }
+  observeConsentLoader(driver, () => {
+    if (consentLoaderStatus(driver).reloadRequired)
+      driver.setPermission(deniedConsentState(), installation?.googleMode ?? 'basic')
+    publish()
+  })
+  const reconcile = () => {
+    const state = effective()
+    const mode = installation?.googleMode ?? 'basic'
+    const blocked = consentLoaderStatus(driver).reloadRequired
+    driver.configure(installation?.integrations ?? [])
+    driver.setPermission(blocked ? deniedConsentState() : state, mode)
+    // Advanced mode is a request exception only for classified Google code. Generic rows stay category-gated.
+    const advanced = !blocked && state.ready && mode === 'advanced'
+    const integrations = installation?.integrations ?? []
+    const selected = advanced
+      ? integrations.filter(
+          (row) => state[row.category] || classifyManagedIntegration(row).kind === 'ga4',
+        )
+      : integrations
+    void loader.apply(advanced ? { ...state, analytics: true } : state, selected).catch(() => {
+      publish()
+    })
+    publish()
+  }
+  const receive = (value: unknown) => {
+    const parsed = ConsentStateSchema.safeParse(value)
+    raw = parsed.success ? parsed.data : deniedConsentState()
+    providerError = raw.ready ? null : 'Consent preferences are unavailable. Retry consent setup.'
+    if (raw.ready) clearTimer()
+    reconcile()
+  }
+  const readAdapter = () => {
+    if (!adapter) {
+      reconcile()
+      return
+    }
+    try {
+      receive(adapter?.read())
+    } catch {
+      receive(undefined)
+    }
+  }
+  const disconnect = () => {
+    ++generation
+    try {
+      unsubscribe?.()
+    } catch {
+      /* authority is already invalid */
+    }
+    unsubscribe = undefined
+    clearTimer()
+    raw = deniedConsentState()
+  }
+  const subscribe = () => {
+    if (!adapter || unsubscribe) return
+    const current = ++generation
+    try {
+      unsubscribe = adapter.subscribe((value) => {
+        if (current === generation && owners.size === 1 && !providerFailed) receive(value)
+      })
+      if (typeof unsubscribe !== 'function') throw Error('Subscription unavailable')
+      activated = true
+      readAdapter()
+    } catch {
+      providerFailed = true
+      providerError = 'Consent subscription unavailable. Retry consent setup.'
+      reconcile()
+    }
+  }
+  const watchReadiness = () => {
+    clearTimer()
+    if (!raw.ready)
+      timer = window.setTimeout(() => {
+        raw = deniedConsentState()
+        providerError = 'Consent provider did not become ready. Retry consent setup.'
+        reconcile()
+      }, CONSENT_LOAD_TIMEOUT_MS)
+  }
+  const install = () => {
+    if (
+      !installation ||
+      !enabled ||
+      providerFailed ||
+      (!registrationComplete() && !embedOnly()) ||
+      owners.size !== 1 ||
+      consentLoaderStatus(driver).reloadRequired
+    )
+      return
+    if (!adapter && !embedOnly()) {
+      if (installation.provider === 'cookiescript') {
+        if ((window as Window & { CookieScript?: unknown }).CookieScript !== undefined) {
+          providerFailed = true
+          providerError =
+            'CookieScript ownership conflicts with an already installed provider. Correct setup and reload.'
+          reconcile()
+          return
+        }
+        adapter = cookieScriptAdapter(window)
+      } else {
+        if (!validRegistration(registration)) {
+          providerError =
+            'Custom consent registration is incomplete. Supply one adapter or a preferences callback.'
+          reconcile()
+          return
+        }
+        adapter = customConsentAdapter(window, registration)
+      }
+    }
+    const wasSubscribed = !!unsubscribe
+    subscribe() // subscription and immediate read precede insertion
+    if (providerFailed) return
+    if (!attempted) {
+      script = window.document.createElement('script')
+      script.async = true
+      script.src = installation.scriptURL!
+      script.dataset.u90ConsentProvider = installation.provider
+      const ownedScript = script
+      loadTimer = window.setTimeout(() => {
+        if (script !== ownedScript) return
+        providerFailed = true
+        raw = deniedConsentState()
+        providerError = 'Consent provider load timed out. Reload after checking setup.'
+        requireConsentReload(driver, providerError)
+        reconcile()
+      }, CONSENT_LOAD_TIMEOUT_MS)
+      script.onload = () => {
+        if (script !== ownedScript) return
+        window.clearTimeout(loadTimer)
+        loadTimer = undefined
+        if (!providerFailed && adapter) {
+          readAdapter()
+          watchReadiness()
+        }
+      }
+      script.onerror = () => {
+        if (script !== ownedScript) return
+        window.clearTimeout(loadTimer)
+        loadTimer = undefined
+        providerFailed = true
+        providerError = 'Consent provider failed to load. Retry consent setup.'
+        raw = deniedConsentState()
+        script?.remove()
+        script = undefined
+        clearTimer()
+        reconcile()
+      }
+      attempted = true
+      window.document.head.appendChild(script)
+    }
+    if (adapter && !wasSubscribed) watchReadiness()
+  }
+  return {
+    read: () => snapshot,
+    subscribe(listener: () => void) {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    attach(owner: object) {
+      owners.add(owner)
+      driver.suspend(true)
+    },
+    detach(owner: object) {
+      owners.delete(owner)
+      driver.suspend(true)
+      // StrictMode's same-turn replay retains installation; a lasting owner loss revokes.
+      queueMicrotask(() => {
+        if (owners.size === 0) {
+          disconnect()
+          reconcile()
+        }
+      })
+    },
+    commit(
+      owner: object,
+      nextEndpoint: string,
+      nextEnabled: boolean,
+      input?: ConsentInstallation,
+      custom?: CustomConsentRegistration,
+    ) {
+      if (!owners.has(owner)) return
+      const parsed = input === undefined ? null : ConsentInstallationSchema.safeParse(input)
+      const next = parsed?.success ? parsed.data : undefined
+      if (endpoint !== undefined && endpoint !== nextEndpoint) {
+        disconnect()
+        enabled = false
+        reconcile()
+        if (activated || attempted || driver.attempted())
+          requireConsentReload(
+            driver,
+            'Reload to apply consent changes. The site consent authority changed.',
+          )
+        else {
+          adapter = undefined
+          installed = undefined
+        }
+      }
+      endpoint = nextEndpoint
+      if (next && installation?.googleMode !== next.googleMode && driver.googleAttempted())
+        requireConsentReload(
+          driver,
+          'Reload to apply consent changes. Google consent mode changed.',
+        )
+      installation = next
+      registration = custom
+      enabled = !!nextEnabled && !!next && next.provider !== 'none'
+      driver.suspend(owners.size !== 1)
+      if (enabled) {
+        const nextIdentity = identity(nextEndpoint, next!, custom)
+        if (installed && !same(installed, nextIdentity)) {
+          disconnect()
+          providerFailed = true
+          if (activated || attempted)
+            requireConsentReload(
+              driver,
+              'Reload to apply consent changes. The consent provider or registration changed.',
+            )
+          else {
+            adapter = undefined
+            installed = undefined
+            providerFailed = false
+          }
+        }
+        if (!installed) installed = nextIdentity
+        if (!consentLoaderStatus(driver).reloadRequired) install()
+      }
+      if (!enabled) {
+        raw = deniedConsentState()
+        providerError = parsed && !parsed.success ? 'Consent installation is invalid.' : null
+      }
+      driver.suspend(owners.size !== 1)
+      if (enabled && !providerFailed && unsubscribe) readAdapter()
+      else reconcile()
+    },
+    page(path: string) {
+      driver.page(path)
+    },
+    openPreferences() {
+      // Existing CMP controls remain necessary UI even after disable or reload latch.
+      try {
+        if (!adapter || !ConsentStateSchema.parse(adapter.read()).ready || providerFailed)
+          throw Error('unavailable')
+        adapter.openPreferences()
+        readAdapter()
+      } catch {
+        raw = deniedConsentState()
+        providerError = 'Cookie preferences are unavailable. Retry consent setup.'
+        reconcile()
+      }
+    },
+    retry() {
+      if (consentLoaderStatus(driver).reloadRequired) return
+      if (enabled && (providerFailed || !raw.ready)) {
+        // A wrapper may have caught subscribe() failure while still returning cleanup.
+        // Retry that same authority from a fresh subscription, retaining its installation.
+        disconnect()
+      }
+      if (providerFailed && attempted && !script) attempted = false
+      providerFailed = false
+      providerError = null
+      install()
+      readAdapter()
+    },
+  }
+}

package/src/features/contracts/askAi.ts

@@ -0,0 +1,166 @@
+import { z } from 'zod'
+import { PageContextSchema, FeatureErrorCodeSchema, type FeatureErrorCode } from './base'
+import { KnowledgeReferenceSchema, type KnowledgeReference } from './knowledge'
+
+export const AskAiInputSchema = z.strictObject({
+  requestId: z.uuid(),
+  conversationId: z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[a-zA-Z0-9_-]+$/)
+    .optional(),
+  message: z.string().trim().min(1).max(2000),
+  page: PageContextSchema,
+})
+export type AskAiInput = z.infer<typeof AskAiInputSchema>
+export type AiProvider = 'anthropic' | 'openai'
+export type AiUsage = {
+  /** All billed input, including cache reads and writes exactly once. */
+  inputTokens: number
+  outputTokens: number
+  cacheReadTokens: number | null
+  cacheWriteTokens: number | null
+}
+export const AiSourceSchema = KnowledgeReferenceSchema
+export type AiSource = KnowledgeReference
+export type AiTurnState = 'queued' | 'streaming' | 'completed' | 'failed' | 'aborted' | 'unknown'
+type AiEventBody =
+  | { type: 'start'; conversationId: string; messageId: string }
+  | { type: 'delta'; text: string }
+  | { type: 'sources'; sources: AiSource[] }
+  | { type: 'usage'; usage: AiUsage }
+  | { type: 'done'; state: 'completed' }
+  | {
+      type: 'error'
+      code: FeatureErrorCode
+      message: string
+      state: 'failed' | 'aborted' | 'unknown'
+    }
+export type AiStreamEvent = AiEventBody & { version: 1; requestId: string; sequence: number }
+
+/** Shared producer/gateway/client runtime boundary. Sizes measure serialized UTF-8, never Content-Length. */
+const wireBytes = (value: unknown) => new TextEncoder().encode(JSON.stringify(value)).byteLength
+const position = z.int().nonnegative().max(Number.MAX_SAFE_INTEGER)
+const opaqueId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[A-Za-z0-9_-]+$/)
+const textScalars = z
+  .string()
+  .refine(
+    (v) =>
+      !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/u.test(v) &&
+      !v.includes('\u0000'),
+  )
+export const AiUsageSchema = z
+  .strictObject({
+    inputTokens: position,
+    outputTokens: position,
+    cacheReadTokens: position.nullable(),
+    cacheWriteTokens: position.nullable(),
+  })
+  .refine((v) => (v.cacheReadTokens ?? 0) + (v.cacheWriteTokens ?? 0) <= v.inputTokens)
+export const AiSourcesSchema = z
+  .array(AiSourceSchema)
+  .max(5)
+  .refine((v) => v.every((s) => wireBytes(s) <= 4096) && wireBytes(v) <= 20480)
+const envelope = { version: z.literal(1), requestId: z.uuid(), sequence: position }
+export const AiStreamEventSchema = z.discriminatedUnion('type', [
+  z.strictObject({
+    ...envelope,
+    type: z.literal('start'),
+    conversationId: opaqueId,
+    messageId: opaqueId,
+  }),
+  z.strictObject({ ...envelope, type: z.literal('delta'), text: textScalars }),
+  z.strictObject({ ...envelope, type: z.literal('sources'), sources: AiSourcesSchema }),
+  z.strictObject({ ...envelope, type: z.literal('usage'), usage: AiUsageSchema }),
+  z.strictObject({ ...envelope, type: z.literal('done'), state: z.literal('completed') }),
+  z.strictObject({
+    ...envelope,
+    type: z.literal('error'),
+    code: FeatureErrorCodeSchema,
+    message: z.string().max(2000),
+    state: z.enum(['failed', 'aborted', 'unknown']),
+  }),
+])
+export const AI_RECOVERY_MAX_BYTES = 131072
+export const AiMessagePartSchema = z
+  .strictObject({
+    messageId: opaqueId,
+    requestId: z.uuid(),
+    sequence: position,
+    role: z.enum(['user', 'assistant']),
+    state: z.enum(['queued', 'streaming', 'completed', 'failed', 'aborted', 'unknown']),
+    contentRevision: position,
+    text: textScalars.refine((v) => wireBytes(v) <= 32768),
+    textStart: position,
+    textEnd: position,
+    totalLength: position,
+    lastPart: z.boolean(),
+    sources: AiSourcesSchema,
+  })
+  .refine(
+    (v) =>
+      v.textEnd === v.textStart + v.text.length &&
+      v.textEnd <= v.totalLength &&
+      v.lastPart === (v.textEnd === v.totalLength) &&
+      wireBytes(v) <= 57344,
+  )
+export const AiConversationPageSchema = z
+  .strictObject({
+    version: z.literal(1),
+    conversationId: opaqueId,
+    historyEpoch: position,
+    snapshotUpperSequence: position,
+    parts: z.array(AiMessagePartSchema).max(8),
+    coverage: z.strictObject({
+      newestSequence: position.nullable(),
+      oldestSequence: position.nullable(),
+      completeMessages: z.array(opaqueId).max(8),
+    }),
+    nextCursor: z
+      .string()
+      .min(1)
+      .max(1024)
+      .regex(/^[A-Za-z0-9_-]+$/)
+      .nullable(),
+    hasEarlier: z.boolean(),
+  })
+  .refine(
+    (v) =>
+      wireBytes(v) <= AI_RECOVERY_MAX_BYTES &&
+      v.parts.every((p) => p.sequence <= v.snapshotUpperSequence) &&
+      v.hasEarlier === (v.nextCursor !== null) &&
+      v.coverage.newestSequence === (v.parts[0]?.sequence ?? null) &&
+      v.coverage.oldestSequence === (v.parts.at(-1)?.sequence ?? null) &&
+      new Set(v.coverage.completeMessages).size === v.coverage.completeMessages.length &&
+      v.coverage.completeMessages.every((id) => {
+        const parts = v.parts.filter((p) => p.messageId === id)
+        return parts.length > 0 && parts[0].textStart === 0 && parts.at(-1)!.lastPart
+      }) &&
+      v.parts.every((part, i) => {
+        const previous = v.parts[i - 1]
+        if (!previous) return true
+        if (previous.sequence < part.sequence) return false
+        if (previous.sequence !== part.sequence) return previous.lastPart
+        return (
+          previous.messageId === part.messageId &&
+          previous.requestId === part.requestId &&
+          previous.role === part.role &&
+          previous.contentRevision === part.contentRevision &&
+          previous.state === part.state &&
+          previous.totalLength === part.totalLength &&
+          previous.textEnd === part.textStart &&
+          JSON.stringify(previous.sources) === JSON.stringify(part.sources)
+        )
+      }),
+  )
+export type AiConversationPage = z.infer<typeof AiConversationPageSchema>
+export type AiMessagePart = z.infer<typeof AiMessagePartSchema>
+export const AiRatingInputSchema = z.strictObject({
+  requestId: z.uuid(),
+  rating: z.enum(['helpful', 'unhelpful']),
+})

package/src/features/contracts/askAiSettings.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod'
+const fields = {
+  launcherLabel: z.string().trim().min(1).max(80).default('Ask AI'),
+  title: z.string().trim().min(1).max(120).default('Ask AI'),
+  greeting: z.string().trim().min(1).max(500).default('How can we help?'),
+  suggestions: z.array(z.string().trim().min(1).max(160)).max(4).default([]),
+  errorMessage: z
+    .string()
+    .trim()
+    .min(1)
+    .max(200)
+    .default('We could not complete that answer. Please try again.'),
+  accentColor: z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/)
+    .default('#1746a2'),
+  cornerStyle: z.enum(['rounded', 'square']).default('rounded'),
+}
+export const AskAiWidgetSettingsSchema = z.strictObject(fields)
+export type AskAiWidgetSettings = z.infer<typeof AskAiWidgetSettingsSchema>
+export const AskAiWidgetSettingsPatchSchema = z.strictObject({
+  launcherLabel: fields.launcherLabel.removeDefault().optional(),
+  title: fields.title.removeDefault().optional(),
+  greeting: fields.greeting.removeDefault().optional(),
+  suggestions: fields.suggestions.removeDefault().optional(),
+  errorMessage: fields.errorMessage.removeDefault().optional(),
+  accentColor: fields.accentColor.removeDefault().optional(),
+  cornerStyle: fields.cornerStyle.removeDefault().optional(),
+})
+export function publicAskAiWidgetSettings(input: unknown): AskAiWidgetSettings {
+  const value = input && typeof input === 'object' ? (input as Record<string, unknown>) : {}
+  return AskAiWidgetSettingsSchema.parse(
+    Object.fromEntries(
+      Object.keys(fields)
+        .filter((key) => value[key] !== undefined)
+        .map((key) => [key, value[key]]),
+    ),
+  )
+}
+export const PublicAskAiWidgetSettingsSchema = z
+  .looseObject(fields)
+  .transform(publicAskAiWidgetSettings)