You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@flagon.apache.org by au...@apache.org on 2026/10/11 15:14:01 UTC

(flagon) branch master updated: feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)

This is an automated email from the ASF dual-hosted git repository.

brucearctor pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/flagon.git


The following commit(s) were added to refs/heads/master by this push:
     new 1b8c34a  feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)
1b8c34a is described below

commit 1b8c34a51328ce0c6984dd5f5a01a2f327be22c8
Author: brucearctor <50...@users.noreply.github.com>
AuthorDate: Sun Oct 11 08:13:56 2026 -0700

    feat(userale): add pluggable LogExporter architecture, unified headers, and ProtoJsonExporter (#133, #139, #142, #143) (#184)
---
 .../packages/flagon-userale/src/configure.ts       |   2 +
 .../flagon-userale/src/exporters/headers.ts        |  54 ++++
 .../flagon-userale/src/exporters/http-json.ts      | 126 ++++++++
 .../packages/flagon-userale/src/exporters/index.ts |  71 +++++
 .../flagon-userale/src/exporters/proto-json.ts     | 219 +++++++++++++
 .../packages/flagon-userale/src/exporters/types.ts |  40 +++
 .../flagon-userale/src/exporters/websocket.ts      |  48 +++
 .../flagon-userale/src/getInitialSettings.ts       |   7 +
 .../userale/packages/flagon-userale/src/main.ts    |  15 +
 .../packages/flagon-userale/src/sendLogs.ts        | 155 +++------
 .../userale/packages/flagon-userale/src/types.d.ts |  14 +-
 .../flagon-userale/test/spec/exporters.spec.ts     | 349 +++++++++++++++++++++
 .../flagon-userale/test/spec/sendLogs.spec.ts      |  41 ++-
 13 files changed, 1034 insertions(+), 107 deletions(-)

diff --git a/products/userale/packages/flagon-userale/src/configure.ts b/products/userale/packages/flagon-userale/src/configure.ts
index 6e42776..0261521 100644
--- a/products/userale/packages/flagon-userale/src/configure.ts
+++ b/products/userale/packages/flagon-userale/src/configure.ts
@@ -30,6 +30,8 @@ export class Configuration {
   public authHeader: Settings.AuthHeader = null;
   public browserSessionId: Settings.SessionId = null;
   public custIndex: Settings.CustomIndex = null;
+  public exporter: Settings.CustomExporter = null;
+  public exporterType: Settings.ExporterType = "http-json";
   public headers: Settings.Headers = null;
   public httpSessionId: Settings.SessionId = null;
   public logCountThreshold: number = 0;
diff --git a/products/userale/packages/flagon-userale/src/exporters/headers.ts b/products/userale/packages/flagon-userale/src/exporters/headers.ts
new file mode 100644
index 0000000..a1443b2
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/headers.ts
@@ -0,0 +1,54 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import { updateAuthHeader, updateCustomHeaders } from "@/utils";
+
+/**
+ * Builds the HTTP headers for outgoing log requests, unifying
+ * Authorization (static or callback), x-api-key, and custom headers.
+ * @param  {Configuration} config Configuration singleton.
+ * @return {Headers}              Constructed Fetch Headers instance.
+ */
+export function buildHeaders(config: Configuration): Headers {
+  const headers = new Headers({
+    "Content-Type": "application/json;charset=UTF-8",
+  });
+
+  updateAuthHeader(config);
+  if (config.authHeader) {
+    const authHeaderValue =
+      typeof config.authHeader === "function"
+        ? config.authHeader()
+        : String(config.authHeader);
+    headers.set("Authorization", authHeaderValue);
+  }
+
+  if (config.apiKey) {
+    headers.set("x-api-key", config.apiKey);
+  }
+
+  // Update custom headers last to allow them to over-write the defaults.
+  updateCustomHeaders(config);
+  if (config.headers) {
+    for (const [header, value] of Object.entries(config.headers)) {
+      headers.set(header, value);
+    }
+  }
+
+  return headers;
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/http-json.ts b/products/userale/packages/flagon-userale/src/exporters/http-json.ts
new file mode 100644
index 0000000..79379e4
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/http-json.ts
@@ -0,0 +1,126 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import type { Logging } from "@/types";
+import { buildHeaders } from "./headers";
+import type { ExportOptions, ExportResult, LogExporter } from "./types";
+
+const MAX_KEEPALIVE_BYTES = 48 * 1024;
+
+/**
+ * Splits a log array into sub-batches whose serialized JSON size stays under
+ * MAX_KEEPALIVE_BYTES so browser pagehide/keepalive requests do not reject.
+ */
+export function chunkLogsForKeepalive<T>(
+  logs: Array<T>,
+  serialize: (batch: Array<T>) => string,
+): Array<string> {
+  const full = serialize(logs);
+  if (full.length <= MAX_KEEPALIVE_BYTES || logs.length <= 1) {
+    return [full];
+  }
+  const mid = Math.ceil(logs.length / 2);
+  return [
+    ...chunkLogsForKeepalive(logs.slice(0, mid), serialize),
+    ...chunkLogsForKeepalive(logs.slice(mid), serialize),
+  ];
+}
+
+export class HttpJsonExporter implements LogExporter {
+  private config: Configuration;
+
+  constructor(config: Configuration) {
+    this.config = config;
+  }
+
+  protected serialize(logs: Array<Logging.Log>): string {
+    return JSON.stringify(logs);
+  }
+
+  protected getEndpoint(): string {
+    return this.config.url;
+  }
+
+  public async export(
+    logs: Array<Logging.Log>,
+    options?: ExportOptions,
+  ): Promise<ExportResult> {
+    const headers = buildHeaders(this.config);
+    const endpoint = this.getEndpoint();
+    const keepalive = Boolean(options?.keepalive);
+    const retries = options?.retries ?? 0;
+
+    if (keepalive) {
+      const payloads = chunkLogsForKeepalive(logs, (batch) =>
+        this.serialize(batch),
+      );
+      try {
+        await Promise.all(
+          payloads.map((body) =>
+            fetch(endpoint, {
+              keepalive: true,
+              method: "POST",
+              headers,
+              body,
+            }),
+          ),
+        );
+        return { success: true };
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        console.error(error);
+        return { success: false, error };
+      }
+    }
+
+    const body = this.serialize(logs);
+
+    async function attemptSend(remainingRetries: number): Promise<void> {
+      try {
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers,
+          body,
+        });
+
+        if (!response.ok) {
+          if (remainingRetries > 0) {
+            return attemptSend(remainingRetries - 1);
+          }
+          throw new Error(`Failed to send logs: ${response.statusText}`);
+        }
+      } catch (error) {
+        if (remainingRetries > 0) {
+          return attemptSend(remainingRetries - 1);
+        }
+        throw error;
+      }
+    }
+
+    await attemptSend(retries);
+    return { success: true };
+  }
+
+  public async flush(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async shutdown(): Promise<void> {
+    return Promise.resolve();
+  }
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/index.ts b/products/userale/packages/flagon-userale/src/exporters/index.ts
new file mode 100644
index 0000000..c0721ac
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/index.ts
@@ -0,0 +1,71 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import { buildHeaders } from "./headers";
+import { HttpJsonExporter, chunkLogsForKeepalive } from "./http-json";
+import {
+  ProtoJsonExporter,
+  toProtoLogBatch,
+  toProtoUserALELog,
+} from "./proto-json";
+import type {
+  ExportOptions,
+  ExportResult,
+  ExporterType,
+  LogExporter,
+} from "./types";
+import { WebSocketExporter } from "./websocket";
+
+export {
+  buildHeaders,
+  chunkLogsForKeepalive,
+  HttpJsonExporter,
+  ProtoJsonExporter,
+  toProtoLogBatch,
+  toProtoUserALELog,
+  WebSocketExporter,
+};
+export type { ExportOptions, ExportResult, ExporterType, LogExporter };
+
+/**
+ * Factory that creates the appropriate LogExporter for the given configuration.
+ */
+export function createExporter(config: Configuration): LogExporter {
+  if (config.exporter) {
+    return config.exporter;
+  }
+
+  try {
+    const url = new URL(config.url);
+    if (
+      url.protocol === "ws:" ||
+      url.protocol === "wss:" ||
+      config.exporterType === "websocket"
+    ) {
+      return new WebSocketExporter(config);
+    }
+  } catch {
+    // Fallback to HTTP exporter if config.url is not a full URL (e.g. relative path in tests)
+  }
+
+  if (config.exporterType === "proto-json") {
+    return new ProtoJsonExporter(config);
+  }
+
+  return new HttpJsonExporter(config);
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/proto-json.ts b/products/userale/packages/flagon-userale/src/exporters/proto-json.ts
new file mode 100644
index 0000000..45a31e7
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/proto-json.ts
@@ -0,0 +1,219 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Logging } from "@/types";
+import { HttpJsonExporter } from "./http-json";
+
+const KNOWN_CUSTOM_LOG_KEYS = new Set([
+  "pageUrl",
+  "pageTitle",
+  "pageReferrer",
+  "userAgent",
+  "clientTime",
+  "scrnRes",
+  "logType",
+  "userAction",
+  "details",
+  "userId",
+  "toolVersion",
+  "toolName",
+  "useraleVersion",
+  "sessionId",
+  "httpSessionId",
+  "browserSessionId",
+]);
+
+function buildProtoMetadata(log: Logging.Log): Logging.JSONObject {
+  const scrnRes = log.scrnRes as
+    { width?: number; height?: number } | undefined;
+  const metadata: Logging.JSONObject = {
+    pageUrl: typeof log.pageUrl === "string" ? log.pageUrl : "",
+    pageTitle: typeof log.pageTitle === "string" ? log.pageTitle : "",
+    pageReferrer: typeof log.pageReferrer === "string" ? log.pageReferrer : "",
+    userAgent: typeof log.userAgent === "string" ? log.userAgent : "",
+    clientTime: String(
+      typeof log.clientTime === "number"
+        ? Math.trunc(log.clientTime)
+        : typeof log.startTime === "number"
+          ? Math.trunc(log.startTime)
+          : 0,
+    ),
+  };
+
+  if (scrnRes && typeof scrnRes === "object") {
+    metadata.screenResolution = {
+      width: typeof scrnRes.width === "number" ? Math.trunc(scrnRes.width) : 0,
+      height:
+        typeof scrnRes.height === "number" ? Math.trunc(scrnRes.height) : 0,
+    };
+  }
+
+  if (typeof log.userId === "string") metadata.userId = log.userId;
+  if (typeof log.sessionId === "string") metadata.sessionId = log.sessionId;
+  if (typeof log.httpSessionId === "string")
+    metadata.httpSessionId = log.httpSessionId;
+  if (typeof log.browserSessionId === "string")
+    metadata.browserSessionId = log.browserSessionId;
+  if (typeof log.toolName === "string") metadata.toolName = log.toolName;
+  if (typeof log.toolVersion === "string")
+    metadata.toolVersion = log.toolVersion;
+  if (typeof log.useraleVersion === "string")
+    metadata.useraleVersion = log.useraleVersion;
+
+  return metadata;
+}
+
+function toStringAttributes(
+  attrs: unknown,
+): Record<string, string> | undefined {
+  if (!attrs || typeof attrs !== "object" || Array.isArray(attrs)) {
+    return undefined;
+  }
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    out[k] = typeof v === "string" ? v : JSON.stringify(v);
+  }
+  return out;
+}
+
+/**
+ * Converts a flat UserALE log entry into the proto3 canonical JSON structure
+ * defined by apache.flagon.userale.v1.UserALELog in log.proto (#142, #143).
+ */
+export function toProtoUserALELog(log: Logging.Log): Logging.JSONObject {
+  const metadata = buildProtoMetadata(log);
+  const logType = log.logType;
+
+  if (logType === "raw") {
+    const loc = log.location as
+      { x?: number | null; y?: number | null } | undefined;
+    const location: Logging.JSONObject = {};
+    if (loc && typeof loc === "object") {
+      if (typeof loc.x === "number") location.x = loc.x;
+      if (typeof loc.y === "number") location.y = loc.y;
+    }
+
+    const raw: Logging.JSONObject = {
+      metadata,
+      target: typeof log.target === "string" ? log.target : "",
+      path: Array.isArray(log.path) ? (log.path as string[]) : [],
+      eventType: typeof log.type === "string" ? log.type : "",
+      location,
+      userAction: Boolean(log.userAction),
+    };
+
+    if (typeof log.microTime === "number") {
+      raw.microTime = log.microTime;
+    }
+    if (
+      log.details &&
+      typeof log.details === "object" &&
+      !Array.isArray(log.details)
+    ) {
+      raw.details = log.details as Logging.JSONObject;
+    }
+    const strAttrs = toStringAttributes(log.attributes);
+    if (strAttrs) {
+      raw.attributes = strAttrs;
+    }
+    if (
+      log.style &&
+      typeof log.style === "object" &&
+      !Array.isArray(log.style)
+    ) {
+      raw.style = log.style as Logging.JSONObject;
+    }
+
+    return {
+      logType: "LOG_TYPE_RAW",
+      raw,
+    };
+  }
+
+  if (logType === "interval") {
+    const interval: Logging.JSONObject = {
+      metadata,
+      target: typeof log.target === "string" ? log.target : "",
+      path: Array.isArray(log.path) ? (log.path as string[]) : [],
+      eventType: typeof log.type === "string" ? log.type : "",
+      count: typeof log.count === "number" ? Math.trunc(log.count) : 0,
+      duration: String(
+        typeof log.duration === "number" ? Math.trunc(log.duration) : 0,
+      ),
+      startTime: String(
+        typeof log.startTime === "number" ? Math.trunc(log.startTime) : 0,
+      ),
+      endTime: String(
+        typeof log.endTime === "number" ? Math.trunc(log.endTime) : 0,
+      ),
+      targetChange: Boolean(log.targetChange),
+      typeChange: Boolean(log.typeChange),
+      userAction: Boolean(log.userAction),
+    };
+
+    return {
+      logType: "LOG_TYPE_INTERVAL",
+      interval,
+    };
+  }
+
+  const customFields: Logging.JSONObject = {};
+  for (const [key, value] of Object.entries(log)) {
+    if (!KNOWN_CUSTOM_LOG_KEYS.has(key) && value !== undefined) {
+      customFields[key] = value;
+    }
+  }
+
+  const custom: Logging.JSONObject = {
+    metadata,
+    userAction: Boolean(log.userAction),
+    customFields,
+  };
+
+  if (
+    log.details &&
+    typeof log.details === "object" &&
+    !Array.isArray(log.details)
+  ) {
+    custom.details = log.details as Logging.JSONObject;
+  }
+
+  return {
+    logType: "LOG_TYPE_CUSTOM",
+    custom,
+  };
+}
+
+/**
+ * Converts an array of UserALE logs into an apache.flagon.userale.v1.LogBatch
+ * proto3 JSON object.
+ */
+export function toProtoLogBatch(logs: Array<Logging.Log>): Logging.JSONObject {
+  return {
+    logs: logs.map(toProtoUserALELog),
+  };
+}
+
+/**
+ * Exporter that serializes UserALE logs using the apache.flagon.userale.v1
+ * Protobuf JSON schema (#142, #143) with zero runtime protobuf dependencies.
+ */
+export class ProtoJsonExporter extends HttpJsonExporter {
+  protected override serialize(logs: Array<Logging.Log>): string {
+    return JSON.stringify(toProtoLogBatch(logs));
+  }
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/types.ts b/products/userale/packages/flagon-userale/src/exporters/types.ts
new file mode 100644
index 0000000..5a1ebcb
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/types.ts
@@ -0,0 +1,40 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Logging } from "@/types";
+
+export type ExporterType =
+  "http-json" | "proto-json" | "otlp" | "websocket" | "custom";
+
+export interface ExportOptions {
+  keepalive?: boolean;
+  retries?: number;
+}
+
+export interface ExportResult {
+  success: boolean;
+  error?: Error;
+}
+
+export interface LogExporter {
+  export(
+    logs: Array<Logging.Log>,
+    options?: ExportOptions,
+  ): Promise<ExportResult>;
+  flush?(): Promise<void>;
+  shutdown?(): Promise<void>;
+}
diff --git a/products/userale/packages/flagon-userale/src/exporters/websocket.ts b/products/userale/packages/flagon-userale/src/exporters/websocket.ts
new file mode 100644
index 0000000..6132778
--- /dev/null
+++ b/products/userale/packages/flagon-userale/src/exporters/websocket.ts
@@ -0,0 +1,48 @@
+/*!
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { Configuration } from "@/configure";
+import type { Logging } from "@/types";
+import type { ExportResult, LogExporter } from "./types";
+
+export class WebSocketExporter implements LogExporter {
+  private wsock: WebSocket;
+
+  constructor(config: Configuration) {
+    this.wsock = new WebSocket(config.url);
+  }
+
+  public async export(logs: Array<Logging.Log>): Promise<ExportResult> {
+    const data = JSON.stringify(logs);
+    this.wsock.send(data);
+    return { success: true };
+  }
+
+  public async flush(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public async shutdown(): Promise<void> {
+    if (
+      typeof WebSocket !== "undefined" &&
+      this.wsock.readyState === WebSocket.OPEN
+    ) {
+      this.wsock.close();
+    }
+    return Promise.resolve();
+  }
+}
diff --git a/products/userale/packages/flagon-userale/src/getInitialSettings.ts b/products/userale/packages/flagon-userale/src/getInitialSettings.ts
index 85e3d78..14118db 100644
--- a/products/userale/packages/flagon-userale/src/getInitialSettings.ts
+++ b/products/userale/packages/flagon-userale/src/getInitialSettings.ts
@@ -38,6 +38,8 @@ export function getInitialSettings(): Settings.Config {
       autostart: true,
       browserSessionId: null,
       custIndex: null,
+      exporter: null,
+      exporterType: "http-json",
       headers: null,
       httpSessionId: null,
       logCountThreshold: +5,
@@ -83,12 +85,17 @@ export function getInitialSettings(): Settings.Config {
         return null;
       };
   const headers = get("data-headers");
+  const exporterAttr = (get("data-exporter-type") ||
+    get("data-exporter") ||
+    "http-json") as Settings.ExporterType;
   const settings: Settings.Config = {
     apiKey: get("data-api-key") || null,
     authHeader: get("data-auth") || null,
     autostart: get("data-autostart") === "false" ? false : true,
     browserSessionId: null,
     custIndex: get("data-index") || null,
+    exporter: null,
+    exporterType: exporterAttr,
     headers: headers ? JSON.parse(headers) : null,
     httpSessionId: httpSessionId,
     logCountThreshold: +(get("data-threshold") || 5),
diff --git a/products/userale/packages/flagon-userale/src/main.ts b/products/userale/packages/flagon-userale/src/main.ts
index dae8393..4934776 100644
--- a/products/userale/packages/flagon-userale/src/main.ts
+++ b/products/userale/packages/flagon-userale/src/main.ts
@@ -55,6 +55,21 @@ export {
   getSelector as getSelector,
   buildPath as buildPath,
 } from "@/packageLogs";
+export {
+  buildHeaders,
+  createExporter,
+  HttpJsonExporter,
+  ProtoJsonExporter,
+  toProtoLogBatch,
+  toProtoUserALELog,
+  WebSocketExporter,
+} from "@/exporters";
+export type {
+  ExportOptions,
+  ExportResult,
+  ExporterType,
+  LogExporter,
+} from "@/exporters";
 export type { Logging, Settings } from "@/types";
 
 config.update({
diff --git a/products/userale/packages/flagon-userale/src/sendLogs.ts b/products/userale/packages/flagon-userale/src/sendLogs.ts
index 29cba74..f62b200 100644
--- a/products/userale/packages/flagon-userale/src/sendLogs.ts
+++ b/products/userale/packages/flagon-userale/src/sendLogs.ts
@@ -16,11 +16,30 @@
  */
 
 import { Configuration } from "@/configure";
+import { buildHeaders, createExporter, type LogExporter } from "@/exporters";
 import { Logging } from "@/types";
-import { updateAuthHeader, updateCustomHeaders } from "@/utils";
+
+export { buildHeaders };
 
 let sendIntervalId: string | number | NodeJS.Timeout | undefined;
-let wsock: WebSocket;
+let activeExporter: LogExporter | null = null;
+let activeExporterKey: string | null = null;
+let activeCustomExporter: LogExporter | null = null;
+
+function resolveExporter(config: Configuration): LogExporter {
+  const key = `${config.url}|${config.exporterType ?? "http-json"}`;
+  if (
+    activeExporter &&
+    activeExporterKey === key &&
+    activeCustomExporter === (config.exporter ?? null)
+  ) {
+    return activeExporter;
+  }
+  activeExporter = createExporter(config);
+  activeExporterKey = key;
+  activeCustomExporter = config.exporter ?? null;
+  return activeExporter;
+}
 
 /**
  * Initializes the log queue processors.
@@ -32,20 +51,24 @@ export function initSender(logs: Array<Logging.Log>, config: Configuration) {
     clearInterval(sendIntervalId);
   }
 
-  const url = new URL(config.url);
-  if (
-    (config.apiKey || config.authHeader) &&
-    url.protocol === "http:" &&
-    !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
-  ) {
-    console.warn(
-      "[UserALE] Sending credentials over plaintext HTTP. Use HTTPS in production.",
-    );
-  }
-  if (url.protocol === "ws:" || url.protocol === "wss:") {
-    wsock = new WebSocket(config.url);
+  try {
+    const url = new URL(config.url);
+    if (
+      (config.apiKey || config.authHeader) &&
+      url.protocol === "http:" &&
+      !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+    ) {
+      console.warn(
+        "[UserALE] Sending credentials over plaintext HTTP. Use HTTPS in production.",
+      );
+    }
+  } catch {
+    // Ignore invalid URL during initialization if a custom exporter is used
   }
 
+  activeExporter = null;
+  resolveExporter(config);
+
   sendIntervalId = sendOnInterval(logs, config);
   sendOnClose(logs, config);
 }
@@ -73,11 +96,11 @@ export function sendOnInterval(
   }, config.transmitInterval);
 }
 
-// /**
-//  * Attempts to flush the remaining logs when the window is closed.
-//  * @param  {Array<Logging.Log>} logs   Array of logs to be flushed.
-//  * @param  {Configuration} config Configuration singleton to be read from.
-//  */
+/**
+ * Attempts to flush the remaining logs when the window is closed.
+ * @param  {Array<Logging.Log>} logs   Array of logs to be flushed.
+ * @param  {Configuration} config Configuration singleton to be read from.
+ */
 export function sendOnClose(
   logs: Array<Logging.Log>,
   config: Configuration,
@@ -88,39 +111,18 @@ export function sendOnClose(
     }
 
     if (logs.length > 0) {
-      const url = new URL(config.url);
-
-      if (url.protocol === "ws:" || url.protocol === "wss:") {
-        const data = JSON.stringify(logs);
-        wsock.send(data);
-      } else {
-        const headers: HeadersInit = new Headers();
-        headers.set("Content-Type", "application/json;charset=UTF-8");
-
-        if (config.authHeader) {
-          headers.set("Authorization", config.authHeader.toString());
-        }
-
-        if (config.apiKey) {
-          headers.set("x-api-key", config.apiKey);
-        }
-
-        fetch(config.url, {
-          keepalive: true,
-          method: "POST",
-          headers: headers,
-          body: JSON.stringify(logs),
-        }).catch((error) => {
-          console.error(error);
-        });
-      }
+      const batch = logs.slice(0);
       logs.splice(0); // clear log queue
+      const exporter = resolveExporter(config);
+      exporter.export(batch, { keepalive: true }).catch((error) => {
+        console.error(error);
+      });
     }
   });
 }
 
 /**
- * Sends the provided array of logs to the specified url,
+ * Sends the provided array of logs to the specified url via the active exporter,
  * retrying the request up to the specified number of retries.
  * @param  {Array<Logging.Log>} logs    Array of logs to send.
  * @param  {Configuration} config     configuration singleton.
@@ -131,63 +133,6 @@ export async function sendLogs(
   config: Configuration,
   retries: number,
 ): Promise<void> {
-  const data = JSON.stringify(logs);
-  const url = new URL(config.url);
-
-  if (url.protocol === "ws:" || url.protocol === "wss:") {
-    wsock.send(data);
-    return;
-  }
-
-  // Build headers
-  const headers = new Headers({
-    "Content-Type": "application/json;charset=UTF-8",
-  });
-
-  updateAuthHeader(config);
-  if (config.authHeader) {
-    const authHeaderValue =
-      typeof config.authHeader === "function"
-        ? config.authHeader()
-        : config.authHeader;
-    headers.set("Authorization", authHeaderValue);
-  }
-
-  if (config.apiKey) {
-    headers.set("x-api-key", config.apiKey);
-  }
-
-  // Update custom headers last to allow them to over-write the defaults. This assumes
-  // the user knows what they are doing and may want to over-write the defaults.
-  updateCustomHeaders(config);
-  if (config.headers) {
-    for (const [header, value] of Object.entries(config.headers)) {
-      headers.set(header, value);
-    }
-  }
-
-  async function attemptSend(remainingRetries: number): Promise<void> {
-    try {
-      const response = await fetch(config.url, {
-        method: "POST",
-        headers,
-        body: data,
-      });
-
-      if (!response.ok) {
-        if (remainingRetries > 0) {
-          return attemptSend(remainingRetries - 1);
-        } else {
-          throw new Error(`Failed to send logs: ${response.statusText}`);
-        }
-      }
-    } catch (error) {
-      if (remainingRetries > 0) {
-        return attemptSend(remainingRetries - 1);
-      }
-      throw error;
-    }
-  }
-
-  return attemptSend(retries);
+  const exporter = resolveExporter(config);
+  await exporter.export(logs, { retries });
 }
diff --git a/products/userale/packages/flagon-userale/src/types.d.ts b/products/userale/packages/flagon-userale/src/types.d.ts
index 75c2af6..d7c0d35 100644
--- a/products/userale/packages/flagon-userale/src/types.d.ts
+++ b/products/userale/packages/flagon-userale/src/types.d.ts
@@ -14,6 +14,11 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type {
+  ExporterType as ExporterMode,
+  LogExporter,
+} from "@/exporters/types";
+
 export declare namespace Settings {
   type Version = string | null;
   type UserId = string | null;
@@ -25,11 +30,14 @@ export declare namespace Settings {
   type CustomIndex = string | null;
   type HeaderObject = { [key: string]: string };
   type Headers = HeaderObject | null;
+  type ExporterType = ExporterMode;
+  type CustomExporter = LogExporter | null;
   type ConfigValueTypes =
     | string
     | number
     | boolean
     | null
+    | undefined
     | Version
     | UserId
     | SessionId
@@ -38,7 +46,9 @@ export declare namespace Settings {
     | AuthHeader
     | ApiKey
     | CustomIndex
-    | Headers;
+    | Headers
+    | ExporterType
+    | CustomExporter;
 
   type TimeFunction = (() => number) | ((ts: number) => number);
 
@@ -52,6 +62,8 @@ export declare namespace Settings {
     authHeader: AuthHeader;
     browserSessionId: SessionId;
     custIndex: CustomIndex;
+    exporter?: CustomExporter;
+    exporterType?: ExporterType;
     headers: Headers;
     httpSessionId: SessionId;
     logCountThreshold: number;
diff --git a/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts b/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts
new file mode 100644
index 0000000..008ccc3
--- /dev/null
+++ b/products/userale/packages/flagon-userale/test/spec/exporters.spec.ts
@@ -0,0 +1,349 @@
+/**
+ * @jest-environment jsdom
+ */
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import "whatwg-fetch";
+import { Configuration } from "@/configure";
+import {
+  buildHeaders,
+  chunkLogsForKeepalive,
+  createExporter,
+  HttpJsonExporter,
+  ProtoJsonExporter,
+  toProtoLogBatch,
+  WebSocketExporter,
+} from "@/exporters";
+import { LogBatchSchema, LogType } from "@/gen/apache/flagon/userale/v1/log_pb";
+import { initSender, sendOnInterval } from "@/sendLogs";
+import {
+  registerAuthCallback,
+  registerHeadersCallback,
+  resetAuthCallback,
+  resetHeadersCallback,
+} from "@/utils";
+import { fromJson } from "@bufbuild/protobuf";
+
+import type { LogExporter } from "@/exporters";
+import type { Logging } from "@/types";
+import type { JsonValue } from "@bufbuild/protobuf";
+
+const config = Configuration.getInstance();
+
+describe("exporters", () => {
+  beforeEach(() => {
+    config.reset();
+    resetAuthCallback();
+    resetHeadersCallback();
+  });
+
+  describe("buildHeaders", () => {
+    it("merges string authHeader, custom headers callback, and apiKey", () => {
+      registerHeadersCallback(() => ({
+        "x-custom": "val",
+      }));
+      config.update({
+        authHeader: "Bearer test-token",
+        apiKey: "api-key-123",
+      });
+
+      const headers = buildHeaders(config);
+      expect(headers.get("Content-Type")).toBe(
+        "application/json;charset=UTF-8",
+      );
+      expect(headers.get("Authorization")).toBe("Bearer test-token");
+      expect(headers.get("x-api-key")).toBe("api-key-123");
+      expect(headers.get("x-custom")).toBe("val");
+    });
+
+    it("supports callback authHeader", () => {
+      registerAuthCallback(() => "Bearer dynamic-token");
+      const headers = buildHeaders(config);
+      expect(headers.get("Authorization")).toBe("Bearer dynamic-token");
+    });
+  });
+
+  describe("createExporter factory", () => {
+    it("creates HttpJsonExporter by default for http URLs", () => {
+      config.update({ url: "http://localhost:8000" });
+      const exporter = createExporter(config);
+      expect(exporter).toBeInstanceOf(HttpJsonExporter);
+    });
+
+    it("creates WebSocketExporter for ws:// or wss:// URLs", () => {
+      const wsSpy = jest.spyOn(global, "WebSocket").mockImplementation(
+        () =>
+          ({
+            readyState: 1,
+            send: jest.fn(),
+            close: jest.fn(),
+          }) as unknown as WebSocket,
+      );
+      config.update({ url: "ws://localhost:8000" });
+      const exporter = createExporter(config);
+      expect(exporter).toBeInstanceOf(WebSocketExporter);
+      wsSpy.mockRestore();
+    });
+
+    it("creates ProtoJsonExporter when exporterType is 'proto-json'", () => {
+      config.update({
+        url: "http://localhost:8000",
+        exporterType: "proto-json",
+      });
+      const exporter = createExporter(config);
+      expect(exporter).toBeInstanceOf(ProtoJsonExporter);
+    });
+
+    it("returns custom config.exporter when provided", () => {
+      const customExporter: LogExporter = {
+        export: jest.fn().mockResolvedValue({ success: true }),
+      };
+      config.update({ exporter: customExporter });
+      const exporter = createExporter(config);
+      expect(exporter).toBe(customExporter);
+    });
+
+    it("routes sendOnInterval through custom config.exporter", () => {
+      const customExporter: LogExporter = {
+        export: jest.fn().mockResolvedValue({ success: true }),
+      };
+      config.update({
+        on: true,
+        transmitInterval: 100,
+        logCountThreshold: 1,
+        exporter: customExporter,
+      });
+
+      const logs: Array<Logging.Log> = [{ target: "button#submit" }];
+      jest.useFakeTimers();
+      initSender(logs, config);
+      sendOnInterval(logs, config);
+
+      jest.advanceTimersByTime(100);
+      expect(customExporter.export).toHaveBeenCalledWith(
+        [{ target: "button#submit" }],
+        { retries: 0 },
+      );
+      jest.useRealTimers();
+    });
+  });
+
+  describe("chunkLogsForKeepalive", () => {
+    it("keeps small batches in a single chunk", () => {
+      const logs = [{ id: 1 }, { id: 2 }];
+      const chunks = chunkLogsForKeepalive(logs, (batch) =>
+        JSON.stringify(batch),
+      );
+      expect(chunks).toHaveLength(1);
+      expect(JSON.parse(chunks[0]!)).toEqual(logs);
+    });
+
+    it("splits batches that exceed MAX_KEEPALIVE_BYTES into multiple chunks", () => {
+      const logs = Array.from({ length: 10 }, (_, i) => ({
+        id: i,
+        payload: "x".repeat(8000),
+      }));
+      const chunks = chunkLogsForKeepalive(logs, (batch) =>
+        JSON.stringify(batch),
+      );
+      expect(chunks.length).toBeGreaterThan(1);
+      const reassembled = chunks.flatMap(
+        (chunk) => JSON.parse(chunk) as typeof logs,
+      );
+      expect(reassembled).toEqual(logs);
+    });
+  });
+
+  describe("ProtoJsonExporter & Protobuf v1 contract (#142, #143)", () => {
+    it("serializes raw, interval, and custom logs into valid apache.flagon.userale.v1.LogBatch JSON", () => {
+      const rawLog: Logging.Log = {
+        target: "button#buy",
+        path: ["button#buy", "div.card", "body", "html"],
+        pageUrl: "https://shop.example.com/product/42",
+        pageTitle: "Shop Example",
+        pageReferrer: "https://shop.example.com/",
+        browser: { browser: "chrome", version: "125.0" },
+        userAgent: "Mozilla/5.0 Chrome/125.0",
+        clientTime: 1712000000000,
+        scrnRes: { width: 1920, height: 1080 },
+        microTime: 123.45,
+        location: { x: 150, y: 320 },
+        type: "click",
+        logType: "raw",
+        userAction: true,
+        details: { button: 0, ctrl: false },
+        userId: "user-42",
+        toolVersion: "1.2.3",
+        toolName: "shop-web",
+        useraleVersion: "2.5.0",
+        sessionId: "sess-abc",
+        httpSessionId: "http-sess-1",
+        browserSessionId: "browser-sess-1",
+        attributes: { id: "buy", class: "btn primary" },
+        style: { color: "rgb(255, 255, 255)" },
+      };
+
+      const intervalLog: Logging.Log = {
+        target: "div.feed",
+        path: ["div.feed", "body", "html"],
+        pageUrl: "https://shop.example.com/product/42",
+        pageTitle: "Shop Example",
+        pageReferrer: "https://shop.example.com/",
+        userAgent: "Mozilla/5.0 Chrome/125.0",
+        count: 14,
+        duration: 480,
+        startTime: 1712000000000,
+        endTime: 1712000000480,
+        type: "mouseover",
+        logType: "interval",
+        targetChange: false,
+        typeChange: false,
+        userAction: false,
+        userId: "user-42",
+        toolVersion: "1.2.3",
+        toolName: "shop-web",
+        useraleVersion: "2.5.0",
+        sessionId: "sess-abc",
+        httpSessionId: "http-sess-1",
+        browserSessionId: "browser-sess-1",
+      };
+
+      const customLog: Logging.Log = {
+        pageUrl: "https://shop.example.com/product/42",
+        pageTitle: "Shop Example",
+        pageReferrer: "https://shop.example.com/",
+        userAgent: "Mozilla/5.0 Chrome/125.0",
+        clientTime: 1712000001000,
+        scrnRes: { width: 1920, height: 1080 },
+        logType: "custom",
+        userAction: true,
+        details: { checkoutStep: 2 },
+        customLabel: "checkout_started",
+        cartValue: 99.95,
+        userId: "user-42",
+        toolVersion: "1.2.3",
+        toolName: "shop-web",
+        useraleVersion: "2.5.0",
+        sessionId: "sess-abc",
+        httpSessionId: "http-sess-1",
+        browserSessionId: "browser-sess-1",
+      };
+
+      const protoBatchJson = toProtoLogBatch([rawLog, intervalLog, customLog]);
+
+      // Validate canonical Proto3 JSON deserialization against @bufbuild/protobuf LogBatchSchema
+      const decoded = fromJson(
+        LogBatchSchema,
+        protoBatchJson as unknown as JsonValue,
+      );
+      expect(decoded.logs).toHaveLength(3);
+
+      // 1. Raw log validation
+      const first = decoded.logs[0]!;
+      expect(first.logType).toBe(LogType.RAW);
+      expect(first.log.case).toBe("raw");
+      if (first.log.case === "raw") {
+        expect(first.log.value.target).toBe("button#buy");
+        expect(first.log.value.eventType).toBe("click");
+        expect(first.log.value.path).toEqual([
+          "button#buy",
+          "div.card",
+          "body",
+          "html",
+        ]);
+        expect(first.log.value.location?.x).toBe(150);
+        expect(first.log.value.location?.y).toBe(320);
+        expect(first.log.value.microTime).toBe(123.45);
+        expect(first.log.value.userAction).toBe(true);
+        expect(first.log.value.metadata?.pageUrl).toBe(
+          "https://shop.example.com/product/42",
+        );
+        expect(first.log.value.metadata?.clientTime).toBe(
+          BigInt(1712000000000),
+        );
+        expect(first.log.value.metadata?.screenResolution?.width).toBe(1920);
+        expect(first.log.value.metadata?.userId).toBe("user-42");
+        expect(first.log.value.details).toEqual({
+          button: 0,
+          ctrl: false,
+        });
+        expect(first.log.value.attributes).toEqual({
+          id: "buy",
+          class: "btn primary",
+        });
+      }
+
+      // 2. Interval log validation
+      const second = decoded.logs[1]!;
+      expect(second.logType).toBe(LogType.INTERVAL);
+      expect(second.log.case).toBe("interval");
+      if (second.log.case === "interval") {
+        expect(second.log.value.target).toBe("div.feed");
+        expect(second.log.value.count).toBe(14);
+        expect(second.log.value.duration).toBe(BigInt(480));
+        expect(second.log.value.startTime).toBe(BigInt(1712000000000));
+        expect(second.log.value.endTime).toBe(BigInt(1712000000480));
+      }
+
+      // 3. Custom log validation
+      const third = decoded.logs[2]!;
+      expect(third.logType).toBe(LogType.CUSTOM);
+      expect(third.log.case).toBe("custom");
+      if (third.log.case === "custom") {
+        expect(third.log.value.userAction).toBe(true);
+        expect(third.log.value.details).toEqual({ checkoutStep: 2 });
+        expect(third.log.value.customFields).toEqual({
+          customLabel: "checkout_started",
+          cartValue: 99.95,
+        });
+      }
+    });
+
+    it("exports LogBatch JSON over fetch when ProtoJsonExporter.export is called", async () => {
+      const fetchSpy = jest
+        .spyOn(global, "fetch")
+        .mockResolvedValue(new Response(null, { status: 200 }));
+
+      config.update({
+        url: "http://localhost:8000",
+        exporterType: "proto-json",
+      });
+
+      const exporter = new ProtoJsonExporter(config);
+      const result = await exporter.export([
+        {
+          target: "a#nav",
+          path: ["a#nav"],
+          type: "click",
+          logType: "raw",
+          clientTime: 1712000000000,
+          userAction: true,
+        },
+      ]);
+
+      expect(result.success).toBe(true);
+      expect(fetchSpy).toHaveBeenCalledTimes(1);
+      const bodyStr = fetchSpy.mock.calls[0]![1]!.body as string;
+      const parsed = JSON.parse(bodyStr) as JsonValue;
+      const decoded = fromJson(LogBatchSchema, parsed);
+      expect(decoded.logs).toHaveLength(1);
+      expect(decoded.logs[0]!.logType).toBe(LogType.RAW);
+
+      fetchSpy.mockRestore();
+    });
+  });
+});
diff --git a/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts b/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
index 8d73234..bad6e83 100644
--- a/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
+++ b/products/userale/packages/flagon-userale/test/spec/sendLogs.spec.ts
@@ -20,7 +20,12 @@
 import "whatwg-fetch";
 import { Configuration } from "@/configure";
 import { initSender, sendOnInterval, sendOnClose } from "@/sendLogs";
