Reference
API
1.0 — what it promises #
From 1.0 this list is a contract rather than a description. Semantic versioning
applies to every name in it: removing or renaming an export, an option or a
data-* attribute needs a major version, adding an entry point needs a
minor one, and a patch changes behaviour only where the behaviour was a bug.
The seven naming rules in CLAUDE.md are what the next name will be chosen by,
and docs/api-audit-1.0.md holds the whole surface — every export of every
entry point, generated from the build — so a rename is visible as a diff rather
than as a surprise. tests/exports.test.ts fails if the exports map, this
section or CLAUDE.md stop agreeing.
What is not frozen: the wire format grows fields rather than changing them (a
report is validated field by field, so an older server ignores a newer one's
additions), the bundle sizes are budgets rather than promises, and anything
under site/, examples/ or scripts/ is not published at all.
bugbottle — initConsoleBuffer, getConsoleBuffer, resetConsoleBuffer,
captureScreenshot (with CaptureInfo, DEFAULT_BYTES_PER_PIXEL_ESTIMATE and
the MaskOptions of its mask option, whose defaults are
DEFAULT_MASK_SELECTOR, DEFAULT_BLOCK_SELECTOR and DEFAULT_MASK_COLOUR),
collectContext, pickElement, describeElement, buildSelector,
buildReport, sendReport, scrubReport, scrubUrl, BUILTIN_SCRUBBERS,
fingerprint, stableHash,
ScreenshotTooLargeError, SendFailedError, SendTimeoutError,
REPORT_TYPES, isReportType, and the shared types and limits — including the
StackFrame type, MAX_STACK_FRAMES, MAX_STACK_STRING_LENGTH,
MAX_CONTACT_LENGTH and MAX_CONTEXT_LENGTHS.
The validators and toMarkdown are not here: they are what a receiving
server does with a report that has arrived, so since 1.0 they live on
bugbottle/server alone. REPORT_TYPES and isReportType stay, because the
panel and the adapters build the type radiogroup out of them and ReportType
would otherwise be a type with no values behind it.
The option and payload types come with them: BugReport, ReportContext,
ReportType, ConsoleEntry, ConsoleLevel, ElementRef, Breadcrumb,
BreadcrumbKind, NetworkEntry, PerfSnapshot, StorageSnapshot,
StorageKeyRef, ReplayCapture, ReplayEvent, BuildReportInput,
SendOptions, SendResult, CaptureOptions, ConsoleBufferOptions,
PickOptions, ScrubOptions, Scrubber, ScrubberName, FingerprintInput,
and the two defaults DEFAULT_SEND_TIMEOUT_MS (15 s) and DEFAULT_REPLACEMENT
(what a scrubber writes in place of what it found).
dist/bugbottle.js — the everything script-tag build: window.bugbottle with
mount, initConsoleBuffer, initBreadcrumbs, initNetwork, initPerf,
createQueue,
locales,
resolveLocale, scrubReport, createSigner, buildReport, sendReport,
pickElement,
onShortcut, onUncaughtError, onShake, requestShakePermission,
version, and
data-* auto-mount. See "One script tag".
dist/bugbottle.slim.js — the same build without createAnnotator,
initPerf, onShake, requestShakePermission and initNetwork, and so
without data-annotate, data-perf, data-shake and data-network, which it
warns about once on the console. See "Two builds".
WordPress — the plugin at github.com/mahope/bugbottle-wordpress bundles this build, adds the receiving endpoint, stores reports as a private post type with an admin list, and emails them if you want. One activation.
bugbottle/annotate — createAnnotator, and the Annotator,
AnnotatorOptions and AnnotateTool types. See "Marking the picture".
bugbottle/breadcrumbs — initBreadcrumbs, getBreadcrumbs,
resetBreadcrumbs, isBreadcrumbsActive, and the BreadcrumbsOptions type.
bugbottle/network — initNetwork, getNetwork, resetNetwork,
isNetworkActive, and the NetworkOptions and NetworkEntry types.
bugbottle/perf — initPerf, getPerf, getStorageSnapshot,
resetPerf, isPerfActive, and the PerfOptions, PerfSnapshot,
StorageSnapshot and StorageKeyRef types. See "Performance and storage".
bugbottle/queue — createQueue, SCREENSHOT_NOTE, and the Queue,
QueueOptions, QueueStorage, QueuedReport and MaybePromise types. See
"When the network is down".
bugbottle/queue-idb — createIdbStorage and the IdbStorageOptions
type: the queue's reports in IndexedDB rather than localStorage, where a
screenshot fits. See "When the network is down".
bugbottle/rrweb — attachRrweb, getReplay, resetRrweb,
isRrwebAttached, DEFAULT_REPLAY_SECONDS, DEFAULT_REPLAY_MAX_BYTES,
REPLAY_CHECKOUT_MS, REPLAY_MASK_SELECTOR, REPLAY_BLOCK_SELECTOR, and the
RrwebOptions, RrwebRecord, RrwebRecordOptions, RrwebEvent,
ReplayCapture and ReplayEvent types. See "Replay with rrweb".
bugbottle/sign — createSigner, computeSignature, hmacHex,
DEFAULT_SIGNATURE_HEADER, and the SignerOptions type. See "Signing
requests".
bugbottle/triggers — onShortcut, onUncaughtError, parseShortcut,
matchesShortcut, isEditableTarget, eventSource, deepActiveElement,
isApplePlatform, describeUncaught,
DEFAULT_SHORTCUT, DEFAULT_DEDUPE_MS, and the Shortcut, ShortcutEvent,
ShortcutOptions, UncaughtError, UncaughtErrorOptions and ListenerHost
types.
bugbottle/shake — onShake, requestShakePermission,
DEFAULT_SHAKE_THRESHOLD, DEFAULT_SHAKE_COOLDOWN_MS,
DEFAULT_SHAKE_WINDOW_MS, and the ShakeOptions and ShakeEvent types. See
"Shake to report".
bugbottle/react — useBugReport, BugReportBoundary,
createRootErrorHandlers, describeRenderError, and the
BugReportBoundaryProps, ReportErrorOptions, RootErrorHandlerOptions and
RootErrorHandlers types.
bugbottle/vue — useBugReport, a composable over refs, and the
UseBugReportOptions and BugReportStatus types. Optional peer vue >= 3.
bugbottle/svelte — createBugReport, a readable store plus the actions,
and the BugReportView, UseBugReportOptions and BugReportStatus types.
Optional peer svelte >= 4.
bugbottle/solid — createBugReport, accessors over the same machine plus
the actions, and the UseBugReportOptions and BugReportStatus types.
Optional peer solid-js >= 1.8.
bugbottle/html-to-image — htmlToImage, a ScreenshotRenderer.
Requires html-to-image.
bugbottle/ui — mountBugbottle, and the MountOptions (whose
annotate takes createAnnotator itself, whose shake takes onShake, and
whose network and perf take initNetwork and initPerf),
Theme, Brand and BugbottleWidget types.
bugbottle/locales — en, da, sv, nb, de, nl, fr, es,
locales, resolveLocale, enMessages (the English messages on their own,
so the hook can default without dragging eight languages in), and the Locale,
Messages, UiTexts, EmailTexts types.
bugbottle/locales-extra — it, pl, pt, fi, uk and
localesExtra, the five optional languages in the same Locale shape. Nothing
imports this entry, so a site that does not ask for it never carries it.
bugbottle/server — handleReport (with clientAddress, the
TrustProxyOptions type, and the ReportDecision and DecisionReason
types onDecision is handed), expressHandler, fileStore
(whose store answers store, list, read, remove, prune and refresh,
with DEFAULT_MAX_REPORTS and the FileStore, FileStoreOptions,
StoredReport and StoredReportFile types), toResend,
toWebhook, toGithub, toLinear, validateReport, collectExtra, resetRateLimits,
resetDedupe, resetSignatures, fingerprint, stableHash,
decodeScreenshotDataUrl, normaliseMessage, normaliseContact,
looksLikeEmail,
normaliseContext, normaliseConsole, normaliseElements,
normaliseBreadcrumbs, normaliseNetwork, normalisePerf,
normaliseStorage, normaliseReplay, normaliseNotes, isReportType, toMarkdown,
scrubReport, scrubUrl,
sendReportEmail, sendReportWebhook, createGithubIssue,
createLinearIssue, smtpSink, sendReportSmtp, buildMessage,
foldHeader, dotStuff, DEFAULT_SMTP_PORT, DEFAULT_SMTP_TIMEOUT_MS,
SMTP_TLS_PORT, SMTP_NO_REPLY, the SmtpSink, SmtpSinkOptions and
SendReportSmtpResult types, jiraSink, buildJiraDescription, jiraBaseUrl,
jiraAuthHeader, messageFromJiraBody, DEFAULT_JIRA_ISSUE_TYPE,
MAX_JIRA_CONSOLE_ENTRIES, MAX_JIRA_SUMMARY, the JiraSink,
JiraSinkOptions, CreateJiraIssueResult, AdfDoc and AdfNode types,
gitlabSink, messageFromGitlabBody, DEFAULT_GITLAB_HOST,
MAX_GITLAB_DESCRIPTION, MAX_GITLAB_TITLE, the GitlabSink,
GitlabSinkOptions and CreateGitlabIssueResult types,
slackSink, discordSink, teamsSink, buildSlackMessage,
buildDiscordMessage, buildTeamsMessage, escapeSlack, escapeTeams,
DISCORD_COLOURS, TEAMS_CARD_SCHEMA, TEAMS_CARD_VERSION,
TEAMS_CARD_CONTENT_TYPE, the MAX_SLACK_*,
MAX_DISCORD_* and MAX_TEAMS_* limits, MAX_CHAT_CONSOLE_ENTRIES, the SlackSinkOptions,
DiscordSinkOptions, TeamsSinkOptions, ChatSink, ChatSinkContext and
UrlFrom types,
sentrySink, buildSentryEvent, buildSentryEnvelope, parseSentryDsn,
sentryAuthHeader, clipBytes, SentrySinkError, SENTRY_CLIENT,
SENTRY_CLIENT_NAME, SENTRY_CLIENT_VERSION, SENTRY_VERSION,
DEFAULT_SENTRY_RETRY_AFTER, the MAX_SENTRY_* limits, and the
SentrySinkOptions, SentrySinkContext, SentryDsn, SentryEnvelope,
SentryItemType and SentryTruncation types,
InvalidScreenshotError, SinkError, SinkTimeoutError, REPORT_TYPES,
the DEFAULT_MAX_BODY_BYTES, DEFAULT_BODY_TIMEOUT_MS and
DEFAULT_SINK_TIMEOUT_MS defaults, the ValidatedReport,
HandleReportOptions, HandleReportResult, RateLimitOptions,
RateLimitStore, DedupeOptions, DedupeStore, DedupeEntry,
SignatureOptions, ReportSink and
SinkContext and ReplayStore types, DEFAULT_SIGNATURE_SKEW_MS,
MAX_SIGNATURE_ENTRIES, MAX_SIGNATURE_ENTRIES_PER_SECOND,
MAX_SIGNATURE_SECONDS,
BAD_SIGNATURE_ERROR, the two refusal messages EMPTY_MESSAGE_ERROR and
TOO_LARGE_ERROR, the StackFrame type, and the MAX_* limits, including
MAX_STACK_FRAMES, MAX_STACK_STRING_LENGTH, MAX_CONTEXT_LENGTHS,
MAX_EXTRA_KEYS, MAX_EXTRA_STRING_LENGTH, MAX_DEDUPE_ENTRIES,
MAX_RATE_LIMIT_BUCKETS and MAX_RATE_LIMIT_KEY_LENGTH.
Each sink's options and result travel with it: SendReportEmailOptions and
SendReportEmailResult, SendReportWebhookOptions (and its
SendReportWebhookTarget and WebhookFormat) with SendReportWebhookResult,
CreateGithubIssueOptions with CreateGithubIssueResult,
CreateLinearIssueOptions with CreateLinearIssueResult, and the FetchLike
every one of them takes as fetch. expressHandler brings the two structural
types it reads an Express request and response through, ExpressRequestLike
and ExpressResponseLike.
bugbottle/report.schema.json — the JSON Schema for the payload, also
served at bugbottle.dev/schema/report.json.
bugbottle/openapi.json — the OpenAPI 3.1 description of the report
endpoint, generated from that schema and from handleReport's answers, also
served at bugbottle.dev/schema/openapi.json.
Ships as ESM with TypeScript declarations. Node 18+ on the server; any evergreen browser on the client.