Enhance TypeScript definitions for Plausible tracking library

tracker/npm_package/CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Changed
+- Convert all TypeScript definition comments from `//` style to JSDoc `/** */` style for better IDE integration and TypeScript tooling support
+
 ## [0.4.3] - 2025-09-15
 
 - Fix formatting issues.

tracker/npm_package/plausible.d.ts

@@ -1,110 +1,130 @@
-// Sets up the tracking library. Can be called once.
+/** Sets up the tracking library. Can be called once. */
 export function init(config: PlausibleConfig): void
 
-// Tracks an event, requires `init` to be called first.
+/** Tracks an event, requires `init` to be called first. */
 export function track(eventName: string, options: PlausibleEventOptions): void
 
 export interface PlausibleConfig {
-  // Your site's domain, as declared by you in Plausible's settings.
+  /** Your site's domain, as declared by you in Plausible's settings. */
   domain: string
 
-  // The URL of the Plausible API endpoint. Defaults to https://plausible.io/api/event
-  // See proxying guide at https://plausible.io/docs/proxy/introduction
+  /** 
+   * The URL of the Plausible API endpoint. Defaults to https://plausible.io/api/event
+   * See proxying guide at https://plausible.io/docs/proxy/introduction
+   */
   endpoint?: string
 
-  // Whether to automatically capture pageviews. Defaults to true.
+  /** Whether to automatically capture pageviews. Defaults to true. */
   autoCapturePageviews?: boolean
 
-  // Whether the page uses hash based routing. Defaults to false.
-  // Read more at https://plausible.io/docs/hash-based-routing
+  /** 
+   * Whether the page uses hash based routing. Defaults to false.
+   * Read more at https://plausible.io/docs/hash-based-routing
+   */
   hashBasedRouting?: boolean
 
-  // Whether to track outbound link clicks. Defaults to false.
+  /** Whether to track outbound link clicks. Defaults to false. */
   outboundLinks?: boolean
 
-  // Whether to track file downloads. Defaults to false.
+  /** Whether to track file downloads. Defaults to false. */
   fileDownloads?: boolean | { fileExtensions: string[] }
 
-  // Whether to track form submissions. Defaults to false.
+  /** Whether to track form submissions. Defaults to false. */
   formSubmissions?: boolean
 
-  // Whether to capture events on localhost. Defaults to false.
+  /** Whether to capture events on localhost. Defaults to false. */
   captureOnLocalhost?: boolean
 
-  // Whether to log on ignored events. Defaults to true.
+  /** Whether to log on ignored events. Defaults to true. */
   logging?: boolean
 
-  // Custom properties to add to all events tracked.
-  // If passed as a function, it will be called when `track` is called.
+  /** 
+   * Custom properties to add to all events tracked.
+   * If passed as a function, it will be called when `track` is called.
+   */
   customProperties?:
     | CustomProperties
     | ((eventName: string) => CustomProperties)
 
-  // A function that can be used to transform the payload before it is sent to the API.
-  // If the function returns null or any other falsy value, the event will be ignored.
-  //
-  // This can be used to avoid sending certain types of events, or modifying any event
-  // parameters, e.g. to clean URLs of values that should not be recorded.
+  /** 
+   * A function that can be used to transform the payload before it is sent to the API.
+   * If the function returns null or any other falsy value, the event will be ignored.
+   * 
+   * This can be used to avoid sending certain types of events, or modifying any event
+   * parameters, e.g. to clean URLs of values that should not be recorded.
+   */
   transformRequest?: (
     payload: PlausibleRequestPayload
   ) => PlausibleRequestPayload | null
 
-  // If enabled (the default), the script will set `window.plausible` after `init` is called.
-  // This is used by the verifier to detect if the script is loaded from npm package.
+  /** 
+   * If enabled (the default), the script will set `window.plausible` after `init` is called.
+   * This is used by the verifier to detect if the script is loaded from npm package.
+   */
   bindToWindow?: boolean
 }
 
 export interface PlausibleEventOptions {
-  // Custom properties to add to the event.
-  // Read more at https://plausible.io/docs/custom-props/introduction
+  /** 
+   * Custom properties to add to the event.
+   * Read more at https://plausible.io/docs/custom-props/introduction
+   */
   props?: CustomProperties
 
-  // Whether the tracked event is interactive. Defaults to true.
-  // By marking a custom event as non-interactive, it will not be counted towards bounce rate calculations.
+  /** 
+   * Whether the tracked event is interactive. Defaults to true.
+   * By marking a custom event as non-interactive, it will not be counted towards bounce rate calculations.
+   */
   interactive?: boolean
 
-  // Revenue data to add to the event.
-  // Read more at https://plausible.io/docs/ecommerce-revenue-tracking
+  /** 
+   * Revenue data to add to the event.
+   * Read more at https://plausible.io/docs/ecommerce-revenue-tracking
+   */
   revenue?: PlausibleEventRevenue
 
-  // Called when request to `endpoint` completes or is ignored.
-  // When request is ignored, the result will be undefined.
-  // When request was delivered, the result will be an object with the response status code of the request.
-  // When there was a network error, the result will be an object with the error object.
+  /** 
+   * Called when request to `endpoint` completes or is ignored.
+   * When request is ignored, the result will be undefined.
+   * When request was delivered, the result will be an object with the response status code of the request.
+   * When there was a network error, the result will be an object with the error object.
+   */
   callback?: (
     result?: { status: number } | { error: unknown } | undefined
   ) => void
 
-  // Overrides the URL of the page that the event is being tracked on.
-  // If not provided, `location.href` will be used.
+  /** 
+   * Overrides the URL of the page that the event is being tracked on.
+   * If not provided, `location.href` will be used.
+   */
   url?: string
 }
 
 export type CustomProperties = Record<string, string>
 
 export type PlausibleEventRevenue = {
-  // Revenue amount in `currency`
+  /** Revenue amount in `currency` */
   amount: number | string
-  // Currency is an ISO 4217 string representing the currency code, e.g. "USD" or "EUR"
+  /** Currency is an ISO 4217 string representing the currency code, e.g. "USD" or "EUR" */
   currency: string
 }
 
 export type PlausibleRequestPayload = {
-  // Event name
+  /** Event name */
   n: string
-  // URL of the event
+  /** URL of the event */
   u: string
-  // Domain of the event
+  /** Domain of the event */
   d: string
-  // Referrer
+  /** Referrer */
   r?: string | null
-  // Custom properties
+  /** Custom properties */
   p?: CustomProperties
-  // Revenue information
+  /** Revenue information */
   $?: PlausibleEventRevenue
-  // Whether the event is interactive
+  /** Whether the event is interactive */
   i?: boolean
 } & Record<string, unknown>
 
-// Default file types that are tracked when `fileDownloads` is enabled.
+/** Default file types that are tracked when `fileDownloads` is enabled. */
 export const DEFAULT_FILE_TYPES: string[]