-import { registerAuthCallback, registerHeadersCallback } from "@/utils";
+import {
+  registerAuthCallback,
+  registerHeadersCallback,
+  resetAuthCallback,
+  resetHeadersCallback,
+} from "@/utils";
 
 import type { Logging } from "@/types";
 
@@ -30,6 +35,8 @@ let xhrMock: Partial<XMLHttpRequest>;
 describe("sendLogs", () => {
   beforeEach(() => {
     config.reset();
+    resetAuthCallback();
+    resetHeadersCallback();
     xhrMock = {
       open: jest.fn(),
       send: jest.fn(),
@@ -300,4 +307,36 @@ describe("sendLogs", () => {
 
     warnSpy.mockRestore();
   });
+
+  it("includes callback authHeader and custom headers on pagehide (#133)", () => {
+    const fetchSpy = jest
+      .spyOn(global, "fetch")
+      .mockResolvedValue(new Response());
+
+    const authCallback = jest.fn().mockReturnValue("Bearer callback-token");
+    const headersCallback = jest.fn().mockReturnValue({
+      "x-custom-header": "custom-val",
+    });
+    registerAuthCallback(authCallback);
+    registerHeadersCallback(headersCallback);
+
+    config.update({
+      on: true,
+      url: "http://test.com",
+      apiKey: "key-123",
+    });
+
+    sendOnClose([{ foo: "bar" }], config);
+    global.window.dispatchEvent(new window.CustomEvent("pagehide"));
+
+    expect(fetchSpy).toHaveBeenCalled();
+    const lastCall = fetchSpy.mock.calls[fetchSpy.mock.calls.length - 1]!;
+    const callHeaders = lastCall[1]!.headers as Headers;
+    expect(callHeaders.get("Authorization")).toBe("Bearer callback-token");
+    expect(callHeaders.get("x-custom-header")).toBe("custom-val");
+    expect(callHeaders.get("x-api-key")).toBe("key-123");
+    expect(lastCall[1]!.keepalive).toBe(true);
+
+    fetchSpy.mockRestore();
+  });
 });