impro-plugin #

Documentation autogenerated by Claude Opus 5

Classes #

App #

The plugin's handle to the running impro app. Exposed as this.app on a Plugin instance. Owns event subscriptions, data accessors (App.data), and user-scoped actions.

Properties #

Property	Type	Description
binaryCache	BinaryCache	Host-mediated binary storage — see BinaryCache.
currentUser	ProfileView | null	The signed-in user's basic profile, populated before onload() runs. Null when no session is active.
data	PluginData	Read-only appview accessors — see PluginData.

Methods #

blockActor() #

blockActor(did): Promise<void>

Block an actor on behalf of the signed-in user. Requires the "block" scope in the plugin manifest's permissions.actions.

Parameters #

Parameter	Type
did	string

Returns #

Promise<void>

muteActor() #

muteActor(did): Promise<void>

Mute an actor on behalf of the signed-in user. Requires the "mute" scope in the plugin manifest's permissions.actions.

Parameters #

Parameter	Type
did	string

Returns #

Promise<void>

on() #

on<K>(event, listener): void

Register an event listener. Supported events:

• "post-context-menu" — (menu: Menu, post) => void, called when the user opens a post's context menu.
• "profile-context-menu" — (menu: Menu, profile) => void, called when the user opens a profile's context menu.
• "post-composer-open" — (composer: Composer, context: { kind, replyTo, replyRoot, quotedPost }) => void, called when the post composer opens; use composer to seed text.

The listener signature varies per event — see PluginEventMap.

Type Parameters #

Type Parameter	Description
K extends keyof PluginEventMap

Parameters #

Parameter	Type
event	K
listener	PluginEventMap[K]

Returns #

void

refreshFeedFilters() #

refreshFeedFilters(feedURI?): Promise<void>

Re-run registered feed filters. Pass a feedURI to limit the refresh to one feed, or omit/pass null to refresh every feed.

Parameters #

Parameter	Type	Default value
feedURI?	string | null	null

Returns #

Promise<void>

showLessLikeThis() #

showLessLikeThis(postUri, feedUri): Promise<void>

Acts like the user clicking "Show less like this": sends the requestLess feedback signal to feedUri and collapses the post behind a feedback message in feeds. Requires the "feedFeedback" scope.

Parameters #

Parameter	Type
postUri	string
feedUri	string

Returns #

Promise<void>

showMoreLikeThis() #

showMoreLikeThis(postUri, feedUri): Promise<void>

Sends the requestMore feedback signal to feedUri for postUri. Requires the "feedFeedback" scope.

Parameters #

Parameter	Type
postUri	string
feedUri	string

Returns #

Promise<void>

unblockActor() #

unblockActor(did): Promise<void>

Unblock an actor. Requires the "block" scope.

Parameters #

Parameter	Type
did	string

Returns #

Promise<void>

unmuteActor() #

unmuteActor(did): Promise<void>

Unmute an actor. Requires the "mute" scope.

Parameters #

Parameter	Type
did	string

Returns #

Promise<void>

---

BinaryCache #

Host-mediated persistent storage for binary data too large for Plugin.loadLocalData/Plugin.saveLocalData. Namespaced per plugin; survives reloads but is cleared on uninstall.

Constructors #

Constructor #

new BinaryCache(): BinaryCache

Returns #

BinaryCache

Methods #

delete() #

delete(key): Promise<void>

Parameters #

Parameter	Type
key	string

Returns #

Promise<void>

get() #

get(key): Promise<ArrayBuffer | null>

Parameters #

Parameter	Type
key	string

Returns #

Promise<ArrayBuffer | null>

has() #

has(key): Promise<boolean>

Whether an entry is stored under key, without transferring its bytes.

Parameters #

Parameter	Type
key	string

Returns #

Promise<boolean>

keys() #

keys(): Promise<string[]>

Every key this plugin currently has stored, in no particular order.

Returns #

Promise<string[]>

put() #

put(key, data): Promise<void>

Parameters #

Parameter	Type
key	string
data	ArrayBuffer | ArrayBufferView<ArrayBufferLike>

Returns #

Promise<void>

---

BlobImageComponent #

Renders a repo blob (by owning DID + blob CID) as an image. Built via VirtualEl.createBlobImage.

Properties #

Property	Type
el	VirtualEl

Methods #

setAlt() #

setAlt(alt): BlobImageComponent

Set the image's alt text.

Parameters #

Parameter	Type
alt	string

Returns #

BlobImageComponent

setCdnPrefix() #

setCdnPrefix(prefix): BlobImageComponent

Override the CDN URL prefix used to fetch the blob.

Parameters #

Parameter	Type
prefix	string

Returns #

BlobImageComponent

setCid() #

setCid(cid): BlobImageComponent

CID of the blob to render.

Parameters #

Parameter	Type
cid	string

Returns #

BlobImageComponent

setDid() #

setDid(did): BlobImageComponent

DID of the repo the blob belongs to.

Parameters #

Parameter	Type
did	string

Returns #

