@duckbug/js 1.0.0 → 1.1.1

package/README.md

@@ -63,6 +63,23 @@ duck.warn('Slow query', { ms: 1200 });
 
 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.

package/dist/cjs/SDK/DuckSDK.cjs

@@ -30,6 +30,7 @@ __webpack_require__.d(__webpack_exports__, {
 const DuckBugHelper_cjs_namespaceObject = require("../DuckBug/DuckBugHelper.cjs");
 const finalizeIngestEvent_cjs_namespaceObject = require("../DuckBug/finalizeIngestEvent.cjs");
 const external_sdkIdentity_cjs_namespaceObject = require("../sdkIdentity.cjs");
+const external_duckLogPayload_cjs_namespaceObject = require("./duckLogPayload.cjs");
 const external_LogLevel_cjs_namespaceObject = require("./LogLevel.cjs");
 const external_LogProvider_cjs_namespaceObject = require("./LogProvider.cjs");
 function isPromiseLike(v) {
@@ -118,16 +119,26 @@ class DuckSDK {
         return out;
     }
     emitLog(level, message, payload) {
+        const { scopePatch, context, dTags } = (0, external_duckLogPayload_cjs_namespaceObject.parseDuckLogPayload)(payload);
+        const platform = void 0 !== scopePatch.platform && "string" == typeof scopePatch.platform ? scopePatch.platform : "node";
+        const scopeForSpread = {
+            ...scopePatch
+        };
+        delete scopeForSpread.platform;
         const event = this.mergeScope({
+            ...scopeForSpread,
             time: Date.now(),
             level,
             message,
-            platform: "node",
+            platform,
             sdk: {
                 ...external_sdkIdentity_cjs_namespaceObject.SDK_IDENTITY
             },
-            ...void 0 !== payload ? {
-                context: payload
+            ...void 0 !== dTags ? {
+                dTags
+            } : {},
+            ...void 0 !== context ? {
+                context
             } : {}
         });
         const finalized = (0, finalizeIngestEvent_cjs_namespaceObject.finalizeIngestEvent)(event, {

package/dist/cjs/SDK/duckLogPayload.cjs

@@ -0,0 +1,86 @@
+"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__, {
+    parseDuckLogPayload: ()=>parseDuckLogPayload
+});
+const EMIT_OWNED = [
+    "time",
+    "level",
+    "message",
+    "sdk"
+];
+function parseDuckLogPayload(payload) {
+    if (void 0 === payload) return {
+        scopePatch: {},
+        context: void 0,
+        dTags: void 0
+    };
+    if (null === payload || Array.isArray(payload) || "object" != typeof payload) return {
+        scopePatch: {},
+        context: payload,
+        dTags: void 0
+    };
+    const rec = {
+        ...payload
+    };
+    const rawDuck = rec._duck;
+    delete rec._duck;
+    let reserved;
+    if (null !== rawDuck && "object" == typeof rawDuck && !Array.isArray(rawDuck)) reserved = rawDuck;
+    const hasRest = Object.keys(rec).length > 0;
+    const restContext = hasRest ? rec : void 0;
+    let scopeContext;
+    let scopePatch = {};
+    const inner = reserved?.scope;
+    if (void 0 !== inner && "object" == typeof inner && !Array.isArray(inner)) {
+        const s = inner;
+        scopeContext = s.context;
+        const { context: _c, ...restScope } = s;
+        scopePatch = {
+            ...restScope
+        };
+    }
+    for (const k of EMIT_OWNED)delete scopePatch[k];
+    let context;
+    if (hasRest) context = restContext;
+    else if (void 0 !== scopeContext) context = scopeContext;
+    let dTags;
+    if (reserved?.dTags !== void 0) dTags = reserved.dTags;
+    else if (void 0 !== scopePatch.dTags) dTags = scopePatch.dTags;
+    const { dTags: _scopeDtags, ...scopePatchNoDtags } = scopePatch;
+    return {
+        scopePatch: scopePatchNoDtags,
+        context,
+        dTags
+    };
+}
+exports.parseDuckLogPayload = __webpack_exports__.parseDuckLogPayload;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "parseDuckLogPayload"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/esm/SDK/DuckSDK.js

@@ -1,6 +1,7 @@
 import { processError } from "../DuckBug/DuckBugHelper.js";
 import { finalizeIngestEvent } from "../DuckBug/finalizeIngestEvent.js";
 import { SDK_IDENTITY } from "../sdkIdentity.js";
+import { parseDuckLogPayload } from "./duckLogPayload.js";
 import { logLevel } from "./LogLevel.js";
 import { LogProvider } from "./LogProvider.js";
 function isPromiseLike(v) {
@@ -89,16 +90,26 @@ class DuckSDK {
         return out;
     }
     emitLog(level, message, payload) {
+        const { scopePatch, context, dTags } = parseDuckLogPayload(payload);
+        const platform = void 0 !== scopePatch.platform && "string" == typeof scopePatch.platform ? scopePatch.platform : "node";
+        const scopeForSpread = {
+            ...scopePatch
+        };
+        delete scopeForSpread.platform;
         const event = this.mergeScope({
+            ...scopeForSpread,
             time: Date.now(),
             level,
             message,
-            platform: "node",
+            platform,
             sdk: {
                 ...SDK_IDENTITY
             },
-            ...void 0 !== payload ? {
-                context: payload
+            ...void 0 !== dTags ? {
+                dTags
+            } : {},
+            ...void 0 !== context ? {
+                context
             } : {}
         });
         const finalized = finalizeIngestEvent(event, {

package/dist/esm/SDK/duckLogPayload.js

@@ -0,0 +1,52 @@
+const EMIT_OWNED = [
+    "time",
+    "level",
+    "message",
+    "sdk"
+];
+function parseDuckLogPayload(payload) {
+    if (void 0 === payload) return {
+        scopePatch: {},
+        context: void 0,
+        dTags: void 0
+    };
+    if (null === payload || Array.isArray(payload) || "object" != typeof payload) return {
+        scopePatch: {},
+        context: payload,
+        dTags: void 0
+    };
+    const rec = {
+        ...payload
+    };
+    const rawDuck = rec._duck;
+    delete rec._duck;
+    let reserved;
+    if (null !== rawDuck && "object" == typeof rawDuck && !Array.isArray(rawDuck)) reserved = rawDuck;
+    const hasRest = Object.keys(rec).length > 0;
+    const restContext = hasRest ? rec : void 0;
+    let scopeContext;
+    let scopePatch = {};
+    const inner = reserved?.scope;
+    if (void 0 !== inner && "object" == typeof inner && !Array.isArray(inner)) {
+        const s = inner;
+        scopeContext = s.context;
+        const { context: _c, ...restScope } = s;
+        scopePatch = {
+            ...restScope
+        };
+    }
+    for (const k of EMIT_OWNED)delete scopePatch[k];
+    let context;
+    if (hasRest) context = restContext;
+    else if (void 0 !== scopeContext) context = scopeContext;
+    let dTags;
+    if (reserved?.dTags !== void 0) dTags = reserved.dTags;
+    else if (void 0 !== scopePatch.dTags) dTags = scopePatch.dTags;
+    const { dTags: _scopeDtags, ...scopePatchNoDtags } = scopePatch;
+    return {
+        scopePatch: scopePatchNoDtags,
+        context,
+        dTags
+    };
+}
+export { parseDuckLogPayload };

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

@@ -1,6 +1,7 @@
 import type { IngestSharedMetadata } from "../contract";
 import type { BeforeSendIngestArg, BeforeSendIngestResult } from "../DuckBug/DuckBugConfig";
 import type { StrippableIngestSection } from "../DuckBug/stripIngestSections";
+import { type DuckLogPayload } from "./duckLogPayload";
 import type { LogProviderConfig } from "./LogProviderConfig";
 import type { Provider } from "./Provider";
 export type DuckSDKOptions = {
@@ -22,11 +23,11 @@ export declare class DuckSDK {
      * (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;
+    log(tag: string, payload?: DuckLogPayload): void;
+    error(tag: string, payload?: DuckLogPayload): void;
+    debug(tag: string, payload?: DuckLogPayload): void;
+    warn(tag: string, payload?: DuckLogPayload): void;
+    fatal(tag: string, payload?: DuckLogPayload): void;
     quack(tag: string, error: Error): void;
     private normalizeBeforeSendLog;
     private normalizeBeforeSendError;

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

@@ -0,0 +1,23 @@
+import type { IngestJsonValue, IngestSharedMetadata } from "../contract";
+/**
+ * Reserved key on the second argument to `Duck` / `DuckSDK` log methods.
+ * Not sent inside `context` on the wire.
+ */
+export type DuckReservedMeta = {
+    dTags?: string[];
+    /** One-shot metadata merged into this log only (after global `setScope`, before fixed fields). */
+    scope?: Partial<IngestSharedMetadata>;
+};
+export type DuckLogPayload = Record<string, unknown> & {
+    _duck?: DuckReservedMeta;
+};
+/**
+ * Splits the optional second argument into scope-like fields, `dTags`, and `context`.
+ * - Plain object: strips `_duck`, remaining keys become `context` if non-empty.
+ * - Non-plain-object payload: entire value becomes `context` (legacy).
+ */
+export declare function parseDuckLogPayload(payload: object | undefined): {
+    scopePatch: Partial<IngestSharedMetadata>;
+    context: IngestJsonValue | undefined;
+    dTags: string[] | undefined;
+};

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duckbug/js",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "type": "module",
   "main": "./dist/cjs/index.cjs",
   "module": "./dist/esm/index.js",