feat(tawk,#93): expose missing methods, event bridges, visitor preload

Vendor-doc audit fixes for Tawk:

Methods (12 + login/logout): maximize, minimize, toggle, popup,
toggleVisibility, endChat, start, addTags, removeTags, getStatus,
getWindowType, isChatMaximized, isChatMinimized, isChatHidden,
isChatOngoing, isVisitorEngaged, login (restores past conversations
via Tawk.login), logout. switchWidget gained the documented completion
callback. identify() now also forwards phone (E.164).

Event bridge: new public on(event, handler) wraps every documented Tawk
hook (beforeLoad/load/statusChange/chatMaximized/.../offlineSubmit) with
the same multi-listener pattern as onUnreadCountChange. The 15 declared
hooks are now actually reachable.

TawkLoadOptions: visitor{} preload (set before script downloads),
customStyleZIndex, autoStart (defer socket), onBeforeLoad as a load-time
shortcut to on('beforeLoad').

Bumps tawk bundle budget 6KB → 9KB (raw 8437B; gzip ≈ 1/3). Tawk's
SDK surface is the largest of the providers we wrap.

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

Author: productdevbook

scripts/bundle-budget.mjs

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

src/providers/tawk.ts

@@ -15,23 +15,46 @@ interface TawkVisitor {
   name?: string
   email?: string
   hash?: string
+  phone?: string
+  userId?: string
+}
+
+interface TawkCustomStyle {
+  zIndex?: number | string
 }
 
 interface TawkAPI {
   visitor?: TawkVisitor
+  customStyle?: TawkCustomStyle
+  autoStart?: boolean
   setAttributes?: (attrs: Record<string, unknown>, cb?: (err?: Error) => void) => void
   addEvent?: (event: string, metadata?: Record<string, unknown>, cb?: (err?: Error) => void) => void
+  addTags?: (tags: string[], cb?: (err?: Error) => void) => void
+  removeTags?: (tags: string[], cb?: (err?: Error) => void) => void
   showWidget?: () => void
   hideWidget?: () => void
+  toggleVisibility?: () => void
   maximize?: () => void
   minimize?: () => void
   toggle?: () => void
   popup?: () => void
   endChat?: () => void
+  start?: (options?: { showWidget?: boolean }) => void
+  getStatus?: () => "online" | "away" | "offline"
+  getWindowType?: () => "inline" | "embed"
+  isChatMaximized?: () => boolean
+  isChatMinimized?: () => boolean
+  isChatHidden?: () => boolean
+  isChatOngoing?: () => boolean
+  isVisitorEngaged?: () => boolean
   login?: (user: TawkVisitor, cb?: (err?: Error) => void) => void
   logout?: (cb?: (err?: Error) => void) => void
-  switchWidget?: (options: { propertyId: string; widgetId: string }) => void
+  switchWidget?: (
+    options: { propertyId: string; widgetId: string },
+    cb?: (err?: Error) => void,
+  ) => void
   // Event hooks Tawk exposes; each must be assignable.
+  onBeforeLoad?: () => void
   onLoad?: () => void
   onStatusChange?: (status: "online" | "away" | "offline") => void
   onChatMaximized?: () => void
@@ -49,6 +72,8 @@ interface TawkAPI {
   onFileUpload?: (url: string) => void
   onTagsUpdated?: (data: unknown) => void
   onUnreadCountChanged?: (count: number) => void
+  onPrechatSubmit?: (data: unknown) => void
+  onOfflineSubmit?: (data: unknown) => void
 }
 
 interface TawkWindow {
@@ -70,9 +95,32 @@ const queue = createQueue<TawkAPI>()
 const store = createIdentityStore()
 const lifecycle = createLifecycle()
 const unreadListeners = new Set<(count: number) => void>()
+const eventListeners = new Map<string, Set<(payload?: unknown) => void>>()
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
 
+const HOOK_TO_EVENT: Record<string, string> = {
+  onBeforeLoad: "beforeLoad",
+  onLoad: "load",
+  onStatusChange: "statusChange",
+  onChatMaximized: "chatMaximized",
+  onChatMinimized: "chatMinimized",
+  onChatHidden: "chatHidden",
+  onChatStarted: "chatStarted",
+  onChatEnded: "chatEnded",
+  onChatMessageVisitor: "chatMessageVisitor",
+  onChatMessageAgent: "chatMessageAgent",
+  onChatMessageSystem: "chatMessageSystem",
+  onAgentJoinChat: "agentJoinChat",
+  onAgentLeaveChat: "agentLeaveChat",
+  onChatSatisfaction: "chatSatisfaction",
+  onVisitorNameChanged: "visitorNameChanged",
+  onFileUpload: "fileUpload",
+  onTagsUpdated: "tagsUpdated",
+  onPrechatSubmit: "prechatSubmit",
+  onOfflineSubmit: "offlineSubmit",
+}
+
 const TAWK_COLLISION_SYMBOLS = ["L", "R", "T"]
 
 function warnCollisions(): void {
@@ -87,9 +135,38 @@ function warnCollisions(): void {
   }
 }
 
+export type TawkEventName =
+  | "beforeLoad"
+  | "load"
+  | "statusChange"
+  | "chatMaximized"
+  | "chatMinimized"
+  | "chatHidden"
+  | "chatStarted"
+  | "chatEnded"
+  | "chatMessageVisitor"
+  | "chatMessageAgent"
+  | "chatMessageSystem"
+  | "agentJoinChat"
+  | "agentLeaveChat"
+  | "chatSatisfaction"
+  | "visitorNameChanged"
+  | "fileUpload"
+  | "tagsUpdated"
+  | "prechatSubmit"
+  | "offlineSubmit"
+
 export interface TawkLoadOptions extends LoadOptions {
   propertyId: string
   widgetId?: string
+  /** Visitor preload — must be assigned before the embed script downloads. */
+  visitor?: { name?: string; email?: string; hash?: string; phone?: string; userId?: string }
+  /** Tawk's only documented customStyle field. */
+  customStyleZIndex?: number | string
+  /** When false, defers the socket connection until start() is called. Default: true. */
+  autoStart?: boolean
+  /** Pre-load hook fired before the embed script downloads. */
+  onBeforeLoad?: () => void
 }
 
 export async function load(options: TawkLoadOptions): Promise<void> {
@@ -108,9 +185,31 @@ export async function load(options: TawkLoadOptions): Promise<void> {
   await waitForDefer(options.defer ?? "immediate")
   const a = api()
   w().Tawk_LoadStart = new Date()
-  a.onLoad = () => {
-    queue.ready(a)
-    readyResolve?.()
+  if (options.visitor) a.visitor = { ...options.visitor }
+  if (options.customStyleZIndex !== undefined) {
+    a.customStyle = { ...a.customStyle, zIndex: options.customStyleZIndex }
+  }
+  if (options.autoStart === false) a.autoStart = false
+  // If the caller passed onBeforeLoad as a load option, register it through
+  // the same emitter so the bridge below doesn't clobber it.
+  if (options.onBeforeLoad) {
+    let set = eventListeners.get("beforeLoad")
+    if (!set) {
+      set = new Set()
+      eventListeners.set("beforeLoad", set)
+    }
+    set.add(options.onBeforeLoad)
+  }
+  // Wire every documented Tawk hook to our typed emitter (multi-listener bridge).
+  for (const [hook, eventName] of Object.entries(HOOK_TO_EVENT)) {
+    ;(a as unknown as Record<string, (payload?: unknown) => void>)[hook] = (payload) => {
+      const set = eventListeners.get(eventName)
+      if (set) for (const l of set) l(payload)
+      if (eventName === "load") {
+        queue.ready(a)
+        readyResolve?.()
+      }
+    }
   }
   a.onUnreadCountChanged = (count: number) => {
     for (const l of unreadListeners) l(count)
@@ -142,6 +241,7 @@ export function identify(identity: Identity): Promise<void> {
     const attrs: Record<string, unknown> = {}
     if (identity.name) attrs["name"] = identity.name
     if (identity.email) attrs["email"] = identity.email
+    if (identity.phone) attrs["phone"] = identity.phone
     if (identity.verification?.kind === "hmac") attrs["hash"] = identity.verification.hash
     if (identity.attributes) Object.assign(attrs, identity.attributes)
     a.setAttributes?.(attrs, (err) => {
@@ -205,11 +305,126 @@ export function onUnreadCountChange(listener: (count: number) => void): () => vo
   return () => unreadListeners.delete(listener)
 }
 
-export function switchWidget(options: { propertyId: string; widgetId: string }): Promise<void> {
+export function switchWidget(
+  options: { propertyId: string; widgetId: string },
+  cb?: (err?: Error) => void,
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((a) => {
+    a.switchWidget?.({ propertyId: options.propertyId, widgetId: options.widgetId }, cb)
+  })
+}
+
+function callMethod(name: keyof TawkAPI, ...args: unknown[]): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((a) => {
-    a.switchWidget?.({ propertyId: options.propertyId, widgetId: options.widgetId })
+    const fn = a[name] as ((...rest: unknown[]) => unknown) | undefined
+    fn?.(...args)
+  })
+}
+
+export function maximize(): Promise<void> {
+  return callMethod("maximize")
+}
+
+export function minimize(): Promise<void> {
+  return callMethod("minimize")
+}
+
+export function toggle(): Promise<void> {
+  return callMethod("toggle")
+}
+
+export function popup(): Promise<void> {
+  return callMethod("popup")
+}
+
+export function toggleVisibility(): Promise<void> {
+  return callMethod("toggleVisibility")
+}
+
+export function endChat(): Promise<void> {
+  return callMethod("endChat")
+}
+
+export function start(options?: { showWidget?: boolean }): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((a) => a.start?.(options))
+}
+
+export function addTags(tags: string[], cb?: (err?: Error) => void): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((a) => a.addTags?.(tags, cb))
+}
+
+export function removeTags(tags: string[], cb?: (err?: Error) => void): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((a) => a.removeTags?.(tags, cb))
+}
+
+export function login(
+  user: { name?: string; email?: string; phone?: string; hash?: string; userId?: string },
+  cb?: (err?: Error) => void,
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  store.identify({
+    id: user.userId,
+    name: user.name,
+    email: user.email,
+    phone: user.phone,
+    ...(user.hash ? { verification: { kind: "hmac" as const, hash: user.hash } } : {}),
   })
+  return queue.enqueue((a) => a.login?.(user, cb))
+}
+
+export function logout(cb?: (err?: Error) => void): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  store.reset()
+  return queue.enqueue((a) => a.logout?.(cb))
+}
+
+function syncRead<T>(name: keyof TawkAPI): T | undefined {
+  if (!isBrowser()) return undefined
+  const fn = w().Tawk_API?.[name] as (() => T) | undefined
+  return fn?.()
+}
+
+export function getStatus(): "online" | "away" | "offline" | undefined {
+  return syncRead<"online" | "away" | "offline">("getStatus")
+}
+
+export function getWindowType(): "inline" | "embed" | undefined {
+  return syncRead<"inline" | "embed">("getWindowType")
+}
+
+export function isChatMaximized(): boolean | undefined {
+  return syncRead<boolean>("isChatMaximized")
+}
+
+export function isChatMinimized(): boolean | undefined {
+  return syncRead<boolean>("isChatMinimized")
+}
+
+export function isChatHidden(): boolean | undefined {
+  return syncRead<boolean>("isChatHidden")
+}
+
+export function isChatOngoing(): boolean | undefined {
+  return syncRead<boolean>("isChatOngoing")
+}
+
+export function isVisitorEngaged(): boolean | undefined {
+  return syncRead<boolean>("isVisitorEngaged")
+}
+
+export function on(event: TawkEventName, 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 async function destroy(): Promise<void> {
@@ -222,6 +437,7 @@ export async function destroy(): Promise<void> {
   queue.reset()
   store.reset()
   unreadListeners.clear()
+  eventListeners.clear()
   readyPromise = undefined
   readyResolve = undefined
   lifecycle.clearConfigHash()