Skip to main content
The bridge a mount talks to the host through, which useTap returns.

Remarks

The host replaces auth, project, filters, theme, ui, params and context with new objects rather than mutating them, so the useTap* hooks can compare snapshots by reference. Read a value through its hook when the component has to re-render on a change, and through tap when it does not.

Example

Extends

Properties

__portal

The portal node inside the mount’s shadow root, or null until the shadow root exists.

Inherited from

TapInternals.__portal

actions

run()

Creates the run and resolves with it as soon as it exists. status is pending while the owner has still to approve — the host draws the approval card — and succeeded or failed when the owner has turned asking off for this install, which no action-declaring extension can do today. Rejects with a TapServerError when the host refuses the run.
Type Parameters
A
A extends string
Parameters
actionId
A
input
ActionInput<A>
Returns
Promise<TapActionRun>

auth

organizationId

scopes

token

The install token to send to your own server as a bearer token.

user

user.id
user.role

can()

Whether the install granted the scope.
Parameters
scope
| "ui:render" | "projects:read" | "analytics:read" | "store.metadata:read" | "reviews:read" | "crashes:read" | "revenue:read" | "metrics:write" | "alerts:write" | "insights:write" | "ai:tools" | "ai:actions" | "store.metadata:write" | "autopilot:trigger" | "work:create" | "work:sync" | "storage:write" | "messaging:send" | "ai:skills"
Returns
boolean

context

What Expand carried in, or the row behind a row action.

data

query()

Rejects with TAP_SCOPE_MISSING when the query’s scope is not granted.
Type Parameters
Q
Q extends TapQuery
Parameters
query
Q
Returns
Promise<TapResult<Q>>

subscribe()

Returns an unsubscribe function; call it when the component unmounts.
Type Parameters
E
E extends | "release.shipped" | "metadata.changed" | "keyword.set_changed" | "screenshots.updated" | "price.changed" | "featuring.started" | "score.changed" | "incident.opened" | "incident.resolved" | "playbook.step_approved" | "review.thread_opened" | "review.thread_resolved" | "approval.requested" | "digest.sent" | "install.created" | "install.paused" | "install.resumed" | "install.revoked" | "install.token_rotated" | "scopes.changed" | "settings.changed"
Parameters
event
E
handler
(payload) => void
Returns
() => void

env

dev while the dev server serves the mount, else the install’s channel.

extension

id

installId

name

projectId

null when the extension is installed on the workspace, not a project.

filters


format


host

sdkMajors

version


locale


openChat()

Opens the owner’s chat and fills the composer with the prompt. The owner reads it and sends it — nothing here sends by itself. The context goes under it as JSON on a visible From <extension name>: line the owner can edit or delete, cut to 2 KB, the same ceiling every vendor block the assistant reads is held to.
Parameters
prompt
string
context?
Record<string, unknown>
Returns
void

openExternal()

Asks the owner to confirm, then opens the url in a new tab.
Parameters
url
string
Returns
void

openSettings()

Opens the owner’s settings page for this install.
Returns
void

push()

Refused with a toast when the path leaves the project or the extension.
Parameters
path
`/${string}`
Returns
void

setSearch()

Sets the query string on the host’s URL; a null drops that parameter.
Parameters
params
Record<string, string | null>
Returns
void

params

A page’s route: pageId, path, and one key per sub-path segment.

project

apps

id

keywords

name

platforms

releases


server


state

get()

Returns the same reference for the same key until set replaces it, so useTapState can use the value as a useSyncExternalStore snapshot.
Type Parameters
T
T
Parameters
key
string
Returns
T | undefined

set()

Notifies every mount of the install that reads the same key.
Type Parameters
T
T
Parameters
key
string
value
T
Returns
void

subscribe()

Returns an unsubscribe function.
Parameters
key
string
handler
() => void
Returns
() => void

storage


telemetry

event()

Queued and sent by the host; the call itself does no network work.
Parameters
name
string
props?
Record<string, string | number | boolean>
Returns
void

theme

mode


timezone


ui

size

confirm()

Resolves to what the owner chose in the host’s confirmation dialog.
Parameters
options
TapConfirmOptions
Returns
Promise<boolean>

copy()

Copies the text to the clipboard and toasts that it was copied.
Parameters
text
string
Returns
Promise<void>

download()

Saves the blob to the owner’s downloads under that filename.
Parameters
blob
Blob
filename
string
Returns
void

expand()

Opens the widget’s expand panel.
Returns
void

openInChat()

Puts the card in the owner’s chat, drawn by the host from the values you send. Needs insights:write; without it the host fills the composer with a sentence describing the card instead, and the owner sends that.
Parameters
card
TapChatCard
Returns
void

toast()

Raises a host toast; the tone defaults to neutral.
Parameters
message
string
tone?
TapToastTone
Returns
void

Methods

__subscribe()

The host replaces the member a key names with a new object and only then calls the key’s listeners; it never mutates a member in place, because the useTap* hooks compare snapshots by reference. Returns an unsubscribe function.

Parameters

key
TapChangeKey
listener
() => void

Returns

() => void

Inherited from

TapInternals.__subscribe

invalidate()

Drops the cached answers for one procedure, or for everything of yours when the name is left out, across every mount of the install.

Parameters

name?
string

Returns

void