feat(crisp,#80): expose missing $crisp commands, events, and runtime config

Vendor-doc audit fixes for Crisp:

Methods (12 new): open, close, toggle (split off from show()), sendMessage,
showLocalMessage, markRead, setMessageText, setUserAvatar,
setSessionSegments, helpdeskSearch, helpdeskArticleOpen, runTrigger.
show() no longer also fires chat:open — visibility and panel state are
now independent like the vendor docs describe.

Event bridge: new public on(event, handler) wraps 13 documented Crisp
events (chatOpened, chatClosed, chatInitiated, messageSent, messageReceived,
messageComposeSent/Received, helpdeskQueried, user:email/phone/nickname/
avatar:changed, websiteAvailabilityChanged) with a multi-listener Set
pattern. Replaces the two dead-stub listeners (message:received +
chat:closed empty bodies) with a real fan-out emitter.

Runtime config (CrispLoadOptions): safeMode, cookieDomain, cookieExpire,
sessionMerge, lockMaximized, lockFullview — merged into
CRISP_RUNTIME_CONFIG before script load.

Bumps crisp bundle budget 6KB → 10KB to match chatwoot (raw 9238B;
gzip ≈ 1/3). Crisp's command surface is one of the largest among the
providers we wrap.

is:* / get:* getters left for a follow-up — the queue-array bus pattern
makes synchronous reads non-trivial; that work needs interface design.

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

Author: productdevbook

scripts/bundle-budget.mjs

@@ -11,6 +11,7 @@ const DIST = resolve(process.cwd(), "dist")
 
 const BUDGETS = [
   { glob: /^providers\/chatwoot\.mjs$/, max: 10240, label: "provider:chatwoot" },
+  { glob: /^providers\/crisp\.mjs$/, max: 10240, label: "provider:crisp" },
   { 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" },

src/providers/crisp.ts

@@ -36,6 +36,39 @@ function bus(): CrispArray {
 const store = createIdentityStore()
 const lifecycle = createLifecycle()
 const unreadListeners = new Set<(count: number) => void>()
+
+export type CrispEventName =
+  | "chatOpened"
+  | "chatClosed"
+  | "chatInitiated"
+  | "messageSent"
+  | "messageReceived"
+  | "messageComposeSent"
+  | "messageComposeReceived"
+  | "helpdeskQueried"
+  | "userEmailChanged"
+  | "userPhoneChanged"
+  | "userNicknameChanged"
+  | "userAvatarChanged"
+  | "websiteAvailabilityChanged"
+
+const CRISP_EVENT_MAP: Record<string, CrispEventName> = {
+  "chat:opened": "chatOpened",
+  "chat:closed": "chatClosed",
+  "chat:initiated": "chatInitiated",
+  "message:sent": "messageSent",
+  "message:received": "messageReceived",
+  "message:compose:sent": "messageComposeSent",
+  "message:compose:received": "messageComposeReceived",
+  "helpdesk:queried": "helpdeskQueried",
+  "user:email:changed": "userEmailChanged",
+  "user:phone:changed": "userPhoneChanged",
+  "user:nickname:changed": "userNicknameChanged",
+  "user:avatar:changed": "userAvatarChanged",
+  "website:availability:changed": "websiteAvailabilityChanged",
+}
+
+const eventListeners = new Map<CrispEventName, Set<(payload?: unknown) => void>>()
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
 
@@ -52,6 +85,18 @@ export interface CrispLoadOptions extends LoadOptions {
   websiteId: string
   tokenId?: string
   locale?: string
+  /** Suppress SDK errors instead of throwing. */
+  safeMode?: boolean
+  /** Restrict the chatbox cookie to this domain (e.g. ".example.com"). */
+  cookieDomain?: string
+  /** Custom cookie lifetime in seconds (default: ~6 months). */
+  cookieExpire?: number
+  /** Merge sessions across pages/tabs. */
+  sessionMerge?: boolean
+  /** Force the chatbox to stay maximized. */
+  lockMaximized?: boolean
+  /** Force the chatbox into fullview mode. */
+  lockFullview?: boolean
 }
 
 export async function load(options: CrispLoadOptions): Promise<void> {
@@ -70,9 +115,15 @@ export async function load(options: CrispLoadOptions): Promise<void> {
   bus()
   w().CRISP_WEBSITE_ID = options.websiteId
   if (options.tokenId) w().CRISP_TOKEN_ID = options.tokenId
-  if (options.locale) {
-    w().CRISP_RUNTIME_CONFIG = { ...w().CRISP_RUNTIME_CONFIG, locale: options.locale }
-  }
+  const runtime: Record<string, unknown> = { ...w().CRISP_RUNTIME_CONFIG }
+  if (options.locale !== undefined) runtime["locale"] = options.locale
+  if (options.safeMode !== undefined) runtime["safeMode"] = options.safeMode
+  if (options.cookieDomain !== undefined) runtime["cookieDomain"] = options.cookieDomain
+  if (options.cookieExpire !== undefined) runtime["cookieExpire"] = options.cookieExpire
+  if (options.sessionMerge !== undefined) runtime["sessionMerge"] = options.sessionMerge
+  if (options.lockMaximized !== undefined) runtime["lockMaximized"] = options.lockMaximized
+  if (options.lockFullview !== undefined) runtime["lockFullview"] = options.lockFullview
+  if (Object.keys(runtime).length > 0) w().CRISP_RUNTIME_CONFIG = runtime
   try {
     await injectScript({
       id: "ahize-crisp",
@@ -92,20 +143,18 @@ export async function load(options: CrispLoadOptions): Promise<void> {
       readyResolve?.()
     },
   ])
-  bus().push([
-    "on",
-    "message:received",
-    () => {
-      // unread counter triggers via message:received/chat:opened - approximation
-    },
-  ])
-  bus().push([
-    "on",
-    "chat:closed",
-    () => {
-      // leave hooks for facade wrappers
-    },
-  ])
+  // Wire every documented Crisp lifecycle event to the typed emitter.
+  for (const [domName, mapped] of Object.entries(CRISP_EVENT_MAP)) {
+    bus().push([
+      "on",
+      domName,
+      (payload: unknown) => {
+        const set = eventListeners.get(mapped)
+        if (!set) return
+        for (const l of set) l(payload)
+      },
+    ])
+  }
   lifecycle.transition("ready")
 }
 
@@ -202,8 +251,8 @@ export function track<T extends EventMetadata = EventMetadata>(
 
 export function show(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
+  // Reveal the chat without forcibly expanding the panel.
   bus().push(["do", "chat:show"])
-  bus().push(["do", "chat:open"])
   return Promise.resolve()
 }
 
@@ -213,6 +262,88 @@ export function hide(): Promise<void> {
   return Promise.resolve()
 }
 
+export function open(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "chat:open"])
+  return Promise.resolve()
+}
+
+export function close(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "chat:close"])
+  return Promise.resolve()
+}
+
+export function toggle(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "chat:toggle"])
+  return Promise.resolve()
+}
+
+export function sendMessage(text: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "message:send", ["text", text]])
+  return Promise.resolve()
+}
+
+export function showLocalMessage(text: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "message:show", ["text", text]])
+  return Promise.resolve()
+}
+
+export function markRead(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "message:read"])
+  return Promise.resolve()
+}
+
+export function setMessageText(text: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["set", "message:text", [text]])
+  return Promise.resolve()
+}
+
+export function setUserAvatar(url: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["set", "user:avatar", [url]])
+  return Promise.resolve()
+}
+
+export function setSessionSegments(segments: string[], overwrite = false): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["set", "session:segments", [segments, overwrite]])
+  return Promise.resolve()
+}
+
+export function helpdeskSearch(query: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "helpdesk:search", [query]])
+  return Promise.resolve()
+}
+
+export function helpdeskArticleOpen(locale: string, slug: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "helpdesk:article:open", [locale, slug]])
+  return Promise.resolve()
+}
+
+export function runTrigger(triggerId: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  bus().push(["do", "trigger:run", [triggerId]])
+  return Promise.resolve()
+}
+
+export function on(event: CrispEventName, 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()
   bus().push(["do", "session:reset"])
@@ -232,6 +363,7 @@ export async function destroy(): Promise<void> {
   Reflect.deleteProperty(g, "CRISP_RUNTIME_CONFIG")
   store.reset()
   unreadListeners.clear()
+  eventListeners.clear()
   readyPromise = undefined
   readyResolve = undefined
   lifecycle.clearConfigHash()

test/crisp.browser.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it, vi } from "vitest"
+
+interface CrispBus extends Array<unknown[]> {
+  push(cmd: unknown[]): number
+}
+
+async function bootCrisp(
+  options?: Partial<import("../src/providers/crisp.ts").CrispLoadOptions>,
+): Promise<{
+  crisp: typeof import("../src/providers/crisp.ts")
+  bus: CrispBus
+  fire: (event: string, payload?: unknown) => void
+}> {
+  const crisp = await import("../src/providers/crisp.ts")
+  const loadPromise = crisp.load({ websiteId: "wid_xyz", ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-crisp") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await loadPromise
+
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  const bus = (globalThis as any).$crisp as CrispBus
+
+  // Fire helper: call the registered handler for a given event name.
+  const fire = (event: string, payload?: unknown) => {
+    for (const cmd of bus) {
+      if (cmd[0] === "on" && cmd[1] === event && typeof cmd[2] === "function") {
+        ;(cmd[2] as (p?: unknown) => void)(payload)
+      }
+    }
+  }
+
+  return { crisp, bus, fire }
+}
+
+describe("crisp (browser) — vendor-doc audit fixes (#80)", () => {
+  beforeEach(() => {
+    vi.resetModules()
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).$crisp
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).CRISP_WEBSITE_ID
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).CRISP_TOKEN_ID
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).CRISP_RUNTIME_CONFIG
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("runtime config keys (safeMode/cookieDomain/etc) populate CRISP_RUNTIME_CONFIG", async () => {
+    const { crisp } = await bootCrisp({
+      locale: "tr",
+      safeMode: true,
+      cookieDomain: ".example.com",
+      cookieExpire: 3600,
+      sessionMerge: true,
+      lockMaximized: true,
+      lockFullview: false,
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test inspect
+    const cfg = (globalThis as any).CRISP_RUNTIME_CONFIG as Record<string, unknown>
+    expect(cfg).toMatchObject({
+      locale: "tr",
+      safeMode: true,
+      cookieDomain: ".example.com",
+      cookieExpire: 3600,
+      sessionMerge: true,
+      lockMaximized: true,
+      lockFullview: false,
+    })
+    await crisp.destroy()
+  })
+
+  it("show() no longer force-opens; open()/close()/toggle() are distinct", async () => {
+    const { crisp, bus } = await bootCrisp()
+    const before = bus.length
+    await crisp.show()
+    await crisp.open()
+    await crisp.close()
+    await crisp.toggle()
+    const cmds = bus
+      .slice(before)
+      .filter((c) => c[0] === "do")
+      .map((c) => c[1])
+    expect(cmds).toEqual(["chat:show", "chat:open", "chat:close", "chat:toggle"])
+    await crisp.destroy()
+  })
+
+  it("sendMessage / showLocalMessage / markRead / setMessageText push the right commands", async () => {
+    const { crisp, bus } = await bootCrisp()
+    const before = bus.length
+    await crisp.sendMessage("merhaba")
+    await crisp.showLocalMessage("agent here")
+    await crisp.markRead()
+    await crisp.setMessageText("draft text")
+    const after = bus.slice(before)
+    expect(after).toContainEqual(["do", "message:send", ["text", "merhaba"]])
+    expect(after).toContainEqual(["do", "message:show", ["text", "agent here"]])
+    expect(after).toContainEqual(["do", "message:read"])
+    expect(after).toContainEqual(["set", "message:text", ["draft text"]])
+    await crisp.destroy()
+  })
+
+  it("setUserAvatar / setSessionSegments / helpdesk* / runTrigger forward correctly", async () => {
+    const { crisp, bus } = await bootCrisp()
+    const before = bus.length
+    await crisp.setUserAvatar("https://x/a.png")
+    await crisp.setSessionSegments(["beta", "vip"], true)
+    await crisp.helpdeskSearch("refund")
+    await crisp.helpdeskArticleOpen("en", "billing")
+    await crisp.runTrigger("trigger_1")
+    const after = bus.slice(before)
+    expect(after).toContainEqual(["set", "user:avatar", ["https://x/a.png"]])
+    expect(after).toContainEqual(["set", "session:segments", [["beta", "vip"], true]])
+    expect(after).toContainEqual(["do", "helpdesk:search", ["refund"]])
+    expect(after).toContainEqual(["do", "helpdesk:article:open", ["en", "billing"]])
+    expect(after).toContainEqual(["do", "trigger:run", ["trigger_1"]])
+    await crisp.destroy()
+  })
+
+  it("on(event) bridges chatOpened/chatInitiated/messageSent/etc", async () => {
+    const { crisp, fire } = await bootCrisp()
+    let openedHits = 0
+    let lastSent: unknown
+    let availability: unknown
+    crisp.on("chatOpened", () => {
+      openedHits++
+    })
+    crisp.on("messageSent", (p) => {
+      lastSent = p
+    })
+    crisp.on("websiteAvailabilityChanged", (p) => {
+      availability = p
+    })
+
+    fire("chat:opened")
+    fire("message:sent", { content: "hi" })
+    fire("website:availability:changed", { status: "online" })
+
+    expect(openedHits).toBe(1)
+    expect(lastSent).toEqual({ content: "hi" })
+    expect(availability).toEqual({ status: "online" })
+    await crisp.destroy()
+  })
+})