feat(helpscout,#84): expose missing Beacon commands, events, and init config

Vendor-doc audit fixes for HelpScout Beacon:

Methods (10 new): search, article (with type sidebar/modal), sessionData
(20 conversation attributes), config (runtime reconfiguration), reset
(clear contact-form fields without logging out), toggle, askQuestion (AI
Answers prefill), showMessage (with delay/force), info (sync state read),
once (one-shot listener). prefill() also gains attachments support, and
shutdown() forwards clearMessages.

Events (5 added to BeaconEvent union): search, message-clicked,
message-closed, message-triggered, plus existing entries kept for
backward compatibility (chat-ended retained even though not in current
public docs).

Init config: HelpScoutLoadOptions now accepts an optional `config` object
typed as BeaconConfig (docsEnabled/messagingEnabled/color/mode/display/
messaging/labels/etc.) merged into Beacon("init", { beaconId, ...config }).

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

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

Author: productdevbook

scripts/bundle-budget.mjs

@@ -12,6 +12,7 @@ const DIST = resolve(process.cwd(), "dist")
 const BUDGETS = [
   { glob: /^providers\/chatwoot\.mjs$/, max: 10240, label: "provider:chatwoot" },
   { glob: /^providers\/intercom\.mjs$/, max: 9216, label: "provider:intercom" },
+  { glob: /^providers\/helpscout\.mjs$/, max: 7168, label: "provider:helpscout" },
   { glob: /^providers\/.+\.mjs$/, max: 6144, label: "provider" },
   { glob: /^index\.mjs$/, max: 4096, label: "core" },
   { glob: /^facade\.mjs$/, max: 3072, label: "facade" },

src/providers/helpscout.ts

@@ -27,8 +27,46 @@ const lifecycle = createLifecycle()
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
 
+export type BeaconMode = "selfService" | "neutral" | "askFirst"
+
+export interface BeaconDisplayConfig {
+  style?: "icon" | "text" | "iconAndText"
+  text?: string
+  position?: "left" | "right"
+  zIndex?: number
+  horizontalOffset?: number | string
+  verticalOffset?: number | string
+}
+
+export interface BeaconMessagingConfig {
+  chatEnabled?: boolean
+  contactForm?: {
+    customFieldsEnabled?: boolean
+    showName?: boolean
+    showSubject?: boolean
+    allowAttachments?: boolean
+  }
+}
+
+export interface BeaconConfig {
+  docsEnabled?: boolean
+  messagingEnabled?: boolean
+  enableFabAnimation?: boolean
+  enablePreviousMessages?: boolean
+  enableSounds?: boolean
+  color?: string
+  mode?: BeaconMode
+  hideAvatars?: boolean
+  hideFABOnMobile?: boolean
+  display?: BeaconDisplayConfig
+  messaging?: BeaconMessagingConfig
+  labels?: Record<string, string>
+}
+
 export interface HelpScoutLoadOptions extends LoadOptions {
   beaconId: string
+  /** Optional Beacon `init` config object (display, color, mode, labels, etc.). */
+  config?: BeaconConfig
 }
 
 export async function load(options: HelpScoutLoadOptions): Promise<void> {
@@ -61,7 +99,10 @@ export async function load(options: HelpScoutLoadOptions): Promise<void> {
   for (let i = 0; i < 80; i++) {
     const beacon = w().Beacon
     if (typeof beacon === "function") {
-      beacon("init", options.beaconId)
+      const initArg = options.config
+        ? { beaconId: options.beaconId, ...options.config }
+        : options.beaconId
+      beacon("init", initArg)
       beacon("on", "ready", () => {
         queue.ready(beacon)
         readyResolve?.()
@@ -122,33 +163,109 @@ export function suggest(articleIds: string[]): Promise<void> {
   return queue.enqueue((Beacon) => Beacon("suggest", ids))
 }
 
-export function navigate(path: string): Promise<void> {
+export type BeaconRoute =
+  | "/ask/"
+  | "/ask/message/"
+  | "/ask/chat/"
+  | "/answers/"
+  | "/ai-answers/"
+  | "/previous-messages/"
+  | (string & {})
+
+export function navigate(path: BeaconRoute): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((Beacon) => Beacon("navigate", path))
 }
 
+export function search(query: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("search", query))
+}
+
+export function article(
+  articleId: string,
+  options?: { type?: "sidebar" | "modal" },
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) =>
+    options ? Beacon("article", articleId, options) : Beacon("article", articleId),
+  )
+}
+
+export function sessionData(data: Record<string, string>): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("session-data", data))
+}
+
+export function config(next: BeaconConfig): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("config", next))
+}
+
+export function reset(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("reset"))
+}
+
+export function toggle(): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("toggle"))
+}
+
+export function askQuestion(question: string): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) => Beacon("ask-question", question))
+}
+
+export function showMessage(
+  id: string,
+  options?: { delay?: number; force?: boolean },
+): Promise<void> {
+  if (!isBrowser()) return Promise.resolve()
+  return queue.enqueue((Beacon) =>
+    options ? Beacon("show-message", id, options) : Beacon("show-message", id),
+  )
+}
+
+export function info(): Promise<unknown> {
+  if (!isBrowser()) return Promise.resolve(undefined)
+  return new Promise((resolve) => {
+    queue
+      .enqueue((Beacon) => {
+        const result = (Beacon as unknown as (cmd: string) => unknown)("info")
+        resolve(result)
+      })
+      .catch(() => resolve(undefined))
+  })
+}
+
 export function prefill(payload: {
   name?: string
   email?: string
   subject?: string
   text?: string
   fields?: Array<{ id: number; value: string }>
+  /** Up to 3 file attachments. */
+  attachments?: Array<{ url: string; filename: string }>
 }): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((Beacon) => Beacon("prefill", payload))
 }
 
