:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { PAGE_TOOLBAR_PORT, PageToolbarTokens } from '../messaging/pageToolbarBridge'
// Chrome exposes the promise-based `chrome.*` namespace to Manifest V3 extensions.
// Only the calls the side panel, the background script and the content script make are typed here.
interface ExtensionTab {
id?: number
url?: string
}
// Returning true keeps sendResponse open for an async response.
type RuntimeMessageListener = (
message: unknown,
sender: unknown,
sendResponse: (response: unknown) => void
) => boolean | void
interface ExtensionPermissions {
origins: string[]
}
interface TabActiveInfo {
tabId: number
windowId: number
}
interface TabChangeInfo {
url?: string
status?: string
}
export interface ExtensionPort {
name: string
postMessage: (message: unknown) => void
disconnect: () => void
onMessage: ExtensionEvent<(message: unknown) => void>
onDisconnect: ExtensionEvent<() => void>
}
interface ExtensionEvent<Listener> {
addListener: (listener: Listener) => void
removeListener: (listener: Listener) => void
}
interface ExtensionBrowserApi {
tabs: {
query: (query: { active: true; windowId?: number; currentWindow?: true }) => Promise<ExtensionTab[]>
create: (properties: { url: string; active?: boolean }) => Promise<ExtensionTab>
remove: (tabId: number) => Promise<void>
connect: (tabId: number, connectInfo: { name: string }) => ExtensionPort
sendMessage: (tabId: number, message: unknown) => Promise<unknown>
onActivated: ExtensionEvent<(activeInfo: TabActiveInfo) => void>
onRemoved: ExtensionEvent<(tabId: number) => void>
onUpdated: ExtensionEvent<
(
tabId: number,
changeInfo: TabChangeInfo,
tab: ExtensionTab & { active?: boolean; windowId?: number }
) => void
>
}
windows: {
getCurrent: () => Promise<{ id?: number }>
}
storage: {
local: {
get: (key: string) => Promise<Record<string, unknown>>
set: (items: Record<string, unknown>) => Promise<void>
}
}
scripting: {
executeScript: <Args extends unknown[], Result>(injection: {
target: { tabId: number }
files?: string[]
world?: 'ISOLATED' | 'MAIN'
func?: (...args: Args) => Result
args?: Args
}) => Promise<{ result?: Result }[]>
}
runtime: {
onMessage: {
addListener: (listener: RuntimeMessageListener) => void
}
onConnect: ExtensionEvent<(port: ExtensionPort) => void>
getURL: (path: string) => string
}
permissions: {
contains: (permissions: ExtensionPermissions) => Promise<boolean>
request: (permissions: ExtensionPermissions) => Promise<boolean>
}
action: {
onClicked: ExtensionEvent<() => void>
}
sidePanel: {
setPanelBehavior: (behavior: { openPanelOnActionClick: boolean }) => Promise<void>
}
}
// Stories and the store listing images install a fake extension API as `browser`, because every Chrome page already
// has a `chrome` object of its own.
const extensionBrowser = ((globalThis as unknown as { browser?: ExtensionBrowserApi }).browser ??
(globalThis as unknown as { chrome: ExtensionBrowserApi }).chrome) as ExtensionBrowserApi
// pinned: extension storage key, renaming it resets the saved PostHog host
const UI_HOST_STORAGE_KEY = 'posthogUiHost'
const CONTENT_SCRIPT_FILE = 'content.js'
export function openPanelFromToolbarButton(): void {
void extensionBrowser.sidePanel.setPanelBehavior({ openPanelOnActionClick: true })
}
export async function getActiveTab(): Promise<ExtensionTab | null> {
const [tab] = await extensionBrowser.tabs.query({ active: true, currentWindow: true })
return tab ?? null
}
/** Returns a function that removes the listeners. */
export function onActiveTabChange(handler: (tab: ExtensionTab | null) => void): () => void {
let panelWindowId: number | undefined
void extensionBrowser.windows.getCurrent().then((panelWindow) => {
panelWindowId = panelWindow.id
})
const onActivated = ({ windowId }: TabActiveInfo): void => {
if (windowId === panelWindowId) {
void getActiveTab().then(handler, () => handler(null))
}
}
const onUpdated = (
_tabId: number,
changeInfo: TabChangeInfo,
tab: ExtensionTab & { active?: boolean; windowId?: number }
): void => {
// A reload keeps the URL but removes everything the extension added to the page.
if (tab.active && tab.windowId === panelWindowId && (changeInfo.url || changeInfo.status === 'complete')) {
handler(tab)
}
}
extensionBrowser.tabs.onActivated.addListener(onActivated)
extensionBrowser.tabs.onUpdated.addListener(onUpdated)
return () => {
extensionBrowser.tabs.onActivated.removeListener(onActivated)
extensionBrowser.tabs.onUpdated.removeListener(onUpdated)
}
}
export async function openTab(url: string): Promise<void> {
await extensionBrowser.tabs.create({ url })
}
export async function getStoredUiHost(): Promise<string | null> {
const stored = await extensionBrowser.storage.local.get(UI_HOST_STORAGE_KEY)
const value = stored[UI_HOST_STORAGE_KEY]
return typeof value === 'string' ? value : null
}
export async function setStoredUiHost(uiHost: string): Promise<void> {
await extensionBrowser.storage.local.set({ [UI_HOST_STORAGE_KEY]: uiHost })
}
function originPattern(uiHost: string): ExtensionPermissions {
// A pattern without a port matches the host on every port.
const { protocol, hostname } = new URL(uiHost)
return { origins: [`${protocol}//${hostname}/*`] }
}
/** The manifest asks for every site, but the user can take access back for a site in the browser's settings. */
export async function hasHostPermission(uiHost: string): Promise<boolean> {
return await extensionBrowser.permissions.contains(originPattern(uiHost))
}
/** Must run inside the click handler: browsers show the permission prompt only for a user gesture. */
export async function requestHostPermission(url: string): Promise<boolean> {
return await extensionBrowser.permissions.request(originPattern(url))
}
// pinned: extension message, the panel and an already injected content script must agree on it
const CONTENT_SCRIPT_PING = 'posthog-toolbar-extension-ping'
export async function ensureContentScript(tabId: number): Promise<void> {
const installed = await extensionBrowser.tabs.sendMessage(tabId, CONTENT_SCRIPT_PING).then(
(response) => response === true,
() => false
)
if (!installed) {
await extensionBrowser.scripting.executeScript({ target: { tabId }, files: [CONTENT_SCRIPT_FILE] })
}
}
export function answerContentScriptPing(): void {
extensionBrowser.runtime.onMessage.addListener((message, _sender, sendResponse) => {
if (message === CONTENT_SCRIPT_PING) {
sendResponse(true)
}
})
}
export function extensionFileUrl(path: string): string {
return extensionBrowser.runtime.getURL(path)
}
export function connectToPageToolbar(tabId: number): ExtensionPort {
return extensionBrowser.tabs.connect(tabId, { name: PAGE_TOOLBAR_PORT })
}
export function onPageToolbarConnect(handler: (port: ExtensionPort) => void): void {
extensionBrowser.runtime.onConnect.addListener((port) => {
if (port.name === PAGE_TOOLBAR_PORT) {
handler(port)
}
})
}
const PAGE_AGENT_FILE = 'page-agent.js'
/** Runs the page agent in the page's own world, where it can call the page's posthog-js for the content script. */
export async function injectPageAgent(tabId: number): Promise<void> {
await extensionBrowser.scripting.executeScript({ target: { tabId }, world: 'MAIN', files: [PAGE_AGENT_FILE] })
}
export async function waitForTabUrl(
url: string,
matches: (tabUrl: string) => boolean,
{ timeoutMs, active }: { timeoutMs: number; active: boolean }
): Promise<string> {
const tab = await extensionBrowser.tabs.create({ url, active })
const tabId = tab.id
if (tabId === undefined) {
throw new Error('The browser did not open the tab')
}
return await new Promise((resolve, reject) => {
const finish = (result: { url: string } | { error: Error }): void => {
clearTimeout(timeout)
extensionBrowser.tabs.onUpdated.removeListener(onUpdated)
extensionBrowser.tabs.onRemoved.removeListener(onRemoved)
if ('url' in result) {
void extensionBrowser.tabs.remove(tabId).catch(() => undefined)
resolve(result.url)
} else {
reject(result.error)
}
}
const onUpdated = (updatedTabId: number, changeInfo: TabChangeInfo): void => {
if (updatedTabId === tabId && changeInfo.url && matches(changeInfo.url)) {
finish({ url: changeInfo.url })
}
}
const onRemoved = (removedTabId: number): void => {
if (removedTabId === tabId) {
finish({ error: new Error('The tab closed before it finished') })
}
}
const timeout = setTimeout(() => {
void extensionBrowser.tabs.remove(tabId).catch(() => undefined)
finish({ error: new Error('The tab did not finish in time') })
}, timeoutMs)
extensionBrowser.tabs.onUpdated.addListener(onUpdated)
extensionBrowser.tabs.onRemoved.addListener(onRemoved)
})
}
// pinned: extension storage key, renaming it signs every project out of the toolbar
const TOKENS_STORAGE_KEY = 'posthogToolbarTokens'
export async function getStoredTokens(key: string): Promise<PageToolbarTokens | null> {
const stored = await extensionBrowser.storage.local.get(TOKENS_STORAGE_KEY)
const tokensByKey = stored[TOKENS_STORAGE_KEY] as Record<string, PageToolbarTokens> | undefined
const tokens = tokensByKey?.[key]
return tokens && typeof tokens.accessToken === 'string' && typeof tokens.clientId === 'string' ? tokens : null
}
export async function setStoredTokens(key: string, tokens: PageToolbarTokens | null): Promise<void> {
const stored = await extensionBrowser.storage.local.get(TOKENS_STORAGE_KEY)
const tokensByKey = { ...(stored[TOKENS_STORAGE_KEY] as Record<string, PageToolbarTokens> | undefined) }
if (tokens) {
tokensByKey[key] = tokens
} else {
delete tokensByKey[key]
}
await extensionBrowser.storage.local.set({ [TOKENS_STORAGE_KEY]: tokensByKey })
}