@logbrew/sdk 0.1.1 → 0.1.2

package/README.md

@@ -120,7 +120,27 @@ await client.flush(RecordingTransport.alwaysAccept());
 
 The helpers validate the W3C `version-traceId-parentSpanId-traceFlags` shape, reject all-zero trace/span ids, normalize valid ids to lowercase, expose the sampled flag from `traceFlags`, and keep span metadata primitive-only. `createTraceparentHeaders()` returns an explicit outbound carrier with only `traceparent`. The helpers do not install OpenTelemetry or patch HTTP clients; use them when you need explicit interop in code you own.
 
-LogBrew severity categories are `info`, `warning`, `error`, and `critical`. The JavaScript SDK accepts common runtime aliases such as `trace`, `debug`, `warn`, and `fatal` for compatibility, then serializes canonical values before queued events are sent.
+LogBrew severity categories are `info`, `warning`, `error`, and `critical`. The JavaScript SDK accepts common runtime aliases such as `trace`, `debug`, `warn`, and `fatal` for compatibility, then serializes canonical values before queued events are sent. The shared mapping is documented in the [LogBrew severity contract](../../docs/severity-contract.md).
+
+## Event Filtering
+
+Use `eventFilter` when your app needs a last-mile privacy or sampling gate before events enter the in-memory queue. The filter receives a copy of the already validated event, so severity aliases are already canonical and mutations inside the callback do not alter queued payloads. Return `false` to drop an event; return `true` or nothing to keep it.
+
+```js
+const client = LogBrewClient.create({
+  apiKey: "LOGBREW_API_KEY",
+  sdkName: "checkout-api",
+  sdkVersion: "1.0.0",
+  eventFilter(event) {
+    if (event.type === "log" && event.attributes.level === "info") {
+      return false;
+    }
+    return true;
+  }
+});
+```
+
+Prefer removing sensitive values at the source before calling LogBrew. `eventFilter` is intentionally drop-only: it avoids broad mutable event processing, global scopes, and hidden context that can make observability payloads harder to reason about.
 
 ## Agent-Readable Timelines
 

package/index.cjs

@@ -79,13 +79,17 @@ class RecordingTransport {
 }
 
 class LogBrewClient {
-  static create({ apiKey, sdkName, sdkVersion, maxRetries = 2 }) {
+  static create({ apiKey, sdkName, sdkVersion, maxRetries = 2, eventFilter }) {
     requireNonEmpty("apiKey", apiKey);
     requireNonEmpty("sdkName", sdkName);
     requireNonEmpty("sdkVersion", sdkVersion);
+    if (eventFilter !== undefined && typeof eventFilter !== "function") {
+      throw new SdkError("validation_error", "eventFilter must be a function");
+    }
 
     return new LogBrewClient({
       apiKey,
+      eventFilter,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -95,8 +99,9 @@ class LogBrewClient {
     });
   }
 
-  constructor({ apiKey, sdk, maxRetries }) {
+  constructor({ apiKey, sdk, maxRetries, eventFilter }) {
     this.apiKey = apiKey;
+    this.eventFilter = eventFilter;
     this.sdk = sdk;
     this.maxRetries = maxRetries;
     this.events = [];
@@ -161,7 +166,11 @@ class LogBrewClient {
     }
     requireNonEmpty("event id", id);
     requireTimestamp(timestamp);
-    this.events.push({ type: eventType, id, timestamp, attributes });
+    const event = { type: eventType, id, timestamp, attributes };
+    if (this.eventFilter && this.eventFilter(cloneEvent(event)) === false) {
+      return;
+    }
+    this.events.push(event);
   }
 
   async #flushInternal(transport) {
@@ -1004,6 +1013,13 @@ function cloneMetadata(metadata) {
   return { ...metadata };
 }
 
+function cloneEvent(event) {
+  const attributes = event.attributes.metadata === undefined
+    ? { ...event.attributes }
+    : { ...event.attributes, metadata: { ...event.attributes.metadata } };
+  return { ...event, attributes };
+}
+
 function validateRelease(attributes) {
   requireNonEmpty("release version", attributes.version);
   if (attributes.commit !== undefined) {

package/index.d.cts

@@ -241,6 +241,9 @@ export type Event =
   | { type: "action"; id: string; timestamp: string; attributes: ActionAttributes }
   | { type: "metric"; id: string; timestamp: string; attributes: MetricAttributes };
 
+/** Drop-only event filter called after validation and before an event is queued. */
+export type EventFilter = (event: Event) => boolean | void;
+
 /** Stable transport response returned from flush and shutdown operations. */
 export type TransportResponse = {
   /** Final HTTP-like status returned by the transport. */
@@ -289,6 +292,7 @@ export declare class LogBrewClient {
     sdkName: string;
     sdkVersion: string;
     maxRetries?: number;
+    eventFilter?: EventFilter;
   }): LogBrewClient;
   /** Return the queued event count currently buffered in memory. */
   pendingEvents(): number;

package/index.d.ts

@@ -241,6 +241,9 @@ export type Event =
   | { type: "action"; id: string; timestamp: string; attributes: ActionAttributes }
   | { type: "metric"; id: string; timestamp: string; attributes: MetricAttributes };
 
+/** Drop-only event filter called after validation and before an event is queued. */
+export type EventFilter = (event: Event) => boolean | void;
+
 /** Stable transport response returned from flush and shutdown operations. */
 export type TransportResponse = {
   /** Final HTTP-like status returned by the transport. */
@@ -289,6 +292,7 @@ export declare class LogBrewClient {
     sdkName: string;
     sdkVersion: string;
     maxRetries?: number;
+    eventFilter?: EventFilter;
   }): LogBrewClient;
   /** Return the queued event count currently buffered in memory. */
   pendingEvents(): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",