@duckbug/js 0.1.3 → 1.1.0

package/README.md

@@ -31,76 +31,251 @@ pnpm add @duckbug/js
 
 ### Basic Usage
 
+DSN must follow the ingest URL shape from the DuckBug SDK spec (`duckbug-sdk-spec`): `{origin}/ingest/{projectId}:{publicKey}` or `{origin}/api/ingest/{projectId}:{publicKey}` (for example on `duckbug.io`).
+
 ```typescript
-import { DuckSDK, DuckBugProvider } from '@duckbug/js';
+import { Duck, DuckBugProvider, Pond } from '@duckbug/js';
+
+const dsn = 'https://api.duckbug.io/ingest/your-project-id:your-public-key';
+const { extraSensitiveKeys } = Pond.ripple(['custom_secret']);
+
+const duck = new Duck(
+  [new DuckBugProvider({ dsn, extraSensitiveKeys })],
+  {
+    logReports: {
+      log: false,
+      warn: true,
+      error: true,
+    },
+  },
+);
+
+// Branded + idiomatic error capture
+const err = new Error('Something failed');
+duck.quack('checkout_failed', err);
+duck.captureException(err, 'checkout_failed');
+
+// Logging (levels normalized to DEBUG, INFO, WARN, ERROR, FATAL)
+duck.warn('Slow query', { ms: 1200 });
+```
 
-// Initialize with DuckBug.io provider
-const providers = [
-  new DuckBugProvider({
-    dsn: 'your-duckbug-dsn-here'
-  })
-];
+`DuckSDK` remains available as an alias of the same runtime; prefer `Duck` for new code.
 
