feat(liveagent,#88): visitor methods + button callbacks + setVisitorLocation

Vendor-doc audit fixes for LiveAgent:

Methods (6): addUserDetail (single-key user property update),
addTicketField, clearAllUserDetails, setVisitorLocation, createForm
(offline contact-form variant of createButton), plus sync hasOpenedWidget()
reading from LiveAgent.instance.

pageView({path}) is no longer a no-op — it forwards to setVisitorLocation
so SPA route changes show up in the agent panel.

Event bridge: new public on(event, handler) wraps the documented
button-level callbacks via the button instance returned from
createButton — chatStarted (button.onClick), chatEnded (onCloseFunction_),
online (onOnline), offline (onOffline). Replaces the dead top-level
LiveAgent.onChatStarted / onChatEnded type fields.

shutdown() now actually clears user details (clearAllUserDetails) so
identity reset means something on the LiveAgent side.

LiveAgentLoadOptions: disableOnlineVisitorsTracking flag fired before
createButton (per vendor docs ordering). identify() also forwards no-arg
setUserDetails-style optionals.

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

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

Author: productdevbook

src/providers/liveagent.ts

@@ -11,13 +11,29 @@ import type {
   LoadOptions,
 } from "../_types.ts"
 
+interface LiveAgentButton {
+  onOnline?: () => void
+  onOffline?: () => void
+  onClick?: () => void
+  onCloseFunction_?: () => void
+}
+
+interface LiveAgentInstance {
+  hasOpenedWidget?(): boolean
+}
+
 interface LiveAgentAPI {
-  setUserDetails(email: string, firstName: string, lastName: string, phone: string): void
+  setUserDetails(email?: string, firstName?: string, lastName?: string, phone?: string): void
+  addUserDetail?(key: "email" | "firstName" | "lastName" | "phone", value: string): void
   addContactField(field: string, value: unknown): void
-  createButton(buttonId: string, container?: unknown): void
+  addTicketField?(key: string, value: unknown): void
+  clearAllUserDetails?(): void
+  setVisitorLocation?(url: string): void
+  disableOnlineVisitorsTracking?(): void
+  createButton(buttonId: string, container?: unknown): LiveAgentButton | undefined
+  createForm?(formId: string, container?: unknown): LiveAgentButton | undefined
   hideButton?(buttonId: string): void
-  onChatStarted?: () => void
-  onChatEnded?: () => void
+  instance?: LiveAgentInstance
 }
 
 interface LiveAgentWindow {
@@ -34,12 +50,17 @@ const lifecycle = createLifecycle()
 let currentSubdomain: string | undefined
 let currentButtonId: string | undefined
 
+export type LiveAgentEventName = "online" | "offline" | "chatStarted" | "chatEnded"
+const eventListeners = new Map<LiveAgentEventName, Set<() => void>>()
+
 export interface LiveAgentLoadOptions extends LoadOptions {
   /** e.g. "yourcompany" — yourcompany.ladesk.com */
   accountSubdomain: string
   buttonId: string
   /** Self-hosted base URL override (e.g. "https://support.example.com"). */
   selfHostedBaseUrl?: string
+  /** When true, calls LiveAgent.disableOnlineVisitorsTracking() before createButton. */
+  disableOnlineVisitorsTracking?: boolean
 }
 
 export async function load(options: LiveAgentLoadOptions): Promise<void> {
@@ -77,7 +98,24 @@ export async function load(options: LiveAgentLoadOptions): Promise<void> {
   for (let i = 0; i < 80; i++) {
     const api = w().LiveAgent
     if (api) {
-      api.createButton(options.buttonId)
+      if (options.disableOnlineVisitorsTracking) api.disableOnlineVisitorsTracking?.()
+      const button = api.createButton(options.buttonId)
+      if (button) {
+        // Vendor pattern: monkey-patch button.onClick / onCloseFunction_ for chat
+        // start/end, and onOnline / onOffline for agent availability.
+        button.onClick = () => {
+          for (const l of eventListeners.get("chatStarted") ?? []) l()
+        }
+        button.onCloseFunction_ = () => {
+          for (const l of eventListeners.get("chatEnded") ?? []) l()
+        }
+        button.onOnline = () => {
+          for (const l of eventListeners.get("online") ?? []) l()
+        }
+        button.onOffline = () => {
+          for (const l of eventListeners.get("offline") ?? []) l()
+        }
+      }
       queue.ready(api)
       break
     }
@@ -113,8 +151,54 @@ export function track<T extends EventMetadata = EventMetadata>(
   })
 }
 
-export function pageView(_info?: { path?: string; locale?: string }): Promise<void> {
-  return Promise.resolve()
+export function pageView(info?: { path?: string; locale?: string }): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => {
+    if (info?.path && api.setVisitorLocation) api.setVisitorLocation(info.path)
+  })
+}
+
+export function addUserDetail(
+  key: "email" | "firstName" | "lastName" | "phone",
+  value: string,
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.addUserDetail?.(key, value))
+}
+
+export function addTicketField(key: string, value: unknown): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.addTicketField?.(key, value))
+}
+
+export function clearAllUserDetails(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.clearAllUserDetails?.())
+}
+
+export function setVisitorLocation(url: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.setVisitorLocation?.(url))
+}
+
+export function createForm(formId: string, container?: unknown): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.createForm?.(formId, container))
+}
+
+export function hasOpenedWidget(): boolean | undefined {
+  if (!isBrowser()) return undefined
+  return w().LiveAgent?.instance?.hasOpenedWidget?.()
+}
+
+export function on(event: LiveAgentEventName, listener: () => 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 show(): Promise<void> {
@@ -133,9 +217,12 @@ export function hide(): Promise<void> {
 
 export function shutdown(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  store.reset()
-  lifecycle.transition("shutdown")
-  return Promise.resolve()
+  return queue
+    .enqueue((api) => api.clearAllUserDetails?.())
+    .then(() => {
+      store.reset()
+      lifecycle.transition("shutdown")
+    })
 }
 
 export async function destroy(): Promise<void> {
@@ -146,6 +233,7 @@ export async function destroy(): Promise<void> {
   Reflect.deleteProperty(g, "LiveAgent")
   queue.reset()
   store.reset()
+  eventListeners.clear()
   currentSubdomain = undefined
   currentButtonId = undefined
   lifecycle.clearConfigHash()

test/liveagent.browser.test.ts

@@ -0,0 +1,157 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+interface CallLog {
+  name: string
+  args: unknown[]
+}
+
+interface FakeButton {
+  onClick?: () => void
+  onCloseFunction_?: () => void
+  onOnline?: () => void
+  onOffline?: () => void
+}
+
+async function bootLiveAgent(
+  options?: Partial<import("../src/providers/liveagent.ts").LiveAgentLoadOptions>,
+): Promise<{
+  liveagent: typeof import("../src/providers/liveagent.ts")
+  log: CallLog[]
+  button: FakeButton
+  api: Record<string, unknown>
+}> {
+  const liveagent = await import("../src/providers/liveagent.ts")
+  const log: CallLog[] = []
+  const rec =
+    (name: string) =>
+    (...args: unknown[]) =>
+      log.push({ name, args })
+  const button: FakeButton = {}
+  const api: Record<string, unknown> = {
+    setUserDetails: rec("setUserDetails"),
+    addUserDetail: rec("addUserDetail"),
+    addContactField: rec("addContactField"),
+    addTicketField: rec("addTicketField"),
+    clearAllUserDetails: rec("clearAllUserDetails"),
+    setVisitorLocation: rec("setVisitorLocation"),
+    disableOnlineVisitorsTracking: rec("disableOnlineVisitorsTracking"),
+    createButton: (...args: unknown[]) => {
+      log.push({ name: "createButton", args })
+      return button
+    },
+    createForm: rec("createForm"),
+    hideButton: rec("hideButton"),
+    instance: { hasOpenedWidget: () => true },
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).LiveAgent = api
+  const loadPromise = liveagent.load({
+    accountSubdomain: "yourcompany",
+    buttonId: "btn_xyz",
+    ...options,
+  })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-liveagent") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await new Promise((r) => setTimeout(r, 60))
+  await loadPromise
+  return { liveagent, log, button, api }
+}
+
+describe("liveagent (browser) — vendor-doc audit fixes (#88)", () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).LiveAgent
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("disableOnlineVisitorsTracking: true is called before createButton", async () => {
+    const { liveagent, log } = await bootLiveAgent({ disableOnlineVisitorsTracking: true })
+    const disableIdx = log.findIndex((c) => c.name === "disableOnlineVisitorsTracking")
+    const createIdx = log.findIndex((c) => c.name === "createButton")
+    expect(disableIdx).toBeGreaterThanOrEqual(0)
+    expect(createIdx).toBeGreaterThan(disableIdx)
+    await liveagent.destroy()
+  })
+
+  it("addUserDetail/addTicketField/clearAllUserDetails/setVisitorLocation/createForm forward", async () => {
+    const { liveagent, log } = await bootLiveAgent()
+    log.length = 0
+    await liveagent.addUserDetail("email", "u@example.com")
+    await liveagent.addTicketField("priority", "high")
+    await liveagent.clearAllUserDetails()
+    await liveagent.setVisitorLocation("/checkout")
+    await liveagent.createForm("form_1")
+    const names = log.map((c) => c.name)
+    for (const m of [
+      "addUserDetail",
+      "addTicketField",
+      "clearAllUserDetails",
+      "setVisitorLocation",
+      "createForm",
+    ]) {
+      expect(names).toContain(m)
+    }
+    await liveagent.destroy()
+  })
+
+  it("pageView({path}) calls setVisitorLocation", async () => {
+    const { liveagent, log } = await bootLiveAgent()
+    log.length = 0
+    await liveagent.pageView({ path: "/products/123" })
+    const call = log.find((c) => c.name === "setVisitorLocation")
+    expect(call?.args).toEqual(["/products/123"])
+    await liveagent.destroy()
+  })
+
+  it("hasOpenedWidget reads from LiveAgent.instance", async () => {
+    const { liveagent } = await bootLiveAgent()
+    expect(liveagent.hasOpenedWidget()).toBe(true)
+    await liveagent.destroy()
+  })
+
+  it("on(chatStarted/chatEnded/online/offline) bridges button callbacks", async () => {
+    const { liveagent, button } = await bootLiveAgent()
+    let started = 0
+    let ended = 0
+    let online = 0
+    let offline = 0
+    liveagent.on("chatStarted", () => {
+      started++
+    })
+    liveagent.on("chatEnded", () => {
+      ended++
+    })
+    liveagent.on("online", () => {
+      online++
+    })
+    liveagent.on("offline", () => {
+      offline++
+    })
+
+    button.onClick?.()
+    button.onCloseFunction_?.()
+    button.onOnline?.()
+    button.onOffline?.()
+
+    expect(started).toBe(1)
+    expect(ended).toBe(1)
+    expect(online).toBe(1)
+    expect(offline).toBe(1)
+    await liveagent.destroy()
+  })
+
+  it("shutdown() calls clearAllUserDetails", async () => {
+    const { liveagent, log } = await bootLiveAgent()
+    log.length = 0
+    await liveagent.shutdown()
+    expect(log.find((c) => c.name === "clearAllUserDetails")).toBeDefined()
+    await liveagent.destroy()
+  })
+})