Bug Handler

Bug Handler

A resilient, privacy‑first error reporting toolkit for Dart & Flutter applications.

It gives you:

• A central client to create, sanitize, deduplicate, rate‑limit, and send error reports.
• Built‑in context providers (app, device, network, UI, user) with caching and opt‑in heavy data.
• A flexible sanitization pipeline (masking by key and content, regex rewrites, depth/size pruning, allow/deny filters).
• Policy controls (severity gating, environment allow‑list, sampling, rate‑limit, dedupe window).
• Outbox persistence for offline scenarios and delivery retries.
• A composable reporter pipeline (console logging, share sheet; adapters stubs for Sentry/Crashlytics).
• Developer‑friendly guard helpers, a Result type, and a Flutter ErrorBoundary widget.
• A typed exception hierarchy that standardizes error shape and severity across domains.

Package entrypoint: package:bug_handler/bug_handler.dart re‑exports all public APIs.

---

AI coding-assistant support (agent plugin)

Package-specific support for Claude Code and OpenAI Codex is available as an installable agent plugin, maintained in this repository. This is developer tooling for coding agents - it is not a runtime feature of the Dart package, and it is not part of the pub.dev archive; it installs from this Git repository.

Supported surfaces: Claude Code (CLI, desktop, and other Claude Code surfaces that support plugins); Codex CLI v0.131.0+ and ChatGPT Work mode (Codex plugins are currently not available in the IDE extension, Chat mode, or mobile).

Claude Code

/plugin marketplace add omar-hanafy/bug_handler
/plugin install bug-handler@bug-handler

OpenAI Codex

codex plugin marketplace add omar-hanafy/bug_handler
codex plugin add bug-handler@bug-handler

Start a new session after installing (required by Codex; in Claude Code run /reload-plugins or restart).

The plugin ships seven skills that activate automatically when relevant, or explicitly via /bug-handler:<skill> (Claude Code) and $<skill> (Codex): setup-reporting, guard-workflow, extend-pipeline, tune-privacy, diagnose-reporting, migrate-legacy-api (0.0.1-dev.x -> 1.0.0-dev.x), audit-error-handling.

Example prompts:

• "Wire bug_handler into this app - we already initialize Sentry in bootstrap."
• "Why do errors from staging never arrive in our backend?"
• "Migrate this project off the old BugReporter API."

Trust note: the plugin contains only instructions, reference markdown, and illustrative fixtures - no hooks, MCP servers, or executable scripts. Skills target bug_handler >= 1.0.0-dev.5. Full documentation, troubleshooting, update/removal instructions: doc/ai-plugin.md.

---

Table of contents

1. Installation

2. Quick start

3. Core concepts

   • BugReportClient
   • ClientConfig & Policy
   • ReportEvent
   • Context providers
   • Sanitizers & Filters
   • Reporters
   • Outbox
   • Breadcrumbs

4. Flutter wiring

   • Global bindings
   • ErrorBoundary widget

5. Guard helpers & Result

6. Exceptions overview

7. Transform hooks

8. Extending

9. Testing & tips

10. Troubleshooting

11. FAQ

12. License

---

Installation

Add the package to yaml:

dependencies:
  bug_handler: ^<latest>

Then import:

import 'package:bug_handler/bug_handler.dart';

---

Quick start

Initialize once during app bootstrap and run your app under the provided bindings:

import 'package:flutter/foundation.dart' show kReleaseMode;
import 'package:bug_handler/bug_handler.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();