feat(hubspot,#85): add AP1 region, event bridges, typed config, status()

Vendor-doc audit fixes for HubSpot Conversations Chat Widget:

- Region: HubSpotRegion now "na1" | "eu1" | "ap1" with the correct
  js-ap1.hs-scripts.com host (previously AP1 portals fell back to NA1
  and loaded the wrong CDN).
- Event bridges (7): on(event) now subscribes to conversationStarted,
  conversationClosed, userSelectedThread, contactAssociated,
  userInteractedWithWidget, widgetLoaded, widgetClosed,
  quickReplyButtonClick — same multi-listener pattern as
  onUnreadCountChange.
- Typed config (7 fields on HubSpotLoadOptions): inlineEmbedSelector,
  enableWidgetCookieBanner, disableAttachment, disableInitialInputFocus,
  avoidInlineStyles, hideNewThreadLink, loadImmediately. Merged into
  hsConversationsSettings before boot.
- New status() helper exposes widget.status() ({ loaded, pending }).
- identify() error message and warn() copy no longer call HubSpot's
  identification token a "JWT" — vendor mints an opaque token, not a JWT.

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

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

Author: productdevbook

scripts/bundle-budget.mjs

@@ -13,6 +13,7 @@ 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\/hubspot\.mjs$/, max: 7168, label: "provider:hubspot" },
   { glob: /^providers\/.+\.mjs$/, max: 6144, label: "provider" },
   { glob: /^index\.mjs$/, max: 4096, label: "core" },
   { glob: /^facade\.mjs$/, max: 3072, label: "facade" },

src/providers/hubspot.ts

@@ -18,6 +18,7 @@ interface HubSpotConversations {
     close(): void
     remove(): void
     refresh(options?: { openToNewThread?: boolean }): void
+    status?(): { loaded: boolean; pending: boolean }
   }
   clear(options?: { resetWidget?: boolean }): void
   on(event: string, listener: (payload: unknown) => void): void
@@ -45,12 +46,59 @@ const conversations = createQueue<HubSpotConversations>()
 const store = createIdentityStore()
 const lifecycle = createLifecycle()
 const unreadListeners = new Set<(count: number) => void>()
+type HubSpotEventName =
+  | "conversationStarted"
+  | "conversationClosed"
+  | "userSelectedThread"
+  | "contactAssociated"
+  | "userInteractedWithWidget"
+  | "widgetLoaded"
+  | "widgetClosed"
+  | "quickReplyButtonClick"
+const eventListeners = new Map<HubSpotEventName, Set<(payload: unknown) => void>>()
+const HUBSPOT_EVENTS: readonly HubSpotEventName[] = [
+  "conversationStarted",
+  "conversationClosed",
+  "userSelectedThread",
+  "contactAssociated",
+  "userInteractedWithWidget",
+  "widgetLoaded",
+  "widgetClosed",
+  "quickReplyButtonClick",
+]
 let readyPromise: Promise<void> | undefined
 let readyResolve: (() => void) | undefined
 
+const TYPED_SETTINGS_KEYS = [
+  "inlineEmbedSelector",
+  "enableWidgetCookieBanner",
+  "disableAttachment",
+  "disableInitialInputFocus",
+  "avoidInlineStyles",
+  "hideNewThreadLink",
+  "loadImmediately",
+] as const
+
+export type HubSpotRegion = "na1" | "eu1" | "ap1"
+export type HubSpotCookieBanner = boolean | "ON_WIDGET_LOAD" | "ON_EXIT_INTENT"
+
 export interface HubSpotLoadOptions extends LoadOptions {
   portalId: string
-  region?: "na1" | "eu1"
+  region?: HubSpotRegion
+  /** Inline-embedded chat: CSS selector for the host element. */
+  inlineEmbedSelector?: string
+  /** GDPR cookie banner mode. */
+  enableWidgetCookieBanner?: HubSpotCookieBanner
+  /** Disable attachment uploads. */
+  disableAttachment?: boolean
+  /** Disable focusing the composer on widget open. */
+  disableInitialInputFocus?: boolean
+  /** Avoid inline styles (helps strict CSP setups). */
+  avoidInlineStyles?: boolean
+  /** Hide the "Start a new conversation" link. */
+  hideNewThreadLink?: boolean
+  /** When true, HubSpot auto-loads the widget on script ready (default: true). Wrapper sets false unless overridden. */
+  loadImmediately?: boolean
 }
 
 function lowercaseKeys<T extends Record<string, unknown>>(obj: T): Record<string, unknown> {
@@ -88,7 +136,12 @@ export async function load(options: HubSpotLoadOptions): Promise<void> {
   lifecycle.setConfigHash(h)
   await waitForDefer(options.defer ?? "immediate")
 
-  w().hsConversationsSettings = { loadImmediately: false }
+  const settings: Record<string, unknown> = { loadImmediately: false }
+  for (const key of TYPED_SETTINGS_KEYS) {
+    const v = options[key]
+    if (v !== undefined) settings[key] = v
+  }
+  w().hsConversationsSettings = settings
 
   readyPromise = new Promise((r) => {
     readyResolve = r
@@ -102,11 +155,23 @@ export async function load(options: HubSpotLoadOptions): Promise<void> {
         const count = (payload as { unreadCount?: number } | undefined)?.unreadCount ?? 0
         for (const l of unreadListeners) l(count)
       })
+      for (const evt of HUBSPOT_EVENTS) {
+        api.on(evt, (payload: unknown) => {
+          const set = eventListeners.get(evt)
+          if (!set) return
+          for (const l of set) l(payload)
+        })
+      }
       readyResolve?.()
     }
   })
 
