@duckbug/js 0.1.3 → 1.0.0

package/dist/types/DuckBug/Pond.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Branded context-enrichment surface (duckbug-sdk-spec).
+ * Use {@link Pond.ripple} to capture extra sensitive field names for client-side scrubbing.
+ */
+export declare const Pond: {
+    ripple(extraSensitiveKeys?: string[]): {
+        extraSensitiveKeys: string[];
+    };
+};

package/dist/types/DuckBug/ensureEventId.d.ts

@@ -0,0 +1,4 @@
+/** Assigns a stable UUID when missing (idempotency / retries). */
+export declare function ensureEventId<E extends {
+    eventId?: string;
+}>(event: E): E;

package/dist/types/DuckBug/finalizeIngestEvent.d.ts

@@ -0,0 +1,11 @@
+import type { DuckBugErrorEvent, DuckBugLogEvent } from "../contract";
+import { type StrippableIngestSection } from "./stripIngestSections";
+export type FinalizeIngestOptions = {
+    extraSensitiveKeys?: string[];
+    stripSections?: StrippableIngestSection[];
+};
+/**
+ * default sdk → strip → sanitize → eventId (duckbug-sdk-spec pipeline before beforeSend).
+ */
+export declare function finalizeIngestEvent(event: DuckBugLogEvent, options?: FinalizeIngestOptions): DuckBugLogEvent;
+export declare function finalizeIngestEvent(event: DuckBugErrorEvent, options?: FinalizeIngestOptions): DuckBugErrorEvent;

package/dist/types/DuckBug/index.d.ts

@@ -1,2 +1,8 @@
-export type { DuckBugConfig } from "./DuckBugConfig";
+export type { BeforeSendIngestArg, BeforeSendIngestResult, DuckBugConfig, DuckBugTransportConfig, } from "./DuckBugConfig";
 export { DuckBugProvider } from "./DuckBugProvider";
+export { ensureEventId } from "./ensureEventId";
+export type { FinalizeIngestOptions } from "./finalizeIngestEvent";
+export { finalizeIngestEvent } from "./finalizeIngestEvent";
+export { Pond } from "./Pond";
+export { type StrippableIngestSection, stripIngestSections, } from "./stripIngestSections";
+export type { TransportFailureInfo } from "./transportTypes";

package/dist/types/DuckBug/parseDuckBugDsn.d.ts

@@ -0,0 +1,17 @@
+export type ParsedIngestDsn = {
+    origin: string;
+    /** `/ingest` or `/api/ingest` (path only, no trailing slash). */
+    ingestPathPrefix: string;
+    projectId: string;
+    key: string;
+};
+/**
+ * Parses a DuckBug ingest DSN: `{origin}/ingest/{projectId}:{publicKey}` or
+ * `{origin}/api/ingest/{projectId}:{publicKey}`.
+ * @see duckbug-sdk-spec docs/03-privacy-and-delivery.md
+ */
+export declare function parseDuckBugIngestDsn(dsn: string): ParsedIngestDsn;
+export declare function ingestLogsUrl(parsed: ParsedIngestDsn): string;
+export declare function ingestErrorsUrl(parsed: ParsedIngestDsn): string;
+export declare function ingestLogsBatchUrl(parsed: ParsedIngestDsn): string;
+export declare function ingestErrorsBatchUrl(parsed: ParsedIngestDsn): string;

package/dist/types/DuckBug/sanitizeIngestPayload.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Deep-clones ingest-ready JSON and masks known sensitive keys (SDK-side best-effort).
+ */
+export declare function sanitizeIngestPayload<T>(payload: T, extraSensitiveKeys?: string[]): T;

package/dist/types/DuckBug/stripIngestSections.d.ts

@@ -0,0 +1,4 @@
+import type { DuckBugErrorEvent, DuckBugLogEvent } from "../contract";
+/** Top-level ingest fields that may be omitted before send (duckbug-sdk-spec privacy). */
+export type StrippableIngestSection = "ip" | "url" | "method" | "headers" | "queryParams" | "bodyParams" | "cookies" | "session" | "files" | "env";
+export declare function stripIngestSections<E extends DuckBugLogEvent | DuckBugErrorEvent>(event: E, sections: StrippableIngestSection[] | undefined): E;

