@duckbug/js

The official JavaScript SDK for DuckBug.io - a flexible logging and error tracking platform.

Features

• 🦆 Simple Integration: Easy setup with DuckBug.io
• 🔌 Provider Architecture: Extensible plugin system for custom logging providers
• 📊 Multiple Log Levels: Support for debug, info, warn, and error levels
• 🎯 TypeScript Support: Full TypeScript support with type definitions
• 📦 Dual Module Format: Both CommonJS and ES Module support
• ⚡ Lightweight: Minimal dependencies and small bundle size

Installation

# npm
npm install @duckbug/js

# yarn
yarn add @duckbug/js

# pnpm
pnpm add @duckbug/js

Quick Start

Basic Usage

import { DuckSDK, DuckBugProvider } from '@duckbug/js';

// Initialize with DuckBug.io provider
const providers = [
  new DuckBugProvider({
    dsn: 'your-duckbug-dsn-here'
  })
];

// Create SDK instance with optional configuration
const duck = new DuckSDK(providers, {
  logReports: {
    log: false,
    warn: true,
    error: true,
  }
});

// Start logging
duck.log('Info message', { userId: 123, action: 'user_login' });
duck.debug('Debug message', { debugInfo: 'Connection established' });
duck.warn('Warning message', { warning: 'Rate limit approaching' });
duck.error('Error message', { error: 'Database connection failed' });
duck.fatal('Fatal message', { error: 'Ay, caramba' });

//Send error
const testError = new Error("Integration test error");
testError.stack =
  "Error: Integration test error\n    at integration.test.ts:1:1";

// Use quack method directly on provider
duckBugProvider.quack("INTEGRATION_ERROR", testError);

API Reference

DuckSDK

The main SDK class that manages logging across multiple providers.

Constructor

new DuckSDK(providers: Provider[], config?: LogProviderConfig)

• providers: Array of provider instances
• config: Optional configuration for log reporting levels

Methods

• log(tag: string, payload?: object): Log an info-level message
• debug(tag: string, payload?: object): Log a debug-level message
• warn(tag: string, payload?: object): Log a warning-level message
• error(tag: string, payload?: object): Log an error-level message
• fatal(tag: string, payload?: object): Log an fatal-level message
• quack(tag: string, error: Error): Report error

DuckBugProvider

The official DuckBug.io provider for sending logs to the DuckBug.io platform.

Constructor

new DuckBugProvider(config: DuckConfig)

• config.dsn: Your DuckBug.io DSN (Data Source Name)

Log Provider Configuration

type LogProviderConfig = {
  logReports: {
    log?: boolean;    // Enable/disable info logs (default: false)
    warn?: boolean;   // Enable/disable warning logs (default: true)
    error?: boolean;  // Enable/disable error logs (default: true)
  }
}

Custom Providers

You can create custom providers by implementing the Provider interface:

import { Provider, LogLevel } from '@duckbug/js';

class TelegramProvider implements Provider {
  constructor(private botToken: string, private chatId: string) {}

  log(...args: unknown[]): void {
    this.sendToTelegram('📝', args);
  }

  warn(...args: unknown[]): void {
    this.sendToTelegram('⚠️', args);
  }

  error(...args: unknown[]): void {
    this.sendToTelegram('🚨', args);
  }

  report(tag: string, level: LogLevel, payload?: object): void {
    const emojiMap: Record<LogLevel, string> = {
      INFO: '📝',
      DEBUG: '🦆',
      WARN: '⚠️',
      ERROR: '🚨',
      FATAL: '💀',
    };
    this.sendToTelegram(emojiMap[level], [tag, payload]);
  }

  quack(tag: string, error: Error): void {
    this.sendToTelegram('💀', [tag, error.message]);
  }

  private sendToTelegram(emoji: string, args: unknown[]) {
    const message = `${emoji} ${args.join(' ')}`;
    // Implementation to send message to Telegram
    fetch(`https://api.telegram.org/bot${this.botToken}/sendMessage`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        chat_id: this.chatId,
        text: message
      })
    });
  }
}

// Usage
const providers = [
  new DuckBugProvider({ dsn: 'your-dsn' }),
  new TelegramProvider('your-bot-token', 'your-chat-id')
];

