feat(jivochat,#87): fix rate limit, add 14 methods, 9 event hooks, pageView

Vendor-doc audit fixes for JivoChat:

Bug fixes:
- Rate limit moved off setContactInfo (not throttled per docs) onto
  setClientAttributes (vendor's documented 10/hr cap). Bucket size also
  bumped from 9 to 10 to match the actual limit. identify() is no longer
  artificially throttled.
- shutdown() no longer calls jivo_api.clearHistory(); that's a destructive
  history wipe, not a logout. clearHistory() is now an explicit method
  callers opt into.

Methods (14): setClientAttributes (rate-limited), setUserToken (called
inside identify when verification.userToken is present), setCustomData,
setWidgetColor, sendOfflineMessage, showProactiveInvitation, startCall,
clearHistory (explicit), plus sync getters chatMode, getUnreadMessagesCount,
getUtm, getContactInfo, and async getVisitorNumber. show({start}) accepts
the documented deep-link parameter.

pageView({path}) is no longer a no-op — it forwards to sendPageTitle().

Event bridge: on(event, handler) gains messageReceived, stateChange,
clientStartChat, introduction, accept, callStart, callEnd, resize,
widgetDestroy. Existing open/close/messageSent kept. New
onUnreadCountChange() listener for parity with other providers.

Bumps jivochat bundle budget 6KB → 8KB (raw 7156B; gzip ≈ 1/3).

NOTE: track() is still a documented no-op — JivoChat has no client-side
event API; the audit confirms there's no documented surface to wire it
through without polluting setContactInfo.description.

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

Author: productdevbook

scripts/bundle-budget.mjs

@@ -19,6 +19,7 @@ const BUDGETS = [
   { 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\/jivochat\.mjs$/, max: 8192, label: "provider:jivochat" },
   { glob: /^providers\/.+\.mjs$/, max: 6144, label: "provider" },
   { glob: /^index\.mjs$/, max: 4096, label: "core" },
   { glob: /^facade\.mjs$/, max: 3072, label: "facade" },

src/providers/jivochat.ts

@@ -18,9 +18,32 @@ interface JivoAPI {
     phone?: string
     description?: string
   }): void
-  open(): void
+  setUserToken?(token: string): void
+  setClientAttributes?(attrs: Record<string, unknown>): void
+  setCustomData?(data: Array<{ title: string; content: string; link?: string }>): void
+  getContactInfo?(): unknown
+  setRules?(rules: unknown): void
+  startCall?(phone: string): void
+  sendOfflineMessage?(payload: {
+    name?: string
+    email?: string
+    phone?: string
+    description?: string
+    message?: string
+  }): void
+  showProactiveInvitation?(text: string, departmentId?: string | number): void
+  setWidgetColor?(color: string, color2?: string): void
+  chatMode?(): "online" | "offline"
+  sendPageTitle?(title: string, fromApi?: boolean, url?: string): void
+  getUnreadMessagesCount?(): number
+  getUtm?(): Record<string, string> | undefined
+  getVisitorNumber?(cb: (n: number) => void): void
+  open(params?: { start?: "chat" | "call" | "menu" }): void
   close(): void
   clearHistory(): void
+  // Top-level lifecycle helpers documented under jivo_ namespace.
+  jivo_destroy?: () => void
+  jivo_init?: () => void
 }
 
 interface JivoWindow {
@@ -29,6 +52,17 @@ interface JivoWindow {
   jivo_onOpen?: () => void
   jivo_onClose?: () => void
   jivo_onMessageSent?: (msg: unknown) => void
+  jivo_onMessageReceived?: (msg: unknown) => void
+  jivo_onChangeState?: (state: unknown) => void
+  jivo_onClientStartChat?: () => void
+  jivo_onIntroduction?: (data: unknown) => void
+  jivo_onAccept?: () => void
+  jivo_onCallStart?: () => void
+  jivo_onCallEnd?: (result: "ok" | "fail") => void
+  jivo_onResizeCallback?: (size: unknown) => void
+  jivo_onWidgetDestroy?: () => void
+  jivo_destroy?: () => void
+  jivo_init?: () => void
 }
 
 function w(): JivoWindow {
@@ -40,19 +74,35 @@ const store = createIdentityStore()
 const lifecycle = createLifecycle()
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
-const openListeners = new Set<() => void>()
-const closeListeners = new Set<() => void>()
-const messageListeners = new Set<(msg: unknown) => void>()
 
-// Token bucket: 9 calls per hour to stay under JivoChat's 10/hr limit.
-const RATE_LIMIT_MAX = 9
+export type JivoEventName =
+  | "open"
+  | "close"
+  | "messageSent"
+  | "messageReceived"
+  | "stateChange"
+  | "clientStartChat"
+  | "introduction"
+  | "accept"
+  | "callStart"
+  | "callEnd"
+  | "resize"
+  | "widgetDestroy"
+
+const eventListeners = new Map<JivoEventName, Set<(payload?: unknown) => void>>()
+const unreadListeners = new Set<(count: number) => void>()
+
+// Token bucket: 10 calls per hour for setClientAttributes (vendor's 10/hr limit
+// applies to setClientAttributes; the previous wrapper applied it to
+// setContactInfo, which is unthrottled per the docs).
+const CLIENT_ATTR_LIMIT = 10
 const RATE_WINDOW_MS = 60 * 60 * 1000
-let bucket: number[] = []
-function takeContactInfoToken(): boolean {
+let clientAttrBucket: number[] = []
+function takeClientAttrToken(): boolean {
   const now = Date.now()
-  bucket = bucket.filter((ts) => now - ts < RATE_WINDOW_MS)
-  if (bucket.length >= RATE_LIMIT_MAX) return false
-  bucket.push(now)
+  clientAttrBucket = clientAttrBucket.filter((ts) => now - ts < RATE_WINDOW_MS)
+  if (clientAttrBucket.length >= CLIENT_ATTR_LIMIT) return false
+  clientAttrBucket.push(now)
   return true
 }
 
@@ -76,15 +126,24 @@ export async function load(options: JivoChatLoadOptions): Promise<void> {
 
   // Multi-listener bridge — JivoChat allows only one global callback per event.
   w().jivo_onLoadCallback = () => readyResolve?.()
-  w().jivo_onOpen = () => {
-    for (const l of openListeners) l()
-  }
-  w().jivo_onClose = () => {
-    for (const l of closeListeners) l()
-  }
-  w().jivo_onMessageSent = (msg) => {
-    for (const l of messageListeners) l(msg)
-  }
+  const fanOut =
+    (event: JivoEventName) =>
+    (payload?: unknown): void => {
+      const set = eventListeners.get(event)
+      if (set) for (const l of set) l(payload)
+    }
+  w().jivo_onOpen = fanOut("open")
+  w().jivo_onClose = fanOut("close")
+  w().jivo_onMessageSent = fanOut("messageSent")
+  w().jivo_onMessageReceived = fanOut("messageReceived")
+  w().jivo_onChangeState = fanOut("stateChange")
+  w().jivo_onClientStartChat = fanOut("clientStartChat")
+  w().jivo_onIntroduction = fanOut("introduction")
+  w().jivo_onAccept = fanOut("accept")
+  w().jivo_onCallStart = fanOut("callStart")
+  w().jivo_onCallEnd = fanOut("callEnd") as (result: "ok" | "fail") => void
+  w().jivo_onResizeCallback = fanOut("resize")
+  w().jivo_onWidgetDestroy = fanOut("widgetDestroy")
 
   try {
     await injectScript({
@@ -116,22 +175,31 @@ export function ready(): Promise<void> {
 
 export function identify(identity: Identity): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  if (!takeContactInfoToken()) {
-    console.warn(
-      "[ahize/jivochat] setContactInfo throttled (>9 calls/hour); skipped to stay under JivoChat's rate limit.",
-    )
-    return Promise.resolve()
-  }
   store.identify(identity)
   return queue.enqueue((api) => {
     api.setContactInfo({
       name: identity.name,
       email: identity.email,
       phone: identity.phone,
     })
+    if (identity.verification && "userToken" in identity.verification) {
+      const token = (identity.verification as { userToken?: string }).userToken
+      if (token) api.setUserToken?.(token)
+    }
   })
 }
 
+export function setClientAttributes(attrs: Record<string, unknown>): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  if (!takeClientAttrToken()) {
+    console.warn(
+      "[ahize/jivochat] setClientAttributes throttled (>10 calls/hour) per JivoChat's documented rate limit.",
+    )
+    return Promise.resolve()
+  }
+  return queue.enqueue((api) => api.setClientAttributes?.(attrs))
+}
+
 export function track<T extends EventMetadata = EventMetadata>(
   _event: string,
   _metadata?: T,
@@ -140,38 +208,121 @@ export function track<T extends EventMetadata = EventMetadata>(
   return Promise.resolve()
 }
 
-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.sendPageTitle) {
+      api.sendPageTitle(typeof document === "undefined" ? "" : "", true, info.path)
+    }
+  })
 }
 
-export function show(): Promise<void> {
+export function show(params?: { start?: "chat" | "call" | "menu" }): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  return queue.enqueue((api) => api.open())
+  return queue.enqueue((api) => (params ? api.open(params) : api.open()))
 }
 
 export function hide(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((api) => api.close())
 }
 
-export function on(
-  event: "open" | "close" | "message",
-  listener: (payload?: unknown) => void,
-): () => void {
-  const set =
-    event === "open" ? openListeners : event === "close" ? closeListeners : messageListeners
-  set.add(listener as () => void)
-  return () => set.delete(listener as () => void)
+export function setCustomData(
+  data: Array<{ title: string; content: string; link?: string }>,
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.setCustomData?.(data))
+}
+
+export function startCall(phone: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.startCall?.(phone))
+}
+
+export function sendOfflineMessage(payload: {
+  name?: string
+  email?: string
+  phone?: string
+  description?: string
+  message?: string
+}): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.sendOfflineMessage?.(payload))
+}
+
+export function showProactiveInvitation(
+  text: string,
+  departmentId?: string | number,
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.showProactiveInvitation?.(text, departmentId))
+}
+
+export function setWidgetColor(color: string, color2?: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.setWidgetColor?.(color, color2))
+}
+
+export function clearHistory(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((api) => api.clearHistory())
+}
+
+export function chatMode(): "online" | "offline" | undefined {
+  if (!isBrowser()) return undefined
+  return w().jivo_api?.chatMode?.()
+}
+
+export function getUnreadMessagesCount(): number | undefined {
+  if (!isBrowser()) return undefined
+  return w().jivo_api?.getUnreadMessagesCount?.()
+}
+
+export function getUtm(): Record<string, string> | undefined {
+  if (!isBrowser()) return undefined
+  return w().jivo_api?.getUtm?.()
+}
+
+export function getContactInfo(): unknown {
+  if (!isBrowser()) return undefined
+  return w().jivo_api?.getContactInfo?.()
+}
+
+export function getVisitorNumber(): Promise<number | undefined> {
+  if (!isBrowser()) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    const api = w().jivo_api
+    if (!api?.getVisitorNumber) {
+      resolve(undefined)
+      return
+    }
+    api.getVisitorNumber((n: number) => resolve(n))
+  })
+}
+
+export function on(event: JivoEventName, 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 onUnreadCountChange(listener: (count: number) => void): () => void {
+  unreadListeners.add(listener)
+  return () => unreadListeners.delete(listener)
 }
 
 export function shutdown(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  return queue
-    .enqueue((api) => api.clearHistory())
-    .then(() => {
-      store.reset()
-      lifecycle.transition("shutdown")
-    })
+  // Vendor doesn't expose a logout/end-session method; just reset our local
+  // state and let the snippet keep its session. Use clearHistory() explicitly
+  // if the caller wants to wipe browser-side history.
+  store.reset()
+  lifecycle.transition("shutdown")
+  return Promise.resolve()
 }
 
 export async function destroy(): Promise<void> {
@@ -185,15 +336,23 @@ export async function destroy(): Promise<void> {
     "jivo_onOpen",
     "jivo_onClose",
     "jivo_onMessageSent",
+    "jivo_onMessageReceived",
+    "jivo_onChangeState",
+    "jivo_onClientStartChat",
+    "jivo_onIntroduction",
+    "jivo_onAccept",
+    "jivo_onCallStart",
+    "jivo_onCallEnd",
+    "jivo_onResizeCallback",
+    "jivo_onWidgetDestroy",
   ]) {
     Reflect.deleteProperty(g, k)
   }
   queue.reset()
   store.reset()
-  openListeners.clear()
-  closeListeners.clear()
-  messageListeners.clear()
-  bucket = []
+  eventListeners.clear()
+  unreadListeners.clear()
+  clientAttrBucket = []
   readyPromise = undefined
   readyResolve = undefined
   lifecycle.clearConfigHash()