BlobImageComponent

---

ButtonComponent #

Clickable button, built via Setting.addButton.

Properties #

Property	Type
el	VirtualEl

Methods #

onClick() #

onClick(callback): ButtonComponent

Register a click handler.

Parameters #

Parameter	Type
callback	() => void

Returns #

ButtonComponent

setButtonText() #

setButtonText(text): ButtonComponent

Set the button's label.

Parameters #

Parameter	Type
text	string

Returns #

ButtonComponent

setCta() #

setCta(): ButtonComponent

Style the button as the row's primary call-to-action.

Returns #

ButtonComponent

---

Composer #

Builder passed as the first argument to post-composer-open event listeners. Queues text operations that the host applies to the composer once all listeners have run. operations from multiple plugins are applied in order.

Constructors #

Constructor #

new Composer(): Composer

Returns #

Composer

Methods #

appendText() #

appendText(text): Composer

Append text to the end of the composer.

Parameters #

Parameter	Type
text	string

Returns #

Composer

prependText() #

prependText(text): Composer

Prepend text to the start of the composer.

Parameters #

Parameter	Type
text	string

Returns #

Composer

setCursor() #

setCursor(index): Composer

Move the caret to the given character index in the final text.

Parameters #

Parameter	Type
index	number

Returns #

Composer

setText() #

setText(text): Composer

Replace the composer's current text.

Parameters #

Parameter	Type
text	string

Returns #

Composer

---

DropdownComponent #

Single-select dropdown, built via Setting.addDropdown.

Properties #

Property	Type
el	VirtualEl

Methods #

addOption() #

addOption(value, label): DropdownComponent

Append one option.

Parameters #

Parameter	Type
value	string
label	string

Returns #

DropdownComponent

addOptions() #

addOptions(map): DropdownComponent

Append every { value: label } entry as an option.

Parameters #

Parameter	Type
map	Record<string, string>

Returns #

DropdownComponent

onChange() #

onChange(callback): DropdownComponent

Fires with the newly selected value on every change.

Parameters #

Parameter	Type
callback	(value) => void

Returns #

DropdownComponent

setValue() #

setValue(value): DropdownComponent

Select the option whose value matches.

Parameters #

Parameter	Type
value	string

Returns #

DropdownComponent

---

FlattenedTokens #

Flattens a rich-text token stream into a plain string with a position map, so a rich-text transform can pattern-match (e.g. with a regex) across token boundaries and map matches back to the original tokens.

Constructors #

Constructor #

new FlattenedTokens(tokens): FlattenedTokens

Parameters #

Parameter	Type
tokens	RichTextToken[]

Returns #

FlattenedTokens

Properties #

Property	Type
text	string

Methods #

textFor() #

textFor(start, end): string

Return the plain-text slice for [start, end) — inert, with no facets.

Parameters #

Parameter	Type
start	number
end	number

Returns #

string

tokensFor() #

tokensFor(start, end): RichTextToken[]

Return the tokens covering [start, end). Facet tokens partially overlapping the range are demoted to plain text tokens so the emitted slice never carries a truncated facet.

Parameters #

Parameter	Type
start	number
end	number

Returns #

RichTextToken[]

---

IconComponent #

Renders a host-provided icon by name. Built via VirtualEl.createIcon.

Properties #

Property	Type
el	VirtualEl

Methods #

setIcon() #

setIcon(name): IconComponent

Set the icon name.

Parameters #

Parameter	Type
name	string

Returns #

IconComponent

---

Menu #

A context-menu builder passed as the first argument to post-context-menu and profile-context-menu event listeners. Call addItem to append menu entries.

Constructors #

Constructor #

new Menu(): Menu

Returns #

Menu

Properties #

Property	Type
items	MenuItem[]

Methods #

addItem() #

addItem(builder): Menu

Append a menu item. The builder receives a MenuItem to configure.

Parameters #

Parameter	Type
builder	(item) => void

Returns #

Menu

---

MenuItem #

A single item in a Menu. Configure with the chained setters and an onClick handler. Not constructed directly — obtained via Menu.addItem(builder).

Constructors #

Constructor #

new MenuItem(): MenuItem

Returns #

MenuItem

Properties #

Property	Type
icon	string | VirtualEl | null
title	string

Methods #

onClick() #

onClick(callback): MenuItem

Called when the user activates the item.

Parameters #

Parameter	Type
callback	() => void

Returns #

MenuItem

setIcon() #

setIcon(icon): MenuItem

Set the leading icon. Either a named icon (string) or a VirtualEl to render as the icon.

Parameters #

Parameter	Type
icon	string | VirtualEl

Returns #

MenuItem

setTitle() #

setTitle(title): MenuItem

Set the menu item's label.

Parameters #

Parameter	Type
title	string

Returns #

MenuItem

---

Modal #

A dismissable modal dialog. Subclass and populate contentEl and titleEl (both VirtualEl), typically inside Modal.onOpen. Call open() to show and close() to hide.

Constructors #

Constructor #

new Modal(): Modal