package/dist/types/DuckBug/transportTypes.d.ts

@@ -0,0 +1,7 @@
+export type TransportFailureInfo = {
+    kind: "log" | "error";
+    itemCount: number;
+    attempts: number;
+    error: unknown;
+    message: string;
+};

package/dist/types/SDK/DuckSDK.d.ts

@@ -1,12 +1,39 @@
-import type { LogProviderConfig, Provider } from ".";
+import type { IngestSharedMetadata } from "../contract";
+import type { BeforeSendIngestArg, BeforeSendIngestResult } from "../DuckBug/DuckBugConfig";
+import type { StrippableIngestSection } from "../DuckBug/stripIngestSections";
+import type { LogProviderConfig } from "./LogProviderConfig";
+import type { Provider } from "./Provider";
+export type DuckSDKOptions = {
+    beforeSend?: (arg: BeforeSendIngestArg) => BeforeSendIngestResult | Promise<BeforeSendIngestResult>;
+    extraSensitiveKeys?: string[];
+    stripSections?: StrippableIngestSection[];
+};
 export declare class DuckSDK {
     private providers;
-    constructor(providers: Array<Provider>, logProviderConfig?: LogProviderConfig);
+    private scope;
+    private readonly beforeSendHook?;
+    private readonly extraSensitiveKeys?;
+    private readonly stripSections?;
+    constructor(providers: Array<Provider>, logProviderConfig?: LogProviderConfig, options?: DuckSDKOptions);
+    /** Merge default scope metadata into every captured event. */
+    setScope(scope: Partial<IngestSharedMetadata>): void;
+    /**
+     * Wait until queued ingest work finishes for providers that expose `flush`
+     * (e.g. {@link DuckBugProvider}).
+     */
+    flush(): Promise<void>;
     log(tag: string, payload?: object): void;
     error(tag: string, payload?: object): void;
     debug(tag: string, payload?: object): void;
     warn(tag: string, payload?: object): void;
     fatal(tag: string, payload?: object): void;
     quack(tag: string, error: Error): void;
-    private sendReportToPlugins;
+    private normalizeBeforeSendLog;
+    private normalizeBeforeSendError;
+    private emitLog;
+    private mergeScope;
+}
+/** Branded facade per duckbug-sdk-spec naming doctrine. */
+export declare class Duck extends DuckSDK {
+    captureException(error: Error, tag?: string): void;
 }

package/dist/types/SDK/Provider.d.ts

@@ -1,8 +1,16 @@
-import type { LogLevel } from "./LogLevel";
+import type { DuckBugErrorEvent, DuckBugLogEvent } from "../contract";
+/** When set by {@link DuckSDK}, the event already passed finalize + beforeSend in core. */
+export type SendEventMeta = {
+    skipPrivacyPipeline?: boolean;
+};
+/**
+ * Pluggable destination for canonical DuckBug ingest events.
+ * Console-style methods exist for {@link LogProvider} hooks only.
+ */
 export interface Provider {
+    sendLog(event: DuckBugLogEvent, meta?: SendEventMeta): void | Promise<void>;
+    sendError(event: DuckBugErrorEvent, meta?: SendEventMeta): void | Promise<void>;
     log(...args: unknown[]): void;
     warn(...args: unknown[]): void;
     error(...args: unknown[]): void;
-    report(tag: string, level: LogLevel, payload?: object): void;
-    quack(tag: string, error: Error): void;
 }

package/dist/types/SDK/index.d.ts

@@ -1,5 +1,6 @@
-export type { Provider } from "../SDK/Provider";
-export { DuckSDK } from "./DuckSDK";
+export type { Provider, SendEventMeta } from "../SDK/Provider";
+export type { DuckSDKOptions } from "./DuckSDK";
+export { Duck, DuckSDK } from "./DuckSDK";
 export type { LogLevel } from "./LogLevel";
 export { logLevel } from "./LogLevel";
 export { LogProvider } from "./LogProvider";

package/dist/types/contract/index.d.ts

@@ -0,0 +1 @@
+export type { DuckBugErrorEvent, DuckBugLogEvent, IngestJsonValue, IngestSharedMetadata, IngestStringMap, } from "./ingestEvents";

