pinqloq 1.1.0

package/dist/index.cjs

@@ -0,0 +1,716 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CORRELATION_ID_HEADER_NAME: () => CORRELATION_ID_HEADER_NAME,
+  DEVICE_IDENTIFIER_HEADER_NAME: () => DEVICE_IDENTIFIER_HEADER_NAME,
+  PinqloqLogFailureReason: () => PinqloqLogFailureReason,
+  PinqloqLogLevel: () => PinqloqLogLevel,
+  PinqloqLogSourceType: () => PinqloqLogSourceType,
+  PinqloqRedactionPlan: () => PinqloqRedactionPlan,
+  createPinqloq: () => createPinqloq
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/buffering/callback.ts
+function raiseSent(onSent, entry) {
+  if (!onSent) return;
+  try {
+    onSent(entry);
+  } catch (error) {
+    console.warn("Pinqloq: the onSent callback threw an exception; swallowed.", error);
+  }
+}
+function raiseFailed(onFailed, entry, error) {
+  if (!onFailed) return;
+  try {
+    onFailed(entry, error);
+  } catch (callbackError) {
+    console.warn("Pinqloq: the onFailed callback threw an exception; swallowed.", callbackError);
+  }
+}
+
+// src/logging/types.ts
+var PinqloqLogLevel = /* @__PURE__ */ ((PinqloqLogLevel2) => {
+  PinqloqLogLevel2[PinqloqLogLevel2["Debug"] = 1] = "Debug";
+  PinqloqLogLevel2[PinqloqLogLevel2["Information"] = 2] = "Information";
+  PinqloqLogLevel2[PinqloqLogLevel2["Warning"] = 3] = "Warning";
+  PinqloqLogLevel2[PinqloqLogLevel2["Error"] = 4] = "Error";
+  PinqloqLogLevel2[PinqloqLogLevel2["Fatal"] = 5] = "Fatal";
+  return PinqloqLogLevel2;
+})(PinqloqLogLevel || {});
+var PinqloqLogSourceType = /* @__PURE__ */ ((PinqloqLogSourceType2) => {
+  PinqloqLogSourceType2[PinqloqLogSourceType2["Device"] = 1] = "Device";
+  PinqloqLogSourceType2[PinqloqLogSourceType2["Backend"] = 2] = "Backend";
+  return PinqloqLogSourceType2;
+})(PinqloqLogSourceType || {});
+var PinqloqLogFailureReason = /* @__PURE__ */ ((PinqloqLogFailureReason2) => {
+  PinqloqLogFailureReason2["Unauthorized"] = "Unauthorized";
+  PinqloqLogFailureReason2["Forbidden"] = "Forbidden";
+  PinqloqLogFailureReason2["MissingCollection"] = "MissingCollection";
+  PinqloqLogFailureReason2["QueueFull"] = "QueueFull";
+  PinqloqLogFailureReason2["HttpError"] = "HttpError";
+  PinqloqLogFailureReason2["Timeout"] = "Timeout";
+  PinqloqLogFailureReason2["Network"] = "Network";
+  PinqloqLogFailureReason2["Unknown"] = "Unknown";
+  return PinqloqLogFailureReason2;
+})(PinqloqLogFailureReason || {});
+
+// src/buffering/buffer.ts
+var PinqloqLogBuffer = class {
+  constructor(capacity) {
+    this.capacity = capacity;
+  }
+  capacity;
+  queue = [];
+  droppedCount = 0;
+  completed = false;
+  get size() {
+    return this.queue.length;
+  }
+  enqueue(entry, onSent, onFailed) {
+    if (this.completed) throw new Error("Pinqloq: the log queue is closed.");
+    if (!entry) return false;
+    entry.date ??= /* @__PURE__ */ new Date();
+    if (this.queue.length >= this.capacity) {
+      this.droppedCount++;
+      if (this.droppedCount === 1 || this.droppedCount % 1e3 === 0) {
+        console.warn(`Pinqloq: log queue is full; ${this.droppedCount} logs dropped so far.`);
+      }
+      raiseFailed(onFailed, entry, {
+        reason: "QueueFull" /* QueueFull */,
+        message: "Log queue is full; the log was dropped. Increase queueCapacity or lower flushIntervalMs."
+      });
+      return false;
+    }
+    this.queue.push({ entry, onSent, onFailed });
+    return true;
+  }
+  enqueueMany(entries, onSent, onFailed) {
+    if (!entries) return 0;
+    let queuedCount = 0;
+    for (const entry of entries) {
+      if (this.enqueue(entry, onSent, onFailed)) queuedCount++;
+    }
+    return queuedCount;
+  }
+  complete() {
+    this.completed = true;
+  }
+  drain(max) {
+    return this.queue.splice(0, max);
+  }
+};
+
+// src/buffering/dispatcher.ts
+var PinqloqLogDispatcher = class {
+  constructor(buffer, apiClient, options) {
+    this.buffer = buffer;
+    this.apiClient = apiClient;
+    this.options = options;
+  }
+  buffer;
+  apiClient;
+  options;
+  timer;
+  pendingSend;
+  stopping = false;
+  start() {
+    this.notifyEnqueued();
+  }
+  notifyEnqueued() {
+    if (this.stopping || this.pendingSend || this.buffer.size === 0) return;
+    if (this.buffer.size >= this.options.batchSize) {
+      void this.flush();
+      return;
+    }
+    if (this.timer) return;
+    this.timer = setTimeout(() => void this.flush(), this.options.flushIntervalMs);
+    this.timer.unref?.();
+  }
+  flush() {
+    if (this.pendingSend) return this.pendingSend;
+    this.clearTimer();
+    if (this.buffer.size === 0) return Promise.resolve();
+    this.pendingSend = this.sendBatches().finally(() => {
+      this.pendingSend = void 0;
+      this.notifyEnqueued();
+    });
+    return this.pendingSend;
+  }
+  async sendBatches() {
+    do {
+      const batch = this.buffer.drain(this.options.batchSize);
+      try {
+        await this.apiClient.sendBatch(batch);
+      } catch (error) {
+        console.warn(`Pinqloq: batch of ${batch.length} logs could not be sent; dropped.`, error);
+      }
+    } while (this.buffer.size > 0 && (this.stopping || this.buffer.size >= this.options.batchSize));
+  }
+  clearTimer() {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = void 0;
+  }
+  async shutdown() {
+    this.stopping = true;
+    this.buffer.complete();
+    this.clearTimer();
+    await this.flush();
+  }
+};
+
+// src/express/middleware.ts
+var import_node_crypto = require("crypto");
+
+// src/redaction/plan.ts
+var ALWAYS_REDACTED_NAMES = new Set(
+  [
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-secret-key",
+    "x-auth-token",
+    "x-access-token",
+    "x-csrf-token",
+    "x-xsrf-token",
+    "secret_key",
+    "password",
+    "newpassword",
+    "oldpassword",
+    "currentpassword",
+    "passwordconfirmation",
+    "confirmpassword",
+    "secret",
+    "secretkey",
+    "clientsecret",
+    "apikey",
+    "accesstoken",
+    "refreshtoken",
+    "idtoken",
+    "token",
+    "otp",
+    "otpcode",
+    "verificationcode",
+    "pin",
+    "privatekey",
+    "cardnumber",
+    "cvv",
+    "cvc",
+    "securitycode",
+    "iban",
+    "ssn"
+  ].map((name) => name.toLowerCase())
+);
+function isLetterOrDigit(char) {
+  return char !== void 0 && /[A-Za-z0-9]/.test(char);
+}
+function isUpper(char) {
+  return char !== void 0 && char !== char.toLowerCase() && char === char.toUpperCase();
+}
+function isBoundedName(body, index, length) {
+  const endIndex = index + length;
+  const isStartBounded = index === 0 || !isLetterOrDigit(body[index - 1]) || isUpper(body[index]) && !isUpper(body[index - 1]);
+  const isEndBounded = endIndex === body.length || !isLetterOrDigit(body[endIndex]) || isUpper(body[endIndex]);
+  return isStartBounded && isEndBounded;
+}
+function containsWholeName(body, names) {
+  const lowerBody = body.toLowerCase();
+  for (const name of names) {
+    if (name.length === 0) continue;
+    let searchFrom = 0;
+    while (searchFrom <= lowerBody.length - name.length) {
+      const index = lowerBody.indexOf(name, searchFrom);
+      if (index < 0) break;
+      if (isBoundedName(body, index, name.length)) return true;
+      searchFrom = index + 1;
+    }
+  }
+  return false;
+}
+var PinqloqRedactionPlan = class _PinqloqRedactionPlan {
+  constructor(redactAll, declaredNames) {
+    this.redactAll = redactAll;
+    this.declaredNames = new Set([...declaredNames].map((name) => name.toLowerCase()));
+  }
+  redactAll;
+  static NONE = new _PinqloqRedactionPlan(false, []);
+  static ALL = new _PinqloqRedactionPlan(true, []);
+  declaredNames;
+  get hasDeclaredRedactions() {
+    return this.redactAll || this.declaredNames.size > 0;
+  }
+  shouldRedact(propertyOrHeaderName) {
+    const lower = propertyOrHeaderName.toLowerCase();
+    return this.redactAll || ALWAYS_REDACTED_NAMES.has(lower) || this.declaredNames.has(lower);
+  }
+  containsDeclaredName(body) {
+    return containsWholeName(body, this.declaredNames);
+  }
+  static containsAlwaysRedactedName(body) {
+    return containsWholeName(body, ALWAYS_REDACTED_NAMES);
+  }
+};
+
+// src/internal/throttledWarn.ts
+var nextAllowedAt = /* @__PURE__ */ new Map();
+function warnThrottled(key, intervalMs, message, ...args) {
+  const now = Date.now();
+  const next = nextAllowedAt.get(key) ?? 0;
+  if (now < next) return;
+  nextAllowedAt.set(key, now + intervalMs);
+  console.warn(message, ...args);
+}
+
+// src/redaction/redaction.ts
+var REDACTED_VALUE = "*****REDACTED*****";
+var MALFORMED_BODY_WARNING_THROTTLE_MS = 6e4;
+var UNPARSEABLE_SENSITIVE_BODY_VALUE = "*****REDACTED: body carries a credential field and is not parseable JSON (non-JSON content type, or longer than the capture limit)*****";
+function redactProperties(value, plan) {
+  if (Array.isArray(value)) return value.map((item) => redactProperties(item, plan));
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) {
+      result[key] = plan.shouldRedact(key) ? REDACTED_VALUE : redactProperties(item, plan);
+    }
+    return result;
+  }
+  return value;
+}
+function redactFully(value) {
+  if (Array.isArray(value)) return value.map(redactFully);
+  if (value !== null && typeof value === "object") {
+    const result = {};
+    for (const [key, item] of Object.entries(value)) result[key] = redactFully(item);
+    return result;
+  }
+  return REDACTED_VALUE;
+}
+function redactJsonProperties(body, plan, isSensitive) {
+  if (!body.trim()) return body;
+  try {
+    return JSON.stringify(redactProperties(JSON.parse(body), plan));
+  } catch (error) {
+    warnThrottled(
+      "redactJsonProperties",
+      MALFORMED_BODY_WARNING_THROTTLE_MS,
+      "Pinqloq: a captured body could not be parsed as JSON; falling back to whole-body handling.",
+      error
+    );
+    return isSensitive ? UNPARSEABLE_SENSITIVE_BODY_VALUE : body;
+  }
+}
+function redactJsonFully(body) {
+  if (!body.trim()) return body;
+  try {
+    return JSON.stringify(redactFully(JSON.parse(body)));
+  } catch (error) {
+    warnThrottled(
+      "redactJsonFully",
+      MALFORMED_BODY_WARNING_THROTTLE_MS,
+      "Pinqloq: a captured body under a redactAll plan could not be parsed as JSON; masking it wholesale.",
+      error
+    );
+    return REDACTED_VALUE;
+  }
+}
+function applyBodyRedaction(body, plan) {
+  if (plan.redactAll) return redactJsonFully(body);
+  const mentionsCredential = PinqloqRedactionPlan.containsAlwaysRedactedName(body) || plan.containsDeclaredName(body);
+  if (!plan.hasDeclaredRedactions && !mentionsCredential) return body;
+  return redactJsonProperties(body, plan, mentionsCredential);
+}
+function serializeHeaders(headers, plan) {
+  const result = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (value === void 0) continue;
+    const stringValue = Array.isArray(value) ? value.join(", ") : String(value);
+    result[key] = plan.shouldRedact(key) ? REDACTED_VALUE : stringValue;
+  }
+  return JSON.stringify(result);
+}
+
+// src/express/pathMatch.ts
+function matchesAnyPathPrefix(path, prefixes) {
+  if (!prefixes || prefixes.length === 0) return false;
+  const lowerPath = path.toLowerCase();
+  return prefixes.some((prefix) => matchesSegmentPrefix(lowerPath, prefix.toLowerCase()));
+}
+function matchesSegmentPrefix(lowerPath, prefix) {
+  const normalized = prefix.startsWith("/") ? prefix : `/${prefix}`;
+  const trimmed = normalized.length > 1 && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
+  if (!lowerPath.startsWith(trimmed)) return false;
+  return lowerPath.length === trimmed.length || lowerPath[trimmed.length] === "/";
+}
+
+// src/express/captureResponseBody.ts
+function captureResponseBody(res, maxBytes) {
+  const originalWrite = res.write.bind(res);
+  const originalEnd = res.end.bind(res);
+  const chunks = [];
+  let capturedBytes = 0;
+  function capture(chunk) {
+    if (chunk === void 0 || chunk === null || capturedBytes >= maxBytes) return;
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    const remaining = maxBytes - capturedBytes;
+    const slice = buffer.length > remaining ? buffer.subarray(0, remaining) : buffer;
+    chunks.push(slice);
+    capturedBytes += slice.length;
+  }
+  res.write = function(chunk, ...args) {
+    capture(chunk);
+    return originalWrite(chunk, ...args);
+  };
+  res.end = function(chunk, ...args) {
+    if (chunk !== void 0 && typeof chunk !== "function") capture(chunk);
+    return originalEnd(chunk, ...args);
+  };
+  return {
+    getBody: () => Buffer.concat(chunks).toString("utf8"),
+    restore: () => {
+      res.write = originalWrite;
+      res.end = originalEnd;
+    }
+  };
+}
+
+// src/express/middleware.ts
+var MAX_BODY_CHARACTERS = 32 * 1024;
+var MAX_BODY_BYTES = 4 * MAX_BODY_CHARACTERS;
+var SELECTOR_WARNING_THROTTLE_MS = 6e4;
+var DEVICE_IDENTIFIER_HEADER_NAME = "device-identifier";
+var CORRELATION_ID_HEADER_NAME = "correlation-id";
+var DEVICE_IDENTIFIER_REQUIRED_MESSAGE = "Pinqloq: the required deviceIdentifier could not be resolved. Send the 'device-identifier' request header, or configure resolveDeviceIdentifier, or set PinqloqOptions.deviceIdentifier.";
+var SERVER_ERROR_STATUS_THRESHOLD = 500;
+var CLIENT_ERROR_STATUS_THRESHOLD = 400;
+function resolveLogLevel(statusCode) {
+  if (statusCode >= SERVER_ERROR_STATUS_THRESHOLD) return 4 /* Error */;
+  if (statusCode >= CLIENT_ERROR_STATUS_THRESHOLD) return 3 /* Warning */;
+  return 2 /* Information */;
+}
+function truncate(value) {
+  return value.length <= MAX_BODY_CHARACTERS ? value : value.slice(0, MAX_BODY_CHARACTERS);
+}
+function resolveSelector(selector, req, throttleKey) {
+  if (!selector) return "";
+  try {
+    return selector(req) ?? "";
+  } catch (error) {
+    warnThrottled(throttleKey, SELECTOR_WARNING_THROTTLE_MS, `Pinqloq: ${throttleKey} threw an exception; ignored.`, error);
+    return "";
+  }
+}
+function resolveDeviceIdentifier(req, requestOptions, globalOptions) {
+  const overridden = resolveSelector(requestOptions.resolveDeviceIdentifier, req, "resolveDeviceIdentifier");
+  if (overridden.trim()) return overridden;
+  const header = req.headers[DEVICE_IDENTIFIER_HEADER_NAME];
+  const headerValue = Array.isArray(header) ? header[0] : header;
+  if (headerValue?.trim()) return headerValue;
+  return globalOptions.deviceIdentifier ?? "";
+}
+function resolveCorrelationId(req) {
+  const header = req.headers[CORRELATION_ID_HEADER_NAME];
+  const headerValue = Array.isArray(header) ? header[0] : header;
+  return headerValue?.trim() ? headerValue : (0, import_node_crypto.randomUUID)();
+}
+function applyEnrichers(target, enrichers, req, res) {
+  if (!enrichers) return;
+  for (const [key, selector] of Object.entries(enrichers)) {
+    let value;
+    try {
+      value = selector(req, res);
+    } catch (error) {
+      warnThrottled(`enricher:${key}`, SELECTOR_WARNING_THROTTLE_MS, `Pinqloq: the '${key}' enricher threw an exception; ignored.`, error);
+      continue;
+    }
+    if (value) target[key] = value;
+  }
+}
+function createPinqloqRequestLogging(logger, globalOptions, requestOptions = {}) {
+  return function pinqloqRequestLoggingMiddleware(req, res, next) {
+    if (matchesAnyPathPrefix(req.path, requestOptions.excludePaths)) {
+      next();
+      return;
+    }
+    const deviceIdentifier = resolveDeviceIdentifier(req, requestOptions, globalOptions);
+    if (!deviceIdentifier.trim()) {
+      res.status(400).send(DEVICE_IDENTIFIER_REQUIRED_MESSAGE);
+      return;
+    }
+    const startedAt = process.hrtime.bigint();
+    const redactPlan = requestOptions.redactPaths?.length && matchesAnyPathPrefix(req.path, requestOptions.redactPaths) ? PinqloqRedactionPlan.ALL : new PinqloqRedactionPlan(false, requestOptions.redactFields ?? []);
+    const requestHeaders = truncate(serializeHeaders(req.headers, redactPlan));
+    const inputJson = truncate(
+      applyBodyRedaction(req.body !== void 0 ? JSON.stringify(req.body) : "", redactPlan)
+    );
+    const correlationId = resolveCorrelationId(req);
+    const appVersionName = resolveSelector(requestOptions.resolveAppVersionName, req, "resolveAppVersionName");
+    const capture = captureResponseBody(res, MAX_BODY_BYTES);
+    res.once("finish", () => {
+      capture.restore();
+      const elapsedMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
+      const statusCode = res.statusCode;
+      const method = req.method;
+      const path = req.path;
+      const outputJson = truncate(applyBodyRedaction(capture.getBody(), redactPlan));
+      const responseHeaders = truncate(serializeHeaders(res.getHeaders(), redactPlan));
+      const metadata = {};
+      metadata.event = `${method} ${path}`.trim();
+      applyEnrichers(metadata, requestOptions.metadata, req, res);
+      const resolvedEventName = metadata.event;
+      delete metadata.event;
+      metadata.method = method;
+      metadata.statusCode = String(statusCode);
+      metadata.durationMs = String(Math.round(elapsedMs));
+      metadata.RequestMethod = method;
+      metadata.ResponseCode = String(statusCode);
+      const detail = {};
+      applyEnrichers(detail, requestOptions.detail, req, res);
+      detail.InputJson = inputJson;
+      detail.OutputJson = outputJson;
+      detail.RequestHeaders = requestHeaders;
+      detail.ResponseHeaders = responseHeaders;
+      const logLevel = resolveLogLevel(statusCode);
+      const resolvedAppVersionName = appVersionName || void 0;
+      logger.enqueue({
+        logLevel,
+        event: resolvedEventName,
+        deviceIdentifier,
+        appVersionName: resolvedAppVersionName,
+        logSourceType: 2 /* Backend */,
+        correlationId,
+        path,
+        metadata,
+        detail
+      });
+    });
+    next();
+  };
+}
+
+// src/options.ts
+var INGEST_BASE_ADDRESS = "https://pinqloq-external-api.pinqponq.io";
+var DEFAULTS = {
+  bulkPath: "api/client-logs/bulk",
+  batchSize: 200,
+  flushIntervalMs: 2e3,
+  queueCapacity: 1e4,
+  httpTimeoutMs: 1e4
+};
+function resolveOptions(options) {
+  if (!options.secretKey) {
+    throw new Error("Pinqloq: secretKey is required.");
+  }
+  return {
+    secretKey: options.secretKey,
+    apiLogsCollectionName: options.apiLogsCollectionName,
+    bulkPath: options.bulkPath ?? DEFAULTS.bulkPath,
+    batchSize: Math.max(1, options.batchSize ?? DEFAULTS.batchSize),
+    flushIntervalMs: Math.max(1, options.flushIntervalMs ?? DEFAULTS.flushIntervalMs),
+    queueCapacity: Math.max(1, options.queueCapacity ?? DEFAULTS.queueCapacity),
+    httpTimeoutMs: Math.max(1, options.httpTimeoutMs ?? DEFAULTS.httpTimeoutMs),
+    appVersionName: options.appVersionName,
+    deviceIdentifier: options.deviceIdentifier
+  };
+}
+
+// src/http/ingestClient.ts
+var SECRET_KEY_HEADER = "X-Secret-Key";
+var HTTP_WARNING_THROTTLE_MS = 6e4;
+var MAX_ERROR_BODY_CHARACTERS = 512;
+var PinqloqIngestApiClient = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  nextHttpWarningAt = 0;
+  async sendBatch(items) {
+    if (items.length === 0) return;
+    const groups = /* @__PURE__ */ new Map();
+    for (const item of items) {
+      const collectionName = this.resolveCollectionName(item.entry) ?? "";
+      const group = groups.get(collectionName);
+      if (group) group.push(item);
+      else groups.set(collectionName, [item]);
+    }
+    for (const [collectionName, groupItems] of groups) {
+      await this.sendGroup(collectionName || void 0, groupItems);
+    }
+  }
+  async sendGroup(collectionName, groupItems) {
+    const url = `${INGEST_BASE_ADDRESS}/${this.options.bulkPath.replace(/^\/+/, "")}`;
+    const payload = {
+      collectionName,
+      logs: groupItems.map((item) => this.toWireItem(item.entry))
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.options.httpTimeoutMs);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          [SECRET_KEY_HEADER]: this.options.secretKey
+        },
+        body: JSON.stringify(payload),
+        signal: controller.signal
+      });
+      if (response.ok) {
+        for (const item of groupItems) raiseSent(item.onSent, item.entry);
+        return;
+      }
+      const errorBody = await this.readErrorBody(response);
+      const error = this.buildHttpError(response.status, collectionName, errorBody);
+      for (const item of groupItems) raiseFailed(item.onFailed, item.entry, error);
+    } catch (exception) {
+      const aborted = controller.signal.aborted;
+      const error = this.buildExceptionError(exception, aborted);
+      console.warn(
+        `Pinqloq: group of ${groupItems.length} logs could not be sent (${this.formatCollectionName(collectionName)}).`,
+        exception
+      );
+      for (const item of groupItems) raiseFailed(item.onFailed, item.entry, error);
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+  buildHttpError(statusCode, collectionName, errorBody) {
+    const reason = statusCode === 401 ? "Unauthorized" /* Unauthorized */ : statusCode === 403 ? "Forbidden" /* Forbidden */ : "HttpError" /* HttpError */;
+    let message;
+    if (reason === "Unauthorized" /* Unauthorized */) {
+      message = "Unauthorized (HTTP 401): the secret key is invalid or missing.";
+    } else if (reason === "Forbidden" /* Forbidden */) {
+      message = `Forbidden (HTTP 403): the secret key is not authorized for the '${this.formatCollectionName(collectionName)}' collection.`;
+    } else if (statusCode === 400) {
+      message = `The server rejected the request (HTTP 400, '${this.formatCollectionName(collectionName)}'): check the collectionName (required for keys allowed on multiple collections) or event fields.`;
+    } else {
+      message = `The server returned an error (HTTP ${statusCode}).`;
+    }
+    if (errorBody) message += ` Server response: ${errorBody}`;
+    if (this.shouldLogHttpFailure()) {
+      console.error(
+        `Pinqloq: batch send rejected (HTTP ${statusCode}, collection '${this.formatCollectionName(collectionName)}'); logs in this group were dropped. ${message}`
+      );
+    }
+    return { reason, statusCode, message };
+  }
+  buildExceptionError(exception, aborted) {
+    const isTimeout = aborted || exception instanceof DOMException && exception.name === "AbortError";
+    return isTimeout ? { reason: "Timeout" /* Timeout */, message: "The request timed out.", cause: exception } : {
+      reason: "Network" /* Network */,
+      message: `Network error: ${exception instanceof Error ? exception.message : String(exception)}`,
+      cause: exception
+    };
+  }
+  async readErrorBody(response) {
+    try {
+      const body = (await response.text()).trim();
+      return body.length <= MAX_ERROR_BODY_CHARACTERS ? body : body.slice(0, MAX_ERROR_BODY_CHARACTERS);
+    } catch (error) {
+      console.warn("Pinqloq: could not read the error response body; continuing without it.", error);
+      return "";
+    }
+  }
+  resolveCollectionName(entry) {
+    return entry.collectionName?.trim() || this.options.apiLogsCollectionName;
+  }
+  shouldLogHttpFailure() {
+    const now = Date.now();
+    if (now < this.nextHttpWarningAt) return false;
+    this.nextHttpWarningAt = now + HTTP_WARNING_THROTTLE_MS;
+    return true;
+  }
+  formatCollectionName(collectionName) {
+    return collectionName?.trim() ? collectionName : "(not resolved server-side)";
+  }
+  toWireItem(entry) {
+    return {
+      logLevel: entry.logLevel ?? 2,
+      event: entry.event,
+      date: entry.date?.toISOString(),
+      appVersionName: entry.appVersionName?.trim() ? entry.appVersionName : this.options.appVersionName,
+      deviceIdentifier: entry.deviceIdentifier?.trim() ? entry.deviceIdentifier : this.options.deviceIdentifier ?? "",
+      logSourceType: PinqloqLogSourceType[entry.logSourceType ?? 2 /* Backend */],
+      correlationId: entry.correlationId,
+      path: entry.path,
+      metadata: entry.metadata,
+      detail: entry.detail
+    };
+  }
+};
+
+// src/logging/logger.ts
+var DEVICE_IDENTIFIER_REQUIRED_MESSAGE2 = "Pinqloq: deviceIdentifier is required. Set it on the entry, or configure the global PinqloqOptions.deviceIdentifier fallback.";
+var DefaultPinqloqLogger = class {
+  constructor(buffer, dispatcher, options) {
+    this.buffer = buffer;
+    this.dispatcher = dispatcher;
+    this.options = options;
+  }
+  buffer;
+  dispatcher;
+  options;
+  enqueue(entry, onSent, onFailed) {
+    this.ensureDeviceIdentifier(entry);
+    const written = this.buffer.enqueue(entry, onSent, onFailed);
+    this.dispatcher.notifyEnqueued();
+    return written;
+  }
+  enqueueMany(entries, onSent, onFailed) {
+    for (const entry of entries) this.ensureDeviceIdentifier(entry);
+    const written = this.buffer.enqueueMany(entries, onSent, onFailed);
+    this.dispatcher.notifyEnqueued();
+    return written;
+  }
+  ensureDeviceIdentifier(entry) {
+    if (!entry.deviceIdentifier?.trim() && !this.options.deviceIdentifier?.trim()) {
+      throw new Error(DEVICE_IDENTIFIER_REQUIRED_MESSAGE2);
+    }
+  }
+};
+
+// src/client.ts
+function createPinqloq(options) {
+  const resolved = resolveOptions(options);
+  const buffer = new PinqloqLogBuffer(resolved.queueCapacity);
+  const apiClient = new PinqloqIngestApiClient(resolved);
+  const dispatcher = new PinqloqLogDispatcher(buffer, apiClient, resolved);
+  const logger = new DefaultPinqloqLogger(buffer, dispatcher, resolved);
+  dispatcher.start();
+  return {
+    logger,
+    requestLogging: (requestOptions) => createPinqloqRequestLogging(logger, resolved, requestOptions),
+    shutdown: () => dispatcher.shutdown()
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CORRELATION_ID_HEADER_NAME,
+  DEVICE_IDENTIFIER_HEADER_NAME,
+  PinqloqLogFailureReason,
+  PinqloqLogLevel,
+  PinqloqLogSourceType,
+  PinqloqRedactionPlan,
+  createPinqloq
+});
+//# sourceMappingURL=index.cjs.map