feat(olark,#90): visitor.getDetails + chat API + events + group/locale config

Vendor-doc audit fixes for Olark:

Methods (10): setLocale, setOperatorGroup, sendMessageToVisitor,
sendNotificationToVisitor, sendNotificationToOperator,
updateVisitorNickname, updateVisitorStatus, plus async getVisitorDetails()
that resolves with the SDK's callback-based payload (the wrapper's
getIdentity() now has a real read path back to Olark's resolved details).

Event bridge: new public on(event, handler) wraps 12 documented Olark
events (api.box.onShow/Hide/Expand/Shrink + api.chat.onReady/
onBeginConversation/onMessageToVisitor/onMessageToOperator/
onCommandFromOperator/onOfflineMessageToOperator/onOperatorsAvailable/
onOperatorsAway), exposed under typed names.

Load options: group (calls api.chat.setOperatorGroup at boot) and
locale (api.box.setLocale at boot).

Bumps olark bundle budget 6KB → 7KB (raw 6299B; gzip ≈ 1/3).

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

Author: productdevbook

scripts/bundle-budget.mjs

@@ -18,6 +18,7 @@ const BUDGETS = [
   { glob: /^providers\/hubspot\.mjs$/, max: 7168, label: "provider:hubspot" },
   { glob: /^providers\/tawk\.mjs$/, max: 9216, label: "provider:tawk" },
   { glob: /^providers\/zendesk\.mjs$/, max: 7168, label: "provider:zendesk" },
+  { glob: /^providers\/olark\.mjs$/, max: 7168, label: "provider:olark" },
   { glob: /^providers\/.+\.mjs$/, max: 6144, label: "provider" },
   { glob: /^index\.mjs$/, max: 4096, label: "core" },
   { glob: /^facade\.mjs$/, max: 3072, label: "facade" },

src/providers/olark.ts

@@ -11,7 +11,7 @@ import type {
   LoadOptions,
 } from "../_types.ts"
 
-type OlarkFn = (method: string, ...args: unknown[]) => void
+type OlarkFn = (method: string, ...args: unknown[]) => unknown
 
 interface OlarkWindow {
   olark?: OlarkFn
@@ -25,8 +25,55 @@ const queue = createQueue<OlarkFn>()
 const store = createIdentityStore()
 const lifecycle = createLifecycle()
 
+export type OlarkEventName =
+  | "boxShow"
+  | "boxHide"
+  | "boxExpand"
+  | "boxShrink"
+  | "chatReady"
+  | "beginConversation"
+  | "messageToVisitor"
+  | "messageToOperator"
+  | "commandFromOperator"
+  | "offlineMessageToOperator"
+  | "operatorsAvailable"
+  | "operatorsAway"
+
+const OLARK_EVENT_MAP: Record<OlarkEventName, string> = {
+  boxShow: "api.box.onShow",
+  boxHide: "api.box.onHide",
+  boxExpand: "api.box.onExpand",
+  boxShrink: "api.box.onShrink",
+  chatReady: "api.chat.onReady",
+  beginConversation: "api.chat.onBeginConversation",
+  messageToVisitor: "api.chat.onMessageToVisitor",
+  messageToOperator: "api.chat.onMessageToOperator",
+  commandFromOperator: "api.chat.onCommandFromOperator",
+  offlineMessageToOperator: "api.chat.onOfflineMessageToOperator",
+  operatorsAvailable: "api.chat.onOperatorsAvailable",
+  operatorsAway: "api.chat.onOperatorsAway",
+}
+
+const eventListeners = new Map<OlarkEventName, Set<(payload?: unknown) => void>>()
+
+export interface OlarkVisitorDetails {
+  emailAddress?: string
+  fullName?: string
+  phoneNumber?: string
+  organization?: string
+  city?: string
+  region?: string
+  country?: string
+  customFields?: Record<string, unknown>
+  [key: string]: unknown
+}
+
 export interface OlarkLoadOptions extends LoadOptions {
   siteId: string
+  /** Initial agent group routing. */
+  group?: string
+  /** Initial widget locale. */
+  locale?: string
 }
 
 export async function load(options: OlarkLoadOptions): Promise<void> {
@@ -58,6 +105,18 @@ export async function load(options: OlarkLoadOptions): Promise<void> {
     const olark = w().olark
     if (typeof olark === "function") {
       olark("api.box.onReady", () => {})
+      // Wire every documented Olark event to the typed emitter.
+      for (const [mapped, vendor] of Object.entries(OLARK_EVENT_MAP) as Array<
+        [OlarkEventName, string]
+      >) {
+        olark(vendor, (payload: unknown) => {
+          const set = eventListeners.get(mapped)
+          if (!set) return
+          for (const l of set) l(payload)
+        })
+      }
+      if (options.group !== undefined) olark("api.chat.setOperatorGroup", { group: options.group })
+      if (options.locale !== undefined) olark("api.box.setLocale", options.locale)
       queue.ready(olark)
       break
     }
@@ -116,6 +175,67 @@ export function shrink(): Promise<void> {
   return queue.enqueue((olark) => olark("api.box.shrink"))
 }
 
+export function setLocale(locale: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.box.setLocale", locale))
+}
+
+export function setOperatorGroup(group: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.setOperatorGroup", { group }))
+}
+
+export function sendMessageToVisitor(body: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.sendMessageToVisitor", { body }))
+}
+
+export function sendNotificationToVisitor(body: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.sendNotificationToVisitor", { body }))
+}
+
+export function sendNotificationToOperator(body: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.sendNotificationToOperator", { body }))
+}
+
+export function updateVisitorNickname(args: {
+  snippet: string
+  hideDefault?: boolean
+}): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.updateVisitorNickname", args))
+}
+
+export function updateVisitorStatus(args: { snippet: string | string[] }): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((olark) => olark("api.chat.updateVisitorStatus", args))
+}
+
+export function getVisitorDetails(): Promise<OlarkVisitorDetails | undefined> {
+  if (!isBrowser()) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    queue
+      .enqueue((olark) => {
+        olark("api.visitor.getDetails", (details: unknown) =>
+          resolve(details as OlarkVisitorDetails | undefined),
+        )
+      })
+      .catch(() => resolve(undefined))
+  })
+}
+
+export function on(event: OlarkEventName, 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
@@ -137,6 +257,7 @@ export async function destroy(): Promise<void> {
   Reflect.deleteProperty(g, "olark")
   queue.reset()
   store.reset()
+  eventListeners.clear()
   lifecycle.clearConfigHash()
   lifecycle.transition("idle")
 }

test/olark.browser.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+interface OCall {
+  method: string
+  args: unknown[]
+}
+
+async function bootOlark(
+  options?: Partial<import("../src/providers/olark.ts").OlarkLoadOptions>,
+): Promise<{
+  olark: typeof import("../src/providers/olark.ts")
+  calls: OCall[]
+  fire: (event: string, payload?: unknown) => void
+  visitorDetailsResponse: { current: unknown }
+}> {
+  const olark = await import("../src/providers/olark.ts")
+  const calls: OCall[] = []
+  const handlers = new Map<string, Array<(p?: unknown) => void>>()
+  const visitorDetailsResponse = { current: { emailAddress: "x@y", fullName: "Test User" } }
+  const fn = (method: string, ...args: unknown[]) => {
+    calls.push({ method, args })
+    if (typeof args[0] === "function" && method.startsWith("api.") && method.includes(".on")) {
+      const arr = handlers.get(method) ?? []
+      arr.push(args[0] as (p?: unknown) => void)
+      handlers.set(method, arr)
+    }
+    if (method === "api.visitor.getDetails" && typeof args[0] === "function") {
+      ;(args[0] as (d: unknown) => void)(visitorDetailsResponse.current)
+    }
+    return undefined
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).olark = fn
+  const loadPromise = olark.load({ siteId: "site_xyz", ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-olark") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await new Promise((r) => setTimeout(r, 60))
+  await loadPromise
+  const fire = (vendor: string, payload?: unknown) => {
+    for (const cb of handlers.get(vendor) ?? []) cb(payload)
+  }
+  return { olark, calls, fire, visitorDetailsResponse }
+}
+
+describe("olark (browser) — vendor-doc audit fixes (#90)", () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).olark
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("group + locale at load time fire setOperatorGroup + setLocale", async () => {
+    const { olark, calls } = await bootOlark({ group: "support", locale: "tr" })
+    expect(calls.find((c) => c.method === "api.chat.setOperatorGroup")?.args).toEqual([
+      { group: "support" },
+    ])
+    expect(calls.find((c) => c.method === "api.box.setLocale")?.args).toEqual(["tr"])
+    await olark.destroy()
+  })
+
+  it("getVisitorDetails resolves with the callback payload", async () => {
+    const { olark } = await bootOlark()
+    const details = await olark.getVisitorDetails()
+    expect(details).toMatchObject({ emailAddress: "x@y", fullName: "Test User" })
+    await olark.destroy()
+  })
+
+  it("chat.* methods (sendMessageToVisitor/etc) forward correctly", async () => {
+    const { olark, calls } = await bootOlark()
+    calls.length = 0
+    await olark.sendMessageToVisitor("hi")
+    await olark.sendNotificationToVisitor("note v")
+    await olark.sendNotificationToOperator("note o")
+    await olark.updateVisitorNickname({ snippet: "VIP", hideDefault: true })
+    await olark.updateVisitorStatus({ snippet: "browsing" })
+    await olark.setOperatorGroup("sales")
+
+    const methods = calls.map((c) => c.method)
+    for (const m of [
+      "api.chat.sendMessageToVisitor",
+      "api.chat.sendNotificationToVisitor",
+      "api.chat.sendNotificationToOperator",
+      "api.chat.updateVisitorNickname",
+      "api.chat.updateVisitorStatus",
+      "api.chat.setOperatorGroup",
+    ]) {
+      expect(methods).toContain(m)
+    }
+    await olark.destroy()
+  })
+
+  it("on() bridges box + chat events", async () => {
+    const { olark, fire } = await bootOlark()
+    let shown = 0
+    let beginCount = 0
+    let lastMsg: unknown
+    olark.on("boxShow", () => {
+      shown++
+    })
+    olark.on("beginConversation", () => {
+      beginCount++
+    })
+    olark.on("messageToOperator", (p) => {
+      lastMsg = p
+    })
+
+    fire("api.box.onShow")
+    fire("api.chat.onBeginConversation")
+    fire("api.chat.onMessageToOperator", { body: "test" })
+
+    expect(shown).toBe(1)
+    expect(beginCount).toBe(1)
+    expect(lastMsg).toEqual({ body: "test" })
+    await olark.destroy()
+  })
+})