apitally 0.11.4 → 0.12.0

package/README.md

@@ -1,28 +1,29 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://assets.apitally.io/logos/logo-vertical-dark.png">
-    <source media="(prefers-color-scheme: light)" srcset="https://assets.apitally.io/logos/logo-vertical-light.png">
-    <img alt="Apitally logo" src="https://assets.apitally.io/logos/logo-vertical-light.png" width="150">
-  </picture>
+  <a href="https://apitally.io" target="_blank">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://assets.apitally.io/logos/logo-vertical-dark.png">
+      <source media="(prefers-color-scheme: light)" srcset="https://assets.apitally.io/logos/logo-vertical-light.png">
+      <img alt="Apitally logo" src="https://assets.apitally.io/logos/logo-vertical-light.png" width="150">
+    </picture>
+  </a>
 </p>
 
-<p align="center"><b>Analytics, logging & monitoring for REST APIs.</b></p>
+<p align="center"><b>Simple, privacy-focused API monitoring & analytics</b></p>
 
-<p align="center"><i>Apitally helps you understand how your APIs are being used and alerts you when things go wrong.<br>It's super easy to use and designed to protect your data privacy.</i></p>
-
-<p align="center">🔗 <b><a href="https://apitally.io" target="_blank">apitally.io</a></b></p>
+<p align="center"><i>Apitally helps you understand how your APIs are being used and alerts you when things go wrong.<br>Just add two lines of code to your project to get started.</i></p>
+<br>
 
 ![Apitally screenshots](https://assets.apitally.io/screenshots/overview.png)
 
 ---
 
-# Apitally client library for Node.js
+# Apitally SDK for Node.js
 
 [![Tests](https://github.com/apitally/apitally-js/actions/workflows/tests.yaml/badge.svg?event=push)](https://github.com/apitally/apitally-js/actions)
 [![Codecov](https://codecov.io/gh/apitally/apitally-js/graph/badge.svg?token=j5jqlrL7Pd)](https://codecov.io/gh/apitally/apitally-js)
 [![npm](https://img.shields.io/npm/v/apitally?logo=npm&color=%23cb0000)](https://www.npmjs.com/package/apitally)
 
-This client library for Apitally currently supports the following Node.js web
+This SDK for Apitally currently supports the following Node.js web
 frameworks:
 
 - [Express](https://docs.apitally.io/frameworks/express)
@@ -36,9 +37,21 @@ the 📚 [documentation](https://docs.apitally.io).
 
 ## Key features
 
-- Middleware/plugins for different frameworks to capture metadata about API
-  endpoints, requests and responses
-- Non-blocking client that aggregates and sends captured data to Apitally in regular intervals
+### API analytics
+
+Track traffic, error and performance metrics for your API, each endpoint and individual API consumers, allowing you to make informed, data-driven engineering and product decisions.
+
+### Error tracking
+
+Understand which validation rules in your endpoints cause client errors. Capture error details and stack traces for 500 error responses, and have them linked to Sentry issues automatically.
+
+### Request logging
+
+Drill down from insights to individual requests or use powerful filtering to understand how consumers have interacted with your API. Configure exactly what is included in the logs to meet your requirements.
+
+### API monitoring & alerting
+
+Get notified immediately if something isn't right using custom alerts, synthetic uptime checks and heartbeat monitoring. Notifications can be delivered via email, Slack or Microsoft Teams.
 
 ## Installation
 

package/dist/common/client.cjs

@@ -194,14 +194,116 @@ var RequestCounter = _RequestCounter;
 // src/common/requestLogger.ts
 var import_async_lock = __toESM(require("async-lock"), 1);
 var import_buffer2 = require("buffer");
-var import_crypto2 = require("crypto");
+var import_crypto3 = require("crypto");
 var import_fs2 = require("fs");
 var import_os2 = require("os");
 var import_path2 = require("path");
 
+// src/common/sentry.ts
+var sentry;
+(async () => {
+  try {
+    sentry = await import("@sentry/node");
+  } catch (e) {
+  }
+})();
+function getSentryEventId() {
+  if (sentry && sentry.lastEventId) {
+    return sentry.lastEventId();
+  }
+  return void 0;
+}
+__name(getSentryEventId, "getSentryEventId");
+
+// src/common/serverErrorCounter.ts
+var import_crypto = require("crypto");
+var MAX_MSG_LENGTH = 2048;
+var MAX_STACKTRACE_LENGTH = 65536;
+var _ServerErrorCounter = class _ServerErrorCounter {
+  errorCounts;
+  errorDetails;
+  sentryEventIds;
+  constructor() {
+    this.errorCounts = /* @__PURE__ */ new Map();
+    this.errorDetails = /* @__PURE__ */ new Map();
+    this.sentryEventIds = /* @__PURE__ */ new Map();
+  }
+  addServerError(serverError) {
+    const key = this.getKey(serverError);
+    if (!this.errorDetails.has(key)) {
+      this.errorDetails.set(key, serverError);
+    }
+    this.errorCounts.set(key, (this.errorCounts.get(key) || 0) + 1);
+    const sentryEventId = getSentryEventId();
+    if (sentryEventId) {
+      this.sentryEventIds.set(key, sentryEventId);
+    }
+  }
+  getAndResetServerErrors() {
+    const data = [];
+    this.errorCounts.forEach((count, key) => {
+      const serverError = this.errorDetails.get(key);
+      if (serverError) {
+        data.push({
+          consumer: serverError.consumer || null,
+          method: serverError.method,
+          path: serverError.path,
+          type: serverError.type,
+          msg: truncateExceptionMessage(serverError.msg),
+          traceback: truncateExceptionStackTrace(serverError.traceback),
+          sentry_event_id: this.sentryEventIds.get(key) || null,
+          error_count: count
+        });
+      }
+    });
+    this.errorCounts.clear();
+    this.errorDetails.clear();
+    return data;
+  }
+  getKey(serverError) {
+    const hashInput = [
+      serverError.consumer || "",
+      serverError.method.toUpperCase(),
+      serverError.path,
+      serverError.type,
+      serverError.msg.trim(),
+      serverError.traceback.trim()
+    ].join("|");
+    return (0, import_crypto.createHash)("md5").update(hashInput).digest("hex");
+  }
+};
+__name(_ServerErrorCounter, "ServerErrorCounter");
+var ServerErrorCounter = _ServerErrorCounter;
+function truncateExceptionMessage(msg) {
+  if (msg.length <= MAX_MSG_LENGTH) {
+    return msg;
+  }
+  const suffix = "... (truncated)";
+  const cutoff = MAX_MSG_LENGTH - suffix.length;
+  return msg.substring(0, cutoff) + suffix;
+}
+__name(truncateExceptionMessage, "truncateExceptionMessage");
+function truncateExceptionStackTrace(stack) {
+  const suffix = "... (truncated) ...";
+  const cutoff = MAX_STACKTRACE_LENGTH - suffix.length;
+  const lines = stack.trim().split("\n");
+  const truncatedLines = [];
+  let length = 0;
+  for (const line of lines) {
+    if (length + line.length + 1 > cutoff) {
+      truncatedLines.push(suffix);
+      break;
+    }
+    truncatedLines.push(line);
+    length += line.length + 1;
+  }
+  return truncatedLines.join("\n");
+}
+__name(truncateExceptionStackTrace, "truncateExceptionStackTrace");
+
 // src/common/tempGzipFile.ts
 var import_buffer = require("buffer");
-var import_crypto = require("crypto");
+var import_crypto2 = require("crypto");
 var import_fs = require("fs");
 var import_os = require("os");
 var import_path = require("path");
@@ -214,16 +316,16 @@ var _TempGzipFile = class _TempGzipFile {
   readyPromise;
   closedPromise;
   constructor() {
-    this.uuid = (0, import_crypto.randomUUID)();
+    this.uuid = (0, import_crypto2.randomUUID)();
     this.filePath = (0, import_path.join)((0, import_os.tmpdir)(), `apitally-${this.uuid}.gz`);
     this.writeStream = (0, import_fs.createWriteStream)(this.filePath);
     this.readyPromise = new Promise((resolve, reject) => {
       this.writeStream.once("ready", resolve);
       this.writeStream.once("error", reject);
     });
-    this.closedPromise = new Promise((resolve) => {
+    this.closedPromise = new Promise((resolve, reject) => {
       this.writeStream.once("close", resolve);
-      this.writeStream.once("error", resolve);
+      this.writeStream.once("error", reject);
     });
     this.gzip = (0, import_zlib.createGzip)();
     this.gzip.pipe(this.writeStream);
@@ -321,6 +423,7 @@ var DEFAULT_CONFIG = {
   logRequestBody: false,
   logResponseHeaders: true,
   logResponseBody: false,
+  logException: true,
   maskQueryParams: [],
   maskHeaders: [],
   excludePaths: []
@@ -373,7 +476,10 @@ var _RequestLogger = class _RequestLogger {
   hasSupportedContentType(headers) {
     var _a2;
     const contentType = (_a2 = headers.find(([k]) => k.toLowerCase() === "content-type")) == null ? void 0 : _a2[1];
-    return contentType !== void 0 && ALLOWED_CONTENT_TYPES.some((t) => contentType.startsWith(t));
+    return this.isSupportedContentType(contentType);
+  }
+  isSupportedContentType(contentType) {
+    return typeof contentType === "string" && ALLOWED_CONTENT_TYPES.some((t) => contentType.startsWith(t));
   }
   maskQueryParams(search) {
     const params = new URLSearchParams(search);
@@ -390,7 +496,7 @@ var _RequestLogger = class _RequestLogger {
       this.shouldMaskHeader(k) ? MASKED : v
     ]);
   }
-  logRequest(request, response) {
+  logRequest(request, response, error) {
     var _a2, _b, _c;
     if (!this.enabled || this.suspendUntil !== null) return;
     const url = new URL(request.url);
@@ -401,8 +507,6 @@ var _RequestLogger = class _RequestLogger {
     }
     url.search = this.config.logQueryParams ? this.maskQueryParams(url.search) : "";
     request.url = url.toString();
-    request.headers = this.config.logRequestHeaders ? this.maskHeaders(request.headers) : [];
-    response.headers = this.config.logResponseHeaders ? this.maskHeaders(response.headers) : [];
     if (!this.config.logRequestBody || !this.hasSupportedContentType(request.headers)) {
       request.body = void 0;
     } else if (request.body) {
@@ -435,10 +539,18 @@ var _RequestLogger = class _RequestLogger {
         }
       }
     }
+    request.headers = this.config.logRequestHeaders ? this.maskHeaders(request.headers) : [];
+    response.headers = this.config.logResponseHeaders ? this.maskHeaders(response.headers) : [];
     const item = {
-      uuid: (0, import_crypto2.randomUUID)(),
+      uuid: (0, import_crypto3.randomUUID)(),
       request: skipEmptyValues(request),
-      response: skipEmptyValues(response)
+      response: skipEmptyValues(response),
+      exception: error && this.config.logException ? {
+        type: error.name,
+        message: truncateExceptionMessage(error.message),
+        stacktrace: truncateExceptionStackTrace(error.stack || ""),
+        sentryEventId: getSentryEventId()
+      } : null
     };
     [
       item.request.body,
@@ -535,7 +647,7 @@ function skipEmptyValues(data) {
 __name(skipEmptyValues, "skipEmptyValues");
 function checkWritableFs() {
   try {
-    const testPath = (0, import_path2.join)((0, import_os2.tmpdir)(), `apitally-${(0, import_crypto2.randomUUID)()}`);
+    const testPath = (0, import_path2.join)((0, import_os2.tmpdir)(), `apitally-${(0, import_crypto3.randomUUID)()}`);
     (0, import_fs2.writeFileSync)(testPath, "test");
     (0, import_fs2.unlinkSync)(testPath);
     return true;
@@ -545,104 +657,6 @@ function checkWritableFs() {
 }
 __name(checkWritableFs, "checkWritableFs");
 
-// src/common/serverErrorCounter.ts
-var import_crypto3 = require("crypto");
-var MAX_MSG_LENGTH = 2048;
-var MAX_STACKTRACE_LENGTH = 65536;
-var _ServerErrorCounter = class _ServerErrorCounter {
-  errorCounts;
-  errorDetails;
-  sentryEventIds;
-  sentry;
-  constructor() {
-    this.errorCounts = /* @__PURE__ */ new Map();
-    this.errorDetails = /* @__PURE__ */ new Map();
-    this.sentryEventIds = /* @__PURE__ */ new Map();
-    this.tryImportSentry();
-  }
-  addServerError(serverError) {
-    const key = this.getKey(serverError);
-    if (!this.errorDetails.has(key)) {
-      this.errorDetails.set(key, serverError);
-    }
-    this.errorCounts.set(key, (this.errorCounts.get(key) || 0) + 1);
-    this.captureSentryEventId(key);
-  }
-  getAndResetServerErrors() {
-    const data = [];
-    this.errorCounts.forEach((count, key) => {
-      const serverError = this.errorDetails.get(key);
-      if (serverError) {
-        data.push({
-          consumer: serverError.consumer || null,
-          method: serverError.method,
-          path: serverError.path,
-          type: serverError.type,
-          msg: this.getTruncatedMessage(serverError.msg),
-          traceback: this.getTruncatedStack(serverError.traceback),
-          sentry_event_id: this.sentryEventIds.get(key) || null,
-          error_count: count
-        });
-      }
-    });
-    this.errorCounts.clear();
-    this.errorDetails.clear();
-    return data;
-  }
-  getKey(serverError) {
-    const hashInput = [
-      serverError.consumer || "",
-      serverError.method.toUpperCase(),
-      serverError.path,
-      serverError.type,
-      serverError.msg.trim(),
-      serverError.traceback.trim()
-    ].join("|");
-    return (0, import_crypto3.createHash)("md5").update(hashInput).digest("hex");
-  }
-  getTruncatedMessage(msg) {
-    msg = msg.trim();
-    if (msg.length <= MAX_MSG_LENGTH) {
-      return msg;
-    }
-    const suffix = "... (truncated)";
-    const cutoff = MAX_MSG_LENGTH - suffix.length;
-    return msg.substring(0, cutoff) + suffix;
-  }
-  getTruncatedStack(stack) {
-    const suffix = "... (truncated) ...";
-    const cutoff = MAX_STACKTRACE_LENGTH - suffix.length;
-    const lines = stack.trim().split("\n");
-    const truncatedLines = [];
-    let length = 0;
-    for (const line of lines) {
-      if (length + line.length + 1 > cutoff) {
-        truncatedLines.push(suffix);
-        break;
-      }
-      truncatedLines.push(line);
-      length += line.length + 1;
-    }
-    return truncatedLines.join("\n");
-  }
-  captureSentryEventId(serverErrorKey) {
-    if (this.sentry && this.sentry.lastEventId) {
-      const eventId = this.sentry.lastEventId();
-      if (eventId) {
-        this.sentryEventIds.set(serverErrorKey, eventId);
-      }
-    }
-  }
-  async tryImportSentry() {
-    try {
-      this.sentry = await import("@sentry/node");
-    } catch (e) {
-    }
-  }
-};
-__name(_ServerErrorCounter, "ServerErrorCounter");
-var ServerErrorCounter = _ServerErrorCounter;
-
 // src/common/validationErrorCounter.ts
 var import_crypto4 = require("crypto");
 var _ValidationErrorCounter = class _ValidationErrorCounter {
@@ -716,6 +730,7 @@ var _ApitallyClient = class _ApitallyClient {
   syncIntervalId;
   startupData;
   startupDataSent = false;
+  enabled = true;
   requestCounter;
   requestLogger;
   validationErrorCounter;
@@ -752,12 +767,16 @@ var _ApitallyClient = class _ApitallyClient {
     }
     return _ApitallyClient.instance;
   }
+  isEnabled() {
+    return this.enabled;
+  }
   static async shutdown() {
     if (_ApitallyClient.instance) {
       await _ApitallyClient.instance.handleShutdown();
     }
   }
   async handleShutdown() {
+    this.enabled = false;
     this.stopSync();
     await this.sendSyncData();
     await this.sendLogData();
@@ -941,6 +960,7 @@ var _ApitallyClient = class _ApitallyClient {
     if (error instanceof HTTPError) {
       if (error.response.status === 404) {
         this.logger.error(`Invalid Apitally client ID: '${this.clientId}'`);
+        this.enabled = false;
         this.stopSync();
         return true;
       }