feat(livechat,#89): typed __lc init config, methods, sync getters, events

Vendor-doc audit fixes for LiveChat (Text):

Methods (5): maximize(messageDraft?), minimize, hideGreeting,
triggerSalesTracker (purchase analytics), setSessionVariables (replace
semantics, distinct from update_session_variables which is what identify()
and track() still use).

Sync getters: get<T>(method), plus convenience getState / getCustomerData
/ getChatData reading from widget.get(...).

Event bridge: new public on(event, handler) wraps 10 documented
LiveChatWidget events (ready, availability_changed, visibility_changed,
customer_status_changed, new_event, form_submitted, rating_submitted,
greeting_displayed, greeting_hidden, rich_message_button_clicked).

Typed __lc init config (LiveChatLoadOptions): group, visibility (initial
maximized/minimized/hidden), sessionVariables, customerName, customerEmail,
chatBetweenGroups, asyncInit. Also writes product_name="ahize" alongside
the existing integration_name.

Bundle within existing 6KB budget (raw 5691B; gzip ≈ 1/3).

NOTE: track() still maps to update_session_variables (no first-class event
API in the Chat Widget). Audit also flags custom_identity_provider / JWT
secure session — that's a Developers Console + server-side concern more
than a wrapper change, deferred.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/providers/livechat.ts

@@ -16,10 +16,25 @@ interface LiveChatWidget {
   on(event: string, cb: (payload: unknown) => void): void
   off(event: string, cb: (payload: unknown) => void): void
   get<T = unknown>(method: string): T
+  init?(): void
+}
+
+interface LiveChatLcConfig {
+  license: number
+  integration_name?: string
+  product_name?: string
+  group?: number
+  visibility?: "maximized" | "minimized" | "hidden"
+  sessionVariables?: Record<string, string>
+  customerName?: string
+  customerEmail?: string
+  chatBetweenGroups?: boolean
+  asyncInit?: boolean
+  [key: string]: unknown
 }
 
 interface LiveChatWindow {
-  __lc?: { license: number; integration_name?: string; product_name?: string }
+  __lc?: LiveChatLcConfig
   LiveChatWidget?: LiveChatWidget
 }
 
@@ -30,11 +45,62 @@ function w(): LiveChatWindow {
 const queue = createQueue<LiveChatWidget>()
 const store = createIdentityStore()
 const lifecycle = createLifecycle()
+
+export type LiveChatEventName =
+  | "ready"
+  | "availabilityChanged"
+  | "visibilityChanged"
+  | "customerStatusChanged"
+  | "newEvent"
+  | "formSubmitted"
+  | "ratingSubmitted"
+  | "greetingDisplayed"
+  | "greetingHidden"
+  | "richMessageButtonClicked"
+
+const LIVECHAT_EVENT_MAP: Record<LiveChatEventName, string> = {
+  ready: "ready",
+  availabilityChanged: "availability_changed",
+  visibilityChanged: "visibility_changed",
+  customerStatusChanged: "customer_status_changed",
+  newEvent: "new_event",
+  formSubmitted: "form_submitted",
+  ratingSubmitted: "rating_submitted",
+  greetingDisplayed: "greeting_displayed",
+  greetingHidden: "greeting_hidden",
+  richMessageButtonClicked: "rich_message_button_clicked",
+}
+
+const eventListeners = new Map<LiveChatEventName, Set<(payload?: unknown) => void>>()
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
 
+const TYPED_LC_KEYS = [
+  "group",
+  "visibility",
+  "sessionVariables",
+  "customerName",
+  "customerEmail",
+  "chatBetweenGroups",
+  "asyncInit",
+] as const
+
 export interface LiveChatLoadOptions extends LoadOptions {
   license: number
+  /** Route to a specific agent group. */
+  group?: number
+  /** Initial widget visibility. */
+  visibility?: "maximized" | "minimized" | "hidden"
+  /** Session variables set at init time. */
+  sessionVariables?: Record<string, string>
+  /** Pre-fill customer name. */
+  customerName?: string
+  /** Pre-fill customer email. */
+  customerEmail?: string
+  /** Allow customer to chat across multiple groups. */
+  chatBetweenGroups?: boolean
+  /** Defer LiveChatWidget.init() until manually called via the SDK. */
+  asyncInit?: boolean
 }
 
 export async function load(options: LiveChatLoadOptions): Promise<void> {
@@ -51,7 +117,16 @@ export async function load(options: LiveChatLoadOptions): Promise<void> {
   })
   await waitForDefer(options.defer ?? "immediate")
 
-  w().__lc = { license: options.license, integration_name: "ahize" }
+  const lc: LiveChatLcConfig = {
+    license: options.license,
+    integration_name: "ahize",
+    product_name: "ahize",
+  }
+  for (const key of TYPED_LC_KEYS) {
+    const v = options[key]
+    if (v !== undefined) (lc as Record<string, unknown>)[key] = v
+  }
+  w().__lc = lc
 
   try {
     await injectScript({
@@ -71,7 +146,16 @@ export async function load(options: LiveChatLoadOptions): Promise<void> {
     const widget = w().LiveChatWidget
     if (widget) {
       queue.ready(widget)
-      widget.on("ready", () => readyResolve?.())
+      // Wire every documented widget event to the typed emitter.
+      for (const [mapped, vendor] of Object.entries(LIVECHAT_EVENT_MAP) as Array<
+        [LiveChatEventName, string]
+      >) {
+        widget.on(vendor, (payload: unknown) => {
+          const set = eventListeners.get(mapped)
+          if (set) for (const l of set) l(payload)
+          if (mapped === "ready") readyResolve?.()
+        })
+      }
       break
     }
     await new Promise((r) => setTimeout(r, 50))
@@ -119,6 +203,64 @@ export function hide(): Promise<void> {
   return queue.enqueue((widget) => widget.call("hide"))
 }
 
+export function maximize(messageDraft?: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((widget) =>
+    messageDraft === undefined ? widget.call("maximize") : widget.call("maximize", messageDraft),
+  )
+}
+
+export function minimize(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((widget) => widget.call("minimize"))
+}
+
+export function hideGreeting(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((widget) => widget.call("hide_greeting"))
+}
+
+export function triggerSalesTracker(args: {
+  trackerId: number
+  orderPrice: number
+  orderId?: string
+}): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((widget) => widget.call("trigger_sales_tracker", args))
+}
+
+export function setSessionVariables(vars: Record<string, string>): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((widget) => widget.call("set_session_variables", vars))
+}
+
+export function get<T = unknown>(method: string): T | undefined {
+  if (!isBrowser()) return undefined
+  return w().LiveChatWidget?.get<T>(method)
+}
+
+export function getState(): unknown {
+  return get("state")
+}
+
+export function getCustomerData(): unknown {
+  return get("customer_data")
+}
+
+export function getChatData(): unknown {
+  return get("chat_data")
+}
+
+export function on(event: LiveChatEventName, listener: (payload?: unknown) => void): () => void {
+  let set = eventListeners.get(event)
+  if (!set) {
+    set = new Set()
+    eventListeners.set(event, set)
+  }
+  set.add(listener)
+  return () => set?.delete(listener)
+}
+
 export function shutdown(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue
@@ -138,6 +280,7 @@ export async function destroy(): Promise<void> {
   Reflect.deleteProperty(g, "LiveChatWidget")
   queue.reset()
   store.reset()
+  eventListeners.clear()
   readyPromise = undefined
   readyResolve = undefined
   lifecycle.clearConfigHash()

test/livechat.browser.test.ts

@@ -0,0 +1,143 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+interface CallLog {
+  name: "call" | "on"
+  args: unknown[]
+}
+
+async function bootLiveChat(
+  options?: Partial<import("../src/providers/livechat.ts").LiveChatLoadOptions>,
+): Promise<{
+  livechat: typeof import("../src/providers/livechat.ts")
+  log: CallLog[]
+  fire: (event: string, payload?: unknown) => void
+  getReturns: Map<string, unknown>
+}> {
+  const livechat = await import("../src/providers/livechat.ts")
+  const log: CallLog[] = []
+  const handlers = new Map<string, Array<(p?: unknown) => void>>()
+  const getReturns = new Map<string, unknown>()
+  const widget = {
+    call: (...args: unknown[]) => log.push({ name: "call", args }),
+    on: (event: string, cb: (p?: unknown) => void) => {
+      log.push({ name: "on", args: [event] })
+      const arr = handlers.get(event) ?? []
+      arr.push(cb)
+      handlers.set(event, arr)
+    },
+    off: () => {},
+    get: <T>(method: string) => getReturns.get(method) as T,
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).LiveChatWidget = widget
+  const loadPromise = livechat.load({ license: 12345, ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-livechat") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await new Promise((r) => setTimeout(r, 60))
+  // Fire ready so the wrapper resolves.
+  for (const cb of handlers.get("ready") ?? []) cb()
+  await loadPromise
+  const fire = (event: string, payload?: unknown) => {
+    for (const cb of handlers.get(event) ?? []) cb(payload)
+  }
+  return { livechat, log, fire, getReturns }
+}
+
+describe("livechat (browser) — vendor-doc audit fixes (#89)", () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).LiveChatWidget
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).__lc
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("typed __lc keys (group/visibility/etc) propagate", async () => {
+    const { livechat } = await bootLiveChat({
+      group: 7,
+      visibility: "minimized",
+      sessionVariables: { plan: "pro" },
+      customerName: "Mehmet",
+      customerEmail: "m@example.com",
+      chatBetweenGroups: true,
+      asyncInit: true,
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test inspect
+    const lc = (globalThis as any).__lc as Record<string, unknown>
+    expect(lc).toMatchObject({
+      group: 7,
+      visibility: "minimized",
+      sessionVariables: { plan: "pro" },
+      customerName: "Mehmet",
+      customerEmail: "m@example.com",
+      chatBetweenGroups: true,
+      asyncInit: true,
+      product_name: "ahize",
+    })
+    await livechat.destroy()
+  })
+
+  it("maximize(messageDraft)/minimize/hideGreeting/triggerSalesTracker/setSessionVariables forward", async () => {
+    const { livechat, log } = await bootLiveChat()
+    log.length = 0
+    await livechat.maximize("draft text")
+    await livechat.minimize()
+    await livechat.hideGreeting()
+    await livechat.triggerSalesTracker({ trackerId: 1, orderPrice: 99, orderId: "ord_1" })
+    await livechat.setSessionVariables({ utm: "google" })
+
+    const calls = log.filter((c) => c.name === "call").map((c) => c.args)
+    expect(calls).toContainEqual(["maximize", "draft text"])
+    expect(calls).toContainEqual(["minimize"])
+    expect(calls).toContainEqual(["hide_greeting"])
+    expect(calls).toContainEqual([
+      "trigger_sales_tracker",
+      { trackerId: 1, orderPrice: 99, orderId: "ord_1" },
+    ])
+    expect(calls).toContainEqual(["set_session_variables", { utm: "google" }])
+    await livechat.destroy()
+  })
+
+  it("get() / getState / getCustomerData / getChatData read from widget.get", async () => {
+    const { livechat, getReturns } = await bootLiveChat()
+    getReturns.set("state", { availability: "online" })
+    getReturns.set("customer_data", { id: "u1" })
+    getReturns.set("chat_data", { chatId: "c1" })
+    expect(livechat.getState()).toEqual({ availability: "online" })
+    expect(livechat.getCustomerData()).toEqual({ id: "u1" })
+    expect(livechat.getChatData()).toEqual({ chatId: "c1" })
+    await livechat.destroy()
+  })
+
+  it("on() bridges availability/visibility/customer_status/new_event/etc", async () => {
+    const { livechat, fire } = await bootLiveChat()
+    let availability: unknown
+    let lastForm: unknown
+    let ratingCount = 0
+    livechat.on("availabilityChanged", (p) => {
+      availability = p
+    })
+    livechat.on("formSubmitted", (p) => {
+      lastForm = p
+    })
+    livechat.on("ratingSubmitted", () => {
+      ratingCount++
+    })
+
+    fire("availability_changed", { availability: "online" })
+    fire("form_submitted", { type: "prechat" })
+    fire("rating_submitted", "good")
+
+    expect(availability).toEqual({ availability: "online" })
+    expect(lastForm).toEqual({ type: "prechat" })
+    expect(ratingCount).toBe(1)
+    await livechat.destroy()
+  })
+})