const duck = new DuckSDK(providers);

Development

Setup

Install dependencies:

bun install

Build

Build the library:

bun run build

Linting

Run linting:

bun run lint

Commit Messages

Этот проект использует Conventional Commits для стандартизации сообщений коммитов. Все коммиты должны соответствовать следующему формату:

<type>(<scope>): <subject>

<body>

<footer>

Типы коммитов (обязательные)

• feat: Новая функциональность
• fix: Исправление бага
• docs: Изменения в документации
• style: Форматирование кода (не влияет на выполнение кода)
• refactor: Рефакторинг кода
• perf: Улучшение производительности
• test: Добавление или изменение тестов
• build: Изменения в системе сборки или внешних зависимостях
• ci: Изменения в CI конфигурации
• chore: Обновление задач сборки, настроек и т.д.
• revert: Откат предыдущего коммита

Примеры корректных коммитов

feat: добавить поддержку логирования ошибок
fix: исправить утечку памяти в DuckBugProvider
docs: обновить README с примерами использования
test: добавить тесты для DuckSDK
refactor: улучшить структуру классов провайдеров

Проверка коммитов

Автоматическая проверка формата коммитов выполняется через git hook. При создании коммита с неправильным форматом вы получите подробное сообщение об ошибке с описанием проблемы и примерами правильного формата.

Примеры ошибок:

❌ Если забыли указать тип:

❌ Тип коммита обязателен!
📝 Формат коммита: <type>: <описание>
💡 Примеры:
   feat: добавить новую функцию
   fix: исправить обработку ошибок

❌ Если использовали неправильный тип:

❌ Неверный тип коммита!
✅ Используйте один из допустимых типов:
   - feat: новая функциональность
   - fix: исправление бага
   ...

Для ручной проверки сообщения коммита:

bun run commitlint -- --from HEAD~1 --to HEAD

Автоматические релизы

Этот проект использует semantic-release для автоматического управления версиями и релизами.

Как это работает:

• Версионирование: Версия автоматически обновляется на основе типов коммитов:

  • feat: → минорное обновление (1.0.0 → 1.1.0)
  • fix: → патч (1.0.0 → 1.0.1)
  • BREAKING CHANGE или feat!: → мажорное обновление (1.0.0 → 2.0.0)
  • chore:, docs:, style: и другие → без релиза

• Автоматические действия при пуше в main:

  1. Анализ коммитов с последнего релиза
  2. Определение новой версии
  3. Генерация CHANGELOG.md
  4. Обновление версии в package.json
  5. Создание git тега
  6. Публикация в npm
  7. Создание GitHub Release с заметками

Настройка:

1. Создайте NPM токен (только для публикации):

   • Перейдите на https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Создайте токен с правами Automation
   • Добавьте его в GitHub Secrets как NPM_TOKEN

2. GitHub Actions:

   • Workflow release.yaml автоматически запускается при пуше в main или beta
   • Использует GITHUB_TOKEN (автоматически предоставляется GitHub Actions)
   • Использует NPM_TOKEN из секретов для публикации в npm

Примеры коммитов для релизов:

# Патч релиз (1.0.0 → 1.0.1)
fix: исправить обработку ошибок в DuckBugProvider

# Минорный релиз (1.0.0 → 1.1.0)
feat: добавить поддержку фильтрации логов

# Мажорный релиз (1.0.0 → 2.0.0)
feat!: изменить API провайдеров

# или

feat: добавить новую функцию

BREAKING CHANGE: изменена структура конфигурации DuckBugProvider

Примечание: Коммиты без типа или с типом chore, docs, style не создают новый релиз, но могут быть включены в CHANGELOG.

TypeScript Support

This package includes TypeScript definitions. All exports are fully typed:

import type { Provider, DuckConfig, LogLevel } from '@duckbug/js';

Browser Compatibility

This SDK works in all modern browsers that support:

• ES2015+ (ES6)
• Fetch API
• JSON API

For older browsers, you may need to include polyfills.

License

MIT © DuckBug.io

Support

• 🐛 Issues: GitHub Issues

---

Made with 🦆 by the DuckBug.io team