package/dist/types/contract/ingestEvents.d.ts

@@ -0,0 +1,58 @@
+import type { LogLevel } from "../SDK/LogLevel";
+/** JSON values allowed by DuckBug ingest schemas for open fields. */
+export type IngestJsonValue = string | number | boolean | null | {
+    [key: string]: IngestJsonValue;
+} | IngestJsonValue[];
+/** Request-related maps after privacy filtering (schema: object with arbitrary keys). */
+export type IngestStringMap = Record<string, unknown>;
+/** Shared optional fields from docs/02-error-log-contract.md */
+export type IngestSharedMetadata = {
+    eventId?: string;
+    fingerprint?: string;
+    dTags?: string[];
+    context?: IngestJsonValue;
+    ip?: string;
+    url?: string;
+    method?: string;
+    headers?: IngestStringMap;
+    queryParams?: IngestStringMap;
+    bodyParams?: IngestStringMap;
+    cookies?: IngestStringMap;
+    /** Session map; duckbug.io ingest currently rejects top-level `session` (400). Prefer `context` / `extra`. */
+    session?: IngestStringMap;
+    files?: IngestStringMap;
+    env?: IngestStringMap;
+    platform?: string;
+    release?: string;
+    environment?: string;
+    dist?: string;
+    serverName?: string;
+    service?: string;
+    requestId?: string;
+    transaction?: string;
+    traceId?: string;
+    spanId?: string;
+    sdk?: IngestJsonValue;
+    user?: IngestJsonValue;
+    runtime?: IngestJsonValue;
+    breadcrumbs?: IngestJsonValue;
+    extra?: IngestJsonValue;
+};
+/** Canonical DuckBug error event (wire contract). */
+export type DuckBugErrorEvent = IngestSharedMetadata & {
+    time: number;
+    message: string;
+    stacktrace: IngestJsonValue;
+    file: string;
+    line: number;
+    exception?: IngestJsonValue;
+    stacktraceAsString?: string;
+    handled?: boolean;
+    mechanism?: string;
+};
+/** Canonical DuckBug log event (wire contract). */
+export type DuckBugLogEvent = IngestSharedMetadata & {
+    time: number;
+    level: LogLevel;
+    message: string;
+};

package/dist/types/index.d.ts

@@ -1,2 +1,4 @@
+export * from "./contract";
 export * from "./DuckBug";
+export * from "./integrations/node";
 export * from "./SDK";

package/dist/types/integrations/node.d.ts

@@ -0,0 +1,12 @@
+import type { DuckSDK } from "../SDK/DuckSDK";
+export type NodeGlobalErrorIntegrationOptions = {
+    duck: DuckSDK;
+    /** Tag passed to `quack` for unhandled errors. Default `"unhandledRejection"` / `"uncaughtException"`. */
+    rejectionTag?: string;
+    exceptionTag?: string;
+};
+/**
+ * Registers one-shot handlers for `unhandledRejection` and `uncaughtException`.
+ * Core stays framework-free; opt in via this helper.
+ */
+export declare function registerNodeGlobalErrorHandlers(options: NodeGlobalErrorIntegrationOptions): () => void;

package/dist/types/sdkIdentity.d.ts

@@ -0,0 +1,7 @@
+/** Keep in sync with package.json version when releasing. */
+export declare const SDK_NAME: "@duckbug/js";
+export declare const SDK_VERSION: "0.1.3";
+export declare const SDK_IDENTITY: {
+    readonly name: "@duckbug/js";
+    readonly version: "0.1.3";
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckbug/js",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",
@@ -19,23 +19,39 @@
   },
   "files": [
     "dist",
+    "schemas",
     "README.md"
   ],
   "scripts": {
     "build": "rslib build",
-    "lint": "yarn biome ci",
+    "check": "bun run lint && bun run typecheck && bun test",
+    "lint": "bunx biome ci",
     "prepare": "husky",
-    "test": "vitest run",
-    "publish": "yarn build && npm publish"
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test:live-ingest": "DUCKBUG_EXPECT_LIVE_INGEST=1 bun test --env-file=.env ./tests/duckbugLiveIngestEnv.ingest.ts",
+    "semantic-release": "semantic-release",
+    "commitlint": "commitlint --edit"
   },
   "devDependencies": {
     "@biomejs/biome": "2.1.1",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
     "@rslib/core": "0.10.6",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "@types/bun": "latest",
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
     "husky": "9.1.7",
     "pinst": "3.0.0",
+    "semantic-release": "^24.0.0",
     "ts-node": "10.9.2",
-    "typescript": "5.8.3",
-    "vitest": "^3.2.4"
+    "typescript": "5.8.3"
   },