-  const host = options.region === "eu1" ? "js-eu1.hs-scripts.com" : "js.hs-scripts.com"
+  const host =
+    options.region === "eu1"
+      ? "js-eu1.hs-scripts.com"
+      : options.region === "ap1"
+        ? "js-ap1.hs-scripts.com"
+        : "js.hs-scripts.com"
   try {
     await injectScript({
       id: "ahize-hubspot",
@@ -125,11 +190,15 @@ export async function load(options: HubSpotLoadOptions): Promise<void> {
 export function identify(identity: Identity): Promise<void> {
   if (!isBrowser()) return Promise.resolve()
   if (identity.verification && identity.verification.kind !== "jwt") {
-    return Promise.reject(new Error("HubSpot requires JWT verification (kind: 'jwt')"))
+    return Promise.reject(
+      new Error(
+        "HubSpot requires an identification token (modeled as kind: 'jwt'); HubSpot's token is opaque, not a true JWT.",
+      ),
+    )
   }
   if (identity.email && !identity.verification) {
     console.warn(
-      "[ahize/hubspot] identify() called with email but no JWT — HubSpot treats the session as anonymous until identificationToken is provided.",
+      "[ahize/hubspot] identify() called with email but no identificationToken — HubSpot treats the session as anonymous until a token is provided.",
     )
   }
   store.identify(identity)
@@ -214,6 +283,21 @@ export function onUnreadCountChange(listener: (count: number) => void): () => vo
   return () => unreadListeners.delete(listener)
 }
 
+export function on(event: HubSpotEventName, 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 status(): { loaded: boolean; pending: boolean } | undefined {
+  if (!isBrowser()) return undefined
+  return w().HubSpotConversations?.widget.status?.()
+}
+
 export async function destroy(): Promise<void> {
   if (!isBrowser()) return
   await shutdown().catch(() => undefined)
@@ -226,6 +310,7 @@ export async function destroy(): Promise<void> {
   conversations.reset()
   store.reset()
   unreadListeners.clear()
+  eventListeners.clear()
   readyPromise = undefined
   readyResolve = undefined
   lifecycle.clearConfigHash()

test/hubspot.browser.test.ts

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+import { beforeEach, describe, expect, it } from "vitest"
+
+interface FakeApi {
+  on: Map<string, Array<(p: unknown) => void>>
+  widget: {
+    load: () => void
+    open: () => void
+    close: () => void
+    remove: () => void
+    refresh: () => void
+    status: () => { loaded: boolean; pending: boolean }
+  }
+  clear: () => void
+  fire: (event: string, payload?: unknown) => void
+}
+
+function fakeHubSpot(): FakeApi {
+  const handlers = new Map<string, Array<(p: unknown) => void>>()
+  return {
+    on: handlers,
+    widget: {
+      load: () => {},
+      open: () => {},
+      close: () => {},
+      remove: () => {},
+      refresh: () => {},
+      status: () => ({ loaded: true, pending: false }),
+    },
+    clear: () => {},
+    fire(event, payload) {
+      for (const h of handlers.get(event) ?? []) h(payload)
+    },
+  }
+}
+
+async function bootHubSpot(
+  options?: Partial<import("../src/providers/hubspot.ts").HubSpotLoadOptions>,
+): Promise<{
+  hubspot: typeof import("../src/providers/hubspot.ts")
+  fake: FakeApi
+}> {
+  const hubspot = await import("../src/providers/hubspot.ts")
+  const fake = fakeHubSpot()
+  const apiShim = {
+    widget: fake.widget,
+    clear: fake.clear,
+    on: (event: string, listener: (p: unknown) => void) => {
+      const arr = fake.on.get(event) ?? []
+      arr.push(listener)
+      fake.on.set(event, arr)
+    },
+    off: () => {},
+  }
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  ;(globalThis as any).HubSpotConversations = apiShim
+  const loadPromise = hubspot.load({ portalId: "12345", ...options })
+  await new Promise((r) => setTimeout(r, 0))
+  const script = document.getElementById("ahize-hubspot") as HTMLScriptElement
+  expect(script).toBeTruthy()
+  script.dispatchEvent(new Event("load"))
+  // biome-ignore lint/suspicious/noExplicitAny: test shim
+  for (const cb of (globalThis as any).hsConversationsOnReady ?? []) cb()
+  await loadPromise
+  return { hubspot, fake }
+}
+
+describe("hubspot (browser) — vendor-doc audit fixes (#85)", () => {
+  beforeEach(() => {
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).HubSpotConversations
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).hsConversationsSettings
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any).hsConversationsOnReady
+    // biome-ignore lint/suspicious/noExplicitAny: test cleanup
+    delete (globalThis as any)._hsq
+    const scripts = document.querySelectorAll("script")
+    for (let i = 0; i < scripts.length; i++) {
+      ;(scripts[i] as { remove(): void } | undefined)?.remove()
+    }
+  })
+
+  it("ap1 region uses js-ap1.hs-scripts.com", async () => {
+    const { hubspot } = await bootHubSpot({ region: "ap1" })
+    const script = document.getElementById("ahize-hubspot") as HTMLScriptElement
+    expect(script.src).toContain("js-ap1.hs-scripts.com")
+    await hubspot.destroy()
+  })
+
+  it("typed settings populate hsConversationsSettings", async () => {
+    const { hubspot } = await bootHubSpot({
+      inlineEmbedSelector: "#chat-here",
+      enableWidgetCookieBanner: "ON_EXIT_INTENT",
+      disableAttachment: true,
+      disableInitialInputFocus: true,
+      avoidInlineStyles: true,
+      hideNewThreadLink: true,
+      loadImmediately: true,
+    })
+    // biome-ignore lint/suspicious/noExplicitAny: test shim
+    const settings = (globalThis as any).hsConversationsSettings as Record<string, unknown>
+    expect(settings).toMatchObject({
+      inlineEmbedSelector: "#chat-here",
+      enableWidgetCookieBanner: "ON_EXIT_INTENT",
+      disableAttachment: true,
+      disableInitialInputFocus: true,
+      avoidInlineStyles: true,
+      hideNewThreadLink: true,
+      loadImmediately: true,
+    })
+    await hubspot.destroy()
+  })
+
+  it("on(event) bridges all 7 documented widget events", async () => {
+    const { hubspot, fake } = await bootHubSpot()
+    const seen: Record<string, unknown[]> = {}
+    const events = [
+      "conversationStarted",
+      "conversationClosed",
+      "userSelectedThread",
+      "contactAssociated",
+      "userInteractedWithWidget",
+      "widgetLoaded",
+      "widgetClosed",
+      "quickReplyButtonClick",
+    ] as const
+    for (const e of events) {
+      seen[e] = []
+      hubspot.on(e, (p) => seen[e]?.push(p))
+    }
+    for (const e of events) fake.fire(e, { event: e })
+    for (const e of events) expect(seen[e]).toEqual([{ event: e }])
+    await hubspot.destroy()
+  })
+
+  it("status() returns the widget's loaded/pending state", async () => {
+    const { hubspot } = await bootHubSpot()
+    expect(hubspot.status()).toEqual({ loaded: true, pending: false })
+    await hubspot.destroy()
+  })
+
+  it("identify() rejects non-jwt verification with token-not-jwt error message", async () => {
+    const { hubspot } = await bootHubSpot()
+    await expect(
+      hubspot.identify({
+        id: "u1",
+        verification: { kind: "hmac", hash: "x" },
+      }),
+    ).rejects.toThrow(/identification token/)
+    await hubspot.destroy()
+  })
+})