Returns #

Modal

Properties #

Property	Type
contentEl	VirtualEl
titleEl	VirtualEl

Methods #

close() #

close(): void

Hide the modal and fire Modal.onClose.

Returns #

void

onClose() #

onClose(): void

Lifecycle hook — override to react to the modal being dismissed (by close() or the user).

Returns #

void

onOpen() #

onOpen(): void

Lifecycle hook — override to populate titleEl / contentEl before the modal mounts.

Returns #

void

open() #

open(): void

Show the modal. Runs Modal.onOpen first, then mounts the current el state.

Returns #

void

update() #

update(): void

Re-render the open modal from the current titleEl / contentEl state. No-op if closed.

Returns #

void

---

Notice #

Shows a toast notification. noticeEl is a VirtualEl that can be mutated (e.g. addClass, appending children) synchronously after construction — the host serializes and renders the toast on a microtask, so any mutations made in the same task apply to the initial render. Mutations or setMessage calls made after that point do NOT propagate to the mounted toast; call Notice.hide and create a new Notice to change it.

Constructors #

Constructor #

new Notice(message, timeout?): Notice

timeout is in milliseconds; 0 (the default) keeps the toast up until Notice.hide is called.

Parameters #

Parameter	Type	Default value
message	string	undefined
timeout?	number	0

Returns #

Notice

Properties #

Property	Type
noticeEl	VirtualEl

Methods #

hide() #

hide(): void

Dismisses the toast. No-op if already hidden.

Returns #

void

setMessage() #

setMessage(message): Notice

Updates noticeEl's text. Only takes effect if called synchronously before the microtask that snapshots the toast for the initial render.

Parameters #

Parameter	Type
message	string

Returns #

Notice

---

Plugin #

Base class for impro plugins. Subclass this and override Plugin.onload (and optionally Plugin.onunload) to wire up your plugin's extension points. this.app is the shared App instance for host actions and data. Call MyPlugin.register() at the top of your plugin's main.js to boot.

Properties #

Property	Type
app	App

Methods #

addFeedFilter() #

addFeedFilter(callback?): void

Registers a feed filter. callback(feedUri, feedItems) returns an object { [postUri]: false } for posts to hide from the feed. Only false hides; any other value is ignored, so one plugin can't un-hide what another hid.

Parameters #

Parameter	Type
callback	(feedUri, feedItems) => Record<string, boolean> | Promise<Record<string, boolean>>

Returns #

void

addSettingTab() #

addSettingTab(tab): void

Registers a PluginSettingTab shown under this plugin's entry in the app's settings.

Parameters #

Parameter	Type
tab	PluginSettingTab

Returns #

void

addSidebarItem() #

addSidebarItem(icon, title, callback?): void

Adds an item to the impro sidebar. icon is a VirtualEl (typically an SVG) or a string; callback runs when the item is clicked.

Parameters #

Parameter	Type
icon	string | VirtualEl
title	string
callback?	() => void

Returns #

void

loadData() #

loadData(): Promise<unknown>

Loads this plugin's account-synced JSON blob. Follows the user across devices via account preferences. Returns whatever was last saved, or null.

Returns #

Promise<unknown>

loadLocalData() #

loadLocalData(): Promise<unknown>

Device-local counterpart to Plugin.loadData: never synced through the user's account preferences, so it's the right place for anything that shouldn't silently follow the plugin to another device (e.g. a locally held secret key). Cleared on uninstall, same as loadData/saveData.

Returns #

Promise<unknown>

onload() #

onload(): void | Promise<void>

Override in your subclass. Runs after the plugin is loaded and the current user is resolved.

Returns #

void | Promise<void>

onunload() #

onunload(): void | Promise<void>

Override in your subclass. Runs when the plugin is being torn down (uninstall/reload).

Returns #

void | Promise<void>

openPage() #

openPage(pageId): Promise<void>

Navigates the user to one of this plugin's registered pages.

Parameters #

Parameter	Type
pageId	string

Returns #

Promise<void>

refreshPage() #

refreshPage(pageId, options?): Promise<void>

Re-invokes a registered page's display callback if the page is open. options.reset also discards the rendered tree instead of patching it.

Parameters #

Parameter	Type
pageId	string
options?	{ reset?: boolean; }
options.reset?	boolean

Returns #

Promise<void>

refreshSlot() #

refreshSlot(name, options?): Promise<void>

Makes mounted <plugin-slot name=...> instances re-invoke this plugin's registered callback for that slot, and drops any cached results. Useful when a slot's content depends on plugin state that changed after render.

options.keys is an array of matcher objects OR'd together, e.g. [{ did: "..." }] — any matching slots are invalidated and refreshed. Omit to refresh every instance. A slot registered with a cacheKey can only be matched on those declared fields, since its output depends on nothing else.

Parameters #

Parameter	Type
name	string
options?	{ keys?: Record<string, string>[]; }
options.keys?	Record<string, string>[]

Returns #

Promise<void>

registerPage() #

registerPage(options): void