-// Create SDK instance with optional configuration
-const duck = new DuckSDK(providers, {
-  logReports: {
-    log: false,
-    warn: true,
-    error: true,
-  }
+Before process exit, await `duck.flush()` so queued HTTP work finishes (for example at the end of an `async main()`).
+
+### Reserved `_duck` on log payloads
+
+The second argument to `log` / `debug` / `warn` / `error` / `fatal` may be a plain object with a reserved **`_duck`** field for technical metadata. **`_duck` is not sent inside `context`** on the wire.
+
+- **`_duck.dTags`** — sets top-level `dTags` on the ingest event (same as in a raw JSON body).
+- **`_duck.scope`** — one-shot `Partial<IngestSharedMetadata>` merged into **this** log only (after global `setScope`, before fixed fields). Use e.g. `platform: "ios"` to override the default `"node"`. Optional **`_duck.scope.context`** is used as the event `context` only when there are no other keys besides `_duck`.
+
+Any other keys on the object become **`context`**, which matches typical ingest JSON (`dTags` at the root, domain fields under `context`).
+
+```typescript
+duck.warn("DUCKBUG_DTAGS_SMOKE_TEST", {
+  source: "initDuckBugDeviceContext",
+  platform: "ios",
+  _duck: { dTags: ["smoke-test", "dtags"] },
+});
+```
+
+## Full usage example
+
+End-to-end pattern for a Node/Bun service: DSN from env, scope (release, user, fingerprint), privacy pipeline, `beforeSend`, batched transport with retries, transport errors, console forwarding, global error handlers, structured logs, manual errors, and clean shutdown.
+
+```typescript
+import {
+  Duck,
+  DuckBugProvider,
+  Pond,
+  registerNodeGlobalErrorHandlers,
+} from "@duckbug/js";
+
+const dsn = process.env.DUCKBUG_DSN;
+if (!dsn) {
+  throw new Error("Set DUCKBUG_DSN to your ingest URL");
+}
+
+const { extraSensitiveKeys } = Pond.ripple([
+  "custom_secret",
+  "internalToken",
+]);
+
+// Transport + ingest errors. Privacy (strip / sanitize / eventId / beforeSend) is applied in `Duck` when you use the core client.
+const duckBug = new DuckBugProvider({
+  dsn,
+  transport: {
+    maxBatchSize: 25,
+    maxRetries: 2,
+    retryDelayMs: 200,
+  },
+  onTransportError: (info) => {
+    console.error("[duckbug transport]", info.message, info.kind, info.itemCount);
+  },
 });
 
-// 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' });
+const duck = new Duck(
+  [duckBug],
+  {
+    logReports: {
+      log: true,
+      warn: true,
+      error: true,
+    },
+  },
+  {
+    extraSensitiveKeys,
+    // Omit whole sections before sanitize (see StrippableIngestSection in types)
+    stripSections: ["cookies", "headers"],
+    beforeSend: async (arg) => {
+      // Drop PII-heavy events in dev, or tweak payload
+      if (process.env.NODE_ENV === "test") {
+        return null;
+      }
+      if (arg.kind === "log" && arg.event.message.includes("healthcheck")) {
+        return null;
+      }
+      return arg.event;
+    },
+  },
+);
+
+// Applied to every subsequent log / error (merge into event)
+duck.setScope({
+  release: "my-app@1.4.2",
+  environment: process.env.NODE_ENV ?? "development",
+  service: "checkout-api",
+  fingerprint: "checkout-api-default",
+  // Prefer nesting session-like data under context; top-level `session` may be rejected by ingest.
+  context: { deployment: "eu-west" },
+});
+
+const unregisterGlobals = registerNodeGlobalErrorHandlers({
+  duck,
+  rejectionTag: "unhandledRejection",
+  exceptionTag: "uncaughtException",
+});
 
-//Send error
-const testError = new Error("Integration test error");
-testError.stack =
-  "Error: Integration test error\n    at integration.test.ts:1:1";
+async function main() {
+  duck.debug("boot", { pid: process.pid });
 
-// Use quack method directly on provider
-duckBugProvider.quack("INTEGRATION_ERROR", testError);
+  try {
+    await doCheckout();
+  } catch (e) {
+    const err = e instanceof Error ? e : new Error(String(e));
+    duck.quack("checkout_failed", err);
+    duck.captureException(err, "checkout_failed");
+  }
+
+  duck.warn("slow_query", { table: "orders", ms: 850 });
+  duck.error("inventory_low", { sku: "SKU-12", qty: 2 });
+  duck.fatal("migration_required", { from: "v10", to: "v11" });
+
+  await duck.flush();
+}
+
+async function doCheckout() {
+  // ...
+}
+
+main()
+  .catch((e) => {
+    console.error(e);
+    process.exitCode = 1;
+  })
+  .finally(async () => {
+    unregisterGlobals();
+    await duck.flush();
+  });
+```
+
+**Direct provider (no `Duck`)** — same privacy defaults via `finalizeIngestEvent` inside the provider; you call `sendLog` / `sendError` with `DuckBugLogEvent` / `DuckBugErrorEvent` shapes:
+
+```typescript
+import { DuckBugProvider, logLevel } from "@duckbug/js";
+
+const provider = new DuckBugProvider({ dsn });
+provider.sendLog({
+  time: Date.now(),
+  level: logLevel.INFO,
+  message: "Job finished",
+  platform: "node",
+  dTags: ["worker", "nightly"],
+});
+await provider.flush();
 ```
 
 ## API Reference
 
-### DuckSDK
+### Duck / DuckSDK
 
-The main SDK class that manages logging across multiple providers.
+The main SDK class fans out canonical log and error events to all registered providers.
 
 #### Constructor
 
 ```typescript
-new DuckSDK(providers: Provider[], config?: LogProviderConfig)
+new Duck(
+  providers: Provider[],
+  logProviderConfig?: LogProviderConfig,
+  options?: DuckSDKOptions,
+)
 ```
 
 - `providers`: Array of provider instances
-- `config`: Optional configuration for log reporting levels
+- `logProviderConfig`: Optional configuration for console interception (`LogProvider`)
+- `options`: Optional `beforeSend`, `stripSections`, `extraSensitiveKeys` (strip → sanitize → `eventId` → `beforeSend` → providers; matches `duckbug-sdk-spec`)
 
 #### 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
+- `log` / `debug` / `warn` / `error` / `fatal(tag, payload?)`: structured logs
+- `quack(tag, error)`: branded manual error capture; tag is sent as `dTags`, message comes from `error.message`
+- `captureException(error, tag?)`: idiomatic alias for `quack` (default tag `error`)
+- `setScope(partial)`: merge shared metadata into subsequent events
+- `flush()`: await transport drains on providers that implement `flush` (for example `DuckBugProvider`)
+
+Each captured log/error gets a UUID `eventId` when omitted (idempotency / retries).
 
 ### DuckBugProvider
 
-The official DuckBug.io provider for sending logs to the DuckBug.io platform.
+First-party provider: posts JSON to single-event ingest by default, or to `/logs/batch` and `/errors/batch` when `transport.maxBatchSize > 1` (body is a JSON array, as required by the DuckBug API).
 
 #### Constructor
 
 ```typescript
-new DuckBugProvider(config: DuckConfig)
+new DuckBugProvider({
+  dsn: string,
+  extraSensitiveKeys?: string[],
+  stripSections?: StrippableIngestSection[],
+  beforeSend?: (arg) => event | null | undefined | Promise<...>,
+  transport?: {
+    maxBatchSize?: number; // default 1 — one POST per event
+    maxRetries?: number;
+    retryDelayMs?: number;
+    fetchImpl?: typeof fetch;
+  },
+  onTransportError?: (info: TransportFailureInfo) => void,
+})
+// or
+DuckBugProvider.fromDSN(dsn)
 ```
 
-- `config.dsn`: Your DuckBug.io DSN (Data Source Name)
+- `config.dsn`: full ingest URL, e.g. `https://api.duckbug.io/ingest/myProject:myKey`
+- `flush()`: returns a `Promise` that resolves when queued requests for this provider have been sent
+
+### Privacy, batching, and Node hooks
+
+- **Strip sections**: omit whole request fields (`headers`, `cookies`, `session`, …) before sanitize via `stripSections` on `DuckBugProvider` or `DuckSDK` options.
+- **`beforeSend`**: on `Duck` / `DuckSDK` for all providers; on `DuckBugProvider` when using the provider without the core client. Return `null` to drop an event.
+- **Node global errors** (optional, no core framework deps):
+
+```typescript
+import { Duck, DuckBugProvider, registerNodeGlobalErrorHandlers } from '@duckbug/js';
+
+const duck = new Duck([DuckBugProvider.fromDSN(dsn)]);
+const unregister = registerNodeGlobalErrorHandlers({ duck });
+// ... on shutdown: unregister();
+```
 
 ### Log Provider Configuration
 
@@ -116,62 +291,54 @@ type LogProviderConfig = {
 
 ## Custom Providers
 
-You can create custom providers by implementing the `Provider` interface:
+Implement `Provider`: handle canonical `DuckBugLogEvent` / `DuckBugErrorEvent` from `sendLog` / `sendError` (optional second argument `SendEventMeta` when events are already finalized in `DuckSDK`), and optional console-style methods for `LogProvider` hooks.
 
 ```typescript
-import { Provider, LogLevel } from '@duckbug/js';
+import type {
+  DuckBugErrorEvent,
+  DuckBugLogEvent,
+  Provider,
+} from '@duckbug/js';
 
 class TelegramProvider implements Provider {
   constructor(private botToken: string, private chatId: string) {}
 
-  log(...args: unknown[]): void {
-    this.sendToTelegram('📝', args);
+  sendLog(event: DuckBugLogEvent): void {
+    this.sendToTelegram('📝', `${event.level} ${event.message}`);
   }
 
-  warn(...args: unknown[]): void {
-    this.sendToTelegram('⚠️', args);
+  sendError(event: DuckBugErrorEvent): void {
+    this.sendToTelegram('💀', event.message);
   }
 
-  error(...args: unknown[]): void {
-    this.sendToTelegram('🚨', args);
+  log(...args: unknown[]): void {
+    this.sendToTelegram('📝', String(args[0]));
   }
 
-  report(tag: string, level: LogLevel, payload?: object): void {
-    const emojiMap: Record<LogLevel, string> = {
-      INFO: '📝',
-      DEBUG: '🦆',
-      WARN: '⚠️',
-      ERROR: '🚨',
-      FATAL: '💀',
-    };
-    this.sendToTelegram(emojiMap[level], [tag, payload]);
+  warn(...args: unknown[]): void {
+    this.sendToTelegram('⚠️', String(args[0]));
   }
 
-  quack(tag: string, error: Error): void {
-    this.sendToTelegram('💀', [tag, error.message]);
+  error(...args: unknown[]): void {
+    this.sendToTelegram('🚨', String(args[0]));
   }
 
-  private sendToTelegram(emoji: string, args: unknown[]) {
-    const message = `${emoji} ${args.join(' ')}`;
-    // Implementation to send message to Telegram
+  private sendToTelegram(emoji: string, text: string) {
+    const message = `${emoji} ${text}`;
     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
-      })
+      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')
+  DuckBugProvider.fromDSN('https://api.duckbug.io/ingest/project:key'),
+  new TelegramProvider('your-bot-token', 'your-chat-id'),
 ];
 
-const duck = new DuckSDK(providers);
+const duck = new Duck(providers);
 ```
 
 ## Development
@@ -181,7 +348,7 @@ const duck = new DuckSDK(providers);
 Install dependencies:
 
 ```bash
-yarn install
+bun install
 ```
 
 ### Build
@@ -189,7 +356,7 @@ yarn install
 Build the library:
 
 ```bash
-yarn build
+bun run build
 ```
 
 ### Linting
@@ -197,15 +364,140 @@ yarn build
 Run linting:
 
 ```bash
-yarn lint
+bun run lint
+```
+
+### Commit Messages
+
+Этот проект использует [Conventional Commits](https://www.conventionalcommits.org/) для стандартизации сообщений коммитов. Все коммиты должны соответствовать следующему формату:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+#### Типы коммитов (обязательные)
+
+- `feat`: Новая функциональность
+- `fix`: Исправление бага
+- `docs`: Изменения в документации
+- `style`: Форматирование кода (не влияет на выполнение кода)
+- `refactor`: Рефакторинг кода
+- `perf`: Улучшение производительности
+- `test`: Добавление или изменение тестов
+- `build`: Изменения в системе сборки или внешних зависимостях
+- `ci`: Изменения в CI конфигурации
+- `chore`: Обновление задач сборки, настроек и т.д.
+- `revert`: Откат предыдущего коммита
+
+#### Примеры корректных коммитов
+
+```bash
+feat: добавить поддержку логирования ошибок
+fix: исправить утечку памяти в DuckBugProvider
+docs: обновить README с примерами использования
+test: добавить тесты для DuckSDK
+refactor: улучшить структуру классов провайдеров
+```
+
+#### Проверка коммитов
+
+Автоматическая проверка формата коммитов выполняется через git hook. При создании коммита с неправильным форматом вы получите подробное сообщение об ошибке с описанием проблемы и примерами правильного формата.
+
+**Примеры ошибок:**
+
+❌ Если забыли указать тип:
+```
+❌ Тип коммита обязателен!
+📝 Формат коммита: <type>: <описание>
+💡 Примеры:
+   feat: добавить новую функцию
+   fix: исправить обработку ошибок
+```
+
+❌ Если использовали неправильный тип:
 ```
+❌ Неверный тип коммита!
+✅ Используйте один из допустимых типов:
+   - feat: новая функциональность
+   - fix: исправление бага
+   ...
+```
+
+Для ручной проверки сообщения коммита:
+
+```bash
+bun run commitlint -- --from HEAD~1 --to HEAD
+```
+
+### Автоматические релизы
+
+Этот проект использует [semantic-release](https://github.com/semantic-release/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
+
+#### Примеры коммитов для релизов:
+
+```bash
+# Патч релиз (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:
 
 ```typescript
-import type { Provider, DuckConfig, LogLevel } from '@duckbug/js';
+import type {
+  Provider,
+  DuckBugConfig,
+  DuckBugLogEvent,
+  LogLevel,
+} from "@duckbug/js";
 ```
 
 ## Browser Compatibility

package/dist/cjs/DuckBug/DuckBugHelper.cjs

@@ -0,0 +1,136 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    processError: ()=>processError,
+    parseError: ()=>parseError
+});
+const external_sdkIdentity_cjs_namespaceObject = require("../sdkIdentity.cjs");
+function tryJsonObjectFromMessage(message) {
+    const trimmed = message.trim();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return null;
+    try {
+        const v = JSON.parse(message);
+        if (null !== v && "object" == typeof v) return v;
+    } catch  {}
+    return null;
+}
+function parseStacktrace(stack) {
+    let file = "unknown";
+    let line = 0;
+    let stacktrace;
+    if (stack) {
+        const stackLines = stack.split("\n");
+        let firstStackLineWithFile = null;
+        for(let i = 1; i < stackLines.length; i++){
+            const lineStr = stackLines[i];
+            if (-1 !== lineStr.indexOf("at ") && (-1 !== lineStr.indexOf(":") || -1 !== lineStr.indexOf("("))) {
+                firstStackLineWithFile = lineStr;
+                break;
+            }
+        }
+        if (firstStackLineWithFile) {
+            const match = firstStackLineWithFile.match(/\(([^)]+):(\d+):(\d+)\)/) || firstStackLineWithFile.match(/at\s+.*?\(([^)]+):(\d+):(\d+)\)/) || firstStackLineWithFile.match(/([^:()\s]+):(\d+):(\d+)/);
+            if (match?.[1]) {
+                file = match[1].replace(/^file:\/\//, "").replace(/^\/+/, "");
+                line = parseInt(match[2] || "0", 10);
+            }
+        }
+        stacktrace = {
+            raw: stack,
+            frames: stackLines.filter((lineStr)=>lineStr.trim()).map((lineStr, index)=>({
+                    index,
+                    content: lineStr.trim()
+                }))
+        };
+    } else {
+        stacktrace = {
+            raw: "",
+            frames: []
+        };
+        file = "unknown";
+        line = 0;
+    }
+    return {
+        file,
+        line,
+        stacktrace
+    };
+}
+function parseContext(contextStr) {
+    if (!contextStr) return null;
+    try {
+        return JSON.parse(contextStr);
+    } catch  {
+        return {
+            message: contextStr
+        };
+    }
+}
+function parseError(error) {
+    const { file, line, stacktrace } = parseStacktrace(error.stack);
+    const context = parseContext(error.message);
+    return {
+        file,
+        line,
+        stacktrace,
+        context
+    };
+}
+function processError(error, tag, time) {
+    const parsed = parseError(error);
+    const message = "string" == typeof error.message && error.message.length > 0 ? error.message : "Error";
+    const event = {
+        time,
+        message,
+        stacktrace: parsed.stacktrace,
+        stacktraceAsString: error.stack ?? "",
+        file: parsed.file,
+        line: parsed.line,
+        exception: {
+            type: error.name,
+            message: error.message
+        },
+        platform: "node",
+        sdk: {
+            ...external_sdkIdentity_cjs_namespaceObject.SDK_IDENTITY
+        }
+    };
+    if (tag.length > 0) event.dTags = [
+        tag
+    ];
+    const fromJson = tryJsonObjectFromMessage(error.message);
+    if (fromJson) event.extra = fromJson;
+    return event;
+}
+exports.parseError = __webpack_exports__.parseError;
+exports.processError = __webpack_exports__.processError;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "parseError",
+    "processError"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});