BeePort

Embeddable feedback widget that turns user feedback into agent-ready GitHub issues. Automatically captures 90% of technical context (browser, OS, screen, URL) so users only need to describe their intent.

Why BeePort?

• Zero-friction feedback: Users describe what they want, BeePort captures the technical details
• Agent-ready issues: Structured format optimized for AI/agent consumption and automation
• Tiny bundle: ~3KB gzipped, zero dependencies
• Privacy-first: No tracking, no analytics, issues go directly to your GitHub repo
• Shadow DOM isolation: Won't break your styles or scripts

Installation

Via npm/yarn/pnpm

npm install beeport
# or
yarn add beeport
# or
pnpm add beeport

Via CDN

<!-- unpkg -->
<script src="https://unpkg.com/beeport@latest/dist/beeport.min.js"></script>

<!-- jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/beeport@latest/dist/beeport.min.js"></script>

Quick Start

ES Modules

import { init } from 'beeport';

const beeport = init({
  repo: 'your-org/your-repo',
  token: 'ghp_your_github_token'
});

Script Tag (CDN)

<script src="https://unpkg.com/beeport@latest/dist/beeport.min.js"></script>
<script>
  const beeport = BeePort.init({
    repo: 'your-org/your-repo',
    token: 'ghp_your_github_token'
  });
</script>

TypeScript

import { init, BeePortConfig, BeePortInstance } from 'beeport';

const config: BeePortConfig = {
  repo: 'your-org/your-repo',
  token: 'ghp_your_github_token',
  position: 'bottom-right',
  theme: 'auto'
};

const beeport: BeePortInstance = init(config);

Configuration API

init(config)

Initialize the BeePort widget. Returns an BeePortInstance.

interface BeePortConfig {
  /** GitHub repository in "owner/repo" format (required) */
  repo: string;

  /** GitHub Personal Access Token with repo:write scope (required) */
  token: string;

  /** Position of the widget button */
  position?: 'bottom-right' | 'bottom-left';  // default: 'bottom-right'

  /** Widget theme */
  theme?: 'light' | 'dark' | 'auto';  // default: 'auto'
}

BeePortInstance Methods

interface BeePortInstance {
  /** Show the widget */
  show(): void;

  /** Hide the widget */
  hide(): void;

  /** Change the widget theme */
  setTheme(theme: 'light' | 'dark' | 'auto'): void;

  /** Destroy the widget and remove from DOM */
  destroy(): void;
}

Examples

Basic Bug Report Widget

import { init } from 'beeport';

init({
  repo: 'acme/web-app',
  token: 'ghp_xxxxxxxxxxxxx'
});

Feature Request Widget (Left Position)

import { init } from 'beeport';

const beeport = init({
  repo: 'acme/product',
  token: 'ghp_xxxxxxxxxxxxx',
  position: 'bottom-left'
});

Custom Theme Control

import { init } from 'beeport';

const beeport = init({
  repo: 'acme/app',
  token: 'ghp_xxxxxxxxxxxxx',
  theme: 'dark'
});

// Later, switch to light theme
beeport.setTheme('light');

Conditional Widget Display

import { init } from 'beeport';

const beeport = init({
  repo: 'acme/beta-app',
  token: 'ghp_xxxxxxxxxxxxx'
});

// Hide widget for certain users
if (user.isPremium) {
  beeport.hide();
}

// Show it again later
beeport.show();

Complete Lifecycle Management

import { init } from 'beeport';

// Initialize
const beeport = init({
  repo: 'acme/app',
  token: 'ghp_xxxxxxxxxxxxx'
});

// Use the widget...

// Clean up when done (e.g., SPA route change)
beeport.destroy();

TypeScript Support

BeePort is written in TypeScript and includes full type definitions.

import type {
  BeePortConfig,
  BeePortInstance,
  Position,
  Theme,
  FeedbackType,
  BrowserContext
} from 'beeport';

All configuration options and methods are fully typed for excellent IDE autocomplete and type safety.

Browser Support

BeePort supports all modern browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Opera 76+

ES2020 Required: The widget uses modern JavaScript features (optional chaining, nullish coalescing, etc.). No IE11 support.

Bundle Size

• Minified: ~11KB
• Gzipped: ~3KB
• Zero dependencies

The widget uses Shadow DOM for style isolation and has no external dependencies, making it extremely lightweight and non-intrusive.

What Gets Captured?

When a user submits feedback, BeePort automatically captures:

• Page URL
• Browser name and version
• Operating system and version
• Screen resolution and pixel ratio
• Viewport dimensions
• Language and timezone
• Timestamp (ISO 8601)

This context is formatted into a GitHub issue with structured metadata for easy parsing by AI agents or automation tools.

Security

• Token security: Your GitHub token is used client-side to create issues. For production use, consider proxying requests through your backend or using a token with minimal scopes (only public_repo or repo for private repos).
• No tracking: BeePort doesn't phone home, track analytics, or send data anywhere except your specified GitHub repository.
• Shadow DOM: Isolates the widget from your page's CSS and JavaScript, preventing conflicts or security issues.

License

MIT License - see LICENSE for details.

Contributing

We welcome contributions! Please see our contributing guidelines for details.

Links

• GitHub Repository
• Issue Tracker
• npm Package

Made with care for developers building better products.