Registers a full-page view reachable via Plugin.openPage. display() is called on navigation and must return a VirtualEl, or nothing to render an empty page.

Parameters #

Parameter	Type
options	{ display?: () => RenderResult | Promise<RenderResult>; id: string; title?: string | null; }
options.display?	() => RenderResult | Promise<RenderResult>
options.id	string
options.title?	string | null

Returns #

void

registerRichTextTransform() #

registerRichTextTransform(callback?, options?): void

Registers a rich-text transform. callback(tokens, context) receives the token stream for one post and returns a new token array (or the input unchanged). Tokens are one of: text (plain string run), facet (linked text with an atproto facet feature), inline (a plugin-produced inline VirtualEl), or block (a plugin-produced block VirtualEl). See FlattenedTokens for pattern-matching across token boundaries.

A node token's node is a VirtualEl when this transform creates it, but arrives in serialized form when an earlier transform produced it.

options.handlesFacetTypes is an array of facet feature $type strings this transform owns, so the host can suppress fallback rendering flash while the transform runs.

Parameters #

Parameter	Type
callback	(tokens, context) => RichTextToken[] | Promise<RichTextToken[]>
options?	{ handlesFacetTypes?: string[]; }
options.handlesFacetTypes?	string[]

Returns #

void

registerSlot() #

registerSlot(name, callback?, options?): void

