olark: audit vs current vendor docs (2026-04-16)

[productdevbook]

Summary

The ahize/olark wrapper covers basic box visibility and a subset of api.visitor.update* setters, but is missing the entire api.chat.* surface (operator messaging + notifications), group routing, visitor detail retrieval, locale switching, and every documented event hook.

Gaps found

Missing API surface

• api.visitor.getDetails(callback) — primary way to read back visitor identity (emailAddress, fullName, phonenumber, organization, geo, browser, customfields, conversation metrics). Wrapper's getIdentity() only returns locally-stored values and never reconciles with Olark's resolved details. — https://www.olark.com/api/api_visitor_getdetails
• api.chat.sendMessageToVisitor({ body }) — programmatic operator-style message into the chat stream. — https://www.olark.com/api
• api.chat.sendNotificationToVisitor({ body }) — system/notification message to visitor. — https://www.olark.com/api
• api.chat.sendNotificationToOperator({ body }) — surface client-side context to the operator console. — https://www.olark.com/api
• api.chat.setOperatorGroup({ group }) — group routing; required for any multi-team Olark account. — https://www.olark.com/api/api_chat_setoperatorgroup
• api.chat.updateVisitorNickname({ snippet, hideDefault }) — operator-side label for the visitor. — https://www.olark.com/api
• api.chat.updateVisitorStatus({ snippet }) — operator-side status badge. — https://www.olark.com/api
• api.box.setLocale(locale) — dynamic language switching; pairs with the wrapper's pageView({ locale }) which is currently a no-op. — https://www.olark.com/api

Events not bridged

• api.box.onShow — https://www.olark.com/api
• api.box.onHide — https://www.olark.com/api
• api.box.onExpand — https://www.olark.com/api
• api.box.onShrink — https://www.olark.com/api
• api.chat.onReady — https://www.olark.com/api
• api.chat.onBeginConversation — https://www.olark.com/api
• api.chat.onMessageToVisitor — https://www.olark.com/api
• api.chat.onMessageToOperator — https://www.olark.com/api
• api.chat.onCommandFromOperator — https://www.olark.com/api
• api.chat.onOfflineMessageToOperator — https://www.olark.com/api
• api.chat.onOperatorsAvailable — https://www.olark.com/api
• api.chat.onOperatorsAway — https://www.olark.com/api

Config options not exposed

• Group routing at load time — wrapper's OlarkLoadOptions only accepts siteId; no group field that would call api.chat.setOperatorGroup after onReady. — https://www.olark.com/api/api_chat_setoperatorgroup
• Initial locale — no locale load option; would map to api.box.setLocale. — https://www.olark.com/api

Deprecations in our current code

• track(event, metadata) writes { [event]: metadata } via api.visitor.updateCustomFields, which Olark treats as a single named custom field per event name (later events with the same name overwrite). This isn't an event bus and silently drops repeated events; should either be documented as "writes a custom field" or routed through api.chat.sendNotificationToOperator for true event semantics. — https://www.olark.com/api
• shutdown() calls api.visitor.updateCustomFields({}) to "clear" identity, but Olark's documented API has no clear/reset semantics for custom fields — passing {} is a no-op, not a reset. — https://www.olark.com/api/api_visitor_updatecustomfields
• OlarkFn is typed as (method: string, ...args: unknown[]) => void, but api.visitor.getDetails and the on* callbacks make Olark's real signature (method, callbackOrPayload?) => void with a meaningful return path via callback — current type prevents wiring those without a cast.

Intentionally out of scope

• Operator-panel / dashboard APIs.
• PowerUps configuration: no public JS-API surface documented at olark.com/api beyond what's already covered.
• Speculative methods not present in current docs: api.box.hideAfterUpdate, api.box.maximize, api.box.conceal, api.box.reveal, api.box.isExpanded, api.box.setColors, api.box.setCustomCSS, api.box.theme, api.box.autotrigger, api.box.onTargeted, api.chat.onTargeted, api.visitor.updateContactInfo, api.visitor.updateAttributes, api.visitor.updateOperatorGroup — confirmed not present in current public docs.

Sources

• https://www.olark.com/api
• https://www.olark.com/api/api_visitor_getdetails
• https://www.olark.com/api/api_chat_setoperatorgroup
• https://www.olark.com/api/api_box_show
• https://www.olark.com/api/api_box_hide
• https://www.olark.com/api/api_box_expand
• https://www.olark.com/api/api_box_shrink
• https://www.olark.com/api/api_box_setlocale
• https://www.olark.com/api/api_visitor_updatecustomfields

[productdevbook]

All audit findings shipped in 7f82fd8:

Methods (10): setLocale, setOperatorGroup, sendMessageToVisitor, sendNotificationToVisitor, sendNotificationToOperator, updateVisitorNickname, updateVisitorStatus, async getVisitorDetails() (resolves with the callback payload — getIdentity() now has a real read path back to Olark).

Event bridge: on(event, handler) covers 12 documented events under typed names (boxShow/Hide/Expand/Shrink, chatReady, beginConversation, messageToVisitor/Operator, commandFromOperator, offlineMessageToOperator, operatorsAvailable/Away).

Load options: group (calls api.chat.setOperatorGroup at boot), locale (api.box.setLocale).

Test coverage: test/olark.browser.test.ts (4 cases). Bundle budget bumped 6KB → 7KB. Closing.

shutdown()'s updateCustomFields({}) no-op note is correct — kept as-is to avoid breaking callers; documenting it as docs-only.