-  "packageManager": "yarn@3.8.7"
+  "packageManager": "bun@latest"
 }

package/schemas/error-event.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://duckbug.io/schemas/error-event.schema.json",
+  "title": "DuckBug Error Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["time", "message", "stacktrace", "file", "line"],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "fingerprint": {
+      "type": "string",
+      "minLength": 1
+    },
+    "time": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1
+    },
+    "exception": {
+      "description": "Any structured JSON representation of the exception.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "stacktrace": {
+      "description": "Any structured JSON representation of frames.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "stacktraceAsString": {
+      "type": "string"
+    },
+    "file": {
+      "type": "string",
+      "minLength": 1
+    },
+    "line": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "dTags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "context": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "ip": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "method": {
+      "type": "string"
+    },
+    "headers": {
+      "$ref": "#/$defs/map"
+    },
+    "queryParams": {
+      "$ref": "#/$defs/map"
+    },
+    "bodyParams": {
+      "$ref": "#/$defs/map"
+    },
+    "cookies": {
+      "$ref": "#/$defs/map"
+    },
+    "session": {
+      "$ref": "#/$defs/map"
+    },
+    "files": {
+      "$ref": "#/$defs/map"
+    },
+    "env": {
+      "$ref": "#/$defs/map"
+    },
+    "platform": {
+      "type": "string"
+    },
+    "release": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string"
+    },
+    "dist": {
+      "type": "string"
+    },
+    "serverName": {
+      "type": "string"
+    },
+    "service": {
+      "type": "string"
+    },
+    "requestId": {
+      "type": "string"
+    },
+    "transaction": {
+      "type": "string"
+    },
+    "traceId": {
+      "type": "string"
+    },
+    "spanId": {
+      "type": "string"
+    },
+    "handled": {
+      "type": "boolean"
+    },
+    "mechanism": {
+      "type": "string"
+    },
+    "sdk": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "user": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "runtime": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "breadcrumbs": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "extra": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    }
+  },
+  "$defs": {
+    "map": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/log-event.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://duckbug.io/schemas/log-event.schema.json",
+  "title": "DuckBug Log Event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["time", "level", "message"],
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "fingerprint": {
+      "type": "string",
+      "minLength": 1
+    },
+    "time": {
+      "type": "integer",
+      "minimum": 0
+    },
+    "level": {
+      "type": "string",
+      "enum": ["DEBUG", "INFO", "WARN", "ERROR", "FATAL"]
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1
+    },
+    "dTags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "context": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "ip": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string"
+    },
+    "method": {
+      "type": "string"
+    },
+    "headers": {
+      "$ref": "#/$defs/map"
+    },
+    "queryParams": {
+      "$ref": "#/$defs/map"
+    },
+    "bodyParams": {
+      "$ref": "#/$defs/map"
+    },
+    "cookies": {
+      "$ref": "#/$defs/map"
+    },
+    "session": {
+      "$ref": "#/$defs/map"
+    },
+    "files": {
+      "$ref": "#/$defs/map"
+    },
+    "env": {
+      "$ref": "#/$defs/map"
+    },
+    "platform": {
+      "type": "string"
+    },
+    "release": {
+      "type": "string"
+    },
+    "environment": {
+      "type": "string"
+    },
+    "dist": {
+      "type": "string"
+    },
+    "serverName": {
+      "type": "string"
+    },
+    "service": {
+      "type": "string"
+    },
+    "requestId": {
+      "type": "string"
+    },
+    "transaction": {
+      "type": "string"
+    },
+    "traceId": {
+      "type": "string"
+    },
+    "spanId": {
+      "type": "string"
+    },
+    "sdk": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "user": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "runtime": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "breadcrumbs": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "extra": {
+      "description": "Any JSON value.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    }
+  },
+  "$defs": {
+    "map": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}