Registers a slot renderer. <plugin-slot name="..."> elements in the host UI (or other plugins' output) invoke callback(context), where context is a flat string map of the slot element's attributes. The callback should return a VirtualEl or null.

options.cacheKey is an array of context field names. If provided, the host treats the slot content as a pure function of these fields — omitting other fields from the callback's context and caching return values until invalidated by Plugin.refreshSlot. An empty array declares that the content depends on no context at all, so one cached result serves every instance.

The host batches all pending contexts of a render into one call.

Parameters #

Parameter	Type
name	string
callback	(context) => RenderResult | Promise<RenderResult>
options?	{ cacheKey?: string[]; }
options.cacheKey?	string[]

Returns #

void

saveData() #

saveData(data): Promise<void>

Persists data as this plugin's account-synced JSON blob.

Parameters #

Parameter	Type
data	Cloneable

Returns #

Promise<void>

saveLocalData() #

saveLocalData(data): Promise<void>

Device-local counterpart to Plugin.saveData.

Parameters #

Parameter	Type
data	Cloneable

Returns #

Promise<void>

register() #

static register(): void

Boots the plugin. Call as MyPlugin.register() at the top of your plugin's main.js — instantiates the subclass, resolves the current user onto app.currentUser, then invokes Plugin.onload. Idempotent.

Returns #

void

---

PluginData #

Read-only accessors for appview data with the current user as the viewer. Reached via App.data on the plugin's App instance.

Constructors #

Constructor #

new PluginData(): PluginData

Returns #

PluginData

Methods #

getBacklinks() #

getBacklinks(params): Promise<BacklinkRecord[]>

Get records that link to subject, from a backlink index of public records.

subject is an AT-URI or a DID; source names the linking field as <collection>:<dot.path.to.field> (e.g. "app.bsky.graph.listitem:list"). The host paginates for you, up to limit records (max 1000 per call — page by making further calls with a narrower subject).

Parameters #

Parameter	Type
params	{ limit?: number; source: string; subject: string; }
params.limit?	number
params.source	string
params.subject	string

Returns #

Promise<BacklinkRecord[]>

getCurrentUserProfile() #

getCurrentUserProfile(): Promise<DetailedProfileView | null>

The current user's full hydrated profile (unlike app.currentUser, which carries only did and handle). null when signed out.

Returns #

Promise<DetailedProfileView | null>

getDetailedProfile() #

getDetailedProfile(did): Promise<DetailedProfileView>

Like PluginData.getProfile, but includes viewer relationship details not present on the basic profile view: viewer.following, viewer.followedBy, and viewer.knownFollowers (a summary of mutual followers).

Parameters #

Parameter	Type
did	string

Returns #

Promise<DetailedProfileView>

getFeedGenerator() #

getFeedGenerator(uri): Promise<FeedGeneratorView | null>

Fetch a feed generator view by AT-URI.

Parameters #

Parameter	Type
uri	string

Returns #

Promise<FeedGeneratorView | null>

getKnownFollowers() #

getKnownFollowers(did): Promise<KnownFollowersResponse>

The full known-followers list for did. The summary on PluginData.getDetailedProfile's viewer.knownFollowers is capped to a handful; use this to paginate the complete list.

Parameters #

Parameter	Type
did	string

Returns #

Promise<KnownFollowersResponse>

getList() #

getList(uri): Promise<ListView | null>

Fetch a list's metadata view by AT-URI.

Parameters #

Parameter	Type
uri	string

Returns #

Promise<ListView | null>

getPost() #

getPost(uri): Promise<PostView>

Fetch a hydrated post view by AT-URI, as seen by the current user.

Parameters #

Parameter	Type
uri	string

Returns #

Promise<PostView>

getPostThread() #

getPostThread(uri): Promise<PostThreadView | null>

Fetch the hydrated thread around a post (the post, its parents, and replies), as the host renders it.

Parameters #

Parameter	Type
uri	string

Returns #

Promise<PostThreadView | null>

getProfile() #

getProfile(did): Promise<ProfileView>

Fetch the basic profile view for a DID.

Parameters #

Parameter	Type
did	string

Returns #

Promise<ProfileView>

getRecord() #

getRecord(repo, collection, rkey): Promise<RepoRecord>

Fetch a raw repo record by (repo, collection, rkey).

Parameters #

Parameter	Type
repo	string
collection	string
rkey	string

Returns #

Promise<RepoRecord>

xrpcQuery() #

xrpcQuery(nsid, params?): Promise<XrpcQueryResponse>

Call a read-only AppView query endpoint through the current user's session and get the raw XRPC response back.

Only an allowlisted set of app.bsky.* query NSIDs is accepted; viewer-private queries (mutes, bookmarks, notifications, preferences, timeline, ...) additionally require the "privateData" action permission. Unlike the curated methods above, responses are canonical server state — they may briefly disagree with what the host UI shows while an optimistic update is in flight, and results are not cached.

Parameters #

Parameter	Type	Description
nsid	string	e.g. "app.bsky.feed.getQuotes"
params?	Record<string, string | number | boolean | string[]>	-

Returns #

Promise<XrpcQueryResponse>

---

PluginResponse #

Response returned from fetch. The host buffers the raw response bytes and sends them as an ArrayBuffer, and this class decodes them on demand depending on which accessor is called. status, ok, and headers (a Map) mirror the underlying HTTP response.

Properties #

Property	Type
headers	Map<string, string>
ok	boolean
status	number

Methods #

arrayBuffer() #

arrayBuffer(): Promise<ArrayBuffer>

Resolves with the raw response bytes.

Returns #

Promise<ArrayBuffer>

json() #

json(): Promise<unknown>

Resolves with the response body parsed as JSON.

Returns #

Promise<unknown>

text() #

text(): Promise<string>

Resolves with the response body decoded as UTF-8 text.

Returns #

Promise<string>

---

PluginSettingTab #

A tab in the plugin's settings UI. Subclass and override PluginSettingTab.display to render into this.containerEl. Pass the owning plugin to super(plugin) and register with plugin.addSettingTab(tab).

Constructors #

Constructor #

new PluginSettingTab(plugin): PluginSettingTab

Parameters #

Parameter	Type	Description
plugin	Plugin	The owning plugin, available as this.plugin.

Returns #

PluginSettingTab

Properties #

Property	Type
containerEl	VirtualEl
name	string | null
plugin	Plugin

Methods #

display() #

display(): void

Override to render the tab's contents into this.containerEl.

Returns #

void

refresh() #

refresh(options?): Promise<void>

Re-invoke PluginSettingTab.display. reset: true also discards the rendered tree.

Parameters #

Parameter	Type
options?	{ reset?: boolean; }
options.reset?	boolean

Returns #

Promise<void>

setName() #

setName(name): PluginSettingTab

Set the tab's label.

Parameters #

Parameter	Type
name	string

Returns #

PluginSettingTab

---

PostsFeedComponent #

Renders a feed of posts from an array of post URIs, hydrated by the host. Built via VirtualEl.createPostsFeed.

Properties #

Property	Type
el	VirtualEl

Methods #

setEmptyMessage() #

setEmptyMessage(message): PostsFeedComponent

Message shown when the feed is empty.

Parameters #

Parameter	Type
message	string

Returns #

PostsFeedComponent

setUris() #

setUris(uris): PostsFeedComponent

Set the post URIs to render (array or comma-separated string).

Parameters #

Parameter	Type
uris	string | string[]

Returns #

PostsFeedComponent

---

ProfilesListComponent #

Renders a list of profiles from an array of DIDs, hydrated by the host. Built via VirtualEl.createProfilesList.

Properties #

Property	Type
el	VirtualEl

Methods #

setDids() #

setDids(dids): ProfilesListComponent

Set the DIDs to render (array or comma-separated string).

Parameters #

Parameter	Type
dids	string | string[]

Returns #

ProfilesListComponent

setEmptyMessage() #

setEmptyMessage(message): ProfilesListComponent

Message shown when the list is empty.

Parameters #

Parameter	Type
message	string

Returns #

ProfilesListComponent

---

Setting #

Fluent builder for a single labeled settings row. new Setting(containerEl) appends a row (name + description + control area) to containerEl and returns a builder for populating it.

Constructors #

Constructor #

new Setting(containerEl): Setting

Parameters #

Parameter	Type
containerEl	VirtualEl

Returns #

Setting

Properties #

Property	Type
controlEl	VirtualEl
descEl	VirtualEl
infoEl	VirtualEl
nameEl	VirtualEl
settingEl	VirtualEl

Methods #

addButton() #

addButton(callback): Setting

Add a button; the callback receives a ButtonComponent.

Parameters #

Parameter	Type
callback	(component) => void

Returns #

Setting

addDropdown() #

addDropdown(callback): Setting

Add a dropdown; the callback receives a DropdownComponent.

Parameters #

Parameter	Type
callback	(component) => void

Returns #

Setting

addText() #

addText(callback): Setting

Add a text input; the callback receives a TextComponent.

Parameters #

Parameter	Type
callback	(component) => void

Returns #

Setting

addTextArea() #

addTextArea(callback): Setting

Add a multi-line text input; the callback receives a TextAreaComponent.

Parameters #

Parameter	Type
callback	(component) => void

Returns #

Setting

addToggle() #

addToggle(callback): Setting

Add a toggle switch; the callback receives a ToggleComponent.

Parameters #

Parameter	Type
callback	(component) => void

Returns #

Setting

setDesc() #

setDesc(text): Setting

Set the row's description text below the name.

Parameters #

Parameter	Type
text	string

Returns #

Setting

setName() #

setName(text): Setting

Set the row's name/label.

Parameters #

Parameter	Type
text	string

Returns #

Setting

---

SimpleUUID #

Constructors #

Constructor #

new SimpleUUID(): SimpleUUID

Returns #

SimpleUUID

Methods #

create() #

create(): number

Returns #

number

---

StyleSnippet #

Injects a CSS block scoped to the plugin. The stylesheet is mounted by the host on the next microtask; snippets are automatically removed when the plugin unloads.

Constructors #

Constructor #

new StyleSnippet(cssText): StyleSnippet

Parameters #

Parameter	Type
cssText	string

Returns #

StyleSnippet

Properties #

Property	Type	Description
ready	Promise<void>	Resolves once the snippet has been applied by the host.

Methods #

remove() #

remove(): void

Removes the snippet from the document. No-op if already removed.

Returns #

void

---

TextAreaComponent #

Multi-line text input, built via Setting.addTextArea.

Properties #

Property	Type
el	VirtualEl

Methods #

onChange() #

onChange(callback): TextAreaComponent

Fires with the new string value on every change.

Parameters #

Parameter	Type
callback	(value) => void

Returns #

TextAreaComponent

setPlaceholder() #

setPlaceholder(value): TextAreaComponent

Set the placeholder text shown when the input is empty.

Parameters #

Parameter	Type
value	string

Returns #

TextAreaComponent

setValue() #

setValue(value): TextAreaComponent

Set the current value.

Parameters #

Parameter	Type
value	string | null

Returns #

TextAreaComponent

---

TextComponent #

Single-line text input, built via Setting.addText.

Properties #

Property	Type
el	VirtualEl

Methods #

onChange() #

onChange(callback): TextComponent

Fires with the new string value on every change.

Parameters #

Parameter	Type
callback	(value) => void

Returns #

TextComponent

setPlaceholder() #

setPlaceholder(value): TextComponent

Set the placeholder text shown when the input is empty.

Parameters #

Parameter	Type
value	string

Returns #

TextComponent

setValue() #

setValue(value): TextComponent

Set the current value.

Parameters #

Parameter	Type
value	string | null

Returns #

TextComponent

---

ToggleComponent #

On/off toggle switch, built via Setting.addToggle.

Properties #

Property	Type
el	VirtualEl

Methods #

onChange() #

onChange(callback): ToggleComponent

Fires with the new boolean value on every change.

Parameters #

Parameter	Type
callback	(checked) => void

Returns #

ToggleComponent

setValue() #

setValue(value): ToggleComponent

Set the checked state.

Parameters #

Parameter	Type
value	boolean

Returns #

ToggleComponent

---

VirtualEl #

Minimal DOM-builder node. Plugins run in a sandbox and cannot touch the real DOM directly; instead they build a serializable VirtualEl tree that the host renders and reconciles.

Constructors #

Constructor #

new VirtualEl(tag): VirtualEl

Parameters #

Parameter	Type
tag	string

Returns #

VirtualEl

Properties #

Property	Type
attrs	Record<string, string>
children	(VirtualEl | VirtualText)[]
events	Record<string, number>
styles	Record<string, string>
tag	string

Methods #

addClass() #

addClass(cls): VirtualEl

Add a CSS class, whitespace-joined with any existing classes.

Parameters #

Parameter	Type
cls	string

Returns #

VirtualEl

appendChild() #

appendChild(child): VirtualEl

Append a VirtualEl or VirtualText; throws on anything else.

Parameters #

Parameter	Type
child	VirtualEl | VirtualText

Returns #

VirtualEl

appendText() #

appendText(value): VirtualEl

Append a VirtualText child.

Parameters #

Parameter	Type
value	string

Returns #

VirtualEl

createBlobImage() #

createBlobImage(callback?): BlobImageComponent

Append a blob-image custom component and return its builder.

Parameters #

Parameter	Type
callback?	(c) => void

Returns #

BlobImageComponent

createDiv() #

createDiv(options?, callback?): VirtualEl

Shorthand for createEl("div", ...).

Parameters #

Parameter	Type
options?	{ attr?: Record<string, string>; cls?: string | string[]; text?: string; }
options.attr?	Record<string, string>
options.cls?	string | string[]
options.text?	string
callback?	(child) => void

Returns #

VirtualEl

createEl() #

createEl(tag, options?, callback?): VirtualEl

Append a child element and return it. options accepts text, cls (string or string[]), and attr (object). The optional callback receives the new child for further building.

Parameters #

Parameter	Type
tag	string
options?	{ attr?: Record<string, string>; cls?: string | string[]; text?: string; }
options.attr?	Record<string, string>
options.cls?	string | string[]
options.text?	string
callback?	(child) => void

Returns #

VirtualEl

createIcon() #

createIcon(callback?): IconComponent

Append an icon custom component and return its builder.

Parameters #

Parameter	Type
callback?	(c) => void

Returns #

IconComponent

createPostsFeed() #

createPostsFeed(callback?): PostsFeedComponent

Append a posts-feed custom component and return its builder.

Parameters #

Parameter	Type
callback?	(c) => void

Returns #

PostsFeedComponent

createProfilesList() #

createProfilesList(callback?): ProfilesListComponent

Append a profiles-list custom component and return its builder.

Parameters #

Parameter	Type
callback?	(c) => void

Returns #

ProfilesListComponent

createSpan() #

createSpan(options?, callback?): VirtualEl

Shorthand for createEl("span", ...).

Parameters #

Parameter	Type
options?	{ attr?: Record<string, string>; cls?: string | string[]; text?: string; }
options.attr?	Record<string, string>
options.cls?	string | string[]
options.text?	string
callback?	(child) => void

Returns #

VirtualEl

createText() #

createText(value): VirtualText

Append and return a VirtualText child.

Parameters #

Parameter	Type
value	string

Returns #

VirtualText

empty() #

empty(): VirtualEl

Remove all children.

Returns #

VirtualEl

onChange() #

onChange(fn): VirtualEl

Register a change handler (form controls).

Parameters #

Parameter	Type
fn	(event) => void

Returns #

VirtualEl

onClick() #

onClick(fn): VirtualEl

Register a click handler.

Parameters #

Parameter	Type
fn	(event?) => void

Returns #

VirtualEl

onInput() #

onInput(fn): VirtualEl

Register an input handler (text inputs).

Parameters #

Parameter	Type
fn	(event) => void

Returns #

VirtualEl

setAttr() #

setAttr(name, value): VirtualEl

Set an attribute; undefined coerces to "".

Parameters #

Parameter	Type
name	string
value	string | undefined

Returns #

VirtualEl

setStyle() #

setStyle(name, value): VirtualEl

Set an inline style.

Parameters #

Parameter	Type
name	string
value	string | null

Returns #

VirtualEl

setText() #

setText(text): VirtualEl

Replace all children with a single VirtualText node.

Parameters #

Parameter	Type
text	string | null

Returns #

VirtualEl

---

VirtualText #

A text node in a VirtualEl tree. Null/undefined coerce to "".

Constructors #

Constructor #

new VirtualText(value): VirtualText

Parameters #

Parameter	Type
value	string | null | undefined

Returns #

VirtualText

Properties #

Property	Type
value	string

Type Aliases #

BacklinkRecord #

BacklinkRecord = object

A record that links to a queried subject.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
collection	string
did	string
rkey	string

---

Cloneable #

Cloneable = null | undefined | boolean | number | string | ArrayBuffer | CloneableArray | CloneableObject

JSON-shaped data, plus ArrayBuffer for binary payloads — the only thing that can cross between a plugin and the host. Functions, class instances, Date, Map and friends cannot.

Type Parameters #

Type Parameter

---

CloneableArray #

CloneableArray = Cloneable[]

An array of Cloneable values.

Type Parameters #

Type Parameter

---

CloneableObject #

CloneableObject = object

An object whose values are all Cloneable.

Type Parameters #

Type Parameter

Index Signature #

[key: string]: Cloneable

---

DetailedProfileView #

DetailedProfileView = Record<string, unknown>

Detailed profile view with viewer relationship fields.

Type Parameters #

Type Parameter

---

FeedGeneratorView #

FeedGeneratorView = Record<string, unknown>

An app.bsky.feed.defs#generatorView shape.

Type Parameters #

Type Parameter

---

FeedItem #

FeedItem = Record<string, unknown>

A app.bsky.feed.defs#feedViewPost (post + reply/repost context).

Type Parameters #

Type Parameter

---

KnownFollowersResponse #

KnownFollowersResponse = Record<string, unknown>

Paginated response from getKnownFollowers: { followers, cursor }.

Type Parameters #

Type Parameter

---

ListView #

ListView = Record<string, unknown>

An app.bsky.graph.defs#listView shape.

Type Parameters #

Type Parameter

---

PluginEventMap #

PluginEventMap = object

The events Plugin.on accepts, and the listener each one takes.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
post-composer-open()	(composer, context) => void
post-context-menu()	(menu, post, meta?) => void
profile-context-menu()	(menu, profile) => void

---

PluginFetchHeaders #

PluginFetchHeaders = Record<string, string> | Headers | Map<string, string> | Iterable<[string, string], void, undefined>

Any header collection fetch accepts — read structurally, not by class.

Type Parameters #

Type Parameter

---

PluginFetchInit #

PluginFetchInit = object

Options for fetch — a subset of RequestInit the host proxy supports.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
body?	string
headers?	PluginFetchHeaders
method?	string

---

PostComposerContext #

PostComposerContext = object

What the composer is being opened for, passed to post-composer-open listeners.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
kind	"post" | "reply" | "quote"
quotedPost	PostView | null
replyRoot	PostView | null
replyTo	PostView | null

---

PostContextMenuMeta #

PostContextMenuMeta = object

Where a post was seen, passed to post-context-menu listeners.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
feedContext	string | null
feedGenerator	Record<string, unknown> | null
feedProxyUrl	string | null

---

PostThreadView #

PostThreadView = Record<string, unknown>

Hydrated thread for a post: the post plus parent/replies.

Type Parameters #

Type Parameter

---

PostView #

PostView = Record<string, unknown>

Hydrated app.bsky.feed.defs#postView shape.

Type Parameters #

Type Parameter

---

ProfileView #

ProfileView = Record<string, unknown>

Basic app.bsky.actor.defs#profileView shape.

Type Parameters #

Type Parameter

---

RenderResult #

RenderResult = VirtualEl | null | undefined

What a render callback may return: a tree to render, or nothing.

Type Parameters #

Type Parameter

---

RepoRecord #

RepoRecord = Record<string, unknown>

A raw repo record: { uri, cid, value }.

Type Parameters #

Type Parameter

---

RichTextFacet #

RichTextFacet = object

An app.bsky.richtext.facet — a byte range plus the features applying to it.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
features?	RichTextFacetFeature[]
index	object
index.byteEnd	number
index.byteStart	number

---

RichTextFacetFeature #

RichTextFacetFeature = object & Record<string, unknown>

One feature of a facet; fields beyond $type vary by service.

Type Declaration #

Name	Type
$type	string

Type Parameters #

Type Parameter

---

RichTextFacetToken #

RichTextFacetToken = object

The text covered by one facet; the host restores the original facet payload.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
facet	RichTextFacet
text	string
type	"facet"

---

RichTextNodeToken #

RichTextNodeToken = object

Custom content the plugin renders itself — block on its own line, inline in the text flow.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
node	VirtualEl | Record<string, unknown>
pluginId?	string
type	"inline" | "block"

---

RichTextTextToken #

RichTextTextToken = object

A run of plain text.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
type	"text"
value	string

---

RichTextToken #

RichTextToken = RichTextTextToken | RichTextFacetToken | RichTextNodeToken

One token in a rich-text stream — text, facet, inline, or block.

Type Parameters #

Type Parameter

---

XrpcQueryResponse #

XrpcQueryResponse = object

Raw XRPC response: on failure data is the error body ({ error, message }) when the service provided one.

Type Parameters #

Type Parameter

Type Declaration #

Name	Type
data	unknown
ok	boolean
status	number

Functions #

fetch() #

fetch(url, init?): Promise<PluginResponse>

Proxied fetch through the host. The target URL must match one of the permissions.fetch URL patterns declared in the plugin's manifest, which the user grants at install. init accepts method, headers (plain object, Headers, Map, or [name, value] iterable), and a string body. Resolves to a PluginResponse.

Parameters #

Parameter	Type
url	string
init?	PluginFetchInit

Returns #

Promise<PluginResponse>

---

flattenForScan() #

flattenForScan(tokens): FlattenedTokens

Convenience wrapper that returns a new FlattenedTokens for tokens.

Parameters #

Parameter	Type
tokens	RichTextToken[]

Returns #

FlattenedTokens

---

getUserGrantedFetchOrigins() #

getUserGrantedFetchOrigins(): Promise<string[]>

The origins the user has granted this plugin, as fetch patterns (https://example.com/*). Manifest-declared permissions are not included.

Returns #

Promise<string[]>

---

requestFetchPermission() #

requestFetchPermission(url): Promise<boolean>

Asks the user to grant this plugin network access to url's origin — for endpoints the plugin can't know in advance, such as a user-supplied API provider. Requires permissions.userFetch in the manifest.

Grants are origin-scoped (scheme, host, and port; the path is ignored) and persist until the user revokes them in the app's plugin settings. Resolves true without prompting if the origin is already permitted, so it is safe to call before every request. Resolves false if the user declines, if url can't be an origin, or if a prompt for this plugin is already open.

Any credential for the endpoint is the plugin's to hold — use Plugin.saveLocalData rather than Plugin.saveData, which syncs through the user's account preferences.

Parameters #

Parameter	Type
url	string

Returns #

Promise<boolean>