@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:

yarn install

Build

Build the library:

yarn build

Linting

Run linting:

yarn lint

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