feat(tidio,#94): fix track(), add methods, events, pre-load config

Vendor-doc audit fixes for Tidio:

Bug fix: track() previously wrote metadata into setContactProperties under
the event name, silently breaking Tidio automation triggers. Now calls
the documented tidioChatApi.track(eventName), and stores any metadata as
a separate `${event}_metadata` contact property so it isn't lost.

Methods (8): setColorPalette, display (async visibility distinct from
show/hide), messageFromOperator, messageFromVisitor, addVisitorTags,
setVisitorCurrency, plus open/close (split from show/hide which used to
fire both unconditionally).

Events (6 added to TidioEventName): setStatus, conversationStart,
preFormFilled, resize, open, close. Existing ready/messageFromVisitor/
messageFromOperator/visitorJoined kept (visitorJoined retained for
backward compat even though current public docs don't list it).

Pre-load config (TidioLoadOptions): language → window.tidioChatLang,
identify → window.tidioIdentify (set before script load per the
documented installation pattern).

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

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

Author: productdevbook

src/providers/tidio.ts

@@ -20,16 +20,31 @@ interface TidioAPI {
     tags?: string[]
   }): void
   setContactProperties(props: Record<string, unknown>): void
+  track?(event: string): void
+  setColorPalette?(hex: string): void
+  display?(state: boolean): void
+  messageFromOperator?(message: string): void
+  messageFromVisitor?(message: string): void
+  addVisitorTags?(tags: string[]): void
+  setVisitorCurrency?(currency: { code: string; exchangeRate?: number }): void
   show(): void
   hide(): void
   open(): void
   close(): void
-  display?(state: boolean): void
-  messageFromOperator?(message: string): void
+}
+
+interface TidioIdentity {
+  distinct_id?: string
+  email?: string
+  name?: string
+  phone?: string
+  tags?: string[]
 }
 
 interface TidioWindow {
   tidioChatApi?: TidioAPI
+  tidioChatLang?: string
+  tidioIdentify?: TidioIdentity
 }
 
 function w(): TidioWindow {
@@ -47,9 +62,15 @@ const TIDIO_EVENTS = {
   messageFromVisitor: "tidioChat-messageFromVisitor",
   messageFromOperator: "tidioChat-messageFromOperator",
   visitorJoined: "tidioChat-visitorJoined",
+  setStatus: "tidioChat-setStatus",
+  conversationStart: "tidioChat-conversationStart",
+  preFormFilled: "tidioChat-preFormFilled",
+  resize: "tidioChat-resize",
+  open: "tidioChat-open",
+  close: "tidioChat-close",
 } as const
 
-type TidioEventName = keyof typeof TIDIO_EVENTS
+export type TidioEventName = keyof typeof TIDIO_EVENTS
 const eventListeners = new Map<TidioEventName, Set<(payload: unknown) => void>>()
 const domHandlers = new Map<TidioEventName, () => void>()
 
@@ -66,6 +87,10 @@ function bindDomEvent(event: TidioEventName): void {
 
 export interface TidioLoadOptions extends LoadOptions {
   publicKey: string
+  /** Pre-load language (writes window.tidioChatLang before script load). */
+  language?: string
+  /** Pre-load identity (writes window.tidioIdentify before script load). */
+  identify?: TidioIdentity
 }
 
 export async function load(options: TidioLoadOptions): Promise<void> {
@@ -82,13 +107,15 @@ export async function load(options: TidioLoadOptions): Promise<void> {
   })
   await waitForDefer(options.defer ?? "immediate")
 
-  bindDomEvent("ready")
-  bindDomEvent("messageFromVisitor")
-  bindDomEvent("messageFromOperator")
-  bindDomEvent("visitorJoined")
+  for (const evt of Object.keys(TIDIO_EVENTS) as TidioEventName[]) {
+    bindDomEvent(evt)
+  }
 
   document.addEventListener(TIDIO_EVENTS.ready, () => readyResolve?.(), { once: true } as never)
 
+  if (options.language !== undefined) w().tidioChatLang = options.language
+  if (options.identify !== undefined) w().tidioIdentify = options.identify
+
   try {
     await injectScript({
       id: "ahize-tidio",
@@ -136,13 +163,56 @@ export function track<T extends EventMetadata = EventMetadata>(
   metadata?: T,
 ): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  return queue.enqueue((api) => api.setContactProperties({ [event]: metadata }))
+  return queue.enqueue((api) => {
+    if (api.track) {
+      // Prefer the documented automation-trigger API.
+      api.track(event)
+      // Tidio's track() doesn't accept metadata; surface it as contact properties
+      // so it isn't lost.
+      if (metadata) api.setContactProperties({ [`${event}_metadata`]: metadata })
+    } else {
+      api.setContactProperties({ [event]: metadata })
+    }
+  })
 }
 
 export function pageView(_info?: { path?: string; locale?: string }): Promise<void> {
   return Promise.resolve()
 }
 
+export function setColorPalette(hex: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.setColorPalette?.(hex))
+}
+
+export function display(state: boolean): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.display?.(state))
+}
+
+export function messageFromOperator(message: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.messageFromOperator?.(message))
+}
+
+export function messageFromVisitor(message: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.messageFromVisitor?.(message))
+}
+
+export function addVisitorTags(tags: string[]): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.addVisitorTags?.(tags))
+}
+
+export function setVisitorCurrency(currency: {
+  code: string
+  exchangeRate?: number
+}): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.setVisitorCurrency?.(currency))
+}
+
 export function on(event: TidioEventName, listener: (payload: unknown) => void): () => void {
   let set = eventListeners.get(event)
   if (!set) {
@@ -155,17 +225,24 @@ export function on(event: TidioEventName, listener: (payload: unknown) => void):
 
 export function show(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  return queue.enqueue((api) => {
-    api.show()
-    api.open()
-  })
+  return queue.enqueue((api) => api.show())
 }
 
 export function hide(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((api) => api.hide())
 }
 
+export function open(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.open())
+}
+
+export function close(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.close())
+}
+
 export function shutdown(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   store.reset()
@@ -182,6 +259,8 @@ export async function destroy(): Promise<void> {
   removeScript("ahize-tidio")
   const g = w()
   Reflect.deleteProperty(g, "tidioChatApi")
+  Reflect.deleteProperty(g, "tidioChatLang")
+  Reflect.deleteProperty(g, "tidioIdentify")
   queue.reset()
   store.reset()
   readyPromise = undefined

test/tidio.browser.test.ts

@@ -0,0 +1,161 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+interface CallLog {
+  name: string
+  args: unknown[]
+}
+
+function fakeApi(): {
+  api: Record<string, unknown>
+  log: CallLog[]
+} {
+  const log: CallLog[] = []
+  const rec =
+    (name: string) =>
+    (...args: unknown[]) =>
+      log.push({ name, args })
+  const api: Record<string, unknown> = {
+    setVisitorData: rec("setVisitorData"),
+    setContactProperties: rec("setContactProperties"),
+    track: rec("track"),
+    setColorPalette: rec("setColorPalette"),
+    display: rec("display"),
+    messageFromOperator: rec("messageFromOperator"),
+    messageFromVisitor: rec("messageFromVisitor"),
+    addVisitorTags: rec("addVisitorTags"),
+    setVisitorCurrency: rec("setVisitorCurrency"),
+    show: rec("show"),
+    hide: rec("hide"),
+    open: rec("open"),
+    close: rec("close"),
+  }
+  return { api, log }
+}
+
+async function bootTidio(
+  options?: Partial<import("../src/providers/tidio.ts").TidioLoadOptions>,
+): Promise<{
+  tidio: typeof import("../src/providers/tidio.ts")
+  log: CallLog[]
+}> {
+  const tidio = await import("../src/providers/tidio.ts")
+  const { api, log } = fakeApi()
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).tidioChatApi = api
+  const loadPromise = tidio.load({ publicKey: "pub_xyz", ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-tidio") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await new Promise((r) => setTimeout(r, 60))
+  document.dispatchEvent(new CustomEvent("tidioChat-ready"))
+  await loadPromise
+  return { tidio, log }
+}
+
+describe("tidio (browser) — vendor-doc audit fixes (#94)", () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).tidioChatApi
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).tidioChatLang
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).tidioIdentify
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("language + identify pre-load globals are written before script load", async () => {
+    const { tidio } = await bootTidio({
+      language: "tr",
+      identify: { distinct_id: "u1", email: "u@example.com" },
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test inspect
+    expect((globalThis as any).tidioChatLang).toBe("tr")
+    // biome-ignore lint/suspicious/noExplicitAny: test inspect
+    expect((globalThis as any).tidioIdentify).toEqual({
+      distinct_id: "u1",
+      email: "u@example.com",
+    })
+    await tidio.destroy()
+  })
+
+  it("track() now calls tidioChatApi.track instead of setContactProperties", async () => {
+    const { tidio, log } = await bootTidio()
+    log.length = 0
+    await tidio.track("plan_upgraded", { tier: "pro" })
+    const trackCall = log.find((c) => c.name === "track")
+    expect(trackCall?.args).toEqual(["plan_upgraded"])
+    // metadata stored as a separate contact property to avoid loss
+    const meta = log.find(
+      (c) =>
+        c.name === "setContactProperties" &&
+        JSON.stringify(c.args).includes("plan_upgraded_metadata"),
+    )
+    expect(meta).toBeDefined()
+    await tidio.destroy()
+  })
+
+  it("show()/open() now distinct (no more conflated show+open)", async () => {
+    const { tidio, log } = await bootTidio()
+    log.length = 0
+    await tidio.show()
+    await tidio.open()
+    await tidio.hide()
+    await tidio.close()
+    expect(log.map((c) => c.name)).toEqual(["show", "open", "hide", "close"])
+    await tidio.destroy()
+  })
+
+  it("setColorPalette/display/messageFromOperator/messageFromVisitor/addVisitorTags/setVisitorCurrency forward", async () => {
+    const { tidio, log } = await bootTidio()
+    log.length = 0
+    await tidio.setColorPalette("#ff0000")
+    await tidio.display(true)
+    await tidio.messageFromOperator("welcome")
+    await tidio.messageFromVisitor("hi")
+    await tidio.addVisitorTags(["beta"])
+    await tidio.setVisitorCurrency({ code: "TRY", exchangeRate: 32 })
+    const names = log.map((c) => c.name)
+    for (const m of [
+      "setColorPalette",
+      "display",
+      "messageFromOperator",
+      "messageFromVisitor",
+      "addVisitorTags",
+      "setVisitorCurrency",
+    ]) {
+      expect(names).toContain(m)
+    }
+    await tidio.destroy()
+  })
+
+  it("on(event) covers setStatus/conversationStart/preFormFilled/resize/open/close", async () => {
+    const { tidio } = await bootTidio()
+    let status: unknown
+    let convStart = 0
+    let openCount = 0
+    tidio.on("setStatus", (p) => {
+      status = p
+    })
+    tidio.on("conversationStart", () => {
+      convStart++
+    })
+    tidio.on("open", () => {
+      openCount++
+    })
+
+    document.dispatchEvent(new CustomEvent("tidioChat-setStatus", { detail: { status: "online" } }))
+    document.dispatchEvent(new CustomEvent("tidioChat-conversationStart"))
+    document.dispatchEvent(new CustomEvent("tidioChat-open"))
+
+    expect(status).toEqual({ status: "online" })
+    expect(convStart).toBe(1)
+    expect(openCount).toBe(1)
+    await tidio.destroy()
+  })
+})