-export function on(
-  event:
-    | "ready"
-    | "open"
-    | "close"
-    | "article-viewed"
-    | "email-sent"
-    | "chat-started"
-    | "chat-ended",
-  listener: (payload: unknown) => void,
-): () => void {
+export type BeaconEvent =
+  | "ready"
+  | "open"
+  | "close"
+  | "article-viewed"
+  | "email-sent"
+  | "chat-started"
+  | "chat-ended"
+  | "search"
+  | "message-clicked"
+  | "message-closed"
+  | "message-triggered"
+
+export function on(event: BeaconEvent, listener: (payload: unknown) => void): () => void {
   if (!isBrowser()) return () => {}
   let removed = false
   queue.enqueue((Beacon) => {
@@ -160,6 +277,18 @@ export function on(
   }
 }
 
+export function once(event: BeaconEvent, listener: (payload: unknown) => void): () => void {
+  if (!isBrowser()) return () => {}
+  let removed = false
+  queue.enqueue((Beacon) => {
+    if (!removed) Beacon("once", event, listener)
+  })
+  return () => {
+    removed = true
+    queue.enqueue((Beacon) => Beacon("off", event, listener))
+  }
+}
+
 export function show(): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   return queue.enqueue((Beacon) => Beacon("open"))
@@ -170,11 +299,15 @@ export function hide(): Promise<void> {
   return queue.enqueue((Beacon) => Beacon("close"))
 }
 
-export function shutdown(opts?: { endActiveChat?: boolean }): Promise<void> {
+export function shutdown(opts?: {
+  endActiveChat?: boolean
+  clearMessages?: boolean
+}): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
-  const endActiveChat = opts?.endActiveChat ?? true
+  const payload: Record<string, unknown> = { endActiveChat: opts?.endActiveChat ?? true }
+  if (opts?.clearMessages !== undefined) payload["clearMessages"] = opts.clearMessages
   return queue
-    .enqueue((Beacon) => Beacon("logout", { endActiveChat }))
+    .enqueue((Beacon) => Beacon("logout", payload))
     .then(() => {
       store.reset()
       lifecycle.transition("shutdown")

test/helpscout.browser.test.ts

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from "vitest"
+
+interface BeaconCall {
+  method: string
+  args: unknown[]
+}
+
+function recorderBeacon(calls: BeaconCall[]): (method: string, ...args: unknown[]) => unknown {
+  return (method, ...args) => {
+    calls.push({ method, args })
+    if (method === "on" && args[0] === "ready" && typeof args[1] === "function") {
+      ;(args[1] as () => void)()
+    }
+    if (method === "info") return { open: false, beaconId: "test" }
+    return undefined
+  }
+}
+
+async function bootHelpScout(
+  calls: BeaconCall[],
+  options?: Partial<import("../src/providers/helpscout.ts").HelpScoutLoadOptions>,
+): Promise<typeof import("../src/providers/helpscout.ts")> {
+  const helpscout = await import("../src/providers/helpscout.ts")
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).Beacon = recorderBeacon(calls)
+  const loadPromise = helpscout.load({ beaconId: "bid_xyz", ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-helpscout") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  await loadPromise
+  return helpscout
+}
+
+describe("helpscout (browser) — vendor-doc audit fixes (#84)", () => {
+  beforeEach(() => {
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).Beacon
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("init forwards a config object when provided", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls, {
+      config: {
+        color: "#abcdef",
+        mode: "askFirst",
+        display: { style: "iconAndText", position: "left", zIndex: 99 },
+        labels: { greeting: "Selam" },
+      },
+    })
+    const initCall = calls.find((c) => c.method === "init")
+    expect(initCall).toBeTruthy()
+    expect(initCall?.args[0]).toMatchObject({
+      beaconId: "bid_xyz",
+      color: "#abcdef",
+      mode: "askFirst",
+      display: { style: "iconAndText", position: "left", zIndex: 99 },
+      labels: { greeting: "Selam" },
+    })
+    await helpscout.destroy()
+  })
+
+  it("init falls back to bare beaconId when no config", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+    const initCall = calls.find((c) => c.method === "init")
+    expect(initCall?.args).toEqual(["bid_xyz"])
+    await helpscout.destroy()
+  })
+
+  it("forwards search/article/sessionData/config/reset/toggle/askQuestion/showMessage", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+
+    await helpscout.search("how to refund")
+    await helpscout.article("art_1", { type: "modal" })
+    await helpscout.sessionData({ plan: "pro", country: "TR" })
+    await helpscout.config({ color: "#000" })
+    await helpscout.reset()
+    await helpscout.toggle()
+    await helpscout.askQuestion("Where is my order?")
+    await helpscout.showMessage("msg_1", { delay: 500, force: true })
+
+    const methods = calls.map((c) => c.method)
+    expect(methods).toContain("search")
+    expect(methods).toContain("article")
+    expect(methods).toContain("session-data")
+    expect(methods).toContain("config")
+    expect(methods).toContain("reset")
+    expect(methods).toContain("toggle")
+    expect(methods).toContain("ask-question")
+    expect(methods).toContain("show-message")
+
+    expect(calls.find((c) => c.method === "article")?.args).toEqual(["art_1", { type: "modal" }])
+    expect(calls.find((c) => c.method === "show-message")?.args).toEqual([
+      "msg_1",
+      { delay: 500, force: true },
+    ])
+    await helpscout.destroy()
+  })
+
+  it("info() returns the Beacon synchronous result", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+    const result = await helpscout.info()
+    expect(result).toEqual({ open: false, beaconId: "test" })
+    await helpscout.destroy()
+  })
+
+  it("on('search'|'message-clicked'|'message-closed'|'message-triggered') subscribes via Beacon", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+
+    helpscout.on("search", () => {})
+    helpscout.on("message-clicked", () => {})
+    helpscout.on("message-closed", () => {})
+    helpscout.on("message-triggered", () => {})
+    await new Promise((r) => setTimeout(r, 0))
+
+    const subscribed = calls.filter((c) => c.method === "on").map((c) => c.args[0])
+    expect(subscribed).toContain("search")
+    expect(subscribed).toContain("message-clicked")
+    expect(subscribed).toContain("message-closed")
+    expect(subscribed).toContain("message-triggered")
+    await helpscout.destroy()
+  })
+
+  it("once() registers a one-shot Beacon listener", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+    helpscout.once("open", () => {})
+    await new Promise((r) => setTimeout(r, 0))
+    const onceCall = calls.find((c) => c.method === "once")
+    expect(onceCall?.args[0]).toBe("open")
+    await helpscout.destroy()
+  })
+
+  it("shutdown forwards clearMessages when provided", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+    await helpscout.shutdown({ endActiveChat: false, clearMessages: true })
+    const logoutCall = calls.find((c) => c.method === "logout")
+    expect(logoutCall?.args[0]).toEqual({ endActiveChat: false, clearMessages: true })
+    await helpscout.destroy()
+  })
+
+  it("prefill accepts attachments", async () => {
+    const calls: BeaconCall[] = []
+    const helpscout = await bootHelpScout(calls)
+    await helpscout.prefill({
+      name: "x",
+      attachments: [{ url: "https://x/a.png", filename: "a.png" }],
+    })
+    const prefill = calls.find((c) => c.method === "prefill")
+    expect(prefill?.args[0]).toMatchObject({
+      attachments: [{ url: "https://x/a.png", filename: "a.png" }],
+    })
+    await helpscout.destroy()
+  })
+})